@pikku/core 0.12.115 → 0.12.117

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## 0.12.117
+
+### Patch Changes
+
+- 8a0ecb7: `pikku scenario run <env> --run browser --strict` now refuses every route off the run surface, rather than only reporting one at the end. An action step that would fall back to its `default` binding throws `ScenarioNoSurfaceBinding` even when it declares `default`, and a `then` witnessed only server-side throws the new `ScenarioUnwitnessedAssertion`. Without `--strict` nothing changes: the fallback still runs and the unwitnessed assertion is still counted into the coverage line.
+
+  It exists because a run is becoming a source of documentation. A docs build runs the suite `--run browser --strict`, so a feature that cannot be driven end to end through the UI cannot produce a page — no flow where three steps are screenshots and the fourth quietly happened over RPC with nothing to show. The refusal names the step, the surface the run asked for and the surfaces that did bind it, which turns "what still has no browser binding" into a worklist the run prints rather than something to go looking for.
+
+  `--strict` on `--run default` is accepted and does nothing, since nothing on the default surface can fall back or be witnessed elsewhere. `PikkuScenarioService.setRunSurface` takes the flag as a second argument, and `isStrictSurface()` reads it back.
+
+## 0.12.116
+
+### Patch Changes
+
+- 87971bd: `browser.screenshot('the order, confirmed', { showcase: true })` marks one shot as fit to publish outside the run, and the artifact ledger carries the flag. A gallery, a docs page or a marketing card can then be built from the scenario run itself instead of a second browser pass configured somewhere else, and the author of the step — the only one who knows the page is at a moment worth showing a stranger — is who decides.
+
+  Each filed screenshot also carries an `id`: the same shot under one key across runs. `path` leads with the order the run happened in, so inserting a step ahead of a shot renumbers it and anything meant to outlive one run (a caption override, a diff against last week's build) loses track of it.
+
+  Two supporting fixes in `@pikku/playwright`: contexts open at a pinned `viewport` (1440x900, overridable per config or via `E2E_VIEWPORT_WIDTH`/`E2E_VIEWPORT_HEIGHT`) and screenshots are taken with animations disabled, so two runs of the same scenario photograph the same thing. `{ fullPage: true }` is available for shots of a whole scrollable page.
+
+- b312867: A project can now serve several MCP endpoints, one per connector.
+
+  Until now every MCP tool in a project was pooled onto a single `/mcp`, so a hub offering three connectors offered one endpoint listing all three connectors' tools at once. A client pointed at it saw tools it had no business calling, and the only way to give a connector an endpoint of its own was to give it a deployment of its own — three deploys, three bills, three service graphs.
+
+  `wireAddon` gains `mcpEndpoint`. `true` serves that instance's tools at `/mcp/<name>`; a string is the path, used as given. Leaving it unset keeps the tools on the shared endpoint, which is where they have always been, so nothing existing moves.
+
+  A surfaced instance now gets its own manifest (`.pikku/mcp/mcp.<name>.gen.json`, carrying the path it answers on), its own deploy unit (`mcp-<name>`, routed on that path), and its own MCP server — with its own tool list, so a client pointed at one endpoint never sees another's tools. The plumbing for the per-surface manifest and unit already existed in `deploy apply`; nothing had ever produced one.
+
+  `pikku dev` mounts every endpoint the generated tree describes, not just the default one. Without that a project that moved its tools onto their own endpoints would have served nothing locally at all — the default manifest it reads is empty precisely because they moved — and the only way to try a connector would have been to deploy it.
+
+  The node and bun transports take `mcpSurfaces` alongside `mcpJson` and mount each at its own path, longest path first. `/mcp` claims everything beneath `/mcp/`, so without that ordering the default endpoint answers `/mcp/weather` and the surface's tools are unreachable.
+
+  OAuth discovery is split between the endpoints rather than duplicated across them. RFC 9728 folds a resource's path into its well-known route, so each endpoint's own document is already distinct, but the path-less `/.well-known/oauth-protected-resource` predates that and describes whichever resource answers it. Only the default endpoint claims it — otherwise every unit registers the same route and the provider's router decides which resource a client is told about, and in dev a client probing it is described whichever surface sorted first.
+
+- 51bd35a: Document five public keys that carried no JSDoc: `wireChannel`'s `onDisconnect`,
+  `wireRemoteAddon`'s `serverUrl` and `tags`, and `CoreUserSession`'s `userId` and
+  `orgId`. A key printed as a name and a type is a shape; what a caller needs is
+  what to put in it, and only the JSDoc where the type is declared carries that
+  into the IDE, the console and the shipped surface doc at once.
+
 ## 0.12.115
 
 ### Patch Changes

package/dist/types/core.types.d.ts

@@ -81,7 +81,9 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
     postgres?: PostgresConfig;
 } & Config;
 export interface CoreUserSession {
+    /** Who the session belongs to, as your own system identifies them. Pikku only carries it. */
     userId?: string;
+    /** The tenant the session is acting inside, when the project has more than one. */
     orgId?: string;
     /** True when the session belongs to a synthetic scenario actor — lets audits/analytics address synthetic traffic */
     actor?: boolean;

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

@@ -16,6 +16,18 @@ export type WireAddonConfig = {
      * and is typed against the addon's function names.
      */
     mcp?: boolean | string[];
+    /**
+     * Serves this addon's MCP tools on an endpoint of their own rather than
+     * folding them into the project's single `/mcp`. `true` mounts them at
+     * `/mcp/<name>`; a string is the path, used as given.
+     *
+     * This is what lets one project expose several connectors: each wired
+     * instance becomes its own MCP server, with its own tool list, so a client
+     * pointed at one never sees another's tools. Leaving it unset keeps the
+     * addon's tools on the shared endpoint, which is where they have always
+     * been.
+     */
+    mcpEndpoint?: boolean | string;
     /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /** Required of every function in the addon, on top of the function's own. */

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

@@ -12,11 +12,13 @@ export type WireRemoteAddonConfig = {
     name: string;
     /** Must be installed as a devDependency — `pikku verify` enforces this. */
     package: string;
+    /** Where the addon is deployed, e.g. `https://registry.example.com`. A function when it varies per environment. */
     serverUrl: string | ((services: CoreServices) => string | Promise<string>);
     /** Omit when the addon declares its remote surface public. */
     auth?: RemoteAddonAuth;
     /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
     remoteName?: (fn: string) => string;
+    /** Applied to every function the addon contributes, so tag middleware and permissions reach them. */
     tags?: string[];
 };
 /**

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

@@ -68,6 +68,7 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
         func?: ChannelConnect;
         middleware?: PikkuMiddleware[];
     };
+    /** Runs once after the socket closes, however it closed. Nothing it returns reaches the client. */
     onDisconnect?: ChannelDisconnect | {
         func?: ChannelDisconnect;
         middleware?: PikkuMiddleware[];

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

@@ -21,12 +21,24 @@ export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'mid
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
+    /**
+     * The MCP endpoint this belongs to, when the project serves more than one.
+     * Absent means the project's default endpoint. Codegen splits the metadata
+     * by this key, so each endpoint's manifest lists only its own.
+     */
+    surface?: string;
 }>;
 export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
+    /**
+     * The MCP endpoint this belongs to, when the project serves more than one.
+     * Absent means the project's default endpoint. Codegen splits the metadata
+     * by this key, so each endpoint's manifest lists only its own.
+     */
+    surface?: string;
 }>;
 export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
     pikkuFuncId: string;
@@ -38,6 +50,12 @@ export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middlew
         required: boolean;
     }>;
     middleware?: MiddlewareMetadata[];
