@pikku/cli 0.12.99 → 0.12.102

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

package/dist/src/functions/validate/validate-registry.d.ts

@@ -0,0 +1,52 @@
+import type { ValidateFinding as Finding } from './persona-checks.js';
+export type ValidateTarget = {
+    /** Absolute directory the check runs against. */
+    dir: string;
+    /** How the target is named in output — repo-relative, or "." for the root. */
+    label: string;
+};
+/**
+ * A check plus the condition under which it means anything.
+ *
+ * `pikku validate` runs every check whose precondition holds, wherever it
+ * holds. It deliberately does not detect a project *kind* and then dispatch:
+ * the repos that motivated this are several kinds at once — the addons
+ * monorepo is a workspace containing 217 publishable addons — and any
+ * single-kind guess is wrong for them. Preconditions compose where a mode
+ * would have had to pick.
+ */
+export type ValidateCheck = {
+    id: string;
+    /** What this check is for, shown when reporting what ran. */
+    subject: string;
+    applies: (target: ValidateTarget) => Promise<boolean>;
+    run: (target: ValidateTarget) => Promise<Finding[]>;
+};
+/**
+ * Every directory under `root` that holds a package.json.
+ *
+ * Walking beats reading the `workspaces` globs: the field is an array in one
+ * repo and `{ packages: [...] }` in the next, spells the same layout as
+ * `packages/**` or as six explicit globs, and a package that is real but
+ * unlisted is exactly the kind of thing worth validating. Over-collecting is
+ * harmless here because the preconditions decide what actually runs.
+ */
+export declare function discoverTargets(root: string, maxDepth?: number): Promise<ValidateTarget[]>;
+export declare const CHECKS: ValidateCheck[];
+export type ValidationPlan = Array<{
+    check: ValidateCheck;
+    target: ValidateTarget;
+}>;
+export declare function planValidation(root: string): Promise<ValidationPlan>;
+export type ValidateReport = {
+    ok: boolean;
+    root: string;
+    /** What ran, so a clean result can say what it actually looked at. */
+    ran: Array<{
+        checkId: string;
+        subject: string;
+        target: string;
+    }>;
+    findings: Finding[];
+};
+export declare function runValidate(root: string): Promise<ValidateReport>;

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

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { isAddonPackage, runAddonPackageChecks, } from './addon-package-checks.js';
+import { runSharedProjectChecks } from './shared-checks.js';
+/** A hand-written `types/application-types.d.ts` beside package.json. */
+const ADDON_MARKER = join('types', 'application-types.d.ts');
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.pikku',
+    '.pikku-runtime',
+    'coverage',
+    '.next',
+    '.yarn',
+]);
+/**
+ * Every directory under `root` that holds a package.json.
+ *
+ * Walking beats reading the `workspaces` globs: the field is an array in one
+ * repo and `{ packages: [...] }` in the next, spells the same layout as
+ * `packages/**` or as six explicit globs, and a package that is real but
+ * unlisted is exactly the kind of thing worth validating. Over-collecting is
+ * harmless here because the preconditions decide what actually runs.
+ */
+export async function discoverTargets(root, maxDepth = 5) {
+    const targets = [];
+    const visit = async (dir, depth) => {
+        if (existsSync(join(dir, 'package.json'))) {
+            targets.push({ dir, label: relative(root, dir) || '.' });
+        }
+        if (depth >= maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name))
+                continue;
+            await visit(join(dir, entry.name), depth + 1);
+        }
+    };
+    await visit(root, 0);
+    return targets;
+}
+export const CHECKS = [
+    {
+        id: 'app-project',
+        subject: 'app project',
+        // An addon also carries a pikku.config.json, and running the app-shaped
+        // checks against one reports every app convention it has no reason to
+        // follow — starting with a packages/functions/ it will never have.
+        applies: async ({ dir }) => existsSync(join(dir, 'pikku.config.json')) &&
+            !existsSync(join(dir, ADDON_MARKER)),
+        run: async ({ dir }) => (await runSharedProjectChecks(dir)).findings,
+    },
+    {
+        id: 'addon-package',
+        subject: 'addon',
+        applies: async ({ dir }) => isAddonPackage(dir),
+        run: async ({ dir }) => runAddonPackageChecks(dir),
+    },
+];
+export async function planValidation(root) {
+    const plan = [];
+    for (const target of await discoverTargets(root)) {
+        for (const check of CHECKS) {
+            if (await check.applies(target))
+                plan.push({ check, target });
+        }
+    }
+    return plan;
+}
+export async function runValidate(root) {
+    const plan = await planValidation(root);
+    const findings = [];
+    const ran = [];
+    for (const { check, target } of plan) {
+        findings.push(...(await check.run(target)));
+        ran.push({
+            checkId: check.id,
+            subject: check.subject,
+            target: target.label,
+        });
+    }
+    return {
+        ok: !findings.some((f) => f.severity === 'error'),
+        root,
+        ran,
+        findings,
+    };
+}

