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

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:
@@ -46,31 +43,29 @@ rules:
     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.
+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
+tags: [body, button, call-to-action, dialog-title, heading, nav]
 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`. 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** 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).
 
@@ -100,7 +95,7 @@ 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`
 
@@ -143,23 +138,23 @@ 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:
+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. When a rule includes `examples`, reference them as concrete tone/shape guidance.
 
 ### 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 +166,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,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 {};