@pikku/cli 0.12.93 → 0.12.96

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

@@ -1,18 +1,21 @@
 import { resolve, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku';
-import { InMemoryWorkflowService, createHttpScenarioActors, } from '@pikku/core/services';
+import { InMemoryWorkflowService } from '@pikku/core/services';
+import { createHttpPersonas } from '@pikku/core/persona';
 import { PikkuScenarioService } from '@pikku/core/scenario';
 import { pikkuState, getAllPackageStates } from '@pikku/core/internal';
 import { resolveFeatureScenarios } from '@pikku/core/workflow';
 import { loadScenarioBootstrap } from './load-user-project.js';
-import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, } from './scenario-ladder.js';
+import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, scenarioStepsWithoutBinding, scenarioSurfaceCoverage, } from './scenario-ladder.js';
+import { SCENARIO_SURFACES } from '@pikku/core/workflow';
 import { formatScenarioReport } from './scenario-formatter.js';
 import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './scenario-browser.js';
-import { resolveScenarioActors } from '../../utils/resolve-scenario-actors.js';
+import { resolvePersonas } from '../../utils/resolve-personas.js';
 import { spawnDevServer } from '../../server/spawn-dev-server.js';
 import { buildScenarioPlan } from './scenario-plan.js';
-import { resolveScenarioEnvironment } from './scenario-environment.js';
+import { resolveEnvironment } from './environment.js';
+import { createDevAIAgentRunner } from './dev-ai-runner.js';
 const isScenario = (wf) => wf?.scenario === true;
 const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     .filter(([, wf]) => isScenario(wf))