+    /**
+     * The MCP endpoint this belongs to, when the project serves more than one.
+     * Absent means the project's default endpoint. Codegen splits the metadata
+     * by this key, so each endpoint's manifest lists only its own.
+     */
+    surface?: string;
 }>;
 export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     /** How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema. */

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -6,7 +6,7 @@ import type { ScenarioPersonas } from '../../services/personas-service.js';
 import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
-export type { CoreFeature, CoreFeatureScenario, FeatureMeta, FeaturesMeta, PikkuBrowserWire, PikkuScenarioWire, ScenarioBrowserFailure, ScenarioBrowserProvider, ScenarioEnvironment, ScenarioStepKind, ScenarioStepMeta, ScenarioStepOptions, ScenarioStepPhase, ScenarioSurface, TestIdSelector, } from './scenario.types.js';
+export type { CoreFeature, CoreFeatureScenario, FeatureMeta, FeaturesMeta, PikkuBrowserWire, PikkuScenarioWire, ScenarioBrowserFailure, ScenarioBrowserProvider, ScenarioEnvironment, ScenarioStepKind, ScenarioStepMeta, ScenarioStepOptions, ScenarioScreenshotOptions, ScenarioStepPhase, ScenarioSurface, TestIdSelector, } from './scenario.types.js';
 export type { ScenarioArtifact, ScenarioFailureDetail, ScenarioResult, ScenarioRunRecord, ScenarioRunReport, ScenarioRunStatus, ScenarioRunStore, ScenarioRunSummary, ScenarioStepRow, } from './scenario-run.types.js';
 export { SCENARIO_SURFACES } from './scenario-step.types.js';
 export { resolveScenarioSurfaces } from './scenario-surface.js';
@@ -92,6 +92,9 @@ export declare class ScenarioActorRequired extends PikkuError {
  * coverage gap. (A `then` that ran somewhere, just not on the run surface, is
  * the coverage gap; it is reported rather than thrown. See
  * {@link ScenarioNoWitness} for one that ran nowhere.)
+ *
+ * A strict run also throws it for a step that *could* fall back, because there
+ * the fallback is the thing being refused.
  */
 export declare class ScenarioNoSurfaceBinding extends PikkuError {
     readonly stepFunc: string;
@@ -114,6 +117,22 @@ export declare class ScenarioNoWitness extends PikkuError {
     readonly runSurface: ScenarioSurface;
     constructor(stepFunc: string, declared: ScenarioSurface[], runSurface: ScenarioSurface);
 }
+/**
+ * An assertion ran, but not on the surface the run targets.
+ *
+ * The sibling of {@link ScenarioNoWitness}: that one checked nothing anywhere,
+ * this one checked the system of record while the prose claims the actor saw it
+ * on the page. Ordinary runs count it as a coverage gap; a strict run refuses
+ * it, because a flow that cannot be observed end to end on the run surface is
+ * not a flow that surface can be documented from.
+ */
+export declare class ScenarioUnwitnessedAssertion extends PikkuError {
+    readonly stepFunc: string;
+    readonly declared: ScenarioSurface[];
+    readonly runSurface: ScenarioSurface;
+    readonly witnessedOn: ScenarioSurface[];
+    constructor(stepFunc: string, declared: ScenarioSurface[], runSurface: ScenarioSurface, witnessedOn: ScenarioSurface[]);
+}
 /**
  * The scenario capability, layered onto a workflow service rather than being
  * one.
@@ -145,13 +164,21 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     private scenarioBrowserProvider?;
     private scenarioEnvironment?;
     private runSurface;
+    private strictSurface;
     constructor(engine: WorkflowRunEngine);
     /**
      * The surface every actor drives the system through for this run, set once by
      * the runner from `--run`. `default` is the server-side path — the fast suite.
+     *
+     * `strict` removes both routes off that surface: an action may not fall back
+     * to its `default` binding, and a `then` may not be witnessed anywhere else.
+     * It is what lets a run stand as evidence of the whole flow on one surface,
+     * which is what generating documentation from a run requires. On a `default`
+     * run it changes nothing, because nothing there can fall back.
      */
-    setRunSurface(surface: ScenarioSurface): void;
+    setRunSurface(surface: ScenarioSurface, strict?: boolean): void;
     getRunSurface(): ScenarioSurface;
+    isStrictSurface(): boolean;
     /**
      * Registered by `@pikku/playwright` (or any other driver) before a scenario
      * runs. Absent means browser steps cannot run, which the CLI checks up front

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -132,14 +132,21 @@ addError(ScenarioActorRequired, {
  * coverage gap. (A `then` that ran somewhere, just not on the run surface, is
  * the coverage gap; it is reported rather than thrown. See
  * {@link ScenarioNoWitness} for one that ran nowhere.)
+ *
+ * A strict run also throws it for a step that *could* fall back, because there
+ * the fallback is the thing being refused.
  */
 export class ScenarioNoSurfaceBinding extends PikkuError {
     stepFunc;
     declared;
     runSurface;
     constructor(stepFunc, declared, runSurface) {
-        super(`[scenario] step '${stepFunc}' declares no binding for '${runSurface}' and no 'default' to fall back to ` +
-            `(declares: ${declared.join(', ') || 'nothing'}).`);
+        const declares = `(declares: ${declared.join(', ') || 'nothing'})`;
+        super(declared.includes('default')
+            ? `[scenario] step '${stepFunc}' has no binding for '${runSurface}' and a strict run will not let it ` +
+                `fall back to 'default' ${declares}. Add a '${runSurface}' binding, or drop --strict.`
+            : `[scenario] step '${stepFunc}' declares no binding for '${runSurface}' and no 'default' to fall back to ` +
+                `${declares}.`);
         this.stepFunc = stepFunc;
         this.declared = declared;
         this.runSurface = runSurface;
@@ -175,6 +182,34 @@ addError(ScenarioNoWitness, {
     status: 500,
     message: 'Assertion has no witness for this surface.',
 });
+/**
+ * An assertion ran, but not on the surface the run targets.
+ *
+ * The sibling of {@link ScenarioNoWitness}: that one checked nothing anywhere,
+ * this one checked the system of record while the prose claims the actor saw it
+ * on the page. Ordinary runs count it as a coverage gap; a strict run refuses
+ * it, because a flow that cannot be observed end to end on the run surface is
+ * not a flow that surface can be documented from.
+ */
+export class ScenarioUnwitnessedAssertion extends PikkuError {
+    stepFunc;
+    declared;
+    runSurface;
+    witnessedOn;
+    constructor(stepFunc, declared, runSurface, witnessedOn) {
+        super(`[scenario] assertion '${stepFunc}' was checked on ${witnessedOn.join(', ')}, not on '${runSurface}'. ` +
+            `It held there — but nothing looked at '${runSurface}', which is what the step's prose claims the actor saw. ` +
+            `Add a '${runSurface}' witness (declares: ${declared.join(', ') || 'nothing'}), or drop --strict.`);
+        this.stepFunc = stepFunc;
+        this.declared = declared;
+        this.runSurface = runSurface;
+        this.witnessedOn = witnessedOn;
+    }
+}
+addError(ScenarioUnwitnessedAssertion, {
+    status: 500,
+    message: 'Assertion was checked, but not on the run surface.',
+});
 /**
  * The scenario capability, layered onto a workflow service rather than being
  * one.
@@ -211,19 +246,30 @@ export class PikkuScenarioService {
     scenarioBrowserProvider;
     scenarioEnvironment;
     runSurface = 'default';
+    strictSurface = false;
     constructor(engine) {
         this.engine = engine;
     }
     /**
      * The surface every actor drives the system through for this run, set once by
      * the runner from `--run`. `default` is the server-side path — the fast suite.
+     *
+     * `strict` removes both routes off that surface: an action may not fall back
+     * to its `default` binding, and a `then` may not be witnessed anywhere else.
+     * It is what lets a run stand as evidence of the whole flow on one surface,
+     * which is what generating documentation from a run requires. On a `default`
+     * run it changes nothing, because nothing there can fall back.
      */
-    setRunSurface(surface) {
+    setRunSurface(surface, strict = false) {
         this.runSurface = surface;
+        this.strictSurface = strict;
     }
     getRunSurface() {
         return this.runSurface;
     }
+    isStrictSurface() {
+        return this.strictSurface;
+    }
     /**
      * Registered by `@pikku/playwright` (or any other driver) before a scenario
      * runs. Absent means browser steps cannot run, which the CLI checks up front
@@ -605,7 +651,8 @@ export class PikkuScenarioService {
                 });
             };
             if (resolution.kind === 'action') {
-                if (resolution.fellBack && !declared.includes('default')) {
+                if (resolution.fellBack &&
+                    (this.strictSurface || !declared.includes('default'))) {
                     throw new ScenarioNoSurfaceBinding(resolvedStepFunc, declared, this.runSurface);
                 }
                 return await runOnSurface(resolution.surface);
@@ -613,6 +660,9 @@ export class PikkuScenarioService {
             if (resolution.surfaces.length === 0) {
                 throw new ScenarioNoWitness(resolvedStepFunc, declared, this.runSurface);
             }
+            if (this.strictSurface && resolution.unwitnessed) {
+                throw new ScenarioUnwitnessedAssertion(resolvedStepFunc, declared, this.runSurface, resolution.surfaces);
+            }
             // A `then` runs every witness it has and they must agree. The surface
             // witness runs first so that when the page is the thing that is wrong,
             // it is the failure that surfaces.

package/dist/wirings/workflow/scenario-run.types.d.ts

@@ -31,6 +31,15 @@ export interface ScenarioArtifact {
     actor?: string;
     /** The caption the scenario author took a screenshot under. */
     name?: string;
+    /**
+     * The same shot across runs, under one key. `path` carries the order the run
+     * happened in, so it moves whenever a step is inserted before it — nothing
+     * that outlives a run (a caption override, a diff against last week) can key
+     * off it.
+     */
+    id?: string;
+    /** Fit to show outside the run: a marketing card, a docs page, a gallery. */
+    showcase?: boolean;
 }
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -166,11 +166,22 @@ export interface TestIdSelector {
  * interface via `declare module`, so `wire.browser.page` is a fully typed
  * Playwright `Page` in a project that installs it.
  */
+/** How one deliberate screenshot is taken, and what it is for. */
+export interface ScenarioScreenshotOptions {
+    /**
+     * Publish this one outside the run — a marketing card, a docs page, a
+     * gallery. Declared at the call site because only the author of the step
+     * knows the page is at a moment worth showing a stranger.
+     */
+    showcase?: boolean;
+    /** Photograph the whole scrollable page rather than the viewport. */
+    fullPage?: boolean;
+}
 export interface PikkuBrowserWire {
     /** The actor whose browser context this is */
     readonly actor: string;
     goto(url: string): Promise<void>;
-    screenshot(name?: string): Promise<Uint8Array>;
+    screenshot(name?: string, options?: ScenarioScreenshotOptions): Promise<Uint8Array>;
 }
 /**
  * What one actor's window looked like at the moment a scenario failed.

package/dist/wirings/workflow/scenario.types.d.ts

@@ -1,6 +1,6 @@
 import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
 export type { ScenarioStepInvocation, ScenarioStepMeta, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
-export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
+export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, PikkuBrowserWire, ScenarioScreenshotOptions, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
 export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
     scenario: CorePikkuFunctionConfig<any, any, any>;
     data: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.115",
+  "version": "0.12.117",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/src/public-surface.json

@@ -82,6 +82,7 @@
     "ScenarioHookError",
     "ScenarioNoSurfaceBinding",
     "ScenarioNoWitness",
+    "ScenarioUnwitnessedAssertion",
     "ScenarioWitnessDisagreement",
     "addFeature",
     "composeStepProse",