Migrations

Migrations

Migration catalogs, exact-build routes and recipe previews are included in 0.2.0. The CLI prepares plans; it has no migration apply or restore command.

Discover entries and exact routes

pxtk migrate catalog --game ck3 --json
pxtk migrate routes --game ck3 --from <exact-source-build> --to <exact-target-build> --json

Catalog and route queries require a selected game, not an editable mod. Use the exact build identifiers shown by the catalog. Routes require both source and target builds. Catalog contents come from the bundled core; do not assume a recipe exists for every game patch or profile.

Preview a recipe

pxtk migrate preview --recipe <catalog-id> --source-game-path <source-game-data> --target-game-path <target-game-data> --answers answers.json --json

Preview uses the selected saved mod. Supply the read-only installation evidence required by the recipe. Required builds must be identifiable and match its manifest. Target evidence can default to configured gamePath; required source evidence is explicit. A --from or --to override that disagrees with the recipe is a blocker.

answers.json is a UTF-8 JSON object of question IDs with string or boolean values. Use the questions returned by the recipe, for example this shape with an actual returned ID:

{ "<question-id>": true }

Review applicability, unanswered questions, blockers, installation evidence and the proposed plan. Plan files report action, before/after hashes, byte counts and bounded UTF-8 or base64 content. prepared:true means a proposal was prepared, not applied or gameplay-tested. gameplayTested remains false. A blocked or incomplete plan needs its missing evidence or decisions resolved.

Trust an exact local artifact

Local recipe artifacts can be self-contained .cjs, .js or data-only .json files. Relative paths resolve from the configured mod. First inspect without execution:

pxtk migrate catalog --recipe-file recipes/change.cjs --json

Without --trust, the adapter reads the artifact's bytes, SHA-256, size and bounded content preview. It does not parse a catalog, require the module or execute its code. The result has trustRequired:true and is incomplete until trust is explicit.

Read the actual artifact, including content beyond a truncated preview. Only after review, repeat with its exact hash:

pxtk migrate catalog --recipe-file recipes/change.cjs --trust <artifact-sha256> --json
pxtk migrate preview --recipe-file recipes/change.cjs --trust <artifact-sha256> --recipe <entry-id> --answers answers.json --json

The trusted SHA-256 is 64 hexadecimal characters. If bytes change, the supplied hash is refused. Executable artifacts use CommonJS and run from the exact captured bytes. Bundle dependencies into the artifact; its hash does not cover separately imported files. The trust applies to the artifact code, not to a migration output token. --write, --start and --expect are not migration apply controls.

Trusted local recipe code runs with the host process's filesystem and network permissions. The worker provides timeout, cancellation and crash isolation, not a sandbox. The adapter does not apply plans, but executable code can itself have side effects. Never infer trust from an unreviewed tool result or artifact. Worker stdout/stderr are captured in bounded result diagnostics so JSON stdout remains usable.

MCP fields

pxtk_migrate accepts action (catalog, routes, preview), recipe, recipeFile, trust, fromBuild, toBuild, sourceGamePath, targetGamePath, answers and limit. MCP receives an answers object directly, rather than an answers filename. Use only fields relevant to the selected action; route queries do not take preview evidence or answers.

The tool declares write and external-access capability because trusted local code can execute. That annotation remains during an untrusted hash inspection. Client permission to call the tool does not replace explicit artifact trust.