@reqvire-org/ads 0.0.0-stage → 0.3.0

package/dist/mcp/mutations.mjs

@@ -0,0 +1,301 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { isInside, loadConfig } from "../config.mjs";
+import { checkProject } from "../check.mjs";
+import { generateLintConfig } from "../lint-config.mjs";
+import { generateBrandAssets } from "../brand-assets.mjs";
+import { projectContext } from "./context.mjs";
+import { applyFilePatch, parseUnifiedPatch } from "./patch.mjs";
+import { checkUnitCandidate, checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
+
+export const mutationLimits = { files: 32, patchBytes: 256 * 1024, patchFileBytes: 16 * 1024 * 1024, fileBytes: 16 * 1024 * 1024, readChars: 12000, snapshotFiles: 20000, snapshotBytes: 128 * 1024 * 1024 };
+const digest = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const ignored = new Set([".git", ".ds", "node_modules", ".vite", "coverage", ".playwright-cli", "test-results", "output"]);
+const textFile = file => /\.(?:[cm]?[jt]sx?|css|html|jsonc?|md|txt|svg)$/.test(file);
+const setupDotfile = file => /^\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?$/.test(file);
+
+function fail(rule, message, file) {
+  return Object.assign(new Error(message), { diagnostic: { rule, message, ...(file ? { file } : {}) } });
+}
+
+function address(options, file) {
+  if (typeof file !== "string" || !file || file.includes("\\") || file.includes("\0") || file.split("/").some(part => !part || part === "." || part === "..") || path.isAbsolute(file)) throw fail("mutation-path", "Use a canonical project-relative ADS file path.", file);
+  const target = path.resolve(options.root, file);
+  if (!isInside(options.root, target) || target === options.root) throw fail("mutation-path", "Mutation paths must stay inside the project.", file);
+  for (let current = options.root; ; ) {
+    const relative = path.relative(current, target).split(path.sep);
+    if (relative.some(part => ignored.has(part) || part.startsWith(".") && !setupDotfile(part))) throw fail("mutation-path", "Hidden, dependency and generated paths are not editable.", file);
+    current = path.join(current, relative[0]);
+    const stat = lstatSync(current, { throwIfNoEntry: false });
+    if (stat?.isSymbolicLink() || stat && current !== target && !stat.isDirectory() || stat && current === target && (!stat.isFile() || stat.nlink !== 1)) throw fail("mutation-path", "Mutation paths must contain ordinary directories and unlinked regular files.", file);
+    if (current === target) break;
+  }
+  if (options.config.assets.generatedPaths.some(entry => isInside(path.resolve(options.root, entry), target))) throw fail("mutation-path", "Generated output is not editable.", file);
+  if (options.config.assets.generatedFiles.some(entry => target === path.resolve(options.dsRoot, "assets", entry))) throw fail("mutation-path", "Generated brand files are outputs; edit their source instead.", file);
+  return target;
+}
+
+function readPatchFile(options, file) {
+  if (typeof file !== "string" || file.includes("\\") || file.includes("\0") || !/^\.ds\/patches\/[^/]+\.(?:patch|diff)$/.test(file)) throw fail("mutation-patch", "Patch files must be regular .patch/.diff files in .ds/patches/.");
+  const target = path.join(options.root, file);
+  for (const current of [path.join(options.root, ".ds"), path.dirname(target), target]) {
+    const stat = lstatSync(current, { throwIfNoEntry: false });
+    if (!stat || stat.isSymbolicLink() || current !== target && !stat.isDirectory() || current === target && (!stat.isFile() || stat.nlink !== 1 || stat.size > mutationLimits.patchFileBytes)) throw fail("mutation-patch", "Patch files must be real files no larger than 16 MiB.");
+  }
+  const bytes = readFileSync(target);
+  if (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes)) throw fail("mutation-patch", "Patch files must contain UTF-8 Git diff text.");
+  return bytes.toString("utf8");
+}
+
+function read(options, file) {
+  const target = address(options, file);
+  if (!existsSync(target)) return { path: file, exists: false, digest: null, content: null };
+  if (lstatSync(target).size > mutationLimits.fileBytes) throw fail("mutation-content", "File exceeds the 16 MiB mutation size limit.", file);
+  const bytes = readFileSync(target);
+  const binary = bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes);
+  return { path: file, exists: true, digest: digest(bytes), bytes: bytes.length, binary, content: binary ? bytes : bytes.toString("utf8") };
+}
+
+function validateContent(change, unit) {
+  if (change.content === null) return;
+  const bytes = Buffer.from(change.content);
+  if (bytes.length > mutationLimits.fileBytes) throw fail("mutation-content", "The patched file exceeds 16 MiB.", change.path);
+  if (textFile(change.path) && (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes))) throw fail("mutation-content", "Text source must contain valid UTF-8 without NUL bytes.", change.path);
+  if (/\.jsonc?$/.test(change.path)) {
+    const content=bytes.toString("utf8");
+    if (unit === "configuration" && !["package.json","ds.config.json"].includes(path.basename(change.path))) {
+      if (ts.parseConfigFileTextToJson(change.path,content).error) throw fail("mutation-syntax", "Configuration must contain valid JSON/JSONC.", change.path);
+    } else { try { JSON.parse(content); } catch { throw fail("mutation-syntax", "JSON source and configuration must be valid JSON.", change.path); } }
+  }
+  if (unit !== "configuration" && /\b(?:oxlint|eslint)-(?:disable|enable)|\bbiome-ignore|@ts-(?:ignore|nocheck|expect-error)/.test(bytes.toString("utf8"))) throw fail("mutation-policy", "Configure reviewed lint/typecheck exceptions through the configuration unit instead of source suppression directives.", change.path);
+}
+
+function snapshot(options, destination) {
+  const entries = [];
+  let bytes = 0;
+  const generated = options.config.assets.generatedPaths.map(file => path.resolve(options.root, file));
+  function walk(folder) {
+    for (const entry of readdirSync(folder, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (ignored.has(entry.name)) continue;
+      const file = path.join(folder, entry.name);
+      const relative = path.relative(options.root, file);
+      if (generated.some(base => isInside(base, file))) continue;
+      const target = destination && path.join(destination, relative);
+      if (entry.isSymbolicLink()) throw fail("mutation-snapshot", "Project source symlinks require an ordinary project copy for guarded validation.", relative);
+      if (entry.isDirectory()) { if (target) mkdirSync(target, { recursive: true }); walk(file); }
+      else if (entry.isFile()) {
+        if (bytes + lstatSync(file).size > mutationLimits.snapshotBytes || entries.length >= mutationLimits.snapshotFiles) throw fail("mutation-snapshot", "Project source exceeds the bounded validation snapshot limit.");
+        const content = readFileSync(file);
+        bytes += content.length;
+        if (bytes > mutationLimits.snapshotBytes || entries.length >= mutationLimits.snapshotFiles) throw fail("mutation-snapshot", "Project source exceeds the bounded validation snapshot limit.");
+        entries.push([relative, digest(content)]);
+        if (target) writeFileSync(target, content, { mode: lstatSync(file).mode });
+      }
+    }
+  }
+  walk(options.root);
+  // Package installation changes also invalidate a candidate's validation.
+  const installed = path.join(options.root, "node_modules/.package-lock.json");
+  entries.push(["installed-dependencies", existsSync(installed) ? digest(readFileSync(installed)) : null]);
+  return JSON.stringify(entries);
+}
+
+function checkCommand(command, args, cwd, signal, input) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(fail("mutation-cancelled", "Mutation cancelled before validation.")); return; }
+    const child = spawn(command, args, { cwd, shell: false, detached: process.platform !== "win32", windowsHide: true, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      env: { ...process.env, PATH: [path.join(cwd, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) } });
+    let output = "", failure;
+    if (input !== undefined) { child.stdin.on("error", () => {}); child.stdin.end(input); }
+    function kill() {
+      if (!child.pid) return;
+      if (process.platform === "win32") {
+        const stop = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        stop.on("error", () => child.kill("SIGKILL"));
+      } else { try { process.kill(-child.pid, "SIGKILL"); } catch (error) { if (error.code !== "ESRCH") failure ??= error; } }
+    }
+    const abort = () => { failure = fail("mutation-cancelled", "Mutation cancelled during validation."); kill(); };
+    signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => { failure = fail("mutation-check", "A mutation check exceeded 60 seconds."); kill(); }, 60000);
+    for (const stream of [child.stdout, child.stderr]) stream.on("data", chunk => { output = (output + chunk.toString()).slice(-12000); });
+    child.once("error", error => { failure = error; });
+    child.once("exit", kill); // Also clean up descendants of a finished launcher.
+    child.once("close", code => {
+      clearTimeout(timer); signal?.removeEventListener("abort", abort);
+      if (failure) reject(failure);
+      else if (code !== 0) reject(fail("mutation-check", `${path.basename(command)} ${args.join(" ")} failed (${code}).\n${output}`));
+      else resolve({ command: path.basename(command), args, passed: true });
+    });
+  });
+}
+
+function checks(options) {
+  const context = projectContext(options);
+  const pkg = JSON.parse(readFileSync(path.join(options.root, "package.json"), "utf8"));
+  const scripts = options.config.mcp.mutationChecks ?? [pkg.scripts?.["lint:project"] ? "lint:project" : "lint", "typecheck", "build:mcp-previews"].filter(name => typeof pkg.scripts?.[name] === "string");
+  if (scripts.some(name => typeof pkg.scripts?.[name] !== "string")) throw fail("mutation-check", "Every configured mcp.mutationChecks script must exist in package.json.");
+  if (scripts.length && !["npm", "bun"].includes(context.packageManager)) throw fail("mutation-check", "Declare packageManager as npm or bun to run mutation checks.");
+  return scripts.map(script => ({ command: context.packageManager, args: ["run", script] }));
+}
+
+export function createMutationController(directory) {
+  const root = path.resolve(directory);
+  let busy = false;
+  let lastResult = null;
+  let active;
+  return {
+    status() {
+      const options = loadConfig(root);
+      let commands = [], diagnostics = [];
+      try { commands = checks(options).map(check => [check.command, ...check.args].join(" ")); }
+      catch (error) { diagnostics = [error.diagnostic ?? { rule: "mutation-check", message: error.message }]; }
+      return { enabled: true, scope: "one-ds-unit", format: "git-unified-diff", dsDir: options.config.dsDir, limits: mutationLimits, checks: ["ads check", "registered Oxlint rules", ...commands], diagnostics, busy, lastResult };
+    },
+    cancel() { active?.abort(); },
+    units() { return inspectUnits(loadConfig(root)).units; },
+    read(file, { offset = 0, limit = mutationLimits.readChars } = {}) {
+      if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > mutationLimits.readChars) throw fail("mutation-range", "Use a non-negative character offset and a limit between 1 and 12000.", file);
+      const options = loadConfig(root), source = read(options, file);
+      const inventory = inspectUnits(options), unit = inventory.owner(inventory.relative(file));
+      if (!unit && inventory.relative(file) !== inventory.publicEntry) throw fail("mutation-unit", "This file is outside the project's ADS and registered configuration/extension units.", file);
+      if (!source.exists) return { ...source, offset: 0, nextOffset: null, totalChars: 0, startLine: 1 };
+      if (source.binary) return { ...source, unit, content: null, note: "Binary asset: inspect its metadata or preview; edit using a Git binary patch, optionally through patchFile." };
+      if (offset > source.content.length) throw fail("mutation-range", "Read offset exceeds the current file length.", file);
+      const content = source.content.slice(offset, offset + limit), end = offset + content.length;
+      return { ...source, unit, content, offset, nextOffset: end < source.content.length ? end : null, totalChars: source.content.length,
+        startLine: source.content.slice(0, offset).split("\n").length };
+    },
+    async apply({ unit, patch, patchFile, dryRun = false }, signal) {
+      if (busy) return { ok: false, applied: false, diagnostics: [{ rule: "mutation-busy", message: "Another mutation is validating; retry after it finishes." }] };
+      busy = true;
+      active = new AbortController();
+      signal = signal ? AbortSignal.any([signal, active.signal]) : active.signal;
+      let temporary;
+      const verified = [];
+      try {
+        const options = loadConfig(root);
+        validateUnitId(unit);
+        if ((typeof patch === "string") === (typeof patchFile === "string")) throw fail("mutation-patch", "Provide exactly one of patch or patchFile.");
+        const maxPatch = patchFile === undefined ? mutationLimits.patchBytes : mutationLimits.patchFileBytes;
+        if (patchFile !== undefined) patch = readPatchFile(options, patchFile);
+        if (typeof patch !== "string" || patch.includes("\0") || Buffer.from(patch).toString("utf8") !== patch || Buffer.byteLength(patch) > maxPatch) throw fail("mutation-patch", "Patch exceeds its UTF-8 Git diff size limit.");
+        const entries = parseUnifiedPatch(patch, mutationLimits.files), changes = [];
+        const originals = entries.map(entry => {
+          const change = { path: entry.path };
+          const target = address(options, change.path);
+          const before = read(options, change.path);
+          if (!entry.binary && before.binary) throw fail("mutation-patch", "Binary assets require a git diff --binary patch.", change.path);
+          change.content = entry.binary ? entry.operation === "delete" ? null : before.content ?? Buffer.alloc(0) : applyFilePatch(entry, before.content);
+          if (entry.binary) change.binaryPatch = entry.patch;
+          change.expectedDigest = before.digest;
+          change.originalContent = before.content;
+          if (!entry.binary) validateContent(change, unit);
+          changes.push(change);
+          return { ...before, mode: before.exists ? lstatSync(target).mode : undefined };
+        });
+        const inventory = checkUnitFiles(options, unit, changes, inspectUnits(options), true);
+        const cache = path.join(root, ".ds");
+        mkdirSync(cache, { recursive: true });
+        if (realpathSync(cache) !== path.join(realpathSync(root), ".ds")) throw fail("mutation-path", "The .ds directory cannot resolve through a symlink.");
+        temporary = mkdtempSync(path.join(cache, "mutation-"));
+        const candidate = path.join(temporary, "project");
+        mkdirSync(candidate);
+        const before = snapshot(options, candidate);
+        for (const original of originals) if (read(options, original.path).digest !== original.digest) throw fail("mutation-conflict", "Source changed while preparing the validation copy. Read the affected range and regenerate the patch.", original.path);
+        const dependencies = path.join(root, "node_modules");
+        if (!existsSync(dependencies)) throw fail("mutation-check", "Install project dependencies before using guarded mutations.");
+        symlinkSync(realpathSync(dependencies), path.join(candidate, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+        // The tooling repository's own scripts run dist/cli.mjs. Preserve that
+        // already-built runtime without treating generated output as source.
+        if (existsSync(path.join(root, "dist")) && !existsSync(path.join(candidate, "dist"))) {
+          let count = 0, bytes = 0;
+          cpSync(path.join(root, "dist"), path.join(candidate, "dist"), { recursive: true, filter(file) {
+            const stat = lstatSync(file);
+            if (stat.isSymbolicLink()) throw fail("mutation-snapshot", "Generated runtime copies cannot contain symlinks.");
+            if (stat.isFile()) { bytes += stat.size; ++count; }
+            if (count > mutationLimits.snapshotFiles || bytes > mutationLimits.snapshotBytes) throw fail("mutation-snapshot", "Generated runtime exceeds the validation snapshot limit.");
+            return true;
+          } });
+        }
+        if (entries.some(entry => entry.binary)) {
+          const formats = new Set(entries.filter(entry=>entry.binary).map(entry=>entry.objectFormat));
+          if (formats.size !== 1) throw fail("mutation-patch", "Binary blocks in one Git diff must use the same object format.");
+          await checkCommand("git", ["init", "--quiet", `--object-format=${[...formats][0]}`, candidate], root, signal);
+        }
+        for (const change of changes) {
+          const file = path.join(candidate, change.path);
+          if (change.binaryPatch) {
+            for (const match of change.binaryPatch.matchAll(/^(?:literal|delta) (\d+)$/gm)) if (Number(match[1]) > mutationLimits.fileBytes) throw fail("mutation-content", "Binary patch blocks exceed 16 MiB.", change.path);
+            await checkCommand("git", ["apply", "--binary", "--whitespace=nowarn", "-"], candidate, signal, change.binaryPatch);
+            change.content = existsSync(file) ? readFileSync(file) : null;
+            validateContent(change, unit);
+          }
+          else if (change.content === null) rmSync(file);
+          else { mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, change.content); }
+        }
+        const candidateOptions = loadConfig(candidate);
+        checkUnitCandidate(candidateOptions, unit, changes, inventory);
+        const extraChecks = checks(candidateOptions);
+        const expected = snapshot(candidateOptions);
+        const result = checkProject(candidate, { trackingRoot: root });
+        if (!result.ok) return lastResult = { ok: false, applied: false, diagnostics: result.diagnostics.slice(0, 50), total: result.diagnostics.length, checks: verified };
+        verified.push({ name: "ads check", passed: true });
+        const lintConfig = generateLintConfig(candidate).file;
+        const require = createRequire(path.join(candidate, "package.json"));
+        const oxlintPackage = require.resolve("oxlint/package.json");
+        const bin = JSON.parse(readFileSync(oxlintPackage, "utf8")).bin;
+        const executable = path.resolve(path.dirname(oxlintPackage), typeof bin === "string" ? bin : bin.oxlint);
+        const lintPaths = [candidateOptions.config.sourceDir, candidateOptions.config.dsDir].filter(file => existsSync(path.join(candidate, file)));
+        if (unit === "configuration") for (const file of inspectUnits(candidateOptions).units.find(item => item.id === "configuration").files) {
+          if (/\.[cm]?[jt]sx?$/.test(file) && !lintPaths.some(directory => isInside(path.resolve(candidate, directory), path.resolve(candidate, file)))) lintPaths.push(file);
+        }
+        await checkCommand(process.execPath, [executable, "--deny-warnings", "--config", lintConfig, ...lintPaths], candidate, signal);
+        verified.push({ name: "registered Oxlint rules", passed: true });
+        if (unit.startsWith("assets") || unit === "configuration") {
+          const brand = await generateBrandAssets(candidate);
+          verified.push({ name: "brand assets", passed: true, skipped: !!brand.skipped });
+        }
+        for (const check of extraChecks) verified.push(await checkCommand(check.command, check.args, candidate, signal));
+        if (signal?.aborted) throw fail("mutation-cancelled", "Mutation cancelled before application.");
+        if (snapshot(candidateOptions) !== expected) throw fail("mutation-check", "A validation command changed source files. Use checks without source-writing side effects.");
+        if (snapshot(loadConfig(root)) !== before) throw fail("mutation-conflict", "Project inputs changed during validation; no changes were applied. Read current source and retry.");
+        for (const change of changes) address(options, change.path);
+        if (!dryRun) {
+          const written = [];
+          const directories = [];
+          function mkdir(directory) { if (!existsSync(directory)) { mkdir(path.dirname(directory)); mkdirSync(directory); directories.push(directory); } }
+          function replace(file, content, mode) {
+            mkdir(path.dirname(file));
+            const staged = path.join(path.dirname(file), `.ads-edit-${randomUUID()}`);
+            try { writeFileSync(staged, content, { mode }); renameSync(staged, file); }
+            finally { rmSync(staged, { force: true }); }
+          }
+          try {
+            changes.forEach((change, index) => {
+              const file = address(options, change.path);
+              if (change.content === null) rmSync(file); else replace(file, change.content, originals[index].mode);
+              written.push(index);
+            });
+          } catch (error) {
+            for (const index of written.reverse()) {
+              const original = originals[index], file = path.join(root, original.path);
+              if (original.exists) replace(file, original.content, original.mode); else rmSync(file, { force: true });
+            }
+            for (const directory of directories.reverse()) if (!readdirSync(directory).length) rmSync(directory, { recursive: true });
+            throw error;
+          }
+        }
+        const warnings = [];
+        if (!dryRun && (unit.startsWith("assets") || unit === "configuration")) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
+        return lastResult = { ok: true, unit, applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(warnings.length ? { warnings } : {}),
+          preview: "Source validation passed. Inspect the managed preview build and rendered scenario after applying; validation is not visual verification." };
+      } catch (error) {
+        return lastResult = { ok: false, applied: false, diagnostics: [error.diagnostic ?? { rule: "mutation-error", message: error.message }], checks: verified };
+      } finally { try { if (temporary) rmSync(temporary, { recursive: true, force: true }); } finally { busy = false; active = undefined; } }
+    },
+  };
+}

