whale-igniter 1.3.7 → 1.5.1

package/dist/commands/forge.js

@@ -0,0 +1,159 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { resolveTarget } from "../utils/paths.js";
+import { loadConfig } from "../utils/config.js";
+import { loadComponents } from "../utils/components.js";
+import { ui } from "../ui/index.js";
+export async function forgeCommand(componentName, options = {}) {
+    const target = resolveTarget();
+    const config = await loadConfig(target);
+    const components = await loadComponents(target);
+    const component = components.find((c) => c.name === componentName);
+    if (!component) {
+        console.log(ui.fail(`Component "${componentName}" not found in intelligence/components.json.`));
+        console.log(ui.muted(`  Run \`whale create component ${componentName}\` first, or \`whale component add ${componentName}\`.`));
+        process.exitCode = 1;
+        return;
+    }
+    const grid = config.foundations?.grid ?? 8;
+    const controlRadius = config.foundations?.radius?.control ?? 2;
+    const containerRadius = config.foundations?.radius?.container ?? 4;
+    const accent = config.branding?.accent ?? "blue";
+    const isControl = isControlCategory(component.category);
+    const radius = isControl ? controlRadius : containerRadius;
+    const px = grid * 2;
+    const py = grid;
+    const outDir = options.out ?? "docs/forge";
+    const fileRel = path.join(outDir, `${componentName}.md`).replace(/\\/g, "/");
+    const fileAbs = path.join(target, fileRel);
+    if (await fs.pathExists(fileAbs) && !options.force) {
+        console.log(ui.fail(`${ui.path(fileRel)} already exists. Use --force to overwrite.`));
+        process.exitCode = 1;
+        return;
+    }
+    await fs.ensureDir(path.dirname(fileAbs));
+    const content = renderForgeContract({
+        component,
+        grid,
+        radius,
+        px,
+        py,
+        accent,
+        isControl,
+    });
+    await fs.writeFile(fileAbs, content, "utf8");
+    console.log(ui.ok(`Forge contract → ${ui.path(fileRel)}`));
+    console.log(`  ${ui.kv("component", componentName, { keyWidth: 10 })}`);
+    console.log(`  ${ui.kv("template", isControl ? "control" : "container", { keyWidth: 10 })}`);
+    console.log(`  ${ui.kv("grid", `${grid}px`, { keyWidth: 10 })}`);
+    console.log(`  ${ui.kv("radius", `${radius}px`, { keyWidth: 10 })}`);
+}
+// ---------------------------------------------------------------------------
+// Renderer
+// ---------------------------------------------------------------------------
+function renderForgeContract(args) {
+    const { component, grid, radius, px, py, accent, isControl } = args;
+    const { name, category, variants = [], states = [], files = [], tokens = [] } = component;
+    const paddingNote = isControl
+        ? `${px}px horizontal / ${py}px vertical (${grid}px grid × 2 / × 1)`
+        : `${py * 3}px all sides (${grid}px grid × 3)`;
+    const derivedTokens = deriveTokens(variants, accent, tokens);
+    const checklist = buildChecklist(isControl, variants, states);
+    const lines = [
+        `# Forge — ${name}`,
+        "",
+        `> Auto-generated implementation contract. Keep in sync with \`intelligence/components.json\`.`,
+        "",
+        "## Component spec",
+        "",
+        `| Property  | Value |`,
+        `|-----------|-------|`,
+        `| Template  | ${isControl ? "control" : "container"} |`,
+        `| Category  | ${category ?? "unspecified"} |`,
+        `| Grid      | ${grid}px |`,
+        `| Radius    | ${radius}px |`,
+        `| Padding   | ${paddingNote} |`,
+    ];
+    if (variants.length > 0) {
+        lines.push(`| Variants  | ${variants.join(", ")} |`);
+    }
+    if (states.length > 0) {
+        lines.push(`| States    | ${states.join(", ")} |`);
+    }
+    lines.push("", "## Design tokens", "");
+    if (derivedTokens.length > 0) {
+        for (const t of derivedTokens) {
+            lines.push(`- \`${t.token}\` — ${t.usage}`);
+        }
+    }
+    else {
+        lines.push("- No tokens registered. Run `whale selene describe` to infer them.");
+    }
+    lines.push("", "## Implementation checklist", "");
+    for (const item of checklist) {
+        lines.push(`- [ ] ${item}`);
+    }
+    if (files.length > 0) {
+        lines.push("", "## Files", "");
+        for (const f of files) {
+            lines.push(`- \`${f}\``);
+        }
+    }
+    lines.push("", "---", `_Generated by Whale Igniter · \`whale forge ${name}\`_`, "");
+    return lines.join("\n");
+}
+function deriveTokens(variants, accent, existing) {
+    if (existing.length > 0) {
+        return existing.map((t) => ({ token: t, usage: "registered token" }));
+    }
+    const result = [];
+    for (const v of variants) {
+        switch (v) {
+            case "primary":
+                result.push({ token: `--color-${accent}-600`, usage: "primary background" });
+                result.push({ token: `--color-${accent}-700`, usage: "primary hover" });
+                break;
+            case "secondary":
+                result.push({ token: `--color-gray-100`, usage: "secondary background" });
+                result.push({ token: `--color-gray-200`, usage: "secondary hover" });
+                break;
+            case "ghost":
+                result.push({ token: `--color-gray-100`, usage: "ghost hover background" });
+                break;
+            case "destructive":
+                result.push({ token: `--color-red-600`, usage: "destructive background" });
+                break;
+        }
+    }
+    return result;
+}
+function buildChecklist(isControl, variants, states) {
+    const items = [];
+    if (isControl) {
+        items.push("forwardRef implemented with correct HTMLElement type");
+        items.push("baseClasses use grid-aligned padding");
+        items.push(`radius matches control radius from whale.config.json`);
+    }
+    else {
+        items.push("Container uses grid-aligned padding (grid × 3)");
+        items.push("radius matches container radius from whale.config.json");
+    }
+    if (states.includes("focus") || states.includes("focus-visible")) {
+        items.push(":focus-visible ring is visible at 2px offset");
+    }
+    if (states.includes("disabled")) {
+        items.push("disabled state reduces opacity and removes pointer-events");
+    }
+    if (states.includes("hover")) {
+        items.push("hover state uses a darker/lighter token variant, not raw hex");
+    }
+    for (const v of variants) {
+        items.push(`Variant "${v}" visually tested at all states`);
+    }
+    items.push("Color values come from tokens (var(--color-*)), not raw hex");
+    items.push("Component registered in intelligence/components.json");
+    return items;
+}
+function isControlCategory(category) {
+    return ["form", "navigation"].includes(category ?? "");
+}

