create-basalt 1.4.1 → 1.5.0

package/README.md

@@ -30,7 +30,7 @@ yarn create basalt my-app
 bun create basalt my-app
 ```
 
-> Requirements: Node.js 18+ and a package manager. Projects with `--ui` require **pnpm** (explained below).
+> Requirements: Node.js 22.5+ and a package manager. Projects with `--ui` require **pnpm** (explained below).
 
 ## Get started in 5 minutes
 
@@ -93,6 +93,7 @@ Usage: npm create basalt <name> [options]
 | `--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") |
+| `--offline` | off | Don't query the npm registry for the latest versions; use the ranges bundled with this create-basalt release |
 | `--pm=<manager>` | autodetect | Package manager: `pnpm` \| `npm` \| `yarn` \| `bun` |
 | `-y`, `--yes` | — | Skips the questions and accepts the defaults |
 | `-h`, `--help` | — | Shows help and exits |
@@ -102,6 +103,7 @@ 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 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).
+- **Latest dependency versions**: before writing files, the CLI asks the npm registry (`npm_config_registry` when set by your package manager, else `registry.npmjs.org`) for the `latest` version of every dependency the project will contain and writes `^<latest>`. `@basaltkit/*` packages always take the latest release. Third-party packages (TypeScript, Vitest, React, Vite, Tailwind, …) take the latest only on the major the templates are written for — a newer major keeps the bundled range and prints a `Note:`. If the registry can't be reached (offline, timeout), the bundled ranges are used with one `Warning:` line; the scaffold never fails because of the registry. `--offline` skips the lookup entirely.
 - **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.
 
@@ -144,7 +146,7 @@ my-app/
 └── tests/app.test.ts     # smoke test adapted to the options
 ```
 
-With `--cli`, adds `bin/basalt.ts` and the `"basalt": "tsx bin/basalt.ts"` script. With `--ui`, adds the `web/` folder (Vite + React + Tailwind + shadcn, with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
+With `--cli`, adds `bin/basalt.ts` and the `"basalt": "tsx bin/basalt.ts"` script. With `--ui`, adds the `web/` folder (Vite 8 + React 19 + Tailwind CSS 4 via `@tailwindcss/vite` + shadcn — Tailwind is configured in `web/src/index.css`, no `tailwind.config.js`/PostCSS — with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
 
 ### With `--ui`: running the API and frontend
 
@@ -185,7 +187,7 @@ console.log(result.files)   // relative paths, sorted
 console.log(detectPackageManager()) // 'pnpm' | 'npm' | 'yarn' | 'bun'
 ```
 
-Note: `createProject` **only writes files** — it doesn't install dependencies or initialize git (that's the executable's job, with `--install`/`--git`).
+Note: `createProject` **only writes files** — it doesn't install dependencies or initialize git (that's the executable's job, with `--install`/`--git`). It also uses the bundled dependency ranges unless you pass `resolveLatest: true` (what the executable does), so a script never touches the network by surprise.
 
 ## API reference
 
@@ -205,6 +207,8 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | `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` |
+| `resolveLatest` | `boolean` | No | `false` | Resolve every dependency to `^<latest>` from the npm registry before writing (falls back to the bundled ranges on any registry failure) |
+| `registry` | `ResolveLatestOptions` | No | — | `{ fetch?, registry?, timeoutMs?, overallTimeoutMs?, concurrency? }` — injectable fetch (tests), registry URL (default `npm_config_registry` or `https://registry.npmjs.org`), timeouts (5 s per request, 15 s overall) |
 
 `CreateProjectResult`:
 
@@ -213,6 +217,7 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | `dir` | `string` | Absolute path of the created folder |
 | `files` | `string[]` | Files written (relative, sorted) |
 | `options` | `ProjectOptions` | The options actually applied (with defaults resolved) |
+| `versions` | `VersionResolution \| undefined` | With `resolveLatest`: `{ versions, resolved, failed, heldBack, registry }` — the final ranges, which packages got `^<latest>`, which kept the fallback after a registry failure, and third-party packages held back because their latest is a new major |
 
 Throws `TargetNotEmptyError` if the destination folder exists and isn't empty.
 

package/dist/args.d.ts

@@ -0,0 +1,21 @@
+import type { PackageManager } from './index.js';
+export declare const USAGE = "Usage: npm create basalt <name> [options]\n\nOptions:\n  --dir=<path>    Target directory (default: ./<name>)\n  --no-tenancy    Skip multi-tenancy\n  --no-auth       Skip authentication\n  --billing       Include subscriptions/billing\n  --ui            Scaffold a web/ frontend (React + shadcn + SDK)\n  --cli           Scaffold the 'basalt' CLI (code generators + commands)\n  --mcp           Expose read-only routes as MCP tools at /mcp\n  --install       Install dependencies (default: yes in an interactive\n                  terminal, skipped in CI/non-TTY; --no-install to opt out)\n  --no-install    Never install dependencies\n  --git           Initialize a git repository with a first commit\n                  (same default rule as --install; --no-git to opt out)\n  --no-git        Never initialize a git repository\n  --offline       Don't query the npm registry for the latest versions;\n                  use the ranges bundled with this create-basalt release\n  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)\n  -y, --yes       Skip prompts and accept defaults\n  -h, --help      Show this help\n\nRun with no name in a terminal to be prompted interactively.\n";
+export interface Flags {
+    name?: string;
+    dir?: string;
+    tenancy: boolean;
+    auth: boolean;
+    billing: boolean;
+    ui: boolean;
+    cli: boolean;
+    mcp: boolean;
+    /** Tri-state: undefined = decide from the environment (TTY yes, CI no). */
+    install?: boolean;
+    git?: boolean;
+    yes: boolean;
+    offline: boolean;
+    pm?: PackageManager;
+}
+export declare function parseArgs(argv: string[]): Flags;
+/** Whether the scaffold should query the registry for the latest versions. */
+export declare const resolvesLatest: (flags: Pick<Flags, 'offline'>) => boolean;

package/dist/args.js