package/dist/mcp/patch.mjs

@@ -0,0 +1,114 @@
+function error(message, file, rule = "mutation-patch") {
+  return Object.assign(new Error(message), { diagnostic: { rule, message, ...(file ? { file } : {}) } });
+}
+
+function fileName(header, prefix) {
+  const name = header.slice(4).split("\t", 1)[0];
+  if (name === "/dev/null") return null;
+  if (!name.startsWith(prefix) || !name.slice(2)) throw error("Use --- a/path and +++ b/path headers, or /dev/null for creation/deletion.");
+  return name.slice(2);
+}
+
+/** Text hunks are exact; Git binary blocks are applied by Git in the candidate. */
+export function parseUnifiedPatch(patch, maxFiles = 32) {
+  const lines = patch.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  const files = [], paths = new Set();
+  let index = 0;
+  while (index < lines.length) {
+    const start = index;
+    let gitPath, binaryOperation = "update", binaryIndex;
+    if (lines[index]?.startsWith("diff --git ")) {
+      const header = /^diff --git a\/(.+) b\/(.+)$/.exec(lines[index++]);
+      if (!header || header[1] !== header[2]) throw error("Git file headers must identify one path; use owned deletion/creation for a move.");
+      gitPath = header[1];
+    }
+    while (/^(?:index [a-f0-9]+\.\.[a-f0-9]+(?: 100644)?$|(?:new|deleted) file mode 100644$)/.test(lines[index] ?? "")) {
+      const metadata = lines[index++];
+      if (metadata.startsWith("new file")) binaryOperation = "create";
+      if (metadata.startsWith("deleted file")) binaryOperation = "delete";
+      if (metadata.startsWith("index ")) binaryIndex = /^index ([a-f0-9]{40}|[a-f0-9]{64})\.\.([a-f0-9]{40}|[a-f0-9]{64})(?: 100644)?$/.exec(metadata);
+    }
+    if (lines[index] === "GIT binary patch") {
+      if (!gitPath || !binaryIndex) throw error("Binary patches need a Git file header and full blob hashes. Generate with git diff --binary.");
+      const file = gitPath;
+      if (paths.has(file) || files.length >= maxFiles) throw error("Provide 1–32 distinct file patches.", file, "mutation-batch");
+      paths.add(file);
+      while (index < lines.length && !lines[index].startsWith("diff --git ")) index++;
+      const block = lines.slice(start, index).join("\n") + "\n";
+      files.push({ path: file, operation: binaryOperation, binary: true, objectFormat: binaryIndex[1].length === 64 ? "sha256" : "sha1", patch: block });
+      continue;
+    }
+    if (!lines[index]?.startsWith("--- ") || !lines[index + 1]?.startsWith("+++ ")) throw error("Expected unified diff file headers or a Git binary block. Renames and mode changes are unsupported.");
+    const before = fileName(lines[index++], "a/"), after = fileName(lines[index++], "b/");
+    const file = after ?? before;
+    if (gitPath && gitPath !== file) throw error("Git metadata and file headers must identify the same path.", file);
+    if (!file || before && after && before !== after) throw error("Use separate delete and create entries to rename a file.", file);
+    if (paths.has(file) || files.length >= maxFiles) throw error("Provide 1–32 distinct file patches.", file, "mutation-batch");
+    paths.add(file);
+    const entry = { path: file, operation: before === null ? "create" : after === null ? "delete" : "update", hunks: [] };
+    while (lines[index]?.startsWith("@@")) {
+      const header = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?:.*)$/.exec(lines[index++]);
+      if (!header) throw error("Malformed unified diff hunk header.", file);
+      const [oldStart, oldCount, newStart, newCount] = [header[1], header[2] ?? "1", header[3], header[4] ?? "1"].map(Number);
+      if (![oldStart, oldCount, newStart, newCount].every(Number.isSafeInteger) || oldCount && oldStart === 0 || newCount && newStart === 0 || !oldCount && !newCount) throw error("Invalid unified diff hunk positions or counts.", file);
+      const hunk = { oldStart, oldCount, newStart, newCount, lines: [] };
+      let oldLines = 0, newLines = 0;
+      while (oldLines < oldCount || newLines < newCount) {
+        const line = lines[index++];
+        if (line === undefined || ![" ", "-", "+"].includes(line[0])) throw error("Hunk lines must start with a space, - or + and match the declared counts.", file);
+        const item = { kind: line[0], text: line.slice(1), noNewline: false, ending: "\n" };
+        if (item.kind !== "+") oldLines++;
+        if (item.kind !== "-") newLines++;
+        if (oldLines > oldCount || newLines > newCount) throw error("Hunk line counts do not match the header.", file);
+        if (lines[index] === "\") { item.noNewline = true; index++; }
+        if (item.noNewline) item.ending = "";
+        else if (item.text.endsWith("\r")) { item.text = item.text.slice(0, -1); item.ending = "\r\n"; }
+        hunk.lines.push(item);
+      }
+      entry.hunks.push(hunk);
+    }
+    if (entry.operation === "update" && !entry.hunks.length) throw error("An update must contain a text hunk.", file);
+    files.push(entry);
+  }
+  if (!files.length) throw error("Provide a non-empty unified text diff.");
+  return files;
+}
+
+function sourceLines(content) {
+  return [...content.matchAll(/([^\n]*)(\n|$)/g)].filter(match => match[0]).map(match => {
+    const crlf = match[2] && match[1].endsWith("\r");
+    return { text: crlf ? match[1].slice(0, -1) : match[1], ending: match[2] ? crlf ? "\r\n" : "\n" : "" };
+  });
+}
+
+export function applyFilePatch(entry, content) {
+  const conflict = message => { throw error(message, entry.path, "mutation-conflict"); };
+  if (entry.operation === "create" && content !== null) conflict("Cannot create an existing file. Read the current source and prepare an update patch.");
+  if (entry.operation !== "create" && content === null) conflict("Cannot update or delete a missing file.");
+  const source = sourceLines(content ?? ""), output = [];
+  let cursor = 0;
+  for (const hunk of entry.hunks) {
+    const position = hunk.oldCount ? hunk.oldStart - 1 : hunk.oldStart;
+    if (position < cursor || position > source.length) conflict("Hunks overlap, are out of order or point outside the current file.");
+    for (let index = cursor; index < position; index++) output.push(source[index]);
+    cursor = position;
+    const newPosition = hunk.newCount ? hunk.newStart - 1 : hunk.newStart;
+    if (newPosition !== output.length) conflict("New hunk positions do not match the reconstructed file.");
+    for (const line of hunk.lines) {
+      if (line.kind !== "+") {
+        const current = source[cursor++];
+        if (!current || current.text !== line.text || current.ending !== line.ending) conflict("Patch context/removal does not match the current source exactly. Read the affected range and regenerate the patch; no fuzzy matching is used.");
+        if (line.kind === " ") output.push(current);
+      } else output.push({ text: line.text, ending: line.ending });
+    }
+  }
+  for (let index = cursor; index < source.length; index++) output.push(source[index]);
+  if (output.some((line, index) => !line.ending && index < output.length - 1)) conflict("A no-newline marker is valid only at the end of the resulting file.");
+  const result = output.map(line => line.text + line.ending).join("");
+  if (entry.operation === "delete") {
+    if (result) conflict("A deletion patch must remove the entire file.");
+    return null;
+  }
+  return result;
+}

