whale-igniter 1.2.3 → 1.3.0

package/dist/scanner/extractors/styleBlocks.js

@@ -0,0 +1,37 @@
+import fs from "fs-extra";
+import { glob } from "glob";
+import { extractFromContent } from "./css.js";
+const IGNORE = ["node_modules/**", "dist/**", ".next/**", "build/**", "coverage/**"];
+const STYLE_BLOCK_REGEX = /<style[^>]*>([\s\S]*?)<\/style>/gi;
+function linesBefore(content, index) {
+    let count = 0;
+    for (let i = 0; i < index; i++) {
+        if (content[i] === "\n")
+            count++;
+    }
+    return count;
+}
+async function extractFromFile(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const observations = [];
+    let match;
+    STYLE_BLOCK_REGEX.lastIndex = 0;
+    while ((match = STYLE_BLOCK_REGEX.exec(content)) !== null) {
+        const blockStart = match.index;
+        const cssContent = match[1];
+        // +1 because the opening <style> tag is on that line, CSS starts on next
+        const lineOffset = linesBefore(content, blockStart) + 1;
+        const blockObs = await extractFromContent(cssContent, filePath, lineOffset, "style-block");
+        observations.push(...blockObs);
+    }
+    return observations;
+}
+export async function extractFromStyleBlocks(root) {
+    const files = await glob("**/*.{html,vue,svelte,astro}", {
+        cwd: root,
+        ignore: IGNORE,
+        absolute: true
+    });
+    const results = await Promise.all(files.map(extractFromFile));
+    return results.flat();
+}

package/dist/scanner/normalizer.js

@@ -0,0 +1,59 @@
+export const TRACKED_PROPERTIES = new Set([
+    "padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
+    "margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
+    "gap", "column-gap", "row-gap",
+    "color", "background-color", "border-color",
+    "border-radius",
+    "border-top-left-radius", "border-top-right-radius",
+    "border-bottom-left-radius", "border-bottom-right-radius",
+    "font-size", "font-weight", "line-height"
+]);
+const REM_BASE = 16;
+export function parsePxValue(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    const pxMatch = trimmed.match(/^(-?\d+(?:\.\d+)?)px$/);
+    if (pxMatch)
+        return parseFloat(pxMatch[1]);
+    const remMatch = trimmed.match(/^(-?\d+(?:\.\d+)?)rem$/);
+    if (remMatch)
+        return parseFloat(remMatch[1]) * REM_BASE;
+    const emMatch = trimmed.match(/^(-?\d+(?:\.\d+)?)em$/);
+    if (emMatch)
+        return parseFloat(emMatch[1]) * REM_BASE;
+    if (trimmed === "0")
+        return 0;
+    return undefined;
+}
+// Camel-case JSX property names → CSS property names
+const CAMEL_TO_CSS = {
+    padding: "padding",
+    paddingTop: "padding-top",
+    paddingRight: "padding-right",
+    paddingBottom: "padding-bottom",
+    paddingLeft: "padding-left",
+    margin: "margin",
+    marginTop: "margin-top",
+    marginRight: "margin-right",
+    marginBottom: "margin-bottom",
+    marginLeft: "margin-left",
+    gap: "gap",
+    columnGap: "column-gap",
+    rowGap: "row-gap",
+    color: "color",
+    backgroundColor: "background-color",
+    borderColor: "border-color",
+    borderRadius: "border-radius",
+    borderTopLeftRadius: "border-top-left-radius",
+    borderTopRightRadius: "border-top-right-radius",
+    borderBottomLeftRadius: "border-bottom-left-radius",
+    borderBottomRightRadius: "border-bottom-right-radius",
+    fontSize: "font-size",
+    fontWeight: "font-weight",
+    lineHeight: "line-height"
+};
+export function camelToCssProperty(camel) {
+    const css = CAMEL_TO_CSS[camel];
+    return (css && TRACKED_PROPERTIES.has(css)) ? css : null;
+}

package/dist/scanner/tailwindScanner.js

@@ -166,6 +166,45 @@ export function aggregateTailwind(classNameStrings) {
     }
     return Array.from(map.values()).sort((a, b) => b.count - a.count);
 }
