@pikku/cli 0.12.104 → 0.12.107

package/dist/src/utils/pikku-cli-config.js

@@ -1,6 +1,7 @@
 import { join, dirname, resolve, isAbsolute, parse as parsePath } from 'path';
 import { readdir, readFile } from 'fs/promises';
 import { resolveScaffoldFeature } from './resolve-scaffold-feature.js';
+import { setScaffoldWriteGuard } from './file-writer.js';
 const CLIENT_FILE_KEYS = [
     'fetchFile',
     'websocketFile',
@@ -17,7 +18,24 @@ export const getPikkuCLIConfig = async (logger, configFile = undefined, required
     const config = await _getPikkuCLIConfig(logger, configFile, requiredFields, exitProcess, outDirOverride);
     return config;
 };
-async function findConfigFile() {
+/**
+ * Like `getPikkuCLIConfig`, but returns null when the project has no config at
+ * all rather than throwing.
+ *
+ * Some commands are meant to run *outside* a Pikku project: `pikku skills
+ * install` seeds a repo's agent skills, which is something you do before there
+ * is a pikku.config.json to read. Requiring one to find out there isn't one is
+ * a chicken-and-egg. A config that exists but is broken still throws — that is
+ * a real error, and staying quiet about it would hide it.
+ */
+export const tryGetPikkuCLIConfig = async (logger, configFile = undefined, requiredFields, outDirOverride) => {
+    const resolved = configFile ?? (await findConfigFileOrNull());
+    if (!resolved) {
+        return null;
+    }
+    return await getPikkuCLIConfig(logger, resolved, requiredFields, false, outDirOverride);
+};
+async function findConfigFileOrNull() {
     let dir = process.cwd();
     const { root } = parsePath(dir);
     while (true) {
@@ -31,7 +49,14 @@ async function findConfigFile() {
             break;
         dir = dirname(dir);
     }
-    throw new Error('Config file pikku.config.json not found');
+    return null;
+}
+async function findConfigFile() {
+    const configFile = await findConfigFileOrNull();
+    if (!configFile) {
+        throw new Error('Config file pikku.config.json not found');
+    }
+    return configFile;
 }
 /** A config that was found and parsed, but says something impossible. */
 export class PikkuCLIConfigError extends Error {
@@ -119,6 +144,17 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
                 ? outDirOverride
                 : resolve(result.rootDir, outDirOverride);
         }
+        // An addon's whole generated tree roots one level down, so every leaf it
+        // authors is reached as `#pikku/addon/<leaf>`. tsconfig `paths` are global
+        // to a tsx process rather than scoped to the package that declared them, so
+        // a linked addon's `#pikku/function` would otherwise match the *host
+        // application's* flat leaf and type the addon's functions against the
+        // host's services. An application generates nothing at this depth, so the
+        // pattern finds no candidate and resolution falls back to Node's
+        // per-package `imports`, which is package-scoped by definition.
+        if (result.addon) {
+            result.outDir = join(result.outDir, 'addon');
+        }
         // Create transport/event directories
         const functionDir = join(result.outDir, 'function');
         const httpDir = join(result.outDir, 'http');
@@ -147,8 +183,21 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.functionTypesFile) {
             result.functionTypesFile = join(functionDir, 'pikku-function-types.gen.ts');
         }
-        if (!result.typesDeclarationFile) {
-            result.typesDeclarationFile = join(result.outDir, 'pikku-types.gen.ts');
+        if (!result.middlewareTypesFile) {
+            result.middlewareTypesFile = join(middlewareDir, 'pikku-middleware-types.gen.ts');
+        }
+        const setupDir = join(result.outDir, 'setup');
+        if (!result.setupTypesFile) {
+            result.setupTypesFile = join(setupDir, 'pikku-setup-types.gen.ts');
+        }
+        if (!result.addonSetupTypesFile) {
+            result.addonSetupTypesFile = join(setupDir, 'pikku-addon-setup-types.gen.ts');
+        }
+        // Sits in the same directory as the better-auth wrapper so both reach the
+        // reader as `#pikku/auth`, but is written unconditionally: every project
+        // decides who may call a function, only some projects use better-auth.
+        if (!result.authGuardsFile) {
+            result.authGuardsFile = join(result.outDir, 'auth', 'pikku-auth-types.gen.ts');
         }
         // HTTP
         if (!result.httpWiringsFile) {
@@ -174,6 +223,9 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         }
         // Gateways
         const gatewayDir = join(result.outDir, 'gateway');
+        if (!result.gatewaysTypesFile) {
+            result.gatewaysTypesFile = join(gatewayDir, 'pikku-gateway-types.gen.ts');
+        }
         if (!result.gatewaysWiringFile) {
             result.gatewaysWiringFile = join(gatewayDir, 'pikku-gateway-wirings.gen.ts');
         }
@@ -232,6 +284,14 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         const resolvedScaffoldDir = isAbsolute(scaffoldDir)
             ? scaffoldDir
             : join(result.rootDir, scaffoldDir);
+        // Per-unit deploy codegen re-runs the whole of `pikku all` with `--outDir`
+        // pointed at one unit's `.pikku`. It needs the `.pikku` artifacts and
+        // nothing else — the scaffold is project source, and regenerating it under
+        // a redirected outDir rewrites the developer's imports to point inside
+        // `.deploy/`. Read straight from the environment rather than through the
+        // variables service: that service JSON-parses, so `'1'` arrives as the
+        // number 1 and every `=== '1'` check against it silently never matched.
+        setScaffoldWriteGuard(process.env.PIKKU_DEPLOY_CODEGEN === '1' ? resolvedScaffoldDir : undefined);
         // Read every scaffold feature once, here, so a legacy 'auth'/'no-auth'
         // fails at load with the migration named, rather than downstream where the
         // value has already been coerced into something plausible.
@@ -407,11 +467,18 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.workflowMetaDir) {
             result.workflowMetaDir = join(workflowDir, 'meta');
         }
-        if (!result.personasWiringFile) {
-            result.personasWiringFile = join(workflowDir, 'pikku-personas.gen.ts');
-        }
         // Scenarios
         const scenarioDir = join(result.outDir, 'scenarios');
+        if (!result.scenarioTypesFile) {
+            result.scenarioTypesFile = join(scenarioDir, 'pikku-scenario-types.gen.ts');
+        }
+        // The actors a scenario drives. Sat under `workflow/` beside a different
+        // file of the same name — `scopes/pikku-personas.gen.ts` declares personas,
+        // this one types them at runtime — which made the pair impossible to tell
+        // apart by import path.
+        if (!result.personasWiringFile) {
+            result.personasWiringFile = join(scenarioDir, 'pikku-personas.gen.ts');
+        }
         if (!result.scenarioStepsFile) {
             result.scenarioStepsFile = join(scenarioDir, 'pikku-scenario-functions.gen.ts');
         }
@@ -537,16 +604,17 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.addonMetaJsonFile) {
             result.addonMetaJsonFile = join(consoleDir, 'pikku-addon-meta.gen.json');
         }
-        if (!result.nodeTypesFile) {
-            result.nodeTypesFile = join(consoleDir, 'pikku-node-types.gen.ts');
-        }
         const addonDir = join(result.outDir, 'addon');
         if (!result.packageFile) {
-            result.packageFile = join(addonDir, 'pikku-package.gen.ts');
+            result.packageFile = join(result.addon ? result.outDir : addonDir, 'pikku-package.gen.ts');
         }
         if (!result.addonTypesFile) {
             result.addonTypesFile = join(addonDir, 'pikku-addon-types.gen.ts');
         }
+        const errorDir = join(result.outDir, 'error');
+        if (!result.errorTypesFile) {
+            result.errorTypesFile = join(errorDir, 'pikku-error-types.gen.ts');
+        }
         // Secrets (typed wrapper for SecretService)
         const secretsDir = join(result.outDir, 'secrets');
         if (!result.secretTypesFile) {
@@ -669,7 +737,9 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
             throw e;
         }
         logger.error(e);
-        throw new Error(`Config file not found: ${configFile}`);
+        // The file was found and read; it is the loading that failed. Reporting
+        // that as "not found" sends the reader hunting for a file that is there.
+        throw new Error(`Failed to load config file: ${configFile}`);
     }
 };
 export const validateCLIConfig = (cliConfig, required) => {

package/dist/src/utils/remove-legacy-scaffold-file.d.ts

@@ -14,4 +14,18 @@ export declare const removeLegacyScaffoldFile: (file: string) => Promise<void>;
  * to write to, this removes a file pikku no longer writes at all.
  */
 export declare const removeRetiredScaffoldFiles: (config: PikkuCLIConfig) => Promise<void>;
+/**
+ * Delete agent scaffolds that import an entry point pikku no longer publishes.
+ *
+ * A scaffold is written once, when missing, and left alone afterwards so a
+ * project can edit it. That is the right default until the import at the top
+ * stops resolving: the file then fails to compile and pikku will not replace it,
+ * because it is still there. Deleting it puts it back in the missing set, so the
+ * same `pikku all` regenerates it against the current entry point.
+ *
+ * Only the specifiers above count as stale. Anything a
+ * project added to the file is lost with it — which is why this is keyed to an
+ * import that cannot compile rather than to the file simply being out of date.
+ */
+export declare const refreshScaffoldsImportingRemovedEntryPoints: (config: PikkuCLIConfig) => Promise<void>;
 export declare const pruneLegacyScaffoldFiles: (config: PikkuCLIConfig) => Promise<void>;

package/dist/src/utils/remove-legacy-scaffold-file.js

@@ -1,5 +1,5 @@
 import { rm } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 const scaffoldFiles = (config) => {
     const authDir = config.authFile ? dirname(config.authFile) : undefined;
@@ -57,6 +57,41 @@ export const removeRetiredScaffoldFiles = async (config) => {
         }
     }
 };
+/**
+ * Entry points a scaffold may still import that nothing resolves any more: the
+ * two #596 renamed, and the `#pikku` hub #1308 replaced with per-wiring leaves.
+ * The hub was the project's own file, so a scaffold names it by a relative path
+ * rather than by package — matching on the file name is what catches it wherever
+ * `outDir` sits.
+ */
+const REMOVED_ENTRY_POINTS = [
+    '@pikku/core/ai-agent',
+    '@pikku/core/ai-scorer',
+    'pikku-types.gen.js',
+];
+/**
+ * Delete agent scaffolds that import an entry point pikku no longer publishes.
+ *
+ * A scaffold is written once, when missing, and left alone afterwards so a
+ * project can edit it. That is the right default until the import at the top
+ * stops resolving: the file then fails to compile and pikku will not replace it,
+ * because it is still there. Deleting it puts it back in the missing set, so the
+ * same `pikku all` regenerates it against the current entry point.
+ *
+ * Only the specifiers above count as stale. Anything a
+ * project added to the file is lost with it — which is why this is keyed to an
+ * import that cannot compile rather than to the file simply being out of date.
+ */
+export const refreshScaffoldsImportingRemovedEntryPoints = async (config) => {
+    for (const file of [config.publicAgentFile, config.publicAgentSchemasFile]) {
+        if (!file || !existsSync(file))
+            continue;
+        const contents = readFileSync(file, 'utf-8');
+        if (REMOVED_ENTRY_POINTS.some((entry) => contents.includes(entry))) {
+            await rm(file, { force: true });
+        }
+    }
+};
 export const pruneLegacyScaffoldFiles = async (config) => {
     for (const file of scaffoldFiles(config)) {
         if (file) {

package/dist/src/utils/resolve-scaffold-feature.js

@@ -35,7 +35,11 @@ export const resolveScaffoldFeature = (feature, value) => {
  * path — so guessing would be wrong twice over.
  */
 const legacyValueMessage = (feature, value) => {
-    const migrated = value === 'no-auth' ? '{ "auth": false }' : LEGACY_VALUES.has(value) ? 'true' : null;
+    const migrated = value === 'no-auth'
+        ? '{ "auth": false }'
+        : LEGACY_VALUES.has(value)
+            ? 'true'
+            : null;
     if (!migrated) {
         return (`pikku.config.json: scaffold.${feature} must be true, false, or an object ` +
             `like { "auth": false } — received the string ${JSON.stringify(value)}.`);

package/dist/src/utils/schema-diff.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Field-level compatibility diff between two JSON Schemas.
+ *
+ * Whether a change breaks anyone depends on which way the data flows, so every
+ * comparison carries a `direction`. An input schema is contravariant — the
+ * caller writes it, so tightening (a new required field, a narrower enum) is
+ * what breaks. An output schema is covariant — the caller reads it, so
+ * loosening (a field that may now be absent, a new enum member the consumer
+ * never handled) is what breaks. Removing a field breaks in both directions.
+ */
+export type SchemaDirection = 'input' | 'output';
+export interface SchemaChange {
+    /** Dotted path from the schema root, `[]` marking array items. */
+    path: string;
+    breaking: boolean;
+    reason: string;
+}
+/**
+ * Diff two schemas, either of which may be absent — a function that gained or
+ * lost an input/output entirely is a real compatibility event, not a no-op.
+ */
+export declare function diffSchema(before: unknown, after: unknown, direction: SchemaDirection): SchemaChange[];

package/dist/src/utils/schema-diff.js

@@ -0,0 +1,190 @@
+/**
+ * Field-level compatibility diff between two JSON Schemas.
+ *
+ * Whether a change breaks anyone depends on which way the data flows, so every
+ * comparison carries a `direction`. An input schema is contravariant — the
+ * caller writes it, so tightening (a new required field, a narrower enum) is
+ * what breaks. An output schema is covariant — the caller reads it, so
+ * loosening (a field that may now be absent, a new enum member the consumer
+ * never handled) is what breaks. Removing a field breaks in both directions.
+ */
+const isSchema = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const joinPath = (parent, key) => parent ? `${parent}.${key}` : key;
+/**
+ * Resolve local `#/definitions/...` / `#/$defs/...` pointers against the root
+ * they were authored in. Anything non-local is left alone — an unresolvable
+ * `$ref` is compared as the opaque object it is rather than guessed at.
+ */
+function deref(schema, root, seen) {
+    let current = schema;
+    while (typeof current.$ref === 'string') {
+        const ref = current.$ref;
+        if (!ref.startsWith('#/') || seen.has(ref))
+            return current;
+        seen.add(ref);
+        let target = root;
+        for (const rawSegment of ref.slice(2).split('/')) {
+            const segment = rawSegment.replace(/~1/g, '/').replace(/~0/g, '~');
+            if (!isSchema(target))
+                return current;
+            target = target[segment];
+        }
+        if (!isSchema(target))
+            return current;
+        current = target;
+    }
+    return current;
+}
+const typeOf = (schema) => {
+    const type = schema.type;
+    if (typeof type === 'string')
+        return type;
+    if (Array.isArray(type))
+        return [...type].sort().join('|');
+    return undefined;
+};
+const requiredSet = (schema) => new Set(Array.isArray(schema.required) ? schema.required : []);
+const propertiesOf = (schema) => isSchema(schema.properties) ? schema.properties : {};
+/**
+ * `additionalProperties: false` is what makes an unknown key an error, so a
+ * removed input field only breaks callers when the schema is closed.
+ */
+const isClosed = (schema) => schema.additionalProperties === false;
+function compare(beforeRaw, afterRaw, direction, path, beforeRoot, afterRoot, depth, changes) {
+    // Deep enough to have left any sane generated schema behind; a cyclic pair of
+    // `$ref`s that dodges the per-branch guard stops here rather than recursing.
+    if (depth > 24)
+        return;
+    const before = deref(beforeRaw, beforeRoot, new Set());
+    const after = deref(afterRaw, afterRoot, new Set());
+    const beforeType = typeOf(before);
+    const afterType = typeOf(after);
+    if (beforeType !== afterType && (beforeType || afterType)) {
+        changes.push({
+            path,
+            breaking: true,
+            reason: `type changed from ${beforeType ?? 'unknown'} to ${afterType ?? 'unknown'}`,
+        });
+        return;
+    }
+    compareEnums(before, after, direction, path, changes);
+    const beforeProps = propertiesOf(before);
+    const afterProps = propertiesOf(after);
+    const beforeRequired = requiredSet(before);
+    const afterRequired = requiredSet(after);
+    for (const key of Object.keys(beforeProps)) {
+        const childPath = joinPath(path, key);
+        if (!(key in afterProps)) {
+            // Dropping an input field only breaks callers that still send it, which
+            // is only an error against a closed schema.
+            const breaking = direction === 'output' || isClosed(after);
+            changes.push({
+                path: childPath,
+                breaking,
+                reason: breaking
+                    ? 'field removed'
+                    : 'field removed (schema accepts additional properties)',
+            });
+            continue;
+        }
+        if (beforeRequired.has(key) && !afterRequired.has(key)) {
+            changes.push({
+                path: childPath,
+                breaking: direction === 'output',
+                reason: direction === 'output'
+                    ? 'field is no longer guaranteed to be present'
+                    : 'field became optional',
+            });
+        }
+        else if (!beforeRequired.has(key) && afterRequired.has(key)) {
+            changes.push({
+                path: childPath,
+                breaking: direction === 'input',
+                reason: direction === 'input'
+                    ? 'optional field became required'
+                    : 'field is now always present',
+            });
+        }
+        compare(beforeProps[key], afterProps[key], direction, childPath, beforeRoot, afterRoot, depth + 1, changes);
+    }
+    for (const key of Object.keys(afterProps)) {
+        if (key in beforeProps)
+            continue;
+        const childPath = joinPath(path, key);
+        const required = afterRequired.has(key);
+        const breaking = direction === 'input' && required;
+        changes.push({
+            path: childPath,
+            breaking,
+            reason: breaking
+                ? 'required field added'
+                : `${required ? 'required' : 'optional'} field added`,
+        });
+    }
+    if (isSchema(before.items) && isSchema(after.items)) {
+        compare(before.items, after.items, direction, `${path}[]`, beforeRoot, afterRoot, depth + 1, changes);
+    }
+}
+function compareEnums(before, after, direction, path, changes) {
+    if (!Array.isArray(before.enum) || !Array.isArray(after.enum))
+        return;
+    const beforeValues = before.enum.map((v) => JSON.stringify(v));
+    const afterValues = new Set(after.enum.map((v) => JSON.stringify(v)));
+    const beforeSet = new Set(beforeValues);
+    const removed = beforeValues.filter((v) => !afterValues.has(v));
+    const added = after.enum
+        .map((v) => JSON.stringify(v))
+        .filter((v) => !beforeSet.has(v));
+    if (removed.length > 0) {
+        changes.push({
+            path,
+            // A value the caller may still send is now rejected; a value the caller
+            // will simply never see again is not their problem.
+            breaking: direction === 'input',
+            reason: `enum values removed: ${removed.join(', ')}`,
+        });
+    }
+    if (added.length > 0) {
+        changes.push({
+            path,
+            // A new value in a response reaches consumers that never handled it.
+            breaking: direction === 'output',
+            reason: `enum values added: ${added.join(', ')}`,
+        });
+    }
+}
+/**
+ * Diff two schemas, either of which may be absent — a function that gained or
+ * lost an input/output entirely is a real compatibility event, not a no-op.
+ */
+export function diffSchema(before, after, direction) {
+    const hasBefore = isSchema(before);
+    const hasAfter = isSchema(after);
+    if (!hasBefore && !hasAfter)
+        return [];
+    if (!hasBefore && hasAfter) {
+        const required = requiredSet(after);
+        const breaking = direction === 'input' && required.size > 0;
+        return [
+            {
+                path: '',
+                breaking,
+                reason: breaking
+                    ? `${direction} schema added with required fields: ${[...required].join(', ')}`
+                    : `${direction} schema added`,
+            },
+        ];
+    }
+    if (hasBefore && !hasAfter) {
+        return [
+            {
+                path: '',
+                breaking: direction === 'output',
+                reason: `${direction} schema removed`,
+            },
+        ];
+    }
+    const changes = [];
+    compare(before, after, direction, '', before, after, 0, changes);
+    return changes;
+}

package/dist/src/utils/serialize-meta-ts.js

@@ -3,7 +3,7 @@ export function serializeMetaTS({ jsonImportPath, supportsImportAttributes, pikk
         ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
         : `import metaData from '${jsonImportPath}'`;
     const serializedOutput = [];
-    serializedOutput.push("import { pikkuState } from '@pikku/core/ecosystem'");
+    serializedOutput.push("import { pikkuState } from '@pikku/core/state'");
     serializedOutput.push(`import { ${metaTypeName} } from '${metaTypeImport}'`);
     serializedOutput.push(importStatement);
     serializedOutput.push('');

package/dist/src/utils/serialize-schemas.d.ts

@@ -1,4 +1,4 @@
-import type { JSONValue } from '@pikku/core';
+import type { JSONValue } from '@pikku/core/utils';
 import type { CLILogger } from '../services/cli-logger.service.js';
 export declare function saveSchemas(logger: CLILogger, schemaParentDir: string, schemas: Record<string, JSONValue>, requiredSchemas: Set<string>, supportsImportAttributes: boolean, packageName?: string | null, 
 /** Names the set in log output — there is more than one now (app, scenario). */

package/dist/src/utils/surface-diff.d.ts

@@ -0,0 +1,35 @@
+import type { Surface, WiringCategory } from './surface.js';
+/**
+ * Turn two surfaces into the release verdict and the reasons behind it.
+ *
+ * The three rules, in order: anything a client depended on that is gone or
+ * tightened is **major**; anything new or compatibly loosened is **minor**;
+ * a surface that did not move at all is **patch** — the release is internal
+ * work, which is the only thing left for it to be.
+ */
+export type Verdict = 'major' | 'minor' | 'patch';
+export type ChangeKind = 'function' | WiringCategory;
+export type ChangeStatus = 'added' | 'removed' | 'modified';
+export interface SurfaceChange {
+    kind: ChangeKind;
+    id: string;
+    status: ChangeStatus;
+    breaking: boolean;
+    reasons: string[];
+}
+export interface SurfaceChanges {
+    schemaVersion: number;
+    generatedAt: string;
+    /** The `--against` value, recorded so the artifact says what it is relative to. */
+    baseline: string;
+    verdict: Verdict;
+    summary: {
+        breaking: number;
+        added: number;
+        removed: number;
+        modified: number;
+    };
+    changes: SurfaceChange[];
+}
+export declare const CHANGES_SCHEMA_VERSION = 1;
+export declare function computeSurfaceDiff(before: Surface, after: Surface, baseline: string): SurfaceChanges;