@rsc-kit/core 0.30.23 → 0.30.25

package/dist/clientImports.d.ts

@@ -1,14 +1,23 @@
 /**
- * Server files that import a client library.
+ * Server files that reach client-only React on the server.
  *
  * A server component may import a client library - `<SheetClose>` from
  * base-ui rendered inside server output is legal here and in Next.js. What
  * is worth a line is the shape that cost an afternoon: a file with no
- * "use client" that only wraps client components (a shadcn ui/ file that
- * lost its directive in a port) imported from the server, so the library's
- * internals run in the rsc environment. The build cannot tell the two
- * apart; it can say which server files do it, and with which packages, so
- * the person reading can.
+ * "use client" (a shadcn ui/ file that lost its directive in a port) whose
+ * code, or a library's under it, calls a hook in the rsc environment, which
+ * fails at render as "(0, import_react_react_server.useState) is not a
+ * function" - naming React, not the file.
+ *
+ * This used to name every server file importing any package that depends on
+ * React, which on a real app was 26 files of icons, markdown and base-ui
+ * parts that carry their own "use client", and the one that mattered was
+ * lost among them. So the code is read instead: from the server file into
+ * the packages it imports, stopping at a client reference - a module with
+ * the directive, whose code never runs on the server - and a file is named
+ * only when what is left mentions a React API the server build does not
+ * have. Mentions, not calls: a library can hold a hook in an export the
+ * page never renders, so the line names the API for the reader to judge.
  *
  * Read off the rsc environment's module graph after it is built. A file with
  * the directive never appears: in that graph it is already a reference, and
@@ -17,8 +26,10 @@
 export interface ClientLibraryImport {
     /** The server file, relative to the source dir. */
     file: string;
-    /** The client packages it imports, by name. */
+    /** The packages whose server-run code reaches a client-only API, by name. Empty when the file itself does. */
     packages: string[];
+    /** The client-only React APIs reached, by name. */
+    calls: string[];
     /** The first app file that imports it, relative to the source dir - or null for a route file. */
     from: string | null;
 }
@@ -26,7 +37,16 @@ export interface ModuleGraph {
     moduleIds(): Iterable<string>;
     importedIds(id: string): readonly string[];
     importers(id: string): readonly string[];
+    /** The module's code as built - for a client reference, the reference. */
+    code(id: string): string | null;
 }
