@pygmalionjs/pygmalion 0.8.1 → 0.10.0

package/node/token-source-service.mjs

@@ -0,0 +1,151 @@
+import { createHash } from 'node:crypto';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+import { applySourceFilePlan, previewSourceFilePlan, captureSourceFilePlan } from './source-file-plan.mjs';
+
+const capture = value => JSON.parse(fingerprint(value));
+const keyOf = value => createHash('sha256').update(fingerprint(value)).digest('hex');
+const expired = receipt => { const now = Date.now(); return now < receipt.createdAt || now - receipt.createdAt >= 30 * 60_000; };
+function completePreview(result, plan) {
+  const changed = new Set(plan.changes.map(change => change.file));
+  const complete = entries => Array.isArray(entries) && entries.length === changed.size
+    && new Set(entries).size === changed.size && entries.every(file => changed.has(file));
+  if (!result || !Array.isArray(result.files) || !complete(result.files.map(entry => entry?.file))
+    || !complete(result.affectedFiles) || result.files.some(entry => typeof entry.diff !== 'string' || !entry.diff.trim())) {
+    throw new Error('Review must include each changed file exactly once with a nonempty diff and affected-file entry.');
+  }
+}
+
+/** Token codecs describe the product files; this service owns receipts, review, cancellation, and source application. */
+export function createTokenSourceService({
+  appRoot, loadCodec, assertRevision, assertTarget, archive, loadSource, compilePlan, listConsumers,
+  previewPlan = previewSourceFilePlan, applyPlan = applySourceFilePlan, currentRevision,
+  regenerate, install, applyMessage = 'The reviewed token source changes were applied.',
+  regenerationFailureMessage = error => `Source changes were applied, but regeneration failed: ${error instanceof Error ? error.message : String(error)}`,
+}) {
+  if (![loadCodec, assertRevision, assertTarget, archive, loadSource, compilePlan, listConsumers, currentRevision, regenerate, install].every(callback => typeof callback === 'function')) {
+    throw new Error('A token source service requires explicit codec, source, revision, and build callbacks.');
+  }
+  const receipts = new Map();
+  let busy = false; let revision = 0; let disposed = false;
+  const checkActive = signal => {
+    signal.throwIfAborted();
+    if (disposed) throw new Error('The token source service has been disposed.');
+  };
+  const checkRevision = async (value, signal) => {
+    checkActive(signal);
+    if (typeof value !== 'string' || !/^[a-f0-9]{40}$/.test(value)) throw new Error('An exact source revision is required.');
+    await assertRevision(value, signal); checkActive(signal);
+  };
+  const receiptKey = document => keyOf({ sourceRevision: document.sourceRevision, document });
+  const validateRequest = async (input, signal, requireReview = true) => {
+    const request = capture(input);
+    await checkRevision(request?.target?.sourceRevision, signal);
+    if (request.sourceKind !== 'file-plan') throw new Error('A compiled file-plan request is required.');
+    await assertTarget(request.target, signal); checkActive(signal);
+    const receipt = receipts.get(receiptKey(request.document));
+    if (!receipt || receipt.consumed || expired(receipt)) throw new Error('The token source receipt is unavailable or expired. Compile and review again.');
+    if (request.target.sourceRevision !== request.document.sourceRevision || receipt.plan.sourceRevision !== request.target.sourceRevision) throw new Error('The target, token document, and source plan revisions differ.');
+    const beforeFingerprint = fingerprint(receipt.before);
+    const parts = { version: 1, target: request.target, documentId: request.document.id, beforeFingerprint,
+      afterFingerprint: fingerprint(request.document),
+      mappingFingerprint: fingerprint({ version: 1, target: request.target, documentId: request.document.id, baselineFingerprint: beforeFingerprint, files: receipt.plan.proofs }),
+      payloadFingerprint: fingerprint(receipt.plan) };
+    if (fingerprint(request.payload) !== parts.payloadFingerprint || fingerprint(request.identity) !== fingerprint({ ...parts, fingerprint: fingerprint(parts) })) {
+      throw new Error('The complete token document and source plan differ from the reviewed request.');
+    }
+    if (requireReview && !receipt.reviewed.has(request.identity.fingerprint)) throw new Error('Review the complete token source diff for this target first.');
+    return { request, receipt };
+  };
+  const service = {
+    async load(sourceRevision, signal) {
+      await checkRevision(sourceRevision, signal);
+      const codec = await loadCodec();
+      checkActive(signal);
+      const result = await archive(sourceRevision, signal, async ({ appRoot: root }) => {
+        const baseline = await loadSource({ appRoot: root, sourceRevision, codec, signal });
+        checkActive(signal);
+        return capture({ document: baseline.document, proofs: baseline.proofs, sourceFiles: baseline.sourceFiles, ledger: baseline.ledger });
+      });
+      checkActive(signal);
+      return result;
+    },
+    async compile(input, signal) {
+      const { baseline, document } = capture(input);
+      receipts.delete(receiptKey(document));
+      await checkRevision(document.sourceRevision, signal);
+      const codec = await loadCodec();
+      checkActive(signal);
+      const receipt = await archive(document.sourceRevision, signal, async ({ appRoot: root }) => {
+        const actual = await loadSource({ appRoot: root, sourceRevision: document.sourceRevision, codec, signal });
+        checkActive(signal);
+        if (fingerprint(baseline) !== fingerprint({ document: actual.document, proofs: actual.proofs })) throw new Error('The token source baseline differs from the loaded source.');
+        if (document.id !== actual.document.id || actual.document.sourceRevision !== document.sourceRevision) throw new Error('The edited token library differs from the source identity.');
+        await install(root, signal); checkActive(signal);
+        const compiled = await compilePlan({ appRoot: root, sourceRevision: document.sourceRevision, before: actual.document, after: document, codec, signal, dependenciesReady: true });
+        checkActive(signal);
+        const plan = captureSourceFilePlan(compiled, { sourceRevision: document.sourceRevision, allowedFiles: actual.proofs.map(proof => proof.file) });
+        if (plan.version !== 1 || plan.sourceRevision !== document.sourceRevision || fingerprint(plan.proofs) !== fingerprint(actual.proofs)) throw new Error('The compiled plan proofs differ from the loaded source.');
+        if (!plan.changes.length) throw new Error('There are no token source changes to apply.');
+        return { before: capture(actual.document), plan: capture(plan), consumerFiles: [...actual.consumerFiles], reviewed: new Set(), consumed: false, createdAt: Date.now() };
+      });
+
+      checkActive(signal);
+      const key = receiptKey(document); receipts.delete(key); receipts.set(key, receipt);
+      for (const [oldKey, oldReceipt] of receipts) if (expired(oldReceipt)) receipts.delete(oldKey);
+      while (receipts.size > 8) receipts.delete(receipts.keys().next().value);
+      return capture(receipt.plan);
+    },
+    async preview(input, signal) {
+      const { request, receipt } = await validateRequest(input, signal, false);
+      receipt.reviewed.delete(request.identity.fingerprint);
+      const result = await archive(request.target.sourceRevision, signal, ({ appRoot: root }) => previewPlan(root, capture(receipt.plan), {
+        sourceRevision: request.target.sourceRevision, allowedFiles: receipt.plan.changes.map(change => change.file), signal,
+      }));
+      checkActive(signal);
+      if (receipts.get(receiptKey(request.document)) !== receipt || receipt.consumed || expired(receipt)) throw new Error('The token source receipt changed or expired during review. Review again.');
+      completePreview(result, receipt.plan);
+      receipt.reviewed.add(request.identity.fingerprint);
+      return { ...result, revision: ++revision };
+    },
+    async validatePreviewRequest(input, signal) {
+      const { request } = await validateRequest(input, signal);
+      return request;
+    },
+    async apply(input, signal) {
+      const { request, receipt } = await validateRequest(input, signal);
+      receipt.consumed = true; receipts.clear();
+      if (await currentRevision() !== request.target.sourceRevision) throw new Error('The working source revision differs from the selected revision.');
+      checkActive(signal);
+      if (fingerprint(await listConsumers(appRoot, signal)) !== fingerprint(receipt.consumerFiles)) throw new Error('The token consumer file set changed after review. Compile and review again.');
+      checkActive(signal);
+      const result = await applyPlan(appRoot, capture(receipt.plan), {
+        sourceRevision: request.target.sourceRevision, allowedFiles: receipt.plan.changes.map(change => change.file), signal,
+      });
+      receipts.clear();
+      checkActive(signal);
+      if (!result || !Number.isSafeInteger(result.applied) || result.applied < 1) throw new Error('The source writer did not record the reviewed changes. Compile and review again.');
+      try { await regenerate(signal); }
+      catch (error) { return { applied: result.applied, message: regenerationFailureMessage(error) }; }
+      return { applied: result.applied, message: applyMessage };
+    },
+    dispose() { disposed = true; receipts.clear(); },
+  };
+  const operations = new Set();
+  return Object.freeze(Object.fromEntries(Object.entries(service).map(([name, operation]) => [name,
+    name === 'dispose' ? () => {
+      for (const controller of operations) controller.abort(new Error('The token source service has been disposed.'));
+      operation();
+    } : async (input, signal) => {
+      if (disposed) throw new Error('The token source service has been disposed.');
+      signal?.throwIfAborted();
+      const exclusive = name !== 'load';
+      if (exclusive && busy) throw new Error('Another token source operation is in progress.');
+      if (exclusive) busy = true;
+      const controller = new AbortController(); operations.add(controller);
+      const abort = () => controller.abort(signal.reason);
+      signal?.addEventListener('abort', abort, { once: true });
+      try { const result = await operation(input, controller.signal); checkActive(controller.signal); return result; }
+      finally { signal?.removeEventListener('abort', abort); operations.delete(controller); if (exclusive) busy = false; }
+    },
+  ])));
+}

