@parity-app/cli 0.0.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity-app/cli",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Drive the Parity app from a terminal or an agent: read state, run edits, take screenshots, serve MCP.",
@@ -34,6 +34,11 @@
     "dist",
     "skills"
   ],
+  "scripts": {
+    "build": "vp pack",
+    "prepack": "vp pack",
+    "try-packed": "node scripts/try-packed.ts"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -42,12 +47,9 @@
     "typescript": "6.0.3"
   },
   "devDependencies": {
+    "@parity-app/agent": "0.0.0",
     "@parity-app/core": "0.0.0",
     "@parity-app/libgen": "0.0.0",
     "@parity-app/registry": "0.0.0"
-  },
-  "scripts": {
-    "build": "vp pack",
-    "try-packed": "node scripts/try-packed.ts"
   }
-}
+}

package/skills/SKILL.md

@@ -22,25 +22,62 @@ it.
 
 ## Tools
 
-The same tools are MCP tools and `parity` commands in a terminal. They act on a tab, which is one open project; the
-active tab is the default.
+The same tools are MCP tools and `parity` commands in a terminal. They act on a tab, which is one open project. Without
+`tab`, they act on the open project your working folder is in, and otherwise on `active`: what the person is looking at,
+the active tab of the Parity window they used last. When the person says "this" or "what I've selected" without naming a
+project, pass `tab: "active"` (`--tab active`) and read `get_app_state` for the selection.
 
 | MCP                   | CLI                          | What it does                                                                                                                                               |
 | --------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `get_app_state`       | `parity state`               | Designs, the selection, modes, components and token names, and what Parity detected (builder and config, package manager, installed versions). Start here. |
-| `execute`             | `parity exec`                | Runs a JavaScript snippet against the designs. All changes land as one undo step.                                                                          |
+| `get_status`          | `parity status`              | The revision, whether anything is unsaved and which files and tokens, the last save, and undo and redo; `summary` names them.                              |
+| `get_modes`           | `parity modes [design]`      | Viewports (the ids `Responsive` takes), modes (the ids renders take) and what each design shows; a design adds its frames.                                 |
+| `execute`             | `parity exec`                | Runs a JavaScript snippet against the designs. Its changes land as one undo step, merged per design with edits made meanwhile.                             |
 | `screenshot`          | `parity screenshot <design>` | Renders a design in its states and modes, offscreen, and returns the images.                                                                               |
 | `find_problems`       | `parity problems <design>`   | Render errors, overflow, clipping and unknown components, per frame.                                                                                       |
 | `check_accessibility` | `parity a11y <design>`       | axe-core against WCAG 2.2 AA, per frame, on the layers that break each rule.                                                                               |
 | `get_console`         | `parity console`             | What the project's own code wrote to the console, on the canvas and offscreen.                                                                             |
+| `get_tokens`          | `parity tokens`              | Tokens filtered by category, source or name, with values in every theme.                                                                                   |
+| `get_components`      | `parity components`          | Components, libraries, icon sets and exports left out or failing to render.                                                                                |
+| `get_props`           | `parity props <Component>`   | Props from source; `all` includes passed-through attributes.                                                                                               |
 | `get_tabs`            | `parity tabs`                | The open projects.                                                                                                                                         |
 | `open_project`        | `parity open <folder>`       | Opens a project in a new tab.                                                                                                                              |
 | `read_skill`          | `parity skill [file]`        | This skill.                                                                                                                                                |
 
