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

package/dist/commands/scaffold.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.scaffold = scaffold;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const config_1 = require("../config");
+const SPEC_FILENAME = "index.ditto.md";
+async function scaffold(opts) {
+    const dest = path_1.default.join(opts.targetDir, SPEC_FILENAME);
+    if (fs_1.default.existsSync(dest)) {
+        console.log(`${SPEC_FILENAME} already exists at ${opts.targetDir}. Nothing to do.`);
+        return;
+    }
+    const nameYaml = js_yaml_1.default.dump({ component: opts.componentName }, { lineWidth: -1 }).trimEnd();
+    const content = `---
+${nameYaml}
+tags: []
+surfaces: {}
+# Managed by Ditto — do not edit below
+rules: []
+---
+`;
+    fs_1.default.mkdirSync(opts.targetDir, { recursive: true });
+    fs_1.default.writeFileSync(dest, content);
+    console.log(`✓ Created ${path_1.default.relative(process.cwd(), dest)}`);
+    warnIfOutsideRoots(opts.targetDir);
+    console.log(`
+Next steps:
+  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`);
+}
+function warnIfOutsideRoots(targetDir) {
+    try {
+        const { config, root } = (0, config_1.loadConfig)();
+        const roots = config.roots ?? ["."];
+        const absTarget = path_1.default.resolve(targetDir);
+        const inside = roots.some((r) => absTarget.startsWith(path_1.default.resolve(root, r)));
+        if (!inside) {
+            console.log(`\n⚠ Target directory is outside configured roots (${roots.join(", ")}). This file won't be found by pull, check, or list.`);
+        }
+    }
+    catch (err) {
+        if (!(err instanceof config_1.ConfigNotFoundError))
+            throw err;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export interface Config {
+    apiBase: string;
+    workspaceId: string;
+    roots?: string[];
+}
+export declare class ConfigNotFoundError extends Error {
+    constructor(cwd: string);
+}
+export declare function loadConfig(cwd?: string): {
+    config: Config;
+    root: string;
+};
+export declare function getApiKey(): string;

package/dist/config.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigNotFoundError = void 0;
+exports.loadConfig = loadConfig;
+exports.getApiKey = getApiKey;
+const dotenv_1 = __importDefault(require("dotenv"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DEFAULT_CONFIG_NAME = "dittospec.config.json";
+class ConfigNotFoundError extends Error {
+    constructor(cwd) {
+        super(`No ${DEFAULT_CONFIG_NAME} found from ${cwd} up to filesystem root.`);
+    }
+}
+exports.ConfigNotFoundError = ConfigNotFoundError;
+function loadConfig(cwd = process.cwd()) {
+    let dir = path_1.default.resolve(cwd);
+    while (true) {
+        const candidate = path_1.default.join(dir, DEFAULT_CONFIG_NAME);
+        if (fs_1.default.existsSync(candidate)) {
+            const raw = fs_1.default.readFileSync(candidate, "utf8");
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`${candidate}: invalid JSON. Check for syntax errors.`);
+            }
+            validate(parsed, candidate);
+            return { config: parsed, root: dir };
+        }
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new ConfigNotFoundError(cwd);
+}
+function validate(c, source) {
+    if (!c || typeof c !== "object")
+        throw new Error(`${source}: must be a JSON object.`);
+    const obj = c;
+    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) {
+        if (!Array.isArray(obj.roots))
+            throw new Error(`${source}: "roots" must be an array of strings if present.`);
+        if (obj.roots.some((r) => typeof r !== "string")) {
+            throw new Error(`${source}: every entry in "roots" must be a string.`);
+        }
+    }
+}
+function getApiKey() {
+    try {
+        const { root } = loadConfig();
+        dotenv_1.default.config({ path: path_1.default.join(root, ".env") });
+    }
+    catch (err) {
+        if (!(err instanceof ConfigNotFoundError))
+            throw err;
+    }
+    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/dist/discover.d.ts

@@ -0,0 +1,5 @@
+export interface DiscoveredFile {
+    abs: string;
+    rel: string;
+}
+export declare function discover(repoRoot: string, roots?: string[]): DiscoveredFile[];

package/dist/discover.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discover = discover;
+const glob_1 = require("glob");
+const path_1 = __importDefault(require("path"));
+const SPEC_GLOB = "**/*.ditto.md";
+const IGNORE = ["**/node_modules/**", "**/dist*/**", "**/.git/**", "**/.next/**", "**/coverage/**"];
+function discover(repoRoot, roots = ["."]) {
+    const patterns = roots.map((r) => path_1.default.posix.join(r, SPEC_GLOB));
+    const results = (0, glob_1.globSync)(patterns, {
+        cwd: repoRoot,
+        ignore: IGNORE,
+        absolute: true,
+    });
+    return results.map((abs) => ({ abs, rel: path_1.default.relative(repoRoot, abs) })).sort((a, b) => a.rel.localeCompare(b.rel));
+}

package/dist/parse.d.ts

@@ -0,0 +1,24 @@
+export interface SurfaceLike {
+    tags?: string[];
+    maxLength?: number;
+}
+export interface SpecLike {
+    tags?: string[];
+    surfaces?: Record<string, SurfaceLike>;
+}
+export interface ParsedSpec {
+    kind: "component" | "workspace";
+    name?: string;
+    spec: Record<string, unknown>;
+    filePath: string;
+}
+export declare class ParseError extends Error {
+    filePath: string;
+    reason: string;
+    constructor(filePath: string, reason: string);
+}
+export declare function parseSpecFile(filePath: string): ParsedSpec;
+export declare function extractFrontmatter(source: string, filePath: string): {
+    yaml: string;
+    afterFrontmatter: string;
+};

package/dist/parse.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseError = void 0;
+exports.parseSpecFile = parseSpecFile;
+exports.extractFrontmatter = extractFrontmatter;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+class ParseError extends Error {
+    constructor(filePath, reason) {
+        super(`${filePath}: ${reason}`);
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+exports.ParseError = ParseError;
+function parseSpecFile(filePath) {
+    const source = fs_1.default.readFileSync(filePath, "utf8");
+    const { yaml: frontmatter } = extractFrontmatter(source, filePath);
+    const raw = js_yaml_1.default.load(frontmatter);
+    if (!raw || typeof raw !== "object") {
+        throw new ParseError(filePath, "frontmatter must be a YAML object");
+    }
+    const spec = raw;
+    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, filePath) {
+    const cleaned = source.replace(/^\uFEFF/, "");
+    const match = cleaned.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) {
+        throw new ParseError(filePath, "no YAML frontmatter found (expected --- delimiters)");
+    }
+    return { yaml: match[1], afterFrontmatter: cleaned.slice(match[0].length) };
+}

package/dist/serialize.d.ts

@@ -0,0 +1,4 @@
+export declare function rewriteManagedKeys(filePath: string, updates: {
+    tags?: string[];
+    rules?: unknown[];
+}): void;

package/dist/serialize.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rewriteManagedKeys = rewriteManagedKeys;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const parse_1 = require("./parse");
+const MANAGED_COMMENT = "# Managed by Ditto — do not edit below";
+function rewriteManagedKeys(filePath, updates) {
+    const source = fs_1.default.readFileSync(filePath, "utf8");
+    const { yaml: frontmatterYaml, afterFrontmatter } = (0, parse_1.extractFrontmatter)(source, filePath);
+    const spec = js_yaml_1.default.load(frontmatterYaml);
+    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 = js_yaml_1.default
+        .dump(spec, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: false,
+        quotingType: '"',
+    })
+        .trimEnd();
+    dumped = insertManagedComment(dumped, updates.tags !== undefined);
+    fs_1.default.writeFileSync(filePath, `---\n${dumped}\n---${afterFrontmatter}`);
+}
+function insertManagedComment(dumped, managedTagsPresent) {
+    const targetKey = managedTagsPresent ? "tags" : "rules";
+    const idx = dumped.search(new RegExp(`^${targetKey}:`, "m"));
+    if (idx === -1)
+        return dumped;
+    const before = dumped.slice(0, idx);
+    if (before.includes(MANAGED_COMMENT))
+        return dumped;
+    return before + MANAGED_COMMENT + "\n" + dumped.slice(idx);
+}

package/package.json

@@ -1,19 +1,32 @@
 {
   "name": "@dittowords/spec-cli",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.4",
   "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
-  "main": "src/cli.ts",
+  "main": "dist/cli.js",
   "bin": {
-    "ditto-spec": "src/bin.js"
+    "ditto-spec": "dist/bin.js"
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
     "ditto-spec": "tsx src/cli.ts"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "dotenv": "^16.0.0",
     "glob": "^11.0.1",
-    "js-yaml": "^4.1.0",
-    "tsx": "^4.0.0"
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
   },
   "license": "Proprietary"
 }

package/src/api.ts

@@ -1,45 +0,0 @@
-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

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

package/src/cli.ts

@@ -1,70 +0,0 @@
-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.
-
-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/src/commands/check.ts

@@ -1,48 +0,0 @@
-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);
-  }
-}