create-forte-ui 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/args.d.ts

@@ -6,8 +6,19 @@ export type CliOptions = {
     framework?: Framework;
     tailwind?: boolean;
     pm?: PackageManager;
+    /** Version spec for `@forte-ui/react` — exact ("1.0.0-alpha.4"), dist-tag
+     *  ("alpha"), or range. Deliberately NOT validated here: the package
+     *  manager understands every legal form (tags, ranges, `file:`…) and
+     *  rejects a wrong one at install with a better error than any regex
+     *  would give. Undefined = the registry's `latest`. Dev/CI knob only —
+     *  no prompt, and the studio dialog knows nothing about it. */
+    library?: string;
     yes: boolean;
     install: boolean;
+    /** Install the forte-ui agent skill (skills.sh) into the project. On by
+     *  default; `--no-skill` opts out, and `--no-install` skips it with
+     *  everything else. */
+    skill: boolean;
     help: boolean;
     version: boolean;
     /** Only the keys given as flags — presence is what suppresses the prompt. */
@@ -16,4 +27,4 @@ export type CliOptions = {
 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";
+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  --library              version spec for @forte-ui/react \u2014 exact\n                         (\"1.0.0-alpha.4\"), a dist-tag (\"alpha\"), or a range.\n                         Default: latest.\n  --no-install           write files only; skip installing dependencies\n                         and the agent skill\n  --no-skill             skip installing the forte-ui agent skill\n                         (skills.sh \u2014 .agents/skills plus .claude/skills)\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

@@ -53,9 +53,11 @@ export function parseCliArgs(argv) {
             motion: { type: "string" },
             "font-sans": { type: "string" },
             "font-mono": { type: "string" },
+            library: { type: "string" },
             pm: { type: "string" },
             yes: { type: "boolean", short: "y" },
             "no-install": { type: "boolean" },
+            "no-skill": { type: "boolean" },
             help: { type: "boolean", short: "h" },
             version: { type: "boolean", short: "v" },
         },
@@ -103,8 +105,10 @@ export function parseCliArgs(argv) {
         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),
+        library: values.library,
         yes: values.yes ?? false,
         install: !(values["no-install"] ?? false),
+        skill: !(values["no-skill"] ?? false),
         help: values.help ?? false,
         version: values.version ?? false,
         answers,
@@ -126,7 +130,13 @@ Project
   --tailwind             wire the Tailwind v4 bridge (default yes)
   --no-tailwind          plain CSS setup
   --pm                   npm | pnpm | yarn | bun (default: whoever invoked us)
+  --library              version spec for @forte-ui/react — exact
+                         ("1.0.0-alpha.4"), a dist-tag ("alpha"), or a range.
+                         Default: latest.
   --no-install           write files only; skip installing dependencies
+                         and the agent skill
+  --no-skill             skip installing the forte-ui agent skill
+                         (skills.sh — .agents/skills plus .claude/skills)
   -y, --yes              accept the defaults for everything not passed
 
 Theme — every skipped value keeps the library default and writes NOTHING,

package/dist/index.js

@@ -15,8 +15,8 @@ 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";
+import { applyOverlay, dependenciesFor, recordDependencies, toAddSpecs, } from "./overlay.js";
+import { detectPackageManager, runScaffolder, addDependencies, installSkill, 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;
@@ -109,17 +109,35 @@ async function main() {
         process.exit(1);
     }
     p.log.success(`Wired up forte-ui: ${written.join(", ")}`);
-    const deps = dependenciesFor(plan);
+    const deps = dependenciesFor(plan, opts.library);
+    const specs = toAddSpecs(deps);
     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.`);
+        p.log.step(`Installing ${specs.join(", ")} with ${pm}…`);
+        if (!addDependencies(pm, specs, plan.dir)) {
+            /* A `--library` spec is validated only here, by the registry itself —
+             * so on failure say which spec died rather than suggesting a re-run
+             * that would resolve the exact same thing. */
+            p.cancel(opts.library
+                ? `${pm} could not install @forte-ui/react@${opts.library} — see its output above. ` +
+                    `Check that the --library spec exists on the registry.`
+                : `${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.`);
+        p.log.info(`Skipped install; added ${specs.join(", ")} to package.json.`);
+    }
+    /* The agent skill, so AI tooling in the new project starts past the
+     * library's silent traps. Gated on `install` too: `--no-install` means
+     * "write files, run nothing". Failure is a warning, not an exit — the app
+     * is complete without it, and the guide's one-liner recovers it. */
+    if (opts.install && opts.skill) {
+        p.log.step("Installing the forte-ui agent skill…");
+        if (!installSkill(pm, plan.dir)) {
+            p.log.warn("Skill install failed — the app is unaffected. " +
+                `Run ${pc.bold("npx skills add arsen/forte-ui -s forte-ui")} in ./${plan.name} to retry.`);
+        }
     }
     const steps = [
         `cd ${plan.name}`,

package/dist/overlay.d.ts

@@ -9,8 +9,16 @@ export type ProjectPlan = {
 };
 /** Returns the files it wrote (project-relative), for the summary. */
 export declare function applyOverlay(plan: ProjectPlan): string[];
+export type Dependency = {
+    name: string;
+    spec: 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[];
+ *  install resolves them. The default spec is the "latest" dist-tag, which
+ *  every manager accepts and replaces with a real range on first install —
+ *  and so is anything `--library` put there instead, tag, range or exact. */
+export declare function recordDependencies(dir: string, deps: Dependency[]): void;
+/** `pm add` arguments: the bare name resolves `latest` exactly as before, so
+ *  only a `--library` spec changes what gets asked of the registry. */
+export declare function toAddSpecs(deps: Dependency[]): string[];
+export declare function dependenciesFor(plan: ProjectPlan, library?: string): Dependency[];

package/dist/overlay.js

@@ -88,20 +88,28 @@ function applyNext({ name, dir, tailwind, answers }) {
     return written;
 }
 /** 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. */
+ *  install resolves them. The default spec is the "latest" dist-tag, which
+ *  every manager accepts and replaces with a real range on first install —
+ *  and so is anything `--library` put there instead, tag, range or exact. */
 export function recordDependencies(dir, deps) {
     const pkgPath = path.join(dir, "package.json");
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
     pkg.dependencies ??= {};
     for (const dep of deps)
-        pkg.dependencies[dep] = "latest";
+        pkg.dependencies[dep.name] = dep.spec;
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
-export function dependenciesFor(plan) {
-    /* create-next-app's --tailwind scaffold already carries tailwindcss v4;
-     * on Vite the guide installs it alongside the library, plus the plugin. */
+/** `pm add` arguments: the bare name resolves `latest` exactly as before, so
+ *  only a `--library` spec changes what gets asked of the registry. */
+export function toAddSpecs(deps) {
+    return deps.map((d) => (d.spec === "latest" ? d.name : `${d.name}@${d.spec}`));
+}
+export function dependenciesFor(plan, library) {
+    /* `--library` steers ONLY the library. The Vite Tailwind extras stay on
+     * latest — the templates target current Tailwind v4 regardless of which
+     * forte-ui build is being tried out. */
+    const lib = { name: "@forte-ui/react", spec: library ?? "latest" };
     return plan.framework === "vite" && plan.tailwind
-        ? ["@forte-ui/react", "tailwindcss", "@tailwindcss/vite"]
-        : ["@forte-ui/react"];
+        ? [lib, { name: "tailwindcss", spec: "latest" }, { name: "@tailwindcss/vite", spec: "latest" }]
+        : [lib];
 }

package/dist/scaffold.d.ts

@@ -12,6 +12,13 @@ export declare function runScaffolder(pm: PackageManager, pkg: string, args: str
 /** `pm add <deps>` in the project — resolves "latest" into a real caret range
  *  in package.json and performs the full install in one pass. */
 export declare function addDependencies(pm: PackageManager, deps: string[], cwd: string): boolean;
+/** Install the forte-ui agent skill into the project via skills.sh, the
+ *  same command the AI-agents guide documents. `-s forte-ui` is load-bearing:
+ *  the repository also carries internal skills (release-prep) that must not
+ *  reach consumers. `-y` writes the universal `.agents/skills` copy plus the
+ *  per-agent links — `.claude/skills` for Claude Code among them — without
+ *  prompting. */
+export declare function installSkill(pm: PackageManager, cwd: string): boolean;
 /** The dev-server line for the outro, in the user's own manager. */
 export declare function devCommand(pm: PackageManager): string;
 export declare function installCommand(pm: PackageManager): string;

package/dist/scaffold.js

@@ -46,6 +46,15 @@ export function addDependencies(pm, deps, cwd) {
     const sub = pm === "npm" ? "install" : "add";
     return run(pm, [sub, ...deps], cwd);
 }
+/** Install the forte-ui agent skill into the project via skills.sh, the
+ *  same command the AI-agents guide documents. `-s forte-ui` is load-bearing:
+ *  the repository also carries internal skills (release-prep) that must not
+ *  reach consumers. `-y` writes the universal `.agents/skills` copy plus the
+ *  per-agent links — `.claude/skills` for Claude Code among them — without
+ *  prompting. */
+export function installSkill(pm, cwd) {
+    return runScaffolder(pm, "skills@latest", ["add", "arsen/forte-ui", "-s", "forte-ui", "-y"], cwd);
+}
 /** The dev-server line for the outro, in the user's own manager. */
 export function devCommand(pm) {
     return pm === "npm" ? "npm run dev" : `${pm} dev`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forte-ui",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.5",
   "description": "Scaffold a new app wired up with forte-ui — Vite or Next.js, with or without Tailwind, themed from your answers.",
   "license": "MIT",
   "type": "module",