@basaltkit/cli 1.4.2 → 1.6.0

package/README.md

@@ -24,6 +24,23 @@ pnpm add @basaltkit/cli
 
 > Note: the package depends on `@basaltkit/core` (the heart of the framework, where `createApp` and the dependency container live). If you created the project with `create-basalt --cli`, both are already installed.
 
+### The global `basalt` launcher
+
+Inside an app, `basalt` is a `package.json` script: `pnpm basalt <command>`.
+Install the launcher once to type `basalt <command>` instead:
+
+```bash
+npm i -g @basaltkit/cli
+basalt routes        # anywhere inside the app = pnpm basalt routes, in the app's root
+```
+
+It finds the nearest `package.json` with a `basalt` script, from the current
+directory up, and runs that script with the app's package manager
+(`packageManager`, else the lockfile). So the code that runs is always the
+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.
+
 ## 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:
@@ -93,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/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runLauncher } from './launcher.js';
+process.exitCode = await runLauncher(process.argv.slice(2));

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

@@ -0,0 +1,46 @@
+/**
+ * The global `basalt` launcher: `npm i -g @basaltkit/cli`, then `basalt <command>`
+ * anywhere inside an app does what `pnpm basalt <command>` does there.
+ *
+ * It never runs commands itself. It finds the app (the nearest package.json
+ * with a `basalt` script) and hands the arguments to that script through the
+ * 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.
+ */
+export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+export interface LauncherProject {
+    /** The directory whose package.json declares the `basalt` script. */
+    root: string;
+    /** The script itself, e.g. `tsx bin/basalt.ts`. */
+    script: string;
+    pm: PackageManager;
+}
+/** Set on the script's environment: a `basalt` script that calls `basalt` again would loop. */
+export declare const LAUNCHER_ENV = "BASALT_LAUNCHER_ROOT";
+/** The nearest app at or above `from`: a package.json with a `basalt` script. */
+export declare function findProject(from: string): LauncherProject | undefined;
+/**
+ * `packageManager` in the nearest package.json that has one, else the nearest
+ * lockfile — both walking up, so an app inside a workspace uses the
+ * workspace's manager. Nothing found: npm.
+ */
+export declare function detectPackageManager(root: string): PackageManager;
+/**
+ * The command that runs the app's `basalt` script with `args`, as given:
+ * pnpm, yarn and bun pass everything after the script name through (a `--`
+ * included); npm needs a `--` first.
+ */
+export declare function launchCommand(pm: PackageManager, args: readonly string[]): {
+    command: string;
+    args: string[];
+};
+export interface RunLauncherOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Where the launcher's own lines go (never the app's output). */
+    error?: (line: string) => void;
+    log?: (line: string) => void;
+}
+/** 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

@@ -0,0 +1,154 @@
+/**
+ * The global `basalt` launcher: `npm i -g @basaltkit/cli`, then `basalt <command>`
+ * anywhere inside an app does what `pnpm basalt <command>` does there.
+ *
+ * It never runs commands itself. It finds the app (the nearest package.json
+ * with a `basalt` script) and hands the arguments to that script through the
+ * 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.
+ */
+import { spawn } 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. */
+export const LAUNCHER_ENV = 'BASALT_LAUNCHER_ROOT';
+function readManifest(dir) {
+    const file = join(dir, 'package.json');
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof value === 'object' && value !== null ? value : undefined;
+    }
+    catch {
+        return undefined; // an unreadable package.json is not an app: keep walking
+    }
+}
+/** Every directory from `from` up to the filesystem root, nearest first. */
+function* ancestors(from) {
+    let dir = resolve(from);
+    while (true) {
+        yield dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return;
+        dir = parent;
+    }
+}
+/** The nearest app at or above `from`: a package.json with a `basalt` script. */
+export function findProject(from) {
+    for (const dir of ancestors(from)) {
+        const script = readManifest(dir)?.scripts?.['basalt'];
+        if (typeof script === 'string' && script.trim() !== '') {
+            return { root: dir, script, pm: detectPackageManager(dir) };
+        }
+    }
+    return undefined;
+}
+const LOCKFILES = [
+    ['pnpm', ['pnpm-lock.yaml']],
+    ['bun', ['bun.lock', 'bun.lockb']],
+    ['yarn', ['yarn.lock']],
+    ['npm', ['package-lock.json']],
+];
+/**
+ * `packageManager` in the nearest package.json that has one, else the nearest
+ * lockfile — both walking up, so an app inside a workspace uses the
+ * workspace's manager. Nothing found: npm.
+ */
+export function detectPackageManager(root) {
+    for (const dir of ancestors(root)) {
+        const declared = readManifest(dir)?.packageManager;
+        if (typeof declared === 'string') {
+            const name = declared.split('@')[0];
+            if (name === 'pnpm' || name === 'npm' || name === 'yarn' || name === 'bun')
+                return name;
+        }
+        for (const [pm, files] of LOCKFILES)
+            if (files.some((file) => existsSync(join(dir, file))))
+                return pm;
+    }
+    return 'npm';
+}
+/**
+ * The command that runs the app's `basalt` script with `args`, as given:
+ * pnpm, yarn and bun pass everything after the script name through (a `--`
+ * included); npm needs a `--` first.
+ */
+export function launchCommand(pm, args) {
+    switch (pm) {
+        case 'pnpm': return { command: 'pnpm', args: ['run', '--silent', 'basalt', ...args] };
+        case 'npm': return { command: 'npm', args: ['run', '--silent', 'basalt', '--', ...args] };
+        case 'yarn': return { command: 'yarn', args: ['run', 'basalt', ...args] };
+        case 'bun': return { command: 'bun', args: ['run', 'basalt', ...args] };
+    }
+}
+function launcherVersion() {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return manifest.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+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',
+    '  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. */
+export async function runLauncher(argv, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    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`));
+    const project = findProject(cwd);
+    if (!project) {
+        if (argv[0] === '--version' || argv[0] === '-v') {
+            log(`basalt launcher ${launcherVersion()} (@basaltkit/cli)`);
+            return 0;
+        }
+        for (const line of NOT_AN_APP)
+            error(line);
+        return 1;
+    }
+    if (env[LAUNCHER_ENV] === project.root) {
+        error(`basalt: the "basalt" script in ${join(project.root, 'package.json')} runs \`basalt\` again (${project.script}).`);
+        error('  Point it at the app\'s own CLI instead, e.g. "basalt": "tsx bin/basalt.ts".');
+        return 1;
+    }
+    const { command, args } = launchCommand(project.pm, argv);
+    return new Promise((done) => {
+        const child = spawn(command, args, {
+            cwd: project.root,
+            env: { ...env, [LAUNCHER_ENV]: project.root },
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        // Ctrl-C reaches the whole foreground group: the app handles it; the
+        // launcher only waits for it to finish and reports its code.
+        const ignore = () => { };
+        const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+        for (const signal of signals)
+            process.on(signal, ignore);
+        const settle = (code) => {
+            for (const signal of signals)
+                process.off(signal, ignore);
+            done(code);
+        };
+        child.on('error', (cause) => {
+            error(cause.code === 'ENOENT'
+                ? `basalt: ${command} is not installed, and this app uses it (${project.root}).`
+                : `basalt: could not start ${command}: ${cause.message}`);
+            settle(1);
+        });
+        child.on('exit', (code, signal) => {
+            settle(code ?? (signal ? 128 + signalNumber(signal) : 1));
+        });
+    });
+}
+function signalNumber(signal) {
+    return { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 }[signal] ?? 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cli",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -14,6 +14,9 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": {
+    "basalt": "./dist/bin.js"
+  },
   "files": [
     "dist"
   ],
@@ -22,9 +25,9 @@
     "@basaltkit/http": "^3.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.5",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.1",
+    "vitest": "^5.0.5",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {