@pikku/cli 0.12.160 → 0.12.163

package/dist/src/functions/db/better-auth-schema.js

@@ -106,11 +106,28 @@ function fakeSecretService() {
         setSecret: async () => { },
     };
 }
+// Better Auth checks its tables against the database the moment it is built,
+// and logs "Database schema mismatch" when they are missing. Here they are
+// always missing: the database is a scratch one the auth migrations are about
+// to run into. The check reaches the database through `connection()` alone,
+// so parking that call keeps the instance quiet without touching the queries
+// the migrator runs.
+export function withoutAuthSchemaCheck(kysely) {
+    return new Proxy(kysely, {
+        get: (target, prop) => {
+            if (prop === 'connection') {
+                return () => ({ execute: () => new Promise(() => { }) });
+            }
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
 function schemaServicesStub(kysely, logger) {
     const variables = new LocalVariablesService();
     const secrets = fakeSecretService();
     const base = {
-        kysely,
+        kysely: withoutAuthSchemaCheck(kysely),
         logger,
         secrets,
         variables,
@@ -144,6 +161,62 @@ async function loadAuthConfig(opts) {
         return undefined;
     return userCreateConfig(new LocalVariablesService());
 }
+/**
+ * Build the auth instance without a plugin's background init being able to kill
+ * the process.
+ *
+ * Reading the schema means reading `options`, which Better Auth assembles while
+ * the constructor runs — but from 1.7 a plugin's `init` also starts real work
+ * and does not wait for it. The OAuth provider behind `@better-auth/mcp` seeds
+ * its `oauthResource` rows this way. Here that work has nowhere to go: the
+ * database it is handed is a throwaway whose auth tables do not exist yet, and
+ * on the SQLite path the handle is closed as soon as the options have been
+ * read. The seed then rejects with nothing awaiting it, and Node's default for
+ * an unhandled rejection is to terminate — so `pikku db generate` died on
+ * `database is not open`, from a write the schema derivation never wanted, in a
+ * project whose only offence was configuring MCP.
+ *
+ * Rejections are reported rather than swallowed: they say a plugin tried to
+ * touch the database while being introspected, which is worth seeing, but never
+ * worth failing the command over. Whatever the plugin was doing is irrelevant
+ * to the shape of its tables, which is all that is being read.
+ *
+ * The handler is installed only around the call and only added to whatever the
+ * host already has, so a real unhandled rejection anywhere else still behaves
+ * exactly as it did.
+ */
+async function withoutPluginInitCrashing(build) {
+    const existing = process.listeners('unhandledRejection');
+    const swallow = (reason) => {
+        const message = reason instanceof Error ? reason.message : String(reason);
+        debugInitRejection(message);
+    };
+    for (const listener of existing) {
+        process.off('unhandledRejection', listener);
+    }
+    process.on('unhandledRejection', swallow);
+    try {
+        const instance = await build();
+        // One turn of the loop, so an init that rejects immediately does so while
+        // the guard is still the only listener. A slower one is caught by the
+        // `swallow` handler that outlives this only if the host had none of its
+        // own — which is why the originals go back on before it comes off.
+        await new Promise((resolve) => setImmediate(resolve));
+        return instance;
+    }
+    finally {
+        for (const listener of existing) {
+            process.on('unhandledRejection', listener);
+        }
+        process.off('unhandledRejection', swallow);
+    }
+}
+function debugInitRejection(message) {
+    if (process.env.PIKKU_DEBUG) {
+        // eslint-disable-next-line no-console
+        console.debug(`[pikku] a Better Auth plugin's init failed while its schema was being read, which does not affect the schema: ${message}`);
+    }
+}
 export async function loadAuthOptions(opts) {
     const sourceFile = findAuthSourceFile(opts.rootDir, opts.srcDirectories);
     if (!sourceFile)
@@ -153,7 +226,7 @@ export async function loadAuthOptions(opts) {
         return null;
     const services = schemaServicesStub(opts.kysely, opts.logger);
     services.config = await loadAuthConfig(opts);
-    const instance = await factory(services);
+    const instance = await withoutPluginInitCrashing(() => factory(services));
     const options = instance.options;
     return options ?? null;
 }

package/dist/src/functions/db/ensure-db-types.d.ts

@@ -0,0 +1,12 @@
+import { resolveDb } from './local-db.js';
+/**
+ * Make sure `db/schema.gen.ts` exists before anything is typechecked.
+ *
+ * A fresh project's services import `DB` from `#pikku/db/schema.gen.js`, but
+ * only `pikku db migrate` / `pikku db codegen` used to write it, so the first
+ * `pikku all` failed on a module that had not been generated yet. The types
+ * come from the migrations alone (a scratch database), so nothing needs to be
+ * reachable. If even that fails, an empty `DB` keeps the import resolvable
+ * until `db migrate` writes the real one.
+ */
+export declare function ensureDbTypes(rootDir: string, outDir: string, runtimeDir?: string, dbConfig?: Parameters<typeof resolveDb>[4]): Promise<'present' | 'generated' | 'stubbed' | 'no-db'>;

package/dist/src/functions/db/ensure-db-types.js

@@ -0,0 +1,29 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { resolveDb, migrateAndCodegen } from './local-db.js';
+/**
+ * Make sure `db/schema.gen.ts` exists before anything is typechecked.
+ *
+ * A fresh project's services import `DB` from `#pikku/db/schema.gen.js`, but
+ * only `pikku db migrate` / `pikku db codegen` used to write it, so the first
+ * `pikku all` failed on a module that had not been generated yet. The types
+ * come from the migrations alone (a scratch database), so nothing needs to be
+ * reachable. If even that fails, an empty `DB` keeps the import resolvable
+ * until `db migrate` writes the real one.
+ */
+export async function ensureDbTypes(rootDir, outDir, runtimeDir, dbConfig) {
+    const resolved = resolveDb({}, rootDir, outDir, runtimeDir, dbConfig);
+    if (!resolved)
+        return 'no-db';
+    if (existsSync(resolved.schemaFile))
+        return 'present';
+    try {
+        await migrateAndCodegen(resolved, { scratch: true });
+        if (existsSync(resolved.schemaFile))
+            return 'generated';
+    }
+    catch { }
+    mkdirSync(dirname(resolved.schemaFile), { recursive: true });
+    writeFileSync(resolved.schemaFile, 'export interface DB {}\n', 'utf8');
+    return 'stubbed';
+}

package/dist/src/functions/knowledge/console-url.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const ConsoleUrlOutput: z.ZodObject<{
+    consoleUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Where the console shows a knowledge file: the running dev server's address
+ * when there is one, the default port otherwise. The id keeps its slashes so the
+ * link reads as the path it names.
+ */
+export declare const knowledgeConsoleUrl: (config: {
+    rootDir: string;
+    runtimeDir?: string;
+}, path: string) => string | undefined;

package/dist/src/functions/knowledge/console-url.js

@@ -0,0 +1,18 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { readDevAddress } from '../commands/dev-address.js';
+const FALLBACK_ORIGIN = 'http://localhost:3000';
+export const ConsoleUrlOutput = z.object({ consoleUrl: z.string().optional() });
+/**
+ * Where the console shows a knowledge file: the running dev server's address
+ * when there is one, the default port otherwise. The id keeps its slashes so the
+ * link reads as the path it names.
+ */
+export const knowledgeConsoleUrl = (config, path) => {
+    if (!path)
+        return undefined;
+    const runtimeDir = config.runtimeDir ?? join(config.rootDir, '.pikku-runtime');
+    const origin = (readDevAddress(runtimeDir)?.apiUrl ?? FALLBACK_ORIGIN).replace(/\/+$/, '');
+    const id = encodeURIComponent(path).replace(/%2F/g, '/');
+    return `${origin}/console/knowledge?id=${id}`;
+};

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

@@ -1,10 +1,13 @@
 import type { KnowledgeIndexResult, KnowledgePlanDeferResult, KnowledgePlanProgressResult, KnowledgePlanSchemaResult, KnowledgePlanSetResult, KnowledgePlanShowResult, KnowledgeReconcileResult, 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;
+type ConsoleUrl = {
+    consoleUrl?: string;
+};
 export declare const renderKnowledgePlanSchema: (_services: unknown, { schema }: KnowledgePlanSchemaResult) => void;
-export declare const renderKnowledgePlanShow: (_services: unknown, { ok, path, body }: KnowledgePlanShowResult) => void;
-export declare const renderKnowledgePlanProgress: (_services: unknown, { ok, path, message, done, missing, deferred, problems, }: KnowledgePlanProgressResult) => void;
-export declare const renderKnowledgePlanSet: (_services: unknown, { ok, path, problems, schema }: KnowledgePlanSetResult) => void;
+export declare const renderKnowledgePlanShow: (_services: unknown, { ok, path, body, consoleUrl }: KnowledgePlanShowResult & ConsoleUrl) => void;
+export declare const renderKnowledgePlanProgress: (_services: unknown, { ok, path, message, done, missing, deferred, problems, consoleUrl, }: KnowledgePlanProgressResult & ConsoleUrl) => void;
+export declare const renderKnowledgePlanSet: (_services: unknown, { ok, path, problems, schema, consoleUrl, }: KnowledgePlanSetResult & ConsoleUrl) => void;
 export declare const renderKnowledgePlanDefer: (_services: unknown, { ok, message }: KnowledgePlanDeferResult) => void;
 /**
  * What to do next, and — when only a person can settle it — the question to put to
@@ -17,3 +20,4 @@ export declare const renderKnowledgePlanDefer: (_services: unknown, { ok, messag
  * better reads the same answer as JSON.
  */
 export declare const renderKnowledgeReconcile: (_services: unknown, { kind, reason, note, hold, notes, question, required, satisfied, }: KnowledgeReconcileResult) => void;
+export {};

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

@@ -82,10 +82,14 @@ export const renderKnowledgeIndex = (_services, { ok, check, files }) => {
             process.exitCode = 1;
     }
 };
+const printConsoleUrl = (url) => {
+    if (url)
+        console.log(`${dim('see it in the console:')} ${url}`);
+};
 export const renderKnowledgePlanSchema = (_services, { schema }) => {
     console.log(schema);
 };
-export const renderKnowledgePlanShow = (_services, { ok, path, body }) => {
+export const renderKnowledgePlanShow = (_services, { ok, path, body, consoleUrl }) => {
     if (!ok) {
         console.log(`${removed('✗')}  ${body}`);
         process.exitCode = 1;
@@ -93,6 +97,7 @@ export const renderKnowledgePlanShow = (_services, { ok, path, body }) => {
     }
     console.log(dim(path));
     console.log(body);
+    printConsoleUrl(consoleUrl);
 };
 const list = (label, entries, colour) => {
     if (entries.length === 0)
@@ -102,13 +107,14 @@ const list = (label, entries, colour) => {
         console.log(`   ${entry}`);
     console.log();
 };
-export const renderKnowledgePlanProgress = (_services, { ok, path, message, done, missing, deferred, problems, }) => {
+export const renderKnowledgePlanProgress = (_services, { ok, path, message, done, missing, deferred, problems, consoleUrl, }) => {
     if (message) {
         console.log(`${removed('✗')}  ${message}`);
         process.exitCode = 1;
         return;
     }
     console.log(dim(path));
+    printConsoleUrl(consoleUrl);
     console.log();
     list('DONE', done, added);
     list('MISSING', missing, removed);
@@ -134,10 +140,11 @@ export const renderKnowledgePlanProgress = (_services, { ok, path, message, done
     // and not only by whoever is reading the output.
     process.exitCode = 1;
 };
-export const renderKnowledgePlanSet = (_services, { ok, path, problems, schema }) => {
+export const renderKnowledgePlanSet = (_services, { ok, path, problems, schema, consoleUrl, }) => {
     if (ok) {
         console.log(`${added('✓')}  plan written to ${path}`);
         console.log(dim('the build is measured against it'));
+        printConsoleUrl(consoleUrl);
         return;
     }
     console.log(`${removed('✗')}  not written:`);

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

@@ -64,6 +64,7 @@ export declare const KnowledgePlanProgressOutputSchema: import("zod").ZodObject<
     missing: import("zod").ZodArray<import("zod").ZodString>;
     deferred: import("zod").ZodArray<import("zod").ZodString>;
     problems: import("zod").ZodArray<import("zod").ZodString>;
+    consoleUrl: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$strip>;
 export declare const KnowledgePlanShowInputSchema: import("zod").ZodObject<{
     milestone: import("zod").ZodString;
@@ -73,6 +74,7 @@ export declare const KnowledgePlanShowOutputSchema: import("zod").ZodObject<{
     ok: import("zod").ZodBoolean;
     path: import("zod").ZodString;
     body: import("zod").ZodString;
+    consoleUrl: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$strip>;
 export declare const KnowledgePlanSetInputSchema: import("zod").ZodObject<{
     milestone: import("zod").ZodString;
@@ -83,6 +85,7 @@ export declare const KnowledgePlanSetOutputSchema: import("zod").ZodObject<{
     path: import("zod").ZodString;
     problems: import("zod").ZodArray<import("zod").ZodString>;
     schema: import("zod").ZodOptional<import("zod").ZodString>;
+    consoleUrl: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$strip>;
 export declare const KnowledgePlanDeferInputSchema: import("zod").ZodObject<{
     milestone: import("zod").ZodString;

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

@@ -1,4 +1,5 @@
 import { KnowledgeIndexInput, KnowledgeIndexOutput, KnowledgePlanDeferInput, KnowledgePlanDeferOutput, KnowledgePlanProgressInput, KnowledgePlanProgressOutput, KnowledgePlanSchemaInput, KnowledgePlanSchemaOutput, KnowledgePlanSetInput, KnowledgePlanSetOutput, KnowledgePlanShowInput, KnowledgePlanShowOutput, KnowledgeReconcileInput, KnowledgeReconcileOutput, KnowledgeValidateInput, KnowledgeValidateOutput, } from '@pikku/knowledge';
+import { ConsoleUrlOutput } from './console-url.js';
 /**
  * The knowledge command schemas, re-bound to variables declared HERE rather than
  * imported straight into the command files.
@@ -26,11 +27,11 @@ export const KnowledgeValidateOutputSchema = KnowledgeValidateOutput;
 export const KnowledgePlanSchemaInputSchema = KnowledgePlanSchemaInput;
 export const KnowledgePlanSchemaOutputSchema = KnowledgePlanSchemaOutput;
 export const KnowledgePlanProgressInputSchema = KnowledgePlanProgressInput;
-export const KnowledgePlanProgressOutputSchema = KnowledgePlanProgressOutput;
+export const KnowledgePlanProgressOutputSchema = KnowledgePlanProgressOutput.extend(ConsoleUrlOutput.shape);
 export const KnowledgePlanShowInputSchema = KnowledgePlanShowInput;
-export const KnowledgePlanShowOutputSchema = KnowledgePlanShowOutput;
+export const KnowledgePlanShowOutputSchema = KnowledgePlanShowOutput.extend(ConsoleUrlOutput.shape);
 export const KnowledgePlanSetInputSchema = KnowledgePlanSetInput;
-export const KnowledgePlanSetOutputSchema = KnowledgePlanSetOutput;
+export const KnowledgePlanSetOutputSchema = KnowledgePlanSetOutput.extend(ConsoleUrlOutput.shape);
 export const KnowledgePlanDeferInputSchema = KnowledgePlanDeferInput;
 export const KnowledgePlanDeferOutputSchema = KnowledgePlanDeferOutput;
 export const KnowledgeReconcileInputSchema = KnowledgeReconcileInput;

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;