How to Migrate a Legacy v1 Workflow JSON to v2 Schema Using Archify CLI

Archify ships a built-in migration command that automatically converts legacy v1 workflow JSON files to the v2 schema using archify migrate workflow <old.json> <new.json> --to-schema 2, preserving geometry and validating the output against the new schema.

The Archify CLI provides a fully automated pipeline for upgrading workflow definitions from the original schema v1 to the richer, coordinate-centered schema v2. This process handles validation, geometry probing, and viewBox expansion without requiring manual edits to the source JSON.

CLI Command Syntax and Options

The migration command follows a strict signature defined in archify/bin/archify.mjs:

archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]

• <old.json> – Path to the legacy workflow file. Must be valid JSON conforming to schema v1.
• <new.json> – Destination path for the migrated v2 workflow.
• --to-schema 2 – Required flag that explicitly requests migration to schema v2. The CLI aborts if this flag is missing or set to a different value.
• --json – Optional flag that outputs a machine-readable migration report instead of human-friendly console messages.

Step-by-Step Migration Process

When executed, Archify performs a logical sequence of operations to ensure safe and accurate transformation.

Argument Validation

The CLI first verifies that the command name, source path, and destination path are present, and confirms that --to-schema 2 is supplied. If any check fails, the utility aborts with a usage message defined at lines 65–75 of archify/bin/archify.mjs.

Reading and Parsing the Source

The source file is read synchronously using fs.readFileSync and parsed as JSON. Errors during this phase are captured as diagnostics and reported immediately to the user (see lines 96–100 of archify/bin/archify.mjs).

Core Migration Logic

The heart of the transformation resides in archify/migrations/workflow-v2.mjs. The migrateWorkflowDocument function executes the following sub-steps:

1. Schema Validation – The source document is validated against the v1 schema via validateSchema. If pre-existing diagnostics are found, migration stops early and returns a report containing those issues (lines 30–33).

2. Legacy Layout Probing – The system runs legacyLayoutProbe and legacyRequirementProbe to capture the intrinsic canvas capacity without relying on the author-provided meta.viewBox.

3. Geometry Planning – Using either an intrinsic rank mapper or a fallback planning workflow (intrinsicWorkflow / planningWorkflow), Archify calculates the target geometry for the v2 coordinate system.

4. ViewBox Expansion – The routine expands the viewBox as needed so that all absolute pins can be represented in the new rank-centered coordinate system.

5. Final Validation – After transformation, the workflow is compiled once more with the v2 compiler to ensure the result is error-free. The final result object returned at lines 84–112 contains the migrated document, diagnostics, and the old/new viewBox dimensions.

Output and Idempotence

If migration succeeds, Archify writes the JSON representation of the migrated workflow to the destination path and prints a success message. If any step fails, a detailed diagnostic report is emitted (or printed as JSON when --json is used).

The process is idempotent: running the command on a document already at schema v2 simply re-validates the file and returns it unchanged. This early-exit branch is implemented at lines 38–58 of archify/migrations/workflow-v2.mjs.

Practical Code Examples

Basic Migration

Convert a legacy workflow with human-readable output:

archify migrate workflow legacy-workflow.json migrated-workflow.json --to-schema 2

Truncated output:

migrated workflow schema v1→v2: /path/legacy-workflow.json → /path/migrated-workflow.json

Migration with JSON Report

Generate a machine-readable report for CI/CD pipelines:

archify migrate workflow legacy-workflow.json migrated-workflow.json --to-schema 2 --json

Sample output:

{
  "ok": true,
  "command": "migrate",
  "type": "workflow",
  "source": {
    "path": "/path/legacy-workflow.json",
    "sha256": "a1b2c3…",
    "bytes": 1234
  },
  "destination": {
    "path": "/path/migrated-workflow.json",
    "sha256": "d4e5f6…",
    "bytes": 1300
  },
  "fromSchemaVersion": 1,
  "toSchemaVersion": 2,
  "preExistingDiagnostics": [],
  "migrationDiagnostics": [],
  "newSchemaDiagnostics": [],
  "changedCoordinates": [],
  "oldRequiredViewBox": [720, 240],
  "newRequiredViewBox": [768, 404]
}

Programmatic Usage

Import the migration logic directly in Node.js applications:

import { migrateWorkflowDocument } from './archify/migrations/workflow-v2.mjs';
import { readFileSync, writeFileSync } from 'fs';

const legacy = JSON.parse(readFileSync('legacy-workflow.json', 'utf8'));
const { ok, document, migrationDiagnostics } = migrateWorkflowDocument(legacy);

if (ok) {
  writeFileSync('migrated-workflow.json', JSON.stringify(document, null, 2));
  console.log('Migration succeeded');
} else {
  console.error('Migration failed:', migrationDiagnostics);
}

Key Source Files and Architecture

Understanding the underlying implementation helps when debugging complex migrations:

• archify/bin/archify.mjs – CLI entry point that parses the migrate command and assembles the migration report.
• archify/migrations/workflow-v2.mjs – Core migration implementation containing migrateWorkflowDocument, validation logic, and geometry transformation routines.
• archify/renderers/workflow/workflow-compiler.mjs – Compiler used for both the legacy probe phase and final v2 validation.
• archify/renderers/workflow/README.md – User documentation confirming exact CLI usage patterns.
• archify/test/workflow-migration.test.mjs – Test suite confirming correct behavior and idempotence guarantees.

Summary

• Archify CLI provides a first-party migrate workflow command for upgrading v1 JSON files to schema v2.
• The --to-schema 2 flag is mandatory and explicitly targets the v2 schema.
• Migration performs geometry-preserving transformation by probing legacy layouts and expanding viewBox coordinates to accommodate rank-centered positioning.
• The process is idempotent: running migration on an already-v2 file validates and returns it unchanged.
• Use the --json flag for machine-readable output suitable for automated build pipelines.
• Core logic resides in archify/migrations/workflow-v2.mjs, specifically the migrateWorkflowDocument function.

Frequently Asked Questions

What happens if my v1 workflow file contains validation errors?

If validateSchema detects pre-existing diagnostics during the initial check at lines 30–33 of archify/migrations/workflow-v2.mjs, the migration stops immediately. The CLI returns a report containing the specific validation errors without writing an output file, allowing you to fix the legacy document before retrying.

Is the migration process idempotent?

Yes. According to the early-exit branch at lines 38–58 of archify/migrations/workflow-v2.mjs, Archify detects when a document is already at schema v2. In this case, it re-validates the file and returns it unchanged, making the command safe to run multiple times without side effects.

Why does my viewBox change size during migration?

Archify probes the legacy layout using legacyLayoutProbe and legacyRequirementProbe to determine the intrinsic canvas capacity. It then expands the viewBox to ensure all absolute pins can be represented in the new rank-centered coordinate system. The final dimensions are reported in the oldRequiredViewBox and newRequiredViewBox fields of the migration report.

Can I integrate this migration into my Node.js build scripts?

Yes. The migrateWorkflowDocument function exported from archify/migrations/workflow-v2.mjs can be imported directly into Node.js applications. Pass the parsed JSON object as an argument and handle the returned ok boolean and document properties to programmatically control file writing and error handling.

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