@basaltkit/cli 1.2.0 → 1.2.2

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/cli
 
 Terminal command framework (the `basalt` command) for Basalt applications: define your own commands, run them against the already-booted application, and inspect HTTP routes and scheduled tasks. You need it when you want to give your application its own "command line" — for example `basalt routes` or `basalt db:seed`.
@@ -203,6 +209,8 @@ A Basalt plugin that registers the commands in the `'commands'` metadata bucket,
 
 A minimal argument parser: the first "loose" word is the command; `--key=value` and `--flag` become flags. Returns `{ command: string | undefined, args: string[], flags: Record<string, string | boolean> }`.
 
+A bare `--no-<name>` is the conventional **negation**: it yields `flags['<name>'] === false`, not `flags['no-<name>'] === true`. That is what makes documented opt-outs such as `basalt dev --no-routes` take effect — commands test `flags['routes'] !== false`. Only the bare form negates: `--no-cache=x` still parses as the literal key `no-cache`.
+
 ### `consoleIo(): CommandIo`
 
 A `CommandIo` implementation that writes to the console (`console.log` / `console.error`; `table` renders via `renderTable`). It's the default for `runCli`.

package/dist/builtins.d.ts

@@ -0,0 +1,16 @@
+import { type CommandDefinition } from './command.js';
+/** Route entries written by HTTP adapters into the 'http:routes' bucket. */
+export interface RouteMetadata {
+    method: string;
+    url: string;
+    [key: string]: unknown;
+}
+/** Schedule entries written by the scheduler into the 'schedule:entries' bucket. */
+export interface ScheduleMetadata {
+    name: string;
+    cron: string;
+    timezone: string;
+}
+export declare const routesCommand: CommandDefinition;
+export declare const scheduleListCommand: CommandDefinition;
+export declare function builtinCommands(): CommandDefinition[];

package/dist/builtins.js

@@ -0,0 +1,36 @@
+import { METADATA } from '@basaltkit/core';
+import { defineCommand } from './command.js';
+import { devCommand } from './dev.js';
+import { upgradeCommand } from './upgrade.js';
+import { publishCommand } from './publish.js';
+export const routesCommand = defineCommand({
+    name: 'routes',
+    description: 'List the HTTP routes registered by the app',
+    handle({ container, io }) {
+        const routes = container.has(METADATA)
+            ? container.get(METADATA).get('http:routes')
+            : [];
+        if (routes.length === 0) {
+            io.log('No routes registered.');
+            return;
+        }
+        io.table(routes.map(({ method, url }) => ({ method, url })));
+    },
+});
+export const scheduleListCommand = defineCommand({
+    name: 'schedule:list',
+    description: 'List scheduled tasks and their cron expressions',
+    handle({ container, io }) {
+        const entries = container.has(METADATA)
+            ? container.get(METADATA).get('schedule:entries')
+            : [];
+        if (entries.length === 0) {
+            io.log('No scheduled tasks.');
+            return;
+        }
+        io.table(entries.map(({ name, cron, timezone }) => ({ name, cron, timezone })));
+    },
+});
+export function builtinCommands() {
+    return [routesCommand, scheduleListCommand, devCommand, upgradeCommand, publishCommand];
+}

package/dist/command.d.ts

@@ -0,0 +1,25 @@
+import type { Container, BasaltApp } from '@basaltkit/core';
+/** Output surface — swappable in tests to capture what a command prints. */
+export interface CommandIo {
+    log(message: string): void;
+    error(message: string): void;
+    table(rows: Record<string, unknown>[]): void;
+    /** Ask a yes/no question. Resolves true only on an explicit yes. */
+    confirm(question: string): Promise<boolean>;
+}
+export interface CommandContext {
+    app: BasaltApp;
+    container: Container;
+    io: CommandIo;
+    /** Positional arguments after the command name. */
+    args: string[];
+    /** Parsed flags: `--key=value` → string, `--flag` → true. */
+    flags: Record<string, string | boolean>;
+}
+export interface CommandDefinition {
+    /** Command name, by convention `noun:verb` (e.g. `tenant:migrate`). */
+    name: string;
+    description?: string;
+    handle(context: CommandContext): void | number | Promise<void | number>;
+}
+export declare function defineCommand(command: CommandDefinition): CommandDefinition;

package/dist/command.js

@@ -0,0 +1,3 @@
+export function defineCommand(command) {
+    return command;
+}

package/dist/dev.d.ts

