@dittowords/spec-cli 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,148 @@
+# @dittowords/spec-cli
+
+> **Alpha** — this package is in early development. The format and CLI interface may change between releases.
+
+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:
+
+- **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.
+- **Humans** review content decisions in PRs.
+
+## File format
+
+Everything lives in YAML frontmatter. The markdown body below the closing `---` is unused.
+
+### Component spec (`<Component>/index.ditto.md`)
+
+```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:
+    tags: [heading, dialog-title]
+    maxLength: 60
+  content:
+    tags: [body, dialog-body]
+    maxLength: 240
+  actionText:
+    tags: [call-to-action]
+    maxLength: 25
+  cancelText:
+    tags: [button]
+    maxLength: 25
+# Managed by Ditto — do not edit below
+rules:
+  - name: Confirmation dialogs should be direct
+    description: Keep confirmation copy terse and unambiguous
+  - surface: actionText
+    name: Calls to action should use active voice
+    description: Always lead with a verb
+    examples:
+      - from: "Your settings"
+        to: "Open settings"
+examples: []
+---
+```
+
+### 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.
+
+```yaml
+---
+workspace: true
+description: >
+  Workspace-wide content rules. Read alongside any component's index.ditto.md.
+# Managed by Ditto — do not edit below
+rules: []
+---
+```
+
+### Key concepts
+
+**Developer-owned keys**: `component`, `description`, `tags`, `surfaces`. Edit these freely.
+
+**CLI-managed keys**: `rules`, `examples`. Overwritten by `ditto-spec pull`. Do not edit by hand.
+
+**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.
+
+**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
+
+| 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 |
+
+## CLI commands
+
+### `ditto-spec init`
+
+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).
+
+### `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
+
+Use `--dry-run` to see what would change without writing.
+
+### `ditto-spec check`
+
+Validates all spec files: YAML parses correctly, required keys are present, surfaces have `tags` arrays. Exits non-zero on any failure — useful for CI.
+
+### `ditto-spec list`
+
+Prints an inventory of all component specs with their surfaces, tags, and constraints.
+
+## Configuration
+
+Create `dittospec.config.json` at your repo root (or any ancestor directory):
+
+```json
+{
+  "apiBase": "https://api.dittowords.com",
+  "workspaceId": "your-workspace-id",
+  "roots": ["design-system"]
+}
+```
+
+| Key | Description |
+|---|---|
+| `apiBase` | Ditto API base URL |
+| `workspaceId` | Your workspace ID |
+| `roots` | Repo-relative directories to search for `.ditto.md` files. Defaults to `["."]`. |
+
+Set `DITTO_API_KEY` in your environment or in a `.env` file at the repo root.
+
+## Agent contract
+
+When writing or editing text props 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.
+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.
+
+### Creating specs
+
+When scaffolding a new design-system component with text-bearing props, create an `index.ditto.md` alongside it. Declare a surface for each prop that holds user-facing copy. Tag surfaces with relevant content categories (e.g., `heading`, `body`, `button`, `cta`) so platform rules propagate on the next `pull`.
+
+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/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dittowords/spec-cli",
+  "version": "0.0.1-alpha.0",
+  "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
+  "main": "src/cli.ts",
+  "bin": {
+    "ditto-spec": "src/bin.js"
+  },
+  "scripts": {
+    "ditto-spec": "tsx src/cli.ts"
+  },
+  "dependencies": {
+    "dotenv": "^16.0.0",
+    "glob": "^11.0.1",
+    "js-yaml": "^4.1.0",
+    "tsx": "^4.0.0"
+  },
+  "license": "Proprietary"
+}

package/src/api.ts

@@ -0,0 +1,45 @@
+import type { Config } from "./config";
+
+export interface RuleResponse {
+  name: string;
+  type: "style" | "wordlist";
+  description: string;
+  examples: { from: string; to: string }[];
+  tags: string[];
+}
+
+export interface GetRulesMCPResponse {
+  workspaceRules: RuleResponse[];
+  projectRules: Record<string, RuleResponse[]>;
+}
+
+export class DittoApi {
+  constructor(private readonly config: Config, private readonly apiKey: string) {}
+
+  async getRules(): Promise<RuleResponse[]> {
+    const url = new URL("/v2/rules/mcp", this.config.apiBase);
+    const res = await this.fetch(url, { method: "GET" });
+    const data = (await res.json()) as GetRulesMCPResponse;
+    return data.workspaceRules;
+  }
+
+  private async fetch(url: URL, init: RequestInit): Promise<Response> {
+    const res = await fetch(url.toString(), {
+      ...init,
+      headers: { ...this.headers(), ...(init.headers ?? {}) },
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`${init.method} ${url} → ${res.status}: ${body}`);
+    }
+    return res;
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      authorization: this.apiKey,
+      workspace_id: this.config.workspaceId,
+      "content-type": "application/json",
+    };
+  }
+}

