@pikku/cli 0.12.160 → 0.12.162

package/dist/.pikku/variables/pikku-variables.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.160
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { TypedVariablesService as CoreTypedVariablesService, } from '@pikku/core/services';
 /**

package/dist/.pikku/workflow/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.160
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/workflow` resolves here.

package/dist/.pikku/workflow/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.160
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/workflow` resolves here.

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.160
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import type { PikkuWorkflowGraphConfig, PikkuWorkflowGraphResult } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.160
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { pikkuWorkflowGraph as corePikkuWorkflowGraph } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.160
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { pikkuState } from '@pikku/core/state';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.160
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.160') {
-      process.stderr.write(`\n  Update available  0.12.160 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.162') {
+      process.stderr.write(`\n  Update available  0.12.162 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/deploy/analyzer/analyzer.js

@@ -303,7 +303,13 @@ export function analyzeDeployment(state, options) {
     // ── Step 1b: Addon units ───────────────────────────────────────────
     const addonUnitByRpcName = new Map();
     for (const [namespace, addonMeta] of entries(state.addonFunctions ?? {})) {
-        const exposed = entries(addonMeta).filter(([, meta]) => meta.expose);
+        // The wiring's `expose` decides when it is `false` or a list; otherwise
+        // the addon's own `expose: true` does — the same rule `rpc.exposed`
+        // applies at runtime, so the unit carries exactly what can be called.
+        const wiredExpose = state.rpc?.wireAddonDeclarations?.get(namespace)?.expose;
+        const exposed = entries(addonMeta).filter(([funcName, meta]) => Array.isArray(wiredExpose)
+            ? wiredExpose.includes(funcName)
+            : wiredExpose !== false && meta.expose);
         if (exposed.length === 0) {
             continue;
         }

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

@@ -180,8 +180,13 @@ export const serve = pikkuSessionlessFunc({
             ? await resolveFrontendMount(config.frontend)
             : undefined;
         // The console goes first so a frontend mounted at `/` cannot claim
-        // `/console` before the console's own mount is offered the request.
-        const staticMounts = [consoleMount, frontendMount].filter((mount) => Boolean(mount));
+        // `/console` before the console's own mount is offered the request, and
+        // the app's own mounts are kept ahead of the catch-all frontend.
+        const staticMounts = [
+            ...(consoleMount ? [consoleMount] : []),
+            ...(userConfig.staticMounts ?? []),
+            ...(frontendMount ? [frontendMount] : []),
+        ];
         const pikkuServer = devServerRunner.createServer({
             ...userConfig,
             hostname: bindHostname,

package/dist/src/functions/surface/collect-snippets.d.ts

@@ -1,13 +1 @@
-export declare class UnclosedSnippetError extends Error {
-    constructor(name: string, file: string);
-}
-export declare class DuplicateSnippetError extends Error {
-    constructor(name: string, file: string, other: string);
-}
-/**
- * The `// @snippet start <name>` regions in a project's source, so an example
- * in a doc comment can name one instead of restating it. The same mechanism the
- * website uses to pull its code blocks out of the shop template: the code that
- * reaches the reader is the code that compiles, and it cannot drift.
- */
-export declare const collectSnippets: (projectDir: string, into?: Map<string, string>, origins?: Map<string, string>) => Promise<Map<string, string>>;
+export { collectSnippets, UnclosedSnippetError, DuplicateSnippetError, } from '@pikku/skills';

package/dist/src/functions/surface/collect-snippets.js

