Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(migrate): repair legacy workflow outputs explicitly
tt-a1i0a2d2fde5c01
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex be1b6d8f..1d595684 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -2180,7 +2180,7 @@ function usage() {archify deliver <type> <input.json> [output.html] [--json] [--open] [--quality standard|showcase] [--repo-root path]archify preview <type> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path]archify validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path]- archify migrate workflow <old.json> <new.json> --to-schema 2 [--json] [--repo-root path]+ archify migrate workflow <old.json> <new.json> --to-schema 2 [--output portable.html] [--json] [--repo-root path]archify inspect <type> <input.json>archify check <output.html> [--require-provenance]archify visual-check <output.html> [--json] [--require-provenance] [--out-dir <dir>]@@ -5911,6 +5911,7 @@ function extractMigrationOptions(args) {const positional = [];let json = false;let toSchema;+ let output;for (let index = 0; index < args.length; index += 1) {const arg = args[index];if (arg === '--json') {@@ -5928,10 +5929,21 @@ function extractMigrationOptions(args) {if (!toSchema) fail('--to-schema requires a schema version.');continue;}+ if (arg === '--output') {+ output = args[index + 1];+ if (!output || output.startsWith('--')) fail('--output requires a portable HTML path.');+ index += 1;+ continue;+ }+ if (arg.startsWith('--output=')) {+ output = arg.slice('--output='.length);+ if (!output) fail('--output requires a portable HTML path.');+ continue;+ }if (arg.startsWith('--')) fail(`Unknown migrate option "${arg}".`);positional.push(arg);}- return { positional, json, toSchema };+ return { positional, json, toSchema, output };}async function commandMigrate(args) {@@ -5945,7 +5957,7 @@ async function commandMigrate(args) {|| options.positional.length !== 3|| options.toSchema !== '2') {- fail('Usage: archify migrate workflow <old.json> <new.json> --to-schema 2 [--json] [--repo-root path]');+ fail('Usage: archify migrate workflow <old.json> <new.json> --to-schema 2 [--output portable.html] [--json] [--repo-root path]');}const sourcePath = path.resolve(sourceArgument);@@ -5984,9 +5996,29 @@ async function commandMigrate(args) {verifyAtomicOutput,verifyRegularFileBinding,} = await import('../renderers/shared/atomic-output.mjs');- if (sourceDocument?.meta?.output !== undefined) {+ // `--output` repairs only the durable output field in the migration+ // candidate. It never writes the source and deliberately leaves every+ // other schema and compiler failure visible to the normal migration path.+ let migrationSourceDocument = sourceDocument;+ if (options.output !== undefined) {try {- validateAuthoredOutputPath(sourceDocument.meta.output);+ validateAuthoredOutputPath(options.output);+ } catch (error) {+ reportMigrationFailure({+ preExistingDiagnostics: migrationPathDiagnostics(error, sourcePath, destinationPath),+ });+ return;+ }+ if (sourceDocument?.meta && typeof sourceDocument.meta === 'object' && !Array.isArray(sourceDocument.meta)) {+ migrationSourceDocument = {+ ...sourceDocument,+ meta: { ...sourceDocument.meta, output: options.output },+ };+ }+ }+ if (migrationSourceDocument?.meta?.output !== undefined) {+ try {+ validateAuthoredOutputPath(migrationSourceDocument.meta.output);} catch (error) {reportMigrationFailure({preExistingDiagnostics: migrationPathDiagnostics(error, sourcePath, destinationPath),@@ -5997,7 +6029,7 @@ async function commandMigrate(args) {// Unlike render/validate, migrate has no --quality override. Pin every stage// to the document's durable policy and scrub any ambient profile from the// staged renderer by passing this value explicitly.- const activeQualityProfile = sourceDocument?.meta?.quality_profile || 'standard';+ const activeQualityProfile = migrationSourceDocument?.meta?.quality_profile || 'standard';let sourceDestinationAlias;try {@@ -6023,7 +6055,7 @@ async function commandMigrate(args) {const { migrateWorkflowDocument, serializeMigratedWorkflow } = await import('../migrations/workflow-v2.mjs');let migration;try {- migration = migrateWorkflowDocument(sourceDocument);+ migration = migrateWorkflowDocument(migrationSourceDocument);} catch (error) {migration = {ok: false,@@ -6041,18 +6073,6 @@ async function commandMigrate(args) {return;}- if (sourceDocument?.meta?.output === undefined) {- try {- validateAuthoredOutputPath(sourceDocument?.meta?.output);- } catch (error) {- reportMigrationFailure({- ...migration,- preExistingDiagnostics: migrationPathDiagnostics(error, sourcePath, destinationPath),- });- return;- }- }-const destinationDirectory = path.dirname(destinationPath);let stagingDirectory;let stagingIdentity;diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 61b00fb9..0cd8e43e 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -190,11 +190,15 @@ Archify intentionally separates durable authored paths from command-line paths:Windows spelling restrictions. Every host rejects NUL, unpaired surrogates,and components that exceed its supported bound.-These contracts are not interchangeable: an explicit CLI output does not hide-an invalid durable `meta.output` (including a missing value), and `validate` and `migrate` check-the authored output even when they do not publish to that path. To migrate an-older v1 document that omitted it, add a portable POSIX-relative `.html` path-to `meta.output`; no schema-version change is otherwise required.+These contracts are not interchangeable: an explicit CLI artifact output does+not hide an invalid durable `meta.output` (including a missing value), and+`validate` checks the authored output even when it does not publish to that+path. A workflow v1-to-v2 migration may explicitly receive a portable durable+replacement through `migrate workflow old.json new.json --to-schema 2 --output+reports/diagram.html`; that value is written only to its separate verified v2+destination. It does not repair the source or bypass any non-output schema or+compiler error. For every other repair, add a portable POSIX-relative `.html`+path to `meta.output`; no schema-version change is otherwise required.Use `validate` after every candidate edit. CLI HTML output paths must end in`.html`, including after symbolic-link resolution. Compare receipt paths mustdiff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.mdindex aed5fb82..ae022631 100644--- a/archify/renderers/workflow/README.md+++ b/archify/renderers/workflow/README.md@@ -74,6 +74,17 @@ node archify/bin/archify.mjs migrate workflow old.json new.json --to-schema 2 --Running the command again with its schema-v2 output as the new source is anidempotent verification pass: the destination bytes and geometry stay unchanged.+If a legacy v1 source is blocked solely because `meta.output` is missing or no+longer portable, supply its replacement for the separate v2 destination:++```bash+node archify/bin/archify.mjs migrate workflow old.json new.json --to-schema 2 --output reports/workflow.html --json+```++`--output` must itself be a portable POSIX-relative `.html` path. It updates+only the verified destination candidate; the source bytes remain unchanged and+all non-output schema and compiler diagnostics still block migration.+The command never overwrites the source by default. It maps absolute`via[*][0]`, `labelAt[0]`, and `channelX` values from legacy to solved rankspace, preserves y coordinates unless a reported vertical constraint needsdiff --git a/archify/schemas/README.md b/archify/schemas/README.mdindex 12beacce..e2f1be05 100644--- a/archify/schemas/README.md+++ b/archify/schemas/README.md@@ -112,7 +112,12 @@ output.Workflow supports schema versions 1 and 2. Version 1 remains the fixed-layoutcompatibility contract; version 2 opts into the readable workflow compiler andcan be produced explicitly with `archify migrate workflow ... --to-schema 2`.-The other four diagram schemas keep `schema_version` pinned to `1`.+The other four diagram schemas keep `schema_version` pinned to `1`; they have+no schema-version migration command. For any of the five diagram types, repair+a legacy missing or nonportable `meta.output` in the source and run `validate`.+For a workflow v1-to-v2 migration specifically, `migrate workflow` also accepts+`--output reports/diagram.html` to put that portable value in the separate v2+destination without changing the legacy source.Workflow also accepts optional `semanticChecks`. `allowedRoots` and`allowedTerminals` close the set of intentional graph sources and sinks;@@ -127,8 +132,10 @@ A file that validates today must keep validating and rendering within itsdeclared version throughout the 2.x release line. The explicitly reviewedportable-output hardening is the one exception: older v1 documents that omit`meta.output` must add a portable POSIX-relative `.html` path (for example,-`reports/diagram.html`); an explicit CLI output argument does not replace this-durable authored value. Additive viewer,+`reports/diagram.html`); ordinary explicit CLI output arguments do not replace+this durable authored value. The workflow-only v1-to-v2 migration command may+instead receive that value explicitly as `--output reports/diagram.html`; it+writes the value only to its separate validated destination. Additive viewer,accessibility, and presentation improvements may enhance generated HTML, butthey must not reinterpret authored IR or turn a previously valid profile-lessv1 file into a new hard layout failure. Breaking IR changes require a newdiff --git a/archify/test/workflow-migration.test.mjs b/archify/test/workflow-migration.test.mjsindex 127fd873..e28c23fe 100644--- a/archify/test/workflow-migration.test.mjs+++ b/archify/test/workflow-migration.test.mjs@@ -31,7 +31,7 @@ function sha256(value) {return createHash('sha256').update(value).digest('hex');}-function runMigration(source, destination, { importModule, env } = {}) {+function runMigration(source, destination, { importModule, env, output } = {}) {return spawnSync(process.execPath, [...(importModule ? ['--import', pathToFileURL(importModule).href] : []),cli,@@ -41,6 +41,7 @@ function runMigration(source, destination, { importModule, env } = {}) {destination,'--to-schema','2',+ ...(output !== undefined ? ['--output', output] : []),'--json',], {encoding: 'utf8',@@ -253,6 +254,68 @@ test('CLI atomically commits a capacity-expanded migration and preserves sourceassert.deepEqual(report.newSchemaDiagnostics, []);});+test('CLI migration can repair a missing legacy output only in the v2 destination', () => {+ const source = copyFixture('missing-output-source.workflow.json', (workflow) => {+ delete workflow.meta.output;+ return workflow;+ });+ const destination = path.join(tmp, 'missing-output-destination.workflow.json');+ const sourceBytes = fs.readFileSync(source);++ const withoutReplacement = runMigration(source, destination);+ assert.notEqual(withoutReplacement.status, 0);+ assert.equal(fs.existsSync(destination), false);+ assert.deepEqual(fs.readFileSync(source), sourceBytes);++ const result = runMigration(source, destination, { output: 'migrated/legacy-workflow.html' });+ assert.equal(result.status, 0, result.stderr || result.stdout);+ assert.deepEqual(fs.readFileSync(source), sourceBytes, 'migration must not repair the source in place');+ const migrated = JSON.parse(fs.readFileSync(destination, 'utf8'));+ assert.equal(migrated.meta.output, 'migrated/legacy-workflow.html');+ assert.equal(migrated.schema_version, 2);+ assert.equal(parseJsonOutput(result).ok, true);+});++test('CLI migration repairs an invalid legacy output only with an explicit portable replacement', () => {+ const source = copyFixture('invalid-output-source.workflow.json', (workflow) => {+ workflow.meta.output = '/tmp/legacy-workflow.html';+ return workflow;+ });+ const destination = path.join(tmp, 'invalid-output-destination.workflow.json');+ const sourceBytes = fs.readFileSync(source);++ const result = runMigration(source, destination, { output: 'migrated/portable-workflow.html' });+ assert.equal(result.status, 0, result.stderr || result.stdout);+ assert.deepEqual(fs.readFileSync(source), sourceBytes);+ assert.equal(JSON.parse(fs.readFileSync(destination, 'utf8')).meta.output, 'migrated/portable-workflow.html');++ const rejectedDestination = path.join(tmp, 'invalid-replacement-destination.workflow.json');+ const rejected = runMigration(source, rejectedDestination, { output: '/tmp/not-portable.html' });+ assert.notEqual(rejected.status, 0);+ assert.equal(fs.existsSync(rejectedDestination), false);+ assert.deepEqual(fs.readFileSync(source), sourceBytes);+ assert.ok(parseJsonOutput(rejected).diagnostics.some(({ code }) => code.startsWith('output/')));+});++test('CLI migration replacement does not hide malformed non-output schema errors', () => {+ const source = copyFixture('malformed-non-output-source.workflow.json', (workflow) => {+ delete workflow.meta.title;+ delete workflow.meta.output;+ return workflow;+ });+ const destination = path.join(tmp, 'malformed-non-output-destination.workflow.json');+ const sourceBytes = fs.readFileSync(source);++ const result = runMigration(source, destination, { output: 'migrated/repaired-output.html' });+ assert.notEqual(result.status, 0);+ assert.equal(fs.existsSync(destination), false);+ assert.deepEqual(fs.readFileSync(source), sourceBytes);+ const failure = parseJsonOutput(result);+ assert.ok(failure.diagnostics.some(({ code, subject }) => (+ !code.startsWith('output/') && subject?.path === '/meta'+ )), JSON.stringify(failure.diagnostics, null, 2));+});+test('column-capacity diagnostics do not advertise migration across a quality-profile divergence', () => {const document = profileDivergenceWorkflow();const standard = compileWorkflow({ workflow: document, qualityProfile: 'standard' });