whale-igniter 1.1.0

package/dist/validators/cssValidator.js

@@ -0,0 +1,204 @@
+import fs from "fs-extra";
+import { glob } from "glob";
+import path from "node:path";
+import postcss from "postcss";
+import { loadConfig } from "../utils/config.js";
+import { loadRefinements, isSuppressed } from "../utils/refinements.js";
+// Properties that take spacing values (length-based, grid-relevant).
+const SPACING_PROPS = new Set([
+    "margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
+    "padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
+    "gap", "row-gap", "column-gap",
+    "top", "right", "bottom", "left",
+    "width", "height", "min-width", "min-height", "max-width", "max-height"
+]);
+// Heuristic: a stylesheet is "interactive" if it styles something that needs focus.
+// Token sheets typically just declare custom properties; they don't need :focus-visible.
+function hasInteractiveTargets(root) {
+    let found = false;
+    root.walkRules((rule) => {
+        const sel = rule.selector;
+        if (sel.includes("button") ||
+            sel.includes("input") ||
+            sel.includes("select") ||
+            sel.includes("textarea") ||
+            sel.includes("a[") ||
+            /\ba\b/.test(sel) ||
+            sel.includes("[role=") ||
+            sel.includes("[tabindex")) {
+            found = true;
+            return false; // stop walking
+        }
+    });
+    return found;
+}
+// A token sheet is one that mostly declares CSS custom properties at :root.
+// We don't expect focus styles or grid compliance from these.
+function isTokenSheet(root) {
+    let customProps = 0;
+    let otherDecls = 0;
+    root.walkDecls((decl) => {
+        if (decl.prop.startsWith("--"))
+            customProps++;
+        else
+            otherDecls++;
+    });
+    return customProps > 0 && customProps >= otherDecls * 2;
+}
+// Parse a CSS value into individual length tokens. Ignores function calls
+// like url(...), var(...), calc(...) — those are handled separately.
+function extractPxValues(value) {
+    // Strip function calls so we don't pick up px inside url("foo.png?w=10px").
+    const stripped = value.replace(/\b\w+\s*\([^)]*\)/g, "");
+    const matches = stripped.matchAll(/(-?\d+(?:\.\d+)?)px\b/g);
+    const out = [];
+    for (const m of matches) {
+        out.push({ raw: m[0], px: parseFloat(m[1]) });
+    }
+    return out;
+}
+// Extract hex colors from a value, but ignore those inside url() or var()
+// (var() shouldn't contain hex but be safe). Also ignore inside strings.
+function extractHexColors(value) {
+    // Remove function-call contents and quoted strings first.
+    const cleaned = value
+        .replace(/"[^"]*"/g, "")
+        .replace(/'[^']*'/g, "")
+        .replace(/\b\w+\s*\([^)]*\)/g, "");
+    const matches = cleaned.matchAll(/#[0-9a-fA-F]{3,8}\b/g);
+    return Array.from(matches, (m) => m[0]);
+}
+function getSelectorFor(node) {
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === "rule")
+            return parent.selector;
+        parent = parent.parent;
+    }
+    return undefined;
+}
+export async function validateCss(target, options = {}) {
+    const config = options.configOverride ?? await loadConfig(target);
+    const refinements = await loadRefinements(target);
+    const grid = config.foundations?.grid ?? 8;
+    const allowedRadii = [
+        0,
+        config.foundations?.radius?.control ?? 2,
+        config.foundations?.radius?.container ?? 4
+    ];
+    const files = await glob("**/*.css", {
+        cwd: target,
+        absolute: true,
+        ignore: ["node_modules/**", "dist/**", ".git/**"]
+    });
+    const issues = [];
+    for (const file of files) {
+        const content = await fs.readFile(file, "utf8");
+        const relativeFile = path.relative(target, file);
+        let root;
+        try {
+            root = postcss.parse(content, { from: file });
+        }
+        catch (err) {
+            issues.push({
+                severity: "error",
+                type: "parse-error",
+                file: relativeFile,
+                line: 1,
+                column: 1,
+                message: `CSS parse failed: ${err.message}`,
+                suggestion: "Fix the CSS syntax."
+            });
+            continue;
+        }
+        const tokenSheet = isTokenSheet(root);
+        root.walkDecls((decl) => {
+            const line = decl.source?.start?.line ?? 1;
+            const column = decl.source?.start?.column ?? 1;
+            const selector = getSelectorFor(decl);
+            // Skip declarations inside custom-property definitions —
+            // token sheets are allowed to declare raw values.
+            const isCustomPropDef = decl.prop.startsWith("--");
+            // --- Raw hex colors ---
+            if (!isCustomPropDef) {
+                const hexes = extractHexColors(decl.value);
+                for (const hex of hexes) {
+                    const issue = {
+                        severity: "warning",
+                        type: "raw-hex-color",
+                        file: relativeFile,
+                        line,
+                        column,
+                        message: `Raw hex color detected: ${hex}`,
+                        suggestion: "Use a semantic CSS token (var(--color-...)) instead.",
+                        selector
+                    };
+                    if (!isSuppressed(issue, refinements))
+                        issues.push(issue);
+                }
+            }
+            // --- Spacing grid compliance ---
+            if (SPACING_PROPS.has(decl.prop) && !isCustomPropDef) {
+                const pxValues = extractPxValues(decl.value);
+                for (const { raw, px } of pxValues) {
+                    if (px === 0)
+                        continue;
+                    if (px % grid !== 0) {
+                        const nearest = Math.round(px / grid) * grid;
+                        const issue = {
+                            severity: "error",
+                            type: "spacing-scale",
+                            file: relativeFile,
+                            line,
+                            column,
+                            message: `${decl.prop}: ${raw} does not follow the ${grid}px grid.`,
+                            suggestion: `Use ${nearest}px or a spacing token.`,
+                            selector
+                        };
+                        if (!isSuppressed(issue, refinements))
+                            issues.push(issue);
+                    }
+                }
+            }
+            // --- Border radius consistency ---
+            if (decl.prop === "border-radius" && !isCustomPropDef) {
+                const pxValues = extractPxValues(decl.value);
+                for (const { raw, px } of pxValues) {
+                    if (!allowedRadii.includes(px)) {
+                        const issue = {
+                            severity: "error",
+                            type: "radius-consistency",
+                            file: relativeFile,
+                            line,
+                            column,
+                            message: `Invalid border-radius: ${raw}.`,
+                            suggestion: `Use ${allowedRadii.filter((r) => r > 0).join("px or ")}px (controls vs. containers).`,
+                            selector
+                        };
+                        if (!isSuppressed(issue, refinements))
+                            issues.push(issue);
+                    }
+                }
+            }
+        });
+        // --- Focus-visible: only required on sheets with interactive targets,
+        // and only flagged once per sheet, not once per declaration. ---
+        if (!tokenSheet && hasInteractiveTargets(root) && !content.includes(":focus-visible")) {
+            const issue = {
+                severity: "warning",
+                type: "focus-visible",
+                file: relativeFile,
+                line: 1,
+                column: 1,
+                message: "Stylesheet has interactive elements but no :focus-visible state.",
+                suggestion: "Add visible keyboard focus styles for buttons/inputs/links."
+            };
+            if (!isSuppressed(issue, refinements))
+                issues.push(issue);
+        }
+    }
+    return issues;
+}
+export function hasErrors(issues) {
+    return issues.some((i) => i.severity === "error");
+}

