How to Migrate Workflow JSON from Schema v1 to v2 Using the Archify CLI

Use the migrate workflow sub-command to safely upgrade legacy v1 workflow files to the v2 schema while preserving original bytes and generating a detailed JSON receipt.

Archify persists workflow diagrams as typed JSON adhering to a versioned schema. When upgrading legacy automation definitions authored against the older v1 specification, you can migrate workflow JSON from schema v1 to v2 using the CLI toolchain distributed in archify/bin/archify.mjs. The process automatically handles coordinate remapping, viewBox expansion, and diagnostic preservation without mutating source files.

How the Migration Engine Transforms Documents

The core migration logic resides in archify/migrations/workflow-v2.mjs. This module reads the source v1 document, validates its structure, and extracts any pre-existing diagnostics before applying geometric transformations. If the original workflow declares an explicit size in meta.viewBox that is too small for modern layout engines, the system automatically expands the capacity to meet v2 requirements.

The engine remaps absolute x coordinates onto the new horizontal rank system using the horizontal rank mapper exported from archify/renderers/workflow/workflow-migration-geometry.mjs. During the final stage, the migrator attaches fresh diagnostics and injects a migration_probe node that records the capacity change, then emits a v2-compliant document alongside a structured receipt.

CLI Syntax and Command Usage

The entry point at archify/bin/archify.mjs exposes the migration through the migrate workflow sub-command. You must provide distinct source and destination paths.

Basic invocation:

node archify/bin/archify.mjs migrate workflow \
    path/to/old-workflow.json \
    path/to/new-workflow.json

The CLI automatically detects v1 schema source files and emits v2-compatible output at the destination.

Optional Flags

• --capacity – Forces a specific viewBox capacity rather than auto-calculating the minimum required size.
• --quality <profile> – Specifies a rendering profile (standard, showcase, etc.). When the source document includes an authored profile, the migration preserves it automatically, as verified in archify/test/workflow-migration.test.mjs at lines 270-283.
• --json – Outputs a machine-readable receipt instead of human-readable logs.

Example with quality override:

node archify/bin/archify.mjs migrate workflow old.json new.json --quality showcase

Interpreting the Migration Receipt

Adding the --json flag returns a structured receipt matching the return value of the internal migrateWorkflowDocument function. This object contains diagnostic metadata and the migrated document:

• ok – Boolean indicating overall success.
• migrationDiagnostics – Array of issues discovered during the conversion process.
• newSchemaDiagnostics – Validation results against the strict v2 schema.
• oldRequiredViewBox – Original dimensions (e.g., [720, 280]), reported separately from authored capacity per the test at lines 430-440.
• newRequiredViewBox – Computed dimensions for v2 compliance (e.g., [1600, 900]).
• document – The complete migrated workflow object ready for persistence.

Example output:

{
  "ok": true,
  "migrationDiagnostics": [],
  "newSchemaDiagnostics": [],
  "oldRequiredViewBox": [720, 280],
  "newRequiredViewBox": [1600, 900],
  "document": { }
}

Safety Guarantees and Atomicity

The migration toolchain provides strict safety guarantees enforced by the test suite in archify/test/workflow-migration.test.mjs. The source file is never modified in-place; the test "migration must not mutate its source bytes" (lines 362-368) asserts that original byte sequences remain untouched throughout the process.

If the migration fails—for instance, when the destination path creates a symlink cycle or matches the source path—the CLI aborts without creating partial files. The test "failed workflow migration never writes its destination" (lines 594-608) verifies this atomic behavior, ensuring your filesystem remains clean even when operations encounter errors.

Summary

• The migrate workflow sub-command in archify/bin/archify.mjs automates the upgrade from v1 to v2 schema.
• Core logic lives in archify/migrations/workflow-v2.mjs with geometric calculations in archify/renderers/workflow/workflow-migration-geometry.mjs.
• The process expands meta.viewBox capacity and remaps coordinates using the horizontal rank mapper.
• Use --json to receive a detailed receipt containing oldRequiredViewBox, newRequiredViewBox, and diagnostic arrays.
• Original files are read-only; failed migrations never write partial destinations.

Frequently Asked Questions

Does the migration modify the original v1 workflow file?

No. According to the test "migration must not mutate its source bytes" in archify/test/workflow-migration.test.mjs at lines 362-368, the CLI treats the source as immutable. It reads the original bytes and writes a completely new file at the destination path, leaving the legacy document intact for rollback purposes.

What information does the migration receipt contain?

The receipt contains an ok boolean, migrationDiagnostics for conversion issues, newSchemaDiagnostics for v2 validation results, and dimensional tracking via oldRequiredViewBox and newRequiredViewBox. When using the --json flag, this receipt prints to stdout for piping into other tools like jq.

How does the CLI handle coordinate differences between v1 and v2?

The migration uses the horizontal rank mapper from archify/renderers/workflow/workflow-migration-geometry.mjs to translate absolute x coordinates from the v1 absolute positioning system into the v2 horizontal rank system. This ensures visual fidelity while adopting the new layout engine's constraints.

What happens if the destination path is invalid?

The CLI performs pre-flight checks before writing. If the destination is a symlink cycle or identical to the source path, the operation aborts without creating a file. As tested in archify/test/workflow-migration.test.mjs lines 594-608, failed migrations never write their destination, preventing corruption or data loss.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}