@pikku/core 0.12.135 → 0.12.137

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.12.137
+
+### Patch Changes
+
+- 0c865d9: Changes and changesets replace milestones. The changes commands run on a local queue when the checkout has no fabric project; `pikku changes next` routes to a changes, upgrade or knowledge agent and merges finished changesets. A changeset that creates or alters a table, or has 6 or more changes, needs a plan at `knowledge/plans/<changeset>.plan.json` (anything else goes to an optional judge at `PIKKU_PLAN_JUDGE_URL`), and `changes done` holds it to that plan. `pikku knowledge gaps` replaces `knowledge next`/`reconcile`, and also reports code a merged plan built that is gone and notes that were deleted.
+- c36b066: Scenario coverage moves into OSS. `@pikku/core/scenario/coverage` adds `readScenarioCoverage`, which reports the lines no scenario reaches, the mutations no scenario drives, and the pages scenarios open. It is exposed through `pikku scenario coverage`, `console:getScenarioCoverage`, and a "Not tested by any scenario" card on the Scenarios page. `LocalMetaService.getRpcMeta` now reads the `.internal.gen.json` file that codegen actually writes.
+- 0963b73: Every scope tree now records where it came from: `origin` on `ScopeDefinitionMeta` is `{ kind: 'app' }` for the app's own `defineScope`, `{ kind: 'generated' }` for a tree the CLI wrote into the project (a `.gen.ts`, or the `app` root derived from personas), and `{ kind: 'addon', package, displayName }` for one an installed addon declared. An addon's build stamps its own package and display name on its trees, and the host keeps that name while recording the package it actually installed. `MetaService.getScopesMeta()` reads the result, and the console's all-meta payload carries it as `scopes`.
+
+  The console's Scopes page becomes **Permissions** and is grouped by that origin: the app's own permissions first, then what Pikku generated into the project, then one card per addon (Pikku's own before third-party, each alphabetical), each card folding to its header — the app's own starts open, every addon's starts folded, and any search or filter opens them all. Above the cards, two filters narrow the page to what one role is given (or to what no role is given yet) and to one source. A permission group no longer says "Not part of any role yet" above lines that are each given to a role.
+
+## 0.12.136
+
+### Patch Changes
+
+- 149faae: Webhook `receive` steps lose their boilerplate. `pikkuWebhookReceive` (from `#pikku/trigger` or `#pikku/addon/trigger`) declares one: it is public, typed to the raw request with a required `http`, and never registered as an RPC, and the inspector rejects a `receive` declared with any other wrapper. `parseJson` (in `@pikku/core/utils`, generated as `#pikku/utils` and `#pikku/addon/utils`) parses text or bytes and answers a body that is not JSON with a 400. A webhook source whose `method` includes `'head'` answers HEAD probes itself with a 200.
+
+  `receive` no longer returns `{ respond }`: a handshake returns nothing and writes its answer to `http.response`, like any other HTTP function. The webhook route no longer returns a fetch `Response` either. An HTTP function that returns nothing is now answered with whatever status its response has (200 unless it set another), no longer a forced 204. A webhook receive is also left out of contract versioning, since nothing but its own route calls it.
+
 ## 0.12.135
 
 ### Patch Changes

package/dist/analytics/analytics.types.d.ts

@@ -8,6 +8,7 @@ import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core
  * events carry more than a fixed set of props.
  */
 export type AnalyticsEventBase = {
+    /** The event name, as declared in `defineAnalyticsEvents`. */
     name: string;
 } & Record<string, unknown>;
 export interface AnalyticsEventInput {
@@ -20,8 +21,11 @@ export interface AnalyticsEventInput {
  * which is what makes an unauthenticated ingest safe to expose.
  */
 export interface AnalyticsIdentity {
+    /** The session's user id, or null for a visitor with no session. */
     userId: string | null;
+    /** The session's organization, when it has one. */
     orgId?: string;
+    /** The pikku user the session resolves to; absent without a session. */
     pikkuUserId?: string;
     /**
      * Identifiers a destination keys on that pikku does not mint — GA4's
@@ -80,14 +84,23 @@ resolved?: Pick<AnalyticsIdentity, 'vendorIds' | 'consent' | 'anonymousId'>) =>
  * through, so a sink never has to trust — or re-derive — any of them.
  */
 export interface AnalyticsRecord {
+    /** The event name. */
     name: string;
+    /** The validated props the event carried. */
     props?: Record<string, unknown>;
+    /** When the server accepted the event, as an ISO timestamp. */
     occurredAt: string;
+    /** When a browser says it happened, in epoch milliseconds; only on relayed events. */
     at?: number;
+    /** Who the event is attributed to, stamped from the session and cookies. */
     userIdentity: AnalyticsIdentity;
+    /** The trace the emitting invocation belongs to. */
     traceId?: string;
+    /** The function that recorded the event, when one did. */
     functionId?: string;
+    /** The kind of wire the event came in on. */
     wireType?: PikkuWiringTypes;
+    /** `client` when relayed from a browser, `server` when a function recorded it. */
     source: 'server' | 'client';
 }
 /**
@@ -100,6 +113,7 @@ export interface AnalyticsRecord {
  * to implement and every caller had to choose between.
  */
 export interface AnalyticsService {
+    /** Delivers one batch of accepted records; a rejection is logged, never surfaced to the caller. */
     write(batch: AnalyticsRecord[]): Promise<void>;
 }
 /**
@@ -111,7 +125,9 @@ export interface AnalyticsService {
  * should look like once it gets there is the sink's, and lives in its mapper.
  */
 export interface AnalyticsSink {
+    /** The destination the filtered records are written to. */
     service: AnalyticsService;
+    /** Returns true for the records this destination should get; omit to send everything. */
     accepts?: (record: AnalyticsRecord) => boolean;
 }
 /**
@@ -119,6 +135,7 @@ export interface AnalyticsSink {
  * beacon is free to omit `at`.
  */
 export interface AnalyticsClientContext {
+    /** When the browser says the event happened, in epoch milliseconds. */
     at?: number;
 }
 /**
@@ -127,8 +144,11 @@ export interface AnalyticsClientContext {
  * narrow `Events` in its own `SingletonServices`.
  */
 export interface AnalyticsLog<Events extends AnalyticsEventBase = AnalyticsEventBase> {
+    /** Buffers an event for the invocation; pass `client` when relaying one from a browser. */
     record(event: Events, client?: AnalyticsClientContext): Promise<void>;
+    /** Writes what is buffered to the service now, rather than when the invocation ends. */
     flush(): Promise<void>;
+    /** Flushes and stops accepting events; called for you when the invocation ends. */
     close(): Promise<void>;
 }
 /**

package/dist/analytics/anonymous-analytics-identity.d.ts

@@ -19,5 +19,7 @@ export interface AnonymousAnalyticsIdentityOptions {
  * browser script needs it, and a cookie scripts cannot touch is both harder to
  * misuse and not subject to the seven-day cap browsers place on script-set
  * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const anonymousAnalyticsIdentity: (options?: AnonymousAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

package/dist/analytics/anonymous-analytics-identity.js

@@ -14,6 +14,8 @@ const DEFAULT_COOKIE = {
  * browser script needs it, and a cookie scripts cannot touch is both harder to
  * misuse and not subject to the seven-day cap browsers place on script-set
  * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const anonymousAnalyticsIdentity = (options = {}) => {
     return (wire, resolved) => {

package/dist/analytics/compose-analytics-identity.d.ts

@@ -10,5 +10,7 @@ import type { AnalyticsIdentityResolver } from './analytics.types.js';
  *
  * A later resolver wins a key it sets, so a minter's freshly created id
  * replaces the absent one the cookie reader could not find.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const composeAnalyticsIdentity: (...resolvers: AnalyticsIdentityResolver[]) => AnalyticsIdentityResolver;

package/dist/analytics/compose-analytics-identity.js

@@ -9,6 +9,8 @@
  *
  * A later resolver wins a key it sets, so a minter's freshly created id
  * replaces the absent one the cookie reader could not find.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const composeAnalyticsIdentity = (...resolvers) => {
     return (wire, initial) => {

package/dist/analytics/cookie-analytics-identity.d.ts

@@ -20,5 +20,7 @@ export interface CookieAnalyticsIdentityOptions {
  * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
  * worker have no browser behind them, so any vendor id they produced would be
  * invented.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const cookieAnalyticsIdentity: (options: CookieAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

package/dist/analytics/cookie-analytics-identity.js

@@ -9,6 +9,8 @@ const DENIALS = new Set(['0', 'false', 'denied', 'deny', 'no']);
  * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
  * worker have no browser behind them, so any vendor id they produced would be
  * invented.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const cookieAnalyticsIdentity = (options) => {
     return (wire) => {

package/dist/analytics/define-analytics-events.d.ts

@@ -7,6 +7,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
  * and saying so here fails at the declaration rather than in generated code.
  */
 export type AnalyticsEventPropsSchema = StandardSchemaV1 & {
+    /** The object schema's fields, which the CLI reads to list an event's props. */
     shape: Record<string, unknown>;
 };
 /** Events keyed by name; each value is the schema for that event's props. */
@@ -18,5 +19,7 @@ export type AnalyticsEventDefinitions = Record<string, AnalyticsEventPropsSchema
  * It must stay an exported const — the schema pipeline reads the value by name.
  * It registers nothing at runtime: where events go is an `AnalyticsService` on
  * singleton services.
+ *
+ * @example snippet: analyticsEvents
  */
 export declare const defineAnalyticsEvents: <const Events extends AnalyticsEventDefinitions>(events: Events) => Events;

package/dist/analytics/define-analytics-events.js

@@ -5,5 +5,7 @@
  * It must stay an exported const — the schema pipeline reads the value by name.
  * It registers nothing at runtime: where events go is an `AnalyticsService` on
  * singleton services.
+ *
+ * @example snippet: analyticsEvents
  */
 export const defineAnalyticsEvents = (events) => events;

package/dist/analytics/fan-out-analytics.d.ts

@@ -11,5 +11,7 @@ import type { AnalyticsService, AnalyticsSink } from './analytics.types.js';
  * is down must not cost the others their events. A destination that throws is
  * reported by the caller's existing flush guard, which already treats analytics
  * as best-effort.
+ *
+ * @example snippet: shopServices
  */
 export declare const fanOutAnalytics: (sinks: ReadonlyArray<AnalyticsSink | AnalyticsService>) => AnalyticsService;

package/dist/analytics/fan-out-analytics.js

@@ -10,6 +10,8 @@
  * is down must not cost the others their events. A destination that throws is
  * reported by the caller's existing flush guard, which already treats analytics
  * as best-effort.
+ *
+ * @example snippet: shopServices
  */
 export const fanOutAnalytics = (sinks) => {
     const resolved = sinks.map((sink) => 'service' in sink ? sink : { service: sink });

package/dist/analytics/logger-analytics-service.d.ts

@@ -9,6 +9,8 @@ import type { AnalyticsRecord, AnalyticsService } from './analytics.types.js';
  */
 export declare class LoggerAnalyticsService implements AnalyticsService {
     private readonly logger;
+    /** @param logger Receives each event at `debug`. */
     constructor(logger: Logger);
+    /** Logs each record in the batch at `debug`. */
     write(batch: AnalyticsRecord[]): Promise<void>;
 }

package/dist/analytics/logger-analytics-service.js

@@ -7,9 +7,11 @@
  */
 export class LoggerAnalyticsService {
     logger;
+    /** @param logger Receives each event at `debug`. */
     constructor(logger) {
         this.logger = logger;
     }
+    /** Logs each record in the batch at `debug`. */
     async write(batch) {
         for (const event of batch) {
             this.logger.debug(`analytics: ${event.name}`, {

package/dist/analytics/mint-cookie.d.ts

@@ -10,6 +10,7 @@ export interface MintCookieOptions {
      * is answered has already done the thing the send gate was meant to prevent.
      */
     requires?: string[];
+    /** What the visitor agreed to, as resolved by an earlier resolver; `requires` is checked against it. */
     consent?: Record<string, boolean>;
     /**
      * Replace the cookie already on the device rather than returning it.
@@ -37,8 +38,14 @@ export interface MintCookieOptions {
  * has been sent; a cron task and a queue worker have no browser to store it,
  * and a stream's headers are long gone. Both return undefined rather than
  * pretending.
+ *
+ * @example snippet: mintVendorCookie
  */
 export declare const mintCookie: (wire: AnyWire, name: string, options: MintCookieOptions, mint: () => string) => string | undefined;
-/** Cryptographically random digits, the shape both vendor formats use. */
+/**
+ * Cryptographically random digits, the shape both vendor formats use.
+ *
+ * @example snippet: mintVendorCookie
+ */
 export declare const randomDigits: (length: number) => string;
 export {};

package/dist/analytics/mint-cookie.js

@@ -21,11 +21,11 @@ const permitted = (requires, consent) => {
  * has been sent; a cron task and a queue worker have no browser to store it,
  * and a stream's headers are long gone. Both return undefined rather than
  * pretending.
+ *
+ * @example snippet: mintVendorCookie
  */
 export const mintCookie = (wire, name, options, mint) => {
-    const existing = options.overwrite
-        ? null
-        : wire.http?.request?.cookie(name);
+    const existing = options.overwrite ? null : wire.http?.request?.cookie(name);
     if (existing)
         return existing;
     const cache = minted.get(wire) ?? new Map();
@@ -43,7 +43,11 @@ export const mintCookie = (wire, name, options, mint) => {
     minted.set(wire, cache);
     return value;
 };
-/** Cryptographically random digits, the shape both vendor formats use. */
+/**
+ * Cryptographically random digits, the shape both vendor formats use.
+ *
+ * @example snippet: mintVendorCookie
+ */
 export const randomDigits = (length) => {
     const bytes = new Uint8Array(length);
     crypto.getRandomValues(bytes);

package/dist/function/function-meta.types.d.ts

@@ -49,6 +49,11 @@ export type FunctionRuntimeMeta = {
      * everywhere else, so it is never network-callable.
      */
     scenarioStep?: boolean;
+    /**
+     * A webhook source's `receive` step, declared with `pikkuWebhookReceive`.
+     * Only its source's route runs it, so it is never RPC-callable.
+     */
+    webhookReceive?: boolean;
     /**
      * The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`,
      * so it is held back from the app bootstrap and from every deployed unit.

package/dist/function/functions.types.d.ts

@@ -17,12 +17,23 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessS
 };
 export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'>>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
 export type CorePikkuPermissionFactory<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
+/**
+ * Declares a permission that takes configuration, so one check serves many
+ * call sites: `hasProfileRole({ role: 'support' })`.
+ *
+ * @example snippet: permissionFactory
+ */
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
 /**
  * Renders a human-readable approval prompt for an AI agent, in place of the
  * raw tool arguments.
  */
 export type CorePikkuApprovalDescription<In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices> = (services: Services, data: In) => Promise<string>;
+/**
+ * Declares the approval prompt a function shows in place of its raw arguments.
+ *
+ * @example snippet: approvalDescription
+ */
 export declare const pikkuApprovalDescription: <In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices>(fn: CorePikkuApprovalDescription<In, Services>) => CorePikkuApprovalDescription<In, Services>;
 export type CorePikkuAuth<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
 export type CorePikkuAuthConfig<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = {

package/dist/function/functions.types.js

@@ -1,9 +1,20 @@
 export const pikkuPermission = (permission) => {
     return typeof permission === 'function' ? permission : permission.func;
 };
+/**
+ * Declares a permission that takes configuration, so one check serves many
+ * call sites: `hasProfileRole({ role: 'support' })`.
+ *
+ * @example snippet: permissionFactory
+ */
 export const pikkuPermissionFactory = (factory) => {
     return factory;
 };
+/**
+ * Declares the approval prompt a function shows in place of its raw arguments.
+ *
+ * @example snippet: approvalDescription
+ */
 export const pikkuApprovalDescription = (fn) => {
     return fn;
 };

package/dist/middleware/require-origin.d.ts

@@ -16,6 +16,8 @@ export declare const isAllowedOrigin: (requestOrigin: string | null, hostOrigin:
  * before the function body. It stops another site's page from posting to an unauthed
  * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
  * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ *
+ * @example snippet: requireOrigin
  */
 export declare const requireOrigin: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
     /** Extra allowed origins beyond the request's own host, or a resolver for them. */

package/dist/middleware/require-origin.js

@@ -33,6 +33,8 @@ export const isAllowedOrigin = (requestOrigin, hostOrigin, configuredOrigins) =>
  * before the function body. It stops another site's page from posting to an unauthed
  * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
  * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ *
+ * @example snippet: requireOrigin
  */
 export const requireOrigin = pikkuMiddlewareFactory(({ origins = [] } = {}) => pikkuMiddleware({
     name: 'requireOrigin',

package/dist/permissions.d.ts

@@ -8,6 +8,11 @@ import type { PikkuRPC } from './wirings/rpc/rpc-types.js';
 export type PermissionWire = PikkuWire<any, never, false, any, PikkuRPC, never, never>;
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 export declare const clearPermissionsCache: () => void;
+/**
+ * Applies permissions to every function, ahead of the per-function ones.
+ *
+ * @example snippet: globalPermission
+ */
 export declare const addGlobalPermission: (permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
 export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, label, }: {
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];

package/dist/permissions.js

@@ -29,6 +29,11 @@ export const clearPermissionsCache = () => {
         delete globalPermissionsCache[key];
     }
 };
+/**
+ * Applies permissions to every function, ahead of the per-function ones.
+ *
+ * @example snippet: globalPermission
+ */
 export const addGlobalPermission = (permissions, packageName = null) => {
     const state = pikkuState(packageName, 'permissions', 'global');
     if (Array.isArray(permissions)) {

package/dist/services/meta-service.d.ts

@@ -10,6 +10,7 @@ import type { FeaturesMeta } from '../wirings/workflow/scenario.types.js';
 import type { ResolvedPersona } from './personas-service.js';
 import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
 import type { FeatureFlagDefinitionsMeta } from '../wirings/flag/flag.types.js';
+import type { ScopeDefinitionsMeta } from '../wirings/scope/scope.types.js';
 import type { AnalyticsEventsMeta } from '../analytics/analytics.types.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
@@ -156,6 +157,14 @@ export interface MetaService {
      * seed granted from rather than a second one.
      */
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    /**
+     * The scope trees declared with `defineScope`, keyed by root, each carrying
+     * where it came from.
+     *
+     * The scope store holds the grantable ids; this holds what the store does
+     * not — a root's display name and which addon, if any, declared it.
+     */
+    getScopesMeta(): Promise<ScopeDefinitionsMeta>;
     /**
      * The flags declared with `defineFeatureFlags`, keyed by name.
      *
@@ -199,6 +208,7 @@ export declare class LocalMetaService implements MetaService {
     private workflowMetaCache;
     private personasMetaCache;
     private systemRolesMetaCache;
+    private scopesMetaCache;
     private featureFlagsMetaCache;
     private analyticsMetaCache;
     private featuresMetaCache;
@@ -236,6 +246,7 @@ export declare class LocalMetaService implements MetaService {
     getWorkflowMeta(): Promise<WorkflowsMeta>;
     getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    getScopesMeta(): Promise<ScopeDefinitionsMeta>;
     getFeatureFlagsMeta(): Promise<FeatureFlagDefinitionsMeta>;
     getAnalyticsMeta(): Promise<AnalyticsEventsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;

package/dist/services/meta-service.js

@@ -16,6 +16,7 @@ export class LocalMetaService {
     workflowMetaCache = null;
     personasMetaCache = null;
     systemRolesMetaCache = null;
+    scopesMetaCache = null;
     featureFlagsMetaCache = null;
     analyticsMetaCache = null;
     featuresMetaCache = null;
@@ -115,6 +116,7 @@ export class LocalMetaService {
         this.workflowMetaCache = null;
         this.personasMetaCache = null;
         this.systemRolesMetaCache = null;
+        this.scopesMetaCache = null;
         this.featureFlagsMetaCache = null;
         this.analyticsMetaCache = null;
         this.featuresMetaCache = null;
@@ -216,7 +218,7 @@ export class LocalMetaService {
         if (this.rpcMetaCache)
             return this.rpcMetaCache;
         try {
-            const content = await this.readFile('rpc/pikku-rpc-wirings-meta.gen.json');
+            const content = await this.readFile('rpc/pikku-rpc-wirings-meta.internal.gen.json');
             this.rpcMetaCache = content ? JSON.parse(content) : {};
             return this.rpcMetaCache;
         }
@@ -278,6 +280,13 @@ export class LocalMetaService {
         this.systemRolesMetaCache = content ? JSON.parse(content) : {};
         return this.systemRolesMetaCache;
     }
+    async getScopesMeta() {
+        if (this.scopesMetaCache)
+            return this.scopesMetaCache;
+        const content = await this.readFile('scopes/pikku-scopes-meta.gen.json');
+        this.scopesMetaCache = content ? JSON.parse(content) : {};
+        return this.scopesMetaCache;
+    }
     async getFeatureFlagsMeta() {
         if (this.featureFlagsMetaCache)
             return this.featureFlagsMetaCache;

package/dist/utils.d.ts

@@ -4,6 +4,13 @@ export declare const closeWireServices: (logger: Logger, wireServices: WireServi
 export declare const createWeakUID: () => string;
 export declare const isSerializable: (data: any) => boolean;
 export declare const getTagGroups: <T>(tagGroups: Record<string, T>, tag: string) => T[];
+/**
+ * `JSON.parse` of text or UTF-8 bytes, refusing anything that is not JSON with
+ * a 400 rather than a 500.
+ *
+ * @example snippet: pikkuWebhookReceive
+ */
+export declare const parseJson: <T = any>(input: string | Uint8Array) => T;
 export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) => readonly T[];
 /** Stops addon package services first, then the parent singleton services. */
 export declare const stopSingletonServices: () => Promise<void>;

package/dist/utils.js

@@ -1,4 +1,5 @@
 import { getSingletonServices, getAllPackageStates } from './pikku-state.js';
+import { BadRequestError } from './errors/errors.js';
 export const closeWireServices = async (logger, wireServices) => {
     await Promise.all(Object.values(wireServices).map(async (service) => {
         if (service?.close) {
@@ -44,6 +45,21 @@ export const getTagGroups = (tagGroups, tag) => {
     }
     return results;
 };
+/**
+ * `JSON.parse` of text or UTF-8 bytes, refusing anything that is not JSON with
+ * a 400 rather than a 500.
+ *
+ * @example snippet: pikkuWebhookReceive
+ */
+export const parseJson = (input) => {
+    const text = typeof input === 'string' ? input : new TextDecoder().decode(input);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new BadRequestError('Body is not valid JSON');
+    }
+};
 const EMPTY_ARRAY = Object.freeze([]);
 export const freezeDedupe = (arr) => {
     if (!arr || arr.length === 0)

package/dist/wirings/flag/define-feature-flags.d.ts

@@ -16,18 +16,6 @@ import type { CoreFeatureFlags } from './flag.types.js';
  * the same reason: a mid-deploy revocation is not something a code edit should
  * be able to cause.
  *
- * @example
- * ```typescript
- * defineFeatureFlags({
- *   takeInBike: {
- *     description: 'Book a bike in at the counter',
- *     anyOf: ['bikes:intake'],
- *   },
- *   aiAssistant: {
- *     description: 'The assistant panel',
- *     // no anyOf — the switch is the whole answer
- *   },
- * })
- * ```
+ * @example snippet: defineFeatureFlags
  */
 export declare const defineFeatureFlags: (_config: CoreFeatureFlags) => void;

package/dist/wirings/flag/define-feature-flags.js

@@ -15,18 +15,6 @@
  * the same reason: a mid-deploy revocation is not something a code edit should
  * be able to cause.
  *
- * @example
- * ```typescript
- * defineFeatureFlags({
- *   takeInBike: {
- *     description: 'Book a bike in at the counter',
- *     anyOf: ['bikes:intake'],
- *   },
- *   aiAssistant: {
- *     description: 'The assistant panel',
- *     // no anyOf — the switch is the whole answer
- *   },
- * })
- * ```
+ * @example snippet: defineFeatureFlags
  */
 export const defineFeatureFlags = (_config) => { };

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

@@ -215,9 +215,7 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             await applyWebResponse(http.response, result);
         }
         else if (result === undefined || result === null) {
-            if (!statusSetByRoute) {
-                http?.response?.status(204);
-            }
+            // Nothing returned: the response keeps the status the function left on it.
         }
         else if (route.returnsJSON === false) {
             http?.response?.arrayBuffer(result);

package/dist/wirings/persona/persona-app-scopes.js

@@ -57,5 +57,6 @@ export const buildAppScopeDefinition = (personas) => {
         displayName: 'Apps',
         description: 'Which frontend a person may sign in to',
         scopes,
+        origin: { kind: 'generated' },
     };
 };

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

@@ -1,4 +1,4 @@
 export { defineScope } 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/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/webhook-source-runner.d.ts

@@ -14,9 +14,9 @@ export declare const subscribedWebhookEvents: (source: string) => string[];
  */
 export declare const receiveWebhookSourceRequest: (sourceName: string, wire: {
     http?: PikkuHTTP;
-}) => Promise<Response | {
+}) => Promise<{
     received: number;
-}>;
+} | void>;
 /** The `pikku-incoming-webhooks` worker: runs the trigger an event was queued for. Throws so the queue retries. */
 export declare const dispatchWebhookSourceJob: (job: WebhookSourceJob) => Promise<void>;
 export type WebhookSourceOutcome = {

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

@@ -1,5 +1,6 @@
 import { getSingletonServices, pikkuState } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+import { parseJson } from '../../utils.js';
 import { PikkuMissingMetaError, UnauthorizedError, } from '../../errors/errors.js';
 import { timingSafeStringEqual, verifyHmacSignature, verifyPublicKeySignature, } from '../../utils/hmac.js';
 import { webhookSecretCredentialName } from './webhook-source.types.js';
@@ -37,11 +38,11 @@ const getSourceMeta = (source) => {
     }
     return meta;
 };
-const runSourceStep = (singletonServices, source, funcId, data) => runPikkuFunc('trigger', source, funcId, {
+const runSourceStep = (singletonServices, source, funcId, data, wire = {}) => runPikkuFunc('trigger', source, funcId, {
     singletonServices,
     auth: false,
     data: () => data,
-    wire: {},
+    wire,
 });
 const readRequest = async (http) => {
     const request = http?.request;
@@ -134,31 +135,30 @@ export const receiveWebhookSourceRequest = async (sourceName, wire) => {
     const meta = getSourceMeta(sourceName);
     const store = singletonServices.triggerSourceStore;
     if (store && !(await store.getTriggerSource(sourceName))?.enabled) {
-        return new Response(null, { status: 404 });
+        wire.http?.response?.status(404);
+        return;
     }
     const source = pikkuState(null, 'trigger', 'webhookSources').get(sourceName);
     const request = await readRequest(wire.http);
+    // A HEAD is a provider checking the URL is live. It carries no events, so
+    // it is answered here rather than in every source's `receive`.
+    if (request.method.toLowerCase() === 'head') {
+        wire.http?.response?.status(200);
+        return;
+    }
     const verified = await verifyRequest(source, request, singletonServices);
     const result = meta.receive
-        ? await runSourceStep(singletonServices, sourceName, meta.receive, request)
+        ? await runSourceStep(singletonServices, sourceName, meta.receive, request, wire)
         : {
             events: [
                 {
                     name: '',
-                    data: request.body.length
-                        ? JSON.parse(new TextDecoder().decode(request.body))
-                        : undefined,
+                    data: request.body.length ? parseJson(request.body) : undefined,
                 },
             ],
         };
-    if ('respond' in result) {
-        const { status, body, headers } = result.respond;
-        const text = body === undefined
-            ? null
-            : typeof body === 'string'
-                ? body
-                : JSON.stringify(body);
-        return new Response(text, { status, headers });
+    if (!result) {
+        return;
     }
     if (!verified && result.events.length > 0) {
         throw new UnauthorizedError(`The ${sourceName} webhook source received events in an unsigned request`);

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -20,16 +20,12 @@ export type WebhookRequest = {
     url: string;
     query: Record<string, string>;
 };
+/**
+ * The events a request carries. A handshake returns nothing and answers
+ * through `http.response` instead, which is sent only then.
+ */
 export type WebhookReceiveResult = {
     events: TriggerEvent[];
-}
-/** A handshake, such as Slack's `url_verification`: answered directly, nothing is dispatched. */
- | {
-    respond: {
-        status: number;
-        body?: unknown;
-        headers?: Record<string, string>;
-    };
 };
 export type WebhookSourceMethod = 'post' | 'put' | 'get' | 'head';
 /** Whatever `setup` wants back on the next deploy, for providers whose endpoints cannot be found by label. */
@@ -128,7 +124,7 @@ export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchem
      */
     verify?: WebhookVerify;
     /** Omitted: the JSON body is one event dispatched to the trigger named `<name>`. */
-    receive?: SourceFunction<WebhookRequest, WebhookReceiveResult>;
+    receive?: SourceFunction<WebhookRequest, WebhookReceiveResult | void>;
     check?: SourceFunction<WebhookLifecycleInput, WebhookCheckResult>;
     setup?: SourceFunction<WebhookLifecycleInput, WebhookSetupResult>;
     teardown?: SourceFunction<WebhookTeardownInput, WebhookTeardownResult>;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.135",
+  "version": "0.12.137",
   "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",

package/src/public-surface.json

@@ -99,6 +99,10 @@
     "resolveFeatureScenarios",
     "resolveScenarioSurfaces"
   ],
+  "./scenario/coverage": [
+    "aggregateScenarioCoverageGaps",
+    "readScenarioCoverage"
+  ],
   "./workflow/timeline": [
     "buildRunTimeline",
     "reconstructFinalState",
@@ -572,6 +576,7 @@
     "isSerializable",
     "isVersionedId",
     "parseDurationString",
+    "parseJson",
     "parseVersionedId",
     "pikkuServerLifecycle",
     "stopSingletonServices"