whale-igniter 1.1.0

package/dist/generators/wikiGenerator.js

@@ -0,0 +1,365 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { loadConfig } from "../utils/config.js";
+import { loadRefinements } from "../utils/refinements.js";
+import { loadDecisions } from "../utils/decisions.js";
+import { loadComponents } from "../utils/components.js";
+import { validateCss } from "../validators/cssValidator.js";
+export async function generateWiki(target) {
+    const config = await loadConfig(target);
+    const refinements = await loadRefinements(target);
+    const decisions = await loadDecisions(target);
+    const components = await loadComponents(target);
+    const issues = await validateCss(target);
+    const errors = issues.filter((i) => i.severity === "error").length;
+    const warnings = issues.filter((i) => i.severity === "warning").length;
+    const wikiDir = path.join(target, "llm-wiki");
+    await fs.ensureDir(wikiDir);
+    // ---- llm-wiki/ themed files ------------------------------------------------
+    const themedFiles = {
+        "README.md": renderWikiReadme(config),
+        "PROJECT.md": renderProject(config, errors, warnings, refinements.length, decisions.length),
+        "FOUNDATIONS.md": renderFoundations(config),
+        "CONVENTIONS.md": renderConventions(config, refinements),
+        "DECISIONS.md": renderDecisions(decisions),
+        "COMPONENTS.md": renderComponents(components),
+        "WORKFLOWS.md": renderWorkflows(config)
+    };
+    const wikiFiles = [];
+    for (const [name, content] of Object.entries(themedFiles)) {
+        const filePath = path.join(wikiDir, name);
+        await fs.writeFile(filePath, content);
+        wikiFiles.push(filePath);
+    }
+    // ---- root-level AI entry points -------------------------------------------
+    const rootIndex = renderRootIndex(config, {
+        errors,
+        warnings,
+        refinementCount: refinements.length,
+        decisionCount: decisions.length,
+        componentCount: components.length
+    });
+    const rootFiles = [];
+    const targets = config.aiTargets ?? ["claude"];
+    // CLAUDE.md is always written (default reader). Other agent files mirror it.
+    const filenamesByTarget = {
+        claude: "CLAUDE.md",
+        codex: "AGENTS.md", // OpenAI Codex / agents.md convention
+        cursor: ".cursorrules",
+        copilot: ".github/copilot-instructions.md"
+    };
+    // Always emit CLAUDE.md as the canonical file, even if claude isn't listed.
+    const written = new Set();
+    const emit = async (filename) => {
+        if (written.has(filename))
+            return;
+        written.add(filename);
+        const filePath = path.join(target, filename);
+        await fs.ensureDir(path.dirname(filePath));
+        await fs.writeFile(filePath, rootIndex);
+        rootFiles.push(filePath);
+    };
+    await emit("CLAUDE.md");
+    for (const t of targets) {
+        await emit(filenamesByTarget[t]);
+    }
+    return { rootFiles, wikiFiles };
+}
+// ----------------------------------------------------------------------------
+// Renderers
+// ----------------------------------------------------------------------------
+function renderRootIndex(config, stats) {
+    const name = config.projectName ?? "this project";
+    const grid = config.foundations?.grid ?? 8;
+    const ctrl = config.foundations?.radius?.control ?? 2;
+    const cont = config.foundations?.radius?.container ?? 4;
+    const stack = config.stack ?? "css";
+    const packs = (config.packs ?? []).join(", ") || "(none)";
+    return `# AI Agent Context — ${name}
+
+> This file is auto-generated by [Whale Igniter](https://github.com/whale-igniter).
+> Do not edit by hand. Run \`whale sync\` after changes to regenerate.
+
+You are working in a project managed by Whale Igniter. Whale maintains
+machine-readable operational context so AI agents understand the design
+system, conventions and decisions without re-explaining them every session.
+
+## Quick facts
+
+- **Project type:** ${config.projectType ?? "unspecified"}
+- **Stack:** ${stack}
+- **Grid:** ${grid}px (all spacing must be a multiple)
+- **Border radius:** ${ctrl}px (controls), ${cont}px (containers)
+- **Active packs:** ${packs}
+- **Validation status:** ${stats.errors} error(s), ${stats.warnings} warning(s)
+- **Decisions logged:** ${stats.decisionCount}
+- **Refinements active:** ${stats.refinementCount}
+- **Components catalogued:** ${stats.componentCount}
+
+## How to read this project
+
+Whale stores structured context in two locations:
+
+1. **\`intelligence/\`** — source of truth (JSON). Read these when you need precise data:
+   - \`intelligence/refinements.json\` — validator overrides the team has accepted
+   - \`intelligence/decisions.json\` — architectural and product decisions
+   - \`intelligence/components.json\` — catalog of components in the project
+
+2. **\`llm-wiki/\`** — human + AI readable markdown rendered from the JSON:
+   - \`llm-wiki/FOUNDATIONS.md\` — design tokens and grid rules
+   - \`llm-wiki/CONVENTIONS.md\` — coding and design conventions
+   - \`llm-wiki/DECISIONS.md\` — decision log in narrative form
+   - \`llm-wiki/COMPONENTS.md\` — component catalog
+   - \`llm-wiki/WORKFLOWS.md\` — how the team uses Whale day to day
+
+If a question can be answered from \`intelligence/*.json\`, prefer that file —
+it's the source. The wiki is a rendered view.
+
+## Rules you must follow
+
+1. **Spacing.** Every padding, margin and gap must be a multiple of \`${grid}px\`.
+2. **Radius.** Buttons, inputs, selects use \`${ctrl}px\`. Cards, modals, sheets use \`${cont}px\`.
+3. **Color.** Prefer semantic tokens over raw hex. If you must add a hex,
+   record a refinement explaining why.
+4. **Focus.** Every interactive element needs a visible \`:focus-visible\` state.
+5. **Decisions.** When you make a non-obvious choice, propose recording it via
+   \`whale decision\` so future sessions inherit the reasoning.
+6. **Refinements.** Honor entries in \`intelligence/refinements.json\` —
+   they encode intentional exceptions the team approved.
+
+## When the user asks you to add a component
+
+Before writing code:
+- Check \`intelligence/components.json\` to see if it already exists.
+- Check \`llm-wiki/FOUNDATIONS.md\` for the tokens to use.
+- After creating it, suggest the user run \`whale component add <name>\`
+  so future agents know it exists.
+
+## Commands available
+
+- \`whale validate\` — runs the validators, exits non-zero on errors
+- \`whale refine "<note>"\` — record a validator override
+- \`whale decision\` — record an architectural decision (interactive)
+- \`whale component add <name>\` — register a component
+- \`whale sync\` — regenerate this file and the wiki
+- \`whale docs\` — generate human-facing reports
+
+---
+_Last sync: ${new Date().toISOString()}_
+`;
+}
+function renderWikiReadme(config) {
+    return `# LLM Wiki
+
+This directory is generated by Whale Igniter. It contains a human-and-AI
+readable view of the project's operational context.
+
+**Do not edit these files directly** — they are regenerated from
+\`intelligence/*.json\` and \`whale.config.json\` whenever you run
+\`whale sync\`.
+
+## Files
+
+- \`PROJECT.md\` — high-level project facts
+- \`FOUNDATIONS.md\` — grid, radius, tokens
+- \`CONVENTIONS.md\` — active conventions and refinements
+- \`DECISIONS.md\` — decision log
+- \`COMPONENTS.md\` — component catalog
+- \`WORKFLOWS.md\` — recommended usage flow
+
+## For AI agents
+
+The canonical entry point for AI agents is \`/CLAUDE.md\` at the project root.
+This wiki is the detailed view — start with the root file, drill in here.
+
+_Generated by Whale Igniter v0.7._
+`;
+}
+function renderProject(config, errors, warnings, refinementCount, decisionCount) {
+    return `# Project Context
+
+- **Project name:** ${config.projectName ?? "(unset)"}
+- **Project type:** ${config.projectType ?? "unspecified"}
+- **Stack:** ${config.stack ?? "css"}
+- **AI targets:** ${(config.aiTargets ?? []).join(", ") || "(none)"}
+- **Active packs:** ${(config.packs ?? []).join(", ") || "(none)"}
+- **Ignited:** ${config.ignited?.at ?? "(not yet)"} (${config.ignited?.mode ?? "—"})
+
+## Current status
+
+- Validation errors: ${errors}
+- Validation warnings: ${warnings}
+- Decisions logged: ${decisionCount}
+- Active refinements: ${refinementCount}
+
+_Generated by Whale Igniter._
+`;
+}
+function renderFoundations(config) {
+    const grid = config.foundations?.grid ?? 8;
+    const ctrl = config.foundations?.radius?.control ?? 2;
+    const cont = config.foundations?.radius?.container ?? 4;
+    return `# Foundations
+
+The invariants of this project. All UI must conform unless explicitly refined.
+
+## Spacing
+
+Grid unit: **${grid}px**.
+
+Every padding, margin and gap should be a multiple of ${grid}px. The allowed
+scale is:
+
+\`\`\`
+${[1, 2, 3, 4, 5, 6, 8, 10, 12].map((n) => `${n * grid}px`).join("  ")}
+\`\`\`
+
+## Radius
+
+| Use            | Value   |
+| -------------- | ------- |
+| Controls       | ${ctrl}px |
+| Containers     | ${cont}px |
+
+Controls = buttons, inputs, selects, toggles. Containers = cards, modals,
+sheets, popovers.
+
+## Tone & accent
+
+- Tone: ${config.branding?.tone ?? "(unset)"}
+- Accent: ${config.branding?.accent ?? "(unset)"}
+
+_Generated by Whale Igniter._
+`;
+}
+function renderConventions(config, refinements) {
+    const lines = [
+        "# Conventions",
+        "",
+        "## Rules",
+        "",
+        `- Spacing is a multiple of ${config.foundations?.grid ?? 8}px.`,
+        "- Controls and containers use distinct radius values (see FOUNDATIONS.md).",
+        "- Every interactive element has a visible \`:focus-visible\` state.",
+        "- Prefer semantic tokens over raw color values.",
+        "",
+        "## Active refinements",
+        ""
+    ];
+    if (refinements.length === 0) {
+        lines.push("_No refinements recorded yet._");
+    }
+    else {
+        lines.push("These are exceptions the team has explicitly approved. The validator", "suppresses matching issues.", "");
+        for (const r of refinements) {
+            const scopeParts = [];
+            if (r.scope?.issueType)
+                scopeParts.push(`type=\`${r.scope.issueType}\``);
+            if (r.scope?.selector)
+                scopeParts.push(`selector=\`${r.scope.selector}\``);
+            if (r.scope?.file)
+                scopeParts.push(`file=\`${r.scope.file}\``);
+            const scope = scopeParts.length ? ` _(${scopeParts.join(", ")})_` : "";
+            lines.push(`- **${r.timestamp.slice(0, 10)}** — ${r.note}${scope}`);
+        }
+    }
+    lines.push("", "_Generated by Whale Igniter._");
+    return lines.join("\n");
+}
+function renderDecisions(decisions) {
+    const lines = [
+        "# Decision Log",
+        "",
+        "Architectural, product and tooling decisions, in reverse chronological order.",
+        ""
+    ];
+    if (decisions.length === 0) {
+        lines.push("_No decisions logged yet. Use `whale decision` to record one._");
+    }
+    else {
+        const sorted = [...decisions].sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        for (const d of sorted) {
+            lines.push(`## ${d.title}`);
+            lines.push("");
+            lines.push(`- **Date:** ${d.timestamp.slice(0, 10)}`);
+            lines.push(`- **Category:** ${d.category}`);
+            lines.push(`- **Status:** ${d.status}`);
+            if (d.context) {
+                lines.push("", "**Context**", "", d.context);
+            }
+            lines.push("", "**Decision**", "", d.decision);
+            if (d.consequences) {
+                lines.push("", "**Consequences**", "", d.consequences);
+            }
+            lines.push("", "---", "");
+        }
+    }
+    lines.push("_Generated by Whale Igniter._");
+    return lines.join("\n");
+}
+function renderComponents(components) {
+    const lines = ["# Component Catalog", ""];
+    if (components.length === 0) {
+        lines.push("_No components catalogued yet. Use `whale component add <name>` to register one._");
+    }
+    else {
+        const sorted = [...components].sort((a, b) => a.name.localeCompare(b.name));
+        for (const c of sorted) {
+            lines.push(`## ${c.name}`);
+            lines.push("");
+            if (c.description)
+                lines.push(c.description, "");
+            const meta = [];
+            if (c.category)
+                meta.push(`Category: ${c.category}`);
+            if (c.variants?.length)
+                meta.push(`Variants: ${c.variants.join(", ")}`);
+            if (c.states?.length)
+                meta.push(`States: ${c.states.join(", ")}`);
+            if (meta.length)
+                lines.push(meta.map((m) => `- ${m}`).join("\n"), "");
+            if (c.files?.length) {
+                lines.push("**Files:**");
+                for (const f of c.files)
+                    lines.push(`- \`${f}\``);
+                lines.push("");
+            }
+            lines.push("---", "");
+        }
+    }
+    lines.push("_Generated by Whale Igniter._");
+    return lines.join("\n");
+}
+function renderWorkflows(_config) {
+    return `# Workflows
+
+## Daily flow
+
+\`\`\`
+whale validate                  # see what's drifting
+whale refine "<note>"           # accept an intentional exception
+whale decision                  # record a non-obvious choice
+whale component add <name>      # register a new component
+whale sync                      # regenerate AI context
+\`\`\`
+
+## When to use what
+
+| You want to...                                | Command                       |
+| --------------------------------------------- | ----------------------------- |
+| See what's broken                             | \`whale validate\`            |
+| Accept an exception ("we use radius 0 here")  | \`whale refine "..."\`        |
+| Log an architecture/product choice            | \`whale decision\`            |
+| Track a new component                         | \`whale component add\`       |
+| Refresh AI context after manual edits         | \`whale sync\`                |
+| Produce human reports                         | \`whale docs\`                |
+
+## Recommended cadence
+
+- **Per change:** run \`validate\` before commit.
+- **Per significant choice:** record a \`decision\` or \`refinement\`.
+- **Per session:** run \`sync\` before handing off to an AI agent.
+
+_Generated by Whale Igniter._
+`;
+}

package/dist/index.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { initCommand } from "./commands/init.js";
+import { validateCommand } from "./commands/validate.js";
+import { docsCommand } from "./commands/docs.js";
+import { wikiCommand } from "./commands/wiki.js";
+import { refineCommand } from "./commands/refine.js";
+import { addCommand } from "./commands/add.js";
+import { igniteCommand } from "./commands/ignite.js";
+import { syncCommand } from "./commands/sync.js";
+import { decisionCommand } from "./commands/decision.js";
+import { componentAddCommand, componentListCommand } from "./commands/component.js";
+import { adoptCommand } from "./commands/adopt.js";
+import { adoptReviewCommand, adoptStatusCommand } from "./commands/adoptReview.js";
+import { insightsCommand } from "./commands/insights.js";
+import { createComponentCommand } from "./commands/createComponent.js";
+import { seleneDescribeCommand, seleneAuditCommand, seleneSuggestCommand, seleneApplyCommand, seleneStatusCommand, seleneCacheClearCommand } from "./commands/selene.js";
+import { mcpServeCommand, mcpConfigCommand } from "./commands/mcp.js";
+import { watchCommand } from "./commands/watch.js";
+import { PACKAGE_VERSION } from "./version.js";
+const program = new Command();
+program
+    .name("whale")
+    .description("Whale Igniter — CLI-first operational intelligence. " +
+    "Bootstraps and adopts AI-readable project context for Claude, Codex, Cursor and Copilot.")
+    .version(PACKAGE_VERSION);
+program
+    .command("ignite [projectName]")
+    .description("Bootstrap a Whale workspace with AI-readable context (opinionated by default).")
+    .option("-i, --interactive", "Run an interactive wizard to configure stack, packs, AI targets")
+    .option("-m, --minimal", "Minimal scaffold: folders + config + one validator pack")
+    .action((projectName, opts) => igniteCommand(projectName, opts));
+program
+    .command("init [projectName]")
+    .description("Create an empty Whale workspace (no packs, no AI context).")
+    .action(async (projectName) => {
+    await initCommand(projectName);
+});
+program
+    .command("sync [target]")
+    .description("Regenerate CLAUDE.md and the LLM Wiki from intelligence/*.json.")
+    .action(syncCommand);
+program
+    .command("add <pack>")
+    .description("Install a Whale operational pack.")
+    .action(addCommand);
+program
+    .command("validate [target]")
+    .description("Run operational validations (exits non-zero on errors).")
+    .action(validateCommand);
+program
+    .command("docs [target]")
+    .description("Generate validation report and run installed generator packs.")
+    .action(docsCommand);
+program
+    .command("wiki [target]")
+    .description("Regenerate AI context (alias of `sync`).")
+    .action(wikiCommand);
+program
+    .command("refine <note>")
+    .description("Record an operational refinement. Mention an issue type to suppress matching issues.")
+    .option("--no-sync", "Skip automatic AI context regeneration")
+    .action((note, opts) => refineCommand(note, opts));
+const selene = program
+    .command("selene")
+    .description("AI-assisted suggestions — works offline (prompt mode) or via API key (API mode).");
+const apiFlagsHelp = "API mode flags: --prompt-only, --api-only, --provider, --model, --no-cache, --confirm-cost";
+selene
+    .command("describe <component>")
+    .description("Generate a catalog description for a component. " + apiFlagsHelp)
+    .option("--file <path>", "Component file path (defaults to the one registered in the catalog)")
+    .option("--out <path>", "Write the prompt to this file instead of clipboard / API")
+    .option("--stdout", "Print the prompt to stdout")
+    .option("--prompt-only", "Force prompt mode even if an API key is available")
+    .option("--api-only", "Force API mode (errors if no key configured)")
+    .option("--provider <name>", "Override the provider: anthropic | openai")
+    .option("--model <name>", "Override the model id")
+    .option("--no-cache", "Skip the on-disk response cache")
+    .option("--confirm-cost", "Show estimated cost before each call and require confirmation")
+    .option("--no-auto-apply", "In API mode, don't auto-apply the response")
+    .action((name, opts) => seleneDescribeCommand(name, opts));
+selene
+    .command("audit <file>")
+    .description("Audit a file against project foundations and conventions. " + apiFlagsHelp)
+    .option("--out <path>", "Write the prompt to this file instead of clipboard / API")
+    .option("--stdout", "Print the prompt to stdout")
+    .option("--prompt-only", "Force prompt mode even if an API key is available")
+    .option("--api-only", "Force API mode (errors if no key configured)")
+    .option("--provider <name>", "Override the provider: anthropic | openai")
+    .option("--model <name>", "Override the model id")
+    .option("--no-cache", "Skip the on-disk response cache")
+    .option("--confirm-cost", "Show estimated cost before each call and require confirmation")
+    .option("--no-auto-apply", "In API mode, don't auto-apply the response")
+    .action((file, opts) => seleneAuditCommand(file, opts));
+selene
+    .command("suggest")
+    .description("Suggest patterns or decisions worth recording. " + apiFlagsHelp)
+    .option("--focus <area>", "decisions | refinements | components | all")
+    .option("--out <path>", "Write the prompt to this file instead of clipboard / API")
+    .option("--stdout", "Print the prompt to stdout")
+    .option("--prompt-only", "Force prompt mode even if an API key is available")
+    .option("--api-only", "Force API mode (errors if no key configured)")
+    .option("--provider <name>", "Override the provider: anthropic | openai")
+    .option("--model <name>", "Override the model id")
+    .option("--no-cache", "Skip the on-disk response cache")
+    .option("--confirm-cost", "Show estimated cost before each call and require confirmation")
+    .option("--no-auto-apply", "In API mode, don't auto-apply the response")
+    .option("--yes", "Skip per-suggestion confirmation when auto-applying")
+    .action((opts) => seleneSuggestCommand(opts));
+selene
+    .command("apply <kind>")
+    .description("Paste the LLM response (stdin or --from) and apply it. kind: describe | audit | suggest")
+    .option("--from <path>", "Read the response from a file instead of stdin")
+    .option("--yes", "Skip per-change confirmation prompts")
+    .action((kind, opts) => seleneApplyCommand(kind, opts));
+selene
+    .command("status")
+    .description("Show available providers, current selene config, cache state.")
+    .action(() => seleneStatusCommand());
+const cache = selene
+    .command("cache")
+    .description("Manage the Selene response cache.");
+cache
+    .command("clear")
+    .description("Delete all cached Selene responses.")
+    .action(() => seleneCacheClearCommand());
+program
+    .command("insights [target]")
+    .description("Run local analyzers over the intelligence stores and surface accountable recommendations.")
+    .option("--json", "Emit insights as JSON (for scripting / CI)")
+    .option("--category <name>", "Filter by category: refinements | decisions | components | foundations | tokens | coverage")
+    .option("--min-severity <level>", "Show only insights at this severity or higher (info | warning | critical)")
+    .option("--skip-scan", "Skip the source scan (faster, but disables orphan/drift insights)")
+    .action((target, opts) => insightsCommand(target, opts));
+const create = program
+    .command("create")
+    .description("Generate new code that respects the project's foundations.");
+create
+    .command("component <name>")
+    .description("Generate a typed React component scaffold using current foundations.")
+    .option("--variants <list>", "Comma-separated variants (e.g. primary,secondary,ghost)")
+    .option("--states <list>", "Comma-separated states (e.g. hover,focus,disabled)")
+    .option("--category <name>", "Component category (form, navigation, feedback, surface, layout)")
+    .option("--out-dir <path>", "Output directory relative to project root (default: src/components)")
+    .option("--force", "Overwrite the file if it already exists")
+    .option("--no-register", "Don't add this component to intelligence/components.json")
+    .option("--no-sync", "Don't regenerate CLAUDE.md / wiki after creating")
+    .action((name, opts) => createComponentCommand(name, opts));
+const adopt = program
+    .command("adopt [target]")
+    .description("Scan an existing project and propose components, foundations and decisions.")
+    .option("--pattern <glob>", "Glob pattern for source files (default: src/**/*.{tsx,jsx})")
+    .option("--dry-run", "Run the scanner but don't write proposals to disk")
+    .action((target, opts) => adoptCommand(target, opts));
+adopt
+    .command("review [target]")
+    .description("Walk through pending proposals and accept, reject, or edit each.")
+    .option("--limit <n>", "Review at most N proposals in this pass", (v) => parseInt(v, 10))
+    .option("--accept-all", "Accept every pending proposal without prompting (use with care)")
+    .option("--category <kind>", "Only review one kind: component | foundations | decision")
+    .action((target, opts) => adoptReviewCommand(target, opts));
+adopt
+    .command("status [target]")
+    .description("Show counts and a preview of pending proposals.")
+    .action((target) => adoptStatusCommand(target));
+const decision = program
+    .command("decision")
+    .description("Record an architectural, product or tooling decision.")
+    .option("--title <title>", "Decision title")
+    .option("--category <category>", "architecture | design-system | product | tooling | convention")
+    .option("--context <text>", "Context: why this came up")
+    .option("--decision <text>", "What was decided")
+    .option("--consequences <text>", "Tradeoffs and implications")
+    .option("--no-sync", "Skip automatic AI context regeneration")
+    .action((opts) => decisionCommand(opts));
+const component = program
+    .command("component")
+    .description("Manage the component catalog.");
+component
+    .command("add <name>")
+    .description("Register a component in the catalog.")
+    .option("--description <text>", "Component description")
+    .option("--category <text>", "form | navigation | feedback | layout | ...")
+    .option("--variants <list>", "Comma-separated variants")
+    .option("--states <list>", "Comma-separated states (hover, focus, disabled, ...)")
+    .option("--files <list>", "Comma-separated file paths")
+    .option("--no-sync", "Skip automatic AI context regeneration")
+    .action((name, opts) => componentAddCommand(name, opts));
+component
+    .command("list")
+    .description("List components registered in the catalog.")
+    .action(componentListCommand);
+const mcp = program
+    .command("mcp")
+    .description("Run or configure the Whale MCP server (for Claude Code, Cursor, Zed, etc.).");
+mcp
+    .command("serve")
+    .description("Start the MCP server on stdio. Invoked by AI clients via their MCP config.")
+    .action(() => mcpServeCommand());
+mcp
+    .command("config")
+    .description("Print example MCP client configuration for the current workspace.")
+    .option("--client <name>", "claude-code | cursor | zed | raw", "claude-code")
+    .option("--project <path>", "Workspace path (default: cwd)")
+    .action((opts) => mcpConfigCommand(opts));
+program
+    .command("watch [target]")
+    .description("Watch foundations and intelligence stores; regenerate CLAUDE.md and wiki on change.")
+    .option("--debounce <ms>", "Debounce window in milliseconds (default 250)", (v) => parseInt(v, 10))
+    .option("--verbose", "Print every change event and regeneration detail")
+    .option("--once", "Run a single regeneration and exit (useful for CI)")
+    .action((target, opts) => watchCommand(target, opts));
+program.parse();