cawdev-cli 0.9.0 → 1.0.0-beta

package/README.md

@@ -1,175 +1,8 @@
 # tools
-
-Plain Node, **zero dependencies**, by design (see `CLAUDE.md`): stdio JSON-RPC
+# Cawdev CLI Runner
+Plain Node, **zero dependencies**, by design : stdio JSON-RPC
 and spawning processes are Node's home turf, and a file with no dependencies is
 one you can read before running it against your repositories.
+visit https://cawdev.com to learn more
 
-Everything here reads `CAWDEV_URL`, `CAWDEV_TOKEN` and optionally
-`CAWDEV_PROJECT` from the environment or a `.env` at the repository root —
-**read on every call**, so editing `.env` needs no restart.
-
-Mint a token in the console under **Agent tokens**. It needs `roadmap:write`
-and `changelog:write` on the project you are exporting.
-
-## The generated files
-
-`ROADMAP.md` and `CHANGELOG.md` at the repository root are **exports**. Editing
-them by hand is lost at the next export. Change the entry in the console or
-through MCP, then regenerate:
-
-```sh
-node tools/roadmap/export.mjs cawdev
-node tools/changelog/export.mjs cawdev
-```
-
-Both are byte-stable: the same data produces the same bytes, so a regenerated
-file shows a diff only when the roadmap actually changed. CI proves
-export → import → export is a fixed point.
-
-### Where a section goes in the file
-
-An entry's `section` is a planning decision and lives in the database. The
-**order** the sections appear in is prose layout, and lives beside the exporter
-as `SECTION_ORDER` in `tools/roadmap/export.mjs`. `Considering` and `Declined`
-are not in that list: they are derived from status by `sectionOf`, and always
-come last.
-
-A section that is not in `SECTION_ORDER` is **appended, and named in the note
-the exporter prints** under its per-status counts, along with the number of
-entries it holds. It is a note rather than a failure — a new phase is
-legitimate, and an exporter that refused one would block the release that
-introduced it — but it should not arrive unannounced. Silence is how the list
-fell three sections behind and `"Roadmap"`, the fallback for an entry with no
-section of its own, became a junk drawer holding eight built features (R45).
-
-When you see the note: add the section to `SECTION_ORDER` in the position it
-should read in, or give those entries a section that is already there. Sections
-are renamed, merged and unfiled from the console's **Sections** dialog on the
-roadmap board (R264), and that dialog cannot reach this file: after a rename,
-update `SECTION_ORDER` too, or the note will list the new name.
-
-## `tools/roadmap/import.mjs`
-
-The one-time move from a hand-written `ROADMAP.md` into the platform, and the
-other half of that fixed point.
-
-```sh
-node tools/roadmap/import.mjs cawdev --file ROADMAP.md
-```
-
-It is **idempotent enough to re-run after a partial failure**: entries that
-already exist are updated rather than duplicated. It refuses to start when
-preserving ids is impossible — ids are permanent, and silently renumbering them
-would break every commit message that points at one.
-
-## `roadmap.mjs` (repository root)
-
-```sh
-node roadmap.mjs           # shape: ids unique, statuses legal, required fields present
-node roadmap.mjs --live    # also: SHIPPED versions are real tags, CODING and
-                           # REVIEW branches exist, and the file matches the database
-node roadmap.mjs --live --project cawdev   # when CAWDEV_PROJECT is not set
-```
-
-Both forms run in CI. The shape checks catch what a review forgets — an entry
-that says `CODING` without naming a branch, an entry that says `MERGED` without
-naming the merge, a `Related:` pointing at nothing. `--live` catches the claims a
-file cannot check about itself: that a version someone wrote down was in fact
-tagged, and that the file is still the export it says it is. A `REVIEW` entry's
-branch is checked like a `CODING` one — the status claims there is something to
-read. A `MERGED` entry is checked against neither tags nor branches, because its
-branch is meant to have been deleted.
-
-That last one re-runs `tools/roadmap/export.mjs` into a temporary file and
-compares the bytes. It goes through the exporter rather than rendering a second
-copy of it, so the two cannot drift apart. A difference fails and names the
-entries — missing here, missing there, or changed — with the remedy. If every
-entry agrees and the bytes still differ, the preamble or the section layout was
-edited by hand.
-
-It needs a `CAWDEV_TOKEN` and a project. Without them it prints a note saying it
-was skipped and the git checks still run; a check that cannot answer says so
-rather than passing (R41). If the token is set and the platform rejects it or is
-down, that is not "cannot answer" — it fails, with the API's own message.
-
-## Tests
-
-```sh
-node --test "tools/**/*.test.mjs"
-```
-
-`tools/lib/roadmap-format.test.mjs` covers the parse/render round trip. If those
-two stop agreeing, the generated file churns on every export and its diff stops
-meaning "the roadmap changed".
-
-`tools/lib/usage.test.mjs` covers what a turn reports. One of its tests asserts
-that **no dollar figure reaches a transcript**: the CLI quotes list prices, and
-a subscription does not work that way.
-
-`tools/lib/tool-rules.test.mjs` covers the matcher for what a run may do (R51).
-Every assertion of `false` in it is asserting that somebody gets asked a
-question they may have answered before — the cheap failure. The expensive one is
-a `true` nobody intended.
-
-`tools/mcp/approve.test.mjs` drives the real server over stdio against a faked
-platform, and pins the shape Claude Code reads back: a permission decision is
-JSON in the result text, and getting it wrong does not fail loudly — it stops a
-session, which is the failure R51 exists to end.
-
-`tools/runner/control.test.mjs` covers the socket a daemon offers (R52) on a
-real socket, including the backlog somebody attaching to an hour-old session
-needs, and that an unknown command is ignored rather than obeyed — that socket
-is a read-only view on purpose.
-
-`tools/runner/attach.test.mjs` covers the rendering arithmetic, which is where a
-terminal UI goes wrong silently: transcripts carry the agent's ANSI colour, and
-measuring it as plain text wraps the pane into nonsense.
-
-`tools/runner/workspaces.test.mjs` is R47 against the real daemon: two coding
-runs on one project, at the same time, in different checkouts, each reporting
-which. Getting that gate wrong is expensive in both directions — too tight and a
-machine with three checkouts still runs one session, too loose and two agents
-share a working copy.
-
-`tools/runner/test-platform.mjs` is the cawdev those two tests register with.
-Not a test itself, and not production code: it is a fake platform with a queue,
-shared because two fakes drift.
-
-`tools/runner/daemon-boot.test.mjs` starts the **real daemon** against a faked
-platform and a fake agent command. It is the only test of the first ten seconds
-— registering, the R51 permission-flag probe, opening the socket, and removing
-it again on the way out — a path that otherwise needs a `runner:operate` token
-to reach at all.
-
-## `tools/mcp/`
-
-The MCP server an agent talks to — zero dependencies, stdio JSON-RPC.
-`tools/mcp/README.md` covers setting it up in a repository, and is also written
-for the agent that reads it: it teaches the working method (branch first,
-`CODING` names the branch before the first commit, `roadmap_where` when in
-doubt).
-
-`tools/mcp/smoke.mjs` drives the server the way a client does — spawn, write
-lines to stdin, read lines from stdout — because the parts most likely to break
-are the transport and the framing. CI runs it against the compose stack.
-
-## `tools/runner/`
-
-The daemon that claims queued runs and spawns a real agent CLI in a working
-copy. `tools/runner/README.md` covers running one.
-
-## `tools/console/`
-
-`console-smoke.mjs` is the end-to-end test for the console's half of the loop
-(R12): start a run on an entry, watch the messages, answer the question from the
-inbox, see the finish report carrying the branch — all over the endpoints the
-browser calls, on a real session cookie. Point it at a **scratch project**: it
-creates an entry, cancels any live run, and declines the entry afterwards.
-
-```sh
-node tools/console/console-smoke.mjs scratch
-```
-
-Unlike everything else here it signs in rather than using `CAWDEV_TOKEN`, because
-starting a run and answering a question are both a *person's* acts — an agent
-cannot do either, so the test cannot bootstrap itself from a token.
+https://github.com/4dali/cawdev-cli