@@ -84,14 +87,17 @@ export const scenarioList = pikkuSessionlessFunc({
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
+        if (!SCENARIO_SURFACES.includes(runSurface)) {
+            throw new Error(`Unknown --run surface '${runSurface}'. Expected one of: ${SCENARIO_SURFACES.join(', ')}.`);
+        }
         const state = await getInspectorState(true, false, false, true);
         // Resolved once, so actors, step env, the browser driver and any spawned
         // server all target the same place — including when the target only exists
         // at run time and arrives through --api-url/--app-url.
-        const env = resolveScenarioEnvironment({
+        const env = resolveEnvironment({
             environment,
-            environments: config.scenarios?.environments ?? {},
+            environments: config.environments ?? {},
             apiUrl,
             appUrl,
             spawn,
@@ -164,16 +170,17 @@ export const scenarioRun = pikkuSessionlessFunc({
             throw new Error('SCENARIO_ACTOR_SECRET is not set — scenario actors cannot sign in. ' +
                 'Export it in the environment running this command (never put it in pikku.config.json).');
         }
-        // Declared actors plus one per persona nobody declared a body for. Resolved
-        // once: the HTTP actors and the Playwright provider below must see the same
-        // registry, and codegen resolved the same way to type `ScenarioActorName`.
-        const scenarioActors = resolveScenarioActors(config.scenarios);
-        const actors = createHttpScenarioActors({
+        // Every declared persona, with its address filled in. Resolved once: the
+        // HTTP personas and the Playwright provider below must see the same
+        // registry, and codegen resolved the same way to type `PersonaName`.
+        const scenarioActors = resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain);
+        const actors = createHttpPersonas({
             apiUrl: env.apiUrl,
             secret,
-            actors: scenarioActors,
+            personas: scenarioActors,
             signInPath: env.signInPath,
             rpcPath: env.rpcPath,
+            model: config.scenarios?.model,
         });
         const functionsMeta = state.functions?.meta ?? {};
         const scenarioNames = new Set(groups.flatMap((group) => group.entries.map((e) => e.scenarioName)));
@@ -183,6 +190,15 @@ export const scenarioRun = pikkuSessionlessFunc({
             scenarioBrowserSteps(state.workflows?.meta?.[name], functionsMeta),
         ])
             .filter(([, steps]) => steps.length > 0));
+        // `--no-browser` is the blunt form of `--run default`: a machine with no
+        // browser takes the server-side path rather than skipping the scenario.
+        const effectiveSurface = browser === false && runSurface === 'browser' ? 'default' : runSurface;
+        const unrunnableStepsByFlow = new Map([...scenarioNames]
+            .map((name) => [
+            name,
+            scenarioStepsWithoutBinding(state.workflows?.meta?.[name], functionsMeta, effectiveSurface),
+        ])
+            .filter(([, steps]) => steps.length > 0));
         // Two reasons a scenario is held back, both reported as SKIP rather than
         // failed. `--no-browser` is the direct replacement for cucumber's `@console`
         // tag, so a standard run stays green on a machine with no browser; a `skip`
@@ -191,8 +207,9 @@ export const scenarioRun = pikkuSessionlessFunc({
         const skipReasonFor = (entry) => {
             if (entry.skip)
                 return entry.skip;
-            if (!browser && browserStepsByFlow.has(entry.scenarioName)) {
-                return 'browser steps, --no-browser';
+            const unrunnable = unrunnableStepsByFlow.get(entry.scenarioName);
+            if (unrunnable?.length) {
+                return `no ${effectiveSurface} or default binding: ${unrunnable.join(', ')}`;
             }
             return undefined;
         };
@@ -215,10 +232,27 @@ export const scenarioRun = pikkuSessionlessFunc({
             apiUrl: env.apiUrl,
             appUrl: env.appUrl,
         });
+        scenarioService.setRunSurface(effectiveSurface);
+        // Scenario steps run here, not on the target — everything they touch of the
+        // app goes over HTTP through an actor, which is what `guardRpc` below
+        // enforces. `actor.converse` is the exception, and the reason this is not
+        // just the three services above: the persona's own turns are LLM calls made
+        // in this process, and without a runner every conversing scenario fails
+        // before it says anything. Built the same way `pikku dev` builds its own,
+        // and only when the project declares agents, so a project with no agents
+        // does not have to have AI env set to run scenarios.
+        const aiAgentRunner = Object.keys(state.agents?.agentsMeta ?? {}).length > 0
+            ? await createDevAIAgentRunner({
+                logger,
+                projectRoot: config.rootDir,
+                variables,
+            })
+            : undefined;
         pikkuState(null, 'package', 'singletonServices', {
             logger,
             workflowService,
             workflowRunService: workflowService,
+            ...(aiAgentRunner ? { aiAgentRunner } : {}),
         });
         const guardRpc = {
             rpcWithWire: async (rpcName) => {
@@ -227,7 +261,11 @@ export const scenarioRun = pikkuSessionlessFunc({
                     `'${environment}' (${env.apiUrl}), not local services.`);
             },
         };
-        const needsBrowser = groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
+        // Only a browser run launches one. Under `--run default` a step with a
+        // browser binding takes its default path instead, so there is nothing to
+        // drive and nothing to pay for.
+        const needsBrowser = effectiveSurface === 'browser' &&
+            groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
         const failureDir = join(resolve(config.rootDir, config.outDir), 'scenario-failures');
         const browserLifecycle = scenarioBrowserLifecycle(needsBrowser
             ? await (async () => {
@@ -448,8 +486,32 @@ export const scenarioRun = pikkuSessionlessFunc({
         })) {
             logger[level](text);
         }
+        // How much of the run actually happened on the surface it targeted. Every
+        // step counts, so a step that fell back to the server lowers the ratio
+        // rather than needing a footnote. Assertions that fell back are named
+        // separately — those are sentences claiming an observation nobody made.
+        const surfaceCoverage = { onSurface: 0, total: 0 };
+        const unwitnessed = new Set();
+        for (const name of scenarioNames) {
+            const scenario = scenarioSurfaceCoverage(state.workflows?.meta?.[name], functionsMeta, effectiveSurface);
+            surfaceCoverage.onSurface += scenario.onSurface;
+            surfaceCoverage.total += scenario.total;
+            for (const step of scenario.unwitnessed)
+                unwitnessed.add(step);
+        }
+        if (effectiveSurface !== 'default' && surfaceCoverage.total > 0) {
+            const line = `${surfaceCoverage.onSurface}/${surfaceCoverage.total} steps ran on ${effectiveSurface}`;
+            if (unwitnessed.size === 0) {
+                logger.info(line);
+            }
+            else {
+                logger[strict ? 'error' : 'warn'](`${line} — asserted server-side only: ${[...unwitnessed].join(', ')}`);
+            }
+        }
         const failed = results.filter((r) => r.status === 'failed');
-        if (failed.length > 0 || hookFailures.length > 0) {
+        if (failed.length > 0 ||
+            hookFailures.length > 0 ||
+            (strict && unwitnessed.size > 0)) {
             process.exitCode = 1;
         }
     },

package/dist/src/functions/commands/scopes-shared.d.ts

@@ -1,5 +1,7 @@
+import type { Kysely } from 'kysely';
 import type { FlatScope } from '@pikku/core/scope';
 import { KyselyScopeService } from '@pikku/kysely';
+import type { KyselyPikkuDB } from '@pikku/kysely';
 type Logger = {
     info: (msg: string) => void;
     warn: (msg: string) => void;
@@ -8,6 +10,12 @@ type Logger = {
 export declare const loadDeclaredScopes: (scopesMetaJsonFile: string, logger: Logger) => Promise<FlatScope[] | null>;
 export type OpenedScopeService = {
     service: KyselyScopeService;
+    /**
+     * The same connection the service holds, for the one thing it cannot answer:
+     * a user's id from their address. Grants are keyed by id, and the `user`
+     * table those ids come from is better-auth's, not the scope schema's.
+     */
+    db: Kysely<KyselyPikkuDB>;
     destroy: () => Promise<void>;
 };
 /**

package/dist/src/functions/commands/scopes-shared.js

@@ -62,7 +62,7 @@ export const openScopeService = async ({ config, logger, }, declared, command) =
         const service = new KyselyScopeService(db);
         await service.init();
         await service.syncScopes(declared);
-        return { service, destroy: () => db.destroy() };
+        return { service, db, destroy: () => db.destroy() };
     }
     catch (e) {
         await db.destroy();

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

@@ -12,6 +12,7 @@ import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
+import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
 export const serve = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole }) => {
@@ -54,8 +55,11 @@ export const serve = pikkuSessionlessFunc({
                 sizeLimit: userConfig.content.sizeLimit,
             }
             : undefined;
-        const localContent = localContentConfig
-            ? new LocalContent(localContentConfig, logger)
+        const contentSigningJWT = localContentConfig
+            ? createEphemeralContentSigningJWT()
+            : undefined;
+        const localContent = localContentConfig && contentSigningJWT
+            ? new LocalContent(localContentConfig, logger, contentSigningJWT)
             : undefined;
         const schedulerService = new InMemorySchedulerService();
         const aiStorage = kysely
@@ -128,7 +132,7 @@ export const serve = pikkuSessionlessFunc({
             port: resolvedPort,
             content: localContentConfig,
             ...(consoleMount ? { staticMounts: [consoleMount] } : {}),
-        }, logger);
+        }, logger, { contentSigningJWT });
         const lifecycle = await loadLifecycle();
         await pikkuServer.init();
         await lifecycle?.beforeStart?.(resolvedServices);

package/dist/src/functions/commands/virtual-user-formatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The virtual user run report, and how it is rendered.
+ *
+ * A run is not a pass/fail: a virtual user pursuing plausible goals against a
+ * real stage produces a story — what it tried, what it gave up on, and what
+ * came back that should not have. The findings are the product; everything else
+ * is context for reading them.
+ *
+ * Kept a pure function over plain data for the same reason the scenario
+ * reporter is: a second formatter (JSON for fabric, JUnit for CI) is then one
+ * function rather than an unpicking of the runner.
+ */
+import type { VirtualUserRunResult } from '@pikku/core/virtual-user';
+export interface VirtualUserReportContext {
+    persona: string;
+    disposition: string;
+    environment: string;
+    apiUrl: string;
+    /** How much of the catalogue's read/write split had to be guessed at. */
+    catalogue: {
+        total: number;
+        annotated: number;
+        inferred: number;
+    };
+}
+export interface VirtualUserReportLine {
+    level: 'info' | 'error' | 'warn';
+    text: string;
+}
+export declare const formatVirtualUserReport: (result: VirtualUserRunResult, context: VirtualUserReportContext) => VirtualUserReportLine[];

package/dist/src/functions/commands/virtual-user-formatter.js

@@ -0,0 +1,65 @@
+const STATUS_MARK = {
+    completed: 'DONE',
+    abandoned: 'DROP',
+    stuck: 'STUCK',
+    suspended: 'OPEN',
+    open: 'OPEN',
+};
+/** Why a run ended, in words rather than an enum. */
+const STOPPED_BY = {
+    'no-intents': 'this persona had nothing to want — no scenario names them',
+    'budget-steps': 'ran out of steps',
+    'budget-mutations': 'ran out of mutations',
+    'budget-duration': 'ran out of time',
+    'stop-hook': 'the app called a halt',
+    exhausted: 'saw everything it came for through',
+};
+const findingLine = (finding) => `  ${finding.kind.padEnd(18)} ${finding.detail} (step ${finding.step})`;
+const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+export const formatVirtualUserReport = (result, context) => {
+    const lines = [];
+    const info = (text) => lines.push({ level: 'info', text });
+    const error = (text) => lines.push({ level: 'error', text });
+    const warn = (text) => lines.push({ level: 'warn', text });
+    info(`Virtual user '${context.persona}' (${context.disposition}) against '${context.environment}' — ${context.apiUrl}`);
+    info(`  seed ${result.seed} · ${plural(context.catalogue.total, 'endpoint')} offered` +
+        (context.catalogue.inferred
+            ? ` · read/write guessed for ${context.catalogue.inferred} of them`
+            : ''));
+    if (result.intents.length) {
+        info('');
+        info('What it tried');
+        for (const intent of result.intents) {
+            const mark = STATUS_MARK[intent.status] ?? intent.status.toUpperCase();
+            const interrupted = intent.suspensions
+                ? `, put down ${plural(intent.suspensions, 'time')}`
+                : '';
+            const summary = intent.summary ? ` — ${intent.summary}` : '';
+            info(`  ${mark.padEnd(5)} ${intent.title} (${plural(intent.steps.length, 'step')}${interrupted})${summary}`);
+        }
+    }
+    info('');
+    if (result.findings.length === 0) {
+        info('Nothing came back that should not have.');
+    }
+    else {
+        error(`${plural(result.findings.length, 'finding')}`);
+        for (const finding of result.findings) {
+            error(findingLine(finding));
+        }
+    }
+    const { tally } = result;
+    info('');
+    info(`${plural(tally.steps, 'step')} · ${plural(tally.calls, 'call')} · ` +
+        `${plural(tally.mutations, 'mutation')} · ${tally.tokensIn}/${tally.tokensOut} tokens ` +
+        `(${tally.model}) · ${Math.round(tally.elapsedMs / 1000)}s`);
+    info(`Stopped because it ${STOPPED_BY[result.stoppedBy]}.`);
+    if (result.stoppedBy === 'no-intents') {
+        warn(`Give it something to want: declare a scenario naming '${context.persona}', or pass --goals.`);
+    }
+    // A seed is only worth printing when there is something to reproduce.
+    if (result.findings.length) {
+        info(`Replay this exact run with --seed ${result.seed}.`);
+    }
+    return lines;
+};

package/dist/src/functions/db/local-db.js

@@ -123,13 +123,50 @@ async function createPostgresClient(resolved) {
     const db = await createEmbeddedPostgres(resolved.pgliteDir);
     return pgliteAsClient(db);
 }
+let embeddedPostgresWasm;
+/**
+ * Compile PGlite's two WASM modules once and hand them to every instance.
+ *
+ * PGlite already caches them across instances internally, so this saves one
+ * 10.5MB compile per process rather than one per instance — measured at ~5% off
+ * a four-instance run. It is worth the few lines because a `WebAssembly.Module`
+ * is stateless compiled code, safe to instantiate any number of times.
+ *
+ * Note what this does *not* fix: each instance still compiles ~4MB of its own
+ * WASM (~3.3MB of it the pgcrypto side module, which PGlite offers no way to
+ * share) across ~15 module constructions, and frees it on close. That per
+ * instance churn is the suspected trigger for the rare V8 abort seen in CI on
+ * Linux x64, where PKU-based ThreadIsolation loses track of a code allocation:
+ *
+ *   Check failed: jit_page_->allocations_.erase(addr) == 1.
+ *
+ * Resolution mirrors PGlite's own `new URL('./pglite.wasm', import.meta.url)`.
+ * If the files are not where the package puts them (a bundled CLI, say), we
+ * hand back nothing and PGlite loads them itself as before.
+ */
+async function loadEmbeddedPostgresWasm() {
+    try {
+        const dist = dirname(createRequire(import.meta.url).resolve('@electric-sql/pglite'));
+        const [pgliteWasmModule, initdbWasmModule] = await Promise.all([
+            WebAssembly.compile(readFileSync(join(dist, 'pglite.wasm'))),
+            WebAssembly.compile(readFileSync(join(dist, 'initdb.wasm'))),
+        ]);
+        return { pgliteWasmModule, initdbWasmModule };
+    }
+    catch {
+        return undefined;
+    }
+}
 async function createEmbeddedPostgres(dataDir) {
-    const [{ PGlite }, { pgcrypto }] = await Promise.all([
+    embeddedPostgresWasm ??= loadEmbeddedPostgresWasm();
+    const [{ PGlite }, { pgcrypto }, wasm] = await Promise.all([
         import('@electric-sql/pglite'),
         import('@electric-sql/pglite/contrib/pgcrypto'),
+        embeddedPostgresWasm,
     ]);
     return new PGlite({
         ...(dataDir ? { dataDir } : {}),
+        ...wasm,
         extensions: {
             pgcrypto,
         },

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

@@ -97,7 +97,7 @@ export async function runWorkspaceValidate(startDir = process.cwd()) {
         }
         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": "auth" 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)');
+            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');

package/dist/src/functions/wirings/ai-agent/pikku-command-public-agent.js

@@ -4,11 +4,12 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializePublicAgent } from './serialize-public-agent.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuPublicAgent = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         if (config.scaffold?.agent && config.publicAgentSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.publicAgentFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializePublicAgent(pathToPikkuTypes, config.scaffold.agent === 'auth', config.globalHTTPPrefix || '');
+            const { schemas, functions } = serializePublicAgent(pathToPikkuTypes, resolveScaffoldFeature('agent', config.scaffold.agent).auth, config.globalHTTPPrefix || '');
             await writeFileInDir(logger, config.publicAgentSchemasFile, schemas);
             await writeFileInDir(logger, config.publicAgentFile, functions);
             await removeLegacyScaffoldFile(config.publicAgentFile);

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

@@ -81,6 +81,7 @@ export const isThreadOwner = pikkuPermission<{ threadId: string }>(
 )
 
 export const agentCaller = pikkuSessionlessFunc({
+  description: 'Run a named AI agent with a message and return its reply',
   tags: ['pikku'],
   auth: ${authFlag},
   input: AgentCall,

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

@@ -5,14 +5,14 @@ import type { AuthDefinition } from '@pikku/inspector';
  * They are split because the CLI's schema/wiring-separation rule (PKU490)
  * forbids a file from declaring Zod schemas AND `wireHTTPRoutes` together —
  * schema files are imported at runtime, which would fire HTTP wiring
- * side-effects without a server context. `wireSecret`/`wireVariable` are NOT
+ * side-effects without a server context. `defineSecret`/`defineVariable` are NOT
  * HTTP wiring, so schemas may sit alongside them; only the route wiring must be
  * separated out.
  */
 export interface AuthGenOutput {
     /** Handler + catch-all routes (+ session middleware, unless split out). */
     wiring: string;
-    /** The secrets file: Zod schemas + wireSecret/wireVariable. */
+    /** The secrets file: Zod schemas + defineSecret/defineVariable. */
     secrets: string;
     /** Global session-middleware registration, split into its own file only when
      * `session.cookieCache` is enabled (stateless path); undefined otherwise. */

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

@@ -59,22 +59,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 +92,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 +105,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 +116,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/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

@@ -65,14 +65,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
@@ -108,29 +110,40 @@ export function serializeChannelCLIClient(programName, programMeta, clientFile,
         ? `,\n    defaultRenderer: ${defaultRendererBinding}`
         : '';
     return `
-import { executeCLIViaChannel } from '@pikku/core/cli/channel'
+import { executeRawCLIViaChannel } 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}
 
-  await executeCLIViaChannel({
-    programName: '${programName}',
+  return executeRawCLIViaChannel({
     pikkuWS,
     args,
-    renderers${defaultRendererCode},
+    renderers,
+    capabilities${defaultRendererCode},
   })
 }
 
@@ -183,11 +196,12 @@ if (import.meta.url === \`file://\${process.argv[1]}\`) {
     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)
+    })
 }
 `;
 }