tapeo-cli 0.3.0 → 0.5.0

package/README.md

@@ -1,27 +1,93 @@
-# Tapeo local clients (developer preview)
+<p align="center">
+  <img src="https://tapeo.net/icons/icon-512.png" alt="Tapeo" width="96" height="96">
+</p>
 
-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`. They are a developer preview: installed from this repository. Publishing on npm (`tapeo-cli`) and the VS Code Marketplace (`tapeo.tapeo-vscode`) is prepared but not done; see [`docs/RELEASING.md`](../docs/RELEASING.md).
+<h1 align="center">Tapeo for your terminal and VS Code</h1>
+
+<p align="center">Design, run, and fix chips from your own shell or editor, on the same projects as <a href="https://tapeo.net">tapeo.net</a>.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/tapeo-cli"><img src="https://img.shields.io/npm/v/tapeo-cli?label=tapeo-cli&logo=npm&color=cb3837" alt="tapeo-cli on npm"></a>
+  <a href="https://marketplace.visualstudio.com/items?itemName=tapeo.tapeo-vscode"><img src="https://img.shields.io/badge/VS%20Code%20Marketplace-Tapeo-0078d4?logo=visualstudiocode&logoColor=white" alt="Tapeo for VS Code"></a>
+  <img src="https://img.shields.io/node/v/tapeo-cli?logo=nodedotjs&logoColor=white&color=5fa04e" alt="Node.js version">
+  <a href="https://tapeo.net/docs#local-clients"><img src="https://img.shields.io/badge/docs-tapeo.net-e8914a" alt="Documentation"></a>
+</p>
+
+## Quick start
+
+```sh
+npm install -g tapeo-cli
+tapeo login                                   # approve this device in your browser
+tapeo new "A 4-bit counter with enable" ./counter   # design, build, and pull the files
+cd counter && tapeo show                         # stage results of that build
+# edit rtl/…, then: tapeo push --all && tapeo run --watch
+```
+
+In VS Code, install **Tapeo** from the Extensions view and run **Tapeo: Connect to Server**.
+
+| Feature | What you get |
+|---|---|
+| 🧭 **Design with the Architect** | `tapeo new` asks clarifying questions, proposes design options, shows the build plan, and builds. |
+| 🔁 **Edit → run → results** | Push your files, run the full flow or one stage, and read stage results, tool logs, and goals. |
+| 🎯 **Errors on the right line** | `tapeo problems`, or the VS Code Problems panel, points at the line a tool complained about. |
+| 🛠️ **AI Engineer** | `tapeo ask` streams an answer; review the proposed diff and `tapeo apply` it locally. |
+| 🔒 **Safe sync** | Every push names the version it was based on; your local edits are never overwritten. |
+
+## 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.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.
 
-The server needs migrations `0008_client_tokens` and `0009_device_authorization` (`npx prisma migrate deploy`; the Docker deployment applies them on start).
+Self-hosted servers need migrations `0008_client_tokens` and `0009_device_authorization` (`npx prisma migrate deploy`; the Docker deployment applies them on start). Maintainers: releasing is described in `docs/RELEASING.md` in the Tapeo repository.
 
 ## Sign in
 
 ```sh
-npm install -g ./clients          # or: npm run tapeo -- <command> from the repository root
-                                  # once published: npm install -g tapeo-cli
+npm install -g tapeo-cli          # from source: npm install -g ./clients, or npm run tapeo -- <command>
 tapeo login                       # https://tapeo.net; or: tapeo login https://your-own-server
 ```
 
 `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
 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
@@ -42,6 +108,8 @@ tapeo open                             # the project's web address
 tapeo --version                        # this client's version (tapeo help lists every command)
 ```
 
+`tapeo delete` removes a project on the server for good, like the delete button in the browser's project list: its files, checkpoints, runs, layouts, and Engineer history (a running workflow stops). In a linked folder it deletes that folder's project unless you name another. You confirm by typing the project name (`--yes` skips this, for scripts). Local files stay, and the folder is no longer linked.
+
 ### AI
 
 ```sh
@@ -54,16 +122,47 @@ 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.
 
