@dittowords/spec-cli 0.0.1-alpha.3 → 0.0.1-alpha.4

package/README.md

@@ -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:
@@ -46,7 +43,6 @@ rules:
     examples:
       - from: "Your settings"
         to: "Open settings"
-examples: []
 ---
 ```
 
@@ -57,8 +53,6 @@ A repo may have a single `workspace.ditto.md` somewhere under the CLI's configur
 ```yaml
 ---
 workspace: true
-description: >
-  Workspace-wide content rules. Read alongside any component's index.ditto.md.
 # Managed by Ditto — do not edit below
 tags: [body, button, call-to-action, dialog-title, heading, nav]
 rules: []
@@ -67,9 +61,9 @@ rules: []
 
 ### 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`, and workspace `tags`. Overwritten by `ditto-spec pull`. Do not edit by hand.
+**CLI-managed keys**: `rules` and workspace `tags`. Overwritten by `ditto-spec pull`. Do not edit by hand.
 
 **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`).
 
@@ -150,7 +144,7 @@ When writing or editing user-facing text for a component:
 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. When a rule includes `examples`, reference them as concrete tone/shape guidance.
 
 ### Creating specs
 
@@ -174,7 +168,7 @@ surfaces:
 
 - 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` or `examples` by hand.** Run `ditto-spec pull` after adding surfaces to populate rules from the platform.
+- **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.
 

package/dist/api.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from "./config";
+export interface RuleResponse {
+    name: string;
+    type: "style" | "wordlist";
+    description: string;
+    examples: {
+        from: string;
+        to: string;
+    }[];
+    tags: string[];
+}
+export declare class DittoApi {
+    private readonly config;
+    private readonly apiKey;
+    constructor(config: Config, apiKey: string);
+    getRules(): Promise<RuleResponse[]>;
+    private fetch;
+    private headers;
+}

