whale-igniter 1.1.0

package/dist/ui/capabilities.js

@@ -0,0 +1,64 @@
+/**
+ * Terminal capability detection.
+ *
+ * The UI layer asks two questions of every output:
+ *   1. Can the terminal render ANSI color?
+ *   2. Can the terminal render Unicode symbols?
+ *
+ * Answering "no" to (1) is common in CI logs and when piping. Answering
+ * "no" to (2) is rare on modern terminals but happens in containers
+ * with C/POSIX locales and in dumb terminals. Chalk handles (1) on its
+ * own, so this module mostly exists for (2) plus a global "plain"
+ * override.
+ *
+ * Overrides:
+ *   - WHALE_PLAIN=1 — disable color AND unicode, useful for CI logs and grep
+ *   - WHALE_UNICODE=0 — disable unicode but keep color
+ *   - NO_COLOR / FORCE_COLOR — standard chalk-respected vars (informational only here)
+ */
+const ASCII_LOCALE = /^(C|POSIX)$/i;
+function detectColor() {
+    if (process.env.WHALE_PLAIN === "1")
+        return false;
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR === "0")
+        return false;
+    if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0")
+        return true;
+    return process.stdout.isTTY === true;
+}
+function detectUnicode() {
+    if (process.env.WHALE_PLAIN === "1")
+        return false;
+    if (process.env.WHALE_UNICODE === "0")
+        return false;
+    if (process.env.LANG && /UTF-?8/i.test(process.env.LANG))
+        return true;
+    if (process.env.LC_ALL && /UTF-?8/i.test(process.env.LC_ALL))
+        return true;
+    if (process.env.LC_CTYPE && /UTF-?8/i.test(process.env.LC_CTYPE))
+        return true;
+    // Common modern-terminal signals.
+    if (process.env.WT_SESSION)
+        return true;
+    if (process.env.TERM_PROGRAM === "vscode")
+        return true;
+    if (process.env.TERM_PROGRAM === "iTerm.app")
+        return true;
+    if (process.env.LANG && ASCII_LOCALE.test(process.env.LANG))
+        return false;
+    // Default: assume Unicode if attached to a TTY.
+    return process.stdout.isTTY === true;
+}
+let cached = null;
+export function capabilities() {
+    if (cached)
+        return cached;
+    cached = { color: detectColor(), unicode: detectUnicode() };
+    return cached;
+}
+/** Test-only — clear the memo so tests can flip env vars between cases. */
+export function resetCapabilities() {
+    cached = null;
+}

package/dist/ui/index.js

@@ -0,0 +1,13 @@
+/**
+ * The UI layer's public surface.
+ *
+ *   import { ui } from "../ui/index.js";
+ *   console.log(ui.header("Whale Igniter", "ignite"));
+ *
+ * Everything a command needs lives on `ui`. Individual atoms are
+ * importable if needed but `ui.<name>` is the canonical entry point.
+ */
+export { ui } from "./blocks.js";
+export * from "./atoms.js";
+export { glyph } from "./symbols.js";
+export { theme, setTheme } from "./theme.js";

package/dist/ui/symbols.js

@@ -0,0 +1,41 @@
+/**
+ * Pre-styled glyphs. Use these when you want the icon + the correct
+ * color in one shot, instead of composing them every time.
+ *
+ * Naming mirrors the symbol roles in theme.ts so the autocomplete is
+ * predictable: `glyph.check`, `glyph.cross`, etc.
+ */
+import { theme } from "./theme.js";
+import { accent, success, danger, warning, info as infoColor, muted } from "./atoms.js";
+/**
+ * Standalone glyphs. Use when a renderer needs the glyph alone.
+ */
+export const glyph = {
+    get diamond() {
+        return accent(theme().symbols.diamond);
+    },
+    get check() {
+        return success(theme().symbols.check);
+    },
+    get cross() {
+        return danger(theme().symbols.cross);
+    },
+    get warn() {
+        return warning(theme().symbols.warn);
+    },
+    get info() {
+        return infoColor(theme().symbols.info);
+    },
+    get bullet() {
+        return muted(theme().symbols.bullet);
+    },
+    get dot() {
+        return muted(theme().symbols.dot);
+    },
+    get arrow() {
+        return accent(theme().symbols.arrow);
+    },
+    get tee() {
+        return muted(theme().symbols.tee);
+    }
+};

