@pikku/cli 0.12.93 → 0.12.99

package/dist/src/functions/wirings/auth/serialize-auth-gen.js

@@ -40,11 +40,26 @@ function variableSchemaName(name, field) {
 // addHTTPMiddleware('*') call as the session middleware: the inspector keys
 // route-middleware groups by pattern, so a second '*' registration from another
 // file would silently displace this one in deployed units.
+//
+// The session carries the two scope roots the console addon gates itself on.
+// Without them this token authenticates but authorizes nothing: `wireAddon`
+// gates the whole addon on `admin`, so every console:* RPC — reads included —
+// answers MissingScopeError, and an external console can reach the deployment
+// while being unable to do a single thing in it.
+//
+// Roots rather than a wildcard: a parent grant satisfies its children, so
+// `admin` covers `admin:*` and `pikku` covers `pikku:scopes:*`/`pikku:audit:*`,
+// which is every scope the console's own functions require. A `*` would also
+// hand the token every scope the HOST app declares, which is authority the
+// console never asks for.
 const consoleTokenMiddlewareLines = () => [
     `  authBearer({`,
     `    token: {`,
     `      secretId: 'PIKKU_CONSOLE_TOKEN',`,
-    `      userSession: { userId: 'pikku-console-token' },`,
+    `      userSession: {`,
+    `        userId: 'pikku-console-token',`,
+    `        scopes: ['admin', 'pikku'],`,
+    `      },`,
     `    },`,
     `  }),`,
 ];
@@ -59,22 +74,22 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
     // the package's `imports` map (e.g. a project's `pikku/` dir), where `#pikku`
     // would not resolve. This mirrors how the console/agent scaffolds import it.
     const pikkuTypesImportPath = getFileImportRelativePath(authFile, typesDeclarationFile, packageMappings);
-    // ─── Secrets file: Zod schemas + wireSecret/wireVariable ──────────────────
+    // ─── Secrets file: Zod schemas + defineSecret/defineVariable ──────────────────
     const secrets = [
         '// AUTO-GENERATED by pikku CLI — do not edit',
         '',
-        `import { wireSecret } from '@pikku/core/secret'`,
+        `import { defineSecret } from '@pikku/core/secret'`,
     ];
     const hasVariables = known.some((name) => PROVIDER_REGISTRY[name].variables);
     if (hasVariables) {
-        secrets.push(`import { wireVariable } from '@pikku/core/variable'`);
+        secrets.push(`import { defineVariable } from '@pikku/core/variable'`);
     }
     secrets.push(`import { z } from 'zod'`, '');
     // better-auth's session-signing secret is always required (its BETTER_AUTH_SECRET
     // env convention). Wire it so the platform collects it, regardless of providers.
     secrets.push(`export const BetterAuthSecretSchema = z.string()`);
     secrets.push('');
-    secrets.push(`wireSecret({`);
+    secrets.push(`defineSecret({`);
     secrets.push(`  name: 'betterAuthSecret',`);
     secrets.push(`  displayName: 'Better Auth Secret',`);
     secrets.push(`  description: 'Signing secret for better-auth sessions',`);
@@ -92,12 +107,12 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
         secrets.push(`})`);
         secrets.push('');
     }
-    // wireSecret for each provider.
+    // defineSecret for each provider.
     for (const name of known) {
         const def = PROVIDER_REGISTRY[name];
         const schemaName = providerSchemaName(name);
         const secretName = providerSecretName(name);
-        secrets.push(`wireSecret({`);
+        secrets.push(`defineSecret({`);
         secrets.push(`  name: '${secretName}',`);
         secrets.push(`  displayName: '${def.displayName}',`);
         secrets.push(`  secretId: '${def.secretId}',`);
@@ -105,7 +120,7 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
         secrets.push(`})`);
         secrets.push('');
     }