+/**
+ * Converts aggregated TailwindObservations to the unified StyleObservation type.
+ * Tailwind observations don't carry file/line info — they are class-level aggregates.
+ * We emit source: "tailwind" with line: 0 to signal this.
+ */
+export function tailwindToStyleObservations(observations, sourceFile = "(tailwind)") {
+    return observations.flatMap((obs) => {
+        if (obs.kind === "spacing") {
+            return [{
+                    property: "padding",
+                    value: obs.pxValue != null ? `${obs.pxValue}px` : obs.raw,
+                    pxValue: obs.pxValue ?? undefined,
+                    file: sourceFile,
+                    line: 0,
+                    source: "tailwind"
+                }];
+        }
+        if (obs.kind === "radius") {
+            return [{
+                    property: "border-radius",
+                    value: obs.pxValue != null ? `${obs.pxValue}px` : obs.raw,
+                    pxValue: obs.pxValue ?? undefined,
+                    file: sourceFile,
+                    line: 0,
+                    source: "tailwind"
+                }];
+        }
+        if (obs.kind === "color" && obs.colorToken) {
+            return [{
+                    property: "color",
+                    value: obs.colorToken,
+                    file: sourceFile,
+                    line: 0,
+                    source: "tailwind"
+                }];
+        }
+        return [];
+    });
+}
 /**
  * Try to read tailwind.config.{js,ts,mjs,cjs} to override default scales.
  * We use a conservative approach: don't execute the file (no eval, no

package/dist/templates/claude.js

@@ -0,0 +1,93 @@
+export function renderReferencesSection(uiReferences) {
+    if (uiReferences.length === 0)
+        return "";
+    const categoryDescriptions = {
+        forms: "buttons, inputs, selects, checkboxes, radios, toggles, textareas",
+        navigation: "nav bars, tabs, sidebar, breadcrumbs, dropdown menus, pagination, command palette",
+        feedback: "toasts, modals, alerts, progress, loading states, skeletons, empty states",
+        surface: "cards, popovers, tooltips, sheets, avatars, separators, badges",
+        layout: "container, stack, grid, responsive patterns, sidebar layout",
+        "data-display": "tables, lists, code blocks, stats, timelines"
+    };
+    const lines = [
+        "## UI references available",
+        "",
+        "This project ships with curated component references in `references/`.",
+        "Consult these when building UI — they define the quality bar and best",
+        "implementations to model.",
+        "",
+        "- `references/INDEX.md` — start here for category navigation"
+    ];
+    for (const cat of uiReferences) {
+        const desc = categoryDescriptions[cat] ?? cat;
+        lines.push(`- \`references/${cat}.md\` — ${desc}`);
+    }
+    lines.push("", "When asked to build a component, consult the relevant references file first.", "Look for the **Minimum quality bar** checklist — every item must be satisfied", "before the component is considered complete.", "", "");
+    return lines.join("\n");
+}
+export 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)";
+    const refsSection = renderReferencesSection(config.uiReferences ?? []);
+    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.
+
+## What this project is
+
+You are working in **${name}** — a ${config.projectType ?? "web"} 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.
+
+- **Stack:** ${stack}
+- **Grid:** ${grid}px — all spacing must be a multiple
+- **Border radius:** ${ctrl}px (controls) · ${cont}px (containers)
+- **Active packs:** ${packs}
+
+## What to read
+
+Whale stores structured context in two locations:
+
+1. **\`intelligence/\`** — source of truth (JSON). Prefer these for precise data:
+   - \`intelligence/refinements.json\` — approved validator overrides
+   - \`intelligence/decisions.json\` — architectural and product decisions
+   - \`intelligence/components.json\` — component catalog
+
+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
+
+**Current status:** ${stats.errors} error(s) · ${stats.warnings} warning(s) · ${stats.decisionCount} decision(s) · ${stats.refinementCount} refinement(s) · ${stats.componentCount} component(s)
+
+${refsSection}## How to work here
+
+1. **Spacing.** Every padding, margin and gap must be a multiple of \`${grid}px\`. No exceptions.
+2. **Radius.** Buttons, inputs, selects → \`${ctrl}px\`. Cards, modals, sheets → \`${cont}px\`.
+3. **Color.** Prefer semantic tokens over raw hex. Adding a hex requires a refinement note.
+4. **Focus.** Every interactive element needs a visible \`:focus-visible\` state.
+5. **Decisions.** Non-obvious choices → propose \`whale decision\` so future sessions inherit the reasoning.
+6. **Refinements.** Honor \`intelligence/refinements.json\` — those are intentional team-approved exceptions.
+7. **Components.** Before building, check \`intelligence/components.json\`. After building, run \`whale component add <name>\`.
+
+## Commands available
+
+- \`whale validate\` — run 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 insights drift <category>\` — review style drift interactively
+- \`whale docs\` — generate human-facing reports
+
+---
+_Last sync: ${new Date().toISOString()}_
+`;
+}

package/dist/templates/components.js

@@ -0,0 +1,45 @@
+export 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._");
+        lines.push("", "_Generated by Whale Igniter._");
+        return lines.join("\n");
+    }
+    const sorted = [...components].sort((a, b) => a.name.localeCompare(b.name));
+    // Group by category
+    const grouped = new Map();
+    for (const c of sorted) {
+        const key = c.category ?? "uncategorized";
+        if (!grouped.has(key))
+            grouped.set(key, []);
+        grouped.get(key).push(c);
+    }
+    for (const [category, entries] of grouped) {
+        lines.push(`## ${capitalize(category)}`, "");
+        for (const c of entries) {
+            lines.push(`### ${c.name}`, "");
+            if (c.description)
+                lines.push(c.description, "");
+            const meta = [];
+            if (c.variants?.length)
+                meta.push(`Variants: ${c.variants.join(", ")}`);
+            if (c.states?.length)
+                meta.push(`States: ${c.states.join(", ")}`);
+            if (c.tokens?.length)
+                meta.push(`Tokens: ${c.tokens.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("_Generated by Whale Igniter._");
+    return lines.join("\n");
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/dist/templates/conventions.js

@@ -0,0 +1,45 @@
+export function renderConventions(config, refinements) {
+    const grid = config.foundations?.grid ?? 8;
+    const ctrl = config.foundations?.radius?.control ?? 2;
+    const cont = config.foundations?.radius?.container ?? 4;
+    const scoped = refinements.filter((r) => r.scope);
+    const scopeless = refinements.filter((r) => !r.scope);
+    const lines = [
+        "# Conventions",
+        "",
+        "## Confirmed conventions",
+        "",
+        `- Spacing is a multiple of ${grid}px. No exceptions without a refinement.`,
+        `- Controls (buttons, inputs, selects) use border-radius ${ctrl}px.`,
+        `- Containers (cards, modals, sheets) use border-radius ${cont}px.`,
+        "- Every interactive element has a visible `:focus-visible` state.",
+        "- Prefer semantic tokens over raw color values.",
+        ""
+    ];
+    if (scoped.length > 0) {
+        lines.push("### Active refinements (approved exceptions)", "");
+        lines.push("These have been reviewed and approved. The validator suppresses matching issues.", "");
+        for (const r of scoped) {
+            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("");
+    }
+    if (scopeless.length > 0) {
+        lines.push("## Open questions", "");
+        lines.push("These notes do not yet have a scope — the validator cannot act on them.", "Review and convert to scoped refinements or decisions.", "");
+        for (const r of scopeless) {
+            lines.push(`> ⚠️ Unresolved — **${r.timestamp.slice(0, 10)}**: ${r.note}`);
+        }
+        lines.push("");
+    }
+    lines.push("_Generated by Whale Igniter._");
+    return lines.join("\n");
+}

package/dist/templates/decisions.js

@@ -0,0 +1,34 @@
+const MAX_DETAIL = 500;
+function truncate(text) {
+    return text.length > MAX_DETAIL ? text.slice(0, MAX_DETAIL) + "…" : text;
+}
+export function renderDecisions(decisions) {
+    const lines = [
+        "# Decision Log",
+        "",
+        "Architectural, product and tooling decisions, most recent first.",
+        ""
+    ];
+    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(`_${d.timestamp.slice(0, 10)} · ${d.category} · ${d.status}_`);
+            lines.push("");
+            if (d.context) {
+                lines.push("**Context**", "", truncate(d.context), "");
+            }
+            lines.push("**Decision**", "", truncate(d.decision));
+            if (d.consequences) {
+                lines.push("", "**Consequences**", "", truncate(d.consequences));
+            }
+            lines.push("", "---", "");
+        }
+    }
+    lines.push("_Generated by Whale Igniter._");
+    return lines.join("\n");
+}

package/dist/templates/foundations.js

@@ -0,0 +1,34 @@
+export function renderFoundations(config, decisions = []) {
+    const grid = config.foundations?.grid ?? 8;
+    const ctrl = config.foundations?.radius?.control ?? 2;
+    const cont = config.foundations?.radius?.container ?? 4;
+    const foundationDecisions = decisions.filter((d) => d.category === "design-system" && d.status === "active");
+    const lines = [
+        "# Foundations",
+        "",
+        "The invariants of this project. All UI must conform unless explicitly refined.",
+        "",
+        "## Core values",
+        "",
+        `| Property | Value | Rule |`,
+        `| --- | --- | --- |`,
+        `| Grid unit | **${grid}px** | All spacing must be a multiple |`,
+        `| Control radius | **${ctrl}px** | Buttons, inputs, selects, toggles |`,
+        `| Container radius | **${cont}px** | Cards, modals, sheets, popovers |`,
+    ];
+    if (config.branding?.accent) {
+        lines.push(`| Accent | **${config.branding.accent}** | Brand color |`);
+    }
+    lines.push("", "## Spacing scale", "");
+    lines.push(`Grid: **${grid}px**. Allowed values:`);
+    lines.push("");
+    lines.push("`" + [1, 2, 3, 4, 5, 6, 8, 10, 12].map((n) => `${n * grid}px`).join("  ") + "`");
+    if (foundationDecisions.length > 0) {
+        lines.push("", "## Why these foundations", "");
+        for (const d of foundationDecisions.slice(0, 5)) {
+            lines.push(`- **${d.title}** _(${d.timestamp.slice(0, 10)})_ — ${d.decision}`);
+        }
+    }
+    lines.push("", "_Generated by Whale Igniter._");
+    return lines.join("\n");
+}

package/dist/templates/project.js

@@ -0,0 +1,82 @@
+export 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._
+`;
+}
+export 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._
+`;
+}
+export 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\`                |
+| Review style drift interactively              | \`whale insights drift <cat>\`|
+
+## 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.
+- **Per sprint:** review \`whale insights drift spacing\` for accumulated drift.
+
+_Generated by Whale Igniter._
+`;
+}

package/dist/utils/aiAvailability.js

@@ -0,0 +1,25 @@
+import { loadConfig } from "./config.js";
+import { resolveTarget } from "./paths.js";
+export async function getAiAvailability(target) {
+    if (process.env.ANTHROPIC_API_KEY) {
+        return { available: true, source: "env-anthropic" };
+    }
+    if (process.env.OPENAI_API_KEY) {
+        return { available: true, source: "env-openai" };
+    }
+    try {
+        const ws = resolveTarget(target);
+        const config = await loadConfig(ws);
+        const provider = config.selene?.provider;
+        if (provider === "anthropic" && process.env.ANTHROPIC_API_KEY) {
+            return { available: true, source: "config" };
+        }
+        if (provider === "openai" && process.env.OPENAI_API_KEY) {
+            return { available: true, source: "config" };
+        }
+    }
+    catch {
+        // config unreadable — no AI
+    }
+    return { available: false, source: "none" };
+}

package/dist/utils/wizardMapping.js

@@ -0,0 +1,54 @@
+const PROJECT_TYPE_MAP = {
+    "web-app": "web-app",
+    "marketing-site": "landing-page",
+    "portfolio": "landing-page",
+    "internal-tool": "web-app",
+    "prototype": "web-app",
+    "other": "other"
+};
+const STACK_MAP = {
+    "react-ts": "tailwind",
+    "vue-ts": "css",
+    "svelte-ts": "css",
+    "html-css-js": "css",
+    "other": "css"
+};
+const AI_TARGETS_MAP = {
+    solo: ["claude"],
+    small: ["claude", "codex"],
+    large: ["claude", "codex", "cursor"]
+};
+export function suggestUiCategories(projectType) {
+    const map = {
+        "web-app": ["forms", "navigation", "feedback"],
+        "marketing-site": ["surface", "layout"],
+        "portfolio": ["surface", "layout"],
+        "internal-tool": ["forms", "navigation", "feedback", "data-display"],
+        "prototype": ["forms", "feedback"],
+        "other": ["forms"]
+    };
+    return map[projectType] ?? ["forms"];
+}
+export function mapWizardAnswers(answers) {
+    const projectType = PROJECT_TYPE_MAP[answers.projectType];
+    const stack = STACK_MAP[answers.stack];
+    const aiTargets = AI_TARGETS_MAP[answers.teamSize];
+    const packs = answers.agentPacks && answers.agentPacks.length > 0
+        ? answers.agentPacks
+        : ["selene"];
+    const uiReferences = answers.uiCategories ?? [];
+    const config = {
+        projectType,
+        stack,
+        aiTargets: aiTargets,
+        packs,
+        uiReferences,
+        foundations: { grid: 8, radius: { control: 2, container: 4 } },
+        branding: { tone: "enterprise-minimal", accent: "cyan" },
+        intelligence: { trackPreferences: true, trackRefinements: true, decisionLogging: true }
+    };
+    const projectIntentNote = answers.projectType === "other" && answers.projectTypeOther
+        ? answers.projectTypeOther
+        : undefined;
+    return { config, projectIntentNote };
+}

package/dist/version.js

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.2.3";
+export const PACKAGE_VERSION = "1.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "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",
@@ -18,7 +18,7 @@
     "dev": "tsx src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
-    "test": "tsx tests/run.ts && tsx tests/mcp-smoke.ts",
+    "test": "tsx tests/run.ts && tsx tests/mcp-smoke.ts && tsx tests/extractors.ts && tsx tests/driftAnalyzers.ts",
     "prepublishOnly": "npm run build && npm test"
   },
   "engines": {