package/dist/api.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DittoApi = void 0;
+class DittoApi {
+    constructor(config, apiKey) {
+        this.config = config;
+        this.apiKey = apiKey;
+    }
+    async getRules() {
+        const url = new URL("/v2/rules/mcp", this.config.apiBase);
+        const res = await this.fetch(url, { method: "GET" });
+        const data = (await res.json());
+        return data.workspaceRules;
+    }
+    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,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const check_1 = require("./commands/check");
+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") }),
+    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 });
+    },
+};
+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.).
+  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.
+
+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/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,199 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../config");
+const CONFIG_NAME = "dittospec.config.json";
+const WORKSPACE_SPEC_NAME = "workspace.ditto.md";
+const DEFAULT_CONFIG = JSON.stringify({
+    apiBase: "https://api.dittowords.com",
+    workspaceId: "TODO: your Ditto workspace ID",
+    roots: ["."],
+}, null, 2);
+const WORKSPACE_SPEC = `---
+workspace: true
+# Managed by Ditto — do not edit below
+tags: []
+rules: []
+---
+`;
+function agentDocs(format) {
+    const md = format === "claude";
+    const h2 = md ? "##" : "#";
+    const h3 = md ? "###" : "##";
+    const c = (s) => (md ? `\`${s}\`` : s);
+    const neverRules = md
+        ? `**Never write \`rules\` by hand.**`
+        : "NEVER write rules by hand.";
+    return `
+${h2} Ditto Content Specs
+
+This project uses ${c(".ditto.md")} files to declare text surfaces on components. Rules are synced from the Ditto platform — never written by hand.
+
+${h3} Reading specs
+
+When writing or editing text props for a component:
+
+1. Check for ${c("workspace.ditto.md")} at the project root for universal content rules.
+2. Check for ${c("index.ditto.md")} next to the component for surface-specific rules and constraints.
+3. Respect ${c("maxLength")} — it's a layout constraint, not a suggestion.
+4. Follow all rules in the ${c("rules")} key. Rules without a ${c("surface")} field apply to every surface; rules with ${c("surface")} apply only to that surface.
+
+${h3} Creating specs
+
+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 ${c("index.ditto.md")} to add surfaces — one entry per piece of user-facing text the component renders:
+
+    surfaces:
+      title:
+        tags: [heading]
+        maxLength: 60
+      $children:
+        tags: [button, cta]
+        maxLength: 30
+
+- Use ${c("$children")} for text via children. Use dot notation for nested props (${c("primaryAction.label")}). For hardcoded or internal strings, use a descriptive role name (${c("headline")}, ${c("bodyText")}, ${c("submitLabel")}).
+- Check the ${c("tags")} key in ${c("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).
+- ${neverRules} Run ${c("npx 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.
+
+Run ${c("npx ditto-spec list")} to see all existing specs.
+`;
+}
+const AGENTS_MD_ROW = "| Ditto component specs | `.ditto.md` content specs — read `workspace.ditto.md` and component `index.ditto.md` before writing copy |";
+async function init(opts = {}) {
+    const cwd = process.cwd();
+    const configExistsHere = fs_1.default.existsSync(path_1.default.join(cwd, CONFIG_NAME));
+    if (configExistsHere && !opts.writeAgent) {
+        console.log(`${CONFIG_NAME} already exists. Nothing to do.`);
+        console.log("Run with --agent to add agent configuration (CLAUDE.md, .cursorrules, etc.).");
+        return;
+    }
+    if (!configExistsHere) {
+        const ancestorConfig = findAncestorConfig(cwd);
+        if (ancestorConfig) {
+            console.log(`⚠ Found existing ${CONFIG_NAME} at ${ancestorConfig}`);
+            console.log("  Creating a new config here will shadow it for commands run in this directory.");
+        }
+        fs_1.default.writeFileSync(path_1.default.join(cwd, CONFIG_NAME), DEFAULT_CONFIG + "\n");
+        console.log(`✓ Created ${CONFIG_NAME}`);
+        fs_1.default.writeFileSync(path_1.default.join(cwd, WORKSPACE_SPEC_NAME), WORKSPACE_SPEC);
+        console.log(`✓ Created ${WORKSPACE_SPEC_NAME}`);
+    }
+    const env = detectAgentEnv(cwd);
+    if (opts.writeAgent) {
+        writeAgentConfig(cwd, env);
+    }
+    else {
+        printAgentSuggestions(env);
+    }
+    if (!configExistsHere) {
+        printNextSteps();
+    }
+}
+function findAncestorConfig(cwd) {
+    try {
+        const { root } = (0, config_1.loadConfig)(cwd);
+        if (path_1.default.resolve(root) !== path_1.default.resolve(cwd)) {
+            return path_1.default.join(root, CONFIG_NAME);
+        }
+    }
+    catch (err) {
+        if (!(err instanceof config_1.ConfigNotFoundError))
+            throw err;
+    }
+    return null;
+}
+function detectAgentEnv(cwd) {
+    if (fs_1.default.existsSync(path_1.default.join(cwd, ".claude")) || fs_1.default.existsSync(path_1.default.join(cwd, "CLAUDE.md"))) {
+        return "claude";
+    }
+    if (fs_1.default.existsSync(path_1.default.join(cwd, ".cursor")) || fs_1.default.existsSync(path_1.default.join(cwd, ".cursorrules"))) {
+        return "cursor";
+    }
+    return "none";
+}
+function writeAgentConfig(cwd, env) {
+    if (env === "claude") {
+        const claudeMd = path_1.default.join(cwd, "CLAUDE.md");
+        const block = agentDocs("claude");
+        if (fs_1.default.existsSync(claudeMd)) {
+            const existing = fs_1.default.readFileSync(claudeMd, "utf8");
+            if (existing.includes("Ditto Content Specs")) {
+                console.log("  CLAUDE.md already has Ditto Content Specs section — skipped.");
+            }
+            else {
+                fs_1.default.appendFileSync(claudeMd, block);
+                console.log("✓ Appended Ditto Content Specs section to CLAUDE.md");
+            }
+        }
+        else {
+            fs_1.default.writeFileSync(claudeMd, `# CLAUDE.md${block}`);
+            console.log("✓ Created CLAUDE.md with Ditto Content Specs section");
+        }
+        const agentsMd = path_1.default.join(cwd, "AGENTS.md");
+        if (fs_1.default.existsSync(agentsMd)) {
+            const existing = fs_1.default.readFileSync(agentsMd, "utf8");
+            if (existing.includes("Ditto component specs")) {
+                console.log("  AGENTS.md already has Ditto row — skipped.");
+            }
+            else {
+                fs_1.default.appendFileSync(agentsMd, "\n" + AGENTS_MD_ROW + "\n");
+                console.log("✓ Appended Ditto row to AGENTS.md");
+            }
+        }
+        return;
+    }
+    if (env === "cursor") {
+        const cursorrules = path_1.default.join(cwd, ".cursorrules");
+        const block = agentDocs("cursor");
+        if (fs_1.default.existsSync(cursorrules)) {
+            const existing = fs_1.default.readFileSync(cursorrules, "utf8");
+            if (existing.includes("Ditto Content Specs")) {
+                console.log("  .cursorrules already has Ditto section — skipped.");
+            }
+            else {
+                fs_1.default.appendFileSync(cursorrules, block);
+                console.log("✓ Appended Ditto section to .cursorrules");
+            }
+        }
+        else {
+            fs_1.default.writeFileSync(cursorrules, block.trimStart());
+            console.log("✓ Created .cursorrules with Ditto section");
+        }
+        return;
+    }
+    console.log("\nNo agent environment detected. See next steps for manual setup.");
+}
+function printAgentSuggestions(env) {
+    if (env === "claude") {
+        console.log("\nDetected Claude Code environment.");
+        console.log("Add this to your CLAUDE.md (or run `ditto-spec init --agent` to do it automatically):\n");
+        console.log(agentDocs("claude").trim());
+        return;
+    }
+    if (env === "cursor") {
+        console.log("\nDetected Cursor environment.");
+        console.log("Add this to your .cursorrules (or run `ditto-spec init --agent` to do it automatically):\n");
+        console.log(agentDocs("cursor").trim());
+        return;
+    }
+    console.log("\nTo help your AI agent use ditto specs, add the agent contract from the README");
+    console.log("to your project's agent configuration file (CLAUDE.md, .cursorrules, etc.).");
+}
+function printNextSteps() {
+    console.log(`
+Next steps:
+  1. Fill in your workspaceId in ${CONFIG_NAME}
+  2. Set DITTO_API_KEY in .env or your shell
+  3. Create your first component spec (index.ditto.md next to a component)
+  4. Run \`ditto-spec pull\` to sync rules from the platform`);
+}

