@shortlink-org/portolan 0.2.4 → 0.4.0

package/scripts/local-api.mjs

@@ -20,7 +20,11 @@ import { basename, dirname, join, posix, relative, resolve, sep } from "node:pat
 
 import { loadManifest, readManifest, readManifestText } from "./manifest.mjs";
 import { builtinPluginNames } from "./builtin-plugins.mjs";
+import { pluginsFresh } from "./plugins-fresh.mjs";
+import { djangoAggregateCandidates } from "../src/lib/django-aggregates.mjs";
 import { installDeliveryPreset, planDeliveryPreset, publicDeliveryPreset } from "./delivery-presets.mjs";
+import { formatLike } from "./json-format.mjs";
+import { UPLOAD_LIMIT, checkRecording, manifestWithTraceStep, recordingPath, stepWithMappings, summarizeTraceTrial, traceStepFor } from "./trace-trials.mjs";
 import {
   discoverProject,
   matches,
@@ -310,7 +314,16 @@ function pluginOptions(plugin, project, detectedOptions = {}) {
       out: "project.json",
     };
   }
-  if (["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin)) {
+  if (plugin === "php-ddd" || plugin === "csharp-ddd") {
+    // The tree names its own contexts and services; the manifest only says
+    // where the code lives and how core it is.
+    return {
+      ...(project.repository ? { repo: repositoryParts(project.repository).web } : {}),
+      ...(detectedOptions?.classification ? { classification: detectedOptions.classification } : {}),
+      out: "domain.json",
+    };
+  }
+  if (["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain"].includes(plugin)) {
     return { ...common, ...(project.repository ? { repo: repositoryParts(project.repository).web } : {}), ...detectedOptions, serviceName: project.name, out: "domain.json" };
   }
   if (plugin === "sql") return { ...common, store: "pg", ...detectedOptions, out: "stores.json" };
@@ -325,7 +338,7 @@ function pluginOptions(plugin, project, detectedOptions = {}) {
   if (plugin === "graphql") return { ...common, ...detectedOptions, out: "graphql.json" };
   if (plugin === "proto") return { ...common, ...detectedOptions, out: "proto.json" };
   if (plugin === "glossary") return { context: group, ...detectedOptions, out: "glossary.json" };
-  if (plugin === "adr") return { ...detectedOptions, out: "adr.json" };
+  if (plugin === "adr") return { scope: [group, component].filter(Boolean).join(".") || "org", ...detectedOptions, out: "adr.json" };
   return {};
 }
 
@@ -430,7 +443,7 @@ export function planProject(workspace, manifest, request) {
   };
   const out = posix.join(finalRoot, "portolan");
   const detectionByPlugin = new Map(discovery.detections.map((item) => [item.plugin, item]));
-  const hasDomainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin));
+  const hasDomainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain", "php-ddd", "csharp-ddd"].includes(plugin));
   const projectDetectionOptions = {
     groupKind: splitDeployables ? "system" : hasDomainModel ? "bounded-context" : "system",
     ...(hasDomainModel ? { componentKind: "service" } : {}),
@@ -455,7 +468,7 @@ export function planProject(workspace, manifest, request) {
     if (!splitDeployables) {
       const options = plugin === "project"
         ? projectDetectionOptions
-        : ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin)
+        : ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain", "php-ddd", "csharp-ddd"].includes(plugin)
           ? domainDetectionOptions(plugin)
           : detectionByPlugin.get(plugin)?.options;
       return [{ plugin, in: finalRoot, out, options: pluginOptions(plugin, project, options) }];
@@ -604,11 +617,19 @@ function projectRequestPlan(workspace, manifest, request) {
   return { base, plan, starter };
 }
 
+/**
+ * Writes the manifest in the style the file already has: an unchanged
+ * subtree is copied byte for byte, a changed array keeps the shape its old
+ * self had, so that what the page changed is what the diff shows.
+ */
 export function writeManifest(path, manifest) {
+  let before = "";
+  try { before = readFileSync(path, "utf8"); } catch {}
+  const text = before.trim() ? formatLike(before.replace(/\n$/, ""), manifest) : JSON.stringify(manifest, null, 2);
   const staging = mkdtempSync(join(dirname(path), ".portolan-manifest-"));
   const temp = join(staging, "portolan.json");
   try {
-    writeFileSync(temp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+    writeFileSync(temp, `${text}\n`, { flag: "wx" });
     const validation = loadManifest(temp);
     if (validation.problems.length) throw new Error(validation.problems.join("\n"));
     renameSync(temp, path);
@@ -617,6 +638,86 @@ export function writeManifest(path, manifest) {
   }
 }
 
+export function djangoAggregateProposals(workspace) {
+  const path = join(workspace, "portolan.json");
+  const text = readFileSync(path, "utf8");
+  const manifest = readManifestText(text, path);
+  const revision = createHash("sha256").update(text).digest("hex");
+  let report;
+  try { report = JSON.parse(readFileSync(join(workspace, ".portolan/build-report.json"), "utf8")); } catch {}
+  const proposals = [];
+  for (const step of report?.steps ?? []) {
+    if (step.phase !== "extract") continue;
+    const matches = (manifest.extract ?? []).map((entry, index) => ({ entry, index }))
+      .filter(({ entry }) => entry.plugin === step.plugin && entry.in === step.input && entry.out === step.output);
+    if (matches.length !== 1) continue;
+    const { entry, index } = matches[0];
+    for (const message of step.warnings ?? []) {
+      const candidates = djangoAggregateCandidates(message);
+      if (!candidates) continue;
+      const id = `${index}:${candidates.app}`;
+      if (proposals.some((proposal) => proposal.id === id)) continue;
+      proposals.push({ id, step: index, plugin: entry.plugin, input: entry.in, output: entry.out, message, ...candidates });
+    }
+  }
+  return { revision, stale: !report || report.manifestSha256 !== revision || report.status === "running", proposals };
+}
+
+export function saveDjangoAggregates(workspace, request) {
+  const current = djangoAggregateProposals(workspace);
+  if (current.stale || request.revision !== current.revision) {
+    throw new Error("The manifest or extraction report has changed. Regenerate and review the candidates again.");
+  }
+  if (!Array.isArray(request.selections) || !request.selections.length) throw new Error("Choose at least one aggregate root.");
+  const manifest = readManifest(join(workspace, "portolan.json"));
+  const seen = new Set();
+  for (const choice of request.selections) {
+    const proposal = current.proposals.find((candidate) => candidate.id === choice?.id);
+    if (!proposal || !proposal.models.some((model) => model.name === choice.model) || seen.has(choice.id)) {
+      throw new Error("Choose one of the reported models for each application.");
+    }
+    seen.add(choice.id);
+    const step = manifest.extract[proposal.step];
+    step.options = { ...step.options, aggregates: { ...step.options?.aggregates, [proposal.app]: choice.model } };
+  }
+  writeManifest(join(workspace, "portolan.json"), manifest);
+  return { saved: request.selections.length };
+}
+
+/**
+ * The manifest's `problemRules` as written, with a revision of the whole file:
+ * a save quotes it, so two pages editing the rules cannot overwrite each
+ * other, and neither can a hand edit made while the page was open.
+ */
+export function problemRulesState(workspace) {
+  const path = join(workspace, "portolan.json");
+  const text = readFileSync(path, "utf8");
+  const manifest = readManifestText(text, path);
+  return {
+    revision: createHash("sha256").update(text).digest("hex"),
+    rules: Array.isArray(manifest.problemRules) ? manifest.problemRules : [],
+  };
+}
+
+/**
+ * Replaces `problemRules`. The expressions are type-checked and the shape is
+ * checked against the schema by writeManifest, through the same loader gen
+ * uses, so a rule the page accepts is a rule gen accepts.
+ */
+export function saveProblemRules(workspace, request) {
+  const current = problemRulesState(workspace);
+  if (request?.revision !== current.revision) {
+    throw new Error("portolan.json has changed since the rules were read. Reload the page and try again.");
+  }
+  if (!Array.isArray(request.rules)) throw new Error("rules must be an array.");
+  const path = join(workspace, "portolan.json");
+  const manifest = readManifest(path);
+  if (request.rules.length) manifest.problemRules = request.rules;
+  else delete manifest.problemRules;
+  writeManifest(path, manifest);
+  return problemRulesState(workspace);
+}
+
 export function writeProject(workspace, request) {
   const manifestPath = join(workspace, "portolan.json");
   const before = readFileSync(manifestPath, "utf8");
@@ -715,6 +816,18 @@ async function body(req) {
   return text ? JSON.parse(text) : {};
 }
 
+/** The bytes of an upload, as they came, up to a limit that is said out loud. */
+async function rawBody(req, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) throw new Error(`The upload is larger than ${Math.round(limit / 1024 / 1024)} MB.`);
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
 function localRequest(req) {
   const address = req.socket.remoteAddress ?? "";
   const localAddress = address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
@@ -747,11 +860,21 @@ function feed(job, stream, chunk) {
   }
 }
 
-function workspaceFingerprint(workspace) {
+// The tree with nothing in it, which every repository has. Before the first
+// commit there is no HEAD to diff against, and the index diffed against this
+// tree is exactly what has been staged.
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+export function workspaceFingerprint(workspace) {
   const hash = createHash("sha256");
   try {
-    const options = { cwd: workspace, encoding: "buffer", maxBuffer: 128 * 1024 * 1024 };
-    hash.update(execFileSync("git", ["diff", "--binary", "HEAD", "--", "."], options));
+    // Git speaks to nobody here: a workspace that is not a checkout, or one
+    // without a commit yet, is a case this function handles, not an error to
+    // print from the dev server.
+    const options = { cwd: workspace, encoding: "buffer", maxBuffer: 128 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] };
+    let base = EMPTY_TREE;
+    try { base = execFileSync("git", ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], options).toString().trim() || EMPTY_TREE; } catch {}
+    hash.update(execFileSync("git", ["diff", "--binary", base, "--", "."], options));
     const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], options)
       .toString().split("\0").filter(Boolean).sort();
     for (const name of untracked) {
@@ -865,6 +988,7 @@ export function summarizeProjectTrial(snapshot, plan, events) {
       fileCount: event.fileCount,
       changedCount: event.changedCount,
       warnings: event.warnings ?? [],
+      diagnostics: event.diagnostics ?? [],
       ...(event.message ? { message: event.message } : {}),
     }));
   const facts = new Map(TRIAL_FACTS.map(([key]) => [key, new Set()]));
@@ -912,10 +1036,12 @@ export function summarizeProjectTrial(snapshot, plan, events) {
     for (const term of fragment.terms ?? []) add("terms", term.id ?? term.slug ?? term.name);
   }
   const warnings = steps.flatMap((step) => step.warnings.map((message) => ({ plugin: step.plugin, message })));
+  const diagnostics = steps.flatMap((step) => step.diagnostics);
   return {
     steps,
     facts: TRIAL_FACTS.map(([key, label]) => ({ key, label, count: facts.get(key)?.size ?? 0 })).filter((fact) => fact.count > 0),
     warnings,
+    diagnostics,
     generatedFiles: files.length,
   };
 }
@@ -933,6 +1059,65 @@ function prepareProjectTrial(workspace, request) {
   return { ...snapshot, fingerprint, plan };
 }
 
+/**
+ * A recording uploaded from the page, staged where the verifier will read it
+ * - the project's recordings directory, in a snapshot of the workspace - with
+ * the verify step that reads it, added to the snapshot's manifest when the
+ * project has none. The workspace itself is not touched until the trial is
+ * applied.
+ */
+function prepareTraceTrial(workspace, { projectId, name, content }) {
+  const manifest = readManifest(join(workspace, "portolan.json"));
+  const project = (manifest.projects ?? []).find((candidate) => candidate.id === projectId);
+  if (!project) throw new Error(`Project "${projectId}" does not exist. Add the project before recording it.`);
+  const known = builtinPluginNames().has("otel") || (manifest.plugins ?? []).some((plugin) => plugin.name === "otel");
+  if (!known) throw new Error("The otel verifier is not available in this installation.");
+  const { batches, spans } = checkRecording(content);
+  const recording = recordingPath(name, { taken: (candidate) => lstatExists(join(workspace, project.root, candidate)) });
+  const fingerprint = workspaceFingerprint(workspace);
+  const snapshot = snapshotWorkspace(workspace);
+  if (workspaceFingerprint(workspace) !== fingerprint) {
+    rmSync(snapshot.holder, { recursive: true, force: true });
+    throw new Error("Files changed while the trial workspace was being created. Try again.");
+  }
+  const target = join(snapshot.snapshot, project.root, recording);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  const next = manifestWithTraceStep(manifest, project);
+  if (next.changed) writeManifest(join(snapshot.snapshot, "portolan.json"), next.manifest);
+  const trace = { projectId, root: project.root, recording, step: next.step, stepAdded: next.changed, stepChange: next.change, batches, spans, content };
+  return { ...snapshot, fingerprint, trace };
+}
+
+/**
+ * The recording written beside the project, and the manifest with the step
+ * that reads it and the names the page mapped. Undoable the way a project
+ * is: the manifest before is remembered for a while.
+ */
+function applyTraceTrial(workspace, trial, { services, events, routes } = {}) {
+  const manifestPath = join(workspace, "portolan.json");
+  const before = readFileSync(manifestPath, "utf8");
+  const manifest = readManifestText(before, manifestPath);
+  const project = (manifest.projects ?? []).find((candidate) => candidate.id === trial.trace.projectId);
+  if (!project) throw new Error(`Project "${trial.trace.projectId}" no longer exists.`);
+  const target = join(workspace, project.root, trial.trace.recording);
+  if (lstatExists(target)) throw new Error(`${posix.join(project.root, trial.trace.recording)} appeared while the trial ran. Run it again.`);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, trial.trace.content, { flag: "wx" });
+  const next = manifestWithTraceStep(manifest, project);
+  const found = traceStepFor(next.manifest, project);
+  const mapped = stepWithMappings(found.step, { services, events, routes });
+  const changed = next.changed || JSON.stringify(mapped) !== JSON.stringify(found.step);
+  let undoToken = null;
+  if (changed) {
+    const verify = [...next.manifest.verify];
+    verify[found.index] = mapped;
+    writeManifest(manifestPath, { ...next.manifest, verify });
+    undoToken = rememberManifestUndo(workspace, before, readFileSync(manifestPath, "utf8"));
+  }
+  return { recording: posix.join(project.root, trial.trace.recording), project: project.id, stepAdded: next.changed, manifestChanged: changed, undoToken };
+}
+
 function freeLocalPort() {
   return new Promise((resolvePort, reject) => {
     const server = createNetServer();
@@ -993,9 +1178,31 @@ async function startProjectPreview(job) {
   return job.previewUrl;
 }
 
+/**
+ * Rebuilds src/likec4/generated.jsx from likec4/ in the workspace, the way
+ * `npm run likec4:gen` does before `dev`. Said in the run's log either way;
+ * a bundle that fails to build leaves the last one in place.
+ */
+function refreshLikeC4Bundle(job) {
+  return new Promise((done) => {
+    const bin = join(job.runRoot, "node_modules/likec4/bin/likec4.mjs");
+    if (!lstatExists(bin)) return done();
+    emit(job, { type: "log", stream: "stdout", message: "likec4 → src/likec4/generated.jsx" });
+    const child = spawn(process.execPath, [bin, "gen", "react", "likec4", "-o", "src/likec4/generated.jsx", "--no-use-dot"], { cwd: job.runRoot, stdio: ["ignore", "pipe", "pipe"] });
+    let output = "";
+    child.stdout.on("data", (chunk) => { output += chunk; });
+    child.stderr.on("data", (chunk) => { output += chunk; });
+    child.on("error", (error) => { emit(job, { type: "log", stream: "stderr", message: `likec4: ${error.message}` }); done(); });
+    child.on("close", (code) => {
+      if (code !== 0) emit(job, { type: "log", stream: "stderr", message: `likec4 gen react exited with ${code}:\n${output.trim()}` });
+      done();
+    });
+  });
+}
+
 function startJob(workspace, mode, approvedPreview, preparedTrial) {
   const id = randomUUID();
-  const preview = mode === "preview" || mode === "project-preview";
+  const preview = mode === "preview" || mode === "project-preview" || mode === "trace-preview";
   const fingerprint = preparedTrial?.fingerprint ?? (preview ? workspaceFingerprint(workspace) : approvedPreview?.fingerprint);
   const snapshot = preparedTrial ?? (preview ? snapshotWorkspace(workspace) : null);
   if (preview && !preparedTrial && workspaceFingerprint(workspace) !== fingerprint) {
@@ -1004,13 +1211,21 @@ function startJob(workspace, mode, approvedPreview, preparedTrial) {
   }
   const generatedAt = preview ? new Date().toISOString() : approvedPreview?.generatedAt;
   const gitAuth = gitAuthEnvironment();
-  const job = { id, mode, status: "running", events: [], subscribers: new Set(), buffers: { stdout: "", stderr: "" }, child: null, gitAuth, runRoot: snapshot?.snapshot ?? workspace, snapshotHolder: snapshot?.holder ?? null, fingerprint, generatedAt, projectPlan: preparedTrial?.plan ?? null, projectRequest: preparedTrial ? structuredClone(preparedTrial.request) : null };
+  const job = { id, mode, status: "running", events: [], subscribers: new Set(), buffers: { stdout: "", stderr: "" }, child: null, gitAuth, runRoot: snapshot?.snapshot ?? workspace, snapshotHolder: snapshot?.holder ?? null, fingerprint, generatedAt, projectPlan: preparedTrial?.plan ?? null, projectRequest: preparedTrial?.request ? structuredClone(preparedTrial.request) : null, trace: preparedTrial?.trace ?? null };
   jobs.set(id, job);
   const cli = process.env.PORTOLAN_CLI;
-  const command = cli ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
+  // `npm run gen` builds the plugins first, which a checkout whose plugin
+  // sources have not moved since the last build does not need: the fourth
+  // trial of a recording in a row learns nothing from a minute of javac.
+  // When every artefact is at least as new as its sources the generator
+  // runs on its own; anything doubtful takes the road that builds.
+  const fresh = !cli && pluginsFresh(job.runRoot);
+  const command = cli || fresh ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
   const args = cli
     ? [cli, mode === "check" ? "check" : "generate", "--cwd", job.runRoot]
-    : ["run", mode === "check" ? "gen:check" : "gen"];
+    : fresh
+      ? [join(job.runRoot, "scripts/gen.mjs"), ...(mode === "check" ? ["--check"] : [])]
+      : ["run", mode === "check" ? "gen:check" : "gen"];
   let child;
   try {
     child = spawn(command, args, {
@@ -1047,6 +1262,18 @@ function startJob(workspace, mode, approvedPreview, preparedTrial) {
       }
       catch (cause) { job.status = "failed"; emit(job, { type: "log", stream: "stderr", message: `Could not summarise project trial: ${cause instanceof Error ? cause.message : String(cause)}` }); }
     }
+    if (mode === "trace-preview" && job.status === "ok") {
+      try {
+        job.traceTrial = summarizeTraceTrial(job.runRoot, job.trace, job.events);
+        emit(job, { type: "trace-trial-ready", ...job.traceTrial });
+      }
+      catch (cause) { job.status = "failed"; emit(job, { type: "log", stream: "stderr", message: `Could not summarise the recording: ${cause instanceof Error ? cause.message : String(cause)}` }); }
+    }
+    // The catalog is written, and the pictures' sources with it; the bundle
+    // the dev server draws them from is built once before it starts, so a
+    // write from the page rebuilds it here, or the new flow has no picture
+    // until the next start.
+    if (mode === "write" && job.status === "ok" && !process.env.PORTOLAN_CLI) await refreshLikeC4Bundle(job);
     emit(job, { type: "process-finished", status: job.status, code, signal });
     for (const response of job.subscribers) response.end();
     job.subscribers.clear();
@@ -1077,6 +1304,12 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             const active = [...jobs.values()].find((job) => job.status === "running");
             return send(res, 200, { local: true, workspace: realpathSync(workspace), setup: setup(workspace, publicSetupFrom), activeRun: active ? { id: active.id, mode: active.mode } : null });
           }
+          if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/django-aggregates`) {
+            return send(res, 200, djangoAggregateProposals(workspace));
+          }
+          if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/rules`) {
+            return send(res, 200, problemRulesState(workspace));
+          }
           if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/delivery-presets`) {
             const features = url.searchParams.has("features")
               ? url.searchParams.get("features").split(",").filter(Boolean)
@@ -1096,10 +1329,31 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             req.on("close", () => job.subscribers.delete(res));
             return;
           }
+          if (req.method === "POST" && url.pathname === `${LOCAL_API_PREFIX}/traces/trials` && req.headers["x-portolan-local"] === "1") {
+            // The one upload the local API takes: a recording, as bytes,
+            // named by headers rather than wrapped in JSON.
+            if ([...jobs.values()].some((job) => job.status === "running")) return send(res, 409, { error: "A generator run is already active." });
+            const content = await rawBody(req, UPLOAD_LIMIT);
+            const projectId = String(req.headers["x-portolan-project"] ?? "");
+            const name = decodeURIComponent(String(req.headers["x-portolan-filename"] ?? "recording.jsonl"));
+            const prepared = prepareTraceTrial(workspace, { projectId, name, content });
+            let job;
+            try { job = startJob(workspace, "trace-preview", null, prepared); }
+            catch (cause) { rmSync(prepared.holder, { recursive: true, force: true }); throw cause; }
+            return send(res, 202, { runId: job.id, mode: job.mode, recording: posix.join(prepared.trace.root, prepared.trace.recording), project: projectId, stepAdded: prepared.trace.stepAdded, stepChange: prepared.trace.stepChange, spans: prepared.trace.spans });
+          }
           if (req.method !== "POST" || req.headers["content-type"]?.split(";")[0] !== "application/json" || req.headers["x-portolan-local"] !== "1") {
             return send(res, 405, { error: "Use a local JSON request." });
           }
           const input = await body(req);
+          if (url.pathname === `${LOCAL_API_PREFIX}/django-aggregates`) {
+            if ([...jobs.values()].some((job) => job.status === "running")) throw new Error("Wait for the current generation to finish before saving aggregate roots.");
+            return send(res, 200, saveDjangoAggregates(workspace, input));
+          }
+          if (url.pathname === `${LOCAL_API_PREFIX}/rules`) {
+            if ([...jobs.values()].some((job) => job.status === "running")) throw new Error("Wait for the current generation to finish before saving rules.");
+            return send(res, 200, saveProblemRules(workspace, input));
+          }
           if (url.pathname === `${LOCAL_API_PREFIX}/delivery-presets/install`) {
             return send(res, 201, installDeliveryPreset(workspace, input));
           }
@@ -1134,6 +1388,27 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             disposeProjectTrial(trial);
             return send(res, 200, { runId: trial.id, status: "disposed" });
           }
+          const applyTraceMatch = url.pathname.match(/^\/__portolan\/traces\/trials\/([^/]+)\/apply$/);
+          if (applyTraceMatch) {
+            if ([...jobs.values()].some((job) => job.status === "running")) return send(res, 409, { error: "A generator run is already active." });
+            const trial = jobs.get(applyTraceMatch[1]);
+            if (!trial?.trace || trial.status !== "ok" || !trial.traceTrial) return send(res, 409, { error: "Run a successful recording trial before keeping it." });
+            if (trial.applied) return send(res, 409, { error: "This recording was already kept." });
+            if (workspaceFingerprint(workspace) !== trial.fingerprint) return send(res, 409, { error: "Files changed after this trial. Upload the recording again." });
+            const result = applyTraceTrial(workspace, trial, { services: input.services, events: input.events, routes: input.routes });
+            trial.applied = true;
+            const generation = input.generate ? startJob(workspace, "write", trial) : null;
+            return send(res, 201, { ...result, setup: setup(workspace, publicSetupFrom), run: generation ? { runId: generation.id, mode: generation.mode } : null });
+          }
+          const disposeTraceMatch = url.pathname.match(/^\/__portolan\/traces\/trials\/([^/]+)\/dispose$/);
+          if (disposeTraceMatch) {
+            const trial = jobs.get(disposeTraceMatch[1]);
+            if (!trial?.trace) return send(res, 404, { error: "Recording trial not found." });
+            if (trial.status === "running") return send(res, 409, { error: "Cancel the running trial first." });
+            trial.trace.content = null;
+            disposeProjectTrial(trial);
+            return send(res, 200, { runId: trial.id, status: "disposed" });
+          }
           if (url.pathname === `${LOCAL_API_PREFIX}/projects/preview`) {
             const manifest = readManifest(join(workspace, "portolan.json"));
             return send(res, 200, projectRequestPlan(workspace, manifest, input).plan);

package/scripts/local-api.test.mjs

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { rmSync } from "node:fs";
 
-import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, externalProjectDefaults, forgetRepositoryCredential, inspectionRoot, localApiPath, manifestWithoutProject, manifestWithProject, planProject, readLocalSource, removeProject, resolveRepositoryCommit, starterManifestProject, storeRepositoryCredential, summarizeProjectTrial, undoProjectRemoval, writeProject } from "./local-api.mjs";
+import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, externalProjectDefaults, forgetRepositoryCredential, inspectionRoot, localApiPath, manifestWithoutProject, manifestWithProject, planProject, problemRulesState, readLocalSource, removeProject, saveProblemRules, resolveRepositoryCommit, starterManifestProject, storeRepositoryCredential, summarizeProjectTrial, undoProjectRemoval, workspaceFingerprint, writeManifest, writeProject } from "./local-api.mjs";
 import { installDeliveryPreset, planDeliveryPreset, providerFromRemote, publicDeliveryPreset } from "./delivery-presets.mjs";
 
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -48,7 +48,10 @@ describe("local API base path", () => {
   });
 });
 
-describe("local project setup", () => {
+// Each delivery-preset test spawns a dozen git processes; while the whole
+// suite is starting, one spawn takes hundreds of milliseconds, so the
+// default five seconds is a coin flip rather than a limit.
+describe("local project setup", { timeout: 30_000 }, () => {
   it("detects GitHub and GitLab remotes without treating arbitrary hosts as a forge", () => {
     expect(providerFromRemote("git@github.com:acme/shop.git")).toBe("github");
     expect(providerFromRemote("https://gitlab.example.com/acme/shop.git")).toBe("gitlab");
@@ -140,13 +143,18 @@ describe("local project setup", () => {
     writeFileSync(join(root, ".gitlab-ci.yml"), "lint:\n  script: echo lint\n");
     const preview = planDeliveryPreset(root);
     expect(preview).toMatchObject({ provider: "gitlab", detectedProvider: "gitlab", status: "available" });
-    expect(preview.files[0].diff).toContain("+\"portolan:check\":");
+    expect(preview.features.filter((feature) => feature.selected).map((feature) => feature.id)).toEqual(["pages"]);
+    expect(preview.files[0].diff).not.toContain("+\"portolan:check\":");
     const installed = installDeliveryPreset(root, { provider: "gitlab", revision: preview.revision });
     expect(installed.status).toBe("installed");
     const pipeline = readFileSync(join(root, ".gitlab-ci.yml"), "utf8");
     expect(pipeline).toContain("lint:\n  script: echo lint");
     expect(pipeline).toContain("# >>> Portolan delivery preset >>>");
-    expect(pipeline).toContain("pages:\n    publish: dist");
+    expect(pipeline).toContain("\npages:\n");
+    expect(pipeline).toContain("stage: deploy");
+    expect(pipeline).toContain("tags:\n    - runner-type:docker");
+    expect(pipeline).toContain("portolan build --output public");
+    expect(pipeline).toContain("artifacts:\n    paths:\n      - public");
     expect(existsSync(join(root, ".github"))).toBe(false);
   });
 
@@ -239,6 +247,33 @@ describe("local project setup", () => {
     expect(discovery.detections.find((item) => item.plugin === "adr")?.selected).toBe(false);
   });
 
+  it("recognizes common ADR markdown variants and previews extracted fields", () => {
+    const root = workspace();
+    const adrRoot = join(root, "services/billing/docs/adr");
+    rmSync(join(adrRoot, "0001.md"));
+    writeFileSync(join(adrRoot, "0001-store-invoices.md"), "# 1. Store invoices\n\nDate: 2025-01-02\n\n## Status\n\nAccepted\n\n## Decision\n\nUse Postgres.\n");
+    writeFileSync(join(adrRoot, "02-package-layout.md"), "# ADR-2. Архитектура пакетов\n\n#### Статус: на рассмотрении\n\n### Решение\n\nУпростить структуру.\n");
+
+    const discovery = discoverProject(root, "services/billing");
+    const adr = discovery.detections.find((item) => item.plugin === "adr");
+    expect(adr).toMatchObject({
+      selected: true,
+      confidence: "high",
+      evidence: "docs/adr/*.md",
+      options: { files: ["docs/adr/*.md"] },
+    });
+    expect(adr?.preview).toEqual([
+      { file: "docs/adr/0001-store-invoices.md", fields: { number: "1", title: "Store invoices", status: "accepted", date: "2025-01-02" } },
+      { file: "docs/adr/02-package-layout.md", fields: { number: "2", title: "Архитектура пакетов", status: "proposed", date: "from git history" } },
+    ]);
+
+    const manifest = JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"));
+    const plan = planProject(root, manifest, {
+      root: "services/billing", id: "billing", name: "Billing", group: "finance", component: "billing", plugins: ["adr"],
+    });
+    expect(plan.steps[0].options).toEqual({ files: ["docs/adr/*.md"], scope: "finance.billing", out: "adr.json" });
+  });
+
   it("names external projects from the repository or selected component instead of the inspection cache", () => {
     expect(externalProjectDefaults("https://github.com/batazor/microservice-template-ddd")).toEqual({
       id: "microservice-template-ddd",
@@ -691,7 +726,7 @@ describe("local project setup", () => {
       plugins: ["openapi", "redis"],
       steps: [{ plugin: "openapi", out: output }, { plugin: "redis", out: output }],
     }, [
-      { type: "step-finished", phase: "extract", plugin: "openapi", output, status: "written", durationMs: 4, fileCount: 1, changedCount: 1, files: [`${output}/api.json`], warnings: ["one route has no description"] },
+      { type: "step-finished", phase: "extract", plugin: "openapi", output, status: "written", durationMs: 4, fileCount: 1, changedCount: 1, files: [`${output}/api.json`], warnings: ["one route has no description"], diagnostics: [{ plugin: "openapi", rule: "plugin.openapi.other-test", severity: "warning", action: "Inspect it.", message: "one route has no description", count: 1, project: "billing", phase: "extract", suppressed: true, suppressionReason: "Owned upstream." }] },
       { type: "step-finished", phase: "extract", plugin: "redis", output, status: "written", durationMs: 3, fileCount: 1, changedCount: 1, files: [`${output}/redis.json`], warnings: [] },
       { type: "step-finished", phase: "generate", plugin: "markdown", output: "docs", status: "written", durationMs: 2, fileCount: 10, changedCount: 10, files: ["docs/index.md"], warnings: [] },
     ]);
@@ -709,6 +744,116 @@ describe("local project setup", () => {
     });
     expect(result.steps.map((step) => step.plugin)).toEqual(["openapi", "redis"]);
     expect(result.warnings).toEqual([{ plugin: "openapi", message: "one route has no description" }]);
+    expect(result.diagnostics).toEqual([expect.objectContaining({ rule: "plugin.openapi.other-test", suppressed: true })]);
     expect(result.generatedFiles).toBe(2);
   });
 });
+
+describe("workspaceFingerprint", () => {
+  it("reads a repository before its first commit without complaint, and moves when a file does", () => {
+    const root = workspace();
+    execFileSync("git", ["init", "-q", "-b", "main"], { cwd: root });
+    execFileSync("git", ["add", "services/billing/go.mod"], { cwd: root });
+
+    const before = workspaceFingerprint(root);
+    expect(workspaceFingerprint(root)).toBe(before);
+
+    writeFileSync(join(root, "services/billing/go.mod"), "module example.com/billing\n\ngo 1.22\n");
+    const staged = workspaceFingerprint(root);
+    expect(staged).not.toBe(before);
+
+    writeFileSync(join(root, "services/billing/api/handlers.go"), "package api\n");
+    expect(workspaceFingerprint(root)).not.toBe(staged);
+  });
+
+  it("is the same whether or not the repository has a commit, for the same tree", () => {
+    const root = workspace();
+    execFileSync("git", ["init", "-q", "-b", "main"], { cwd: root });
+    const unborn = workspaceFingerprint(root);
+    execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "--allow-empty", "-m", "empty"], { cwd: root });
+    expect(workspaceFingerprint(root)).toBe(unborn);
+  });
+});
+
+describe("writing the manifest", () => {
+  it("keeps the file's own formatting and changes only what changed", () => {
+    const root = workspace();
+    const path = join(root, "portolan.json");
+    const before = [
+      "{",
+      '  "sources": ["data/*.json", "services/*/portolan/*.json"],',
+      '  "projects": [],',
+      '  "plugins": [{ "name": "otel", "process": { "command": "true" } }],',
+      '  "extract": [],',
+      '  "verify": [',
+      "    {",
+      '      "plugin": "otel",',
+      '      "in": "services/billing",',
+      '      "out": "services/billing/portolan",',
+      '      "options": {',
+      '        "traces": [',
+      '          "telemetry/traces.jsonl"',
+      "        ]",
+      "      }",
+      "    }",
+      "  ]",
+      "}",
+      "",
+    ].join("\n");
+    writeFileSync(path, before);
+
+    const manifest = JSON.parse(before);
+    manifest.verify[0].options.traces.push("telemetry/recordings/*.jsonl");
+    writeManifest(path, manifest);
+
+    const after = readFileSync(path, "utf8");
+    expect(JSON.parse(after)).toEqual(manifest);
+    expect(after).toContain('  "sources": ["data/*.json", "services/*/portolan/*.json"],');
+    expect(after).toContain('  "plugins": [{ "name": "otel", "process": { "command": "true" } }],');
+    expect(after).toContain('          "telemetry/traces.jsonl",\n          "telemetry/recordings/*.jsonl"\n        ]');
+    expect(after.endsWith("}\n")).toBe(true);
+  });
+
+  it("still refuses a manifest the schema rejects, and leaves the file as it was", () => {
+    const root = workspace();
+    const path = join(root, "portolan.json");
+    const before = readFileSync(path, "utf8");
+    expect(() => writeManifest(path, { ...JSON.parse(before), verify: [{ plugin: "nope", in: "x", out: "y" }] })).toThrow();
+    expect(readFileSync(path, "utf8")).toBe(before);
+  });
+});
+
+describe("problem rules", () => {
+  it("reads the manifest's rules with a revision, and writes them back through the schema", () => {
+    const root = workspace();
+    const before = problemRulesState(root);
+    expect(before.rules).toEqual([]);
+    expect(before.revision).toMatch(/^[0-9a-f]{64}$/);
+
+    const rules = [
+      { id: "shared-store", enabled: false, reason: "one database by design" },
+      { id: "team.quiet-event", over: "event", severity: "warning", title: "Quiet event", when: "size(event.consumers) == 0", message: "'nothing consumes ' + event.id" },
+    ];
+    const after = saveProblemRules(root, { revision: before.revision, rules });
+    expect(after.rules).toEqual(rules);
+    expect(after.revision).not.toBe(before.revision);
+    expect(JSON.parse(readFileSync(join(root, "portolan.json"), "utf8")).problemRules).toEqual(rules);
+
+    // Emptying the list removes the key, so a manifest that never had one
+    // does not gain an empty array.
+    const emptied = saveProblemRules(root, { revision: after.revision, rules: [] });
+    expect(emptied.rules).toEqual([]);
+    expect(JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"))).not.toHaveProperty("problemRules");
+  });
+
+  it("refuses a stale revision and a rule the type check rejects, and leaves the file alone", () => {
+    const root = workspace();
+    const { revision } = problemRulesState(root);
+    const text = readFileSync(join(root, "portolan.json"), "utf8");
+    expect(() => saveProblemRules(root, { revision: "0".repeat(64), rules: [] })).toThrow(/changed since/);
+    expect(() => saveProblemRules(root, { revision, rules: [{ id: "team.a", over: "event", title: "A", when: "event.nme == 'x'", message: "'m'" }] })).toThrow(/nme/);
+    expect(() => saveProblemRules(root, { revision, rules: [{ id: "rpc", when: "true" }] })).toThrow(/built-in/);
+    expect(() => saveProblemRules(root, { revision, rules: [{ id: "team.b", over: "event", title: "B", when: "true", message: "'m'", extra: 1 }] })).toThrow();
+    expect(readFileSync(join(root, "portolan.json"), "utf8")).toBe(text);
+  });
+});