feat: respect $XDG_DATA_HOME for the data directory (legacy ~/.plannotator preserved)#1093
Merged
Merged
Conversation
…otator does not exist
New resolution order for the Plannotator data directory:
1. PLANNOTATOR_DATA_DIR (unchanged, top priority, ~ expansion)
2. ~/.plannotator when it already exists (legacy default — existing
installs never move)
3. $XDG_DATA_HOME/plannotator when XDG_DATA_HOME is set to a
non-empty absolute path
4. ~/.plannotator (default for everyone else)
This is git's legacy-first pattern: the XDG branch only fires for fresh
installs whose user has explicitly set XDG_DATA_HOME. The XDG spec's
implicit ~/.local/share default is deliberately NOT applied, and the
directory stays monolithic (no config/data/cache split).
Mirrored in every private copy of the resolver: the Amp plugin,
scripts/install.sh, scripts/install.ps1, and scripts/install.cmd. The
Pi runtime picks the change up automatically via vendor.sh. Docs updated
in README.md, AGENTS.md/CLAUDE.md, and the marketing env-var reference.
Claude-Session: https://claude.ai/code/session_01YXkgsNucxDwAL4GdR4XYRk
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
1 participant
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.
What
Adds XDG-aware placement for the Plannotator data directory, using the git-style legacy-first pattern. New resolution order:
PLANNOTATOR_DATA_DIR— unchanged, remains the top-priority override (with~expansion)~/.plannotatorif it exists — the legacy default always wins$XDG_DATA_HOME/plannotator— whenXDG_DATA_HOMEis set to a non-empty absolute path~/.plannotator— default for everyone elseZero change for existing users — the fallback only fires when
~/.plannotatordoes not exist and$XDG_DATA_HOMEis set. All macOS/Windows users and anyone who doesn't set XDG vars keep~/.plannotatorexactly as before. The XDG spec's implicit~/.local/sharedefault is deliberately not applied — only an explicitly-set$XDG_DATA_HOMEmoves the directory.Where
packages/shared/data-dir.ts— the shared resolver (Pi picks it up automatically viavendor.sh)apps/amp-plugin/plannotator.ts— the Amp plugin's private copy, mirroredscripts/install.sh/install.ps1/install.cmd— config.json resolution mirrored (XDG honored on Windows too if set, same rule)packages/shared/data-dir.test.ts— new unit tests covering all four branches (run in subprocesses with a fakedHOME, since Bun resolveshomedir()at process start)README.md(newPLANNOTATOR_DATA_DIRmention + export example),AGENTS.md/CLAUDE.md, and the marketing env-var referenceHistory
This builds on the direction from #568 (@cwrau) and #612 (@Joao-O-Santos), which proposed full XDG base-directory support, and the single monolithic-directory model established in #795 (@IstPlayer). Per the maintainer feedback on those PRs, this change deliberately stops short of a config/data/cache split — it only adds XDG-aware placement of the one directory, and
PLANNOTATOR_DATA_DIRremains the top-priority override for anyone who wants full control.Closes #1051
https://claude.ai/code/session_01YXkgsNucxDwAL4GdR4XYRk