package/node/workspace-draft-entry.mjs

@@ -0,0 +1,52 @@
+function text(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} must be a non-empty string.`);
+  return value;
+}
+
+function literal(value) {
+  const serialized = workspaceSourceFingerprint(value);
+  return serialized.replace(/[<\u2028\u2029]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/** Creates a browser module that reports a mounted draft recipe through the workspace readiness protocol. */
+export function createWorkspaceDraftEntry({
+  documentRevision,
+  recipe,
+  sdkModule = '@pygmalionjs/pygmalion',
+  desiredStateAdapter,
+  failureMessage = 'Draft state could not be reproduced: ',
+}) {
+  text(documentRevision, 'documentRevision');
+  text(sdkModule, 'sdkModule');
+  text(failureMessage, 'failureMessage');
+  if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) throw new TypeError('recipe must be an object.');
+  if (desiredStateAdapter) {
+    text(desiredStateAdapter.module, 'desiredStateAdapter.module');
+    text(desiredStateAdapter.exportName, 'desiredStateAdapter.exportName');
+  }
+  return `import { runWorkspaceDraftRecipe } from ${literal(sdkModule)};
+${desiredStateAdapter ? `import * as desiredStateAdapter from ${literal(desiredStateAdapter.module)};` : ''}
+const controller = new AbortController();
+addEventListener('pagehide', () => controller.abort(), { once: true });
+document.documentElement.dataset.pygmalionDraftStatus = 'preparing';
+Promise.resolve().then(() => {
+  controller.signal.throwIfAborted();
+  return runWorkspaceDraftRecipe({ document, window }, JSON.parse(${literal(workspaceSourceFingerprint(recipe))}), {
+    signal: controller.signal,
+    ${desiredStateAdapter ? `applyDesiredState(state, context) { return desiredStateAdapter[${literal(desiredStateAdapter.exportName)}](state, context); },` : ''}
+  });
+}).then(() => {
+  if (controller.signal.aborted) return;
+  document.documentElement.dataset.pygmalionDraftStatus = 'ready';
+  parent.postMessage({ type: 'pygmalion:workspace-draft-ready', documentRevision: ${literal(documentRevision)}, status: 'ready' }, '*');
+}, error => {
+  if (controller.signal.aborted) return;
+  document.documentElement.dataset.pygmalionDraftStatus = 'failed';
+  const message = document.createElement('div');
+  message.setAttribute('role', 'alert');
+  message.textContent = ${literal(failureMessage)} + String(error?.message ?? error);
+  document.body.prepend(message);
+  parent.postMessage({ type: 'pygmalion:workspace-draft-ready', documentRevision: ${literal(documentRevision)}, status: 'failed', message: message.textContent }, '*');
+});`;
+}
+import { workspaceSourceFingerprint } from './workspace-source-identity.mjs';

package/node/workspace-draft-preview-plugin.mjs

@@ -0,0 +1,70 @@
+import { randomUUID } from 'node:crypto';
+
+/** Local transport for a host-configured isolated builder. The browser supplies no build commands. */
+export function workspaceDraftPreviewPlugin({ service, resolveRequest, waitForReady = false, endpoint = '/__pygmalion-workspace-draft-preview' }) {
+  if (!/^\/[A-Za-z0-9/_-]+$/.test(endpoint) || typeof resolveRequest !== 'function') {
+    throw new Error('Draft preview requires a local endpoint and a host request resolver.');
+  }
+  const leases = new Map();
+  return {
+    name: 'pygmalion-workspace-draft-preview',
+    apply: 'serve',
+    configureServer(server) {
+      server.httpServer?.once('close', () => {
+        for (const controller of leases.values()) controller.abort();
+        leases.clear();
+        void service.dispose().catch(error => server.config.logger.error(String(error)));
+      });
+      server.middlewares.use(async (req, res, next) => {
+        if (req.url?.split('?')[0] !== endpoint) return next();
+        try {
+          if (req.headers.origin && new URL(req.headers.origin).host !== req.headers.host) {
+            res.statusCode = 403; res.end(JSON.stringify({ error: 'Draft preview requires the editor origin.' })); return;
+          }
+        } catch { res.statusCode = 403; res.end(); return; }
+        if (req.method === 'DELETE') {
+          const lease = new URL(req.url, 'http://local.invalid').searchParams.get('lease');
+          leases.get(lease)?.abort(); leases.delete(lease);
+          res.statusCode = 204; res.end(); return;
+        }
+        if (req.method !== 'POST') { res.statusCode = 405; res.end(); return; }
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        req.once('aborted', abort);
+        res.once('close', abort);
+        res.setHeader('content-type', 'application/json; charset=utf-8');
+        res.setHeader('cache-control', 'no-store');
+        try {
+          if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] ?? '')) {
+            res.statusCode = 415; res.end(JSON.stringify({ error: 'Draft preview requires a JSON request.' })); return;
+          }
+          const chunks = []; let bytes = 0;
+          for await (const chunk of req) {
+            bytes += chunk.length;
+            if (bytes > 10 * 1024 * 1024) throw new Error('Draft preview request exceeds the size limit.');
+            chunks.push(chunk);
+          }
+          controller.signal.throwIfAborted();
+          const input = await resolveRequest(JSON.parse(Buffer.concat(chunks).toString('utf8')), { signal: controller.signal });
+          controller.signal.throwIfAborted();
+          const surface = await service.prepare(input, { signal: controller.signal });
+          controller.signal.throwIfAborted();
+          const lease = randomUUID();
+          leases.set(lease, controller);
+          controller.signal.addEventListener('abort', () => leases.delete(lease), { once: true });
+          res.setHeader('x-pygmalion-preview-lease', lease);
+          res.end(JSON.stringify({ surface: waitForReady ? { ...surface, waitForReady: true } : surface, lease }));
+        } catch (error) {
+          controller.abort();
+          if (!res.destroyed && !res.writableEnded) {
+            res.statusCode = 409;
+            res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+          }
+        } finally {
+          req.removeListener('aborted', abort);
+          res.removeListener('close', abort);
+        }
+      });
+    },
+  };
+}

package/node/workspace-draft-preview.mjs

@@ -0,0 +1,232 @@
+import { materializeSourceArchive } from './source-archive.mjs';
+import { createHash } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { writeInspectChanges } from './inspect-writeback.mjs';
+import { validateInspectSourceProofs } from './source-file-proofs.mjs';
+import { applySourceFilePlan } from './source-file-plan.mjs';
+import { workspaceSourceFingerprint } from './workspace-source-identity.mjs';
+import { WORKSPACE_DRAFT_TEMP_PREFIX, WORKSPACE_DRAFT_OUTPUT_DIRECTORY } from './workspace-draft-runtime.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const same = (left, right) => workspaceSourceFingerprint(left) === workspaceSourceFingerprint(right);
+function freeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+function relative(value) {
+  return typeof value === 'string' && value.length > 0 && !/[\\\x00-\x1f\x7f]/.test(value)
+    && !path.posix.isAbsolute(value) && !/^[a-z]:/i.test(value)
+    && !value.split('/').some(part => !part || part === '.' || part === '..' || part === '.git');
+}
+function positive(value, fallback) {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < 1) throw new Error('Preview resource limits must be positive integers.');
+  return selected;
+}
+function validateRoute(route) {
+  if (typeof route !== 'string' || !route.startsWith('/') || route.startsWith('//') || /[\\\x00-\x20\x7f]/.test(route)) throw new Error('The preview route must be an application-relative URL.');
+  const rawPath = decodeURIComponent(route.split(/[?#]/)[0]);
+  if (rawPath.split('/').some(part => part === '.' || part === '..') || rawPath.includes('\\')) throw new Error('The preview route cannot escape the application.');
+  return route;
+}
+
+/** Verify the complete browser capture before materializing source or invoking a build. */
+function captureInput(input) {
+  const captured = JSON.parse(workspaceSourceFingerprint(input));
+  const { request, documentRevision, route } = captured ?? {};
+  const { target, document, identity, payload } = request ?? {};
+  if (request?.sourceKind !== undefined && request.sourceKind !== 'file-plan') throw new Error('The draft preview request has an unsupported source kind.');
+  if (!target || !document || !identity || !payload || !/^(?:[a-f\d]{40}|[a-f\d]{64})$/.test(target.sourceRevision ?? '')
+    || typeof target.screenId !== 'string' || !target.screenId.trim() || identity.version !== 1
+    || document.schemaVersion !== 1 || document.id !== identity.documentId || document.sourceRevision !== target.sourceRevision
+    || !same(identity.target, target) || identity.afterFingerprint !== workspaceSourceFingerprint(document)
+    || identity.payloadFingerprint !== workspaceSourceFingerprint(payload)) throw new Error('The draft preview request has inconsistent document, payload, or source identity.');
+  const { fingerprint, ...parts } = identity;
+  if (fingerprint !== workspaceSourceFingerprint(parts) || documentRevision !== hash(identity.afterFingerprint)) throw new Error('The draft revision must hash the complete captured document identity.');
+  let before; let mapping;
+  try {
+    before = JSON.parse(identity.beforeFingerprint);
+    mapping = JSON.parse(identity.mappingFingerprint);
+  } catch { throw new Error('The draft preview requires complete source baseline and mapping fingerprints.'); }
+  if (workspaceSourceFingerprint(before) !== identity.beforeFingerprint || workspaceSourceFingerprint(mapping) !== identity.mappingFingerprint
+    || before.id !== document.id || before.sourceRevision !== target.sourceRevision || mapping.version !== 1
+    || mapping.documentId !== document.id || mapping.baselineFingerprint !== identity.beforeFingerprint || !same(mapping.target, target)) throw new Error('The captured source baseline, mapping, and file proofs must agree.');
+  if (request.sourceKind === 'file-plan') {
+    if (payload.version !== 1 || payload.sourceRevision !== target.sourceRevision || !Array.isArray(payload.proofs)
+      || !same(mapping.files, payload.proofs)) throw new Error('The captured file plan, mapping, and file proofs must agree.');
+  } else if (!payload.sourceProof || payload.sourceProof.sourceRevision !== target.sourceRevision || !same(mapping.files, payload.sourceProof.files)) {
+    throw new Error('The captured source baseline, mapping, and file proofs must agree.');
+  }
+  validateRoute(route);
+  return freeze(captured);
+}
+
+async function captureOutput(outputDirectory, { maxOutputFiles, maxOutputBytes }, signal) {
+  const files = new Map(); let total = 0;
+  const visit = async (directory, prefix) => {
+    const directoryStat = await fsp.lstat(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) throw new Error('Build output directories must not be symbolic links.');
+    for (const entry of await fsp.readdir(directory, { withFileTypes: true })) {
+      signal.throwIfAborted();
+      const key = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (!relative(key)) throw new Error('Build output contains an unsafe path.');
+      const absolute = path.join(directory, entry.name);
+      const stat = await fsp.lstat(absolute);
+      if (stat.isDirectory()) { await visit(absolute, key); continue; }
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Build output must contain regular files only.');
+      if (files.size >= maxOutputFiles || total + stat.size > maxOutputBytes) throw new Error('The built preview exceeds its output resource limits.');
+      const bytes = await fsp.readFile(absolute, { signal });
+      if (bytes.length !== stat.size) throw new Error('Build output changed while it was captured.');
+      total += bytes.length; files.set(key, bytes);
+    }
+  };
+  await visit(outputDirectory, '');
+  if (!files.has('index.html')) throw new Error('The built application requires index.html.');
+  return files;
+}
+
+const mimeTypes = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.map': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.ico': 'image/x-icon',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.wasm': 'application/wasm', '.txt': 'text/plain; charset=utf-8' };
+function closeServer(server) {
+  if (!server) return Promise.resolve();
+  return new Promise(resolve => { server.close(() => resolve()); server.closeAllConnections(); });
+}
+
+/**
+ * Build in a disposable archive and serve only captured bytes from a separate loopback origin.
+ * The host must first validate file-plan requests against its canonical source compiler.
+ * Identity consistency and archived file proofs do not establish a document-to-source mapping.
+ * The archive is the request's exact commit; a request for another revision than the
+ * checked-out one builds that revision's files, never the working tree relabelled.
+ */
+export function createWorkspaceDraftPreviewService(options) {
+  if (!options || typeof options.projectRoot !== 'string' || typeof options.build !== 'function') throw new Error('A draft preview service requires a project root and trusted build callback.');
+  if (options.prepareSource !== undefined && typeof options.prepareSource !== 'function') throw new Error('Source preparation must be a trusted host callback.');
+  const projectRoot = path.resolve(options.projectRoot);
+  const appDirectory = options.appDirectory ?? '.';
+  if (appDirectory !== '.' && !relative(appDirectory)) throw new Error('The application directory must be project-relative.');
+  const maxRuns = positive(options.maxRuns, 3);
+  const limits = { maxOutputFiles: positive(options.maxOutputFiles, 10000), maxOutputBytes: positive(options.maxOutputBytes, 128 * 1024 * 1024) };
+  const build = options.build; const handleRequest = options.handleRequest; const prepareSource = options.prepareSource;
+  const dependenciesRoot = options.dependenciesRoot ? path.resolve(options.dependenciesRoot) : null;
+  const runs = new Set(); let disposed = false; let disposal;
+
+  const prepare = (input, { signal } = {}) => {
+    if (disposed) return Promise.reject(new Error('The draft preview service has been disposed.'));
+    if (signal?.aborted) return Promise.reject(signal.reason ?? new Error('Draft preview was aborted.'));
+    if (runs.size >= maxRuns) return Promise.reject(new Error('The draft preview service has reached its active run limit.'));
+    let captured;
+    try { captured = captureInput(input); } catch (error) { return Promise.reject(error); }
+    const controller = new AbortController();
+    const run = { controller, server: null, files: null, temporary: null, done: null };
+    const abort = () => { controller.abort(signal?.reason); void closeServer(run.server); };
+    signal?.addEventListener('abort', abort, { once: true });
+    runs.add(run);
+    run.done = (async () => {
+      let ready = false;
+      try {
+        run.temporary = await fsp.mkdtemp(path.join(os.tmpdir(), WORKSPACE_DRAFT_TEMP_PREFIX));
+        controller.signal.throwIfAborted();
+        // The archive holds exactly the requested commit, whatever the repository's
+        // working tree or HEAD currently contains. Every host callback receives that
+        // commit so a build for one revision can never be labelled as another.
+        const sourceRevision = captured.request.target.sourceRevision;
+        const appRoot = await materializeSourceArchive(projectRoot, appDirectory, sourceRevision, run.temporary, controller.signal);
+        controller.signal.throwIfAborted();
+        // A trusted host may stage its reviewed working-copy inputs in this archive.
+        // Full request proofs are still checked below, after the callback settles.
+        if (prepareSource) await prepareSource({ appRoot, request: captured.request, sourceRevision, signal: controller.signal });
+        controller.signal.throwIfAborted();
+        if (captured.request.sourceKind === 'file-plan') {
+          await applySourceFilePlan(appRoot, captured.request.payload, {
+            sourceRevision: captured.request.target.sourceRevision,
+            allowedFiles: captured.request.payload.changes.map(change => change.file),
+            signal: controller.signal,
+          });
+        } else {
+          await validateInspectSourceProofs(appRoot, captured.request.payload, { sourceRevision: captured.request.target.sourceRevision });
+          controller.signal.throwIfAborted();
+          await writeInspectChanges(appRoot, captured.request.payload);
+        }
+        controller.signal.throwIfAborted();
+        if (dependenciesRoot) {
+          const dependencies = await fsp.realpath(dependenciesRoot);
+          if (!(await fsp.stat(dependencies)).isDirectory()) throw new Error('The dependency root must identify an existing node_modules directory.');
+          await fsp.symlink(dependencies, path.join(appRoot, 'node_modules'), 'dir');
+        }
+        const outputDirectory = path.join(run.temporary, WORKSPACE_DRAFT_OUTPUT_DIRECTORY);
+        await fsp.mkdir(outputDirectory);
+        await build({ appRoot, outputDirectory, request: captured.request, sourceRevision, signal: controller.signal });
+        controller.signal.throwIfAborted();
+        run.files = await captureOutput(outputDirectory, limits, controller.signal);
+        await fsp.rm(run.temporary, { recursive: true, force: true }); run.temporary = null;
+        controller.signal.throwIfAborted();
+        let authority;
+        const server = http.createServer((request, response) => {
+          void (async () => {
+            response.setHeader('cache-control', 'no-store'); response.setHeader('x-content-type-options', 'nosniff');
+            if (request.headers.host !== authority) { response.writeHead(403).end('Unexpected preview origin.'); return; }
+            if (handleRequest) {
+              const handled = await handleRequest(request, response, { request: captured.request, sourceRevision });
+              if (handled || response.headersSent || response.writableEnded) return;
+            }
+            if (!['GET', 'HEAD'].includes(request.method)) { response.writeHead(405, { allow: 'GET, HEAD' }).end(); return; }
+            let pathname;
+            try { pathname = decodeURIComponent(new URL(request.url, `http://${authority}`).pathname); }
+            catch { response.writeHead(400).end(); return; }
+            if (pathname.includes('\\') || pathname.split('/').some(part => part === '..' || part === '.')) { response.writeHead(400).end(); return; }
+            let key = pathname.slice(1) || 'index.html';
+            let bytes = run.files?.get(key);
+            if (!bytes && !path.posix.extname(key)) { key = 'index.html'; bytes = run.files?.get(key); }
+            if (!bytes) { response.writeHead(404).end(); return; }
+            response.writeHead(200, { 'content-type': mimeTypes[path.posix.extname(key)] ?? 'application/octet-stream', 'content-length': bytes.length });
+            response.end(request.method === 'HEAD' ? undefined : bytes);
+          })().catch(() => { if (response.headersSent) response.destroy(); else response.writeHead(500).end('Preview request failed.'); });
+        });
+        run.server = server;
+        await new Promise((resolve, reject) => {
+          const aborted = () => reject(controller.signal.reason ?? new Error('Draft preview was aborted.'));
+          const cleanup = () => { controller.signal.removeEventListener('abort', aborted); server.off('error', failed); };
+          const failed = error => { cleanup(); reject(error); };
+          controller.signal.addEventListener('abort', aborted, { once: true });
+          server.once('error', failed);
+          server.listen({ host: '127.0.0.1', port: 0, signal: controller.signal }, () => { cleanup(); resolve(); });
+        });
+        controller.signal.throwIfAborted();
+        authority = `127.0.0.1:${server.address().port}`;
+        ready = true;
+        return Object.freeze({ url: `http://${authority}${captured.route}`, documentRevision: captured.documentRevision });
+      } finally {
+        if (!ready) {
+          await closeServer(run.server);
+          if (run.temporary) await fsp.rm(run.temporary, { recursive: true, force: true });
+          run.files?.clear(); runs.delete(run); signal?.removeEventListener('abort', abort);
+        }
+      }
+    })();
+    controller.signal.addEventListener('abort', () => {
+      void closeServer(run.server).then(() => {
+        if (!run.temporary) { run.files?.clear(); runs.delete(run); signal?.removeEventListener('abort', abort); }
+      });
+    }, { once: true });
+    return run.done;
+  };
+
+  return Object.freeze({ prepare, dispose() {
+    if (disposal) return disposal;
+    disposed = true;
+    const active = [...runs]; active.forEach(run => run.controller.abort(new Error('The draft preview service was disposed.')));
+    disposal = (async () => {
+      await Promise.allSettled(active.map(run => run.done));
+      await Promise.all(active.map(async run => { await closeServer(run.server); if (run.temporary) await fsp.rm(run.temporary, { recursive: true, force: true }); run.files?.clear(); runs.delete(run); }));
+    })();
+    return disposal;
+  } });
+}
+
+export { workspaceDraftPreviewPlugin } from './workspace-draft-preview-plugin.mjs';