package/dist/ui/theme.js

@@ -0,0 +1,78 @@
+/**
+ * Theme — semantic tokens for the Whale Igniter CLI.
+ *
+ * The rule: commands describe *intent* (this is a section header,
+ * this is a success state, this is dim metadata), not appearance.
+ * The theme decides what intent looks like.
+ *
+ * v1.1 ships one theme. The structure deliberately matches the shape
+ * a multi-theme system in v1.2 will need, so swapping themes will be
+ * a one-line change in the resolver, not a refactor of every renderer.
+ */
+import chalkLib, { Chalk } from "chalk";
+import { capabilities } from "./capabilities.js";
+/**
+ * Resolve the chalk instance once per process. If WHALE_PLAIN is set
+ * we force level 0, otherwise we let chalk's auto-detection decide.
+ */
+function resolveChalk() {
+    if (process.env.WHALE_PLAIN === "1") {
+        return new Chalk({ level: 0 });
+    }
+    return chalkLib;
+}
+const chalk = resolveChalk();
+/**
+ * Pick Unicode or ASCII symbol based on terminal capabilities.
+ * Used inline below so the active theme always has the right glyphs.
+ */
+function pick(unicodeGlyph, asciiFallback) {
+    return capabilities().unicode ? unicodeGlyph : asciiFallback;
+}
+// ---------------------------------------------------------------------------
+// Whale theme — the only theme that ships in v1.1.
+// ---------------------------------------------------------------------------
+const whale = {
+    name: "whale",
+    identity: {
+        accent: chalk.cyan,
+        // bold without color — combined with accent it produces "cyan bold"
+        // when wrapped through accent(emphasis(...))
+        emphasis: chalk.bold
+    },
+    semantic: {
+        success: chalk.green,
+        warning: chalk.yellow,
+        danger: chalk.red,
+        info: chalk.cyan,
+        muted: chalk.gray,
+        code: chalk.cyan,
+        path: chalk.cyan,
+        heading: chalk.bold,
+        subheading: chalk.bold.gray
+    },
+    symbols: {
+        diamond: pick("◆", "*"),
+        check: pick("✓", "v"),
+        cross: pick("✗", "x"),
+        warn: pick("!", "!"),
+        info: pick("·", "-"),
+        bullet: pick("•", "-"),
+        dot: pick("·", "."),
+        arrow: pick("→", "->"),
+        rule: pick("─", "-"),
+        tee: pick("└", "`-")
+    }
+};
+let active = whale;
+/** Get the active theme. Single global — fine for a CLI process. */
+export function theme() {
+    return active;
+}
+/**
+ * Replace the active theme. Exists so v1.2 can introduce a `whale theme set`
+ * command without touching anything in src/ui/. v1.1 doesn't expose this.
+ */
+export function setTheme(next) {
+    active = next;
+}

