@vendoai/vendo 0.4.0

package/dist/cli/theme/extract-theme.js

@@ -0,0 +1,358 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { contrastingText, normalizeColor, normalizeLength, resolveCssVarRefs } from "./color.js";
+import { parseCssVars } from "./css-vars.js";
+import { ENTRY_FILE_CANDIDATES } from "./entry-candidates.js";
+import { walk } from "./walk.js";
+/** Key ORDER is load-bearing: assembleTheme derives accentText from the
+ *  already-settled accent and headingFamily from fontFamily within one pass
+ *  over SLOT_KEYS, so accent must precede accentText and fontFamily must
+ *  precede headingFamily. Do not alphabetize. */
+const DEFAULT_THEME_SLOTS = {
+    accent: "#2563eb",
+    accentText: "#ffffff",
+    background: "#ffffff",
+    border: "#e2e8f0",
+    danger: "#dc2626",
+    surface: "#f8fafc",
+    text: "#0f172a",
+    mutedText: "#64748b",
+    radius: "8px",
+    fontFamily: "system-ui, sans-serif",
+    headingFamily: "system-ui, sans-serif",
+    baseSize: "16px",
+    density: "comfortable",
+    motion: "full",
+};
+const CSS_IMPORT_RE = /\bimport\s+(?:[^"']+\s+from\s+)?["']([^"']+\.css)["']|\brequire\(\s*["']([^"']+\.css)["']\s*\)/g;
+const CSS_AT_IMPORT_RE = /@import\s+(?:url\(\s*)?["']?([^"')\s;]+)["']?\s*\)?/g;
+const CSS_FALLBACK_NAME = /^(?:globals?|app|main|index|tokens?|theme|styles?)\.css$/;
+const MAX_CSS_FILES = 12;
+const MAX_FILE_BYTES = 24_000;
+async function readCapped(file) {
+    try {
+        const content = await fs.readFile(file, "utf8");
+        return content.length > MAX_FILE_BYTES ? content.slice(0, MAX_FILE_BYTES) : content;
+    }
+    catch {
+        return null;
+    }
+}
+async function exists(file) {
+    return fs.access(file).then(() => true, () => false);
+}
+function resolveLocalSpec(spec, fromDir, targetDir) {
+    if (spec.startsWith(".") || spec.startsWith("/"))
+        return path.resolve(fromDir, spec);
+    // The near-universal `@/` alias; package-specifier CSS (vendor sheets) is
+    // deliberately not chased — host brand tokens live in the host's own tree.
+    if (spec.startsWith("@/"))
+        return path.join(targetDir, "src", spec.slice(2));
+    return null;
+}
+async function collectCss(layout, targetDir) {
+    const files = [];
+    const seen = new Set();
+    const visit = async (absolute, depth) => {
+        if (seen.has(absolute) || files.length >= MAX_CSS_FILES || depth > 3)
+            return;
+        seen.add(absolute);
+        const content = await readCapped(absolute);
+        if (content === null)
+            return;
+        files.push({ path: path.relative(targetDir, absolute), content });
+        for (const match of content.matchAll(CSS_AT_IMPORT_RE)) {
+            const spec = match[1];
+            if (spec === "tailwindcss" || spec.startsWith("http"))
+                continue;
+            const resolved = resolveLocalSpec(spec, path.dirname(absolute), targetDir);
+            if (resolved === null)
+                continue;
+            const candidate = resolved.endsWith(".css") ? resolved : `${resolved}.css`;
+            if (await exists(candidate))
+                await visit(candidate, depth + 1);
+            else if (spec.startsWith("@/") && await exists(path.join(targetDir, spec.slice(2)))) {
+                await visit(path.join(targetDir, spec.slice(2)), depth + 1);
+            }
+        }
+    };
+    if (layout !== null) {
+        const layoutDir = path.dirname(path.join(targetDir, layout.path));
+        for (const match of layout.content.matchAll(CSS_IMPORT_RE)) {
+            const spec = (match[1] ?? match[2]);
+            let resolved = resolveLocalSpec(spec, layoutDir, targetDir);
+            if (resolved !== null && spec.startsWith("@/") && !(await exists(resolved))) {
+                resolved = path.join(targetDir, spec.slice(2));
+            }
+            if (resolved !== null && await exists(resolved))
+                await visit(resolved, 0);
+        }
+    }
+    if (files.length === 0) {
+        // No layout-imported CSS found: fall back to conventionally named sheets.
+        const all = await walk(targetDir, (rel) => rel.endsWith(".css"), 500);
+        const named = all.filter((file) => CSS_FALLBACK_NAME.test(path.basename(file)));
+        for (const file of (named.length > 0 ? named : all).slice(0, 4))
+            await visit(file, 0);
+    }
+    return files;
+}
+async function gatherContext(targetDir) {
+    let layout = null;
+    for (const candidate of ENTRY_FILE_CANDIDATES) {
+        const content = await readCapped(path.join(targetDir, candidate));
+        if (content !== null) {
+            layout = { path: candidate, content };
+            break;
+        }
+    }
+    let tailwindConfig = null;
+    for (const name of ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs", "tailwind.config.cjs"]) {
+        const content = await readCapped(path.join(targetDir, name));
+        if (content !== null) {
+            tailwindConfig = { path: name, content };
+            break;
+        }
+    }
+    return { layout, css: await collectCss(layout, targetDir), tailwindConfig };
+}
+function evidencePathsOf(context) {
+    return [
+        ...(context.layout ? [context.layout.path] : []),
+        ...context.css.map((file) => file.path),
+        ...(context.tailwindConfig ? [context.tailwindConfig.path] : []),
+    ];
+}
+/**
+ * The shadcn theme-variable vocabulary (ui.shadcn.com/docs/theming), mapped
+ * only where the shadcn semantic IS the Vendo slot semantic. Notably absent:
+ * shadcn's `--accent` (a hover wash, not the brand color — `--primary` is),
+ * `--muted` (a muted surface, not muted text), `--secondary`, `--popover`,
+ * `--input`, `--ring`, `--chart-*`, `--sidebar-*`. Each name is also accepted
+ * with the Tailwind-v4 `@theme` namespace prefix (`--color-primary`, ...).
+ */
+const EXACT_COLOR_TOKENS = [
+    ["background", ["--background"]],
+    ["text", ["--foreground"]],
+    ["surface", ["--card"]],
+    ["accent", ["--primary"]],
+    ["accentText", ["--primary-foreground"]],
+    ["mutedText", ["--muted-foreground"]],
+    ["border", ["--border"]],
+    ["danger", ["--destructive"]],
+];
+/** Non-color conventions: shadcn `--radius`; Tailwind v4 `--font-*` and
+ *  `--text-base` namespaces; Vendo's own documented `--density`/`--motion`. */
+const FONT_TOKENS = [
+    ["fontFamily", ["--font-sans"]],
+    ["headingFamily", ["--font-heading", "--font-display"]],
+];
+function lastLightDecl(vars, names) {
+    for (const name of names) {
+        const spellings = [name, `--color-${name.slice(2)}`];
+        const hit = [...vars].reverse().find((v) => !v.darkScope && spellings.includes(v.name));
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function normalizeFontStack(value) {
+    // Quotes are optional CSS syntax around family names, not identity: "Outfit"
+    // and Outfit are the same family (unquoted multi-word names are valid too).
+    const stack = value.split(",")
+        .map((part) => part.trim().replace(/^(["'])(.*)\1$/, "$2").trim())
+        .filter(Boolean)
+        .join(", ");
+    return /(?:^|,\s*)(?:sans-serif|serif|monospace|cursive|fantasy)(?:\s*,|$)/i.test(stack)
+        ? stack
+        : `${stack}, sans-serif`;
+}
+/** Fully-resolved font stack: no var() refs, no CSS structural characters. */
+function isSafeFontStack(value) {
+    return value.length > 0 && !value.includes("var(") && !/[{};\n]/.test(value);
+}
+function readExact(vars) {
+    const values = {};
+    const matched = {};
+    const put = (slot, decl, value) => {
+        if (decl === undefined || value === null)
+            return;
+        values[slot] = value;
+        matched[slot] = decl.name;
+    };
+    for (const [slot, names] of EXACT_COLOR_TOKENS) {
+        const decl = lastLightDecl(vars, names);
+        const resolved = decl === undefined ? null : resolveCssVarRefs(decl.value, vars);
+        put(slot, decl, resolved === null ? null : normalizeColor(resolved));
+    }
+    for (const [slot, names] of FONT_TOKENS) {
+        const decl = lastLightDecl(vars, names);
+        const resolved = decl === undefined ? null : resolveCssVarRefs(decl.value, vars);
+        put(slot, decl, resolved !== null && isSafeFontStack(resolved) ? normalizeFontStack(resolved) : null);
+    }
+    const radius = lastLightDecl(vars, ["--radius"]);
+    const radiusResolved = radius === undefined ? null : resolveCssVarRefs(radius.value, vars);
+    put("radius", radius, radiusResolved === null ? null : normalizeLength(radiusResolved));
+    const baseSize = lastLightDecl(vars, ["--font-size", "--text-base"]);
+    const baseResolved = baseSize === undefined ? null : resolveCssVarRefs(baseSize.value, vars);
+    put("baseSize", baseSize, baseResolved === null ? null : normalizeLength(baseResolved));
+    const density = lastLightDecl(vars, ["--density"]);
+    if (density && /^(?:compact|comfortable)$/.test(density.value.trim())) {
+        put("density", density, density.value.trim());
+    }
+    const motion = lastLightDecl(vars, ["--motion"]);
+    if (motion && /^(?:full|reduced)$/.test(motion.value.trim())) {
+        put("motion", motion, motion.value.trim());
+    }
+    return { values, matched };
+}
+// ---------------------------------------------------------------------------
+// Staged-pass artifact schema — parsed by `runStagedExtraction`'s theme stage
+// (../extract/stages.ts), merged back here by `applyThemeDraft`.
+// ---------------------------------------------------------------------------
+/** Brand-defining slots: any of these missing after the exact pass triggers
+ *  the staged theme pass, and only doubt about these becomes an init
+ *  question. The remaining slots (accentText, headingFamily, baseSize,
+ *  density, motion) derive or default safely — accentText derives from the
+ *  accent by WCAG contrast, headingFamily inherits fontFamily, and the rest
+ *  have safe brand-neutral defaults — so they never trigger a call or a
+ *  question on their own. */
+export const BRAND_SLOTS = [
+    "accent", "background", "surface", "text", "mutedText",
+    "border", "danger", "radius", "fontFamily",
+];
+const SLOT_KEYS = Object.keys(DEFAULT_THEME_SLOTS);
+export const modelThemeSchema = z.object({
+    slots: z.object({
+        accent: z.string().optional(),
+        accentText: z.string().optional(),
+        background: z.string().optional(),
+        border: z.string().optional(),
+        danger: z.string().optional(),
+        surface: z.string().optional(),
+        text: z.string().optional(),
+        mutedText: z.string().optional(),
+        radius: z.string().optional(),
+        fontFamily: z.string().optional(),
+        headingFamily: z.string().optional(),
+        baseSize: z.string().optional(),
+        density: z.enum(["compact", "comfortable"]).optional(),
+        motion: z.enum(["full", "reduced"]).optional(),
+    }),
+    uncertain: z.array(z.object({ slot: z.string(), note: z.string() })).optional(),
+});
+/** Deterministic validation of a proposed slot value (model or human). */
+export function validateSlotValue(slot, raw) {
+    const value = raw.trim();
+    switch (slot) {
+        case "radius":
+        case "baseSize":
+            return normalizeLength(value);
+        case "density":
+            return /^(?:compact|comfortable)$/.test(value) ? value : null;
+        case "motion":
+            return /^(?:full|reduced)$/.test(value) ? value : null;
+        case "fontFamily":
+        case "headingFamily":
+            return isSafeFontStack(value) ? normalizeFontStack(value) : null;
+        default:
+            return normalizeColor(value);
+    }
+}
+function assembleTheme(values, matchedExact, fromModel) {
+    const slots = { ...DEFAULT_THEME_SLOTS };
+    const matched = {};
+    const defaulted = [];
+    for (const slot of SLOT_KEYS) {
+        const exactValue = values[slot];
+        const modelValue = fromModel[slot];
+        if (exactValue !== undefined) {
+            slots[slot] = exactValue;
+            matched[slot] = matchedExact[slot];
+        }
+        else if (modelValue !== undefined) {
+            slots[slot] = modelValue;
+            matched[slot] = "(model)";
+        }
+        else if (slot === "accentText" && (values.accent !== undefined || fromModel.accent !== undefined)) {
+            slots.accentText = contrastingText(slots.accent);
+            matched[slot] = "(contrast) accent";
+        }
+        else if (slot === "headingFamily" && (values.fontFamily !== undefined || fromModel.fontFamily !== undefined)) {
+            slots.headingFamily = slots.fontFamily;
+            matched[slot] = "(inherit) fontFamily";
+        }
+        else {
+            defaulted.push(slot);
+        }
+    }
+    return { slots, matched, defaulted };
+}
+// ---------------------------------------------------------------------------
+// Exact-only extraction
+// ---------------------------------------------------------------------------
+export async function extractTheme(targetDir) {
+    const context = await gatherContext(targetDir);
+    const vars = context.css.flatMap((file) => parseCssVars(file.content, file.path));
+    const exact = readExact(vars);
+    const needed = SLOT_KEYS.filter((slot) => exact.values[slot] === undefined);
+    const { slots, matched, defaulted } = assembleTheme(exact.values, exact.matched, {});
+    return {
+        slots,
+        matched,
+        defaulted,
+        uncertain: [],
+        usedModel: false,
+        errors: [],
+        hasDarkVariant: vars.some((v) => v.darkScope),
+        needed,
+        evidencePaths: evidencePathsOf(context),
+    };
+}
+/**
+ * Merges a parsed theme-stage artifact (`modelThemeSchema`) onto an
+ * exact-only `ThemeSummary` — the precedence law (kill-list §B2, Task 2):
+ * exact reads are never overwritten; only `needed` slots may be filled; every
+ * proposed value passes through `validateSlotValue` (invalid values are
+ * ignored, the slot stays defaulted/derived); a model-provided accentText
+ * stands; accentText re-derives by contrast only when the model filled
+ * accent but not accentText and accentText itself wasn't an exact read;
+ * headingFamily inherits fontFamily under the mirror condition.
+ */
+export function applyThemeDraft(summary, draft) {
+    const neededSet = new Set(summary.needed);
+    const fromModel = {};
+    for (const slot of summary.needed) {
+        const raw = draft.slots[slot];
+        if (raw === undefined)
+            continue;
+        const value = validateSlotValue(slot, String(raw));
+        if (value !== null)
+            fromModel[slot] = value;
+    }
+    // Reconstruct the "already exact" values/provenance: everything NOT in
+    // `needed` was an exact read (or, for a re-applied summary, already
+    // settled) and must never be reconsidered here.
+    const exactValues = {};
+    const exactMatched = {};
+    for (const slot of SLOT_KEYS) {
+        if (!neededSet.has(slot)) {
+            exactValues[slot] = summary.slots[slot];
+            exactMatched[slot] = summary.matched[slot];
+        }
+    }
+    const { slots, matched, defaulted } = assembleTheme(exactValues, exactMatched, fromModel);
+    const usedModel = Object.keys(fromModel).length > 0;
+    const uncertain = (draft.uncertain ?? [])
+        .filter((entry) => BRAND_SLOTS.includes(entry.slot))
+        .filter((entry) => neededSet.has(entry.slot));
+    return {
+        ...summary,
+        slots,
+        matched,
+        defaulted,
+        uncertain,
+        usedModel,
+    };
+}

package/dist/cli/theme/walk.d.ts

@@ -0,0 +1,2 @@
+/** Bounded, deterministic source walk that avoids generated dependency trees. */
+export declare function walk(root: string, keep: (relativePath: string) => boolean, maxFiles?: number): Promise<string[]>;

package/dist/cli/theme/walk.js

@@ -0,0 +1,24 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const SKIP_DIRECTORIES = new Set(["node_modules", "dist", ".next"]);
+/** Bounded, deterministic source walk that avoids generated dependency trees. */
+export async function walk(root, keep, maxFiles = 5_000) {
+    const files = [];
+    async function visit(directory) {
+        const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                return;
+            const full = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!entry.name.startsWith(".") && !SKIP_DIRECTORIES.has(entry.name))
+                    await visit(full);
+            }
+            else if (keep(path.relative(root, full))) {
+                files.push(full);
+            }
+        }
+    }
+    await visit(root);
+    return files.sort();
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function main(argv: string[]): Promise<number>;
+export declare function isCliEntrypoint(metaUrl: string, argv1: string | undefined): boolean;