-In a terminal, `parity tokens`, `parity components` and `parity props <Component>` read what designs can use without
-writing a snippet. `parity components` also says which of the app's exports aren't components and why, which components
-fail to draw on the canvas and why (often a missing provider, which a decorator adds), and what the person listed or
-took off the list by hand.
+The token, component and prop tools read what designs can use without writing a snippet in either transport.
+`parity components` also says which of the app's exports aren't components and why, which components fail to draw on the
+canvas and why (often a missing provider, which a decorator adds), and what the person listed or took off the list by
+hand.
+
+CLI commands and MCP tools share validation and defaults. Screenshot scale defaults to 1 and accepts 0.25 to 3. Audits
+check every state and shown mode unless narrowed; a single-element selector list is equivalent to a string. Screenshot
+failures and audit findings exit with 1 in the CLI and set MCP `isError`, with details retained. `get_console` defaults
+`clear` to false; `get_props` defaults `all` to false. MCP project paths must be absolute; the CLI resolves relative
+folders from its working directory. Skill reading is local and needs no running app.
+
+Several copies of Parity can run at once, each with its own projects open. Each call goes to the copy that has its
+project open, so naming the project is enough; `get_tabs` lists every copy's projects. A project open in two copies goes
+to the one that has been running longest. A copy kept apart with `PARITY_AGENT_FILE` is reached only through that file:
+
+```sh
+parity tabs                                         # every project open in any copy
+parity state --tab active                           # what the person is looking at, and their selection
+PARITY_AGENT_FILE=copy/agent.json pnpm dev &        # a copy of Parity kept apart
+PARITY_AGENT_FILE=copy/agent.json parity tabs       # just that copy
+```
+
+Every tool returns its result as data too: MCP `structuredContent`, or `--json` in the CLI. Read that rather than the
+text. A failure has `error.code` to branch on, `retryable` (send it again unchanged), `path` (the input at fault) and
+`alternatives` (valid ids for one it didn't know), so a mistyped id is fixed in one retry:
+
+```sh
+parity problems button --state loading --json
+# {"error": {"code": "unknown_state", "path": "/state", "alternatives": ["default", "outline", "destructive", "disabled"], ...}}
+parity problems button --state disabled --json
+```
+
+`get_tokens` returns the first 100 tokens and `get_console` the newest 50 messages, with `total` and `truncated`; narrow
+the read or raise `limit` when `truncated` is true.
 
 When a library's components, tokens or icons don't show, `parity lib <package> --root <project>` describes the package
 in a `.lib.par`: its components, tokens and the providers its frames need. It writes `./<id>.lib.par` in the current
@@ -54,7 +91,8 @@ keeping the designs there, so ask before running that in someone's project.
 2. **Look before you change.** Read the design with `Get("design-id", { depth: 3 })` in `execute`, and take a screenshot
    of what's there. Find the components you need with `Components()` and their props with `Props()`.
 3. **Change it in one snippet.** Build or edit the design with `Insert`, `Update`, `Replace`, `Move` and the rest. A
-   snippet either applies whole, as one step the person can undo, or changes nothing. Name the layouts you make.
+   snippet either applies whole, as one step the person can undo, or changes nothing. Name the layouts you make. If it
+   fails because the person changed a design it changes, run it again by its `editId`.
 4. **Cover every state.** A screen that loads has a loading state, a list has an empty one, a form has an error one. Add
    them with `AddState`, as changes to the base design, not as copies.
 5. **Check every frame.** Screenshot the design in all its states and the modes it shows (`state: "all"`,
@@ -65,7 +103,15 @@ keeping the designs there, so ask before running that in someone's project.
 
 Your changes to designs are on the canvas but not saved: the person saves (Ctrl+S) or undoes them, as with their own
 edits. Don't say they're saved. Token values from `SetTokens` are the same: they show at once, and go into the project's
-stylesheet when the person saves.
+stylesheet when the person saves. `get_status` says what's saved and what isn't, and its `revision` (also in
+`get_app_state`) stays the same until something changes, so compare it before reading the board again:
+
+```sh
+parity status --summary
+# shadcn-vite is at revision 7c612c04:1.
+# 1 file isn't saved. They wait for the person to save; agents can't.
+#   shadcn-vite.par: changed button
+```
 
 ## Rules
 
@@ -86,11 +132,12 @@ stylesheet when the person saves.
 - **Reuse what repeats.** When a row, card or list item appears more than twice, make it a component design with
   `ExtractComponent`, so each copy is an instance with its own content.
 - **Leave the canvas tidy.** New designs go into empty space (`FindEmptySpace`); `Overlaps()` tells you if boards
-  collide.
+  collide, sizing boards the canvas hasn't drawn yet from their frames (`estimated: true`).
 
 ## When something fails
 
-`execute` returns an `editId` when a snippet throws, and nothing changes. Fix it with `editId` and `edits` (exact find
-and replace on the snippet) instead of sending it all again. The error names the line. Common causes: a node path that
-matches two designs (write it as `design/node`), a node property that doesn't exist, and a state change to something
-states can't change (only `hidden`, `text`, `props` and `style`).
+`execute` returns an `editId` when a snippet throws, and nothing changes; `error.code` says why, and
+`error.alternatives` names the valid ids when a design, state, mode or component wasn't found. Fix it with `editId` and
+`edits` (exact find and replace on the snippet) instead of sending it all again. The error names the line. Common
+causes: a node path that matches two designs (write it as `design/node`), a node property that doesn't exist, and a
+state change to something states can't change (only `hidden`, `text`, `props` and `style`).

package/skills/document.md

@@ -120,6 +120,10 @@ type name a token from `GetTokens()`, without the `--`.
 | `transform`, `decoration`, `italic`              | `uppercase` and the like, `underline` or `line-through`, `true`           |
 | `lines`                                          | Lines of text before an ellipsis                                          |
 
+A text layer sizes as Figma's text does, by its `width` and `height`: `width: "hug"` is auto width, one line as wide as
+its text, wrapped only by a `maxWidth`; any other width, or none, with no `height` is auto height, wrapping at its width
+and growing down; a `height` as well is fixed.
+
 Type set on a layout applies to the text inside it. A component's own look comes from its props, so reach for a variant
 (`variant: "secondary"`) before styling a component from outside.
 
@@ -150,7 +154,8 @@ or hides the node. `ExtractComponent` sets all of this up from the occurrences i
 A **variant** is a param whose `options` each patch the component design, the way a state does: a size or a tone the
 instance chooses. Its `default` is an option's id, else the first option. An instance picks one in its `args`, and
 `view.variants` picks which one the component's own board shows. Patches apply in this order: the viewport's, the
-variant options', the state's, then the instance's overrides.
+variant options', the state's, then the instance's overrides. `Get` returns the stored node, with the text it was given;
+`Get(path, { state })` returns it as the board shows it, the param's value filled in and `bind` kept (see execute.md).
 
 ```json
 "params": {

package/skills/execute.md

@@ -4,12 +4,30 @@
 `await` works at the top level. When the snippet finishes, every change lands on the canvas as one step the person can
 undo; when it throws, nothing changes and you get an `editId` to fix it with.
 
-- Pass `description`: 3 to 8 words the person sees while it runs, such as "Add a pricing section".
+The person, and other agents, can change the tab while your snippet runs. Only the designs your snippet changed, created
+or deleted are applied, over what's there by then, so their edits to other designs, even in the same file, stay. If a
+design you changed was changed or deleted in the meantime, or the modes were and you set them, nothing is applied and
+the call fails naming it:
+
+```text
+Failed, nothing changed: Not applied: since this call read the tab, "Pricing" (app.par) was changed in the editor, and
+this call changes it too. Run the call again to work from what's there now.
+```
+
+Run it again with its `editId` and no edits (`parity exec --edit-id <id>`, or `execute` with just `editId`): the snippet
+reads the tab afresh, so it works from their change. Read the design again first if your snippet depends on what it
+held.
+
+- Prefer a `description` of 3 to 8 words, such as "Add a pricing section". CLI `exec` calls it `--label`. Both default
+  to "Edit designs" if omitted.
 - `Print(...)` (or `console.log`) is how you see values. Objects print as JSON.
 - Values assigned without `const` or `let` carry over to your next snippet in the same tab.
 - A snippet has 5 seconds of computing time. Rendering (screenshots and checks) doesn't count against it.
 - To retry a failed snippet, send `editId` with `edits`, each an exact `{ find, replace }` on the snippet text (`all` to
-  replace every match).
+  replace every match). Omitted edits default to an empty list. Do not send a new snippet with `editId`.
+- Both CLI and MCP validate the same request: a nonblank snippet or `editId`, nonblank label and tab when supplied, and
+  patches with a nonempty `find`, string `replace` (which can be empty), and optional boolean `all`. Invalid requests
+  are rejected before reaching the app.
 
 ## API
 
@@ -17,12 +35,15 @@ undo; when it throws, nothing changes and you get an `editId` to fix it with.
 // Reading
 Designs(): DesignSummary[]                       // every design: id, name, kind, states, what it shows, size
 GetDesign(design): Design                        // a whole design, as in document.md
-Get(path, { depth?, state? }?): Node             // a design's root or a node; depth cuts children off with "…"
+Get(path, { depth?, state?, mode? }?): Node      // a design's root or a node; depth cuts children off with "…"
 Get(path?, visit): any[]                         // walks nodes, collecting what visit returns
+Get(path, visit, { state?, mode? }): any[]       // walks nodes as a frame draws them
 Components(): string[]                           // the components designs can use
 Props(component, { all? }?): PropsInfo           // a component's props, from its source
+Icons(): IconSet[]                               // the project's icon sets, with their styles
+Icons(set, { search?, style?, limit? }): Icon[]  // async: a set's icons, as component nodes name them
 GetTokens({ category?, source?, search? }?): Token[]
-GetModes(): { settings, modes }                  // the project's modes, and each resolved
+GetModes(design?): { settings, variables, viewports, modes, designs }   // modes resolved; what each design shows
 Selection(): { design?, node?, mode? }           // what the person has selected
 
 // Designs
@@ -80,11 +101,27 @@ canvas, the main mode and the modes beside it. Start here to find ids.
 ### Get
 
 `Get("dashboard", { depth: 2 })` returns the design's root with two levels of children; deeper ones show as `"…"`. Read
-a branch with a node path, as in `Get("dashboard/Stats", { depth: 2 })`. With `state`, the result shows the nodes as
-that state changes them.
+a branch with a node path, as in `Get("dashboard/Stats", { depth: 2 })`. Without `state` or `mode`, Get returns the
+nodes as stored, which is what `Update` and the other edits change.
+
+With `state`, `mode` or both, Get returns the nodes as that frame of the board draws them: the design's variant options
+(`view.variants`), its params' defaults filled into bound values, its responsive patches for the mode, then the state's
+patches. `mode` is a mode id from `GetModes()`, as Screenshot takes. A state alone is read in the design's main mode,
+and a mode alone in the state the design shows. A bound value comes back filled in, with its `bind` kept so you can tell
+it comes from a param. An instance comes back as its own node with the args it's drawn with; read what's inside it by
+its path, `design/instance/inner`, which only works with `state` or `mode`.
+
+```js
+// A component whose title is bound to its "title" param: stored, then as the board shows it.
+Print(Get("card/title").text) // "Title"
+Print(Get("card/title", { state: "base" }).text) // "Card title", the param's default
+// A copy of the card on a screen, inside the instance, in a state and on mobile.
+Print(Get("profile/person/title", { state: "selected", mode: "mobile-light" }).text) // "Selected"
+```
 
 `Get(path, visit)` walks the nodes under `path`, or every design without one, and returns what `visit` returns for each.
-`visit(node, { design, path, depth, index, parent, skipChildren })`. Return `undefined` to collect nothing.
+`visit(node, { design, path, depth, index, parent, skipChildren })`. Return `undefined` to collect nothing. Given a
+path, `Get(path, visit, { state, mode })` visits the nodes as that frame draws them, as above.
 
 ```js
 // Every Button in the project, with where it is.
@@ -97,6 +134,26 @@ Print(Get((node, at) => (node.type === "component" && node.component === "Button
 source: variants with their options (`variant`, `size`), its own props, and with `{ all: true }` the attributes it
 passes to its element. A prop that isn't listed, or a variant value outside its options, comes back as a warning.
 
+### Icons
+
+`Icons()` lists the project's icon sets: each one's `id`, `name`, `package`, `styles` (such as `outline` and `solid`,
+empty when it has one) and the `style` used when none is asked for. An icon is a component node named `<set>/<Icon>`,
+with no children. `await Icons("lucide", { search: "settings" })` finds icons by name, by the other names the set
+exports them under and by the tags it publishes, best first; each comes back with its `label` and the `component` (and
+`props`, for sets that take the style as a prop) to insert it with. Without `search` it lists the set's icons in order.
+It returns 50 unless `limit` says otherwise, in the set's default style unless `style` names another.
+
+```js
+// A settings button with the project's own settings icon.
+const [icon] = await Icons(Icons()[0].id, { search: "settings", limit: 1 })
+Insert("dashboard/Toolbar", {
+  type: "component",
+  component: "Button",
+  props: { variant: "ghost", "aria-label": "Settings" },
+  slots: { children: [{ type: "component", component: icon.component, props: icon.props }] }
+})
+```
+
 ### GetTokens
 
 Each token has a `name`, a `category` (`color`, `font-size`, `radius`, `shadow`, `spacing`, `font`, `font-weight`,
@@ -217,6 +274,18 @@ ExtractComponent("team-members", rows.nodes, { name: "Member row", params: { [ro
 `SetModes(settings)` replaces the project's modes: take `GetModes().settings`, change it, and pass it back. Modes are
 shared by every design.
 
+`GetModes()` also gives `viewports`, the ids `Responsive` takes, each with its width and window height; `modes`, the ids
+`Screenshot` and the checks take, each with its `values` (one option per variable), width, window height, classes and
+attributes; and `designs`, each design's `state` (or `states` when it shows every state), `main` mode and `beside`
+modes. `GetModes("dashboard")` gives just that design, with each frame's width, fixed `height` if it has one, and
+`window`.
+
+```js
+const { viewports, designs } = GetModes("dashboard")
+Print(viewports.map((viewport) => viewport.id)) // ["desktop", "tablet", "mobile"]: for Responsive
+Print(designs[0].frames.map((frame) => `${frame.mode} ${frame.window.width}x${frame.window.height}`))
+```
+
 `SetTokens` changes token values in the project's stylesheets: `SetTokens({ primary: "oklch(0.55 0.2 260)" })` for every
 theme, or `SetTokens({ primary: { default: "…", dark: "…" } })` per theme. Every frame shows the new values at once, and
 saving writes them into the project's code, so do it only when the person asks to change the design system, not to style
@@ -228,15 +297,34 @@ one design. They're undone with the call's other changes.
 result. `state` and `mode` take an id, a list, or `"all"`; `mode` also takes `"shown"`, the modes the design shows. The
 defaults are the state on the canvas and the main mode.
 
+Frames draw as the canvas does: instances of a library's component designs (from its `.lib.par`) draw that design, and
+token values not yet saved show, the person's edits and this call's own `SetTokens` alike, so
+`SetTokens({ primary: "red" }); await Screenshot(id)` shows the new value in the same call.
+
 `Measure` lays out one frame and returns its size, whether it overflows sideways, and every node's box (`clipped` when a
 parent cuts it off). `Problems` checks frames for render errors, overflow, clipping and unknown components.
 `Accessibility` returns axe-core's findings per node and frame, with the rule, its impact and what's wrong.
 
+These frames are drawn in the same window as the canvas's: as wide as the frame, and as tall as the design's fixed
+height for the viewport, else the viewport's screen height, else the device nearest its width. So `100vh` and window
+size checks measure the same in `Measure` and `Screenshot` as on the canvas, even when the frame grows past that height.
+
 ## The canvas
 
 `FindEmptySpace({ width, height })` finds room for a new board, to the right of the others unless `direction: "below"`,
 or next to the design named in `near`. `Overlaps()` lists boards that collide, titles included; move one with
-`UpdateDesign(design, { x, y })`.
+`UpdateDesign(design, { x, y })`. A board is as big as the canvas last drew it. One it hasn't drawn yet is sized from
+its frames, laid out as the canvas lays them out: each shown mode's frame size (`frames` on the design, else the mode's
+width), companions shrunk to 640 wide, and a frame without a fixed height as tall as its window. Those overlaps say
+`estimated: true`.
+
+```js
+// With the default modes: a 1280 main frame, the dark one beside it at half size and the 390 phone, 2505 wide in all.
+const dashboard = CreateDesign({ name: "Dashboard", x: 0, y: 0 })
+UpdateDesign(dashboard, { showModes: ["desktop-dark", "mobile-light"] })
+CreateDesign({ name: "Settings", x: 2200, y: 0 })
+Print(Overlaps(dashboard)) // Dashboard and Settings, 305 across, estimated: true
+```
 
 ## Examples
 

package/skills/guide/states-and-modes.md

@@ -30,9 +30,11 @@ Modes are the project's, shared by every design. Each mode picks one option of e
 - **Theme:** a class on the frame, such as `dark`, that switches the project's tokens.
 - **Locale:** `lang` and `dir` attributes, for languages and right-to-left scripts.
 
-`GetModes()` lists them. A design shows its main mode and, beside it, any others you choose with
-`UpdateDesign(design, { showModes: ["desktop-dark", "mobile-light"] })`. Show the modes that matter for the design: a
-dashboard in desktop and mobile, a component in light and dark.
+`get_modes` (`parity modes`) lists them, and `get_modes` with a design gives its frames: run it before a responsive
+change, since the ids `Responsive` takes are viewports (`mobile`) and the ids screenshots take are modes
+(`mobile-light`). `GetModes()` gives the same in a snippet. A design shows its main mode and, beside it, any others you
+choose with `UpdateDesign(design, { showModes: ["desktop-dark", "mobile-light"] })`. Show the modes that matter for the
+design: a dashboard in desktop and mobile, a component in light and dark.
 
 ## Viewports and responsive patches
 

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Andrew Craswell
-
-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.