package/dist/commands/list.d.ts

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

package/dist/commands/list.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.list = list;
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../config");
+const discover_1 = require("../discover");
+const parse_1 = require("../parse");
+async function list() {
+    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;
+    }
+    for (const f of files) {
+        let parsed;
+        try {
+            parsed = (0, parse_1.parseSpecFile)(f.abs);
+        }
+        catch (err) {
+            console.error(`× ${path_1.default.relative(root, f.abs)}: ${err instanceof Error ? err.message : err}`);
+            continue;
+        }
+        if (parsed.kind === "workspace") {
+            const rules = Array.isArray(parsed.spec.rules) ? parsed.spec.rules : [];
+            console.log(`\n[workspace]  (${path_1.default.relative(root, f.abs)})`);
+            console.log(`  ${rules.length} rule${rules.length === 1 ? "" : "s"}`);
+            continue;
+        }
+        console.log(`\n${parsed.name}  (${path_1.default.relative(root, f.abs)})`);
+        const specLike = parsed.spec;
+        const componentTags = specLike.tags ?? [];
+        if (componentTags.length > 0) {
+            console.log(`  component tags: [${componentTags.join(", ")}]`);
+        }
+        const surfaces = specLike.surfaces ?? {};
+        const entries = Object.entries(surfaces);
+        if (entries.length === 0) {
+            console.log("  (no surfaces)");
+            continue;
+        }
+        for (const [key, surface] of entries) {
+            const tags = (surface.tags ?? []).join(", ");
+            const maxLen = surface.maxLength != null ? `  max ${surface.maxLength}` : "";
+            console.log(`  ${key.padEnd(28)} [${tags}]${maxLen}`);
+        }
+    }
+}

package/dist/commands/pull.d.ts

@@ -0,0 +1,5 @@
+interface PullOptions {
+    dryRun?: boolean;
+}
+export declare function pull(opts?: PullOptions): Promise<void>;
+export {};

