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(compare): retain backups after incomplete rollback (#439)
逺坂凛4e45fe77a31b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d267195e..c27f5ebb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo> Development identity: `v2.17.0-dev.1`. Not a stable release.### Fixed+- **Compare rollback recovery (#438).** If restoring a previous output fails, compare preserves its recovery directory and reports backup-to-target paths instead of deleting the remaining backups during cleanup.- **固定提交的来源校验 (#420)。** 校验忽略本地 Git replacement refs,始终读取指定提交的原始对象,避免替换后的文件或行范围造成误接受或误拒绝;保留原有来源链接、诊断与用户 Git 配置。- **Compare 输入快照一致性 (#400)。** 原始输入校验使用首次读取的字节快照,使其与回执哈希和差异计算保持一致;读取后原文件发生变化不会影响本次比较,非法原始字段仍会被拒绝。- **DSH plugin refresh.** Adapter 0.2.0 pins the current Archify development snapshot, includes the newer runtime and CLI fixes, and targets DSH 0.1.2-rc.1. Release metadata replaces the frozen 0.1.0 packaging source; the tarball uses the canonical clean-Skill stager and documents independent plugin upgrades.diff --git a/archify.zip b/archify.zipindex 702ce0ec..516a0742 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex 07ad91ba..9ea8ab9a 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -392,6 +392,7 @@ function commitComparePair({ htmlCandidate, receiptCandidate, outputPath, receip}} catch (cause) {const rollbackErrors = [];+ const recoveryFiles = [];for (const item of [...committed].reverse()) {try {fs.rmSync(item.target, { force: true });@@ -405,17 +406,27 @@ function commitComparePair({ htmlCandidate, receiptCandidate, outputPath, receipfs.renameSync(item.backup, item.target);} catch (error) {rollbackErrors.push(`${item.label}: restore failed (${error.message})`);+ // Track failed restoration rather than probing existence: a permission+ // error must not make cleanup discard a potentially recoverable backup.+ recoveryFiles.push({ backup: item.backup, target: item.target });}}throw compareCommitError(- rollbackErrors.length+ (rollbackErrors.length? 'Architecture Delta pair commit failed and its previous files could not be fully restored.'- : 'Architecture Delta pair commit failed; the previous files were restored.',+ : 'Architecture Delta pair commit failed; the previous files were restored.')+ + (recoveryFiles.length ? ` Recovery directory retained at ${stagingDirectory}.` : ''),rollbackErrors.length ? 'delta/commit-rollback-failed' : 'delta/commit-failed',{reason: cause.message,...(rollbackErrors.length ? { rollbackErrors } : {}),- supportedFixes: ['check that both output paths are writable regular files, then retry'],+ ...(recoveryFiles.length ? { recoveryDirectory: stagingDirectory, recoveryFiles } : {}),+ supportedFixes: recoveryFiles.length+ ? [+ ...recoveryFiles.map(({ backup, target }) => `resolve the filesystem error, inspect the current target, then restore ${JSON.stringify(backup)} to ${JSON.stringify(target)} before retrying`),+ 'remove the recovery directory only after the previous files have been recovered and verified',+ ]+ : ['check that both output paths are writable regular files, then retry'],},);}@@ -582,6 +593,7 @@ async function commandCompare(args) {const canonicalHeadInput = path.join(stagingDirectory, 'head.architecture.json');const htmlCandidate = path.join(stagingDirectory, path.basename(outputPath));const receiptCandidate = path.join(stagingDirectory, path.basename(receiptPath));+ let preserveRecoveryDirectory = false;try {let baseResult;@@ -745,6 +757,7 @@ async function commandCompare(args) {if (error instanceof ArchitectureDeltaError) {reportCompareFailure({ json: options.json, stage: 'artifact', error: error.message, code: error.code, details: error.details });} else if (error.compareStage === 'commit') {+ preserveRecoveryDirectory = Boolean(error.compareDetails?.recoveryFiles?.length);reportCompareFailure({json: options.json,stage: error.compareStage,@@ -757,7 +770,7 @@ async function commandCompare(args) {}} finally {try {- fs.rmSync(stagingDirectory, { recursive: true, force: true });+ if (!preserveRecoveryDirectory) fs.rmSync(stagingDirectory, { recursive: true, force: true });} catch (error) {console.error(`Warning: could not remove compare staging directory: ${error.message}`);}diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 301d7df7..11d0dfe6 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -32,6 +32,24 @@ The delivery interface exposes three separate claims:Passing one claim never implies either of the others. Never claim that the deterministic receipt includes visual review. It does not include browser evidence either.+## Recovering a failed comparison++`compare` commits an HTML artifact and its JSON receipt as a pair. If that commit+fails, it attempts to restore the previous files. A complete rollback removes+the temporary directory as usual.++If a previous file cannot be restored, compare exits non-zero with+`delta/commit-rollback-failed` and retains the recovery directory. In the JSON+failure receipt, `diagnostics[].evidence.recoveryDirectory` identifies that+directory and `recoveryFiles` lists `{ backup, target }` paths for the files whose+restoration failed. Human-readable diagnostics also print the recovery paths.++Resolve the filesystem error, inspect the current targets, and restore each+listed backup to its corresponding target before retrying. Keep the recovery+directory until both previous files have been recovered and verified; it can+also contain rejected candidate files, which must not be mistaken for backups.+Successful comparisons and failures before commit retain their normal cleanup.+## Automated browser evidenceAfter delivery, inspect the exact trusted HTML without rerendering or modifyingdiff --git a/archify/test/architecture-compare-recovery.test.mjs b/archify/test/architecture-compare-recovery.test.mjsnew file mode 100644index 00000000..014564e4--- /dev/null+++ b/archify/test/architecture-compare-recovery.test.mjs@@ -0,0 +1,157 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { spawnSync } from 'node:child_process';+import { createHash } from 'node:crypto';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const cli = path.join(skillRoot, 'bin/archify.mjs');+const base = path.join(skillRoot, 'examples/checkout-platform.base.architecture.json');+const head = path.join(skillRoot, 'examples/checkout-platform.head.architecture.json');+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');+const cases = [+ { name: 'successful replacement cleans staging', failures: [] },+ { name: 'receipt commit failure restores the entire old pair', failures: ['commit-receipt'] },+ { name: 'HTML restore failure retains its old backup', failures: ['commit-receipt', 'restore-html'], retained: ['html'] },+ { name: 'receipt restore failure retains its old backup', failures: ['commit-receipt', 'restore-receipt'], retained: ['receipt'] },+ { name: 'both restore failures retain both old backups', failures: ['commit-receipt', 'restore-receipt', 'restore-html'], retained: ['html', 'receipt'] },+ { name: 'second backup failure restores the first target', failures: ['backup-receipt'] },+ { name: 'second backup and HTML restore failures retain only HTML', failures: ['backup-receipt', 'restore-html'], retained: ['html'] },+ { name: 'transient removal failure leaves no backup after successful restoration', failures: ['commit-receipt', 'remove-html'] },+];++function fixture(t) {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-compare-recovery-'));+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));+ const targets = { html: path.join(root, 'review.html'), receipt: path.join(root, 'review.receipt.json') };+ const run = (preload, newHead = head, json = true) => spawnSync(process.execPath, [+ ...(preload ? ['--require', preload] : []), cli, 'compare', 'architecture', base, newHead,+ targets.html, '--receipt', targets.receipt, ...(json ? ['--json'] : []),+ ], { cwd: skillRoot, encoding: 'utf8', timeout: 30000 });+ // Establish a genuinely valid old pair, distinct from the candidate revision.+ const initial = run(undefined, base);+ assert.ifError(initial.error);+ assert.equal(initial.status, 0, initial.stderr || initial.stdout);+ const old = Object.fromEntries(Object.entries(targets).map(([key, file]) => [key, fs.readFileSync(file)]));+ assert.equal(JSON.parse(old.receipt).artifact.sha256, hash(old.html));+ return { root, targets, old, run };+}++test('compare recovery: human diagnostics identify the retained backup and target', { timeout: 70000 }, (t) => {+ const data = fixture(t);+ const { preload } = inject(data, ['commit-receipt', 'restore-html']);+ const result = data.run(preload, head, false);+ assert.ifError(result.error);+ assert.equal(result.status, 1);+ assert.equal(result.stdout.trim(), '');+ const directories = fs.readdirSync(data.root).filter((name) => name.startsWith('.archify-compare-'));+ assert.equal(directories.length, 1);+ const recoveryDirectory = path.join(data.root, directories[0]);+ const backup = path.join(recoveryDirectory, '.previous-output');+ assert.ok(result.stderr.includes(recoveryDirectory));+ assert.ok(result.stderr.includes(JSON.stringify(backup)));+ assert.ok(result.stderr.includes(JSON.stringify(data.targets.html)));+ assert.deepEqual(fs.readFileSync(backup), data.old.html);+});++function inject(data, failures) {+ const preload = path.join(data.root, 'fail-compare-commit.cjs');+ const log = path.join(data.root, 'injected.jsonl');+ fs.writeFileSync(preload, `+ const fs = require('node:fs');+ const path = require('node:path');+ const root = ${JSON.stringify(data.root)};+ const targets = ${JSON.stringify(data.targets)};+ const wanted = new Set(${JSON.stringify(failures)});+ const fired = new Set();+ const rename = fs.renameSync;+ const remove = fs.rmSync;+ const inside = value => typeof value === 'string' && value.startsWith(root + path.sep);+ const staging = value => inside(value) && path.basename(path.dirname(value)).startsWith('.archify-compare-');+ function failOnce(action) {+ if (!wanted.has(action) || fired.has(action)) return;+ fired.add(action);+ fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify(action) + '\\n');+ const error = new Error('injected ' + action);+ error.code = 'EACCES';+ throw error;+ }+ fs.renameSync = function(source, target) {+ if (inside(source) && inside(target)) {+ if (source === targets.receipt && staging(target)) failOnce('backup-receipt');+ if (staging(source) && target === targets.receipt && path.basename(source) === path.basename(target)) failOnce('commit-receipt');+ if (staging(source) && path.basename(source) === '.previous-output' && target === targets.html) failOnce('restore-html');+ if (staging(source) && path.basename(source) === '.previous-receipt' && target === targets.receipt) failOnce('restore-receipt');+ }+ return rename.apply(this, arguments);+ };+ fs.rmSync = function(target) {+ if (target === targets.html && fired.has('commit-receipt')) failOnce('remove-html');+ return remove.apply(this, arguments);+ };+ `);+ return { preload, log };+}++for (const scenario of cases) {+ test(`compare recovery: ${scenario.name}`, { timeout: 70000 }, (t) => {+ const data = fixture(t);+ const { preload, log } = inject(data, scenario.failures);+ const result = data.run(preload);+ assert.ifError(result.error);+ const observed = fs.existsSync(log) ? fs.readFileSync(log, 'utf8').trim().split('\n').map(JSON.parse) : [];+ assert.deepEqual(observed.sort(), [...scenario.failures].sort(), 'every requested fault must fire exactly once');+ const staging = fs.readdirSync(data.root).filter((name) => name.startsWith('.archify-compare-'));+ const response = JSON.parse(result.stdout);+ if (!scenario.failures.length) {+ assert.equal(result.status, 0, result.stderr || result.stdout);+ assert.equal(response.ok, true);+ const nextHtml = fs.readFileSync(data.targets.html);+ assert.notEqual(hash(nextHtml), hash(data.old.html));+ assert.equal(JSON.parse(fs.readFileSync(data.targets.receipt, 'utf8')).artifact.sha256, hash(nextHtml));+ assert.deepEqual(staging, []);+ return;+ }++ assert.notEqual(result.status, 0);+ assert.equal(response.ok, false);+ assert.equal(response.stage, 'commit');+ const retained = scenario.retained || [];+ const incompleteRollback = retained.length > 0 || scenario.failures.includes('remove-html');+ const diagnostic = response.diagnostics[0];+ assert.equal(diagnostic.code, incompleteRollback ? 'delta/commit-rollback-failed' : 'delta/commit-failed');+ const evidence = diagnostic.evidence;+ for (const key of ['html', 'receipt'].filter((key) => !retained.includes(key))) {+ const restored = fs.readFileSync(data.targets[key]);+ assert.deepEqual(restored, data.old[key], `${key} must be restored byte-for-byte`);+ assert.equal(hash(restored), hash(data.old[key]));+ }+ if (!retained.length) {+ assert.deepEqual(staging, [], 'clean up when no recovery material remains');+ assert.equal(evidence.recoveryDirectory, undefined);+ assert.deepEqual(evidence.recoveryFiles || [], []);+ return;+ }++ assert.equal(typeof evidence.recoveryDirectory, 'string', 'report the surviving recovery directory');+ assert.ok(path.isAbsolute(evidence.recoveryDirectory));+ assert.equal(path.dirname(evidence.recoveryDirectory), data.root);+ assert.deepEqual(staging, [path.basename(evidence.recoveryDirectory)]);+ assert.ok(response.error.includes(evidence.recoveryDirectory), 'human-readable error must identify recovery location');+ assert.ok(Array.isArray(evidence.recoveryFiles));+ assert.equal(evidence.recoveryFiles.length, retained.length);+ assert.deepEqual(evidence.recoveryFiles.map(({ target }) => target).sort(), retained.map((key) => data.targets[key]).sort());+ for (const { backup, target } of evidence.recoveryFiles) {+ assert.ok(path.isAbsolute(backup));+ assert.equal(path.dirname(backup), evidence.recoveryDirectory);+ const key = Object.keys(data.targets).find((key) => data.targets[key] === target);+ const saved = fs.readFileSync(backup);+ assert.deepEqual(saved, data.old[key], `${key} backup must remain recoverable byte-for-byte`);+ assert.equal(hash(saved), hash(data.old[key]));+ assert.equal(fs.existsSync(target), false, 'failed restoration must not be reported as a committed target');+ }+ });+}