create-forte-ui 1.0.0-alpha.4

package/README.md

@@ -0,0 +1,46 @@
+# create-forte-ui
+
+Scaffold a brand-new app wired up with [forte-ui](https://forte-ui.com) — Vite
+or Next.js, with or without Tailwind, themed from your answers.
+
+```bash
+pnpm create forte-ui my-app
+npm create forte-ui@latest my-app
+```
+
+Four questions get you to a running app (name, framework, Tailwind, accent
+color); everything else — secondary color, neutral tint, radius, density,
+motion, fonts — hides behind one "customize further?" gate. Every prompt has a
+flag twin, so the [Theme Studio](https://forte-ui.com/theme/) can hand you a
+complete command line and `--yes` runs without a single question:
+
+```bash
+pnpm create forte-ui my-app --seed "#e11d48" --radius pill --font-sans "Inter" --yes
+```
+
+Run `create-forte-ui --help` for the full flag list.
+
+## How it works
+
+The framework scaffold is not ours: `create-next-app` / `create-vite` run
+non-interactively and stay current upstream. This CLI applies only the
+forte-ui overlay on top — the same steps as the
+[getting-started guides](https://forte-ui.com/getting-started/nextjs/), which
+are the spec: a scaffolded app should diff against the walkthrough and show
+only your answers.
+
+Answers you skip write **nothing** — no restated defaults, no attributes for
+default presets — so the app keeps following the library when its defaults
+are tuned.
+
+## Maintaining
+
+- The starter files live in `src/templates.ts`; when a guide step changes,
+  change the matching builder in the same commit.
+- The font catalogue (`src/fonts.ts`) and colour maths (`src/color.ts`) are
+  the modules of record — the docs' Theme Studio re-exports them from this
+  package.
+- `pnpm --filter create-forte-ui smoke` scaffolds and builds all four
+  framework × Tailwind paths against the workspace library (network, takes
+  minutes). Run it before releasing this package or after editing a guide's
+  setup steps.

package/dist/args.d.ts

@@ -0,0 +1,19 @@
+import { type ThemeAnswers } from "./theme.js";
+import { type PackageManager } from "./scaffold.js";
+import type { Framework } from "./overlay.js";
+export type CliOptions = {
+    name?: string;
+    framework?: Framework;
+    tailwind?: boolean;
+    pm?: PackageManager;
+    yes: boolean;
+    install: boolean;
+    help: boolean;
+    version: boolean;
+    /** Only the keys given as flags — presence is what suppresses the prompt. */
+    answers: Partial<ThemeAnswers>;
+};
+export declare class UsageError extends Error {
+}
+export declare function parseCliArgs(argv: string[]): CliOptions;
+export declare const HELP = "create-forte-ui \u2014 scaffold a new app wired up with forte-ui\n\nUsage\n  pnpm create forte-ui [name] [flags]\n  npm create forte-ui@latest [name] -- [flags]\n\nEvery flag has a prompt twin; a passed flag suppresses its prompt. With no\nflags you get the questionnaire, with --yes you get a Next.js + Tailwind app\non the library's default theme.\n\nProject\n  [name]                 project directory (prompted if omitted)\n  -f, --framework        next | vite\n  --tailwind             wire the Tailwind v4 bridge (default yes)\n  --no-tailwind          plain CSS setup\n  --pm                   npm | pnpm | yarn | bun (default: whoever invoked us)\n  --no-install           write files only; skip installing dependencies\n  -y, --yes              accept the defaults for everything not passed\n\nTheme \u2014 every skipped value keeps the library default and writes NOTHING,\nso the app keeps following the library when defaults are tuned.\n  --seed, --accent       accent seed, hex (\"#6d43d4\")\n  --secondary            secondary seed, hex\n  --tint                 neutral tint, 0 (pure grey) to 1 (default)\n  --radius               none | soft | pill\n  --density              compact | spacious\n  --motion               system (default) | reduce | full\n                         \"full\" overrides the OS reduced-motion preference\n                         for everyone \u2014 prefer leaving it unset.\n  --font-sans            a catalogue name (\"Inter\", \"DM Sans\", ...)\n  --font-mono            a catalogue name (\"JetBrains Mono\", ...)\n\nDesign the theme visually instead: https://forte-ui.com/theme\n";

package/dist/args.js

@@ -0,0 +1,146 @@
+/* Flag parsing. Every prompt has a flag twin — that is what lets the Theme
+ * Studio export a ready-made command line, and what makes the CI smoke runs
+ * possible at all — and the flag names are the studio's config keys, kebab-
+ * cased, so the two stay alignable by inspection.
+ *
+ * Values are validated HERE, before anything runs: the library's own failure
+ * mode for a bad custom property is silence at computed-value time, and the
+ * one thing a scaffolder must never do is bake that silence into a fresh
+ * project.
+ */
+import { parseArgs } from "node:util";
+import { SANS_FONTS, MONO_FONTS } from "./fonts.js";
+import { hexToOklch } from "./color.js";
+import { RADIUS, DENSITY, MOTION } from "./theme.js";
+import { PACKAGE_MANAGERS } from "./scaffold.js";
+export class UsageError extends Error {
+}
+function normalizeHex(flag, value) {
+    const hex = value.startsWith("#") ? value : `#${value}`;
+    if (!hexToOklch(hex)) {
+        throw new UsageError(`--${flag} expects a hex colour like "#6d43d4", got "${value}"`);
+    }
+    return hex.toLowerCase();
+}
+function oneOf(flag, value, options) {
+    const v = value.toLowerCase();
+    if (!options.includes(v)) {
+        throw new UsageError(`--${flag} must be one of ${options.join(", ")} — got "${value}"`);
+    }
+    return v;
+}
+function fontByName(flag, value, list) {
+    const match = list.find((f) => f.name.toLowerCase() === value.toLowerCase());
+    if (!match) {
+        throw new UsageError(`--${flag}: "${value}" is not in the catalogue. Choices: ${list.map((f) => f.name).join(", ")}`);
+    }
+    return match.name;
+}
+export function parseCliArgs(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            framework: { type: "string", short: "f" },
+            tailwind: { type: "boolean" },
+            "no-tailwind": { type: "boolean" },
+            seed: { type: "string" },
+            accent: { type: "string" },
+            secondary: { type: "string" },
+            tint: { type: "string" },
+            radius: { type: "string" },
+            density: { type: "string" },
+            motion: { type: "string" },
+            "font-sans": { type: "string" },
+            "font-mono": { type: "string" },
+            pm: { type: "string" },
+            yes: { type: "boolean", short: "y" },
+            "no-install": { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+    });
+    if (positionals.length > 1) {
+        throw new UsageError(`expected one project name, got: ${positionals.join(", ")}`);
+    }
+    if (values.tailwind && values["no-tailwind"]) {
+        throw new UsageError("--tailwind and --no-tailwind are mutually exclusive");
+    }
+    if (values.seed !== undefined && values.accent !== undefined) {
+        throw new UsageError("--seed and --accent are the same flag — pass one");
+    }
+    const answers = {};
+    const seed = values.seed ?? values.accent;
+    if (seed !== undefined)
+        answers.seed = normalizeHex(values.seed !== undefined ? "seed" : "accent", seed);
+    if (values.secondary !== undefined)
+        answers.secondary = normalizeHex("secondary", values.secondary);
+    if (values.tint !== undefined) {
+        const tint = Number(values.tint);
+        if (!Number.isFinite(tint) || tint < 0 || tint > 1) {
+            throw new UsageError(`--tint expects a number between 0 and 1, got "${values.tint}"`);
+        }
+        answers.tint = tint;
+    }
+    if (values.radius !== undefined)
+        answers.radius = oneOf("radius", values.radius, RADIUS);
+    if (values.density !== undefined)
+        answers.density = oneOf("density", values.density, DENSITY);
+    if (values.motion !== undefined) {
+        /* "system" is the honest name for the default from the outside: no
+         * attribute, so the OS reduced-motion preference stays in charge. */
+        answers.motion =
+            values.motion.toLowerCase() === "system" ? "default" : oneOf("motion", values.motion, MOTION);
+    }
+    if (values["font-sans"] !== undefined) {
+        answers.fontSans = fontByName("font-sans", values["font-sans"], SANS_FONTS);
+    }
+    if (values["font-mono"] !== undefined) {
+        answers.fontMono = fontByName("font-mono", values["font-mono"], MONO_FONTS);
+    }
+    return {
+        name: positionals[0],
+        framework: values.framework === undefined ? undefined : oneOf("framework", values.framework, ["next", "vite"]),
+        tailwind: values.tailwind ? true : values["no-tailwind"] ? false : undefined,
+        pm: values.pm === undefined ? undefined : oneOf("pm", values.pm, PACKAGE_MANAGERS),
+        yes: values.yes ?? false,
+        install: !(values["no-install"] ?? false),
+        help: values.help ?? false,
+        version: values.version ?? false,
+        answers,
+    };
+}
+export const HELP = `create-forte-ui — scaffold a new app wired up with forte-ui
+
+Usage
+  pnpm create forte-ui [name] [flags]
+  npm create forte-ui@latest [name] -- [flags]
+
+Every flag has a prompt twin; a passed flag suppresses its prompt. With no
+flags you get the questionnaire, with --yes you get a Next.js + Tailwind app
+on the library's default theme.
+
+Project
+  [name]                 project directory (prompted if omitted)
+  -f, --framework        next | vite
+  --tailwind             wire the Tailwind v4 bridge (default yes)
+  --no-tailwind          plain CSS setup
+  --pm                   npm | pnpm | yarn | bun (default: whoever invoked us)
+  --no-install           write files only; skip installing dependencies
+  -y, --yes              accept the defaults for everything not passed
+
+Theme — every skipped value keeps the library default and writes NOTHING,
+so the app keeps following the library when defaults are tuned.
+  --seed, --accent       accent seed, hex ("#6d43d4")
+  --secondary            secondary seed, hex
+  --tint                 neutral tint, 0 (pure grey) to 1 (default)
+  --radius               none | soft | pill
+  --density              compact | spacious
+  --motion               system (default) | reduce | full
+                         "full" overrides the OS reduced-motion preference
+                         for everyone — prefer leaving it unset.
+  --font-sans            a catalogue name ("Inter", "DM Sans", ...)
+  --font-mono            a catalogue name ("JetBrains Mono", ...)
+
+Design the theme visually instead: https://forte-ui.com/theme
+`;

package/dist/color.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Colour maths for the Theme Studio and the create-forte-ui CLI. This is the
+ * module of record — the docs' `lib/color.ts` re-exports it from here.
+ *
+ * Mirrors the model the library's CSS uses, so what the studio reports is what
+ * the browser will actually paint:
+ *  - sRGB is naive-CLIPPED, not gamut-mapped, because that is what browsers do
+ *    today. Reporting a gamut-mapped colour here would understate how far an
+ *    out-of-range seed drifts.
+ *  - Contrast is WCAG 2.x relative luminance, the ratio the success criteria
+ *    are actually written against.
+ */
+export type Oklch = {
+    l: number;
+    c: number;
+    h: number;
+};
+type Rgb = [number, number, number];
+/** OKLCH -> linear sRGB, plus whether sRGB could represent it at all. */
+export declare function oklchToLinear(o: Oklch): {
+    rgb: Rgb;
+    outOfGamut: boolean;
+};
+export declare function oklchToHex(o: Oklch): string;
+export declare function hexToOklch(hex: string): Oklch | null;
+export declare function contrast(a: Rgb, b: Rgb): number;
+/**
+ * The exact readable text colour for a solid fill, chosen by measuring both
+ * candidates rather than by the CSS fallback's fitted lightness threshold.
+ * Emitting this as a literal is what makes the studio's output correct in
+ * every browser, including those without contrast-color().
+ */
+export declare function bestOnColor(seed: Oklch): {
+    color: "white" | "black";
+    ratio: number;
+};
+/** The envelope the library's contrast guarantees were verified across. */
+export declare const ENVELOPE: {
+    lMin: number;
+    lMax: number;
+    cMin: number;
+    cMax: number;
+};
+export type SeedWarning = {
+    level: "warn" | "info";
+    message: string;
+};
+export declare function validateSeed(seed: Oklch): SeedWarning[];
+export {};

package/dist/color.js

@@ -0,0 +1,96 @@
+/**
+ * Colour maths for the Theme Studio and the create-forte-ui CLI. This is the
+ * module of record — the docs' `lib/color.ts` re-exports it from here.
+ *
+ * Mirrors the model the library's CSS uses, so what the studio reports is what
+ * the browser will actually paint:
+ *  - sRGB is naive-CLIPPED, not gamut-mapped, because that is what browsers do
+ *    today. Reporting a gamut-mapped colour here would understate how far an
+ *    out-of-range seed drifts.
+ *  - Contrast is WCAG 2.x relative luminance, the ratio the success criteria
+ *    are actually written against.
+ */
+/** OKLCH -> linear sRGB, plus whether sRGB could represent it at all. */
+export function oklchToLinear(o) {
+    const hr = (o.h * Math.PI) / 180;
+    const a = o.c * Math.cos(hr);
+    const b = o.c * Math.sin(hr);
+    const l3 = (o.l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m3 = (o.l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s3 = (o.l - 0.0894841775 * a - 1.2914855480 * b) ** 3;
+    const raw = [
+        +4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
+        -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
+        -0.0041960863 * l3 - 0.7034186147 * m3 + 1.7076147010 * s3,
+    ];
+    return {
+        rgb: raw.map((v) => Math.min(1, Math.max(0, v))),
+        outOfGamut: raw.some((v) => v < -1e-4 || v > 1 + 1e-4),
+    };
+}
+const encode = (v) => Math.round((v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055) * 255);
+export function oklchToHex(o) {
+    const { rgb } = oklchToLinear(o);
+    return "#" + rgb.map((v) => encode(v).toString(16).padStart(2, "0")).join("");
+}
+function srgbToLinear(v) {
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+export function hexToOklch(hex) {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    let s = m[1];
+    if (s.length === 3)
+        s = s.split("").map((ch) => ch + ch).join("");
+    const [r, g, b] = [0, 2, 4].map((i) => srgbToLinear(parseInt(s.slice(i, i + 2), 16) / 255));
+    const l_ = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m_ = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s_ = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    const L = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+    const A = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+    const B = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+    const h = (Math.atan2(B, A) * 180) / Math.PI;
+    return { l: L, c: Math.hypot(A, B), h: h < 0 ? h + 360 : h };
+}
+const luminance = ([r, g, b]) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+export function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+const WHITE = [1, 1, 1];
+const BLACK = [0, 0, 0];
+/**
+ * The exact readable text colour for a solid fill, chosen by measuring both
+ * candidates rather than by the CSS fallback's fitted lightness threshold.
+ * Emitting this as a literal is what makes the studio's output correct in
+ * every browser, including those without contrast-color().
+ */
+export function bestOnColor(seed) {
+    const { rgb } = oklchToLinear(seed);
+    const w = contrast(WHITE, rgb);
+    const b = contrast(BLACK, rgb);
+    return w >= b ? { color: "white", ratio: w } : { color: "black", ratio: b };
+}
+/** The envelope the library's contrast guarantees were verified across. */
+export const ENVELOPE = { lMin: 0.45, lMax: 0.9, cMin: 0.02, cMax: 0.3 };
+export function validateSeed(seed) {
+    const out = [];
+    const { outOfGamut } = oklchToLinear(seed);
+    if (outOfGamut) {
+        out.push({
+            level: "warn",
+            message: "Outside the sRGB gamut. Browsers clip rather than gamut-map, which shifts the painted lightness — the 9/10 hover step can visually collapse, and the colour will differ between sRGB and P3 displays.",
+        });
+    }
+    if (seed.l < ENVELOPE.lMin) {
+        out.push({ level: "warn", message: `Very dark (L ${seed.l.toFixed(2)}). Steps 9 and 12 converge, so solid fills and high-contrast text stop being distinguishable.` });
+    }
+    if (seed.l > ENVELOPE.lMax) {
+        out.push({ level: "warn", message: `Very light (L ${seed.l.toFixed(2)}). The subtle background steps have nowhere left to go and flatten against the page.` });
+    }
+    if (seed.c < ENVELOPE.cMin) {
+        out.push({ level: "info", message: "Nearly achromatic — the accent ramp will be hard to tell apart from the neutrals." });
+    }
+    return out;
+}

package/dist/fonts.d.ts

@@ -0,0 +1,23 @@
+export type FontOption = {
+    /** Display name, and the value stored in the studio config. */
+    name: string;
+    /** `font-family` value, fallback stack included. `null` means "System" —
+     *  no override at all, so the token keeps its shipped default. */
+    stack: string | null;
+    /** Full stylesheet for actually using the font. `null` for System. */
+    css: string | null;
+    /** Subsetted stylesheet carrying only the glyphs of the family's own name —
+     *  a few KB, loaded when the picker opens so each menu item can render in
+     *  its own face without pulling ten full families. */
+    preview: string | null;
+};
+export declare const SANS_FALLBACK = "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif";
+export declare const MONO_FALLBACK = "ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace";
+export declare const SANS_FONTS: readonly FontOption[];
+export declare const MONO_FONTS: readonly FontOption[];
+export declare function findFont(list: readonly FontOption[], name: string): FontOption;
+/** Append a stylesheet `<link>` once. Loaded fonts are deliberately never
+ *  removed on switch-away — the files are cached, and keeping the link means
+ *  flipping back to a font shows it instantly instead of re-flashing the
+ *  fallback. */
+export declare function ensureFontLink(href: string): void;

package/dist/fonts.js

@@ -0,0 +1,83 @@
+/* The font catalogue — the ten most-used Google Fonts of each kind, plus the
+ * library's own default stack as "System". This is the module of record: the
+ * docs' Theme Studio re-exports it from here, so the CLI's font prompt and
+ * the studio's pickers cannot drift apart. Everything a consumer of
+ * an entry needs (the CSS stack, the full stylesheet URL, the tiny preview
+ * URL) is precomputed here, so the component never builds a URL of its own
+ * and the pre-paint replay in `layout.tsx` can trust what was stored.
+ *
+ * The axes in `axes` are per-family on purpose: css2 rejects a range a static
+ * family cannot serve (`Lato:wght@400..700` is a 400), so variable families
+ * ask for the 400..700 range and static ones list the weights they actually
+ * have. The tokens only ever use 400/500/600/700; a family missing a step
+ * (Lato, Space Mono…) lets the browser synthesise it, which is fine for a
+ * preview and stated in the copied CSS by the import carrying the real list. */
+/* The shipped defaults from `tokens.css`, verbatim. They double as the
+ * fallback tail behind every Google family, so a font that has not arrived
+ * yet degrades to exactly the look the studio started with. */
+export const SANS_FALLBACK = 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
+export const MONO_FALLBACK = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+const GOOGLE = "https://fonts.googleapis.com/css2";
+function font(name, axes, fallback) {
+    const family = name.replaceAll(" ", "+");
+    return {
+        name,
+        stack: `"${name}", ${fallback}`,
+        css: `${GOOGLE}?family=${family}:${axes}&display=swap`,
+        preview: `${GOOGLE}?family=${family}&text=${encodeURIComponent(name)}&display=swap`,
+    };
+}
+const system = { name: "System", stack: null, css: null, preview: null };
+export const SANS_FONTS = [
+    system,
+    font("Inter", "wght@400..700", SANS_FALLBACK),
+    font("Roboto", "wght@400;500;700", SANS_FALLBACK),
+    font("Open Sans", "wght@400..700", SANS_FALLBACK),
+    font("Lato", "wght@400;700", SANS_FALLBACK),
+    font("Montserrat", "wght@400..700", SANS_FALLBACK),
+    font("Poppins", "wght@400;500;600;700", SANS_FALLBACK),
+    font("Nunito", "wght@400..700", SANS_FALLBACK),
+    font("Source Sans 3", "wght@400..700", SANS_FALLBACK),
+    font("Work Sans", "wght@400..700", SANS_FALLBACK),
+    font("DM Sans", "wght@400..700", SANS_FALLBACK),
+];
+export const MONO_FONTS = [
+    system,
+    font("JetBrains Mono", "wght@400..700", MONO_FALLBACK),
+    font("Fira Code", "wght@400..700", MONO_FALLBACK),
+    font("Source Code Pro", "wght@400..700", MONO_FALLBACK),
+    font("IBM Plex Mono", "wght@400;500;600;700", MONO_FALLBACK),
+    font("Roboto Mono", "wght@400..700", MONO_FALLBACK),
+    font("Geist Mono", "wght@400..700", MONO_FALLBACK),
+    font("Space Mono", "wght@400;700", MONO_FALLBACK),
+    font("Ubuntu Mono", "wght@400;700", MONO_FALLBACK),
+    font("Inconsolata", "wght@400..700", MONO_FALLBACK),
+    font("Courier Prime", "wght@400;700", MONO_FALLBACK),
+];
+export function findFont(list, name) {
+    // Falls back to System rather than throwing: the name may come from
+    // user-editable storage, and readStored() has already validated it — this
+    // is belt-and-braces for the one caller that builds CSS from it.
+    return list.find((f) => f.name === name) ?? list[0];
+}
+/** Append a stylesheet `<link>` once. Loaded fonts are deliberately never
+ *  removed on switch-away — the files are cached, and keeping the link means
+ *  flipping back to a font shows it instantly instead of re-flashing the
+ *  fallback. */
+export function ensureFontLink(href) {
+    if (document.head.querySelector(`link[href="${href}"]`))
+        return;
+    // One preconnect ahead of the first font request; gstatic is where the
+    // actual woff2 files live and the stylesheet origin connects itself.
+    if (!document.head.querySelector('link[rel="preconnect"][href="https://fonts.gstatic.com"]')) {
+        const pre = document.createElement("link");
+        pre.rel = "preconnect";
+        pre.href = "https://fonts.gstatic.com";
+        pre.crossOrigin = "anonymous";
+        document.head.appendChild(pre);
+    }
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    document.head.appendChild(link);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/* create-forte-ui: scaffold a brand-new app wired up with forte-ui.
+ *
+ * The division of labour is the whole design: `create-next-app` / `create-vite`
+ * own the framework scaffold (run non-interactively, kept current upstream),
+ * and this CLI owns only the forte-ui overlay — the getting-started guides'
+ * steps, mechanized. The guides are the spec; when a step changes there,
+ * change `templates.ts` with it.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { parseCliArgs, UsageError, HELP } from "./args.js";
+import { collectPlan } from "./prompts.js";
+import { hexToOklch, validateSeed } from "./color.js";
+import { applyOverlay, dependenciesFor, recordDependencies } from "./overlay.js";
+import { detectPackageManager, runScaffolder, addDependencies, devCommand, installCommand, } from "./scaffold.js";
+function ownVersion() {
+    const pkgPath = path.join(fileURLToPath(import.meta.url), "../../package.json");
+    return JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
+}
+/** The library's contrast guarantees were measured across a seed envelope;
+ *  a seed outside it still works, but the studio would have warned — so the
+ *  CLI does too, after the answers are settled and before anything runs. */
+function warnAboutSeeds(plan) {
+    for (const [label, hex] of [
+        ["accent", plan.answers.seed],
+        ["secondary", plan.answers.secondary],
+    ]) {
+        if (!hex)
+            continue;
+        const oklch = hexToOklch(hex);
+        if (!oklch)
+            continue;
+        for (const warning of validateSeed(oklch)) {
+            p.log[warning.level === "warn" ? "warn" : "info"](`${label} ${hex}: ${warning.message}`);
+        }
+    }
+}
+function scaffold(plan, pm) {
+    if (plan.framework === "vite") {
+        return runScaffolder(pm, "create-vite@latest", [plan.name, "--template", "react-ts"], process.cwd());
+    }
+    return runScaffolder(pm, "create-next-app@latest", [
+        plan.name,
+        "--typescript",
+        "--app",
+        plan.tailwind ? "--tailwind" : "--no-tailwind",
+        "--no-src-dir",
+        "--import-alias",
+        "@/*",
+        /* One install at the end (ours, with the library included) instead of
+         * two; --yes answers whatever prompts remain in future versions. */
+        "--skip-install",
+        "--yes",
+    ], process.cwd());
+}
+async function main() {
+    let opts;
+    try {
+        opts = parseCliArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        if (error instanceof UsageError || error instanceof TypeError) {
+            console.error(pc.red(`create-forte-ui: ${error.message}`));
+            console.error(`Run with ${pc.bold("--help")} for usage.`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    if (opts.help) {
+        console.log(HELP);
+        return;
+    }
+    if (opts.version) {
+        console.log(ownVersion());
+        return;
+    }
+    p.intro(pc.bold("create-forte-ui"));
+    let plan;
+    try {
+        plan = await collectPlan(opts);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            p.cancel(error.message);
+            process.exit(1);
+        }
+        throw error;
+    }
+    warnAboutSeeds(plan);
+    const pm = opts.pm ?? detectPackageManager();
+    const upstream = plan.framework === "vite" ? "create-vite" : "create-next-app";
+    p.log.step(`Scaffolding with ${upstream}…`);
+    if (!scaffold(plan, pm)) {
+        p.cancel(`${upstream} failed — see its output above. Nothing else was written.`);
+        process.exit(1);
+    }
+    let written;
+    try {
+        written = applyOverlay(plan);
+    }
+    catch (error) {
+        p.cancel(`${error.message}\n` +
+            `The ${upstream} scaffold in ./${plan.name} is intact — ` +
+            `finish by hand with the guide: https://forte-ui.com/getting-started/${plan.framework === "vite" ? "vite" : "nextjs"}/`);
+        process.exit(1);
+    }
+    p.log.success(`Wired up forte-ui: ${written.join(", ")}`);
+    const deps = dependenciesFor(plan);
+    if (opts.install) {
+        p.log.step(`Installing ${deps.join(", ")} with ${pm}…`);
+        if (!addDependencies(pm, deps, plan.dir)) {
+            p.cancel(`${pm} failed to install — run ${pc.bold(`${installCommand(pm)}`)} in ./${plan.name} yourself.`);
+            process.exit(1);
+        }
+    }
+    else {
+        recordDependencies(plan.dir, deps);
+        p.log.info(`Skipped install; added ${deps.join(", ")} to package.json.`);
+    }
+    const steps = [
+        `cd ${plan.name}`,
+        ...(opts.install ? [] : [installCommand(pm)]),
+        devCommand(pm),
+    ];
+    p.note(steps.join("\n"), "Next");
+    p.outro(`Docs: ${pc.underline("https://forte-ui.com")} · design the theme visually: ${pc.underline("https://forte-ui.com/theme/")}`);
+}
+main().catch((error) => {
+    console.error(pc.red(`create-forte-ui: ${error instanceof Error ? error.message : String(error)}`));
+    process.exit(1);
+});

package/dist/overlay.d.ts

@@ -0,0 +1,16 @@
+import { type ThemeAnswers } from "./theme.js";
+export type Framework = "next" | "vite";
+export type ProjectPlan = {
+    name: string;
+    dir: string;
+    framework: Framework;
+    tailwind: boolean;
+    answers: ThemeAnswers;
+};
+/** Returns the files it wrote (project-relative), for the summary. */
+export declare function applyOverlay(plan: ProjectPlan): string[];
+/** The `--no-install` fallback: record the dependencies so the user's own
+ *  install resolves them. "latest" is a dist-tag, which every manager
+ *  accepts and replaces with a real range on first install. */
+export declare function recordDependencies(dir: string, deps: string[]): void;
+export declare function dependenciesFor(plan: ProjectPlan): string[];