@pikku/cli 0.12.126 → 0.12.127

package/dist/src/fabric/lib/finding.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import type { ReportEnvironment } from './report-environment.js';
+export declare const FindingInput: z.ZodObject<{
+    title: z.ZodString;
+    kind: z.ZodEnum<{
+        product: "product";
+        harness: "harness";
+    }>;
+    model: z.ZodString;
+    expected: z.ZodString;
+    actual: z.ZodString;
+    skill: z.ZodOptional<z.ZodString>;
+    passage: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    repro: z.ZodOptional<z.ZodString>;
+    workaround: z.ZodOptional<z.ZodString>;
+    proposal: z.ZodOptional<z.ZodString>;
+    tried: z.ZodOptional<z.ZodString>;
+    unresolved: z.ZodOptional<z.ZodBoolean>;
+    area: z.ZodOptional<z.ZodString>;
+    surface: z.ZodOptional<z.ZodEnum<{
+        local: "local";
+        deployed: "deployed";
+        both: "both";
+    }>>;
+    cost: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodString>;
+    deployTarget: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FindingInput = z.infer<typeof FindingInput>;
+export type ParsedFinding = {
+    finding: FindingInput;
+} | {
+    problems: string[];
+};
+/** Shape-check a finding from either path, naming every field that is wrong. */
+export declare function parseFinding(value: unknown): ParsedFinding;
+/**
+ * A finding read as JSON rather than assembled out of flags.
+ *
+ * Half the fields are prose, and prose carries apostrophes, quotes, backticks
+ * and newlines — every one of them a shell metacharacter before it is a
+ * character in a sentence. An error message pasted into `--error` breaks the
+ * command at its first newline; one carrying a backtick runs whatever follows
+ * it. JSON has its own escaping, so this path has none of that.
+ *
+ * Returns the finding or the problems with it, never throws: a malformed
+ * payload is a usage mistake worth naming precisely.
+ */
+export declare function parseFindingJson(raw: string): ParsedFinding;
+export interface FindingPayload extends Omit<FindingInput, 'run'> {
+    runId?: string;
+    environment: ReportEnvironment;
+    reportedAt: string;
+}
+/**
+ * The rules the field set exists to enforce, checked before anything is sent.
+ *
+ * A usage mistake is the agent's own and is worth failing loudly for — unlike a
+ * failed send, which must never surface as a build failure. Every problem is
+ * returned at once so a malformed call is fixed in one pass.
+ */
+export declare function validateFinding(input: FindingInput): string[];
+export declare function buildFindingPayload(input: FindingInput, environment: ReportEnvironment, now?: Date): FindingPayload;
+/**
+ * Best-effort by construction. A finding is worth having and never worth
+ * failing a build for, so a refused, slow or unreachable endpoint is reported
+ * to the terminal and swallowed.
+ */
+export declare function postFinding(opts: {
+    apiUrl: string;
+    token: string;
+    /**
+     * Provenance, not a routing key. A finding is about the framework rather
+     * than about anyone's project, and the reports worth having most — a
+     * scaffold that never produced a config, a first run that went wrong — come
+     * from checkouts that have no project to name.
+     */
+    projectId: string | null;
+    payload: FindingPayload;
+    timeoutMs?: number;
+}): Promise<{
+    sent: boolean;
+    reason?: string;
+}>;
+/**
+ * The receipt. Nothing is written to disk, so the terminal is the only place
+ * the user sees what left their machine. Printed before the request goes out,
+ * so it is there whether or not the send succeeds.
+ */
+export declare function renderReceipt(payload: FindingPayload): string;

package/dist/src/fabric/lib/finding.js

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+export const FindingInput = z.object({
+    title: z.string(),
+    kind: z.enum(['product', 'harness']),
+    model: z.string(),
+    expected: z.string(),
+    actual: z.string(),
+    skill: z.string().optional(),
+    passage: z.string().optional(),
+    command: z.string().optional(),
+    error: z.string().optional(),
+    repro: z.string().optional(),
+    workaround: z.string().optional(),
+    proposal: z.string().optional(),
+    tried: z.string().optional(),
+    unresolved: z.boolean().optional(),
+    area: z.string().optional(),
+    surface: z.enum(['local', 'deployed', 'both']).optional(),
+    cost: z.string().optional(),
+    run: z.string().optional(),
+    deployTarget: z.string().optional(),
+});
+/** Shape-check a finding from either path, naming every field that is wrong. */
+export function parseFinding(value) {
+    const result = FindingInput.safeParse(value);
+    if (result.success)
+        return { finding: result.data };
+    return {
+        problems: result.error.issues.map((issue) => `${issue.path.join('.') || 'finding'}: ${issue.message}`),
+    };
+}
+/**
+ * A finding read as JSON rather than assembled out of flags.
+ *
+ * Half the fields are prose, and prose carries apostrophes, quotes, backticks
+ * and newlines — every one of them a shell metacharacter before it is a
+ * character in a sentence. An error message pasted into `--error` breaks the
+ * command at its first newline; one carrying a backtick runs whatever follows
+ * it. JSON has its own escaping, so this path has none of that.
+ *
+ * Returns the finding or the problems with it, never throws: a malformed
+ * payload is a usage mistake worth naming precisely.
+ */
+export function parseFindingJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            problems: [`--stdin expected a JSON object (${error.message}).`],
+        };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { problems: ['--stdin expected a JSON object.'] };
+    }
+    return parseFinding(parsed);
+}
+/**
+ * The rules the field set exists to enforce, checked before anything is sent.
+ *
+ * A usage mistake is the agent's own and is worth failing loudly for — unlike a
+ * failed send, which must never surface as a build failure. Every problem is
+ * returned at once so a malformed call is fixed in one pass.
+ */
+export function validateFinding(input) {
+    const problems = [];
+    if (input.kind === 'harness' && !input.skill) {
+        problems.push('A harness finding names the skill that misled you — pass --skill (and --passage for the line it contradicts).');
+    }
+    if (input.unresolved) {
+        if (!input.tried) {
+            problems.push('An unresolved finding carries what you tried and how each attempt failed — pass --tried.');
+        }
+        if (input.workaround) {
+            problems.push('Unresolved means no workaround was found. Drop --unresolved, or drop --workaround.');
+        }
+    }
+    else if (!input.workaround && !input.proposal) {
+        problems.push('A resolved finding carries the workaround you used — pass --workaround, or --unresolved if there was none.');
+    }
+    return problems;
+}
+export function buildFindingPayload(input, environment, now = new Date()) {
+    const { run, ...rest } = input;
+    return { ...rest, runId: run, environment, reportedAt: now.toISOString() };
+}
+/**
+ * Best-effort by construction. A finding is worth having and never worth
+ * failing a build for, so a refused, slow or unreachable endpoint is reported
+ * to the terminal and swallowed.
+ */
+export async function postFinding(opts) {
+    try {
+        const response = await fetch(`${opts.apiUrl}/findings`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${opts.token}`,
+            },
+            body: JSON.stringify({
+                projectId: opts.projectId,
+                finding: opts.payload,
+            }),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
+        });
+        if (!response.ok) {
+            return { sent: false, reason: `fabric answered ${response.status}` };
+        }
+        return { sent: true };
+    }
+    catch (error) {
+        return { sent: false, reason: error?.message ?? 'request failed' };
+    }
+}
+/**
+ * The receipt. Nothing is written to disk, so the terminal is the only place
+ * the user sees what left their machine. Printed before the request goes out,
+ * so it is there whether or not the send succeeds.
+ */
+export function renderReceipt(payload) {
+    const lines = [`[fabric] reporting: ${payload.title}`];
+    const field = (label, value) => {
+        if (value)
+            lines.push(`  ${label}: ${value}`);
+    };
+    field('kind', payload.unresolved ? `${payload.kind} (unresolved)` : payload.kind);
+    field('area', payload.area);
+    field('skill', payload.passage ? `${payload.skill} — ${payload.passage}` : payload.skill);
+    field('command', payload.command);
+    field('expected', payload.expected);
+    field('actual', payload.actual);
+    field('error', payload.error);
+    field('surface', payload.surface);
+    field('cost', payload.cost);
+    field('repro', payload.repro);
+    field('workaround', payload.workaround);
+    field('tried', payload.tried);
+    field('proposal', payload.proposal);
+    field('model', payload.model);
+    field('run', payload.runId);
+    field('deploy target', payload.deployTarget);
+    field('reported at', payload.reportedAt);
+    const env = payload.environment;
+    field('versions', env.packages
+        .map((p) => `${p.name}@${p.version}${p.linked ? ' (linked)' : ''}`)
+        .join(' ') || 'no @pikku/* found');
+    if (env.versionSkew) {
+        lines.push('  note: the installed @pikku/* versions are not all the same');
+    }
+    if (env.linkedFramework) {
+        lines.push('  note: an @pikku/* resolves to a workspace or link — this app is running framework code that may be modified');
+    }
+    field('runtime', `node ${env.node} ${env.platform} ${env.packageManager ?? ''}`.trim());
+    return lines.join('\n');
+}

package/dist/src/fabric/lib/report-environment.d.ts

@@ -0,0 +1,53 @@
+/** One installed `@pikku/*` package as it actually resolves on disk. */
+export interface PikkuPackageVersion {
+    name: string;
+    version: string;
+    /**
+     * Resolved through a symlink — a yarn workspace or a `yarn link`ed checkout
+     * rather than a published tarball. The framework is read-only during a build
+     * run, so a linked package is code that may already have been modified, and a
+     * finding describing it is describing something other than a release.
+     */
+    linked: boolean;
+}
+export interface ReportEnvironment {
+    packages: PikkuPackageVersion[];
+    /**
+     * The resolved `@pikku/*` versions are not all the same. Pinning the CLI does
+     * not pin its `@pikku/*` dependencies, so a mixed tree is a common cause of
+     * behaviour that looks like a framework bug.
+     */
+    versionSkew: boolean;
+    /** Any package is `linked` — see {@link PikkuPackageVersion.linked}. */
+    linkedFramework: boolean;
+    node: string;
+    packageManager: string | null;
+    platform: string;
+}
+/**
+ * Walk up from `startDir` for the first `node_modules/@pikku` that holds
+ * packages. A monorepo hoists to the root, an app installs locally, and either
+ * way the nearest populated scope is the one that was loaded.
+ *
+ * Populated means holding something `readPikkuPackages` would read, so the
+ * hidden entries it skips cannot qualify a scope either: a stray `.DS_Store` in
+ * an empty nested scope would otherwise end the walk there and report a tree
+ * with no packages in it.
+ */
+export declare function findPikkuScope(startDir: string): Promise<string | null>;
+/**
+ * Versions read off the installed tree rather than out of `package.json`. A
+ * range like `^0.12.35` says nothing about what ran, and the version that ran
+ * is the only one worth reporting.
+ */
+export declare function readPikkuPackages(scopeDir: string): Promise<PikkuPackageVersion[]>;
+/**
+ * `packageManager` in the nearest manifest is authoritative when it is set;
+ * otherwise the lockfile is the only evidence of what installed the tree.
+ */
+export declare function detectPackageManager(startDir: string): Promise<string | null>;
+/**
+ * Everything about the run a finding needs and no agent should be asked for.
+ * All of it is a directory read — no network, no prompting.
+ */
+export declare function collectReportEnvironment(startDir?: string): Promise<ReportEnvironment>;

package/dist/src/fabric/lib/report-environment.js

@@ -0,0 +1,119 @@
+import { readFile, lstat, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Walk up from `startDir` for the first `node_modules/@pikku` that holds
+ * packages. A monorepo hoists to the root, an app installs locally, and either
+ * way the nearest populated scope is the one that was loaded.
+ *
+ * Populated means holding something `readPikkuPackages` would read, so the
+ * hidden entries it skips cannot qualify a scope either: a stray `.DS_Store` in
+ * an empty nested scope would otherwise end the walk there and report a tree
+ * with no packages in it.
+ */
+export async function findPikkuScope(startDir) {
+    let dir = startDir;
+    while (true) {
+        const candidate = join(dir, 'node_modules', '@pikku');
+        if (existsSync(candidate)) {
+            const entries = await readdir(candidate).catch(() => []);
+            if (entries.some((entry) => !entry.startsWith('.')))
+                return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Versions read off the installed tree rather than out of `package.json`. A
+ * range like `^0.12.35` says nothing about what ran, and the version that ran
+ * is the only one worth reporting.
+ */
+export async function readPikkuPackages(scopeDir) {
+    const entries = await readdir(scopeDir).catch(() => []);
+    const packages = [];
+    for (const entry of entries.sort()) {
+        if (entry.startsWith('.'))
+            continue;
+        const packageDir = join(scopeDir, entry);
+        const manifest = join(packageDir, 'package.json');
+        const raw = await readFile(manifest, 'utf8').catch(() => null);
+        if (!raw)
+            continue;
+        let version;
+        try {
+            version = JSON.parse(raw).version;
+        }
+        catch {
+            continue;
+        }
+        if (typeof version !== 'string')
+            continue;
+        const stats = await lstat(packageDir).catch(() => null);
+        packages.push({
+            name: `@pikku/${entry}`,
+            version,
+            linked: stats?.isSymbolicLink() ?? false,
+        });
+    }
+    return packages;
+}
+const LOCKFILES = [
+    ['yarn.lock', 'yarn'],
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['package-lock.json', 'npm'],
+];
+/**
+ * `packageManager` in the nearest manifest is authoritative when it is set;
+ * otherwise the lockfile is the only evidence of what installed the tree.
+ */
+export async function detectPackageManager(startDir) {
+    let dir = startDir;
+    while (true) {
+        const manifest = join(dir, 'package.json');
+        if (existsSync(manifest)) {
+            const raw = await readFile(manifest, 'utf8').catch(() => null);
+            if (raw) {
+                try {
+                    const declared = JSON.parse(raw)
+                        .packageManager;
+                    if (typeof declared === 'string' && declared.length > 0) {
+                        return declared;
+                    }
+                }
+                catch {
+                    // An unparseable manifest tells us nothing; keep walking up.
+                }
+            }
+        }
+        for (const [lockfile, manager] of LOCKFILES) {
+            if (existsSync(join(dir, lockfile)))
+                return manager;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Everything about the run a finding needs and no agent should be asked for.
+ * All of it is a directory read — no network, no prompting.
+ */
+export async function collectReportEnvironment(startDir = process.cwd()) {
+    const scope = await findPikkuScope(startDir);
+    const packages = scope ? await readPikkuPackages(scope) : [];
+    const versions = new Set(packages.map((p) => p.version));
+    return {
+        packages,
+        versionSkew: versions.size > 1,
+        linkedFramework: packages.some((p) => p.linked),
+        node: process.version,
+        packageManager: await detectPackageManager(startDir),
+        platform: `${process.platform}-${process.arch}`,
+    };
+}

package/dist/src/functions/commands/environment.d.ts

@@ -11,6 +11,11 @@
 export interface PikkuEnvironment {
     apiUrl: string;
     signInPath?: string;
+    /**
+     * Where the session and its roles are read back, for a stage that reports
+     * them somewhere other than `get-session` under the sign-in path's own mount.
+     */
+    sessionPath?: string;
     rpcPath?: string;
     appUrl?: string;
     /**

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

@@ -115,6 +115,7 @@ export const personaRun = pikkuSessionlessFunc({
             ...credentials,
             personas,
             signInPath: env.signInPath,
+            sessionPath: env.sessionPath,
             rpcPath: env.rpcPath,
             model: resolvedModel,
         });

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

@@ -176,6 +176,7 @@ export const scenarioRun = pikkuSessionlessFunc({
             ...credentials,
             personas: scenarioActors,
             signInPath: env.signInPath,
+            sessionPath: env.sessionPath,
             rpcPath: env.rpcPath,
             model: config.scenarios?.model,
         });

package/dist/src/functions/validate/auth-plugin-checks.d.ts

@@ -10,7 +10,7 @@ export type AuthPluginCheckConfig = {
  * running two authorization models and projecting one onto the other. The
  * inspector refuses it outright at prebuild; this reports the same thing
  * without one, and additionally catches the quieter half of the migration, an
- * app that dropped `admin()` and never wired `ban()`, which keeps its ban
+ * app that dropped `admin()` and never wired `pikkuBan()`, which keeps its ban
  * columns and its ban UI while silently enforcing nothing.
  */
 export declare const runAuthPluginChecks: (root: string, config: AuthPluginCheckConfig | null) => Promise<ValidateFinding[]>;

package/dist/src/functions/validate/auth-plugin-checks.js

@@ -113,7 +113,7 @@ const configuresPlugin = (text, module, exported) => {
  * running two authorization models and projecting one onto the other. The
  * inspector refuses it outright at prebuild; this reports the same thing
  * without one, and additionally catches the quieter half of the migration, an
- * app that dropped `admin()` and never wired `ban()`, which keeps its ban
+ * app that dropped `admin()` and never wired `pikkuBan()`, which keeps its ban
  * columns and its ban UI while silently enforcing nothing.
  */
 export const runAuthPluginChecks = async (root, config) => {
@@ -131,7 +131,10 @@ export const runAuthPluginChecks = async (root, config) => {
             continue;
         if (configuresPlugin(text, 'better-auth/plugins', 'admin'))
             adminFiles.push(file);
-        if (configuresPlugin(text, '@pikku/better-auth', 'ban'))
+        // `pikkuBan` is the current export; `ban` is the deprecated alias, which
+        // configures exactly the same plugin and so must satisfy the check too.
+        if (configuresPlugin(text, '@pikku/better-auth', 'pikkuBan') ||
+            configuresPlugin(text, '@pikku/better-auth', 'ban'))
             bansAnywhere = true;
     }
     for (const file of adminFiles) {
@@ -140,7 +143,7 @@ export const runAuthPluginChecks = async (root, config) => {
             severity: 'error',
             message: "better-auth's admin() plugin is not supported — it authorizes against a user.role column while pikku authorizes on scopes, so one has to be projected onto the other",
             path: file,
-            fixHint: lines('Replace it with ban(), which keeps the one capability admin() had that', 'pikku cannot supply from outside better-auth — refusing a banned user a', 'session:', "  import { ban } from '@pikku/better-auth'", '  betterAuth({ plugins: [ban()] })', 'User management is already scoped RPCs in @pikku/addon-admin: list,', 'create, ban, remove, revoke sessions and set password.'),
+            fixHint: lines('Replace it with pikkuBan(), which keeps the one capability admin() had', 'that pikku cannot supply from outside better-auth — refusing a banned', 'user a session:', "  import { pikkuBan } from '@pikku/better-auth'", '  betterAuth({ plugins: [pikkuBan()] })', 'User management is already scoped RPCs in @pikku/addon-admin: list,', 'create, ban, remove, revoke sessions and set password.'),
         });
     }
     if (!bansAnywhere && adminFiles.length === 0) {
@@ -153,9 +156,9 @@ export const runAuthPluginChecks = async (root, config) => {
                 findings.push({
                     id: 'better-auth-no-ban-plugin',
                     severity: 'warn',
-                    message: 'better-auth is configured without ban() — the banned/banReason/banExpires columns do not exist, so banning a user through @pikku/addon-admin has nothing to write and nothing refuses their next sign-in',
+                    message: 'better-auth is configured without pikkuBan() — the banned/banReason/banExpires columns do not exist, so banning a user through @pikku/addon-admin has nothing to write and nothing refuses their next sign-in',
                     path: file,
-                    fixHint: lines("  import { ban } from '@pikku/better-auth'", '  betterAuth({ plugins: [ban()] })', 'Wire it wherever the rest of your plugins are, then run', '`pikku db migrate` to add the columns.'),
+                    fixHint: lines("  import { pikkuBan } from '@pikku/better-auth'", '  betterAuth({ plugins: [pikkuBan()] })', 'Wire it wherever the rest of your plugins are, then run', '`pikku db migrate` to add the columns.'),
                 });
                 break;
             }

package/dist/src/functions/validate/persona-checks.js

@@ -81,17 +81,19 @@ const countPersonas = async (root, config, sourceFiles) => {
 /**
  * Whether a persona can actually sign in.
  *
- * Two shapes count. `actor()` from `@pikku/better-auth` is the one the scaffold
- * wires, and a hand-rolled `/sign-in/actor` route is the one a project that does
- * not use better-auth ends up with. Both terminate at the same endpoint, so
- * either satisfies the check.
+ * Two shapes count. `pikkuActor()` from `@pikku/better-auth` is the one the
+ * scaffold wires, and a hand-rolled `/sign-in/actor` route is the one a project
+ * that does not use better-auth ends up with. Both terminate at the same
+ * endpoint, so either satisfies the check. The deprecated `actor()` alias is
+ * matched too — it is the same plugin under its old name.
  */
 const hasActorSignIn = async (sourceFiles) => {
     for (const file of sourceFiles) {
         const text = await readTextSafe(file);
         if (!text)
             continue;
-        const wiresPlugin = /@pikku\/better-auth/.test(text) && /\bactor\s*\(/.test(text);
+        const wiresPlugin = /@pikku\/better-auth/.test(text) &&
+            /(^|[^\w$.])(pikkuActor|actor)\s*\(/.test(text);
         if (wiresPlugin || /sign-in\/actor/.test(text))
             return true;
     }
@@ -123,7 +125,7 @@ export const runPersonaChecks = async (root, config) => {
         return findings;
     }
     if (!(await hasActorSignIn(sourceFiles))) {
-        w('personas-no-actor-sign-in', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but nothing wires actor sign-in — a scenario run signs in over POST /auth/sign-in/actor, so every persona fails to acquire a session`, pikkuConfigPath, lines('Wire the actor plugin where better-auth is configured:', "  import { actor } from '@pikku/better-auth'", '  plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]', '`pikku dev` turns the endpoint on and mints the secret itself, so there', 'is nothing to configure locally. A deployed stage that must run', 'scenarios opts in with', 'PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in; everywhere else', 'the endpoint stays off whatever the environment happens to contain.'));
+        w('personas-no-actor-sign-in', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but nothing wires actor sign-in — a scenario run signs in over POST /auth/sign-in/actor, so every persona fails to acquire a session`, pikkuConfigPath, lines('Wire the actor plugin where better-auth is configured:', "  import { pikkuActor } from '@pikku/better-auth'", '  plugins: [pikkuActor({ secret: SCENARIO_ACTOR_SECRET })]', '`pikku dev` turns the endpoint on and mints the secret itself, so there', 'is nothing to configure locally. A deployed stage that must run', 'scenarios opts in with', 'PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in; everywhere else', 'the endpoint stays off whatever the environment happens to contain.'));
     }
     const environments = config?.environments;
     const hasEnvironment = typeof environments === 'object' &&

package/dist/src/functions/wirings/user-admin/pikku-command-user-admin-functions.js

@@ -28,12 +28,17 @@ export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
         // Ban is the one capability with a schema requirement of its own, and it is
         // only one of the six — a warning rather than a failure, so an app that
         // never bans anyone is not forced to carry the columns.
-        if (!definition.plugins.includes('ban')) {
-            logger.warn(`"scaffold.userAdmin" is enabled but better-auth is configured without the ban() plugin, ` +
+        // The plugin ids here are the callee names read off the `plugins: [...]`
+        // array, so both the current `pikkuBan()` and the deprecated `ban()` alias
+        // have to count as wired.
+        const bansUsers = definition.plugins.includes('pikkuBan') ||
+            definition.plugins.includes('ban');
+        if (!bansUsers) {
+            logger.warn(`"scaffold.userAdmin" is enabled but better-auth is configured without the pikkuBan() plugin, ` +
                 `so the banned/banReason/banExpires columns do not exist and setUserBanned will fail.\n` +
-                `Fix: add ban() to the plugins array in ${definition.sourceFile}:\n` +
-                `  import { ban } from '@pikku/better-auth'\n` +
-                `  betterAuth({ plugins: [ban()] })`);
+                `Fix: add pikkuBan() to the plugins array in ${definition.sourceFile}:\n` +
+                `  import { pikkuBan } from '@pikku/better-auth'\n` +
+                `  betterAuth({ plugins: [pikkuBan()] })`);
         }
         const leaf = (name) => getLeafImportPath(config.userAdminFunctionsFile, name, config);
         const { schemas, functions } = serializeUserAdminFunctions(leaf);

package/dist/src/functions/wirings/user-admin/serialize-user-admin-functions.d.ts

@@ -13,7 +13,7 @@ export interface UserAdminGenOutput {
  * codegen on conflicting declarations.
  *
  * Each function is gated on its own `admin:users:*` scope, and works through
- * better-auth's internal adapter. Banning additionally needs the `ban()` plugin
+ * better-auth's internal adapter. Banning additionally needs the `pikkuBan()` plugin
  * from `@pikku/better-auth` for the columns it writes to exist.
  *
  * Emitted as two files. The schemas are zod, and the inspector reads a zod

package/dist/src/functions/wirings/user-admin/serialize-user-admin-functions.js

@@ -9,7 +9,7 @@
  * codegen on conflicting declarations.
  *
  * Each function is gated on its own `admin:users:*` scope, and works through
- * better-auth's internal adapter. Banning additionally needs the `ban()` plugin
+ * better-auth's internal adapter. Banning additionally needs the `pikkuBan()` plugin
  * from `@pikku/better-auth` for the columns it writes to exist.
  *
  * Emitted as two files. The schemas are zod, and the inspector reads a zod
@@ -27,7 +27,7 @@ import { z } from 'zod'
 
 /**
  * A user, as the directory sees one. Ban state is optional because those
- * columns belong to the \`ban()\` plugin: a host without it reports no ban state
+ * columns belong to the \`pikkuBan()\` plugin: a host without it reports no ban state
  * at all, which a client can render as "unknown" rather than as a misleading
  * "not banned".
  */
@@ -224,7 +224,7 @@ export const pikkuAdminSetUserBanned = pikkuFunc({
   tags: ['pikku'],
   title: 'Ban or Unban User',
   description:
-    'Bans a user — revoking their sessions and blocking sign-in — or lifts an existing ban. An expiry lets the ban lapse on its own; without one it holds until it is lifted. Requires better-auth wired with the \`ban()\` plugin.',
+    'Bans a user — revoking their sessions and blocking sign-in — or lifts an existing ban. An expiry lets the ban lapse on its own; without one it holds until it is lifted. Requires better-auth wired with the \`pikkuBan()\` plugin.',
   expose: true,
   scopes: ['admin:users:ban'],
   input: SetUserBannedInput,

package/dist/src/services.js

@@ -71,12 +71,21 @@ export const defaultCLIRenderer = pikkuCLIRender((_services, data) => {
  * `skills install` writes agent skills into a repo that has no pikku.config.json
  * yet — that is the whole point of it — so it cannot require one to start, and
  * `doc` answers from the surface shipped inside the CLI rather than the project.
+ * `fabric report` files a finding about pikku itself: a scaffold that never
+ * produced a config, or a command run from the wrong directory, is exactly the
+ * kind of thing worth reporting, so demanding a config would refuse the finding
+ * at the moment it is most worth having.
  */
 const CONFIG_FREE_COMMANDS = new Set([
     'skills',
     'skills.list',
     'skills.install',
     'doc',
+    'fabric.report',
+    'fabric.findings',
+    'fabric.findings.list',
+    'fabric.findings.flush',
+    'fabric.findings.clear',
 ]);
 export const createConfig = async (_variablesService, data, commandPath = []) => {
     // Determine log level based on CLI flags with precedence: