tapeo-cli 0.4.0 → 0.5.0

package/README.md

@@ -35,7 +35,7 @@ In VS Code, install **Tapeo** from the Extensions view and run **Tapeo: Connect
 
 ## About
 
-A terminal client and a VS Code extension for the same Tapeo projects as the web app. They call the same server, file storage, workflow queue, and plan allowances as the browser, through the token-authenticated API under `/api/client/v1`. Version 0.4.0 was published on 2026-10-24 (`tapeo-cli` on npm and **Tapeo**, `tapeo.tapeo-vscode`, on the VS Code Marketplace). They are early releases (0.x).
+A terminal client and a VS Code extension for the same Tapeo projects as the web app. They call the same server, file storage, workflow queue, and plan allowances as the browser, through the token-authenticated API under `/api/client/v1`. Version 0.5.0 was published on 2026-10-24 (`tapeo-cli` on npm and **Tapeo**, `tapeo.tapeo-vscode`, on the VS Code Marketplace). They are early releases (0.x).
 
 The edit → run → results loop works without the browser: push your files, start a run, follow it stage by stage, and read stage results, tool logs, and goal results. You can also start a new design with the Architect, ask the AI Engineer and apply its proposed changes locally, and see tool errors on the lines they name. The 2D/3D layout views, Evaluation-plan review, and Architect image/PDF attachments stay in the web workspace.
 
@@ -50,6 +50,29 @@ tapeo login                       # https://tapeo.net; or: tapeo login https://y
 
 `tapeo login` opens `/device?code=ABCD-EFGH` in your browser. Check that the code matches, approve the device, and the terminal finishes signing in. Only a digest of the device code is stored, and no token exists until you approve. The device gets its own token: it expires after 90 days, appears on **Account → VS Code and terminal access**, and can be revoked there. Without a browser, create a token on that page and use `tapeo login <url> --token` (hidden prompt). The sign-in is saved in `~/.config/tapeo/client.json` (mode 0600); `tapeo logout` removes it. `TAPEO_URL` and `TAPEO_TOKEN` override it for automation. `TAPEO_NO_BROWSER=1` makes `tapeo login` only print the approval address instead of opening a browser. Remote servers must use HTTPS; HTTP is accepted for localhost only.
 
+## Bringing an existing project (tapeo.json)
+
+Any folder layout works: `tapeo create "My design" .` then `tapeo push --all` keeps every path. By convention Tapeo treats every `.v`/`.sv` outside testbench folders as the design, picks the top module that nothing else instantiates, and finds the testbench by name. When that guess is wrong for your repository, add a `tapeo.json` at the project root:
+
+```json
+{
+  "top": "soc_top",
+  "filelist": "hw/files.f",
+  "sources": ["hw/extra/**/*.sv", "!hw/legacy/**"],
+  "includeDirs": ["hw/include"],
+  "defines": ["WIDTH=32"],
+  "verification": ["verif/common/**/*.sv"],
+  "testbenches": { "default": "verif/tb_soc.sv", "uart": { "files": ["verif/uart/*.sv"], "top": "tb_uart" } },
+  "constraints": "constraints/soc.sdc"
+}
+```
+
+- `sources` are patterns (`**` matches folders, `*` part of a name, `!` removes); `filelist` reads an existing simulator file list (`.f`: files in compile order, `+incdir+`, `+define+`, `-I`, `-D`, `-f`, `-v`). Either one is required.
+- Lint, simulation, synthesis, the FPGA build, and timing all use the same sources, top, defines, and include folders. Simulation compiles only the design, the `verification` files, and the chosen testbench; workflows run `default` (or the first), and `tapeo sim --testbench <name>` picks another.
+- `tapeo manifest` (or **Show Project Manifest**) shows what Tapeo resolved. A broken `tapeo.json` stops the stages with a message that says what to fix; deleting it returns to the conventions.
+- Include folders may use only letters, digits, `.`, `_`, `+`, `-`, and `/`; defines are `NAME` or `NAME=value` without spaces or quotes.
+- Without `tapeo.json`, nothing changes.
+
 ## Terminal
 
 ```sh
@@ -57,6 +80,14 @@ tapeo projects                         # your projects
 tapeo create "My sensor" ./my-sensor   # new empty project, bound to the folder
 tapeo pull PROJECT_ID ./existing       # or bind an existing project
 tapeo delete PROJECT_ID                # delete a project on the server for good (asks for its name)
+tapeo lock rtl/top.sv                  # protect a file: the AI's fixes become suggestions (pushed files start protected)
+tapeo unlock rtl/top.sv                # let the AI Engineer repair it during runs again
+tapeo checkpoints                      # saved checkpoints, newest first
+tapeo checkpoint "before the FIFO"     # save one (holds the files saved in Tapeo now)
+tapeo restore 12 rtl/top.sv            # put back a file's version from checkpoint 12 (saved as your edit)
+tapeo target                           # where the design runs, with the boards
+tapeo target fpga --board tangnano20k --clock 50
+tapeo process sky130hs                 # change the chip process (old flows and layouts are rebuilt)
 cd ./my-sensor
 tapeo status                           # what changed locally, and the latest run
 tapeo push --all                       # push every modified and new source file
@@ -91,13 +122,27 @@ tapeo push --all         # then save them in Tapeo
 tapeo discard            # or forget them
 tapeo history            # the Engineer conversation, shared with the browser (--limit N, default 10)
 tapeo problems           # tool errors and warnings of the latest run, as file:line:col
+tapeo lint               # lint the pushed design RTL in seconds (no build), as file:line:col
+tapeo sim                # simulate the saved files now (no workflow run, no build)
+tapeo sim --testbench uart   # a testbench named in tapeo.json
+tapeo manifest           # what tapeo.json resolves to: sources, top, testbenches
+tapeo sims               # recent simulations
+tapeo wave --open        # save the latest waveform (.tapeo/waveforms/) and open it in Surfer or GTKWave
+tapeo goals list         # the goals and how each is measured
+tapeo goals add fpga_logic_utilization between 0..80 % --note "room to grow"
+tapeo goals remove fpga_logic_utilization
+tapeo goals edit         # write .tapeo/goals.json; edit it, then: tapeo goals save
 ```
 
+Goals you add are measured once a full workflow run plans how (it keeps your goals and adds the measuring step). Checkpoints, restores, goal edits, and target or process changes are the same actions as in the browser and show up there.
+
 `tapeo new` asks the Architect's clarifying questions and lets you pick an option when run in a terminal. For scripts, `--auto-answers` answers "Not sure — you choose", `--option N` picks a design, `--yes` confirms the build (one build from your plan), and `--no-build` creates the project without building. After the build, the generated files are pulled into the folder. The Architect conversation is not saved on the server; the project keeps the chosen requirements and design.
 
 The Engineer reads the saved server copy of your files (`tapeo ask` warns when local edits are not pushed). Its proposed changes are kept in `.tapeo/proposals.json` until you apply or discard them, and a new answer with changes replaces them. Applying follows the browser's rules: a new file must not exist yet, and the code being replaced must occur exactly once. A change that no longer fits is marked failed with the reason and can be retried after you fix the file. Changes to tool outputs (`generated/`, `signoff/`) or paths outside the project are refused. Deleting a file applies locally; `tapeo rm` deletes it on the server. If the Engineer also proposed an evaluation plan, review it in the web workspace.
 
-`tapeo problems [run-id]` reads the run's tool logs and lists file-level errors from every tool run, plus warnings from tool runs that failed. It recognizes Verilator, Icarus Verilog, Yosys, and Tcl script locations and matches log paths to project files by their ending. Messages without a project file and line stay in `tapeo logs`.
+`tapeo lint` runs only the lint stage (Verilator on the design RTL; testbenches and FPGA board wrappers are left out) on the files saved in Tapeo, so push first. It prints errors, warnings that usually mean a bug (widths, latches, multiple drivers), and style notes such as unused signals, and exits with an error when lint finds errors. **Lint Design** does the same in VS Code and fills the Problems panel. Every full workflow run also lints first.
+
+`tapeo problems [run-id]` reads the run's tool logs and lists file-level errors from every tool run, plus warnings from tool runs that failed and from lint. Lint style notes (unused signals, zero-extended widths) are labelled `note`, and appear as information in VS Code's Problems panel. It recognizes Verilator, Icarus Verilog, Yosys, and Tcl script locations and matches log paths to project files by their ending. Messages without a project file and line stay in `tapeo logs`.
 
 Stages: `simulation`, `synthesis`, `timing`, `physical`, `post-route-timing`, `drc`, `extraction`, `erc`, `lvs`. `--no-ai-repairs` turns off AI repairs for a stage run. A full run uses one build from your plan; a stage run does not. `tapeo run --watch` exits with code 3 when the run fails.
 
@@ -131,6 +176,13 @@ Run `npm run build:vscode`, open `clients/vscode` in VS Code, and press F5; or r
 - **Open AI Engineer** opens the **Tapeo Engineer** panel beside the editor: the project conversation, streamed answers, and the proposed changes with **Review** (a side-by-side diff), **Apply**, **Apply all**, and **Discard**. **Ask the AI Engineer**, **Review Proposed Changes**, **Apply All Proposed Changes**, and **Discard Proposed Changes** do the same from the Command Palette. Applying is refused while the file has unsaved edits; push afterwards.
 - **Program FPGA Board** (FPGA projects): downloads the bitstream and programs the connected board with `openFPGALoader` in a **Tapeo FPGA** terminal.
 - **Open Serial Monitor** (macOS and Linux): shows the board's serial output in a terminal and sends the lines you type.