@@ -0,0 +1,76 @@
+import { stdout } from 'node:process';
+export const USAGE = `Usage: npm create basalt <name> [options]
+
+Options:
+  --dir=<path>    Target directory (default: ./<name>)
+  --no-tenancy    Skip multi-tenancy
+  --no-auth       Skip authentication
+  --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 (default: yes in an interactive
+                  terminal, skipped in CI/non-TTY; --no-install to opt out)
+  --no-install    Never install dependencies
+  --git           Initialize a git repository with a first commit
+                  (same default rule as --install; --no-git to opt out)
+  --no-git        Never initialize a git repository
+  --offline       Don't query the npm registry for the latest versions;
+                  use the ranges bundled with this create-basalt release
+  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)
+  -y, --yes       Skip prompts and accept defaults
+  -h, --help      Show this help
+
+Run with no name in a terminal to be prompted interactively.
+`;
+export function parseArgs(argv) {
+    const flags = {
+        tenancy: true,
+        auth: true,
+        billing: false,
+        ui: false,
+        cli: false,
+        mcp: false,
+        yes: false,
+        offline: 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 === '--no-install')
+            flags.install = false;
+        else if (token === '--git')
+            flags.git = true;
+        else if (token === '--no-git')
+            flags.git = false;
+        else if (token === '-y' || token === '--yes')
+            flags.yes = true;
+        else if (token === '--offline')
+            flags.offline = 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;
+}
+/** Whether the scaffold should query the registry for the latest versions. */
+export const resolvesLatest = (flags) => !flags.offline;

package/dist/cli.js

