@bezel-labs/bezel-kit 0.9.0 → 0.10.0

package/dist/chunk-WQRF54FG.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/agent-skill.ts"],"sourcesContent":["/* Generated from skill/bezel by scripts/build-agent-skill.mjs — do not edit by hand. */\n\n/** The Bezel agent skill, embedded so it can be installed into a repo or served by the Bezel MCP. */\nexport interface AgentSkill {\n  /** Skill name; also the folder name under `.claude/skills` or `.agents/skills`. */\n  name: string\n  /** Frontmatter description: when the skill applies. */\n  description: string\n  /** Skill files keyed by path relative to the skill folder (`SKILL.md`, `references/...`). */\n  files: Record<string, string>\n  /** Markdown placed inside the managed block of AGENTS.md. */\n  agentsMdBlock: string\n  /** Description plus the hard rules, sized for an MCP `instructions` field. */\n  summary: string\n}\n\nexport const AGENT_SKILL: AgentSkill = {\n  name: \"bezel\",\n  description: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\",\n  files: {\n    \"SKILL.md\": \"---\\nname: bezel\\ndescription: Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\\n---\\n\\n# Bezel in this repository\\n\\nBezel is a design-token platform. Designers maintain the tokens in the Bezel app; this repo holds an exported copy and generates CSS from it with `@bezel-labs/bezel-kit`.\\n\\n```\\nBezel app (cloud, source of truth)\\n  -> design-tokens.json          DTCG file at the repo root, exported from Bezel\\n  -> bezel build                 reads bezel.json for options and output paths\\n  -> variables.css               one CSS scope per context (:root, .dark, .light, ...)\\n     contexts.ts, fonts.ts       optional generated TypeScript modules\\n```\\n\\nThe Bezel app stays the source of truth. Local edits to `design-tokens.json` reach Bezel only when they are pushed through the Bezel MCP, after a preview and the user's explicit yes (see \\\"Pushing changes back to Bezel\\\"); until then the next sync replaces them.\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed, and a sync from Bezel overwrites them. Never silently sync over local edits: say so and offer to push them first. Pushing means `preview-design-tokens-push`, showing its `confirmationPrompt` word for word, then `push-design-tokens-file` only after the user says yes. Never push without that confirmation, and never push from a \\\"sync\\\" or \\\"pull\\\" request.\\n\\n## The tokens file\\n\\n`design-tokens.json` follows the W3C Design Tokens (DTCG) format. Every token is an object with a `$type` and one `$value` per context:\\n\\n```json\\n\\\"semantic\\\": {\\n  \\\"color\\\": {\\n    \\\"primary\\\": {\\n      \\\"$type\\\": \\\"color\\\",\\n      \\\"$root\\\": { \\\"$value\\\": \\\"{base.color.green.500}\\\" },\\n      \\\"dark\\\":  { \\\"$value\\\": { \\\"colorSpace\\\": \\\"oklch\\\", \\\"components\\\": [0.85, 0.16, 152] } },\\n      \\\"$extensions\\\": { \\\"com.bezel.app\\\": { \\\"exportName\\\": [\\\"primary\\\", \\\"ring\\\"] } }\\n    }\\n  }\\n}\\n```\\n\\n- Context keys (`$root`, `dark`, `light`, or whatever `bezel.json` `contexts` lists) sit inside the token. `$root` is the base; other contexts only need the values that differ.\\n- `$value` is either a literal (DTCG color, dimension, font family, ...) or a reference like `{base.color.green.500}`. References are resolved to literal values in the generated CSS.\\n- `$extensions[\\\"com.bezel.app\\\"].exportName` is the list of CSS variable names the token emits. One token can emit several (`foreground`, `card-foreground`). An empty list means no variable.\\n- Groups (`base`, `semantic`, `color`, ...) are plain nesting with no `$type`.\\n\\n## What to do for common requests\\n\\n| Request | Edit | Then |\\n|---|---|---|\\n| Change a color, size, radius, or font value | The token's `$value` in the right context key (`$root` for every mode, `dark` for dark mode only) | Rebuild |\\n| A value should differ in dark mode | Add or edit the `dark` key on that token | Rebuild |\\n| New CSS variable | Add a token with `$type`, `$root.$value`, and an `exportName` (or reference an existing token) | Rebuild |\\n| Rename a CSS variable | Change the `exportName` entry; update every consumer of the old `--name` | Rebuild |\\n| New theme or brand context | Add the context to `bezel.json` `contexts` (name -> selector) and add that key to the tokens that differ | Rebuild |\\n| Change where files are generated | Edit `variablesOutput` / `contextsOutput` / `fontsOutput` in `bezel.json`; update the CSS import | Rebuild, delete the old outputs |\\n| \\\"Pull the latest tokens\\\" / \\\"sync from Bezel\\\" | See the next section | Rebuild |\\n| \\\"Push my changes to Bezel\\\" / save local token edits back | Nothing locally; follow \\\"Pushing changes back to Bezel\\\" | Write the returned `revision` to `bezel.json`; rebuild only if the file was re-synced |\\n\\nFind the token for an existing variable by searching `design-tokens.json` for its name inside an `exportName` array.\\n\\n## Pulling the latest tokens from Bezel\\n\\n`bezel.json` `projectId` and `version` (`\\\"latest\\\"` or a published semver) say which Bezel project and snapshot this repo tracks. `revision` records the project revision the file was last synced from or pushed to.\\n\\nWith the Bezel MCP connected: call `get-design-tokens-file` with that `projectId` and `version`, write the returned `content` string to `design-tokens.json` verbatim (no reformatting), set `\\\"revision\\\"` in `bezel.json` to the returned `revision`, then rebuild. The `sync-project` prompt walks through this, including linking a project when `projectId` is missing. Never pick a project or version yourself; ask when it is ambiguous.\\n\\nWithout the MCP: ask the user to download `design-tokens.json` from the project in the Bezel app and replace the file at the repo root, then rebuild.\\n\\nBefore overwriting a `design-tokens.json` that has local edits, stop and offer to push them first (next section) or confirm they should be discarded.\\n\\n## Pushing changes back to Bezel\\n\\nNeeds the Bezel MCP. Pushing saves this repo's `design-tokens.json` as the project's working tokens (`latest`), so the Bezel app stays the source of truth and everyone who syncs gets the change. Publishing a version still happens in the Bezel app.\\n\\n1. Read `projectId`, `version`, and `revision` from `bezel.json`. If `version` is a semver, tell the user the push updates the working project, not that pinned release.\\n2. Call `preview-design-tokens-push` with the exact file text as `content`, `revision` as `baseRevision`, and `version` as `trackedVersion`. It saves nothing.\\n3. `invalid` or `blocked`: report the errors and stop (`blocked` is a plan limit on groups, themes, or descriptions). `no-changes`: say the project already matches. Theme keys the file uses that the project does not have yet are added to the project by the push, within the plan's theme limit; the preview lists them as `addedContexts`.\\n4. `ready`: show `confirmationPrompt` to the user word for word and wait. Do not push on silence, a question, or a different request.\\n5. After an explicit yes, call `push-design-tokens-file` with the same `content` and `expectedRevision` = the preview's `currentRevision`. `conflict` means Bezel changed in between: go back to step 2.\\n6. Write the returned `revision` to `bezel.json`. If the result says `normalized`, sync once (`get-design-tokens-file`, write verbatim, rebuild) so the local file matches Bezel byte for byte.\\n\\nThe `push-project` prompt walks through this.\\n\\n## With the Bezel MCP connected\\n\\nPrefer small, targeted calls over reading the whole tokens file:\\n\\n- `get-project-manifest` first: groups, counts, types, contexts, no values.\\n- `query-tokens` to find tokens by group, type, name, or `exportName`; `get-token-by-path` for one token with every context value.\\n- `get-token-bundle` for a curated set per task (`theming-setup`, `button`, `card`, `form`, ...).\\n- `export-tokens` and `get-framework-overrides` to generate CSS, JS/TS objects, or Tailwind / shadcn / Mantine config from tokens.\\n- `contrast-check`, `color-convert`, `color-ramp`, `unit-convert` for deterministic math instead of estimating.\\n- `design-review` to check a component description against the tokens.\\n\\nSee `references/mcp-tools.md` for the full list and `references/bezel-json.md` for every config field.\\n\\n## Setting up a repo that is not on Bezel yet\\n\\nRun the `setup-project` tool (or the `/mcp__bezel__setup-project` prompt) and follow it; it installs `@bezel-labs/bezel-kit`, writes `bezel.json`, fetches the tokens, builds, and wires the CSS import. Do not improvise the steps.\\n\",\n    \"references/bezel-json.md\": \"# bezel.json reference\\n\\n`bezel.json` lives at the repo root (or the working directory `bezel build` runs in). `bezel build` loads it automatically; `bezel init` writes it. The tokens input is always `design-tokens.json` in that same directory and is not configurable.\\n\\n| Field | Default | Used by | Meaning |\\n|---|---|---|---|\\n| `projectId` | none | MCP | UUID of the Bezel project this repo tracks. Set with `npx bezel init --project <uuid>`. |\\n| `version` | `\\\"latest\\\"` | MCP | Which tokens snapshot to fetch: `\\\"latest\\\"` or a published semver such as `\\\"1.4.0\\\"`. Set with `--tokens-version`. |\\n| `revision` | none | MCP | Project revision the file was last synced from or pushed to. Written by the MCP after a sync or push, never by hand; lets a push preview warn when Bezel changed since. `bezel init --project` drops it when the project changes. |\\n| `variablesOutput` | `\\\"src/bezel/variables.css\\\"` | build | Generated CSS file. Import this from the app entry. |\\n| `contextsOutput` | none | build | When set, writes a TypeScript module exporting `CONTEXTS` (the context names). |\\n| `fontsOutput` | none | build | When set, writes a TypeScript module exporting `FONTS` (web fonts derived from the tokens). |\\n| `contexts` | `{ \\\"$root\\\": \\\":root\\\", \\\"dark\\\": \\\".dark\\\", \\\"light\\\": \\\".light\\\" }` | build | Context name -> CSS selector. The first entry is the base context and is emitted in full; the rest are override-only blocks. |\\n| `colorFormat` | `\\\"oklch\\\"` | build | `\\\"oklch\\\"` or `\\\"hex\\\"`. |\\n| `dimensionUnit` | `\\\"preserve\\\"` | build | `\\\"preserve\\\"` keeps authored units; `\\\"rem\\\"` converts `px` to `rem`. |\\n| `nameExtension` | `\\\"com.bezel.app\\\"` | build | The `$extensions` key that holds `exportName`. Only change for files exported before the 0.3.0 rename. |\\n| `includeAll` | `false` | build | Also emit a variable for every token without an `exportName`, named by its kebab-cased path (`--base-color-primary-500`). |\\n| `write` | `true` | build | `false` returns the CSS without writing files (programmatic use). |\\n| `gitignore` | `true` | build | Maintain a `# bezel:start` ... `# bezel:end` block in `.gitignore` listing the generated outputs. |\\n| `gitignorePath` | `\\\".gitignore\\\"` | build | Which `.gitignore` to manage. |\\n| `cwd` | process cwd | build | Base directory paths resolve against. |\\n\\n`projectId`, `version`, and `revision` are ignored by `bezel build`; everything else is ignored by the MCP.\\n\\n## CLI\\n\\n```\\nbezel init [--project <uuid>] [--tokens-version <v>] [--dir <path>] ...   create or update bezel.json\\nbezel build [--stdout] [--no-gitignore] ...                                generate the outputs (default command)\\nbezel install-mcp [--client <name>]                                        connect an AI coding tool to the Bezel MCP\\nbezel install-skills [--client <name>] [--no-agents-md]                    install this skill into the repo\\n```\\n\\n`bezel init` on an existing `bezel.json` with `--project` or `--tokens-version` updates only those keys. Any other re-run leaves the file alone unless `--force` is passed, which agents must not do.\\n\",\n    \"references/mcp-tools.md\": \"# Bezel MCP quick reference\\n\\nRemote server at `https://mcp.bezel.new/mcp` (Streamable HTTP, OAuth). The server returns data and instructions; the coding agent performs every local file edit and command. Project-scoped tools take the `projectId` from `bezel.json` or from `find-project`.\\n\\n## Guided workflows\\n\\n| Tool / prompt | Use |\\n|---|---|\\n| `setup-project` (tool and prompt) | Resumable setup: install bezel-kit, link a project, write `bezel.json`, fetch tokens, build, wire the CSS import, optional Crystal live preview. |\\n| `sync-project` (prompt) | Refresh `design-tokens.json` from the linked project and version, record the revision, then rebuild. Offers to push local edits first instead of overwriting them. |\\n| `push-project` (prompt) | Preview, confirm with the user, and push the repo's `design-tokens.json` to the linked project as its working tokens; records the new revision. |\\n| `safe-usage-guide` (prompt) | Context-budget rules: manifest first, targeted queries, cite token paths. |\\n| `manifest-first-workflow`, `context-resolution` (prompts) | Recommended reading order and how contexts resolve. |\\n| `get-agent-guide` (tool) | Returns this skill's text when the repo has no local copy. |\\n\\n## Discovery\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `find-project` | `query?` | All owned projects (name + id), or one project resolved from a name or UUID. |\\n| `get-project-manifest` | `projectId` | Groups, token counts, types, contexts. No values. Call this first. |\\n\\n## Repo sync\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `get-design-tokens-file` | `projectId`, `version?` | The exact `design-tokens.json` content to write to disk, plus project name, version, and `revision` (store it in `bezel.json`). Unknown version -> list of available versions. |\\n| `preview-design-tokens-push` | `projectId`, `content`, `baseRevision?`, `trackedVersion?` | Diff of the file against the project's working tokens, validation and plan-limit problems, the themes the file would add (`addedContexts`), a `stale` flag when Bezel changed since the last sync, and a `confirmationPrompt` to show the user verbatim. Saves nothing. |\\n| `push-design-tokens-file` | `projectId`, `content`, `expectedRevision` | Saves the file as the project's working tokens, only when the project is still at `expectedRevision` (else `conflict`). Call only after the user confirms the preview. Returns the new `revision`. |\\n\\n## Reading tokens\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `query-tokens` | `projectId`, `groupPath?`, `tokenType?`, `search?`, `exportName?`, `contextKey?`, `resolveAliases?` | Filtered tokens. |\\n| `get-token-by-path` | `projectId`, `tokenPath`, `contextKey?`, `resolveAliases?` | One token with every context value and alias detail. |\\n| `get-token-bundle` | `projectId`, `intent` | Curated set: `theming-setup`, `button`, `card`, `input`, `form`, `auth-page`, `dashboard-shell`. |\\n| `get-project-contexts` | `projectId` | Context groups and values (theme modes, platforms, brands). |\\n| `resolve-context` | `projectId`, `contextGroup`, `contextValue` | Canonical context value or a structured error. |\\n\\n## Generating code\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `export-tokens` | `projectId`, `format` (`css-variables`, `js-object`, `ts-object`), filters, `prefix?`, `includeAll?` | Generated code with aliases resolved. |\\n| `get-framework-overrides` | `projectId`, `framework` (`tailwind`, `shadcn`, `mantine`), `version?`, filters | Framework config derived from the tokens. |\\n\\n## Color and unit math (deterministic)\\n\\n| Tool | Parameters |\\n|---|---|\\n| `contrast-check` | `foreground`, `background` -> WCAG ratio, grade, recommendations |\\n| `color-convert` | `color`, `targetFormat`, `manipulation?`, `mixColor?` |\\n| `color-ramp` | `baseColor`, `steps`, `endColor?`, `colorSpace?` |\\n| `unit-convert` | `value`, `fromUnit`, `toUnit`, `rootFontSize?`, `parentFontSize?` |\\n\\n## Review and history\\n\\n| Tool | Parameters |\\n|---|---|\\n| `design-review` | `projectId`, `componentDescription`, `tokenPathsUsed?`, `contextKey?` |\\n| `get-chat-history` | `projectId` |\\n| `search-chat-history` | `projectId`, `query` |\\n\\n## Resources\\n\\n- `bezel://projects`: your projects with ids and names.\\n- `bezel://agent-guide`: this skill's text.\\n\"\n  },\n  agentsMdBlock: \"## Bezel design tokens\\n\\n- `design-tokens.json` at the repo root is the source for every design token. Edit it to change a color, size, font, or radius, or to add a CSS variable (add an `exportName` under `$extensions[\\\"com.bezel.app\\\"]`).\\n- Files under the Bezel output folder (`variablesOutput`, `contextsOutput`, `fontsOutput` in `bezel.json`; `src/bezel/` by default) are generated. Never edit them; they are overwritten on every build.\\n- After changing `design-tokens.json` or `bezel.json`, run `npm run tokens` (or `npx bezel build`) and check the outputs were rewritten.\\n- Dark mode and other contexts are keys inside each token (`$root`, `dark`, `light`). Add a value under the context key instead of writing a CSS override.\\n- The Bezel app is the source of truth. Local edits to `design-tokens.json` are not in Bezel until pushed, and the next sync (`get-design-tokens-file` via the Bezel MCP, or a download from the app) replaces them. Before syncing over local edits, or when asked to push, call `preview-design-tokens-push`, show its confirmation prompt word for word, and call `push-design-tokens-file` only after the user says yes.\\n- Never run `bezel init --force`; it discards the existing `bezel.json`. Use `--project` or `--tokens-version` to update a single key.\\n- Full guidance: the `bezel` skill in `.claude/skills/bezel/SKILL.md` or `.agents/skills/bezel/SKILL.md`.\",\n  summary: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed, and a sync from Bezel overwrites them. Never silently sync over local edits: say so and offer to push them first. Pushing means `preview-design-tokens-push`, showing its `confirmationPrompt` word for word, then `push-design-tokens-file` only after the user says yes. Never push without that confirmation, and never push from a \\\"sync\\\" or \\\"pull\\\" request.\",\n}\n"],"mappings":";AAgBO,IAAM,cAA0B;AAAA,EACrC,MAAM;AAAA,EACN,aAAa;AAAA,EACb,OAAO;AAAA,IACL,YAAY;AAAA,IACZ,4BAA4B;AAAA,IAC5B,2BAA2B;AAAA,EAC7B;AAAA,EACA,eAAe;AAAA,EACf,SAAS;AACX;","names":[]}