Skip to content

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

fix(preview): close owned connections during forced shutdown

To3akaRin6cae7c9c3e55
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b841d01..89a9183b 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
+- **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 --git a/archify.zip b/archify.zip
index ede3ba35..afd5933e 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/bin/preview.mjs b/archify/bin/preview.mjs
index 16ed94ed..04c6d804 100644
--- a/archify/bin/preview.mjs
+++ b/archify/bin/preview.mjs
@@ -212,6 +212,7 @@ export async function startPreview(options) {
let stopKillTimer;
let child;
let stopping = false;
+ let forceStopping = false;
let stopped = false;
let serverClosing = false;
let serverClosed = false;
@@ -223,6 +224,7 @@ export async function startPreview(options) {
let pendingBuild = false;
let artifactBuffer = null;
const clients = new Set();
+ const sockets = new Set();
const state = {
schemaVersion: 1,
status: 'checking',
@@ -314,6 +316,14 @@ export async function startPreview(options) {
res.end('Not found');
});
+ server.on('connection', (socket) => {
+ sockets.add(socket);
+ socket.once('close', () => sockets.delete(socket));
+ // A connection event already queued when force-stop begins must not keep
+ // server.close() waiting after the current sockets have been destroyed.
+ if (forceStopping) socket.destroy();
+ });
+
try {
await new Promise((resolve, reject) => {
server.once('error', reject);
@@ -382,6 +392,7 @@ export async function startPreview(options) {
}
async function stop({ force = false } = {}) {
+ if (force) forceStopping = true;
if (!stopping) {
stopping = true;
clearTimeout(debounceTimer);
@@ -389,6 +400,9 @@ export async function startPreview(options) {
watcher?.close();
closeServer();
}
+ if (forceStopping) {
+ for (const socket of sockets) socket.destroy();
+ }
if (child && force) {
clearTimeout(stopGraceTimer);
clearTimeout(stopKillTimer);
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index 11d0dfe6..46ce1056 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -98,7 +98,7 @@ Preview watches one explicit input on loopback, binds each stable digest to a pr
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.
## Perceptual delivery gate
diff --git a/archify/test/preview-force-stop.test.mjs b/archify/test/preview-force-stop.test.mjs
new file mode 100644
index 00000000..5659dcad
--- /dev/null
+++ b/archify/test/preview-force-stop.test.mjs
@@ -0,0 +1,184 @@
+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 });
+ }
+});