package/dist/src/functions/validate/validate.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+export { readJsonSafe, readTextSafe } from './shared-checks.js';
+export declare const FindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    severity: z.ZodEnum<{
+        warn: "warn";
+        error: "error";
+        info: "info";
+    }>;
+    message: z.ZodString;
+    path: z.ZodString;
+    fixHint: z.ZodString;
+}, z.core.$strip>;
+export type Finding = z.infer<typeof FindingSchema>;
+export declare const ValidateInput: z.ZodObject<{}, z.core.$strip>;
+export declare const ValidateOutput: z.ZodObject<{
+    ok: z.ZodBoolean;
+    root: z.ZodString;
+    ran: z.ZodArray<z.ZodObject<{
+        checkId: z.ZodString;
+        subject: z.ZodString;
+        target: z.ZodString;
+    }, z.core.$strip>>;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            warn: "warn";
+            error: "error";
+            info: "info";
+        }>;
+        message: z.ZodString;
+        path: z.ZodString;
+        fixHint: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The workspace root, or failing that the package the caller is standing in.
+ *
+ * A standalone publishable addon has no `workspaces` anywhere above it, and
+ * running from its `src/` would otherwise validate `src/` — a directory with no
+ * package.json, where every check's precondition is false and the run reports
+ * that nothing applied. The addon author is exactly who the addon checks are
+ * for, so the nearest package.json is the answer when no workspace claims it.
+ */
+export declare function findProjectRoot(startDir: string): Promise<string>;
+export declare function runProjectValidate(startDir?: string): Promise<z.infer<typeof ValidateOutput>>;
+export declare const renderValidate: (_s: unknown, { ok, root, ran, findings }: z.infer<typeof ValidateOutput>) => void;

