@plotio/cli 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+# @plotio/cli
 
-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.
+`plot`: read Plot pages, follow a meeting while it happens, and post back, from
+any agent with a shell (Claude Code, Codex CLI, Amp, OpenCode) or a script.
+
+Design and reasoning: `plans/agent-cli-and-mcp.md` at the repo root.
+
+## Install
+
+```bash
+npx @plotio/cli help agents      # no install
+npm install -g @plotio/cli       # or install the `plot` binary
+```
+
+Node 22 or later (the repo pins 24 in `.nvmrc`). In this repo,
+`pnpm --filter @plotio/cli start <command>` runs the TypeScript directly (no
+`--` before the command: pnpm passes it through, and `plot` would read it as
+the command).
+
+## Getting access
+
+Two kinds of credential, both `plot_agent_sk_…` tokens that Plot stores only
+as a hash:
+
+- **A page.** Someone picks "Copy agent instructions" on a page, which gives
+  a one-time `temp_code_…` (ten minutes, single use).
+  `plot open temp_code_… --agent "Claude Code"` redeems it for a token that
+  reads that one page (24 hours from the last read, a week at most).
+- **A workspace.** `plot login --agent "Claude Code"` signs in the way Claude
+  Code does: OAuth authorization code with PKCE (S256), client id `plot-cli`,
+  against the authorization server the API names in
+  `/.well-known/oauth-authorization-server`. So `--api` at a local or preview
+  deployment signs in on that deployment's own web app, never production's.
+  The code is exchanged at the token endpoint, `/v1/me` names the workspace,
+  and the token is stored as that API's workspace grant.
+
+One verifier and state make two authorize URLs that differ only in
+`redirect_uri`, and the server binds a code to the one it was approved with:
+a loopback one (`http://127.0.0.1:<port>/callback`) and the out-of-band
+`urn:ietf:wg:oauth:2.0:oob`, for which the consent page shows the code
+instead of redirecting. The loopback URL is only ever opened, never printed,
+because a browser on any other machine would be redirected into a dead port.
+
+- **On your own machine.** The browser opens on the loopback URL; approve
+  and it calls the terminal back by itself. Nothing to paste.
+- **Browser elsewhere (SSH, another computer).** The terminal prints the
+  out-of-band URL under "A browser tab should have opened. If it did not, or
+  it is on another machine, open this URL:". Approve there, and paste the
+  code the page shows at `Paste code here if prompted:`. Whichever arrives
+  first wins, within ten minutes. `--no-browser` prints only that URL and
+  does not listen at all.
+- **An agent or a sandbox (no TTY).** Nothing listens and nothing waits.
+  `plot login` prints the out-of-band URL and
+  `After approving, run: plot login --code <code>`, saves a pending login
+  (API base, verifier, state, agent name, time) in
+  `$XDG_CONFIG_HOME/plot/pending-login.json` at `0600`, and exits 0. The agent
+  hands the URL to its person, who approves and sends the code back;
+  `plot login --code <code>` exchanges it, stores the grant, deletes the
+  pending file and prints `Connected to <workspace>`. A pending login lasts
+  ten minutes, and `--code` works at a terminal too.
+
+## Commands
+
+| Command                                           | Does                                                                          |
+| ------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `plot open <temp_code_…> [--agent <name>]`        | Redeem a handoff code and store the page token                                |
+| `plot login [--agent] [--no-browser]`             | Connect a workspace: sign in and approve in the browser                       |
+| `plot login --code <code>`                        | Finish a login started without a terminal, with the code the browser showed   |
+| `plot logout [<page>] [--all]`                    | Revoke a credential on the server, then forget it                             |
+| `plot whoami [<page>] [--json]`                   | What the credential acts for, its scope and expiry                            |
+| `plot pages [--limit <n>] [--next <c>] [--json]`  | Pages the workspace grant can read, newest first                              |
+| `plot read <page> [--json]`                       | The page as Markdown (topics included), or as JSON; stores the updates cursor |
+| `plot watch <page> [--level …] [options]`         | Wait for the next update, print it, store the cursor                          |
+| `plot topics <page>`                              | Topics as JSON, with the quotes behind each point                             |
+| `plot search <query> [--limit] [--next] [--json]` | Search every page the workspace grant can read                                |
+| `plot post <page> [--branch <id>] [--body <t>]`   | Post a message (body from `--body`, else stdin), idempotent per run           |
+| `plot mcp-config [--host <h>] [--write] [<page>]` | The MCP server block for a host, pointing at `<api>/mcp`                      |
+| `plot help agents`                                | The guide for an AI agent                                                     |
+
+`<page>` is a page id or a page URL (`https://www.plot.io/p/<id>`).
+
+Every command takes `--api <url>`, `--token <token>` and `-h`/`--help`.
+`plot help <command>` lists a command's options.
+
+### `watch`
+
+One command is one turn: it blocks until something qualifies, prints only
+what is new since the last `watch` of that page, stores the new cursor and
+exits. Levels: `substantial` (default, when Plot's topic model completed a
+run), `every` (any new words), `topics` (a topic changed). Each request asks
+the server to hold it for up to 240 seconds (`wait=240`, kept under the 300
+seconds Node's fetch waits for response headers); where the server
+answers at once instead (Convex reached directly, in local dev and previews),
+`watch` pauses `--interval` seconds (default 3) and asks again.
+`--timeout <seconds>` gives up, cursor unchanged; keep it under your shell
+tool's own timeout. `--from-start` and `--cursor` override the stored cursor,
+and `--partial` includes words still being spoken (marked `interim`).
+
+An update is `{notice, page, level, lines, topics, room, lastRunAt, cursor}`:
+`lines` carry `authorName`, `text` and the flags `continues`, `revised`,
+`removed`, `interim`; `topics` carry their `points` with source quotes;
+`room` is who is present. `plot read` also stores the cursor (from its
+`X-Plot-Updates-Cursor` header), so a `watch` after a `read` brings only what
+was said after it. A stored cursor the server refuses (`bad_cursor`,
+`wrong_cursor_page`) is dropped and the watch starts over once.
+
+### `pages` and `search`
+
+Both page with an opaque `next`; keep passing `--next` until the output has
+no "More:" line, since a short batch does not mean the end. A page token on
+either is refused (`wrong_scope`): they need `plot login`.
+
+### `post`
+
+Each run generates one idempotency `id` and reuses it if the connection drops
+or a gateway answers 502 to 504, so the message lands once. A refusal is never
+retried: `read_only` means the person who granted access cannot post there.
+
+### `mcp-config`
+
+Hosts: `claude-code` (default, `.mcp.json`), `cursor` (`~/.cursor/mcp.json`),
+`vscode` (`.vscode/mcp.json`), `zed` (its `settings.json`) and
+`claude-desktop` (a connector added in its settings, OAuth only). The
+`Authorization` header names the `PLOT_TOKEN` environment variable in the
+host's own syntax (`${PLOT_TOKEN}` for Claude Code, `${env:PLOT_TOKEN}` for
+Cursor and VS Code) rather than holding the token, because `.mcp.json` and
+`.vscode/mcp.json` are usually committed. The token itself (the stored
+workspace one, or `<page>`'s) is printed to stderr as an `export` line to run
+where the host starts. `--inline-token` puts the token in the header instead
+(and makes a file it writes `0600`); Zed cannot read a variable there, so its
+block always holds the token. `--no-token` leaves the header out so the host
+signs in with OAuth. `--write` merges the block into the host's file, keeping
+every other server, and refuses a file whose top level is not a JSON object.
+
+## Environment
+
+| Variable          | Meaning                                                                   |
+| ----------------- | ------------------------------------------------------------------------- |
+| `PLOT_API_URL`    | API base. Default `https://agents.plot.io`; a deployment's `.convex.site` |
+|                   | host for local dev and previews. `--api` wins over it.                    |
+| `PLOT_TOKEN`      | Use this token instead of the store (a sandbox or CI job).                |
+| `PLOT_AGENT_NAME` | Default `--agent`. Inside Claude Code the default is "Claude Code".       |
+| `XDG_CONFIG_HOME` | Where the credential store lives (below).                                 |
+
+Token resolution for a page command: `--token`, then `PLOT_TOKEN`, then the
+page's stored grant, then the stored workspace grant. A stored token the
+server calls expired or revoked is removed and the next one tried.
+
+## Where credentials live
+
+`$XDG_CONFIG_HOME/plot/credentials.json`, by default
+`~/.config/plot/credentials.json`, mode `0600` in a `0700` directory. Keyed by
+API base, so production's and a preview's tokens never collide:
+
+```json
+{
+  "https://agents.plot.io": {
+    "workspace": {
+      "token": "plot_agent_sk_…",
+      "workspace": "Acme",
+      "expiresAt": "…"
+    },
+    "pages": {
+      "<pageId>": {
+        "token": "plot_agent_sk_…",
+        "expiresAt": "…",
+        "title": "…",
+        "cursor": "…"
+      }
+    }
+  }
+}
+```
+
+A page entry can hold just a `cursor` when that page is watched through the
+workspace grant. `plot logout --all` revokes and removes everything for the
+current API base.
+
+## Development
+
+```bash
+pnpm --filter @plotio/cli test         # node --test, no network
+pnpm --filter @plotio/cli type-check
+pnpm --filter @plotio/cli lint
+pnpm --filter @plotio/cli build        # dist/plot.js, one bundled file
+```
+
+`dist/` is not committed; `prepack` runs the build, so `pnpm pack` and
+`pnpm publish` from a clean tree still ship `dist/plot.js`.
+
+All HTTP lives in `src/api.ts`. The build bundles with esbuild rather than
+emitting with `tsc`, because `@plot/shared` (token shapes) is a private
+workspace package: the bundle inlines it, so the
+published package has no dependencies at all.