Adds XDG Base Directory support (backward compatible)#612
Open
Joao-O-Santos wants to merge 9 commits intobacknotprop:mainfrom
Open
Adds XDG Base Directory support (backward compatible)#612Joao-O-Santos wants to merge 9 commits intobacknotprop:mainfrom
Joao-O-Santos wants to merge 9 commits intobacknotprop:mainfrom
Conversation
Add packages/shared/paths.ts as the single source of truth for config/data/cache directories. Respects PLANNOTATOR_*_DIR overrides and XDG_*_HOME variables, falling back to ~/.config/plannotator, ~/.config/plannotator/data, and ~/.cache/plannotator. Updates config.ts, storage.ts, draft.ts, and improvement-hooks.ts to use the new paths with transparent legacy fallback for reads. Archive listing merges results from new and legacy paths so existing plans remain visible.
Update server-side paths to use getCacheDir() for transient state: - sessions.ts: ~/.cache/plannotator/sessions/ - browser.ts: ~/.cache/plannotator/vscode-ipc.json - codex-review.ts: ~/.cache/plannotator/ (debug log + schema) - tour/tour-review.ts: ~/.cache/plannotator/ (tour schema)
- vscode-extension/src/extension.ts: resolve vscode-ipc.json via getCacheDir() (PLANNOTATOR_CACHE_DIR / XDG_CACHE_HOME / ~/.cache) - paste-service/targets/bun.ts: default paste dir under cache, keeping PASTE_DATA_DIR override for backward compat
Update user-facing labels, placeholders, and tooltip text to reflect the new default data directory: ~/.config/plannotator/data/plans/
install.sh, install.ps1, and install.cmd now resolve config.json through PLANNOTATOR_CONFIG_DIR > XDG_CONFIG_HOME > default (~/.config/plannotator/config.json) instead of hardcoding ~/.plannotator/config.json. Updates install.test.ts assertions to match the new resolution functions.
- improvement-hooks.test.ts: create new-path fixtures under .config/plannotator/data/hooks/ and update assertions - test-sessions.sh: use XDG_CACHE_HOME or ~/.cache for sessions dir
Update AGENTS.md and marketing docs to reflect the new directory layout: - Config: ~/.config/plannotator/ - Data: ~/.config/plannotator/data/ - Cache: ~/.cache/plannotator/ Add new env vars (PLANNOTATOR_CONFIG_DIR, PLANNOTATOR_DATA_DIR, PLANNOTATOR_CACHE_DIR) to the environment variables reference.
Previously, all plannotator data lived in ~/.plannotator. This change adds support for the XDG Base Directory Specification while keeping ~/.plannotator as the default for backward compatibility. New behavior: - No XDG_*_HOME set → uses ~/.plannotator (original behavior) - XDG_CONFIG_HOME set → config goes to /home/random_user/.config/plannotator/ - XDG_DATA_HOME set → data goes to /home/random_user/.config/plannotator/ - XDG_CACHE_HOME set → cache goes to /home/random_user/.cache/plannotator/ - PLANNOTATOR_*_DIR → overrides everything (highest priority) Data categories: - Config: config.json - Data: plans/, history/, hooks/ - Cache: drafts/, sessions/, pastes/, logs/, schemas/ Reads fall back transparently to ~/.plannotator so existing data remains accessible. Writes always go to the resolved path. New env vars documented: - PLANNOTATOR_CONFIG_DIR - PLANNOTATOR_DATA_DIR - PLANNOTATOR_CACHE_DIR Fixes #XXX (replace with actual issue number if applicable)
3 tasks
Author
Owner
|
I will evaluate both approaches this weekend Thanks for thoughtful approach! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add XDG Base Directory support (backward compatible)
First off, let me thank you for building this plugin and open sourcing it. I'm still just trying out the plugin, but I'm already seeing the benefits!
PR Rationale
I like to keep my $HOME directory as clean as possible, and have configured XDG_ env vars to help keep it that way. It is just a personal nit pick, but I wanted to get plannotator to respect XDG spec.
What this PR does
This PR adds support for the XDG Base Directory Specification while keeping
~/.plannotatoras the default for full backward compatibility.Before this PR
All plannotator data lived in a single
~/.plannotator/directory:config.json)plans/,history/,hooks/)drafts/,sessions/,pastes/, debug logs,schemas)
After this PR
Path resolution now follows this priority (highest wins):
PLANNOTATOR_*_DIRenv var (explicit override)XDG_*_HOMEenv var (spec compliance)~/.plannotator(original default — unchanged)| Category | Contents | Env override | XDG fallback | Default |
|----------|----------|--------------|--------------|---------| Config |
|
config.json|PLANNOTATOR_CONFIG_DIR|XDG_CONFIG_HOME||
~/.plannotator| Data |plans/,history/,hooks/||
PLANNOTATOR_DATA_DIR|XDG_DATA_HOME|~/.plannotator| Cache ||
drafts/,sessions/,pastes/, logs, schemas |PLANNOTATOR_CACHE_DIR||
XDG_CACHE_HOME|~/.plannotator|Migration strategy
~/.plannotator/XDG vars
Files changed
packages/shared/paths.ts— new path resolution modulepackages/shared/config.ts,storage.ts,draft.ts,improvement-hooks.ts— use new paths
packages/server/sessions.ts,browser.ts,codex-review.ts,tour/tour-review.ts— use new pathsapps/vscode-extension/src/extension.ts— match server's IPC pathapps/paste-service/targets/bun.ts— paste store uses cache dirpackages/ui/components/Settings.tsx,utils/planSave.ts,utils/quickLabels.ts— UI strings updatedscripts/install.sh,install.ps1,install.cmd— dynamic config path resolutionpackages/shared/improvement-hooks.test.ts,tests/manual/local/test-sessions.sh— tests updatedXDG_DESIGN.md— design decision recordTesting
plannotator --help✓plannotator annotate md_file.md✓~/.plannotatoris not created when XDG vars are set ✓About this PR
The key design constraint was: no breaking changes. Users who don't set
XDG_*_HOMEshould see absolutely zero difference in behavior. XDG support ispurely opt-in.
I am not a Node.js/TypeScript developer by trade, nor an AI tooling specialist. I reviewed the generated changes, tested them on my machine, and validated that the behavior is correct. The implementation was done with the help of an AI coding assistant (namely, OpenCode with the plannotator plugin). I reviewed the decisions, and overall approach. Still, this is not my wheel house.
Please review carefully, and do let me know what I need to fix.
Thank you for reading and considering the PR. Please keep up the good work!