@pikku/cli 0.12.92 → 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/knowledge/render.d.ts

@@ -0,0 +1,3 @@
+import type { KnowledgeIndexResult, KnowledgeValidateResult } from '@pikku/knowledge';
+export declare const renderKnowledgeValidate: (_services: unknown, { ok, notes, findings }: KnowledgeValidateResult) => void;
+export declare const renderKnowledgeIndex: (_services: unknown, { ok, check, files }: KnowledgeIndexResult) => void;

package/dist/src/functions/knowledge/render.js

@@ -0,0 +1,66 @@
+import { added, changed, dim, removed } from '../../fabric/lib/output.js';
+export const renderKnowledgeValidate = (_services, { ok, notes, findings }) => {
+    const errors = findings.filter((f) => f.severity === 'error');
+    const warns = findings.filter((f) => f.severity === 'warn');
+    const infos = findings.filter((f) => f.severity === 'info');
+    for (const finding of [...errors, ...warns, ...infos]) {
+        const icon = finding.severity === 'error'
+            ? removed('✗')
+            : finding.severity === 'warn'
+                ? changed('⚠')
+                : dim('ℹ');
+        console.log(`${icon}  ${finding.message}`);
+        console.log(`   ${dim('fix:')}  ${finding.fixHint}`);
+        console.log();
+    }
+    const counts = [dim(`${notes} note${notes !== 1 ? 's' : ''}`)];
+    if (errors.length) {
+        counts.push(removed(`${errors.length} error${errors.length !== 1 ? 's' : ''}`));
+    }
+    if (warns.length) {
+        counts.push(changed(`${warns.length} warning${warns.length !== 1 ? 's' : ''}`));
+    }
+    console.log('─'.repeat(40));
+    console.log(counts.join('  '));
+    if (ok && warns.length === 0 && errors.length === 0) {
+        console.log(added('✓') + '  ' + dim('the knowledge base is consistent'));
+    }
+    // An error means the base contradicts itself, which a pipeline has to be able
+    // to stop on — so this command reports it the only way a shell can read.
+    if (!ok)
+        process.exitCode = 1;
+};
+export const renderKnowledgeIndex = (_services, { ok, check, files }) => {
+    if (files.length === 0) {
+        console.log(dim('No knowledge notes — nothing to index.'));
+        return;
+    }
+    for (const file of files) {
+        if (file.action === 'unchanged') {
+            console.log(`${dim('=')}  ${dim(file.path)}`);
+        }
+        else if (check) {
+            console.log(`${removed('✗')}  ${file.path} ${dim(`(${file.action})`)}`);
+        }
+        else {
+            console.log(`${added('✓')}  ${file.path} ${dim(`(${file.action})`)}`);
+        }
+    }
+    console.log('─'.repeat(40));
+    if (!check) {
+        const written = files.filter((f) => f.action !== 'unchanged').length;
+        console.log(written === 0
+            ? added('✓') + '  ' + dim('every index was already current')
+            : added('✓') +
+                `  ${written} index file${written !== 1 ? 's' : ''} written`);
+    }
+    else {
+        console.log(ok
+            ? added('✓') + '  ' + dim('every index is current')
+            : removed('✗') +
+                '  ' +
+                'indexes are stale — run `pikku knowledge index`');
+        if (!ok)
+            process.exitCode = 1;
+    }
+};

package/dist/src/functions/knowledge/schemas.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The knowledge command schemas, re-bound to variables declared HERE rather than
+ * imported straight into the command files.
+ *
+ * Two things about how the CLI builds itself make this the only shape that works:
+ *
+ * 1. The build bootstraps with the PUBLISHED CLI and inspector, so the code that
+ *    reads these schemas is whatever npm has, not what is in this worktree. An
+ *    identifier imported from `@pikku/knowledge` resolves to that package's
+ *    `.d.ts`, and importing a declaration file yields a module with no exports at
+ *    all — every one of them is a type. A binding declared in a `.ts` gives the
+ *    inspector a file it can execute, and the import inside it resolves to the
+ *    package's emitted JS.
+ * 2. The command files import `#pikku`, which points at `dist/.pikku/` — output
+ *    that does not exist yet while the bootstrap is running. A schema the
+ *    inspector has to import therefore cannot live beside a wired function.
+ *
+ * `schemaRuntimeFile` in the inspector fixes (1) at the root, so once a release
+ * carrying it is the bootstrap version, (2) is the only reason this file is here.
+ */
+export declare const KnowledgeIndexInputSchema: import("zod").ZodObject<{
+    check: import("zod").ZodOptional<import("zod").ZodBoolean>;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgeIndexOutputSchema: import("zod").ZodObject<{
+    ok: import("zod").ZodBoolean;
+    check: import("zod").ZodBoolean;
+    files: import("zod").ZodArray<import("zod").ZodObject<{
+        path: import("zod").ZodString;
+        action: import("zod").ZodEnum<{
+            created: "created";
+            updated: "updated";
+            unchanged: "unchanged";
+        }>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgeValidateInputSchema: import("zod").ZodObject<{}, import("zod/v4/core").$strip>;
+export declare const KnowledgeValidateOutputSchema: import("zod").ZodObject<{
+    ok: import("zod").ZodBoolean;
+    notes: import("zod").ZodNumber;
+    findings: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        severity: import("zod").ZodEnum<{
+            error: "error";
+            warn: "warn";
+            info: "info";
+        }>;
+        message: import("zod").ZodString;
+        path: import("zod").ZodString;
+        fixHint: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;

package/dist/src/functions/knowledge/schemas.js

@@ -0,0 +1,25 @@
+import { KnowledgeIndexInput, KnowledgeIndexOutput, KnowledgeValidateInput, KnowledgeValidateOutput, } from '@pikku/knowledge';
+/**
+ * The knowledge command schemas, re-bound to variables declared HERE rather than
+ * imported straight into the command files.
+ *
+ * Two things about how the CLI builds itself make this the only shape that works:
+ *
+ * 1. The build bootstraps with the PUBLISHED CLI and inspector, so the code that
+ *    reads these schemas is whatever npm has, not what is in this worktree. An
+ *    identifier imported from `@pikku/knowledge` resolves to that package's
+ *    `.d.ts`, and importing a declaration file yields a module with no exports at
+ *    all — every one of them is a type. A binding declared in a `.ts` gives the
+ *    inspector a file it can execute, and the import inside it resolves to the
+ *    package's emitted JS.
+ * 2. The command files import `#pikku`, which points at `dist/.pikku/` — output
+ *    that does not exist yet while the bootstrap is running. A schema the
+ *    inspector has to import therefore cannot live beside a wired function.
+ *
+ * `schemaRuntimeFile` in the inspector fixes (1) at the root, so once a release
+ * carrying it is the bootstrap version, (2) is the only reason this file is here.
+ */
+export const KnowledgeIndexInputSchema = KnowledgeIndexInput;
+export const KnowledgeIndexOutputSchema = KnowledgeIndexOutput;
+export const KnowledgeValidateInputSchema = KnowledgeValidateInput;
+export const KnowledgeValidateOutputSchema = KnowledgeValidateOutput;

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