package/dist/utils/components.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { randomUUID } from "node:crypto";
+const STORE = "intelligence/components.json";
+export async function loadComponents(target) {
+    const file = path.join(target, STORE);
+    if (!(await fs.pathExists(file)))
+        return [];
+    try {
+        return await fs.readJson(file);
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveComponents(target, components) {
+    const file = path.join(target, STORE);
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeJson(file, components, { spaces: 2 });
+}
+export async function upsertComponent(target, input) {
+    const components = await loadComponents(target);
+    const now = new Date().toISOString();
+    const existing = components.find((c) => c.name === input.name);
+    if (existing) {
+        Object.assign(existing, input, { updatedAt: now });
+        await saveComponents(target, components);
+        return existing;
+    }
+    const created = {
+        id: randomUUID(),
+        addedAt: now,
+        updatedAt: now,
+        ...input,
+        name: input.name
+    };
+    components.push(created);
+    await saveComponents(target, components);
+    return created;
+}

package/dist/utils/config.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import fs from "fs-extra";
+export const DEFAULT_CONFIG = {
+    projectType: "landing-page",
+    stack: "css",
+    aiTargets: ["claude"],
+    packs: ["lighthouse", "scribe"],
+    foundations: {
+        grid: 8,
+        radius: { control: 2, container: 4 }
+    },
+    branding: { tone: "enterprise-minimal", accent: "cyan" },
+    intelligence: { trackPreferences: true, trackRefinements: true, decisionLogging: true }
+};
+export async function loadConfig(target) {
+    const configPath = path.join(target, "whale.config.json");
+    if (!(await fs.pathExists(configPath))) {
+        return DEFAULT_CONFIG;
+    }
+    try {
+        const raw = await fs.readJson(configPath);
+        return { ...DEFAULT_CONFIG, ...raw };
+    }
+    catch {
+        return DEFAULT_CONFIG;
+    }
+}
+export async function saveConfig(target, config) {
+    const configPath = path.join(target, "whale.config.json");
+    await fs.writeJson(configPath, config, { spaces: 2 });
+}

package/dist/utils/decisions.js

@@ -0,0 +1,32 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { randomUUID } from "node:crypto";
+const STORE = "intelligence/decisions.json";
+export async function loadDecisions(target) {
+    const file = path.join(target, STORE);
+    if (!(await fs.pathExists(file)))
+        return [];
+    try {
+        return await fs.readJson(file);
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveDecisions(target, decisions) {
+    const file = path.join(target, STORE);
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeJson(file, decisions, { spaces: 2 });
+}
+export async function appendDecision(target, input) {
+    const decisions = await loadDecisions(target);
+    const decision = {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        status: "active",
+        ...input
+    };
+    decisions.push(decision);
+    await saveDecisions(target, decisions);
+    return decision;
+}

package/dist/utils/paths.js

@@ -0,0 +1,4 @@
+import path from "node:path";
+export function resolveTarget(target) {
+    return path.resolve(process.cwd(), target ?? ".");
+}

package/dist/utils/proposals.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { createHash } from "node:crypto";
+const STORE_PATH = "intelligence/proposed.json";
+const EMPTY = { scannedAt: null, scannerVersion: "0.8.0", proposals: [] };
+export async function loadProposals(target) {
+    const file = path.join(target, STORE_PATH);
+    if (!(await fs.pathExists(file)))
+        return { ...EMPTY };
+    try {
+        return await fs.readJson(file);
+    }
+    catch {
+        return { ...EMPTY };
+    }
+}
+export async function saveProposals(target, store) {
+    const file = path.join(target, STORE_PATH);
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeJson(file, store, { spaces: 2 });
+}
+/**
+ * Deterministic fingerprint so re-running `adopt` doesn't duplicate.
+ * We hash kind + identifying fields, not the whole payload — that way
+ * a component whose className list changes still has the same
+ * fingerprint and we can update it in place.
+ */
+export function fingerprintComponent(name, file) {
+    return createHash("sha256").update(`component::${name}::${file}`).digest("hex").slice(0, 16);
+}
+export function fingerprintDecision(title, category) {
+    return createHash("sha256").update(`decision::${title}::${category}`).digest("hex").slice(0, 16);
+}
+export function fingerprintFoundations() {
+    // There's only ever one foundations proposal at a time.
+    return "foundations::singleton";
+}
+/**
+ * Upsert a proposal by fingerprint. Returns true if it was newly added,
+ * false if it updated an existing entry. Status of an existing reviewed
+ * proposal is preserved — we don't re-open accepted/rejected items
+ * automatically. The user can re-open via `--reset` (future).
+ */
+export function upsertProposal(store, proposal) {
+    const idx = store.proposals.findIndex((p) => p.fingerprint === proposal.fingerprint);
+    if (idx === -1) {
+        store.proposals.push(proposal);
+        return { added: true, preserved: false };
+    }
+    const existing = store.proposals[idx];
+    if (existing.status !== "pending") {
+        // User already decided on this. Don't overwrite their decision.
+        return { added: false, preserved: true };
+    }
+    // Update payload/evidence but keep timestamps.
+    store.proposals[idx] = { ...proposal, proposedAt: existing.proposedAt };
+    return { added: false, preserved: false };
+}
+export function pendingProposals(store) {
+    return store.proposals.filter((p) => p.status === "pending");
+}

package/dist/utils/refinements.js

@@ -0,0 +1,81 @@
+import path from "node:path";
+import fs from "fs-extra";
+const STORE_FILENAME = "refinements.json";
+const STORE_DIR = "intelligence";
+export async function loadRefinements(target) {
+    const file = path.join(target, STORE_DIR, STORE_FILENAME);
+    if (!(await fs.pathExists(file)))
+        return [];
+    try {
+        return await fs.readJson(file);
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveRefinements(target, refinements) {
+    const dir = path.join(target, STORE_DIR);
+    await fs.ensureDir(dir);
+    const file = path.join(dir, STORE_FILENAME);
+    await fs.writeJson(file, refinements, { spaces: 2 });
+}
+export async function appendRefinement(target, refinement) {
+    const current = await loadRefinements(target);
+    current.push(refinement);
+    await saveRefinements(target, current);
+}
+// Lightweight natural-language extractor. Recognises hints like:
+//   "Button radius should remain 2px for controls" -> issueType: radius-consistency
+//   "Spacing of 6px is intentional in legacy/" -> issueType: spacing-scale, file: legacy
+// This is intentionally conservative: it only suppresses when the note
+// clearly references a known issue type. Anything ambiguous becomes a
+// note-only refinement (still logged, but not active).
+export function inferScope(note) {
+    const lower = note.toLowerCase();
+    const scope = {};
+    // Issue type detection
+    if (/\bradius\b|\bborder[\s-]?radius\b/.test(lower)) {
+        scope.issueType = "radius-consistency";
+    }
+    else if (/\bspacing\b|\bpadding\b|\bmargin\b|\bgap\b|\bgrid\b/.test(lower)) {
+        scope.issueType = "spacing-scale";
+    }
+    else if (/\bhex\b|\bcolou?r\b/.test(lower)) {
+        scope.issueType = "raw-hex-color";
+    }
+    else if (/\bfocus\b/.test(lower)) {
+        scope.issueType = "focus-visible";
+    }
+    // Selector detection: words like "button", "input", "card"
+    const selectorMatch = lower.match(/\b(button|input|select|card|hero|nav|footer|header|modal)s?\b/);
+    if (selectorMatch) {
+        scope.selector = selectorMatch[1];
+    }
+    // File scope: "in <path>" or "for <path>"
+    const fileMatch = note.match(/\b(?:in|for|inside)\s+([./\w-]+\/[\w./-]+)/);
+    if (fileMatch) {
+        scope.file = fileMatch[1];
+    }
+    return Object.keys(scope).length > 0 ? scope : undefined;
+}
+// Check whether a given issue should be suppressed by any active refinement.
+// A refinement suppresses an issue when ALL its specified scope fields match.
+// If a refinement has no scope at all, it does NOT suppress anything — it's
+// just a logged note.
+export function isSuppressed(issue, refinements) {
+    for (const r of refinements) {
+        if (!r.scope)
+            continue;
+        if (r.scope.issueType && r.scope.issueType !== issue.type)
+            continue;
+        if (r.scope.file && !issue.file.includes(r.scope.file))
+            continue;
+        if (r.scope.selector) {
+            if (!issue.selector || !issue.selector.toLowerCase().includes(r.scope.selector))
+                continue;
+        }
+        // All present scope fields matched.
+        return true;
+    }
+    return false;
+}

package/dist/utils/registry.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// The registry lives in the package itself, not in user projects.
+// User projects only reference packs by name in whale.config.json.
+const REGISTRY = {
+    lighthouse: {
+        name: "lighthouse",
+        kind: "executable",
+        description: "Accessibility audits, contrast and semantic validation."
+    },
+    selene: {
+        name: "selene",
+        kind: "executable",
+        description: "AI-assisted UX intelligence and refinement memory."
+    },
+    forge: {
+        name: "forge",
+        kind: "generator",
+        description: "Implementation specs, dev contracts and handoff.",
+        audience: "engineering",
+        template: "handoff"
+    },
+    scribe: {
+        name: "scribe",
+        kind: "generator",
+        description: "Generated docs, recipes and READMEs.",
+        audience: "team",
+        template: "docs"
+    },
+    atlas: {
+        name: "atlas",
+        kind: "generator",
+        description: "Product strategy, decision logs and roadmaps.",
+        audience: "product",
+        template: "strategy"
+    }
+};
+export function getPack(name) {
+    return REGISTRY[name];
+}
+export function listPacks() {
+    return Object.values(REGISTRY);
+}

package/dist/utils/writeJson.js

@@ -0,0 +1,6 @@
+import path from "node:path";
+import fs from "fs-extra";
+export async function writeJsonFile(filePath, data) {
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2));
+}