@pikku/cli 0.12.90 → 0.12.92

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,22 +1,36 @@
 /**
- * This file was generated by @pikku/cli@0.12.90
+ * This file was generated by @pikku/cli@0.12.92
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';
 import { type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult } from '@pikku/core/workflow';
-import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions } from '@pikku/core/workflow';
+import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions, ScenarioStepOptions } from '@pikku/core/workflow';
 export { WorkflowCancelledException };
 import type { PikkuFunctionSessionless, PikkuFunctionConfig } from '../function/pikku-function-types.gen.js';
 import type { FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js';
 import type { FlattenedWorkflowMap } from './pikku-workflow-map.gen.d.js';
 import type { AgentMap as FlattenedAgentMap } from '../agent/pikku-agent-map.gen.d.js';
+import type { FlattenedScenarioStepMap } from './pikku-scenario-step-map.gen.d.js';
+import type { TypedScenarioActors } from './pikku-scenario-actors.gen.js';
+export type { TypedScenarioActors };
 export { template };
 export interface TypedWorkflow extends PikkuWorkflowWire {
     do<K extends keyof FlattenedRPCMap>(stepName: string, rpcName: K, data: FlattenedRPCMap[K]['input'], options?: WorkflowStepOptions): Promise<FlattenedRPCMap[K]['output']>;
     do<K extends keyof FlattenedWorkflowMap>(stepName: string, workflowName: K, data: FlattenedWorkflowMap[K]['input'], options?: WorkflowStepOptions): Promise<FlattenedWorkflowMap[K]['output']>;
     do<T>(stepName: string, fn: () => T | Promise<T>, options?: WorkflowStepOptions): Promise<T>;
 }
-export type TypedScenario = TypedWorkflow & Omit<PikkuScenarioWire, keyof PikkuWorkflowWire>;
+/**
+ * The typed half of a scenario wire: `step` and its `given`/`when`/`then`
+ * sugar, narrowed to the names declared by `pikkuScenarioStep` in this project.
+ * The phase only changes the prose the reporter renders.
+ */
+export interface TypedScenarioSteps {
+    step<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+    given<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+    when<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+    then<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+}
+export type TypedScenario = TypedWorkflow & Omit<PikkuScenarioWire, keyof PikkuWorkflowWire | keyof TypedScenarioSteps> & TypedScenarioSteps;
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { InferSchemaOutput, PikkuPermission, PikkuMiddleware, NodeConfig, PikkuApprovalDescription } from '../function/pikku-function-types.gen.js';
 import type { ScopeId } from '../scopes/pikku-scopes.gen.js';
@@ -58,7 +72,39 @@ export declare function pikkuWorkflowComplexFunc<InputSchema extends StandardSch
 export declare function pikkuWorkflowComplexFunc<In, Out = unknown>(func: PikkuFunctionWorkflow<In, Out> | PikkuFunctionConfig<In, Out, 'workflow', PikkuFunctionWorkflow<In, Out>>): PikkuFunctionConfig<In, Out, 'workflow'>;
 export type PikkuScenarioConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<PikkuWorkflowConfigWithSchema<InputSchema, OutputSchema>, 'func' | 'auth' | 'scopes' | 'permissions'> & {
     func: PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>;
+    /**
+     * Runs before the scenario body. Same signature as `func`, but its return
+     * value is discarded — a hook is setup, not a step, so it is never recorded
+     * on the ladder. Throwing skips the body and fails the run; `after` still
+     * runs.
+     */
+    before?: PikkuScenarioHook<InputSchema>;
+    /**
+     * Always runs after the scenario body, in a `finally`, whether it passed or
+     * failed. Throwing fails a run that would otherwise have passed; on an
+     * already-failed run it attaches as the `cause` and never replaces the
+     * original error.
+     */
+    after?: PikkuScenarioHook<InputSchema>;
+    /**
+     * Why this scenario is held out of a default run, stated where the scenario
+     * is. The scenario still appears in the plan and is reported as skipped
+     * rather than quietly omitted; naming it directly with `--flows` runs it
+     * anyway.
+     */
+    skip?: string;
 };
+/**
+ * A scenario lifecycle hook: the scenario's own `(services, data, wire)`
+ * signature with its result discarded.
+ */
+export type PikkuScenarioHook<InputSchema extends StandardSchemaV1 | undefined = undefined> = PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, void>;
+/**
+ * Declares a scenario hook. Returns the function verbatim — a hook is never
+ * registered, so this exists purely to give an inline hook a call site to be
+ * contextually typed from, the way every other pikku primitive is.
+ */
+export declare function pikkuScenarioHook<In = unknown>(hook: PikkuFunctionScenario<In, void>): PikkuFunctionScenario<In, void>;
 /**
  * A scenario: a complex workflow that drives the app the way users do.
  * Steps run as actors over the REAL transport — `scenario.do(step, rpc,
@@ -67,6 +113,109 @@ export type PikkuScenarioConfigWithSchema<InputSchema extends StandardSchemaV1 |
  */
 export declare function pikkuScenario<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuScenarioConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenario' | 'actors', PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>, InputSchema, OutputSchema>;
 export declare function pikkuScenario<In, Out = unknown>(func: PikkuFunctionScenario<In, Out> | PikkuFunctionConfig<In, Out, 'scenario' | 'actors', PikkuFunctionScenario<In, Out>>): PikkuFunctionConfig<In, Out, 'scenario' | 'actors'>;
