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

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.
@@ -52,7 +52,7 @@ 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
 ---
@@ -60,6 +60,7 @@ 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: []
 ---
 ```
@@ -68,9 +69,9 @@ rules: []
 
 **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.
+**CLI-managed keys**: `rules`, `examples`, 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 +101,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 +144,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.
 
 ### 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 +172,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`.
+- 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.
 
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dittowords/spec-cli",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.1-alpha.3",
   "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
   "main": "src/cli.ts",
   "bin": {

package/src/commands/init.ts

@@ -19,6 +19,7 @@ workspace: true
 description: >
   Workspace-wide content rules. Read alongside any component's index.ditto.md.
 # Managed by Ditto — do not edit below
+tags: []
 rules: []
 ---
 `;
@@ -39,11 +40,11 @@ When writing or editing text props for a component:
 
 ### 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:
 
     surfaces:
       title:
@@ -53,10 +54,12 @@ Then edit the generated \`index.ditto.md\` to add surfaces — one entry per tex
         tags: [button, cta]
         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\`.
+- 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 \`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 \`npx ditto-spec list\` to see all existing specs.
 `;
 
@@ -76,11 +79,11 @@ When writing or editing text props for a component:
 
 ## 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:
 
     surfaces:
       title:
@@ -90,10 +93,12 @@ Then edit the generated index.ditto.md to add surfaces — one entry per text-be
         tags: [button, cta]
         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.
+- 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 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 npx ditto-spec list to see all existing specs.
 `;
 

package/src/commands/pull.ts

@@ -59,6 +59,8 @@ export async function pull(opts: PullOptions = {}): Promise<void> {
   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;
 
@@ -66,14 +68,20 @@ export async function pull(opts: PullOptions = {}): Promise<void> {
     const { file, parsed } = workspaceFiles[0];
     const universalRules = allRules.filter((r) => r.tags.length === 0).map(toRuleObj);
 
-    if (rulesMatch(parsed.spec.rules, universalRules)) {
+    if (rulesMatch(parsed.spec.rules, universalRules) && tagsMatch(parsed.spec.tags, platformTags)) {
       unchanged++;
     } else if (opts.dryRun) {
-      console.log(`~ ${path.relative(root, file.abs)} (would write ${universalRules.length} workspace rule(s))`);
+      console.log(
+        `~ ${path.relative(root, file.abs)} (would write ${universalRules.length} workspace rule(s), ${
+          platformTags.length
+        } tag(s))`
+      );
     } else {
-      rewriteManagedKeys(file.abs, { rules: universalRules });
+      rewriteManagedKeys(file.abs, { tags: platformTags, rules: universalRules });
       written++;
-      console.log(`✓ ${path.relative(root, file.abs)} — ${universalRules.length} workspace rule(s)`);
+      console.log(
+        `✓ ${path.relative(root, file.abs)} — ${universalRules.length} workspace rule(s), ${platformTags.length} tag(s)`
+      );
     }
   }
 
@@ -138,3 +146,7 @@ function toSurfaceRuleObj(surface: string, rule: RuleResponse): Record<string, u
 function rulesMatch(existing: unknown, incoming: unknown): boolean {
   return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
 }
+
+function tagsMatch(existing: unknown, incoming: string[]): boolean {
+  return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
+}

package/src/commands/scaffold.ts

@@ -34,7 +34,7 @@ examples: []
 
   console.log(`
 Next steps:
-  1. Add text-bearing props as surface keys under 'surfaces'
+  1. Add a surface key for each piece of user-facing text the component renders
   2. Tag each surface with content categories (heading, body, button, cta, etc.)
   3. Run \`ditto-spec pull\` to populate rules from the platform`);
 }

package/src/serialize.ts

@@ -3,13 +3,19 @@ import yaml from "js-yaml";
 
 const MANAGED_COMMENT = "# Managed by Ditto — do not edit below";
 
-export function rewriteManagedKeys(filePath: string, updates: { rules?: unknown[] }): void {
+export function rewriteManagedKeys(filePath: string, updates: { tags?: string[]; 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.tags !== undefined) {
+    const savedRules = spec.rules;
+    delete spec.rules;
+    spec.tags = updates.tags;
+    spec.rules = savedRules;
+  }
   if (updates.rules !== undefined) spec.rules = updates.rules;
 
   let dumped = yaml
@@ -21,18 +27,19 @@ export function rewriteManagedKeys(filePath: string, updates: { rules?: unknown[
     })
     .trimEnd();
 
-  dumped = insertManagedComment(dumped);
+  dumped = insertManagedComment(dumped, updates.tags !== undefined);
 
   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;
+function insertManagedComment(dumped: string, managedTagsPresent: boolean): string {
+  const targetKey = managedTagsPresent ? "tags" : "rules";
+  const idx = dumped.search(new RegExp(`^${targetKey}:`, "m"));
+  if (idx === -1) return dumped;
 
-  const before = dumped.slice(0, rulesIdx);
+  const before = dumped.slice(0, idx);
   if (before.includes(MANAGED_COMMENT)) return dumped;
 
-  return before + MANAGED_COMMENT + "\n" + dumped.slice(rulesIdx);
+  return before + MANAGED_COMMENT + "\n" + dumped.slice(idx);
 }