+/**
+ * React's APIs that its server build leaves out, as of React 19: the ones a
+ * render needs state or an effect for. A test reads them off React itself.
+ * Not Component or startTransition - the one is a word in every library's
+ * prose, the other runs in an event handler, never during a render.
+ */
+export declare const CLIENT_ONLY_APIS: readonly ["createContext", "useActionState", "useContext", "useDeferredValue", "useEffect", "useEffectEvent", "useFormState", "useFormStatus", "useImperativeHandle", "useInsertionEffect", "useLayoutEffect", "useOptimistic", "useReducer", "useRef", "useState", "useSyncExternalStore", "useTransition"];
 /** The package a node_modules id belongs to, or null for anything else. */
 export declare function packageOf(id: string): string | null;
 export declare function serverImportsOfClientPackages(graph: ModuleGraph, options: {

package/dist/clientImports.js

@@ -1,3 +1,38 @@
+/**
+ * React's APIs that its server build leaves out, as of React 19: the ones a
+ * render needs state or an effect for. A test reads them off React itself.
+ * Not Component or startTransition - the one is a word in every library's
+ * prose, the other runs in an event handler, never during a render.
+ */
+export const CLIENT_ONLY_APIS = [
+    "createContext",
+    "useActionState",
+    "useContext",
+    "useDeferredValue",
+    "useEffect",
+    "useEffectEvent",
+    "useFormState",
+    "useFormStatus",
+    "useImperativeHandle",
+    "useInsertionEffect",
+    "useLayoutEffect",
+    "useOptimistic",
+    "useReducer",
+    "useRef",
+    "useState",
+    "useSyncExternalStore",
+    "useTransition",
+];
+const CLIENT_ONLY = new RegExp(`\\b(${CLIENT_ONLY_APIS.join("|")})\\b`, "g");
+const COMMENT = /\/\*[\s\S]*?\*\/|(^|[^:])\/\/[^\n]*/g;
+/** plugin-rsc's reference for a "use client" module: its code stays on the client. */
+const isReference = (code) => code.includes("registerClientReference");
+/** The client-only APIs a module's own code mentions, outside its comments. */
+function clientOnlyIn(code) {
+    if (!code || isReference(code))
+        return [];
+    return [...new Set([...code.replace(COMMENT, "$1").matchAll(CLIENT_ONLY)].map((m) => m[1]))];
+}
 const PACKAGE = /\/node_modules\/(@[^/]+\/[^/]+|[^/@][^/]*)/;
 /** The package a node_modules id belongs to, or null for anything else. */
 export function packageOf(id) {
@@ -13,21 +48,54 @@ export function serverImportsOfClientPackages(graph, options) {
         !id.startsWith("\0");
     const relative = (id) => (id.split("?")[0] ?? id).slice(root.length);
     const out = [];
+    const inClientPackage = (id) => {
+        const name = packageOf(id);
+        return name !== null && client.has(name) && !ignore.has(name);
+    };
+    // What a package module and everything it runs on the server reach,
+    // memoised: one barrel is imported by many files. A cycle reads as nothing
+    // more on its second visit, which is all a union needs.
+    const reached = new Map();
+    const reach = (id) => {
+        const known = reached.get(id);
+        if (known)
+            return known;
+        const apis = new Set();
+        reached.set(id, apis);
+        const code = graph.code(id);
+        if (code !== null && isReference(code))
+            return apis;
+        for (const api of clientOnlyIn(code))
+            apis.add(api);
+        for (const next of graph.importedIds(id)) {
+            if (inClientPackage(next))
+                for (const api of reach(next))
+                    apis.add(api);
+        }
+        return apis;
+    };
     for (const id of graph.moduleIds()) {
         if (!isApp(id))
             continue;
+        const calls = new Set(clientOnlyIn(graph.code(id)));
         const packages = new Set();
         for (const imported of graph.importedIds(id)) {
-            const name = packageOf(imported);
-            if (name && client.has(name) && !ignore.has(name))
-                packages.add(name);
+            if (!inClientPackage(imported))
+                continue;
+            const apis = reach(imported);
+            if (apis.size === 0)
+                continue;
+            packages.add(packageOf(imported));
+            for (const api of apis)
+                calls.add(api);
         }
-        if (packages.size === 0)
+        if (calls.size === 0)
             continue;
         const from = graph.importers(id).find(isApp);
         out.push({
             file: relative(id),
             packages: [...packages].sort(),
+            calls: [...calls].sort(),
             from: from ? relative(from) : null,
         });
     }

package/dist/clientImports.js.map

@@ -1 +1 @@
-{"version":3,"file":"clientImports.js","sourceRoot":"","sources":["../src/clientImports.ts"],"names":[],"mappings":"AA+BA,MAAM,OAAO,GAAG,4CAA4C,CAAC;AAE7D,2EAA2E;AAC3E,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAEnD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,KAAkB,EAClB,OAIC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAC3B,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;QACnB,CAAC,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAC9B,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7E,MAAM,GAAG,GAA0B,EAAE,CAAC;IAEtC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,SAAS;QAEzB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QAEnC,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;YAEjC,IAAI,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxE,CAAC;QAED,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;YAAE,SAAS;QAElC,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE7C,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;YAClB,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE;YAC9B,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;SACnC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC1D,CAAC","sourcesContent":["/**\n * Server files that import a client library.\n *\n * A server component may import a client library - `<SheetClose>` from\n * base-ui rendered inside server output is legal here and in Next.js. What\n * is worth a line is the shape that cost an afternoon: a file with no\n * \"use client\" that only wraps client components (a shadcn ui/ file that\n * lost its directive in a port) imported from the server, so the library's\n * internals run in the rsc environment. The build cannot tell the two\n * apart; it can say which server files do it, and with which packages, so\n * the person reading can.\n *\n * Read off the rsc environment's module graph after it is built. A file with\n * the directive never appears: in that graph it is already a reference, and\n * a reference imports nothing.\n */\nexport interface ClientLibraryImport {\n  /** The server file, relative to the source dir. */\n  file: string;\n  /** The client packages it imports, by name. */\n  packages: string[];\n  /** The first app file that imports it, relative to the source dir - or null for a route file. */\n  from: string | null;\n}\n\nexport interface ModuleGraph {\n  moduleIds(): Iterable<string>;\n  importedIds(id: string): readonly string[];\n  importers(id: string): readonly string[];\n}\n\nconst PACKAGE = /\\/node_modules\\/(@[^/]+\\/[^/]+|[^/@][^/]*)/;\n\n/** The package a node_modules id belongs to, or null for anything else. */\nexport function packageOf(id: string): string | null {\n  const match = PACKAGE.exec(id.split(\"?\")[0] ?? id);\n\n  return match ? match[1]! : null;\n}\n\nexport function serverImportsOfClientPackages(\n  graph: ModuleGraph,\n  options: {\n    sourceDir: string;\n    clientPackages: Iterable<string>;\n    ignore?: Iterable<string>;\n  },\n): ClientLibraryImport[] {\n  const root = options.sourceDir.replace(/\\/+$/, \"\") + \"/\";\n  const client = new Set(options.clientPackages);\n  const ignore = new Set(options.ignore ?? []);\n  const isApp = (id: string) =>\n    id.startsWith(root) &&\n    !id.includes(\"/node_modules/\") &&\n    !id.startsWith(\"\\0\");\n  const relative = (id: string) => (id.split(\"?\")[0] ?? id).slice(root.length);\n  const out: ClientLibraryImport[] = [];\n\n  for (const id of graph.moduleIds()) {\n    if (!isApp(id)) continue;\n\n    const packages = new Set<string>();\n\n    for (const imported of graph.importedIds(id)) {\n      const name = packageOf(imported);\n\n      if (name && client.has(name) && !ignore.has(name)) packages.add(name);\n    }\n\n    if (packages.size === 0) continue;\n\n    const from = graph.importers(id).find(isApp);\n\n    out.push({\n      file: relative(id),\n      packages: [...packages].sort(),\n      from: from ? relative(from) : null,\n    });\n  }\n\n  return out.sort((a, b) => a.file.localeCompare(b.file));\n}\n"]}
+{"version":3,"file":"clientImports.js","sourceRoot":"","sources":["../src/clientImports.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server files that reach client-only React on the server.\n *\n * A server component may import a client library - `<SheetClose>` from\n * base-ui rendered inside server output is legal here and in Next.js. What\n * is worth a line is the shape that cost an afternoon: a file with no\n * \"use client\" (a shadcn ui/ file that lost its directive in a port) whose\n * code, or a library's under it, calls a hook in the rsc environment, which\n * fails at render as \"(0, import_react_react_server.useState) is not a\n * function\" - naming React, not the file.\n *\n * This used to name every server file importing any package that depends on\n * React, which on a real app was 26 files of icons, markdown and base-ui\n * parts that carry their own \"use client\", and the one that mattered was\n * lost among them. So the code is read instead: from the server file into\n * the packages it imports, stopping at a client reference - a module with\n * the directive, whose code never runs on the server - and a file is named\n * only when what is left mentions a React API the server build does not\n * have. Mentions, not calls: a library can hold a hook in an export the\n * page never renders, so the line names the API for the reader to judge.\n *\n * Read off the rsc environment's module graph after it is built. A file with\n * the directive never appears: in that graph it is already a reference, and\n * a reference imports nothing.\n */\nexport interface ClientLibraryImport {\n  /** The server file, relative to the source dir. */\n  file: string;\n  /** The packages whose server-run code reaches a client-only API, by name. Empty when the file itself does. */\n  packages: string[];\n  /** The client-only React APIs reached, by name. */\n  calls: string[];\n  /** The first app file that imports it, relative to the source dir - or null for a route file. */\n  from: string | null;\n}\n\nexport interface ModuleGraph {\n  moduleIds(): Iterable<string>;\n  importedIds(id: string): readonly string[];\n  importers(id: string): readonly string[];\n  /** The module's code as built - for a client reference, the reference. */\n  code(id: string): string | null;\n}\n\n/**\n * React's APIs that its server build leaves out, as of React 19: the ones a\n * render needs state or an effect for. A test reads them off React itself.\n * Not Component or startTransition - the one is a word in every library's\n * prose, the other runs in an event handler, never during a render.\n */\nexport const CLIENT_ONLY_APIS = [\n  \"createContext\",\n  \"useActionState\",\n  \"useContext\",\n  \"useDeferredValue\",\n  \"useEffect\",\n  \"useEffectEvent\",\n  \"useFormState\",\n  \"useFormStatus\",\n  \"useImperativeHandle\",\n  \"useInsertionEffect\",\n  \"useLayoutEffect\",\n  \"useOptimistic\",\n  \"useReducer\",\n  \"useRef\",\n  \"useState\",\n  \"useSyncExternalStore\",\n  \"useTransition\",\n] as const;\n\nconst CLIENT_ONLY = new RegExp(`\\\\b(${CLIENT_ONLY_APIS.join(\"|\")})\\\\b`, \"g\");\nconst COMMENT = /\\/\\*[\\s\\S]*?\\*\\/|(^|[^:])\\/\\/[^\\n]*/g;\n\n/** plugin-rsc's reference for a \"use client\" module: its code stays on the client. */\nconst isReference = (code: string) => code.includes(\"registerClientReference\");\n\n/** The client-only APIs a module's own code mentions, outside its comments. */\nfunction clientOnlyIn(code: string | null): string[] {\n  if (!code || isReference(code)) return [];\n\n  return [...new Set([...code.replace(COMMENT, \"$1\").matchAll(CLIENT_ONLY)].map((m) => m[1]!))];\n}\n\nconst PACKAGE = /\\/node_modules\\/(@[^/]+\\/[^/]+|[^/@][^/]*)/;\n\n/** The package a node_modules id belongs to, or null for anything else. */\nexport function packageOf(id: string): string | null {\n  const match = PACKAGE.exec(id.split(\"?\")[0] ?? id);\n\n  return match ? match[1]! : null;\n}\n\nexport function serverImportsOfClientPackages(\n  graph: ModuleGraph,\n  options: {\n    sourceDir: string;\n    clientPackages: Iterable<string>;\n    ignore?: Iterable<string>;\n  },\n): ClientLibraryImport[] {\n  const root = options.sourceDir.replace(/\\/+$/, \"\") + \"/\";\n  const client = new Set(options.clientPackages);\n  const ignore = new Set(options.ignore ?? []);\n  const isApp = (id: string) =>\n    id.startsWith(root) &&\n    !id.includes(\"/node_modules/\") &&\n    !id.startsWith(\"\\0\");\n  const relative = (id: string) => (id.split(\"?\")[0] ?? id).slice(root.length);\n  const out: ClientLibraryImport[] = [];\n  const inClientPackage = (id: string) => {\n    const name = packageOf(id);\n    return name !== null && client.has(name) && !ignore.has(name);\n  };\n\n  // What a package module and everything it runs on the server reach,\n  // memoised: one barrel is imported by many files. A cycle reads as nothing\n  // more on its second visit, which is all a union needs.\n  const reached = new Map<string, Set<string>>();\n  const reach = (id: string): Set<string> => {\n    const known = reached.get(id);\n    if (known) return known;\n\n    const apis = new Set<string>();\n    reached.set(id, apis);\n\n    const code = graph.code(id);\n    if (code !== null && isReference(code)) return apis;\n\n    for (const api of clientOnlyIn(code)) apis.add(api);\n\n    for (const next of graph.importedIds(id)) {\n      if (inClientPackage(next)) for (const api of reach(next)) apis.add(api);\n    }\n\n    return apis;\n  };\n\n  for (const id of graph.moduleIds()) {\n    if (!isApp(id)) continue;\n\n    const calls = new Set(clientOnlyIn(graph.code(id)));\n    const packages = new Set<string>();\n\n    for (const imported of graph.importedIds(id)) {\n      if (!inClientPackage(imported)) continue;\n\n      const apis = reach(imported);\n      if (apis.size === 0) continue;\n\n      packages.add(packageOf(imported)!);\n      for (const api of apis) calls.add(api);\n    }\n\n    if (calls.size === 0) continue;\n\n    const from = graph.importers(id).find(isApp);\n\n    out.push({\n      file: relative(id),\n      packages: [...packages].sort(),\n      calls: [...calls].sort(),\n      from: from ? relative(from) : null,\n    });\n  }\n\n  return out.sort((a, b) => a.file.localeCompare(b.file));\n}\n"]}

package/dist/commands.js

@@ -184,7 +184,7 @@ export async function runCommand(argv, options) {
             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`);
+            err(`[rsc-kit] the command "${name}" failed: ${describeError(error, true)}\n`);
             return 1;
         }
     })();
@@ -209,7 +209,7 @@ export async function runCommand(argv, options) {
         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`)),
+                .catch((error) => err(`[rsc-kit] instrumentation.ts shutdown() failed: ${describeError(error, false)}\n`)),
             new Promise((resolve) => {
                 timer = setTimeout(resolve, limit);
                 unref(timer);
@@ -219,4 +219,24 @@ export async function runCommand(argv, options) {
     }
     return code;
 }
+/**
+ * An error and every cause under it, one line of `[cause]:` each.
+ *
+ * A library that wraps an error keeps the reason in `cause`, and a stack does
+ * not print it: Drizzle's DrizzleQueryError carries the SQL as its message and
+ * the database's refusal - a timeout, a wrong password - as its cause, so a
+ * failed migration said what it tried and never why. A cause that is not an
+ * Error is printed as it is, and a chain that loops back stops there.
+ */
+function describeError(error, stack) {
+    const seen = new Set();
+    const parts = [];
+    let current = error;
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        parts.push(current instanceof Error ? (stack ? (current.stack ?? `${current.name}: ${current.message}`) : current.message) : String(current));
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return parts.join('\n[cause]: ');
+}
 //# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -1 +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, context) => number\n * | void`, where `context` is `{ signal, deadline }`. 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   * A getter, because what it answers changes: read `context.deadline` when\n   * you need it. `({ deadline }) => ...` reads it once, as the command\n   * starts, when it is always undefined, and keeps that.\n   */\n  readonly deadline: number | undefined\n}\n\n/** A command's default export. */\nexport type CommandFunction = (args: string[], context: CommandContext) => number | void | Promise<number | void>\n\n/**\n * Types a command's default export, so its arguments and context are known\n * without annotating them: `export default defineCommand(async (args, context) => {})`.\n * It returns what it is given.\n */\nexport function defineCommand(command: CommandFunction): CommandFunction {\n  return command\n}\n\n/** Resolves after the event loop has taken a turn, which is when it hands out the signals that arrived while it was busy. */\nconst nextTurn = () => new Promise<void>((resolve) => (typeof setImmediate === 'function' ? setImmediate(resolve) : setTimeout(resolve, 0)))\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      // A stop that arrived while the loop was busy with a synchronous load has\n      // not been delivered: a signal is delivered on the loop's next turn. One\n      // turn here, so that the command is told before it starts rather than a\n      // moment after - the same on Node, on Bun and in a binary.\n      await nextTurn()\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"]}
+{"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, context) => number\n * | void`, where `context` is `{ signal, deadline }`. 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   * A getter, because what it answers changes: read `context.deadline` when\n   * you need it. `({ deadline }) => ...` reads it once, as the command\n   * starts, when it is always undefined, and keeps that.\n   */\n  readonly deadline: number | undefined\n}\n\n/** A command's default export. */\nexport type CommandFunction = (args: string[], context: CommandContext) => number | void | Promise<number | void>\n\n/**\n * Types a command's default export, so its arguments and context are known\n * without annotating them: `export default defineCommand(async (args, context) => {})`.\n * It returns what it is given.\n */\nexport function defineCommand(command: CommandFunction): CommandFunction {\n  return command\n}\n\n/** Resolves after the event loop has taken a turn, which is when it hands out the signals that arrived while it was busy. */\nconst nextTurn = () => new Promise<void>((resolve) => (typeof setImmediate === 'function' ? setImmediate(resolve) : setTimeout(resolve, 0)))\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      // A stop that arrived while the loop was busy with a synchronous load has\n      // not been delivered: a signal is delivered on the loop's next turn. One\n      // turn here, so that the command is told before it starts rather than a\n      // moment after - the same on Node, on Bun and in a binary.\n      await nextTurn()\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: ${describeError(error, true)}\\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: ${describeError(error, false)}\\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\n/**\n * An error and every cause under it, one line of `[cause]:` each.\n *\n * A library that wraps an error keeps the reason in `cause`, and a stack does\n * not print it: Drizzle's DrizzleQueryError carries the SQL as its message and\n * the database's refusal - a timeout, a wrong password - as its cause, so a\n * failed migration said what it tried and never why. A cause that is not an\n * Error is printed as it is, and a chain that loops back stops there.\n */\nfunction describeError(error: unknown, stack: boolean): string {\n  const seen = new Set<unknown>()\n  const parts: string[] = []\n  let current: unknown = error\n\n  while (current !== undefined && current !== null && !seen.has(current)) {\n    seen.add(current)\n    parts.push(\n      current instanceof Error ? (stack ? (current.stack ?? `${current.name}: ${current.message}`) : current.message) : String(current),\n    )\n    current = current instanceof Error ? current.cause : undefined\n  }\n\n  return parts.join('\\n[cause]: ')\n}\n"]}

package/dist/vite.js

@@ -1907,18 +1907,17 @@ async function prerenderAfterBundles(bundle, staticDir, assetsDir, knownActions
         console.log("     React's cache() dedupes only inside a component render; in a guard, an action or\n" +
             "     an api route it calls straight through. Import it from @rsc-kit/core/cache instead.");
     }
-    // Server files importing a client library. Legal - a server component may
-    // render a client component from a package - but the shape that costs an
-    // afternoon is a file with no "use client" that only wraps them, so the
-    // library's internals run on the server. Said, with the packages and the
-    // importer, so the person reading can tell which it is.
+    // Server files whose code, or a library's under them, reaches a hook on the
+    // server (clientImports.ts). The render that calls one fails naming React,
+    // not the file; this names the file, the package and the hook.
     if (clientLibraryImports.length > 0) {
-        console.log(`\n  \u2139  ${clientLibraryImports.length} server ${clientLibraryImports.length === 1 ? "file imports" : "files import"} a client library: ` +
+        console.log(`\n  \u2139  ${clientLibraryImports.length} server ${clientLibraryImports.length === 1 ? "file reaches" : "files reach"} client-only React: ` +
             clientLibraryImports
-                .map((c) => `${c.file} (${c.packages.join(", ")}${c.from ? `; imported by ${c.from}` : ""})`)
+                .map((c) => `${c.file} (${c.packages.length > 0 ? `${c.packages.join(", ")}: ` : ""}${c.calls.join(", ")}${c.from ? `; imported by ${c.from}` : ""})`)
                 .join("; "));
-        console.log('     Legal for a server component. A file that only wraps client components wants "use client" -\n' +
-            "     as shadcn ships it - so the server stops at the boundary.");
+        console.log('     The server has none of these, so a render that calls one fails with "... is not a function".\n' +
+            '     A file that only wraps client components wants "use client" - as shadcn ships it. A library\n' +
+            "     export holding a hook the page never renders is fine.");
     }
     // Written from the rows that were just printed rather than recomputed: the
     // report and the terminal must not be able to disagree about what happened.
@@ -7128,6 +7127,7 @@ function clientImportsAudit() {
                 moduleIds: () => this.getModuleIds(),
                 importedIds: (id) => this.getModuleInfo(id)?.importedIds ?? [],
                 importers: (id) => this.getModuleInfo(id)?.importers ?? [],
+                code: (id) => this.getModuleInfo(id)?.code ?? null,
             }, {
                 sourceDir,
                 clientPackages,