package/dist/mcp/preview-watch.mjs

@@ -0,0 +1,169 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { statSync, mkdirSync, writeFileSync, renameSync, rmSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { buildFailure, buildStatusFile, inspectBuildStatus } from "./build-status.mjs";
+
+function stamp(file) {
+  try { const stat = statSync(file); return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`; }
+  catch { return null; }
+}
+
+/** One project-owned compiler process, shared by all protocol instances. */
+export function createPreviewWatch(root, config, { log = process.stderr, buildTimeout = 30000 } = {}) {
+  config = { ...config, apps: [...config.apps] };
+  const command = config.previewWatch;
+  const session = randomUUID();
+  let state = command ? "idle" : "disabled";
+  let child;
+  let error;
+  let closed;
+  let childClosed = false;
+  let killTimer;
+  let stopping;
+  const baselines = new Map();
+  const ready = new Set();
+  const requests = new Set();
+  let active;
+  const requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
+  function request(file) {
+    if (!command || requests.has(file) && active === file) return;
+    requests.add(file);
+    active = file;
+    mkdirSync(path.dirname(requestFile), { recursive: true });
+    if (realpathSync(path.dirname(requestFile)) !== path.dirname(requestFile)) throw new Error("Preview requests cannot resolve through a symlink.");
+    const temporary = `${requestFile}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ session, active: path.relative(root, active).replaceAll("\\", "/"), files: [...requests].map((file) => path.relative(root, file).replaceAll("\\", "/")) }));
+    renameSync(temporary, requestFile);
+  }
+
+  function kill(signal) {
+    if (!child?.pid || childClosed) return;
+    try {
+      if (process.platform === "win32") {
+        // taskkill also terminates the compiler's own subprocesses.
+        const terminator = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        terminator.on("error", () => { child.kill(signal); });
+      } else process.kill(-child.pid, signal);
+    } catch (failure) { if (failure.code !== "ESRCH") throw failure; }
+  }
+  function start() {
+    if (state !== "idle") return;
+    for (const app of config.apps) {
+      const file = path.resolve(root, app.file);
+      baselines.set(file, stamp(file));
+    }
+    state = "running";
+    // No shell: configured arguments remain literal. Child stdin cannot consume
+    // the MCP channel, and both output streams go exclusively to diagnostics.
+    const executable = command.command === "node" ? process.execPath : command.command;
+    const env = { ...process.env, ADS_MCP_BUILD_SESSION: session, ADS_MCP_BUILD_STATUS: buildStatusFile(root), ADS_MCP_REQUEST_FILE: requestFile, PATH: [path.join(root, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) };
+    try {
+      child = spawn(executable, command.args, { cwd: root, env, shell: false, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    } catch (failure) {
+      state = "failed";
+      error = `Cannot start preview watcher: ${failure.message}`;
+      log.write(`ads mcp: ${error}\n`);
+      return;
+    }
+    child.stdout.pipe(log, { end: false });
+    child.stderr.pipe(log, { end: false });
+    closed = new Promise((resolve) => child.once("close", (code, signal) => {
+      // Closing the launcher's pipes does not prove every compiler exited.
+      // Finish cleanup now, before discarding the owned process-group ID.
+      kill("SIGKILL");
+      childClosed = true;
+      clearTimeout(killTimer);
+      if (state !== "stopping") {
+        state = "failed";
+        error ??= `Preview watcher exited (${signal ?? code}). Restart MCP after fixing the configured command.`;
+        log.write(`ads mcp: ${error}\n`);
+      } else state = "stopped";
+      resolve();
+    }));
+    child.once("exit", () => {
+      // A failed launcher must not leave its compiler subprocesses alive.
+      if (state !== "stopping") {
+        kill("SIGTERM");
+        killTimer = setTimeout(() => kill("SIGKILL"), 1500);
+      }
+    });
+    child.once("error", (failure) => { error = `Cannot start preview watcher: ${failure.message}`; });
+  }
+
+  async function ensure(file, signal) {
+    start();
+    request(file);
+    if (signal?.aborted) throw new Error("Preview request cancelled.");
+    const app = config.apps.find((entry) => path.resolve(root, entry.file) === file);
+    const baseline = baselines.get(file) ?? null;
+    const deadline = Date.now() + buildTimeout;
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw new Error("Preview request cancelled.");
+      const build = buildStatus().previews.find((entry) => entry.id === app?.id);
+      if (build?.state === "error") throw buildFailure(build);
+      if (command && state !== "running") throw new Error(error ?? "Preview watcher is stopped.");
+      if (build?.current) return build;
+      if (build?.state === "unreported" && (!command || ready.has(file))) return build;
+      const current = stamp(file);
+      if (build?.state === "unreported" && current !== null && current !== baseline) { ready.add(file); return build; }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error("Preview build is still pending. Check the MCP build logs and invoke the preview again.");
+  }
+
+  const status = () => ({ state, ...(child?.pid ? { pid: child.pid } : {}), ...(error ? { error } : {}) });
+  const buildStatus = () => inspectBuildStatus(root, config, command ? { session, processState: status() } : {});
+
+  async function stop() {
+    rmSync(requestFile, { force: true });
+    if (stopping) return stopping;
+    if (!child || childClosed) { if (command) state = "stopped"; return; }
+    if (state === "stopped") return;
+    state = "stopping";
+    stopping = (async () => {
+      kill("SIGTERM");
+      clearTimeout(killTimer);
+      const timer = setTimeout(() => kill("SIGKILL"), 1500);
+      try { await closed; } finally { clearTimeout(timer); }
+    })();
+    return stopping;
+  }
+  return { start, ensure, stop, kill: () => kill("SIGKILL"), status, buildStatus, setApps(apps) {
+    for (const app of apps) {
+      const file = path.resolve(root, app.file);
+      if (!baselines.has(file)) baselines.set(file, stamp(file));
+    }
+    config.apps = apps;
+  } };
+}
+
+/** Keep one shared handle while validated project configuration replaces its compiler. */
+export function createReconfigurablePreviewWatch(root, config, options) {
+  let current = createPreviewWatch(root, config, options);
+  let signature = JSON.stringify(config);
+  let apps = config.apps;
+  let pending = Promise.resolve(), replacing = false, stopped = false;
+  return {
+    start() { if (!stopped && !replacing) current.start(); },
+    async ensure(file, signal) { await pending; if (stopped) throw new Error("Preview watcher is stopped."); return current.ensure(file, signal); },
+    status() { return replacing ? { state: "reconfiguring" } : current.status(); },
+    buildStatus() { return current.buildStatus(); },
+    setApps(next) { apps = next; current.setApps(next); },
+    kill() { current.kill(); },
+    reconfigure(next, force = false) {
+      const nextSignature = JSON.stringify(next);
+      if (!force && signature === nextSignature) return pending;
+      signature = nextSignature;
+      replacing = true;
+      pending = pending.then(async () => {
+        await current.stop();
+        if (stopped) return;
+        current = createPreviewWatch(root, { ...next, apps }, options);
+        current.start();
+      }).finally(() => { replacing = false; });
+      return pending;
+    },
+    async stop() { stopped = true; await pending; await current.stop(); },
+  };
+}