@rsc-kit/core 0.30.15 → 0.30.16

package/README.md

@@ -28,7 +28,9 @@ is underneath:
   `await rpc('Orders.recent')`, typed from the backend's own signatures. See
   [Backend-Answered Pages](https://docs.rsc-kit.dev/hosts/backend-answered-pages).
 - **It compiles to a single binary** with `bun build --compile`, assets and
-  frozen pages inside it.
+  frozen pages inside it. A file in `src/commands` is a release step or a
+  worker in the same binary: `./app migrate`
+  ([guide](https://docs.rsc-kit.dev/guides/commands)).
 
 ## Setup
 

package/dist/commandFiles.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The build's half of app commands: which files in `src/commands` are
+ * commands, what the generated entry says about them, and the small entries
+ * that run one. The runner they call is `commands.ts`.
+ */
+export interface CommandFile {
+    /** What is typed after the binary: the file's name without its extension. */
+    name: string;
+    /** Absolute path, imported lazily by the entry. */
+    file: string;
+    /** A plain string literal exported as `description`, for `--help`. */
+    description?: string;
+}
+export interface CommandFiles {
+    commands: CommandFile[];
+    /** Paths under src/commands that are not commands, and why, for the build to say. */
+    ignored: {
+        path: string;
+        reason: string;
+    }[];
+}
+/**
+ * The commands under `<sourceDir>/commands`.
+ *
+ * Flat on purpose: a name is what a person types, and `db/seed.ts` raises
+ * whether that is `db:seed`, `db/seed` or `seed`. Declaration files, tests and
+ * anything starting with `_` or `.` are not commands - the last is how a
+ * helper lives beside the commands that share it.
+ */
+export declare function commandFiles(sourceDir: string): CommandFiles;
+/** The module the generated entry reads the table from, resolved when the bundle is built. */
+export declare const COMMANDS_MODULE_ID = "virtual:rsc-kit/commands";
+/**
+ * The table: every command as a dynamic import, so each is a chunk of its own
+ * and the server never evaluates one. An empty object when there are none -
+ * a Worker's build, say, which does not carry them.
+ *
+ * A module of its own rather than text in the entry because the entry is
+ * written while the config is still being read, before anything knows the
+ * build's mode or which Nitro preset it is for.
+ */
+export declare function commandsModule(commands: readonly CommandFile[]): string;
+/**
+ * What the generated server entry adds for an app with a `src/commands`:
+ * `runCommand` over the table, with the entry's own `register()` and
+ * `shutdown()`. `runner` is the engine's `commands` module, named without an
+ * extension like every other engine module the entry imports.
+ */
+export declare function commandsEntry(runner: string): string;
+/**
+ * The entry a plain build runs a command from, written beside the server:
+ *
+ *     node .output/server/commands.mjs migrate
+ *     bun .output/server/commands.mjs migrate
+ *
+ * The server is not started - nothing here imports it - and the flag is set
+ * before the entry is imported, since importing it is what would otherwise
+ * call register().
+ */
+export declare function commandsEntrySource(): string;

package/dist/commandFiles.js

@@ -0,0 +1,136 @@
+/**
+ * The build's half of app commands: which files in `src/commands` are
+ * commands, what the generated entry says about them, and the small entries
+ * that run one. The runner they call is `commands.ts`.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+/** Earlier wins when two files share a name: migrate.ts over migrate.js. */
+const EXTENSION_ORDER = ['ts', 'mts', 'cts', 'tsx', 'js', 'mjs', 'cjs', 'jsx'];
+/**
+ * `export const description = 'Apply the database migrations'`, read off the
+ * source so `--help` can list a command without loading it - a command's
+ * imports are the database and the logger, and listing should not open either.
+ * A plain string literal only; anything computed is simply not listed.
+ */
+function describe(source) {
+    const match = /^\s*export\s+const\s+description\s*(?::\s*string\s*)?=\s*(["'`])([^"'`\\\n$]*)\1/m.exec(source);
+    return match?.[2]?.trim() || undefined;
+}
+/**
+ * The commands under `<sourceDir>/commands`.
+ *
+ * Flat on purpose: a name is what a person types, and `db/seed.ts` raises
+ * whether that is `db:seed`, `db/seed` or `seed`. Declaration files, tests and
+ * anything starting with `_` or `.` are not commands - the last is how a
+ * helper lives beside the commands that share it.
+ */
+export function commandFiles(sourceDir) {
+    const dir = join(sourceDir, 'commands');
+    const found = { commands: [], ignored: [] };
+    if (!existsSync(dir))
+        return found;
+    const taken = new Map();
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.name.startsWith('_') || entry.name.startsWith('.'))
+            continue;
+        if (entry.isDirectory()) {
+            found.ignored.push({ path, reason: 'commands are the files directly in src/commands, not a folder of them' });
+            continue;
+        }
+        if (!SOURCE.test(entry.name) || /\.d\.[cm]?ts$/.test(entry.name) || /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(entry.name))
+            continue;
+        const extension = entry.name.slice(entry.name.lastIndexOf('.') + 1);
+        const name = entry.name.slice(0, -(extension.length + 1));
+        if (!NAME.test(name)) {
+            found.ignored.push({ path, reason: `"${name}" cannot be typed as a command: letters, digits, "-", "_", "." and ":"` });
+            continue;
+        }
+        const existing = taken.get(name);
+        if (existing) {
+            const keep = EXTENSION_ORDER.indexOf(existing.file.split('.').pop() ?? '') <= EXTENSION_ORDER.indexOf(extension);
+            found.ignored.push({
+                path: keep ? path : existing.file,
+                reason: `two files are called "${name}"; ${keep ? existing.file : path} is the command`,
+            });
+            if (keep)
+                continue;
+            found.commands.splice(found.commands.indexOf(existing), 1);
+        }
+        const command = { name, file: path, description: describe(readFileSync(path, 'utf-8')) };
+        taken.set(name, command);
+        found.commands.push(command);
+    }
+    return found;
+}
+/** The module the generated entry reads the table from, resolved when the bundle is built. */
+export const COMMANDS_MODULE_ID = 'virtual:rsc-kit/commands';
+/**
+ * The table: every command as a dynamic import, so each is a chunk of its own
+ * and the server never evaluates one. An empty object when there are none -
+ * a Worker's build, say, which does not carry them.
+ *
+ * A module of its own rather than text in the entry because the entry is
+ * written while the config is still being read, before anything knows the
+ * build's mode or which Nitro preset it is for.
+ */
+export function commandsModule(commands) {
+    const rows = commands.map(({ name, file, description }) => `  ${JSON.stringify(name)}: { load: () => import(${JSON.stringify(file)})${description ? `, description: ${JSON.stringify(description)}` : ''} },`);
+    return `export const commands = {\n${rows.join('\n')}\n}\n`;
+}
+/**
+ * What the generated server entry adds for an app with a `src/commands`:
+ * `runCommand` over the table, with the entry's own `register()` and
+ * `shutdown()`. `runner` is the engine's `commands` module, named without an
+ * extension like every other engine module the entry imports.
+ */
+export function commandsEntry(runner) {
+    return `
+import { commands as __commands } from ${JSON.stringify(COMMANDS_MODULE_ID)}
+import { runCommand as __runCommand } from ${JSON.stringify(runner)}
+
+// src/commands, each loaded only when it is named.
+export function runCommand(argv: string[], program?: string) {
+  return __runCommand(argv, { commands: __commands, program, ready: instrumented, shutdown: __instrumentation.shutdown })
+}
+`;
+}
+/**
+ * The entry a plain build runs a command from, written beside the server:
+ *
+ *     node .output/server/commands.mjs migrate
+ *     bun .output/server/commands.mjs migrate
+ *
+ * The server is not started - nothing here imports it - and the flag is set
+ * before the entry is imported, since importing it is what would otherwise
+ * call register().
+ */
+export function commandsEntrySource() {
+    return ('// Run one of the app\'s commands without starting the server:\n' +
+        '//   node .output/server/commands.mjs <command> [args]\n' +
+        '//   bun .output/server/commands.mjs <command> [args]\n' +
+        'import { relative } from "node:path";\n' +
+        'import { fileURLToPath } from "node:url";\n' +
+        '\n' +
+        'globalThis[Symbol.for("rsc-kit.command")] = true;\n' +
+        '\n' +
+        'let code = 1;\n' +
+        '\n' +
+        'try {\n' +
+        '  const { runCommand } = await import("./_ssr/rsc.mjs");\n' +
+        '  const runtime = process.versions.bun ? "bun" : "node";\n' +
+        '\n' +
+        '  code = await runCommand(process.argv.slice(2), runtime + " " + relative(process.cwd(), fileURLToPath(import.meta.url)));\n' +
+        '} catch (error) {\n' +
+        '  // The app failed to load: instrumentation.ts refusing a bad environment,\n' +
+        '  // as it would stop the server.\n' +
+        '  console.error("[rsc-kit] the app failed to load:", error);\n' +
+        '}\n' +
+        '\n' +
+        'process.exit(code);\n');
+}
+//# sourceMappingURL=commandFiles.js.map

package/dist/commandFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandFiles.js","sourceRoot":"","sources":["../src/commandFiles.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The build's half of app commands: which files in `src/commands` are\n * commands, what the generated entry says about them, and the small entries\n * that run one. The runner they call is `commands.ts`.\n */\n\nimport { existsSync, readdirSync, readFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nexport interface CommandFile {\n  /** What is typed after the binary: the file's name without its extension. */\n  name: string\n  /** Absolute path, imported lazily by the entry. */\n  file: string\n  /** A plain string literal exported as `description`, for `--help`. */\n  description?: string\n}\n\nexport interface CommandFiles {\n  commands: CommandFile[]\n  /** Paths under src/commands that are not commands, and why, for the build to say. */\n  ignored: { path: string; reason: string }[]\n}\n\nconst SOURCE = /\\.(?:[cm]?[jt]sx?)$/\nconst NAME = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/\n\n/** Earlier wins when two files share a name: migrate.ts over migrate.js. */\nconst EXTENSION_ORDER = ['ts', 'mts', 'cts', 'tsx', 'js', 'mjs', 'cjs', 'jsx']\n\n/**\n * `export const description = 'Apply the database migrations'`, read off the\n * source so `--help` can list a command without loading it - a command's\n * imports are the database and the logger, and listing should not open either.\n * A plain string literal only; anything computed is simply not listed.\n */\nfunction describe(source: string): string | undefined {\n  const match = /^\\s*export\\s+const\\s+description\\s*(?::\\s*string\\s*)?=\\s*([\"'`])([^\"'`\\\\\\n$]*)\\1/m.exec(source)\n\n  return match?.[2]?.trim() || undefined\n}\n\n/**\n * The commands under `<sourceDir>/commands`.\n *\n * Flat on purpose: a name is what a person types, and `db/seed.ts` raises\n * whether that is `db:seed`, `db/seed` or `seed`. Declaration files, tests and\n * anything starting with `_` or `.` are not commands - the last is how a\n * helper lives beside the commands that share it.\n */\nexport function commandFiles(sourceDir: string): CommandFiles {\n  const dir = join(sourceDir, 'commands')\n  const found: CommandFiles = { commands: [], ignored: [] }\n\n  if (!existsSync(dir)) return found\n\n  const taken = new Map<string, CommandFile>()\n  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))\n\n  for (const entry of entries) {\n    const path = join(dir, entry.name)\n\n    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue\n\n    if (entry.isDirectory()) {\n      found.ignored.push({ path, reason: 'commands are the files directly in src/commands, not a folder of them' })\n\n      continue\n    }\n\n    if (!SOURCE.test(entry.name) || /\\.d\\.[cm]?ts$/.test(entry.name) || /\\.(?:test|spec)\\.[cm]?[jt]sx?$/.test(entry.name)) continue\n\n    const extension = entry.name.slice(entry.name.lastIndexOf('.') + 1)\n    const name = entry.name.slice(0, -(extension.length + 1))\n\n    if (!NAME.test(name)) {\n      found.ignored.push({ path, reason: `\"${name}\" cannot be typed as a command: letters, digits, \"-\", \"_\", \".\" and \":\"` })\n\n      continue\n    }\n\n    const existing = taken.get(name)\n\n    if (existing) {\n      const keep = EXTENSION_ORDER.indexOf(existing.file.split('.').pop() ?? '') <= EXTENSION_ORDER.indexOf(extension)\n\n      found.ignored.push({\n        path: keep ? path : existing.file,\n        reason: `two files are called \"${name}\"; ${keep ? existing.file : path} is the command`,\n      })\n\n      if (keep) continue\n\n      found.commands.splice(found.commands.indexOf(existing), 1)\n    }\n\n    const command: CommandFile = { name, file: path, description: describe(readFileSync(path, 'utf-8')) }\n\n    taken.set(name, command)\n    found.commands.push(command)\n  }\n\n  return found\n}\n\n/** The module the generated entry reads the table from, resolved when the bundle is built. */\nexport const COMMANDS_MODULE_ID = 'virtual:rsc-kit/commands'\n\n/**\n * The table: every command as a dynamic import, so each is a chunk of its own\n * and the server never evaluates one. An empty object when there are none -\n * a Worker's build, say, which does not carry them.\n *\n * A module of its own rather than text in the entry because the entry is\n * written while the config is still being read, before anything knows the\n * build's mode or which Nitro preset it is for.\n */\nexport function commandsModule(commands: readonly CommandFile[]): string {\n  const rows = commands.map(\n    ({ name, file, description }) =>\n      `  ${JSON.stringify(name)}: { load: () => import(${JSON.stringify(file)})${description ? `, description: ${JSON.stringify(description)}` : ''} },`,\n  )\n\n  return `export const commands = {\\n${rows.join('\\n')}\\n}\\n`\n}\n\n/**\n * What the generated server entry adds for an app with a `src/commands`:\n * `runCommand` over the table, with the entry's own `register()` and\n * `shutdown()`. `runner` is the engine's `commands` module, named without an\n * extension like every other engine module the entry imports.\n */\nexport function commandsEntry(runner: string): string {\n  return `\nimport { commands as __commands } from ${JSON.stringify(COMMANDS_MODULE_ID)}\nimport { runCommand as __runCommand } from ${JSON.stringify(runner)}\n\n// src/commands, each loaded only when it is named.\nexport function runCommand(argv: string[], program?: string) {\n  return __runCommand(argv, { commands: __commands, program, ready: instrumented, shutdown: __instrumentation.shutdown })\n}\n`\n}\n\n/**\n * The entry a plain build runs a command from, written beside the server:\n *\n *     node .output/server/commands.mjs migrate\n *     bun .output/server/commands.mjs migrate\n *\n * The server is not started - nothing here imports it - and the flag is set\n * before the entry is imported, since importing it is what would otherwise\n * call register().\n */\nexport function commandsEntrySource(): string {\n  return (\n    '// Run one of the app\\'s commands without starting the server:\\n' +\n    '//   node .output/server/commands.mjs <command> [args]\\n' +\n    '//   bun .output/server/commands.mjs <command> [args]\\n' +\n    'import { relative } from \"node:path\";\\n' +\n    'import { fileURLToPath } from \"node:url\";\\n' +\n    '\\n' +\n    'globalThis[Symbol.for(\"rsc-kit.command\")] = true;\\n' +\n    '\\n' +\n    'let code = 1;\\n' +\n    '\\n' +\n    'try {\\n' +\n    '  const { runCommand } = await import(\"./_ssr/rsc.mjs\");\\n' +\n    '  const runtime = process.versions.bun ? \"bun\" : \"node\";\\n' +\n    '\\n' +\n    '  code = await runCommand(process.argv.slice(2), runtime + \" \" + relative(process.cwd(), fileURLToPath(import.meta.url)));\\n' +\n    '} catch (error) {\\n' +\n    '  // The app failed to load: instrumentation.ts refusing a bad environment,\\n' +\n    '  // as it would stop the server.\\n' +\n    '  console.error(\"[rsc-kit] the app failed to load:\", error);\\n' +\n    '}\\n' +\n    '\\n' +\n    'process.exit(code);\\n'\n  )\n}\n"]}

package/dist/commands.d.ts

@@ -0,0 +1,74 @@
+/**
+ * App commands: the files in `src/commands`, run as `./app <name>`.
+ *
+ * A compiled app is one binary that starts a server, and a release step or a
+ * queue worker is the same code started differently - `./app migrate`,
+ * `./app work`. The same entry also runs from a plain build, as
+ * `node .output/server/commands.mjs <name>`, so nothing about a command
+ * depends on Bun, on a platform, or on the binary.
+ *
+ * Each command is a file with a default export, `(args, { signal }) => number
+ * | void`. It shares the build's code and dependencies, so the database
+ * package and the logger the pages use are the ones it uses, in the same
+ * bundle. It is loaded only when it is named: the server never evaluates one.
+ *
+ * `register()` from instrumentation.ts is skipped unless the command says
+ * `export const register = true`. Importing instrumentation.ts is not
+ * skipped - a bad environment fails there, at import, for a command as for a
+ * server - but a command that only needs the schema should not pay for, or
+ * fail on, a connection it never uses.
+ *
+ * Nothing here imports `node:` anything: the runner is bundled into the
+ * server's entry for every host, and a host without those modules must still
+ * load it. `process` is reached lazily, inside the functions that need it.
+ */
+/**
+ * Set on `globalThis` before the server's entry is imported, by whatever runs
+ * a command. The entry would otherwise call register() the moment it loads, as
+ * a server does at startup, which a command has not asked for.
+ */
+export declare const COMMAND_MODE: unique symbol;
+/** What a command receives beside its arguments. */
+export interface CommandContext {
+    /** Aborted by SIGTERM or SIGINT: a long-running command stops when it is. */
+    signal: AbortSignal;
+}
+/** What the build knows of one command file: how to load it, and a line to list it by. */
+export interface CommandEntry {
+    load: () => Promise<{
+        default?: unknown;
+        register?: unknown;
+    }>;
+    description?: string;
+}
+export interface RunCommandOptions {
+    commands: Record<string, CommandEntry>;
+    /** instrumentation.ts's register(), once. Awaited only for a command that exports `register = true`. */
+    ready: () => Promise<unknown>;
+    /** instrumentation.ts's shutdown(), called after a command that was given `register()`. */
+    shutdown?: () => unknown;
+    /** How the usage line names this program: `./app`, `node .output/server/commands.mjs`. */
+    program?: string;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+    /** SIGTERM and SIGINT. The process, unless a test brings its own. */
+    signals?: {
+        on: (signal: 'SIGTERM' | 'SIGINT', listener: () => void) => unknown;
+        off: (signal: 'SIGTERM' | 'SIGINT', listener: () => void) => unknown;
+    };
+    /** Milliseconds a command gets to stop once told to, and shutdown() after it. RSC_SHUTDOWN_TIMEOUT seconds (10) by default. */
+    limit?: number;
+}
+/** Whether this process was started to run a command rather than to serve. */
+export declare function inCommandMode(): boolean;
+/** The list `--help` prints, and what an unknown name is answered with. */
+export declare function commandHelp(commands: Record<string, CommandEntry>, program?: string): string;
+/**
+ * Run the command `argv` names and say how it ended.
+ *
+ * Resolves to the exit code and leaves exiting to the caller, so a test sees
+ * the code and an entry decides when the process stops. 0 is success and 1 is
+ * a command that threw or would not stop; 2 is a name that is not a command,
+ * as it is for a tool that was misused.
+ */
+export declare function runCommand(argv: readonly string[], options: RunCommandOptions): Promise<number>;

package/dist/commands.js

@@ -0,0 +1,172 @@
+/**
+ * App commands: the files in `src/commands`, run as `./app <name>`.
+ *
+ * A compiled app is one binary that starts a server, and a release step or a
+ * queue worker is the same code started differently - `./app migrate`,
+ * `./app work`. The same entry also runs from a plain build, as
+ * `node .output/server/commands.mjs <name>`, so nothing about a command
+ * depends on Bun, on a platform, or on the binary.
+ *
+ * Each command is a file with a default export, `(args, { signal }) => number
+ * | void`. It shares the build's code and dependencies, so the database
+ * package and the logger the pages use are the ones it uses, in the same
+ * bundle. It is loaded only when it is named: the server never evaluates one.
+ *
+ * `register()` from instrumentation.ts is skipped unless the command says
+ * `export const register = true`. Importing instrumentation.ts is not
+ * skipped - a bad environment fails there, at import, for a command as for a
+ * server - but a command that only needs the schema should not pay for, or
+ * fail on, a connection it never uses.
+ *
+ * Nothing here imports `node:` anything: the runner is bundled into the
+ * server's entry for every host, and a host without those modules must still
+ * load it. `process` is reached lazily, inside the functions that need it.
+ */
+/**
+ * Set on `globalThis` before the server's entry is imported, by whatever runs
+ * a command. The entry would otherwise call register() the moment it loads, as
+ * a server does at startup, which a command has not asked for.
+ */
+export const COMMAND_MODE = Symbol.for('rsc-kit.command');
+/** Whether this process was started to run a command rather than to serve. */
+export function inCommandMode() {
+    return Boolean(globalThis[COMMAND_MODE]);
+}
+/** The list `--help` prints, and what an unknown name is answered with. */
+export function commandHelp(commands, program = 'app') {
+    const names = Object.keys(commands).sort();
+    const width = Math.max(0, ...names.map((name) => name.length));
+    const rows = names.map((name) => {
+        const description = commands[name]?.description;
+        return description ? `  ${name.padEnd(width)}  ${description}` : `  ${name}`;
+    });
+    return (`Usage: ${program} <command> [args]\n\n` +
+        (rows.length ? `Commands:\n${rows.join('\n')}\n` : 'There are no commands: add a file to src/commands.\n'));
+}
+/**
+ * An exit code from what a command returned. Nothing is success; a number is
+ * the code. Anything else is the command's mistake, and said so, because the
+ * alternative is a process that exits 0 after returning a string.
+ */
+function exitCodeOf(result, name) {
+    if (result === undefined)
+        return 0;
+    if (typeof result === 'number' && Number.isInteger(result) && result >= 0 && result <= 255)
+        return result;
+    throw new TypeError(`the command "${name}" returned ${JSON.stringify(result)}. A command returns an exit code from 0 to 255, or nothing.`);
+}
+function unref(timer) {
+    const handle = timer;
+    if (handle && typeof handle.unref === 'function')
+        handle.unref();
+}
+/** The seconds a command and its shutdown() get after a signal, in milliseconds. */
+function defaultLimit() {
+    const seconds = Number(typeof process !== 'undefined' ? process.env.RSC_SHUTDOWN_TIMEOUT : undefined);
+    return (Number.isFinite(seconds) && seconds > 0 ? seconds : 10) * 1000;
+}
+/**
+ * Run the command `argv` names and say how it ended.
+ *
+ * Resolves to the exit code and leaves exiting to the caller, so a test sees
+ * the code and an entry decides when the process stops. 0 is success and 1 is
+ * a command that threw or would not stop; 2 is a name that is not a command,
+ * as it is for a tool that was misused.
+ */
+export async function runCommand(argv, options) {
+    const out = options.out ?? ((text) => void process.stdout.write(text));
+    const err = options.err ?? ((text) => void process.stderr.write(text));
+    const [name, ...args] = argv;
+    if (name === '--help' || name === '-h') {
+        out(commandHelp(options.commands, options.program));
+        return 0;
+    }
+    if (name === undefined) {
+        err(commandHelp(options.commands, options.program));
+        return 2;
+    }
+    const command = Object.hasOwn(options.commands, name) ? options.commands[name] : undefined;
+    if (!command) {
+        err(`Not a command: ${name}\n\n${commandHelp(options.commands, options.program)}`);
+        return 2;
+    }
+    const limit = options.limit ?? defaultLimit();
+    const signals = options.signals ?? (typeof process !== 'undefined' ? process : undefined);
+    const controller = new AbortController();
+    let registered = false;
+    let stop;
+    let stopTimer;
+    let signalled = 0;
+    // The first signal asks the command to stop and gives it `limit` to do so,
+    // as the server gives in-flight requests theirs. The second is a person who
+    // meant it, and nothing waits.
+    const onSignal = () => {
+        signalled += 1;
+        if (signalled === 1) {
+            controller.abort();
+            stopTimer = setTimeout(() => {
+                err(`[rsc-kit] the command "${name}" did not stop within ${limit / 1000} seconds.\n`);
+                stop?.(1);
+            }, limit);
+            unref(stopTimer);
+            return;
+        }
+        stop?.(1);
+    };
+    const stopped = new Promise((resolve) => {
+        stop = resolve;
+    });
+    signals?.on('SIGTERM', onSignal);
+    signals?.on('SIGINT', onSignal);
+    // A command that is only waiting - for its signal, for a message that has
+    // not come - holds nothing open, and Node answers an event loop with nothing
+    // in it by exiting 13 with a warning about an unsettled await, where Bun
+    // simply waits. A command that is running is running until it returns.
+    const alive = setInterval(() => { }, 2 ** 30);
+    const ran = (async () => {
+        try {
+            const module = await command.load();
+            if (typeof module.default !== 'function') {
+                throw new TypeError(`src/commands/${name} has no default export. Export a function: export default async (args) => {}`);
+            }
+            // Opted in, and only then: a migration that needs the schema should not
+            // fail because the queue it never touches is not up.
+            if (module.register === true) {
+                await options.ready();
+                registered = true;
+            }
+            return exitCodeOf(await module.default(args, { signal: controller.signal }), name);
+        }
+        catch (error) {
+            err(`[rsc-kit] the command "${name}" failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+            return 1;
+        }
+    })();
+    let code;
+    try {
+        code = await Promise.race([ran, stopped]);
+    }
+    finally {
+        clearInterval(alive);
+        clearTimeout(stopTimer);
+        signals?.off('SIGTERM', onSignal);
+        signals?.off('SIGINT', onSignal);
+    }
+    // What register() opened is closed here, bounded like the server's: a
+    // close that hangs must not hold a release step open.
+    if (registered && options.shutdown) {
+        let timer;
+        await Promise.race([
+            Promise.resolve()
+                .then(() => options.shutdown?.())
+                .catch((error) => err(`[rsc-kit] instrumentation.ts shutdown() failed: ${error instanceof Error ? error.message : String(error)}\n`)),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, limit);
+                unref(timer);
+            }),
+        ]);
+        clearTimeout(timer);
+    }
+    return code;
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * App commands: the files in `src/commands`, run as `./app <name>`.\n *\n * A compiled app is one binary that starts a server, and a release step or a\n * queue worker is the same code started differently - `./app migrate`,\n * `./app work`. The same entry also runs from a plain build, as\n * `node .output/server/commands.mjs <name>`, so nothing about a command\n * depends on Bun, on a platform, or on the binary.\n *\n * Each command is a file with a default export, `(args, { signal }) => number\n * | void`. It shares the build's code and dependencies, so the database\n * package and the logger the pages use are the ones it uses, in the same\n * bundle. It is loaded only when it is named: the server never evaluates one.\n *\n * `register()` from instrumentation.ts is skipped unless the command says\n * `export const register = true`. Importing instrumentation.ts is not\n * skipped - a bad environment fails there, at import, for a command as for a\n * server - but a command that only needs the schema should not pay for, or\n * fail on, a connection it never uses.\n *\n * Nothing here imports `node:` anything: the runner is bundled into the\n * server's entry for every host, and a host without those modules must still\n * load it. `process` is reached lazily, inside the functions that need it.\n */\n\n/**\n * Set on `globalThis` before the server's entry is imported, by whatever runs\n * a command. The entry would otherwise call register() the moment it loads, as\n * a server does at startup, which a command has not asked for.\n */\nexport const COMMAND_MODE = Symbol.for('rsc-kit.command')\n\n/** What a command receives beside its arguments. */\nexport interface CommandContext {\n  /** Aborted by SIGTERM or SIGINT: a long-running command stops when it is. */\n  signal: AbortSignal\n}\n\n/** What the build knows of one command file: how to load it, and a line to list it by. */\nexport interface CommandEntry {\n  load: () => Promise<{ default?: unknown; register?: unknown }>\n  description?: string\n}\n\nexport interface RunCommandOptions {\n  commands: Record<string, CommandEntry>\n  /** instrumentation.ts's register(), once. Awaited only for a command that exports `register = true`. */\n  ready: () => Promise<unknown>\n  /** instrumentation.ts's shutdown(), called after a command that was given `register()`. */\n  shutdown?: () => unknown\n  /** How the usage line names this program: `./app`, `node .output/server/commands.mjs`. */\n  program?: string\n  out?: (text: string) => void\n  err?: (text: string) => void\n  /** SIGTERM and SIGINT. The process, unless a test brings its own. */\n  signals?: {\n    on: (signal: 'SIGTERM' | 'SIGINT', listener: () => void) => unknown\n    off: (signal: 'SIGTERM' | 'SIGINT', listener: () => void) => unknown\n  }\n  /** Milliseconds a command gets to stop once told to, and shutdown() after it. RSC_SHUTDOWN_TIMEOUT seconds (10) by default. */\n  limit?: number\n}\n\n/** Whether this process was started to run a command rather than to serve. */\nexport function inCommandMode(): boolean {\n  return Boolean((globalThis as Record<symbol, unknown>)[COMMAND_MODE])\n}\n\n/** The list `--help` prints, and what an unknown name is answered with. */\nexport function commandHelp(commands: Record<string, CommandEntry>, program = 'app'): string {\n  const names = Object.keys(commands).sort()\n  const width = Math.max(0, ...names.map((name) => name.length))\n  const rows = names.map((name) => {\n    const description = commands[name]?.description\n\n    return description ? `  ${name.padEnd(width)}  ${description}` : `  ${name}`\n  })\n\n  return (\n    `Usage: ${program} <command> [args]\\n\\n` +\n    (rows.length ? `Commands:\\n${rows.join('\\n')}\\n` : 'There are no commands: add a file to src/commands.\\n')\n  )\n}\n\n/**\n * An exit code from what a command returned. Nothing is success; a number is\n * the code. Anything else is the command's mistake, and said so, because the\n * alternative is a process that exits 0 after returning a string.\n */\nfunction exitCodeOf(result: unknown, name: string): number {\n  if (result === undefined) return 0\n\n  if (typeof result === 'number' && Number.isInteger(result) && result >= 0 && result <= 255) return result\n\n  throw new TypeError(\n    `the command \"${name}\" returned ${JSON.stringify(result)}. A command returns an exit code from 0 to 255, or nothing.`,\n  )\n}\n\nfunction unref(timer: unknown): void {\n  const handle = timer as { unref?: () => void } | undefined\n\n  if (handle && typeof handle.unref === 'function') handle.unref()\n}\n\n/** The seconds a command and its shutdown() get after a signal, in milliseconds. */\nfunction defaultLimit(): number {\n  const seconds = Number(typeof process !== 'undefined' ? process.env.RSC_SHUTDOWN_TIMEOUT : undefined)\n\n  return (Number.isFinite(seconds) && seconds > 0 ? seconds : 10) * 1000\n}\n\n/**\n * Run the command `argv` names and say how it ended.\n *\n * Resolves to the exit code and leaves exiting to the caller, so a test sees\n * the code and an entry decides when the process stops. 0 is success and 1 is\n * a command that threw or would not stop; 2 is a name that is not a command,\n * as it is for a tool that was misused.\n */\nexport async function runCommand(argv: readonly string[], options: RunCommandOptions): Promise<number> {\n  const out = options.out ?? ((text: string) => void process.stdout.write(text))\n  const err = options.err ?? ((text: string) => void process.stderr.write(text))\n  const [name, ...args] = argv\n\n  if (name === '--help' || name === '-h') {\n    out(commandHelp(options.commands, options.program))\n\n    return 0\n  }\n\n  if (name === undefined) {\n    err(commandHelp(options.commands, options.program))\n\n    return 2\n  }\n\n  const command = Object.hasOwn(options.commands, name) ? options.commands[name] : undefined\n\n  if (!command) {\n    err(`Not a command: ${name}\\n\\n${commandHelp(options.commands, options.program)}`)\n\n    return 2\n  }\n\n  const limit = options.limit ?? defaultLimit()\n  const signals = options.signals ?? (typeof process !== 'undefined' ? process : undefined)\n  const controller = new AbortController()\n\n  let registered = false\n  let stop: ((code: number) => void) | undefined\n  let stopTimer: unknown\n  let signalled = 0\n\n  // The first signal asks the command to stop and gives it `limit` to do so,\n  // as the server gives in-flight requests theirs. The second is a person who\n  // meant it, and nothing waits.\n  const onSignal = () => {\n    signalled += 1\n\n    if (signalled === 1) {\n      controller.abort()\n\n      stopTimer = setTimeout(() => {\n        err(`[rsc-kit] the command \"${name}\" did not stop within ${limit / 1000} seconds.\\n`)\n        stop?.(1)\n      }, limit)\n\n      unref(stopTimer)\n\n      return\n    }\n\n    stop?.(1)\n  }\n\n  const stopped = new Promise<number>((resolve) => {\n    stop = resolve\n  })\n\n  signals?.on('SIGTERM', onSignal)\n  signals?.on('SIGINT', onSignal)\n\n  // A command that is only waiting - for its signal, for a message that has\n  // not come - holds nothing open, and Node answers an event loop with nothing\n  // in it by exiting 13 with a warning about an unsettled await, where Bun\n  // simply waits. A command that is running is running until it returns.\n  const alive = setInterval(() => {}, 2 ** 30)\n\n  const ran = (async (): Promise<number> => {\n    try {\n      const module = await command.load()\n\n      if (typeof module.default !== 'function') {\n        throw new TypeError(`src/commands/${name} has no default export. Export a function: export default async (args) => {}`)\n      }\n\n      // Opted in, and only then: a migration that needs the schema should not\n      // fail because the queue it never touches is not up.\n      if (module.register === true) {\n        await options.ready()\n        registered = true\n      }\n\n      return exitCodeOf(await (module.default as (...a: unknown[]) => unknown)(args, { signal: controller.signal }), name)\n    } catch (error) {\n      err(`[rsc-kit] the command \"${name}\" failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\\n`)\n\n      return 1\n    }\n  })()\n\n  let code: number\n\n  try {\n    code = await Promise.race([ran, stopped])\n  } finally {\n    clearInterval(alive)\n    clearTimeout(stopTimer as Parameters<typeof clearTimeout>[0])\n    signals?.off('SIGTERM', onSignal)\n    signals?.off('SIGINT', onSignal)\n  }\n\n  // What register() opened is closed here, bounded like the server's: a\n  // close that hangs must not hold a release step open.\n  if (registered && options.shutdown) {\n    let timer: unknown\n\n    await Promise.race([\n      Promise.resolve()\n        .then(() => options.shutdown?.())\n        .catch((error) => err(`[rsc-kit] instrumentation.ts shutdown() failed: ${error instanceof Error ? error.message : String(error)}\\n`)),\n      new Promise((resolve) => {\n        timer = setTimeout(resolve, limit)\n        unref(timer)\n      }),\n    ])\n\n    clearTimeout(timer as Parameters<typeof clearTimeout>[0])\n  }\n\n  return code\n}\n"]}

package/dist/files.d.ts

@@ -67,7 +67,9 @@ export declare function assetsReader(assets: AssetsBinding, prefix: string): (na
  * whose other Nitro app compiled with it asked why this one could not.
  * `bun build --compile --bytecode .output/server/compile.mjs` works now.
  */
-export declare function compileEntrySource(dirName: string): string;
+export declare function compileEntrySource(dirName: string, options?: {
+    commands?: boolean;
+}): string;
 /** The name the build writes the inline module under, beside the stored pages' directory. */
 export declare function inlineModuleName(dirName: string): string;
 /**

package/dist/files.js

@@ -264,7 +264,9 @@ function safeUrl(relative, base) {
  * whose other Nitro app compiled with it asked why this one could not.
  * `bun build --compile --bytecode .output/server/compile.mjs` works now.
  */
-export function compileEntrySource(dirName) {
+export function compileEntrySource(dirName, options = {}) {
+    if (options.commands)
+        return compileEntryWithCommands(dirName);
     return ('// The entry to compile into one binary:\n' +
         '//   bun build --compile .output/server/compile.mjs --outfile dist/app\n' +
         '//\n' +
@@ -277,6 +279,50 @@ export function compileEntrySource(dirName) {
         `import "./${inlineModuleName(dirName)}";\n` +
         'import "./index.mjs";\n');
 }
+/**
+ * The same entry for an app that has `src/commands`: the binary is the server
+ * with no arguments, and a command with one.
+ *
+ * The server's import is dynamic here, and only here. A static import starts
+ * the server as it evaluates, before any line of this file could look at
+ * `argv`, and a release step run as `./app migrate` would bind the port the
+ * running version holds. It is not awaited - a top-level await is what stopped
+ * `--bytecode` from applying to this entry - and a literal specifier is one
+ * Bun embeds, as it does the static one.
+ *
+ * Any argument is a command, and an unknown one is the runner's to refuse
+ * (exit 2) rather than a server that ignores it and starts.
+ */
+function compileEntryWithCommands(dirName) {
+    return ('// The entry to compile into one binary:\n' +
+        '//   bun build --compile .output/server/compile.mjs --outfile dist/app\n' +
+        '//\n' +
+        '// ./app starts the server. ./app <command> runs src/commands/<command>.\n' +
+        '//\n' +
+        '// A binary carries what is imported by name. The server reads its frozen pages\n' +
+        '// through a computed import, which a compile cannot see - imported here, they\n' +
+        '// travel inside the binary and are handed to the server before it starts.\n' +
+        '// The server itself is imported only when no command was named: a static\n' +
+        '// import would start it, and bind its port, before argv could be read. Not\n' +
+        '// awaited, since a top-level await is what stopped --bytecode from applying.\n' +
+        'import { basename } from "node:path";\n' +
+        `import "./${inlineModuleName(dirName)}";\n` +
+        '\n' +
+        'const failed = (what) => (error) => {\n' +
+        '  console.error(what, error);\n' +
+        '  process.exit(1);\n' +
+        '};\n' +
+        '\n' +
+        'if (process.argv.length <= 2) {\n' +
+        '  import("./index.mjs").catch(failed("[rsc-kit] the server failed to start:"));\n' +
+        '} else {\n' +
+        '  globalThis[Symbol.for("rsc-kit.command")] = true;\n' +
+        '\n' +
+        '  import("./_ssr/rsc.mjs")\n' +
+        '    .then(({ runCommand }) => runCommand(process.argv.slice(2), "./" + basename(process.execPath)))\n' +
+        '    .then((code) => process.exit(code), failed("[rsc-kit] the app failed to load:"));\n' +
+        '}\n');
+}
 /** The name the build writes the inline module under, beside the stored pages' directory. */
 export function inlineModuleName(dirName) {
     return `${dirName}-inline.mjs`;