@dittowords/spec-cli 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/commands/init.js

@@ -0,0 +1,237 @@
+"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 skills_1 = require("../skills");
+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.
+5. Rules come in two shapes: style rules (${c("name")}, ${c("description")}, ${c("examples")}) and terminology entries (${c("term")}, ${c("disallowed")}). For terminology entries, always use the ${c("term")} form and never use the ${c("disallowed")} alternatives.
+6. Each rule carries a ${c("section")} field (e.g. "Voice & Tone", "Terminology") providing context for how to interpret it.
+7. If a ${c("locales")} key is present, it contains locale-scoped rules keyed by locale code. When writing copy for a specific locale, follow the matching locale's rules in addition to the base ${c("rules")}. When writing for the default locale, only follow ${c("rules")}.
+
+${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, opts.force);
+    }
+    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, force) {
+    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");
+        }
+        writeSkillFiles(cwd, force);
+        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 writeSkillFiles(cwd, force) {
+    const commandsDir = path_1.default.join(cwd, ".claude", "commands");
+    fs_1.default.mkdirSync(commandsDir, { recursive: true });
+    let written = 0;
+    let unchanged = 0;
+    const skipped = [];
+    for (const [filename, content] of Object.entries(skills_1.SKILLS)) {
+        const filePath = path_1.default.join(commandsDir, filename);
+        if (fs_1.default.existsSync(filePath)) {
+            const existing = fs_1.default.readFileSync(filePath, "utf8");
+            if (existing === content) {
+                unchanged++;
+                continue;
+            }
+            if (!force) {
+                skipped.push(filename);
+                continue;
+            }
+        }
+        fs_1.default.writeFileSync(filePath, content);
+        written++;
+    }
+    if (written > 0) {
+        console.log(`✓ Wrote ${written} skill file(s) to .claude/commands/`);
+    }
+    if (unchanged > 0) {
+        console.log(`  ${unchanged} skill file(s) already up to date.`);
+    }
+    if (skipped.length > 0) {
+        console.log(`⚠ Skipped ${skipped.length} locally modified skill file(s): ${skipped.join(", ")}`);
+        console.log("  Re-run with --force to overwrite.");
+    }
+}
+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 {};

package/dist/commands/pull.js

@@ -0,0 +1,168 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pull = pull;
+const path_1 = __importDefault(require("path"));
+const api_1 = require("../api");
+const config_1 = require("../config");
+const discover_1 = require("../discover");
+const parse_1 = require("../parse");
+const serialize_1 = require("../serialize");
+async function pull(opts = {}) {
+    const { config, root } = (0, config_1.loadConfig)();
+    const apiKey = (0, config_1.getApiKey)();
+    const api = new api_1.DittoApi(config, apiKey);
+    const files = (0, discover_1.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"}.`);
+    const componentFiles = [];
+    const workspaceFiles = [];
+    let failed = 0;
+    for (const f of files) {
+        let parsed;
+        try {
+            parsed = (0, parse_1.parseSpecFile)(f.abs);
+        }
+        catch (err) {
+            failed++;
+            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_1.default.relative(root, w.file.abs)).join(", ");
+        throw new Error(`Found multiple workspace specs (${paths}). Expected at most one.`);
+    }
+    const guides = await api.getStyleguides();
+    const allRules = (0, api_1.flattenStyleguides)(guides, config.styleguides);
+    const baseRules = allRules.filter((r) => r.localeCode === null);
+    const configuredLocales = config.locales ?? [];
+    const localeRules = configuredLocales.length > 0
+        ? allRules.filter((r) => r.localeCode !== null && configuredLocales.includes(r.localeCode))
+        : [];
+    const localeGroups = groupByLocale(localeRules);
+    const activeRules = [...baseRules, ...localeRules];
+    console.log(`Fetched ${activeRules.length} rule${activeRules.length === 1 ? "" : "s"} from ${guides.length} style guide(s).`);
+    const platformTags = [...new Set(activeRules.flatMap((r) => r.tags))].filter(Boolean).sort();
+    let written = 0;
+    let unchanged = 0;
+    if (workspaceFiles.length === 1) {
+        const { file, parsed } = workspaceFiles[0];
+        const universalBaseRules = baseRules.filter((r) => r.tags.length === 0).map(toRuleObj);
+        const universalLocales = {};
+        for (const [code, rules] of localeGroups) {
+            const universal = rules.filter((r) => r.tags.length === 0).map(toRuleObj);
+            if (universal.length > 0)
+                universalLocales[code] = universal;
+        }
+        if (jsonMatch(parsed.spec.rules, universalBaseRules) &&
+            jsonMatch(parsed.spec.tags, platformTags) &&
+            jsonMatch(parsed.spec.locales, Object.keys(universalLocales).length > 0 ? universalLocales : undefined)) {
+            unchanged++;
+        }
+        else if (opts.dryRun) {
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${universalBaseRules.length} workspace rule(s), ${platformTags.length} tag(s), ${Object.keys(universalLocales).length} locale(s))`);
+        }
+        else {
+            (0, serialize_1.rewriteManagedKeys)(file.abs, { tags: platformTags, rules: universalBaseRules, locales: universalLocales });
+            written++;
+            console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${universalBaseRules.length} workspace rule(s), ${platformTags.length} tag(s), ${Object.keys(universalLocales).length} locale(s)`);
+        }
+    }
+    for (const { file, parsed } of componentFiles) {
+        const specLike = parsed.spec;
+        const componentTags = specLike.tags ?? [];
+        const surfaces = specLike.surfaces ?? {};
+        const matchedBaseRules = matchRulesForSpec(baseRules, componentTags, surfaces);
+        const matchedLocales = {};
+        for (const [code, rules] of localeGroups) {
+            const matched = matchRulesForSpec(rules, componentTags, surfaces);
+            if (matched.length > 0)
+                matchedLocales[code] = matched;
+        }
+        if (jsonMatch(parsed.spec.rules, matchedBaseRules) &&
+            jsonMatch(parsed.spec.locales, Object.keys(matchedLocales).length > 0 ? matchedLocales : undefined)) {
+            unchanged++;
+            continue;
+        }
+        if (opts.dryRun) {
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${matchedBaseRules.length} rule(s), ${Object.keys(matchedLocales).length} locale(s))`);
+            continue;
+        }
+        (0, serialize_1.rewriteManagedKeys)(file.abs, { rules: matchedBaseRules, locales: matchedLocales });
+        written++;
+        console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${matchedBaseRules.length} rule(s), ${Object.keys(matchedLocales).length} locale(s)`);
+    }
+    console.log(`\nDone. ${written} updated, ${unchanged} unchanged.`);
+    if (failed > 0) {
+        console.error(`${failed} file(s) failed to parse.`);
+        process.exit(1);
+    }
+}
+function matchRulesForSpec(rules, componentTags, surfaces) {
+    const componentMatches = rulesForTags(rules, componentTags);
+    const consumed = new Set(componentMatches);
+    const matched = [];
+    for (const rule of componentMatches) {
+        matched.push(toRuleObj(rule));
+    }
+    for (const [surfaceKey, surface] of Object.entries(surfaces)) {
+        const surfaceMatches = rulesForTags(rules, surface.tags ?? []).filter((r) => !consumed.has(r));
+        for (const rule of surfaceMatches) {
+            matched.push(toSurfaceRuleObj(surfaceKey, rule));
+        }
+    }
+    return matched;
+}
+function groupByLocale(rules) {
+    const groups = new Map();
+    for (const rule of rules) {
+        const code = rule.localeCode;
+        if (!groups.has(code))
+            groups.set(code, []);
+        groups.get(code).push(rule);
+    }
+    return groups;
+}
+function rulesForTags(rules, tags) {
+    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) {
+    const out = {};
+    if (rule.kind === "wordlist") {
+        out.term = rule.term;
+        out.disallowed = rule.disallowed;
+        if (rule.description)
+            out.description = rule.description;
+    }
+    else {
+        out.name = rule.name;
+        if (rule.description)
+            out.description = rule.description;
+        if (rule.examples.length > 0) {
+            out.examples = rule.examples.map((ex) => ({ from: ex.from, to: ex.to }));
+        }
+    }
+    out.section = rule.section;
+    return out;
+}
+function toSurfaceRuleObj(surface, rule) {
+    return { surface, ...toRuleObj(rule) };
+}
+function jsonMatch(existing, incoming) {
+    return JSON.stringify(existing ?? undefined) === JSON.stringify(incoming ?? undefined);
+}

