@pikku/cli 0.12.100 → 0.12.102

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

@@ -13,6 +13,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    screenshots?: boolean;
+    video?: boolean;
     apiUrl?: string;
     appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
@@ -28,6 +30,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    screenshots?: boolean;
+    video?: boolean;
     apiUrl?: string;
     appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<{
@@ -43,6 +47,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    screenshots?: boolean;
+    video?: boolean;
     apiUrl?: string;
     appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

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

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { resolve, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku';
@@ -87,7 +88,7 @@ export const scenarioList = pikkuSessionlessFunc({
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, screenshots = false, video = false, apiUrl, appUrl, }) => {
         if (!SCENARIO_SURFACES.includes(runSurface)) {
             throw new Error(`Unknown --run surface '${runSurface}'. Expected one of: ${SCENARIO_SURFACES.join(', ')}.`);
         }
@@ -285,6 +286,17 @@ export const scenarioRun = pikkuSessionlessFunc({
         const needsBrowser = effectiveSurface === 'browser' &&
             groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
         const failureDir = join(resolve(config.rootDir, config.outDir), 'scenario-failures');
+        // Artifacts are filed under the run, not the scenario, so one run's output
+        // is one folder to open, keep or delete. `--video` implies capture is on:
+        // recording without somewhere to put it is not a thing anyone wants.
+        const captureDir = join(resolve(config.rootDir, config.outDir), 'scenario-runs');
+        // One id for the whole invocation, distinct from a scenario's own runId:
+        // reviewing artifacts means opening what `pikku scenario run` just produced,
+        // not hunting for one scenario's folder among many.
+        const captureRunId = randomUUID();
+        const capture = screenshots || video
+            ? { dir: captureDir, runId: captureRunId, video, compress: true }
+            : undefined;
         const browserLifecycle = scenarioBrowserLifecycle(needsBrowser
             ? await (async () => {
                 const provider = await resolveScenarioBrowserProvider({
@@ -295,6 +307,7 @@ export const scenarioRun = pikkuSessionlessFunc({
                     actors: scenarioActors,
                     signInPath: env.signInPath,
                     failureDir,
+                    capture,
                     browserScenarios: [...browserStepsByFlow.keys()],
                     driver: config.scenarios?.browserDriver,
                 });
@@ -353,10 +366,9 @@ export const scenarioRun = pikkuSessionlessFunc({
          * scenario body gets, the CLI's own singletons included, and its result is
          * discarded.
          *
-         * The context is *feature*-scoped: `before` and `after` of one feature share
-         * it, so setup can hand teardown the ids it created. It is deliberately not
-         * the context the scenarios in the group see — sharing one bag across a
-         * group is the invisible coupling a Cucumber world had.
+         * Its context is *feature*-scoped — shared by that feature's `before` and
+         * `after`, and deliberately not the context the group's scenarios see:
+         * one bag across a group is the invisible coupling a Cucumber world had.
          */
         const singletonServices = pikkuState(null, 'package', 'singletonServices');
         const runFeatureHook = async (hook, context) => {
@@ -371,6 +383,9 @@ export const scenarioRun = pikkuSessionlessFunc({
             // Before the scenario, not after it: the last scenario's window is left
             // open for headed debugging, while this one still starts clean.
             await browserLifecycle.reset();
+            // After the reset, which is what closes the previous scenario's context
+            // and finalises its video.
+            browserLifecycle.beginScenario(label);
             if (coverageActive) {
                 const reset = await invokeCoverage('pikkuScenarioResetLiveCoverage');
                 if (reset && reset.enabled === false) {
@@ -495,6 +510,12 @@ export const scenarioRun = pikkuSessionlessFunc({
             }
         }
         await browserLifecycle.close();
+        // Reported after the browser has closed, because video is only finalised
+        // when its context is. A capture nobody can find is a capture nobody
+        // looks at, and looking at them is the entire point of the flags.
+        if (capture) {
+            logger.info(`Captures → ${join(capture.dir, capture.runId)}`);
+        }
         if (coverage && Object.keys(scenarioCoverage).length > 0) {
             const coverageDir = join(resolve(config.rootDir, config.outDir), 'coverage');
             mkdirSync(coverageDir, { recursive: true });

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

@@ -1,10 +1,13 @@
 export declare const serve: import("#pikku").PikkuFunctionConfig<{
     port?: string;
     console?: boolean;
+    model?: string;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     port?: string;
     console?: boolean;
+    model?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<{
     port?: string;
     console?: boolean;
+    model?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

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

@@ -4,19 +4,24 @@ import { ConsoleLogger, LocalEmailService, InMemoryQueueService, InMemoryWorkflo
 import { KyselyAIStorageService, KyselyAIRunStateService, KyselyAgentRunService, } from '@pikku/kysely';
 import { stopSingletonServices } from '@pikku/core';
 import { pikkuState } from '@pikku/core/ecosystem';
+import { wireAIScorerQueueWorkers } from '@pikku/core/ai-scorer';
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 import { LocalContent, } from '@pikku/core/services/local-content';
 import { InMemorySchedulerService } from '@pikku/schedule';
 import { resolveDb, createKysely, parseDatabaseUrl, } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
+import { registerScenarioInstrumentation } from '../wirings/scenarios/register-scenario-instrumentation.js';
+import { resolveScaffoldFeature } from '../../utils/resolve-scaffold-feature.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
 import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
+import { applyModelAliasOverride } from '../../utils/model-alias-override.js';
 export const serve = pikkuSessionlessFunc({
     remote: true,
-    func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole }) => {
+    func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole, model }) => {
         process.env.PIKKU_DEV_QUICK_LOGIN ??= 'true';
+        applyModelAliasOverride(logger, model, config.models);
         const resolvedPort = parseInt(port || '3000', 10);
         const hostname = 'localhost';
         const bindHostname = '127.0.0.1';
@@ -28,6 +33,14 @@ export const serve = pikkuSessionlessFunc({
             return;
         }
         await loadUserBootstrap(pikkuDir);
+        // Scenario instrumentation exists only on a locally served project: the
+        // runner calls it over RPC to reset and snapshot coverage and stub calls.
+        // It is registered here, after the app bootstrap, rather than generated
+        // into the project — an app bootstrap is what a deployed bundle imports,
+        // and coverage endpoints have no business in one.
+        if (config.scaffold?.scenarios) {
+            registerScenarioInstrumentation(resolveScaffoldFeature('scenarios', config.scaffold.scenarios).auth);
+        }
         const workflowService = new InMemoryWorkflowService();
         const configModule = await loadUserModule(pikkuConfigFactory.file);
         const servicesModule = await loadUserModule(singletonServicesFactory.file);
@@ -115,6 +128,7 @@ export const serve = pikkuSessionlessFunc({
         };
         pikkuState(null, 'package', 'singletonServices', resolvedServices);
         resolvedServices.workflowService?.wireQueueWorkers?.();
+        wireAIScorerQueueWorkers();
         const { serverLifecycleFactory } = inspectorState.filesAndMethods;
         const loadLifecycle = async () => {
             if (!serverLifecycleFactory)

package/dist/src/functions/commands/{workspace-validate.d.ts → validate.d.ts}

@@ -1,7 +1,12 @@
-import { renderWorkspaceValidate } from '../validate/workspace-validate.js';
-export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Record<string, never>, {
+import { renderValidate } from '../validate/validate.js';
+export declare const validate: import("#pikku").PikkuFunctionConfig<Record<string, never>, {
     ok: boolean;
     root: string;
+    ran: {
+        checkId: string;
+        subject: string;
+        target: string;
+    }[];
     findings: {
         id: string;
         severity: "warn" | "error" | "info";
@@ -12,6 +17,11 @@ export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Rec
 }, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<Record<string, never>, {
     ok: boolean;
     root: string;
+    ran: {
+        checkId: string;
+        subject: string;
+        target: string;
+    }[];
     findings: {
         id: string;
         severity: "warn" | "error" | "info";
@@ -22,6 +32,11 @@ export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Rec
 }, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<Record<string, never>, {
     ok: boolean;
     root: string;
+    ran: {
+        checkId: string;
+        subject: string;
+        target: string;
+    }[];
     findings: {
         id: string;
         severity: "warn" | "error" | "info";
@@ -30,4 +45,4 @@ export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Rec
         fixHint: string;
     }[];
 }, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
-export { renderWorkspaceValidate };
+export { renderValidate };

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

@@ -0,0 +1,9 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { ValidateInput, ValidateOutput, renderValidate, runProjectValidate, } from '../validate/validate.js';
+export const validate = pikkuSessionlessFunc({
+    description: 'Check this project against every Pikku check that applies to it — app structure, and the published file set of any addon it contains. Prints what was checked, with fix hints for anything wrong.',
+    input: ValidateInput,
+    output: ValidateOutput,
+    func: async () => runProjectValidate(),
+});
+export { renderValidate };

package/dist/src/functions/db/local-db.d.ts

@@ -40,7 +40,7 @@ export interface ResolvedPostgresDb extends ResolvedDbBase {
     devSeedFile: string;
     /**
      * Postgres extensions the embedded PGlite databases must load, as declared by
-     * `pgliteExtensions` in the project's config. See
+     * `db.pgliteExtensions` in the project's pikku.config.json. See
      * {@link loadPGliteExtensions}.
      *
      * Carried even in `url` mode: the shadow database the CLI migrates and
@@ -72,6 +72,7 @@ export declare function parseDatabaseUrl(url: string): Pick<UserConfigShape, 'sq
 export declare function resolveDb(userConfig: UserConfigShape, rootDir: string, outDir: string, runtimeDir?: string, dbConfig?: {
     schema?: string;
     defaultSchema?: string;
+    pgliteExtensions?: string[];
 } | string): ResolvedDb | null;
 /** @deprecated Use resolveDb(userConfig, ...) instead. */
 export declare function resolveLocalDb(sqliteDb: string | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedSqliteDb | null;

package/dist/src/functions/db/local-db.js

@@ -68,7 +68,7 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir, dbConfig) {
     if (userConfig.postgresUrl && userConfig.sqliteDb) {
         throw new Error('Both postgresUrl and sqliteDb are set. Configure exactly one database dialect.');
     }
-    const pgliteExtensions = userConfig.pgliteExtensions ?? [];
+    const pgliteExtensions = (typeof dbConfig === 'string' ? undefined : dbConfig?.pgliteExtensions) ?? [];
     if (userConfig.postgresUrl) {
         return {
             dialect: 'postgres',
@@ -268,7 +268,7 @@ function explainMissingExtension(error, declared) {
     return new Error(`The embedded PGlite database has no '${name}' extension. ` +
         `The CLI migrates a PGlite shadow database to type and diff your schema, ` +
         `so every extension your migrations use has to be declared as ` +
-        `pgliteExtensions in createConfig — e.g. pgliteExtensions: ['${name}'] ` +
+        `db.pgliteExtensions in pikku.config.json — e.g. "db": { "pgliteExtensions": ["${name}"] } ` +
         `for a PGlite contrib extension, or the package that publishes it ` +
         `('@electric-sql/pglite-pgvector' for pgvector).` +
         (declared.length > 0

package/dist/src/functions/validate/addon-package-checks.d.ts

@@ -0,0 +1,26 @@
+import type { ValidateFinding as Finding } from './persona-checks.js';
+/**
+ * A package that publishes generated pikku output.
+ *
+ * The generated files carry relative imports to hand-written sources, so what
+ * the package ships and what it references have to agree — which is what the
+ * checks below are for.
+ *
+ * Having a `.pikku` directory is not enough on its own: an app's
+ * packages/functions has one too, and it is codegen output for that app rather
+ * than something anybody installs. The question is whether the package *ships*
+ * it, so the signal is a `files`/`exports` that carries it into the tarball.
+ * A private package is excluded for the same reason — nobody installs it, so
+ * its published file set is not a thing that can be wrong.
+ */
+export declare function isAddonPackage(pkgDir: string): Promise<boolean>;
+/**
+ * Every relative import in a shipped generated file must resolve to a file
+ * that is itself shipped.
+ *
+ * Stated as a property rather than as "the build script must copy types/",
+ * because the build script is not the only way to get this wrong and will not
+ * always be a `cp`. The generated files declare what they need; the check just
+ * holds the package to it.
+ */
+export declare function runAddonPackageChecks(pkgDir: string): Promise<Finding[]>;

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

@@ -0,0 +1,258 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { readJsonSafe, readTextSafe } from './shared-checks.js';
+/** Where the CLI writes generated output, both in source and once built. */
+const GENERATED_DIRS = ['.pikku', join('dist', '.pikku')];
+/** Roots that carry generated output into the tarball when listed in `files`. */
+const SHIPPING_ROOTS = new Set(['dist', '.pikku']);
+/**
+ * A package that publishes generated pikku output.
+ *
+ * The generated files carry relative imports to hand-written sources, so what
+ * the package ships and what it references have to agree — which is what the
+ * checks below are for.
+ *
+ * Having a `.pikku` directory is not enough on its own: an app's
+ * packages/functions has one too, and it is codegen output for that app rather
+ * than something anybody installs. The question is whether the package *ships*
+ * it, so the signal is a `files`/`exports` that carries it into the tarball.
+ * A private package is excluded for the same reason — nobody installs it, so
+ * its published file set is not a thing that can be wrong.
+ */
+export async function isAddonPackage(pkgDir) {
+    const pkg = await readJsonSafe(join(pkgDir, 'package.json'));
+    if (!pkg || pkg.private)
+        return false;
+    if (!GENERATED_DIRS.some((dir) => existsSync(join(pkgDir, dir))))
+        return false;
+    const shipsViaFiles = (pkg.files ?? []).some((entry) => SHIPPING_ROOTS.has(entry.replace(/^\.\//, '').split('/')[0]));
+    return shipsViaFiles || JSON.stringify(pkg.exports ?? null).includes('.pikku');
+}
+async function walk(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walk(path)));
+        else
+            out.push(path);
+    }
+    return out;
+}
+const IMPORT_RE = /(?:^|[\s(};])(?:from|import|require)\s*\(?\s*['"]([^'"]+)['"]/g;
+function relativeSpecifiers(source) {
+    const found = new Set();
+    for (const match of source.matchAll(IMPORT_RE)) {
+        const specifier = match[1];
+        if (specifier.startsWith('.'))
+            found.add(specifier);
+    }
+    return [...found];
+}
+/**
+ * The on-disk file a specifier names, under TypeScript's NodeNext rules.
+ *
+ * `./x.js` may be satisfied by `x.ts` or `x.d.ts`, and pikku's generated files
+ * import hand-written declarations as `./x.d.js` — the `.js` extension the
+ * compiler wants, on a file that only ever exists as `.d.ts`.
+ */
+function resolveCandidates(specifier, fromDir) {
+    const base = resolve(fromDir, specifier);
+    if (base.endsWith('.d.js'))
+        return [base.slice(0, -5) + '.d.ts'];
+    if (base.endsWith('.js')) {
+        const stem = base.slice(0, -3);
+        return [base, stem + '.ts', stem + '.d.ts', stem + '.tsx'];
+    }
+    // `.mjs` and `.cjs` are scanned as generated files, so they are also imported
+    // as one, and each has its own TypeScript twin rather than sharing `.ts`.
+    if (base.endsWith('.mjs') || base.endsWith('.cjs')) {
+        const stem = base.slice(0, -4);
+        const kind = base.slice(-3, -2);
+        return [base, `${stem}.${kind}ts`, `${stem}.d.${kind}ts`];
+    }
+    if (/\.(ts|tsx|json)$/.test(base))
+        return [base];
+    return [
+        base + '.ts',
+        base + '.d.ts',
+        base + '.js',
+        join(base, 'index.ts'),
+        join(base, 'index.d.ts'),
+        join(base, 'index.js'),
+    ];
+}
+/**
+ * The directory a `files` entry is rooted at.
+ *
+ * `dist`, `dist/`, `dist/**` and `dist/*` all publish the same tree, so the
+ * root is what decides both whether a path ships and whether the entry has
+ * anything behind it. Anything more elaborate than a trailing wildcard is left
+ * to npm.
+ */
+function packedRoot(entry) {
+    return entry
+        .replace(/^\.\//, '')
+        .replace(/\/\*+$/, '')
+        .replace(/\/$/, '');
+}
+/**
+ * Whether `files` carries this path into the published tarball.
+ *
+ * A package with no `files` publishes everything, so the question only has
+ * teeth when the field is present.
+ */
+function isPacked(absPath, pkgDir, files) {
+    if (!files)
+        return true;
+    const rel = relative(pkgDir, absPath);
+    if (rel.startsWith('..'))
+        return false;
+    return files.some((entry) => {
+        const normalized = packedRoot(entry);
+        return rel === normalized || rel.startsWith(normalized + sep);
+    });
+}
+/**
+ * Every `./…` target reachable through an `exports` or `imports` map, paired
+ * with the entry-point name that leads to it.
+ *
+ * Both fields nest arbitrarily deep — a subpath holds a condition object, which
+ * may hold another — so the walk collects strings rather than assuming a shape.
+ * A `*` is left in place: the wildcard's own directory is what has to ship.
+ */
+function entryPointTargets(map, name = '') {
+    if (typeof map === 'string') {
+        return map.startsWith('./') ? [{ name, target: map }] : [];
+    }
+    if (!map || typeof map !== 'object')
+        return [];
+    return Object.entries(map).flatMap(([key, value]) => entryPointTargets(value, name || key));
+}
+/**
+ * Every relative import in a shipped generated file must resolve to a file
+ * that is itself shipped.
+ *
+ * Stated as a property rather than as "the build script must copy types/",
+ * because the build script is not the only way to get this wrong and will not
+ * always be a `cp`. The generated files declare what they need; the check just
+ * holds the package to it.
+ */
+export async function runAddonPackageChecks(pkgDir) {
+    const findings = [];
+    const pkg = await readJsonSafe(join(pkgDir, 'package.json'));
+    if (!pkg)
+        return findings;
+    // `files` is the package's own statement of what it publishes, so an entry
+    // with nothing behind it means the build has not run — and validating the
+    // published file set of a package that has not been built proves nothing.
+    const absent = (pkg.files ?? []).filter((entry) => !existsSync(join(pkgDir, packedRoot(entry))));
+    if (absent.length > 0) {
+        findings.push({
+            id: 'addon-not-built',
+            severity: 'info',
+            message: `${pkg.name ?? relative(dirname(pkgDir), pkgDir)} lists ${absent.join(', ')} in "files" with nothing on disk — packaging was not verified because the package is not built`,
+            path: join(pkgDir, absent[0]),
+            fixHint: 'Run the package build first, then validate. In CI, `build && pikku validate` is the order that checks what actually publishes.',
+        });
+        return findings;
+    }
+    // The entry points are the package's promise about what can be reached from
+    // outside it, and nothing inside dist/.pikku mentions them — so the import
+    // walk below cannot see a `#pikku` that still points at the source tree.
+    for (const { name, target } of [
+        ...entryPointTargets(pkg.imports),
+        ...entryPointTargets(pkg.exports),
+    ]) {
+        const withoutWildcard = target.slice(2).split('*')[0];
+        if (!isPacked(join(pkgDir, withoutWildcard), pkgDir, pkg.files)) {
+            findings.push({
+                id: 'addon-entry-point-not-packed',
+                severity: 'error',
+                message: `"${name}" resolves to ${target}, which "files" does not publish — the entry point exists here and not for anyone who installs ${pkg.name ?? 'this addon'}`,
+                path: join(pkgDir, withoutWildcard),
+                fixHint: `Point it at the built copy under dist, or add ${withoutWildcard.split('/')[0]} to "files".`,
+            });
+            continue;
+        }
+        // Shipping the directory is not the same as producing the file. A wildcard
+        // names a directory whose contents are the point, so only a concrete
+        // target can be held to existing.
+        if (!target.includes('*') && !existsSync(join(pkgDir, withoutWildcard))) {
+            findings.push({
+                id: 'addon-entry-point-missing',
+                severity: 'error',
+                message: `"${name}" resolves to ${target}, which does not exist — importing it fails for anyone who installs ${pkg.name ?? 'this addon'}`,
+                path: join(pkgDir, withoutWildcard),
+                fixHint: 'Point the entry point at a file the build produces, or drop it from "exports".',
+            });
+        }
+    }
+    // Both generated directories ship, and they are not the same check twice.
+    // `exports` maps `./.pikku/*` to the root one, making it a public entry
+    // point whose imports climb to `<pkg>/types`, while the copy under dist
+    // reaches `<pkg>/dist/types` — two roots, two ways to fall outside the
+    // tarball.
+    const generatedRoots = GENERATED_DIRS.map((dir) => join(pkgDir, dir)).filter((dir) => existsSync(dir) && isPacked(dir, pkgDir, pkg.files));
+    // One missing file is imported by every generated file that needs its types,
+    // so reporting per import turns a single packaging mistake into a page of
+    // findings. Group by what is actually wrong: the thing that is not shipped.
+    const unresolved = new Map();
+    const unpacked = new Map();
+    const shippedFiles = (await Promise.all(generatedRoots.map((root) => walk(root)))).flat();
+    for (const file of shippedFiles) {
+        if (!/\.(ts|tsx|js|mjs|cjs)$/.test(file))
+            continue;
+        const source = await readTextSafe(file);
+        if (!source)
+            continue;
+        for (const specifier of relativeSpecifiers(source)) {
+            const candidates = resolveCandidates(specifier, dirname(file));
+            const target = candidates.find((candidate) => existsSync(candidate));
+            if (!target) {
+                // Keyed by the file that is missing rather than by the specifier: the
+                // same absent file is spelled `../types/x` from one directory and
+                // `../../types/x` from another, and it is still one thing to fix.
+                const missing = candidates[0];
+                const seen = unresolved.get(missing) ?? { specifier, files: [] };
+                seen.files.push(file);
+                unresolved.set(missing, seen);
+            }
+            else if (!isPacked(target, pkgDir, pkg.files)) {
+                const seen = unpacked.get(target) ?? { target, files: [] };
+                seen.files.push(file);
+                unpacked.set(target, seen);
+            }
+        }
+    }
+    const alsoIn = (files) => files.length > 1
+        ? ` (and ${files.length - 1} other generated file${files.length > 2 ? 's' : ''})`
+        : '';
+    for (const [missing, { specifier, files }] of unresolved) {
+        findings.push({
+            id: 'addon-shipped-import-unresolved',
+            severity: 'error',
+            message: `${relative(pkgDir, missing)} is not in the package, but ${files.length} shipped generated file${files.length === 1 ? '' : 's'} import${files.length === 1 ? 's' : ''} it (as "${specifier}" from ${relative(pkgDir, files[0])}) — anything installing ${pkg.name ?? 'this addon'} typechecks against a module that is not there`,
+            path: missing,
+            fixHint: 'Ship the file it names. The generated output is copied into dist, so whatever it imports has to be copied too — e.g. `cp -r .pikku types dist/` rather than `cp -r .pikku dist/`.',
+        });
+    }
+    for (const { target, files } of unpacked.values()) {
+        findings.push({
+            id: 'addon-shipped-import-not-packed',
+            severity: 'error',
+            message: `${relative(pkgDir, files[0])} imports ${relative(pkgDir, target)}${alsoIn(files)}, which exists but is excluded by "files" — it resolves here and not for anyone who installs the package`,
+            path: target,
+            fixHint: `Add ${relative(pkgDir, target).split(sep)[0]} to "files" in package.json, or move the file under a path already listed there.`,
+        });
+    }
+    return findings;
+}

package/dist/src/functions/validate/persona-checks.d.ts

@@ -15,7 +15,7 @@ export type PersonaCheckConfig = {
 /**
  * The people this project can run as, and whether it can run as them.
  *
- * Shared by `pikku workspace validate` and `pikku fabric validate` — the two
+ * Shared by `pikku validate` and `pikku fabric validate` — the two
  * validators are separate implementations, and a check that only one of them
  * makes is a check half the projects never see.
  *

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

@@ -100,7 +100,7 @@ const hasActorSignIn = async (sourceFiles) => {
 /**
  * The people this project can run as, and whether it can run as them.
  *
- * Shared by `pikku workspace validate` and `pikku fabric validate` — the two
+ * Shared by `pikku validate` and `pikku fabric validate` — the two
  * validators are separate implementations, and a check that only one of them
  * makes is a check half the projects never see.
  *

package/dist/src/functions/validate/scenario-file-checks.js

@@ -36,6 +36,16 @@ const SCENARIO_FILE = /\.(scenario|scenarios|steps)\.tsx?$/;
  */
 const VIRTUAL_USER_DECLARATIONS = ['definePersonas', 'runVirtualUser'];
 const VIRTUAL_USER_FILE = /\.(virtual-user|vu)\.tsx?$/;
+/**
+ * The declarations that grade an agent, and where they live.
+ *
+ * A scorer is a test of the agent that is also shipped, which is exactly why it
+ * needs its own file rather than sitting beside the agent it grades: the two
+ * are edited for opposite reasons, and a rubric buried in an agent definition
+ * is one nobody reviews as a rubric.
+ */
+const SCORER_DECLARATIONS = ['pikkuAIScorer', 'pikkuAIJudge'];
+const SCORER_FILE = /\.scorers?\.tsx?$/;
 const isGenerated = (path) => path.includes('.gen.') || path.includes(`${'/'}.pikku${'/'}`);
 const listSourceFiles = async (dir) => {
     if (!existsSync(dir))
@@ -119,5 +129,28 @@ export const runScenarioFileChecks = async (root, srcDirectories) => {
             ].join('\n'),
         });
     }
+    for (const file of files) {
+        if (SCORER_FILE.test(file) || isGenerated(file))
+            continue;
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        const used = SCORER_DECLARATIONS.filter((name) => new RegExp(`\\b${name}\\s*\\(`).test(text));
+        if (used.length === 0)
+            continue;
+        const rel = relative(root, file);
+        findings.push({
+            id: 'scorer-declared-outside-scorer-file',
+            severity: 'error',
+            message: `${rel} declares ${used.join(', ')} — scorers and judges must live in a *.scorer.ts file, not mixed into application code`,
+            path: file,
+            fixHint: [
+                'Move the declaration into a dedicated file, e.g.:',
+                `  ${rel.replace(/[^/\\]+$/, 'grading.scorer.ts')}`,
+                'A scorer grades the agent it sits next to, and is edited for the',
+                'opposite reason — keeping it separate is what keeps it reviewable.',
+            ].join('\n'),
+        });
+    }
     return findings;
 };

package/dist/src/functions/validate/shared-checks.d.ts

@@ -48,7 +48,7 @@ export declare function readTextSafe(path: string): Promise<string | null>;
 /**
  * Every check that is true of any pikku project, regardless of where it deploys.
  *
- * `pikku workspace validate` is exactly this; `pikku fabric validate` is this
+ * `pikku validate`'s app-project check is exactly this; `pikku fabric validate` is this
  * plus the deploy-shaped checks (themes, frontends, the Cloudflare adapter, the
  * .gitignore contract). Before this module the two were separate walks over the
  * same project that duplicated sixteen findings verbatim, and each carried

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

@@ -85,7 +85,7 @@ const REQUIRED_SCAFFOLD = [
 /**
  * Every check that is true of any pikku project, regardless of where it deploys.
  *
- * `pikku workspace validate` is exactly this; `pikku fabric validate` is this
+ * `pikku validate`'s app-project check is exactly this; `pikku fabric validate` is this
  * plus the deploy-shaped checks (themes, frontends, the Cloudflare adapter, the
  * .gitignore contract). Before this module the two were separate walks over the
  * same project that duplicated sixteen findings verbatim, and each carried