Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(migrate): repair legacy workflow outputs explicitly

tt-a1i0a2d2fde5c01
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index 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.md
index 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 must
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.md
index 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 an
idempotent 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 rank
space, preserves y coordinates unless a reported vertical constraint needs
diff --git a/archify/schemas/README.md b/archify/schemas/README.md
index 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-layout
compatibility contract; version 2 opts into the readable workflow compiler and
can 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 its
declared version throughout the 2.x release line. The explicitly reviewed
portable-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, but
they must not reinterpret authored IR or turn a previously valid profile-less
v1 file into a new hard layout failure. Breaking IR changes require a new
diff --git a/archify/test/workflow-migration.test.mjs b/archify/test/workflow-migration.test.mjs
index 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 source
assert.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' });