create-basalt 1.2.1 → 1.3.0

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # create-basalt
 
 Basalt project generator: a single command (`npm create basalt my-app`) creates a complete, ready-to-run SaaS application — typed API, authentication, multi-tenancy, and optionally billing, a web frontend, and the `basalt` CLI. It's the framework's starting point: use it whenever you want to start a new project.
@@ -40,6 +46,7 @@ Multi-tenancy? (Y/n) y
 Authentication? (Y/n) y
 Subscriptions / billing? (y/N) n
 Web UI (React + shadcn)? (y/N) n
+MCP server (routes as AI-agent tools)? (y/N) n
 'basalt' CLI (code generators)? (y/N) n
 Install dependencies now? (y/N) y
 Initialize a git repository? (y/N) y
@@ -83,6 +90,7 @@ Usage: npm create basalt <name> [options]
 | `--billing` | off | Includes subscriptions/plans (`@basaltkit/subscriptions`, example `free` and `pro` plans) |
 | `--ui` | off | Generates the `web/` frontend (React + shadcn via `@basaltkit/admin-shadcn` + `@basaltkit/sdk`). **Forces pnpm** — see note below |
 | `--cli` | off | Generates the `basalt` CLI (`bin/basalt.ts`, `pnpm basalt` script, `make:*` generators from `@basaltkit/generator`) |
+| `--mcp` | off | Exposes read-only routes as MCP tools (`@basaltkit/mcp`) over HTTP at `POST /mcp` — the overview and health endpoints are opted in via `meta.mcp` |
 | `--install` | off | Installs dependencies at the end (with the detected/chosen manager) |
 | `--git` | off | Runs `git init` + first commit ("Initial commit from create-basalt") |
 | `--pm=<manager>` | autodetect | Package manager: `pnpm` \| `npm` \| `yarn` \| `bun` |
@@ -196,6 +204,7 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | `billing` | `boolean` | No | `false` | Include subscriptions |
 | `ui` | `boolean` | No | `false` | Generate the `web/` frontend |
 | `cli` | `boolean` | No | `false` | Generate the `basalt` CLI |
+| `mcp` | `boolean` | No | `false` | Expose read-only routes as MCP tools at `/mcp` |
 
 `CreateProjectResult`:
 

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -1,17 +1,8 @@
 #!/usr/bin/env node
-import {
-  TargetNotEmptyError,
-  WizardCancelledError,
-  createProject,
-  detectPackageManager,
-  runWizard,
-  ttyPrompter
-} from "./chunk-Z6RTS4I7.js";
-
-// src/cli.ts
-import { spawn } from "child_process";
-import { stdin, stdout } from "process";
-var USAGE = `Usage: npm create basalt <name> [options]
+import { spawn } from 'node:child_process';
+import { stdin, stdout } from 'node:process';
+import { createProject, detectPackageManager, runWizard, ttyPrompter, TargetNotEmptyError, WizardCancelledError, } from './index.js';
+const USAGE = `Usage: npm create basalt <name> [options]
 
 Options:
   --dir=<path>    Target directory (default: ./<name>)
@@ -20,6 +11,7 @@ Options:
   --billing       Include subscriptions/billing
   --ui            Scaffold a web/ frontend (React + shadcn + SDK)
   --cli           Scaffold the 'basalt' CLI (code generators + commands)
+  --mcp           Expose read-only routes as MCP tools at /mcp
   --install       Install dependencies after scaffolding
   --git           Initialize a git repository with a first commit
   --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)
