@pikku/cli 0.12.159 → 0.12.162

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

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { resolve, join } from 'node:path';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, join, dirname, relative, sep } from 'node:path';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { glob } from 'tinyglobby';
 import { pikkuSessionlessFunc } from '#pikku/function';
 import { InMemoryWorkflowService } from '@pikku/core/services';
 import { FileScenarioRunStore } from '@pikku/core/services';
@@ -14,7 +15,8 @@ import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './sce
 import { resolvePersonas } from '../../utils/resolve-personas.js';
 import { resolvePersonaCredentials } from '../../utils/persona-credentials.js';
 import { spawnDevServer } from '../../server/spawn-dev-server.js';
-import { buildScenarioPlan } from './scenario-plan.js';
+import { checkGuideCoverage, featureEvidence, guideStep, parseGuideLock, parseGuidePage, renderGuideLock, renderGuidePage, } from './scenario-guide.js';
+import { buildScenarioPlan, identifyScenarioResult } from './scenario-plan.js';
 import { resolveEnvironment, isLocalUrl } from './environment.js';
 import { readDevAddress } from './dev-address.js';
 import { createDevAgentRunner } from './dev-agent-runner.js';
@@ -354,11 +356,18 @@ export const scenarioRun = pikkuSessionlessFunc({
         const runStore = new FileScenarioRunStore({ dir: captureDir });
         const startedAtIso = new Date().toISOString();
         try {
+            const selection = {
+                ...(split(flows) ? { flows: split(flows) } : {}),
+                ...(split(features) ? { features: split(features) } : {}),
+                ...(split(tags) ? { tags: split(tags) } : {}),
+                ...(split(excludeTags) ? { excludeTags: split(excludeTags) } : {}),
+            };
             await runStore.start({
                 runId: captureRunId,
                 environment,
                 surface: runSurface,
                 status: 'running',
+                ...(Object.keys(selection).length > 0 ? { selection } : {}),
                 startedAt: startedAtIso,
                 results: [],
                 skipped,
@@ -371,6 +380,11 @@ export const scenarioRun = pikkuSessionlessFunc({
              * is the formatter's job.
              */
             const readRunSteps = async (service, runId, flowName) => {
+                // Taken from the run rather than derived from the ladder: the video
+                // clock starts when an actor's window opens, which is somewhere after
+                // step one, and every step that never touched a browser burns scenario
+                // time while the recording sits still.
+                const videoOffsets = scenarioService.takeStepVideoOffsets(runId);
                 const prose = collectScenarioStepProse(state.workflows?.meta?.[flowName], functionsMeta, state.personas?.definitions ?? []);
                 const steps = (await service.getRunSteps(runId)).map((step) => ({
                     stepName: step.stepName,
@@ -383,6 +397,7 @@ export const scenarioRun = pikkuSessionlessFunc({
                     expected: step.error?.expected,
                     input: step.data,
                     stepFunc: step.rpcName,
+                    video: videoOffsets.get(step.stepName),
                 }));
                 return {
                     rows: scenarioStepRows(steps, prose),
@@ -427,33 +442,29 @@ export const scenarioRun = pikkuSessionlessFunc({
             };
             const hookFailures = [];
             /**
-             * What a result carries beyond its own outcome: which registration ran,
-             * which feature grouped it, and the tags it was selected by. Snapshotted
-             * into the record because a run read back next week is describing a suite
+             * Which registration ran and which feature grouped it, snapshotted into
+             * the record because a run read back next week is describing a suite
              * whose source has moved on.
              */
-            const identify = (result, scenarioName, feature) => {
-                const tags = state.workflows?.meta?.[scenarioName]?.tags;
-                return {
-                    ...result,
-                    scenarioName,
-                    ...(feature ? { feature } : {}),
-                    ...(tags?.length ? { tags } : {}),
-                };
-            };
-            const runEntry = async (label, scenarioName, data, feature) => {
+            const identityOf = (scenarioName, group) => ({
+                scenarioName,
+                featureId: group?.featureId,
+                featureName: group?.featureName,
+                tags: state.workflows?.meta?.[scenarioName]?.tags,
+            });
+            const runEntry = async (label, scenarioName, data, identity) => {
                 const startedAt = Date.now();
                 if (databaseBaseline) {
                     try {
                         await databaseBaseline.restore();
                     }
                     catch (e) {
-                        const result = identify({
+                        const result = identifyScenarioResult({
                             name: label,
                             status: 'failed',
                             durationMs: Date.now() - startedAt,
                             error: `database reset failed: ${e?.message ?? e}`,
-                        }, scenarioName, feature);
+                        }, identity);
                         results.push(result);
                         await runStore.recordScenario(captureRunId, result);
                         return;
@@ -534,7 +545,7 @@ export const scenarioRun = pikkuSessionlessFunc({
                 // Told here, acted on at the next scenario's reset — that is what closes
                 // these windows and finalises the video this outcome decides the fate of.
                 browserLifecycle.endScenario(result.status);
-                Object.assign(result, identify(result, scenarioName, feature));
+                Object.assign(result, identifyScenarioResult(result, identity));
                 await runStore.recordScenario(captureRunId, result);
                 if (coverageActive) {
                     const report = await invokeCoverage('pikkuScenarioTakeLiveCoverage');
@@ -582,19 +593,19 @@ export const scenarioRun = pikkuSessionlessFunc({
                         // Setup failed, so nothing in the group ran. Reporting them as failed
                         // rather than skipped is the honest reading: they did not pass.
                         for (const entry of group.entries) {
-                            const result = identify({
+                            const result = identifyScenarioResult({
                                 name: label(entry),
                                 status: 'failed',
                                 durationMs: 0,
                                 error: `${groupName ? `feature '${groupName}' ` : ''}${beforeStage} failed: ${beforeError?.message ?? beforeError}`,
-                            }, entry.scenarioName, groupName);
+                            }, identityOf(entry.scenarioName, group));
                             results.push(result);
                             await runStore.recordScenario(captureRunId, result);
                         }
                     }
                     else {
                         for (const entry of group.entries) {
-                            await runEntry(label(entry), entry.scenarioName, entry.data, groupName);
+                            await runEntry(label(entry), entry.scenarioName, entry.data, identityOf(entry.scenarioName, group));
                         }
                     }
                 }
@@ -699,3 +710,156 @@ export const scenarioRun = pikkuSessionlessFunc({
         }
     },
 });
+/**
+ * `pikku scenario guide` — the suite, written out as markdown.
+ *
+ * Structure comes from the registry (which features exist, what their scenarios
+ * are called), and evidence from the latest run record (what the steps actually
+ * said, and what they filed). Editorial prose comes from the project's own
+ * `docs/` sources, which cite a feature by leaving the marker pair where its
+ * block belongs; this merges the three and writes one markdown file per source.
+ * It renders nothing, resolves no asset URLs and calls no model: the writing is
+ * somebody else's concern, and this is the compiler that keeps it honest.
+ */
+export const scenarioGuide = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, { docs = 'docs', output, runId, allowUndocumented = false, artifactBase }) => {
+        const state = await getInspectorState(false, false, false, true);
+        const outDir = resolve(config.rootDir, config.outDir);
+        await loadScenarioBootstrap(outDir);
+        const { features: registeredFeatures } = collectRegisteredWirings();
+        const runsDir = join(outDir, 'scenario-runs');
+        const runStore = new FileScenarioRunStore({ dir: runsDir });
+        const latest = runId ?? (await runStore.list({ limit: 1 }))[0]?.runId;
+        const record = latest ? await runStore.get(latest) : undefined;
+        if (!record) {
+            logger.error(runId
+                ? `No run '${runId}' under ${runsDir}.`
+                : `No scenario run under ${runsDir} — run \`pikku scenario run <environment> --screenshots\` first, since a guide is written out of what a run recorded.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (record.status !== 'passed') {
+            logger.error(`Run '${record.runId}' is ${record.status}. A guide is a claim that the product does what the page says, so it is only ever written out of a run that passed.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (record.selection) {
+            const narrowed = Object.entries(record.selection)
+                .map(([flag, values]) => `--${flag} ${values.join(',')}`)
+                .join(' ');
+            logger.error(`Run '${record.runId}' was narrowed (${narrowed}), so it is missing scenarios the suite has. Guide pages would be written as though those flows do not exist — run the whole suite, or pass --run-id for one that was.`);
+            process.exitCode = 1;
+            return;
+        }
+        const workflowsMeta = state.workflows?.meta ?? {};
+        const features = [...registeredFeatures].map(([id, feature]) => {
+            const name = feature.name ?? id;
+            return {
+                id,
+                name,
+                ...(feature.description ? { description: feature.description } : {}),
+                document: feature.document !== false,
+                scenarios: record.results
+                    // By id, never by the display name: a title is rewritten freely,
+                    // and two features are allowed to share one.
+                    .filter((result) => result.featureId === id ||
+                    (result.featureId === undefined && result.feature === name))
+                    .map((result) => {
+                    const meta = result.scenarioName
+                        ? workflowsMeta[result.scenarioName]
+                        : undefined;
+                    return {
+                        name: result.scenarioName ?? result.name,
+                        title: meta?.title ?? result.name,
+                        ...(meta?.description ? { description: meta.description } : {}),
+                        steps: (result.steps ?? []).map((step) => guideStep(step.sentence)),
+                        screenshots: (result.artifacts ?? [])
+                            .filter((artifact) => artifact.kind === 'screenshot')
+                            .map((artifact) => ({
+                            ...(artifact.id ? { id: artifact.id } : {}),
+                            ...(artifact.name ? { name: artifact.name } : {}),
+                            path: artifact.path,
+                        })),
+                        videos: (result.artifacts ?? [])
+                            .filter((artifact) => artifact.kind === 'video')
+                            .map((artifact) => ({
+                            ...(artifact.id ? { id: artifact.id } : {}),
+                            ...(artifact.actor ? { actor: artifact.actor } : {}),
+                            path: artifact.path,
+                        })),
+                    };
+                }),
+            };
+        });
+        const docsDir = resolve(config.rootDir, docs);
+        const sources = (await glob('**/*.md', { cwd: docsDir, onlyFiles: true })).sort();
+        const pages = [];
+        for (const source of sources) {
+            pages.push(parseGuidePage(source, readFileSync(join(docsDir, source), 'utf-8')));
+        }
+        const lockPath = join(docsDir, '.guide.lock');
+        const lock = existsSync(lockPath)
+            ? parseGuideLock(readFileSync(lockPath, 'utf-8'))
+            : {};
+        const coverage = checkGuideCoverage(features, pages, lock);
+        for (const { path, featureId } of coverage.unknown) {
+            logger.error(`${join(docs, path)} cites '${featureId}', which is not a registered feature — a page describing something that no longer exists.`);
+        }
+        for (const { path, featureId } of coverage.optedOut) {
+            logger.error(`${join(docs, path)} cites '${featureId}', which declares \`document: false\`.`);
+        }
+        for (const { path, featureId } of coverage.figureless) {
+            logger.warn(`${join(docs, path)} cites '${featureId}', whose run filed no screenshot — the block renders empty. Take one with \`actor.screenshot(...)\` in a scenario the feature owns.`);
+        }
+        for (const { path, featureId, locked, current } of coverage.stale) {
+            logger.warn(`${join(docs, path)} was written against '${featureId}' at ${locked}, which is now ${current} — the flow moved, so re-read the prose around that block.`);
+        }
+        for (const featureId of coverage.missing) {
+            const message = `Feature '${featureId}' is cited by no page. Place \`<!-- pikku:guide feature=${featureId} -->\` and \`<!-- /pikku:guide -->\` in a page under ${docs}/, or set \`document: false\` on the feature.`;
+            if (allowUndocumented) {
+                logger.warn(message);
+            }
+            else {
+                logger.error(message);
+            }
+        }
+        // A compiler that has found an error does not emit. Undocumented features
+        // are the one failure that can be downgraded, because a suite mid-way
+        // through being written still wants its pages built.
+        if (coverage.unknown.length > 0 ||
+            coverage.optedOut.length > 0 ||
+            (!allowUndocumented && coverage.missing.length > 0)) {
+            process.exitCode = 1;
+            return;
+        }
+        const byId = new Map(features.map((feature) => [feature.id, feature]));
+        const outputDir = output
+            ? resolve(config.rootDir, output)
+            : join(outDir, 'guide');
+        const artifactRoot = join(runsDir, record.runId);
+        for (const page of pages) {
+            const target = join(outputDir, page.path);
+            // Relative, forward-slashed and computed per page: a guide is markdown
+            // with ordinary image refs, and whoever consumes it rewrites the paths.
+            // `artifactBase` replaces it with one prefix for every page, for a host
+            // that serves the artifacts at a fixed address rather than beside the
+            // markdown — and it stays as given, since only the caller knows whether
+            // it is a path, a route or an origin.
+            const base = artifactBase
+                ? artifactBase.endsWith('/')
+                    ? artifactBase
+                    : `${artifactBase}/`
+                : `${relative(dirname(target), artifactRoot).split(sep).join('/')}/`;
+            const markdown = renderGuidePage(page, byId, base);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, markdown);
+        }
+        writeFileSync(lockPath, renderGuideLock(features, coverage.cited));
+        logger.info(`${pages.length} page(s) → ${outputDir} (run ${record.runId}, ${coverage.cited.length} documented feature(s))`);
+        for (const feature of features) {
+            if (feature.document) {
+                logger.debug(`  ${feature.id} ${featureEvidence(feature)}`);
+            }
+        }
+    },
+});

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;