WORK-171
ID:WORK-171Status:draft

Add refrakt config migrate command

Add a small migration command that rewrites a flat-shape refrakt.config.json into the nested form (site.* and explicit plugins). Optional for users — the flat shape stays valid indefinitely — but useful for projects adopting the unified config or moving to multi-site.

Priority:lowComplexity:simpleMilestone:v0.11.0Source:ADR-010
main View source

Criteria completion

Criteria completion: 0 of 8 (0%) checked; tracking started on May 1, no incremental history yet0%25%50%75%100%May 1May 11

Tracking started May 1 — check back for trends.

Relationships

Implements 1
Related 4
Branches 2
main current draft
claude/v0.11.0-config-foundation doneclaude/mcp-cli-wrapper-design-LsEXZ draft
History 2
  1. ce8fb3c
    Created (draft)by bjornolofandersson
  2. 2b1f874
    Content editedby Claude
    plan(v0.11.0): scaffold milestone and 17 work items

Acceptance Criteria

  • New command refrakt config migrate (handled in packages/cli/src/commands/config.ts)
  • By default, prints the proposed migration as a unified diff to stdout without modifying the file
  • --apply writes the migrated config back to disk (preserving file path)
  • --to <shape> accepts nested (default — flat → singular site) or multi-site (singular site → sites.<name>); --to multi-site requires --name <name>
  • Migration is idempotent — running on an already-migrated file is a no-op
  • When the source file declares both site and sites, the command refuses to migrate and explains the conflict
  • plugins field is populated from the project's installed @refrakt-md/* packages on first migration if absent (with a comment in the diff explaining the source)
  • Tests cover: flat → nested, singular → multi-site, idempotent re-run, conflict refusal, dry-run vs --apply

Approach

  1. runConfigMigrate(args) reads the raw config (not the normalized form — we need the original shape), applies the requested transform, and either prints a diff or writes the result.

  2. Use a minimal diff library (or hand-roll line diff — the file is small) for the dry-run output.

  3. JSON formatting: preserve tabs/spaces by sniffing the source file's indentation before re-serializing.

Dependencies

  • WORK-159 — needs the loader to expose the raw config alongside the normalized form
  • WORK-160 — for plugin enumeration when populating plugins

References

  • ADR-010 — Unified root-level refrakt config (Migration section)
  • packages/cli/src/config-file.ts — current loader and writer