package/dist/commands/scribe.js

@@ -0,0 +1,189 @@
+import path from "node:path";
+import fs from "fs-extra";
+import ora from "ora";
+import { resolveTarget } from "../utils/paths.js";
+import { loadConfig } from "../utils/config.js";
+import { loadComponents } from "../utils/components.js";
+import { loadDecisions } from "../utils/decisions.js";
+import { loadRefinements } from "../utils/refinements.js";
+import { resolveProvider } from "../selene/providers.js";
+import { callProvider } from "../selene/apiClient.js";
+import { ui } from "../ui/index.js";
+// ---------------------------------------------------------------------------
+// whale scribe readme <ComponentName>
+// ---------------------------------------------------------------------------
+export async function scribeReadmeCommand(componentName, options = {}) {
+    const target = resolveTarget();
+    const config = await loadConfig(target);
+    const components = await loadComponents(target);
+    const component = components.find((c) => c.name === componentName);
+    if (!component) {
+        console.log(ui.fail(`Component "${componentName}" not found in intelligence/components.json.`));
+        console.log(ui.muted(`  Run \`whale create component ${componentName}\` first.`));
+        process.exitCode = 1;
+        return;
+    }
+    const outDir = options.out ?? "docs/scribe";
+    const fileRel = path.join(outDir, `${componentName}.md`).replace(/\\/g, "/");
+    const fileAbs = path.join(target, fileRel);
+    if (await fs.pathExists(fileAbs) && !options.force) {
+        console.log(ui.fail(`${ui.path(fileRel)} already exists. Use --force to overwrite.`));
+        process.exitCode = 1;
+        return;
+    }
+    const grid = config.foundations?.grid ?? 8;
+    const controlRadius = config.foundations?.radius?.control ?? 2;
+    const containerRadius = config.foundations?.radius?.container ?? 4;
+    const accent = config.branding?.accent ?? "blue";
+    const projectName = config.projectName ?? "this project";
+    const prompt = buildReadmePrompt({
+        componentName,
+        component,
+        grid,
+        controlRadius,
+        containerRadius,
+        accent,
+        projectName,
+    });
+    if (options.promptOnly) {
+        console.log(prompt);
+        return;
+    }
+    const resolved = resolveProvider(config);
+    if (!resolved) {
+        console.log(ui.warn("No API key found — printing prompt instead."));
+        console.log(ui.muted("  Set ANTHROPIC_API_KEY or OPENAI_API_KEY to use AI generation."));
+        console.log("\n" + prompt);
+        return;
+    }
+    const spinner = ora(`Scribe · generating README for ${componentName}`).start();
+    const result = await callProvider(resolved, { prompt, maxTokens: 1200, temperature: 0.4 });
+    if (!result.ok) {
+        spinner.fail(`API error: ${result.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed(`README generated`);
+    const content = result.text.trim();
+    await fs.ensureDir(path.dirname(fileAbs));
+    await fs.writeFile(fileAbs, content + "\n", "utf8");
+    console.log(ui.ok(`Scribe → ${ui.path(fileRel)}`));
+    console.log(ui.muted(`  provider: ${resolved.provider} · ${resolved.model}`));
+}
+// ---------------------------------------------------------------------------
+// whale scribe overview
+// ---------------------------------------------------------------------------
+export async function scribeOverviewCommand(options = {}) {
+    const target = resolveTarget();
+    const config = await loadConfig(target);
+    const components = await loadComponents(target);
+    const decisions = await loadDecisions(target);
+    const refinements = await loadRefinements(target);
+    const outDir = options.out ?? "docs/scribe";
+    const fileRel = path.join(outDir, "overview.md").replace(/\\/g, "/");
+    const fileAbs = path.join(target, fileRel);
+    if (await fs.pathExists(fileAbs) && !options.force) {
+        console.log(ui.fail(`${ui.path(fileRel)} already exists. Use --force to overwrite.`));
+        process.exitCode = 1;
+        return;
+    }
+    const prompt = buildOverviewPrompt({ config, components, decisions, refinements });
+    if (options.promptOnly) {
+        console.log(prompt);
+        return;
+    }
+    const resolved = resolveProvider(config);
+    if (!resolved) {
+        console.log(ui.warn("No API key found — printing prompt instead."));
+        console.log(ui.muted("  Set ANTHROPIC_API_KEY or OPENAI_API_KEY to use AI generation."));
+        console.log("\n" + prompt);
+        return;
+    }
+    const spinner = ora("Scribe · generating project overview").start();
+    const result = await callProvider(resolved, { prompt, maxTokens: 1600, temperature: 0.4 });
+    if (!result.ok) {
+        spinner.fail(`API error: ${result.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed("Overview generated");
+    const content = result.text.trim();
+    await fs.ensureDir(path.dirname(fileAbs));
+    await fs.writeFile(fileAbs, content + "\n", "utf8");
+    console.log(ui.ok(`Scribe → ${ui.path(fileRel)}`));
+    console.log(ui.muted(`  provider: ${resolved.provider} · ${resolved.model}`));
+}
+// ---------------------------------------------------------------------------
+// Prompt builders
+// ---------------------------------------------------------------------------
+function buildReadmePrompt(args) {
+    const { componentName, component, grid, controlRadius, containerRadius, accent, projectName } = args;
+    const { category, description, variants = [], states = [], files = [], tokens = [] } = component;
+    return [
+        `# Scribe task — README for component: ${componentName}`,
+        "",
+        "You are a technical writer generating a component README for a design system.",
+        `The project is called "${projectName}" and uses an ${grid}px grid, ${controlRadius}px control radius, ${containerRadius}px container radius, and "${accent}" as accent color.`,
+        "",
+        "## Component metadata",
+        `- Name: ${componentName}`,
+        `- Category: ${category ?? "unspecified"}`,
+        `- Description: ${description ?? "(none)"}`,
+        `- Variants: ${variants.length > 0 ? variants.join(", ") : "none"}`,
+        `- States: ${states.length > 0 ? states.join(", ") : "none"}`,
+        `- Files: ${files.length > 0 ? files.join(", ") : "not specified"}`,
+        `- Tokens: ${tokens.length > 0 ? tokens.join(", ") : "not specified"}`,
+        "",
+        "## Task",
+        `Write a concise, developer-focused README.md for the ${componentName} component.`,
+        "Include:",
+        "1. A one-paragraph description of what it does and when to use it",
+        "2. A usage example (JSX/TSX code block)",
+        "3. A props table (name | type | default | description)",
+        "4. A section on accessibility (focus, ARIA if relevant)",
+        "5. A brief design notes section mentioning the grid and token constraints",
+        "",
+        "Write in plain Markdown. Be concise — target 150-250 lines max. No preamble or explanation.",
+    ].join("\n");
+}
+function buildOverviewPrompt(args) {
+    const { config, components, decisions, refinements } = args;
+    const componentList = components
+        .map((c) => `- ${c.name}${c.description ? `: ${c.description}` : ""}`)
+        .join("\n") || "  (none registered)";
+    const decisionList = decisions
+        .map((d) => `- ${d.title}: ${d.decision}`)
+        .join("\n") || "  (none)";
+    return [
+        "# Scribe task — project overview README",
+        "",
+        "You are a technical writer generating a project overview README.",
+        "",
+        "## Project config",
+        `- Name: ${config.projectName ?? "unnamed"}`,
+        `- Type: ${config.projectType ?? "unspecified"}`,
+        `- Stack: ${config.stack ?? "unspecified"}`,
+        `- Grid: ${config.foundations?.grid ?? 8}px`,
+        `- Control radius: ${config.foundations?.radius?.control ?? 2}px`,
+        `- Container radius: ${config.foundations?.radius?.container ?? 4}px`,
+        `- Accent: ${config.branding?.accent ?? "unspecified"}`,
+        `- Active packs: ${(config.packs ?? []).join(", ") || "none"}`,
+        "",
+        "## Registered components",
+        componentList,
+        "",
+        "## Architectural decisions",
+        decisionList,
+        `- Refinements recorded: ${refinements.length}`,
+        "",
+        "## Task",
+        "Write a project overview README.md that a new developer would read to understand:",
+        "1. What this project is and who it's for",
+        "2. The design system foundations (grid, radius, tokens)",
+        "3. The component catalog (what exists, categories)",
+        "4. Key architectural decisions",
+        "5. How to get started (whale commands to run)",
+        "",
+        "Write in plain Markdown. Be concise and direct. No preamble or explanation.",
+    ].join("\n");
+}

package/dist/index.js

@@ -15,6 +15,9 @@ import { adoptReviewCommand, adoptStatusCommand } from "./commands/adoptReview.j
 import { insightsCommand, insightsDriftReviewCommand } from "./commands/insights.js";
 import { createComponentCommand } from "./commands/createComponent.js";
 import { createLandingCommand } from "./commands/createLanding.js";
+import { forgeCommand } from "./commands/forge.js";
+import { scribeReadmeCommand, scribeOverviewCommand } from "./commands/scribe.js";
+import { atlasHealthCommand, atlasDecisionsCommand } from "./commands/atlas.js";
 import { themesListCommand } from "./commands/themes.js";
 import { updateTokensCommand } from "./commands/updateTokens.js";
 import { seleneDescribeCommand, seleneAuditCommand, seleneSuggestCommand, seleneApplyCommand, seleneStatusCommand, seleneCacheClearCommand } from "./commands/selene.js";
@@ -178,13 +181,60 @@ create
 create
     .command("landing")
     .description("Generate a static HTML/CSS landing page using current foundations.")
-    .option("--sections <list>", "Comma-separated sections (hero,features,proof,contact)")
+    .option("--sections <list>", "Comma-separated sections (header,hero,features,proof,contact,footer)")
     .option("--out-dir <path>", "Output directory relative to project root (default: src)")
     .option("--force", "Overwrite generated files if they already exist")
     .option("--no-register", "Don't add generated sections to intelligence/components.json")
     .option("--no-sync", "Don't regenerate CLAUDE.md / wiki after creating")
     .option("--theme <name>", "Visual theme for the generated UI (see `whale themes list`)")
+    .option("--content <path>", "Read landing copy from a local JSON file")
+    .option("--sample-content", "Create an editable landing.json sample and use it")
+    .option("--brief", "Ask a short local brief and generate landing.json")
+    .option("--title <text>", "Override the hero headline")
+    .option("--eyebrow <text>", "Override the hero eyebrow")
+    .option("--tagline <text>", "Override the hero supporting copy")
+    .option("--cta <text>", "Override the primary CTA label")
+    .option("--cta-href <href>", "Override the primary CTA href")
     .action((opts) => createLandingCommand(opts));
+program
+    .command("forge <component>")
+    .description("Generate an implementation contract (Markdown) for a registered component.")
+    .option("--out <dir>", "Output directory relative to project root (default: docs/forge)")
+    .option("--force", "Overwrite the contract if it already exists")
+    .action((component, opts) => forgeCommand(component, opts));
+const atlas = program
+    .command("atlas")
+    .description("Project health and decision intelligence for PMs and tech leads.");
+atlas
+    .command("health")
+    .description("Generate an AI-powered project health report.")
+    .option("--out <dir>", "Output directory (default: docs/atlas)")
+    .option("--force", "Overwrite if already exists")
+    .option("--prompt-only", "Print the prompt without calling the API")
+    .action((opts) => atlasHealthCommand(opts));
+atlas
+    .command("decisions")
+    .description("List active architectural decisions, optionally filtered.")
+    .option("--category <name>", "Filter by category (architecture, design-system, product, tooling, convention)")
+    .option("--status <status>", "Filter by status (active, superseded, deprecated) — default: active")
+    .action((opts) => atlasDecisionsCommand(opts));
+const scribe = program
+    .command("scribe")
+    .description("AI-generated documentation for components and projects.");
+scribe
+    .command("readme <component>")
+    .description("Generate a developer README for a registered component using AI.")
+    .option("--out <dir>", "Output directory (default: docs/scribe)")
+    .option("--force", "Overwrite if already exists")
+    .option("--prompt-only", "Print the prompt without calling the API")
+    .action((component, opts) => scribeReadmeCommand(component, opts));
+scribe
+    .command("overview")
+    .description("Generate a project overview README using AI.")
+    .option("--out <dir>", "Output directory (default: docs/scribe)")
+    .option("--force", "Overwrite if already exists")
+    .option("--prompt-only", "Print the prompt without calling the API")
+    .action((opts) => scribeOverviewCommand(opts));
 const adopt = program
     .command("adopt [target]")
     .description("Scan an existing project and propose components, foundations and decisions.")

package/dist/selene/cache.js

@@ -44,6 +44,7 @@ export async function writeCache(target, model, prompt, text) {
     const key = cacheKey(model, prompt);
     const dir = path.join(target, CACHE_DIR_REL);
     await fs.ensureDir(dir);
+    await ensureWhaleGitignore(target);
     const entry = {
         key,
         model,
@@ -66,3 +67,13 @@ export async function clearCache(target) {
     }
     return removed;
 }
+async function ensureWhaleGitignore(target) {
+    const gitignore = path.join(target, ".gitignore");
+    const entry = ".whale/";
+    const existing = (await fs.pathExists(gitignore)) ? await fs.readFile(gitignore, "utf8") : "";
+    const lines = existing.split(/\r?\n/).map((line) => line.trim());
+    if (lines.includes(entry))
+        return;
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await fs.appendFile(gitignore, `${prefix}${entry}\n`, "utf8");
+}

package/dist/ui/splash.js

@@ -6,13 +6,20 @@
  *   2. Unicode, no color       — same layout, no color
  *   3. Plain                   — single ASCII line, no glyphs
  *
- * Rules: no chalk imports, no direct env var reads, no "premium".
+ * Rules: no chalk imports, no direct env var reads, no vague status copy.
  * Uses `capabilities()` from capabilities.js and `ui` atoms.
  */
 import { capabilities } from "./capabilities.js";
 import { accent, muted, emphasis } from "./atoms.js";
 import { PACKAGE_VERSION } from "../version.js";
 const TAGLINE = "map the project before the agent moves";
+const BLOCK = [
+    ` _|          _|  _|    _|    _|_|    _|        _|_|_|_|  `,
+    ` _|          _|  _|    _|  _|    _|  _|        _|        `,
+    ` _|    _|    _|  _|_|_|_|  _|_|_|_|  _|        _|_|_|    `,
+    `   _|  _|  _|    _|    _|  _|    _|  _|        _|        `,
+    `     _|  _|      _|    _|  _|    _|  _|_|_|_|  _|_|_|_|  `,
+].join("\n");
 export function splash() {
     const { color, unicode } = capabilities();
     const isPlain = !unicode;
@@ -20,17 +27,15 @@ export function splash() {
     if (isPlain) {
         return `WHALE IGNITER v${PACKAGE_VERSION} — ${TAGLINE}`;
     }
-    // Tier 1 & 2 — unicode layout (color applied via atom functions when available)
-    const whale = "◆ ～";
-    const wordmarkWhale = color ? accent("WHALE") : "WHALE";
     const wordmarkIgniter = color ? emphasis("IGNITER") : "IGNITER";
     const version = color ? muted(`v${PACKAGE_VERSION}`) : `v${PACKAGE_VERSION}`;
     const tag = color ? muted(TAGLINE) : TAGLINE;
-    const rule = "─".repeat(36);
+    const title = color ? accent(BLOCK) : BLOCK;
+    const rule = "─".repeat(50);
     return [
-        `${whale}`,
-        `${wordmarkWhale} ${wordmarkIgniter}  ${version}`,
+        title,
+        `${wordmarkIgniter}  ·  ${version}`,
         tag,
-        rule
+        rule,
     ].join("\n");
 }

package/dist/version.js

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.3.7";
+export const PACKAGE_VERSION = "1.5.1";

package/docs/ROADMAP.md

@@ -85,7 +85,7 @@ reveals that the next plan needs revising, we revise it before shipping.
 - **Test coverage.** 44 unit tests + MCP smoke test that spawns the
   server and exercises real protocol calls end-to-end.
 
-### v1.1 — Premium runtime UI
+### v1.1 — Polished runtime UI
 
 The terminal output became the product surface. Commands stopped reaching
 for chalk directly; every command now consumes a semantic UI layer where
@@ -96,7 +96,7 @@ pair) and the active theme decides what each intent looks like.
   with ASCII fallbacks), blocks (header, section, kv, panel, summary,
   next, ok/fail/warn/note), theme dispatcher. Commands import from `ui/`
   rather than chalk; chalk is now confined to the theme module.
-- **Single premium theme — graphite.** Cyan accent, charcoal grays, three
+- **Single polished theme — graphite.** Cyan accent, charcoal grays, three
   text-hierarchy levels. Structure ready for v1.2's multi-theme without
   touching any command.
 - **Capability detection.** Auto-detects color and Unicode support; falls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.3.7",
+  "version": "1.5.1",
   "description": "CLI-first operational intelligence. Bootstraps and adopts AI-readable project context so agents like Claude Code, Codex and Cursor understand your design system from the first commit. Includes an MCP server, a file watcher, deterministic insights, and an opt-in AI bridge (Selene).",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,12 +14,14 @@
     "themes",
     "ui-references",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "docs/ROADMAP.md"
   ],
   "scripts": {
     "dev": "tsx src/index.ts",
     "build": "tsc",
+    "postbuild": "node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
     "start": "node dist/index.js",
     "test": "tsx tests/run.ts && tsx tests/mcp-smoke.ts && tsx tests/extractors.ts && tsx tests/driftAnalyzers.ts",
     "prepublishOnly": "npm run build && npm test"