@@ -29,121 +21,143 @@ Options:
 Run with no name in a terminal to be prompted interactively.
 `;
 function parseArgs(argv) {
-  const flags2 = {
-    tenancy: true,
-    auth: true,
-    billing: false,
-    ui: false,
-    cli: false,
-    install: false,
-    git: false,
-    yes: false
-  };
-  for (const token of argv) {
-    if (token === "--no-tenancy") flags2.tenancy = false;
-    else if (token === "--no-auth") flags2.auth = false;
-    else if (token === "--billing") flags2.billing = true;
-    else if (token === "--ui") flags2.ui = true;
-    else if (token === "--cli") flags2.cli = true;
-    else if (token === "--install") flags2.install = true;
-    else if (token === "--git") flags2.git = true;
-    else if (token === "-y" || token === "--yes") flags2.yes = true;
-    else if (token.startsWith("--dir=")) flags2.dir = token.slice("--dir=".length);
-    else if (token.startsWith("--pm=")) flags2.pm = token.slice("--pm=".length);
-    else if (token === "--help" || token === "-h") {
-      stdout.write(USAGE);
-      process.exit(0);
-    } else if (!token.startsWith("--") && flags2.name === void 0) flags2.name = token;
-  }
-  return flags2;
+    const flags = {
+        tenancy: true,
+        auth: true,
+        billing: false,
+        ui: false,
+        cli: false,
+        mcp: false,
+        install: false,
+        git: false,
+        yes: false,
+    };
+    for (const token of argv) {
+        if (token === '--no-tenancy')
+            flags.tenancy = false;
+        else if (token === '--no-auth')
+            flags.auth = false;
+        else if (token === '--billing')
+            flags.billing = true;
+        else if (token === '--ui')
+            flags.ui = true;
+        else if (token === '--cli')
+            flags.cli = true;
+        else if (token === '--mcp')
+            flags.mcp = true;
+        else if (token === '--install')
+            flags.install = true;
+        else if (token === '--git')
+            flags.git = true;
+        else if (token === '-y' || token === '--yes')
+            flags.yes = true;
+        else if (token.startsWith('--dir='))
+            flags.dir = token.slice('--dir='.length);
+        else if (token.startsWith('--pm='))
+            flags.pm = token.slice('--pm='.length);
+        else if (token === '--help' || token === '-h') {
+            stdout.write(USAGE);
+            process.exit(0);
+        }
+        else if (!token.startsWith('--') && flags.name === undefined)
+            flags.name = token;
+    }
+    return flags;
 }
+/** Runs a command inheriting stdio; resolves false on non-zero exit (never throws). */
 function run(command, args, cwd) {
-  return new Promise((resolve) => {
-    const child = spawn(command, args, {
-      cwd,
-      stdio: "inherit",
-      shell: process.platform === "win32"
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd,
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        child.on('error', () => resolve(false));
+        child.on('close', (code) => resolve(code === 0));
     });
-    child.on("error", () => resolve(false));
-    child.on("close", (code) => resolve(code === 0));
-  });
 }
+/** Cleanly abort on Ctrl+C instead of dumping a Node AbortError stack trace. */
 function cancel() {
-  stdout.write("\nCancelled.\n");
-  process.exit(130);
+    stdout.write('\nCancelled.\n');
+    process.exit(130); // 128 + SIGINT
 }
-var flags = parseArgs(process.argv.slice(2));
-if (!flags.yes && flags.name === void 0 && stdin.isTTY) {
-  try {
-    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 instanceof WizardCancelledError) cancel();
-    throw error;
-  }
+const flags = parseArgs(process.argv.slice(2));
+// Rich interactive wizard when nothing was specified in a terminal. CI, piped
+// input, and `--yes` keep the flag-driven path.
+if (!flags.yes && flags.name === undefined && stdin.isTTY) {
+    try {
+        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.mcp = result.mcp;
+        flags.install = result.install;
+        flags.git = result.git;
+        flags.pm = result.pm;
+    }
+    catch (error) {
+        if (error instanceof WizardCancelledError)
+            cancel();
+        throw error;
+    }
 }
 if (!flags.name) {
-  stdout.write(USAGE);
-  process.exit(1);
+    stdout.write(USAGE);
+    process.exit(1);
 }
-var pm = flags.pm ?? detectPackageManager();
-if (flags.ui && pm !== "pnpm") {
-  console.log(`Note: --ui projects are pnpm workspaces \u2014 using pnpm instead of ${pm}.`);
-  pm = "pnpm";
+let pm = flags.pm ?? detectPackageManager();
+// The web/ frontend is a pnpm workspace member (pnpm-workspace.yaml); npm,
+// yarn and bun can't install or run it, so --ui projects are pnpm-only.
+if (flags.ui && pm !== 'pnpm') {
+    console.log(`Note: --ui projects are pnpm workspaces — using pnpm instead of ${pm}.`);
+    pm = 'pnpm';
 }
 try {
-  const result = await createProject({
-    name: flags.name,
-    ...flags.dir ? { dir: flags.dir } : {},
-    tenancy: flags.tenancy,
-    auth: flags.auth,
-    billing: flags.billing,
-    ui: flags.ui,
-    cli: flags.cli
-  });
-  console.log(`
-Created ${result.options.name} in ${result.dir}
-`);
-  for (const file of result.files) console.log(`  ${file}`);
-  if (flags.git) {
-    console.log("\nInitializing git repository\u2026");
-    const ok = await run("git", ["init", "-q"], result.dir) && await run("git", ["add", "-A"], result.dir) && await run(
-      "git",
-      ["commit", "-q", "-m", "Initial commit from create-basalt"],
-      result.dir
-    );
-    console.log(
-      ok ? "  git repository initialized." : "  (skipped \u2014 git unavailable or already a repo)"
-    );
-  }
-  if (flags.install) {
-    console.log(`
-Installing dependencies with ${pm}\u2026`);
-    const ok = await run(pm, ["install"], result.dir);
-    if (!ok) console.log(`  (install failed \u2014 run "${pm} install" yourself)`);
-  }
-  const steps = [`cd ${result.dir}`];
-  if (!flags.install) steps.push(`${pm} install`);
-  steps.push(`${pm} run dev${flags.ui ? "        # API on :3000" : ""}`);
-  if (flags.ui) steps.push(`pnpm --filter ${result.options.name}-web dev   # UI on :5180`);
-  console.log(`
-Next steps:
-${steps.map((s) => `  ${s}`).join("\n")}
-`);
-} catch (error) {
-  if (error instanceof TargetNotEmptyError) {
-    console.error(error.message);
-    process.exit(1);
-  }
-  throw error;
+    const result = await createProject({
+        name: flags.name,
+        ...(flags.dir ? { dir: flags.dir } : {}),
+        tenancy: flags.tenancy,
+        auth: flags.auth,
+        billing: flags.billing,
+        ui: flags.ui,
+        cli: flags.cli,
+        mcp: flags.mcp,
+    });
+    console.log(`\nCreated ${result.options.name} in ${result.dir}\n`);
+    for (const file of result.files)
+        console.log(`  ${file}`);
+    if (flags.git) {
+        console.log('\nInitializing git repository…');
+        const ok = (await run('git', ['init', '-q'], result.dir)) &&
+            (await run('git', ['add', '-A'], result.dir)) &&
+            (await run('git', ['commit', '-q', '-m', 'Initial commit from create-basalt'], result.dir));
+        console.log(ok ? '  git repository initialized.' : '  (skipped — git unavailable or already a repo)');
+    }
+    if (flags.install) {
+        console.log(`\nInstalling dependencies with ${pm}…`);
+        const ok = await run(pm, ['install'], result.dir);
+        if (!ok)
+            console.log(`  (install failed — run "${pm} install" yourself)`);
+    }
+    const steps = [`cd ${result.dir}`];
+    if (!flags.install)
+        steps.push(`${pm} install`);
+    steps.push(`${pm} run dev${flags.ui ? '        # API on :3000' : ''}`);
+    // `web` is wired as a pnpm workspace member (pnpm-workspace.yaml), so its dev
+    // server is launched with a pnpm filter regardless of the root package manager.
+    if (flags.ui)
+        steps.push(`pnpm --filter ${result.options.name}-web dev   # UI on :5180`);
+    console.log(`\nNext steps:\n${steps.map((s) => `  ${s}`).join('\n')}\n`);
+}
+catch (error) {
+    if (error instanceof TargetNotEmptyError) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    throw error;
 }

