@pikku/cli 0.12.96 → 0.12.99

package/dist/src/functions/validate/workspace-validate.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export { readJsonSafe, readTextSafe } from './shared-checks.js';
 export declare const FindingSchema: z.ZodObject<{
     id: z.ZodString;
     severity: z.ZodEnum<{
@@ -28,7 +29,5 @@ export declare const WorkspaceValidateOutput: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function findProjectRoot(startDir: string): Promise<string>;
-export declare function readJsonSafe<T>(path: string): Promise<T | null>;
-export declare function readTextSafe(path: string): Promise<string | null>;
 export declare function runWorkspaceValidate(startDir?: string): Promise<z.infer<typeof WorkspaceValidateOutput>>;
 export declare const renderWorkspaceValidate: (_s: unknown, { ok, root, findings }: z.infer<typeof WorkspaceValidateOutput>) => void;

package/dist/src/functions/validate/workspace-validate.js

@@ -1,8 +1,10 @@
 import { existsSync } from 'node:fs';
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { added, changed, dim, removed } from '../../fabric/lib/output.js';
+import { runSharedProjectChecks } from './shared-checks.js';
+export { readJsonSafe, readTextSafe } from './shared-checks.js';
 export const FindingSchema = z.object({
     id: z.string(),
     severity: z.enum(['error', 'warn', 'info']),
@@ -35,203 +37,9 @@ export async function findProjectRoot(startDir) {
         dir = parent;
     }
 }
-export async function readJsonSafe(path) {
-    if (!existsSync(path))
-        return null;
-    try {
-        return JSON.parse(await readFile(path, 'utf8'));
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`Invalid JSON in ${path}: ${message}`);
-    }
-}
-export async function readTextSafe(path) {
-    if (!existsSync(path))
-        return null;
-    try {
-        return await readFile(path, 'utf8');
-    }
-    catch {
-        return null;
-    }
-}
-async function hasAuthSessionMiddleware(fnDir) {
-    const metaPath = join(fnDir, '.pikku', 'middleware', 'pikku-middleware-groups-meta.gen.json');
-    const meta = await readJsonSafe(metaPath);
-    if (!meta?.instances)
-        return false;
-    return Object.values(meta.instances).some((instance) => instance.definitionId === 'betterAuthSession');
-}
-function migrationCreatesTable(sql, tableName) {
-    const escapedTable = tableName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
-    const re = new RegExp(`\\bcreate\\s+table\\s+(?:if\\s+not\\s+exists\\s+)?["'\`]?${escapedTable}["'\`]?\\b`, 'i');
-    return re.test(sql);
-}
 export async function runWorkspaceValidate(startDir = process.cwd()) {
     const root = await findProjectRoot(startDir);
-    const findings = [];
-    const e = (id, message, path, fixHint) => {
-        findings.push({ id, severity: 'error', message, path, fixHint });
-    };
-    const w = (id, message, path, fixHint) => {
-        findings.push({ id, severity: 'warn', message, path, fixHint });
-    };
-    const info = (id, message, path, fixHint) => {
-        findings.push({ id, severity: 'info', message, path, fixHint });
-    };
-    const pikkuConfigPath = join(root, 'pikku.config.json');
-    const pikkuConfig = await readJsonSafe(pikkuConfigPath);
-    if (!pikkuConfig) {
-        e('pikku-config-missing', 'pikku.config.json not found at project root', pikkuConfigPath, 'Create pikku.config.json with srcDirectories pointing to packages/functions/src, outDir, and clientFiles');
-    }
-    else {
-        if (!pikkuConfig.srcDirectories) {
-            e('pikku-config-no-src-dirs', 'pikku.config.json missing "srcDirectories"', pikkuConfigPath, 'Add "srcDirectories": ["packages/functions/src"] to pikku.config.json');
-        }
-        if (!pikkuConfig.outDir) {
-            e('pikku-config-no-out-dir', 'pikku.config.json missing "outDir"', pikkuConfigPath, 'Add "outDir": "packages/functions/.pikku" to pikku.config.json');
-        }
-        if (!pikkuConfig.clientFiles) {
-            info('pikku-config-no-client-files', 'pikku.config.json missing "clientFiles" — generated RPC client files and React Query hooks will not be written', pikkuConfigPath, 'Add clientFiles.rpcMapDeclarationFile and clientFiles.reactQueryFile pointing to packages/functions-sdk/src/pikku/ (for example: rpc-map.gen.d.ts and api.gen.ts)');
-        }
-        const scaffold = pikkuConfig.scaffold;
-        if (!scaffold?.console) {
-            e('pikku-config-no-console-scaffold', 'pikku.config.json missing "scaffold.console" — Fabric cannot introspect the running app (console:getFunctionsMeta and friends 404), so the sandbox builder shows no functions', pikkuConfigPath, 'Add "console": true under "scaffold" in pikku.config.json — the console requires an authenticated session, so Better Auth must be set up (see the pikku-better-auth skill)');
-        }
-    }
-    const rootPkgPath = join(root, 'package.json');
-    const rootPkg = await readJsonSafe(rootPkgPath);
-    if (!rootPkg) {
-        e('root-package-missing', 'root package.json not found', rootPkgPath, 'Create a root package.json with workspaces: {"workspaces": ["packages/*", "apps/*"]}');
-    }
-    else {
-        if (!rootPkg.workspaces) {
-            w('root-package-no-workspaces', 'root package.json missing "workspaces"', rootPkgPath, 'Add "workspaces": ["packages/*", "apps/*"] to enable yarn workspaces');
-        }
-        const allDeps = {
-            ...rootPkg.dependencies,
-            ...rootPkg.devDependencies,
-        };
-        if (!allDeps['@pikku/core']) {
-            e('missing-core', '@pikku/core not in dependencies', rootPkgPath, 'Add "@pikku/core" to dependencies');
-        }
-        for (const [pkg, spec] of Object.entries(allDeps)) {
-            if (typeof spec !== 'string' || !spec.startsWith('file:'))
-                continue;
-            const relPath = spec.slice(5);
-            if (!relPath.includes('vendor'))
-                continue;
-            const absPath = join(root, relPath);
-            if (!existsSync(absPath)) {
-                w(`vendor-missing-${pkg.replace(/[@/]/g, '-')}`, `Vendor file missing for ${pkg}: ${relPath}`, absPath, `Restore or replace the missing vendor package at ${relPath}`);
-            }
-        }
-    }
-    const fnDir = join(root, 'packages', 'functions');
-    if (!existsSync(fnDir)) {
-        e('functions-pkg-missing', 'packages/functions/ directory not found', fnDir, 'Create packages/functions/ as a workspace containing src/, tests/, config.ts, and any local db assets you use');
-    }
-    else {
-        const fnPkgPath = join(fnDir, 'package.json');
-        const fnPkg = await readJsonSafe(fnPkgPath);
-        if (!fnPkg) {
-            e('functions-package-json-missing', 'packages/functions/package.json not found', fnPkgPath, 'Create packages/functions/package.json and declare the workspace package');
-        }
-        else if (fnPkg.type !== 'module') {
-            w('functions-pkg-no-esm', 'packages/functions/package.json is missing "type": "module"', fnPkgPath, 'Add "type": "module" to packages/functions/package.json');
-        }
-        // zod v4 must be installed in the functions package: pikku's generated
-        // schemas and the auth scaffold (auth-secrets.gen.ts) both `import { z }
-        // from 'zod'`, so a missing/old zod fails codegen (PKU489) or type-checks.
-        if (fnPkg) {
-            const fnDeps = { ...fnPkg.dependencies, ...fnPkg.devDependencies };
-            const zodRange = fnDeps.zod;
-            const zodMajor = zodRange?.match(/(\d+)/)?.[1];
-            if (!zodRange) {
-                e('functions-missing-zod', 'packages/functions/package.json does not declare "zod" — pikku schemas and the generated auth scaffold import it', fnPkgPath, 'Add "zod": "^4" to packages/functions dependencies');
-            }
-            else if (zodMajor !== '4') {
-                e('functions-zod-not-v4', `packages/functions requires zod v4 but found "${zodRange}"`, fnPkgPath, 'Set "zod": "^4" in packages/functions dependencies');
-            }
-        }
-        const servicesPath = join(fnDir, 'src', 'services.ts');
-        const servicesText = await readTextSafe(servicesPath);
-        if (!servicesText) {
-            w('services-missing', 'packages/functions/src/services.ts not found', servicesPath, 'Create services.ts and export your service factory for the workspace');
-        }
-        const authEnabled = await hasAuthSessionMiddleware(fnDir);
-        const configText = await readTextSafe(join(fnDir, 'src', 'config.ts'));
-        const hasConfiguredDevDb = /sqliteDb/.test(configText ?? '');
-        const hasPostgresUrl = /postgresUrl/.test(configText ?? '');
-        const migrationsDir = hasPostgresUrl
-            ? join(fnDir, 'db', 'postgres')
-            : join(fnDir, 'db', 'sqlite');
-        let createsAppUser = false;
-        let createsAuthVerificationToken = false;
-        if (existsSync(migrationsDir)) {
-            try {
-                const files = (await readdir(migrationsDir))
-                    .filter((f) => f.endsWith('.sql'))
-                    .sort();
-                const nums = [];
-                for (const f of files) {
-                    const m = f.match(/^(\d+)/);
-                    if (m)
-                        nums.push(parseInt(m[1], 10));
-                }
-                for (let idx = 1; idx < nums.length; idx++) {
-                    if (nums[idx] !== nums[idx - 1] + 1) {
-                        const missing = `${nums[idx - 1] + 1}..${nums[idx] - 1}`;
-                        e('migration-gap', `Migration numbering gap: IDs ${missing} are missing`, migrationsDir, 'Migrations must be consecutive. Add the missing .sql file or renumber if not yet applied.');
-                        break;
-                    }
-                }
-                for (const f of files) {
-                    const sql = await readTextSafe(join(migrationsDir, f));
-                    if (!sql)
-                        continue;
-                    createsAppUser ||= migrationCreatesTable(sql, 'app_user');
-                    createsAuthVerificationToken ||= migrationCreatesTable(sql, 'auth_verification_token');
-                }
-            }
-            catch {
-                // readdir failure — skip
-            }
-        }
-        if (authEnabled && !hasConfiguredDevDb) {
-            e('auth-dev-db-missing', 'Auth middleware is registered, but createConfig is missing sqliteDb so local auth schema validation and db migrate cannot run', pikkuConfigPath, 'Add sqliteDb to createConfig so `pikku db migrate` can create and validate the local auth schema');
-        }
-        if (authEnabled && !createsAppUser) {
-            e('auth-schema-missing-app-user', 'Auth middleware is registered, but no SQL migration creates the app_user table', migrationsDir, 'Add a migration that creates app_user before enabling auth');
-        }
-        if (authEnabled && !createsAuthVerificationToken) {
-            e('auth-schema-missing-verification-token', 'Auth middleware is registered, but no SQL migration creates the auth_verification_token table', migrationsDir, 'Add a migration that creates auth_verification_token before enabling auth');
-        }
-        const dbTypesPath = join(fnDir, 'src', 'types', 'db.types.ts');
-        const dbTypesText = await readTextSafe(dbTypesPath);
-        if (dbTypesText) {
-            const isReexport = dbTypesText.includes('.pikku/db/schema') ||
-                dbTypesText.includes('.pikku\\db\\schema');
-            const hasInlineTypes = /(?:^|\n)\s*(?:export\s+)?(?:interface\s+\w|type\s+\w+\s*=)/.test(dbTypesText);
-            if (hasInlineTypes && !isReexport) {
-                w('db-types-hand-edited', 'src/types/db.types.ts contains inline type definitions — it should only re-export from .pikku', dbTypesPath, "Replace the file with a single line: export type { DB } from '../../.pikku/db/schema.gen.js' then regenerate");
-            }
-        }
-        if (!existsSync(join(fnDir, 'src', 'functions'))) {
-            info('functions-dir-missing', 'packages/functions/src/functions/ not found', join(fnDir, 'src', 'functions'), 'Create src/functions/ to hold pikkuSessionlessFunc definitions');
-        }
-        if (!existsSync(join(fnDir, 'src', 'wirings'))) {
-            info('wirings-dir-missing', 'packages/functions/src/wirings/ not found', join(fnDir, 'src', 'wirings'), 'Create src/wirings/ for transport bindings such as *.http.ts or *.queue.ts');
-        }
-        if (!existsSync(join(fnDir, 'src', 'config.ts'))) {
-            info('config-missing', 'packages/functions/src/config.ts not found', join(fnDir, 'src', 'config.ts'), 'Create src/config.ts and export your workspace config factory');
-        }
-    }
-    const sdkDir = join(root, 'packages', 'functions-sdk');
-    if (!existsSync(sdkDir)) {
-        info('functions-sdk-missing', 'packages/functions-sdk/ not found — generated RPC client and React Query hooks will not be available', sdkDir, 'Create packages/functions-sdk/ as a workspace with src/pikku/ as the generated output root; point clientFiles.rpcMapDeclarationFile and clientFiles.reactQueryFile there');
-    }
+    const { findings } = await runSharedProjectChecks(root);
     const ok = !findings.some((f) => f.severity === 'error');
     return { ok, root, findings };
 }

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'],`,
+    `      },`,
     `    },`,
     `  }),`,
 ];

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.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)
  */
