Skip to content

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

Merge PR #455 onto dev and cover interrupted delivery recovery

sunsunsundcc1db983f1b
diff --cc CHANGELOG.md
index 1d9fae2b,89a9183b..bca21143
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -4,20 -4,10 +4,21 @@@ All notable changes are documented here
## [Unreleased]
+### Improved reading
+
+- Showcase sequence message names use larger primary type and matching label plates; real browser readability checks now include message labels.
+
> Development identity: `v2.17.0-dev.1`. Not a stable release.
+### Added
+- **Hermes Agent community opt-in.** `integrations/hermes-agent` is a Skill-only directory plugin: it registers the existing Node Archify `SKILL.md` for Hermes. The documented install is `hermes skills install skills-sh/tt-a1i/archify/archify -y` (published GitHub Skill). A checkout symlink remains the local-dev path. Hermes still runs `node bin/archify.mjs`. This is not an official Nous product and is not an agent-switcher target.
+- **GitHub Copilot agent-switcher target.** The Start page agent switcher, README EN/ZH quick start, and landing copy add `github-copilot` alongside `cursor`, `codex`, `claude-code`, and `opencode`. It installs the same checked Skill and zero-dependency renderers via `npx skills add tt-a1i/archify --skill archify --agent github-copilot ...`; no vendor-specific fork, renderer, or schema behavior was added.
+- **Repository evidence for every diagram type (#59).** `meta.repository` and node `sources` are now accepted by Workflow, Sequence, Data Flow, and Lifecycle as well as Architecture, and `--repo-root` reaches `render`, `validate`, `deliver`, and `preview` for all five. Each mode authors sources on its own node collection (`components`, `nodes`, `participants`, `states`) while verification is unchanged: Git top level, origin match, commit, blob, path containment, and line bounds all still have to hold, GitHub, Gitee, and `link_mode: "local-only"` repositories behave identically in every mode, and the verified payload stays keyed by node id. Architecture output is unchanged and the `repository-evidence/type-unsupported` diagnostic is removed as unreachable.
+
### Fixed
+- **Conservative VS15 text-width estimates.** Text-presentation selectors retain the base character's estimated width instead of forcing every sequence to one unit. This prevents wide labels, including CJK text whose font ignores VS15, from passing layout checks at half their estimated width. Actual glyph widths remain font-dependent; some text-presentation labels may now need more space. VS16 emoji estimates and text without selectors are unchanged.
+- **Readable renderer failures.** `render` and direct renderer entry points format classified input, schema, layout, and output failures without Node stacks. Filesystem failures identify the failing operation instead of labelling output errors as unreadable input; successful artifact bytes and existing validation/delivery receipt formats remain unchanged.
+ - **Preview forced shutdown (#453).** A second Ctrl-C closes unfinished HTTP connections as well as active delivery processes, allowing staging cleanup while preserving the last verified artifact.
- **Architecture Delta baseline arrowheads (#433).** Removed and rerouted baseline relationships retain their marker definitions in the composed Delta SVG, preserving their authored direction alongside current relationships.
- **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 配置。
diff --cc archify.zip
index c9aaf761,afd5933e..6d8fb490
Binary files differ
diff --cc archify/references/delivery-contract.md
index 0b3f8409,46ce1056..61b00fb9
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@@ -371,7 -98,7 +371,7 @@@ Preview watches one explicit input on l
The preview runtime ships inside the zero-dependency Skill ZIP and must work without `node_modules`.
- Never start it by default. Do not use it for CI, unattended agents, remote sharing, or mobile use. `--no-open` is only for a user who will open the printed local URL or for loop testing. Stop it with Ctrl-C before handoff. Server state, port, source path, diagnostics, error text, and reload tokens must never enter the generated artifact or any export.
-Never start it by default. Do not use it for CI, unattended agents, remote sharing, or mobile use. `--no-open` is only for a user who will open the printed local URL or for loop testing. Stop it with Ctrl-C before handoff. The first Ctrl-C drains the active delivery without publishing it; a second Ctrl-C forces shutdown of both delivery processes and HTTP connections, including incomplete requests. Shutdown preserves the last verified artifact and removes preview staging files. Server state, port, source path, diagnostics, error text, and reload tokens must never enter the generated artifact or any export.
++Never start it by default. Do not use it for CI, unattended agents, remote sharing, or mobile use. `--no-open` is only for a user who will open the printed local URL or for loop testing. Stop it with Ctrl-C before handoff. The first Ctrl-C drains the active delivery without publishing it; a second Ctrl-C forces shutdown of both delivery processes and HTTP connections, including incomplete requests. Shutdown preserves the last verified artifact and removes only staging files whose ownership can be verified. If delivery is interrupted before its receipt reaches Preview, unconfirmed files and recovery material may remain in the private staging directory; shutdown does not recursively delete unknown contents. Server state, port, source path, diagnostics, error text, and reload tokens must never enter the generated artifact or any export.
## Perceptual delivery gate
diff --cc archify/test/preview-force-stop.test.mjs
index 00000000,5659dcad..7ab2f2a0
mode 000000,100644..100644
--- a/archify/test/preview-force-stop.test.mjs
+++ b/archify/test/preview-force-stop.test.mjs
@@@ -1,0 -1,184 +1,246 @@@
+ import assert from 'node:assert/strict';
+ import { spawn } from 'node:child_process';
+ import fs from 'node:fs';
+ import http from 'node:http';
+ import net from 'node:net';
+ import os from 'node:os';
+ import path from 'node:path';
+ import { fileURLToPath } from 'node:url';
+ import test from 'node:test';
+
+ import { startPreview } from '../bin/preview.mjs';
+
+ const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+ async function bounded(promise, message, timeout = 1500) {
+ let timer;
+ try {
+ return await Promise.race([
+ promise,
+ new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), timeout); }),
+ ]);
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+
+ async function until(predicate, message) {
+ const deadline = Date.now() + 8000;
+ while (!await predicate()) {
+ if (Date.now() >= deadline) throw new Error(message);
+ await delay(20);
+ }
+ }
+
+ function fixture() {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-preview-force-'));
+ const input = path.join(root, 'input.json');
+ const output = path.join(root, 'output.html');
+ fs.copyFileSync(path.join(skillRoot, 'examples/web-app.architecture.json'), input);
+ return { root, input, output };
+ }
+
+ async function partialRequest(url) {
+ const target = new URL(url);
+ const socket = net.connect(Number(target.port), target.hostname);
+ // A forced server close can reset the peer on some platforms.
+ socket.on('error', () => {});
+ await bounded(new Promise((resolve) => socket.once('connect', resolve)), 'client did not connect');
+ socket.write('GET /state HTTP/1.1\r\n');
+ // Let the server receive the partial header before asking it to stop.
+ await delay(60);
+ return socket;
+ }
+
+ function assertClean(data, previous) {
+ assert.deepEqual(fs.readFileSync(data.output), previous, 'shutdown changed the last artifact');
+ assert.deepEqual(fs.readdirSync(data.root).filter((name) => name.startsWith('.archify-preview-')), []);
+ }
+
+ for (const gracefulFirst of [false, true]) {
+ test(`preview: ${gracefulFirst ? 'escalated' : 'direct'} force closes an unfinished HTTP request`, { timeout: 12000 }, async () => {
+ const data = fixture();
+ let preview;
+ let socket;
+ try {
+ preview = await startPreview({ ...data, type: 'architecture', open: false });
+ await until(() => preview.state().status === 'verified', 'initial delivery did not verify');
+ const previous = fs.readFileSync(data.output);
+ socket = await partialRequest(preview.url);
+ let ordinaryStop;
+ if (gracefulFirst) {
+ ordinaryStop = preview.stop();
+ const completed = await Promise.race([ordinaryStop.then(() => true), delay(60).then(() => false)]);
+ assert.equal(completed, false, 'ordinary stop should still wait for the active request');
+ }
+ await bounded(preview.stop({ force: true }), 'force waited for an unfinished HTTP request');
+ if (ordinaryStop) await ordinaryStop;
+ await preview.closed;
+ await preview.stop({ force: true });
+ await preview.stop();
+ assertClean(data, previous);
+ await assert.rejects(fetch(preview.url));
+ } finally {
+ socket?.destroy();
+ if (preview) await preview.stop({ force: true });
+ fs.rmSync(data.root, { recursive: true, force: true });
+ }
+ });
+ }
+
+ test('preview: force closes SSE clients and remains idempotent', { timeout: 12000 }, async () => {
+ const data = fixture();
+ let preview;
+ let request;
+ let response;
+ try {
+ preview = await startPreview({ ...data, type: 'architecture', open: false });
+ await until(() => preview.state().status === 'verified', 'initial delivery did not verify');
+ const previous = fs.readFileSync(data.output);
+ response = await bounded(new Promise((resolve, reject) => {
+ request = http.get(new URL('/events', preview.url), resolve);
+ request.on('error', reject);
+ }), 'SSE did not connect');
+ response.on('error', () => {});
+ const peerClosed = new Promise((resolve) => response.once('close', resolve));
+ response.resume();
+ await bounded(Promise.all([preview.stop({ force: true }), preview.stop({ force: true })]), 'SSE blocked force');
+ await bounded(peerClosed, 'SSE peer stayed open');
+ await preview.stop();
+ assertClean(data, previous);
+ } finally {
+ response?.destroy();
+ request?.destroy();
+ if (preview) await preview.stop({ force: true });
+ fs.rmSync(data.root, { recursive: true, force: true });
+ }
+ });
+
+ test('preview: force closes HTTP while killing an active delivery without publishing it', { timeout: 12000 }, async () => {
+ const data = fixture();
+ const ready = path.join(data.root, 'child.ready');
+ const deliveryCli = path.join(data.root, 'hung-delivery.mjs');
+ const previous = Buffer.from('<!doctype html><title>Previous artifact</title>');
+ fs.writeFileSync(data.output, previous);
+ fs.writeFileSync(deliveryCli, `import fs from 'node:fs';\nprocess.on('SIGTERM', () => {});\nfs.writeFileSync(${JSON.stringify(ready)}, String(process.pid));\nsetInterval(() => {}, 1000);\n`);
+ let preview;
+ let socket;
+ try {
+ preview = await startPreview({ ...data, type: 'architecture', open: false, deliveryCli, stopGraceMs: 5000 });
+ await until(() => fs.existsSync(ready), 'delivery child did not start');
+ socket = await partialRequest(preview.url);
+ const ordinaryStop = preview.stop();
+ await bounded(preview.stop({ force: true }), 'force did not drain both child and socket');
+ await ordinaryStop;
+ assertClean(data, previous);
+ assert.throws(() => process.kill(Number(fs.readFileSync(ready, 'utf8')), 0), { code: 'ESRCH' });
+ } finally {
+ socket?.destroy();
+ if (preview) await preview.stop({ force: true });
+ fs.rmSync(data.root, { recursive: true, force: true });
+ }
+ });
+
+ // Windows does not deliver child.kill('SIGINT') as a console Ctrl-C event.
+ // The public stop() cases above cover force semantics on every platform.
+ test('preview CLI: second Ctrl-C exits despite an unfinished HTTP request', {
+ skip: process.platform === 'win32' ? 'POSIX signal delivery; public stop API is covered on Windows' : false,
+ timeout: 15000,
+ }, async () => {
+ const data = fixture();
+ const child = spawn(process.execPath, [path.join(skillRoot, 'bin/archify.mjs'), 'preview', 'architecture', data.input, data.output, '--no-open'], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let stdout = '';
+ let stderr = '';
+ let socket;
+ let exited = false;
+ child.stdout.on('data', (chunk) => { stdout += chunk; });
+ child.stderr.on('data', (chunk) => { stderr += chunk; });
+ const closed = new Promise((resolve) => child.once('close', (code, signal) => {
+ exited = true;
+ resolve({ code, signal });
+ }));
+ try {
+ await until(() => /http:\/\/127\.0\.0\.1:\d+\//.test(stdout), `CLI did not print a preview URL: ${stderr}`);
+ const url = stdout.match(/http:\/\/127\.0\.0\.1:\d+\//)[0];
+ await until(async () => (await (await fetch(new URL('/state', url))).json()).status === 'verified', 'CLI did not verify');
+ const previous = fs.readFileSync(data.output);
+ socket = await partialRequest(url);
+ child.kill('SIGINT');
+ await until(() => stdout.includes('stopping preview'), 'first Ctrl-C was not handled');
+ assert.equal(exited, false);
+ child.kill('SIGINT');
+ assert.deepEqual(await bounded(closed, 'second Ctrl-C did not force HTTP shutdown'), { code: 0, signal: null });
+ assert.match(stdout, /forcing preview shutdown/);
+ assertClean(data, previous);
+ } finally {
+ socket?.destroy();
+ if (!exited) child.kill('SIGKILL');
+ await closed;
+ fs.rmSync(data.root, { recursive: true, force: true });
+ }
+ });
++
++for (const window of ['snapshot', 'receipt']) {
++ test(`preview: force preserves recovery material at the real delivery ${window} window`, { timeout: 20000 }, async () => {
++ const data = fixture();
++ const ready = path.join(data.root, 'delivery.ready');
++ const deliveryCli = path.join(data.root, 'paused-delivery.mjs');
++ const cli = path.join(skillRoot, 'bin/archify.mjs');
++ const previous = Buffer.from('<!doctype html><title>Previous verified artifact</title>');
++ fs.writeFileSync(data.output, previous);
++ // Pause a real deliver at a deterministic boundary, without publishing its
++ // receipt to Preview. No environment changes leak into other tests.
++ fs.writeFileSync(deliveryCli, window === 'receipt' ? `
++ import fs from 'node:fs';
++ import { spawnSync } from 'node:child_process';
++ const result = spawnSync(process.execPath, [${JSON.stringify(cli)}, ...process.argv.slice(2)], { encoding: 'utf8' });
++ if (result.status !== 0) { process.stderr.write(result.stderr); process.exit(result.status || 1); }
++ fs.writeFileSync(${JSON.stringify(ready)}, result.stdout);
++ setInterval(() => {}, 1000);
++ ` : `
++ import fs from 'node:fs';
++ import path from 'node:path';
++ import { pathToFileURL } from 'node:url';
++ const write = fs.writeFileSync;
++ fs.writeFileSync = function (target, ...args) {
++ const result = write.call(this, target, ...args);
++ if (typeof target === 'string' && path.basename(target) === 'specification.snapshot.json') {
++ write(${JSON.stringify(ready)}, target);
++ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0);
++ }
++ return result;
++ };
++ await import(pathToFileURL(${JSON.stringify(cli)}).href);
++ `);
++ let preview;
++ let socket;
++ try {
++ preview = await startPreview({ ...data, type: 'architecture', open: false, deliveryCli });
++ await until(() => fs.existsSync(ready), `real delivery did not reach ${window}`);
++ const staging = path.join(data.root, fs.readdirSync(data.root).find((name) => name.startsWith('.archify-preview-')));
++ const claimant = path.join(staging, 'claimant.txt');
++ fs.writeFileSync(claimant, 'unowned content');
++ const retained = window === 'snapshot'
++ ? [fs.readFileSync(ready, 'utf8')]
++ : ['generation-1.html', 'generation-1.delivery.json'].map((name) => path.join(staging, name));
++ const bytes = retained.map((file) => fs.readFileSync(file));
++ if (window === 'receipt') assert.equal(JSON.parse(fs.readFileSync(ready, 'utf8')).ok, true);
++ socket = await partialRequest(preview.url);
++ await bounded(preview.stop({ force: true }), 'force blocked with real delivery and an unfinished request');
++ await preview.closed;
++ await preview.stop({ force: true });
++ assert.deepEqual(fs.readFileSync(data.output), previous);
++ assert.equal(fs.readFileSync(claimant, 'utf8'), 'unowned content');
++ retained.forEach((file, i) => assert.deepEqual(fs.readFileSync(file), bytes[i], 'recovery material changed'));
++ assert.equal(fs.existsSync(path.join(staging, 'generation-1.json')), false, 'owned input snapshot was not cleaned');
++ await assert.rejects(fetch(preview.url));
++ } finally {
++ socket?.destroy();
++ if (preview) await preview.stop({ force: true });
++ fs.rmSync(data.root, { recursive: true, force: true });
++ }
++ });
++}