Skip to content

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

fix: honor recovery path boundary contract

tt-a1i833468cda4eb
diff --git a/archify/bin/recover-output.mjs b/archify/bin/recover-output.mjs
index b389d34c..9b842613 100644
--- a/archify/bin/recover-output.mjs
+++ b/archify/bin/recover-output.mjs
@@ -1,26 +1,41 @@
import { recoverRetiredPublication } from '../renderers/shared/atomic-output.mjs';
-function usage() {
- process.stderr.write('Usage: node bin/recover-output.mjs <private-recovery-directory> [--json]\n');
+function usage(stream = process.stderr) {
+ stream.write('Usage: node bin/recover-output.mjs <private-recovery-directory> [--json]\n');
}
const args = process.argv.slice(2);
-const json = args.at(-1) === '--json';
-if (json) args.pop();
-if (args.length !== 1) {
- usage();
- process.exitCode = 64;
+if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+ usage(process.stdout);
} else {
- const result = recoverRetiredPublication(args[0]);
- if (json) {
- process.stdout.write(`${JSON.stringify(result)}\n`);
+ let json = false;
+ let recoveryDirectory;
+ let invalid = false;
+ for (const argument of args) {
+ if (argument === '--json' && !json) {
+ json = true;
+ } else if (argument.startsWith('-') || recoveryDirectory !== undefined) {
+ invalid = true;
+ } else {
+ recoveryDirectory = argument;
+ }
+ }
+
+ if (invalid || recoveryDirectory === undefined) {
+ usage();
+ process.exitCode = 64;
} else {
- const reason = result.reason?.code || 'publication-recovery-unknown';
- process.stdout.write(`${result.status}: ${reason}\n`);
+ const result = recoverRetiredPublication(recoveryDirectory);
+ if (json) {
+ process.stdout.write(`${JSON.stringify(result)}\n`);
+ } else {
+ const reason = result.reason?.code || 'publication-recovery-unknown';
+ process.stdout.write(`${result.status}: ${reason}\n`);
+ }
+ // A complete prior recovery is idempotent. A preserved target is a safe,
+ // deliberate non-action that needs the operator to inspect the claimant.
+ process.exitCode = ['recovered', 'absent'].includes(result.status)
+ ? 0
+ : result.status === 'preserved' ? 2 : 1;
}
- // A complete prior recovery is idempotent. A preserved target is a safe,
- // deliberate non-action that needs the operator to inspect the claimant.
- process.exitCode = ['recovered', 'absent'].includes(result.status)
- ? 0
- : result.status === 'preserved' ? 2 : 1;
}
diff --git a/archify/renderers/shared/atomic-output.mjs b/archify/renderers/shared/atomic-output.mjs
index de695e20..8895d70d 100644
--- a/archify/renderers/shared/atomic-output.mjs
+++ b/archify/renderers/shared/atomic-output.mjs
@@ -1645,7 +1645,9 @@ function parsePublicationRecoveryRecord(buffer) {
&& validEntry
&& typeof target.commitPath === 'string' && path.isAbsolute(target.commitPath)
&& typeof target.parentPath === 'string' && path.isAbsolute(target.parentPath)
+ // path-contract-allow: lexical-capability -- A record must exactly decompose the captured canonical target spelling.
&& typeof target.name === 'string' && target.name === path.basename(target.commitPath)
+ // path-contract-allow: lexical-capability -- A record must exactly decompose the captured canonical target spelling.
&& target.parentPath === path.dirname(target.commitPath)
&& parseDecimal(target.parentDevice) !== null && parseDecimal(target.parentInode) !== null;
if (!valid) return relation('unknown', 'publication-recovery-record-invalid');
@@ -1689,6 +1691,7 @@ function verifyPublicationRecoveryDirectory(directory, metadata, record) {
recoveryDirectory: directory,
});
}
+ // path-contract-allow: lexical-capability -- The generated private-directory component is an exact record-bound capability.
if (path.basename(directory) !== record.recovery.name
|| !parentMetadata.isDirectory()
|| parentMetadata.dev !== record.target.parentDevice
@@ -1712,8 +1715,12 @@ function verifyRetiredPublicationSlot(record) {
const { target } = record;
const slot = captureWriteSlot(target.requestedPath);
if (slot.status !== 'captured') return slot;
- if (slot.slot.commitPath !== target.commitPath
- || slot.slot.parentPath !== target.parentPath
+ // path-contract-allow: lexical-capability -- The recaptured canonical commit spelling must exactly match the recorded capability.
+ const commitPathChanged = slot.slot.commitPath !== target.commitPath;
+ // path-contract-allow: lexical-capability -- The recaptured canonical parent spelling must exactly match the recorded capability.
+ const parentPathChanged = slot.slot.parentPath !== target.parentPath;
+ if (commitPathChanged
+ || parentPathChanged
|| slot.slot.name !== target.name
|| slot.slot.parentDevice !== target.parentDevice
|| slot.slot.parentInode !== target.parentInode) {
diff --git a/archify/test/atomic-output-recovery.test.mjs b/archify/test/atomic-output-recovery.test.mjs
index 39bb07d8..4d9d1773 100644
--- a/archify/test/atomic-output-recovery.test.mjs
+++ b/archify/test/atomic-output-recovery.test.mjs
@@ -102,6 +102,22 @@ function runRecovery(directory) {
};
}
+test('recovery CLI help is successful and unknown options do not name a recovery directory', () => {
+ for (const option of ['--help', '-h']) {
+ const result = spawnSync(process.execPath, [recoveryCli, option], { encoding: 'utf8' });
+ assert.equal(result.status, 0, result.stderr);
+ assert.match(result.stdout, /^Usage: node bin\/recover-output\.mjs/m);
+ assert.equal(result.stderr, '');
+ }
+
+ const result = spawnSync(process.execPath, [recoveryCli, '--unexpected-option'], {
+ encoding: 'utf8',
+ });
+ assert.equal(result.status, 64, result.stderr);
+ assert.equal(result.stdout, '');
+ assert.match(result.stderr, /^Usage: node bin\/recover-output\.mjs/m);
+});
+
function portableRecoveryFixture(t) {
const root = workspace(t, 'archify-portable-publication-recovery-');
const output = path.join(root, 'diagram.html');