create-basalt 1.1.0 → 1.2.0

package/README.md

@@ -93,13 +93,16 @@ Behavior notes (faithful to the code):
 
 - **Package manager detection**: by default, detects who invoked the command via the `npm_config_user_agent` variable (set by npm/pnpm/yarn/bun); unknown managers fall back to `npm`. `--pm=` overrides this.
 - **`--ui` forces pnpm**: the `web/` frontend is a member of a pnpm *workspace* (declared in the generated `pnpm-workspace.yaml`). npm, yarn, and bun can't install or run that structure, so if you request `--ui` with another manager, you'll see `Note: --ui projects are pnpm workspaces — using pnpm instead of <manager>.` and pnpm is used.
-- **Interactive mode**: only happens when you don't pass a name, you're in a terminal (TTY), and you didn't use `--yes`. Ctrl+C during a question ends cleanly with "Cancelled." (exit code 130).
+- **Interactive wizard**: when you don't pass a name, you're in a terminal (TTY), and you didn't use `--yes`, you get the guided wizard — an intro, a **starting-point preset** (SaaS starter / API only / Full stack / Minimal / Custom), an arrow-key **feature multiselect** on the custom path, package-manager select, and a **summary + confirm** step before anything is written. Ctrl+C (or declining the final confirm) ends cleanly with "Cancelled." (exit code 130).
 - **Occupied folder**: if the destination folder exists and isn't empty, the command refuses with `Target directory "<dir>" already exists and is not empty.` and exits with code 1.
 - At the end, it prints the created files and the "Next steps" appropriate to your choices.
 
 ### Invocation examples
 
 ```bash
+# Interactive wizard (presets, feature multiselect, summary):
+pnpm create basalt
+
 # Full project, no questions, with everything:
 pnpm create basalt my-app --billing --ui --cli --install --git
 

package/dist/{chunk-XV5NMTXT.js → chunk-YJ7RXFTU.js}

@@ -80,7 +80,7 @@ function tsconfigJson() {
 `;
 }
 function envTs(options) {
-  return `import { defineEnv } from '@basaltkit/env'
+  return `import { defineEnv${options.auth ? ", secret" : ""} } from '@basaltkit/env'
 import { z } from 'zod'
 
 export const env = defineEnv({
@@ -88,7 +88,9 @@ export const env = defineEnv({
   HOST: z.string().default('0.0.0.0'),
   LOG_LEVEL: z.string().default('info'),
   NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),${options.auth ? `
-  APP_SECRET: z.string().min(16).default('change-me-in-production--'),` : ""}
+  // Signs JWTs and sessions. secret() is fail-closed: required in production
+  // (no fallback), rejected if it looks like a placeholder. Dev uses devDefault.
+  APP_SECRET: secret({ minLength: 32, devDefault: 'dev-only-insecure-secret-please-change-me' }),` : ""}
 })
 `;
 }
@@ -97,20 +99,26 @@ function envExample(options) {
 HOST=0.0.0.0
 LOG_LEVEL=info
 NODE_ENV=development
-${options.auth ? "APP_SECRET=change-me-in-production--\n" : ""}`;
+${options.auth ? "# Required in production (the app refuses to boot without it).\n# Generate a strong one:  openssl rand -base64 48\n# APP_SECRET=\n" : ""}`;
 }
 function appTs(options) {
   const imports = [
     `import { createApp } from '@basaltkit/core'`,
     `import { configPlugin } from '@basaltkit/config'`,
     `import { eventsPlugin } from '@basaltkit/events'`,
-    `import { fastifyPlugin } from '@basaltkit/fastify'`,
+    `import { fastifyPlugin, securityPlugin } from '@basaltkit/fastify'`,
     `import { loggerPlugin } from '@basaltkit/logger'`
   ];
   const plugins = [
     `configPlugin({ app: { name: '${options.name}' } })`,
     `loggerPlugin({ level: options.logLevel ?? 'info', ...(options.pretty ? { pretty: true } : {}) })`,
-    `eventsPlugin()`
+    `eventsPlugin()`,
+    `securityPlugin({
+      // Secure response headers (HSTS, X-Frame-Options, nosniff, \u2026) are on by
+      // default. Turn on rate limiting and a CORS allow-list for production:
+      // rateLimit: { limit: 120, windowMs: 60_000 },
+      // cors: { origin: ['https://app.example.com'], credentials: true },
+    })`
   ];
   let routesExpression = "appRoutes";
   if (options.tenancy) {
@@ -1037,6 +1045,241 @@ function MfaCard({ status, api, onChange }: { status: { enabled: boolean; pendin
 `;
 }
 
+// src/prompt.ts
+import { emitKeypressEvents } from "readline";
+import { createInterface } from "readline/promises";
+import { stdin, stdout } from "process";
+var WizardCancelledError = class extends Error {
+  constructor() {
+    super("Cancelled.");
+    this.name = "WizardCancelledError";
+  }
+};
+var c = {
+  dim: (s) => `\x1B[2m${s}\x1B[0m`,
+  cyan: (s) => `\x1B[36m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  bold: (s) => `\x1B[1m${s}\x1B[0m`
+};
+function ttyPrompter() {
+  return {
+    intro: (message) => stdout.write(`
+${c.bold(c.cyan("\u25C6 " + message))}
+
+`),
+    note: (message) => stdout.write(`${message}
+`),
+    outro: (message) => stdout.write(`
+${c.green("\u2713 " + message)}
+`),
+    async text({ message, placeholder, initial, validate }) {
+      const rl = createInterface({ input: stdin, output: stdout });
+      rl.on("SIGINT", () => {
+        rl.close();
+        throw new WizardCancelledError();
+      });
+      try {
+        for (; ; ) {
+          const hint = placeholder ? c.dim(` (${placeholder})`) : "";
+          const answer = (await rl.question(`${c.cyan("?")} ${message}${hint}: `)).trim() || initial || "";
+          const error = validate?.(answer);
+          if (!error) return answer;
+          stdout.write(`  ${c.dim(error)}
+`);
+        }
+      } catch (error) {
+        if (error.code === "ABORT_ERR") throw new WizardCancelledError();
+        throw error;
+      } finally {
+        rl.close();
+      }
+    },
+    select({ message, choices, initial = 0 }) {
+      return keyboardSelect(message, choices, initial, false).then((v) => v[0]);
+    },
+    multiselect({ message, choices, initial = [] }) {
+      const preselected = choices.map((choice) => initial.includes(choice.value));
+      return keyboardSelect(message, choices, 0, true, preselected);
+    },
+    async confirm({ message, initial = false }) {
+      const rl = createInterface({ input: stdin, output: stdout });
+      try {
+        const answer = (await rl.question(`${c.cyan("?")} ${message} ${c.dim(initial ? "(Y/n)" : "(y/N)")} `)).trim().toLowerCase();
+        return answer ? answer.startsWith("y") : initial;
+      } finally {
+        rl.close();
+      }
+    }
+  };
+}
+function keyboardSelect(message, choices, initialIndex, multi, selected = choices.map(() => false)) {
+  return new Promise((resolve2, reject) => {
+    let index = initialIndex;
+    let rendered = 0;
+    emitKeypressEvents(stdin);
+    const wasRaw = stdin.isTTY ? stdin.isRaw : false;
+    if (stdin.isTTY) stdin.setRawMode(true);
+    const render = () => {
+      if (rendered > 0) stdout.write(`\x1B[${rendered}A\x1B[0J`);
+      const lines = [`${c.cyan("?")} ${message}${multi ? c.dim(" (space to toggle, enter to confirm)") : ""}`];
+      choices.forEach((choice, i) => {
+        const pointer = i === index ? c.cyan("\u276F") : " ";
+        const box = multi ? (selected[i] ? c.green("\u25C9") : "\u25EF") + " " : "";
+        const label = i === index ? c.cyan(choice.label) : choice.label;
+        const hint = choice.hint ? c.dim(` \u2014 ${choice.hint}`) : "";
+        lines.push(`${pointer} ${box}${label}${hint}`);
+      });
+      stdout.write(lines.join("\n") + "\n");
+      rendered = lines.length;
+    };
+    const cleanup = () => {
+      stdin.off("keypress", onKey);
+      if (stdin.isTTY) stdin.setRawMode(wasRaw);
+      stdin.pause();
+    };
+    const onKey = (_str, key) => {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        reject(new WizardCancelledError());
+      } else if (key.name === "up" || key.name === "k") {
+        index = (index - 1 + choices.length) % choices.length;
+        render();
+      } else if (key.name === "down" || key.name === "j") {
+        index = (index + 1) % choices.length;
+        render();
+      } else if (multi && key.name === "space") {
+        selected[index] = !selected[index];
+        render();
+      } else if (key.name === "return") {
+        cleanup();
+        resolve2(
+          multi ? choices.filter((_, i) => selected[i]).map((choice) => choice.value) : [choices[index].value]
+        );
+      }
+    };
+    stdin.resume();
+    stdin.on("keypress", onKey);
+    render();
+  });
+}
+function scriptedPrompter(script) {
+  const text = [...script.text ?? []];
+  const select = [...script.select ?? []];
+  const multiselect = [...script.multiselect ?? []];
+  const confirm = [...script.confirm ?? []];
+  const log = [];
+  const next = (queue, kind) => {
+    if (queue.length === 0) throw new Error(`scriptedPrompter: no more ${kind} answers`);
+    return queue.shift();
+  };
+  return {
+    log,
+    intro: (m) => log.push(m),
+    note: (m) => log.push(m),
+    outro: (m) => log.push(m),
+    async text() {
+      return next(text, "text");
+    },
+    async select() {
+      return next(select, "select");
+    },
+    async multiselect() {
+      return next(multiselect, "multiselect");
+    },
+    async confirm() {
+      return next(confirm, "confirm");
+    }
+  };
+}
+
+// src/wizard.ts
+var FEATURES = [
+  { value: "tenancy", label: "Multi-tenancy", hint: "per-tenant data isolation" },
+  { value: "auth", label: "Authentication", hint: "JWT, sessions, MFA, OAuth" },
+  { value: "billing", label: "Subscriptions / billing", hint: "Stripe, Paddle, Lemon Squeezy" },
+  { value: "ui", label: "Web UI", hint: "React + shadcn + SDK (pnpm workspace)" },
+  { value: "cli", label: "basalt CLI", hint: "code generators + commands" }
+];
+var PRESETS = [
+  { value: "saas", label: "SaaS starter", hint: "tenancy + auth + billing + CLI", features: ["tenancy", "auth", "billing", "cli"] },
+  { value: "api", label: "API only", hint: "auth, no tenancy or UI", features: ["auth"] },
+  { value: "full", label: "Full stack", hint: "everything + web UI", features: ["tenancy", "auth", "billing", "ui", "cli"] },
+  { value: "minimal", label: "Minimal", hint: "no batteries, add them later", features: [] },
+  { value: "custom", label: "Custom", hint: "pick features yourself", features: null }
+];
+var PACKAGE_MANAGERS = [
+  { value: "pnpm", label: "pnpm", hint: "recommended" },
+  { value: "npm", label: "npm" },
+  { value: "yarn", label: "yarn" },
+  { value: "bun", label: "bun" }
+];
+function validateProjectName(name) {
+  const trimmed = name.trim();
+  if (!trimmed) return "Please enter a project name.";
+  if (trimmed.length > 214) return "Name is too long (max 214 characters).";
+  if (!/^(?:@[a-z0-9-~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(trimmed)) {
+    return "Use a valid npm package name (lowercase, no spaces).";
+  }
+  return void 0;
+}
+async function runWizard(prompter, options = {}) {
+  prompter.intro("create-basalt \u2014 scaffold a Basalt application");
+  const name = options.name && !validateProjectName(options.name) ? options.name : await prompter.text({
+    message: "Project name",
+    placeholder: "my-saas",
+    initial: "my-saas",
+    validate: validateProjectName
+  });
+  const presetValue = await prompter.select({
+    message: "Choose a starting point",
+    choices: PRESETS.map((p) => ({ value: p.value, label: p.label, hint: p.hint })),
+    initial: 0
+  });
+  const preset = PRESETS.find((p) => p.value === presetValue) ?? PRESETS[0];
+  const featureSet = new Set(
+    preset.features ?? await prompter.multiselect({
+      message: "Select features",
+      choices: FEATURES,
+      initial: ["tenancy", "auth"]
+    })
+  );
+  let pm = await prompter.select({
+    message: "Package manager",
+    choices: PACKAGE_MANAGERS,
+    initial: Math.max(0, PACKAGE_MANAGERS.findIndex((m) => m.value === (options.defaultPm ?? "pnpm")))
+  });
+  if (featureSet.has("ui") && pm !== "pnpm") {
+    prompter.note(`  Note: the Web UI is a pnpm workspace \u2014 using pnpm instead of ${pm}.`);
+    pm = "pnpm";
+  }
+  const install = await prompter.confirm({ message: "Install dependencies now?", initial: false });
+  const git = await prompter.confirm({ message: "Initialize a git repository?", initial: false });
+  const enabled = FEATURES.filter((f) => featureSet.has(f.value)).map((f) => f.label);
+  prompter.note(
+    `
+  Summary
+    name      ${name}
+    features  ${enabled.length ? enabled.join(", ") : "(none)"}
+    pm        ${pm}
+    install   ${install ? "yes" : "no"}
+    git       ${git ? "yes" : "no"}
+`
+  );
+  const ok = await prompter.confirm({ message: "Create project?", initial: true });
+  if (!ok) throw new WizardCancelledError();
+  return {
+    name,
+    tenancy: featureSet.has("tenancy"),
+    auth: featureSet.has("auth"),
+    billing: featureSet.has("billing"),
+    ui: featureSet.has("ui"),
+    cli: featureSet.has("cli"),
+    pm,
+    install,
+    git
+  };
+}
+
 // src/index.ts
 var TargetNotEmptyError = class extends Error {
   constructor(dir) {
@@ -1085,6 +1328,13 @@ async function createProject(input) {
 }
 
 export {
+  WizardCancelledError,
+  ttyPrompter,
+  scriptedPrompter,
+  FEATURES,
+  PRESETS,
+  validateProjectName,
+  runWizard,
   TargetNotEmptyError,
   detectPackageManager,
   createProject

package/dist/cli.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 import {
   TargetNotEmptyError,
+  WizardCancelledError,
   createProject,
-  detectPackageManager
-} from "./chunk-XV5NMTXT.js";
+  detectPackageManager,
+  runWizard,
+  ttyPrompter
+} from "./chunk-YJ7RXFTU.js";
 
 // src/cli.ts
 import { spawn } from "child_process";
 import { stdin, stdout } from "process";
-import { createInterface } from "readline/promises";
 var USAGE = `Usage: npm create basalt <name> [options]
 
 Options:
@@ -70,36 +72,26 @@ function cancel() {
   stdout.write("\nCancelled.\n");
   process.exit(130);
 }
-async function promptMissing(flags2) {
-  if (flags2.yes || flags2.name !== void 0 || !stdin.isTTY) return flags2;
-  const rl = createInterface({ input: stdin, output: stdout });
-  rl.on("SIGINT", cancel);
+var flags = parseArgs(process.argv.slice(2));
+if (!flags.yes && flags.name === void 0 && stdin.isTTY) {
   try {
-    const ask = async (question, fallback) => {
-      const answer = (await rl.question(`${question} `)).trim();
-      return answer || fallback;
-    };
-    const confirm = async (question, fallback) => {
-      const answer = (await rl.question(`${question} (${fallback ? "Y/n" : "y/N"}) `)).trim().toLowerCase();
-      return answer ? answer.startsWith("y") : fallback;
-    };
-    flags2.name = await ask("Project name:", "my-saas");
-    flags2.tenancy = await confirm("Multi-tenancy?", true);
-    flags2.auth = await confirm("Authentication?", true);
-    flags2.billing = await confirm("Subscriptions / billing?", false);
-    flags2.ui = await confirm("Web UI (React + shadcn)?", false);
-    flags2.cli = await confirm("'basalt' CLI (code generators)?", false);
-    flags2.install = await confirm("Install dependencies now?", false);
-    flags2.git = await confirm("Initialize a git repository?", false);
+    const result = await runWizard(ttyPrompter(), {
+      defaultPm: flags.pm ?? detectPackageManager()
+    });
+    flags.name = result.name;
+    flags.tenancy = result.tenancy;
+    flags.auth = result.auth;
+    flags.billing = result.billing;
+    flags.ui = result.ui;
+    flags.cli = result.cli;
+    flags.install = result.install;
+    flags.git = result.git;
+    flags.pm = result.pm;
   } catch (error) {
-    if (error.code === "ABORT_ERR") cancel();
+    if (error instanceof WizardCancelledError) cancel();
     throw error;
-  } finally {
-    rl.close();
   }
-  return flags2;
 }
-var flags = await promptMissing(parseArgs(process.argv.slice(2)));
 if (!flags.name) {
   stdout.write(USAGE);
   process.exit(1);

package/dist/index.d.ts

@@ -9,6 +9,101 @@ interface ProjectOptions {
     cli: boolean;
 }
 
+/** A selectable option. `value` is returned; `label`/`hint` are shown. */
+interface Choice<T> {
+    value: T;
+    label: string;
+    hint?: string;
+}
+/**
+ * The prompt surface the wizard talks to. Abstracted so the flow (`runWizard`)
+ * is testable with a scripted implementation — the raw-mode TTY version is the
+ * thin, untested I/O shell.
+ */
+interface Prompter {
+    intro(message: string): void;
+    note(message: string): void;
+    outro(message: string): void;
+    text(opts: {
+        message: string;
+        placeholder?: string;
+        initial?: string;
+        validate?: (v: string) => string | undefined;
+    }): Promise<string>;
+    select<T>(opts: {
+        message: string;
+        choices: Choice<T>[];
+        initial?: number;
+    }): Promise<T>;
+    multiselect<T>(opts: {
+        message: string;
+        choices: Choice<T>[];
+        initial?: T[];
+    }): Promise<T[]>;
+    confirm(opts: {
+        message: string;
+        initial?: boolean;
+    }): Promise<boolean>;
+}
+/** Thrown when the user aborts (Ctrl+C, or declines the final confirmation). */
+declare class WizardCancelledError extends Error {
+    constructor();
+}
+/**
+ * A rich, dependency-free terminal prompter: arrow-key `select`/`multiselect`
+ * (raw mode), validated `text`, and `confirm`. Only usable in a TTY.
+ */
+declare function ttyPrompter(): Prompter;
+/**
+ * A scripted prompter for tests: each call dequeues the next answer of its kind.
+ * `log` captures intro/note/outro lines so a test can assert the summary.
+ */
+declare function scriptedPrompter(script: {
+    text?: string[];
+    select?: unknown[];
+    multiselect?: unknown[][];
+    confirm?: boolean[];
+}): Prompter & {
+    log: string[];
+};
+
+type FeatureKey = 'tenancy' | 'auth' | 'billing' | 'ui' | 'cli';
+/** The feature toggles offered in the "custom" preset (and shown in the summary). */
+declare const FEATURES: Choice<FeatureKey>[];
+interface Preset {
+    value: string;
+    label: string;
+    hint: string;
+    /** null → let the user pick features (custom). */
+    features: FeatureKey[] | null;
+}
+declare const PRESETS: Preset[];
+/** Validates a project name as an npm-installable package name. */
+declare function validateProjectName(name: string): string | undefined;
+interface WizardResult {
+    name: string;
+    tenancy: boolean;
+    auth: boolean;
+    billing: boolean;
+    ui: boolean;
+    cli: boolean;
+    pm: PackageManager;
+    install: boolean;
+    git: boolean;
+}
+interface WizardOptions {
+    /** Pre-filled name (from argv) — skips the name prompt when valid. */
+    name?: string;
+    /** Detected package manager, used as the default selection. */
+    defaultPm?: PackageManager;
+}
+/**
+ * The interactive scaffolding flow. Pure with respect to I/O — it drives the
+ * injected {@link Prompter}, so tests script the answers and assert the result.
+ * Throws {@link WizardCancelledError} if the user declines the final confirm.
+ */
+declare function runWizard(prompter: Prompter, options?: WizardOptions): Promise<WizardResult>;
+
 interface CreateProjectInput {
     name: string;
     /** Target directory. Default: ./<name> under cwd. */
@@ -38,4 +133,4 @@ declare function detectPackageManager(userAgent?: string | undefined): PackageMa
 /** Generates a ready-to-run Basalt app. Does not install dependencies. */
 declare function createProject(input: CreateProjectInput): Promise<CreateProjectResult>;
 
-export { type CreateProjectInput, type CreateProjectResult, type PackageManager, type ProjectOptions, TargetNotEmptyError, createProject, detectPackageManager };
+export { type Choice, type CreateProjectInput, type CreateProjectResult, FEATURES, type FeatureKey, PRESETS, type PackageManager, type ProjectOptions, type Prompter, TargetNotEmptyError, WizardCancelledError, type WizardOptions, type WizardResult, createProject, detectPackageManager, runWizard, scriptedPrompter, ttyPrompter, validateProjectName };

package/dist/index.js

@@ -1,10 +1,24 @@
 import {
+  FEATURES,
+  PRESETS,
   TargetNotEmptyError,
+  WizardCancelledError,
   createProject,
-  detectPackageManager
-} from "./chunk-XV5NMTXT.js";
+  detectPackageManager,
+  runWizard,
+  scriptedPrompter,
+  ttyPrompter,
+  validateProjectName
+} from "./chunk-YJ7RXFTU.js";
 export {
+  FEATURES,
+  PRESETS,
   TargetNotEmptyError,
+  WizardCancelledError,
   createProject,
-  detectPackageManager
+  detectPackageManager,
+  runWizard,
+  scriptedPrompter,
+  ttyPrompter,
+  validateProjectName
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Scaffold a production-shaped Basalt SaaS app: npm create basalt my-saas [--billing] [--ui] [--cli] [--install] [--git]",
   "license": "MIT",
   "type": "module",