@parity-app/cli 0.0.0-stage → 0.1.0

package/dist/src-DXZqtm6z.mjs

@@ -0,0 +1,53 @@
+import { p as parseLibraryManifest, u as libraryManifestExtension } from "./src-D9EMN48r.mjs";
+import { createRequire } from "node:module";
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import semver from "semver";
+// ../registry/src/index.ts
+const require = createRequire(import.meta.url);
+/**
+* The folder the registry's files are in. The published CLI bundles this module and ships the files beside it, where
+* the package can't be resolved. Otherwise they're found through the package's own `package.json`, so it's the same
+* whether this module runs from source or bundled into the app.
+*/
+function registryDir() {
+	const bundled = join(import.meta.dirname, "libraries");
+	if (existsSync(bundled)) return bundled;
+	return join(dirname(require.resolve("@parity-app/registry/package.json")), "libraries");
+}
+let cache;
+/** Every file in the registry, read once. One that doesn't parse is skipped with a warning. */
+function registryEntries(dir = registryDir()) {
+	if (dir !== registryDir()) return readEntries(dir);
+	cache ??= readEntries(dir);
+	return cache;
+}
+async function readEntries(dir) {
+	const files = (await readdir(dir).catch(() => [])).filter((file) => file.endsWith(libraryManifestExtension)).sort();
+	const entries = [];
+	for (const file of files) {
+		const path = join(dir, file);
+		try {
+			const manifest = parseLibraryManifest(JSON.parse(await readFile(path, "utf8")));
+			if (!manifest.package) throw new TypeError("/package: a registry file names the package it describes");
+			entries.push({
+				file,
+				path,
+				manifest
+			});
+		} catch (error) {
+			console.warn(`Skipping registry file ${file}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return entries;
+}
+/** Whether a manifest describes this version of its package. A manifest without a range covers every version. */
+function covers(manifest, version) {
+	const range = manifest.package?.range;
+	if (!range) return true;
+	if (!version) return false;
+	const parsed = semver.coerce(version, { includePrerelease: true });
+	return parsed !== null && semver.satisfies(parsed, range, { includePrerelease: true });
+}
+export { registryDir as n, registryEntries as r, covers as t };

package/dist/src-DYi23Ypb.mjs

@@ -0,0 +1 @@
+export { t as covers, n as registryDir, r as registryEntries } from "./src-DXZqtm6z.mjs";

package/dist/src-FF8eY6EI.mjs

@@ -0,0 +1,2 @@
+export { a as applyLibraryEdits, t as componentNode, y as generateId, n as librarySource, f as parseLibraryEdits, i as withLibraryContext } from "./src-D9EMN48r.mjs";
+import "./src-8MhDV_sA.mjs";

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@parity-app/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Drive the Parity app from a terminal or an agent: read state, run edits, take screenshots, serve MCP.",
+  "keywords": [
+    "parity",
+    "design",
+    "components",
+    "mcp",
+    "cli"
+  ],
+  "homepage": "https://github.com/betterapps-hq/parity/tree/main/packages/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/betterapps-hq/parity.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/betterapps-hq/parity/issues",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "parity": "./dist/bin.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "semver": "^7.8.5",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "@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

@@ -0,0 +1,96 @@
+# Parity
+
+Parity is a design canvas that draws a project's real components, from its own source, styled only with its own tokens.
+A design here isn't a picture of the app: every button, card and table on the canvas is the project's component,
+rendered by its builder. What you design is what the code can build, and the files are the source of truth.
+
+Read this file first. Read `execute.md` and `document.md` before your first change; read a guide when the task calls for
+it.
+
+## Files
+
+| Read                        | When                                                                                   |
+| --------------------------- | -------------------------------------------------------------------------------------- |
+| `execute.md`                | Before any change: the functions a snippet can call, with examples. Required.          |
+| `document.md`               | Before any change: designs, nodes, styles, states and responsive patches. Required.    |
+| `guide/components.md`       | Using the project's components, making component designs, instances and params, icons. |
+| `guide/states-and-modes.md` | Loading, empty, error and other states; themes, viewports and locales.                 |
+| `guide/checking.md`         | Screenshots, layout problems, accessibility, the console, and trying a design.         |
+| `guide/design-system.md`    | Composing screens from the project's components and tokens.                            |
+| `guide/web-app.md`          | Designing web app screens: dashboards, settings, lists, forms.                         |
+| `guide/mobile.md`           | Designing for phones and small viewports.                                              |
+
+## 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.
+
+| 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.                                                                          |
+| `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_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.
+
+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
+folder, or prints with `--out -`. With no package it describes the app at `--root` into the `.lib.par` at its root,
+keeping the designs there, so ask before running that in someone's project.
+
+## How to work
+
+1. **Get your bearings.** Call `get_app_state`. Note the designs, which one is selected (the person usually means that
+   one), the modes, and the components. Designs, states and nodes have ids; use them.
+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.
+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"`,
+   `mode: "shown"`). Run `find_problems` and `check_accessibility` too, and read the warnings `execute` returns: they're
+   usually a token that doesn't exist or a prop the component doesn't take. Fix what you find, then check again.
+6. **Say what you did.** Tell the person what changed and what you couldn't verify. Ask them to try anything interactive
+   themselves with the Interact tool (I), which hands their mouse and keyboard to the real components.
+
+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.
+
+## Rules
+
+- **Use the project's components.** `Components()` lists them; library components are namespaced, as in `nova/Button`,
+  and icons too, as in `lucide/Heart`. A name that isn't in the list renders as a placeholder. Don't rebuild a button,
+  card or input out of layouts and text when the project has one.
+- **Use the project's tokens.** Colours, radii, shadows, fonts, sizes, leading and tracking name a token, such as
+  `muted-foreground`, `radius-lg` or `text-sm`, without the `--`. Lengths are steps of the spacing scale: `4` is four
+  spacing units (1rem in a default Tailwind project). `GetTokens()` lists them. Never write a raw colour or pixel value.
+- **Prefer semantic colours** (`background`, `foreground`, `card`, `muted`, `muted-foreground`, `primary`, `border`,
+  `destructive`) over palette ones (`color-blue-500`). They change with the theme; palette colours don't.
+- **Layout is auto layout.** A `layout` node is a flex box (or a grid with `display: "grid"`); children fill, hug or
+  take a fixed length. Avoid absolute positioning unless something truly overlaps, such as a badge on an avatar.
+- **One design, every viewport.** Don't copy a screen for mobile. Patch it with `Responsive(node, "mobile", patch)`:
+  hide the sidebar, stack the columns, shrink the padding.
+- **Real content.** Write the words the screen would show: names, numbers, dates and messages that fit the product.
+  Lorem ipsum hides layout problems.
+- **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.
+
+## 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`).

package/skills/document.md

@@ -0,0 +1,170 @@
+# Designs and nodes
+
+A project's designs live in `.par` files at its root, as JSON. You change them through `execute`, which validates every
+change, so you never edit the files by hand. This is the shape `GetDesign` and `Get` return and `Insert` takes.
+
+## Designs
+
+A design is a screen or a component, drawn on the canvas as a board of frames: one frame per state and mode it shows.
+
+| Field     | What it is                                                                                                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`      | Made from the name when the design is created. Stable; use it in paths.                                                                     |
+| `name`    | What people see.                                                                                                                            |
+| `kind`    | `screen` (a page or view) or `component` (a reusable part that screens place as instances).                                                 |
+| `root`    | The design itself: one node, usually a layout.                                                                                              |
+| `states`  | Situations the whole design can be in, like loading or empty. The first is the base; the others store only what they change.                |
+| `params`  | A component design's inputs, each with a `type` (`text`, `boolean`, `number`, `value`, `variant`) and a `default`. See Params and bindings. |
+| `frames`  | A fixed size per viewport, when the design isn't as wide as the viewport or as tall as its content.                                         |
+| `view`    | How the canvas shows it: the main mode, the modes beside it, the state and the variant options shown. Not part of the design.               |
+| `context` | Components a component design is drawn inside on its own board, such as a table around a table row.                                         |
+
+## Nodes
+
+Every node has an `id` (given when it's inserted), and can have a `name`, `hidden`, `style` and `responsive`. Name the
+layouts that group things ("Header", "Stats", "Actions"): the layers panel, state changes and paths all read better.
+
+### `layout`
+
+A box that lays out its `children`: a flex box by default, or a grid. Most structure is layouts.
+
+```json
+{ "type": "layout", "name": "Actions", "style": { "direction": "row", "gap": 2, "justify": "end" }, "children": [] }
+```
+
+### `component`
+
+One of the project's components. `component` is a name from `Components()`; `props` are its props; `slots` hold child
+nodes, where `children` is what goes between its tags and any other slot becomes a prop that takes nodes.
+
+```json
+{
+  "type": "component",
+  "component": "Button",
+  "props": { "variant": "outline", "size": "sm" },
+  "slots": {
+    "children": [
+      { "type": "component", "component": "lucide/Download" },
+      { "type": "text", "text": "Export" }
+    ]
+  }
+}
+```
+
+Text that's only a component's label can be its `children` prop instead: `"props": { "children": "Export" }`.
+
+### `instance`
+
+A copy of one of the project's component designs. `design` is the component design's id, `args` give its params values
+(an option's id for a variant), and `state` picks which of its states this copy shows.
+
+```json
+{ "type": "instance", "design": "stat-card", "args": { "label": "Active users", "value": "1,284" } }
+```
+
+`overrides` holds what this copy changes inside the component, keyed by the inner node's id, or `nested/inner` for a
+node inside a nested instance. Each is a patch like a state's (`hidden`, `text`, `props`, `style`). Everything the copy
+doesn't override keeps following the component.
+
+```json
+{ "type": "instance", "design": "stat-card", "overrides": { "trend": { "hidden": true } } }
+```
+
+A state's patches can reach inside an instance the same way, keyed `instance/inner`, so one copy can change in one
+state.
+
+### `text`
+
+Words. `tag` is `p` (the default), `span`, `h1` to `h4` or `strong`, and sets what the text is, not how it looks; size
+and weight come from `style`.
+
+```json
+{ "type": "text", "tag": "h2", "text": "Recent activity", "style": { "size": "text-lg", "weight": 600 } }
+```
+
+### `image`
+
+A picture: `src` is a path the project serves (`/images/team.jpg`) or a URL; `alt` describes it, or is empty when it's
+decoration; `fit` is `cover` (the default), `contain` or `fill`; `credit` names its maker when a photo asks for it.
+
+## Style
+
+Every value comes from the project. Lengths are steps of the spacing scale or the name of a length token; colours and
+type name a token from `GetTokens()`, without the `--`.
+
+| Key                                              | Takes                                                                     |
+| ------------------------------------------------ | ------------------------------------------------------------------------- |
+| `display`                                        | `flex` (the default) or `grid`                                            |
+| `direction`                                      | `column` (the default) or `row`                                           |
+| `columns`, `rows`                                | A grid's column or row count; all the same size                           |
+| `gap`, `rowGap`                                  | A length                                                                  |
+| `padding`, `margin`                              | A length, `[vertical, horizontal]` or `[top, right, bottom, left]`        |
+| `align`                                          | Children across: `start`, `center`, `end`, `stretch`                      |
+| `justify`                                        | Children along: `start`, `center`, `end`, `between`, `around`, `evenly`   |
+| `wrap`                                           | `true` to wrap a row                                                      |
+| `width`, `height`                                | A length, `fill` (take the room the parent gives) or `hug` (fit content)  |
+| `minWidth`, `maxWidth`, `minHeight`, `maxHeight` | A length                                                                  |
+| `grow`                                           | `true` to fill along the parent's direction                               |
+| `self`                                           | This node across its parent, overriding the parent's `align`              |
+| `colSpan`, `rowSpan`                             | Grid cells to span                                                        |
+| `position`, `top`, `right`, `bottom`, `left`     | `absolute`, placed against the parent's edges by lengths                  |
+| `background`, `foreground`, `border`             | A colour token                                                            |
+| `borderWidth`                                    | Pixels: 0, 1, 2, 4 or 8                                                   |
+| `borderStyle`                                    | `solid`, `dashed` or `dotted`                                             |
+| `radius`, `shadow`                               | A radius or shadow token, such as `radius-lg` or `shadow-sm`              |
+| `opacity`                                        | Percent, 0 to 100                                                         |
+| `overflow`                                       | `visible`, `hidden` or `scroll`                                           |
+| `font`, `size`, `leading`, `tracking`            | A token, such as `font-mono`, `text-sm`, `leading-tight`, `tracking-wide` |
+| `weight`                                         | A number: 400, 500, 600, 700                                              |
+| `textAlign`                                      | `start`, `center`, `end` or `justify`                                     |
+| `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.
+
+## States
+
+A state's `overrides` map node ids to patches of `hidden`, `text`, `props` and `style`. A node a state doesn't mention
+looks as it does in the base. States win over responsive patches.
+
+## Responsive
+
+A node's `responsive` maps a viewport option's id (such as `tablet` or `mobile`) to a patch of the same four things,
+applied in every mode on that viewport:
+
+```json
+{ "name": "Sidebar", "type": "instance", "design": "app-sidebar", "responsive": { "mobile": { "hidden": true } } }
+```
+
+## Params and bindings
+
+Inside a component design, a node's `bind` takes its values from the component's params, so each instance shows its own:
+`bind.text` names a text param, `bind.props` maps a prop to a param, and `bind.visible` names a boolean param that shows
+or hides the node. `ExtractComponent` sets all of this up from the occurrences it replaces.
+
+```json
+{ "type": "text", "text": "Revenue", "bind": { "text": "label" } }
+```
+
+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.
+
+```json
+"params": {
+  "size": {
+    "type": "variant",
+    "default": "medium",
+    "options": [
+      { "id": "medium", "name": "Medium" },
+      { "id": "small", "name": "Small", "overrides": { "card": { "style": { "padding": 3 } } } }
+    ]
+  }
+}
+```