@rsc-kit/core 0.30.15 → 0.30.17

package/dist/commands.js

@@ -0,0 +1,207 @@
+/**
+ * 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');
+/**
+ * The entry that loads the app owns the process's SIGTERM and SIGINT, and
+ * leaves this on `globalThis` for the runner.
+ *
+ * Loading can take a while, and a signal before the runner exists finds only
+ * the default action, which ends the process with 143. So the entry holds
+ * them, and the runner is handed over to: the count of those that came first,
+ * and every later one. The entry's listener is never taken off. A signal is
+ * delivered on the event loop's next turn, not when it arrives, and a listener
+ * removed in between has the signal taken from it without anyone getting it.
+ */
+export const EARLY_SIGNALS = Symbol.for('rsc-kit.command.signals');
+/** 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 deadline;
+    let signalled = 0;
+    const context = {
+        signal: controller.signal,
+        get deadline() {
+            return deadline;
+        },
+    };
+    // 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) {
+            deadline = Date.now() + limit;
+            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;
+    });
+    // Behind an entry that loaded the app, the process's signals are the
+    // entry's: it hands each one over, and what came while the app was loading
+    // is counted here. Told to stop while loading is told to stop.
+    const early = globalThis[EARLY_SIGNALS];
+    if (early) {
+        early.handoff(onSignal);
+        for (let caught = 0; caught < early.count; caught++)
+            onSignal();
+    }
+    else {
+        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, context), 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);
+        if (early)
+            early.handoff(undefined);
+        else {
+            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   * When the runner stops waiting for the command, as a time in milliseconds\n   * (`Date.now()`'s), once it has been told to stop; undefined until then.\n   * A worker finishing its job reads `deadline - Date.now()` rather than\n   * RSC_SHUTDOWN_TIMEOUT and its default.\n   */\n  readonly deadline: number | undefined\n}\n\n/**\n * The entry that loads the app owns the process's SIGTERM and SIGINT, and\n * leaves this on `globalThis` for the runner.\n *\n * Loading can take a while, and a signal before the runner exists finds only\n * the default action, which ends the process with 143. So the entry holds\n * them, and the runner is handed over to: the count of those that came first,\n * and every later one. The entry's listener is never taken off. A signal is\n * delivered on the event loop's next turn, not when it arrives, and a listener\n * removed in between has the signal taken from it without anyone getting it.\n */\nexport const EARLY_SIGNALS = Symbol.for('rsc-kit.command.signals')\n\ninterface EarlySignals {\n  /** Stops that arrived before there was a runner to give them to. */\n  count: number\n  /** From now on, the entry gives each signal to this, and stops holding the process to its own timeout. */\n  handoff: (listener: (() => void) | undefined) => void\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, { description?: string }>, 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 deadline: number | undefined\n  let signalled = 0\n  const context: CommandContext = {\n    signal: controller.signal,\n    get deadline() {\n      return deadline\n    },\n  }\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      deadline = Date.now() + limit\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  // Behind an entry that loaded the app, the process's signals are the\n  // entry's: it hands each one over, and what came while the app was loading\n  // is counted here. Told to stop while loading is told to stop.\n  const early = (globalThis as Record<symbol, EarlySignals | undefined>)[EARLY_SIGNALS]\n\n  if (early) {\n    early.handoff(onSignal)\n\n    for (let caught = 0; caught < early.count; caught++) onSignal()\n  } else {\n    signals?.on('SIGTERM', onSignal)\n    signals?.on('SIGINT', onSignal)\n  }\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, context), 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\n    if (early) early.handoff(undefined)\n    else {\n      signals?.off('SIGTERM', onSignal)\n      signals?.off('SIGINT', onSignal)\n    }\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/vite.js

@@ -33,6 +33,7 @@ import { ownHosts } from "./hostRouting.js";
 import { unrollBarrelImports } from "./barrelImports.js";
 import { hasUseSsr, serverRendererMessage, SERVER_RENDERER, ssrProxyModule, UseSsrError, withoutSsrDirective } from "./useSsr.js";
 import { httpHostCalls } from "./hostCalls.js";
+import { COMMANDS_MODULE_ID, commandFiles, commandsEntry, commandsEntrySource, commandsModule, compileEntryWithCommands } from "./commandFiles.js";
 import { clientPackages, importsServerRenderer, packageDir as installedPackageDir, packageEntryInGraph, polyfillsToTrace, traceableByName } from "./clientPackages.js";
 // Resolved once per rscKit() call. One build runs in one process, so these are
 // module state rather than threaded through every helper.
@@ -47,6 +48,57 @@ let clientLibraryImports = [];
  * decisions buildApp makes about where stored pages can live.
  */
 let nitroPreset = null;
+/** `src/commands`, read once per build; null until asked. See buildCommands(). */
+let commandsFound = null;
+/**
+ * What the entries that run a command need from the build: the commands, and
+ * the polyfills the server loads in a Nitro plugin that a command does not go
+ * through. Only the ones the app's graph has, as the plugin does.
+ */
+function commandEntryOptions() {
+    return {
+        commands: buildCommands(),
+        polyfills: FIRST_POLYFILLS.filter((name) => packageEntryInGraph(projectRoot, name) !== null),
+    };
+}
+/**
+ * The presets whose output is a process that Node or Bun starts: where a
+ * command runs. Every other preset is a platform that starts the app itself -
+ * a function, a Worker - and a release step there is not the app's to run.
+ */
+const COMMAND_PRESETS = /^(?:bun|node|node[-_]server|node[-_]cluster)$/;
+/**
+ * The app's commands, for a build that has a process to run them in.
+ *
+ * Decided once, the first time the bundle asks, and every later step reads the
+ * same answer: the table in the bundle, `commands.mjs`, the compile entry and
+ * `.output/rsc-kit.json` cannot disagree about what is there.
+ *
+ * Not the dev server, which has no output to run one from - a command there is
+ * `bun src/commands/<name>.ts`. Not a Worker: its bundle targets workerd, where
+ * the packages a release step wants (a database driver, `node:child_process`)
+ * either resolve to a different build or not at all, so a command that ran there
+ * would run something other than what was written. And not a preset this has not
+ * been run on: it says so, rather than writing an entry for a layout it has not
+ * seen.
+ */
+function buildCommands() {
+    if (resolvedConfig?.command !== "build")
+        return [];
+    if (commandsFound)
+        return commandsFound;
+    const { commands, ignored } = commandFiles(sourceDir);
+    for (const { path, reason } of ignored)
+        log(`${relative(projectRoot, path)} is not a command: ${reason}.`);
+    if (commands.length && !(nitroPreset && COMMAND_PRESETS.test(nitroPreset))) {
+        const names = commands.map((c) => c.name).join(", ");
+        log(nitroPreset?.startsWith("cloudflare")
+            ? `src/commands is not built for a Worker (${names}): the bundle runs on workerd, which is not where a release step runs. Run the file itself, or wrangler.`
+            : `src/commands is built for the bun and node presets, and this build is ${nitroPreset ? `for ${nitroPreset}` : "not using a Nitro preset"} (${names}). Run the file itself from CI.`);
+        return (commandsFound = []);
+    }
+    return (commandsFound = commands);
+}
 /**
  * Modules a runtime provides and no bundle should try to carry.
  *
@@ -2490,6 +2542,20 @@ function registerOpenApiRoutes() {
     }
     apiRoutes.set(name, { name, absPath: OPENAPI_ROUTE_ID, methods: ["GET"], generated: { kind: "openapi", file: "" } });
 }
+/** The table behind `runCommand` in the server's entry: src/commands, or nothing where they are not built. */
+function commandsPlugin() {
+    return {
+        name: "rsc-kit:commands",
+        resolveId(id) {
+            if (id === COMMANDS_MODULE_ID)
+                return "\0" + id;
+        },
+        load(id) {
+            if (id === "\0" + COMMANDS_MODULE_ID)
+                return commandsModule(buildCommands());
+        },
+    };
+}
 /** The module behind the synthesised /openapi.json route. */
 function openApiPlugin() {
     return {
@@ -3070,7 +3136,7 @@ export function instrumentationImport(instrumentation) {
     return (`import { ${hooks.map((hook) => `${hook} as __instrumentation_${hook}`).join(", ")} } from ${from}\n` +
         `const __instrumentation: ${type} = { ${hooks.map((hook) => `${hook}: __instrumentation_${hook}`).join(", ")} }`);
 }
-function generateEntryRsc(fallbackOrigin = "") {
+function generateEntryRsc(fallbackOrigin = "", withCommands = false) {
     const instrumentation = instrumentationFile();
     // Every 404 page the app has, and the layouts each renders inside. Computed
     // here rather than looked up at runtime: not-found is not a route, so the
@@ -3603,7 +3669,9 @@ if (!isolateRuntime) {
   ;(globalThis as { __rscKitShutdown?: () => unknown }).__rscKitShutdown = () => __instrumentation.shutdown?.()
 }
 
-if (__instrumentation.register && !isolateRuntime) {
+// Started to run a command (src/commands), not to serve: register() waits for
+// the command that asks for it, rather than running at import.
+if (__instrumentation.register && !isolateRuntime && !(globalThis as Record<symbol, unknown>)[Symbol.for('rsc-kit.command')]) {
   instrumented().catch((error) => {
     console.error('[rsc-kit] instrumentation.ts register() failed:', error)
 
@@ -5990,7 +6058,11 @@ async function renderNotFound(request: Request): Promise<Response> {
         : ""}
   return new Response('Not found', { status: 404 })
 }
-`;
+${
+    // After everything the entry is for: running a command reads its
+    // register() and shutdown(). Only a build for an app that has commands; what
+    // is in the table is decided later, when the bundle is built.
+    withCommands ? commandsEntry(join(packageDir, "commands")) : ""}`;
 }
 function generateEntrySsr() {
     const devUrls = join(packageDir, "devUrls");
@@ -7219,6 +7291,20 @@ export function rscKit(options = {}) {
                 if (nitro.options.dev)
                     return;
                 nitroPreset = nitro.options.preset ?? null;
+                // The entry a command runs from, beside the server it does not start.
+                // Written once Nitro has assembled the output, because it names a
+                // file Nitro places: if that moves, the build says so rather than a
+                // release step finding out.
+                nitro.hooks.hook("compiled", async () => {
+                    if (buildCommands().length === 0)
+                        return;
+                    const serverDir = nitro.options.output.serverDir;
+                    if (!existsSync(join(serverDir, "_ssr", "rsc.mjs"))) {
+                        throw new Error(`[rsc-kit] src/commands runs from ${join(serverDir, "_ssr", "rsc.mjs")}, and Nitro did not write it there. ` +
+                            "Nitro's output layout changed; the commands entry needs to follow it.");
+                    }
+                    writeFileSync(join(serverDir, "commands.mjs"), commandsEntrySource(commandEntryOptions()));
+                });
                 // On Workers the stored pages ride the static assets, not the bundle.
                 // Copied once Nitro has listed its public files, so the copies are
                 // not in that list: a path in it is served as an asset before the
@@ -7331,6 +7417,7 @@ export function rscKit(options = {}) {
             // Both maps, not one: the config hook runs again when the config
             // changes under a dev server, and a route.ts or a synthesised
             // robots.txt left over from the previous run read as a duplicate.
+            commandsFound = null;
             components.clear();
             apiRoutes.clear();
             discover(appDir);
@@ -7413,7 +7500,7 @@ export function rscKit(options = {}) {
                     : env.command === "build"
                         ? (declaresBackend ? "" : false)
                         : (detected || (declaresBackend ? "" : false));
-            writeGenerated(join(genDir, "entry.rsc.tsx"), generateEntryRsc(fallbackOrigin));
+            writeGenerated(join(genDir, "entry.rsc.tsx"), generateEntryRsc(fallbackOrigin, env.command === "build" && existsSync(join(sourceDir, "commands"))));
             writeGenerated(join(genDir, "entry.ssr.tsx"), generateEntrySsr());
             writeGenerated(join(genDir, "entry.browser.tsx"), generateEntryBrowser());
             // Written beside the entries, for a host to read instead of walking the
@@ -7893,7 +7980,9 @@ export function rscKit(options = {}) {
                 // And the entry a binary is compiled from, so the pages above end up
                 // inside it rather than rendered live: bun build --compile
                 // .output/server/compile.mjs. The scaffold's script names it.
-                writeFileSync(join(dirname(staticDir), "compile.mjs"), compileEntrySource(NITRO_STATIC_DIR));
+                writeFileSync(join(dirname(staticDir), "compile.mjs"), buildCommands().length > 0
+                    ? compileEntryWithCommands(NITRO_STATIC_DIR, commandEntryOptions())
+                    : compileEntrySource(NITRO_STATIC_DIR));
             }
             // Manifest first. The service worker precaches whatever it finds in this
             // directory, so writing it afterwards leaves it out of the list — and an
@@ -7917,7 +8006,12 @@ export function rscKit(options = {}) {
             if (clientOut) {
                 writeFileSync(join(dirname(clientOut), "rsc-kit.json"), JSON.stringify(output === "export"
                     ? { version: PACKAGE_VERSION, output: "export", dir: relative(projectRoot, exportPath) }
-                    : { version: PACKAGE_VERSION, output: "server", ...compileStep(projectRoot) }, null, 2) + "\n");
+                    : {
+                        version: PACKAGE_VERSION,
+                        output: "server",
+                        ...compileStep(projectRoot),
+                        ...(buildCommands().length ? { commands: buildCommands().map((c) => c.name) } : {}),
+                    }, null, 2) + "\n");
             }
         },
         configResolved(config) {
@@ -8000,6 +8094,7 @@ export function rscKit(options = {}) {
         serverRendererInRsc(),
         metadataRoutesPlugin(),
         openApiPlugin(),
+        commandsPlugin(),
         extendableClientReferences(),
         stableComponentNames(),
         typecheckPlugin(),