migration

Overview ¶

Package migration handles one-time migration of legacy sidecar state files to the centralized XDG-compliant locations introduced in the feature/centralized-project-storage PR.

Legacy layout (before centralization):

<project-root>/.sidecar/shells.json      → project shell manifest
<project-root>/.sidecar/config.json      → project prompt config
<project-root>/.td-root                  → td database root pointer
<worktree>/.sidecar-task                 → linked task ID
<worktree>/.sidecar-agent                → agent type
<worktree>/.sidecar-pr                   → PR URL
<worktree>/.sidecar-base                 → base branch
<worktree>/.sidecar-start.sh             → agent launcher script

New layout (after centralization):

~/.local/state/sidecar/projects/<slug>/shells.json
~/.local/state/sidecar/projects/<slug>/config.json
~/.local/state/sidecar/projects/<slug>/td-root
~/.local/state/sidecar/projects/<slug>/worktrees/<wt-slug>/task
~/.local/state/sidecar/projects/<slug>/worktrees/<wt-slug>/agent
~/.local/state/sidecar/projects/<slug>/worktrees/<wt-slug>/pr
~/.local/state/sidecar/projects/<slug>/worktrees/<wt-slug>/base
~/.local/state/sidecar/projects/<slug>/worktrees/<wt-slug>/start.sh

Migration is:

• Automatic: called on first use of a project directory
• Idempotent: safe to call multiple times, will not overwrite existing data
• Non-destructive: legacy files are never deleted
• Logged: each migrated file is reported via slog.Info