@pikku/core 0.12.136 → 0.12.138

package/dist/wirings/scope/index.d.ts

@@ -1,4 +1,4 @@
-export { defineScope } from './define-scope.js';
+export { defineScope, declareScopes } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
-export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, } from './scope.types.js';
+export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, ScopeOrigin, } from './scope.types.js';
 export { hasScopes, verifyScopes } from '../../scopes.js';

package/dist/wirings/scope/index.js

@@ -1,3 +1,3 @@
-export { defineScope } from './define-scope.js';
+export { defineScope, declareScopes } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
 export { hasScopes, verifyScopes } from '../../scopes.js';

package/dist/wirings/scope/scope.types.d.ts

@@ -21,12 +21,26 @@ export type ScopeNodeMeta = {
     description?: string;
     scopes?: Record<string, ScopeNodeMeta>;
 };
+/**
+ * Who put a scope tree into the app: the app's own `defineScope`, a file the
+ * CLI generated into the project, or an installed addon.
+ */
+export type ScopeOrigin = {
+    kind: 'app';
+} | {
+    kind: 'generated';
+} | {
+    kind: 'addon';
+    package: string;
+    displayName?: string;
+};
 export type ScopeDefinitionMeta = {
     name: string;
     displayName?: string;
     description?: string;
     scopes?: Record<string, ScopeNodeMeta>;
     sourceFile?: string;
+    origin?: ScopeOrigin;
 };
 export type ScopeDefinitions = ScopeDefinitionMeta[];
 export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>;

package/dist/wirings/scope/validate-scope-definitions.js

@@ -67,6 +67,7 @@ export function validateAndBuildScopeDefinitionsMeta(definitions) {
             description: def.description,
             scopes: def.scopes,
             sourceFile: def.sourceFile,
+            origin: def.origin,
         };
     }
     return meta;

package/dist/wirings/trigger/trigger-runner.js

@@ -43,7 +43,9 @@ export async function setupTrigger({ name, input, onTrigger, }) {
         trigger: {
             invoke: (data) => {
                 singletonServices.logger.info(`Trigger fired: ${name}`);
-                onTrigger(data);
+                // `invoke` is typed void for trigger sources, so a rejection from the
+                // trigger function is logged here rather than left unhandled.
+                Promise.resolve(onTrigger(data)).catch((e) => singletonServices.logger.error(`Trigger '${name}' handler failed: ${e?.message ?? e}`));
             },
         },
     };

package/dist/wirings/trigger/webhook-source-runner.js

@@ -63,6 +63,9 @@ const readRequest = async (http) => {
     };
 };
 const signedWith = async (verify, request, secret, services) => {
+    // Fail closed: an empty secret never verifies, whatever the scheme.
+    if (!secret)
+        return false;
     if (typeof verify === 'function') {
         return await verify(request, secret, services);
     }
@@ -72,14 +75,14 @@ const signedWith = async (verify, request, secret, services) => {
     };
     if ('hmac' in verify) {
         const { header: name, prefix, algorithm, encoding, secretEncoding, } = verify.hmac;
-        return verifyHmacSignature(secret, header(name, prefix), algorithm, request.body, encoding, secretEncoding);
+        return await verifyHmacSignature(secret, header(name, prefix), algorithm, request.body, encoding, secretEncoding);
     }
     if ('token' in verify) {
         const token = header(verify.token.header, verify.token.prefix);
         return !!token && timingSafeStringEqual(token, secret);
     }
     const { header: name, ...options } = verify.publicKey;
-    return verifyPublicKeySignature(secret, header(name), request.body, options);
+    return await verifyPublicKeySignature(secret, header(name), request.body, options);
 };
 /**
  * Whether the request was signed with the source's secret. A request with a

package/dist/wirings/virtual-user/virtual-user-scaffold.js

@@ -1,3 +1,4 @@
+import { readEnvVariable } from '../../env.js';
 import { BadRequestError, ForbiddenError } from '../../errors/errors.js';
 import { prepareVirtualUserRun } from './prepare-virtual-user-run.js';
 import { runVirtualUser as runVirtualUserEngine } from './run-virtual-user.js';
@@ -122,7 +123,7 @@ const refuseInProduction = (personaId, disposition, config, environments, enviro
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export const startVirtualUserRun = async ({ store, personas, config, environments, environment = process.env.PIKKU_ENV, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
+export const startVirtualUserRun = async ({ store, personas, config, environments, environment = readEnvVariable('PIKKU_ENV'), persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
     const runStore = requireVirtualUserRunStore(store);
     const persona = runnablePersona(personas, personaId);
     const disposition = (requested ??
@@ -251,7 +252,7 @@ export const serializeVirtualUserSchedule = (schedule, personas) => {
  * keeps what it had: enabling a row saved earlier as adversarial is refused
  * just as saving one would be.
  */