package/dist/commands/pull.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pull = pull;
+const path_1 = __importDefault(require("path"));
+const api_1 = require("../api");
+const config_1 = require("../config");
+const discover_1 = require("../discover");
+const parse_1 = require("../parse");
+const serialize_1 = require("../serialize");
+async function pull(opts = {}) {
+    const { config, root } = (0, config_1.loadConfig)();
+    const apiKey = (0, config_1.getApiKey)();
+    const api = new api_1.DittoApi(config, apiKey);
+    const files = (0, discover_1.discover)(root, config.roots);
+    if (files.length === 0) {
+        console.log("No .ditto.md files found.");
+        return;
+    }
+    console.log(`Found ${files.length} spec file${files.length === 1 ? "" : "s"}.`);
+    const componentFiles = [];
+    const workspaceFiles = [];
+    let failed = 0;
+    for (const f of files) {
+        let parsed;
+        try {
+            parsed = (0, parse_1.parseSpecFile)(f.abs);
+        }
+        catch (err) {
+            failed++;
+            console.error(`× ${f.rel}: ${err instanceof Error ? err.message : err}`);
+            continue;
+        }
+        if (parsed.kind === "workspace") {
+            workspaceFiles.push({ file: f, parsed });
+        }
+        else {
+            componentFiles.push({ file: f, parsed });
+        }
+    }
+    if (workspaceFiles.length > 1) {
+        const paths = workspaceFiles.map((w) => path_1.default.relative(root, w.file.abs)).join(", ");
+        throw new Error(`Found multiple workspace specs (${paths}). Expected at most one.`);
+    }
+    const allRules = await api.getRules();
+    console.log(`Fetched ${allRules.length} rule${allRules.length === 1 ? "" : "s"} from workspace.`);
+    const platformTags = [...new Set(allRules.flatMap((r) => r.tags))].filter(Boolean).sort();
+    let written = 0;
+    let unchanged = 0;
+    if (workspaceFiles.length === 1) {
+        const { file, parsed } = workspaceFiles[0];
+        const universalRules = allRules.filter((r) => r.tags.length === 0).map(toRuleObj);
+        if (rulesMatch(parsed.spec.rules, universalRules) && tagsMatch(parsed.spec.tags, platformTags)) {
+            unchanged++;
+        }
+        else if (opts.dryRun) {
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${universalRules.length} workspace rule(s), ${platformTags.length} tag(s))`);
+        }
+        else {
+            (0, serialize_1.rewriteManagedKeys)(file.abs, { tags: platformTags, rules: universalRules });
+            written++;
+            console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${universalRules.length} workspace rule(s), ${platformTags.length} tag(s)`);
+        }
+    }
+    for (const { file, parsed } of componentFiles) {
+        const specLike = parsed.spec;
+        const componentTags = specLike.tags ?? [];
+        const surfaces = specLike.surfaces ?? {};
+        const componentMatches = rulesForTags(allRules, componentTags);
+        const consumed = new Set(componentMatches);
+        const matchedRules = [];
+        for (const rule of componentMatches) {
+            matchedRules.push(toRuleObj(rule));
+        }
+        for (const [surfaceKey, surface] of Object.entries(surfaces)) {
+            const matches = rulesForTags(allRules, surface.tags ?? []).filter((r) => !consumed.has(r));
+            for (const rule of matches) {
+                matchedRules.push(toSurfaceRuleObj(surfaceKey, rule));
+            }
+        }
+        if (rulesMatch(parsed.spec.rules, matchedRules)) {
+            unchanged++;
+            continue;
+        }
+        if (opts.dryRun) {
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${matchedRules.length} rule(s))`);
+            continue;
+        }
+        (0, serialize_1.rewriteManagedKeys)(file.abs, { rules: matchedRules });
+        written++;
+        console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${matchedRules.length} rule(s)`);
+    }
+    console.log(`\nDone. ${written} updated, ${unchanged} unchanged.`);
+    if (failed > 0) {
+        console.error(`${failed} file(s) failed to parse.`);
+        process.exit(1);
+    }
+}
+function rulesForTags(rules, tags) {
+    if (tags.length === 0)
+        return [];
+    const tagSet = new Set(tags);
+    return rules.filter((r) => r.tags.length > 0 && r.tags.some((t) => tagSet.has(t)));
+}
+function toRuleObj(rule) {
+    const out = {
+        name: rule.name,
+        description: rule.description,
+    };
+    if (rule.examples.length > 0) {
+        out.examples = rule.examples.map((ex) => ({ from: ex.from, to: ex.to }));
+    }
+    return out;
+}
+function toSurfaceRuleObj(surface, rule) {
+    return { surface, ...toRuleObj(rule) };
+}
+function rulesMatch(existing, incoming) {
+    return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
+}
+function tagsMatch(existing, incoming) {
+    return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
+}

package/dist/commands/scaffold.d.ts

@@ -0,0 +1,6 @@
+interface ScaffoldOptions {
+    componentName: string;
+    targetDir: string;
+}
+export declare function scaffold(opts: ScaffoldOptions): Promise<void>;
+export {};