@@ -1,83 +1 @@
-import { readdir, readFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-const START = /^\s*(?:\/\/|--)\s*@snippet start (\S+)\s*$/;
-const END = /^\s*(?:\/\/|--)\s*@snippet end (\S+)\s*$/;
-const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.sql'];
-const SKIPPED_DIRECTORIES = new Set(['node_modules', '.pikku', 'dist', '.git']);
-export class UnclosedSnippetError extends Error {
-    constructor(name, file) {
-        super(`The snippet "${name}" opens in ${file} and never closes. Add "// @snippet end ${name}".`);
-        this.name = 'UnclosedSnippetError';
-    }
-}
-export class DuplicateSnippetError extends Error {
-    constructor(name, file, other) {
-        super(`The snippet "${name}" is defined twice, in ${other} and ${file}. Snippet names are the reference an example uses, so they have to be unique.`);
-        this.name = 'DuplicateSnippetError';
-    }
-}
-const dedent = (lines) => {
-    const indents = lines
-        .filter((line) => line.trim().length > 0)
-        .map((line) => line.length - line.trimStart().length);
-    const shortest = indents.length > 0 ? Math.min(...indents) : 0;
-    return lines
-        .map((line) => line.slice(shortest))
-        .join('\n')
-        .trim();
-};
-const sourceFilesIn = async (directory, found = []) => {
-    for (const entry of await readdir(directory, { withFileTypes: true })) {
-        const full = join(directory, entry.name);
-        if (entry.isDirectory()) {
-            if (SKIPPED_DIRECTORIES.has(entry.name) || entry.name.startsWith('.')) {
-                continue;
-            }
-            await sourceFilesIn(full, found);
-        }
-        else if (SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
-            found.push(full);
-        }
-    }
-    return found;
-};
-/**
- * The `// @snippet start <name>` regions in a project's source, so an example
- * in a doc comment can name one instead of restating it. The same mechanism the
- * website uses to pull its code blocks out of the shop template: the code that
- * reaches the reader is the code that compiles, and it cannot drift.
- */
-export const collectSnippets = async (projectDir, into = new Map(), origins = new Map()) => {
-    for (const file of await sourceFilesIn(projectDir)) {
-        const where = relative(projectDir, file);
-        const lines = (await readFile(file, 'utf8')).split('\n');
-        const open = new Map();
-        for (const line of lines) {
-            const end = line.match(END);
-            if (end?.[1] && open.has(end[1])) {
-                const name = end[1];
-                const existing = origins.get(name);
-                if (existing)
-                    throw new DuplicateSnippetError(name, where, existing);
-                into.set(name, dedent(open.get(name)));
-                origins.set(name, where);
-                open.delete(name);
-                continue;
-            }
-            const start = line.match(START);
-            if (start?.[1]) {
-                if (!open.has(start[1]))
-                    open.set(start[1], []);
-                continue;
-            }
-            if (end)
-                continue;
-            for (const body of open.values())
-                body.push(line);
-        }
-        const [unclosed] = open.keys();
-        if (unclosed)
-            throw new UnclosedSnippetError(unclosed, where);
-    }
-    return into;
-};
+export { collectSnippets, UnclosedSnippetError, DuplicateSnippetError, } from '@pikku/skills';

package/dist/src/functions/validate/type-identity-checks.d.ts

@@ -2,8 +2,9 @@ import type { ValidateFinding } from './persona-checks.js';
 /**
  * A linked dependency resolves its own imports from its own checkout, so it can
  * hand the project types built against a different version of a shared package.
- * The symptom is a typecheck that OOMs rather than one that fails, so nothing
- * else in this validator would catch it.
+ * An installed pikku package can do the same from its own store entry. The
+ * symptom is a typecheck that OOMs rather than one that fails, so nothing else
+ * in this validator would catch it.
  *
  * Runs against the workspace root only. The mismatch is a property of the
  * install, not of any one package in it, so running per workspace package would

package/dist/src/functions/validate/type-identity-checks.js

@@ -153,18 +153,87 @@ async function externalDependencyRoots(root) {
     }
     return found;
 }
+/**
+ * Every installed `@pikku/*` package, by the real directory its imports resolve
+ * from. Probed under the root and each workspace package, because an isolated
+ * install links a dependency only under the package that declares it.
+ */
+async function installedPikkuPackages(root) {
+    const bases = [root];
+    for (const group of ['packages', 'apps', 'backends']) {
+        const entries = await readdir(join(root, group), {
+            withFileTypes: true,
+        }).catch(() => []);
+        for (const d of entries) {
+            if (d.isDirectory())
+                bases.push(join(root, group, d.name));
+        }
+    }
+    const found = new Map();
+    for (const base of bases) {
+        const scope = join(base, 'node_modules', '@pikku');
+        const entries = await readdir(scope).catch(() => []);
+        for (const entry of entries) {
+            const real = await realpath(join(scope, entry)).catch(() => null);
+            if (real && !found.has(real))
+                found.set(real, `@pikku/${entry}`);
+        }
+    }
+    return found;
+}
+/**
+ * An installed pikku package can resolve its own copy of a type-identity
+ * package — bun's isolated store keeps one beside each entry — so the CLI can
+ * read the project's zod schemas with a different zod than wrote them. No link
+ * leaves the project, so the linked-dependency check never sees it.
+ *
+ * Only packages that declare the dependency are compared: walking up from one
+ * that never asked for it lands on whatever the store hoisted, which says
+ * nothing about what that package loads.
+ */
+async function runInstallSkewChecks(root) {
+    const findings = [];
+    const installed = await installedPikkuPackages(root);
+    for (const pkg of TYPE_IDENTITY_PKGS) {
+        const local = await projectResolvedVersion(root, pkg);
+        if (!local)
+            continue;
+        for (const [real, name] of installed) {
+            if (name === pkg)
+                continue;
+            const manifest = await readJsonSafe(join(real, 'package.json'));
+            if (!manifest?.dependencies?.[pkg] && !manifest?.peerDependencies?.[pkg])
+                continue;
+            const theirs = await versionResolvedFrom(real, pkg);
+            if (!theirs || theirs === local.version)
+                continue;
+            findings.push({
+                id: `skewed-type-identity-${name.replace(/[@/]/g, '-')}-${pkg.replace(/[@/]/g, '-')}`,
+                severity: 'error',
+                message: `${name} resolves ${pkg}@${theirs}, while this project resolves ${pkg}@${local.version} — two copies of ${pkg} in one install`,
+                path: real,
+                fixHint: [
+                    `${name} reads what the project builds with ${pkg} using its own copy, and TypeScript treats the two as unrelated types, so codegen can fail on schemas that are correct or exhaust the heap instead of reporting an error.`,
+                    `Pin one ${pkg} for the whole install — "overrides": { "${pkg}": "${local.version}" } in the root package.json (bun/npm; "resolutions" for yarn) — and reinstall.`,
+                ].join('\n'),
+            });
+        }
+    }
+    return findings;
+}
 /**
  * A linked dependency resolves its own imports from its own checkout, so it can
  * hand the project types built against a different version of a shared package.
- * The symptom is a typecheck that OOMs rather than one that fails, so nothing
- * else in this validator would catch it.
+ * An installed pikku package can do the same from its own store entry. The
+ * symptom is a typecheck that OOMs rather than one that fails, so nothing else
+ * in this validator would catch it.
  *
  * Runs against the workspace root only. The mismatch is a property of the
  * install, not of any one package in it, so running per workspace package would
  * report the same pair once per package.
  */
 export async function runTypeIdentityChecks(root) {
-    const findings = [];
+    const findings = await runInstallSkewChecks(root);
     const external = await externalDependencyRoots(root);
     if (external.size === 0)
         return findings;
@@ -208,11 +277,11 @@ export async function warnOnSplitTypeIdentity(rootDir, logger) {
     const findings = await runTypeIdentityChecks(rootDir).catch(() => []);
     if (findings.length === 0)
         return;
-    logger.warn(`[${ErrorCode.SPLIT_TYPE_IDENTITY}] ${findings.length === 1 ? 'A linked dependency resolves a shared package' : 'Linked dependencies resolve shared packages'} at a different version than this project:\n` +
+    logger.warn(`[${ErrorCode.SPLIT_TYPE_IDENTITY}] ${findings.length === 1 ? 'A dependency resolves a shared package' : 'Dependencies resolve shared packages'} at a different version than this project:\n` +
         findings.map((f) => `  ${f.message}`).join('\n') +
         `\nTypeScript treats each pair as two unrelated types and structurally compares them\n` +
         `wherever they meet, which inside a generic inference chain can exhaust the heap —\n` +
         `codegen then dies of memory pressure instead of reporting an error.\n\n` +
-        `Fix: align the versions so both trees resolve one copy, or drop the link and\n` +
+        `Fix: align the versions so the install resolves one copy, or drop the link and\n` +
         `reinstall. Set PIKKU_SKIP_TYPE_IDENTITY_CHECK=1 to silence this.`);
 }

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

@@ -82,9 +82,9 @@ export const CHECKS = [
     },
     {
         id: 'type-identity',
-        subject: 'linked dependencies',
-        // Root of an installed tree only. A linked dependency is a property of the
-        // install as a whole, so running this per workspace package reports the
+        subject: 'shared dependency versions',
+        // Root of an installed tree only. A linked or skewed dependency is a
+        // property of the install as a whole, so running this per workspace package reports the
         // same pair N times — and with nothing installed there is nothing to
         // compare.
         applies: async ({ dir, label }) => label === '.' && existsSync(join(dir, 'node_modules')),

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

@@ -72,7 +72,8 @@ export const serializeAuthGen = (definition, providers, authFile, leaf, packageM
         '',
         `import { defineSecret } from '@pikku/core/secret'`,
     ];
-    const hasVariables = known.some((name) => PROVIDER_REGISTRY[name].variables);
+    const hasVariables = known.some((name) => PROVIDER_REGISTRY[name].variables) ||
+        definition.cookieCache;
     if (hasVariables) {
         secrets.push(`import { defineVariable } from '@pikku/core/variable'`);
     }
@@ -133,6 +134,37 @@ export const serializeAuthGen = (definition, providers, authFile, leaf, packageM
             secrets.push('');
         }
     }
+    // The stateless session's cookie lifetime, declared only on the cookieCache
+    // path because that is the only path where it decides anything. There the
+    // signed `session_data` cookie is the ONLY thing authenticating a request —
+    // `betterAuthStatelessSession` verifies it with the secret and never reaches
+    // the database — and an app typically calls no `/api/auth/*` route once
+    // someone is signed in, so nothing rewrites the cookie. better-auth's own
+    // 300s default therefore signs everyone out five minutes after they log in.
+    //
+    // @pikku/better-auth reads this variable and applies it to the instance, so
+    // the app's own `betterAuth({ session: { cookieCache } })` needs no `maxAge`.
+    // It is declared rather than hardcoded because the lifetime is also the
+    // longest a ban or a revoked session can go unnoticed, which is a per-stage
+    // policy decision. Optional: unset means the one-day default.
+    //
+    // The schema is a string, not a coerced number. `TypedVariablesService`
+    // returns a stored host value UNPARSED and runs the schema only to resolve a
+    // default, so a `z.coerce.number()` here would never fire on a real value and
+    // would only mislead whoever read it.
+    if (definition.cookieCache) {
+        secrets.push(`export const SessionCookieCacheMaxAgeSchema = z.string().default('86400')`);
+        secrets.push('');
+        secrets.push(`defineVariable({`);
+        secrets.push(`  name: 'sessionCookieCacheMaxAge',`);
+        secrets.push(`  displayName: 'Session Cookie Lifetime (seconds)',`);
+        secrets.push(`  description: 'How long the signed session cookie is trusted before the API re-reads the session from the database. Also the longest a ban or a revoked session can go unnoticed. Defaults to 86400 (one day).',`);
+        secrets.push(`  variableId: 'SESSION_COOKIE_CACHE_MAX_AGE',`);
+        secrets.push(`  schema: SessionCookieCacheMaxAgeSchema,`);
+        secrets.push(`  optional: true,`);
+        secrets.push(`})`);
+        secrets.push('');
+    }
     // Wiring file: handler + catch-all routes. When cookieCache is enabled the
     // global session middleware is split into its own file (see below) so this
     // file's auth.wiring import (the full better-auth server) isn't dragged into

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

@@ -37,7 +37,7 @@ import type { WireAddonConfig } from '@pikku/core/addon'
 export { wireRemoteAddon } from '@pikku/core/addon'
 
 /**
- * The functions each installed addon publishes. \`mcp\` names them.
+ * The functions each installed addon publishes. \`mcp\` and \`expose\` name them.
  */
 type AddonFunctions = {
 ${entries}
@@ -52,11 +52,13 @@ type AddonFunctionName<Package extends string> =
  *
  * \`mcp: true\` offers every function the addon itself declared as a tool; a list
  * names the functions to offer, checked against the ones the addon publishes.
+ * \`expose\` works the same way for \`rpc.exposed\`, and \`false\` exposes none.
  */
 export const wireAddon = <Package extends string>(
-  config: Omit<WireAddonConfig, 'package' | 'mcp'> & {
+  config: Omit<WireAddonConfig, 'package' | 'mcp' | 'expose'> & {
     package: Package
     mcp?: boolean | AddonFunctionName<Package>[]
+    expose?: boolean | AddonFunctionName<Package>[]
   }
 ): void => wireAddonCore(config)
 `;

package/dist/src/functions/wirings/rpc/pikku-command-react-query.js

@@ -14,14 +14,15 @@ export const pikkuReactQuery = pikkuSessionlessFunc({
             });
             return;
         }
-        const { workflows } = await getInspectorState();
+        const { workflows, auth } = await getInspectorState();
         const hasWorkflows = Object.keys(workflows?.meta ?? {}).length > 0;
         const rpcMapPath = getFileImportRelativePath(reactQueryFile, rpcMapDeclarationFile, packageMappings);
         let workflowMapPath;
         if (hasWorkflows) {
             workflowMapPath = getFileImportRelativePath(reactQueryFile, workflowMapDeclarationFile, packageMappings);
         }
-        const content = serializeReactQueryHooks(rpcMapPath, workflowMapPath);
+        // `useSession` only exists for an app that has auth at all.
+        const content = serializeReactQueryHooks(rpcMapPath, workflowMapPath, !!auth.definition);
         await writeFileInDir(logger, reactQueryFile, content);
     },
     middleware: [

package/dist/src/functions/wirings/rpc/serialize-react-query-hooks.d.ts

@@ -1 +1 @@
-export declare const serializeReactQueryHooks: (rpcMapPath: string, workflowMapPath?: string) => string;
+export declare const serializeReactQueryHooks: (rpcMapPath: string, workflowMapPath?: string, hasAuth?: boolean) => string;

package/dist/src/functions/wirings/rpc/serialize-react-query-hooks.js

@@ -1,4 +1,4 @@
-export const serializeReactQueryHooks = (rpcMapPath, workflowMapPath) => {
+export const serializeReactQueryHooks = (rpcMapPath, workflowMapPath, hasAuth) => {
     const workflowImport = workflowMapPath
         ? `\nimport type { FlattenedWorkflowMap } from '${workflowMapPath}'`
         : '';
@@ -49,10 +49,61 @@ export const useWorkflowStatus = (
     ...options,
   })
 }
+`
+        : '';
+    /**
+     * The session — and, for free, the thing that heals the session cookie.
+     *
+     * Under `betterAuthStatelessSession` the signed `session_data` cookie is the
+     * only thing authenticating a request, and nothing rewrites it once someone
+     * is signed in. When it ages out, better-auth's cookie-cache branch bails on
+     * the stale payload and falls through to the database, reading the session
+     * from the still-valid `session_token` and minting a fresh cookie on the way
+     * out. So an ordinary cached read heals an expired cookie by itself.
+     *
+     * Which is why this does NOT pass `disableCookieCache`. Forcing it would turn
+     * every refetch into a database read — the exact cost the cookie cache exists
+     * to avoid — to re-mint a cookie that has most of its life left. The read is
+     * worth paying once, when the cookie has actually expired, and that is when
+     * better-auth does it anyway.
+     *
+     * better-auth's own sliding renewal (`session.cookieCache.refreshCache`) is
+     * not the answer either: it is force-disabled whenever a database is
+     * configured, and where it does apply it re-signs the cached blob without
+     * reading the database, so a banned user's cookie would renew forever.
+     */
+    const sessionImport = hasAuth ? ', usePikkuFetch' : '';
+    const sessionHook = hasAuth
+        ? `
+/* Short enough that an expired cookie is healed long before anyone notices,
+   and cheap: while the cookie is good this is a cache hit with no database
+   behind it. */
+const SESSION_REFETCH_MS = 10 * 60 * 1000
+/* A tab flicked away from and back to should not refetch on every glance. */
+const SESSION_STALE_MS = 2 * 60 * 1000
+
+export const useSession = <Session = unknown>(
+  options?: Omit<UseQueryOptions<Session | null, Error>, 'queryKey' | 'queryFn'>
+) => {
+  const fetch = usePikkuFetch()
+  return useQuery<Session | null, Error>({
+    queryKey: ['pikkuSession'],
+    queryFn: async () => {
+      const response = await fetch.fetch('/auth/get-session', 'GET', undefined)
+      if (!response.ok) return null
+      // Signed out is a null body, not an error status.
+      return ((await response.json().catch(() => null)) ?? null) as Session | null
+    },
+    refetchInterval: SESSION_REFETCH_MS,
+    refetchOnWindowFocus: true,
+    staleTime: SESSION_STALE_MS,
+    ...options,
+  })
+}
 `
         : '';
     return `import { useQuery, useInfiniteQuery, useMutation, type UseQueryOptions, type UseInfiniteQueryOptions, type UseMutationOptions, type InfiniteData } from '@tanstack/react-query'
-import { usePikkuRPC } from '@pikku/react'
+import { usePikkuRPC${sessionImport} } from '@pikku/react'
 import type { FlattenedRPCMap } from '${rpcMapPath}'${workflowImport}
 
 type RPCInvoke = <Name extends keyof FlattenedRPCMap>(name: Name, data: FlattenedRPCMap[Name]['input']) => Promise<FlattenedRPCMap[Name]['output']>
@@ -104,5 +155,5 @@ export const usePikkuInfiniteQuery = <Name extends PaginatedKeys>(
     ...options,
   })
 }
-${workflowHooks}`;
+${sessionHook}${workflowHooks}`;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.160",
+  "version": "0.12.162",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -38,21 +38,21 @@
     "@jridgewell/trace-mapping": "^0.3.31",
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.4",
     "@pikku/ai-vercel": "^0.12.14",
-    "@pikku/better-auth": "^0.12.44",
+    "@pikku/better-auth": "^0.12.46",
     "@pikku/bun-server": "^0.12.13",
     "@pikku/code-edit": "^0.12.2",
     "@pikku/deploy": "^0.12.11",
     "@pikku/deploy-cloudflare": "^0.12.18",
     "@pikku/fetch": "^0.12.12",
-    "@pikku/inspector": "^0.12.86",
+    "@pikku/inspector": "^0.12.87",
     "@pikku/knowledge": "^0.12.15",
-    "@pikku/kysely": "^0.13.27",
+    "@pikku/kysely": "^0.13.28",
     "@pikku/migrator-sql": "^0.12.5",
     "@pikku/n8n-import": "^0.0.8",
     "@pikku/node-http-server": "^0.12.17",
-    "@pikku/openapi-parser": "^0.12.21",
+    "@pikku/openapi-parser": "^0.12.22",
     "@pikku/schedule": "^0.12.8",
-    "@pikku/skills": "^0.12.35",
+    "@pikku/skills": "^0.12.37",
     "@pikku/websocket": "^0.12.5",
     "@types/cookie": "^1.0.0",
     "@types/json-schema": "^7.0.15",
@@ -75,15 +75,15 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.118",
-    "@pikku/playwright": "^0.12.84",
+    "@pikku/core": "^0.12.120",
+    "@pikku/playwright": "^0.12.85",
     "@pikku/ws": "^0.12.10",
     "better-auth": "^1.7.5",
     "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.118",
-    "@pikku/playwright": "^0.12.84",
+    "@pikku/core": "^0.12.120",
+    "@pikku/playwright": "^0.12.85",
     "@pikku/ws": "^0.12.10",
     "@playwright/test": "^1.50.0",
     "@standard-schema/spec": "^1.1.0",

package/snippets-meta.json

@@ -50,6 +50,7 @@
   "getBasket": "src/functions/basket/get-basket.function.ts",
   "getItem": "src/functions/items/get-item.function.ts",
   "getOrder": "src/functions/orders/get-order.function.ts",
+  "guideCaptureStep": "test/scenarios/guide.steps.ts",
   "httpAuthRoute": "src/wirings/shop.http.ts",
   "httpMiddleware": "src/wirings/shop.http.ts",
   "httpRoutesWiring": "src/wirings/shop.http.ts",

package/snippets.json

@@ -50,6 +50,7 @@
   "getBasket": "export const getBasket = pikkuSessionlessFunc({\n  expose: true,\n  description:\n    'Get basket for the current user or session. Creates one if it does not exist.',\n  input: GetBasketInput,\n  output: GetBasketOutput,\n  func: async ({ kysely }, { sessionId }, { session }) => {\n    const userId = session?.userId ?? null\n    const sid = sessionId ?? null\n\n    // Find or create basket\n    let basket = userId\n      ? await kysely\n          .selectFrom('basket')\n          .selectAll()\n          .where('userId', '=', userId)\n          .executeTakeFirst()\n      : sid\n        ? await kysely\n            .selectFrom('basket')\n            .selectAll()\n            .where('sessionId', '=', sid)\n            .executeTakeFirst()\n        : null\n\n    if (!basket) {\n      const basketId = randomUUID()\n      const now = new Date().toISOString()\n      await kysely\n        .insertInto('basket')\n        .values({\n          basketId,\n          userId,\n          sessionId: sid,\n          createdAt: now,\n          updatedAt: now,\n        })\n        .execute()\n      return { basketId, items: [], totalCents: 0, itemCount: 0 }\n    }\n\n    const rows = await kysely\n      .selectFrom('basketItem')\n      .innerJoin('item', 'item.itemId', 'basketItem.itemId')\n      .select([\n        'basketItem.basketItemId',\n        'basketItem.itemId',\n        'basketItem.quantity',\n        'item.name',\n        'item.slug',\n        'item.priceCents',\n        'item.imageUrl',\n      ])\n      .where('basketItem.basketId', '=', basket.basketId)\n      .execute()\n\n    const items = rows.map((r) => ({\n      basketItemId: r.basketItemId,\n      itemId: r.itemId,\n      name: r.name,\n      slug: r.slug,\n      priceCents: r.priceCents,\n      imageUrl: r.imageUrl,\n      quantity: r.quantity,\n      lineTotalCents: r.priceCents * r.quantity,\n    }))\n\n    return {\n      basketId: basket.basketId,\n      items,\n      totalCents: items.reduce((sum, i) => sum + i.lineTotalCents, 0),\n      itemCount: items.reduce((sum, i) => sum + i.quantity, 0),\n    }\n  },\n})",
   "getItem": "export const getItem = pikkuSessionlessFunc({\n  expose: true,\n  description: 'Get a single item by ID.',\n  input: GetItemInput,\n  output: GetItemOutput,\n  func: async ({ kysely }, { itemId }) => {\n    const row = await kysely\n      .selectFrom('item')\n      .innerJoin('category', 'category.categoryId', 'item.categoryId')\n      .select([\n        'item.itemId',\n        'item.name',\n        'item.slug',\n        'item.description',\n        'item.priceCents',\n        'item.stock',\n        'item.imageUrl',\n        'item.isActive',\n        'item.createdAt',\n        'item.updatedAt',\n        'category.categoryId',\n        'category.name as categoryName',\n        'category.slug as categorySlug',\n      ])\n      .where('item.itemId', '=', itemId)\n      .executeTakeFirst()\n\n    if (!row) throw new Error(`Item not found: ${itemId}`)\n\n    return {\n      ...row,\n      category: {\n        categoryId: row.categoryId,\n        name: row.categoryName,\n        slug: row.categorySlug,\n      },\n    }\n  },\n})",
   "getOrder": "// Three parameters, always: services, data, wire.\n//   services — your toolbox (db, logger, queues)\n//   data     — the typed input, wherever it arrived from\n//   wire     — the protocol context (session, http, channel, rpc)\nexport const getOrder = pikkuFunc({\n  expose: true,\n  description: 'Get a single order. Users can only access their own orders.',\n  input: GetOrderInput,\n  output: GetOrderOutput,\n  func: async ({ kysely }, { orderId }, { session }) => {\n    const order = await kysely\n      .selectFrom('order')\n      .selectAll()\n      .where('orderId', '=', orderId)\n      .executeTakeFirst()\n\n    if (!order) throw new Error('Order not found')\n    if (order.userId !== session.userId && session.role !== 'admin') {\n      throw new Error('Forbidden')\n    }\n\n    const items = await kysely\n      .selectFrom('orderItem')\n      .innerJoin('item', 'item.itemId', 'orderItem.itemId')\n      .select([\n        'orderItem.itemId',\n        'item.name',\n        'orderItem.quantity',\n        'orderItem.unitPriceCents',\n      ])\n      .where('orderItem.orderId', '=', orderId)\n      .execute()\n\n    return {\n      orderId: order.orderId,\n      status: order.status,\n      totalCents: order.totalCents,\n      // Nullable: a walk-through order placed before an address was captured\n      // has none, and returning null beats throwing on a read.\n      shippingAddress: order.shippingAddress\n        ? JSON.parse(order.shippingAddress)\n        : null,\n      items: items.map((i) => ({\n        ...i,\n        lineTotalCents: i.unitPriceCents * i.quantity,\n      })),\n      createdAt: order.createdAt,\n    }\n  },\n})",
+  "guideCaptureStep": "import { z } from 'zod'\nimport { pikkuScenarioStep } from '#pikku/scenarios'\n\nexport const CapturesScreenInput = z.object({\n  path: z.string(),\n  name: z.string(),\n})\n\nexport const CapturesScreenOutput = z.object({ captured: z.boolean() })\n\nexport const capturesScreen = pikkuScenarioStep({\n  name: 'capturesScreen',\n  description: 'captures the named screen',\n  template: 'captures {name}',\n  input: CapturesScreenInput,\n  output: CapturesScreenOutput,\n  browser: async (_services, { path, name }, { browser }) => {\n    await browser.goto(path)\n    await browser.screenshot(name, { showcase: true })\n    return { captured: true }\n  },\n})",
   "httpAuthRoute": "// Public route — no auth required\nwireHTTP({ method: 'get', route: '/items', func: listItems, auth: false })\n\n// Protected route — requires a user session\nwireHTTP({ method: 'post', route: '/orders', func: createOrder, auth: true })",
   "httpMiddleware": "// Global middleware — applies to every HTTP route\naddHTTPMiddleware('*', [\n  async ({ logger }, data, next) => {\n    const start = Date.now()\n    await next()\n    logger.info({ path: data.http?.request?.path(), ms: Date.now() - start })\n  },\n])\n\n// Prefix middleware — applies only to /orders/*\naddHTTPMiddleware('/orders', [\n  async (_services, _data, next) => {\n    // e.g. rate-limit order creation\n    await next()\n  },\n])",
   "httpRoutesWiring": "wireHTTPRoutes({ routes: { shop: shopRoutes } })",

package/surface.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.12.160",
+  "version": "0.12.162",
   "entryPoints": [
     {
       "id": "app",
@@ -1171,8 +1171,8 @@
                 "via": "generated"
               },
               "summary": "Installs an addon into this project: its functions, wirings and scopes become part of the app, under the namespace and options given here.",
-              "docs": "Installs an addon into this project: its functions, wirings and scopes become\npart of the app, under the namespace and options given here.\n\n`mcp: true` offers every function the addon itself declared as a tool; a list\nnames the functions to offer, checked against the ones the addon publishes.",
-              "signature": "<Package extends string>(config: Omit<WireAddonConfig, \"package\" | \"mcp\"> & { package: Package; mcp?: boolean | AddonFunctionName<Package>[]; }) => void",
+              "docs": "Installs an addon into this project: its functions, wirings and scopes become\npart of the app, under the namespace and options given here.\n\n`mcp: true` offers every function the addon itself declared as a tool; a list\nnames the functions to offer, checked against the ones the addon publishes.\n`expose` works the same way for `rpc.exposed`, and `false` exposes none.",
+              "signature": "<Package extends string>(config: Omit<WireAddonConfig, \"package\" | \"mcp\" | \"expose\"> & { package: Package; mcp?: boolean | AddonFunctionName<Package>[]; expose?: boolean | AddonFunctionName<Package>[]; }) => void",
               "members": [
                 {
                   "line": "auth?: boolean",
@@ -4227,6 +4227,8 @@
                 "via": "core",
                 "subpath": "./workflow"
               },
+              "summary": "One actor's browser session, handed to a step as `wire.browser`.",
+              "docs": "One actor's browser session, handed to a step as `wire.browser`.\n\nOnly what every driver can honour is declared here. A driver package adds\nthe rest by declaration-merging onto this interface — `@pikku/playwright`\ncontributes `page`, `context` and `locate` — so a step written against the\nstructural surface keeps working whichever driver runs it.",
               "members": [
                 {
                   "line": "actor: string",
@@ -8132,6 +8134,8 @@
                 "via": "core",
                 "subpath": "./workflow"
               },
+              "summary": "One actor's browser session, handed to a step as `wire.browser`.",
+              "docs": "One actor's browser session, handed to a step as `wire.browser`.\n\nOnly what every driver can honour is declared here. A driver package adds\nthe rest by declaration-merging onto this interface — `@pikku/playwright`\ncontributes `page`, `context` and `locate` — so a step written against the\nstructural surface keeps working whichever driver runs it.",
               "members": [
                 {
                   "line": "actor: string",

package/console-app/assets/architecture-7GRP2DOG-3y7bWtag.js

@@ -1 +0,0 @@
-import"./chunk-FOHPRMQF-CoA4358r.js";import{M as e}from"./mermaid-parser.core-U7wquvx8.js";export{e as createArchitectureServices};