@pikku/cli 0.12.154 → 0.12.155

package/dist/src/fabric/lib/changes.js

@@ -1,6 +1,7 @@
 import { extname } from 'node:path';
 import { resolveApiContext } from './config.js';
 import { getFabricRPC } from './http.js';
+import { FabricPreconditionError } from './errors.js';
 /**
  * Resolve the three things every `changes` command needs: the api url, a
  * bearer, and the project the queue belongs to.
@@ -12,7 +13,7 @@ import { getFabricRPC } from './http.js';
 export async function changesContext(apiUrlOverride, projectIdOverride) {
     const ctx = await resolveApiContext({ apiUrlOverride });
     if (!ctx.token)
-        throw new Error('Not logged in. Run `pikku fabric login` first.');
+        throw new FabricPreconditionError('Not logged in. Run `pikku fabric login` first.');
     return {
         rpc: getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token }),
         projectId: projectIdOverride ?? ctx.projectId,
@@ -20,7 +21,7 @@ export async function changesContext(apiUrlOverride, projectIdOverride) {
 }
 export function requireProjectId(projectId) {
     if (!projectId)
-        throw new Error('No fabric project. Pass --project-id, or run `pikku fabric link` in the checkout.');
+        throw new FabricPreconditionError('No fabric project. Pass --project-id, or run `pikku fabric link` in the checkout.');
     return projectId;
 }
 /**

package/dist/src/fabric/lib/config.js

@@ -2,6 +2,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
+import { FabricPreconditionError } from './errors.js';
 const DEFAULT_API_URL = 'https://api.pikkufabric.com';
 const projectConfigName = 'pikkufabric.config.json';
 const authFilePath = join(homedir(), '.fabric', 'auth.json');
@@ -52,7 +53,7 @@ export async function writeProjectConfig(cwd, config) {
             raw = await readFile(path, 'utf8');
         }
         catch (error) {
-            throw new Error(`Cannot read ${projectConfigName} at ${path} (${error.message}) — refusing to overwrite it`);
+            throw new FabricPreconditionError(`Cannot read ${projectConfigName} at ${path} (${error.message}) — refusing to overwrite it`);
         }
         try {
             const parsed = JSON.parse(raw);

package/dist/src/fabric/lib/deployment.js

@@ -1,3 +1,4 @@
+import { FabricPreconditionError } from './errors.js';
 const IN_FLIGHT = new Set(['queued', 'planning', 'building', 'deploying']);
 const SUCCEEDED = new Set(['active']);
 const FAILED = new Set([
@@ -313,7 +314,7 @@ export function reconcileDeployedRef({ requested, actual, deploymentId, }) {
     if (actual === requested)
         return actual;
     const short = (sha) => sha.slice(0, 8);
-    throw new Error([
+    throw new FabricPreconditionError([
         `Refusing to continue: deployment ${deploymentId} is pinned to ${short(actual)}, not the ${short(requested)} you asked for.`,
         'A deployment already parked for this branch was attached to rather than a new one being cut,',
         'so continuing would deploy a different commit than the one named.',

package/dist/src/fabric/lib/git.d.ts

@@ -1,9 +1,18 @@
+import { PikkuError } from '@pikku/core/errors';
 /**
  * Local git probes for the deploy safety checks (clean tree, HEAD == remote,
  * ref resolution). Shell out to `git` rather than depend on simple-git —
  * matches what wrangler/vercel/fly do, no runtime dep.
  */