+### FPGA boards
+
+For a project whose target is an FPGA board, or an FPGA board and a chip (the Architect asks where a design runs; you can change it on the Workflow tab), the workflow simulates the RTL, then builds and checks a bitstream for the board on the server. Supported boards: Sipeed Tang Nano 9K and Tang Nano 20K, 1BitSquared iCEBreaker, and Radiona ULX3S (12F and 85F). A design clock other than the board clock gets a PLL generated by the toolchain's own calculator.
+
+```sh
+tapeo run --watch        # simulate, build the bitstream, report logic use and Fmax
+tapeo flash              # download the bitstream and program the connected board
+tapeo flash --flash      # keep it after power-off (Tang Nano and ULX3S otherwise load to SRAM)
+tapeo flash --board icebreaker   # when bitstreams exist for several boards
+tapeo monitor            # the board's serial (UART) output; type a line to send it
+tapeo monitor --port /dev/cu.usbserial-1101 --baud 9600
+```
+
+`tapeo flash` runs the open-source `openFPGALoader` on your computer and tells you how to install it if it is missing (`brew install openfpgaloader` on macOS, `sudo apt install openfpgaloader` on Debian/Ubuntu, or OSS CAD Suite elsewhere). `TAPEO_OPENFPGALOADER` points to it when it is not on your PATH. The bitstream is saved read-only under `generated/fpga/<board>/`.
+
+`tapeo monitor` needs no sign-in and works on macOS and Linux: it finds the USB serial port (name one with `--port` when there are several; a Tang Nano shows two and its serial link is usually the second) and uses 115200 baud unless you pass `--baud`. On Linux you may need to be in the `dialout` group. On Windows, use the **Serial monitor** on the project's Workflow tab in Chrome or Edge.
+
 ## VS Code
 
 Run `npm run build:vscode`, open `clients/vscode` in VS Code, and press F5; or run `npm run package:vscode` and install `clients/vscode/tapeo-vscode.vsix` with **Extensions: Install from VSIX...**. In the Command Palette:
@@ -75,6 +174,15 @@ Run `npm run build:vscode`, open `clients/vscode` in VS Code, and press F5; or r
 - **Show Workflow Runs**, **Show Run Details**, **Open a Tool Log**, **Show Goal Results**, **Cancel Workflow**, **Open Project in Browser**.
 - **New Design with the Architect** (in an empty folder): the Architect's questions appear as quick picks with "Not sure — you choose", then the design options and the build plan; **Build** creates the project, starts the first build, and pulls the generated files when it ends.
 - **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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import path from "node:path";
@@ -8,6 +8,9 @@ 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";
 
 const configPath = path.join(homedir(), ".config", "tapeo", "client.json");