package/dist/commands/scaffold.d.ts

@@ -0,0 +1,6 @@
+interface ScaffoldOptions {
+    componentName: string;
+    targetDir: string;
+}
+export declare function scaffold(opts: ScaffoldOptions): Promise<void>;
+export {};

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,18 @@
+export interface Config {
+    apiBase: string;
+    workspaceId: string;
+    roots?: string[];
+    styleguides?: string[];
+    locales?: string[];
+    defaultStyleguide?: string;
+    /** @deprecated Use defaultStyleguide instead. */
+    styleguideId?: 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,101 @@
+"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);
+            const config = parsed;
+            if (config.styleguideId && !config.defaultStyleguide) {
+                config.defaultStyleguide = config.styleguideId;
+            }
+            return { config, 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.`);
+        }
+    }
+    if (obj.styleguides !== undefined) {
+        if (!Array.isArray(obj.styleguides))
+            throw new Error(`${source}: "styleguides" must be an array of strings if present.`);
+        if (obj.styleguides.some((s) => typeof s !== "string")) {
+            throw new Error(`${source}: every entry in "styleguides" must be a string.`);
+        }
+    }
+    if (obj.locales !== undefined) {
+        if (!Array.isArray(obj.locales))
+            throw new Error(`${source}: "locales" must be an array of strings if present.`);
+        if (obj.locales.some((l) => typeof l !== "string")) {
+            throw new Error(`${source}: every entry in "locales" must be a string.`);
+        }
+    }
+    if (obj.defaultStyleguide !== undefined) {
+        if (typeof obj.defaultStyleguide !== "string")
+            throw new Error(`${source}: "defaultStyleguide" must be a string if present.`);
+    }
+    if (obj.styleguideId !== undefined) {
+        if (typeof obj.styleguideId !== "string")
+            throw new Error(`${source}: "styleguideId" must be a string if present.`);
+    }
+    if (obj.defaultStyleguide !== undefined && obj.styleguideId !== undefined) {
+        throw new Error(`${source}: specify "defaultStyleguide" or "styleguideId", not both.`);
+    }
+}
+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,24 @@
+"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 fs_1 = __importDefault(require("fs"));
+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,
+    });
+    const workspacePath = path_1.default.resolve(repoRoot, "workspace.ditto.md");
+    if (fs_1.default.existsSync(workspacePath) && !results.includes(workspacePath)) {
+        results.push(workspacePath);
+    }
+    return results.map((abs) => ({ abs, rel: path_1.default.relative(repoRoot, abs) })).sort((a, b) => a.rel.localeCompare(b.rel));
+}