package/dist/src/functions/validate/{workspace-validate.js → validate.js}

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { added, changed, dim, removed } from '../../fabric/lib/output.js';
-import { runSharedProjectChecks } from './shared-checks.js';
+import { runValidate } from './validate-registry.js';
 export { readJsonSafe, readTextSafe } from './shared-checks.js';
 export const FindingSchema = z.object({
     id: z.string(),
@@ -12,16 +12,32 @@ export const FindingSchema = z.object({
     path: z.string(),
     fixHint: z.string(),
 });
-export const WorkspaceValidateInput = z.object({});
-export const WorkspaceValidateOutput = z.object({
+export const ValidateInput = z.object({});
+export const ValidateOutput = z.object({
     ok: z.boolean(),
     root: z.string(),
+    ran: z.array(z.object({
+        checkId: z.string(),
+        subject: z.string(),
+        target: z.string(),
+    })),
     findings: z.array(FindingSchema),
 });
+/**
+ * The workspace root, or failing that the package the caller is standing in.
+ *
+ * A standalone publishable addon has no `workspaces` anywhere above it, and
+ * running from its `src/` would otherwise validate `src/` — a directory with no
+ * package.json, where every check's precondition is false and the run reports
+ * that nothing applied. The addon author is exactly who the addon checks are
+ * for, so the nearest package.json is the answer when no workspace claims it.
+ */
 export async function findProjectRoot(startDir) {
     let dir = startDir;
+    let nearestPackage;
     while (true) {
         if (existsSync(join(dir, 'package.json'))) {
+            nearestPackage ??= dir;
             try {
                 const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'));
                 if (pkg.workspaces)
@@ -33,19 +49,37 @@ export async function findProjectRoot(startDir) {
         }
         const parent = dirname(dir);
         if (parent === dir)
-            return startDir;
+            return nearestPackage ?? startDir;
         dir = parent;
     }
 }
-export async function runWorkspaceValidate(startDir = process.cwd()) {
+export async function runProjectValidate(startDir = process.cwd()) {
     const root = await findProjectRoot(startDir);
-    const { findings } = await runSharedProjectChecks(root);
-    const ok = !findings.some((f) => f.severity === 'error');
-    return { ok, root, findings };
+    return runValidate(root);
 }
-export const renderWorkspaceValidate = (_s, { ok, root, findings }) => {
+/** "2 addons, 1 app project" — what the run actually looked at. */
+function describeRan(ran) {
+    const bySubject = new Map();
+    for (const entry of ran) {
+        bySubject.set(entry.subject, (bySubject.get(entry.subject) ?? 0) + 1);
+    }
+    return [...bySubject]
+        .map(([subject, count]) => `${count} ${subject}${count === 1 ? '' : 's'}`)
+        .join(', ');
+}
+export const renderValidate = (_s, { ok, root, ran, findings }) => {
+    // A green tick for a run that checked nothing is the one outcome worth
+    // guarding against: auto-detection that finds nothing looks identical to
+    // auto-detection that found everything and liked it.
+    if (ran.length === 0) {
+        console.log(changed('⚠') +
+            '  ' +
+            'Nothing to validate here — no app project and no publishable addon found');
+        console.log(`   ${dim('fix:')}    Run from a directory with a pikku.config.json, or from a package that publishes generated pikku output.`);
+        return;
+    }
     if (findings.length === 0) {
-        console.log(added('✓  All checks passed — workspace is Pikku-compatible'));
+        console.log(added(`✓  All checks passed — checked ${describeRan(ran)}`));
         return;
     }
     const relPath = (p) => p.startsWith(root + '/') || p.startsWith(root + '\\')
@@ -76,9 +110,9 @@ export const renderWorkspaceValidate = (_s, { ok, root, findings }) => {
         counts.push(dim(`${infos.length} info${infos.length !== 1 ? 's' : ''}`));
     }
     console.log('─'.repeat(40));
-    console.log(counts.join('  '));
+    console.log(`${counts.join('  ')}  ${dim(`across ${describeRan(ran)}`)}`);
     if (ok) {
         console.log();
-        console.log(added('✓') + '  ' + dim('no errors — workspace is structurally sound'));
+        console.log(added('✓') + '  ' + dim('no errors'));
     }
 };

package/dist/src/functions/wirings/ai-agent/pikku-command-ai-agent-types.d.ts

@@ -1 +1 @@
-export declare const pikkuAIAgentTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuAIAgentTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/ai-agent/pikku-command-ai-agent-types.js

@@ -5,11 +5,12 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { serializeAIAgentTypes } from './serialize-ai-agent-types.js';
 export const pikkuAIAgentTypes = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
-        const { agentTypesFile, functionTypesFile, agentMapDeclarationFile, scopesFile, packageMappings, } = config;
+        const { agentTypesFile, functionTypesFile, agentMapDeclarationFile, scorerNamesDeclarationFile, scopesFile, packageMappings, } = config;
         const functionTypesImportPath = getFileImportRelativePath(agentTypesFile, functionTypesFile, packageMappings);
         const agentMapImportPath = getFileImportRelativePath(agentTypesFile, agentMapDeclarationFile, packageMappings);
         const scopesImportPath = getFileImportRelativePath(agentTypesFile, scopesFile, packageMappings);
-        const content = serializeAIAgentTypes(functionTypesImportPath, agentMapImportPath, scopesImportPath);
+        const scorerNamesImportPath = getFileImportRelativePath(agentTypesFile, scorerNamesDeclarationFile, packageMappings);
+        const content = serializeAIAgentTypes(functionTypesImportPath, agentMapImportPath, scopesImportPath, scorerNamesImportPath);
         await writeFileInDir(logger, agentTypesFile, content);
     },
     middleware: [