create-basalt 1.4.2 → 1.6.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,8 @@ 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.
+- **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.
 
@@ -132,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
@@ -144,7 +147,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
 
@@ -164,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:
@@ -185,7 +199,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 +219,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?, 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`:
 
@@ -213,6 +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, 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.
 
@@ -252,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/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, 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

@@ -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, 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

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ * - 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.
+ */
+/**
+ * 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";
+/** 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. */
+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 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>;
+    /** 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[];
+    /**
+     * 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;
+}
+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;
+    /**
+     * 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),
+ * 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;
+/** `<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
+ * 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[];