package/src/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+require("tsx/cjs");
+require("./cli.ts");

package/src/cli.ts

@@ -0,0 +1,57 @@
+import { check } from "./commands/check";
+import { init } from "./commands/init";
+import { list } from "./commands/list";
+import { pull } from "./commands/pull";
+
+const COMMANDS: Record<string, (args: string[]) => Promise<void>> = {
+  init: async (args) => init({ writeAgent: args.includes("--agent") }),
+  pull: async (args) => pull({ dryRun: args.includes("--dry-run") }),
+  check: async () => check(),
+  list: async () => list(),
+};
+
+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.).
+  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/src/commands/check.ts

@@ -0,0 +1,48 @@
+import path from "path";
+import { loadConfig } from "../config";
+import { discover } from "../discover";
+import { parseSpecFile } from "../parse";
+
+export async function check(): Promise<void> {
+  const { config, root } = loadConfig();
+  const files = 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 = parseSpecFile(f.abs);
+      const specLike = parsed.spec as Record<string, unknown>;
+
+      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 as Record<string, unknown>)) {
+          if (!val || typeof val !== "object") {
+            throw new Error(`surface '${key}' must be an object`);
+          }
+          const surface = val as Record<string, unknown>;
+          if (!Array.isArray(surface.tags)) {
+            throw new Error(`surface '${key}' missing 'tags' array`);
+          }
+        }
+      }
+
+      console.log(`✓ ${path.relative(root, f.abs)}`);
+    } catch (err) {
+      failed++;
+      console.error(`× ${path.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/src/commands/init.ts

@@ -0,0 +1,175 @@
+import fs from "fs";
+import path from "path";
+
+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
+description: >
+  Workspace-wide content rules. Read alongside any component's index.ditto.md.
+# Managed by Ditto — do not edit below
+rules: []
+---
+`;
+
+const CLAUDE_MD_BLOCK = `
+## Ditto Content Specs
+
+This project uses \`.ditto.md\` files for component content governance.
+
+When writing or editing text props for a component:
+
+1. Check for \`workspace.ditto.md\` at the project root for universal content rules.
+2. Check for \`index.ditto.md\` next to the component for surface-specific rules and constraints.
+3. Respect \`maxLength\` — it's a layout constraint, not a suggestion.
+4. Follow all rules in the \`rules\` key. Rules without a \`surface\` field apply to every surface; rules with \`surface\` apply only to that surface.
+5. When creating a new component with text-bearing props, scaffold an \`index.ditto.md\` alongside it.
+
+Run \`ditto-spec list\` to see all specs, or read the [spec format docs](./packages/ditto-spec-cli/README.md).
+`;
+
+const CURSOR_RULES_BLOCK = `
+# Ditto Content Specs
+
+This project uses .ditto.md files for component content governance.
+
+When writing or editing text props for a component:
+
+1. Check for workspace.ditto.md at the project root for universal content rules.
+2. Check for index.ditto.md next to the component for surface-specific rules and constraints.
+3. Respect maxLength — it's a layout constraint, not a suggestion.
+4. Follow all rules in the rules key. Rules without a surface field apply to every surface; rules with surface apply only to that surface.
+5. When creating a new component with text-bearing props, scaffold an index.ditto.md alongside it.
+`;
+
+const AGENTS_MD_ROW =
+  "| [Ditto component specs](./packages/ditto-spec-cli/README.md) | `.ditto.md` content specs — read before writing component copy |";
+
+interface InitOptions {
+  writeAgent?: boolean;
+}
+
+type AgentEnv = "claude" | "cursor" | "none";
+
+export async function init(opts: InitOptions = {}): Promise<void> {
+  const cwd = process.cwd();
+
+  if (fs.existsSync(path.join(cwd, CONFIG_NAME))) {
+    console.log(`${CONFIG_NAME} already exists. Nothing to do.`);
+    return;
+  }
+
+  fs.writeFileSync(path.join(cwd, CONFIG_NAME), DEFAULT_CONFIG + "\n");
+  console.log(`✓ Created ${CONFIG_NAME}`);
+
+  fs.writeFileSync(path.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);
+  }
+
+  printNextSteps();
+}
+
+function detectAgentEnv(cwd: string): AgentEnv {
+  if (fs.existsSync(path.join(cwd, ".claude")) || fs.existsSync(path.join(cwd, "CLAUDE.md"))) {
+    return "claude";
+  }
+  if (fs.existsSync(path.join(cwd, ".cursor")) || fs.existsSync(path.join(cwd, ".cursorrules"))) {
+    return "cursor";
+  }
+  return "none";
+}
+
+function writeAgentConfig(cwd: string, env: AgentEnv): void {
+  if (env === "claude") {
+    const claudeMd = path.join(cwd, "CLAUDE.md");
+    if (fs.existsSync(claudeMd)) {
+      const existing = fs.readFileSync(claudeMd, "utf8");
+      if (existing.includes("## Ditto Content Specs")) {
+        console.log("  CLAUDE.md already has Ditto Content Specs section — skipped.");
+      } else {
+        fs.appendFileSync(claudeMd, CLAUDE_MD_BLOCK);
+        console.log("✓ Appended Ditto Content Specs section to CLAUDE.md");
+      }
+    } else {
+      fs.writeFileSync(claudeMd, `# CLAUDE.md${CLAUDE_MD_BLOCK}`);
+      console.log("✓ Created CLAUDE.md with Ditto Content Specs section");
+    }
+
+    const agentsMd = path.join(cwd, "AGENTS.md");
+    if (fs.existsSync(agentsMd)) {
+      const existing = fs.readFileSync(agentsMd, "utf8");
+      if (existing.includes("Ditto component specs")) {
+        console.log("  AGENTS.md already has Ditto row — skipped.");
+      } else {
+        fs.appendFileSync(agentsMd, "\n" + AGENTS_MD_ROW + "\n");
+        console.log("✓ Appended Ditto row to AGENTS.md");
+      }
+    }
+    return;
+  }
+
+  if (env === "cursor") {
+    const cursorrules = path.join(cwd, ".cursorrules");
+    if (fs.existsSync(cursorrules)) {
+      const existing = fs.readFileSync(cursorrules, "utf8");
+      if (existing.includes("Ditto Content Specs")) {
+        console.log("  .cursorrules already has Ditto section — skipped.");
+      } else {
+        fs.appendFileSync(cursorrules, CURSOR_RULES_BLOCK);
+        console.log("✓ Appended Ditto section to .cursorrules");
+      }
+    } else {
+      fs.writeFileSync(cursorrules, CURSOR_RULES_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: AgentEnv): void {
+  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(CLAUDE_MD_BLOCK.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(CURSOR_RULES_BLOCK.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(): void {
+  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/src/commands/list.ts

@@ -0,0 +1,59 @@
+import path from "path";
+import { loadConfig } from "../config";
+import { discover } from "../discover";
+import { ParsedSpec, parseSpecFile } from "../parse";
+
+interface SurfaceLike {
+  tags?: string[];
+  maxLength?: number;
+}
+
+interface SpecLike {
+  tags?: string[];
+  surfaces?: Record<string, SurfaceLike>;
+}
+
+export async function list(): Promise<void> {
+  const { config, root } = loadConfig();
+  const files = discover(root, config.roots);
+
+  if (files.length === 0) {
+    console.log("No .ditto.md files found.");
+    return;
+  }
+
+  for (const f of files) {
+    let parsed: ParsedSpec;
+    try {
+      parsed = parseSpecFile(f.abs);
+    } catch (err) {
+      console.error(`× ${path.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.relative(root, f.abs)})`);
+      console.log(`  ${rules.length} rule${rules.length === 1 ? "" : "s"}`);
+      continue;
+    }
+
+    console.log(`\n${parsed.name}  (${path.relative(root, f.abs)})`);
+    const specLike = parsed.spec as SpecLike;
+    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/src/commands/pull.ts

@@ -0,0 +1,140 @@
+import path from "path";
+import { DittoApi, RuleResponse } from "../api";
+import { getApiKey, loadConfig } from "../config";
+import { discover, DiscoveredFile } from "../discover";
+import { ParsedSpec, parseSpecFile } from "../parse";
+import { rewriteManagedKeys } from "../serialize";
+
+interface SurfaceLike {
+  tags?: string[];
+}
+
+interface SpecLike {
+  tags?: string[];
+  surfaces?: Record<string, SurfaceLike>;
+}
+
+interface PullOptions {
+  dryRun?: boolean;
+}
+
+export async function pull(opts: PullOptions = {}): Promise<void> {
+  const { config, root } = loadConfig();
+  const apiKey = getApiKey();
+  const api = new DittoApi(config, apiKey);
+
+  const files = 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"}.`);
+
+  type ParsedFile = { file: DiscoveredFile; parsed: ParsedSpec };
+  const componentFiles: ParsedFile[] = [];
+  const workspaceFiles: ParsedFile[] = [];
+
+  for (const f of files) {
+    let parsed: ParsedSpec;
+    try {
+      parsed = parseSpecFile(f.abs);
+    } catch (err) {
+      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.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.`);
+
+  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)) {
+      unchanged++;
+    } else if (opts.dryRun) {
+      console.log(`~ ${path.relative(root, file.abs)} (would write ${universalRules.length} workspace rule(s))`);
+    } else {
+      rewriteManagedKeys(file.abs, { rules: universalRules });
+      written++;
+      console.log(`✓ ${path.relative(root, file.abs)} — ${universalRules.length} workspace rule(s)`);
+    }
+  }
+
+  for (const { file, parsed } of componentFiles) {
+    const specLike = parsed.spec as SpecLike;
+    const componentTags = specLike.tags ?? [];
+    const surfaces = specLike.surfaces ?? {};
+
+    const componentMatches = rulesForTags(allRules, componentTags);
+    const consumed = new Set<RuleResponse>(componentMatches);
+
+    const matchedRules: Array<Record<string, unknown>> = [];
+    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.relative(root, file.abs)} (would write ${matchedRules.length} rule(s))`);
+      continue;
+    }
+
+    rewriteManagedKeys(file.abs, { rules: matchedRules });
+    written++;
+    console.log(`✓ ${path.relative(root, file.abs)} — ${matchedRules.length} rule(s)`);
+  }
+
+  console.log(`\nDone. ${written} updated, ${unchanged} unchanged.`);
+}
+
+function rulesForTags(rules: RuleResponse[], tags: string[]): RuleResponse[] {
+  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: RuleResponse): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    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: string, rule: RuleResponse): Record<string, unknown> {
+  return { surface, ...toRuleObj(rule) };
+}
+
+function rulesMatch(existing: unknown, incoming: unknown): boolean {
+  return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
+}

package/src/config.ts

@@ -0,0 +1,55 @@
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+
+export interface Config {
+  apiBase: string;
+  workspaceId: string;
+  roots?: string[];
+}
+
+const DEFAULT_CONFIG_NAME = "dittospec.config.json";
+
+export function loadConfig(cwd: string = process.cwd()): { config: Config; root: string } {
+  let dir = path.resolve(cwd);
+  while (true) {
+    const candidate = path.join(dir, DEFAULT_CONFIG_NAME);
+    if (fs.existsSync(candidate)) {
+      const raw = fs.readFileSync(candidate, "utf8");
+      const parsed = JSON.parse(raw);
+      validate(parsed, candidate);
+      return { config: parsed as Config, root: dir };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`No ${DEFAULT_CONFIG_NAME} found from ${cwd} up to filesystem root.`);
+}
+
+function validate(c: unknown, source: string): asserts c is Config {
+  if (!c || typeof c !== "object") throw new Error(`${source}: must be a JSON object.`);
+  const obj = c as Record<string, unknown>;
+  if (typeof obj.apiBase !== "string") throw new Error(`${source}: missing string "apiBase".`);
+  if (typeof obj.workspaceId !== "string") throw new Error(`${source}: missing string "workspaceId".`);
+  if (obj.roots !== undefined && !Array.isArray(obj.roots)) {
+    throw new Error(`${source}: "roots" must be an array of strings if present.`);
+  }
+}
+
+export function getApiKey(): string {
+  try {
+    const { root } = loadConfig();
+    dotenv.config({ path: path.join(root, ".env") });
+  } catch {
+    // No config yet — let getApiKey still work for direct env exports.
+  }
+
+  const key = process.env.DITTO_API_KEY;
+  if (!key) {
+    throw new Error(
+      "DITTO_API_KEY is not set. Add it to .env at the repo root, or `export DITTO_API_KEY=...` in your shell."
+    );
+  }
+  return key;
+}

package/src/discover.ts

@@ -0,0 +1,23 @@
+import { globSync } from "glob";
+import path from "path";
+
+const SPEC_GLOB = "**/*.ditto.md";
+
+const IGNORE = ["**/node_modules/**", "**/dist*/**", "**/.git/**", "**/.next/**", "**/coverage/**"];
+
+export interface DiscoveredFile {
+  abs: string;
+  rel: string;
+}
+
+export function discover(repoRoot: string, roots: string[] = ["."]): DiscoveredFile[] {
+  const patterns = roots.map((r) => path.posix.join(r, SPEC_GLOB));
+
+  const results = globSync(patterns, {
+    cwd: repoRoot,
+    ignore: IGNORE,
+    absolute: true,
+  });
+
+  return results.map((abs) => ({ abs, rel: path.relative(repoRoot, abs) })).sort((a, b) => a.rel.localeCompare(b.rel));
+}

package/src/parse.ts

@@ -0,0 +1,45 @@
+import fs from "fs";
+import yaml from "js-yaml";
+
+export interface ParsedSpec {
+  kind: "component" | "workspace";
+  name?: string;
+  spec: Record<string, unknown>;
+  filePath: string;
+}
+
+export class ParseError extends Error {
+  constructor(public filePath: string, public reason: string) {
+    super(`${filePath}: ${reason}`);
+  }
+}
+
+export function parseSpecFile(filePath: string): ParsedSpec {
+  const source = fs.readFileSync(filePath, "utf8");
+  const frontmatter = extractFrontmatter(source, filePath);
+  const raw = yaml.load(frontmatter);
+
+  if (!raw || typeof raw !== "object") {
+    throw new ParseError(filePath, "frontmatter must be a YAML object");
+  }
+
+  const spec = raw as Record<string, unknown>;
+
+  if (spec.workspace === true) {
+    return { kind: "workspace", spec, filePath };
+  }
+
+  if (typeof spec.component !== "string" || !spec.component) {
+    throw new ParseError(filePath, "missing required 'component' key (string)");
+  }
+
+  return { kind: "component", name: spec.component, spec, filePath };
+}
+
+function extractFrontmatter(source: string, filePath: string): string {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) {
+    throw new ParseError(filePath, "no YAML frontmatter found (expected --- delimiters)");
+  }
+  return match[1];
+}

package/src/serialize.ts

@@ -0,0 +1,38 @@
+import fs from "fs";
+import yaml from "js-yaml";
+
+const MANAGED_COMMENT = "# Managed by Ditto — do not edit below";
+
+export function rewriteManagedKeys(filePath: string, updates: { rules?: unknown[] }): void {
+  const source = fs.readFileSync(filePath, "utf8");
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error(`${filePath}: no YAML frontmatter found`);
+
+  const spec = yaml.load(match[1]) as Record<string, unknown>;
+
+  if (updates.rules !== undefined) spec.rules = updates.rules;
+
+  let dumped = yaml
+    .dump(spec, {
+      lineWidth: -1,
+      noRefs: true,
+      sortKeys: false,
+      quotingType: '"',
+    })
+    .trimEnd();
+
+  dumped = insertManagedComment(dumped);
+
+  const afterFrontmatter = source.slice(match[0].length);
+  fs.writeFileSync(filePath, `---\n${dumped}\n---${afterFrontmatter}`);
+}
+
+function insertManagedComment(dumped: string): string {
+  const rulesIdx = dumped.search(/^rules:/m);
+  if (rulesIdx === -1) return dumped;
+
+  const before = dumped.slice(0, rulesIdx);
+  if (before.includes(MANAGED_COMMENT)) return dumped;
+
+  return before + MANAGED_COMMENT + "\n" + dumped.slice(rulesIdx);
+}