@@ -1,75 +1,8 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { stdin, stdout } from 'node:process';
-import { createProject, detectPackageManager, resolveRunDefaults, runWizard, ttyPrompter, TargetNotEmptyError, WizardCancelledError, } from './index.js';
-const USAGE = `Usage: npm create basalt <name> [options]
-
-Options:
-  --dir=<path>    Target directory (default: ./<name>)
-  --no-tenancy    Skip multi-tenancy
-  --no-auth       Skip authentication
-  --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 (default: yes in an interactive
-                  terminal, skipped in CI/non-TTY; --no-install to opt out)
-  --no-install    Never install dependencies
-  --git           Initialize a git repository with a first commit
-                  (same default rule as --install; --no-git to opt out)
-  --no-git        Never initialize a git repository
-  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)
-  -y, --yes       Skip prompts and accept defaults
-  -h, --help      Show this help
-
-Run with no name in a terminal to be prompted interactively.
-`;
-function parseArgs(argv) {
-    const flags = {
-        tenancy: true,
-        auth: true,
-        billing: false,
-        ui: false,
-        cli: false,
-        mcp: 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 === '--no-install')
-            flags.install = false;
-        else if (token === '--git')
-            flags.git = true;
-        else if (token === '--no-git')
-            flags.git = false;
-        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;
-}
+import { createProject, describeResolution, detectPackageManager, resolveRunDefaults, runWizard, ttyPrompter, TargetNotEmptyError, WizardCancelledError, } from './index.js';
+import { parseArgs, resolvesLatest, USAGE } from './args.js';
 /** Runs a command inheriting stdio; resolves false on non-zero exit (never throws). */
 function run(command, args, cwd) {
     return new Promise((resolve) => {
@@ -124,6 +57,8 @@ if (flags.ui && pm !== 'pnpm') {
     pm = 'pnpm';
 }
 try {
+    if (resolvesLatest(flags))
+        console.log('Resolving the latest published dependency versions…');
     const result = await createProject({
         name: flags.name,
         ...(flags.dir ? { dir: flags.dir } : {}),
@@ -133,10 +68,21 @@ try {
         ui: flags.ui,
         cli: flags.cli,
         mcp: flags.mcp,
+        // New apps get the latest published version of every dependency (with the
+        // bundled ranges as an offline fallback); --offline skips the registry.
+        resolveLatest: resolvesLatest(flags),
     });
     console.log(`\nCreated ${result.options.name} in ${result.dir}\n`);
     for (const file of result.files)
         console.log(`  ${file}`);
+    if (result.versions) {
+        const lines = describeResolution(result.versions);
+        if (lines.length > 0)
+            console.log(`\n${lines.join('\n')}`);
+    }
+    else {
+        console.log('\n--offline: used the dependency ranges bundled with this create-basalt release.');
+    }
     const run_ = resolveRunDefaults({
         install: flags.install,
         git: flags.git,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { type ProjectOptions } from './templates.js';
+import { type ResolveLatestOptions, type VersionResolution } from './latest-versions.js';
 export type { ProjectOptions } from './templates.js';
 export interface CreateProjectInput {
     name: string;
@@ -13,11 +14,22 @@ export interface CreateProjectInput {
     cli?: boolean;
     /** Expose opted-in routes as MCP tools over HTTP at `/mcp`. Default: false. */
     mcp?: boolean;
+    /**
+     * Resolve every dependency to its latest published version (npm registry)
+     * before writing files. Default: false — the embedded fallback ranges are
+     * used and no network is touched. The `create-basalt` CLI turns it on
+     * (unless `--offline`). Registry failures never fail the scaffold.
+     */
+    resolveLatest?: boolean;
+    /** Registry options for `resolveLatest` (injectable fetch, registry, timeouts). */
+    registry?: ResolveLatestOptions;
 }
 export interface CreateProjectResult {
     dir: string;
     files: string[];
     options: ProjectOptions;
+    /** How dependency versions were resolved — present only with `resolveLatest`. */
+    versions?: VersionResolution;
 }
 export declare class TargetNotEmptyError extends Error {
     constructor(dir: string);
@@ -48,5 +60,6 @@ export declare function resolveRunDefaults(input: {
 };
 /** Generates a ready-to-run Basalt app. Does not install dependencies. */
 export declare function createProject(input: CreateProjectInput): Promise<CreateProjectResult>;
+export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, describeResolution, resolveLatestVersions, registryUrl, type HeldBackVersion, type ResolveLatestOptions, type VersionResolution, } from './latest-versions.js';
 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,7 +1,8 @@
 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 { appTest, appTs, devTs, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
 import { uiFiles } from './templates-ui.js';
+import { applyVersions, collectDependencies, resolveLatestVersions, } from './latest-versions.js';
 export class TargetNotEmptyError extends Error {
     constructor(dir) {
         super(`Target directory "${dir}" already exists and is not empty.`);
@@ -54,23 +55,33 @@ export async function createProject(input) {
         'tsconfig.json': tsconfigJson(),
         '.env.example': envExample(options),
         '.gitignore': gitignore(),
+        '.dockerignore': dockerignore(),
         '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(),
+        'src/dev.ts': devTs(),
         'tests/app.test.ts': appTest(options),
         ...(options.cli ? { 'bin/basalt.ts': basaltBin() } : {}),
         ...(options.mcp ? { '.mcp.json': mcpJson(options) } : {}),
         ...(options.ui ? uiFiles(options) : {}),
     };
+    let versions;
+    if (input.resolveLatest) {
+        const manifests = Object.keys(files).filter((path) => path === 'package.json' || path.endsWith('/package.json'));
+        versions = await resolveLatestVersions(collectDependencies(manifests.map((path) => files[path])), input.registry);
+        for (const path of manifests)
+            files[path] = applyVersions(files[path], versions.versions);
+    }
     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 };
+    return { dir, files: Object.keys(files).sort(), options, ...(versions ? { versions } : {}) };
 }
+export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, describeResolution, resolveLatestVersions, registryUrl, } from './latest-versions.js';
 export { runWizard, validateProjectName, PRESETS, FEATURES } from './wizard.js';
 export { ttyPrompter, scriptedPrompter, WizardCancelledError } from './prompt.js';

package/dist/latest-versions.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Scaffold-time dependency resolution: a freshly generated app should depend on
+ * the LATEST PUBLISHED version of every package, not on the ranges that were
+ * current the day this create-basalt release was built.
+ *
+ * - `@basaltkit/*` packages always take the registry's `latest` dist-tag — the
+ *   framework's own release line is the whole point of the scaffold.
+ * - Third-party packages take `latest` only while it stays on the major the
+ *   templates are written for (the major of the fallback range in
+ *   {@link THIRD_PARTY_VERSIONS}). A new breaking major keeps the fallback range
+ *   and is reported as a notice, so it can never silently produce a broken app.
+ * - Any registry failure (offline, timeout, non-2xx, malformed JSON, a bogus
+ *   version string) keeps the embedded fallback range. The registry never fails
+ *   a scaffold.
+ */
+/**
+ * Fallback ranges for every third-party package the templates emit (API +
+ * web UI). The major of each range is also the TEMPLATE-COMPATIBLE major: the
+ * generated code is written for it, and `latest` is accepted only on that
+ * major. Bump a range to a new major only together with the templates.
+ */
+export declare const THIRD_PARTY_VERSIONS: Readonly<Record<string, string>>;
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+/** Packages whose latest is always taken, regardless of major. */
+export declare const alwaysLatest: (name: string) => boolean;
+/** The major the templates are written for, derived from the fallback range. */
+export declare function compatibleMajor(fallbackRange: string): number | undefined;
+export interface HeldBackVersion {
+    name: string;
+    /** The registry's latest version (a new major the templates don't target). */
+    latest: string;
+    /** The range kept instead. */
+    range: string;
+}
+export interface VersionResolution {
+    /** Final range per package name (resolved or fallback). */
+    versions: Record<string, string>;
+    /** Packages set to `^<latest>` from the registry. */
+    resolved: string[];
+    /** Packages that kept their fallback range because the registry failed. */
+    failed: string[];
+    /** Third-party packages whose latest is a new major — fallback kept. */
+    heldBack: HeldBackVersion[];
+    /** Registry actually queried. */
+    registry: string;
+}
+export interface ResolveLatestOptions {
+    /** Injectable fetch (tests). Default: the global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Registry base URL. Default: `npm_config_registry`, else the public npm registry. */
+    registry?: string;
+    /** Per-request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+    /** Cap on the whole resolution in ms. Default 15000. */
+    overallTimeoutMs?: number;
+    /** Requests in flight at once. Default 8. */
+    concurrency?: number;
+}
+/**
+ * The registry to query: an explicit option, else `npm_config_registry` (npm
+ * and pnpm export it to `create` binaries, so a private mirror is honored),
+ * else the public registry. Trailing slashes are normalized; anything that is
+ * not an http(s) URL falls back to the default.
+ */
+export declare function registryUrl(explicit?: string, env?: NodeJS.ProcessEnv): string;
+/** `<registry>/<name>/latest`, with a scoped name's `/` encoded as `%2f`. */
+export declare const latestUrl: (registry: string, name: string) => string;
+/**
+ * Resolves the latest published version of every package in `fallbacks`
+ * (name → fallback range) through a small pool of parallel requests. Never throws: a package the registry
+ * cannot answer for keeps its fallback range and is listed in `failed`.
+ */
+export declare function resolveLatestVersions(fallbacks: Readonly<Record<string, string>>, options?: ResolveLatestOptions): Promise<VersionResolution>;
+/**
+ * Rewrites the dependency ranges of a generated package.json with the
+ * resolved versions (keys, order and every other field untouched).
+ */
+export declare function applyVersions(packageJsonText: string, versions: Readonly<Record<string, string>>): string;
+/** Every dependency/devDependency name → range declared in the given package.json texts. */
+export declare function collectDependencies(packageJsonTexts: readonly string[]): Record<string, string>;
+/** Human-readable lines summarizing a resolution (for the CLI). */
+export declare function describeResolution(resolution: VersionResolution): string[];

package/dist/latest-versions.js

@@ -0,0 +1,209 @@
+/**
+ * Scaffold-time dependency resolution: a freshly generated app should depend on
+ * the LATEST PUBLISHED version of every package, not on the ranges that were
+ * current the day this create-basalt release was built.
+ *
+ * - `@basaltkit/*` packages always take the registry's `latest` dist-tag — the
+ *   framework's own release line is the whole point of the scaffold.
+ * - Third-party packages take `latest` only while it stays on the major the
+ *   templates are written for (the major of the fallback range in
+ *   {@link THIRD_PARTY_VERSIONS}). A new breaking major keeps the fallback range
+ *   and is reported as a notice, so it can never silently produce a broken app.
+ * - Any registry failure (offline, timeout, non-2xx, malformed JSON, a bogus
+ *   version string) keeps the embedded fallback range. The registry never fails
+ *   a scaffold.
+ */
+/**
+ * Fallback ranges for every third-party package the templates emit (API +
+ * web UI). The major of each range is also the TEMPLATE-COMPATIBLE major: the
+ * generated code is written for it, and `latest` is accepted only on that
+ * major. Bump a range to a new major only together with the templates.
+ */
+export const THIRD_PARTY_VERSIONS = {
+    '@tailwindcss/vite': '^4.3.3',
+    '@types/node': '^26.6.2',
+    '@types/react': '^19.3.0',
+    '@types/react-dom': '^19.3.0',
+    '@vitejs/plugin-react': '^6.1.1',
+    'pino-pretty': '^13.1.3',
+    react: '^19.3.0',
+    'react-dom': '^19.3.0',
+    tailwindcss: '^4.3.3',
+    tsx: '^4.23.13',
+    typescript: '^7.0.2',
+    vite: '^8.3.0',
+    vitest: '^5.0.1',
+    zod: '^4.6.5',
+};
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const PER_REQUEST_TIMEOUT_MS = 5_000;
+const OVERALL_TIMEOUT_MS = 15_000;
+/**
+ * Requests in flight at once. A burst of ~35 simultaneous TLS handshakes to one
+ * host is markedly slower (and flakier) on poor links than a small pool that
+ * reuses keep-alive connections.
+ */
+const CONCURRENCY = 8;
+/** A stable `x.y.z` release (pre-releases and build metadata are refused). */
+const STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const CARET_RANGE = /^\^(0|[1-9]\d*)\.\d+\.\d+$/;
+/** Packages whose latest is always taken, regardless of major. */
+export const alwaysLatest = (name) => name.startsWith('@basaltkit/') || name === 'create-basalt';
+/** The major the templates are written for, derived from the fallback range. */
+export function compatibleMajor(fallbackRange) {
+    const match = CARET_RANGE.exec(fallbackRange);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * The registry to query: an explicit option, else `npm_config_registry` (npm
+ * and pnpm export it to `create` binaries, so a private mirror is honored),
+ * else the public registry. Trailing slashes are normalized; anything that is
+ * not an http(s) URL falls back to the default.
+ */
+export function registryUrl(explicit, env = process.env) {
+    const candidate = explicit ?? env['npm_config_registry'] ?? env['NPM_CONFIG_REGISTRY'];
+    if (!candidate)
+        return DEFAULT_REGISTRY;
+    try {
+        const url = new URL(candidate);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return DEFAULT_REGISTRY;
+    }
+    catch {
+        return DEFAULT_REGISTRY;
+    }
+    let end = candidate.length;
+    while (end > 0 && candidate[end - 1] === '/')
+        end--;
+    return candidate.slice(0, end);
+}
+/** `<registry>/<name>/latest`, with a scoped name's `/` encoded as `%2f`. */
+export const latestUrl = (registry, name) => `${registry}/${name.replaceAll('/', '%2f')}/latest`;
+async function lookupLatest(fetchImpl, registry, name, signal) {
+    try {
+        const response = await fetchImpl(latestUrl(registry, name), {
+            headers: { accept: 'application/json' },
+            signal,
+        });
+        if (response.status >= 500 || response.status === 429)
+            return 'transient';
+        if (!response.ok)
+            return 'miss';
+        const body = (await response.json());
+        const version = body?.version;
+        return typeof version === 'string' && STABLE_SEMVER.test(version) ? { version } : 'miss';
+    }
+    catch {
+        // Network error, per-request timeout, or malformed JSON.
+        return 'transient';
+    }
+}
+/**
+ * The latest stable version of `name`, or undefined. A transient failure
+ * (network error, timeout, 5xx/429) is retried once — on slow links the first
+ * wave of cold TLS handshakes is the part that times out, and the retry rides
+ * a warm keep-alive connection. The overall signal bounds both attempts.
+ */
+async function fetchLatest(fetchImpl, registry, name, timeoutMs, overall) {
+    for (let attempt = 0; attempt < 2 && !overall.aborted; attempt++) {
+        const result = await lookupLatest(fetchImpl, registry, name, AbortSignal.any([AbortSignal.timeout(timeoutMs), overall]));
+        if (result === 'miss')
+            return undefined;
+        if (result !== 'transient')
+            return result.version;
+    }
+    return undefined;
+}
+/**
+ * Resolves the latest published version of every package in `fallbacks`
+ * (name → fallback range) through a small pool of parallel requests. Never throws: a package the registry
+ * cannot answer for keeps its fallback range and is listed in `failed`.
+ */
+export async function resolveLatestVersions(fallbacks, options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const registry = registryUrl(options.registry);
+    const versions = { ...fallbacks };
+    const resolved = [];
+    const failed = [];
+    const heldBack = [];
+    const names = Object.keys(fallbacks).sort();
+    if (typeof fetchImpl !== 'function') {
+        return { versions, resolved, failed: names, heldBack, registry };
+    }
+    const overall = new AbortController();
+    const cap = setTimeout(() => overall.abort(), options.overallTimeoutMs ?? OVERALL_TIMEOUT_MS);
+    try {
+        const latest = [];
+        let next = 0;
+        const worker = async () => {
+            while (next < names.length) {
+                const i = next++;
+                latest[i] = await fetchLatest(fetchImpl, registry, names[i], options.timeoutMs ?? PER_REQUEST_TIMEOUT_MS, overall.signal);
+            }
+        };
+        const pool = Math.max(1, Math.min(options.concurrency ?? CONCURRENCY, names.length));
+        await Promise.all(Array.from({ length: pool }, worker));
+        names.forEach((name, i) => {
+            const version = latest[i];
+            const fallback = fallbacks[name];
+            if (version === undefined) {
+                failed.push(name);
+                return;
+            }
+            if (!alwaysLatest(name)) {
+                const major = compatibleMajor(fallback);
+                if (major === undefined || Number(version.split('.')[0]) !== major) {
+                    heldBack.push({ name, latest: version, range: fallback });
+                    return;
+                }
+            }
+            versions[name] = `^${version}`;
+            resolved.push(name);
+        });
+    }
+    finally {
+        clearTimeout(cap);
+    }
+    return { versions, resolved, failed, heldBack, registry };
+}
+/**
+ * Rewrites the dependency ranges of a generated package.json with the
+ * resolved versions (keys, order and every other field untouched).
+ */
+export function applyVersions(packageJsonText, versions) {
+    const pkg = JSON.parse(packageJsonText);
+    for (const field of ['dependencies', 'devDependencies']) {
+        const deps = pkg[field];
+        if (!deps)
+            continue;
+        for (const name of Object.keys(deps)) {
+            const range = versions[name];
+            if (range !== undefined)
+                deps[name] = range;
+        }
+    }
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+/** Every dependency/devDependency name → range declared in the given package.json texts. */
+export function collectDependencies(packageJsonTexts) {
+    const all = {};
+    for (const text of packageJsonTexts) {
+        const pkg = JSON.parse(text);
+        Object.assign(all, pkg.dependencies, pkg.devDependencies);
+    }
+    return all;
+}
+/** Human-readable lines summarizing a resolution (for the CLI). */
+export function describeResolution(resolution) {
+    const lines = [];
+    if (resolution.resolved.length > 0) {
+        lines.push(`Resolved ${resolution.resolved.length} dependencies to their latest published versions:`, `  ${resolution.resolved.map((name) => `${name}@${resolution.versions[name]}`).join(', ')}`);
+    }
+    for (const held of resolution.heldBack) {
+        lines.push(`Note: ${held.name} ${held.latest} is a new major this template does not target yet — kept ${held.range}.`);
+    }
+    if (resolution.failed.length > 0) {
+        lines.push(`Warning: could not reach ${resolution.registry} for ${resolution.failed.length} package(s) — used the bundled fallback ranges for: ${resolution.failed.join(', ')}.`);
+    }
+    return lines;
+}

package/dist/templates-ui.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectOptions } from './templates.js';
+import { type ProjectOptions } from './templates.js';
 /**
  * The `web/` frontend emitted when `--ui` is passed: a Vite + React app on
  * @basaltkit/admin-shadcn (authentic shadcn/ui components) talking to the API

package/dist/templates-ui.js

@@ -1,5 +1,4 @@
-/** Kept in sync with the monorepo release line (mirror of templates.ts). */
-const BASALT_VERSION = '^1.0.0';
+import { thirdPartyVersionOf, versionOf } from './templates.js';
 /**
  * The `web/` frontend emitted when `--ui` is passed: a Vite + React app on
  * @basaltkit/admin-shadcn (authentic shadcn/ui components) talking to the API
@@ -13,8 +12,6 @@ export function uiFiles(options) {
         'web/vite.config.ts': webViteConfig(),
         'web/tsconfig.json': webTsconfig(),
         'web/index.html': webIndexHtml(options),
-        'web/postcss.config.js': webPostcss(),
-        'web/tailwind.config.js': webTailwind(),
         'web/src/main.tsx': webMain(),
         'web/src/crypto-shim.ts': webCryptoShim(),
         'web/src/index.css': webCss(),
@@ -27,34 +24,38 @@ function webPackageJson(options) {
         name: `${options.name}-web`,
         private: true,
         type: 'module',
-        scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview' },
+        scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview', typecheck: 'tsc --noEmit' },
         dependencies: {
-            '@basaltkit/admin': BASALT_VERSION,
-            '@basaltkit/admin-shadcn': BASALT_VERSION,
-            '@basaltkit/sdk': BASALT_VERSION,
-            react: '^18.3.1',
-            'react-dom': '^18.3.1',
-            zod: '^3.24.0',
-        },
-        devDependencies: {
-            '@types/react': '^18.3.0',
-            '@types/react-dom': '^18.3.0',
-            '@vitejs/plugin-react': '^4.3.0',
-            autoprefixer: '^10.4.0',
-            postcss: '^8.4.0',
-            tailwindcss: '^3.4.0',
-            typescript: '^5.8.0',
-            vite: '^6.0.0',
+            '@basaltkit/admin': versionOf('@basaltkit/admin'),
+            '@basaltkit/admin-shadcn': versionOf('@basaltkit/admin-shadcn'),
+            '@basaltkit/sdk': versionOf('@basaltkit/sdk'),
+            react: thirdPartyVersionOf('react'),
+            'react-dom': thirdPartyVersionOf('react-dom'),
+            // Matches the peer every @basaltkit package declares (zod 4).
+            zod: thirdPartyVersionOf('zod'),
         },
+        // Tailwind 4 runs as a Vite plugin (@tailwindcss/vite) — no PostCSS or
+        // autoprefixer config; the theme lives in src/index.css.
+        devDependencies: Object.fromEntries([
+            '@tailwindcss/vite',
+            '@types/node',
+            '@types/react',
+            '@types/react-dom',
+            '@vitejs/plugin-react',
+            'tailwindcss',
+            'typescript',
+            'vite',
+        ].map((pkg) => [pkg, thirdPartyVersionOf(pkg)])),
     }, null, 2)}\n`;
 }
 function webViteConfig() {
     return `import { fileURLToPath } from 'node:url'
+import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
-  plugins: [react()],
+  plugins: [react(), tailwindcss()],
   resolve: {
     alias: {
       // @basaltkit/admin uses randomUUID from crypto; map it to Web Crypto in the browser.
@@ -89,7 +90,9 @@ function webTsconfig() {
             noEmit: true,
             allowImportingTsExtensions: true,
             verbatimModuleSyntax: true,
-            types: ['node'],
+            // vite/client types the CSS/asset imports (TS 6+ checks side-effect
+            // imports such as `import './index.css'`) and import.meta.env.
+            types: ['node', 'vite/client'],
         },
         include: ['src'],
     }, null, 2)}\n`;
@@ -109,41 +112,6 @@ function webIndexHtml(options) {
 </html>
 `;
 }
-function webPostcss() {
-    return `export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}
-`;
-}
-function webTailwind() {
-    return `export default {
-  darkMode: ['class'],
-  content: ['./index.html', './src/**/*.{ts,tsx}', './node_modules/@basaltkit/admin-shadcn/dist/**/*.js'],
-  theme: {
-    extend: {
-      colors: {
-        border: 'hsl(var(--border))',
-        input: 'hsl(var(--input))',
-        ring: 'hsl(var(--ring))',
-        background: 'hsl(var(--background))',
-        foreground: 'hsl(var(--foreground))',
-        primary: { DEFAULT: 'hsl(var(--primary))', foreground: 'hsl(var(--primary-foreground))' },
-        secondary: { DEFAULT: 'hsl(var(--secondary))', foreground: 'hsl(var(--secondary-foreground))' },
-        destructive: { DEFAULT: 'hsl(var(--destructive))', foreground: 'hsl(var(--destructive-foreground))' },
-        muted: { DEFAULT: 'hsl(var(--muted))', foreground: 'hsl(var(--muted-foreground))' },
-        accent: { DEFAULT: 'hsl(var(--accent))', foreground: 'hsl(var(--accent-foreground))' },
-        card: { DEFAULT: 'hsl(var(--card))', foreground: 'hsl(var(--card-foreground))' },
-      },
-      borderRadius: { lg: 'var(--radius)', md: 'calc(var(--radius) - 2px)', sm: 'calc(var(--radius) - 4px)' },
-    },
-  },
-  plugins: [],
-}
-`;
-}
 function webMain() {
     return `import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
@@ -162,9 +130,39 @@ function webCryptoShim() {
 `;
 }
 function webCss() {
-    return `@tailwind base;
-@tailwind components;
-@tailwind utilities;
+    return `@import 'tailwindcss';
+
+/* @basaltkit/admin-shadcn ships precompiled components: let Tailwind scan them
+   (paths are relative to this file, so ../node_modules is web/node_modules). */
+@source '../node_modules/@basaltkit/admin-shadcn/dist';
+
+/* Class-based dark mode: <html class="dark"> (the theme toggle sets it). */
+@custom-variant dark (&:is(.dark *));
+
+/* shadcn/ui tokens → Tailwind utilities (bg-primary, text-muted-foreground,
+   border-input, rounded-lg, …). The values are the CSS variables below. */
+@theme inline {
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+}
 
 @layer base {
   :root {
@@ -206,9 +204,19 @@ function webCss() {
     --input: 240 3.7% 18%;
     --ring: 243 75% 68%;
   }
-  * {
+  /* Tailwind 4 defaults borders to currentColor; keep the themed border. */
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
     border-color: hsl(var(--border));
   }
+  /* Tailwind 4 dropped the pointer cursor on buttons; keep it. */
+  button:not(:disabled),
+  [role='button']:not(:disabled) {
+    cursor: pointer;
+  }
   body {
     margin: 0;
     background-color: hsl(var(--background));

package/dist/templates.d.ts

@@ -10,8 +10,24 @@ export interface ProjectOptions {
     /** Expose opted-in routes as MCP tools (@basaltkit/mcp) over HTTP at `/mcp`. */
     mcp: boolean;
 }
-/** The dependency range for a @basalt package (override, else the base line). */
+export { SCAFFOLD_VERSIONS } from './versions.js';
+export { THIRD_PARTY_VERSIONS } from './latest-versions.js';
+/**
+ * The dependency range for a @basaltkit/* package: the current release line
+ * (`^<major>.<minor>.0`) of its workspace version, from the generated
+ * {@link SCAFFOLD_VERSIONS} map. Throws for an unknown package rather than
+ * guessing a range — a stale guess once pinned new apps to frozen 1.x lines.
+ */
 export declare const versionOf: (pkg: string) => string;
+/**
+ * The fallback range for a third-party package the templates emit, from
+ * {@link THIRD_PARTY_VERSIONS}. At scaffold time the CLI replaces it with
+ * `^<latest>` when the registry's latest is on the same major. Throws for an
+ * unknown package so every emitted range lives in that single table.
+ */
+export declare const thirdPartyVersionOf: (pkg: string) => string;
+/** True when the scaffold binds users to the tenant they act on (tenancy + auth). */
+export declare const enforcesMembership: (options: ProjectOptions) => boolean;
 export declare function packageJson(options: ProjectOptions): string;
 export declare function tsconfigJson(): string;
 export declare function envTs(options: ProjectOptions): string;
@@ -19,6 +35,13 @@ export declare function envExample(options: ProjectOptions): string;
 export declare function appTs(options: ProjectOptions): string;
 export declare function routesTs(options: ProjectOptions): string;
 export declare function serverTs(): string;
+/**
+ * `pnpm dev` entrypoint. Opts into NODE_ENV=development (dev secret defaults,
+ * pretty logs) unless NODE_ENV is already set, then starts the server. Kept out
+ * of server.ts on purpose: `pnpm start` runs server.ts directly, where an unset
+ * NODE_ENV counts as production and secrets are required (fail-closed).
+ */
+export declare function devTs(): string;
 export declare function basaltBin(): string;
 export declare function appTest(options: ProjectOptions): string;
 export declare function readme(options: ProjectOptions): string;
@@ -28,6 +51,14 @@ export declare function readme(options: ProjectOptions): string;
  * project root automatically; Claude Desktop uses the same server entry.
  */
 export declare function mcpJson(_options: ProjectOptions): string;
+/**
+ * Keeps secrets and local state out of Docker build contexts, so a
+ * `COPY . .` can never bake `.env` or private keys into an image layer. Every
+ * rule is `**`-prefixed: .dockerignore patterns are anchored at the context
+ * root, so a bare `.env` or `*.pem` would still let `prisma/.env` or
+ * `certs/server.key` through.
+ */
+export declare function dockerignore(): string;
 export declare function gitignore(): string;
 /**
  * pnpm settings: esbuild's build script is required by tsx;

package/dist/templates.js

@@ -1,55 +1,63 @@
-/** Base release line for @basaltkit/* deps. */
-const BASALT_VERSION = '^1.0.0';
+import { THIRD_PARTY_VERSIONS } from './latest-versions.js';
+import { SCAFFOLD_VERSIONS } from './versions.js';
+export { SCAFFOLD_VERSIONS } from './versions.js';
+export { THIRD_PARTY_VERSIONS } from './latest-versions.js';
 /**
- * Per-package range overrides. In semver 0.x, `^0.4.0` locks the minor, so a
- * package that advances past the base line needs its own range or a fresh app
- * can't install it. Add an entry when a package crosses a minor.
+ * The dependency range for a @basaltkit/* package: the current release line
+ * (`^<major>.<minor>.0`) of its workspace version, from the generated
+ * {@link SCAFFOLD_VERSIONS} map. Throws for an unknown package rather than
+ * guessing a range — a stale guess once pinned new apps to frozen 1.x lines.
  */
-const VERSIONS = {
-    // ai-mcp is on the 0.x line (published separately from the 1.x framework base).
-    '@basaltkit/ai-mcp': '^0.1.0',
+export const versionOf = (pkg) => {
+    const range = SCAFFOLD_VERSIONS[pkg];
+    if (range === undefined) {
+        throw new Error(`create-basalt: no release line for ${pkg} — add it to scripts/sync-versions.mjs.`);
+    }
+    return range;
 };
-/** The dependency range for a @basalt package (override, else the base line). */
-export const versionOf = (pkg) => VERSIONS[pkg] ?? BASALT_VERSION;
+/**
+ * The fallback range for a third-party package the templates emit, from
+ * {@link THIRD_PARTY_VERSIONS}. At scaffold time the CLI replaces it with
+ * `^<latest>` when the registry's latest is on the same major. Throws for an
+ * unknown package so every emitted range lives in that single table.
+ */
+export const thirdPartyVersionOf = (pkg) => {
+    const range = THIRD_PARTY_VERSIONS[pkg];
+    if (range === undefined) {
+        throw new Error(`create-basalt: no fallback range for ${pkg} — add it to THIRD_PARTY_VERSIONS.`);
+    }
+    return range;
+};
+/** True when the scaffold binds users to the tenant they act on (tenancy + auth). */
+export const enforcesMembership = (options) => options.tenancy && options.auth;
 export function packageJson(options) {
-    const dependencies = {
-        '@basaltkit/config': BASALT_VERSION,
-        '@basaltkit/core': BASALT_VERSION,
-        '@basaltkit/env': BASALT_VERSION,
-        '@basaltkit/events': BASALT_VERSION,
-        '@basaltkit/fastify': BASALT_VERSION,
-        '@basaltkit/logger': BASALT_VERSION,
-        zod: '^4.0.0',
-    };
+    const basalt = ['@basaltkit/config', '@basaltkit/core', '@basaltkit/env', '@basaltkit/events', '@basaltkit/fastify', '@basaltkit/logger'];
     if (options.tenancy)
-        dependencies['@basaltkit/tenancy'] = BASALT_VERSION;
+        basalt.push('@basaltkit/tenancy');
     if (options.auth)
-        dependencies['@basaltkit/auth'] = BASALT_VERSION;
+        basalt.push('@basaltkit/auth');
+    // Tenancy + auth: @basaltkit/teams binds each user to the tenants they belong
+    // to (tenantMembershipPlugin) — without it x-tenant-id/Host is a free choice.
+    if (enforcesMembership(options))
+        basalt.push('@basaltkit/teams');
     if (options.billing)
-        dependencies['@basaltkit/subscriptions'] = BASALT_VERSION;
+        basalt.push('@basaltkit/subscriptions');
     if (options.mcp)
-        dependencies['@basaltkit/mcp'] = BASALT_VERSION;
+        basalt.push('@basaltkit/mcp');
     if (options.cli) {
         // Runtime deps: app.ts uses commandsPlugin (@basaltkit/cli); prisma powers
         // prismaPlugin + `basalt prisma:sync`. @basaltkit/generator is dev-only (below).
-        dependencies['@basaltkit/cli'] = BASALT_VERSION;
-        dependencies['@basaltkit/prisma'] = BASALT_VERSION;
-    }
-    // Apply per-package range overrides. Only @basaltkit/* packages: versionOf
-    // falls back to BASALT_VERSION, which would clobber third-party ranges
-    // (this once rewrote zod's range to the @basalt base line).
-    for (const pkg of Object.keys(dependencies)) {
-        if (pkg.startsWith('@basaltkit/'))
-            dependencies[pkg] = versionOf(pkg);
+        basalt.push('@basaltkit/cli', '@basaltkit/prisma');
     }
+    const dependencies = { zod: thirdPartyVersionOf('zod') };
+    for (const pkg of basalt)
+        dependencies[pkg] = versionOf(pkg);
     const devDependencies = {
         '@basaltkit/testing': versionOf('@basaltkit/testing'),
-        '@types/node': '^22.15.0',
-        'pino-pretty': '^13.0.0',
-        tsx: '^4.19.0',
-        typescript: '^5.8.0',
-        vitest: '^3.1.0',
     };
+    for (const pkg of ['@types/node', 'pino-pretty', 'tsx', 'typescript', 'vitest']) {
+        devDependencies[pkg] = thirdPartyVersionOf(pkg);
+    }
     if (options.cli) {
         // Dev-only: only bin/basalt.ts imports the code generator — the runtime server
         // never does, so the app runs completely without the codegen/AI layer.
@@ -67,7 +75,9 @@ export function packageJson(options) {
         private: true,
         type: 'module',
         scripts: {
-            dev: 'tsx watch src/server.ts',
+            // dev opts into NODE_ENV=development (src/dev.ts); start does not, so an
+            // unset NODE_ENV counts as production and secrets are required.
+            dev: 'tsx watch src/dev.ts',
             start: 'tsx src/server.ts',
             test: 'vitest run',
             typecheck: 'tsc --noEmit',
@@ -104,10 +114,12 @@ export const env = defineEnv({
   // Typed against the logger's LogLevel union — a free-form string here fails
   // \`pnpm typecheck\` where loggerPlugin({ level }) consumes it.
   LOG_LEVEL: z.enum(LOG_LEVELS).default('info'),
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),${options.auth
+  // Unset counts as production (fail-closed); \`pnpm dev\` sets development.
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),${options.auth
         ? `
-  // Signs JWTs and sessions. secret() is fail-closed: required in production
-  // (no fallback), rejected if it looks like a placeholder. Dev uses devDefault.
+  // Signs JWTs and sessions. secret() is fail-closed: required unless NODE_ENV
+  // is explicitly development/test (no fallback when NODE_ENV is unset),
+  // rejected if it looks like a placeholder. \`pnpm dev\` uses devDefault.
   APP_SECRET: secret({ minLength: 32, devDefault: 'dev-only-insecure-secret-please-change-me' }),`
         : ''}
 })
@@ -118,7 +130,7 @@ export function envExample(options) {
 HOST=0.0.0.0
 LOG_LEVEL=info
 NODE_ENV=development
-${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' : ''}`;
+${options.auth ? '# Required unless NODE_ENV is development/test — `pnpm start` refuses to boot\n# without it. Generate a strong one:  openssl rand -base64 48\n# APP_SECRET=\n' : ''}`;
 }
 export function appTs(options) {
     const imports = [
@@ -134,8 +146,11 @@ export function appTs(options) {
         `eventsPlugin()`,
         `securityPlugin({
       // Secure response headers (HSTS, X-Frame-Options, nosniff, …) are on by
-      // default. Turn on rate limiting and a CORS allow-list for production:
-      // rateLimit: { limit: 120, windowMs: 60_000 },
+      // default, and so is a global per-IP rate limit (auth routes add their
+      // own stricter budget). Behind a proxy, make the adapter set request.ip
+      // from it; with several replicas, pass a shared \`store\`.
+      rateLimit: { limit: 120, windowMs: 60_000 },
+      // Add a CORS allow-list if a browser app on another origin calls the API:
       // cors: { origin: ['https://app.example.com'], credentials: true },
     })`,
     ];
@@ -162,6 +177,25 @@ export function appTs(options) {
         // password recovery. mfaRoutes(): TOTP enroll/activate/status/disable.
         routesExpression = '[...appRoutes, ...authRoutes(), ...mfaRoutes()]';
     }
+    if (enforcesMembership(options)) {
+        // Secure by default: the tenant comes from client input (x-tenant-id / Host),
+        // so it is identification, never authorization. tenantMembershipPlugin()
+        // rejects (403) every authenticated request for a tenant the user is not a
+        // member of. Routes that act outside a single tenant opt out with
+        // meta: { central: true }.
+        imports[0] = `import { createApp, definePlugin } from '@basaltkit/core'`;
+        imports.push(`import { TEAMS, teamsPlugin, tenantMembershipPlugin } from '@basaltkit/teams'`);
+        plugins.push(`teamsPlugin({
+      // TODO: the default membership/invitation stores are in-memory — pass
+      // persistent ones (memberships, invitations) before production.
+    })`);
+        plugins.push(`// Rejects authenticated requests for a tenant the user is not a member of.
+      tenantMembershipPlugin()`);
+        plugins.push(`// Dev-only seed: each new registrant joins the 'demo' tenant so the scaffold
+      // works out of the box. Never in production — add members explicitly there
+      // (on tenant creation, or via TEAMS invite()/accept()).
+      ...(env.NODE_ENV === 'production' ? [] : [demoMembershipSeed()])`);
+    }
     if (options.billing) {
         imports.push(`import { definePlans, subscriptionsPlugin } from '@basaltkit/subscriptions'`);
         plugins.push(`subscriptionsPlugin({
@@ -211,7 +245,21 @@ export function buildApp(options: BuildAppOptions = {}) {
     ],
   })
 }
-`;
+${enforcesMembership(options)
+        ? `
+/** Dev-only: adds each new registrant as a member of the 'demo' tenant. */
+function demoMembershipSeed() {
+  return definePlugin({
+    name: 'app:demo-membership-seed',
+    register({ container, hooks }) {
+      hooks.on('auth:registered', async ({ user }) => {
+        await container.get(TEAMS).addMember('demo', user.id, 'member')
+      })
+    },
+  })
+}
+`
+        : ''}`;
 }
 export function routesTs(options) {
     const endpoints = [
@@ -283,12 +331,29 @@ for (const signal of ['SIGINT', 'SIGTERM'] as const) {
 }
 `;
 }
+/**
+ * `pnpm dev` entrypoint. Opts into NODE_ENV=development (dev secret defaults,
+ * pretty logs) unless NODE_ENV is already set, then starts the server. Kept out
+ * of server.ts on purpose: `pnpm start` runs server.ts directly, where an unset
+ * NODE_ENV counts as production and secrets are required (fail-closed).
+ */
+export function devTs() {
+    return `// Development entrypoint (\`pnpm dev\`). \`pnpm start\` runs server.ts directly,
+// where an unset NODE_ENV counts as production: secrets are then required.
+process.env['NODE_ENV'] ??= 'development'
+await import('./server.js')
+`;
+}
 export function basaltBin() {
     return `#!/usr/bin/env node
 import { runCli } from '@basaltkit/cli'
 import { generatorCommands } from '@basaltkit/generator'
 import { prismaSyncCommand } from '@basaltkit/prisma'
-import { buildApp } from '../src/app.js'
+
+// Dev tooling: opt into development defaults unless NODE_ENV is already set
+// (imported dynamically below so env.ts is evaluated after this line).
+process.env['NODE_ENV'] ??= 'development'
+const { buildApp } = await import('../src/app.js')
 
 // The 'basalt' CLI: boots the app WITH the dev/CLI commands, runs one, shuts down.
 // The dev tools (@basaltkit/generator; add @basaltkit/ai for ai:*) are imported
@@ -433,6 +498,29 @@ export function mcpJson(_options) {
         },
     }, null, 2)}\n`;
 }
+/**
+ * Keeps secrets and local state out of Docker build contexts, so a
+ * `COPY . .` can never bake `.env` or private keys into an image layer. Every
+ * rule is `**`-prefixed: .dockerignore patterns are anchored at the context
+ * root, so a bare `.env` or `*.pem` would still let `prisma/.env` or
+ * `certs/server.key` through.
+ */
+export function dockerignore() {
+    return `**/.env
+**/.env.*
+!**/.env.example
+**/.npmrc
+**/.git
+**/node_modules
+**/coverage
+**/*.log
+**/*.pem
+**/*.key
+**/*.p12
+**/*.pfx
+**/.DS_Store
+`;
+}
 export function gitignore() {
     return `node_modules/
 dist/

package/dist/versions.d.ts

@@ -0,0 +1 @@
+export declare const SCAFFOLD_VERSIONS: Readonly<Record<string, string>>;

package/dist/versions.js

@@ -0,0 +1,24 @@
+// GENERATED by scripts/sync-versions.mjs (runs before every build) — do not edit.
+// The dependency range a new app gets for each @basaltkit/* package: the
+// current release line (^<major>.<minor>.0) of the workspace version.
+export const SCAFFOLD_VERSIONS = {
+    '@basaltkit/admin': '^2.0.0',
+    '@basaltkit/admin-shadcn': '^1.1.0',
+    '@basaltkit/ai-mcp': '^0.1.0',
+    '@basaltkit/auth': '^3.0.0',
+    '@basaltkit/cli': '^1.2.0',
+    '@basaltkit/config': '^1.1.0',
+    '@basaltkit/core': '^1.3.0',
+    '@basaltkit/env': '^3.0.0',
+    '@basaltkit/events': '^1.2.0',
+    '@basaltkit/fastify': '^2.1.0',
+    '@basaltkit/generator': '^1.4.0',
+    '@basaltkit/logger': '^1.3.0',
+    '@basaltkit/mcp': '^3.0.0',
+    '@basaltkit/prisma': '^2.0.0',
+    '@basaltkit/sdk': '^2.0.0',
+    '@basaltkit/subscriptions': '^4.0.0',
+    '@basaltkit/teams': '^3.0.0',
+    '@basaltkit/tenancy': '^2.0.0',
+    '@basaltkit/testing': '^2.0.0',
+};

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "create-basalt",
-  "version": "1.4.1",
+  "version": "1.5.0",
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "description": "Scaffold a production-shaped Basalt SaaS app: npm create basalt my-saas [--billing] [--ui] [--cli] [--install] [--git]",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "bin": {
     "create-basalt": "./dist/cli.js"
   },
@@ -17,24 +21,25 @@
     "dist"
   ],
   "devDependencies": {
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.5.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "zod": "^4.0.0",
-    "@basaltkit/auth": "^1.6.3",
-    "@basaltkit/config": "^1.1.1",
-    "@basaltkit/cli": "^1.2.1",
-    "@basaltkit/env": "^1.0.1",
-    "@basaltkit/core": "^1.3.0",
-    "@basaltkit/fastify": "^1.7.0",
-    "@basaltkit/generator": "^1.2.0",
-    "@basaltkit/events": "^1.0.1",
-    "@basaltkit/logger": "^1.2.1",
-    "@basaltkit/mcp": "^1.0.3",
-    "@basaltkit/subscriptions": "^2.7.0",
-    "@basaltkit/tenancy": "^1.4.0",
-    "@basaltkit/prisma": "^1.4.2",
-    "@basaltkit/testing": "^1.1.0",
+    "vitest": "^5.0.0",
+    "zod": "^4.5.4",
+    "@basaltkit/auth": "^3.0.0",
+    "@basaltkit/cli": "^1.2.5",
+    "@basaltkit/config": "^1.1.2",
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/env": "^3.0.0",
+    "@basaltkit/events": "^1.2.0",
+    "@basaltkit/fastify": "^2.1.0",
+    "@basaltkit/generator": "^1.4.0",
+    "@basaltkit/logger": "^1.3.0",
+    "@basaltkit/mcp": "^3.0.0",
+    "@basaltkit/prisma": "^2.0.0",
+    "@basaltkit/subscriptions": "^4.0.0",
+    "@basaltkit/teams": "^3.0.0",
+    "@basaltkit/tenancy": "^2.0.0",
+    "@basaltkit/testing": "^2.0.1",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -57,7 +62,8 @@
     "boilerplate"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node scripts/sync-versions.mjs && tsc -p tsconfig.build.json",
+    "sync-versions": "node scripts/sync-versions.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }