@pikku/cli 0.12.93 → 0.12.99

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

@@ -0,0 +1,90 @@
+import { join } from 'node:path';
+import { readJsonSafe } from './shared-checks.js';
+/**
+ * `pikku dev` / `pikku serve` own the server lifecycle, so a project that boots
+ * through them can hang setup off `pikkuServerLifecycle` instead of constructing
+ * its own services. These patterns cover the runner prefixes people put in front
+ * of the binary (npx/yarn/pnpm/bun), leading env assignments, and `&&` chains.
+ */
+const PIKKU_SERVER_SCRIPT = /(?:^|[\s;&|])pikku(?:\.js)?\s+(?:-[^\s]*\s+)*(?:dev|serve)(?:\s|$)/;
+/**
+ * Scripts that hand off to another script rather than starting a process
+ * themselves. We cannot follow the indirection, so they are treated as unknown
+ * rather than reported.
+ */
+const DELEGATING_SCRIPT = /(?:^|[\s;&|])(?:turbo|nx|lerna|npm-run-all|run-p|run-s)(?:\s|$)|(?:^|[\s;&|])(?:npm|yarn|pnpm|bun)\s+(?:run|workspace|workspaces|--filter)(?:\s|$)/;
+/**
+ * Runtime adapters that embed Pikku in a server the project owns. Depending on
+ * one is a deliberate choice to bootstrap by hand — `pikku dev` / `pikku serve`
+ * cannot host these, so their entrypoints are not reported.
+ */
+const RUNTIME_ADAPTER_PACKAGES = new Set([
+    '@pikku/azure-functions',
+    '@pikku/bun-server',
+    '@pikku/cloudflare',
+    '@pikku/express',
+    '@pikku/express-middleware',
+    '@pikku/fastify',
+    '@pikku/fastify-plugin',
+    '@pikku/lambda',
+    '@pikku/modelcontextprotocol',
+    '@pikku/next',
+    '@pikku/node-http-server',
+    '@pikku/tanstack-start',
+    '@pikku/uws',
+    '@pikku/uws-handler',
+    '@pikku/ws',
+]);
+async function hasRuntimeAdapter(root, rootPkg) {
+    const fnPkg = await readJsonSafe(join(root, 'packages', 'functions', 'package.json'));
+    const names = [
+        ...Object.keys(rootPkg.dependencies ?? {}),
+        ...Object.keys(rootPkg.devDependencies ?? {}),
+        ...Object.keys(fnPkg?.dependencies ?? {}),
+        ...Object.keys(fnPkg?.devDependencies ?? {}),
+    ];
+    return names.some((name) => RUNTIME_ADAPTER_PACKAGES.has(name));
+}
+function bootstrapLintSeverity(pikkuConfig) {
+    const lint = pikkuConfig?.lint;
+    const configured = lint?.customServerBootstrap;
+    return configured === 'off' || configured === 'error' || configured === 'warn'
+        ? configured
+        : 'warn';
+}
+/**
+ * Reports a root `start`/`dev` script that boots a server Pikku does not own.
+ *
+ * Services built in a hand-rolled entrypoint never reach the
+ * `pikkuServerLifecycle` hooks, so startup and shutdown work silently does not
+ * run. A project depending on a runtime adapter has opted into owning its own
+ * server, and a script that delegates to another runner cannot be followed, so
+ * neither is reported.
+ */
+export async function runBootstrapChecks(root, rootPkg, pikkuConfig) {
+    if (!rootPkg)
+        return [];
+    const severity = bootstrapLintSeverity(pikkuConfig);
+    if (severity === 'off')
+        return [];
+    if (await hasRuntimeAdapter(root, rootPkg))
+        return [];
+    const customScripts = ['start', 'dev'].filter((name) => {
+        const script = rootPkg.scripts?.[name];
+        if (!script)
+            return false;
+        return !PIKKU_SERVER_SCRIPT.test(script) && !DELEGATING_SCRIPT.test(script);
+    });
+    if (customScripts.length === 0)
+        return [];
+    const named = customScripts.map((n) => `"${n}"`).join(', ');
+    return [
+        {
+            id: 'custom-server-bootstrap',
+            severity,
+            message: `package.json ${named} ${customScripts.length > 1 ? 'scripts start a server' : 'script starts a server'} without \`pikku dev\` or \`pikku serve\`, and no Pikku runtime adapter is installed — services created in a hand-rolled entrypoint bypass the server lifecycle hooks`,
+            path: join(root, 'package.json'),
+            fixHint: 'Start the server with `pikku serve` (or `pikku dev` locally) and move startup and shutdown work into a `pikkuServerLifecycle({ beforeStart, afterStart, beforeStop, afterStop })` export, which receives the already-created singleton services. To keep a custom entrypoint, set "lint": { "customServerBootstrap": "off" } in pikku.config.json',
+        },
+    ];
+}

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

@@ -0,0 +1,24 @@
+export type ValidateSeverity = 'error' | 'warn' | 'info';
+export type ValidateFinding = {
+    id: string;
+    severity: ValidateSeverity;
+    message: string;
+    path: string;
+    fixHint: string;
+};
+export type PersonaCheckConfig = {
+    srcDirectories?: unknown;
+    outDir?: unknown;
+    personasMetaJsonFile?: unknown;
+    environments?: unknown;
+};
+/**
+ * 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
+ * validators are separate implementations, and a check that only one of them
+ * makes is a check half the projects never see.
+ *
+ * knowledge: decisions/internals/validate-checks-personas-through-a-shared-module.md
+ */
+export declare const runPersonaChecks: (root: string, config: PersonaCheckConfig | null) => Promise<ValidateFinding[]>;

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

@@ -0,0 +1,136 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const lines = (...parts) => parts.join('\n');
+const stringArray = (value) => Array.isArray(value)
+    ? value.filter((v) => typeof v === 'string')
+    : [];
+/**
+ * Source files under one directory, flat list, generated files included.
+ *
+ * A persona declaration is `definePersonas({ … })` written by hand, but the
+ * actor plugin is routinely wired in a file the auth scaffold generated, so
+ * `.gen.ts` cannot be skipped the way the undeclared-import walk skips it.
+ */
+const listSourceFiles = async (dir) => {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return (await readdir(dir, { recursive: true }))
+            .filter((f) => typeof f === 'string' &&
+            (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+            !f.includes('node_modules'))
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+};
+const readTextSafe = async (path) => {
+    if (!existsSync(path))
+        return null;
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Where the persona meta lands when the project has not overridden it, mirroring
+ * the default `pikku-cli-config` resolves — validate reads the raw config file
+ * rather than the resolved one, so the default has to be repeated here.
+ */
+const personaMetaPath = (root, config) => {
+    if (typeof config.personasMetaJsonFile === 'string') {
+        return join(root, config.personasMetaJsonFile);
+    }
+    const outDir = typeof config.outDir === 'string' ? config.outDir : '.pikku';
+    return join(root, outDir, 'scopes', 'pikku-personas-meta.gen.json');
+};
+/**
+ * Whether this project declares anyone to run as.
+ *
+ * Two sources, because either one alone is wrong at a predictable moment: the
+ * generated meta is empty on a checkout where codegen has not run yet, and a
+ * source scan cannot see personas a dependency contributed. Declared by either
+ * counts as declared — a validator that cries about a missing persona on a
+ * fresh clone gets muted, and then it never says anything worth hearing.
+ */
+const countPersonas = async (root, config, sourceFiles) => {
+    const metaText = await readTextSafe(personaMetaPath(root, config));
+    if (metaText) {
+        try {
+            const meta = JSON.parse(metaText);
+            const declared = Object.keys(meta).length;
+            if (declared > 0)
+                return declared;
+        }
+        catch {
+            // A corrupt meta file is the scan's problem to answer, not a reason to
+            // claim there are no personas.
+        }
+    }
+    for (const file of sourceFiles) {
+        const text = await readTextSafe(file);
+        if (text && /\bdefinePersonas\s*\(/.test(text))
+            return 1;
+    }
+    return 0;
+};
+/**
+ * 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.
+ */
+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);
+        if (wiresPlugin || /sign-in\/actor/.test(text))
+            return true;
+    }
+    return false;
+};
+/**
+ * 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
+ * validators are separate implementations, and a check that only one of them
+ * makes is a check half the projects never see.
+ *
+ * knowledge: decisions/internals/validate-checks-personas-through-a-shared-module.md
+ */
+export const runPersonaChecks = async (root, config) => {
+    const findings = [];
+    const w = (id, message, path, fixHint) => {
+        findings.push({ id, severity: 'warn', message, path, fixHint });
+    };
+    const srcDirectories = stringArray(config?.srcDirectories);
+    const searchDirs = srcDirectories.length
+        ? srcDirectories
+        : [join('packages', 'functions', 'src')];
+    const sourceFiles = (await Promise.all(searchDirs.map((dir) => listSourceFiles(join(root, dir))))).flat();
+    const personas = await countPersonas(root, config ?? {}, sourceFiles);
+    const pikkuConfigPath = join(root, 'pikku.config.json');
+    if (personas === 0) {
+        w('no-personas', 'No personas are declared — `pikku scenario run` and `pikku persona run` have nobody to run as, so nothing exercises this app the way a user would', pikkuConfigPath, lines('Declare the people who use this app with definePersonas(), e.g. in', 'packages/functions/src/scenarios/personas.virtual-user.ts:', "  import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'", '  definePersonas({', "    founder: { name: 'Anna Müller', jobTitle: 'Managing director' },", '  })', 'Their email addresses are computed from the key and scenarios.emailDomain.'));
+        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 })]', 'The plugin refuses every sign-in while the secret is unset, so a stage', 'that must not run scenarios simply leaves SCENARIO_ACTOR_SECRET out.'));
+    }
+    const environments = config?.environments;
+    const hasEnvironment = typeof environments === 'object' &&
+        environments !== null &&
+        Object.keys(environments).length > 0;
+    if (!hasEnvironment) {
+        w('personas-no-environments', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but pikku.config.json configures no environments — \`pikku scenario run <environment>\` has no target to resolve and refuses every name`, pikkuConfigPath, lines('Add the targets a run may point at:', '  "environments": {', '    "local": { "apiUrl": "http://localhost:4002", "appUrl": "http://localhost:3000" }', '  }'));
+    }
+    return findings;
+};

package/dist/src/functions/validate/scenario-file-checks.d.ts

@@ -0,0 +1,17 @@
+import type { ValidateFinding } from './persona-checks.js';
+/**
+ * Scenarios, features and steps live in files named for what they are.
+ *
+ * A `pikkuScenario` declared next to the functions it exercises reads as more
+ * of the same file — the wiring, the function and the test of the function all
+ * in one scroll — and the scenario is the part that gets lost. Keeping them in
+ * `*.scenario.ts` / `*.scenarios.ts` / `*.steps.ts` means a file's name tells
+ * you whether it ships or whether it tests, before you open it.
+ *
+ * An error rather than a warning: the mixing is only cheap to undo while it is
+ * one file, and every project that let it slide ended up with scenarios spread
+ * across dozens.
+ *
+ * knowledge: decisions/internals/scenarios-live-in-files-named-for-them.md
+ */
+export declare const runScenarioFileChecks: (root: string, srcDirectories: string[]) => Promise<ValidateFinding[]>;

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

@@ -0,0 +1,123 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { readTextSafe } from './shared-checks.js';
+/**
+ * The declarations that must live in a dedicated scenario file.
+ *
+ * Matched on the call, not the import, so a re-export or an aliased import does
+ * not slip past — and a file that only mentions the name in a comment or a
+ * string does not get flagged.
+ */
+const SCENARIO_DECLARATIONS = [
+    'pikkuScenario',
+    'pikkuFeature',
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+];
+/**
+ * A file allowed to declare them.
+ *
+ * Three suffixes rather than one because the split that matters is scenarios
+ * apart from application code, not a particular spelling: `.scenario.ts` and
+ * `.scenarios.ts` hold the scenarios, `.steps.ts` holds the steps they call.
+ */
+const SCENARIO_FILE = /\.(scenario|scenarios|steps)\.tsx?$/;
+/**
+ * The declarations that make up a virtual user, and where they live.
+ *
+ * There is no `defineVirtualUsers` to look for — that name was retired in
+ * favour of `definePersonas`, because a virtual user is derived rather than
+ * authored: the function meta becomes its catalogue, the scenario meta becomes
+ * its intents, and the declared personas become its identities. So the thing a
+ * project actually writes is the persona list, and that is what has to be
+ * findable by filename.
+ */
+const VIRTUAL_USER_DECLARATIONS = ['definePersonas', 'runVirtualUser'];
+const VIRTUAL_USER_FILE = /\.(virtual-user|vu)\.tsx?$/;
+const isGenerated = (path) => path.includes('.gen.') || path.includes(`${'/'}.pikku${'/'}`);
+const listSourceFiles = async (dir) => {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return (await readdir(dir, { recursive: true }))
+            .filter((f) => typeof f === 'string' &&
+            (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+            !f.includes('node_modules'))
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Scenarios, features and steps live in files named for what they are.
+ *
+ * A `pikkuScenario` declared next to the functions it exercises reads as more
+ * of the same file — the wiring, the function and the test of the function all
+ * in one scroll — and the scenario is the part that gets lost. Keeping them in
+ * `*.scenario.ts` / `*.scenarios.ts` / `*.steps.ts` means a file's name tells
+ * you whether it ships or whether it tests, before you open it.
+ *
+ * An error rather than a warning: the mixing is only cheap to undo while it is
+ * one file, and every project that let it slide ended up with scenarios spread
+ * across dozens.
+ *
+ * knowledge: decisions/internals/scenarios-live-in-files-named-for-them.md
+ */
+export const runScenarioFileChecks = async (root, srcDirectories) => {
+    const findings = [];
+    const dirs = srcDirectories.length
+        ? srcDirectories
+        : [join('packages', 'functions', 'src')];
+    const files = (await Promise.all(dirs.map((dir) => listSourceFiles(join(root, dir))))).flat();
+    for (const file of files) {
+        if (SCENARIO_FILE.test(file) || isGenerated(file))
+            continue;
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        const used = SCENARIO_DECLARATIONS.filter((name) => new RegExp(`\\b${name}\\s*\\(`).test(text));
+        if (used.length === 0)
+            continue;
+        const rel = relative(root, file);
+        const suggested = rel.replace(/\.tsx?$/, (ext) => `.scenarios${ext}`);
+        findings.push({
+            id: 'scenario-declared-outside-scenario-file',
+            severity: 'error',
+            message: `${rel} declares ${used.join(', ')} — scenarios, features and steps must live in a *.scenario.ts, *.scenarios.ts or *.steps.ts file, not mixed into application code`,
+            path: file,
+            fixHint: [
+                `Move the ${used.length === 1 ? 'declaration' : 'declarations'} into a dedicated file, e.g.:`,
+                `  ${suggested}`,
+                'Steps belong in *.steps.ts; the scenarios that call them in *.scenarios.ts.',
+                'Keeping them apart is what lets a file name say whether it ships or tests.',
+            ].join('\n'),
+        });
+    }
+    for (const file of files) {
+        if (VIRTUAL_USER_FILE.test(file) || isGenerated(file))
+            continue;
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        const used = VIRTUAL_USER_DECLARATIONS.filter((name) => new RegExp(`\\b${name}\\s*\\(`).test(text));
+        if (used.length === 0)
+            continue;
+        const rel = relative(root, file);
+        findings.push({
+            id: 'virtual-user-declared-outside-virtual-user-file',
+            severity: 'error',
+            message: `${rel} declares ${used.join(', ')} — the personas a virtual user plays must live in a *.virtual-user.ts (or *.vu.ts) file, not mixed into application code`,
+            path: file,
+            fixHint: [
+                'Move the declaration into a dedicated file, e.g.:',
+                `  ${rel.replace(/[^/\\]+$/, 'personas.virtual-user.ts')}`,
+                'A virtual user is derived from what the project already generates —',
+                'the personas are the only part it authors, so they get their own file.',
+            ].join('\n'),
+        });
+    }
+    return findings;
+};

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

@@ -0,0 +1,59 @@
+import { type ValidateFinding } from './persona-checks.js';
+export type Finding = ValidateFinding;
+export type SharedPikkuConfig = {
+    srcDirectories?: unknown;
+    outDir?: unknown;
+    environments?: unknown;
+    clientFiles?: unknown;
+    scaffold?: {
+        console?: unknown;
+        rpc?: unknown;
+        agent?: unknown;
+        workflow?: unknown;
+        events?: unknown;
+        remoteRpc?: unknown;
+    };
+    db?: {
+        engine?: 'sqlite' | 'postgres';
+    };
+    lint?: {
+        customServerBootstrap?: 'off' | 'warn' | 'error';
+    };
+};
+export type SharedFnPkg = {
+    type?: string;
+    imports?: Record<string, unknown>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+};
+export type SharedCheckResult = {
+    findings: Finding[];
+    /** Read once here and handed back, so a caller never parses these twice. */
+    pikkuConfig: SharedPikkuConfig | null;
+    fnPkg: SharedFnPkg | null;
+    fnDir: string;
+    dbEngine: 'sqlite' | 'postgres';
+    migrationsDir: string;
+};
+/**
+ * A malformed config is named, never reported as absent.
+ *
+ * `pikku fabric validate` used to swallow the parse error and report
+ * `pikku-config-missing` for a file that is right there — the one message
+ * guaranteed to send you looking in the wrong place.
+ */
+export declare function readJsonSafe<T>(path: string): Promise<T | null>;
+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
+ * 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
+ * checks the other lacked for no reason anyone could name.
+ *
+ * knowledge: decisions/internals/one-project-shape-check-two-validators.md
+ */
+export declare function runSharedProjectChecks(root: string): Promise<SharedCheckResult>;