+- **Protect File from AI Repairs** / **Allow AI Repairs of File**: the open file's protection, like the lock icon in the browser.
+- **Save Checkpoint** and **Restore File from Checkpoint** (pick a checkpoint; the open file's version from it is written and saved as your edit).
+- **Show Project Manifest**: what `tapeo.json` resolves to. Editing `tapeo.json` in VS Code has completion and checks.
+- **Simulate** (no build; the result in the Tapeo output) and **Open Waveform** (saves the VCD under `.tapeo/waveforms/`; a waveform extension such as VaporView or Surfer shows it as signals).
+- **Edit Goals** opens `.tapeo/goals.json`; **Save Goals** uploads it.
+- **Change Target** (simulation, an FPGA board with its design clock, a chip, or both) and **Change Process**.
+- **Lint Design**: lint the pushed design RTL in seconds (no build) and show its errors and warnings in the Problems panel.
 - **Show Tool Problems**: the latest run's tool errors and warnings in the Problems panel. This also happens automatically when a run the status bar follows ends, and starting a run clears them.
 
 The setting `tapeo.serverUrl` holds the server (Connect to Server sets it; remote servers must use HTTPS).

package/cli/tapeo.mjs

@@ -8,6 +8,7 @@ import { assertUnbound, designFilesFrom, downloadFile, localChanges, moveProject
 import { applyProposals, changeDiff, describeChange, discardProposals, loadProposals, saveProposals } from "../shared/proposals.mjs";
 import { collectRunProblems, formatProblem } from "../shared/problems.mjs";
 import { NOT_SURE, clarificationAnswersMessage } from "../shared/stream.mjs";
+import { GOALS_FILE, describeGoal, describeManifest, goalFromArguments, readGoalsFile, removeLocalOutputs, restoreFromCheckpoint, saveWaveform, writeGoalsFile } from "../shared/project-tools.mjs";
 import { chooseSerialPort, openSerialPort, parseBaud, serialCandidates } from "../shared/serial.mjs";
 import { OPENFPGALOADER_INSTALL, chooseBitstream, downloadBitstream, flashArguments, openFpgaLoaderAvailable, openFpgaLoaderExecutable } from "../shared/fpga.mjs";
 import { createInterface } from "node:readline/promises";
@@ -39,6 +40,20 @@ Projects and files
   tapeo rm <path>                 Delete a file on the server and locally
   tapeo mv <from> <to>            Rename a file on the server and locally
   tapeo download <path> [dest]    Download one project file (any size, e.g. a GDS layout)
+  tapeo manifest                  What tapeo.json resolves to: sources, top, testbenches
+  tapeo lock <path...>            Protect files from automatic AI repairs (suggestions only)
+  tapeo unlock <path...>          Let the AI Engineer repair these files during runs again
+
+Checkpoints
+  tapeo checkpoints               Saved checkpoints, newest first
+  tapeo checkpoint ["name"]       Save a checkpoint of the files saved in Tapeo now
+  tapeo restore <n> <path...>     Put back a file's version from checkpoint n (saved as your edit)
+
+Settings
+  tapeo target [simulation|fpga|asic|fpga-asic] [--board <id>] [--clock <MHz>]
+                                  Show or change where the design runs (board and design clock)
+  tapeo process [id]              Show or change the chip process (clears the old process's
+                                  flows, netlists, and layouts; the next run rebuilds them)
 
 AI
   tapeo new [description] [dir]   Design a new chip with the Architect, then build it
@@ -50,6 +65,8 @@ AI
   tapeo apply [n...]              Apply proposed changes to local files (all by default)
   tapeo discard                   Forget the proposed changes
   tapeo problems [run-id]         Tool errors and warnings as file:line (latest run by default)
+  tapeo lint                      Lint the pushed design RTL with Verilator (seconds; does not
+                                  use a build) and list its problems as file:line
 
 Workflow
   tapeo run [--stage <s> | --from <s>] [--no-ai-repairs] [--watch]
@@ -59,6 +76,16 @@ Workflow
   tapeo show [run-id]             Stage results, AI changes, and tool runs of a run
   tapeo logs <tool-run-id>        A tool run's saved output
   tapeo goals                     The latest goal report
+  tapeo goals list                The goals and how each is measured
+  tapeo goals add <key> <op> <value> [unit] [--note "…"]
+                                  Add a goal (op: "<=", ">=", "=", between low..high)
+  tapeo goals remove <key>        Remove a goal
+  tapeo goals edit | save         Write the goals to .tapeo/goals.json to edit, then save them
+  tapeo sim [--testbench <name>]  Simulate the saved files now (no workflow run, no build);
+                                  --testbench picks one named in tapeo.json
+  tapeo sims                      Recent simulations
+  tapeo wave [sim-id] [--out <file>] [--open]
+                                  Save a simulation's waveform (VCD); --open starts Surfer or GTKWave
   tapeo cancel [run-id]           Cancel a queued or running workflow
   tapeo open                      Print this project's web address
 
@@ -71,7 +98,7 @@ FPGA boards
                                   Show the board's serial (UART) output and send what you
                                   type; default 115200 baud (macOS and Linux)
 
-Stages: simulation, synthesis, timing, physical, post-route-timing, drc, extraction, erc, lvs.
+Stages: lint, simulation, synthesis, timing, physical, post-route-timing, drc, extraction, erc, lvs.
 TAPEO_URL and TAPEO_TOKEN override the saved sign-in (for automation).`);
 }
 
@@ -319,7 +346,7 @@ async function main() {
     return;
   }
   const client = await configuredClient();
-  const { flags, positional: args } = parseArguments(rest, ["stage", "from", "option", "limit", "board"]);
+  const { flags, positional: args } = parseArguments(rest, ["stage", "from", "option", "limit", "board", "clock", "note", "out", "testbench"]);
   if (command === "new") {
     await newDesign(client, args[0], path.resolve(args[1] || "."), flags);
   } else if (command === "ask") {
@@ -360,6 +387,25 @@ async function main() {
   } else if (command === "discard") {
     await discardProposals(process.cwd());
     console.log("Proposed changes discarded.");
+  } else if (command === "lint") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    const changes = await localChanges(directory).catch(() => null);
+    if (changes && (changes.modified.length || changes.added.length)) console.log(`Note: lint reads the files saved in Tapeo; ${changes.modified.length + changes.added.length} local change(s) are not pushed yet (tapeo push --all).`);
+    let run;
+    try {
+      ({ run } = await client.run(projectId, stageScope({ stage: "lint", aiRepairs: false })));
+    } catch (error) {
+      if (error?.status === 400 && /Unknown workflow stage/i.test(error.message)) throw new Error("This Tapeo server does not lint yet. Run the full workflow instead (tapeo run --watch), or ask the server owner to update it.");
+      throw error;
+    }
+    const final = await watchRun(client, projectId, run.id, {});
+    const stage = final.run.details?.stages?.find((item) => item.label === "RTL lint");
+    console.log(stage ? `${stage.status === "completed" ? "✓" : stage.status === "issues" ? "!" : stage.status === "skipped" ? "–" : "✗"} ${stage.summary}` : `Lint run ${run.id} ended: ${final.run.status}.`);
+    const { files } = await client.project(projectId);
+    const problems = await collectRunProblems(client, projectId, run.id, files.map((file) => file.path));
+    for (const problem of problems) console.log(formatProblem(problem));
+    if (stage?.status === "failed") process.exitCode = 1;
   } else if (command === "problems") {
     const projectId = await projectIdFor(client);
     const runId = await client.latestRunId(projectId, args[0]);
@@ -367,7 +413,8 @@ async function main() {
     const problems = await collectRunProblems(client, projectId, runId, files.map((file) => file.path));
     for (const problem of problems) console.log(formatProblem(problem));
     const errors = problems.filter((problem) => problem.severity === "error").length;
-    console.log(problems.length ? `\n${errors} error(s), ${problems.length - errors} warning(s) in run ${runId}.` : `No file-level problems in run ${runId}'s tool logs. See tapeo show for stage results.`);
+    const notes = problems.filter((problem) => problem.severity === "note").length;
+    console.log(problems.length ? `\n${errors} error(s), ${problems.length - errors - notes} warning(s)${notes ? `, ${notes} note(s)` : ""} in run ${runId}.` : `No file-level problems in run ${runId}'s tool logs. See tapeo show for stage results.`);
   } else if (command === "projects") {
     const { projects } = await client.projects();
     for (const project of projects) console.log(`${project.id}\t${project.name}`);
@@ -475,9 +522,128 @@ async function main() {
     if (toolRun.stdout) console.log(`--- stdout ---\n${toolRun.stdout}`);
     if (toolRun.stderr) console.log(`--- stderr ---\n${toolRun.stderr}`);
     if (!toolRun.stdout && !toolRun.stderr) console.log("This tool run saved no output.");
+  } else if (command === "goals" && ["list", "add", "remove", "edit", "save"].includes(args[0])) {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    const [action, ...rest] = args;
+    if (action === "edit") {
+      const { plan } = await client.goalPlan(projectId);
+      const target = await writeGoalsFile(directory, plan);
+      console.log(`Wrote ${plan.goals.length} goal(s) to ${path.relative(directory, target).split(path.sep).join("/")}. Edit it, then run tapeo goals save.`);
+    } else if (action === "save") {
+      const plan = await readGoalsFile(directory);
+      const saved = await client.saveGoalPlan(projectId, plan);
+      console.log(`Saved ${saved.plan.goals.length} goal(s). The goal report is out of date until the next run measures them.`);
+    } else {
+      const { plan } = await client.goalPlan(projectId);
+      if (action === "list") {
+        for (const goal of plan.goals) console.log(`  ${describeGoal(goal)}`);
+        if (!plan.goals.length) console.log("No goals yet. Add one with tapeo goals add, or run the workflow to plan them.");
+      } else if (action === "add") {
+        const goal = goalFromArguments(rest, typeof flags.note === "string" ? flags.note : undefined);
+        if (plan.goals.some((item) => item.key === goal.key)) throw new Error(`A goal for ${goal.key} exists. Remove it first, or edit it with tapeo goals edit.`);
+        await client.saveGoalPlan(projectId, { ...plan, goals: [...plan.goals, goal] });
+        console.log(`Added: ${describeGoal(goal)}.`);
+      } else {
+        if (!rest[0]) throw new Error("Usage: tapeo goals remove <key>");
+        const kept = plan.goals.filter((goal) => goal.key !== rest[0] && goal.id !== rest[0]);
+        if (kept.length === plan.goals.length) throw new Error(`No goal named ${rest[0]}. List them with tapeo goals list.`);
+        await client.saveGoalPlan(projectId, { ...plan, goals: kept });
+        console.log(`Removed ${rest[0]}.`);
+      }
+    }
   } else if (command === "goals") {
     const projectId = await projectIdFor(client, args[0]);
     console.log(describeGoals((await client.goals(projectId)).report));
+  } else if (command === "lock" || command === "unlock") {
+    const projectId = await projectIdFor(client);
+    if (!args.length) throw new Error(`Usage: tapeo ${command} <path...>`);
+    for (const file of args) {
+      await client.lockFile(projectId, file, command === "lock");
+      console.log(command === "lock" ? `Protected ${file}: AI repairs become suggestions you review.` : `Unprotected ${file}: the AI Engineer may repair it during runs.`);
+    }
+  } else if (command === "checkpoints") {
+    const projectId = await projectIdFor(client);
+    const { checkpoints } = await client.checkpoints(projectId);
+    for (const item of checkpoints) console.log(`  ${String(item.version).padStart(3)}  ${new Date(item.createdAt).toLocaleString()}  ${item.note ?? ""}`);
+    if (!checkpoints.length) console.log("No checkpoints yet. Save one with tapeo checkpoint \"name\".");
+  } else if (command === "checkpoint") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    const changes = await localChanges(directory).catch(() => null);
+    if (changes && (changes.modified.length || changes.added.length)) console.log(`Note: the checkpoint holds the files saved in Tapeo; ${changes.modified.length + changes.added.length} local change(s) are not pushed yet.`);
+    const { checkpoint } = await client.saveCheckpoint(projectId, args.join(" ") || undefined);
+    console.log(`Saved checkpoint ${checkpoint.version}: ${checkpoint.note}.`);
+  } else if (command === "restore") {
+    const projectId = await projectIdFor(client);
+    const version = Number(args[0]);
+    if (!Number.isSafeInteger(version) || version < 1 || args.length < 2) throw new Error("Usage: tapeo restore <checkpoint> <path...> (list checkpoints with tapeo checkpoints)");
+    for (const item of await restoreFromCheckpoint(client, projectId, process.cwd(), version, args.slice(1))) console.log(`Restored ${item.path} from checkpoint ${version} (${item.sha256.slice(0, 12)}).`);
+  } else if (command === "sim") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    const changes = await localChanges(directory).catch(() => null);
+    if (changes && (changes.modified.length || changes.added.length)) console.log(`Note: this simulates the files saved in Tapeo; ${changes.modified.length + changes.added.length} local change(s) are not pushed yet.`);
+    console.log("Simulating…");
+    const result = await client.simulate(projectId, typeof flags.testbench === "string" ? flags.testbench : undefined);
+    console.log(`${result.status === "passed" ? "✓" : "✗"} ${result.message}${result.testbenchPath ? ` (${result.testbenchPath})` : ""}`);
+    for (const metric of result.metrics ?? []) console.log(`  ${metric.key} = ${metric.value} ${metric.unit}`);
+    if (result.status !== "passed") console.log(String([result.stdout, result.stderr].filter(Boolean).join("\n")).split("\n").filter(Boolean).slice(-15).join("\n"));
+    if (result.hasWaveform) console.log(`Waveform: tapeo wave ${result.runId}`);
+    if (result.status !== "passed") process.exitCode = 1;
+  } else if (command === "manifest") {
+    const projectId = await projectIdFor(client);
+    const { manifest } = await client.manifest(projectId);
+    for (const line of describeManifest(manifest)) console.log(line);
+    if (manifest?.errors.length) process.exitCode = 1;
+  } else if (command === "sims") {
+    const projectId = await projectIdFor(client);
+    const { simulations } = await client.simulations(projectId);
+    for (const run of simulations) console.log(`  ${run.runId}  ${run.status.padEnd(7)} ${new Date(run.createdAt).toLocaleString()}  ${run.message}${run.hasWaveform ? " · waveform" : ""}`);
+    if (!simulations.length) console.log("No simulations yet. Run tapeo sim.");
+  } else if (command === "wave") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    let runId = args[0];
+    if (!runId) {
+      runId = (await client.simulations(projectId)).simulations.find((run) => run.hasWaveform)?.runId;
+      if (!runId) throw new Error("No simulation with a waveform yet. Run tapeo sim.");
+    }
+    const file = await saveWaveform(client, projectId, runId, directory, typeof flags.out === "string" ? flags.out : undefined);
+    console.log(`Saved the waveform to ${path.relative(directory, file).split(path.sep).join("/") || file}.`);
+    if (flags.open) {
+      const viewer = ["surfer", "gtkwave"].find((name) => spawnSync(name, ["--version"], { stdio: "ignore" }).status === 0);
+      if (!viewer) console.log("Install Surfer (https://surfer-project.org) or GTKWave to open it, or open it in the web workspace.");
+      else { spawn(viewer, [file], { detached: true, stdio: "ignore" }).unref(); console.log(`Opened it in ${viewer}.`); }
+    }
+  } else if (command === "target" || command === "process") {
+    const projectId = await projectIdFor(client);
+    const describe = (settings, choices) => {
+      const board = choices.boards.find((item) => item.id === settings.fpgaBoard);
+      const platform = choices.platforms.find((item) => item.id === settings.technologyPlatform);
+      return `Target: ${choices.targets.find((item) => item.id === settings.target)?.label ?? settings.target}${board && settings.target.startsWith("fpga") ? ` · ${board.label}${settings.fpgaClockMhz ? ` · ${settings.fpgaClockMhz} MHz design clock (PLL)` : ` · ${board.clockMhz} MHz board clock`}` : ""}${settings.target === "asic" || settings.target === "fpga-asic" ? ` · process ${platform?.label ?? (settings.technology || "not chosen")}` : ""}`;
+    };
+    const { settings, choices } = await client.settings(projectId);
+    if (!args.length) {
+      console.log(describe(settings, choices));
+      if (command === "target") {
+        console.log(`Targets: ${choices.targets.map((item) => item.id).join(", ")}`);
+        console.log(`Boards:\n${choices.boards.map((item) => `  ${item.id.padEnd(12)} ${item.label} · ${item.part} · ${item.clockMhz} MHz (PLL ${item.pllMinMhz}-${item.pllMaxMhz} MHz)`).join("\n")}`);
+      } else {
+        console.log(`Processes:\n${choices.platforms.map((item) => `  ${item.id.padEnd(14)} ${item.label}${item.oneClick ? "" : ` · ${item.blocker ?? "manual setup"}`}`).join("\n")}`);
+      }
+    } else {
+      const change = command === "target"
+        ? { target: args[0], ...(typeof flags.board === "string" ? { fpgaBoard: flags.board } : {}), ...(typeof flags.clock === "string" ? { fpgaClockMhz: Number(flags.clock) } : {}) }
+        : { technologyPlatform: args[0] };
+      const saved = await client.saveSettings(projectId, change);
+      console.log(`Saved. ${describe(saved.settings, choices)}`);
+      if (saved.removed?.length) {
+        const local = await removeLocalOutputs(process.cwd(), saved.removed);
+        console.log(`Removed ${saved.removed.length} file(s) from the old process: ${saved.removed.join(", ")}${local.length ? ` (and ${local.length} local cop${local.length === 1 ? "y" : "ies"})` : ""}. Run the workflow to rebuild them for the new process.`);
+      }
+      else console.log("Run the workflow to build for the new settings (tapeo run --watch).");
+    }
   } else if (command === "cancel") {
     const projectId = await projectIdFor(client);
     let runId = args[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tapeo-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Terminal client for Tapeo: edit hardware projects locally, run the server's EDA workflow, read results, and work with the AI Architect and Engineer.",
   "keywords": [
     "tapeo",

package/shared/api.mjs

@@ -5,7 +5,7 @@ export class TapeoApiError extends Error {
 }
 
 /** 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 WORKFLOW_STAGE_KEYS = ["lint", "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. */
@@ -78,7 +78,8 @@ export function normalizeServerUrl(value) {
   return url.origin;
 }
 
-async function send(serverUrl, method, path, { token, body, raw = false } = {}) {
+async function send(serverUrl, method, path, { token, body, raw = false, timeoutMs } = {}) {
+  const limit = timeoutMs ?? (raw ? 300_000 : 20_000);
   let response;
   try {
     response = await fetch(new URL(`/api/client/v1${path}`, serverUrl), {
@@ -86,10 +87,10 @@ async function send(serverUrl, method, path, { token, body, raw = false } = {})
       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)
+      signal: AbortSignal.timeout(limit)
     });
   } catch (error) {
-    const detail = error?.name === "TimeoutError" ? `The server did not answer within ${raw ? 300 : 20} seconds.` : "Could not reach the server.";
+    const detail = error?.name === "TimeoutError" ? `The server did not answer within ${Math.round(limit / 1000)} 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;
@@ -136,7 +137,7 @@ export class TapeoClient {
     this.token = token;
   }
 
-  request(method, path, body) { return send(this.serverUrl, method, path, { token: this.token, body }); }
+  request(method, path, body, options = {}) { return send(this.serverUrl, method, path, { token: this.token, body, ...options }); }
   /** 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 });
@@ -196,6 +197,37 @@ export class TapeoClient {
   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`); }
+
+  // ---- Project tools that were browser-only (lib/client-delegate.ts on the server) ----
+  /** Older servers have no route for these; say so plainly instead of a bare 404/405. */
+  async newerRequest(feature, method, path, body, options) {
+    try {
+      return await this.request(method, path, body, options);
+    } catch (error) {
+      if ((error?.status === 404 && !error?.data?.error) || error?.status === 405) throw new TapeoApiError(`This Tapeo server does not support ${feature} from local clients yet. Use the web workspace: ${this.serverUrl}`, error.status);
+      throw error;
+    }
+  }
+  /** Protect a file from automatic AI repairs, or allow them. */
+  lockFile(id, path, locked) { return this.newerRequest("protecting files", "PATCH", `/projects/${encodeURIComponent(id)}/files/lock`, { path, locked }); }
+  checkpoints(id) { return this.newerRequest("checkpoints", "GET", `/projects/${encodeURIComponent(id)}/checkpoints`); }
+  saveCheckpoint(id, note) { return this.newerRequest("checkpoints", "POST", `/projects/${encodeURIComponent(id)}/checkpoints`, { note }); }
+  checkpoint(id, version) { return this.newerRequest("checkpoints", "GET", `/projects/${encodeURIComponent(id)}/checkpoints/${encodeURIComponent(version)}`); }
+  checkpointFile(id, version, path) { return this.newerRequest("checkpoints", "GET", `/projects/${encodeURIComponent(id)}/checkpoints/${encodeURIComponent(version)}?path=${encodeURIComponent(path)}`); }
+  /** Simulate the saved files now, without a workflow run. */
+  /** A simulation can take minutes (a large design, or the runner starting), so it may wait 5 minutes. */
+  simulate(id, testbench) { return this.newerRequest("quick simulation", "POST", `/projects/${encodeURIComponent(id)}/simulations`, testbench ? { testbench } : {}, { timeoutMs: 300_000 }); }
+  /** What tapeo.json resolves to on the saved files (null when there is none). */
+  manifest(id) { return this.newerRequest("project manifests", "GET", `/projects/${encodeURIComponent(id)}/manifest`); }
+  simulations(id) { return this.newerRequest("quick simulation", "GET", `/projects/${encodeURIComponent(id)}/simulations`); }
+  async waveform(id, runId) {
+    const response = await send(this.serverUrl, "GET", `/projects/${encodeURIComponent(id)}/simulations/${encodeURIComponent(runId)}/waveform`, { token: this.token, raw: true });
+    return Buffer.from(await response.arrayBuffer());
+  }
+  goalPlan(id) { return this.newerRequest("editing goals", "GET", `/projects/${encodeURIComponent(id)}/goals?plan=1`); }
+  saveGoalPlan(id, evaluationPlan) { return this.newerRequest("editing goals", "PUT", `/projects/${encodeURIComponent(id)}/goals`, { evaluationPlan }); }
+  settings(id) { return this.newerRequest("project settings", "GET", `/projects/${encodeURIComponent(id)}/settings`); }
+  saveSettings(id, settings) { return this.newerRequest("project settings", "PUT", `/projects/${encodeURIComponent(id)}/settings`, settings); }
   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)}`); }

package/shared/problems.mjs

@@ -10,9 +10,26 @@
  * 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.
  */
+/**
+ * Verilator warnings that are style rather than likely bugs, shown as notes.
+ * Mirrors LINT_STYLE_CODES in lib/rtl-lint.ts (tests/client-ai.test.ts keeps them equal).
+ */
+export const VERILATOR_STYLE_CODES = new Set([
+  "UNUSED", "UNUSEDSIGNAL", "UNUSEDPARAM", "UNUSEDGENVAR", "DECLFILENAME", "PINCONNECTEMPTY", "PINNOCONNECT", "VARHIDDEN", "GENUNNAMED",
+  "WIDTHEXPAND", "EOFNEWLINE", "PROCASSINIT", "LITENDIAN", "ASSIGNDLY", "INCABSPATH", "IMPORTSTAR", "DEFPARAM", "STMTDLY", "BLKLOOPINIT", "SYMRSVDWORD", "TIMESCALEMOD", "REALCVT"
+]);
+
+/** Verilator severity: errors; a warning that loses bits or is otherwise a likely bug; or a style note (as lib/rtl-lint.ts classifies them). */
+function verilatorSeverity(kind, code, message) {
+  if (kind === "Error") return "error";
+  const width = code === "WIDTH" ? /expects (\d+) bits?.*generates (\d+) bits?/i.exec(message) : null;
+  const effective = width ? (Number(width[2]) > Number(width[1]) ? "WIDTHTRUNC" : "WIDTHEXPAND") : code;
+  return VERILATOR_STYLE_CODES.has(effective) ? "note" : "warning";
+}
+
 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] }) },
+  { regex: /%(Error|Warning)(?:-([A-Z0-9_]+))?:\s*([^\s:]+):(\d+):(?:(\d+):)?\s*(.*)$/, map: (m) => ({ severity: verilatorSeverity(m[1], m[2] ?? "", m[6]), path: m[3], line: m[4], column: m[5], message: m[6] }) },
   // 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"
@@ -46,8 +63,8 @@ export function extractProblems(text, projectPaths, { tool = "", includeWarnings
       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 severity = found.severity === "note" ? "note" : /warn/i.test(found.severity) ? "warning" : "error";
+      if (severity !== "error" && !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}`;
@@ -61,7 +78,8 @@ export function extractProblems(text, projectPaths, { tool = "", includeWarnings
 
 /**
  * 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.
+ * from the tool runs that failed, or from lint (whose warnings are its result).
+ * Returns them grouped by file order.
  */
 export async function collectRunProblems(client, projectId, runId, projectPaths) {
   const { toolRuns = [] } = await client.runDetail(projectId, runId);
@@ -69,7 +87,7 @@ export async function collectRunProblems(client, projectId, runId, projectPaths)
   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 }));
+    problems.push(...extractProblems(`${toolRun.summary ?? ""}\n${toolRun.stdout ?? ""}\n${toolRun.stderr ?? ""}`, projectPaths, { tool: toolRun.tool, includeWarnings: failed || /\blint\b/i.test(toolRun.tool ?? tool.tool ?? "") }));
   }
   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; })

package/shared/project-tools.mjs

@@ -0,0 +1,113 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { localTarget, pushProjectFile, safeSourcePath } from "./sync.mjs";
+
+/**
+ * Project tools shared by the CLI and VS Code that used to need the browser:
+ * restoring files from a checkpoint, editing goals as a file, and saving a
+ * simulation's waveform. Everything goes through the token API.
+ */
+
+/** Put a checkpoint's version of each file back: written locally, then saved in Tapeo as your edit (like Restore in Project history). */
+export async function restoreFromCheckpoint(client, projectId, directory, version, paths) {
+  const restored = [];
+  for (const projectPath of paths) {
+    if (!safeSourcePath(projectPath)) throw new Error(`${projectPath} cannot be restored: tool outputs (generated/, signoff/) are rebuilt by runs, not restored.`);
+    const { file } = await client.checkpointFile(projectId, version, projectPath);
+    const target = await localTarget(directory, projectPath);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, file.content, "utf8");
+    const saved = await pushProjectFile(client, directory, projectPath);
+    restored.push({ path: projectPath, sha256: saved.sha256 });
+  }
+  return restored;
+}
+
+export const GOALS_FILE = ".tapeo/goals.json";
+
+/** The goal plan as an editable file (.tapeo/goals.json, never pushed as a project file). */
+export async function writeGoalsFile(directory, plan) {
+  const target = path.join(directory, GOALS_FILE);
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+  return target;
+}
+
+export async function readGoalsFile(directory) {
+  let text;
+  try { text = await readFile(path.join(directory, GOALS_FILE), "utf8"); }
+  catch (error) { if (error?.code === "ENOENT") throw new Error(`No ${GOALS_FILE} yet. Run tapeo goals edit first.`); throw error; }
+  let plan;
+  try { plan = JSON.parse(text); } catch (error) { throw new Error(`${GOALS_FILE} is not valid JSON: ${error.message}`); }
+  if (!plan || !Array.isArray(plan.goals)) throw new Error(`${GOALS_FILE} must hold { "schemaVersion": 1, "goals": [ ... ] }.`);
+  return { schemaVersion: 1, ...plan };
+}
+
+const COMPARISONS = { "<=": "less-than-or-equal", ">=": "greater-than-or-equal", "=": "equal", "==": "equal" };
+const SYMBOLS = { "less-than-or-equal": "≤", "greater-than-or-equal": "≥", equal: "=", between: "between" };
+
+/**
+ * A goal from the command line: `<key> <= 5 ns`, `<key> >= 50 MHz`, `<key> = 1 result`,
+ * or `<key> between 10..20 %`. Its measurement is planned by the next full workflow run.
+ */
+export function goalFromArguments([key, operator, target, unit = "result"], note) {
+  if (!key || !/^[A-Za-z0-9_.-]{1,80}$/.test(key)) throw new Error("Name the goal's measurement, e.g. tapeo goals add lint_error_count \"<=\" 0 issues");
+  const id = `${key}-${Date.now().toString(36)}`;
+  if (operator === "between") {
+    const match = /^(-?\d+(?:\.\d+)?)\.\.(-?\d+(?:\.\d+)?)$/.exec(target ?? "");
+    if (!match || Number(match[1]) > Number(match[2])) throw new Error("A range is written low..high, e.g. tapeo goals add fpga_logic_utilization between 0..80 %");
+    return { id, key, comparison: "between", target: Number(match[1]), upperTarget: Number(match[2]), unit, source: "user", ...(note ? { note } : {}) };
+  }
+  const comparison = COMPARISONS[operator];
+  if (!comparison) throw new Error(`Use <=, >=, =, or between (got ${operator ?? "nothing"}). Quote < and > in a shell: "<=".`);
+  const number = Number(target);
+  if (target === undefined || target === "") throw new Error("Give the goal's target value.");
+  return { id, key, comparison, target: Number.isFinite(number) ? number : target, unit, source: "user", ...(note ? { note } : {}) };
+}
+
+export function describeGoal(goal) {
+  const target = goal.comparison === "between" ? `${goal.target}..${goal.upperTarget}` : goal.target;
+  return `${goal.key} ${SYMBOLS[goal.comparison] ?? goal.comparison} ${target} ${goal.unit}${goal.verification?.steps?.length ? ` · measured by ${goal.verification.steps.map((step) => step.tool || step.adapterId).join(", ")}` : " · measurement planned on the next full run"}`;
+}
+
+/** A resolved tapeo.json as readable lines (tapeo manifest, Tapeo: Show Project Manifest). */
+export function describeManifest(manifest) {
+  if (!manifest) return ["This project has no tapeo.json: Tapeo finds the design, top, and testbench by convention."];
+  const lines = [];
+  if (manifest.errors.length) lines.push("tapeo.json has problems that stop the stages:", ...manifest.errors.map((error) => `  ✗ ${error}`));
+  else {
+    lines.push(`Design sources (${manifest.sources.length}, in compile order):`, ...manifest.sources.map((source) => `  ${source}`));
+    lines.push(`Top: ${manifest.top ?? "found by Tapeo (the module nothing else instantiates)"}`);
+    if (manifest.includeDirs.length) lines.push(`Include folders: ${manifest.includeDirs.join(", ")}`);
+    if (manifest.defines.length) lines.push(`Defines: ${manifest.defines.join(", ")}`);
+    if (manifest.verification.length) lines.push(`Shared verification files: ${manifest.verification.join(", ")}`);
+    lines.push(manifest.testbenches.length ? `Testbenches: ${manifest.testbenches.map((bench) => `${bench.name} (${bench.files.join(", ")}${bench.top ? `, top ${bench.top}` : ""})`).join("; ")}` : "Testbench: found by name (tb/, *_tb.sv, …)");
+    if (manifest.constraints) lines.push(`Constraints: ${manifest.constraints}`);
+  }
+  for (const warning of manifest.warnings) lines.push(`  ! ${warning}`);
+  return lines;
+}
+
+/** Save a simulation's waveform under .tapeo/waveforms/ (local only). */
+export async function saveWaveform(client, projectId, runId, directory, destination) {
+  const bytes = await client.waveform(projectId, runId);
+  const target = destination ? path.resolve(directory, destination) : path.join(directory, ".tapeo", "waveforms", `${runId}.vcd`);
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, bytes);
+  return target;
+}
+
+/** Delete local copies of tool outputs the server removed (a process change); only generated/ and signoff/ paths. */
+export async function removeLocalOutputs(directory, paths) {
+  const removed = [];
+  for (const projectPath of paths) {
+    if (!/^(?:generated|signoff)\//.test(projectPath) || projectPath.split("/").includes("..")) continue;
+    const target = await localTarget(directory, projectPath);
+    try {
+      await chmod(target, 0o644);
+      await rm(target);
+      removed.push(projectPath);
+    } catch (error) { if (error?.code !== "ENOENT") throw error; }
+  }
+  return removed;
+}

package/shared/sync.mjs

@@ -271,12 +271,12 @@ export async function downloadFile(client, projectId, projectPath, destination)
 }
 
 /** Design files a new design can start from: the browser's upload types and limits (20 files, 300 KB). */
-export const DESIGN_EXTENSIONS = [".v", ".sv", ".vh", ".svh", ".vhd", ".vhdl", ".sdc", ".tcl", ".hex", ".mem"];
+export const DESIGN_EXTENSIONS = [".v", ".sv", ".vh", ".svh", ".vhd", ".vhdl", ".sdc", ".tcl", ".hex", ".mem", ".f"];
 export async function designFilesFrom(directory, { maxFiles = 20, maxBytes = 300 * 1024 } = {}) {
   const files = [];
   let total = 0;
   for (const candidate of await sourceFiles(path.resolve(directory))) {
-    if (!DESIGN_EXTENSIONS.includes(path.extname(candidate))) continue;
+    if (!DESIGN_EXTENSIONS.includes(path.extname(candidate)) && candidate !== "tapeo.json") continue;
     const content = await readFile(await localTarget(directory, candidate), "utf8");
     total += Buffer.byteLength(content, "utf8");
     files.push({ path: candidate, content });