package/lib/run-plugin.mjs

@@ -92,6 +92,46 @@ export function agentFile(agent) {
   return `${head.join('\n')}\n${agent.body ?? ''}\n`;
 }
 
+/**
+ * Antigravity's own name for the same idea — R279. `agy plugin install
+ * <directory>` reads almost the same shape Claude Code's plugin does
+ * (`agents/*.md`, same frontmatter, same `agentFile()` below), confirmed by
+ * hand against the real CLI (v1.2.6): the one difference is where the
+ * manifest lives, `plugin.json` at the plugin's own root rather than under
+ * `.claude-plugin/`. No `skills/` here — R278 already inlines those into the
+ * prompt for this agent, since it has no lazy `Skill` tool to fetch one
+ * through a plugin the way Claude Code does.
+ *
+ * <p>A fixed name, like `registerAntigravityMcp`'s `cawdev` server: `agy
+ * plugin install` is machine-wide state, one project's experts at a time, so
+ * the runner removes whatever this name currently holds and reinstalls
+ * fresh before every spawn rather than trying to reconcile two projects'
+ * agents under one name.
+ */
+export const ANTIGRAVITY_EXPERTS_PLUGIN = 'cawdev-experts';
+
+/**
+ * Writes the run's experts as an Antigravity plugin directory — R279's half
+ * of `writeRunPlugin`. Returns the directory, or null when nothing was
+ * turned on, same contract.
+ */
+export async function writeAntigravityExpertsPlugin(directory, expertAgents) {
+  if (!expertAgents.length) {
+    return null;
+  }
+  const root = join(directory, ANTIGRAVITY_EXPERTS_PLUGIN);
+  await mkdir(join(root, 'agents'), { recursive: true });
+  await writeFile(join(root, 'plugin.json'), JSON.stringify({
+    name: ANTIGRAVITY_EXPERTS_PLUGIN,
+    description: 'What this project turned on in cawdev.',
+    version: '1.0.0',
+  }, null, 2));
+  for (const agent of expertAgents) {
+    await writeFile(join(root, 'agents', `${agent.key}.md`), agentFile(agent));
+  }
+  return root;
+}
+
 export function skillFile(skill) {
   const head = [
     '---',

package/lib/usage-report.mjs

@@ -112,6 +112,33 @@ export function parseUsage(text, now = new Date()) {
   if (!text) {
     return [];
   }
+
+  // Handle Agy output format
+  if (String(text).includes('Limit Remaining')) {
+    const windows = [];
+    for (const raw of String(text).split('\n')) {
+      const line = raw.trim();
+      if (!line || line.startsWith('Quota:')) continue;
+      
+      const match = /^(.*?)\s+(Weekly|Five Hour)\s+Limit Remaining\s+(\d{1,3})%\s+(.*Z)$/i.exec(line);
+      if (!match) continue;
+      
+      const model = match[1].trim();
+      const kind = match[2].toLowerCase() === 'weekly' ? 'WEEKLY' : 'FIVE_HOUR';
+      const remainingPercent = Number(match[3]);
+      const resetsAt = new Date(match[4].trim());
+      
+      windows.push({
+        kind,
+        model: model,
+        percent: 100 - remainingPercent,
+        resetsAt: isNaN(resetsAt.getTime()) ? null : resetsAt,
+        label: line,
+      });
+    }
+    return windows;
+  }
+
   const windows = [];
   for (const raw of String(text).split('\n')) {
     const line = raw.trim();

package/lib/version.mjs

@@ -0,0 +1,48 @@
+// R283 — the CLI's own version, and whether it is old enough to matter.
+//
+// Zero dependencies, like everything in tools/: no semver package, just the
+// three numbers this project actually uses (`tools/package.json`'s own
+// version is always `major.minor.patch`, and so is what the platform sends
+// back on `/api/health`).
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** This CLI's own version, read from `tools/package.json`. */
+export async function cliVersion() {
+  const path = join(HERE, '..', 'package.json');
+  const parsed = JSON.parse(await readFile(path, 'utf8'));
+  return parsed.version;
+}
+
+/**
+ * `major.minor.patch` as three numbers, or null for anything that is not
+ * shaped that way — a pre-release suffix, a build nobody tagged, garbage from
+ * a setting typed by hand. Null is "cannot compare", never "oldest possible":
+ * refusing a version we cannot parse would turn a typo in a setting into
+ * every runner on the platform refusing to boot.
+ */
+function parts(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version ?? '').trim());
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+/**
+ * Whether `version` is older than `minimum`. False when either cannot be
+ * parsed, or when `minimum` is blank — "cannot tell" and "no requirement" are
+ * both the safe reading here, matching `PlatformSettingService`'s own
+ * treatment of a blank `minimum_cli_version`.
+ */
+export function isBelow(version, minimum) {
+  if (!minimum || !String(minimum).trim()) return false;
+  const have = parts(version);
+  const need = parts(minimum);
+  if (!have || !need) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (have[i] !== need[i]) return have[i] < need[i];
+  }
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "0.9.0",
+  "version": "1.0.0-beta",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {

package/runner/README.md

@@ -76,6 +76,7 @@ cawdev --config <path>    the runner config to start a daemon from
 cawdev --no-start         attach only; never launch a daemon
 cawdev --watch-only       do not sign in; watch without being able to act
 cawdev --leave-running    leave the daemon running when you quit
+cawdev --version          this CLI's version, and the platform's
 ```
 
 **Quitting stops the daemon** — R123. One word starts the machine and the
@@ -94,6 +95,59 @@ process and one terminal**, which is what you want when the daemon should die
 with the window — there `q` stops it, and asks first when sessions are live.
 `node runner.mjs attach` joins a daemon started elsewhere.
 
+### `c`, `/config`, `cawdev config` — one change, not the whole walk
+
+`cawdev --setup` (above) asks everything a fresh machine needs at once. Once a
+machine is configured, most changes are smaller than that. **Inside the
+terminal, press `c`** (or type `/config`): a picker over what this machine does
+— add a project, add a workspace, each agent with its current state ("Disable
+claude", "Enable agy"), the console-rules switch, and the config itself with the
+token cut short. Every row is one of the shell commands below, driven through
+the terminal's own line editor and picker; `esc` anywhere in a step changes
+nothing. The screen edits the file the daemon says it booted from (the hello
+carries `configPath` since R288), so an older daemon is told to restart rather
+than guessed at, and adding a project asks for a `/login` first because it
+widens the machine's token.
+
+**Choosing where a checkout goes** (R289) is a picker before it is a line: the
+folder beside the checkouts this machine already serves, the default
+`~/cawdev/<slug>`, for a second workspace `<checkout>-2` — each row saying what
+is there now ("new folder — will clone here", "already a checkout of cawdev",
+"a checkout of …/else, not cawdev"). The last row opens a line **pre-filled**
+with the first suggestion; `tab` completes directories from disk the way a
+shell does, `~` expands, and a preview under the line says what the path is as
+you type. Before anything is cloned the URL and the path are confirmed once; a
+checkout of the same repository already at the path is taken as it is, with no
+question; anything else that exists is refused in words. `paths.mjs` is that
+logic, shared with the shell form below so the two doors agree. The shell form
+is for scripts and for a machine with no daemon to attach to:
+
+```
+cawdev config                          a menu, the same Select widget as everywhere else
+cawdev config add-project              serve one more project you can write to
+cawdev config add-workspace            another checkout for a project already served
+cawdev config agent enable|disable <claude|agy>
+cawdev config rules on|off             accept permission rules from the console — R126
+cawdev config show                     this machine's config, token redacted
+```
+
+Every one of these writes `runner.config.json` and nothing else. Adding a
+project widens the machine's existing `runner:operate` token in place
+(`PUT /api/tokens/{id}/grants`) rather than minting a second one — the id
+travels beside the secret since this card, and a machine set up before it
+falls back to a lookup by label the first time this runs, after which it
+remembers.
+
+Adding a project or a workspace needs a restart to take effect, same as any
+other change to `"projects"` — a live daemon says so. Enabling or disabling an
+agent and turning `rules` on or off do **not**: `cawdev config` — and the `c`
+screen, through the pid the hello names — sends the running daemon a `SIGHUP`,
+which re-reads just those three settings from the file and updates what the
+hello advertises, so the next `c` shows the new state. That is a unix convention asked of a process this operator already
+owns, not a command sent over the control socket in `attach.mjs` — that socket
+is deliberately read-only (see its own header), and a config change is not an
+exception carved into it.
+
 ### What it shows you
 
 The console shows you a session. This shows you **the machine** — and the
@@ -130,6 +184,7 @@ long it has been going, and the key that stops it. It is absent when nothing is.
 | `Y` | allow always, here — writes a project rule |
 | `x`, twice | cancel the session |
 | `g` | print the daemon's own log instead of the transcript |
+| `c` | configure this machine — the `cawdev config` menu, inside the terminal (R288) |
 | `q` | stop the runner and leave (`--leave-running` keeps it up) |
 | `esc` | close whatever is open, without ending the session |
 | `ctrl+c`, twice | the same, and then leave |
@@ -144,6 +199,7 @@ move through the command list while one is open.
 | `/login` | sign in through the browser |
 | `/logout` | forget the stored session on this machine |
 | `/runs` | the run list — the same as `L` |
+| `/config` | this machine's config — the same as `c` |
 | `/cancel` | cancel the session you are watching |
 | `/log` | the daemon's own log, on or off |
 | `/quit` | leave |