@motir/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,22 @@
 # `@motir/cli` — the `motir` command-line tool
 
-Terminal dispatch of the Motir work loop. The CLI is an **MCP client** of the
-Motir server (`/api/mcp`): every command speaks Model Context Protocol to the
-tenant with a personal access token (PAT) as a bearer credential. There is no
-parallel REST path — if the CLI needs a capability it lands as an MCP tool
-first, then the CLI consumes it (story 7.9 architecture).
+Terminal dispatch of the Motir work loop. The CLI is a client of **Motir's
+public REST API** (`/api/v1`): every command is an ordinary HTTPS request
+carrying a personal access token (PAT) as its bearer. There is no private
+channel — the CLI uses the same documented endpoints, the same credential and
+the same scopes any third-party integration gets, and if it needs a capability
+that capability lands on `/api/v1` first, where everyone can reach it.
+
+That is the point rather than an implementation detail: nothing this tool does
+is unavailable to a script you write yourself. The reference is at
+[`/docs/api`](https://app.motir.co/docs/api) and the machine-readable spec at
+[`/api/openapi/v1.json`](https://app.motir.co/api/openapi/v1.json) — the same
+document this package's types are generated from.
+
+> It was an MCP client until Story 11.5 (`docs/decisions/cli-v1-client.md`).
+> Motir still SERVES the Model Context Protocol at `/api/mcp`, for agents; the
+> CLI is simply no longer one of its clients, and no longer ships an
+> agent-protocol SDK to everyone who installs it.
 
 > **Status (Subtask 7.9.1):** this is the scaffold + auth + link layer. Read
 > commands (`ready` / `status` / `open` — 7.9.2), single dispatch (`next` /
@@ -43,9 +55,46 @@ pnpm --filter @motir/cli build      # produces dist/index.js (the `motir` binary
 node packages/cli/dist/index.js --help
 ```
 
-## Commands (this subtask)
+## Authenticate
 
 ```sh
+motir login
+```
+
+`motir login` is a **device grant**: it prints a short code and a URL, opens
+Motir in your browser, and waits for you to approve it there. Codes last 15
+minutes and nothing is written to disk until you approve. It is **headless by
+construction** — the code and URL are printed whether or not a browser opens, so
+an SSH session or a container uses the same command; `--no-browser` skips the
+launch attempt outright.
+
+The approval mints a CLI-scoped PAT: scopes `read`, `work_items:write`,
+`integration` (fixed — the grant can neither widen nor narrow them), 90-day
+expiry, labelled `CLI · <hostname>`. It lands in `~/.config/motir/config.json`,
+`chmod 600`, keyed by server URL.
+
+There are three credential tiers, and `motir login` is the middle one:
+
+| Tier                       | How                                | For                             |
+| -------------------------- | ---------------------------------- | ------------------------------- |
+| `MOTIR_TOKEN`              | export it — no login step, no file | CI, containers, read-only boxes |
+| `motir login`              | browser approval                   | a person at a terminal          |
+| `motir auth login --token` | paste a PAT you already hold       | scripts, older servers          |
+
+`MOTIR_TOKEN` is honoured by **every** command (paired with `MOTIR_SERVER` when
+there is no `.motir.json` to walk up to) and outranks a stored credential.
+
+**Disconnecting** is two different things: `motir logout` forgets the local copy
+on this machine, while **revoking the token in Settings → Account → API tokens**
+is the server-side kill switch. Full guide: [`docs/cli.md` §
+Authenticate](../../docs/cli.md#authenticate).
+
+## Setup commands
+
+```sh
+motir login        [--server <url>] [--no-browser]    # connect this terminal
+motir logout       [--server <url>]                   # forget the local credential
+
 motir auth login   [--server <url>] [--token <pat>]   # validate + store a PAT
 motir auth status  [--server <url>]                   # server, token prefix, owning user
 motir auth logout  [--server <url>]                   # forget the stored token
@@ -67,10 +116,19 @@ motir ready   [--kinds <list>] [--assignee <id|me|unassigned>] [--json]
 motir status  [--json]                                # ready / in-flight + active sprint
 motir sprints [--state <planned|active|complete>] [--json]
 motir sprint  [ref] [--kinds <list>] [--json]         # defaults to the ACTIVE sprint
-motir show    <key> [--json]                          # one item, in full
+motir show    <key> [--activity|--comments] [--json]  # one item, in full
 motir open    <key> [--print]                         # …in the browser
 ```
 
+**`motir show --activity` / `--comments`** add the DISCUSSION the aggregate does
+not carry: `--activity` interleaves comment threads with the change trail,
+`--comments` prints the threads alone. Both are opt-in — the stream is a second
+tool call, so a plain `show` stays one round-trip no matter how loud a card got —
+and comment bodies print **in full**, never excerpted. ONE page is printed and
+never drained: when more remains the footer says how much and points at `motir
+open <key>`; with `--json` the activity page rides along **unaltered** under an
+`activity` key. Passing both flags is refused rather than silently resolved.
+
 `motir sprint`'s **`ref` resolves in order**: omitted → the active sprint; then a
 sprint **id**; then an **exact name**; then a **name prefix** — each
 case-insensitive, first rule yielding exactly one sprint wins. An ambiguous
@@ -154,9 +212,11 @@ the item in the session exclude list so the next `motir next` moves past it;
 > `in_progress` status, so if the store cannot be written the CLI warns once and
 > the run continues rather than aborting.
 
-**Closing out.** After you merge, `motir done <key>`. The default workflow has
-no direct `in_progress → done` edge, so an item dispatched with `--print` (which
-never observed an agent finish) needs `motir done --via in_review <key>`; an
+**Closing out.** After you merge, `motir done <key>`. Since MOTIR-1625 the
+default workflow carries a direct `in_progress → done` edge, so this is one legal
+hop whether or not the item ever reached In Review. `motir done --via in_review
+<key>` still walks it through review explicitly — useful on a custom workflow
+that has no direct edge, or when you want the review hop on the record. An
 illegal flip surfaces the server's own allowed-targets error verbatim. A merged
 **session** PR closes out in bulk with `motir done --session <branch>`.
 
@@ -452,10 +512,10 @@ pnpm vitest run tests/cli/              # the story suite — the BUILT binary,
 ```
 
 **The package suite** (`packages/cli/test/**`) covers each module in isolation.
-Where a module talks to a server it is pointed at a REAL MCP server the test
-starts in-process (`test/helpers/mcpTestServer.ts`) with canned tool results —
-the transport, framing and error envelopes are the real ones, only the data is
-scripted. `test/auto.test.ts` drives the whole `motir auto` loop against a
+Where a module talks to a server it is pointed at a REAL HTTP server the test
+starts in-process (`test/helpers/testServer.ts`) with canned `/api/v1`
+responses — the framing, status handling and URL building are the real ones,
+only the data is scripted. `test/auto.test.ts` drives the whole `motir auto` loop against a
 scripted server, agent and git, because its load-bearing properties — that it
 re-queries every iteration, that an integrated item unlocks its dependents
 mid-run, that `main` is never advanced, and that the pull request opens even when
@@ -463,7 +523,7 @@ the run ended badly — are not visible in any single function.
 
 **The story suite** (`tests/cli/cli-story.test.ts`, in the root Vitest lane where
 Postgres is) spawns the BUILT binary as a child process against the real
-`/api/mcp` route, with a scripted fake agent and a recorded fake `gh`. It is what
+`/api/v1` routes, with a scripted fake agent and a recorded fake `gh`. It is what
 proves the assembled tool works: repo routing into real checkouts, the
 session-branch cascade, one pull request per touched repo, a `main` nobody
 advanced, and the help surface of the binary a user actually runs.
@@ -478,6 +538,9 @@ uses; the story suite rides the sharded Vitest job.
 
 ## Releasing
 
+What each version changed, for the person who installs it, is
+[`CHANGELOG.md`](./CHANGELOG.md). Below is how one gets published.
+
 Releases publish to the **public npm registry** via CI — the
 `.github/workflows/release-cli.yml` workflow, triggered by a package-scoped git
 tag. There is no manual `npm publish` in the normal path.