@@ -0,0 +1,49 @@
+import { type CommandDefinition } from './command.js';
+/** Default entry files probed in order when `--entry` is not given. */
+export declare const DEV_ENTRY_CANDIDATES: string[];
+/**
+ * Picks the first candidate that exists. Pure — `exists` is injected so the
+ * resolution is testable without touching disk.
+ */
+export declare function resolveDevEntry(candidates: string[], exists: (path: string) => boolean): string | undefined;
+export interface DevRunner {
+    command: string;
+    args: string[];
+}
+/**
+ * Chooses how to run the entry with watch/restart, delegating the actual
+ * watching to the runtime (no bespoke watcher). Pure and testable:
+ *
+ * - `.ts` with tsx available → `tsx watch <entry>`
+ * - `.ts` without tsx        → `node --watch --experimental-strip-types <entry>` (Node ≥ 22.6)
+ * - `.js`                     → `node --watch <entry>`
+ */
+export declare function resolveDevRunner(entry: string, options?: {
+    tsx?: boolean;
+}): DevRunner;
+/** A route as published into the `http:routes` metadata bucket by an adapter. */
+export interface DevRoute {
+    method: string;
+    url: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Formats the registered routes into printable rows (method, url, and a compact
+ * flags column for auth/rate-limit) — sorted by url then method. Pure: this is
+ * what `basalt dev` prints on boot, and `pnpm dev` (plain tsx watch) can't.
+ */
+export declare function devRouteRows(routes: DevRoute[]): {
+    method: string;
+    url: string;
+    flags: string;
+}[];
+/**
+ * `basalt dev [--entry=<file>] [--worker] [--queue=<name>] [--no-routes]`
+ *
+ * A richer dev loop than a bare `tsx watch`: prints the app's **route table** on
+ * boot (the app is already booted by the CLI runner, so routes are known), then
+ * 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).
+ */
+export declare const devCommand: CommandDefinition;

package/dist/dev.js

@@ -0,0 +1,126 @@
+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'];
+/**
+ * Picks the first candidate that exists. Pure — `exists` is injected so the
+ * resolution is testable without touching disk.
+ */
+export function resolveDevEntry(candidates, exists) {
+    return candidates.find(exists);
+}
+/**
+ * Chooses how to run the entry with watch/restart, delegating the actual
+ * watching to the runtime (no bespoke watcher). Pure and testable:
+ *
+ * - `.ts` with tsx available → `tsx watch <entry>`
+ * - `.ts` without tsx        → `node --watch --experimental-strip-types <entry>` (Node ≥ 22.6)
+ * - `.js`                     → `node --watch <entry>`
+ */
+export function resolveDevRunner(entry, options = {}) {
+    const isTs = /\.tsx?$/.test(entry);
+    if (isTs && options.tsx)
+        return { command: 'tsx', args: ['watch', entry] };
+    if (isTs)
+        return { command: 'node', args: ['--watch', '--experimental-strip-types', entry] };
+    return { command: 'node', args: ['--watch', entry] };
+}
+/**
+ * Formats the registered routes into printable rows (method, url, and a compact
+ * flags column for auth/rate-limit) — sorted by url then method. Pure: this is
+ * what `basalt dev` prints on boot, and `pnpm dev` (plain tsx watch) can't.
+ */
+export function devRouteRows(routes) {
+    return [...routes]
+        .sort((a, b) => a.url.localeCompare(b.url) || a.method.localeCompare(b.method))
+        .map((r) => {
+        const flags = [];
+        if (r.meta?.['auth'] === true)
+            flags.push('auth');
+        if (r.meta?.['rateLimit'])
+            flags.push('rate-limit');
+        const tags = r.meta?.['tags'];
+        if (Array.isArray(tags) && tags.length)
+            flags.push(...tags.map(String));
+        return { method: r.method.toUpperCase(), url: r.url, flags: flags.join(', ') };
+    });
+}
+/**
+ * `basalt dev [--entry=<file>] [--worker] [--queue=<name>] [--no-routes]`
+ *
+ * A richer dev loop than a bare `tsx watch`: prints the app's **route table** on
+ * boot (the app is already booted by the CLI runner, so routes are known), then
+ * 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).
+ */
+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>.`);
+            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);
+            }));
+        });
+    },
+});
+/** True if a module specifier resolves from the app's node_modules. */
+async function canResolve(specifier) {
+    try {
+        const { createRequire } = await import('node:module');
+        createRequire(`${process.cwd()}/`).resolve(specifier);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -1,217 +1,9 @@
-import * as _basaltkit_core from '@basaltkit/core';
-import { BasaltApp, Container } from '@basaltkit/core';
-
-/** Output surface — swappable in tests to capture what a command prints. */
-interface CommandIo {
-    log(message: string): void;
-    error(message: string): void;
-    table(rows: Record<string, unknown>[]): void;
-    /** Ask a yes/no question. Resolves true only on an explicit yes. */
-    confirm(question: string): Promise<boolean>;
-}
-interface CommandContext {
-    app: BasaltApp;
-    container: Container;
-    io: CommandIo;
-    /** Positional arguments after the command name. */
-    args: string[];
-    /** Parsed flags: `--key=value` → string, `--flag` → true. */
-    flags: Record<string, string | boolean>;
-}
-interface CommandDefinition {
-    /** Command name, by convention `noun:verb` (e.g. `tenant:migrate`). */
-    name: string;
-    description?: string;
-    handle(context: CommandContext): void | number | Promise<void | number>;
-}
-declare function defineCommand(command: CommandDefinition): CommandDefinition;
-
-interface RunCliOptions {
-    app: BasaltApp;
-    /** Defaults to process.argv.slice(2). */
-    argv?: string[];
-    /** Defaults to console output — swap in tests. */
-    io?: CommandIo;
-}
-/**
- * Boots the app, resolves the command (built-ins + everything registered in
- * the 'commands' metadata bucket), runs it and shuts the app down.
- * Returns the process exit code instead of calling process.exit — the bin
- * wrapper decides what to do with it.
- */
-declare function runCli(options: RunCliOptions): Promise<number>;
-
-/** Registers app-defined commands into the 'commands' metadata bucket. */
-declare function commandsPlugin(commands: CommandDefinition[]): _basaltkit_core.BasaltPlugin<unknown>;
-
-/** Renders rows as an aligned text table (no external dependencies). */
-declare function renderTable(rows: Record<string, unknown>[]): string;
-declare function consoleIo(): CommandIo;
-/**
- * In-memory IO for tests. `answers` feeds `confirm()` in order (defaults to yes
- * once the queue is drained), so a test can drive an interactive command.
- */
-declare function memoryIo(options?: {
-    answers?: boolean[];
-}): CommandIo & {
-    lines: string[];
-    errors: string[];
-};
-
-interface ParsedArgv {
-    command: string | undefined;
-    args: string[];
-    flags: Record<string, string | boolean>;
-}
-/** Minimal argv parser: first bare word is the command; `--key=value` and `--flag` become flags. */
-declare function parseArgv(argv: string[]): ParsedArgv;
-
-/** Route entries written by HTTP adapters into the 'http:routes' bucket. */
-interface RouteMetadata {
-    method: string;
-    url: string;
-    [key: string]: unknown;
-}
-/** Schedule entries written by the scheduler into the 'schedule:entries' bucket. */
-interface ScheduleMetadata {
-    name: string;
-    cron: string;
-    timezone: string;
-}
-declare const routesCommand: CommandDefinition;
-declare const scheduleListCommand: CommandDefinition;
-declare function builtinCommands(): CommandDefinition[];
-
-/** Default entry files probed in order when `--entry` is not given. */
-declare const DEV_ENTRY_CANDIDATES: string[];
-/**
- * Picks the first candidate that exists. Pure — `exists` is injected so the
- * resolution is testable without touching disk.
- */
-declare function resolveDevEntry(candidates: string[], exists: (path: string) => boolean): string | undefined;
-interface DevRunner {
-    command: string;
-    args: string[];
-}
-/**
- * Chooses how to run the entry with watch/restart, delegating the actual
- * watching to the runtime (no bespoke watcher). Pure and testable:
- *
- * - `.ts` with tsx available → `tsx watch <entry>`
- * - `.ts` without tsx        → `node --watch --experimental-strip-types <entry>` (Node ≥ 22.6)
- * - `.js`                     → `node --watch <entry>`
- */
-declare function resolveDevRunner(entry: string, options?: {
-    tsx?: boolean;
-}): DevRunner;
-/** A route as published into the `http:routes` metadata bucket by an adapter. */
-interface DevRoute {
-    method: string;
-    url: string;
-    meta?: Record<string, unknown>;
-}
-/**
- * Formats the registered routes into printable rows (method, url, and a compact
- * flags column for auth/rate-limit) — sorted by url then method. Pure: this is
- * what `basalt dev` prints on boot, and `pnpm dev` (plain tsx watch) can't.
- */
-declare function devRouteRows(routes: DevRoute[]): {
-    method: string;
-    url: string;
-    flags: string;
-}[];
-/**
- * `basalt dev [--entry=<file>] [--worker] [--queue=<name>] [--no-routes]`
- *
- * A richer dev loop than a bare `tsx watch`: prints the app's **route table** on
- * boot (the app is already booted by the CLI runner, so routes are known), then
- * 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).
- */
-declare const devCommand: CommandDefinition;
-
-/**
- * Filesystem surface an upgrade migration works against. Injected so migrations
- * (and `runUpgrade`) are testable with an in-memory tree — no disk needed.
- */
-interface UpgradeFs {
-    /** Recursively lists files under `dir` (relative paths). Skips node_modules/dist/.git. */
-    list(dir: string): Promise<string[]>;
-    read(path: string): Promise<string>;
-    write(path: string, content: string): Promise<void>;
-}
-/** A single edit a migration wants to make — surfaced for `--dry` before writing. */
-interface Edit {
-    path: string;
-    before: string;
-    after: string;
-}
-/** A versioned, idempotent codemod. `plan` computes edits without writing them. */
-interface Migration {
-    id: string;
-    description: string;
-    plan(fs: UpgradeFs, dir: string): Promise<Edit[]>;
-}
-interface UpgradeReport {
-    migration: string;
-    changed: string[];
-}
-/**
- * A codemod that rewrites the deprecated `@machize/*` npm scope to `@basaltkit/*`
- * across package.json and source imports. Unambiguous (scoped rename), so a plain
- * text replace is safe and idempotent.
- */
-declare const renameMachizeScope: Migration;
-/** All migrations shipped with the CLI, in application order. */
-declare const MIGRATIONS: Migration[];
-/**
- * Runs the selected migrations. With `dry`, computes and reports edits without
- * writing. Returns a per-migration report of the files it changed.
- */
-declare function runUpgrade(migrations: Migration[], fs: UpgradeFs, options: {
-    dir: string;
-    dry?: boolean;
-    only?: string;
-}): Promise<UpgradeReport[]>;
-/** Node-backed {@link UpgradeFs}. Recursive, skipping build/vcs directories. */
-declare function nodeUpgradeFs(): UpgradeFs;
-/** `basalt upgrade [--dir=<path>] [--dry] [--only=<migration-id>]` */
-declare const upgradeCommand: CommandDefinition;
-
-/** One file a publishable drops into the app. */
-interface PublishableFile {
-    /** Path relative to the target dir, e.g. `Dockerfile` or `.github/workflows/ci.yml`. */
-    path: string;
-    content: string;
-}
-/** A named group of stub files an app can copy in and then own (à la vendor:publish). */
-interface Publishable {
-    id: string;
-    description: string;
-    files(): PublishableFile[];
-}
-/** Filesystem surface for publishing — injected so `runPublish` is testable. */
-interface PublishFs {
-    exists(path: string): Promise<boolean>;
-    write(path: string, content: string): Promise<void>;
-}
-interface PublishResult {
-    written: string[];
-    skipped: string[];
-}
-/** Stubs bundled with the CLI. Apps can register more via the metadata bucket. */
-declare const PUBLISHABLES: Publishable[];
-/**
- * Copies a publishable's files into the target, skipping any that already exist
- * unless `force` is set. Returns which files were written vs skipped.
- */
-declare function runPublish(publishable: Publishable, fs: PublishFs, options?: {
-    force?: boolean;
-}): Promise<PublishResult>;
-/** Node-backed {@link PublishFs} rooted at `dir` (creates parent directories). */
-declare function nodePublishFs(dir: string): PublishFs;
-/** `basalt publish [<id>] [--dir=<path>] [--force]` — list, or copy a stub group. */
-declare const publishCommand: CommandDefinition;
-
-export { type CommandContext, type CommandDefinition, type CommandIo, DEV_ENTRY_CANDIDATES, type DevRoute, type DevRunner, type Edit, MIGRATIONS, type Migration, PUBLISHABLES, type ParsedArgv, type PublishFs, type PublishResult, type Publishable, type PublishableFile, type RouteMetadata, type RunCliOptions, type ScheduleMetadata, type UpgradeFs, type UpgradeReport, builtinCommands, commandsPlugin, consoleIo, defineCommand, devCommand, devRouteRows, memoryIo, nodePublishFs, nodeUpgradeFs, parseArgv, publishCommand, renameMachizeScope, renderTable, resolveDevEntry, resolveDevRunner, routesCommand, runCli, runPublish, runUpgrade, scheduleListCommand, upgradeCommand };
+export { defineCommand, type CommandDefinition, type CommandContext, type CommandIo } from './command.js';
+export { runCli, type RunCliOptions } from './runner.js';
+export { commandsPlugin } from './plugin.js';
+export { consoleIo, memoryIo, renderTable } from './io.js';
+export { parseArgv, type ParsedArgv } from './parse.js';
+export { builtinCommands, routesCommand, scheduleListCommand, type RouteMetadata, type ScheduleMetadata, } from './builtins.js';
+export { devCommand, 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';