Skip to content

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

fix: preserve architecture delta pairs

tt-a1i7da369cd6651
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 67869a79..3e9fe7c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
- **Revision-verified Repository Evidence Passport.** Architecture diagrams can opt into public GitHub source links by declaring a repository URL, a full commit SHA, and one to three repo-relative sources per component, then passing `--repo-root` to `render`, `deliver`, `preview`, or `validate`. Archify verifies the local origin, commit, blobs, and optional line ranges before publishing; verified links appear in Semantic Passport and Node Finder while staying outside the canonical SVG and every visual export. Plain diagrams remain the default, other diagram modes reject the option, and private or unpinned evidence is deliberately out of scope.
### Fixed
+- Architecture Delta now preflights the HTML and receipt destinations as one pair, backs up both existing regular files, and restores the pair if either commit fails. A blocked receipt target can no longer report failure after silently replacing the previous trusted HTML.
- The landing Live Proof now runs in a least-privilege script-only sandbox and starts its bounded chapter in the artifact's first load. This removes parent/child DOM reach-through and avoids a browser-visible `MutationObserver.observe(null)` injection race while preserving one-shot and reduced-motion behavior.
- Existing custom templates remain compatible when repository evidence is unused; only the opt-in evidence path requires the new HTML payload slot. Evidence paths reject control characters, and line verification no longer treats a trailing newline as an extra source line.
diff --git a/archify.zip b/archify.zip
index 1718cffa..1470293a 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index ee67845d..0d0da868 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -297,6 +297,82 @@ function compareReceiptPath(outputPath) {
return extension ? `${outputPath.slice(0, -extension.length)}.receipt.json` : `${outputPath}.receipt.json`;
}
+function compareCommitError(message, code, details = {}) {
+ const error = new Error(message);
+ error.compareStage = 'commit';
+ error.compareCode = code;
+ error.compareDetails = details;
+ return error;
+}
+
+function commitComparePair({ htmlCandidate, receiptCandidate, outputPath, receiptPath, stagingDirectory }) {
+ const targets = [
+ { label: 'HTML artifact', target: outputPath, candidate: htmlCandidate, backup: path.join(stagingDirectory, '.previous-output') },
+ { label: 'receipt', target: receiptPath, candidate: receiptCandidate, backup: path.join(stagingDirectory, '.previous-receipt') },
+ ];
+
+ // Preflight the whole pair before moving either trusted target. This avoids
+ // replacing the HTML and only then discovering that its receipt destination
+ // cannot be committed (for example, because it is a directory).
+ for (const item of targets) {
+ if (!fs.existsSync(item.target)) continue;
+ const existing = fs.lstatSync(item.target);
+ if (!existing.isFile()) {
+ throw compareCommitError(
+ `Could not commit Architecture Delta: existing ${item.label} target is not a regular file.`,
+ 'delta/commit-target',
+ {
+ target: path.basename(item.target),
+ targetType: existing.isDirectory() ? 'directory' : 'non-file',
+ supportedFixes: [`choose a regular-file path for the ${item.label}`],
+ },
+ );
+ }
+ }
+
+ const backedUp = [];
+ const committed = [];
+ try {
+ for (const item of targets) {
+ if (!fs.existsSync(item.target)) continue;
+ fs.renameSync(item.target, item.backup);
+ backedUp.push(item);
+ }
+ for (const item of targets) {
+ fs.renameSync(item.candidate, item.target);
+ committed.push(item);
+ }
+ } catch (cause) {
+ const rollbackErrors = [];
+ for (const item of [...committed].reverse()) {
+ try {
+ fs.rmSync(item.target, { force: true });
+ } catch (error) {
+ rollbackErrors.push(`${item.label}: remove failed (${error.message})`);
+ }
+ }
+ for (const item of [...backedUp].reverse()) {
+ try {
+ if (fs.existsSync(item.target)) fs.rmSync(item.target, { force: true });
+ fs.renameSync(item.backup, item.target);
+ } catch (error) {
+ rollbackErrors.push(`${item.label}: restore failed (${error.message})`);
+ }
+ }
+ throw compareCommitError(
+ 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.',
+ 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'],
+ },
+ );
+ }
+}
+
function renderValidatedArchitecture(inputPath, outputPath, quality, repoRoot) {
const render = runNode([rendererPath('architecture'), inputPath, outputPath], {
stdio: 'pipe',
@@ -500,8 +576,7 @@ async function commandCompare(args) {
};
fs.writeFileSync(receiptCandidate, `${JSON.stringify(finalReceipt, null, 2)}\n`);
- fs.renameSync(htmlCandidate, outputPath);
- fs.renameSync(receiptCandidate, receiptPath);
+ commitComparePair({ htmlCandidate, receiptCandidate, outputPath, receiptPath, stagingDirectory });
if (options.json) console.log(JSON.stringify(finalReceipt, null, 2));
else {
console.log(`compared architecture ${outputPath}`);
@@ -511,6 +586,14 @@ async function commandCompare(args) {
} catch (error) {
if (error instanceof ArchitectureDeltaError) {
reportCompareFailure({ json: options.json, stage: 'artifact', error: error.message, code: error.code, details: error.details });
+ } else if (error.compareStage === 'commit') {
+ reportCompareFailure({
+ json: options.json,
+ stage: error.compareStage,
+ error: error.message,
+ code: error.compareCode,
+ details: error.compareDetails,
+ });
} else {
reportCompareFailure({ json: options.json, stage: 'internal', error: 'Architecture compare failed before commit.', code: 'delta/internal', details: { reason: error.message } });
}
diff --git a/archify/test/architecture-delta.test.mjs b/archify/test/architecture-delta.test.mjs
index 01a0e108..ba1b8e9a 100644
--- a/archify/test/architecture-delta.test.mjs
+++ b/archify/test/architecture-delta.test.mjs
@@ -192,3 +192,24 @@ test('compare failure preserves an existing trusted artifact', () => {
assert.equal(receipt.diagnostics[0].code, 'delta/relationship-id-required');
assert.equal(fs.existsSync(path.join(tmp, 'preserved.receipt.json')), false);
});
+
+test('compare commit preflights both targets before replacing a trusted pair', () => {
+ const caseRoot = fs.mkdtempSync(path.join(tmp, 'pair-target-'));
+ const output = path.join(caseRoot, 'review.html');
+ const receiptPath = path.join(caseRoot, 'review.receipt.json');
+ fs.writeFileSync(output, 'trusted html');
+ fs.mkdirSync(receiptPath);
+
+ const result = run([
+ 'compare', 'architecture', baseFixture, headFixture, output,
+ '--receipt', receiptPath, '--json',
+ ]);
+
+ assert.notEqual(result.status, 0);
+ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted html');
+ assert.equal(fs.statSync(receiptPath).isDirectory(), true);
+ const failure = JSON.parse(result.stdout);
+ assert.equal(failure.stage, 'commit');
+ assert.equal(failure.diagnostics[0].code, 'delta/commit-target');
+ assert.equal(failure.diagnostics[0].evidence.targetType, 'directory');
+});