@parity-app/cli 0.1.0 → 0.2.0

package/README.md

@@ -21,15 +21,22 @@ or install it to get the `parity` command:
 npm install --global @parity-app/cli
 ```
 
-Most commands act on a running Parity app, on its active tab unless `--tab` names another. `parity lib` runs without the
+Most commands act on a project open in a running Parity app: the one `--tab` names, else the one the current folder is
+in, else the active tab of the Parity window used last (`--tab active` names that one). `parity lib` runs without the
 app.
 
+Each running copy of the app writes where to reach it to `~/.parity/agents`, and each call goes to the copy that has its
+project open; a project open in two copies goes to the one running longest. A copy started with `PARITY_AGENT_FILE`
+writes only that file, and a CLI given the same file reaches only that copy.
+
 ## Commands
 
 | Command                      | What it does                                                                               |
 | ---------------------------- | ------------------------------------------------------------------------------------------ |
 | `parity tabs`                | Lists the open projects.                                                                   |
 | `parity state`               | A tab's designs, selection, modes, components and tokens. Start here.                      |
+| `parity status`              | Revision, unsaved files and token values, the last save, and undo and redo.                |
+| `parity modes [design]`      | Viewports, modes and what each design shows; a design adds its frames' sizes.              |
 | `parity exec [file]`         | Runs a JavaScript snippet against the designs, from a file or stdin, as one undoable step. |
 | `parity screenshot <design>` | Renders a design in its states and modes, offscreen, as images.                            |
 | `parity problems <design>`   | Render errors, overflow, clipping and unknown components, per frame.                       |
@@ -60,6 +67,85 @@ Add the MCP server to your agent's configuration:
 
 Then have the agent read the skill first, with the `read_skill` tool or `parity skill`.
 
+## Execute contract
+
+CLI `exec` and MCP `execute` share one operation. CLI file/stdin becomes MCP's `input`; `--label` becomes `description`;
+`--tab`, `--edit-id` and parsed `--edits` have the same meaning in both. The default task label is `Edit designs`, and
+an omitted tab uses the open project the current folder is in, else the active tab.
+
+Send a nonblank snippet or a failed call's `editId`, not both. Retry patches need a nonempty `find`, a string `replace`
+(which can be empty), and optional boolean `all`; omitted patches default to an empty list. Invalid requests are
+rejected before reaching the desktop. Caller identity and session IDs travel separately from operation inputs.
+
+CLI failures exit with 1; MCP failures set `isError` and include the same failure and retry details, as the structured
+`error` below. CLI `--json` omits screenshot image data; MCP returns image content blocks.
+
+## Shared operations
+
+All desktop commands use the same operation contracts as their MCP counterparts:
+
+| CLI                      | MCP                   |
+| ------------------------ | --------------------- |
+| `tabs`                   | `get_tabs`            |
+| `state`                  | `get_app_state`       |
+| `status`                 | `get_status`          |
+| `modes`                  | `get_modes`           |
+| `exec`                   | `execute`             |
+| `screenshot`             | `screenshot`          |
+| `problems`               | `find_problems`       |
+| `a11y` / `accessibility` | `check_accessibility` |
+| `console`                | `get_console`         |
+| `open`                   | `open_project`        |
+| `tokens`                 | `get_tokens`          |
+| `components`             | `get_components`      |
+| `props`                  | `get_props`           |
+| `skill`                  | `read_skill`          |
+
+Screenshot scale defaults to 1 and must be a finite number from 0.25 to 3. Screenshot state and mode default to the
+current state and primary mode. Audits default to every state and shown modes. State and mode accept a nonblank string
+or a nonempty list of nonblank strings; one-item lists normalize to strings. `clear` for console and `all` for props
+default to false. Requests with invalid input fail before contacting the app.
+
+Screenshots that fail and audits that find issues exit with 1 in the CLI and set MCP `isError`, retaining the full
+report. CLI JSON omits screenshot image data; MCP emits image blocks. CLI `open` resolves relative folders; MCP requires
+an absolute path. Skill reading uses the same local reader and default `SKILL.md` in both transports. Library generation
+and checking remain CLI commands; library checking runs its snippets through the shared execute operation.
+
+## Structured results
+
+Every command takes `--json` and prints the same data the MCP tool returns as `structuredContent`. `tools/list` doesn't
+publish output schemas, since agents would pay for them in context; `operations.ts` and `execute.ts` hold them. Human
+text and screenshot images stay beside it. A failure is
+`{ "error": { code, message, retryable, path?, alternatives?, editId? } }` (with `--json` on stdout, and the message on
+stderr), or, for `exec` and `screenshot`, the whole report with `error` in it:
+
+- `code` is stable: `invalid_input`, `not_running`, `not_answering`, `unknown_tab`, `tab_not_ready`, `unknown_design`,
+  `unknown_node`, `ambiguous_reference`, `unknown_state`, `unknown_mode`, `unknown_viewport`, `unknown_component`,
+  `unknown_icon_set`, `unknown_edit_id`, `conflict`, `execution_failed` or `app_error`.
+- `retryable` is true when the same request, unchanged, can succeed: the app is starting, or edits collided.
+- `path` is a JSON pointer to the input at fault, in the transport's field names (`/design`, `/input`, `/edits/0/find`).
+- `alternatives` lists up to 20 valid ids for an unknown or ambiguous one, closest first.
+- `editId` retries a failed snippet with `edits`.
+
+```sh
+$ parity props Buton --json
+{ "error": { "code": "unknown_component", "message": "\"Buton\" isn't one of the project's components. Check Components().",
+  "retryable": false, "path": "/component", "alternatives": ["Avatar", "Badge", "Button", "Card", …] } }
+```
+
+`tokens` returns the first 100 unless `--limit` (up to 1000) says otherwise, and `console` the newest 50; both say
+`total` and `truncated`. `tabs` is `{ "tabs": [...] }`.
+
 ## Licence
 
 MIT. See [LICENSE](https://github.com/betterapps-hq/parity/blob/main/LICENSE).
+
+## Caller name on the canvas
+
+For CLI calls, set `PARITY_AGENT_NAME` to the name you want shown on cursors and badges (for example,
+`DeepSeek Harness`). Without a nonblank name, calls show `Terminal`. Use `PARITY_AGENT_ID` to distinguish concurrent CLI
+callers sharing a display name. `--label` names the task separately.
+
+For MCP, Parity uses the client's declared `clientInfo.title`, then `clientInfo.name`, then `Agent` if neither is
+nonblank. Names are trimmed and otherwise preserved; no list of known agents or tool environment detection is needed.
+These display names are self-reported, not authentication.