tapeo-cli 0.0.0-stage → 0.4.0

package/shared/api.mjs

@@ -0,0 +1,238 @@
+/** Transport shared by the CLI and VS Code extension. No browser session cookies. */
+import { partialJsonStringField, readAnswerStream } from "./stream.mjs";
+export class TapeoApiError extends Error {
+  constructor(message, status, data = {}) { super(message); this.name = "TapeoApiError"; this.status = status; this.data = data; }
+}
+
+/** Workflow stages a run can start from or stop at (lib/workflow-stages.ts). */
+export const WORKFLOW_STAGE_KEYS = ["simulation", "synthesis", "timing", "physical", "post-route-timing", "drc", "extraction", "erc", "lvs"];
+export const ACTIVE_RUN_STATUSES = ["queued", "running"];
+
+/** Keep CLI and VS Code status wording consistent with the persisted run. */
+export function describeRun(run, now = Date.now()) {
+  const stage = run.currentStage ? ` · ${run.currentStage}` : "";
+  const summary = run.summary ? `\n  ${run.summary}` : "";
+  if (run.status === "failed") return `${run.id} · FAILED${stage}${summary}\n  Open its details (tapeo show ${run.id}, or Tapeo: Show Run Details) for stage results and tool logs. Saved local files are unchanged.`;
+  if (run.status === "cancelled") return `${run.id} · CANCELLED${summary}`;
+  if (run.status === "queued" && Number.isFinite(Date.parse(run.startedAt)) && now - Date.parse(run.startedAt) > 120_000) {
+    return `${run.id} · WAITING FOR WORKER${summary}\n  Still queued after two minutes. Check that the server worker is running; retry status later.`;
+  }
+  return `${run.id} · ${String(run.status).toUpperCase()}${stage}${summary}`;
+}
+
+const STAGE_MARK = { completed: "✓", issues: "!", failed: "✗", skipped: "–" };
+const GOAL_MARK = { passed: "✓", failed: "✗", "tool-error": "✗", blocked: "–", inconclusive: "?" };
+
+/** A run's per-stage results, AI changes, and the tool runs whose logs can be read. */
+export function describeRunDetail(detail) {
+  const { run, toolRuns = [] } = detail;
+  const lines = [describeRun(run)];
+  const details = run.details;
+  if (details?.stages?.length) {
+    lines.push("", "Stages:");
+    for (const stage of details.stages) lines.push(`  ${STAGE_MARK[stage.status] ?? "·"} ${stage.label}: ${String(stage.summary).split("\n")[0].slice(0, 220)}`);
+  }
+  if (details?.changes?.length) {
+    lines.push("", "Files the AI Engineer changed:");
+    for (const change of details.changes) lines.push(`  ${change.kind} ${change.path} (${change.stage})`);
+  }
+  if (details?.proposals?.length) lines.push("", `${details.proposals.length} suggested change(s) to protected files are waiting for review in the web workspace.`);
+  if (details?.notes?.length) { lines.push("", "Notes:"); for (const note of details.notes) lines.push(`  ${note}`); }
+  if (toolRuns.length) {
+    lines.push("", "Tool runs (read a log with `tapeo logs <id>`):");
+    for (const tool of toolRuns) {
+      const measured = (tool.metrics ?? []).slice(0, 3).map((metric) => `${metric.key}=${metric.value}${metric.unit ? ` ${metric.unit}` : ""}`).join(", ");
+      lines.push(`  ${tool.id}  ${tool.tool} · ${tool.status}${measured ? ` · ${measured}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** The latest goal report, one line per goal. */
+export function describeGoals(report) {
+  if (!report) return "No goal report yet. Run the workflow to measure the project's goals.";
+  const passed = report.outcomes.filter((outcome) => outcome.status === "passed").length;
+  const lines = [`Goals: ${passed} of ${report.outcomes.length} met · ${report.status === "complete" ? "complete" : "needs review"} · ${new Date(report.createdAt).toLocaleString()}`];
+  for (const outcome of report.outcomes) {
+    const name = outcome.goal?.key ?? outcome.goal?.id ?? "goal";
+    // Behavior goals carry their description as the target; only numeric targets read as a bound.
+    const target = typeof outcome.goal?.target === "number" ? ` · target ${outcome.goal.comparison === "less-than-or-equal" ? "≤" : outcome.goal.comparison === "greater-than-or-equal" ? "≥" : outcome.goal.comparison === "between" ? "between" : "="} ${outcome.goal.target}${outcome.goal.unit ? ` ${outcome.goal.unit}` : ""}` : "";
+    const evidence = outcome.evidence ? ` · measured ${outcome.evidence.value}${outcome.evidence.unit ? ` ${outcome.evidence.unit}` : ""} (${outcome.evidence.tool})` : "";
+    lines.push(`  ${GOAL_MARK[outcome.status] ?? "·"} ${name}: ${outcome.status}${target}${evidence}${outcome.status === "passed" ? "" : ` · ${String(outcome.reason).slice(0, 200)}`}`);
+  }
+  return lines.join("\n");
+}
+
+/** The server a sign-in uses when none is named. */
+export const DEFAULT_SERVER_URL = "https://tapeo.net";
+
+/** Which client and version sends requests (X-Tapeo-Client), so the server can ask outdated clients to update. */
+let clientIdentity = "tapeo-client/0.0.0";
+export function setClientIdentity(name, version) { clientIdentity = `${name}/${version}`; }
+
+export function normalizeServerUrl(value) {
+  const url = new URL(value);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:")) throw new Error("Use HTTPS for a remote Tapeo server.");
+  if (url.username || url.password || url.search || url.hash) throw new Error("Use a server URL without credentials, query, or fragment.");
+  return url.origin;
+}
+
+async function send(serverUrl, method, path, { token, body, raw = false } = {}) {
+  let response;
+  try {
+    response = await fetch(new URL(`/api/client/v1${path}`, serverUrl), {
+      method,
+      headers: { "X-Tapeo-Client": clientIdentity, ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      redirect: "error",
+      signal: AbortSignal.timeout(raw ? 300_000 : 20_000)
+    });
+  } catch (error) {
+    const detail = error?.name === "TimeoutError" ? `The server did not answer within ${raw ? 300 : 20} seconds.` : "Could not reach the server.";
+    throw new TapeoApiError(`${detail} Check ${serverUrl} and retry; local files were not changed.`, 0);
+  }
+  if (raw && response.ok) return response;
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    if (response.status === 401 && token) throw new TapeoApiError("Your sign-in expired or was revoked. Run `tapeo login` (or Tapeo: Connect to Server) again. Local files were not changed.", 401, data);
+    throw new TapeoApiError(data.error ?? `Tapeo returned HTTP ${response.status}.`, response.status, data);
+  }
+  return response.status === 202 ? { ...data, pending: true } : data;
+}
+
+/**
+ * Browser-approved sign-in (the device flow). Starts a request, then waits
+ * until the person approves it in the browser, and returns the new token.
+ * `onCode` receives the code and the page to open.
+ */
+export async function signInWithBrowser(serverUrl, deviceName, { onCode, signal, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
+  const server = normalizeServerUrl(serverUrl);
+  const started = await send(server, "POST", "/device/start", { body: { name: deviceName } });
+  await onCode?.({ userCode: started.userCode, verificationUri: started.verificationUri, verificationUriComplete: started.verificationUriComplete, expiresIn: started.expiresIn });
+  let interval = Math.max(1, Number(started.interval) || 3) * 1000;
+  const deadline = Date.now() + Number(started.expiresIn ?? 600) * 1000;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error("Sign-in canceled.");
+    await sleep(interval);
+    try {
+      const result = await send(server, "POST", "/device/token", { body: { deviceCode: started.deviceCode } });
+      if (result.status === "approved" && result.token) return { serverUrl: server, token: result.token, name: result.name, expiresAt: result.expiresAt };
+      if (result.status === "slow_down") interval += 2000;
+    } catch (error) {
+      if (error?.status === 403) throw new Error("The sign-in was denied in the browser.");
+      if (error?.status === 410) throw new Error("The sign-in request expired. Start again.");
+      if (error?.status !== 0) throw error;
+      // A dropped connection while waiting: keep waiting until the request expires.
+    }
+  }
+  throw new Error("The sign-in request expired before it was approved. Start again.");
+}
+
+export class TapeoClient {
+  constructor(serverUrl, token) {
+    this.serverUrl = normalizeServerUrl(serverUrl);
+    if (!/^tapeo_[A-Za-z0-9_-]{43}$/.test(token)) throw new Error("Use a project token from your Tapeo account page.");
+    this.token = token;
+  }
+
+  request(method, path, body) { return send(this.serverUrl, method, path, { token: this.token, body }); }
+  /** One file as bytes (text or binary), with its SHA-256 and origin. */
+  async rawFile(id, path) {
+    const response = await send(this.serverUrl, "GET", `/projects/${encodeURIComponent(id)}/files/raw?path=${encodeURIComponent(path)}`, { token: this.token, raw: true });
+    return { bytes: Buffer.from(await response.arrayBuffer()), sha256: response.headers.get("x-tapeo-sha256"), origin: response.headers.get("x-tapeo-origin") };
+  }
+
+  /**
+   * A streamed AI answer. `onText` receives the answer's message as it is
+   * written. AI answers can take a minute or more, so the wait is longer.
+   */
+  async stream(path, body, onText, incompleteMessage) {
+    let response;
+    try {
+      response = await fetch(new URL(`/api/client/v1${path}`, this.serverUrl), {
+        method: "POST",
+        headers: { "X-Tapeo-Client": clientIdentity, Authorization: `Bearer ${this.token}`, "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        redirect: "error",
+        signal: AbortSignal.timeout(300_000)
+      });
+    } catch (error) {
+      throw new TapeoApiError(error?.name === "TimeoutError" ? "The AI answer did not finish within 5 minutes. Try again." : `Could not reach the server. Check ${this.serverUrl} and retry.`, 0);
+    }
+    if (!response.ok || !response.body) {
+      const data = await response.json().catch(() => ({}));
+      if (response.status === 401) throw new TapeoApiError("Your sign-in expired or was revoked. Run `tapeo login` (or Tapeo: Connect to Server) again.", 401, data);
+      throw new TapeoApiError(data.error ?? `Tapeo returned HTTP ${response.status}.`, response.status, data);
+    }
+    return readAnswerStream(response.body, (raw) => onText?.(partialJsonStringField(raw, "message")), incompleteMessage);
+  }
+
+  /** Ask the AI Engineer about the saved project; the answer may propose file changes. */
+  askEngineer(id, message, onText) { return this.stream(`/projects/${encodeURIComponent(id)}/engineer`, { message, stream: true }, onText, "The Engineer's answer was incomplete. Please try again."); }
+  /** The project's Engineer conversation, shared with the browser. */
+  engineerHistory(id) { return this.request("GET", `/projects/${encodeURIComponent(id)}/engineer`); }
+  /** One Architect turn for a new design. `messages` is the whole conversation so far. */
+  architect(messages, { designFiles, focusOption } = {}, onText) { return this.stream("/architect", { messages, ...(designFiles?.length ? { designFiles } : {}), ...(focusOption ? { focusOption } : {}) }, onText, "The Architect's answer was incomplete. Please try again."); }
+  /** The stages a build of this design will run. */
+  designPlan(requirements, uploadedPaths = []) { return this.request("POST", "/design/plan", { requirements, uploadedPaths }); }
+  /** Create a project from a chosen design; with `build`, also start its first run (one build). */
+  createFromDesign({ requirements, architecture, designFiles = [], build = false }) { return this.request("POST", "/projects", { design: { requirements, architecture, designFiles }, build }); }
+
+  projects() { return this.request("GET", "/projects"); }
+  createProject(name, description = "", hardwareType = "Undecided") { return this.request("POST", "/projects", { name, description, hardwareType }); }
+  project(id) { return this.request("GET", `/projects/${encodeURIComponent(id)}`); }
+  /** Delete a project on the server for good (files, runs, history). */
+  async deleteProject(id) {
+    try {
+      return await this.request("DELETE", `/projects/${encodeURIComponent(id)}`);
+    } catch (error) {
+      // Servers older than this client have no delete route for local clients.
+      if (error?.status === 405) throw new TapeoApiError(`This Tapeo server cannot delete projects from the terminal yet. Delete it in the browser: open ${this.serverUrl}, then use the delete button next to the project in your project list.`, 405);
+      throw error;
+    }
+  }
+  file(id, path) { return this.request("GET", `/projects/${encodeURIComponent(id)}/files?path=${encodeURIComponent(path)}`); }
+  saveFile(id, path, content, baseSha256, language) { return this.request("PUT", `/projects/${encodeURIComponent(id)}/files?path=${encodeURIComponent(path)}`, { content, baseSha256, language }); }
+  deleteFile(id, path, baseSha256) { return this.request("DELETE", `/projects/${encodeURIComponent(id)}/files?path=${encodeURIComponent(path)}&baseSha256=${encodeURIComponent(baseSha256)}`); }
+  runs(id) { return this.request("GET", `/projects/${encodeURIComponent(id)}/runs`); }
+  runDetail(id, runId) { return this.request("GET", `/projects/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}`); }
+  cancelRun(id, runId) { return this.request("POST", `/projects/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/cancel`, {}); }
+  toolRunLog(id, toolRunId) { return this.request("GET", `/projects/${encodeURIComponent(id)}/tool-runs/${encodeURIComponent(toolRunId)}`); }
+  goals(id) { return this.request("GET", `/projects/${encodeURIComponent(id)}/goals`); }
+  // Local clients run the files the user just pushed. The browser's first-run
+  // generation path remains a separate, explicit action.
+  run(id, scope) { return this.request("POST", `/projects/${encodeURIComponent(id)}/runs`, { reuseCurrentFiles: true, ...(scope ? { scope } : {}) }); }
+
+  /** The newest run, or a named one. */
+  async latestRunId(id, runId) {
+    if (runId) return runId;
+    const { runs } = await this.runs(id);
+    if (!runs.length) throw new Error("This project has no workflow runs yet. Start one with `tapeo run`.");
+    return runs[0].id;
+  }
+}
+
+/** A stage range for `run --stage` (one stage) or `run --from` (that stage and every later one). */
+export function stageScope({ stage, from, aiRepairs = true }) {
+  const key = stage ?? from;
+  if (!key) return undefined;
+  if (!WORKFLOW_STAGE_KEYS.includes(key)) throw new Error(`Unknown stage "${key}". Use one of: ${WORKFLOW_STAGE_KEYS.join(", ")}.`);
+  return { from: key, to: stage ? key : "lvs", aiRepairs };
+}
+
+/**
+ * Follow a run until it ends. `onChange` receives the detail whenever the
+ * status, current stage, or finished stages change. Returns the final detail.
+ */
+export async function watchRun(client, projectId, runId, { onChange, intervalMs = 3000, signal, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
+  let previous = "";
+  for (;;) {
+    if (signal?.aborted) throw new Error("Stopped following the run.");
+    const detail = await client.runDetail(projectId, runId);
+    const fingerprint = JSON.stringify([detail.run.status, detail.run.currentStage, detail.run.details?.stages?.length ?? 0, detail.toolRuns?.length ?? 0]);
+    if (fingerprint !== previous) { previous = fingerprint; await onChange?.(detail); }
+    if (!ACTIVE_RUN_STATUSES.includes(detail.run.status)) return detail;
+    await sleep(intervalMs);
+  }
+}

package/shared/fpga.mjs

@@ -0,0 +1,72 @@
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { localTarget } from "./sync.mjs";
+
+/**
+ * Programming an FPGA board from the local clients (tapeo flash, and Tapeo:
+ * Program FPGA Board in VS Code). The bitstream is built on the server; this
+ * downloads it and runs the open-source openFPGALoader on your computer.
+ * Board names mirror lib/fpga-boards.ts (tests/client-fpga.test.ts keeps them in sync).
+ */
+export const FPGA_PROGRAMMERS = {
+  tangnano9k: { label: "Sipeed Tang Nano 9K", openFpgaLoaderBoard: "tangnano9k" },
+  tangnano20k: { label: "Sipeed Tang Nano 20K", openFpgaLoaderBoard: "tangnano20k" },
+  icebreaker: { label: "1BitSquared iCEBreaker", openFpgaLoaderBoard: "ice40_generic" },
+  ulx3s12f: { label: "Radiona ULX3S (12F)", openFpgaLoaderBoard: "ulx3s" },
+  ulx3s85f: { label: "Radiona ULX3S (85F)", openFpgaLoaderBoard: "ulx3s" }
+};
+
+export const OPENFPGALOADER_INSTALL = [
+  "openFPGALoader is needed to program the board. Install it, then run this again:",
+  "  macOS:          brew install openfpgaloader",
+  "  Debian/Ubuntu:  sudo apt install openfpgaloader",
+  "  Windows/other:  it is included in OSS CAD Suite (https://github.com/YosysHQ/oss-cad-suite-build)"
+].join("\n");
+
+/** The bitstreams a project has, newest builds per board (paths from the server manifest). */
+export function findBitstreams(files) {
+  return files.flatMap((file) => {
+    const match = /^generated\/fpga\/([a-z0-9]+)\/board_top\.(fs|bin|bit)$/.exec(file.path);
+    return match && FPGA_PROGRAMMERS[match[1]] ? [{ path: file.path, boardId: match[1], ...FPGA_PROGRAMMERS[match[1]] }] : [];
+  });
+}
+
+/** Pick the board to program: the only one built, or the one named with --board. */
+export function chooseBitstream(files, boardId) {
+  const bitstreams = findBitstreams(files);
+  if (!bitstreams.length) throw new Error("This project has no bitstream yet. Run the workflow first (tapeo run --watch); FPGA projects build one for their board.");
+  if (boardId) {
+    const chosen = bitstreams.find((item) => item.boardId === boardId);
+    if (!chosen) throw new Error(`No bitstream for ${boardId}. Built for: ${bitstreams.map((item) => item.boardId).join(", ")}.`);
+    return chosen;
+  }
+  if (bitstreams.length > 1) throw new Error(`Bitstreams exist for several boards (${bitstreams.map((item) => item.boardId).join(", ")}). Name one with --board.`);
+  return bitstreams[0];
+}
+
+/** Download the bitstream into the project folder (read-only, like other tool outputs). */
+export async function downloadBitstream(client, projectId, bitstream, directory) {
+  const { bytes } = await client.rawFile(projectId, bitstream.path);
+  const target = await localTarget(directory, bitstream.path);
+  await mkdir(path.dirname(target), { recursive: true });
+  await chmod(target, 0o644).catch(() => undefined);
+  await writeFile(target, bytes);
+  await chmod(target, 0o444).catch(() => undefined);
+  return target;
+}
+
+/** The programmer to run; TAPEO_OPENFPGALOADER overrides the executable (for example a full path). */
+export function openFpgaLoaderExecutable() {
+  return process.env.TAPEO_OPENFPGALOADER || "openFPGALoader";
+}
+
+export function openFpgaLoaderAvailable(executable = openFpgaLoaderExecutable()) {
+  const result = spawnSync(executable, ["-V"], { encoding: "utf8" });
+  return !result.error && result.status === 0;
+}
+
+/** openFPGALoader arguments: SRAM by default (lost at power-off), flash with `flash: true`. */
+export function flashArguments(bitstream, localPath, { flash = false } = {}) {
+  return ["-b", bitstream.openFpgaLoaderBoard, ...(flash ? ["--write-flash"] : []), localPath];
+}

package/shared/problems.mjs

@@ -0,0 +1,82 @@
+/**
+ * File and line problems in tool logs, for the editor's Problems panel and
+ * `tapeo problems`. Recognizes the location formats of the tools Tapeo runs:
+ *
+ *   Icarus Verilog   rtl/a.sv:12: error: Unknown module type: foo
+ *   Verilator        %Error: rtl/a.sv:12:5: message      %Warning-WIDTH: rtl/a.sv:12:5: ...
+ *   Yosys            rtl/a.sv:12: ERROR: syntax error    ... at rtl/a.sv:12.3-12.10
+ *   OpenROAD/STA     Error: analysis/flow.tcl, 42 ...    [ERROR STA-0123] analysis/x.tcl line 42, ...
+ *
+ * Paths in logs may be absolute (the tool's workspace); they are matched to
+ * project files by their ending. Lines without a project file are left out.
+ */
+const PATTERNS = [
+  // Verilator: %Error: path:line:col: message (also %Warning-CODE)
+  { regex: /%(Error|Warning)(?:-[A-Z0-9_]+)?:\s*([^\s:]+):(\d+):(?:(\d+):)?\s*(.*)$/, map: (m) => ({ severity: m[1], path: m[2], line: m[3], column: m[4], message: m[5] }) },
+  // path:line[:col]: [error|warning|ERROR|syntax error]: message (Icarus, Yosys, GCC-style)
+  { regex: /(?:^|\s)([^\s:'"()]+\.[A-Za-z0-9]+):(\d+)(?::(\d+))?:\s*(?:(error|warning|ERROR|WARNING|Error|Warning)\b:?\s*)?(.*)$/, map: (m) => ({ severity: m[4] ?? (/warn/i.test(m[5]) ? "warning" : "error"), path: m[1], line: m[2], column: m[3], message: m[5] }) },
+  // Yosys location at the end: "... at rtl/a.sv:12.3-12.10"
+  { regex: /^(?:(ERROR|Warning|WARNING)[:\s]+)?(.*?)\s+at\s+([^\s:]+\.[A-Za-z0-9]+):(\d+)(?:\.(\d+))?/, map: (m) => ({ severity: m[1] ?? "error", path: m[3], line: m[4], column: m[5], message: m[2] }) },
+  // Tcl scripts: "Error: flow.tcl, 42 message" or "[ERROR STA-0123] flow.tcl line 42, message"
+  { regex: /(Error|ERROR|Warning|WARNING)[^\n]*?([^\s,:'"]+\.tcl)(?:,\s*|\s+line\s+)(\d+)[,:]?\s*(.*)$/, map: (m) => ({ severity: m[1], path: m[2], line: m[3], message: m[4] }) }
+];
+
+/** The project path a log path refers to (exact, or the longest project path it ends with). */
+export function matchProjectPath(logPath, projectPaths) {
+  const clean = logPath.replace(/^\.\//, "").replaceAll("\\", "/");
+  if (projectPaths.includes(clean)) return clean;
+  let best = null;
+  for (const candidate of projectPaths) if (clean.endsWith(`/${candidate}`) && (!best || candidate.length > best.length)) best = candidate;
+  if (best) return best;
+  // A bare file name (tools often print only the script name): only when exactly one project file has it.
+  const byName = projectPaths.filter((candidate) => candidate.endsWith(`/${clean}`));
+  return byName.length === 1 ? byName[0] : null;
+}
+
+/** Problems in one log. `tool` labels them; `includeWarnings` keeps warnings (failed runs only, by default). */
+export function extractProblems(text, projectPaths, { tool = "", includeWarnings = true } = {}) {
+  const problems = [];
+  const seen = new Set();
+  for (const rawLine of String(text ?? "").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    for (const pattern of PATTERNS) {
+      const match = pattern.regex.exec(line);
+      if (!match) continue;
+      const found = pattern.map(match);
+      const path = matchProjectPath(found.path, projectPaths);
+      if (!path) continue;
+      const severity = /warn/i.test(found.severity) ? "warning" : "error";
+      if (severity === "warning" && !includeWarnings) break;
+      const message = (found.message || line).trim().replace(/^:\s*/, "") || line;
+      const problem = { path, line: Math.max(1, Number(found.line)), ...(found.column ? { column: Math.max(1, Number(found.column)) } : {}), severity, message: message.slice(0, 500), ...(tool ? { tool } : {}) };
+      const key = `${problem.path}:${problem.line}:${problem.message}`;
+      if (!seen.has(key)) { seen.add(key); problems.push(problem); }
+      break;
+    }
+    if (problems.length >= 200) break;
+  }
+  return problems;
+}
+
+/**
+ * Problems from a run's tool logs: every tool run's errors, and warnings
+ * from the tool runs that failed. Returns them grouped by file order.
+ */
+export async function collectRunProblems(client, projectId, runId, projectPaths) {
+  const { toolRuns = [] } = await client.runDetail(projectId, runId);
+  const problems = [];
+  for (const tool of toolRuns.slice(-12)) {
+    const failed = !/^(passed|completed|success)/i.test(tool.status ?? "");
+    const { toolRun } = await client.toolRunLog(projectId, tool.id);
+    problems.push(...extractProblems(`${toolRun.summary ?? ""}\n${toolRun.stdout ?? ""}\n${toolRun.stderr ?? ""}`, projectPaths, { tool: toolRun.tool, includeWarnings: failed }));
+  }
+  const seen = new Set();
+  return problems.filter((problem) => { const key = `${problem.path}:${problem.line}:${problem.message}`; if (seen.has(key)) return false; seen.add(key); return true; })
+    .sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line);
+}
+
+/** `path:line:col: severity: message [tool]`, the form editors and terminals link. */
+export function formatProblem(problem) {
+  return `${problem.path}:${problem.line}${problem.column ? `:${problem.column}` : ""}: ${problem.severity}: ${problem.message}${problem.tool ? ` [${problem.tool}]` : ""}`;
+}

package/shared/proposals.mjs

@@ -0,0 +1,112 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { localTarget, readState, safeSourcePath } from "./sync.mjs";
+
+/**
+ * File changes the AI Engineer proposed, kept in `.tapeo/proposals.json` so
+ * the terminal and VS Code can review and apply them, then push. Applying
+ * follows the browser's rules (components/ProjectWorkspace.tsx): a new file
+ * must not exist yet, and a replacement's original code must occur exactly
+ * once in the file.
+ */
+const PROPOSALS_FILE = ".tapeo/proposals.json";
+
+/** The file content after one change, or null when the change deletes the file. Throws when it cannot apply. */
+export function applyChangeToText(current, change) {
+  if (change.action === "create") {
+    if (current !== null) throw new Error(`${change.file} already exists.`);
+    return change.newCode;
+  }
+  if (current === null) throw new Error(`${change.file} was not found.`);
+  if (change.action === "delete") return null;
+  const matches = current.split(change.oldCode).length - 1;
+  if (matches === 0) throw new Error(`The expected code was not found in ${change.file}. The file may have changed since the Engineer suggested this.`);
+  if (matches > 1) throw new Error(`The expected code appears ${matches} times in ${change.file}, so the change is ambiguous.`);
+  // A function replacement keeps "$" sequences in code literal; an empty newCode removes the text.
+  return current.replace(change.oldCode, () => change.newCode);
+}
+
+/** The change as removed (-) and added (+) lines, for review. */
+export function changeDiff(change) {
+  const lines = (text) => String(text ?? "").replace(/\n$/, "").split("\n");
+  if (change.action === "create") return lines(change.newCode).map((line) => `+ ${line}`).join("\n");
+  if (change.action === "delete") return "- (the whole file is deleted)";
+  return [...lines(change.oldCode).map((line) => `- ${line}`), ...(change.newCode ? lines(change.newCode).map((line) => `+ ${line}`) : [])].join("\n");
+}
+
+/** One-line description of a change. */
+export function describeChange(change, index) {
+  const verb = change.action === "create" ? "create" : change.action === "delete" ? "delete" : "edit";
+  const status = change.status && change.status !== "pending" ? ` [${change.status}${change.error ? `: ${change.error}` : ""}]` : "";
+  return `${index + 1}. ${verb} ${change.file}: ${change.reason}${status}`;
+}
+
+export async function loadProposals(directory) {
+  try { return JSON.parse(await readFile(await localTarget(directory, PROPOSALS_FILE), "utf8")); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+}
+
+async function writeProposals(directory, proposals) {
+  const destination = await localTarget(directory, PROPOSALS_FILE);
+  await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+  await writeFile(destination, JSON.stringify(proposals, null, 2) + "\n", { mode: 0o600 });
+}
+
+/** Keep the Engineer's latest answer and its changes for review (replaces earlier unapplied ones). */
+export async function saveProposals(directory, { question, result }) {
+  await readState(directory);
+  const changes = (result.proposedChanges ?? []).map((change) => ({ ...change, status: safeSourcePath(change.file) ? "pending" : "refused", ...(safeSourcePath(change.file) ? {} : { error: "Tool output and unsafe paths cannot be changed locally." }) }));
+  const proposals = { version: 1, createdAt: new Date().toISOString(), question, message: result.message, changes, evaluationPlanProposed: Boolean(result.proposedEvaluationPlan) };
+  await writeProposals(directory, proposals);
+  return proposals;
+}
+
+/** The file's current local text, or null when it does not exist. */
+async function localText(directory, projectPath) {
+  try { return await readFile(await localTarget(directory, projectPath), "utf8"); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+}
+
+/** What a pending change would make the file look like (for a side-by-side review). */
+export async function proposedContent(directory, change) {
+  const current = await localText(directory, change.file);
+  return { current, proposed: applyChangeToText(current, change) };
+}
+
+/**
+ * Apply pending changes (1-based numbers, or "all") to the local files.
+ * Each change applies on its own; one that no longer fits is marked failed
+ * with the reason and the rest still apply. Push afterwards to save them.
+ */
+export async function applyProposals(directory, which = "all") {
+  const proposals = await loadProposals(directory);
+  if (!proposals?.changes?.length) throw new Error("There are no proposed changes. Ask the Engineer first.");
+  const wanted = which === "all" ? proposals.changes.map((_, index) => index) : [].concat(which).map((number) => Number(number) - 1);
+  const results = [];
+  for (const index of wanted) {
+    const change = proposals.changes[index];
+    if (!change) { results.push({ index, ok: false, message: `There is no change ${index + 1}.` }); continue; }
+    // A failed change can be retried (after the file is fixed); applied and refused ones cannot.
+    if (change.status === "applied" || change.status === "refused") { results.push({ index, file: change.file, ok: false, message: `Change ${index + 1} is ${change.status}.` }); continue; }
+    try {
+      const target = await localTarget(directory, change.file);
+      const next = applyChangeToText(await localText(directory, change.file), change);
+      if (next === null) await rm(target, { force: true });
+      else { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, next, "utf8"); }
+      change.status = "applied";
+      delete change.error;
+      results.push({ index, file: change.file, ok: true, deleted: next === null });
+    } catch (error) {
+      change.status = "failed";
+      change.error = error.message;
+      results.push({ index, file: change.file, ok: false, message: error.message });
+    }
+  }
+  await writeProposals(directory, proposals);
+  return results;
+}
+
+/** Forget the proposed changes without applying them. */
+export async function discardProposals(directory) {
+  await rm(await localTarget(directory, PROPOSALS_FILE), { force: true });
+}

package/shared/serial.mjs

@@ -0,0 +1,77 @@
+import { closeSync, constants, openSync, readdirSync, writeSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import tty from "node:tty";
+
+/**
+ * A serial monitor for a connected FPGA board (tapeo monitor, and Tapeo: Open
+ * Serial Monitor in VS Code), without native modules: the port is opened as a
+ * file, configured with the system's stty on that open descriptor, and read as
+ * a terminal stream. macOS and Linux only; on Windows, use the browser's serial
+ * monitor on the Workflow tab (Chrome or Edge).
+ */
+
+export const DEFAULT_BAUD = 115200;
+export const SERIAL_UNSUPPORTED = "The serial monitor runs on macOS and Linux. On Windows, open the project's Workflow tab in Chrome or Edge and use its Serial monitor.";
+
+/** USB serial ports that may be a board, newest naming first. macOS uses the cu.* (call-out) devices, which do not wait for a carrier. */
+export function serialCandidates(platform = process.platform, names = safeList("/dev")) {
+  const pattern = platform === "darwin" ? /^cu\.(?:usbserial|usbmodem|wchusbserial|SLAB_USBtoUART)/ : platform === "linux" ? /^tty(?:USB|ACM)\d+$/ : null;
+  if (!pattern) return [];
+  return names.filter((name) => pattern.test(name)).sort().map((name) => `/dev/${name}`);
+}
+
+function safeList(directory) {
+  try { return readdirSync(directory); } catch { return []; }
+}
+
+/** The port to open: the one named, the only one found, or an explanation. */
+export function chooseSerialPort(candidates, requested) {
+  if (requested) return requested;
+  if (!candidates.length) throw new Error("No USB serial port was found. Connect the board by USB, or name the port with --port.");
+  if (candidates.length > 1) throw new Error(`Several serial ports were found:\n${candidates.map((item) => `  ${item}`).join("\n")}\nName one with --port. A Tang Nano shows two; its serial link is usually the second.`);
+  return candidates[0];
+}
+
+export function parseBaud(value) {
+  if (value === undefined || value === true) return DEFAULT_BAUD;
+  const baud = Number(value);
+  if (!Number.isInteger(baud) || baud < 300 || baud > 4_000_000) throw new Error(`--baud must be a whole number from 300 to 4000000 (got ${value}).`);
+  return baud;
+}
+
+/** stty settings for 8N1 raw data at `baud`, no flow control, ignoring modem lines. */
+export function sttyArguments(baud) {
+  return [String(baud), "raw", "-echo", "cs8", "-cstopb", "-parenb", "clocal", "-crtscts", "-ixon", "-ixoff"];
+}
+
+/**
+ * Open `portPath` at `baud`. Returns the incoming stream, a write function, and close.
+ * The settings are applied while the port is open, so the driver keeps them.
+ */
+export function openSerialPort(portPath, baud = DEFAULT_BAUD, platform = process.platform) {
+  if (platform !== "darwin" && platform !== "linux") throw new Error(SERIAL_UNSUPPORTED);
+  let readFd;
+  try {
+    readFd = openSync(portPath, constants.O_RDWR | constants.O_NOCTTY | constants.O_NONBLOCK);
+  } catch (error) {
+    throw new Error(error?.code === "EBUSY" || error?.code === "EACCES"
+      ? `Could not open ${portPath}: ${error.code === "EBUSY" ? "another program is using it (close other serial monitors)" : "permission denied (on Linux, add yourself to the dialout group, then sign in again)"}.`
+      : `Could not open ${portPath}: ${error?.message ?? error}`);
+  }
+  if (!tty.isatty(readFd)) { closeSync(readFd); throw new Error(`${portPath} is not a serial port.`); }
+  const configured = spawnSync("stty", sttyArguments(baud), { stdio: [readFd, "ignore", "pipe"], encoding: "utf8" });
+  if (configured.error || configured.status !== 0) { closeSync(readFd); throw new Error(`Could not set ${portPath} to ${baud} baud: ${configured.stderr?.trim() || configured.error?.message || "stty failed"}.`); }
+  const writeFd = openSync(portPath, constants.O_WRONLY | constants.O_NOCTTY);
+  const input = new tty.ReadStream(readFd);
+  let closed = false;
+  return {
+    input,
+    write(data) { if (!closed) writeSync(writeFd, typeof data === "string" ? Buffer.from(data, "utf8") : data); },
+    close() {
+      if (closed) return;
+      closed = true;
+      input.destroy();
+      try { closeSync(writeFd); } catch { /* already closed */ }
+    }
+  };
+}

package/shared/stream.mjs

@@ -0,0 +1,62 @@
+/**
+ * Streamed AI answers (the Architect and the Engineer): newline-delimited
+ * JSON with `{ type: "delta", text }` while the model writes, then one
+ * `{ type: "result", data }` or `{ type: "error", error }`. Mirrors
+ * lib/ndjson-stream.ts and lib/architect-response.ts in the web app.
+ */
+export async function readAnswerStream(body, onText, incompleteMessage) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "", raw = "", result = null;
+  const handle = (line) => {
+    if (!line.trim()) return;
+    const event = JSON.parse(line);
+    if (event.type === "delta" && event.text) { raw += event.text; onText?.(raw); }
+    else if (event.type === "result" && event.data !== undefined) result = event.data;
+    else if (event.type === "error") throw new Error(event.error || incompleteMessage);
+  };
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffered += decoder.decode(value, { stream: true });
+    const lines = buffered.split("\n");
+    buffered = lines.pop() ?? "";
+    for (const line of lines) handle(line);
+  }
+  handle(buffered + decoder.decode());
+  if (result === null) throw new Error(incompleteMessage);
+  return result;
+}
+
+/** A top-level string field ("message") of JSON still arriving, decoded so far. */
+export function partialJsonStringField(raw, key) {
+  const match = new RegExp(`"${key}"\\s*:\\s*"`).exec(raw);
+  if (!match) return "";
+  let result = "";
+  for (let index = match.index + match[0].length; index < raw.length; index += 1) {
+    const char = raw[index];
+    if (char === "\"") return result;
+    if (char !== "\\") { result += char; continue; }
+    const next = raw[index + 1];
+    if (next === undefined) return result;
+    if (next === "u") {
+      const hex = raw.slice(index + 2, index + 6);
+      if (hex.length < 4) return result;
+      result += String.fromCharCode(Number.parseInt(hex, 16));
+      index += 5;
+      continue;
+    }
+    result += ({ n: "\n", t: "\t", r: "", b: "", f: "" })[next] ?? next;
+    index += 1;
+  }
+  return result;
+}
+
+/** The choice that leaves a question to the Architect (as in the browser). */
+export const NOT_SURE = "Not sure — you choose";
+
+/** The chat message answering the Architect's clarifying questions (same wording as the browser). */
+export function clarificationAnswersMessage(clarifications, answers, note = "") {
+  const lines = clarifications.map((item, index) => `- ${item.question} → ${answers[index] ?? "Not sure — choose a sensible default and tell me what you chose"}`);
+  return ["My answers:", ...lines, ...(note.trim() ? ["", note.trim()] : [])].join("\n");
+}