create-basalt 1.5.0 → 1.6.0

package/README.md

@@ -104,6 +104,7 @@ Behavior notes (faithful to the code):
 - **`--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.
+- **Release-age window (pnpm `minimumReleaseAge`)**: a third-party `latest` not provably older than the window (default 1440 min = pnpm 11's default; follows `pnpm_config_minimum_release_age` / `npm_config_minimum_release_age`) keeps the bundled range, so the first `pnpm install` is never blocked by a just-published version — pnpm then picks the newest *mature* version inside that range. The age comes from one `HEAD <registry>/<name>` per third-party package (the packument's `last-modified`, measured against the registry's `Date`); a missing header or failed probe counts as "not provably mature" and prints a `Note:`. `@basaltkit/*` is never probed (the generated `pnpm-workspace.yaml` excludes the scope).
 - **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.
 
@@ -134,10 +135,10 @@ Always:
 my-app/
 ├── package.json          # scripts: dev, start, test, typecheck (+ basalt with --cli)
 ├── tsconfig.json         # strict TypeScript, ESM
-├── .env.example          # PORT, HOST, LOG_LEVEL, NODE_ENV (+ APP_SECRET with auth)
+├── .env.example          # PORT, HOST, LOG_LEVEL, NODE_ENV (+ APP_SECRET with auth) + the --env-file precedence warning
 ├── .gitignore
 ├── README.md             # instructions adapted to the chosen options
-├── pnpm-workspace.yaml   # esbuild allowBuilds (+ "web" member with --ui)
+├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
 ├── src/
 │   ├── env.ts            # environment variables validated with Zod (@basaltkit/env)
 │   ├── app.ts            # buildApp() with the chosen plugins
@@ -166,6 +167,17 @@ pnpm basalt routes                  # registered HTTP routes
 pnpm basalt make:resource Project   # generates schema → repository → service → plugin → routes → test
 ```
 
+With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies (`verifyDepsBeforeRun`, default `install`) and runs `pnpm install` when any workspace project is out of sync — so `pnpm basalt …` can need the network. `node_modules/.bin/tsx bin/basalt.ts …` skips that check; `verifyDepsBeforeRun: warn` (commented out in the generated `pnpm-workspace.yaml`) turns it into a warning for the whole project.
+
+### `pnpm-workspace.yaml` and pnpm 11
+
+- `minimumReleaseAgeExclude` is evaluated **first-match-wins by package name**. To exclude several versions of one package, write ONE entry with a union — `'@types/node@22.20.4 || 26.6.2'` — never two `@types/node@…` entries (only the first would apply). The generated file carries this example as a comment.
+- `verifyDepsBeforeRun: warn` is offered commented out; the scaffold keeps pnpm's secure default (`install`).
+
+### Environment variables and `--env-file`
+
+Nothing loads `.env` for you. `node --env-file=.env` / `tsx --env-file=.env` **never override a variable already exported in the shell** — in a terminal where another project exported `DATABASE_URL` or `PORT`, the app boots against that value and only fails on the first request that touches it. The generated `.env.example` and README say so and suggest an app-specific prefix derived from the project name (`my-saas` → `MY_SAAS_DATABASE_URL`).
+
 ### Programmatic usage (Advanced)
 
 The package also exports the API used by the executable, for your own scripts:
@@ -208,7 +220,7 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | `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) |
+| `registry` | `ResolveLatestOptions` | No | — | `{ fetch?, registry?, timeoutMs?, overallTimeoutMs?, concurrency?, minimumReleaseAge?, now? }` — injectable fetch (tests), registry URL (default `npm_config_registry` or `https://registry.npmjs.org`), timeouts (5 s per request, 15 s overall), release-age window in minutes (default `pnpm_config_minimum_release_age` / `npm_config_minimum_release_age`, else 1440; `0` disables the probe), clock (tests) |
 
 `CreateProjectResult`:
 
@@ -217,7 +229,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 |
+| `versions` | `VersionResolution \| undefined` | With `resolveLatest`: `{ versions, resolved, failed, heldBack, tooFresh, registry }` — the final ranges, which packages got `^<latest>`, which kept the fallback after a registry failure, third-party packages held back because their latest is a new major, and third-party packages whose latest is not provably older than the release-age window (`{ name, latest, range, reason: 'recent' \| 'unknown' }`) |
 
 Throws `TargetNotEmptyError` if the destination folder exists and isn't empty.
 
@@ -257,6 +269,12 @@ Automatic installation failed (network, Node version, etc.). Go into the folder
 **I started the app and `GET /auth/login` gives a secret error.**
 With auth on, `src/env.ts` requires `APP_SECRET` with at least 16 characters (there's a development default `change-me-in-production--`). Copy `.env.example` to `.env` and set your own secret before going to production.
 
+**My app connects to the wrong database / port.**
+A variable exported in your shell beats `--env-file`. Check `env | grep DATABASE_URL`, start with `env -u DATABASE_URL pnpm dev`, and prefer app-prefixed names (see *Environment variables and `--env-file`*).
+
+**`pnpm basalt …` starts by running `pnpm install` (or fails offline).**
+pnpm 11's `verifyDepsBeforeRun` (default `install`). Run `node_modules/.bin/tsx bin/basalt.ts …` instead, or set `verifyDepsBeforeRun: warn` in `pnpm-workspace.yaml`.
+
 **I want to change my mind after generating (e.g. add billing).**
 There's no "re-scaffold" command. Either generate a new project with the right flags and compare, or add it by hand: install `@basaltkit/subscriptions` and add the `subscriptionsPlugin` to `src/app.ts` (the generated README and the templates serve as reference).
 

package/dist/index.d.ts

@@ -60,6 +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 { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, type FreshVersion, 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

@@ -82,6 +82,6 @@ export async function createProject(input) {
     }
     return { dir, files: Object.keys(files).sort(), options, ...(versions ? { versions } : {}) };
 }
-export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, describeResolution, resolveLatestVersions, registryUrl, } from './latest-versions.js';
+export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, minimumReleaseAgeMinutes, 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

@@ -9,6 +9,17 @@
  *   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.
+ * - Third-party packages also respect pnpm's `minimumReleaseAge` (pnpm 11
+ *   defaults it to one day): `^<latest>` for a version published minutes ago is
+ *   UNSATISFIABLE under that policy, so the first `pnpm install` would fail. A
+ *   cheap `HEAD <registry>/<name>` reads the packument's `last-modified` (which
+ *   is never older than the latest publish): older than the window proves the
+ *   latest mature and `^<latest>` is written; newer — or no header / a failed
+ *   probe — keeps the fallback range, from which pnpm picks the newest MATURE
+ *   version itself. The full packument (the only per-version `time` source) is
+ *   megabytes for packages like `@types/node`, so it is never fetched; a
+ *   false "fresh" only costs a lower range floor. `@basaltkit/*` is never
+ *   probed: the scaffolded pnpm-workspace.yaml excludes that scope.
  * - Any registry failure (offline, timeout, non-2xx, malformed JSON, a bogus
  *   version string) keeps the embedded fallback range. The registry never fails
  *   a scaffold.
@@ -21,6 +32,8 @@
  */
 export declare const THIRD_PARTY_VERSIONS: Readonly<Record<string, string>>;
 export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+/** pnpm 11's default `minimumReleaseAge`, in minutes (one day). */
+export declare const DEFAULT_MINIMUM_RELEASE_AGE_MINUTES = 1440;
 /** 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. */
@@ -32,6 +45,15 @@ export interface HeldBackVersion {
     /** The range kept instead. */
     range: string;
 }
+export interface FreshVersion {
+    name: string;
+    /** The registry's latest version (same major, but possibly inside the release-age window). */
+    latest: string;
+    /** The range kept instead. */
+    range: string;
+    /** `recent`: published inside the window; `unknown`: its age could not be proven. */
+    reason: 'recent' | 'unknown';
+}
 export interface VersionResolution {
     /** Final range per package name (resolved or fallback). */
     versions: Record<string, string>;
@@ -41,6 +63,11 @@ export interface VersionResolution {
     failed: string[];
     /** Third-party packages whose latest is a new major — fallback kept. */
     heldBack: HeldBackVersion[];
+    /**
+     * Third-party packages whose latest may be younger than the release-age
+     * window (pnpm `minimumReleaseAge`) — fallback kept so installs stay possible.
+     */
+    tooFresh: FreshVersion[];
     /** Registry actually queried. */
     registry: string;
 }
@@ -55,7 +82,21 @@ export interface ResolveLatestOptions {
     overallTimeoutMs?: number;
     /** Requests in flight at once. Default 8. */
     concurrency?: number;
+    /**
+     * Release-age window in minutes (pnpm `minimumReleaseAge`): a third-party
+     * latest not provably older than this keeps its fallback range. Default:
+     * `pnpm_config_minimum_release_age` / `npm_config_minimum_release_age`, else
+     * 1440 (pnpm 11's default). `0` disables the check (no probe requests).
+     */
+    minimumReleaseAge?: number;
+    /** Clock used when the registry sends no `Date` header (tests). Default: Date.now. */
+    now?: () => number;
 }
+/**
+ * The release-age window in minutes: an explicit option, else the pnpm/npm
+ * config env var (a `pnpm create` exports its config), else pnpm 11's default.
+ */
+export declare function minimumReleaseAgeMinutes(explicit?: number, env?: NodeJS.ProcessEnv): 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),
@@ -65,6 +106,8 @@ export interface ResolveLatestOptions {
 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;
+/** `<registry>/<name>` — the packument (probed with HEAD for its `last-modified`). */
+export declare const packumentUrl: (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

package/dist/latest-versions.js

@@ -9,6 +9,17 @@
  *   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.
+ * - Third-party packages also respect pnpm's `minimumReleaseAge` (pnpm 11
+ *   defaults it to one day): `^<latest>` for a version published minutes ago is
+ *   UNSATISFIABLE under that policy, so the first `pnpm install` would fail. A
+ *   cheap `HEAD <registry>/<name>` reads the packument's `last-modified` (which
+ *   is never older than the latest publish): older than the window proves the
+ *   latest mature and `^<latest>` is written; newer — or no header / a failed
+ *   probe — keeps the fallback range, from which pnpm picks the newest MATURE
+ *   version itself. The full packument (the only per-version `time` source) is
+ *   megabytes for packages like `@types/node`, so it is never fetched; a
+ *   false "fresh" only costs a lower range floor. `@basaltkit/*` is never
+ *   probed: the scaffolded pnpm-workspace.yaml excludes that scope.
  * - Any registry failure (offline, timeout, non-2xx, malformed JSON, a bogus
  *   version string) keeps the embedded fallback range. The registry never fails
  *   a scaffold.
@@ -36,6 +47,9 @@ export const THIRD_PARTY_VERSIONS = {
     zod: '^4.6.5',
 };
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/** pnpm 11's default `minimumReleaseAge`, in minutes (one day). */
+export const DEFAULT_MINIMUM_RELEASE_AGE_MINUTES = 1440;
+const ABBREVIATED_METADATA = 'application/vnd.npm.install-v1+json';
 const PER_REQUEST_TIMEOUT_MS = 5_000;
 const OVERALL_TIMEOUT_MS = 15_000;
 /**
@@ -54,6 +68,20 @@ export function compatibleMajor(fallbackRange) {
     const match = CARET_RANGE.exec(fallbackRange);
     return match ? Number(match[1]) : undefined;
 }
+/**
+ * The release-age window in minutes: an explicit option, else the pnpm/npm
+ * config env var (a `pnpm create` exports its config), else pnpm 11's default.
+ */
+export function minimumReleaseAgeMinutes(explicit, env = process.env) {
+    if (explicit !== undefined && Number.isFinite(explicit) && explicit >= 0)
+        return explicit;
+    for (const key of ['pnpm_config_minimum_release_age', 'npm_config_minimum_release_age']) {
+        const raw = env[key];
+        if (raw !== undefined && /^\d+$/.test(raw.trim()))
+            return Number(raw.trim());
+    }
+    return DEFAULT_MINIMUM_RELEASE_AGE_MINUTES;
+}
 /**
  * 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),
@@ -79,6 +107,34 @@ export function registryUrl(explicit, env = process.env) {
 }
 /** `<registry>/<name>/latest`, with a scoped name's `/` encoded as `%2f`. */
 export const latestUrl = (registry, name) => `${registry}/${name.replaceAll('/', '%2f')}/latest`;
+/** `<registry>/<name>` — the packument (probed with HEAD for its `last-modified`). */
+export const packumentUrl = (registry, name) => `${registry}/${name.replaceAll('/', '%2f')}`;
+/**
+ * Whether `name`'s latest is provably older than `windowMs`. A packument's
+ * `last-modified` is never older than its latest publish, so an old header
+ * proves maturity. Age is measured against the registry's own `Date` header
+ * when present (immune to local clock skew). Never throws.
+ */
+async function probeAge(fetchImpl, registry, name, windowMs, now, signal) {
+    try {
+        const response = await fetchImpl(packumentUrl(registry, name), {
+            method: 'HEAD',
+            headers: { accept: ABBREVIATED_METADATA },
+            signal,
+        });
+        if (!response.ok)
+            return 'unknown';
+        const modified = Date.parse(response.headers.get('last-modified') ?? '');
+        if (Number.isNaN(modified))
+            return 'unknown';
+        const serverNow = Date.parse(response.headers.get('date') ?? '');
+        const reference = Number.isNaN(serverNow) ? now() : serverNow;
+        return reference - modified >= windowMs ? 'mature' : 'recent';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 async function lookupLatest(fetchImpl, registry, name, signal) {
     try {
         const response = await fetchImpl(latestUrl(registry, name), {
@@ -126,19 +182,37 @@ export async function resolveLatestVersions(fallbacks, options = {}) {
     const resolved = [];
     const failed = [];
     const heldBack = [];
+    const tooFresh = [];
     const names = Object.keys(fallbacks).sort();
+    const windowMs = minimumReleaseAgeMinutes(options.minimumReleaseAge) * 60_000;
+    const now = options.now ?? Date.now;
+    const timeoutMs = options.timeoutMs ?? PER_REQUEST_TIMEOUT_MS;
     if (typeof fetchImpl !== 'function') {
-        return { versions, resolved, failed: names, heldBack, registry };
+        return { versions, resolved, failed: names, heldBack, tooFresh, registry };
     }
+    /** A third-party latest on the template-compatible major (else undefined). */
+    const compatible = (name, version) => {
+        if (alwaysLatest(name))
+            return true;
+        const major = compatibleMajor(fallbacks[name]);
+        return major !== undefined && Number(version.split('.')[0]) === major;
+    };
     const overall = new AbortController();
     const cap = setTimeout(() => overall.abort(), options.overallTimeoutMs ?? OVERALL_TIMEOUT_MS);
     try {
         const latest = [];
+        const age = [];
         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 name = names[i];
+                const version = await fetchLatest(fetchImpl, registry, name, timeoutMs, overall.signal);
+                latest[i] = version;
+                age[i] =
+                    version === undefined || alwaysLatest(name) || windowMs === 0 || !compatible(name, version)
+                        ? 'mature'
+                        : await probeAge(fetchImpl, registry, name, windowMs, now, AbortSignal.any([AbortSignal.timeout(timeoutMs), overall.signal]));
             }
         };
         const pool = Math.max(1, Math.min(options.concurrency ?? CONCURRENCY, names.length));
@@ -150,12 +224,14 @@ export async function resolveLatestVersions(fallbacks, options = {}) {
                 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;
-                }
+            if (!compatible(name, version)) {
+                heldBack.push({ name, latest: version, range: fallback });
+                return;
+            }
+            const verdict = age[i];
+            if (verdict === 'recent' || verdict === 'unknown') {
+                tooFresh.push({ name, latest: version, range: fallback, reason: verdict });
+                return;
             }
             versions[name] = `^${version}`;
             resolved.push(name);
@@ -164,7 +240,7 @@ export async function resolveLatestVersions(fallbacks, options = {}) {
     finally {
         clearTimeout(cap);
     }
-    return { versions, resolved, failed, heldBack, registry };
+    return { versions, resolved, failed, heldBack, tooFresh, registry };
 }
 /**
  * Rewrites the dependency ranges of a generated package.json with the
@@ -202,6 +278,14 @@ export function describeResolution(resolution) {
     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}.`);
     }
+    const recent = resolution.tooFresh.filter((entry) => entry.reason === 'recent');
+    const unknown = resolution.tooFresh.filter((entry) => entry.reason === 'unknown');
+    for (const fresh of recent) {
+        lines.push(`Note: ${fresh.name} ${fresh.latest} was published inside pnpm's minimumReleaseAge window — kept ${fresh.range} (pnpm installs the newest mature version).`);
+    }
+    if (unknown.length > 0) {
+        lines.push(`Note: could not prove the release age of ${unknown.map((entry) => `${entry.name}@${entry.latest}`).join(', ')} — kept the bundled range(s) so minimumReleaseAge cannot block the install.`);
+    }
     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(', ')}.`);
     }

package/dist/templates.d.ts

@@ -31,6 +31,12 @@ 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;
+/**
+ * An app-specific env-var prefix derived from the project name
+ * (`my-saas` → `MY_SAAS`), suggested for variables whose generic names
+ * (`DATABASE_URL`, …) other projects export too.
+ */
+export declare function envPrefix(name: string): string;
 export declare function envExample(options: ProjectOptions): string;
 export declare function appTs(options: ProjectOptions): string;
 export declare function routesTs(options: ProjectOptions): string;
@@ -65,5 +71,11 @@ export declare function gitignore(): string;
  * msgpackr-extract (optional native accelerator via BullMQ) is declined —
  * msgpackr falls back to pure JS. With --ui, `web` is a workspace member so
  * its own dependencies resolve.
+ *
+ * pnpm 11 notes (BK-002), spelled out in the file because both bite silently:
+ * `minimumReleaseAgeExclude` is evaluated first-match-wins BY PACKAGE NAME, so
+ * per-version exclusions of one package must be a single `||` union entry; and
+ * `verifyDepsBeforeRun` defaults to `install`, so any `pnpm <script>` may run
+ * `pnpm install` first — `warn` is offered commented out, never set for you.
  */
 export declare function pnpmWorkspaceYaml(options: ProjectOptions): string;

package/dist/templates.js

@@ -46,7 +46,8 @@ export function packageJson(options) {
         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).
+        // `basalt prisma:sync` (and prismaPlugin once the app adds a PrismaClient —
+        // the scaffold wires no database itself). @basaltkit/generator is dev-only (below).
         basalt.push('@basaltkit/cli', '@basaltkit/prisma');
     }
     const dependencies = { zod: thirdPartyVersionOf('zod') };
@@ -125,8 +126,34 @@ export const env = defineEnv({
 })
 `;
 }
+/**
+ * An app-specific env-var prefix derived from the project name
+ * (`my-saas` → `MY_SAAS`), suggested for variables whose generic names
+ * (`DATABASE_URL`, …) other projects export too.
+ */
+export function envPrefix(name) {
+    let base = name
+        .replace(/^@[^/]+\//, '')
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_');
+    // Trim underscores in linear time (an anchored `_+$` regex backtracks).
+    let start = 0;
+    let end = base.length;
+    while (start < end && base[start] === '_')
+        start++;
+    while (end > start && base[end - 1] === '_')
+        end--;
+    base = base.slice(start, end);
+    return base === '' || /^\d/.test(base) ? `APP_${base}` : base;
+}
 export function envExample(options) {
-    return `PORT=3000
+    const prefix = envPrefix(options.name);
+    return `# Nothing loads this file for you: copy it to .env and start with
+# \`node --env-file=.env\` / \`tsx --env-file=.env\`, or export the variables.
+# --env-file NEVER overrides a variable already exported in your shell: if
+# another project exported DATABASE_URL, the app silently uses THAT one. Give
+# generic names an app-specific prefix, e.g. ${prefix}_DATABASE_URL.
+PORT=3000
 HOST=0.0.0.0
 LOG_LEVEL=info
 NODE_ENV=development
@@ -427,6 +454,18 @@ pnpm install
 pnpm dev        # API on http://localhost:3000
 pnpm test
 \`\`\`
+
+## Environment
+
+\`src/env.ts\` validates \`process.env\` — nothing loads \`.env\` for you. Copy
+\`.env.example\` to \`.env\` and launch with \`--env-file=.env\` (Node/tsx), or
+export the variables.
+
+**\`--env-file\` never overrides a variable that is already exported.** In a shell
+where another project exported \`DATABASE_URL\` (or \`PORT\`), this app boots
+against THAT value and only fails on the first request that touches it. Give
+generic names an app-specific prefix — \`${envPrefix(options.name)}_DATABASE_URL\` rather than
+\`DATABASE_URL\` — and check \`env | grep DATABASE_URL\` when in doubt.
 ${options.cli
         ? `
 ## The \`basalt\` CLI
@@ -440,6 +479,18 @@ pnpm basalt make:service Project    # a single artifact (--force to overwrite)
 
 Generated resources land in \`src/modules/<name>/\`. Register the generated
 plugin in \`src/app.ts\` to wire it up.
+
+With pnpm 11, \`pnpm basalt …\` first verifies dependencies
+(\`verifyDepsBeforeRun\`, default \`install\`): when any workspace project is out
+of sync it runs \`pnpm install\` — network included — before the command. To
+run the CLI without that check, call it directly:
+
+\`\`\`bash
+node_modules/.bin/tsx bin/basalt.ts make:resource Project
+\`\`\`
+
+or set \`verifyDepsBeforeRun: warn\` in \`pnpm-workspace.yaml\` (a conscious
+choice: you then run \`pnpm install\` yourself after dependency changes).
 `
         : ''}${options.ui
         ? `
@@ -535,6 +586,12 @@ dist/
  * msgpackr-extract (optional native accelerator via BullMQ) is declined —
  * msgpackr falls back to pure JS. With --ui, `web` is a workspace member so
  * its own dependencies resolve.
+ *
+ * pnpm 11 notes (BK-002), spelled out in the file because both bite silently:
+ * `minimumReleaseAgeExclude` is evaluated first-match-wins BY PACKAGE NAME, so
+ * per-version exclusions of one package must be a single `||` union entry; and
+ * `verifyDepsBeforeRun` defaults to `install`, so any `pnpm <script>` may run
+ * `pnpm install` first — `warn` is offered commented out, never set for you.
  */
 export function pnpmWorkspaceYaml(options) {
     return `${options.ui
@@ -548,5 +605,16 @@ export function pnpmWorkspaceYaml(options) {
 # pnpm's minimumReleaseAge policy so \`pnpm up\` is never blocked on a fresh release.
 minimumReleaseAgeExclude:
   - '@basaltkit/*'
+# To let specific versions of ONE package bypass the policy, write ONE entry
+# with a \`||\` union. pnpm evaluates this list first match wins by package
+# name, so a second '<name>@<version>' entry for the same package is ignored:
+#   - '@types/node@22.20.4 || 26.6.2'
+
+# pnpm 11 checks dependencies before every \`pnpm <script>\` / \`pnpm exec\`
+# (verifyDepsBeforeRun defaults to \`install\`): when node_modules is out of sync
+# with ANY workspace project's manifest, it runs \`pnpm install\` first — network
+# and supply-chain checks included. To opt out consciously (you then run
+# \`pnpm install\` yourself after dependency changes), uncomment:
+# verifyDepsBeforeRun: warn
 `;
 }

package/dist/versions.js

@@ -5,17 +5,17 @@ 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/auth': '^3.1.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/events': '^1.3.0',
+    '@basaltkit/fastify': '^2.2.0',
     '@basaltkit/generator': '^1.4.0',
     '@basaltkit/logger': '^1.3.0',
     '@basaltkit/mcp': '^3.0.0',
-    '@basaltkit/prisma': '^2.0.0',
+    '@basaltkit/prisma': '^2.1.0',
     '@basaltkit/sdk': '^2.0.0',
     '@basaltkit/subscriptions': '^4.0.0',
     '@basaltkit/teams': '^3.0.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -21,25 +21,25 @@
     "dist"
   ],
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0",
-    "zod": "^4.5.4",
-    "@basaltkit/auth": "^3.0.0",
-    "@basaltkit/cli": "^1.2.5",
+    "vitest": "^5.0.1",
+    "zod": "^4.6.5",
+    "@basaltkit/auth": "^3.1.0",
     "@basaltkit/config": "^1.1.2",
-    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/core": "^1.3.2",
     "@basaltkit/env": "^3.0.0",
-    "@basaltkit/events": "^1.2.0",
-    "@basaltkit/fastify": "^2.1.0",
+    "@basaltkit/cli": "^1.2.5",
+    "@basaltkit/events": "^1.3.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/prisma": "^2.1.0",
+    "@basaltkit/teams": "^3.0.1",
+    "@basaltkit/fastify": "^2.2.0",
     "@basaltkit/tenancy": "^2.0.0",
-    "@basaltkit/testing": "^2.0.1",
+    "@basaltkit/testing": "^2.0.2",
+    "@basaltkit/subscriptions": "^4.0.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {