@basaltkit/cli 1.5.0 → 1.7.0

package/README.md

@@ -41,6 +41,10 @@ app's, at its pinned versions. Arguments and the exit code pass through
 unchanged. Outside an app it says so and exits 1. The launcher loads nothing of
 the framework, only Node built-ins.
 
+`basalt new <name> [flags]` is the launcher's own command: it scaffolds an app
+with `create-basalt@latest` (through `pnpm dlx`, else `npx`; `--pm=` picks the
+manager), so it always gets the latest scaffolder.
+
 ## Get started in 5 minutes
 
 1. Create a `bin/basalt.ts` file at the root of the project — this will be the entry point for the `basalt` command:
@@ -110,7 +114,7 @@ Without registering anything, `runCli` always provides:
 | `basalt list` (or `basalt` with no arguments) | Lists all available commands, with their descriptions |
 | `basalt routes [--json] [--unguarded --require=auth,can [--allow=<glob,…>]]` | Lists the HTTP routes registered by the application with the guards each declares in `meta` — columns `auth`, `can`, `rateLimit`, `tenant` and `guards` (`mfa`, `teamRole`, `scopes`, `subscribed`, `feature`). `--json` prints one JSON array of route rows. `--unguarded` lists the routes that do not declare the `--require`d guards and exits `1` when there is any (see [Route security review](#route-security-review)). Read from the `http:routes` metadata bucket, populated by every HTTP adapter |
 | `basalt schedule:list` | Lists scheduled tasks and their cron expressions (read from the `schedule:entries` bucket, populated by `@basaltkit/scheduler`) |
-| `basalt dev [--entry] [--worker] [--queue] [--no-routes]` | Runs the app with watch + restart, **prints the route table on boot**, and with `--worker` also starts a watched `queue:work` alongside it (server + worker in one command). Delegates watching to `tsx watch` / `node --watch`. |
+| `basalt dev [--entry] [--worker] [--queue] [--no-routes]` | Runs the app with watch + restart, **prints the route table on boot**, and with `--worker` also starts a watched `queue:work` alongside it (server + worker in one command). Delegates watching to `tsx watch` / `node --watch`. Runs `src/dev.ts` when present (else `src/main.ts`, `src/server.ts`, …), and shuts the CLI's own boot down before the server starts: one app per session. A create-basalt `bin/basalt.ts` routes `dev` to `runDev({ loadApp })` before booting anything, so it starts even while the app cannot boot (the reason is printed, the watcher restarts on save). |
 | `basalt upgrade [--dry] [--only=<id>] [--dir=<path>]` | Applies framework upgrade codemods (ships the `@machize/*` → `@basaltkit/*` scope rename; `--dry` previews). `create-basalt update` runs them for you after an install. `nodeUpgradeFs(baseDir)` resolves relative paths against the directory being upgraded, so `--dir=` reads the tree it lists |
 | `basalt publish [<id>] [--force]` | Copies a bundled stub group into the app — `dockerfile` (a multi-stage build that runs `pnpm build` and ships `dist/src/server.js` on plain node as `USER node`, plus a `.dockerignore` keeping `.env` and keys out of the image — the same files create-basalt scaffolds), `ci` (install, typecheck, build, test), `editorconfig` (run with no id to list). The stub contents are exported too: `DOCKERFILE`, `DOCKERIGNORE`, `CI_WORKFLOW`, `EDITORCONFIG`, `PRODUCTION_ENTRY` |
 

package/dist/dev.d.ts

@@ -1,5 +1,10 @@
-import { type CommandDefinition } from './command.js';
-/** Default entry files probed in order when `--entry` is not given. */
+import { type BasaltApp } from '@basaltkit/core';
+import { type CommandDefinition, type CommandIo } from './command.js';
+/**
+ * Default entry files probed in order when `--entry` is not given. A
+ * create-basalt app's `src/dev.ts` comes first: it is what `pnpm dev` runs
+ * (it loads `.env` and opts into NODE_ENV=development before the server).
+ */
 export declare const DEV_ENTRY_CANDIDATES: string[];
 /**
  * Picks the first candidate that exists. Pure — `exists` is injected so the
@@ -45,5 +50,31 @@ export declare function devRouteRows(routes: DevRoute[]): {
  * runs the server with watch/restart — and, with `--worker`, also starts a
  * watched queue worker alongside it (server + worker in one command, the real
  * producer/worker topology).
+ *
+ * The CLI's own boot exists only to read the route table: it is shut down
+ * before the server starts, so a dev session holds one app (one database
+ * pool, one set of connections), not two. A create-basalt `bin/basalt.ts`
+ * sends `dev` to {@link runDev} before booting anything, so the session also
+ * starts while the app cannot boot; this command is the path for a bin
+ * without that prelude.
  */
 export declare const devCommand: CommandDefinition;
+export interface RunDevOptions {
+    /** Defaults to process.argv.slice(2) — `dev` first, as typed. */
+    argv?: string[];
+    /** Imports and builds the app, unbooted — only to read its route table. */
+    loadApp: () => BasaltApp | Promise<BasaltApp>;
+    io?: CommandIo;
+    /** How long the route table may wait for the boot before the server starts without it. @default 10000 */
+    bootTimeoutMs?: number;
+}
+/**
+ * `basalt dev` without depending on the app booting. The app is loaded and
+ * booted once, only to print the route table, then shut down. When that fails
+ * — a variable missing, the database down, code mid-edit — the reason is
+ * printed and the watcher starts anyway: it restarts the server on every save,
+ * as `pnpm dev` does, so you fix the problem and the session carries on.
+ */
+export declare function runDev(options: RunDevOptions): Promise<number>;
+/** The reason a boot failed, in a few lines: the env report when there is one, else the first line of the message. */
+export declare function bootFailureLines(error: unknown): string[];

package/dist/dev.js

@@ -1,7 +1,13 @@
 import { ensureMetadata } from '@basaltkit/core';
 import { defineCommand } from './command.js';
-/** Default entry files probed in order when `--entry` is not given. */
-export const DEV_ENTRY_CANDIDATES = ['src/main.ts', 'src/server.ts', 'src/index.ts', 'src/main.js', 'src/index.js'];
+import { consoleIo } from './io.js';
+import { parseArgv } from './parse.js';
+/**
+ * Default entry files probed in order when `--entry` is not given. A
+ * create-basalt app's `src/dev.ts` comes first: it is what `pnpm dev` runs
+ * (it loads `.env` and opts into NODE_ENV=development before the server).
+ */
+export const DEV_ENTRY_CANDIDATES = ['src/dev.ts', 'src/main.ts', 'src/server.ts', 'src/index.ts', 'src/main.js', 'src/index.js'];
 /**
  * Picks the first candidate that exists. Pure — `exists` is injected so the
  * resolution is testable without touching disk.
@@ -53,66 +59,144 @@ export function devRouteRows(routes) {
  * runs the server with watch/restart — and, with `--worker`, also starts a
  * watched queue worker alongside it (server + worker in one command, the real
  * producer/worker topology).
+ *
+ * The CLI's own boot exists only to read the route table: it is shut down
+ * before the server starts, so a dev session holds one app (one database
+ * pool, one set of connections), not two. A create-basalt `bin/basalt.ts`
+ * sends `dev` to {@link runDev} before booting anything, so the session also
+ * starts while the app cannot boot; this command is the path for a bin
+ * without that prelude.
  */
 export const devCommand = defineCommand({
     name: 'dev',
     description: 'Run the app with watch + restart, print the route table, and (--worker) an embedded queue worker',
-    async handle({ container, io, flags }) {
-        const { existsSync } = await import('node:fs');
-        const entry = typeof flags['entry'] === 'string'
-            ? flags['entry']
-            : resolveDevEntry(DEV_ENTRY_CANDIDATES, existsSync);
-        if (!entry) {
-            io.error(`No entry file found. Looked for ${DEV_ENTRY_CANDIDATES.join(', ')}. Pass --entry=<file>.`);
+    async handle({ app, container, io, flags }) {
+        const entry = await devEntry(flags, io);
+        if (!entry)
             return 1;
-        }
-        // The route table — the app was already booted by runCli, so `http:routes`
-        // is populated by whichever adapter is in use. Adapter-agnostic (metadata only).
-        if (flags['routes'] !== false) {
-            const routes = ensureMetadata(container).get('http:routes');
-            if (routes.length > 0) {
-                io.log(`Routes (${routes.length}):`);
-                io.table(devRouteRows(routes));
-            }
-        }
-        const tsx = await canResolve('tsx');
-        const server = resolveDevRunner(entry, { tsx });
-        const runners = [{ label: 'server', runner: server }];
-        // Embedded worker: a watched `queue:work` on the same CLI bin, so jobs
-        // process in dev without a second terminal. Separate process (correct
-        // producer/worker split) — each restarts independently on file change.
-        if (flags['worker'] === true || flags['w'] === true) {
-            const bin = process.argv[1] ?? entry;
-            const workerBase = resolveDevRunner(bin, { tsx });
-            const queue = typeof flags['queue'] === 'string' ? [`--queue=${flags['queue']}`] : [];
-            runners.push({ label: 'worker', runner: { command: workerBase.command, args: [...workerBase.args, 'queue:work', ...queue] } });
-        }
-        for (const { label, runner } of runners) {
-            io.log(`▶ ${label}: ${runner.command} ${runner.args.join(' ')}`);
-        }
-        const { spawn } = await import('node:child_process');
-        return await new Promise((resolve) => {
-            const children = runners.map(({ runner }) => spawn(runner.command, runner.args, { stdio: 'inherit' }));
-            const stop = () => children.forEach((c) => c.kill('SIGINT'));
-            process.once('SIGINT', stop);
-            let done = false;
-            const finish = (code) => {
-                if (done)
-                    return;
-                done = true;
-                process.removeListener('SIGINT', stop);
-                children.forEach((c) => c.kill('SIGINT'));
-                resolve(code);
-            };
-            // The server is primary — when it exits, tear everything down.
-            children[0]?.on('exit', (code) => finish(code ?? 0));
-            children.forEach((child, i) => child.on('error', (error) => {
-                io.error(`Failed to start ${runners[i]?.label}: ${error.message}`);
-                finish(1);
-            }));
-        });
+        if (flags['routes'] !== false)
+            printRoutes(container, io);
+        // Done with the CLI's boot: the server below is the app from here on.
+        // runCli's own shutdown afterwards is a no-op.
+        await app.shutdown();
+        return startDevProcesses(entry, flags, io);
     },
 });
+/**
+ * `basalt dev` without depending on the app booting. The app is loaded and
+ * booted once, only to print the route table, then shut down. When that fails
+ * — a variable missing, the database down, code mid-edit — the reason is
+ * printed and the watcher starts anyway: it restarts the server on every save,
+ * as `pnpm dev` does, so you fix the problem and the session carries on.
+ */
+export async function runDev(options) {
+    const io = options.io ?? consoleIo();
+    const { flags } = parseArgv(options.argv ?? process.argv.slice(2));
+    const entry = await devEntry(flags, io);
+    if (!entry)
+        return 1;
+    if (flags['routes'] !== false)
+        await routesIfItBoots(options, io);
+    return startDevProcesses(entry, flags, io);
+}
+async function routesIfItBoots(options, io) {
+    let app;
+    let timer;
+    const timeoutMs = options.bootTimeoutMs ?? 10_000;
+    const boot = (async () => {
+        app = await options.loadApp();
+        if (app.phase === 'created')
+            await app.boot();
+        return app;
+    })();
+    const timedOut = new Promise((resolve) => { timer = setTimeout(() => resolve('timeout'), timeoutMs); });
+    try {
+        const booted = await Promise.race([boot, timedOut]);
+        if (booted === 'timeout') {
+            io.error(`! The app did not boot within ${timeoutMs / 1000}s, so no route table — starting the server anyway.`);
+            // It may still finish: shut it down then, so the session holds one app.
+            boot.then((late) => late.shutdown()).catch(() => { });
+            return;
+        }
+        printRoutes(booted.container, io);
+    }
+    catch (error) {
+        io.error('! The app does not boot yet, so no route table — starting the server anyway; it restarts on every save:');
+        for (const line of bootFailureLines(error))
+            io.error(`  ${line}`);
+    }
+    finally {
+        clearTimeout(timer);
+        if (app && app.phase !== 'created')
+            await app.shutdown().catch(() => { });
+    }
+}
+/** The reason a boot failed, in a few lines: the env report when there is one, else the first line of the message. */
+export function bootFailureLines(error) {
+    const failure = (error ?? {});
+    if (process.env['BASALT_DEBUG'] === '1' && typeof failure.stack === 'string')
+        return failure.stack.split('\n');
+    if (failure.code === 'ENV_INVALID' && Array.isArray(failure.report)) {
+        return ['invalid environment variables:', ...failure.report.map((line) => `- ${String(line)}`)];
+    }
+    const first = String(failure.message ?? error).split('\n')[0] ?? '';
+    return [first, '(BASALT_DEBUG=1 shows the stack trace)'];
+}
+async function devEntry(flags, io) {
+    if (typeof flags['entry'] === 'string')
+        return flags['entry'];
+    const { existsSync } = await import('node:fs');
+    const entry = resolveDevEntry(DEV_ENTRY_CANDIDATES, existsSync);
+    if (!entry)
+        io.error(`No entry file found. Looked for ${DEV_ENTRY_CANDIDATES.join(', ')}. Pass --entry=<file>.`);
+    return entry;
+}
+/** The route table, from the `http:routes` metadata whichever adapter published. Adapter-agnostic. */
+function printRoutes(container, io) {
+    const routes = ensureMetadata(container).get('http:routes');
+    if (routes.length === 0)
+        return;
+    io.log(`Routes (${routes.length}):`);
+    io.table(devRouteRows(routes));
+}
+async function startDevProcesses(entry, flags, io) {
+    const tsx = await canResolve('tsx');
+    const server = resolveDevRunner(entry, { tsx });
+    const runners = [{ label: 'server', runner: server }];
+    // Embedded worker: a watched `queue:work` on the same CLI bin, so jobs
+    // process in dev without a second terminal. Separate process (correct
+    // producer/worker split) — each restarts independently on file change.
+    if (flags['worker'] === true || flags['w'] === true) {
+        const bin = process.argv[1] ?? entry;
+        const workerBase = resolveDevRunner(bin, { tsx });
+        const queue = typeof flags['queue'] === 'string' ? [`--queue=${flags['queue']}`] : [];
+        runners.push({ label: 'worker', runner: { command: workerBase.command, args: [...workerBase.args, 'queue:work', ...queue] } });
+    }
+    for (const { label, runner } of runners) {
+        io.log(`▶ ${label}: ${runner.command} ${runner.args.join(' ')}`);
+    }
+    const { spawn } = await import('node:child_process');
+    return await new Promise((resolve) => {
+        const children = runners.map(({ runner }) => spawn(runner.command, runner.args, { stdio: 'inherit' }));
+        const stop = () => children.forEach((c) => c.kill('SIGINT'));
+        process.once('SIGINT', stop);
+        let done = false;
+        const finish = (code) => {
+            if (done)
+                return;
+            done = true;
+            process.removeListener('SIGINT', stop);
+            children.forEach((c) => c.kill('SIGINT'));
+            resolve(code);
+        };
+        // The server is primary — when it exits, tear everything down.
+        children[0]?.on('exit', (code) => finish(code ?? 0));
+        children.forEach((child, i) => child.on('error', (error) => {
+            io.error(`Failed to start ${runners[i]?.label}: ${error.message}`);
+            finish(1);
+        }));
+    });
+}
 /** True if a module specifier resolves from the app's node_modules. */
 async function canResolve(specifier) {
     try {

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { commandsPlugin } from './plugin.js';
 export { consoleIo, memoryIo, renderTable } from './io.js';
 export { parseArgv, type ParsedArgv } from './parse.js';
 export { builtinCommands, routesCommand, routeAllowPattern, UNGUARDED_SCOPE_NOTE, scheduleListCommand, type RouteMetadata, type ScheduleMetadata, } from './builtins.js';
-export { devCommand, resolveDevEntry, resolveDevRunner, devRouteRows, DEV_ENTRY_CANDIDATES, type DevRunner, type DevRoute, } from './dev.js';
+export { devCommand, runDev, bootFailureLines, type RunDevOptions, resolveDevEntry, resolveDevRunner, devRouteRows, DEV_ENTRY_CANDIDATES, type DevRunner, type DevRoute, } from './dev.js';
 export { upgradeCommand, runUpgrade, MIGRATIONS, renameMachizeScope, nodeUpgradeFs, type Migration, type Edit, type UpgradeFs, type UpgradeReport, } from './upgrade.js';
 export { publishCommand, runPublish, PUBLISHABLES, nodePublishFs, type Publishable, type PublishableFile, type PublishFs, type PublishResult, } from './publish.js';
 export { DOCKERFILE, DOCKERIGNORE, CI_WORKFLOW, EDITORCONFIG, PRODUCTION_ENTRY } from './stubs.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export { commandsPlugin } from './plugin.js';
 export { consoleIo, memoryIo, renderTable } from './io.js';
 export { parseArgv } from './parse.js';
 export { builtinCommands, routesCommand, routeAllowPattern, UNGUARDED_SCOPE_NOTE, scheduleListCommand, } from './builtins.js';
-export { devCommand, resolveDevEntry, resolveDevRunner, devRouteRows, DEV_ENTRY_CANDIDATES, } from './dev.js';
+export { devCommand, runDev, bootFailureLines, resolveDevEntry, resolveDevRunner, devRouteRows, DEV_ENTRY_CANDIDATES, } from './dev.js';
 export { upgradeCommand, runUpgrade, MIGRATIONS, renameMachizeScope, nodeUpgradeFs, } from './upgrade.js';
 export { publishCommand, runPublish, PUBLISHABLES, nodePublishFs, } from './publish.js';
 export { DOCKERFILE, DOCKERIGNORE, CI_WORKFLOW, EDITORCONFIG, PRODUCTION_ENTRY } from './stubs.js';

package/dist/launcher.d.ts

@@ -7,6 +7,10 @@
  * app's own package manager — so the code that runs is always the app's, at
  * the versions its lockfile pins, never the launcher's. Node built-ins only:
  * nothing of the framework is loaded.
+ *
+ * One command is the launcher's own: `basalt new <name> [flags]` scaffolds an
+ * app through `create-basalt@latest` (`pnpm dlx`, else `npx`) — the latest
+ * scaffolder, whatever version the launcher is.
  */
 export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
 export interface LauncherProject {
@@ -41,6 +45,17 @@ export interface RunLauncherOptions {
     /** Where the launcher's own lines go (never the app's output). */
     error?: (line: string) => void;
     log?: (line: string) => void;
+    /** Whether pnpm is installed — what `basalt new` runs create-basalt with. Default: `pnpm --version` answers. */
+    hasPnpm?: () => boolean;
 }
+/**
+ * How `basalt new` runs `create-basalt@latest`: through the manager `--pm=`
+ * names, else pnpm when it is installed, else npx. create-basalt reads the
+ * manager it was started with, so the new app uses the same one.
+ */
+export declare function scaffoldCommand(args: readonly string[], hasPnpm: () => boolean): {
+    command: string;
+    args: string[];
+};
 /** Runs `basalt <argv>`: the app's `basalt` script, through the app's package manager. Resolves to the exit code. */
 export declare function runLauncher(argv: readonly string[], options?: RunLauncherOptions): Promise<number>;

package/dist/launcher.js

@@ -7,8 +7,12 @@
  * app's own package manager — so the code that runs is always the app's, at
  * the versions its lockfile pins, never the launcher's. Node built-ins only:
  * nothing of the framework is loaded.
+ *
+ * One command is the launcher's own: `basalt new <name> [flags]` scaffolds an
+ * app through `create-basalt@latest` (`pnpm dlx`, else `npx`) — the latest
+ * scaffolder, whatever version the launcher is.
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 /** Set on the script's environment: a `basalt` script that calls `basalt` again would loop. */
@@ -93,9 +97,24 @@ function launcherVersion() {
         return 'unknown';
     }
 }
+/**
+ * How `basalt new` runs `create-basalt@latest`: through the manager `--pm=`
+ * names, else pnpm when it is installed, else npx. create-basalt reads the
+ * manager it was started with, so the new app uses the same one.
+ */
+export function scaffoldCommand(args, hasPnpm) {
+    const pm = args.find((arg) => arg.startsWith('--pm='))?.slice('--pm='.length);
+    const pkg = 'create-basalt@latest';
+    if (pm === 'pnpm' || (pm === undefined && hasPnpm()))
+        return { command: 'pnpm', args: ['--silent', 'dlx', pkg, ...args] };
+    if (pm === 'bun')
+        return { command: 'bunx', args: [pkg, ...args] };
+    return { command: 'npx', args: ['--yes', pkg, ...args] }; // npm, and yarn (create-basalt honours --pm=yarn)
+}
+const pnpmInstalled = () => spawnSync('pnpm', ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' }).status === 0;
 const NOT_AN_APP = [
     'basalt: no Basalt app here — no package.json with a "basalt" script in this directory or above it.',
-    '  Start one:   npm create basalt@latest my-app',
+    '  Start one:   basalt new my-app',
     '  Or cd into an app first; `basalt <command>` then runs `<pm> basalt <command>` there.',
 ];
 /** Runs `basalt <argv>`: the app's `basalt` script, through the app's package manager. Resolves to the exit code. */
@@ -104,6 +123,11 @@ export async function runLauncher(argv, options = {}) {
     const env = options.env ?? process.env;
     const error = options.error ?? ((line) => process.stderr.write(`${line}\n`));
     const log = options.log ?? ((line) => process.stdout.write(`${line}\n`));
+    // The launcher's own command, inside an app too: a new app is never the current one's business.
+    if (argv[0] === 'new') {
+        const scaffold = scaffoldCommand(argv.slice(1), options.hasPnpm ?? pnpmInstalled);
+        return spawnAndWait(scaffold.command, scaffold.args, { cwd, env, error, what: 'create a new app' });
+    }
     const project = findProject(cwd);
     if (!project) {
         if (argv[0] === '--version' || argv[0] === '-v') {
@@ -120,14 +144,24 @@ export async function runLauncher(argv, options = {}) {
         return 1;
     }
     const { command, args } = launchCommand(project.pm, argv);
+    return spawnAndWait(command, args, {
+        cwd: project.root,
+        env: { ...env, [LAUNCHER_ENV]: project.root },
+        error,
+        what: `run this app's basalt script (${project.root})`,
+    });
+}
+/** Runs one command with the terminal attached; resolves to its exit code. */
+function spawnAndWait(command, args, options) {
+    const { error } = options;
     return new Promise((done) => {
         const child = spawn(command, args, {
-            cwd: project.root,
-            env: { ...env, [LAUNCHER_ENV]: project.root },
+            cwd: options.cwd,
+            env: options.env,
             stdio: 'inherit',
             shell: process.platform === 'win32',
         });
-        // Ctrl-C reaches the whole foreground group: the app handles it; the
+        // Ctrl-C reaches the whole foreground group: the child handles it; the
         // launcher only waits for it to finish and reports its code.
         const ignore = () => { };
         const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
@@ -140,7 +174,7 @@ export async function runLauncher(argv, options = {}) {
         };
         child.on('error', (cause) => {
             error(cause.code === 'ENOENT'
-                ? `basalt: ${command} is not installed, and this app uses it (${project.root}).`
+                ? `basalt: ${command} is not installed, and it is needed to ${options.what}.`
                 : `basalt: could not start ${command}: ${cause.message}`);
             settle(1);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cli",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "engines": {
     "node": ">=22.5.0"
   },