whale-igniter 1.1.0

package/dist/commands/watch.js

@@ -0,0 +1,150 @@
+/**
+ * `whale watch` — regenerate the AI-readable wiki when relevant files change.
+ *
+ * Why this exists. Whale's value depends on CLAUDE.md being current.
+ * Every write command (refine, decision, component add, adopt review) auto-syncs,
+ * but humans also edit `intelligence/*.json` directly, change `whale.config.json`,
+ * or commit catalog files from another tool. Without a watcher the gap between
+ * "what's true" and "what the AI sees" silently widens. Watcher closes that gap.
+ *
+ * Implementation. Node's built-in fs.watch is enough — we only watch a handful
+ * of small files plus the intelligence directory. We deliberately don't pull in
+ * chokidar; it adds dependencies and we don't need its cross-platform polyfills
+ * for this narrow use. Debouncing handles editors that write through a tmpfile
+ * (which often produces 2-3 events per save).
+ */
+import path from "node:path";
+import fs from "fs-extra";
+import { watch } from "node:fs";
+import { resolveTarget } from "../utils/paths.js";
+import { generateWiki } from "../generators/wikiGenerator.js";
+import { ui } from "../ui/index.js";
+/**
+ * Files and directories whose changes should trigger a regeneration.
+ * Paths are relative to the workspace root.
+ */
+const WATCH_TARGETS = [
+    "whale.config.json",
+    "intelligence" // directory — watch recursively if supported
+];
+export async function watchCommand(targetArg, options = {}) {
+    const target = resolveTarget(targetArg);
+    // Verify this is a Whale project. We don't want the watcher to silently
+    // run against a directory that has nothing to regenerate.
+    if (!(await fs.pathExists(path.join(target, "whale.config.json")))) {
+        console.log(ui.fail(`No whale.config.json at ${ui.path(target)}.`));
+        console.log(ui.muted("  Run `whale ignite` or `whale adopt` first."));
+        process.exitCode = 1;
+        return;
+    }
+    if (options.once) {
+        await regenerate(target, options.verbose);
+        return;
+    }
+    console.log(ui.header("Whale Igniter", `watch • ${path.relative(process.cwd(), target) || "."}`));
+    console.log();
+    console.log(`  ${ui.kv("watching", WATCH_TARGETS.join(", "), { keyWidth: 8 })}`);
+    console.log(ui.muted("  Press Ctrl+C to stop."));
+    console.log();
+    const debounceMs = options.debounce ?? 250;
+    let timer = null;
+    let inFlight = false;
+    let pendingWhileRunning = false;
+    const trigger = (reason) => {
+        if (options.verbose)
+            console.log(ui.muted(`  ◦ ${reason}`));
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(async () => {
+            timer = null;
+            if (inFlight) {
+                // Coalesce: remember that something else changed while we were busy.
+                pendingWhileRunning = true;
+                return;
+            }
+            inFlight = true;
+            try {
+                await regenerate(target, options.verbose);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                console.log(ui.fail(`regeneration failed: ${msg}`));
+            }
+            finally {
+                inFlight = false;
+                if (pendingWhileRunning) {
+                    pendingWhileRunning = false;
+                    trigger("queued change picked up");
+                }
+            }
+        }, debounceMs);
+    };
+    const watchers = [];
+    for (const rel of WATCH_TARGETS) {
+        const abs = path.join(target, rel);
+        if (!(await fs.pathExists(abs))) {
+            if (options.verbose)
+                console.log(ui.muted(`  (skip ${rel} — not present)`));
+            continue;
+        }
+        try {
+            // recursive is supported on macOS and Windows, but not all Linux setups.
+            // Try recursive first, fall back to non-recursive on error.
+            const w = watch(abs, { recursive: true }, (eventType, filename) => {
+                trigger(`${rel}${filename ? "/" + filename : ""} (${eventType})`);
+            });
+            watchers.push(w);
+        }
+        catch {
+            try {
+                const w = watch(abs, (eventType, filename) => {
+                    trigger(`${rel}${filename ? "/" + filename : ""} (${eventType})`);
+                });
+                watchers.push(w);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                console.log(ui.warn(`couldn't watch ${rel}: ${msg}`));
+            }
+        }
+    }
+    if (watchers.length === 0) {
+        console.log(ui.fail("Nothing to watch. Exiting."));
+        process.exitCode = 1;
+        return;
+    }
+    // Do an initial regeneration so the wiki is fresh from the start.
+    await regenerate(target, options.verbose);
+    // Block until interrupted.
+    return new Promise((resolve) => {
+        const stop = () => {
+            console.log();
+            console.log(ui.muted("Stopping watch."));
+            for (const w of watchers) {
+                try {
+                    w.close();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (timer)
+                clearTimeout(timer);
+            resolve();
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+    });
+}
+async function regenerate(target, verbose) {
+    const start = Date.now();
+    const { rootFiles, wikiFiles } = await generateWiki(target);
+    const ms = Date.now() - start;
+    const stamp = new Date().toLocaleTimeString();
+    console.log(ui.success(`[${stamp}] ${ui.glyph.check} regenerated`) +
+        ui.muted(` (${rootFiles.length} root, ${wikiFiles.length} wiki, ${ms}ms)`));
+    if (verbose) {
+        for (const f of rootFiles)
+            console.log(ui.muted(`           ${path.relative(target, f)}`));
+    }
+}

package/dist/commands/wiki.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import ora from "ora";
+import { resolveTarget } from "../utils/paths.js";
+import { generateWiki } from "../generators/wikiGenerator.js";
+import { ui } from "../ui/index.js";
+export async function wikiCommand(targetArg) {
+    const target = resolveTarget(targetArg);
+    const spinner = ora("Generating AI context").start();
+    const { rootFiles, wikiFiles } = await generateWiki(target);
+    spinner.succeed("AI context generated");
+    console.log();
+    console.log(ui.section("Root entry points"));
+    for (const file of rootFiles) {
+        console.log(`  ${ui.ok(ui.path(path.relative(target, file)))}`);
+    }
+    console.log();
+    console.log(ui.section("Wiki"));
+    for (const file of wikiFiles) {
+        console.log(`  ${ui.ok(ui.path(path.relative(target, file)))}`);
+    }
+}

package/dist/generators/markdownGenerator.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { loadConfig } from "../utils/config.js";
+import { loadRefinements } from "../utils/refinements.js";
+import { validateCss } from "../validators/cssValidator.js";
+async function buildContext(target) {
+    const config = await loadConfig(target);
+    const refinements = await loadRefinements(target);
+    const issues = await validateCss(target, { configOverride: config });
+    return { target, config, refinements, issues };
+}
+function renderForge(ctx) {
+    const { config, issues } = ctx;
+    const lines = [
+        "# Forge — Engineering Handoff",
+        "",
+        "**Audience:** engineering",
+        "",
+        "## Foundations",
+        `- Grid: ${config.foundations?.grid ?? 8}px`,
+        `- Control radius: ${config.foundations?.radius?.control ?? 2}px`,
+        `- Container radius: ${config.foundations?.radius?.container ?? 4}px`,
+        "",
+        "## Implementation Contracts",
+        "- All spacing values MUST be multiples of the grid.",
+        "- Controls use the control radius; cards/containers use the container radius.",
+        "- All interactive elements MUST have a `:focus-visible` style.",
+        "- Color values MUST come from semantic tokens (`var(--color-*)`).",
+        "",
+        `## Open Issues (${issues.length})`,
+        ""
+    ];
+    for (const issue of issues) {
+        lines.push(`- \`${issue.file}:${issue.line}\` — ${issue.type}: ${issue.message}`);
+    }
+    return lines.join("\n") + "\n";
+}
+function renderScribe(ctx) {
+    const { config, issues, refinements } = ctx;
+    const lines = [
+        "# Scribe — Team Documentation",
+        "",
+        "**Audience:** team (mixed)",
+        "",
+        "## What this project uses",
+        `- Project type: ${config.projectType}`,
+        `- Active packs: ${(config.packs ?? []).join(", ") || "(none)"}`,
+        "",
+        "## Conventions",
+        `- Spacing: ${config.foundations?.grid ?? 8}px grid`,
+        `- Radii: ${config.foundations?.radius?.control ?? 2}px (controls) / ${config.foundations?.radius?.container ?? 4}px (containers)`,
+        "",
+        `## Recorded Decisions (${refinements.length})`,
+        ""
+    ];
+    for (const r of refinements) {
+        lines.push(`- ${r.timestamp.slice(0, 10)} — ${r.note}`);
+    }
+    lines.push("");
+    lines.push(`## Current Validation Status`);
+    lines.push("");
+    lines.push(`${issues.length} issue(s) open. Run \`whale validate\` for details.`);
+    return lines.join("\n") + "\n";
+}
+function renderAtlas(ctx) {
+    const { config, refinements, issues } = ctx;
+    const errors = issues.filter((i) => i.severity === "error").length;
+    const warnings = issues.filter((i) => i.severity === "warning").length;
+    const lines = [
+        "# Atlas — Product Strategy",
+        "",
+        "**Audience:** product",
+        "",
+        "## Project Posture",
+        `- Type: ${config.projectType}`,
+        `- Tone: ${config.branding?.tone ?? "unspecified"}`,
+        `- Accent: ${config.branding?.accent ?? "unspecified"}`,
+        "",
+        "## Operational Health",
+        `- Errors: ${errors}`,
+        `- Warnings: ${warnings}`,
+        `- Decisions logged: ${refinements.length}`,
+        "",
+        "## Decision Log",
+        ""
+    ];
+    for (const r of refinements) {
+        const scopeInfo = r.scope
+            ? ` _(scope: ${[r.scope.issueType, r.scope.selector, r.scope.file].filter(Boolean).join(", ")})_`
+            : "";
+        lines.push(`- **${r.timestamp.slice(0, 10)}** — ${r.note}${scopeInfo}`);
+    }
+    return lines.join("\n") + "\n";
+}
+const RENDERERS = {
+    forge: renderForge,
+    scribe: renderScribe,
+    atlas: renderAtlas
+};
+export async function runGenerator(target, pack) {
+    const renderer = RENDERERS[pack.name];
+    if (!renderer) {
+        throw new Error(`No renderer registered for pack "${pack.name}".`);
+    }
+    const ctx = await buildContext(target);
+    const content = renderer(ctx);
+    const outDir = path.join(target, "docs", pack.name);
+    await fs.ensureDir(outDir);
+    const outFile = path.join(outDir, `${pack.name}-report.md`);
+    await fs.writeFile(outFile, content);
+    return outFile;
+}

package/dist/generators/reportGenerator.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { validateCss } from "../validators/cssValidator.js";
+export async function generateValidationReport(target) {
+    const issues = await validateCss(target);
+    const reportPath = path.join(target, "docs", "validation-report.md");
+    const errors = issues.filter((i) => i.severity === "error");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    const lines = [
+        "# Whale Validation Report",
+        "",
+        `_Generated ${new Date().toISOString()}_`,
+        "",
+        "## Summary",
+        "",
+        `- Total issues: **${issues.length}**`,
+        `- Errors: **${errors.length}**`,
+        `- Warnings: **${warnings.length}**`,
+        ""
+    ];
+    if (issues.length === 0) {
+        lines.push("✓ Clean run.");
+    }
+    else {
+        // Group by file so the report is actionable.
+        const byFile = new Map();
+        for (const issue of issues) {
+            const arr = byFile.get(issue.file) ?? [];
+            arr.push(issue);
+            byFile.set(issue.file, arr);
+        }
+        for (const [file, fileIssues] of byFile) {
+            lines.push(`## ${file}`);
+            lines.push("");
+            for (const issue of fileIssues) {
+                const tag = issue.severity === "error" ? "ERROR" : "WARNING";
+                lines.push(`- **${tag}** (${issue.type}) at line ${issue.line}`);
+                lines.push(`  - ${issue.message}`);
+                lines.push(`  - Fix: ${issue.suggestion}`);
+                if (issue.selector) {
+                    lines.push(`  - Selector: \`${issue.selector}\``);
+                }
+            }
+            lines.push("");
+        }
+    }
+    await fs.ensureDir(path.dirname(reportPath));
+    await fs.writeFile(reportPath, lines.join("\n"));
+    return reportPath;
+}