@askewly/design 0.4.0 → 0.4.2

package/dist/kickstart.js

@@ -1,8 +1,10 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { builtinModules } from "node:module";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { verifyDir } from "./verify.js";
+const BUILTIN_MODULES = new Set(builtinModules);
 export class KickstartError extends Error {
 }
 const REGISTRY_BASE = "https://ui.askewly.com";
@@ -196,7 +198,11 @@ export function renderBrandCss(answers) {
     const a = ACCENTS[answers.color];
     const c = CANVASES[answers.tone];
     const font = FONT_STACKS[answers.type];
-    const vars = (m, primary, onPrimary, ring) => `  --background: ${m.bg};
+    // `color-scheme` is what the *browser* reads. Tokens only repaint what we
+    // draw; scrollbars, native selects and checkboxes, and the overscroll gutter
+    // behind the page are the browser's, and they stay light without this.
+    const vars = (m, primary, onPrimary, ring, scheme) => `  color-scheme: ${scheme};
+  --background: ${m.bg};
   --foreground: ${m.fg};
   --card: ${m.card};
   --card-foreground: ${m.fg};
@@ -227,13 +233,22 @@ export function renderBrandCss(answers) {
     return `/* Generated by \`askewly-design init --block\` from DESIGN.md (tone=${answers.tone}, color=${answers.color}).
  * This file is the project's token definition layer — the block's required
  * CSS variables (block-contract §4/§6) are defined here, nowhere else. */
+
+/* One switch for dark mode. Without this line Tailwind v4 keys \`dark:\`
+ * utilities off \`prefers-color-scheme\` while the token values below key off
+ * the \`.dark\` class — two independent switches, so a project that toggles the
+ * class gets dark tokens with light-mode utilities (and an OS-dark visitor gets
+ * the reverse). Transplanted shadcn primitives carry \`dark:\` utilities, so this
+ * is load-bearing, not cosmetic. Toggle by putting \`dark\` on <html>. */
+@custom-variant dark (&:where(.dark, .dark *));
+
 :root {
   font-family: ${font};
-${vars(c.light, a.light, a.onLight, a.ring)}
+${vars(c.light, a.light, a.onLight, a.ring, "light")}
 }
 
 .dark {
-${vars(c.dark, a.dark, a.onDark, a.darkRing)}
+${vars(c.dark, a.dark, a.onDark, a.darkRing, "dark")}
 }
 
 @theme inline {
@@ -309,6 +324,167 @@ function destFor(file, srcRoot) {
         return path.join(srcRoot, "lib", libMatch[1]);
     return path.join(srcRoot, "components", path.basename(p));
 }
+// ---------------------------------------------------------------------------
+// What the transplanted code actually needs installed.
+//
+// A registry item's declared `dependencies` is a lower bound, not the answer:
+// shadcn's own button.json declares only `radix-ui` while button.tsx imports
+// `class-variance-authority`. Following the printed `npm i` therefore left cva
+// missing and the first fresh build failed (M27). The authority is the source
+// we just wrote to disk, so read the imports out of it.
+// ---------------------------------------------------------------------------
+const SPECIFIER = /(?:\bfrom\s*|\brequire\s*\(\s*|\bimport\s*\(\s*|^\s*import\s+)(['"])([^'"]+)\1/gm;
+/** Bare npm package names imported by a source file, folded to their install name. */
+export function importedPackages(content) {
+    const found = new Set();
+    for (const match of content.matchAll(SPECIFIER)) {
+        const spec = match[2];
+        // Relative paths and the project's own `@/` alias are not packages.
+        if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("@/"))
+            continue;
+        if (spec.startsWith("node:"))
+            continue;
+        if (BUILTIN_MODULES.has(spec.split("/")[0]))
+            continue;
+        const parts = spec.split("/");
+        // `radix-ui/react-slot` installs as `radix-ui`; `@scope/pkg/sub` as `@scope/pkg`.
+        found.add(spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]);
+    }
+    return [...found];
+}
+/**
+ * The symbol a consumer imports to render the block.
+ *
+ * Derived from the transplanted page rather than declared in the registry:
+ * a meta field would mean regenerating and redeploying all 56 assets for a
+ * defect the CLI can close on its own. `…Demo` exports are the block's own
+ * showcase wrapper, never the entry point.
+ */
+export function blockExportName(pageSource) {
+    for (const match of pageSource.matchAll(/^\s*export\s+function\s+([A-Za-z_$][\w$]*)/gm)) {
+        if (!match[1].endsWith("Demo"))
+            return match[1];
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// The `@/` alias the transplanted code needs.
+//
+// Every registry source imports through `@/…`, so a project without the alias
+// configured fails to typecheck the moment the block lands — six `tsc -b`
+// errors on a stock vite react-ts app, patched by hand in both M28 E2E runs.
+// The printed handoff said nothing about it.
+//
+// Two traps this has to survive:
+//   1. tsconfig files are JSONC. Parsing them would mean shipping a parser, so
+//      the check is a raw scan with comments removed — a commented-out `"@/*"`
+//      must not read as configured.
+//   2. vite's react-ts template makes the root tsconfig.json a *solution* file:
+//      references only, no compilerOptions. `paths` written there is ignored by
+//      `tsc -b`. The step has to name the file that actually owns the options.
+// ---------------------------------------------------------------------------
+/** Blank out comments without touching string contents (JSONC + TS configs). */
+function stripComments(source) {
+    let out = "";
+    let quote = null;
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (quote) {
+            out += ch;
+            if (ch === "\\") {
+                out += source[++i] ?? "";
+            }
+            else if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && source[i + 1] === "/") {
+            while (i < source.length && source[i] !== "\n")
+                i++;
+            out += "\n";
+            continue;
+        }
+        if (ch === "/" && source[i + 1] === "*") {
+            i += 2;
+            while (i < source.length && !(source[i] === "*" && source[i + 1] === "/"))
+                i++;
+            i++;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+const TSCONFIG_ALIAS = /"@\/\*"\s*:/;
+const VITE_ALIAS = /vite-tsconfig-paths|resolve\s*:[\s\S]{0,400}?alias/;
+/**
+ * Which half of the `@/` alias is missing.
+ *
+ * Uncertainty resolves toward printing: an extra step in an already-configured
+ * project costs a glance, a missing one costs the build.
+ */
+export function detectPathAlias(targetDir) {
+    const names = existsSync(targetDir)
+        ? readdirSync(targetDir).filter((n) => /^tsconfig.*\.json$/.test(n))
+        : [];
+    const read = (name) => {
+        try {
+            return stripComments(readFileSync(path.join(targetDir, name), "utf8"));
+        }
+        catch {
+            return "";
+        }
+    };
+    const sources = new Map(names.map((n) => [n, read(n)]));
+    const declared = names.some((n) => TSCONFIG_ALIAS.test(sources.get(n) ?? ""));
+    // Name the file that owns compilerOptions — writing paths anywhere else is a
+    // step the reader can follow and still fail.
+    const owner = names.find((n) => n !== "tsconfig.json" && /"compilerOptions"\s*:/.test(sources.get(n) ?? "")) ??
+        names.find((n) => /"compilerOptions"\s*:/.test(sources.get(n) ?? "")) ??
+        names[0] ??
+        "tsconfig.json";
+    const viteConfig = existsSync(targetDir)
+        ? readdirSync(targetDir).find((n) => /^vite\.config\.[cm]?[jt]s$/.test(n))
+        : undefined;
+    const vite = viteConfig ? VITE_ALIAS.test(stripComments(readFileSync(path.join(targetDir, viteConfig), "utf8"))) : false;
+    return { tsconfig: declared ? null : owner, vite };
+}
+/**
+ * The copy-paste step, or null when both halves are already in place.
+ *
+ * Deliberately free of new npm dependencies: the printed `npm i` list is
+ * contracted to be what the transplanted files import (M28), and recommending
+ * a build-tool plugin there would blur that. `srcRel` keeps the snippet true to
+ * where the block was actually written.
+ */
+export function aliasStep(status, srcRel) {
+    if (!status.tsconfig && status.vite)
+        return null;
+    const parts = [
+        `configure the \`@/\` alias — the transplanted files import through it, and \`tsc\` fails without it:`,
+    ];
+    if (status.tsconfig) {
+        // No `baseUrl`: paths resolve relative to the tsconfig since TS 4.4, and on
+        // TS 6 the option is deprecated hard enough to fail the build (TS5101,
+        // measured on a stock vite react-ts project — the first snippet shipped it
+        // and traded six missing-module errors for one deprecation error).
+        parts.push(`     in ${status.tsconfig}, inside "compilerOptions":`);
+        parts.push(`       "paths": { "@/*": ["${srcRel}/*"] }`);
+    }
+    if (!status.vite) {
+        parts.push(`     in vite.config.ts:`);
+        parts.push(`       import { fileURLToPath } from "node:url"`);
+        parts.push(`       // inside defineConfig({ … })`);
+        parts.push(`       resolve: { alias: { "@": fileURLToPath(new URL("${srcRel}", import.meta.url)) } }`);
+    }
+    return parts.join("\n");
+}
 export async function fetchBlock(blockName, registryBase) {
     const block = await fetchJson(`${registryBase}/r/${blockName}.json`);
     if (block.meta?.tier !== "block") {
@@ -321,6 +497,16 @@ export async function transplantBlock(block, targetDir) {
     const written = [];
     const npmDeps = new Set(["clsx", "tailwind-merge"]);
     const visited = new Set();
+    function write(file) {
+        const dest = destFor(file, srcRoot);
+        const content = rewriteImports(file.content);
+        mkdirSync(path.dirname(dest), { recursive: true });
+        writeFileSync(dest, content);
+        written.push(dest);
+        // The file we just wrote is the authority on what must be installed.
+        for (const pkg of importedPackages(content))
+            npmDeps.add(pkg);
+    }
     async function resolve(item) {
         for (const dep of item.dependencies ?? [])
             npmDeps.add(dep.split("@").slice(0, dep.startsWith("@") ? 2 : 1).join("@"));
@@ -332,21 +518,13 @@ export async function transplantBlock(block, targetDir) {
             visited.add(key);
             const child = await fetchJson(url);
             await resolve(child);
-            for (const file of child.files ?? []) {
-                const dest = destFor(file, srcRoot);
-                mkdirSync(path.dirname(dest), { recursive: true });
-                writeFileSync(dest, rewriteImports(file.content));
-                written.push(dest);
-            }
+            for (const file of child.files ?? [])
+                write(file);
         }
     }
     await resolve(block);
-    for (const file of block.files ?? []) {
-        const dest = destFor(file, srcRoot);
-        mkdirSync(path.dirname(dest), { recursive: true });
-        writeFileSync(dest, rewriteImports(file.content));
-        written.push(dest);
-    }
+    for (const file of block.files ?? [])
+        write(file);
     // cn() — shadcn init would have created it; transplant guarantees it (M18 step-5 friction).
     const utils = path.join(srcRoot, "lib", "utils.ts");
     if (!existsSync(utils)) {
@@ -401,10 +579,23 @@ export async function runKickstart(dir, opts) {
         throw new KickstartError("transplanted block bypasses the token system — fix before continuing");
     }
     console.log(`verify PASS — ${files} block file(s), no color literals`);
-    // 7. handoff
+    // 7. handoff — every line here must be true of the project that now exists on
+    //    disk. A printed step the reader cannot follow is worse than no step.
+    const pagePath = path.join(blockDir, "page.tsx");
+    const exportName = existsSync(pagePath) ? blockExportName(readFileSync(pagePath, "utf8")) : null;
+    const srcRel = srcRoot === targetDir ? "." : "./src";
+    const steps = [];
+    const alias = aliasStep(detectPathAlias(targetDir), srcRel);
+    if (alias)
+        steps.push(alias);
+    steps.push(`npm i ${[...result.npmDeps].sort().join(" ")}`);
+    steps.push(`import "./askewly-brand.css" after \`@import "tailwindcss";\` in your global stylesheet (order matters — it registers the dark variant)`);
+    steps.push(`toggle dark mode by putting the \`dark\` class on <html> — tokens and \`dark:\` utilities both key off it`);
+    steps.push(exportName
+        ? `render the block: import { ${exportName} } from "@/components/blocks/${opts.block}/page"`
+        : `render the block from "@/components/blocks/${opts.block}/page" — open it to see which component it exports`);
+    steps.push(`wire routing yourself — the block deliberately ships none (block-contract §3)`);
     console.log(`\nNext steps:`);
-    console.log(`  1. npm i ${[...result.npmDeps].sort().join(" ")}`);
-    console.log(`  2. import "./askewly-brand.css" after \`@import "tailwindcss";\` in your global stylesheet`);
-    console.log(`  3. render the block: import { SaasAppShell } from "@/components/blocks/${opts.block}/page"`);
-    console.log(`  4. wire routing yourself — the block deliberately ships none (block-contract §3)`);
+    for (const [index, step] of steps.entries())
+        console.log(`  ${index + 1}. ${step}`);
 }

package/dist/verify.js

@@ -30,6 +30,21 @@ const LINE_COMMENT_EXTENSIONS = new Set(["ts", "tsx", "js", "jsx"]);
 // Two SVG shapes: paired <svg>…</svg> and self-closing <svg … />.
 const SVG_PAIRED = /<svg\b[\s\S]*?<\/svg\s*>/gi;
 const SVG_SELF_CLOSING = /<svg\b[^>]*\/>/gi;
+/**
+ * CSS attribute selectors whose value is a hex color, e.g. the Tailwind
+ * arbitrary variant `[&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border`.
+ *
+ * The hex there is a *match target*, not a color the file paints with: it names
+ * a value some third-party library already emitted so the rule can override it
+ * with a token. Flagging it inverts the gate — the line doing the token work is
+ * the line getting reported.
+ *
+ * Deliberately narrow: an attribute name, an `=` (optionally prefixed by a CSS
+ * match operator), and a *quoted* hex. Tailwind arbitrary values like
+ * `bg-[#ccc]` have no `=` and no quotes, so they stay violations. The optional
+ * backslashes cover selectors written inside a same-quoted JS string.
+ */
+const ATTR_SELECTOR_HEX = /\[[A-Za-z_-][\w:.-]*\s*[~^|*$]?=\s*\\?(['"])#[0-9a-fA-F]{3,8}\\?\1\s*[iIsS]?\s*\]/g;
 /**
  * Blanks regions whose color literals are not rendered output — comments and
  * SVG markup — while preserving every character position and newline, so
@@ -109,7 +124,7 @@ export function maskIgnoredRegions(source, ext) {
     // Pass 2 — SVG markup, matched against the comment-masked text so a commented
     // out `</svg>` cannot terminate a block early.
     let masked = chars.join("");
-    for (const pattern of [SVG_PAIRED, SVG_SELF_CLOSING]) {
+    for (const pattern of [SVG_PAIRED, SVG_SELF_CLOSING, ATTR_SELECTOR_HEX]) {
         masked = masked.replace(pattern, (match) => match.replace(/[^\n]/g, " "));
     }
     return masked;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askewly/design",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Query, inject, and verify the Askewly Design system (tokens, UI vocabulary, recipes) from your terminal or coding agent.",
   "license": "MIT",
   "homepage": "https://ui.askewly.com",