@basaltkit/cli 1.5.0 → 1.6.0

package/README.md

@@ -110,7 +110,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/package.json

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