+/**
+ * A scenario as a feature references it. Any `pikkuScenario` export is
+ * assignable; `In` is recovered from it so the paired form's `data` is
+ * checked against that scenario's own input.
+ */
+export type PikkuScenarioRef<In = any, Out = any> = PikkuFunctionConfig<In, Out, 'scenario' | 'actors', PikkuFunctionScenario<In, Out>, any, any>;
+/**
+ * One entry in a feature's `scenarios` list, validated against itself: a bare
+ * scenario, or a scenario paired with the input to run it with. The paired form
+ * is gherkin's `Examples:` written as an ordinary loop.
+ */
+export type PikkuFeatureEntry<Entry> = Entry extends {
+    scenario: PikkuScenarioRef<infer In>;
+} ? {
+    scenario: PikkuScenarioRef<In>;
+    data: In;
+} : Entry extends PikkuScenarioRef ? Entry : never;
+export type PikkuFeatureConfig<Scenarios extends readonly unknown[]> = {
+    /** Human-readable name. The export identifier is the id. */
+    name: string;
+    description?: string;
+    tags?: string[];
+    scenarios: {
+        [K in keyof Scenarios]: PikkuFeatureEntry<Scenarios[K]>;
+    };
+    /**
+     * Runs ONCE before the whole group — not before each scenario. Per-scenario
+     * setup is the scenario's own `before`; gherkin's `Background:` is
+     * deliberately not expressible here.
+     */
+    before?: PikkuScenarioHook;
+    after?: PikkuScenarioHook;
+};
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * A scenario does not have to belong to a feature — a void-input scenario
+ * still runs standalone.
+ *
+ * ```ts
+ * export const credentialFeature = pikkuFeature({
+ *   name: 'Credential API',
+ *   tags: ['credential'],
+ *   before: startsMockOAuthServer,
+ *   after: stopsMockOAuthServer,
+ *   scenarios: [
+ *     credentialLazyLoadScenario,
+ *     ...['stripe', 'google'].map((name) => ({
+ *       scenario: credentialRoundTripScenario,
+ *       data: { name },
+ *     })),
+ *   ],
+ * })
+ * ```
+ */
+export declare function pikkuFeature<const Scenarios extends readonly unknown[]>(config: PikkuFeatureConfig<Scenarios>): PikkuFeatureConfig<Scenarios>;
+export type PikkuFunctionScenarioStep<In = unknown, Out = never, B extends boolean = false> = PikkuFunctionSessionless<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>;
+export type PikkuScenarioStepConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, B extends boolean = false> = {
+    /** Registered name — this is the string `scenario.step()` references. */
+    name: string;
+    /**
+     * What this step does, for the console and for whoever reads the source. It
+     * is also the fallback prose when no `template` is declared, in which case a
+     * reporter renders "Given the shopper buys an apple". Defaults to the call
+     * site's step name.
+     */
+    description?: string;
+    /**
+     * The prose a reporter renders for this step, with `{placeholders}` filled
+     * from the input the step was called with — `'sees {packageName}'` reports as
+     * "Then the admin sees @pikku/addon-todos". Every input field should appear,
+     * so the report names the values under test rather than repeating one
+     * sentence per call site.
+     */
+    template?: string;
+    /**
+     * This step drives a browser. The runner provisions one for the step's actor
+     * before calling it — which also makes an actor mandatory — and `wire.browser`
+     * is non-optional inside `func`.
+     */
+    browser?: B;
+    title?: string;
+    tags?: string[];
+    input?: InputSchema;
+    output?: OutputSchema;
+    errors?: Array<typeof PikkuError>;
+    func: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>;
+};
+export type PikkuScenarioStepConfig<In, Out, B extends boolean = false> = Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, B>, 'func' | 'input' | 'output'> & {
+    func: PikkuFunctionScenarioStep<In, Out, B>;
+};
+/**
+ * A named, reusable scenario step. Unlike `scenario.do`, which can only name an
+ * RPC, a step's body is an ordinary pikku function — so it may drive a browser,
+ * invoke RPCs as its actor, or run a workflow.
+ *
+ * Steps are deliberately NOT registered as RPCs: a browser-driving step must
+ * never be network-callable.
+ */
+export declare function pikkuScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, B extends boolean = false>(config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, B>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>, InputSchema, OutputSchema>;
+export declare function pikkuScenarioStep<In, Out = unknown, B extends boolean = false>(config: PikkuScenarioStepConfig<In, Out, B>): PikkuFunctionConfig<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>;
 type TypedRef<T> = {
     $ref: string;
     path?: string;

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.90
+ * This file was generated by @pikku/cli@0.12.92
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';
@@ -12,9 +12,47 @@ export function pikkuWorkflowFunc(func) {
 export function pikkuWorkflowComplexFunc(func) {
     return typeof func === 'function' ? { func } : func;
 }
+/**
+ * Declares a scenario hook. Returns the function verbatim — a hook is never
+ * registered, so this exists purely to give an inline hook a call site to be
+ * contextually typed from, the way every other pikku primitive is.
+ */
+export function pikkuScenarioHook(hook) {
+    return hook;
+}
 export function pikkuScenario(func) {
     return typeof func === 'function' ? { func } : func;
 }
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * A scenario does not have to belong to a feature — a void-input scenario
+ * still runs standalone.
+ *
+ * ```ts
+ * export const credentialFeature = pikkuFeature({
+ *   name: 'Credential API',
+ *   tags: ['credential'],
+ *   before: startsMockOAuthServer,
+ *   after: stopsMockOAuthServer,
+ *   scenarios: [
+ *     credentialLazyLoadScenario,
+ *     ...['stripe', 'google'].map((name) => ({
+ *       scenario: credentialRoundTripScenario,
+ *       data: { name },
+ *     })),
+ *   ],
+ * })
+ * ```
+ */
+export function pikkuFeature(config) {
+    return config;
+}
+export function pikkuScenarioStep(config) {
+    return config;
+}
 export function pikkuWorkflowGraph(config) {
     return corePikkuWorkflowGraph(config);
 }

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.90
+ * This file was generated by @pikku/cli@0.12.92
  */
 import { pikkuState } from '@pikku/core/internal';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.90
+ * This file was generated by @pikku/cli@0.12.92
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.90') {
-      process.stderr.write(`\n  Update available  0.12.90 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.92') {
+      process.stderr.write(`\n  Update available  0.12.92 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/cli.wiring.js

@@ -397,14 +397,42 @@ wireCLI({
                             description: 'Comma-separated flow names to run (default: all)',
                             short: 'f',
                         },
+                        features: {
+                            description: 'Comma-separated feature names to run (pikkuFeature exports) — the feature is the run unit, so its hooks run once around the group',
+                        },
                         tags: {
                             description: 'Comma-separated tags — run flows matching any',
                             short: 't',
                         },
+                        excludeTags: {
+                            description: 'Comma-separated tags to hold back — flows matching any are not run, unless named directly with --flows',
+                        },
                         coverage: {
                             description: 'Reset/snapshot server coverage per scenario (target must run with --coverage); writes coverage/scenario-coverage.json',
                             default: false,
                         },
+                        browser: {
+                            description: 'Run scenarios with browser steps. --no-browser skips them (they are reported as skipped, not failed)',
+                            default: true,
+                        },
+                        spawn: {
+                            description: "Start `pikku dev` on the environment's apiUrl for the run and stop it afterwards. Without it, the environment must already be serving",
+                            default: false,
+                        },
+                        keepAlive: {
+                            description: 'With --spawn, leave the server running after the run (dev loop)',
+                            default: false,
+                        },
+                        trace: {
+                            description: 'Keep every stack frame on a failure. Without it, only the project’s own frames are shown',
+                            default: false,
+                        },
+                        apiUrl: {
+                            description: "Override the environment's apiUrl for this run — for a target that only exists at run time, such as a freshly deployed sandbox",
+                        },
+                        appUrl: {
+                            description: "Override the environment's appUrl for this run (the frontend browser steps navigate against)",
+                        },
                     },
                 }),
                 list: pikkuCLICommand({

package/dist/src/deploy/analyzer/analyzer.js

@@ -7,6 +7,7 @@
  * Workflow orchestrators dispatch to step units via queue or RPC (inline).
  */
 import { resolveDeployTarget, } from '@pikku/inspector';
+import { isScenarioFunction, withoutScenarios, withoutScenarioWorkflows, } from '../../functions/wirings/scenarios/scenario-partition.js';
 export function analyzeDeployment(state, options) {
     const serverlessIncompatible = new Set(options.serverlessIncompatible ?? []);
     const defaultTarget = options.defaultTarget ?? 'serverless';
@@ -18,7 +19,13 @@ export function analyzeDeployment(state, options) {
     const agents = [];
     const mcpEndpoints = [];
     const workflows = [];
-    const functionsMeta = state.functions.meta;
+    // Scenarios, features and steps are test artifacts that happen to be built out
+    // of functions and workflows, so without this they analyze like application
+    // code: every scenario became its own unit, its own `WorkflowDefinition` and —
+    // because a scenario IS a workflow — a `wf-orchestrator-<scenario>` queue that
+    // a provider would then create in production.
+    const functionsMeta = withoutScenarios(state.functions.meta);
+    const graphMeta = withoutScenarioWorkflows(state.workflows.graphMeta);
     const httpMeta = state.http.meta;
     // ── Step 1: Create function units ──────────────────────────────────
     // Each function gets one unit. Collect all its triggers.
@@ -190,9 +197,19 @@ export function analyzeDeployment(state, options) {
         });
     }
     // ── Step 3: MCP gateway ────────────────────────────────────────────
-    const mcpToolIds = values(state.mcpEndpoints.toolsMeta).map((t) => t.pikkuFuncId);
-    const mcpResourceIds = values(state.mcpEndpoints.resourcesMeta).map((r) => r.pikkuFuncId);
-    const mcpPromptIds = values(state.mcpEndpoints.promptsMeta).map((p) => p.pikkuFuncId);
+    // The MCP metas are keyed by wiring, not by function, so they are the one
+    // place a scenario or step id can still arrive from raw state. A gateway that
+    // lists one would depend on a unit that was never emitted.
+    const deployableFuncId = (funcId) => !isScenarioFunction(state.functions.meta[funcId]);
+    const mcpToolIds = values(state.mcpEndpoints.toolsMeta)
+        .map((t) => t.pikkuFuncId)
+        .filter(deployableFuncId);
+    const mcpResourceIds = values(state.mcpEndpoints.resourcesMeta)
+        .map((r) => r.pikkuFuncId)
+        .filter(deployableFuncId);
+    const mcpPromptIds = values(state.mcpEndpoints.promptsMeta)
+        .map((p) => p.pikkuFuncId)
+        .filter(deployableFuncId);
     // Include functions explicitly marked mcp: true
     for (const [funcId, funcMeta] of entries(functionsMeta)) {
         if (funcMeta.mcp &&
@@ -248,7 +265,7 @@ export function analyzeDeployment(state, options) {
         });
     }
     // ── Step 5: Workflows ──────────────────────────────────────────────
-    buildWorkflows(state.workflows.graphMeta, functionsMeta, { ...state.rpc?.exposedMeta, ...state.rpc?.internalMeta }, httpMeta, units, workflows, queues, workflowQueues);
+    buildWorkflows(graphMeta, functionsMeta, { ...state.rpc?.exposedMeta, ...state.rpc?.internalMeta }, httpMeta, units, workflows, queues, workflowQueues);
     // ── Step 6: Ensure function units exist for gateway dependencies ───
     // Gateways depend on function units. If a function is only used via
     // a gateway (not directly wired to HTTP/queue/cron), it still needs

package/dist/src/deploy/build-pipeline.js

@@ -8,6 +8,7 @@ import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { mkdir, writeFile, copyFile } from 'node:fs/promises';
 import { analyzeDeployment } from './analyzer/index.js';
+import { withoutScenarios } from '../functions/wirings/scenarios/scenario-partition.js';
 import { generatePerUnitCodegen } from './codegen/per-unit-codegen.js';
 import { generateServerEntrySource, SERVER_DOCKERFILE, SERVER_DOCKERIGNORE, } from './server-entry.js';
 const MERGED_SERVER_UNIT_NAME = 'pikku-server-container';
@@ -63,7 +64,10 @@ export async function runBuildPipeline(options) {
             name: unitName,
             role: 'function',
             target: 'serverless',
-            functionIds: Object.keys(inspectorState.functions.meta),
+            // Scenarios and steps are excluded for the same reason the analyzer drops
+            // them: a single-unit bundle is still a deployment, and a test harness has
+            // no business inside one.
+            functionIds: Object.keys(withoutScenarios(inspectorState.functions.meta)),
             services: [],
             dependsOn: [],
             handlers: [],

package/dist/src/fabric/fabric-commands.d.ts

@@ -451,37 +451,65 @@ export declare const fabricCommands: {
                 value?: string | undefined;
                 force?: boolean | undefined;
             }, {
-                ok: boolean;
+                name: string;
+                keyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 name: string;
                 branch: string;
                 value?: string | undefined;
                 force?: boolean | undefined;
             }, {
-                ok: boolean;
+                name: string;
+                keyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 name: string;
                 branch: string;
                 value?: string | undefined;
                 force?: boolean | undefined;
             }, {
-                ok: boolean;
+                name: string;
+                keyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
             list: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
+            }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
+            rotate: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
+                branch: string;
+                force?: boolean | undefined;
+            }, {
+                retiredKeyId: string;
+            }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
+                branch: string;
+                force?: boolean | undefined;
+            }, {
+                retiredKeyId: string;
+            }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
+                branch: string;
+                force?: boolean | undefined;
+            }, {
+                retiredKeyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
         };
     };
@@ -622,21 +650,21 @@ export declare const fabricCommands: {
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
             add: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;
                 cnameTarget: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;
                 cnameTarget: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;

package/dist/src/fabric/fabric-commands.js

@@ -31,6 +31,7 @@ import { FabricDbSchema, renderDbSchema, } from './functions/db-schema.function.
 import { FabricRollback } from './functions/rollback.function.js';
 import { FabricSecretsSet } from './functions/secrets-set.function.js';
 import { FabricSecretsList } from './functions/secrets-list.function.js';
+import { FabricSecretsRotate } from './functions/secrets-rotate.function.js';
 import { FabricLogs } from './functions/logs.function.js';
 import { FabricMetrics } from './functions/metrics.function.js';
 import { FabricTrace } from './functions/trace.function.js';
@@ -241,6 +242,17 @@ export const fabricCommands = defineCLICommands({
                     json: { description: 'Machine-readable output', default: false },
                 },
             }),
+            rotate: pikkuCLICommand({
+                func: FabricSecretsRotate,
+                description: "Retire a stage's sealing key (secrets must be set again)",
+                options: {
+                    branch: { description: 'Target branch', short: 'b' },
+                    force: {
+                        description: 'Confirm that existing secrets become unreadable',
+                        default: false,
+                    },
+                },
+            }),
         },
     },
     logs: pikkuCLICommand({

package/dist/src/fabric/functions/domains-add.function.d.ts

@@ -2,8 +2,8 @@ import { z } from 'zod';
 export declare const FabricDomainsAddInput: z.ZodObject<{
     hostname: z.ZodString;
     target: z.ZodOptional<z.ZodEnum<{
-        api: "api";
         app: "app";
+        api: "api";
     }>>;
     apiUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -13,21 +13,21 @@ export declare const FabricDomainsAddOutput: z.ZodObject<{
 }, z.core.$strip>;
 export declare const FabricDomainsAdd: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;
     cnameTarget: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;
     cnameTarget: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;

package/dist/src/fabric/functions/secrets-list.function.d.ts

@@ -4,21 +4,33 @@ export declare const FabricSecretsListInput: z.ZodObject<{
     json: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FabricSecretsListOutput: z.ZodObject<{
-    names: z.ZodArray<z.ZodString>;
+    secrets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const FabricSecretsList: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/secrets-list.function.js

@@ -2,13 +2,16 @@ import { z } from 'zod';
 import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
 import { resolveApiContext } from '../lib/config.js';
 import { getFabricRPC } from '../lib/http.js';
+import { resolveStageId } from '../lib/stage.js';
 export const FabricSecretsListInput = z.object({
     branch: z.string(),
     json: z.boolean().optional(),
 });
-export const FabricSecretsListOutput = z.object({ names: z.array(z.string()) });
+export const FabricSecretsListOutput = z.object({
+    secrets: z.array(z.object({ name: z.string(), updatedAt: z.string() })),
+});
 export const FabricSecretsList = pikkuSessionlessFunc({
-    description: 'List secret names visible to a stage (values never leave the server).',
+    description: 'List the secrets set on a stage, by name. Values are sealed to the stage and never leave it.',
     input: FabricSecretsListInput,
     output: FabricSecretsListOutput,
     func: async (_services, { branch, json }) => {
@@ -18,19 +21,18 @@ export const FabricSecretsList = pikkuSessionlessFunc({
         if (!ctx.projectId)
             throw new Error('No fabric project linked. Run `pikku fabric link` first.');
         const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const result = await rpc.invoke('listStageSecrets', {
-            projectId: ctx.projectId,
-            branch,
-        });
+        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        const result = await rpc.invoke('listStageSecretNames', { stageId });
         if (json) {
-            console.log(JSON.stringify({ branch, names: result.names }, null, 2));
+            console.log(JSON.stringify({ branch, secrets: result.secrets }, null, 2));
         }
-        else if (result.names.length === 0) {
+        else if (result.secrets.length === 0) {
             console.log(`[fabric] no secrets set on ${branch}`);
         }
         else {
-            for (const name of result.names)
-                console.log(name);
+            for (const { name, updatedAt } of result.secrets) {
+                console.log(`${name}\t${updatedAt}`);
+            }
         }
         return result;
     },