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

package/README.md

@@ -92,6 +92,16 @@ First-time setup. Creates `dittospec.config.json` and `workspace.ditto.md` in th
 
 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 scaffold <ComponentName>`
+
+Creates a new `index.ditto.md` for a component with the correct YAML structure and empty managed keys.
+
+```
+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.
+
 ### `ditto-spec pull`
 
 Syncs rules from the platform into spec files.
@@ -143,6 +153,26 @@ When writing or editing text props for a component:
 
 ### 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`.
+When creating a new component with text-bearing props, 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:
+
+```yaml
+surfaces:
+  title:
+    tags: [heading]
+    maxLength: 60
+  $children:
+    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`.
+- **Never write `rules` or `examples` by hand.** Run `ditto-spec pull` after adding surfaces to populate rules from the platform.
 
 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.0",
+  "version": "0.0.1-alpha.2",
   "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
   "main": "src/cli.ts",
   "bin": {

package/src/cli.ts

@@ -2,12 +2,23 @@ import { check } from "./commands/check";
 import { init } from "./commands/init";
 import { list } from "./commands/list";
 import { pull } from "./commands/pull";
+import { scaffold } from "./commands/scaffold";
 
 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(),
+  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 scaffold({ componentName: name, targetDir });
+  },
 };
 
 const HELP = `ditto-spec — sync .ditto.md content specs with the Ditto platform.
@@ -18,6 +29,8 @@ Usage:
 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.

package/src/commands/init.ts

@@ -26,7 +26,9 @@ rules: []
 const CLAUDE_MD_BLOCK = `
 ## Ditto Content Specs
 
-This project uses \`.ditto.md\` files for component content governance.
+This project uses \`.ditto.md\` files to declare text surfaces on components. Rules are synced from the Ditto platform — never written by hand.
+
+### Reading specs
 
 When writing or editing text props for a component:
 
@@ -34,15 +36,36 @@ When writing or editing text props for a component:
 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).
+### Creating specs
+
+When creating a new component with text-bearing props, 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:
+
+    surfaces:
+      title:
+        tags: [heading]
+        maxLength: 60
+      $children:
+        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\`.
+- **Never write \`rules\` or \`examples\` by hand.** Run \`npx ditto-spec pull\` after adding surfaces to populate rules from the platform.
+
+Run \`npx ditto-spec list\` to see all existing specs.
 `;
 
 const CURSOR_RULES_BLOCK = `
 # Ditto Content Specs
 
-This project uses .ditto.md files for component content governance.
+This project uses .ditto.md files to declare text surfaces on components. Rules are synced from the Ditto platform — never written by hand.
+
+## Reading specs
 
 When writing or editing text props for a component:
 
@@ -50,7 +73,28 @@ When writing or editing text props for a component:
 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.
+
+## Creating specs
+
+When creating a new component with text-bearing props, 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:
+
+    surfaces:
+      title:
+        tags: [heading]
+        maxLength: 60
+      $children:
+        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.
+- NEVER write rules or examples by hand. Run npx ditto-spec pull after adding surfaces to populate rules from the platform.
+
+Run npx ditto-spec list to see all existing specs.
 `;
 
 const AGENTS_MD_ROW =
@@ -65,16 +109,21 @@ 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))) {
+  const configExists = fs.existsSync(path.join(cwd, CONFIG_NAME));
+
+  if (configExists && !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;
   }
 
-  fs.writeFileSync(path.join(cwd, CONFIG_NAME), DEFAULT_CONFIG + "\n");
-  console.log(`✓ Created ${CONFIG_NAME}`);
+  if (!configExists) {
+    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}`);
+    fs.writeFileSync(path.join(cwd, WORKSPACE_SPEC_NAME), WORKSPACE_SPEC);
+    console.log(`✓ Created ${WORKSPACE_SPEC_NAME}`);
+  }
 
   const env = detectAgentEnv(cwd);
 
@@ -84,7 +133,9 @@ export async function init(opts: InitOptions = {}): Promise<void> {
     printAgentSuggestions(env);
   }
 
-  printNextSteps();
+  if (!configExists) {
+    printNextSteps();
+  }
 }
 
 function detectAgentEnv(cwd: string): AgentEnv {

package/src/commands/scaffold.ts

@@ -0,0 +1,40 @@
+import fs from "fs";
+import path from "path";
+
+const SPEC_FILENAME = "index.ditto.md";
+
+interface ScaffoldOptions {
+  componentName: string;
+  targetDir: string;
+}
+
+export async function scaffold(opts: ScaffoldOptions): Promise<void> {
+  const dest = path.join(opts.targetDir, SPEC_FILENAME);
+
+  if (fs.existsSync(dest)) {
+    console.log(`${SPEC_FILENAME} already exists at ${opts.targetDir}. Nothing to do.`);
+    return;
+  }
+
+  const content = `---
+component: ${opts.componentName}
+description: >
+  TODO: describe this component.
+tags: []
+surfaces: {}
+# Managed by Ditto — do not edit below
+rules: []
+examples: []
+---
+`;
+
+  fs.mkdirSync(opts.targetDir, { recursive: true });
+  fs.writeFileSync(dest, content);
+  console.log(`✓ Created ${path.relative(process.cwd(), dest)}`);
+
+  console.log(`
+Next steps:
+  1. Add text-bearing props as surface keys under 'surfaces'
+  2. Tag each surface with content categories (heading, body, button, cta, etc.)
+  3. Run \`ditto-spec pull\` to populate rules from the platform`);
+}