-    // wireVariable for providers with non-secret config (issuer, tenantId, etc.).
+    // defineVariable for providers with non-secret config (issuer, tenantId, etc.).
     for (const name of known) {
         const def = PROVIDER_REGISTRY[name];
         if (!def.variables)
@@ -116,7 +131,7 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
             const schemaName = variableSchemaName(name, field);
             secrets.push(`export const ${schemaName} = z.string()`);
             secrets.push('');
-            secrets.push(`wireVariable({`);
+            secrets.push(`defineVariable({`);
             secrets.push(`  name: '${name}_${field}',`);
             secrets.push(`  displayName: '${def.displayName} ${capitalize(field)}',`);
             secrets.push(`  description: '${meta.description}',`);

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

@@ -16,7 +16,9 @@
  * them at runtime — the same treatment addon services get from
  * `pikkuAddonServices`. That gives the factory typed, map-aware access:
  *
- *   socialProviders: { github: await secrets.getSecret('GITHUB_OAUTH') }
+ *   socialProviders: {
+ *     github: (await secrets.getSecret('GITHUB_OAUTH')).reveal(),
+ *   }
  *
  * with no inline `getSecrets<{ ... }>()` generic, because the secret types flow
  * from the generated `CredentialsMap`.

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

@@ -17,7 +17,9 @@ import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
  * them at runtime — the same treatment addon services get from
  * `pikkuAddonServices`. That gives the factory typed, map-aware access:
  *
- *   socialProviders: { github: await secrets.getSecret('GITHUB_OAUTH') }
+ *   socialProviders: {
+ *     github: (await secrets.getSecret('GITHUB_OAUTH')).reveal(),
+ *   }
  *
  * with no inline `getSecrets<{ ... }>()` generic, because the secret types flow
  * from the generated `CredentialsMap`.

package/dist/src/functions/wirings/channels/pikku-channels.d.ts

@@ -1 +1 @@
-export declare const pikkuChannels: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuChannels: import("#pikku").PikkuFunctionSessionlessConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/channels/serialize-typed-channel-map.js

@@ -109,15 +109,23 @@ function generateChannels(logger, typesMap, functionsMeta, addonFunctions, chann
             }
         }
     }
