@pikku/core 0.12.84 → 0.12.86

package/dist/wirings/cli/command-parser.js

@@ -1,3 +1,4 @@
+import { pikkuState } from '../../pikku-state.js';
 /** "from-plan" → "fromPlan"; the parser accepts either spelling. */
 function toCamelCase(str) {
     return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -57,6 +58,114 @@ function warnUnknownOption(typed, availableOptions, result) {
  * one error per character.
  */
 const MAX_SHORT_FLAG_CLUSTER = 64;
+function resolveOptionType(optionDef) {
+    if (optionDef.type) {
+        return optionDef.type;
+    }
+    if (typeof optionDef.default === 'boolean') {
+        return 'boolean';
+    }
+    if (typeof optionDef.default === 'number') {
+        return 'number';
+    }
+    return 'string';
+}
+/**
+ * A command's options are keys of its function's input, so the input schema
+ * already records what each one is. Reading it here means a declaration never
+ * has to repeat — or contradict — the type the function is validated against.
+ * An explicit `type` still wins, and an option the schema says nothing about
+ * (a program-level option belonging to no function input) is left untouched.
+ */
+function applySchemaOptionTypes(options, commandMeta) {
+    const properties = commandInputProperties(commandMeta);
+    if (!properties) {
+        return options;
+    }
+    const typed = { ...options };
+    for (const [name, option] of Object.entries(typed)) {
+        if (option.type) {
+            continue;
+        }
+        const schemaType = optionTypeFromSchema(properties[name]);
+        if (schemaType) {
+            typed[name] = { ...option, type: schemaType };
+        }
+    }
+    return typed;
+}
+function commandInputProperties(commandMeta) {
+    const funcMeta = pikkuState(null, 'function', 'meta')[commandMeta.pikkuFuncId];
+    const schemaName = funcMeta?.inputSchemaName;
+    if (!schemaName) {
+        return null;
+    }
+    const schema = pikkuState(funcMeta.packageName ?? null, 'misc', 'schemas').get(schemaName);
+    const properties = schema?.properties;
+    return properties && typeof properties === 'object' ? properties : null;
+}
+function optionTypeFromSchema(property) {
+    if (!property || typeof property !== 'object') {
+        return undefined;
+    }
+    // An optional field can arrive as a union with null, which is not a shape the
+    // parser can read a value into.
+    const declared = Array.isArray(property.type)
+        ? property.type.filter((entry) => entry !== 'null')[0]
+        : property.type;
+    switch (declared) {
+        case 'array':
+            return 'string[]';
+        case 'number':
+        case 'integer':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'string':
+            return 'string';
+        default:
+            return undefined;
+    }
+}
+const BOOLEAN_LITERALS = new Map([
+    ['true', true],
+    ['false', false],
+    ['1', true],
+    ['0', false],
+    ['yes', true],
+    ['no', false],
+]);
+/**
+ * A boolean option is a flag, but `--watch false` is how scripts and CI turn a
+ * default-on flag off, so an explicit literal directly after the flag is taken
+ * as its value rather than left behind as a positional.
+ */
+function readBooleanLiteral(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    return BOOLEAN_LITERALS.get(raw.toLowerCase());
+}
+function readOptionValue(raw, optionDef) {
+    if (resolveOptionType(optionDef) !== 'string[]') {
+        return parseOptionValue(raw, optionDef);
+    }
+    return raw
+        .split(',')
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0)
+        .map((item) => parseOptionValue(item, optionDef));
+}
+/** A repeated array option accumulates rather than replacing. */
+function assignOptionValue(optionArgs, key, value) {
+    const existing = optionArgs[key];
+    if (Array.isArray(existing) && Array.isArray(value)) {
+        optionArgs[key] = [...existing, ...value];
+    }
+    else {
+        optionArgs[key] = value;
+    }
+}
 export function parseCLIArguments(args, programName, allMeta) {
     const result = {
         program: programName,
@@ -131,7 +240,7 @@ export function parseCLIArguments(args, programName, allMeta) {
         result.errors.push(`Missing subcommand: ${result.commandPath.join(' ')}`);
         return result;
     }
-    const availableOptions = collectAvailableOptions(meta, result.commandPath);
+    const availableOptions = applySchemaOptionTypes(collectAvailableOptions(meta, result.commandPath), commandMeta);
     const positionalArgs = [];
     const optionArgs = {};
     while (currentIndex < args.length) {
@@ -142,8 +251,9 @@ export function parseCLIArguments(args, programName, allMeta) {
                 : undefined;
             const equalIndex = arg.indexOf('=');
             if (negatedKey &&
-                typeof availableOptions[negatedKey]?.default === 'boolean') {
-                // Requiring a boolean default keeps a literal `--no-something` option
+                availableOptions[negatedKey] &&
+                resolveOptionType(availableOptions[negatedKey]) === 'boolean') {
+                // Requiring a boolean type keeps a literal `--no-something` option
                 // name parsing as itself rather than as a negation.
                 optionArgs[negatedKey] = false;
             }
@@ -154,7 +264,12 @@ export function parseCLIArguments(args, programName, allMeta) {
                     warnUnknownOption(arg.slice(2, equalIndex), availableOptions, result);
                 }
                 const value = arg.slice(equalIndex + 1);
-                optionArgs[key] = parseOptionValue(value, optionDef);
+                if (optionDef) {
+                    assignOptionValue(optionArgs, key, readOptionValue(value, optionDef));
+                }
+                else {
+                    optionArgs[key] = parseOptionValue(value, optionDef);
+                }
             }
             else {
                 const key = toCamelCase(arg.slice(2));
@@ -162,21 +277,31 @@ export function parseCLIArguments(args, programName, allMeta) {
                 if (!optionDef) {
                     warnUnknownOption(arg.slice(2), availableOptions, result);
                 }
-                if (optionDef && optionDef.array) {
-                    currentIndex++;
-                    const values = [];
-                    while (currentIndex < args.length &&
-                        !args[currentIndex].startsWith('-')) {
-                        values.push(parseOptionValue(args[currentIndex], optionDef));
+                if (!optionDef) {
+                    // With no spec there is nothing to consult, so the lookahead
+                    // heuristic is all that is left.
+                    if (currentIndex + 1 < args.length &&
+                        !args[currentIndex + 1].startsWith('-')) {
                         currentIndex++;
+                        optionArgs[key] = parseOptionValue(args[currentIndex], optionDef);
+                    }
+                    else {
+                        optionArgs[key] = true;
                     }
-                    currentIndex--; // Back up one since we'll increment at loop end
-                    optionArgs[key] = values;
                 }
-                else if (currentIndex + 1 < args.length &&
-                    !args[currentIndex + 1].startsWith('-')) {
+                else if (resolveOptionType(optionDef) === 'boolean') {
+                    const literal = readBooleanLiteral(args[currentIndex + 1]);
+                    if (literal === undefined) {
+                        optionArgs[key] = true;
+                    }
+                    else {
+                        currentIndex++;
+                        optionArgs[key] = literal;
+                    }
+                }
+                else if (currentIndex + 1 < args.length) {
                     currentIndex++;
-                    optionArgs[key] = parseOptionValue(args[currentIndex], optionDef);
+                    assignOptionValue(optionArgs, key, readOptionValue(args[currentIndex], optionDef));
                 }
                 else {
                     optionArgs[key] = true;
@@ -193,12 +318,21 @@ export function parseCLIArguments(args, programName, allMeta) {
                 const shortFlag = arg[i];
                 const longOption = findLongOption(shortFlag, availableOptions);
                 if (longOption) {
+                    const optionDef = availableOptions[longOption];
                     // Only the last flag in a cluster can take a value.
-                    if (i === arg.length - 1 &&
-                        currentIndex + 1 < args.length &&
-                        !args[currentIndex + 1].startsWith('-')) {
+                    const isLast = i === arg.length - 1;
+                    const literal = isLast && resolveOptionType(optionDef) === 'boolean'
+                        ? readBooleanLiteral(args[currentIndex + 1])
+                        : undefined;
+                    if (literal !== undefined) {
+                        currentIndex++;
+                        optionArgs[longOption] = literal;
+                    }
+                    else if (isLast &&
+                        resolveOptionType(optionDef) !== 'boolean' &&
+                        currentIndex + 1 < args.length) {
                         currentIndex++;
-                        optionArgs[longOption] = parseOptionValue(args[currentIndex], availableOptions[longOption]);
+                        assignOptionValue(optionArgs, longOption, readOptionValue(args[currentIndex], optionDef));
                     }
                     else {
                         optionArgs[longOption] = true;
@@ -272,11 +406,11 @@ function parseOptionValue(value, optionDef) {
             return parseFloat(value);
         return value;
     }
-    const defaultValue = optionDef.default;
-    if (typeof defaultValue === 'boolean') {
-        return value === 'true' || value === '1' || value === 'yes';
+    const optionType = resolveOptionType(optionDef);
+    if (optionType === 'boolean') {
+        return readBooleanLiteral(value) ?? false;
     }
-    if (typeof defaultValue === 'number') {
+    if (optionType === 'number') {
         return parseFloat(value);
     }
     if (optionDef.choices && !optionDef.choices.includes(value)) {

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

@@ -1,4 +1,5 @@
-import type { CommonWireMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CoreSingletonServices } from '../../types/core.types.js';
+import type { CommonWireMeta, CoreSingletonServices } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { PikkuHTTPRequest } from '../http/http.types.js';
 export interface GatewayAttachment {

package/dist/wirings/http/http-runner.d.ts

@@ -1,6 +1,6 @@
 import type { CoreHTTPFunctionWiring, RunHTTPWiringOptions, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse } from './http.types.js';
 import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
-import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../middleware/middleware.types.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(pattern: string, middleware: CorePikkuMiddlewareGroup, packageName?: string | null) => CorePikkuMiddlewareGroup;
 export declare const wireHTTP: <In, Out, Route extends string, PikkuFunction extends CorePikkuFunction<In, Out> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out> = CorePikkuFunctionSessionless<In, Out>, PikkuPermissionGroup extends CorePikkuPermission<In> = CorePikkuPermission<In>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware>(httpWiring: CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermissionGroup, PikkuMiddleware>) => void;

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

@@ -42,7 +42,7 @@ export const wireHTTP = (httpWiring) => {
         return;
     }
     if (httpWiring.func) {
-        addFunction(routeMeta.pikkuFuncId, httpWiring.func);
+        addFunction(routeMeta.pikkuFuncId, httpWiring.func, routeMeta.packageName ?? null);
     }
     const routes = pikkuState(null, 'http', 'routes');
     if (!routes.has(httpWiring.method)) {

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

@@ -1,6 +1,7 @@
 import type { SerializeOptions } from 'cookie';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
+import type { CommonWireMeta } from '../../types/core.types.js';
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePikkuFunctionConfig } from '../../function/functions.types.js';
 type ExtractHTTPWiringParams<S extends string> = S extends `${string}:${infer Param}/${infer Rest}` ? Param | ExtractHTTPWiringParams<`/${Rest}`> : S extends `${string}:${infer Param}` ? Param : never;
 export type AssertHTTPWiringParams<In, HTTPWiring extends string> = ExtractHTTPWiringParams<HTTPWiring> extends keyof In ? unknown : [
@@ -104,7 +105,6 @@ export type HTTPWiringMeta = CommonWireMeta & {
      * join wrong reads an open route as a closed one.
      */
     requiresSession?: boolean;
-    refTarget?: string;
     params?: string[];
     query?: string[];
     inputTypes?: HTTPFunctionMetaInputTypes;

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

@@ -4,4 +4,5 @@ export { logRoutes } from './log-http-routes.js';
 export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js';
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js';
 export { toWebRequest, applyWebResponse } from './web-request.js';
+export { httpRouter } from './routers/http-router.js';
 export type { AssertHTTPWiringParams, CoreHTTPFunctionWiring, HTTPMethod, HTTPRouteBaseConfig, HTTPRouteContract, HTTPRouteMap, HTTPWiringsMeta, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse, PikkuQuery, RunHTTPWiringOptions, } from './http.types.js';

package/dist/wirings/http/index.js

@@ -4,3 +4,4 @@ export { logRoutes } from './log-http-routes.js';
 export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js';
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js';
 export { toWebRequest, applyWebResponse } from './web-request.js';
+export { httpRouter } from './routers/http-router.js';

package/dist/wirings/http/pikku-fetch-http-request.js

@@ -1,5 +1,5 @@
 import { parse as parseQuery } from 'picoquery';
-import { parse as parseCookie } from 'cookie';
+import { parseCookie } from 'cookie';
 import { PayloadTooLargeError, UnprocessableContentError, } from '../../errors/errors.js';
 export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 /**

package/dist/wirings/http/pikku-fetch-http-response.js

@@ -1,4 +1,4 @@
-import { serialize as serializeCookie } from 'cookie';
+import { stringifySetCookie } from 'cookie';
 export class PikkuFetchHTTPResponse {
     #statusCode = 200;
     #headers = new Headers();
@@ -95,7 +95,7 @@ export class PikkuFetchHTTPResponse {
         return this;
     }
     toResponse(args) {
-        const cookieHeader = Array.from(this.#cookies.entries()).map(([name, { value, flags }]) => serializeCookie(name, value, flags));
+        const cookieHeader = Array.from(this.#cookies.entries()).map(([name, { value, flags }]) => stringifySetCookie({ name, value, ...flags }, flags));
         cookieHeader.forEach((cookie) => this.#headers.append('Set-Cookie', cookie));
         return new Response(this.#body, {
             ...args,

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

@@ -1,5 +1,5 @@
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
 /** "user/{userId}/post/{postId}" => "userId" | "postId" */
 type ExtractMCPURIParams<S extends string> = S extends `${string}{${infer Param}}/${infer Rest}` ? Param | ExtractMCPURIParams<Rest> : S extends `${string}{${infer Param}}` ? Param : never;
 /** Resolves to a tuple of error strings, not `never`, so the mismatch surfaces in the type error. */

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

@@ -3,7 +3,7 @@ export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBu
 export type { RoleVerification } from './validate-personas.js';
 export { personaEnvironmentErrors, personaEnvironmentRefusal, } from './persona-environments.js';
 export type { PersonaEnvironment, PersonaEnvironmentSubject, } from './persona-environments.js';
-export { personaEmail, personaEmails, } from './persona-email.js';
+export { personaEmail, personaEmails } from './persona-email.js';
 export type { MailboxAllowlist, PersonaMailbox, ReceivedEmail, } from './persona-mailbox.js';
 export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions, PersonaMeta, PersonasMeta, } from './persona.types.js';
 /**

package/dist/wirings/persona/index.js

@@ -1,7 +1,7 @@
 export { definePersonas } from './define-personas.js';
 export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBuildPersonasMeta, verifyPersonaRoles, } from './validate-personas.js';
 export { personaEnvironmentErrors, personaEnvironmentRefusal, } from './persona-environments.js';
-export { personaEmail, personaEmails, } from './persona-email.js';
+export { personaEmail, personaEmails } from './persona-email.js';
 /**
  * Signing in as a persona and talking to a stage over HTTP.
  *

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

@@ -105,6 +105,18 @@ export type CorePersona = {
      * into a flaky suite.
      */
     runnable?: boolean;
+    /**
+     * The app this person signs into, when the product is more than one frontend.
+     *
+     * A person uses one of them — staff their app, customers theirs — and that is
+     * what decides where a browser step navigates: `/dashboard` is a different
+     * page in each, so the actor settles which one without the scenario saying.
+     * The runner takes the base url per app (`--app-url <app>=<url>`, or
+     * `appUrls` on the environment) and each actor browses against its own.
+     *
+     * Omitted is the normal case: one app, one url, nothing to say.
+     */
+    app?: string;
 };
 /** Personas to declare, keyed by id. */
 export type CorePersonas = Record<string, CorePersona>;
@@ -130,6 +142,8 @@ export type PersonaMeta = {
     /** Absent means "everywhere but production", which is resolved, not stored. */
     environments?: string[];
     runnable: boolean;
+    /** The app this person signs into; picks their base url on a browser run. */
+    app?: string;
     sourceFile?: string;
 };
 export type PersonaDefinitions = PersonaMeta[];

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

@@ -1,7 +1,7 @@
 import type { CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { QueueConfigMapping } from './validate-worker-config.js';
-import type { Safe } from '../../secret-value.js';
+import type { Safe } from '../../classification/secret-value.js';
 export interface PikkuWorkerConfig {
     name?: string;
     /** Total worker concurrency. */

package/dist/wirings/queue/signed-queue-service.d.ts

@@ -1,4 +1,4 @@
-import type { Safe } from '../../secret-value.js';
+import type { Safe } from '../../classification/secret-value.js';
 import type { Logger } from '../../services/logger.js';
 import type { SecretService } from '../../services/secret-service.js';
 import type { JobOptions, QueueJob, QueueService } from './queue.types.js';

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

@@ -1,8 +1,2 @@
 export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
-export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
-export type { RemoteAddonAuthBinding } from './remote-addon-auth.js';
 export type { PikkuRPC, RPCMeta } from './rpc-types.js';
-export { wireAddon } from './wire-addon.js';
-export type { WireAddonConfig } from './wire-addon.js';
-export { wireRemoteAddon } from './wire-remote-addon.js';
-export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wire-remote-addon.js';

package/dist/wirings/rpc/index.js

@@ -1,4 +1 @@
 export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
-export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
-export { wireAddon } from './wire-addon.js';
-export { wireRemoteAddon } from './wire-remote-addon.js';

package/dist/wirings/rpc/remote-addon-auth.d.ts

@@ -1,6 +1,6 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
-import { type SecretValue } from '../../secret-value.js';
+import { type SecretValue } from '../../classification/secret-value.js';
 export type RemoteAddonAuthBinding = {
     credentialId: string;
 } | {

package/dist/wirings/rpc/remote-addon-auth.js

@@ -1,5 +1,5 @@
 import { PikkuError, addError } from '../../errors/error-handler.js';
-import { isSecretValue } from '../../secret-value.js';
+import { isSecretValue, } from '../../classification/secret-value.js';
 export class RemoteAddonAuthError extends PikkuError {
     namespace;
     constructor(namespace, detail) {

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

@@ -1,9 +1,9 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
-import { addonInstanceForNamespace } from './addon-runner.js';
+import { addonInstanceForNamespace } from '../addon/addon-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
-import { resolveRemoteAddonToken } from './remote-addon-auth.js';
+import { resolveRemoteAddonToken } from '../addon/remote-addon-auth.js';
 import { createAgentRPC } from '../agent/agent-rpc.js';
 /**
  * The session for a wire: read through `getSession` when a runner attached one,

package/dist/wirings/rpc/wire-addon.d.ts

@@ -1,4 +1,4 @@
-import type { CorePikkuMiddleware } from '../../types/core.types.js';
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 export type WireAddonConfig = {
     name: string;
     package: string;

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

@@ -1,4 +1,5 @@
-import type { CoreUserSession, CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
+import type { CoreUserSession, CommonWireMeta } from '../../types/core.types.js';
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Record<string, CommonWireMeta & {
     name: string;

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

@@ -1,3 +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 { hasScopes, verifyScopes } from '../../scopes.js';

package/dist/wirings/scope/index.js

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

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

@@ -4,6 +4,15 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
+    /**
+     * A secret is REQUIRED by default because `getSecret` throws when the value is
+     * missing — a deploy without it is a runtime failure waiting to happen, so the
+     * deploy gate refuses it. Mark a secret `optional` when absence is a supported
+     * state the app handles (a feature that simply stays off): the generated map
+     * emits it as an optional property and `getSecret` resolves `undefined`
+     * instead of throwing.
+     */
+    optional?: boolean;
     /**
      * Where a user goes to obtain this value — a provider's API-key page, a setup
      * guide, an internal runbook. Consoles and deploy UIs surface it beside a
@@ -36,6 +45,7 @@ export type SecretDefinitionMeta = {
     description?: string;
     secretId: string;
     schema?: Record<string, unknown> | string;
+    optional?: boolean;
     docsUrl?: string;
     oauth2?: OAuth2CredentialConfig;
     rotationPeriod?: string;

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

@@ -32,6 +32,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     description: def.description,
                     secretId: def.secretId,
                     schema: def.schema,
+                    optional: def.optional,
                     oauth2: def.oauth2,
                     rotationPeriod: def.rotationPeriod,
                     allowedHosts: def.allowedHosts,
@@ -49,6 +50,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 description: def.description,
                 secretId: def.secretId,
                 schema: def.schema,
+                optional: def.optional,
                 oauth2: def.oauth2,
                 rotationPeriod: def.rotationPeriod,
                 allowedHosts: def.allowedHosts,

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

@@ -24,6 +24,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                     description: def.description,
                     variableId: def.variableId,
                     schema: def.schema,
+                    required: def.required,
                     docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
@@ -38,6 +39,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                 description: def.description,
                 variableId: def.variableId,
                 schema: def.schema,
+                required: def.required,
                 docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };

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

@@ -4,6 +4,14 @@ export type CoreVariable<T = unknown> = {
     description?: string;
     variableId: string;
     schema: T;
+    /**
+     * A variable is OPTIONAL by default because `variables.get` returns
+     * `T | undefined` and never throws — every caller already handles absence, so
+     * a deploy gate that blocks on one contradicts the API. Mark a variable
+     * `required` for the few whose absence genuinely breaks the app; only those
+     * block a deploy.
+     */
+    required?: boolean;
     docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
@@ -12,6 +20,7 @@ export type VariableDefinitionMeta = {
     description?: string;
     variableId: string;
     schema?: Record<string, unknown> | string;
+    required?: boolean;
     docsUrl?: string;
     sourceFile?: string;
 };

package/dist/wirings/virtual-user/index.d.ts

@@ -24,6 +24,6 @@ export type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart,
 export { DISPOSITIONS, dispositionProfile, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';
-export { IntentStack, intentsForPersona, } from './virtual-user-intents.js';
+export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, type SchemaMap, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, type PersonaTargetOptions, } from './virtual-user-target.js';

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

@@ -3,6 +3,6 @@ export { runVirtualUser, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
-export { IntentStack, intentsForPersona, } from './virtual-user-intents.js';
+export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, } from './virtual-user-target.js';

package/dist/wirings/virtual-user/prepare-virtual-user-run.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '../../types/core.types.js';
+import type { FunctionsMeta } from '../../function/function-meta.types.js';
 import type { WorkflowsMeta } from '../workflow/workflow.types.js';
 import type { SystemRoleDefinitions, SystemRoleDefinitionsMeta } from '../role/role.types.js';
 import { type SchemaMap } from './virtual-user-derive.js';

package/dist/wirings/virtual-user/virtual-user-derive.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '../../types/core.types.js';
+import type { FunctionsMeta } from '../../function/function-meta.types.js';
 import type { WorkflowsMeta } from '../workflow/workflow.types.js';
 import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js';
 /** A generated JSON schema, keyed by the name the function meta refers to. */

package/dist/wirings/workflow/graph/graph-node.d.ts

@@ -1,4 +1,4 @@
-import type { GraphNodeConfig, NextConfig, RefValue } from './workflow-graph.types.js';
+import type { ForEachConfig, ForEachMode, GraphNodeConfig, ItemFn, NextConfig, RefValue, TemplateFn } from './workflow-graph.types.js';
 export interface RPCHandler<I = any, O = any> {
     input: I;
     output: O;
@@ -19,7 +19,14 @@ export declare function createGraph<RPCMap extends Record<string, RPCHandler>>()
 type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends Record<string, RPCHandler>> = {
     [K in Extract<keyof FuncMap, string>]?: {
         next?: NextConfig<Extract<keyof FuncMap, string>>;
-        input?: (ref: <N extends Extract<keyof FuncMap, string>, P extends keyof ComputeNodeOutputs<FuncMap, RPCMap>[N] & string>(nodeId: N, path: P) => TypedRef<ComputeNodeOutputs<FuncMap, RPCMap>[N][P]>) => InputWithRefs<ComputeNodeInputs<FuncMap, RPCMap>[K]>;
+        /**
+         * Run this node once per element of an upstream array. The node's own
+         * result becomes the ordered array of per-item results.
+         */
+        forEach?: ForEachConfig<Extract<keyof FuncMap, string>>;
+        /** How the per-item instances run. Defaults to 'parallel'. */
+        mode?: ForEachMode;
+        input?: (ref: <N extends Extract<keyof FuncMap, string>, P extends keyof ComputeNodeOutputs<FuncMap, RPCMap>[N] & string>(nodeId: N, path: P) => TypedRef<ComputeNodeOutputs<FuncMap, RPCMap>[N][P]>, template: TemplateFn, $item: ItemFn) => InputWithRefs<ComputeNodeInputs<FuncMap, RPCMap>[K]>;
         onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[];
         retries?: number;
         retryDelay?: string | number;

package/dist/wirings/workflow/graph/graph-node.js

@@ -16,6 +16,8 @@ export function createGraph() {
         for (const [nodeId, def] of Object.entries(nodes)) {
             result[nodeId] = {
                 func: funcMap[nodeId],
+                forEach: def?.forEach,
+                mode: def?.mode,
                 input: def?.input,
                 next: def?.next,
                 onError: def?.onError,

package/dist/wirings/workflow/graph/graph-runner.d.ts

@@ -7,6 +7,7 @@ export declare class ChildWorkflowStartedException extends Error {
     name: string;
     constructor(parentRunId: string, stepId: string, childRunId: string);
 }
+export declare function stripInstanceOrdinal(name: string): string;
 export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string, overrideMeta?: WorkflowRuntimeMeta): Promise<void>;
 export declare function executeGraphStep(workflowService: PikkuWorkflowService, rpcService: any, runId: string, stepId: string, nodeId: string, rpcName: string, data: any, graphName: string): Promise<any>;
 export declare function runFromMeta(workflowService: PikkuWorkflowService, runId: string, meta: WorkflowRuntimeMeta, _rpcService: any): Promise<void>;