-export const writeVirtualUserSchedule = async ({ store, personas, persona, enabled, disposition, goals, budget, minIntervalMs, maxIntervalMs, nextRunAt, config, environments, environment = process.env.PIKKU_ENV, }) => {
+export const writeVirtualUserSchedule = async ({ store, personas, persona, enabled, disposition, goals, budget, minIntervalMs, maxIntervalMs, nextRunAt, config, environments, environment = readEnvVariable('PIKKU_ENV'), }) => {
     const scheduleStore = requireVirtualUserScheduleStore(store);
     const declared = runnablePersona(personas, persona);
     const current = enabled === undefined || disposition === undefined

package/dist/wirings/workflow/scenario-coverage.d.ts

@@ -0,0 +1,70 @@
+import type { MetaService } from '../../services/meta-service.js';
+/** Per-function line coverage as `pikku scenario run --coverage` records it. */
+export interface ScenarioFunctionCoverage {
+    name: string;
+    sourceFile: string;
+    status: 'covered' | 'partial' | 'uncovered' | 'unknown';
+    totalLines: number;
+    missedLines: number[];
+}
+/** The file `pikku scenario run --coverage` writes to `.pikku/coverage/scenario-coverage.json`. */
+export interface ScenarioCoverageFile {
+    generatedAt: string;
+    environment: string;
+    scenarios: Record<string, {
+        functions?: ScenarioFunctionCoverage[];
+        summary?: {
+            total?: number;
+        };
+    }>;
+}
+/** A function with lines no scenario reaches. */
+export interface ScenarioCoverageGap {
+    function: string;
+    sourceFile: string;
+    status: 'uncovered' | 'partial';
+    /** Collapsed line ranges, e.g. `["L14-31", "L42"]`. */
+    missing: string[];
+    missedLines: number;
+    totalLines: number;
+}
+/** A mutation a user can perform that no scenario drives. */
+export interface UncoveredMutation {
+    id: string;
+    sourceFile?: string;
+}
+export interface ScenarioCoverage {
+    /** Line coverage across every scenario; `null` until a run with `--coverage` has been recorded. */
+    api: {
+        generatedAt: string;
+        environment: string;
+        pct: number;
+        covered: number;
+        total: number;
+        gaps: ScenarioCoverageGap[];
+    } | null;
+    mutations: {
+        required: number;
+        covered: number;
+        uncovered: UncoveredMutation[];
+    };
+    /** Paths a scenario opens; `unvisited` only when the caller knows the app's routes. */
+    routes: {
+        visited: string[];
+        total: number | null;
+        unvisited: string[] | null;
+    };
+}
+/** Lines no scenario reaches, per function: a line counts as covered if any scenario hit it. */
+export declare function aggregateScenarioCoverageGaps(file: ScenarioCoverageFile): ScenarioCoverageGap[];
+/**
+ * Everything a scenario measures about the app, read from the meta codegen and
+ * `pikku scenario run --coverage` leave in `.pikku`.
+ *
+ * A mutation is a function a user changes something with: a mutating HTTP
+ * route, or an exposed RPC whose name opens with a mutating verb. Only RPCs a
+ * scenario can drive are required.
+ */
+export declare function readScenarioCoverage(metaService: MetaService, { routes }?: {
+    routes?: string[];
+}): Promise<ScenarioCoverage>;

package/dist/wirings/workflow/scenario-coverage.js

@@ -0,0 +1,159 @@
+const MUTATING_METHODS = new Set(['post', 'put', 'patch', 'delete']);
+const MUTATING_VERB = /^(create|add|new|update|edit|set|change|rename|delete|remove|destroy|archive|restore|assign|unassign|submit|approve|reject|cancel|complete|start|stop|send|invite|upload|register|book|reserve|claim|join|leave|mark|toggle|move|reorder|import|apply|save|record|log|generate|grant|revoke|link|unlink|publish|unpublish|enable|disable|accept|decline|resend|retry|sync|trigger|run|provision|deploy|purchase|checkout|pay|refund|subscribe|unsubscribe|reset|confirm|rotate|attach|detach|duplicate|clone|merge|split|schedule|reschedule|dispatch|finish|close|reopen|promote|demote|transfer|swap|seed|clear|cleanup|refresh|rebuild|install|uninstall|connect|disconnect|activate|deactivate|block|unblock|pin|unpin|vote|rate|comment|reply|post)([A-Z0-9]|$)/;
+const NAVIGATION_STEPS = new Set(['opensPage']);
+const isFrameworkTagged = (tags) => (tags ?? []).some((tag) => tag === 'pikku' || tag.startsWith('pikku:'));
+const isGenerated = (sourceFile) => /\.gen\.ts$/.test(sourceFile ?? '');
+const normalisePath = (path) => path.replace(/\/+$/, '') || '/';
+const pct = (covered, total) => total === 0 ? 100 : Math.round((covered / total) * 100);
+function collapseRanges(lines) {
+    const sorted = [...new Set(lines)].sort((a, b) => a - b);
+    const ranges = [];
+    for (let i = 0; i < sorted.length;) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1)
+            j++;
+        ranges.push(sorted[i] === sorted[j] ? `L${sorted[i]}` : `L${sorted[i]}-${sorted[j]}`);
+        i = j + 1;
+    }
+    return ranges;
+}
+/** Lines no scenario reaches, per function: a line counts as covered if any scenario hit it. */
+export function aggregateScenarioCoverageGaps(file) {
+    const byFunction = new Map();
+    for (const report of Object.values(file.scenarios ?? {})) {
+        for (const fn of report.functions ?? []) {
+            if (fn.status === 'unknown' || fn.totalLines === 0)
+                continue;
+            let entry = byFunction.get(fn.name);
+            if (!entry) {
+                entry = {
+                    sourceFile: fn.sourceFile,
+                    missed: null,
+                    total: fn.totalLines,
+                };
+                byFunction.set(fn.name, entry);
+            }
+            const missed = new Set(fn.missedLines);
+            entry.missed =
+                entry.missed === null
+                    ? missed
+                    : new Set([...entry.missed].filter((line) => missed.has(line)));
+        }
+    }
+    const gaps = [];
+    for (const [name, entry] of byFunction) {
+        if (!entry.missed || entry.missed.size === 0)
+            continue;
+        const missed = [...entry.missed];
+        gaps.push({
+            function: name,
+            sourceFile: entry.sourceFile,
+            status: missed.length >= entry.total ? 'uncovered' : 'partial',
+            missing: collapseRanges(missed),
+            missedLines: missed.length,
+            totalLines: entry.total,
+        });
+    }
+    return gaps.sort((a, b) => (a.status === b.status ? 0 : a.status === 'uncovered' ? -1 : 1) ||
+        b.missedLines - a.missedLines ||
+        a.function.localeCompare(b.function));
+}
+function scenarioNodes(workflows) {
+    return Object.values(workflows).flatMap((meta) => {
+        const workflow = meta;
+        return workflow?.source === 'scenario'
+            ? Object.values(workflow.nodes ?? {})
+            : [];
+    });
+}
+/**
+ * Everything a scenario measures about the app, read from the meta codegen and
+ * `pikku scenario run --coverage` leave in `.pikku`.
+ *
+ * A mutation is a function a user changes something with: a mutating HTTP
+ * route, or an exposed RPC whose name opens with a mutating verb. Only RPCs a
+ * scenario can drive are required.
+ */
+export async function readScenarioCoverage(metaService, { routes } = {}) {
+    const [functions, http, rpc, workflows, coverageFile] = await Promise.all([
+        metaService.getFunctionsMeta(),
+        metaService.getHttpMeta(),
+        metaService.getRpcMeta(),
+        metaService.getWorkflowMeta(),
+        metaService.readFile('coverage/scenario-coverage.json'),
+    ]);
+    const nodes = scenarioNodes(workflows);
+    const driven = new Set(nodes.map((node) => node?.rpcName).filter((name) => !!name));
+    const visited = [
+        ...new Set(nodes
+            .filter((node) => node?.rpcName && NAVIGATION_STEPS.has(node.rpcName))
+            .map((node) => node.input?.['path'])
+            .filter((path) => typeof path === 'string')
+            .map(normalisePath)),
+    ].sort();
+    const invocable = new Set(Object.keys(rpc));
+    const required = new Map();
+    for (const [id, meta] of Object.entries(functions)) {
+        const funcId = meta.pikkuFuncId ?? id;
+        if (meta.functionType && meta.functionType !== 'user')
+            continue;
+        if (meta.expose === false || meta.readonly === true)
+            continue;
+        if (!MUTATING_VERB.test(funcId))
+            continue;
+        if (isFrameworkTagged(meta.tags) || isGenerated(meta.sourceFile))
+            continue;
+        if (!invocable.has(funcId))
+            continue;
+        required.set(funcId, meta.sourceFile);
+    }
+    for (const [method, wirings] of Object.entries(http)) {
+        if (!MUTATING_METHODS.has(method.toLowerCase()))
+            continue;
+        for (const route of Object.values(wirings ?? {})) {
+            const funcId = route?.pikkuFuncId;
+            if (!funcId || !invocable.has(funcId))
+                continue;
+            if (isFrameworkTagged(route.tags))
+                continue;
+            const sourceFile = functions[funcId]?.sourceFile;
+            if (isGenerated(sourceFile))
+                continue;
+            required.set(funcId, sourceFile);
+        }
+    }
+    const uncovered = [...required]
+        .filter(([id]) => !driven.has(id))
+        .map(([id, sourceFile]) => (sourceFile ? { id, sourceFile } : { id }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    let api = null;
+    if (coverageFile) {
+        const file = JSON.parse(coverageFile);
+        const total = Object.values(file.scenarios ?? {}).reduce((most, one) => Math.max(most, one?.summary?.total ?? 0), 0);
+        if (total > 0) {
+            const gaps = aggregateScenarioCoverageGaps(file);
+            api = {
+                generatedAt: file.generatedAt,
+                environment: file.environment,
+                total,
+                covered: total - gaps.length,
+                pct: pct(total - gaps.length, total),
+                gaps,
+            };
+        }
+    }
+    const known = routes ? [...new Set(routes.map(normalisePath))].sort() : null;
+    return {
+        api,
+        mutations: {
+            required: required.size,
+            covered: required.size - uncovered.length,
+            uncovered,
+        },
+        routes: {
+            visited,
+            total: known ? known.length : null,
+            unvisited: known ? known.filter((path) => !visited.includes(path)) : null,
+        },
+    };
+}

package/dist/wirings/workflow/workflow-invocation-id.js

@@ -1,16 +1,93 @@
-import { createHash } from 'node:crypto';
 const PIKKU_WORKFLOW_NAMESPACE = '70696b6b-7500-5770-9f6c-6f77000a0001';
-const parseUuid = (uuid) => Buffer.from(uuid.replace(/-/g, ''), 'hex');
+const encoder = new TextEncoder();
+const parseUuid = (uuid) => {
+    const hex = uuid.replace(/-/g, '');
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+};
 const formatUuid = (bytes) => {
-    const hex = bytes.toString('hex');
+    let hex = '';
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, '0');
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 };
+/**
+ * SHA-1 (FIPS 180-4). Web Crypto only offers an async digest and `uuidv5` is
+ * called synchronously (and is a public export), so this is a small pure-JS
+ * one. It only derives dedupe IDs, never anything secret.
+ */
+const sha1 = (message) => {
+    const padded = new Uint8Array(((message.length + 9 + 63) >> 6) << 6);
+    padded.set(message);
+    padded[message.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor((message.length * 8) / 2 ** 32));
+    view.setUint32(padded.length - 4, (message.length * 8) >>> 0);
+    let h0 = 0x67452301;
+    let h1 = 0xefcdab89;
+    let h2 = 0x98badcfe;
+    let h3 = 0x10325476;
+    let h4 = 0xc3d2e1f0;
+    const w = new Uint32Array(80);
+    const rotl = (x, n) => (x << n) | (x >>> (32 - n));
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 80; i++) {
+            w[i] = rotl(w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16], 1);
+        }
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        for (let i = 0; i < 80; i++) {
+            let f;
+            let k;
+            if (i < 20) {
+                f = (b & c) | (~b & d);
+                k = 0x5a827999;
+            }
+            else if (i < 40) {
+                f = b ^ c ^ d;
+                k = 0x6ed9eba1;
+            }
+            else if (i < 60) {
+                f = (b & c) | (b & d) | (c & d);
+                k = 0x8f1bbcdc;
+            }
+            else {
+                f = b ^ c ^ d;
+                k = 0xca62c1d6;
+            }
+            const temp = (rotl(a, 5) + f + e + k + w[i]) >>> 0;
+            e = d;
+            d = c;
+            c = rotl(b, 30) >>> 0;
+            b = a;
+            a = temp;
+        }
+        h0 = (h0 + a) >>> 0;
+        h1 = (h1 + b) >>> 0;
+        h2 = (h2 + c) >>> 0;
+        h3 = (h3 + d) >>> 0;
+        h4 = (h4 + e) >>> 0;
+    }
+    const out = new Uint8Array(20);
+    const outView = new DataView(out.buffer);
+    [h0, h1, h2, h3, h4].forEach((h, i) => outView.setUint32(i * 4, h));
+    return out;
+};
 export const uuidv5 = (name, namespace = PIKKU_WORKFLOW_NAMESPACE) => {
-    const hash = createHash('sha1')
-        .update(parseUuid(namespace))
-        .update(name, 'utf8')
-        .digest();
-    const bytes = hash.subarray(0, 16);
+    const ns = parseUuid(namespace);
+    const nameBytes = encoder.encode(name);
+    const input = new Uint8Array(ns.length + nameBytes.length);
+    input.set(ns);
+    input.set(nameBytes, ns.length);
+    const bytes = sha1(input).subarray(0, 16);
     bytes[6] = (bytes[6] & 0x0f) | 0x50;
     bytes[8] = (bytes[8] & 0x3f) | 0x80;
     return formatUuid(bytes);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.136",
+  "version": "0.12.138",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -39,6 +39,7 @@
     "./channel": "./dist/wirings/channel/index.js",
     "./workflow": "./dist/wirings/workflow/index.js",
     "./scenario": "./dist/wirings/workflow/pikku-scenario-service.js",
+    "./scenario/coverage": "./dist/wirings/workflow/scenario-coverage.js",
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
     "./actor-flow": "./dist/wirings/actor-flow/index.js",
@@ -80,6 +81,7 @@
     "./services/local-content": "./dist/services/local-content.js",
     "./services/local-content-request-handler": "./dist/services/local-content-request-handler.js",
     "./services/temporary-file-service": "./dist/services/temporary-file-service.js",
+    "./services/file-scenario-run-store": "./dist/services/file-scenario-run-store.js",
     "./crypto-utils": "./dist/crypto-utils.js",
     "./hmac": "./dist/utils/hmac.js",
     "./state": "./dist/pikku-state.js",
@@ -99,6 +101,7 @@
   },
   "devDependencies": {
     "@ag-ui/core": "0.0.57",
+    "@pikku/deploy": "^0.12.15",
     "@types/node": "^24.13.3",
     "esbuild": "~0.28.2",
     "tsx": "^4.23.12"

package/src/public-surface.json

@@ -99,6 +99,10 @@
     "resolveFeatureScenarios",
     "resolveScenarioSurfaces"
   ],