+    /**
+     * A route or message key that is not a bare identifier has to be quoted to be
+     * a legal property name. Channel routes are author-chosen strings and a CLI
+     * channel's are command ids, where `app-smoke` and `registry.search` are the
+     * norm — unquoted, each one ends the property early and the whole map fails
+     * to parse. Quoted only when it has to be, so existing output is unchanged.
+     */
+    const propertyKey = (key) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : `'${key}'`;
     let routesStr = 'export type ChannelsMap = {\n';
     for (const [channelPath, { routes, message }] of Object.entries(channelsObject)) {
         routesStr += `  readonly '${channelPath}': {\n`;
         // Add `routes` object
         routesStr += `    readonly routes: {\n`;
         for (const [key, methods] of Object.entries(routes)) {
-            routesStr += `      readonly ${key}: {\n`;
+            routesStr += `      readonly ${propertyKey(key)}: {\n`;
             for (const [method, handler] of Object.entries(methods)) {
-                routesStr += `        readonly ${method}: ChannelHandler<${formatTypeArray(handler.inputTypes) || 'void'}, ${formatTypeArray(handler.outputTypes) || 'never'}>,\n`;
+                routesStr += `        readonly ${propertyKey(method)}: ChannelHandler<${formatTypeArray(handler.inputTypes) || 'void'}, ${formatTypeArray(handler.outputTypes) || 'never'}>,\n`;
             }
             routesStr += '      },\n';
         }

package/dist/src/functions/wirings/cli/pikku-command-cli-entry.js

@@ -64,15 +64,20 @@ export const pikkuCLIEntry = pikkuSessionlessFunc({
                     // Generate client code if clientPath is provided
                     if (channelClientPath) {
                         const channelClientFile = join(config.rootDir, channelClientPath);
-                        // Validate that renderers don't depend on services (client-side renderers can't access server services)
+                        // A renderer for a CLI-over-channel program runs on the client, where
+                        // there is no service container to resolve from — the only thing the
+                        // runtime can hand it is a logger. Anything else it destructures
+                        // would be undefined at runtime, so it fails generation instead.
                         const rendererNames = collectRendererNames(programMeta);
                         const problematicRenderers = [];
                         for (const rendererName of rendererNames) {
                             const rendererMeta = visitState.cli.meta.renderers[rendererName];
-                            if (rendererMeta?.services?.services?.length > 0) {
+                            const services = rendererMeta?.services?.services ?? [];
+                            const unavailable = services.filter((name) => name !== 'logger');
+                            if (unavailable.length > 0) {
                                 problematicRenderers.push({
                                     name: rendererName,
-                                    services: rendererMeta.services.services,
+                                    services: unavailable,
                                 });
                             }
                         }
@@ -81,7 +86,7 @@ export const pikkuCLIEntry = pikkuSessionlessFunc({
                             const details = problematicRenderers
                                 .map((r) => `  - ${r.name} depends on: ${r.services.join(', ')}`)
                                 .join('\n');
-                            logger.critical(ErrorCode.CLI_CLIENTSIDE_RENDERER_HAS_SERVICES, `Cannot generate CLI channel client for '${programName}': renderers cannot depend on services (client-side execution)\n${details}\n\nRenderers used in CLI-over-channel must be service-free since they execute on the client.`);
+                            logger.critical(ErrorCode.CLI_CLIENTSIDE_RENDERER_HAS_SERVICES, `Cannot generate CLI channel client for '${programName}': a renderer reached for a service that does not exist on the client\n${details}\n\nRenderers in a CLI-over-channel program run on the client side of the socket, where the only available service is 'logger'.`);
                             // Delete existing client file if it exists
                             if (existsSync(channelClientFile)) {
                                 await rm(channelClientFile);

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

@@ -5,7 +5,11 @@ import type { Config } from '../../../../types/application-types.js';
  */
 export declare function collectRendererNames(programMeta: CLIProgramMeta): Set<string>;
 /**
- * Serializes a CLI-over-Channel client bootstrap file
- * Similar to local CLI bootstrap but uses WebSocket connection
+ * Serializes a CLI-over-Channel client bootstrap file.
+ *
+ * The client deliberately does NOT import the CLI bootstrap: loading the
+ * command tree here would bind the client's version to the server's, which is
+ * the coupling running commands remotely exists to remove. Renderers are the
+ * only local artefact, and they are optional.
  */
-export declare function serializeChannelCLIClient(programName: string, programMeta: CLIProgramMeta, clientFile: string, config: Config, cliBootstrapPath: string, channelRoute?: string, renderersMeta?: Record<string, any>): string;
+export declare function serializeChannelCLIClient(programName: string, programMeta: CLIProgramMeta, clientFile: string, config: Config, _cliBootstrapPath: string, channelRoute?: string, renderersMeta?: Record<string, any>): string;

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

@@ -1,4 +1,5 @@
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { DIRECT_EXECUTION_GUARD } from './serialize-cli-entrypoint-guard.js';
 /**
  * Collect all unique renderer names from CLI metadata (populated by inspector)
  */
@@ -65,14 +66,16 @@ function buildRenderersMap(programMeta, renderersMeta) {
     return `{\n${entries.join(',\n')}\n  }`;
 }
 /**
- * Serializes a CLI-over-Channel client bootstrap file
- * Similar to local CLI bootstrap but uses WebSocket connection
+ * Serializes a CLI-over-Channel client bootstrap file.
+ *
+ * The client deliberately does NOT import the CLI bootstrap: loading the
+ * command tree here would bind the client's version to the server's, which is
+ * the coupling running commands remotely exists to remove. Renderers are the
+ * only local artefact, and they are optional.
  */
-export function serializeChannelCLIClient(programName, programMeta, clientFile, config, cliBootstrapPath, channelRoute, renderersMeta) {
+export function serializeChannelCLIClient(programName, programMeta, clientFile, config, _cliBootstrapPath, channelRoute, renderersMeta) {
     const capitalizedName = programName.charAt(0).toUpperCase() + programName.slice(1).replace(/-/g, '');
     const finalChannelRoute = channelRoute || `/cli/${programName}`;
-    // Get relative import path to CLI bootstrap (for metadata)
-    const bootstrapImportPath = getFileImportRelativePath(clientFile, cliBootstrapPath, config.packageMappings);
     // Collect all unique renderer names from CLI metadata (populated by inspector)
     const rendererNames = collectRendererNames(programMeta);
     // Generate renderer imports from their source files
@@ -105,32 +108,48 @@ export function serializeChannelCLIClient(programName, programMeta, clientFile,
         ? resolveRendererBinding(programMeta.defaultRenderName, renderersMeta)
         : null;
     const defaultRendererCode = defaultRendererBinding
-        ? `,\n    defaultRenderer: ${defaultRendererBinding}`
+        ? `,\n    defaultRenderer: ${defaultRendererBinding} as CorePikkuCLIClientRender<any>`
         : '';
     return `
-import { executeCLIViaChannel } from '@pikku/core/cli/channel'
+import { executeRawCLIViaChannel } from '@pikku/core/cli/channel'
+import type { CorePikkuCLIClientRender } from '@pikku/core/cli/channel'
+import type { Capabilities } from '@pikku/core/channel'
 import { CorePikkuWebsocket } from '@pikku/websocket'
-import '${bootstrapImportPath}'
 ${rendererImports}
 /**
  * ${capitalizedName} CLI Client (via WebSocket Channel)
- * Executes CLI commands over a WebSocket connection
+ *
+ * Forwards argv to the server untouched — the command tree is never parsed
+ * here, so this client stays valid as the server's commands change. Renderers
+ * are matched by the command id the server reports; anything it doesn't
+ * recognise falls back to JSON.
+ *
+ * \`capabilities\` are the functions this client agrees to run on the server's
+ * behalf (a git sha, a local path). It is an allowlist, not a convenience —
+ * nothing outside it is reachable from the server. A bare function is
+ * unclassified and so needs approval before every call; write
+ * \`{ execute, needsApproval: false }\` for one that may run unattended.
  */
 export async function ${capitalizedName}CLIClient(
   ws: WebSocket,
-  args?: string[]
-): Promise<void> {
+  args?: string[],
+  capabilities: Capabilities = {}
+): Promise<number> {
   // Create Pikku WebSocket wrapper
   const pikkuWS = new CorePikkuWebsocket(ws)
 
-  // Register renderers for CLI commands
-  const renderers = ${renderersMap}
+  // Renderers are declared against this app's \`SingletonServices\`, but on this
+  // side of the socket the only service that exists is a logger. The cast is
+  // sound because generation refuses to emit this file at all when a renderer
+  // reaches for anything else — see CLI_CLIENTSIDE_RENDERER_HAS_SERVICES. It is
+  // localised here so \`executeRawCLIViaChannel\` can keep an honest signature.
+  const renderers = ${renderersMap} as Record<string, CorePikkuCLIClientRender<any>>
 
-  await executeCLIViaChannel({
-    programName: '${programName}',
+  return executeRawCLIViaChannel({
     pikkuWS,
     args,
-    renderers${defaultRendererCode},
+    renderers,
+    capabilities${defaultRendererCode},
   })
 }
 
@@ -138,15 +157,17 @@ export async function ${capitalizedName}CLIClient(
 export default ${capitalizedName}CLIClient
 
 // For direct execution (if this file is run directly)
-if (import.meta.url === \`file://\${process.argv[1]}\`) {
+${DIRECT_EXECUTION_GUARD}
+
+if (isDirectExecution) {
   const url = process.env.PIKKU_WS_URL || 'ws://localhost:4002${finalChannelRoute}'
 
   // Attach credentials so the channel authenticates like any other pikku client.
   // A machine API key (PIKKU_API_KEY -> x-api-key) takes precedence; otherwise
   // the human session token saved by \`pikku login\` (~/.pikku/session.json ->
-  // Authorization: Bearer) is used. This block only runs under Node (direct
-  // execution), so reading the session file and using the 'ws' headers option
-  // is safe — the browser WebSocket cannot set custom headers anyway.
+  // Authorization: Bearer) is used. This block only runs on a server runtime
+  // (direct execution), so reading the session file is safe — a browser could
+  // neither reach it nor set custom headers on its WebSocket.
   const headers: Record<string, string> = {}
   if (process.env.PIKKU_API_KEY) {
     headers['x-api-key'] = process.env.PIKKU_API_KEY
@@ -173,21 +194,36 @@ if (import.meta.url === \`file://\${process.argv[1]}\`) {
   }
   const hasAuth = Object.keys(headers).length > 0
 
-  // Custom headers require the Node 'ws' module — the global/browser WebSocket
-  // cannot set them — so prefer 'ws' whenever we have credentials to send.
+  // Node's global WebSocket reads its second argument as subprotocols and drops
+  // custom headers on the floor, so credentials there need the 'ws' module.
+  // Bun's honours them natively, and reaching for 'ws' under Bun would load its
+  // compatibility shim for nothing. Detected once, the way the CLI picks its
+  // dev-server runner.
+  const isBun = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'
+
+  // Only the header-carrying Bun call needs the cast: the DOM lib types the
+  // second argument as subprotocols, which is what Node implements.
+  type WebSocketWithHeaders = new (
+    url: string,
+    options: { headers: Record<string, string> }
+  ) => WebSocket
+
   let ws: WebSocket
-  if (hasAuth || typeof WebSocket === 'undefined') {
+  if (!isBun && (hasAuth || typeof WebSocket === 'undefined')) {
     const wsModule = await import('ws')
     ws = new wsModule.default(url, { headers }) as unknown as WebSocket
+  } else if (hasAuth) {
+    ws = new (WebSocket as unknown as WebSocketWithHeaders)(url, { headers })
   } else {
     ws = new WebSocket(url)
   }
 
-  ${capitalizedName}CLIClient(ws, process.argv.slice(2)).catch(error => {
-    console.error('Fatal channel CLI error:', error)
-    // TODO: We get an error code even when it exists cleanly, investigate
-    // process.exit(1)
-  })
+  ${capitalizedName}CLIClient(ws, process.argv.slice(2))
+    .then((exitCode) => process.exit(exitCode))
+    .catch(error => {
+      console.error('Fatal channel CLI error:', error)
+      process.exit(1)
+    })
 }
 `;
 }

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

@@ -60,7 +60,7 @@ export function serializeChannelCLI(programName, programMeta, channelFile, funct
 import { wireChannel } from '${channelTypesPath}'
 import { pikkuMiddleware${hasAddonFuncs ? ', ref' : ''}, pikkuSessionlessFunc } from '${functionTypesPath}'
 import { generateCommandHelp } from '@pikku/core/cli'
-import { handleRawCLI } from '@pikku/core/cli/channel'
+import { handleRawCLI, type RawCLIFrame } from '@pikku/core/cli/channel'
 import { pikkuState } from '@pikku/core/internal'
 ${imports}
 
@@ -97,22 +97,79 @@ export const cliHelp = pikkuSessionlessFunc<{ args?: string[] }, { help: string
   },
 })
 
-export const cliRaw = pikkuSessionlessFunc<{ args: string[] }, { help?: string; result?: unknown; error?: string }>({
+/**
+ * Raw entry point: the client forwards argv untouched and this side owns
+ * parsing, so a client binary never carries the command tree and its version
+ * is free to drift from the server's.
+ *
+ * Progressive output is streamed on the same channel rather than returned,
+ * and the terminating control frame carries the exit code so the client
+ * process can exit non-zero.
+ */
+export const cliRaw = pikkuSessionlessFunc<{ args: string[] }, RawCLIFrame>({
   auth: false,
-  func: async (services, data: { args: string[] }) => {
-    return handleRawCLI({
+  func: async (services, data: { args: string[] }, { channel, session }) => {
+    const { help, result, error, exitCode, commandId } = await handleRawCLI({
       programName: '${programName}',
       args: data.args,
       singletonServices: services as any,
+      createWireServices: pikkuState(null, 'package', 'factories')?.createWireServices,
+      // The connection authenticated during its upgrade — commands run as it.
+      session,
+      // The socket the command arrived on, so \`channel.remote(...)\` inside a
+      // command reaches the client that invoked it.
+      transport: channel,
+      onOutput: (output, commandId) =>
+        channel?.send({ action: 'cli-output', commandId, data: output }),
     })
+
+    // A failed parse carries both: the error says what was wrong, the help
+    // says what was available. The error goes last so it is the line still on
+    // screen after the help text has scrolled past.
+    if (help !== undefined) {
+      await channel?.send({ action: 'cli-help', help })
+      if (error !== undefined) {
+        await channel?.send({ action: 'cli-error', error })
+      }
+    } else if (error !== undefined) {
+      await channel?.send({ action: 'cli-error', error })
+    } else if (result !== undefined) {
+      await channel?.send({ action: 'cli-result', commandId, result })
+    }
+
+    // Returned rather than sent so the runtime tags it with the routing key,
+    // and so the terminal frame cannot be emitted before the ones above it.
+    return { action: 'cli-control', event: 'complete', exitCode }
   },
 })
 
+${programMeta.auth === true
+        ? `/**
+ * Refuses a connection that arrives without a session.
+ *
+ * A CLI authenticates once, when it connects — there is no later message that
+ * would establish a session, so a connection that starts anonymous can never
+ * run anything. Saying so immediately and hanging up gives the caller a
+ * non-zero exit instead of a socket that silently refuses every command.
+ */
+export const cliRequireSession = pikkuSessionlessFunc<void, RawCLIFrame | void>({
+  auth: false,
+  func: async (_services, _data, { channel, session }) => {
+    if (session) {
+      return
+    }
+    await channel?.send({ action: 'cli-error', error: 'Authentication required' })
+    await channel?.send({ action: 'cli-control', event: 'complete', exitCode: 1 })
+    await channel?.close()
+  },
+})
+`
+        : ''}
 wireChannel({
   name: '${finalChannelName}',
   route: '${finalChannelRoute}',
-  auth: false,
-  onMessageWiring: {
+  auth: ${programMeta.auth === true},
+${programMeta.auth === true ? '  onConnect: cliRequireSession,\n' : ''}  onMessageWiring: {
     command: {
       '__help': {
         func: cliHelp,

package/dist/src/functions/wirings/cli/serialize-cli-entrypoint-guard.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The snippet every generated CLI entrypoint uses to decide whether it is being
+ * run or merely imported. It declares `isDirectExecution`; the caller writes the
+ * `if`.
+ *
+ * `import.meta.url === \`file://${process.argv[1]}\`` — the shape this replaces —
+ * is false for any CLI invoked through a symlinked bin, because Node reports the
+ * symlink in argv and the realpath in the URL, so the block never ran for an
+ * installed `node_modules/.bin/<name>`. It also fails on paths the URL has to
+ * percent-encode, such as one containing a space.
+ */
+export declare const DIRECT_EXECUTION_GUARD = "const isDirectExecution = await (async () => {\n  if (typeof import.meta.main === 'boolean') {\n    return import.meta.main\n  }\n  // Node exposes import.meta.main from 24.2; earlier 24.x compares realpaths,\n  // which is what it is shorthand for.\n  try {\n    const { fileURLToPath } = await import('node:url')\n    const { realpathSync } = await import('node:fs')\n    return (\n      process.argv[1] !== undefined &&\n      realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)\n    )\n  } catch {\n    return false\n  }\n})()";

package/dist/src/functions/wirings/cli/serialize-cli-entrypoint-guard.js

@@ -0,0 +1,28 @@
+/**
+ * The snippet every generated CLI entrypoint uses to decide whether it is being
+ * run or merely imported. It declares `isDirectExecution`; the caller writes the
+ * `if`.
+ *
+ * `import.meta.url === \`file://${process.argv[1]}\`` — the shape this replaces —
+ * is false for any CLI invoked through a symlinked bin, because Node reports the
+ * symlink in argv and the realpath in the URL, so the block never ran for an
+ * installed `node_modules/.bin/<name>`. It also fails on paths the URL has to
+ * percent-encode, such as one containing a space.
+ */
+export const DIRECT_EXECUTION_GUARD = `const isDirectExecution = await (async () => {
+  if (typeof import.meta.main === 'boolean') {
+    return import.meta.main
+  }
+  // Node exposes import.meta.main from 24.2; earlier 24.x compares realpaths,
+  // which is what it is shorthand for.
+  try {
+    const { fileURLToPath } = await import('node:url')
+    const { realpathSync } = await import('node:fs')
+    return (
+      process.argv[1] !== undefined &&
+      realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+    )
+  } catch {
+    return false
+  }
+})()`;

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

@@ -1,4 +1,5 @@
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { DIRECT_EXECUTION_GUARD } from './serialize-cli-entrypoint-guard.js';
 /**
  * Serializes the local (in-program) CLI bootstrap code
  */
@@ -40,7 +41,9 @@ ${wireServicesFactory ? '      createWireServices,' : ''}
 export default ${capitalizedName}CLI
 
 // For direct execution (if this file is run directly)
-if (import.meta.url === \`file://\${process.argv[1]}\`) {
+${DIRECT_EXECUTION_GUARD}
+
+if (isDirectExecution) {
   ${capitalizedName}CLI(process.argv.slice(2)).catch(error => {
     console.error('Fatal error:', error.message)
     process.exit(1)

package/dist/src/functions/wirings/console/serialize-console-functions.js

@@ -40,6 +40,7 @@ import {
 } from './console.schemas.gen.js'
 
 export const pikkuConsoleSetSecret = pikkuFunc({
+  secretBroker: true,
   tags: ['pikku'],
   description: 'Set the value of a secret',
   expose: true,
@@ -89,6 +90,7 @@ export const pikkuConsoleSetVariable = pikkuFunc({
 })
 
 export const pikkuConsoleHasSecret = pikkuFunc({
+  secretBroker: true,
   tags: ['pikku'],
   description: 'Check if a secret exists without reading its value',
   expose: true,
@@ -101,6 +103,7 @@ export const pikkuConsoleHasSecret = pikkuFunc({
 })
 
 export const pikkuConsoleGetSecret = pikkuFunc({
+  secretBroker: true,
   tags: ['pikku'],
   description: 'Get the current value of a secret',
   expose: true,
@@ -112,7 +115,7 @@ export const pikkuConsoleGetSecret = pikkuFunc({
       return { exists: false, value: null }
     }
     const value = await secrets.getSecret(secretId)
-    return { exists: true, value }
+    return { exists: true, value: value.reveal() }
   },
 })
 
@@ -129,13 +132,7 @@ export const consoleRoutes = defineHTTPRoutes({
   },
 })
 
-// The console addon's functions have no authorization of their own. An app
-// gates the whole privileged surface (credential read/write, source editing,
-// package install) with a single package-scoped global permission —
-// addGlobalPermission([isAdmin], '@pikku/addon-console') — which is resolved in
-// the addon's package namespace, so it applies to every one of its functions at
-// once. Apps that don't register one are unaffected (no globals => allow).
-wireAddon({ name: 'console', package: '@pikku/addon-console' })
+wireAddon({ name: 'console', package: '@pikku/addon-console', scopes: ['admin'] })
 wireHTTPRoutes({ basePath: '${globalHTTPPrefix}', routes: { console: consoleRoutes } })
 `;
     return { schemas, functions };

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

@@ -53,7 +53,7 @@ export const pikkuAddonConfig = <ExistingServices extends Omit<Partial<Singleton
  *   { secrets }
  * ) => {
  *   const creds = await secrets.getSecret<GithubCredentials>('GITHUB_CREDENTIALS')
- *   const github = new GithubService(creds)
+ *   const github = new GithubService(creds.reveal())
  *   return { github }
  * })
  * \`\`\`