whale-igniter 1.5.1 → 1.5.3

package/dist/index.js

@@ -39,25 +39,31 @@ program
     .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")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .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);
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action(async (projectName, opts) => {
+    await initCommand(projectName, opts);
 });
 program
     .command("sync [target]")
-    .description("Regenerate CLAUDE.md and the LLM Wiki from intelligence/*.json.")
-    .action(syncCommand);
+    .description("Regenerate CLAUDE.md and the LLM Wiki from project intelligence.")
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action((target, opts) => syncCommand(target, opts));
 program
     .command("remember [target]")
     .description("Update project memory for AI assistants (friendly alias for sync).")
-    .action((target) => rememberCommand(target));
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action((target, opts) => rememberCommand(target, opts));
 program
     .command("check [target]")
     .description("Check project health and recommendations (validate + insights).")
-    .action((target) => checkCommand(target));
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .option("--full", "Show every validation issue instead of grouped summaries")
+    .action((target, opts) => checkCommand(target, opts));
 program
     .command("improve")
     .description("Ask Selene for project-wide improvement suggestions.")
@@ -73,7 +79,9 @@ program
 program
     .command("validate [target]")
     .description("Run operational validations (exits non-zero on errors).")
-    .action(validateCommand);
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .option("--full", "Show every validation issue instead of grouped summaries")
+    .action((target, opts) => validateCommand(target, opts));
 program
     .command("docs [target]")
     .description("Generate validation report and run installed generator packs.")
@@ -81,7 +89,8 @@ program
 program
     .command("wiki [target]")
     .description("Regenerate AI context (alias of `sync`).")
-    .action(wikiCommand);
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action((target, opts) => wikiCommand(target, opts));
 program
     .command("refine <note>")
     .description("Record an operational refinement. Mention an issue type to suppress matching issues.")
@@ -157,12 +166,14 @@ const insightsCmd = program
     .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)")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .action((target, opts) => insightsCommand(target, opts));
 insightsCmd
     .command("drift <category>")
     .description("Show or review drift in spacing | color | radii.")
     .option("--review", "Enter interactive review loop: accept as refinement, flag for refactor, or skip")
     .option("--target <path>", "Workspace path (default: cwd)")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .action((category, opts) => insightsDriftReviewCommand(category, opts));
 const create = program
     .command("create")
@@ -240,6 +251,7 @@ const adopt = program
     .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")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .action((target, opts) => adoptCommand(target, opts));
 adopt
     .command("review [target]")

package/dist/mcp/server.js

@@ -38,7 +38,6 @@ import { collectReferencedFiles, normalizePath } from "../analyzer/imports.js";
 import { scanComponents } from "../scanner/componentScanner.js";
 import { aggregateTailwind } from "../scanner/tailwindScanner.js";
 import { validateCss } from "../validators/cssValidator.js";