package/node/workspace-draft-process.mjs

@@ -0,0 +1,129 @@
+import { execFile, spawn } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+
+function signalGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+async function hasRunningGroup(pid) {
+  if (!signalGroup(pid, 0)) return false;
+  let stdout;
+  try {
+    ({ stdout } = await execute('ps', ['-ax', '-o', 'pgid=,stat='], { timeout: 5_000 }));
+  } catch {
+    if (process.platform === 'linux') {
+      try {
+        for (const entry of await readdir('/proc')) {
+          if (!/^\d+$/.test(entry)) continue;
+          const stat = await readFile(`/proc/${entry}/stat`, 'utf8').catch(error => {
+            if (error.code === 'ENOENT' || error.code === 'ESRCH') return '';
+            throw error;
+          });
+          // Parenthesized command names may contain spaces and closing parentheses.
+          const [state, , group] = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+          if (Number(group) === pid && state !== 'Z') return true;
+        }
+        return false;
+      } catch { /* Keep the process group alive until its state can be determined. */ }
+    }
+    // An unavailable inspector cannot authorize cleanup while descendants remain.
+    return signalGroup(pid, 0);
+  }
+  return stdout.split('\n').some(line => {
+    const [group, status] = line.trim().split(/\s+/);
+    // Reaping belongs to the operating system; zombies cannot write source files.
+    return Number(group) === pid && status && !status.startsWith('Z');
+  });
+}
+
+async function terminateGroup(pid, graceMs) {
+  if (!pid || !signalGroup(pid, 'SIGTERM')) return;
+  const deadline = Date.now() + graceMs;
+  while (await hasRunningGroup(pid)) {
+    if (Date.now() >= deadline) signalGroup(pid, 'SIGKILL');
+    await delay(25);
+  }
+}
+
+/** Resolve or reject only after the command and its process group stop writing. */
+export async function executeWorkspaceDraftProcess(command, args, {
+  signal, timeout = 240_000, terminationGraceMs = 1_000, maxBuffer = 8 * 1024 * 1024, ...options
+} = {}) {
+  signal?.throwIfAborted();
+  if (process.platform === 'win32') {
+    throw new Error('Draft process group cleanup supports macOS and Linux.');
+  }
+  if (!Number.isFinite(timeout) || timeout < 0 || timeout > 2 ** 31 - 1
+    || !Number.isFinite(terminationGraceMs) || terminationGraceMs < 0
+    || !Number.isSafeInteger(maxBuffer) || maxBuffer < 0) {
+    throw new TypeError('Process timeout, termination grace, and output limits must be finite non-negative values.');
+  }
+  let child;
+  let termination;
+  let cancellation;
+  let cancelled = false;
+  let timeoutHandle;
+  const terminate = () => {
+    termination ??= terminateGroup(child?.pid, terminationGraceMs);
+    // Observe termination failure while the process close event is still pending.
+    void termination.catch(() => {});
+    return termination;
+  };
+  const cancel = reason => {
+    if (!cancelled) { cancelled = true; cancellation = reason; }
+    void terminate();
+  };
+  const onAbort = () => cancel(signal.reason ?? new DOMException('Draft execution cancelled.', 'AbortError'));
+  const closed = new Promise(resolve => {
+    // spawn owns the detached process group; execFile does not forward detached.
+    child = spawn(command, args, { ...options, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = []; const stderr = [];
+    let stdoutSize = 0; let stderrSize = 0; let spawnError;
+    const append = (chunks, chunk, size) => {
+      if (size > maxBuffer) {
+        const error = Object.assign(new Error('Draft process output exceeded its byte limit.'), {
+          code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+        });
+        cancel(error);
+      } else chunks.push(chunk);
+    };
+    child.stdout.on('data', chunk => { stdoutSize += chunk.length; append(stdout, chunk, stdoutSize); });
+    child.stderr.on('data', chunk => { stderrSize += chunk.length; append(stderr, chunk, stderrSize); });
+    child.once('error', error => { spawnError = error; });
+    child.once('close', (code, exitSignal) => {
+      const out = Buffer.concat(stdout).toString(); const err = Buffer.concat(stderr).toString();
+      const error = spawnError ?? (code === 0 ? undefined : Object.assign(
+        new Error(`Draft process failed (${exitSignal ?? code}).${err ? `\n${err}` : ''}`),
+        { code, signal: exitSignal, stdout: out, stderr: err },
+      ));
+      resolve({ error, stdout: out, stderr: err });
+    });
+    // Successful or failed leaders may leave descendants behind as well.
+    child.once('exit', terminate);
+  });
+  signal?.addEventListener('abort', onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+  if (timeout > 0) {
+    timeoutHandle = setTimeout(() => cancel(new DOMException('Draft execution timed out.', 'TimeoutError')), timeout);
+  }
+  try {
+    const result = await closed;
+    await terminate();
+    if (cancelled) throw cancellation;
+    if (result.error) throw result.error;
+    return { stdout: result.stdout, stderr: result.stderr };
+  } finally {
+    clearTimeout(timeoutHandle);
+    signal?.removeEventListener('abort', onAbort);
+  }
+}