@@ -107,10 +108,11 @@ 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 { 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'
 ${rendererImports}
@@ -136,8 +138,12 @@ export async function ${capitalizedName}CLIClient(
   // 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>>
 
   return executeRawCLIViaChannel({
     pikkuWS,
@@ -151,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
@@ -186,12 +194,26 @@ 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)
   }

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

@@ -115,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() }
   },
 })
 

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 }
  * })
  * \`\`\`

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

@@ -16,7 +16,7 @@ export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeNam
  */
 
 import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired, SecretlessServices, SecretService } from '@pikku/core'
-import type { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
+import type { CorePikkuFunctionConfig, CorePikkuSessionlessFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
 import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
 import {
   addTagMiddleware as addTagMiddlewareCore,
@@ -358,6 +358,19 @@ export type PikkuFunctionConfig<
   OutputSchema extends StandardSchemaV1 | undefined = undefined
 > = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema, ScopeId>
 
+/**
+ * {@link PikkuFunctionConfig} for a function that runs without a session.
+ * Has no \`scopes\`: an anonymous caller holds none, so none can ever be met.
+ */
+export type PikkuFunctionSessionlessConfig<
+  In = unknown,
+  Out = unknown,
+  RequiredWires extends keyof PikkuWire = never,
+  PikkuFunc extends PikkuFunctionSessionless<In, Out, RequiredWires, any> = PikkuFunctionSessionless<In, Out, RequiredWires>,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = CorePikkuSessionlessFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema>
+
 /**
  * Configuration object for Pikku functions with Zod schema validation.
  * Use this when you want to define input/output schemas using Zod.
@@ -479,7 +492,8 @@ export const pikkuListFunc = <
  */
 /**
  * Schema-overload variant for pikkuSessionlessFunc. Derived from
- * CorePikkuFunctionConfig to stay in sync with the generic-typed config.
+ * CorePikkuSessionlessFunctionConfig to stay in sync with the generic-typed
+ * config — so it has no \`scopes\` either.
  */
 export type PikkuFunctionSessionlessConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
@@ -487,7 +501,7 @@ export type PikkuFunctionSessionlessConfigWithSchema<
   RequiredWires extends keyof PikkuWire = never,
   RequiredServices extends SecretlessServices<Services> = WiredServices
 > = Omit<
-  CorePikkuFunctionConfig<
+  CorePikkuSessionlessFunctionConfig<
     PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
   >,
   'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
@@ -542,7 +556,7 @@ export function pikkuSessionlessFunc<
 export function pikkuSessionlessFunc<In, Out = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices>(
   func:
     | PikkuFunctionSessionless<In, Out, 'session' | 'rpc', RequiredServices>
-    | PikkuFunctionConfig<In, Out, 'session' | 'rpc', PikkuFunctionSessionless<In, Out, 'session' | 'rpc', RequiredServices>>
+    | PikkuFunctionSessionlessConfig<In, Out, 'session' | 'rpc', PikkuFunctionSessionless<In, Out, 'session' | 'rpc', RequiredServices>>
 ): PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
 export function pikkuSessionlessFunc(func: any) {
   return typeof func === 'function' ? { func } : func
@@ -567,7 +581,7 @@ export function pikkuSessionlessFunc(func: any) {
 export const pikkuVoidFunc = (
   func:
     | PikkuFunctionSessionless<void, void, 'session' | 'rpc'>
-    | PikkuFunctionConfig<void, void, 'session' | 'rpc'>
+    | PikkuFunctionSessionlessConfig<void, void, 'session' | 'rpc'>
 ) => {
   return typeof func === 'function' ? { func } : func
 }

package/dist/src/functions/wirings/package/pikku-command-package-types.d.ts

@@ -1,3 +1,3 @@
-export declare const pikkuSecretDefinitionTypes: 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 pikkuScopeDefinitionTypes: 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 pikkuVariableDefinitionTypes: 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 pikkuSecretDefinitionTypes: import("#pikku").PikkuFunctionSessionlessConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuScopeDefinitionTypes: import("#pikku").PikkuFunctionSessionlessConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuVariableDefinitionTypes: import("#pikku").PikkuFunctionSessionlessConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/personas/personas-secrets-file.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where the generated `SCENARIO_ACTOR_SECRET` declaration lives — beside the
+ * personas file, like `auth-secrets.gen.ts` sits beside the auth scaffold.
+ *
+ * Shared with the inspector's scaffold-file list: nothing imports this file, so
+ * it is unreachable through the import graph and has to be inspected explicitly.
+ */
+export declare const personasSecretsFilePath: (personasFile: string) => string;

package/dist/src/functions/wirings/personas/personas-secrets-file.js

@@ -0,0 +1,9 @@
+import { join, dirname } from 'node:path';
+/**
+ * Where the generated `SCENARIO_ACTOR_SECRET` declaration lives — beside the
+ * personas file, like `auth-secrets.gen.ts` sits beside the auth scaffold.
+ *
+ * Shared with the inspector's scaffold-file list: nothing imports this file, so
+ * it is unreachable through the import graph and has to be inspected explicitly.
+ */
+export const personasSecretsFilePath = (personasFile) => join(dirname(personasFile), 'pikku-personas-secrets.gen.ts');