scripts: add migrate-v1-to-v2 for v2 spec migration

[bendebury]

Summary

Standalone Go script kit authors run to convert their spec.yaml from schemaVersion 1 to schemaVersion 2. Lands ahead of the rest of the v2 migration so kit authors have a working tool the moment the breaking changes start shipping.

The script is intentionally incremental. Today's scope covers Phase 1 cosmetic renames; later phases (volumes redesign, credentials redesign, settings lift) extend the same applyPhase1Transforms pattern as their PRs land. See scripts/README.md for the current scope and the v2 spec doc on docker/sandboxes for the migration roadmap.

Usage

go run scripts/migrate-v1-to-v2.go <path-to-kit-directory>

Writes <path>/spec.yaml in place and leaves <path>/spec.yaml.bak as a backup. Running on an already-v2 spec is a no-op and does not create a .bak.

Transforms (Phase 1)

v1 spelling	v2 spelling
kind: agent	kind: sandbox
agent: block	sandbox: block
memory: field	agentContext: field

Design

• Standalone module-free — package main with only stdlib imports, so kit authors can go run against any checkout without pulling sbx-kits-contrib's deps.
• Regex line replacement — preserves comments, blank lines, and block-scalar formatting. A YAML re-marshal would have reformatted the entire file; the regex approach keeps the diff to just the renamed fields.
• Refuses to clobber an existing .bak — if a previous migration left one, the script errors rather than silently overwriting the backup.
• Anchored regexes — top-level YAML keys only. Nested agent: (unlikely but possible) is left alone.

Test plan

• Golden-file tests under scripts/testdata/ — v1 input + v2 expected pairs compared byte-for-byte
• End-to-end tests via the migrate() function against temp-dir copies of the fixtures
• No-op verification on already-v2 specs
• Refuse-to-clobber-.bak verification
• Missing-spec verification
• go test ./scripts/... green

Docs

• New scripts/README.md — canonical usage reference, scope-as-it-grows, fixture conventions
• CONTRIBUTING.md adds a "Migrating an existing kit to v2" section pointing at the script

🤖 Generated with Claude Code