@dittowords/spec-cli 0.0.1-alpha.1 → 0.0.1-alpha.11

package/README.md

@@ -4,7 +4,7 @@
 
 CLI for syncing `.ditto.md` content specs with the Ditto platform.
 
-A `.ditto.md` file lives next to a component and declares its **text surfaces** — the props (and `children`) that hold user-facing copy. The file is pure metadata; nothing imports it at runtime. It exists for three consumers:
+A `.ditto.md` file lives next to a component and declares its **text surfaces** — every piece of user-facing copy the component renders, whether passed as props, `children`, or hardcoded in the component itself. The file is pure metadata; nothing imports it at runtime. It exists for three consumers:
 
 - **Agents** read it as fast-path context when writing or editing copy for the component.
 - **The CLI** (`ditto-spec pull`) syncs style guide rules from the platform whose tags match the file's surface tags.
@@ -19,9 +19,6 @@ Everything lives in YAML frontmatter. The markdown body below the closing `---`
 ```yaml
 ---
 component: DialogueModal
-description: >
-  A two-button confirmation modal for actions that need explicit
-  acknowledgement. Used for routine confirms and destructive flows.
 tags: [dialog, confirmation]
 surfaces:
   headline:
@@ -40,49 +37,71 @@ surfaces:
 rules:
   - name: Confirmation dialogs should be direct
     description: Keep confirmation copy terse and unambiguous
+    section: Voice & Tone
   - surface: actionText
     name: Calls to action should use active voice
     description: Always lead with a verb
     examples:
       - from: "Your settings"
         to: "Open settings"
-examples: []
+    section: Voice & Tone
+  - term: sign up
+    disallowed:
+      - signup
+      - sign-up
+    description: Always use as two words (verb form)
+    section: Terminology
+locales:
+  de-DE:
+    - name: Use informal address
+      description: Use "Du" instead of "Sie" for all user-facing copy
+      section: Formality
 ---
 ```
 
 ### Workspace spec (`workspace.ditto.md`)
 
-A repo may have a single `workspace.ditto.md` somewhere under the CLI's configured `roots`. It holds universal rules from the workspace style guide that carry no tags — these apply to every surface in every component.
+A repo may have a single `workspace.ditto.md` somewhere under the CLI's configured `roots`. It holds universal rules from the workspace style guide that carry no tags — these apply to every surface in every component. It also carries an inventory of all tags available on the platform, populated by `ditto-spec pull`.
 
 ```yaml
 ---
 workspace: true
-description: >
-  Workspace-wide content rules. Read alongside any component's index.ditto.md.
 # Managed by Ditto — do not edit below
-rules: []
+tags: [body, button, call-to-action, dialog-title, heading, nav]
+rules:
+  - name: Write in active voice
+    description: Lead with verbs, avoid passive constructions
+    section: Voice & Tone
+locales:
+  de-DE:
+    - name: Use informal address
+      description: Use "Du" instead of "Sie" for all user-facing copy
+      section: Formality
 ---
 ```
 
 ### Key concepts
 
-**Developer-owned keys**: `component`, `description`, `tags`, `surfaces`. Edit these freely.
+**Developer-owned keys**: `component`, `tags`, `surfaces`. Edit these freely.
 
-**CLI-managed keys**: `rules`, `examples`. Overwritten by `ditto-spec pull`. Do not edit by hand.
+**CLI-managed keys**: `rules`, `locales`, and workspace `tags`. Overwritten by `ditto-spec pull`. Do not edit by hand. Rules come in two shapes: style rules (`name`/`description`/`examples`) and terminology entries (`term`/`disallowed`/`description`).
 
-**Surface keys** are prop paths on the component. Dot-notation works for nested props (e.g., `primaryAction.label`). Use `$children` for components whose text comes through the `children` prop.
+**Surface keys** identify each distinct piece of user-facing text the component renders. For text passed as props, use the prop path as the key — dot-notation works for nested props (e.g., `primaryAction.label`). Use `$children` for text via the `children` prop. For hardcoded or internal strings, use a descriptive role name (e.g., `headline`, `bodyText`, `submitLabel`).
 
 **Component-level `tags`** cause matching rules to apply to every surface in the component (emitted in `rules` with no `surface` field). Per-surface tags cause rules to emit with `surface: "<key>"`. If a rule matches both levels, it emits once at component level (broader scope wins).
 
 **`maxLength` / `minLength`** are hard layout constraints, not stylistic preferences. Stylistic guidance belongs on the platform as rules.
 