package/dist/version.js

@@ -0,0 +1 @@
+export const PACKAGE_VERSION = "1.1.0";

package/docs/ROADMAP.md

@@ -0,0 +1,206 @@
+# Whale Igniter — Roadmap
+
+The path from "a CLI that bootstraps AI context" to "the operating
+system for AI-assisted product work."
+
+This roadmap is followed in order. We don't skip versions; if a step
+reveals that the next plan needs revising, we revise it before shipping.
+
+---
+
+## Shipped
+
+### v0.6 — Real validation + closed refinement loop
+
+- PostCSS-based CSS validator (no regex, AST-correct).
+- Foundations driven by `whale.config.json`.
+- Scope-inferred refinements suppress matching issues automatically.
+- Pack taxonomy: executable vs. generator.
+
+### v0.7 — AI context bootstrapper
+
+- `whale ignite` in three modes (opinionated, minimal, interactive wizard).
+- `CLAUDE.md` at project root + optional `AGENTS.md`, `.cursorrules`,
+  `.github/copilot-instructions.md`.
+- Structured stores: `decisions.json`, `components.json`,
+  `refinements.json`.
+- Auto-sync on every recorded change.
+
+### v0.8 — Brownfield adoption
+
+- `whale adopt` scans React + Tailwind projects with a real AST.
+- Component detection across function / arrow / forwardRef / memo /
+  class patterns. Entry-point names excluded.
+- Tailwind class observation pipeline with variant stripping, arbitrary
+  values, font-size vs color disambiguation, ring-width handling.
+- Foundation inference: grid via weighted coverage, radii with single
+  vs split detection, color palette.
+- Staged proposals in `intelligence/proposed.json` with idempotent
+  fingerprints; interactive `adopt review` with accept/reject/edit.
+
+### v0.9 — Insights + generation
+
+- `whale insights` analyzer with 7+ deterministic checks: refinement
+  clusters, scopeless refinements, catalog coverage, orphan
+  components, decision tension, token drift, grid drift.
+- `whale create component <Name>` generates typed React scaffolds
+  respecting current foundations (control or container template).
+- `--json`, `--category`, `--min-severity` for scripting / CI.
+
+### v0.10 — Selene MVP (prompt mode)
+
+- `whale selene describe / audit / suggest / apply`.
+- Prompt builder composes self-contained prompts with project context,
+  task, input, and strict output schemas.
+- Robust response parser handles preambles, multiple fenced blocks,
+  bare JSON. Type-guarded schemas.
+- Clipboard helper with cross-platform cascade (pbcopy / clip.exe /
+  wl-copy / xclip / xsel) and zero npm dependencies.
+- Works fully offline.
+
+### v0.11 — Selene API mode
+
+- Auto-detect `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` and call directly.
+- Bloque `selene` en `whale.config.json` para model, temperature,
+  autoCall, confirmCost, noCache.
+- Pre-flight cost estimation, opt-in via `--confirm-cost`.
+- On-disk response cache (sha256, 7-day TTL).
+- Transparent fallback to prompt mode on any API failure.
+
+### v1.0 — Production
+
+- **MCP server.** Ten tools exposed over stdio: `whale_project_overview`,
+  `whale_list_components`, `whale_list_decisions`,
+  `whale_list_refinements`, `whale_validate`, `whale_insights`,
+  `whale_register_component`, `whale_record_decision`,
+  `whale_record_refinement`, `whale_sync`. Configurable for Claude Code,
+  Cursor, Zed, or any MCP client via `whale mcp config`.
+- **File watcher.** `whale watch` regenerates CLAUDE.md and wiki on
+  changes to foundations or intelligence stores. Debounced, with
+  in-flight coalescing.
+- **npm distribution.** Published as `whale-igniter`. Works with
+  `npx whale-igniter` or global install.
+- **Production package.** Engines, license, files, .npmignore,
+  prepublishOnly script. README and ROADMAP refreshed.
+- **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
+
+The terminal output became the product surface. Commands stopped reaching
+for chalk directly; every command now consumes a semantic UI layer where
+output describes *intent* (success, warning, section header, key/value
+pair) and the active theme decides what each intent looks like.
+
+- **Semantic UI layer in `src/ui/`.** Atoms (color roles), symbols (glyphs
+  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
+  text-hierarchy levels. Structure ready for v1.2's multi-theme without
+  touching any command.
+- **Capability detection.** Auto-detects color and Unicode support; falls
+  back to ASCII glyphs (`*`, `v`, `x`, `->`) and plain output without a
+  TTY. Three env overrides — `WHALE_PLAIN`, `WHALE_UNICODE`, `NO_COLOR` —
+  let users force a mode in CI logs or in legacy terminals.
+- **All 12 commands migrated.** ignite, adopt, adopt review, init, sync,
+  wiki, validate, refine, decision, component (add/list), create
+  component, add, docs, watch, mcp (serve/config), selene (describe /
+  audit / suggest / apply / status / cache). Zero `chalk` imports outside
+  `src/ui/theme.ts`.
+- **Tests.** 14 new UI tests on top of the v1.0 suite: capability
+  detection, theme structure, block formatting, alignment, glyph fallback.
+  Total: 61 unit tests + 6 MCP smoke checks, all green.
+
+---
+
+## Next
+
+The post-v1.1 plan is shaped by what actual users hit first. The list
+below is in rough priority order, but every item will be re-evaluated
+once real usage produces feedback.
+
+### v1.2 — Hardening from real-world usage
+
+Now that the surface area is feature-complete, the next version should
+be small and reactive. Expected items:
+
+- Edge cases in the scanner discovered against larger repos (10k+ LOC
+  Next.js apps, monorepos).
+- MCP server polishing: better error messages, validation of inputs
+  the agents pass, telemetry helpers for the user to debug.
+- Pre-commit hook helper: `whale hook install` to wire up
+  `whale validate && whale sync` automatically.
+- Selene prompt caching at the Anthropic API level (split the context
+  prefix as a separate system message so caching can hit).
+- Optional second theme once real users have asked for it. The
+  architecture is ready; we're deliberately waiting for demand before
+  shipping more themes.
+
+### v1.3 — Multi-framework parsing
+
+The Vue + Svelte parser is the largest stretch from current code. The
+rest of the pipeline (foundation inference, insights, generators) is
+already framework-agnostic; only the scanner needs new dialects.
+
+### v1.4 — Style-system breadth
+
+CSS-in-JS (vanilla-extract, Panda CSS, styled-components), plus
+Tailwind config resolution that actually evaluates the user's
+`tailwind.config.{js,ts}` for accurate scales. Style Dictionary /
+Figma Tokens import would slot in here too.
+
+### v2.0 — Team layer (uncommitted)
+
+The decision we keep deferring: how teams collaborate around
+`intelligence/`. Today it's local + git, and PRs are the workflow. At
+some scale that breaks down — multiple writers, conflicting
+decisions, no review surface. Possibilities:
+
+- A "shared inbox" of proposed decisions/refinements that need
+  approval, separate from accepted ones.
+- A web viewer for the wiki that's read-only and link-shareable.
+- A schema lock that prevents PRs from contradicting active decisions
+  without an explicit `supersedes`.
+
+We won't pick one until we have multiple teams telling us which one
+they need most.
+
+---
+
+## What we will NOT do
+
+These are listed explicitly to defend focus over time.
+
+- **A web dashboard.** Whale is CLI-first. Forever.
+- **A hosted SaaS.** Intelligence stays in the user's repo. No accounts.
+- **Generic linting.** ESLint, Stylelint, Biome already exist. Whale's
+  validators only check what's tied to operational context (foundations,
+  refinements, decisions). Everything else is out of scope.
+- **Lighthouse-style perf / SEO audits.** Different problem space. The
+  `lighthouse` pack name is about *guidance* (the lighthouse metaphor),
+  not the Google tool.
+- **Project management.** No tasks, no kanban, no time tracking.
+
+---
+
+## Operational milestones (not engineering work)
+
+These are tasks that depend on the project owner, not on the codebase:
+
+- **Publish to npm.** Code is ready. Requires an npm account and
+  `npm publish` from a clean checkout.
+- **Public repo.** Move from local zips to a versioned GitHub repo
+  with releases.
+- **Demo video.** Record the 5-minute "adopt a real repo and watch
+  Claude Code work with full context" walkthrough referenced in the
+  done criteria.
+- **Field test.** Adopt the tool in three real projects (own or
+  partner teams) and feed observations into v1.1.
+
+Until those happen, v1.0 is "feature-complete and ready to ship" but
+not "released and validated in the wild."
+
+---
+
+_Last updated: v1.1 release._

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "whale-igniter",
+  "version": "1.1.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",
+  "bin": {
+    "whale": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs/ROADMAP.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "tsx tests/run.ts && tsx tests/mcp-smoke.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "cli",
+    "design-system",
+    "ai",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "mcp",
+    "model-context-protocol",
+    "tailwind",
+    "react",
+    "design-ops",
+    "intelligence",
+    "documentation",
+    "ai-context",
+    "agents-md"
+  ],
+  "author": "Whale Igniter contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/luisviol/whale-igniter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/luisviol/whale-igniter/issues"
+  },
+  "homepage": "https://github.com/luisviol/whale-igniter#readme",
+  "dependencies": {
+    "@babel/parser": "^7.25.0",
+    "@babel/traverse": "^7.25.0",
+    "@babel/types": "^7.25.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "glob": "^10.4.5",
+    "ora": "^8.1.0",
+    "postcss": "^8.4.47",
+    "prompts": "^2.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.20.6",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.0.0",
+    "@types/prompts": "^2.4.9",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.4"
+  }
+}