-import { randomUUID } from "node:crypto";
 import { PACKAGE_VERSION } from "../version.js";
 function ok(text) {
     return { content: [{ type: "text", text }] };
@@ -354,12 +353,7 @@ export function buildMcpServer() {
         if (!check.ok)
             return err(check.reason);
         const scope = inferScope(note);
-        await appendRefinement(ws, {
-            id: randomUUID(),
-            timestamp: new Date().toISOString(),
-            note,
-            scope
-        });
+        await appendRefinement(ws, { note, scope });
         await generateWiki(ws);
         const scopeDesc = scope
             ? `Scope inferred: ${Object.entries(scope).map(([k, v]) => `${k}=${v}`).join(", ")}.`
@@ -368,8 +362,8 @@ export function buildMcpServer() {
     });
     server.registerTool("whale_sync", {
         title: "Regenerate CLAUDE.md and the LLM wiki",
-        description: "Regenerates the AI-readable context files from intelligence/*.json. Call " +
-            "this if you've manually edited the JSON stores and want the wiki to catch " +
+        description: "Regenerates the AI-readable context files from project intelligence. Call " +
+            "this if you've manually edited the source stores and want the wiki to catch " +
             "up. Whale auto-syncs on every recorded change, so manual calls are rarely needed.",
         inputSchema: { target: z.string().optional() }
     }, async ({ target }) => {

package/dist/selene/promptBuilder.js

@@ -42,7 +42,7 @@ function renderProjectContext(ctx) {
     lines.push(`- Control radius: ${c.foundations?.radius?.control ?? 4}px (buttons, inputs)`);
     lines.push(`- Container radius: ${c.foundations?.radius?.container ?? 8}px (cards, modals)`);
     // Active decisions — show titles only to keep tokens down. Full text
-    // is available in intelligence/decisions.json if the model needs it.
+    // is available in the linked intelligence/decisions Markdown files.
     const active = ctx.decisions.filter((d) => d.status === "active");
     if (active.length > 0) {
         lines.push("");
@@ -52,7 +52,7 @@ function renderProjectContext(ctx) {
             lines.push(`- [${d.category}] ${d.title}`);
         }
         if (active.length > recent.length) {
-            lines.push(`- … and ${active.length - recent.length} more in intelligence/decisions.json`);
+            lines.push(`- … and ${active.length - recent.length} more in llm-wiki/DECISIONS.md`);
         }
     }
     if (ctx.refinements.length > 0) {

package/dist/templates/claude.js

@@ -33,7 +33,7 @@ export function renderRootIndex(config, stats) {
     const stack = config.stack ?? "css";
     const packs = (config.packs ?? []).join(", ") || "(none)";
     const refsSection = renderReferencesSection(config.uiReferences ?? []);
-    return `# AI Agent Context — ${name}
+    return `${stats.healthWarning ?? ""}# 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.
@@ -53,19 +53,27 @@ the design system, conventions and decisions without re-explaining them every se
 
 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
+1. **\`intelligence/\`** — source of truth. Prefer these for precise data:
+   - \`intelligence/refinements/\` — approved validator overrides as Markdown
+   - \`intelligence/decisions/\` — architectural and product decisions as ADRs
    - \`intelligence/components.json\` — component catalog
 
-2. **\`llm-wiki/\`** — human + AI readable markdown rendered from the JSON:
+2. **\`llm-wiki/\`** — compact human + AI readable markdown indexes:
    - \`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)
+## Current status
+
+- Decisions: ${stats.decisionCount}
+- Active refinements: ${stats.refinementCount}
+- Components: ${stats.componentCount}
+
+### Validation
+
+${stats.validationSummary}
 
 ${refsSection}## How to work here
 

package/dist/templates/conventions.js

@@ -28,7 +28,8 @@ export function renderConventions(config, refinements) {
             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}`);
+            const ref = r.sourcePath ? `[${r.id}](../${r.sourcePath})` : r.id;
+            lines.push(`- **${ref}** · ${r.timestamp.slice(0, 10)} — ${r.note}${scope}`);
         }
         lines.push("");
     }
@@ -36,7 +37,8 @@ export function renderConventions(config, refinements) {
         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}`);
+            const ref = r.sourcePath ? `[${r.id}](../${r.sourcePath})` : r.id;
+            lines.push(`> ⚠️ Unresolved — **${ref}** · ${r.timestamp.slice(0, 10)}: ${r.note}`);
         }
         lines.push("");
     }

package/dist/templates/decisions.js

@@ -1,12 +1,21 @@
-const MAX_DETAIL = 500;
-function truncate(text) {
-    return text.length > MAX_DETAIL ? text.slice(0, MAX_DETAIL) + "…" : text;
+const MAX_SUMMARY = 120;
+function summarize(d) {
+    const text = (d.context ?? d.decision).replace(/\s+/g, " ").trim();
+    const oneLine = text.length > MAX_SUMMARY ? text.slice(0, MAX_SUMMARY) + "…" : text;
+    return oneLine.replace(/\|/g, "\\|");
+}
+function linkFor(d) {
+    // Wiki lives in llm-wiki/; decisions live in intelligence/decisions/.
+    if (!d.sourcePath)
+        return d.title;
+    return `[${d.title}](../${d.sourcePath})`;
 }
 export function renderDecisions(decisions) {
     const lines = [
         "# Decision Log",
         "",
-        "Architectural, product and tooling decisions, most recent first.",
+        "Compact index of architectural, product and tooling decisions, most recent first.",
+        "Open the linked file for full Context / Decision / Consequences.",
         ""
     ];
     if (decisions.length === 0) {
@@ -14,20 +23,12 @@ export function renderDecisions(decisions) {
     }
     else {
         const sorted = [...decisions].sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        lines.push("| ID | Decision | Category | Status | Summary |");
+        lines.push("| --- | --- | --- | --- | --- |");
         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(`| ${d.id} | ${linkFor(d)} | ${d.category} | ${d.status} | ${summarize(d)} |`);
         }
+        lines.push("");
     }
     lines.push("_Generated by Whale Igniter._");
     return lines.join("\n");

package/dist/templates/project.js

@@ -1,5 +1,5 @@
-export function renderProject(config, errors, warnings, refinementCount, decisionCount) {
-    return `# Project Context
+export function renderProject(config, validationSummary, healthWarning, refinementCount, decisionCount) {
+    return `${healthWarning ?? ""}# Project Context
 
 - **Project name:** ${config.projectName ?? "(unset)"}
 - **Project type:** ${config.projectType ?? "unspecified"}
@@ -10,11 +10,13 @@ export function renderProject(config, errors, warnings, refinementCount, decisio
 
 ## Current status
 
-- Validation errors: ${errors}
-- Validation warnings: ${warnings}
 - Decisions logged: ${decisionCount}
 - Active refinements: ${refinementCount}
 
+## Validation
+
+${validationSummary}
+
 _Generated by Whale Igniter._
 `;
 }

package/dist/utils/decisions.js

@@ -1,9 +1,60 @@
 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);
+import matter from "gray-matter";
+const DIR = "intelligence/decisions";
+const LEGACY_STORE = "intelligence/decisions.json";
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
+function section(body, heading) {
+    const re = new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im");
+    const match = body.match(re);
+    const text = match?.[1]?.trim();
+    return text && text.length > 0 ? text : undefined;
+}
+function parseFile(raw) {
+    const { data, content } = matter(raw);
+    const decision = section(content, "Decision");
+    if (!data.id || !data.title || !decision)
+        return null;
+    return {
+        id: String(data.id),
+        timestamp: String(data.createdAt ?? data.timestamp ?? ""),
+        title: String(data.title),
+        category: (data.category ?? "architecture"),
+        context: section(content, "Context"),
+        decision,
+        consequences: section(content, "Consequences"),
+        status: (data.status ?? "active"),
+        supersedes: data.supersedes ? String(data.supersedes) : undefined
+    };
+}
+function serialize(d) {
+    const fm = matter.stringify([
+        "## Context",
+        d.context ?? "",
+        "",
+        "## Decision",
+        d.decision,
+        "",
+        "## Consequences",
+        d.consequences ?? ""
+    ].join("\n"), {
+        id: d.id,
+        title: d.title,
+        category: d.category,
+        status: d.status,
+        createdAt: d.timestamp,
+        supersedes: d.supersedes ?? null
+    });
+    return fm;
+}
+async function loadLegacy(target) {
+    const file = path.join(target, LEGACY_STORE);
     if (!(await fs.pathExists(file)))
         return [];
     try {
@@ -13,20 +64,49 @@ export async function loadDecisions(target) {
         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 loadDecisions(target) {
+    const dir = path.join(target, DIR);
+    const fromFiles = [];
+    if (await fs.pathExists(dir)) {
+        const entries = (await fs.readdir(dir)).filter((f) => f.endsWith(".md")).sort();
+        for (const entry of entries) {
+            const raw = await fs.readFile(path.join(dir, entry), "utf8");
+            const parsed = parseFile(raw);
+            if (parsed) {
+                parsed.sourcePath = `${DIR}/${entry}`;
+                fromFiles.push(parsed);
+            }
+        }
+    }
+    // Dual read: surface legacy JSON entries that haven't been migrated yet.
+    const legacy = await loadLegacy(target);
+    const seen = new Set(fromFiles.map((d) => d.id));
+    for (const d of legacy) {
+        if (!seen.has(d.id))
+            fromFiles.push(d);
+    }
+    return fromFiles;
+}
+function nextId(existing) {
+    let max = 0;
+    for (const d of existing) {
+        const m = /^ADR-(\d+)$/.exec(d.id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `ADR-${String(max + 1).padStart(4, "0")}`;
 }
 export async function appendDecision(target, input) {
-    const decisions = await loadDecisions(target);
+    const existing = await loadDecisions(target);
     const decision = {
-        id: randomUUID(),
-        timestamp: new Date().toISOString(),
+        id: nextId(existing),
+        timestamp: new Date().toISOString().slice(0, 10),
         status: "active",
         ...input
     };
-    decisions.push(decision);
-    await saveDecisions(target, decisions);
+    const dir = path.join(target, DIR);
+    await fs.ensureDir(dir);
+    const file = path.join(dir, `${decision.id}-${slugify(decision.title)}.md`);
+    await fs.writeFile(file, serialize(decision));
     return decision;
 }

package/dist/utils/refinements.js

@@ -1,9 +1,49 @@
 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);
+import matter from "gray-matter";
+const DIR = "intelligence/refinements";
+const LEGACY_STORE = "intelligence/refinements.json";
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
+function parseFile(raw) {
+    const { data, content } = matter(raw);
+    const note = content.trim();
+    if (!data.id || !note)
+        return null;
+    const scope = {};
+    if (data.issueType)
+        scope.issueType = String(data.issueType);
+    if (data.selector)
+        scope.selector = String(data.selector);
+    if (data.file)
+        scope.file = String(data.file);
+    return {
+        id: String(data.id),
+        timestamp: String(data.createdAt ?? data.timestamp ?? ""),
+        note,
+        scope: Object.keys(scope).length > 0 ? scope : undefined
+    };
+}
+function serialize(r) {
+    const fm = {
+        id: r.id,
+        createdAt: r.timestamp
+    };
+    if (r.scope?.issueType)
+        fm.issueType = r.scope.issueType;
+    if (r.scope?.selector)
+        fm.selector = r.scope.selector;
+    if (r.scope?.file)
+        fm.file = r.scope.file;
+    return matter.stringify(r.note, fm);
+}
+async function loadLegacy(target) {
+    const file = path.join(target, LEGACY_STORE);
     if (!(await fs.pathExists(file)))
         return [];
     try {
@@ -13,16 +53,49 @@ export async function loadRefinements(target) {
         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 loadRefinements(target) {
+    const dir = path.join(target, DIR);
+    const fromFiles = [];
+    if (await fs.pathExists(dir)) {
+        const entries = (await fs.readdir(dir)).filter((f) => f.endsWith(".md")).sort();
+        for (const entry of entries) {
+            const raw = await fs.readFile(path.join(dir, entry), "utf8");
+            const parsed = parseFile(raw);
+            if (parsed)
+                fromFiles.push({ ...parsed, sourcePath: `${DIR}/${entry}` });
+        }
+    }
+    // Dual read: surface legacy JSON entries that haven't been migrated yet.
+    const legacy = await loadLegacy(target);
+    const seen = new Set(fromFiles.map((r) => r.id));
+    for (const r of legacy) {
+        if (!seen.has(r.id))
+            fromFiles.push(r);
+    }
+    return fromFiles;
 }
-export async function appendRefinement(target, refinement) {
-    const current = await loadRefinements(target);
-    current.push(refinement);
-    await saveRefinements(target, current);
+function nextId(existing) {
+    let max = 0;
+    for (const r of existing) {
+        const m = /^REF-(\d+)$/.exec(r.id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `REF-${String(max + 1).padStart(4, "0")}`;
+}
+export async function appendRefinement(target, input) {
+    const existing = await loadRefinements(target);
+    const refinement = {
+        id: nextId(existing),
+        timestamp: new Date().toISOString().slice(0, 10),
+        note: input.note,
+        scope: input.scope
+    };
+    const dir = path.join(target, DIR);
+    await fs.ensureDir(dir);
+    const file = path.join(dir, `${refinement.id}-${slugify(refinement.note)}.md`);
+    await fs.writeFile(file, serialize(refinement));
+    return refinement;
 }
 // Lightweight natural-language extractor. Recognises hints like:
 //   "Button radius should remain 2px for controls" -> issueType: radius-consistency

package/dist/utils/targetGuard.js

@@ -0,0 +1,77 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import { ui } from "../ui/index.js";
+function isSamePath(a, b) {
+    return path.resolve(a) === path.resolve(b);
+}
+function isAncestorOf(ancestor, child) {
+    const relative = path.relative(ancestor, child);
+    return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function projectMarkerMessage(target, command) {
+    const commandHint = command ? `whale ${command}` : "this command";
+    return [
+        `This does not look like a project directory: ${target}`,
+        "I could not find a .git directory or package.json there.",
+        `Run ${ui.code(commandHint)} from inside your project, pass an explicit project path, or add ${ui.code("--force")} if this really is the target you want.`
+    ].join("\n");
+}
+function protectedDirectoryMessage(target, command) {
+    const commandHint = command ? `whale ${command} path/to/project` : "pass an explicit project path";
+    return [
+        `I will not run in ${target}.`,
+        "That directory is your home folder, the filesystem root, or a parent of your home folder.",
+        `Please cd into a project directory first, or run ${ui.code(commandHint)}.`
+    ].join("\n");
+}
+export async function checkTargetDirectory(target, options = {}) {
+    const resolvedTarget = path.resolve(target);
+    const home = path.resolve(os.homedir());
+    const root = path.parse(resolvedTarget).root;
+    if (isSamePath(resolvedTarget, home) ||
+        isSamePath(resolvedTarget, root) ||
+        isAncestorOf(resolvedTarget, home)) {
+        return {
+            ok: false,
+            target: resolvedTarget,
+            reason: "protected-directory",
+            message: protectedDirectoryMessage(resolvedTarget, options.command)
+        };
+    }
+    const hasGit = await fs.pathExists(path.join(resolvedTarget, ".git"));
+    const hasPackageJson = await fs.pathExists(path.join(resolvedTarget, "package.json"));
+    if (!hasGit && !hasPackageJson) {
+        const message = projectMarkerMessage(resolvedTarget, options.command);
+        if (!options.force) {
+            return {
+                ok: false,
+                target: resolvedTarget,
+                reason: "missing-project-marker",
+                message
+            };
+        }
+        return {
+            ok: true,
+            target: resolvedTarget,
+            warning: message
+        };
+    }
+    return { ok: true, target: resolvedTarget };
+}
+export async function guardTargetDirectory(target, options = {}) {
+    const result = await checkTargetDirectory(target, options);
+    if (!result.ok) {
+        console.log();
+        console.log(ui.fail(result.message));
+        console.log();
+        process.exitCode = 1;
+        return false;
+    }
+    if (result.warning) {
+        console.log();
+        console.log(ui.warn(result.warning));
+        console.log();
+    }
+    return true;
+}