-### Three-level rule hierarchy
+### Rule hierarchy
 
 | Scope | Where | Applies to |
 |---|---|---|
 | **Workspace** | `workspace.ditto.md` `rules[]` | Every surface in every component |
 | **Component-level** | Component's `rules[]`, no `surface` field | Every surface in this component |
 | **Per-surface** | Component's `rules[]`, with `surface: "<key>"` | That one surface |
+| **Locale-scoped** | `locales.<code>[]` (workspace or component) | Same hierarchy as above, but only when writing copy for that locale |
+
+Base rules in `rules` always apply. Locale-scoped rules in `locales` apply only when writing copy for the matching locale — they never conflict with each other because each locale is a separate scope.
 
 ## CLI commands
 
@@ -90,7 +109,12 @@ rules: []
 
 First-time setup. Creates `dittospec.config.json` and `workspace.ditto.md` in the current directory, then detects your agent environment (Claude Code, Cursor) and prints setup suggestions.
 
-Use `--agent` to also write agent configuration directly: appends a Ditto Content Specs section to `CLAUDE.md` or `.cursorrules` (creates the file if absent).
+Use `--agent` to also write agent configuration directly:
+
+- **Claude Code**: appends a Ditto Content Specs section to `CLAUDE.md` (creates the file if absent) and writes skill files to `.claude/commands/` (see [Agent skills](#agent-skills) below).
+- **Cursor**: appends a Ditto Content Specs section to `.cursorrules`.
+
+Re-running `init --agent` is safe — it updates skill files to the current CLI version and skips sections that already exist in `CLAUDE.md`.
 
 ### `ditto-spec scaffold <ComponentName>`
 
@@ -100,16 +124,18 @@ Creates a new `index.ditto.md` for a component with the correct YAML structure a
 ditto-spec scaffold DialogueModal --path src/components/DialogueModal
 ```
 
-Use `--path <dir>` to specify where the file is created (defaults to the current directory). After scaffolding, add surfaces for the component's text-bearing props and run `ditto-spec pull` to populate rules.
+Use `--path <dir>` to specify where the file is created (defaults to the current directory). After scaffolding, add a surface for each piece of user-facing text the component renders and run `ditto-spec pull` to populate rules.
 
 ### `ditto-spec pull`
 
 Syncs rules from the platform into spec files.
 
 1. Discovers all `.ditto.md` files under configured roots
-2. Fetches all workspace rules from `GET /v2/rules/mcp`
-3. Matches rules to specs by tag intersection (client-side)
-4. Rewrites the `rules` key in each file's YAML frontmatter
+2. Fetches style guides from `GET /v2/styleguides`
+3. Flattens rules and wordlist entries across all guides (or only those named in `styleguides` config)
+4. Separates base rules from locale-scoped rules (included when `locales` is configured)
+5. Matches rules to specs by tag intersection (client-side)
+6. Rewrites the `rules` and `locales` keys in each file's YAML frontmatter
 
 Use `--dry-run` to see what would change without writing.
 
@@ -121,6 +147,24 @@ Validates all spec files: YAML parses correctly, required keys are present, surf
 
 Prints an inventory of all component specs with their surfaces, tags, and constraints.
 
+### `ditto-spec create-rule`
+
+Creates a new rule on the Ditto platform.
+
+```
+ditto-spec create-rule --name "Use active voice" --description "Lead CTAs with a verb" --tags "button,call-to-action" --examples '[{"from":"Your settings","to":"Open settings"}]'
+```
+
+| Flag | Description |
+|---|---|
+| `--name` | Rule name (required) |
+| `--description` | What the rule enforces (required) |
+| `--styleguide` | Target style guide name or ID (optional, overrides `defaultStyleguide` config) |
+| `--tags` | Comma-separated tags to scope the rule (optional) |
+| `--examples` | JSON array of `{from, to}` pairs (optional) |
+
+After creating rules, run `ditto-spec pull` to sync them into spec files.
+
 ## Configuration
 
 Create `dittospec.config.json` at your repo root (or any ancestor directory):
@@ -138,28 +182,51 @@ Create `dittospec.config.json` at your repo root (or any ancestor directory):
 | `apiBase` | Ditto API base URL |
 | `workspaceId` | Your workspace ID |
 | `roots` | Repo-relative directories to search for `.ditto.md` files. Defaults to `["."]`. |
+| `styleguides` | Optional list of style guide names or IDs to pull. Defaults to all. |
+| `locales` | Optional list of locale codes (e.g. `["de-DE", "fr-FR"]`). Includes locale-scoped style guides matching these codes. Base (no-variant) guides are always included. |
+| `defaultStyleguide` | Optional style guide name or ID for `create-rule`. Overridable with the `--styleguide` flag. Defaults to the first guide returned by the API. |
 
 Set `DITTO_API_KEY` in your environment or in a `.env` file at the repo root.
 
+## Agent skills
+
+When you run `ditto-spec init --agent` in a Claude Code project, the CLI writes three skill files into `.claude/commands/`. These are slash commands that give agents interactive, multi-step workflows for working with ditto specs.
+
+| Skill | What it does |
+|---|---|
+| `/spec-component <Name>` | Analyze a component's text surfaces, scaffold a `.ditto.md` spec (or update an existing one), and sync rules from the platform. Handles child components too. |
+| `/spec-audit [Name]` | Audit copy in component instances against spec rules. Reports violations with file locations and suggested corrections. Omit the name to audit all specced components. |
+| `/spec-gaps [Name]` | Find copy patterns that should be rules but aren't. Proposes new style rules and terminology entries, then creates approved ones on the platform via `create-rule`. |
+
+Skills are written into your repo and committed alongside your specs and config. Every team member gets them automatically — no separate plugin install.
+
+**Updating skills**: Re-run `ditto-spec init --agent` after updating the CLI to get the latest skill versions. Existing skills are overwritten; the CLAUDE.md section is left untouched if already present.
+
+**Customizing skills**: The skill files are plain markdown in `.claude/commands/`. You can edit them to add project-specific behavior (e.g. default tags, custom audit checks). Re-running `init --agent` will overwrite your changes, so commit customizations and manage updates deliberately.
+
 ## Agent contract
 
-When writing or editing text props for a component:
+When writing or editing user-facing text for a component:
 
 1. Read `workspace.ditto.md` (if it exists) for universal rules.
-2. Read the component's `index.ditto.md`. Match each prop you're filling to a surface key.
+2. Read the component's `index.ditto.md`. Match each piece of text you're writing to a surface key.
 3. Respect `maxLength` — it's a layout invariant, not a suggestion.
 4. Follow all rules in `rules[]`. Entries without `surface` apply to every surface; entries with `surface` apply only to that surface.
-5. Reference `examples[]` entries with `status: "approved"` as concrete tone/shape guidance.
+5. Rules come in two shapes:
+   - **Style rules** have `name`, `description`, and optional `examples` (before/after pairs). Use `examples` as concrete tone/shape guidance.
+   - **Terminology entries** have `term` and `disallowed`. Always use the `term` form; never use any of the `disallowed` alternatives.
+6. Each rule carries a `section` field (e.g. "Voice & Tone", "Terminology") providing context for how to interpret it.
+7. If a `locales` key is present, it contains locale-scoped rules keyed by locale code (e.g. `de-DE`). When writing copy for a specific locale, follow the matching `locales.<code>` rules **in addition to** the base `rules`. When writing for the default/base locale, only follow `rules`. Locale-scoped rules never conflict — each locale is a separate boundary.
 
 ### Creating specs
 
-When creating a new component with text-bearing props, scaffold a spec file:
+When creating a new component that renders any user-facing text, scaffold a spec file:
 
 ```
 npx ditto-spec scaffold <ComponentName> --path <dir>
 ```
 
-Then edit the generated `index.ditto.md` to add surfaces — one entry per text-bearing prop:
+Then edit the generated `index.ditto.md` to add surfaces — one entry per piece of user-facing text the component renders:
 
 ```yaml
 surfaces:
@@ -171,8 +238,10 @@ surfaces:
     maxLength: 30
 ```
 
-- Use `$children` for text via children. Use dot notation for nested props (`primaryAction.label`).
-- Choose `tags` from content categories like `heading`, `body`, `button`, `cta`, `dialog-title`, `call-to-action`.
-- **Never write `rules` or `examples` by hand.** Run `ditto-spec pull` after adding surfaces to populate rules from the platform.
+- Use `$children` for text via children. Use dot notation for nested props (`primaryAction.label`). For hardcoded or internal strings, use a descriptive role name (`headline`, `bodyText`, `submitLabel`).
+- Check the `tags` key in `workspace.ditto.md` for tags available on the platform. Prefer reusing an existing tag over creating a new one — only a tag that exists on the platform will match rules. If no existing tag fits, create a new one following the convention of existing tags (lowercase, hyphenated).
+- **Never write `rules` by hand.** Run `ditto-spec pull` after adding surfaces to populate rules from the platform.
+
+Parent and child specs both contribute rules. If your component passes a label to a child Button, add a surface in the parent's spec — the parent's rules (e.g., dialog-level tone) layer with the child's rules (e.g., button-level constraints). A child having its own spec does not exempt the parent from declaring surfaces for text it provides.
 
 If a component lacks a spec and you'd have found one useful, propose creating one. If a spec lacks a rule you'd have wanted, propose adding the rule to the platform style guide with appropriate tags.

package/dist/api.d.ts

@@ -0,0 +1,82 @@
+import type { Config } from "./config";
+export interface StyleguideVariant {
+    id: string;
+    name: string;
+    localeCode: string | null;
+}
+export interface StyleRule {
+    name: string;
+    description: string;
+    examples: {
+        from: string;
+        to: string;
+    }[];
+    tags: string[];
+}
+export interface WordlistEntry {
+    term: string;
+    disallowed: string[];
+    description: string;
+    tags: string[];
+}
+export interface StyleguideSection {
+    name: string;
+    kind: "rules" | "wordlist";
+    rules: StyleRule[] | WordlistEntry[];
+}
+export interface Styleguide {
+    id: string;
+    name: string;
+    description: string;
+    variant: StyleguideVariant | null;
+    sections: StyleguideSection[];
+}
+export type FlatRule = {
+    kind: "style";
+    styleguide: string;
+    section: string;
+    localeCode: string | null;
+    name: string;
+    description: string;
+    examples: {
+        from: string;
+        to: string;
+    }[];
+    tags: string[];
+} | {
+    kind: "wordlist";
+    styleguide: string;
+    section: string;
+    localeCode: string | null;
+    term: string;
+    disallowed: string[];
+    description: string;
+    tags: string[];
+};
+export declare function flattenStyleguides(guides: Styleguide[], filter?: string[]): FlatRule[];
+export declare class DittoApi {
+    private readonly config;
+    private readonly apiKey;
+    constructor(config: Config, apiKey: string);
+    getStyleguides(): Promise<Styleguide[]>;
+    getStyleguideInfo(styleguideOverride?: string): Promise<{
+        styleguideId: string;
+        sectionId: string;
+    } | null>;
+    createRule(opts: {
+        styleguideId: string;
+        sectionId: string;
+        name: string;
+        description: string;
+        examples?: {
+            from: string;
+            to: string;
+        }[];
+        tags?: string[];
+    }): Promise<{
+        id: string;
+        name: string;
+    }>;
+    private fetch;
+    private headers;
+}

package/dist/api.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DittoApi = void 0;
+exports.flattenStyleguides = flattenStyleguides;
+function flattenStyleguides(guides, filter) {
+    const selected = filter?.length
+        ? guides.filter((g) => filter.includes(g.name) || filter.includes(g.id))
+        : guides;
+    const result = [];
+    for (const guide of selected) {
+        for (const section of guide.sections) {
+            if (section.kind === "rules") {
+                for (const rule of section.rules) {
+                    result.push({
+                        kind: "style",
+                        styleguide: guide.name,
+                        section: section.name,
+                        localeCode: guide.variant?.localeCode ?? null,
+                        name: rule.name,
+                        description: rule.description,
+                        examples: rule.examples,
+                        tags: rule.tags,
+                    });
+                }
+            }
+            else {
+                for (const entry of section.rules) {
+                    result.push({
+                        kind: "wordlist",
+                        styleguide: guide.name,
+                        section: section.name,
+                        localeCode: guide.variant?.localeCode ?? null,
+                        term: entry.term,
+                        disallowed: entry.disallowed,
+                        description: entry.description,
+                        tags: entry.tags,
+                    });
+                }
+            }
+        }
+    }
+    return result;
+}
+class DittoApi {
+    constructor(config, apiKey) {
+        this.config = config;
+        this.apiKey = apiKey;
+    }
+    async getStyleguides() {
+        const url = new URL("/v2/styleguides", this.config.apiBase);
+        const res = await this.fetch(url, { method: "GET" });
+        const data = (await res.json());
+        return data.styleguides;
+    }
+    async getStyleguideInfo(styleguideOverride) {
+        const guides = await this.getStyleguides();
+        if (guides.length === 0)
+            return null;
+        const target = styleguideOverride ?? this.config.defaultStyleguide;
+        const guide = target
+            ? guides.find((g) => g.name === target || g.id === target) ?? guides[0]
+            : guides[0];
+        if (guide.sections.length === 0)
+            return null;
+        const section = guide.sections.find((s) => s.kind === "rules") ?? guide.sections[0];
+        return { styleguideId: guide.name, sectionId: section.name };
+    }
+    async createRule(opts) {
+        const url = new URL(`/v2/styleguides/${encodeURIComponent(opts.styleguideId)}/rules`, this.config.apiBase);
+        const res = await this.fetch(url, {
+            method: "POST",
+            body: JSON.stringify({
+                sectionId: opts.sectionId,
+                name: opts.name,
+                description: opts.description,
+                examples: opts.examples,
+                tags: opts.tags,
+            }),
+        });
+        return (await res.json());
+    }
+    async fetch(url, init) {
+        const res = await fetch(url.toString(), {
+            ...init,
+            headers: { ...this.headers(init.method ?? "GET"), ...(init.headers ?? {}) },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`${init.method} ${url} → ${res.status}: ${body}`);
+        }
+        return res;
+    }
+    headers(method) {
+        const h = {
+            authorization: this.apiKey, // Ditto API expects bare key, no Bearer prefix
+            workspace_id: this.config.workspaceId,
+        };
+        if (method !== "GET")
+            h["content-type"] = "application/json";
+        return h;
+    }
+}
+exports.DittoApi = DittoApi;

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./cli";

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("./cli");

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const check_1 = require("./commands/check");
+const create_rule_1 = require("./commands/create-rule");
+const init_1 = require("./commands/init");
+const list_1 = require("./commands/list");
+const pull_1 = require("./commands/pull");
+const scaffold_1 = require("./commands/scaffold");
+const COMMANDS = {
+    init: async (args) => (0, init_1.init)({ writeAgent: args.includes("--agent"), force: args.includes("--force") }),
+    pull: async (args) => (0, pull_1.pull)({ dryRun: args.includes("--dry-run") }),
+    check: async () => (0, check_1.check)(),
+    list: async () => (0, list_1.list)(),
+    scaffold: async (args) => {
+        const name = args.find((a) => !a.startsWith("--"));
+        if (!name) {
+            process.stderr.write("Usage: ditto-spec scaffold <ComponentName> [--path <dir>]\n");
+            process.exit(2);
+        }
+        const pathIdx = args.indexOf("--path");
+        const targetDir = pathIdx !== -1 && args[pathIdx + 1] ? args[pathIdx + 1] : process.cwd();
+        return (0, scaffold_1.scaffold)({ componentName: name, targetDir });
+    },
+    "create-rule": async (args) => {
+        function getFlag(flag) {
+            const idx = args.indexOf(flag);
+            return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+        }
+        const name = getFlag("--name");
+        const description = getFlag("--description");
+        if (!name || !description) {
+            process.stderr.write('Usage: ditto-spec create-rule --name "<name>" --description "<desc>" [--styleguide "<name-or-id>"] [--tags "<t1,t2>"] [--examples \'<json>\']\n');
+            process.exit(2);
+        }
+        return (0, create_rule_1.createRule)({ name, description, styleguide: getFlag("--styleguide"), tags: getFlag("--tags"), examples: getFlag("--examples") });
+    },
+};
+const HELP = `ditto-spec — sync .ditto.md content specs with the Ditto platform.
+
+Usage:
+  ditto-spec <command> [options]
+
+Commands:
+  init             Set up ditto specs: creates config, workspace spec, and prints agent setup.
+  init --agent     Also writes agent configuration (CLAUDE.md, .cursorrules, etc.).
+  init --force     Overwrite locally modified skill files in .claude/commands/.
+  scaffold <Name>  Create a new index.ditto.md for a component.
+  scaffold <Name> --path <dir>  Create the spec in a specific directory.
+  pull             Pull rules from the platform into the managed keys of each spec.
+  pull --dry-run   Show which files would change without writing.
+  check            Parse every spec file; exit non-zero on any malformed file.
+  list             Print every component spec with its surfaces and tags.
+  create-rule      Create a rule on the platform.
+    --name "<name>"              Rule name (required)
+    --description "<desc>"       Rule description (required)
+    --styleguide "<name-or-id>"  Target style guide (optional, overrides config)
+    --tags "<t1,t2>"             Comma-separated tags (optional)
+    --examples '<json>'          JSON array of {from,to} pairs (optional)
+
+Environment:
+  DITTO_API_KEY    Workspace API key (required for pull).
+
+Config:
+  Reads dittospec.config.json from the nearest ancestor directory:
+    { "apiBase": "https://...", "workspaceId": "...", "roots": ["design-system"] }
+`;
+async function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    if (!cmd || cmd === "--help" || cmd === "-h") {
+        process.stdout.write(HELP);
+        return;
+    }
+    const handler = COMMANDS[cmd];
+    if (!handler) {
+        process.stderr.write(`Unknown command: ${cmd}\n\n${HELP}`);
+        process.exit(2);
+    }
+    try {
+        await handler(args.slice(1));
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+main();

package/dist/commands/check.d.ts

@@ -0,0 +1 @@
+export declare function check(): Promise<void>;

package/dist/commands/check.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.check = check;
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../config");
+const discover_1 = require("../discover");
+const parse_1 = require("../parse");
+async function check() {
+    const { config, root } = (0, config_1.loadConfig)();
+    const files = (0, discover_1.discover)(root, config.roots);
+    if (files.length === 0) {
+        console.log("No .ditto.md files found.");
+        return;
+    }
+    let failed = 0;
+    for (const f of files) {
+        try {
+            const parsed = (0, parse_1.parseSpecFile)(f.abs);
+            const specLike = parsed.spec;
+            if (parsed.kind === "workspace") {
+                if (specLike.tags !== undefined && !Array.isArray(specLike.tags)) {
+                    throw new Error("workspace spec 'tags' must be an array");
+                }
+                if (specLike.rules !== undefined && !Array.isArray(specLike.rules)) {
+                    throw new Error("workspace spec 'rules' must be an array");
+                }
+            }
+            if (parsed.kind === "component") {
+                const surfaces = specLike.surfaces;
+                if (!surfaces || typeof surfaces !== "object") {
+                    throw new Error("component spec missing 'surfaces' object");
+                }
+                for (const [key, val] of Object.entries(surfaces)) {
+                    if (!val || typeof val !== "object") {
+                        throw new Error(`surface '${key}' must be an object`);
+                    }
+                    const surface = val;
+                    if (!Array.isArray(surface.tags)) {
+                        throw new Error(`surface '${key}' missing 'tags' array`);
+                    }
+                }
+            }
+            console.log(`✓ ${path_1.default.relative(root, f.abs)}`);
+        }
+        catch (err) {
+            failed++;
+            console.error(`× ${path_1.default.relative(root, f.abs)}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    if (failed > 0) {
+        console.error(`\n${failed} file(s) failed validation.`);
+        process.exit(1);
+    }
+}

package/dist/commands/create-rule.d.ts

@@ -0,0 +1,9 @@
+interface CreateRuleOptions {
+    name: string;
+    description: string;
+    tags?: string;
+    examples?: string;
+    styleguide?: string;
+}
+export declare function createRule(opts: CreateRuleOptions): Promise<void>;
+export {};

package/dist/commands/create-rule.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRule = createRule;
+const api_1 = require("../api");
+const config_1 = require("../config");
+async function createRule(opts) {
+    const { config } = (0, config_1.loadConfig)();
+    const apiKey = (0, config_1.getApiKey)();
+    const api = new api_1.DittoApi(config, apiKey);
+    const info = await api.getStyleguideInfo(opts.styleguide);
+    if (!info) {
+        throw new Error("Could not discover style guide sections. Check that your workspace has at least one style guide with rules.");
+    }
+    let examples;
+    if (opts.examples) {
+        try {
+            examples = JSON.parse(opts.examples);
+        }
+        catch {
+            throw new Error('--examples must be valid JSON, e.g. \'[{"from":"bad","to":"good"}]\'');
+        }
+    }
+    const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
+    const result = await api.createRule({
+        styleguideId: info.styleguideId,
+        sectionId: info.sectionId,
+        name: opts.name,
+        description: opts.description,
+        examples,
+        tags,
+    });
+    console.log(`✓ Created rule "${result.name}" (${result.id})`);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,6 @@
+interface InitOptions {
+    writeAgent?: boolean;
+    force?: boolean;
+}
+export declare function init(opts?: InitOptions): Promise<void>;
+export {};