tapeo-cli 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2026 Tapeo (https://tapeo.net). All rights reserved.
+
+This software is proprietary. You may install and use it to work with Tapeo
+services. You may not copy, modify, redistribute, sublicense, or create
+derivative works of it, except as permitted by law, without written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://tapeo.net/icons/icon-512.png" alt="Tapeo" width="96" height="96">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<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.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).
+
+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.
+
+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 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.
+
+## 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)
+cd ./my-sensor
+tapeo status                           # what changed locally, and the latest run
+tapeo push --all                       # push every modified and new source file
+tapeo run --watch                      # full run; follow it, then show results and goals
+tapeo run --stage drc                  # rerun one stage on the saved files
+tapeo run --from synthesis             # rerun a stage and every later one
+tapeo runs                             # recent runs and their status
+tapeo watch                            # follow the latest run until it ends, then show results
+tapeo show                             # stage results, AI changes, tool runs of the latest run
+tapeo logs TOOL_RUN_ID                 # a tool run's saved output (ids from tapeo show)
+tapeo goals                            # the latest goal report
+tapeo cancel                           # cancel the active run
+tapeo pull --outputs                   # also download tool outputs (read-only)
+tapeo download generated/layout/top.openroad.gds
+tapeo rm rtl/old.sv                    # delete on the server and locally
+tapeo mv rtl/a.sv rtl/core/a.sv        # rename
+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
+tapeo new "A sensor that warns when a tank is full" ./tank   # design with the Architect, then build
+tapeo new "Wrap my FIFO" . --from-files                        # start from the RTL in this folder
+tapeo ask "Why does the counter not wrap at 15?"                # ask the Engineer (answer streams)
+tapeo proposals                                                 # its proposed changes, as diffs
+tapeo apply              # apply all of them to local files (or: tapeo apply 1 3)
+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 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`.
+
+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:
+
+- **Tapeo: Connect to Server**: sign in with your browser (recommended) or paste a token. The token is kept in VS Code SecretStorage. **Tapeo: Sign Out** removes it.
+- **Create Project** / **Pull Project Files** bind the open folder; **Pull Tool Outputs (read-only)** adds tool outputs.
+- **Show Local Changes**, **Push Current File**, **Push All Changes**, **Delete Current File on the Server**.
+- **Run Workflow** (full run, one stage, or from a stage). The status bar follows the run; when it ends, a notification offers the details, the goals, or the project in the browser.
+- **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.
+- **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).
+
+In a bound folder, the status bar shows the latest run when VS Code starts and follows it if it is still running.
+
+## How files are kept safe
+
+- `.tapeo/state.json` records the project id, the server, and the SHA-256 of each file as last pulled or pushed. It holds no token and is ignored by Git.
+- Pull skips `generated/`, `signoff/`, and files over 2 MB, never overwrites a local edit, and reports conflicts. When both sides changed, the server copy is saved under `.tapeo/conflicts/` for comparison.
+- Push (one file or `--all`) sends each file with the hash it was based on. If the server copy changed meanwhile, that file is refused (HTTP 409), the local edit is kept, and the server copy is saved under `.tapeo/conflicts/`; other files still push. New files are found by source extension (`.sv`, `.v`, `.vhd`, `.sdc`, `.tcl`, `.hex`, `.mem`, `.c`, `.h`, `.S`, `.ld`, and similar) outside `generated/`, `signoff/`, hidden folders, and build folders.
+- Deleting a file locally does not delete it on the server; `tapeo rm` does, and only the version last pulled.
+- Tool outputs (`generated/`, `signoff/`) are read-only: they download with mode 0444 and are never pushed. Outputs over 25 MB (a layout) are listed for `tapeo download`.
+- An expired or revoked sign-in asks you to sign in again; an unreachable server reports a network error or timeout. A run is refused before using a build when no workflow worker is connected. None of these change local files.
+
+## Workflow runs
+
+A run from a local client executes the saved files, including edits just pushed; it never regenerates HDL. It uses the same queue, checkpoints, plan limits, and usage accounting as the browser (`lib/workflow-runs.ts`). Cancelling stops a run before its next stage; a tool step already running finishes first, and finished stages keep their results. A full run still counts as the build it started as.
+
+## Tests
+
+- `tests/client-ai.test.ts`: streamed answers, clarification wording, problem extraction for each tool's format, proposals (apply rules, retry, refusals, discard), design-file limits, the client API, and the real `tapeo` command for `ask`/`proposals`/`apply`/`history`/`problems`/`discard` and `new` (questions, option, plan, build, follow, pull, bound-folder refusal).
+- `npm test` includes `tests/client-workflow.test.ts` (shared client: sign-in, watching, status, push-all, rm/mv, outputs, formatting), `tests/client-sync.test.ts`, and `tests/client-cli.test.ts` (the real `tapeo` command against a fake server, from sign-in to cancel).
+- `npm run test:e2e` checks the server side against a real database: browser device approval, run details, tool logs, goals, cancel (client and browser), raw download, delete with its conflict check, the Engineer and Architect routes' sign-in, validation, and ownership checks, the build plan, and creating a project from a design (with "build" refused, and no run recorded, when no worker is connected). It does not call the AI.
+- `npm run test:vscode` drives a real VS Code Extension Development Host through connect, create, a new design with the Architect (and its refusal in a bound folder), pull, push, push all, run, tool problems in the Problems panel, run details, goals, the Engineer (ask, review diff, apply refused for an unsaved file, apply, push), and conflict, worker, and sign-in failures, against a local fixture server. `TAPEO_VSCODE_VSIX="$PWD/clients/vscode/tapeo-vscode.vsix" npm run test:vscode` repeats it with the packaged extension. VS Code must be installed; `TAPEO_VSCODE_BIN` selects another `code` executable.