root-at-skicandClaude Opus 5.5
22815a9940
VS Code extension that previews Archify diagrams from their JSON sources (live, as you type) and opens rendered Archify HTML in a viewer tab. Bundles the Archify 3.0.1 renderer and runs it on VS Code's Node runtime. Adds validation diagnostics, JSON schema help, source-link navigation, export saving, render-to-file and open-in-browser commands. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
970 lines
36 KiB
JavaScript
970 lines
36 KiB
JavaScript
import { spawn } from 'node:child_process';
|
|
import { createHash } from 'node:crypto';
|
|
import fs from 'node:fs';
|
|
import http from 'node:http';
|
|
import path from 'node:path';
|
|
import { fileURLToPath } from 'node:url';
|
|
|
|
import { openLoopbackUrl } from './open-artifact.mjs';
|
|
import { resolveOutputPath } from '../renderers/shared/output-path.mjs';
|
|
import { sameLocation } from '../renderers/shared/path-semantics.mjs';
|
|
import {
|
|
captureAtomicOutput,
|
|
captureRegularFileBinding,
|
|
publishRegularFileBinding,
|
|
releaseRegularFileBinding,
|
|
removeEmptyDirectoryWithRetry,
|
|
removeOwnedRegularFile,
|
|
verifyAtomicOutput,
|
|
} from '../renderers/shared/atomic-output.mjs';
|
|
|
|
const here = path.dirname(fileURLToPath(import.meta.url));
|
|
const cliPath = path.join(here, 'archify.mjs');
|
|
const loopbackHost = '127.0.0.1';
|
|
const defaultDebounceMs = 400;
|
|
const defaultPollMs = 800;
|
|
const defaultStopGraceMs = 3000;
|
|
const defaultStopKillMs = 750;
|
|
const diagramTypes = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle']);
|
|
let previewCommitSequence = 0;
|
|
|
|
function sha256(value) {
|
|
return createHash('sha256').update(value).digest('hex');
|
|
}
|
|
|
|
function sourceDigest(inputPath) {
|
|
try {
|
|
const bytes = fs.readFileSync(inputPath);
|
|
return { hash: sha256(bytes), bytes, missing: false };
|
|
} catch (error) {
|
|
return { hash: `unreadable:${error.code || 'unknown'}`, bytes: null, missing: true };
|
|
}
|
|
}
|
|
|
|
function initialAuthoredOutput(inputPath) {
|
|
try {
|
|
const source = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
|
|
if (typeof source?.meta?.output === 'string') {
|
|
return source.meta.output;
|
|
}
|
|
} catch {
|
|
// An invalid initial source still gets a status shell. Its output target is
|
|
// fixed to the same fallback that `deliver` would use after repair.
|
|
}
|
|
return undefined;
|
|
}
|
|
|
|
function previewPage() {
|
|
return `<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>Archify Live Preview</title>
|
|
<style>
|
|
:root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
|
|
* { box-sizing: border-box; }
|
|
html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; background: #0b111b; }
|
|
body { display: grid; grid-template-rows: auto minmax(0, 1fr); color: #e8edf5; }
|
|
header { position: relative; z-index: 2; display: flex; align-items: center; gap: 12px; min-height: 44px; padding: 7px 12px; border-bottom: 1px solid #253248; background: rgba(11, 17, 27, .96); box-shadow: 0 8px 22px rgba(0,0,0,.18); }
|
|
.brand { font-size: 12px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: #9cadc6; }
|
|
#status { margin-left: auto; display: inline-flex; align-items: center; gap: 8px; min-height: 30px; padding: 5px 10px; border: 1px solid #33435d; border-radius: 999px; background: #111b2a; font-size: 12px; white-space: nowrap; }
|
|
#status::before { content: ''; width: 8px; height: 8px; border-radius: 50%; background: #6f819d; }
|
|
body[data-state="checking"] #status::before { background: #f3b44b; box-shadow: 0 0 0 4px rgba(243,180,75,.12); }
|
|
body[data-state="verified"] #status::before { background: #45d6a8; box-shadow: 0 0 0 4px rgba(69,214,168,.12); }
|
|
body[data-state="needs-fix"] #status::before { background: #ff6f78; box-shadow: 0 0 0 4px rgba(255,111,120,.12); }
|
|
details { max-width: min(62vw, 760px); }
|
|
summary { cursor: pointer; color: #ffbdc2; font-size: 12px; }
|
|
.diagnostic { position: absolute; top: 38px; right: 12px; width: min(760px, calc(100vw - 24px)); max-height: min(44vh, 360px); overflow: auto; padding: 14px; border: 1px solid #6a3440; border-radius: 10px; background: #17131b; box-shadow: 0 14px 48px rgba(0,0,0,.42); }
|
|
pre { margin: 0 0 10px; white-space: pre-wrap; overflow-wrap: anywhere; font: 11px/1.55 ui-monospace, SFMono-Regular, Menlo, monospace; color: #f2dfe2; }
|
|
button { min-height: 32px; padding: 5px 10px; border: 1px solid #4a5d79; border-radius: 7px; background: #1a273a; color: #eef4ff; cursor: pointer; }
|
|
main { position: relative; min-height: 0; }
|
|
iframe { display: none; width: 100%; height: 100%; border: 0; background: #fff; }
|
|
body[data-has-artifact="true"] iframe { display: block; }
|
|
#empty { position: absolute; inset: 0; display: grid; place-items: center; padding: 32px; color: #91a2bc; text-align: center; background: radial-gradient(circle at 50% 38%, #15233a 0, #0b111b 55%); }
|
|
body[data-has-artifact="true"] #empty { display: none; }
|
|
@media (prefers-reduced-motion: reduce) { * { scroll-behavior: auto !important; } }
|
|
</style>
|
|
</head>
|
|
<body data-state="checking" data-has-artifact="false">
|
|
<header>
|
|
<span class="brand">Archify Preview</span>
|
|
<details id="failure" hidden>
|
|
<summary role="button" aria-controls="diagnostic-panel">View diagnostic</summary>
|
|
<div class="diagnostic" id="diagnostic-panel"><pre id="diagnostic"></pre><button id="copy" type="button">Copy diagnostic</button></div>
|
|
</details>
|
|
<span id="status" role="status" aria-live="polite">Checking · generation 1</span>
|
|
</header>
|
|
<main>
|
|
<div id="empty">Waiting for the first verified diagram. Invalid input will stay here with an exact diagnostic.</div>
|
|
<iframe id="artifact" title="Verified Archify diagram"></iframe>
|
|
</main>
|
|
<script>
|
|
(function () {
|
|
'use strict';
|
|
var body = document.body;
|
|
var status = document.getElementById('status');
|
|
var failure = document.getElementById('failure');
|
|
var diagnostic = document.getElementById('diagnostic');
|
|
var artifact = document.getElementById('artifact');
|
|
var lastRevision = 0;
|
|
|
|
function render(state) {
|
|
body.dataset.state = state.status;
|
|
if (state.status === 'verified') {
|
|
status.textContent = 'Verified · rev ' + state.revision;
|
|
failure.hidden = true;
|
|
failure.open = false;
|
|
if (state.revision !== lastRevision) {
|
|
lastRevision = state.revision;
|
|
artifact.src = '/artifact.html?revision=' + encodeURIComponent(state.revision) + '&sha=' + encodeURIComponent(state.lastVerified.sha256.slice(0, 12));
|
|
body.dataset.hasArtifact = 'true';
|
|
}
|
|
} else if (state.status === 'needs-fix') {
|
|
status.textContent = 'Needs fix · ' + (state.revision ? 'showing rev ' + state.revision : 'no verified revision');
|
|
diagnostic.textContent = 'Generation ' + state.generation + ' · ' + state.failure.stage + '\\n\\n' + state.failure.message;
|
|
failure.hidden = false;
|
|
} else {
|
|
status.textContent = 'Checking · generation ' + state.generation;
|
|
failure.hidden = true;
|
|
}
|
|
}
|
|
|
|
document.getElementById('copy').addEventListener('click', function () {
|
|
if (navigator.clipboard && navigator.clipboard.writeText) {
|
|
navigator.clipboard.writeText(diagnostic.textContent).catch(function () {});
|
|
}
|
|
});
|
|
|
|
var events = new EventSource('/events');
|
|
events.addEventListener('state', function (event) {
|
|
try { render(JSON.parse(event.data)); } catch (_) {}
|
|
});
|
|
}());
|
|
</script>
|
|
</body>
|
|
</html>`;
|
|
}
|
|
|
|
function compactMessage(value) {
|
|
let text = String(value || 'Preview build failed without a diagnostic.').trim();
|
|
const lines = text.split(/\r?\n/);
|
|
const errorLine = lines.findIndex((line) => /^Error:\s/.test(line));
|
|
if (errorLine > 0) text = lines.slice(errorLine).join('\n');
|
|
const relevant = text.split(/\r?\n/);
|
|
const stackLine = relevant.findIndex((line, index) => index > 0 && /^\s*at\s/.test(line));
|
|
if (stackLine > 0) text = relevant.slice(0, stackLine).join('\n');
|
|
return text.length > 6000 ? `${text.slice(0, 6000)}\n… diagnostic truncated` : text;
|
|
}
|
|
|
|
function redactDiagnostic(value, paths) {
|
|
let text = compactMessage(value);
|
|
for (const [absolutePath, replacement] of paths) {
|
|
if (!absolutePath) continue;
|
|
text = text.split(absolutePath).join(replacement);
|
|
}
|
|
return text;
|
|
}
|
|
|
|
function safeJson(value) {
|
|
return JSON.stringify(value).replace(/</g, '\\u003c');
|
|
}
|
|
|
|
function responseHeaders(contentType) {
|
|
return {
|
|
'Cache-Control': 'no-store',
|
|
'Content-Type': contentType,
|
|
'Cross-Origin-Resource-Policy': 'same-origin',
|
|
'Referrer-Policy': 'no-referrer',
|
|
'X-Content-Type-Options': 'nosniff',
|
|
'X-Frame-Options': 'SAMEORIGIN',
|
|
};
|
|
}
|
|
|
|
function parseReceipt(stdout) {
|
|
try {
|
|
return JSON.parse(stdout);
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function atomicOutputFailure(result) {
|
|
const code = result?.reason?.code || 'unclassified';
|
|
let diagnosticCode = 'output/target-indeterminate';
|
|
let message;
|
|
if (code === 'target-hardlinked' || code === 'candidate-hardlinked') {
|
|
diagnosticCode = 'output/target-hardlinked';
|
|
message = code === 'candidate-hardlinked'
|
|
? 'Preview commit candidate has multiple hard-link names and cannot be published safely.'
|
|
: 'Preview output has multiple hard-link names; atomic publication cannot update every name.';
|
|
} else if (code === 'target-not-regular-file' || code === 'candidate-not-regular-file') {
|
|
diagnosticCode = 'output/target-not-regular-file';
|
|
message = code === 'candidate-not-regular-file'
|
|
? 'Preview commit candidate is no longer a regular file.'
|
|
: 'Preview output already exists and is not a regular file.';
|
|
} else if (result?.status === 'different') {
|
|
diagnosticCode = 'output/target-changed';
|
|
message = `Preview output changed while the verified candidate was being prepared (${code}).`;
|
|
} else {
|
|
message = `Preview output stability could not be determined safely (${code}).`;
|
|
}
|
|
return {
|
|
code: diagnosticCode,
|
|
message,
|
|
evidence: { relation: result?.reason || { code } },
|
|
};
|
|
}
|
|
|
|
function atomicOutputError(result) {
|
|
const failure = atomicOutputFailure(result);
|
|
return Object.assign(new Error(failure.message), { previewFailure: failure });
|
|
}
|
|
|
|
function stagePreviewCommit(commitPath, artifact, mode) {
|
|
for (let attempt = 0; attempt < 100; attempt += 1) {
|
|
previewCommitSequence += 1;
|
|
const candidatePath = path.join(
|
|
path.dirname(commitPath),
|
|
`.archify-preview-commit-${process.pid}-${Date.now().toString(36)}-${previewCommitSequence}.tmp`,
|
|
);
|
|
let descriptor;
|
|
let identity;
|
|
try {
|
|
const noFollow = process.platform === 'win32' ? 0 : (fs.constants.O_NOFOLLOW || 0);
|
|
descriptor = fs.openSync(
|
|
candidatePath,
|
|
fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow,
|
|
mode ?? 0o666,
|
|
);
|
|
let metadata;
|
|
try {
|
|
metadata = fs.fstatSync(descriptor, { bigint: true });
|
|
} catch (error) {
|
|
try {
|
|
const retry = fs.fstatSync(descriptor, { bigint: true });
|
|
if (retry.isFile() && retry.ino !== 0n) {
|
|
identity = { device: retry.dev, inode: retry.ino };
|
|
}
|
|
} catch {}
|
|
throw error;
|
|
}
|
|
if (!metadata.isFile() || metadata.ino === 0n) {
|
|
throw new Error('Preview commit candidate identity could not be verified safely.');
|
|
}
|
|
identity = { device: metadata.dev, inode: metadata.ino };
|
|
fs.writeFileSync(descriptor, artifact);
|
|
if (mode !== null) fs.fchmodSync(descriptor, mode);
|
|
fs.closeSync(descriptor);
|
|
descriptor = undefined;
|
|
return { candidatePath, identity };
|
|
} catch (error) {
|
|
if (descriptor !== undefined) {
|
|
try { fs.closeSync(descriptor); } catch {}
|
|
}
|
|
if (error.code === 'EEXIST') continue;
|
|
if (identity) removeOwnedRegularFile(candidatePath, identity);
|
|
throw error;
|
|
}
|
|
}
|
|
throw Object.assign(new Error('Could not reserve a preview commit candidate beside the output.'), {
|
|
code: 'EEXIST',
|
|
errno: -17,
|
|
syscall: 'open',
|
|
});
|
|
}
|
|
|
|
function captureOwnedDirectory(directoryPath) {
|
|
const metadata = fs.lstatSync(directoryPath, { bigint: true });
|
|
if (!metadata.isDirectory() || metadata.ino === 0n) {
|
|
throw new Error('Preview staging directory identity could not be verified safely.');
|
|
}
|
|
return { device: metadata.dev, inode: metadata.ino };
|
|
}
|
|
|
|
function cleanupOwnedDirectory(directoryPath, identity) {
|
|
let current;
|
|
try {
|
|
current = fs.lstatSync(directoryPath, { bigint: true });
|
|
} catch (error) {
|
|
if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return;
|
|
throw error;
|
|
}
|
|
// Preserve a replacement rather than recursively deleting a directory that
|
|
// this preview instance did not create.
|
|
if (!current.isDirectory()
|
|
|| current.ino === 0n
|
|
|| current.dev !== identity.device
|
|
|| current.ino !== identity.inode) return;
|
|
try {
|
|
removeEmptyDirectoryWithRetry(directoryPath);
|
|
} catch (error) {
|
|
// An entry whose identity was never bound to this preview may be an
|
|
// external claimant. Preserve the private directory as recovery material
|
|
// instead of recursively deleting unknown contents.
|
|
if (error?.code !== 'ENOTEMPTY' && error?.code !== 'EEXIST') throw error;
|
|
}
|
|
}
|
|
|
|
function captureOwnedDeliverySidecars(candidatePath, snapshotPath, receipt) {
|
|
const suffixes = ['.delivery.json', '.delivery-pending.json'];
|
|
const capturedSidecars = [];
|
|
for (const suffix of suffixes) {
|
|
const sidecarPath = candidatePath.replace(/\.html$/iu, suffix);
|
|
const captured = captureRegularFileBinding(sidecarPath, {
|
|
subject: 'preview-delivery-sidecar',
|
|
expectedLinks: 1,
|
|
includeContent: true,
|
|
});
|
|
if (captured.status !== 'captured') continue;
|
|
try {
|
|
const sidecar = JSON.parse(captured.content.buffer.toString('utf8'));
|
|
const commonMatches = sidecar?.schemaVersion === 1
|
|
&& sidecar.command === 'deliver'
|
|
&& sameLocation(sidecar.output, candidatePath).status === 'match'
|
|
&& (!receipt?.receiptId || sidecar.receiptId === receipt.receiptId);
|
|
const currentMatches = suffix === '.delivery.json'
|
|
&& commonMatches
|
|
&& sidecar.status === 'current'
|
|
&& receipt?.artifact?.sha256
|
|
&& sidecar.artifact?.sha256 === receipt.artifact.sha256;
|
|
const pendingMatches = suffix === '.delivery-pending.json'
|
|
&& commonMatches
|
|
&& sidecar.status === 'pending'
|
|
&& sameLocation(sidecar.input, snapshotPath).status === 'match';
|
|
if (currentMatches || pendingMatches) {
|
|
capturedSidecars.push({ path: sidecarPath, identity: captured.identity });
|
|
}
|
|
} catch {
|
|
// Preserve malformed or claimant-controlled sidecars for recovery.
|
|
} finally {
|
|
releaseRegularFileBinding(captured.binding);
|
|
}
|
|
}
|
|
return capturedSidecars;
|
|
}
|
|
|
|
export async function startPreview(options) {
|
|
const type = options.type;
|
|
if (!diagramTypes.has(type)) throw new Error(`Unknown diagram type "${type}".`);
|
|
if (options.quality && !['standard', 'showcase'].includes(options.quality)) {
|
|
throw new Error(`Unknown quality profile "${options.quality}".`);
|
|
}
|
|
const inputPath = path.resolve(options.input);
|
|
const outputRequest = {
|
|
requestedOutput: options.output,
|
|
authoredOutput: initialAuthoredOutput(inputPath),
|
|
defaultOutput: `${type}.html`,
|
|
inputPaths: [inputPath],
|
|
inputDescription: 'its JSON input',
|
|
cwd: options.cwd || process.cwd(),
|
|
};
|
|
const { outputPath } = resolveOutputPath(outputRequest);
|
|
const outputDirectory = path.dirname(outputPath);
|
|
const debounceMs = Number.isFinite(options.debounceMs) ? options.debounceMs : defaultDebounceMs;
|
|
const pollMs = Number.isFinite(options.pollMs) ? options.pollMs : defaultPollMs;
|
|
const stopGraceMs = Number.isFinite(options.stopGraceMs) ? Math.max(0, options.stopGraceMs) : defaultStopGraceMs;
|
|
const stopKillMs = Number.isFinite(options.stopKillMs) ? Math.max(0, options.stopKillMs) : defaultStopKillMs;
|
|
const shouldOpen = options.open !== false;
|
|
|
|
fs.mkdirSync(outputDirectory, { recursive: true });
|
|
// Keep cleanup bound to the physical directory selected at startup. A
|
|
// symlink or junction in the requested output parent may be redirected while
|
|
// preview is running and must not redirect recursive cleanup to a claimant.
|
|
const physicalOutputDirectory = fs.realpathSync.native(outputDirectory);
|
|
const stagingDirectory = fs.mkdtempSync(path.toNamespacedPath(
|
|
path.join(physicalOutputDirectory, '.archify-preview-'),
|
|
));
|
|
let stagingIdentity;
|
|
try {
|
|
stagingIdentity = captureOwnedDirectory(stagingDirectory);
|
|
} catch (error) {
|
|
try { fs.rmdirSync(stagingDirectory); } catch {}
|
|
throw error;
|
|
}
|
|
|
|
let port = 0;
|
|
let watcher;
|
|
let debounceTimer;
|
|
let pollTimer;
|
|
let stopGraceTimer;
|
|
let stopKillTimer;
|
|
let child;
|
|
let stopping = false;
|
|
let forceStopping = false;
|
|
let stopped = false;
|
|
let serverClosing = false;
|
|
let serverClosed = false;
|
|
let queuedHash = null;
|
|
let activeHash = null;
|
|
let lastGoodSourceHash = null;
|
|
let sourceEpoch = 0;
|
|
let activeEpoch = 0;
|
|
let pendingBuild = false;
|
|
let artifactBuffer = null;
|
|
const clients = new Set();
|
|
const sockets = new Set();
|
|
const state = {
|
|
schemaVersion: 1,
|
|
status: 'checking',
|
|
generation: 0,
|
|
revision: 0,
|
|
lastVerified: null,
|
|
failure: null,
|
|
};
|
|
|
|
let resolveClosed;
|
|
const closed = new Promise((resolve) => { resolveClosed = resolve; });
|
|
|
|
function publicState() {
|
|
return JSON.parse(JSON.stringify(state));
|
|
}
|
|
|
|
function sendState(res) {
|
|
res.write(`event: state\ndata: ${safeJson(publicState())}\n\n`);
|
|
}
|
|
|
|
function broadcast() {
|
|
for (const res of clients) sendState(res);
|
|
}
|
|
|
|
const page = Buffer.from(previewPage());
|
|
const server = http.createServer((req, res) => {
|
|
const expectedHost = `${loopbackHost}:${port}`;
|
|
if (req.headers.host !== expectedHost) {
|
|
res.writeHead(403, responseHeaders('text/plain; charset=utf-8'));
|
|
res.end('Forbidden host');
|
|
return;
|
|
}
|
|
if (req.method !== 'GET' && req.method !== 'HEAD') {
|
|
res.writeHead(405, { ...responseHeaders('text/plain; charset=utf-8'), Allow: 'GET, HEAD' });
|
|
res.end('Method not allowed');
|
|
return;
|
|
}
|
|
|
|
let url;
|
|
try {
|
|
url = new URL(req.url, `http://${expectedHost}`);
|
|
} catch {
|
|
res.writeHead(400, responseHeaders('text/plain; charset=utf-8'));
|
|
res.end('Bad request');
|
|
return;
|
|
}
|
|
|
|
if (url.pathname === '/') {
|
|
res.writeHead(200, {
|
|
...responseHeaders('text/html; charset=utf-8'),
|
|
'Content-Security-Policy': "default-src 'none'; frame-src 'self'; connect-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'",
|
|
'Content-Length': page.byteLength,
|
|
});
|
|
if (req.method === 'HEAD') res.end();
|
|
else res.end(page);
|
|
return;
|
|
}
|
|
if (url.pathname === '/state') {
|
|
const body = Buffer.from(`${safeJson(publicState())}\n`);
|
|
res.writeHead(200, { ...responseHeaders('application/json; charset=utf-8'), 'Content-Length': body.byteLength });
|
|
if (req.method === 'HEAD') res.end();
|
|
else res.end(body);
|
|
return;
|
|
}
|
|
if (url.pathname === '/artifact.html') {
|
|
if (!artifactBuffer) {
|
|
res.writeHead(404, responseHeaders('text/plain; charset=utf-8'));
|
|
res.end('No verified artifact yet');
|
|
return;
|
|
}
|
|
res.writeHead(200, { ...responseHeaders('text/html; charset=utf-8'), 'Content-Length': artifactBuffer.byteLength });
|
|
if (req.method === 'HEAD') res.end();
|
|
else res.end(artifactBuffer);
|
|
return;
|
|
}
|
|
if (url.pathname === '/events' && req.method === 'GET') {
|
|
res.writeHead(200, {
|
|
...responseHeaders('text/event-stream; charset=utf-8'),
|
|
Connection: 'keep-alive',
|
|
});
|
|
res.write('retry: 1000\n\n');
|
|
clients.add(res);
|
|
sendState(res);
|
|
req.on('close', () => clients.delete(res));
|
|
return;
|
|
}
|
|
|
|
res.writeHead(404, responseHeaders('text/plain; charset=utf-8'));
|
|
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);
|
|
server.listen(0, loopbackHost, () => {
|
|
server.off('error', reject);
|
|
port = server.address().port;
|
|
resolve();
|
|
});
|
|
});
|
|
} catch (error) {
|
|
try { server.close(); } catch {}
|
|
cleanupOwnedDirectory(stagingDirectory, stagingIdentity);
|
|
throw error;
|
|
}
|
|
|
|
const url = `http://${loopbackHost}:${port}/`;
|
|
|
|
function finishStop() {
|
|
if (stopped || child || !serverClosed) return;
|
|
stopped = true;
|
|
clearTimeout(debounceTimer);
|
|
clearInterval(pollTimer);
|
|
clearTimeout(stopGraceTimer);
|
|
clearTimeout(stopKillTimer);
|
|
try {
|
|
cleanupOwnedDirectory(stagingDirectory, stagingIdentity);
|
|
} finally {
|
|
resolveClosed();
|
|
}
|
|
}
|
|
|
|
function signalActiveChild(signal) {
|
|
if (!child || child.exitCode !== null || child.signalCode !== null) return;
|
|
try {
|
|
if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal);
|
|
else child.kill(signal);
|
|
} catch (error) {
|
|
if (error.code === 'ESRCH') return;
|
|
try { child.kill(signal); } catch {}
|
|
}
|
|
}
|
|
|
|
function closeServer() {
|
|
if (serverClosing) return;
|
|
serverClosing = true;
|
|
for (const res of clients) res.end();
|
|
clients.clear();
|
|
server.close(() => {
|
|
serverClosed = true;
|
|
finishStop();
|
|
});
|
|
server.closeIdleConnections?.();
|
|
}
|
|
|
|
function startBoundedChildDrain() {
|
|
if (!child || stopGraceTimer || stopKillTimer) return;
|
|
stopGraceTimer = setTimeout(() => {
|
|
stopGraceTimer = undefined;
|
|
if (!child) return finishStop();
|
|
signalActiveChild('SIGTERM');
|
|
stopKillTimer = setTimeout(() => {
|
|
stopKillTimer = undefined;
|
|
signalActiveChild('SIGKILL');
|
|
}, stopKillMs);
|
|
}, stopGraceMs);
|
|
}
|
|
|
|
async function stop({ force = false } = {}) {
|
|
if (force) forceStopping = true;
|
|
if (!stopping) {
|
|
stopping = true;
|
|
clearTimeout(debounceTimer);
|
|
clearInterval(pollTimer);
|
|
watcher?.close();
|
|
closeServer();
|
|
}
|
|
if (forceStopping) {
|
|
for (const socket of sockets) socket.destroy();
|
|
}
|
|
if (child && force) {
|
|
clearTimeout(stopGraceTimer);
|
|
clearTimeout(stopKillTimer);
|
|
stopGraceTimer = undefined;
|
|
stopKillTimer = undefined;
|
|
signalActiveChild('SIGKILL');
|
|
} else if (child) {
|
|
startBoundedChildDrain();
|
|
} else {
|
|
finishStop();
|
|
}
|
|
return closed;
|
|
}
|
|
|
|
function publishFailure(receipt, stdout, stderr, candidatePath, snapshotPath) {
|
|
const repairDetails = receipt?.diagnostics
|
|
?.slice(0, 12)
|
|
.map((entry) => {
|
|
const fix = entry.supportedFixes?.length ? `\nFix: ${entry.supportedFixes.join('; ')}` : '';
|
|
return `[${entry.code}] ${entry.message}${fix}`;
|
|
}) || [];
|
|
const checkerDetails = receipt?.checker?.checks
|
|
?.filter((check) => !check.ok)
|
|
.flatMap((check) => check.details || [])
|
|
.filter(Boolean)
|
|
.slice(0, 12) || [];
|
|
const diagnostic = [
|
|
receipt?.error,
|
|
...(repairDetails.length ? repairDetails : checkerDetails),
|
|
].filter(Boolean).join('\n') || stderr || stdout;
|
|
state.status = 'needs-fix';
|
|
state.failure = {
|
|
stage: receipt?.stage || 'render',
|
|
...(receipt?.code ? { code: receipt.code } : {}),
|
|
...(receipt?.evidence ? { evidence: receipt.evidence } : {}),
|
|
message: redactDiagnostic(
|
|
diagnostic,
|
|
[
|
|
[inputPath, '<input.json>'],
|
|
[outputPath, '<output.html>'],
|
|
[snapshotPath, '<input.json>'],
|
|
[candidatePath, '<candidate.html>'],
|
|
[stagingDirectory, '<preview-staging>'],
|
|
[path.resolve(here, '..'), '<archify-skill>'],
|
|
[path.resolve(options.cwd || process.cwd()), '<working-directory>'],
|
|
...(options.repoRoot ? [[path.resolve(options.repoRoot), '<repo-root>']] : []),
|
|
],
|
|
),
|
|
};
|
|
broadcast();
|
|
}
|
|
|
|
function commitCandidate(candidatePath, receipt, generationHash, outputCapture) {
|
|
let candidate;
|
|
let sourceCandidateBinding;
|
|
let sourceCandidateIdentity;
|
|
let commitCandidatePath;
|
|
let commitCandidateIdentity;
|
|
let commitCandidateBinding;
|
|
try {
|
|
const sourceCapture = captureRegularFileBinding(candidatePath, {
|
|
subject: 'candidate',
|
|
expectedSha256: receipt?.artifact?.sha256,
|
|
expectedBytes: receipt?.artifact?.bytes,
|
|
includeContent: true,
|
|
});
|
|
if (sourceCapture.status !== 'captured') throw atomicOutputError(sourceCapture);
|
|
sourceCandidateBinding = sourceCapture.binding;
|
|
sourceCandidateIdentity = sourceCapture.identity;
|
|
candidate = sourceCapture.content.buffer;
|
|
const digest = sourceCapture.content.sha256;
|
|
const releasedSource = releaseRegularFileBinding(sourceCandidateBinding);
|
|
sourceCandidateBinding = undefined;
|
|
if (releasedSource.status !== 'released') throw atomicOutputError(releasedSource);
|
|
resolveOutputPath(outputRequest);
|
|
const sameArtifact = state.lastVerified?.sha256 === digest;
|
|
const currentSource = sourceDigest(inputPath);
|
|
if (currentSource.hash !== generationHash) {
|
|
return {
|
|
committed: false,
|
|
supersededBy: currentSource,
|
|
candidateIdentity: sourceCandidateIdentity,
|
|
};
|
|
}
|
|
const beforeStage = verifyAtomicOutput(outputCapture.snapshot);
|
|
if (beforeStage.status !== 'match') throw atomicOutputError(beforeStage);
|
|
({
|
|
candidatePath: commitCandidatePath,
|
|
identity: commitCandidateIdentity,
|
|
} = stagePreviewCommit(outputCapture.commitPath, candidate, outputCapture.mode));
|
|
const candidateCapture = captureRegularFileBinding(commitCandidatePath, {
|
|
subject: 'candidate',
|
|
expectedSha256: digest,
|
|
expectedBytes: candidate.byteLength,
|
|
expectedIdentity: commitCandidateIdentity,
|
|
...(outputCapture.mode === null ? {} : { expectedMode: outputCapture.mode }),
|
|
});
|
|
if (candidateCapture.status !== 'captured') throw atomicOutputError(candidateCapture);
|
|
commitCandidateBinding = candidateCapture.binding;
|
|
const beforeCommit = verifyAtomicOutput(outputCapture.snapshot);
|
|
if (beforeCommit.status !== 'match') throw atomicOutputError(beforeCommit);
|
|
const publication = publishRegularFileBinding(
|
|
commitCandidateBinding,
|
|
commitCandidatePath,
|
|
outputCapture.snapshot,
|
|
{ subject: 'candidate' },
|
|
);
|
|
if (!['committed', 'committed-with-warning'].includes(publication.status)) {
|
|
throw atomicOutputError(publication);
|
|
}
|
|
const releasedCandidate = releaseRegularFileBinding(commitCandidateBinding);
|
|
commitCandidateBinding = undefined;
|
|
if (releasedCandidate.status !== 'released') throw atomicOutputError(releasedCandidate);
|
|
commitCandidatePath = undefined;
|
|
commitCandidateIdentity = undefined;
|
|
artifactBuffer = candidate;
|
|
lastGoodSourceHash = generationHash;
|
|
state.status = 'verified';
|
|
if (!sameArtifact) {
|
|
state.revision += 1;
|
|
state.lastVerified = {
|
|
sha256: digest,
|
|
bytes: candidate.byteLength,
|
|
checksPassed: receipt.validation.checksPassed,
|
|
checkCount: receipt.validation.checkCount,
|
|
compositionProfile: receipt.validation.compositionProfile,
|
|
compositionStatus: receipt.validation.compositionStatus,
|
|
};
|
|
}
|
|
state.failure = null;
|
|
broadcast();
|
|
return { committed: true, supersededBy: null, candidateIdentity: sourceCandidateIdentity };
|
|
} catch (error) {
|
|
publishFailure({
|
|
stage: 'commit',
|
|
error: `Could not publish the verified preview: ${error.message}`,
|
|
...(error.previewFailure || {}),
|
|
}, '', '', candidatePath);
|
|
return { committed: false, supersededBy: null, candidateIdentity: sourceCandidateIdentity };
|
|
} finally {
|
|
if (sourceCandidateBinding) releaseRegularFileBinding(sourceCandidateBinding);
|
|
if (commitCandidateBinding) releaseRegularFileBinding(commitCandidateBinding);
|
|
if (commitCandidatePath && commitCandidateIdentity) {
|
|
removeOwnedRegularFile(commitCandidatePath, commitCandidateIdentity);
|
|
}
|
|
}
|
|
}
|
|
|
|
function beginBuild(digest, epoch) {
|
|
if (stopping || child) return;
|
|
activeHash = digest.hash;
|
|
activeEpoch = epoch;
|
|
state.generation += 1;
|
|
state.status = 'checking';
|
|
state.failure = null;
|
|
broadcast();
|
|
|
|
const candidatePath = path.join(stagingDirectory, `generation-${state.generation}.html`);
|
|
const snapshotPath = path.join(stagingDirectory, `generation-${state.generation}.json`);
|
|
let snapshotIdentity;
|
|
const outputCapture = captureAtomicOutput(outputPath);
|
|
if (outputCapture.status !== 'captured') {
|
|
const failure = atomicOutputFailure(outputCapture);
|
|
publishFailure(
|
|
{ stage: 'prepare', error: failure.message, ...failure },
|
|
'',
|
|
'',
|
|
candidatePath,
|
|
snapshotPath,
|
|
);
|
|
return;
|
|
}
|
|
const beforeBuild = verifyAtomicOutput(outputCapture.snapshot);
|
|
if (beforeBuild.status !== 'match') {
|
|
const failure = atomicOutputFailure(beforeBuild);
|
|
publishFailure(
|
|
{ stage: 'prepare', error: failure.message, ...failure },
|
|
'',
|
|
'',
|
|
candidatePath,
|
|
snapshotPath,
|
|
);
|
|
return;
|
|
}
|
|
if (digest.bytes !== null) {
|
|
try {
|
|
fs.writeFileSync(snapshotPath, digest.bytes, { flag: 'wx', mode: 0o600 });
|
|
const metadata = fs.lstatSync(snapshotPath, { bigint: true });
|
|
if (metadata.isFile() && metadata.ino !== 0n) {
|
|
snapshotIdentity = { device: metadata.dev, inode: metadata.ino };
|
|
}
|
|
} catch (error) {
|
|
publishFailure(
|
|
{ stage: 'prepare', error: `Could not snapshot the observed input: ${error.message}` },
|
|
'',
|
|
'',
|
|
candidatePath,
|
|
snapshotPath,
|
|
);
|
|
return;
|
|
}
|
|
}
|
|
const args = [options.deliveryCli || cliPath, 'deliver', type, snapshotPath, candidatePath, '--json'];
|
|
if (options.quality) args.push('--quality', options.quality);
|
|
if (options.repoRoot) args.push('--repo-root', path.resolve(options.repoRoot));
|
|
let stdout = '';
|
|
let stderr = '';
|
|
child = spawn(process.execPath, args, {
|
|
cwd: options.cwd || process.cwd(),
|
|
env: process.env,
|
|
stdio: ['ignore', 'pipe', 'pipe'],
|
|
detached: process.platform !== 'win32',
|
|
});
|
|
child.stdout.setEncoding('utf8');
|
|
child.stderr.setEncoding('utf8');
|
|
child.stdout.on('data', (chunk) => { stdout += chunk; });
|
|
child.stderr.on('data', (chunk) => { stderr += chunk; });
|
|
child.on('error', (error) => { stderr += error.message; });
|
|
child.on('close', (code) => {
|
|
const receipt = parseReceipt(stdout);
|
|
const generationEpoch = activeEpoch;
|
|
const generationHash = activeHash;
|
|
const stale = generationEpoch !== sourceEpoch;
|
|
let supersededBy = null;
|
|
let candidateIdentity;
|
|
const deliverySidecars = captureOwnedDeliverySidecars(
|
|
candidatePath,
|
|
snapshotPath,
|
|
receipt,
|
|
);
|
|
child = null;
|
|
clearTimeout(stopGraceTimer);
|
|
clearTimeout(stopKillTimer);
|
|
stopGraceTimer = undefined;
|
|
stopKillTimer = undefined;
|
|
if (!stopping && !stale && code === 0 && receipt?.ok) {
|
|
({ supersededBy, candidateIdentity } = commitCandidate(
|
|
candidatePath,
|
|
receipt,
|
|
generationHash,
|
|
outputCapture,
|
|
));
|
|
} else if (code === 0 && receipt?.ok) {
|
|
const abandonedCandidate = captureRegularFileBinding(candidatePath, {
|
|
subject: 'abandoned-preview-candidate',
|
|
expectedSha256: receipt.artifact?.sha256,
|
|
expectedBytes: receipt.artifact?.bytes,
|
|
});
|
|
if (abandonedCandidate.status === 'captured') {
|
|
candidateIdentity = abandonedCandidate.identity;
|
|
releaseRegularFileBinding(abandonedCandidate.binding);
|
|
}
|
|
} else if (!stopping && !stale) {
|
|
publishFailure(receipt, stdout, stderr, candidatePath, snapshotPath);
|
|
}
|
|
if (candidateIdentity) removeOwnedRegularFile(candidatePath, candidateIdentity);
|
|
if (snapshotIdentity) removeOwnedRegularFile(snapshotPath, snapshotIdentity, { subject: 'snapshot' });
|
|
for (const deliverySidecar of deliverySidecars) {
|
|
removeOwnedRegularFile(deliverySidecar.path, deliverySidecar.identity, {
|
|
subject: 'preview-delivery-sidecar',
|
|
});
|
|
}
|
|
|
|
if (stopping) {
|
|
finishStop();
|
|
} else if (pendingBuild || stale || supersededBy) {
|
|
pendingBuild = false;
|
|
if (supersededBy && sourceEpoch === generationEpoch) sourceEpoch += 1;
|
|
const digest = supersededBy || sourceDigest(inputPath);
|
|
queueStableBuild(digest.hash, true);
|
|
}
|
|
});
|
|
}
|
|
|
|
function queueStableBuild(hash, immediate = false) {
|
|
queuedHash = hash;
|
|
clearTimeout(debounceTimer);
|
|
const launch = () => {
|
|
if (stopping) return;
|
|
const digest = sourceDigest(inputPath);
|
|
if (digest.hash !== queuedHash) {
|
|
queueStableBuild(digest.hash);
|
|
return;
|
|
}
|
|
if (digest.hash === lastGoodSourceHash) {
|
|
if (state.status !== 'verified' && state.lastVerified) {
|
|
state.status = 'verified';
|
|
state.failure = null;
|
|
broadcast();
|
|
}
|
|
return;
|
|
}
|
|
if (child) {
|
|
pendingBuild = true;
|
|
return;
|
|
}
|
|
beginBuild(digest, sourceEpoch);
|
|
};
|
|
debounceTimer = setTimeout(launch, immediate ? 0 : debounceMs);
|
|
}
|
|
|
|
function observeSource({ immediate = false } = {}) {
|
|
const digest = sourceDigest(inputPath);
|
|
if (!immediate && digest.hash === queuedHash) return;
|
|
sourceEpoch += 1;
|
|
queueStableBuild(digest.hash, immediate);
|
|
}
|
|
|
|
if (options.watch !== false) {
|
|
try {
|
|
// `path.resolve` keeps Windows 8.3 names intact. Canonicalize short names
|
|
// and junctions before libuv opens the directory so its callback path has
|
|
// the same prefix as the watched path.
|
|
const watchedDirectory = fs.realpathSync.native(path.dirname(inputPath));
|
|
watcher = fs.watch(watchedDirectory, (event, filename) => {
|
|
// On Windows the watcher hands us just the basename; on POSIX it can be
|
|
// null. Resolve named events against the directory libuv actually opened
|
|
// so file-level case, 8.3, and hard-link aliases still identify the input.
|
|
if (
|
|
!filename
|
|
|| sameLocation(path.join(watchedDirectory, filename.toString()), inputPath).status === 'match'
|
|
) {
|
|
observeSource();
|
|
}
|
|
});
|
|
watcher.on('error', () => {
|
|
const failedWatcher = watcher;
|
|
watcher = undefined;
|
|
failedWatcher?.close();
|
|
});
|
|
} catch (error) {
|
|
await stop();
|
|
throw new Error(`Could not watch the input directory: ${error.message}`);
|
|
}
|
|
}
|
|
pollTimer = setInterval(() => observeSource(), pollMs);
|
|
|
|
let opener = null;
|
|
if (shouldOpen) {
|
|
try {
|
|
opener = openLoopbackUrl(url);
|
|
} catch {
|
|
opener = { requested: true, status: 'unsupported', target: url, method: null };
|
|
}
|
|
}
|
|
|
|
observeSource({ immediate: true });
|
|
|
|
return {
|
|
url,
|
|
input: inputPath,
|
|
output: outputPath,
|
|
opener,
|
|
state: publicState,
|
|
stop,
|
|
closed,
|
|
};
|
|
}
|
|
|
|
export async function runPreview(options) {
|
|
const preview = await startPreview(options);
|
|
console.log(`preview ${preview.url}`);
|
|
console.log(`watching ${preview.input}`);
|
|
console.log(`output ${preview.output}`);
|
|
if (preview.opener && preview.opener.status !== 'opened') {
|
|
console.error(`Could not open the preview (${preview.opener.status}). ${preview.opener.failure?.reason || 'Open it manually.'} Target: ${preview.url}`);
|
|
}
|
|
|
|
let signalCount = 0;
|
|
const stop = () => {
|
|
signalCount += 1;
|
|
if (signalCount === 1) {
|
|
console.log('\nstopping preview…');
|
|
preview.stop();
|
|
} else {
|
|
console.log('\nforcing preview shutdown…');
|
|
preview.stop({ force: true });
|
|
}
|
|
};
|
|
process.on('SIGINT', stop);
|
|
process.on('SIGTERM', stop);
|
|
await preview.closed;
|
|
process.off('SIGINT', stop);
|
|
process.off('SIGTERM', stop);
|
|
}
|