@plotio/cli 0.0.0-stage → 0.1.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,171 @@
-# 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"` mints a token on this
+  machine, opens `<site>/connect?hash=…&agent=…&fp=…` for a person to approve,
+  and waits up to ten minutes. Only the hash goes to the browser. The terminal
+  prints a six-character code (the hash's first six characters) and the page
+  asks the person to type it, so a link sent on by someone else cannot be
+  approved by mistake. The URL is printed too, for SSH and sandboxes. The site
+  is `--site`, else `PLOT_SITE_URL`, else the web app the API names in its
+  OAuth metadata, so `--api` at a local or preview deployment approves there
+  rather than on production.
+
+## Commands
+
+| Command                                           | Does                                                                          |
+| ------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `plot open <temp_code_…> [--agent <name>]`        | Redeem a handoff code and store the page token                                |
+| `plot login [--agent] [--site] [--no-browser]`    | Connect a workspace, approved in the browser                                  |
+| `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_SITE_URL`   | Where `login` sends the browser. Default: the site the API names.         |
+| `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, minting and
+hashing) is a private workspace package: the bundle inlines it, so the
+published package has no dependencies at all.