-export declare class GitError extends Error {
+/**
+ * A `git` invocation that came back non-zero.
+ *
+ * A `PikkuError`, because the message already carries the whole diagnosis —
+ * which command, which exit code, and git's own stderr — and ten frames of the
+ * spawn helper in front of "fatal: not a git repository" answer a question
+ * nobody asked. `--verbose` / `PIKKU_DEBUG` still prints the stack.
+ */
+export declare class GitError extends PikkuError {
     command: string;
     exitCode: number;
     stderr: string;

package/dist/src/fabric/lib/git.js

@@ -1,11 +1,20 @@
 import { spawn } from 'node:child_process';
 import { FabricPreconditionError } from './errors.js';
+import { PikkuError } from '@pikku/core/errors';
 /**
  * Local git probes for the deploy safety checks (clean tree, HEAD == remote,
  * ref resolution). Shell out to `git` rather than depend on simple-git —
  * matches what wrangler/vercel/fly do, no runtime dep.
  */
-export class GitError extends Error {
+/**
+ * A `git` invocation that came back non-zero.
+ *
+ * A `PikkuError`, because the message already carries the whole diagnosis —
+ * which command, which exit code, and git's own stderr — and ten frames of the
+ * spawn helper in front of "fatal: not a git repository" answer a question
+ * nobody asked. `--verbose` / `PIKKU_DEBUG` still prints the stack.
+ */
+export class GitError extends PikkuError {
     command;
     exitCode;
     stderr;

package/dist/src/fabric/lib/prompt.d.ts

@@ -1,12 +1,21 @@
 /**
- * Read a line from stdin with optional masking. Used for secret-set when the
- * user didn't pass `--value` on the command line so we can avoid leaving
- * the plaintext in shell history.
+ * Ask for a value that should not end up in shell history.
+ *
+ * With a tty this is a prompt. Without one — piped input, CI, an agent — the
+ * value is read from stdin instead, because scripting `pikku fabric secrets
+ * set` is a reasonable thing to want, and because a prompt with nobody to
+ * answer it is a hang. If stdin is closed or empty, `nonInteractiveHint` tells
+ * the caller which flag to reach for; it is raised as a `PikkuError` so
+ * `formatCLIError` prints that sentence and nothing else.
  */
-export declare function promptSecret(label: string): Promise<string>;
+export declare function promptSecret(label: string, { nonInteractiveHint }: {
+    nonInteractiveHint: string;
+}): Promise<string>;
 /**
  * Classic yes/no confirmation. Returns `defaultYes` on an empty answer.
  * Callers must gate on `process.stdin.isTTY` first — there is no human to
- * answer in a non-interactive session, so prompting there would hang.
+ * answer in a non-interactive session, so prompting there would hang. The
+ * guard below is the backstop for a caller that forgets: a refusal naming the
+ * question beats a process that never returns.
  */
 export declare function promptConfirm(label: string, defaultYes?: boolean): Promise<boolean>;

package/dist/src/fabric/lib/prompt.js

@@ -1,32 +1,95 @@
 import { createInterface } from 'node:readline/promises';
+import { createInterface as createLineInterface } from 'node:readline';
 import { stdin, stdout } from 'node:process';
+import { FabricPreconditionError } from './errors.js';
 /**
- * Read a line from stdin with optional masking. Used for secret-set when the
- * user didn't pass `--value` on the command line so we can avoid leaving
- * the plaintext in shell history.
+ * Read the first line stdin has to offer, or `null` if it has none.
+ *
+ * Resolves on the first newline rather than on EOF, so a pipe that stays open
+ * after the value has been written (a harness holding the write end, `cat |`)
+ * does not hang the command. `terminal: false` matters: readline's terminal
+ * mode tries to drive a tty it does not have, and on a closed stdin the
+ * `question()` promise it returns never settles at all — which is how
+ * `pikku fabric secrets set NAME < /dev/null` used to end in node's
+ * "Detected unsettled top-level await" warning instead of an error.
  */
-export async function promptSecret(label) {
+const readFirstLine = async () => {
+    const rl = createLineInterface({ input: stdin, terminal: false });
+    try {
+        return await new Promise((resolve) => {
+            rl.once('line', (line) => resolve(line));
+            rl.once('close', () => resolve(null));
+        });
+    }
+    finally {
+        rl.close();
+    }
+};
+/**
+ * Ask for a value that should not end up in shell history.
+ *
+ * With a tty this is a prompt. Without one — piped input, CI, an agent — the
+ * value is read from stdin instead, because scripting `pikku fabric secrets
+ * set` is a reasonable thing to want, and because a prompt with nobody to
+ * answer it is a hang. If stdin is closed or empty, `nonInteractiveHint` tells
+ * the caller which flag to reach for; it is raised as a `PikkuError` so
+ * `formatCLIError` prints that sentence and nothing else.
+ */
+export async function promptSecret(label, { nonInteractiveHint }) {
+    if (!stdin.isTTY) {
+        const piped = await readFirstLine();
+        const value = piped?.trim() ?? '';
+        if (!value) {
+            throw new FabricPreconditionError(`${label}: stdin is not a tty and nothing was piped in.\n${nonInteractiveHint}`);
+        }
+        return value;
+    }
     const rl = createInterface({ input: stdin, output: stdout, terminal: true });
     // Best-effort masking — the readline API doesn't suppress echo natively;
     // for hardened input you'd want `read -s` or a tty trick, but for our
     // CLI the standard prompt is fine and matches what wrangler does.
     process.stdout.write(`${label}: `);
-    const value = await rl.question('');
-    rl.close();
-    return value.trim();
+    try {
+        // `question()` never rejects when the stream ends under it, so the close is
+        // raced explicitly: ^D at a prompt is an abort, not an infinite wait.
+        const value = await Promise.race([
+            rl.question(''),
+            new Promise((resolve) => rl.once('close', () => resolve(null))),
+        ]);
+        if (value === null) {
+            throw new FabricPreconditionError(`${label}: input closed before a value was given.\n${nonInteractiveHint}`);
+        }
+        return value.trim();
+    }
+    finally {
+        rl.close();
+    }
 }
 /**
  * Classic yes/no confirmation. Returns `defaultYes` on an empty answer.
  * Callers must gate on `process.stdin.isTTY` first — there is no human to
- * answer in a non-interactive session, so prompting there would hang.
+ * answer in a non-interactive session, so prompting there would hang. The
+ * guard below is the backstop for a caller that forgets: a refusal naming the
+ * question beats a process that never returns.
  */
 export async function promptConfirm(label, defaultYes = false) {
+    if (!stdin.isTTY) {
+        throw new FabricPreconditionError(`Cannot ask "${label}" — stdin is not a tty. Re-run interactively, or pass the flag that answers it (--force / --auto-approve / --yes).`);
+    }
     const rl = createInterface({ input: stdin, output: stdout });
-    const answer = (await rl.question(`${label} [${defaultYes ? 'Y/n' : 'y/N'}] `))
-        .trim()
-        .toLowerCase();
-    rl.close();
-    if (!answer)
-        return defaultYes;
-    return answer === 'y' || answer === 'yes';
+    try {
+        const answer = await Promise.race([
+            rl.question(`${label} [${defaultYes ? 'Y/n' : 'y/N'}] `),
+            new Promise((resolve) => rl.once('close', () => resolve(null))),
+        ]);
+        if (answer === null)
+            return false;
+        const normalized = answer.trim().toLowerCase();
+        if (!normalized)
+            return defaultYes;
+        return normalized === 'y' || normalized === 'yes';
+    }
+    finally {
+        rl.close();
+    }
 }

package/dist/src/fabric/lib/sealed-box.js

@@ -16,6 +16,7 @@
  * business having one; opening a value happens in the worker.
  */
 import { createCipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from 'node:crypto';
+import { FabricPreconditionError } from './errors.js';
 /** Algorithm tag carried by every sealed value. Must match fabric's. */
 export const SEALED_BOX_ALGORITHM = 'sealed-x25519-v1';
 /** HKDF domain separator. Must match fabric's byte for byte. */
@@ -60,13 +61,13 @@ function importPublicKey(publicKey) {
         });
     }
     catch (error) {
-        throw new Error(`Not a valid X25519 public key (${error instanceof Error ? error.message : String(error)})`);
+        throw new FabricPreconditionError(`Not a valid X25519 public key (${error instanceof Error ? error.message : String(error)})`);
     }
     // A public key of the wrong curve would still ECDH, just against a key the
     // stage's worker cannot match — the failure would surface as an unopenable
     // secret much later, so refuse it at the point the type is still knowable.
     if (key.asymmetricKeyType !== 'x25519') {
-        throw new Error(`Stage sealing key is ${key.asymmetricKeyType}, expected x25519 — this CLI is too old for it, run \`npm i -g @pikku/cli\``);
+        throw new FabricPreconditionError(`Stage sealing key is ${key.asymmetricKeyType}, expected x25519 — this CLI is too old for it, run \`npm i -g @pikku/cli\``);
     }
     return key;
 }

package/dist/src/fabric/lib/stage.js

@@ -1,3 +1,4 @@
+import { FabricPreconditionError } from './errors.js';
 /**
  * Resolve a stage from (projectId, branch) via the `listStages` RPC. The
  * stageId-based read RPCs (listDeployments, listDeploymentWorkers,
@@ -22,13 +23,13 @@ export async function resolveStage(rpc, projectId, branch) {
         if (stages.length === 1 && only) {
             return { stageId: only.stageId, branch: only.branch };
         }
-        throw new Error(stages.length === 0
+        throw new FabricPreconditionError(stages.length === 0
             ? 'No stages deployed for this project yet — run `pikku fabric deploy apply <branch>` first.'
             : `--branch is required — this project has ${stages.length} stages: ${known.join(', ')}`);
     }
     const stage = stages.find((s) => s.branch === branch);
     if (!stage) {
-        throw new Error(`No stage for branch "${branch}".${known.length ? ` Existing: ${known.join(', ')}` : ''}`);
+        throw new FabricPreconditionError(`No stage for branch "${branch}".${known.length ? ` Existing: ${known.join(', ')}` : ''}`);
     }
     return { stageId: stage.stageId, branch: stage.branch };
 }

package/dist/src/functions/commands/watch.js

@@ -30,8 +30,11 @@ export const watch = pikkuSessionlessFunc({
                     });
                 }
                 catch (err) {
-                    console.error(err);
-                    logger.error('Error running watch');
+                    // Through the logger, so it obeys --log-level and the dev server's
+                    // formatting. `console.error(err)` printed a bare stack over the top
+                    // of the watch output no matter what verbosity was asked for.
+                    logger.error(`Error running watch: ${err instanceof Error ? err.message : String(err)}`);
+                    logger.debug(err instanceof Error ? (err.stack ?? '') : String(err));
                 }
             };
             // A codegen pass holds a whole ts.Program, so two overlapping passes double

package/dist/src/functions/wirings/agent/serialize-public-agent.js

@@ -203,6 +203,7 @@ export const agentRoutes = defineHTTPRoutes({
       route: '${globalHTTPPrefix}/rpc/agent/:agentName/stream',
       method: 'post',
       sse: true,
+      streamProtocol: 'agui',
       func: agentStreamCaller,
     },
     agentApprove: {
@@ -214,6 +215,7 @@ export const agentRoutes = defineHTTPRoutes({
       route: '${globalHTTPPrefix}/rpc/agent/:agentName/resume',
       method: 'post',
       sse: true,
+      streamProtocol: 'agui',
       func: agentResumeCaller,
     },
   },

package/dist/src/functions/wirings/cli/serialize-channel-cli-client.js

@@ -112,6 +112,7 @@ export function serializeChannelCLIClient(programName, programMeta, clientFile,
         : '';
     return `
 import { executeRawCLIViaChannel } from '@pikku/core/cli/channel'
+import { formatCLIError, wantsStackTrace } from '@pikku/core/cli'
 import type { CorePikkuCLIClientRender } from '@pikku/core/cli/channel'
 import type { Capabilities } from '@pikku/core/channel'
 import { CorePikkuWebsocket } from '@pikku/websocket'
@@ -218,12 +219,25 @@ if (isDirectExecution) {
     ws = new WebSocket(url)
   }
 
+  // Whatever comes back is printed the way the rest of the CLI prints errors:
+  // a deliberate error as its message, anything unexpected with its stack, and
+  // either with a stack under --verbose / PIKKU_DEBUG.
+  const reportFatal = (error: unknown): void => {
+    // stderr is asynchronous when it is a pipe, so exiting on the next line can
+    // truncate the diagnostic. Exit from the write callback, with exitCode set
+    // first in case the stream is already gone and the callback never fires.
+    process.exitCode = 1
+    process.stderr.write(
+      formatCLIError(error, { verbose: wantsStackTrace(process.argv.slice(2)) }) + '\\n',
+      () => process.exit(1)
+    )
+  }
+  process.on('uncaughtException', reportFatal)
+  process.on('unhandledRejection', reportFatal)
+
   ${capitalizedName}CLIClient(ws, process.argv.slice(2))
     .then((exitCode) => process.exit(exitCode))
-    .catch(error => {
-      console.error('Fatal channel CLI error:', error)
-      process.exit(1)
-    })
+    .catch(reportFatal)
 }
 `;
 }

package/dist/src/functions/wirings/cli/serialize-local-cli-bootstrap.js

@@ -14,7 +14,7 @@ export function serializeLocalCLIBootstrap(programName, _programMeta, bootstrapF
         : null;
     const cliBootstrapPath = getFileImportRelativePath(bootstrapFile, config.bootstrapFile, config.packageMappings);
     return `
-import { executeCLI, CLIError } from '@pikku/core/cli'
+import { executeCLI, CLIError, formatCLIError, wantsStackTrace } from '@pikku/core/cli'
 ${pikkuConfigFactory ? `import { ${pikkuConfigFactory.variable} as createConfig } from '${pikkuConfigPath}'` : ''}
 import { ${singletonServicesFactory.variable} as createSingletonServices } from '${singletonServicesPath}'
 ${wireServicesFactory ? `import { ${wireServicesFactory.variable} as createWireServices } from '${wireServicesPath}'` : ''}
@@ -44,10 +44,21 @@ export default ${capitalizedName}CLI
 ${DIRECT_EXECUTION_GUARD}
 
 if (isDirectExecution) {
-  ${capitalizedName}CLI(process.argv.slice(2)).catch(error => {
-    console.error('Fatal error:', error.message)
-    process.exit(1)
-  })
+  const reportFatal = (error: unknown): void => {
+    // executeCLI already printed a CLIError; it carries the exit code, not text.
+    if (error instanceof CLIError) process.exit(error.exitCode)
+    // stderr is asynchronous when it is a pipe, so exiting on the next line can
+    // truncate the diagnostic. Exit from the write callback, with exitCode set
+    // first in case the stream is already gone and the callback never fires.
+    process.exitCode = 1
+    process.stderr.write(
+      formatCLIError(error, { verbose: wantsStackTrace(process.argv.slice(2)) }) + '\\n',
+      () => process.exit(1)
+    )
+  }
+  process.on('uncaughtException', reportFatal)
+  process.on('unhandledRejection', reportFatal)
+  ${capitalizedName}CLI(process.argv.slice(2)).catch(reportFatal)
 }
 `;
 }

package/dist/src/functions/wirings/functions/pikku-command-addon-types.js

@@ -5,6 +5,25 @@ import { checkRequiredTypes } from '../../../utils/check-required-types.js';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeAddonInstallTypes, serializeAddonTypes, } from './serialize-addon-types.js';
+/**
+ * The functions each installed addon publishes, by package — what `mcp` on a
+ * `wireAddon` is typed against. A package wired twice contributes the same
+ * names under both namespaces, and a remote addon contributes none: its
+ * functions run on the host, and it is `wireRemoteAddon` that installs it.
+ */
+const addonFunctionNames = (state) => {
+    const names = {};
+    for (const [namespace, decl] of state.rpc.wireAddonDeclarations) {
+        if (decl.remote) {
+            continue;
+        }
+        const meta = state.addonFunctions[namespace];
+        if (meta) {
+            names[decl.package] = Object.keys(meta);
+        }
+    }
+    return names;
+};
 export const pikkuAddonTypes = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }, input) => {
         const { addonTypesFile, addonSetupTypesFile, packageMappings, servicesFile, secretsFile, credentialsFile, variablesFile, } = config;
@@ -15,14 +34,16 @@ export const pikkuAddonTypes = pikkuSessionlessFunc({
         await rm(config.addon ? addonTypesFile : addonSetupTypesFile, {
             force: true,
         });
-        // An application installs addons; an addon package declares itself. Both
-        // halves are static, so the app half needs no inspector pass and is written
-        // on the bootstrap run as readily as on the full one.
+        const bootstrap = input?.bootstrap === true;
+        // An application installs addons; an addon package declares itself. The app
+        // half is written on the bootstrap run too — `wireAddon` has to resolve
+        // before the inspector can read the calls that say which addons are
+        // installed — but only the full run knows what each addon publishes, so
+        // that is when `mcp` gets its names.
         if (!config.addon) {
-            await writeFileInDir(logger, addonTypesFile, serializeAddonInstallTypes());
+            await writeFileInDir(logger, addonTypesFile, serializeAddonInstallTypes(bootstrap ? {} : addonFunctionNames(await getInspectorState())));
             return;
         }
-        const bootstrap = input?.bootstrap === true;
         if (bootstrap) {
             await writeFileInDir(logger, addonSetupTypesFile, 'export {}\n');
             return;

package/dist/src/functions/wirings/functions/serialize-addon-types.d.ts

@@ -10,5 +10,5 @@
  * `#pikku/addon/<leaf>` — a depth at which an application has nothing to match,
  * leaving the resolver to fall back to Node's per-package `imports`.
  */
-export declare const serializeAddonInstallTypes: () => string;
+export declare const serializeAddonInstallTypes: (addonFunctionNames?: Record<string, string[]>) => string;
 export declare const serializeAddonTypes: (singletonServicesTypeImport: string, singletonServicesTypeName: string, configTypeImport: string, requiredServicesTypeImport: string, typedSecretServiceImport: string, typedVariablesServiceImport: string, typedCredentialServiceImport?: string | null) => string;

package/dist/src/functions/wirings/functions/serialize-addon-types.js

@@ -10,12 +10,57 @@
  * `#pikku/addon/<leaf>` — a depth at which an application has nothing to match,
  * leaving the resolver to fall back to Node's per-package `imports`.
  */
-export const serializeAddonInstallTypes = () => `/**
+export const serializeAddonInstallTypes = (addonFunctionNames = {}) => {
+    const packages = Object.entries(addonFunctionNames).filter(([, names]) => names.length > 0);
+    // Nothing installed yet — the bootstrap run writes this before any addon's
+    // metadata has been read, and a project with no addons never gets more.
+    if (packages.length === 0) {
+        return `/**
  * Installing an addon into this application
  */
 
 export { wireAddon, wireRemoteAddon } from '@pikku/core/addon'
 `;
+    }
+    const entries = packages
+        .map(([pkg, names]) => `  ${JSON.stringify(pkg)}: ${names
+        .map((name) => JSON.stringify(name))
+        .join(' | ')}`)
+        .join('\n');
+    return `/**
+ * Installing an addon into this application
+ */
+
+import { wireAddon as wireAddonCore } from '@pikku/core/addon'
+import type { WireAddonConfig } from '@pikku/core/addon'
+
+export { wireRemoteAddon } from '@pikku/core/addon'
+
+/**
+ * The functions each installed addon publishes. \`mcp\` names them.
+ */
+type AddonFunctions = {
+${entries}
+}
+
+type AddonFunctionName<Package extends string> =
+  Package extends keyof AddonFunctions ? AddonFunctions[Package] : string
+
+/**
+ * Installs an addon into this project: its functions, wirings and scopes become
+ * part of the app, under the namespace and options given here.
+ *
+ * \`mcp: true\` offers every function the addon itself declared as a tool; a list
+ * names the functions to offer, checked against the ones the addon publishes.
+ */
+export const wireAddon = <Package extends string>(
+  config: Omit<WireAddonConfig, 'package' | 'mcp'> & {
+    package: Package
+    mcp?: boolean | AddonFunctionName<Package>[]
+  }
+): void => wireAddonCore(config)
+`;
+};
 export const serializeAddonTypes = (singletonServicesTypeImport, singletonServicesTypeName, configTypeImport, requiredServicesTypeImport, typedSecretServiceImport, typedVariablesServiceImport, typedCredentialServiceImport = null) => {
     return `/**
  * Addon package types for pikkuAddonConfig and pikkuAddonServices

package/dist/src/functions/wirings/mcp/pikku-command-mcp.js

@@ -44,7 +44,9 @@ const generateArgumentsFromSchema = async (inputSchema, schemaDirectory, typesMa
     }
     catch (e) {
         logger.warn(`Command MCP: Could not load schema for type: ${uniqueName} from ${schemaPath}`);
-        console.error(e);
+        // The warning above is the actionable half; the cause is detail, and detail
+        // belongs behind the verbosity control rather than on everyone's stderr.
+        logger.debug(e instanceof Error ? (e.stack ?? e.message) : String(e));
         return [];
     }
 };

package/dist/src/functions/wirings/middleware/pikku-command-middleware.js

@@ -13,10 +13,22 @@ export const pikkuMiddleware = pikkuSessionlessFunc({
         const hasDefinitions = Object.keys(state.middleware.definitions).length > 0;
         const hasChannelMiddleware = state.channelMiddleware.tagMiddleware.size > 0 ||
             Object.keys(state.channelMiddleware.definitions).length > 0;
+        // A project whose only middleware is `addGlobalMiddleware([...])` over
+        // middleware defined in a package (a session bridge, say) has no group and
+        // no local definition, and used to generate no middleware file at all — so
+        // the registration never ran.
+        // `globalFiles` is the current record, but the serializer also still reads
+        // `global:*` out of `instances` so that a state serialized by an older
+        // inspector keeps working. This gate decides whether the serializer runs at
+        // all, so it has to accept exactly what the serializer accepts — otherwise
+        // an older state is dropped here and the file it needed is never written.
+        const hasGlobalMiddleware = (state.middleware.globalFiles?.size ?? 0) > 0 ||
+            Object.keys(state.middleware.instances).some((id) => id.startsWith('global:'));
         if (hasHTTPGroups ||
             hasTagGroups ||
             hasDefinitions ||
-            hasChannelMiddleware) {
+            hasChannelMiddleware ||
+            hasGlobalMiddleware) {
             const metaData = state.middlewareGroupsMeta;
             await writeFileInDir(logger, config.middlewareGroupsMetaJsonFile, JSON.stringify(metaData, null, 2));
             await writeFileInDir(logger, middlewareFile, serializeMiddlewareImports(middlewareFile, middleware, state.http, packageMappings, state));

package/dist/src/functions/wirings/middleware/serialize-middleware-imports.d.ts

@@ -1,2 +1,15 @@
 import type { InspectorMiddlewareState, InspectorHTTPState, InspectorState } from '@pikku/inspector';
 export declare const serializeMiddlewareImports: (outputPath: string, middlewareState: InspectorMiddlewareState, httpState: InspectorHTTPState, packageMappings?: Record<string, string>, fullState?: InspectorState) => string;
+/**
+ * Fail the build if a file that calls `addGlobalMiddleware` has no side-effect
+ * import in the generated middleware file.
+ *
+ * Auth commonly lives in global middleware, and a deployed unit that misses its
+ * import does not fail to build — it serves every authenticated route a 401
+ * with a clean build log. Checking the emitted text (rather than the set it was
+ * built from) is what makes this a check and not a restatement: it fails if the
+ * emit is ever dropped, put behind a condition, or handed a path the import
+ * list does not actually carry. It cannot fire on a build that does emit the
+ * import.
+ */
+export declare const assertGlobalMiddlewareImported: (outputPath: string, output: string, globalImportPaths: Map<string, string>) => void;

package/dist/src/functions/wirings/middleware/serialize-middleware-imports.js

@@ -54,21 +54,34 @@ export const serializeMiddlewareImports = (outputPath, middlewareState, httpStat
     // Global middleware (addGlobalMiddleware) is registered by a top-level call
     // at module evaluation, so a side-effect import of its source file runs the
     // registration. Unlike tag/http middleware it has no associated wire group —
-    // it lives only in `instances` keyed `global:*` — so the per-unit `--names`
-    // filter leaves it out of every deployed unit (the `state.http.files`
-    // fallback that add-middleware adds gets stripped by that filter). Emitting
-    // it here, into the always-bootstrap-imported pikku-middleware.gen.ts,
-    // guarantees global middleware registers in every unit. A duplicate import
-    // in full builds is harmless — module bodies evaluate once.
+    // the inspector records it as a source file in `globalFiles` (and as
+    // `global:*` entries in `instances`) — so the per-unit `--names` filter
+    // leaves it out of every deployed unit (the `state.http.files` fallback that
+    // add-middleware adds gets stripped by that filter). Emitting it here, into
+    // the always-bootstrap-imported pikku-middleware.gen.ts, guarantees global
+    // middleware registers in every unit. A duplicate import in full builds is
+    // harmless — module bodies evaluate once.
     //
     // `isFactoryCall` is not consulted: it distinguishes `mw()` from `mw` as an
     // array element, not a deferred registration behind an exported factory, and
     // addGlobalMiddleware registers at module evaluation under either form.
+    //
+    // `globalFiles` is the primary source: it is a plain set of file names, where
+    // `instances` is a map whose keys an unrelated registration could once
+    // collide with. The `global:*` sweep stays as well, so a state serialized by
+    // an older inspector (no `globalFiles`) still emits its imports.
+    const globalSourceFiles = new Set(middlewareState.globalFiles ?? []);
     for (const [instanceId, instance] of Object.entries(middlewareState.instances)) {
         if (instanceId.startsWith('global:')) {
-            directImports.add(getFileImportRelativePath(outputPath, instance.sourceFile, packageMappings));
+            globalSourceFiles.add(instance.sourceFile);
         }
     }
+    const globalImportPaths = new Map();
+    for (const sourceFile of globalSourceFiles) {
+        const filePath = getFileImportRelativePath(outputPath, sourceFile, packageMappings);
+        globalImportPaths.set(sourceFile, filePath);
+        directImports.add(filePath);
+    }
     const allFactories = new Map([
         ...httpFactories,
         ...tagFactories,
@@ -90,5 +103,32 @@ export const serializeMiddlewareImports = (outputPath, middlewareState, httpStat
             serializedFactoryCalls.push(`${exportName}()`);
         }
     }
-    return [...serializedImports, ...serializedFactoryCalls].join('\n');
+    const output = [...serializedImports, ...serializedFactoryCalls].join('\n');
+    assertGlobalMiddlewareImported(outputPath, output, globalImportPaths);
+    return output;
+};
+/**
+ * Fail the build if a file that calls `addGlobalMiddleware` has no side-effect
+ * import in the generated middleware file.
+ *
+ * Auth commonly lives in global middleware, and a deployed unit that misses its
+ * import does not fail to build — it serves every authenticated route a 401
+ * with a clean build log. Checking the emitted text (rather than the set it was
+ * built from) is what makes this a check and not a restatement: it fails if the
+ * emit is ever dropped, put behind a condition, or handed a path the import
+ * list does not actually carry. It cannot fire on a build that does emit the
+ * import.
+ */
+export const assertGlobalMiddlewareImported = (outputPath, output, globalImportPaths) => {
+    const missing = [...globalImportPaths.entries()].filter(([, filePath]) => !output.includes(`import '${filePath}'`));
+    if (missing.length === 0) {
+        return;
+    }
+    throw new Error(`Global middleware would not be registered in ${outputPath}.\n` +
+        `These files call addGlobalMiddleware() but no side-effect import for them was emitted:\n` +
+        missing.map(([sourceFile]) => `  - ${sourceFile}`).join('\n') +
+        `\n\nGlobal middleware — auth gates included — only runs if its module is imported, so ` +
+        `this build would start up with it silently missing. Re-run \`pikku all\`; if it persists, ` +
+        `register the middleware from a file that also makes a wire registration ` +
+        `(e.g. addHTTPMiddleware) and report this as a pikku bug.`);
 };