@@ -15,7 +18,7 @@ const clientVersion = JSON.parse(await readFile(new URL("../package.json", impor
 setClientIdentity("tapeo-cli", clientVersion);
 
 function usage() {
-  console.log(`Tapeo terminal client (developer preview)
+  console.log(`Tapeo terminal client
 
 Sign in
   tapeo login [server-url]        Sign in through your browser (approve this device there);
@@ -27,6 +30,9 @@ Sign in
 Projects and files
   tapeo projects                  List your projects
   tapeo create <name> [dir]       Create an empty project and bind a local folder
+  tapeo delete [project-id]       Delete a project on the server for good (this folder's
+                                  project by default; asks you to type its name, --yes
+                                  skips that); local files are kept
   tapeo pull <project-id> [dir]   Pull source files without overwriting local edits
   tapeo pull --outputs            Also download tool outputs (generated/, signoff/) read-only
   tapeo status                    What changed locally, and the latest run
@@ -34,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
@@ -45,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]
@@ -54,10 +76,29 @@ 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
 
-Stages: simulation, synthesis, timing, physical, post-route-timing, drc, extraction, erc, lvs.
+FPGA boards
+  tapeo flash [--board <id>] [--flash]
+                                  Download the bitstream and program the connected board with
+                                  openFPGALoader (--flash: keep it after power-off on boards
+                                  that load to SRAM by default, such as the Tang Nano 9K)
+  tapeo monitor [--port <path>] [--baud <n>]
+                                  Show the board's serial (UART) output and send what you
+                                  type; default 115200 baud (macOS and Linux)
+
+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).`);
 }
 
@@ -121,7 +162,7 @@ async function configuredClient() {
   catch (error) { if (error.code !== "ENOENT") throw error; }
   const serverUrl = process.env.TAPEO_URL || saved.serverUrl;
   const token = process.env.TAPEO_TOKEN || saved.token;
-  if (!serverUrl || !token) throw new Error("Run `tapeo login <server-url>` first, or set TAPEO_URL and TAPEO_TOKEN.");
+  if (!serverUrl || !token) throw new Error("Run `tapeo login` first (or `tapeo login <server-url>` for your own server), or set TAPEO_URL and TAPEO_TOKEN.");
   return new TapeoClient(serverUrl, token);
 }
 
@@ -283,8 +324,29 @@ async function main() {
     console.log("Signed out on this computer. Revoke the token on the Account page to end its access everywhere.");
     return;
   }
+  // The serial monitor talks only to the board, so it needs no sign-in.
+  if (command === "monitor") {
+    const { flags } = parseArguments(rest, ["port", "baud"]);
+    const port = chooseSerialPort(serialCandidates(), typeof flags.port === "string" ? flags.port : undefined);
+    const baud = parseBaud(flags.baud);
+    const serial = openSerialPort(port, baud);
+    console.error(`Connected to ${port} at ${baud} baud. Type a line and press Enter to send it; Ctrl+C stops.`);
+    serial.input.pipe(process.stdout);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (text) => serial.write(text));
+    await new Promise((resolve) => {
+      const stop = () => { serial.close(); resolve(); };
+      process.once("SIGINT", stop);
+      // Ctrl+D at a keyboard stops; piped input just sends and keeps listening.
+      if (process.stdin.isTTY) process.stdin.once("end", stop);
+      serial.input.once("close", stop);
+      serial.input.once("error", (error) => { console.error(`The serial port closed: ${error.message}`); stop(); });
+    });
+    process.stdin.destroy();
+    return;
+  }
   const client = await configuredClient();
-  const { flags, positional: args } = parseArguments(rest, ["stage", "from", "option", "limit"]);
+  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") {
@@ -325,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]);
@@ -332,11 +413,30 @@ 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}`);
     if (!projects.length) console.log("No projects yet. Run tapeo create <name> [directory].");
+  } else if (command === "delete") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client, args[0]);
+    const { project } = await client.project(projectId);
+    if (!flags.yes) {
+      if (!process.stdin.isTTY) throw new Error(`Deleting "${project.name}" cannot be undone. Confirm with --yes.`);
+      const prompt = prompter();
+      try {
+        console.log(`This deletes "${project.name}" (${project.id}) on ${client.serverUrl} for good: its files, checkpoints, runs, layouts, and Engineer history. A running workflow stops. Local files are kept.`);
+        const typed = (await prompt.ask("Type the project name to confirm: ")).trim();
+        if (typed !== project.name.trim()) { console.log("The name did not match. Nothing was deleted."); return; }
+      } finally { prompt.close(); }
+    }
+    await client.deleteProject(projectId);
+    // A folder bound to the deleted project is unbound, so later commands do not point at it.
+    const bound = await readState(directory).catch(() => null);
+    if (bound?.projectId === projectId && bound.serverUrl === client.serverUrl) await rm(path.join(directory, ".tapeo"), { recursive: true, force: true });
+    console.log(`Deleted "${project.name}".${bound?.projectId === projectId ? " This folder is no longer linked to a Tapeo project; its files are unchanged." : ""}`);
   } else if (command === "create") {
     if (!args[0]?.trim()) throw new Error("Usage: tapeo create <name> [directory]");
     const directory = path.resolve(args[1] || ".");
@@ -422,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];
@@ -435,6 +654,18 @@ async function main() {
     }
     const { run } = await client.cancelRun(projectId, runId);
     console.log(`Cancelled ${run.id}. A tool step already running finishes first; finished stages keep their results.`);
+  } else if (command === "flash") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    const { files } = await client.project(projectId);
+    const bitstream = chooseBitstream(files, flags.board);
+    const executable = openFpgaLoaderExecutable();
+    if (!openFpgaLoaderAvailable(executable)) throw new Error(OPENFPGALOADER_INSTALL);
+    const local = await downloadBitstream(client, projectId, bitstream, directory);
+    console.log(`Programming the ${bitstream.label} with ${path.relative(directory, local)}${flags.flash ? " (writing to flash)" : ""}…`);
+    const result = spawnSync(executable, flashArguments(bitstream, local, { flash: Boolean(flags.flash) }), { stdio: "inherit" });
+    if (result.error || result.status !== 0) throw new Error("openFPGALoader could not program the board. Check the USB cable and that no other program is using the board; its messages are above.");
+    console.log(`Programmed the ${bitstream.label}.`);
   } else if (command === "open") {
     const projectId = await projectIdFor(client, args[0]);
     console.log(`${client.serverUrl}/?project=${encodeURIComponent(projectId)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tapeo-cli",
-  "version": "0.3.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 });
@@ -182,10 +183,51 @@ export class TapeoClient {
   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`); }
+
+  // ---- 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/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

@@ -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/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/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 });