+  "./scenario/coverage": [
+    "aggregateScenarioCoverageGaps",
+    "readScenarioCoverage"
+  ],
   "./workflow/timeline": [
     "buildRunTimeline",
     "reconstructFinalState",
@@ -322,6 +326,7 @@
     "validateAndBuildCredentialDefinitionsMeta"
   ],
   "./scope": [
+    "declareScopes",
     "defineScope",
     "flattenScopeDefinitions",
     "hasScopes",
@@ -428,7 +433,6 @@
     "ACTOR_SECRET_NAME",
     "ConsoleLogger",
     "DEFAULT_WEBHOOK_RETRIES",
-    "FileScenarioRunStore",
     "InMemoryAgentRunStateService",
     "InMemoryLeaseService",
     "InMemoryQueueService",
@@ -478,8 +482,6 @@
     "pikkuRemoteScheduledJobFunc",
     "pikkuWebhookWorkerFunc",
     "renderEmail",
-    "scenarioArtifactContentType",
-    "scenarioRunSummary",
     "spy",
     "stub",
     "verifyActorSecret",
@@ -506,6 +508,11 @@
     "createLocalContentRequestHandler",
     "verifySignedContentRequest"
   ],
+  "./services/file-scenario-run-store": [
+    "FileScenarioRunStore",
+    "scenarioArtifactContentType",
+    "scenarioRunSummary"
+  ],
   "./services/temporary-file-service": [
     "TemporaryFileInstance",
     "TemporaryFileService"