package/dist/index.d.ts

@@ -1,110 +1,6 @@
-interface ProjectOptions {
-    name: string;
-    tenancy: boolean;
-    auth: boolean;
-    billing: boolean;
-    /** Scaffold a web/ frontend (React + shadcn + SDK). */
-    ui: boolean;
-    /** Scaffold the `basalt` CLI entrypoint (code generators + built-in commands). */
-    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 {
+import { type ProjectOptions } from './templates.js';
+export type { ProjectOptions } from './templates.js';
+export interface CreateProjectInput {
     name: string;
     /** Target directory. Default: ./<name> under cwd. */
     dir?: string;
@@ -115,22 +11,24 @@ interface CreateProjectInput {
     ui?: boolean;
     /** Scaffold the `basalt` CLI entrypoint (code generators + commands). Default: false. */
     cli?: boolean;
+    /** Expose opted-in routes as MCP tools over HTTP at `/mcp`. Default: false. */
+    mcp?: boolean;
 }
-interface CreateProjectResult {
+export interface CreateProjectResult {
     dir: string;
     files: string[];
     options: ProjectOptions;
 }
-declare class TargetNotEmptyError extends Error {
+export declare class TargetNotEmptyError extends Error {
     constructor(dir: string);
 }
-type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
 /**
  * Detects the package manager that invoked `npm create` / `npx`, via the
  * `npm_config_user_agent` env var npm/pnpm/yarn/bun all set. Falls back to npm.
  */
-declare function detectPackageManager(userAgent?: string | undefined): PackageManager;
+export declare function detectPackageManager(userAgent?: string | undefined): PackageManager;
 /** Generates a ready-to-run Basalt app. Does not install dependencies. */
-declare function createProject(input: CreateProjectInput): Promise<CreateProjectResult>;
-
-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 };
+export declare function createProject(input: CreateProjectInput): Promise<CreateProjectResult>;
+export { runWizard, validateProjectName, PRESETS, FEATURES, type WizardResult, type WizardOptions, type FeatureKey } from './wizard.js';
+export { ttyPrompter, scriptedPrompter, WizardCancelledError, type Prompter, type Choice } from './prompt.js';

package/dist/index.js

@@ -1,24 +1,60 @@
-import {
-  FEATURES,
-  PRESETS,
-  TargetNotEmptyError,
-  WizardCancelledError,
-  createProject,
-  detectPackageManager,
-  runWizard,
-  scriptedPrompter,
-  ttyPrompter,
-  validateProjectName
-} from "./chunk-Z6RTS4I7.js";
-export {
-  FEATURES,
-  PRESETS,
-  TargetNotEmptyError,
-  WizardCancelledError,
-  createProject,
-  detectPackageManager,
-  runWizard,
-  scriptedPrompter,
-  ttyPrompter,
-  validateProjectName
-};
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { appTest, appTs, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
+import { uiFiles } from './templates-ui.js';
+export class TargetNotEmptyError extends Error {
+    constructor(dir) {
+        super(`Target directory "${dir}" already exists and is not empty.`);
+        this.name = 'TargetNotEmptyError';
+    }
+}
+/**
+ * Detects the package manager that invoked `npm create` / `npx`, via the
+ * `npm_config_user_agent` env var npm/pnpm/yarn/bun all set. Falls back to npm.
+ */
+export function detectPackageManager(userAgent = process.env['npm_config_user_agent']) {
+    const name = userAgent?.split(' ')[0]?.split('/')[0];
+    if (name === 'pnpm' || name === 'yarn' || name === 'bun')
+        return name;
+    return 'npm';
+}
+/** Generates a ready-to-run Basalt app. Does not install dependencies. */
+export async function createProject(input) {
+    const options = {
+        name: input.name,
+        tenancy: input.tenancy ?? true,
+        auth: input.auth ?? true,
+        billing: input.billing ?? false,
+        ui: input.ui ?? false,
+        cli: input.cli ?? false,
+        mcp: input.mcp ?? false,
+    };
+    const dir = resolve(input.dir ?? input.name);
+    const existing = await readdir(dir).catch(() => null);
+    if (existing && existing.length > 0)
+        throw new TargetNotEmptyError(dir);
+    const files = {
+        'package.json': packageJson(options),
+        'tsconfig.json': tsconfigJson(),
+        '.env.example': envExample(options),
+        '.gitignore': gitignore(),
+        'README.md': readme(options),
+        'pnpm-workspace.yaml': pnpmWorkspaceYaml(options),
+        'src/env.ts': envTs(options),
+        'src/app.ts': appTs(options),
+        'src/routes.ts': routesTs(options),
+        'src/server.ts': serverTs(),
+        'tests/app.test.ts': appTest(options),
+        ...(options.cli ? { 'bin/basalt.ts': basaltBin() } : {}),
+        ...(options.mcp ? { '.mcp.json': mcpJson(options) } : {}),
+        ...(options.ui ? uiFiles(options) : {}),
+    };
+    for (const [path, content] of Object.entries(files)) {
+        const target = join(dir, path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+    }
+    return { dir, files: Object.keys(files).sort(), options };
+}
+export { runWizard, validateProjectName, PRESETS, FEATURES } from './wizard.js';
+export { ttyPrompter, scriptedPrompter, WizardCancelledError } from './prompt.js';

package/dist/prompt.d.ts

@@ -0,0 +1,57 @@
+/** A selectable option. `value` is returned; `label`/`hint` are shown. */
+export 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.
+ */
+export 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). */
+export 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.
+ */
+export 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.
+ */
+export declare function scriptedPrompter(script: {
+    text?: string[];
+    select?: unknown[];
+    multiselect?: unknown[][];
+    confirm?: boolean[];
+}): Prompter & {
+    log: string[];
+};