Skip to content

feat(paths): use XDG base directories instead of ~/.plannotator#568

Open
cwrau wants to merge 1 commit intobacknotprop:mainfrom
cwrau:feat/xdg-base-dirs
Open

feat(paths): use XDG base directories instead of ~/.plannotator#568
cwrau wants to merge 1 commit intobacknotprop:mainfrom
cwrau:feat/xdg-base-dirs

Conversation

@cwrau
Copy link
Copy Markdown

@cwrau cwrau commented Apr 15, 2026

Summary

  • Adds packages/shared/paths.ts with three helpers: getDataBase(), getStateBase(), getConfigBase()
  • Stores persistent data (plans/, history/) under $XDG_DATA_HOME/plannotator (default: ~/.local/share/plannotator)
  • Stores ephemeral state (drafts/, sessions/, debug logs) under $XDG_STATE_HOME/plannotator (default: ~/.local/state/plannotator)
  • Stores configuration (config.json, improvement hooks) under $XDG_CONFIG_HOME/plannotator (default: ~/.config/plannotator)
  • Existing installations are unaffected: if ~/.plannotator already exists on disk, all three helpers return it — zero migration required

Call sites updated

File Change
packages/shared/storage.ts getDataBase() for plans + history
packages/shared/draft.ts getStateBase() for drafts
packages/shared/config.ts getConfigBase() for config.json
packages/shared/improvement-hooks.ts getConfigBase() for hooks dir
packages/server/sessions.ts getStateBase() for sessions
packages/server/codex-review.ts getStateBase() for schema file + debug log

Migration for existing users

No action needed — ~/.plannotator continues to work unchanged. To adopt XDG paths, simply move the directory:

mv ~/.plannotator ~/.local/share/plannotator   # data + state
# or symlink: ln -s ~/.local/share/plannotator ~/.plannotator

Config and state can be split further if desired:

mkdir -p ~/.config/plannotator ~/.local/state/plannotator
mv ~/.local/share/plannotator/config.json ~/.config/plannotator/
mv ~/.local/share/plannotator/hooks      ~/.config/plannotator/
mv ~/.local/share/plannotator/drafts     ~/.local/state/plannotator/
mv ~/.local/share/plannotator/sessions   ~/.local/state/plannotator/

Test plan

  • Fresh install: verify data lands in ~/.local/share/plannotator/, state in ~/.local/state/plannotator/, config in ~/.config/plannotator/
  • With ~/.plannotator present: verify all paths still resolve to ~/.plannotator (no regression)
  • Custom XDG_DATA_HOME, XDG_STATE_HOME, XDG_CONFIG_HOME: verify respected on fresh install

🤖 Generated with Claude Code

New installations now store data, state, and config under the
XDG Base Directory Specification:

  data   -> $XDG_DATA_HOME/plannotator  (plans, version history)
  state  -> $XDG_STATE_HOME/plannotator (drafts, sessions, debug logs)
  config -> $XDG_CONFIG_HOME/plannotator (config.json, hooks)

Existing installations are unaffected: the legacy ~/.plannotator
directory is detected at runtime and used as-is for all three
bases, so no migration is required for current users.

The central logic lives in packages/shared/paths.ts, which exports
getDataBase(), getStateBase(), and getConfigBase(). All six call
sites (storage, draft, config, improvement-hooks, sessions,
codex-review) now import from there instead of hardcoding homedir().

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@backnotprop
Copy link
Copy Markdown
Owner

I understand this on one hand. And the code organization is great.

On the other, this is a fairly big lift I need to just map out mentally.

Also, there is a lot of convenience in ~/ dot directories.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants