@pikku/inspector 0.12.85 → 0.12.87

package/CHANGELOG.md

@@ -1,3 +1,84 @@
+## 0.12.87
+
+### Patch Changes
+
+- a95179a: An AI agent's `providerOptions` now reaches the generated metadata.
+
+  The inspector read `model`, `temperature`, `maxSteps` and `toolChoice` off an agent declaration but never `providerOptions`, so `agentsMeta` always showed an agent with no provider configuration — even though the type says it carries one. Runs were unaffected, since the runner takes the value from the live agent object, which is exactly why the gap went unnoticed by everything except what reads the compiled meta: the console's agent view and `infra.json`.
+
+  The value is read as an object literal of strings, numbers, booleans, arrays and nested objects, all-or-nothing. A computed one is reported as `PKU156` rather than silently dropped.
+
+- 145b32b: Generated type aliases are deterministic
+
+  A type name that collided across files got a `Math.random()` suffix, so every
+  `pikku all` emitted different names into `pikku-agent-map.gen.d.ts` and
+  `pikku-workflow-map.gen.d.ts`. Those files sit in the schema generator's
+  dependency closure, so rewriting them invalidated the schema cache partway
+  through the same run and forced a full `ts-json-schema-generator` pass each
+  time. The suffix now comes from the declaring file's path.
+
+- 42b7ac3: The app decides which of an addon's functions `rpc.exposed` reaches
+
+  `wireAddon` takes `expose?: boolean | string[]`, mirroring `mcp`. Unset or
+  `true` keeps the functions the addon declared `expose: true`; `false` exposes
+  none of the instance's functions; a list names exactly the functions to expose,
+  whether or not the addon declared them, typed against the addon's function
+  names. A listed name the addon does not publish fails the build with PKU343, a value that is not written inline fails it with
+  PKU344,
+  and the deploy analyzer's per-addon unit carries only what the wiring exposes.
+
+- Updated dependencies [4a9dcd2]
+- Updated dependencies [5ab24ad]
+- Updated dependencies [42b7ac3]
+  - @pikku/core@0.12.120
+
+## 0.12.86
+
+### Patch Changes
+
+- f05fb4e: A scenario that belongs to no feature is now reported.
+
+  Features are what the guide is written against: prose cites a feature, and the compiler fills that citation with the evidence from the scenarios the feature owns. A scenario nobody listed is therefore invisible — it runs, it captures screenshots and recordings, and none of it ever reaches a page. That failure is silent today, and it is the single reason two real projects have hundreds of captures bound to nothing.
+
+  The inspector now walks every feature's scenario list, and any scenario not claimed by one is reported as `PKU682`. It is an error rather than a critical, so `pikku all` keeps passing by default and the list is there to work through; `--fail-on-error` makes it a wall once a project has caught up.
+
+  Membership reads the scenario each entry names, not the entry itself. A `data` the AST cannot evaluate — `'a'.repeat(64)`, a call, anything computed — leaves the entry partial for the console but says nothing about who owns the scenario, and the check no longer treats the two as the same thing.
+
+  An entry that names no scenario at all — a spread, a `.map()` — does leave membership unknown. That only matters once something is already unowned, so the check reports it then, as a warn naming both the unowned scenarios and the features that could be hiding them, rather than accusing a scenario that may well be in one of those arrays.
+
+- b4a895e: `pikku scenario guide` writes the user guide a scenario suite already contains. A feature reads as a page and a scenario as a section, and a run leaves screenshots behind with the captions their author took them under — the command joins that to the editorial prose a project checks in under `docs/` and writes markdown. It renders no HTML, ships no components, resolves no asset URLs and calls no model: an image is an ordinary relative `![caption](path)`, and whoever consumes the markdown rewrites the paths.
+
+  A page cites a feature by leaving the marker pair where the block belongs:
+
+  ```markdown
+  ---
+  title: Deployments
+  ---
+
+  A deployment is one tracked shipment of your app.
+
+  <!-- pikku:guide feature=deploymentsFeature -->
+  <!-- /pikku:guide -->
+
+  ## Does my app go down during a deploy?
+  ```
+
+  That one line does both halves of the job. It says _where_ the block goes, which a frontmatter list cannot express, and it is what the coverage gate counts to decide _whether_ a feature is documented at all. The mapping stays many-to-many and falls out of the union of every marker in the tree. A rebuild rewrites exactly the regions between the markers, so every sentence a human wrote around them survives.
+
+  **The steps are evidence, not content.** A generated block is the scenario's title, the description its author wrote, and the shots it filed — never a numbered Given/When/Then ladder, which is a test report and not something anybody arrives at a documentation page wanting. The sentences are still what the guide is kept honest against: `docs/.guide.lock` records a hash of each feature's step sentences and artifact ids, deliberately not of the image bytes. Restyling a UI changes every screenshot and no sentence; inserting or renaming a step changes what the prose was describing, and the page is reported stale. The lock is generated and checked in, so no hash is ever typed or merged by hand — and a tree whose lock is untracked reports every page as current forever.
+
+  Every registered feature has to be cited by some page, and a feature that is pure plumbing says so rather than being written about — `pikkuFeature({ document: false })`, threaded through the inspector and `FeatureMeta`. An uncited feature fails the command by name; `--allow-undocumented` downgrades that one failure to a report. A page citing a feature id that is not registered stays an error either way.
+
+  A guide is only written out of a run that can stand behind it. A run that failed or was killed halfway is refused, because a page is a claim that the product does what it says. So is a narrowed one: `pikku scenario run --flows`/`--features`/`--tags` leaves out scenarios the suite has, and a guide built from it would describe those flows as though they do not exist. `ScenarioRunRecord.selection` records the filters a run was selected with, since nothing in the results afterwards can tell a suite of forty from forty that were asked for.
+
+  Results are joined to features by `featureId`, falling back to the display name only for records written before that field existed — a title is rewritten freely and two features may share one.
+
+  Emission is deterministic — identical inputs give byte-identical output, and no timestamp goes in that did not come from the run record. Frontmatter the compiler does not own (`slug`, `draft`, `sidebar_position`, anything else a docs site reads) passes through untouched, and a source written with CRLF line endings is read as having frontmatter.
+
+- Updated dependencies [b4a895e]
+- Updated dependencies [b4a895e]
+  - @pikku/core@0.12.118
+
 ## 0.12.85
 
 ### Patch Changes

package/dist/add/add-agent.d.ts

@@ -1,4 +1,14 @@
 import * as ts from 'typescript';
 import type { AddWiring, InspectorLogger } from '../types.js';
+/**
+ * Reads `providerOptions` off the declaration so it survives into `agentsMeta`.
+ *
+ * The runner takes the value from the live agent object, so an in-process run
+ * honours it either way — but everything that reads the compiled meta instead
+ * (the console's agent view, `infra.json`, the deploy analyzer) saw an agent
+ * with no provider configuration at all. A computed value is reported rather
+ * than dropped, because that is the case nobody notices.
+ */
+export declare function resolveProviderOptions(obj: ts.ObjectLiteralExpression, agentName: string, logger: InspectorLogger): Record<string, Record<string, unknown>> | null;
 export declare function resolveWorkflowReferences(obj: ts.ObjectLiteralExpression, checker: ts.TypeChecker, agentName: string, logger: InspectorLogger): string[] | null;
 export declare const addAgent: AddWiring;

package/dist/add/add-agent.js

@@ -4,8 +4,33 @@ import { extractWireNames } from '../utils/post-process.js';
 import { extractFunctionName, funcIdToTypeName, } from '../utils/extract-function-name.js';
 import { resolveMiddleware, resolveChannelMiddleware, resolveAgentMiddleware, } from '../utils/middleware.js';
 import { resolvePermissions } from '../utils/permissions.js';
+import { getProperty, jsonObjectProperty } from '../utils/literal-properties.js';
 import { ErrorCode } from '../error-codes.js';
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
+/**
+ * Reads `providerOptions` off the declaration so it survives into `agentsMeta`.
+ *
+ * The runner takes the value from the live agent object, so an in-process run
+ * honours it either way — but everything that reads the compiled meta instead
+ * (the console's agent view, `infra.json`, the deploy analyzer) saw an agent
+ * with no provider configuration at all. A computed value is reported rather
+ * than dropped, because that is the case nobody notices.
+ */
+export function resolveProviderOptions(obj, agentName, logger) {
+    if (!getProperty(obj, 'providerOptions')) {
+        return null;
+    }
+    const providerOptions = jsonObjectProperty(obj, 'providerOptions');
+    if (!providerOptions) {
+        logger.diagnostic({
+            severity: 'warn',
+            code: ErrorCode.AGENT_PROVIDER_OPTIONS_UNREADABLE,
+            message: `AI agent '${agentName}' has a 'providerOptions' the inspector cannot read statically, so it is missing from the generated metadata. Inline it as an object literal of strings, numbers, booleans, arrays and nested objects.`,
+        });
+        return null;
+    }
+    return providerOptions;
+}
 function resolveToolReferences(obj, checker, agentName, logger) {
     const property = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
         ts.isIdentifier(p.name) &&
@@ -267,6 +292,7 @@ export const addAgent = (logger, node, checker, state, options) => {
         const maxStepsValue = getPropertyValue(obj, 'maxSteps');
         const temperatureValue = getPropertyValue(obj, 'temperature');
         const toolChoiceValue = getPropertyValue(obj, 'toolChoice');
+        const providerOptionsValue = resolveProviderOptions(obj, nameValue || '', logger);
         const scorersValue = resolveScorerNames(obj, nameValue || '', logger);
         const toolsValue = resolveToolReferences(obj, checker, nameValue || '', logger);
         if (toolsValue) {
@@ -410,6 +436,9 @@ export const addAgent = (logger, node, checker, state, options) => {
             ...(toolChoiceValue !== null && {
                 toolChoice: toolChoiceValue,
             }),
+            ...(providerOptionsValue !== null && {
+                providerOptions: providerOptionsValue,
+            }),
             ...(toolsValue !== null && { tools: toolsValue }),
             ...(agentsValue !== null && { agents: agentsValue }),
             ...(workflowsValue !== null && { workflows: workflowsValue }),

package/dist/add/add-feature.js

@@ -96,6 +96,16 @@ const stringProperty = (config, name) => {
     const value = getProperty(config, name);
     return value && ts.isStringLiteralLike(value) ? value.text : undefined;
 };
+const booleanProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value) {
+        return undefined;
+    }
+    if (value.kind === ts.SyntaxKind.TrueKeyword) {
+        return true;
+    }
+    return value.kind === ts.SyntaxKind.FalseKeyword ? false : undefined;
+};
 const stringArrayProperty = (config, name) => {
     const value = getProperty(config, name);
     if (!value || !ts.isArrayLiteralExpression(value)) {
@@ -106,6 +116,16 @@ const stringArrayProperty = (config, name) => {
         .map((e) => e.text);
     return values.length === value.elements.length ? values : undefined;
 };
+const mentionedScenario = (element, checker) => {
+    if (ts.isIdentifier(element)) {
+        return scenarioName(element, checker);
+    }
+    if (ts.isObjectLiteralExpression(element)) {
+        const reference = getProperty(element, 'scenario');
+        return reference ? scenarioName(reference, checker) : undefined;
+    }
+    return undefined;
+};
 const readEntry = (element, checker) => {
     if (ts.isIdentifier(element)) {
         const scenario = scenarioName(element, checker);
@@ -164,6 +184,8 @@ export const addFeature = (logger, node, checker, state) => {
         exportedName,
         entries: [],
         unresolvedEntries: 0,
+        mentions: [],
+        unnamedEntries: 0,
         hasBefore: false,
         hasAfter: false,
     };
@@ -172,6 +194,10 @@ export const addFeature = (logger, node, checker, state) => {
         const name = stringProperty(config, 'name');
         const description = stringProperty(config, 'description');
         const tags = stringArrayProperty(config, 'tags');
+        const document = booleanProperty(config, 'document');
+        if (document !== undefined) {
+            feature.document = document;
+        }
         if (name !== undefined) {
             feature.name = name;
         }
@@ -186,6 +212,13 @@ export const addFeature = (logger, node, checker, state) => {
         const scenarios = getProperty(config, 'scenarios');
         if (scenarios && ts.isArrayLiteralExpression(scenarios)) {
             for (const element of scenarios.elements) {
+                const mention = mentionedScenario(element, checker);
+                if (mention) {
+                    feature.mentions.push(mention);
+                }
+                else {
+                    feature.unnamedEntries += 1;
+                }
                 const entry = readEntry(element, checker);
                 if (entry) {
                     feature.entries.push(entry);

package/dist/add/add-wire-addon.js

@@ -1,4 +1,5 @@
 import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
 function parseStringArray(node) {
     if (!ts.isArrayLiteralExpression(node))
         return undefined;
@@ -95,6 +96,7 @@ export function addWireAddon(node, state, logger) {
     let pkg;
     let rpcEndpoint;
     let mcp;
+    let expose;
     let mcpEndpoint;
     let auth;
     let tags;
@@ -126,6 +128,18 @@ export function addWireAddon(node, state, logger) {
                     ? prop.initializer.kind === ts.SyntaxKind.TrueKeyword
                     : parseStringArray(prop.initializer);
         }
+        else if (key === 'expose') {
+            expose =
+                prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                    prop.initializer.kind === ts.SyntaxKind.FalseKeyword
+                    ? prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+                    : parseStringArray(prop.initializer);
+            // Read as unset, the deploy analyzer would build this addon's unit from
+            // the addon's own declarations while the runtime follows the real list.
+            if (expose === undefined) {
+                logger.critical(ErrorCode.ADDON_EXPOSE_NOT_STATIC, `wireAddon's expose must be true, false or an array of string literals, got: ${prop.initializer.getText()}`);
+            }
+        }
         else if (key === 'mcpEndpoint') {
             if (ts.isStringLiteral(prop.initializer)) {
                 mcpEndpoint = prop.initializer.text;
@@ -186,6 +200,7 @@ export function addWireAddon(node, state, logger) {
         rpcEndpoint,
         mcp,
         mcpEndpoint,
+        expose,
         auth,
         tags,
         scopes,

package/dist/error-codes.d.ts

@@ -25,6 +25,7 @@ export declare enum ErrorCode {
     SCENARIO_NOT_EXTRACTABLE = "PKU679",
     SCENARIO_HAS_NO_ASSERTION = "PKU680",
     SCENARIO_STEP_PROSE_NAMES_ACTOR = "PKU681",
+    SCENARIO_HAS_NO_FEATURE = "PKU682",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",
     WORKFLOW_GRAPH_ADDON_NOT_WIRED = "PKU642",
@@ -33,6 +34,8 @@ export declare enum ErrorCode {
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
     ADDON_NOT_INSTALLED = "PKU340",
     ADDON_MCP_FUNCTION_NOT_FOUND = "PKU341",
+    ADDON_EXPOSE_FUNCTION_NOT_FOUND = "PKU343",
+    ADDON_EXPOSE_NOT_STATIC = "PKU344",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
@@ -66,6 +69,7 @@ export declare enum ErrorCode {
     AGENT_TOOL_NOT_FOUND = "PKU153",
     AGENT_TOOL_MISSING_DESCRIPTION = "PKU154",
     AGENT_SCORER_NOT_FOUND = "PKU155",
+    AGENT_PROVIDER_OPTIONS_UNREADABLE = "PKU156",
     SCHEMA_AND_WIRING_COLOCATED = "PKU490",
     SCHEMA_TRANSFORM_NOT_SUPPORTED = "PKU491",
     SERVICES_NOT_DESTRUCTURED = "PKU410",

package/dist/error-codes.js

@@ -27,6 +27,7 @@ export var ErrorCode;
     ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
     ErrorCode["SCENARIO_HAS_NO_ASSERTION"] = "PKU680";
     ErrorCode["SCENARIO_STEP_PROSE_NAMES_ACTOR"] = "PKU681";
+    ErrorCode["SCENARIO_HAS_NO_FEATURE"] = "PKU682";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";
@@ -36,6 +37,8 @@ export var ErrorCode;
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
     ErrorCode["ADDON_NOT_INSTALLED"] = "PKU340";
     ErrorCode["ADDON_MCP_FUNCTION_NOT_FOUND"] = "PKU341";
+    ErrorCode["ADDON_EXPOSE_FUNCTION_NOT_FOUND"] = "PKU343";
+    ErrorCode["ADDON_EXPOSE_NOT_STATIC"] = "PKU344";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
@@ -84,6 +87,8 @@ export var ErrorCode;
     ErrorCode["AGENT_TOOL_MISSING_DESCRIPTION"] = "PKU154";
     // Agent scorer reference errors
     ErrorCode["AGENT_SCORER_NOT_FOUND"] = "PKU155";
+    // Agent provider configuration errors
+    ErrorCode["AGENT_PROVIDER_OPTIONS_UNREADABLE"] = "PKU156";
     // File structure errors
     ErrorCode["SCHEMA_AND_WIRING_COLOCATED"] = "PKU490";
     // Schema authoring errors

package/dist/inspector.js

@@ -7,7 +7,7 @@ import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
@@ -405,6 +405,7 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validateWorkflowGraphAddons(logger, state);
         validateScenarioServices(logger, state);
         validateScenarioSteps(logger, state);
+        validateScenarioFeatures(logger, state);
         // Needs every route, every function and every wireAddon declaration
         // together, so it can only run once the whole program is inspected.
         annotateHttpRouteAuth(state);

package/dist/types-map.d.ts

@@ -6,6 +6,13 @@ export declare class TypesMap {
     }>;
     addCustomType(name: string, type: string, references: string[]): void;
     addType(originalName: string, path: string): void;
+    /**
+     * A pure function of the path, with no dependence on insertion order: the
+     * alias lands in generated `.d.ts` maps, and anything that varies between
+     * runs rewrites those files, which invalidates the schema cache mid-`pikku
+     * all` and costs a full ts-json-schema-generator pass each time. A counter
+     * over already-taken names would reintroduce that through traversal order.
+     */
     addUniqueType(originalName: string, path: string): string;
     getUniqueName(name: string): string;
     getTypeMeta(name: string): {

package/dist/types-map.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 export class TypesMap {
     map = new Map();
     customTypes = new Map();
@@ -7,8 +8,16 @@ export class TypesMap {
     addType(originalName, path) {
         this.map.set(originalName, { originalName, path });
     }
+    /**
+     * A pure function of the path, with no dependence on insertion order: the
+     * alias lands in generated `.d.ts` maps, and anything that varies between
+     * runs rewrites those files, which invalidates the schema cache mid-`pikku
+     * all` and costs a full ts-json-schema-generator pass each time. A counter
+     * over already-taken names would reintroduce that through traversal order.
+     */
     addUniqueType(originalName, path) {
-        const uniqueName = `${originalName}_${Math.random().toString(36).substring(7)}`;
+        const digest = createHash('sha256').update(path).digest('hex').slice(0, 12);
+        const uniqueName = `${originalName}_${digest}`;
         this.map.set(uniqueName, { originalName, path });
         return uniqueName;
     }

package/dist/types.d.ts

@@ -455,6 +455,8 @@ export interface InspectorFeature {
     name?: string;
     description?: string;
     tags?: string[];
+    /** `document: false` on the config, and only that — an absent flag documents. */
+    document?: boolean;
     entries: InspectorFeatureEntry[];
     /**
      * Entries that are not literal — a spread, a `.map()`, a call. Counted rather
@@ -462,6 +464,17 @@ export interface InspectorFeature {
      * quietly showing a short feature.
      */
     unresolvedEntries: number;
+    /**
+     * Every scenario the array names, including entries whose `data` could not be
+     * read. Membership is knowable there even when the entry is not — which is
+     * what the check for a scenario belonging to no feature compares against.
+     */
+    mentions: string[];
+    /**
+     * Entries that name no scenario at all — a spread, a `.map()`. Only these
+     * leave membership genuinely unknown.
+     */
+    unnamedEntries: number;
     /**
      * Feature hooks run once around the whole group, never per scenario, and are
      * runtime-only — so only their presence is recorded.
@@ -596,6 +609,13 @@ export interface InspectorState {
              * endpoint, which is where they have always been.
              */
             mcpEndpoint?: boolean | string;
+            /**
+             * Which functions `rpc.exposed` may call under `<name>:<function>`.
+             * Unset or `true` keeps what the addon declared `expose: true`; `false`
+             * exposes none; a list names exactly the functions to expose, whatever
+             * the addon declared.
+             */
+            expose?: boolean | string[];
             /**
              * The addon's own gates. `runPikkuFunc` applies these to every function
              * in the package, on every wiring path — not just `namespace:function`.

package/dist/utils/literal-properties.d.ts

@@ -20,3 +20,14 @@ export declare const booleanProperty: (config: ts.ObjectLiteralExpression, name:
 export declare const stringArrayProperty: (config: ts.ObjectLiteralExpression, name: string) => string[] | undefined;
 /** Unwraps `x as const` / `x satisfies T` so a cast is still extracted. */
 export declare const unwrapAs: (node: ts.Expression) => ts.Expression;
+/**
+ * Reads a property whose value is a JSON-shaped object literal — nested
+ * objects, arrays, strings, numbers, booleans and `null`.
+ *
+ * All-or-nothing for the same reason as `stringArrayProperty`, and then some:
+ * these values are handed to a provider verbatim, so a half-read
+ * `providerOptions` would send the model a *different* configuration from the
+ * one in source rather than none. `undefined` for anything computed lets the
+ * caller say so instead of guessing.
+ */
+export declare const jsonObjectProperty: (config: ts.ObjectLiteralExpression, name: string) => Record<string, unknown> | undefined;

package/dist/utils/literal-properties.js

@@ -67,3 +67,82 @@ export const stringArrayProperty = (config, name) => {
 export const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
     ? unwrapAs(node.expression)
     : node;
+/**
+ * Reads a property whose value is a JSON-shaped object literal — nested
+ * objects, arrays, strings, numbers, booleans and `null`.
+ *
+ * All-or-nothing for the same reason as `stringArrayProperty`, and then some:
+ * these values are handed to a provider verbatim, so a half-read
+ * `providerOptions` would send the model a *different* configuration from the
+ * one in source rather than none. `undefined` for anything computed lets the
+ * caller say so instead of guessing.
+ */
+export const jsonObjectProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value) {
+        return undefined;
+    }
+    const read = readJsonValue(value);
+    return read.ok && isPlainRecord(read.value) ? read.value : undefined;
+};
+const isPlainRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const UNREADABLE = { ok: false };
+const readJsonValue = (node) => {
+    const value = unwrapAs(node);
+    if (ts.isStringLiteralLike(value)) {
+        return { ok: true, value: value.text };
+    }
+    if (ts.isNumericLiteral(value)) {
+        return { ok: true, value: Number(value.text) };
+    }
+    if (ts.isPrefixUnaryExpression(value) &&
+        value.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(value.operand)) {
+        return { ok: true, value: -Number(value.operand.text) };
+    }
+    if (value.kind === ts.SyntaxKind.TrueKeyword) {
+        return { ok: true, value: true };
+    }
+    if (value.kind === ts.SyntaxKind.FalseKeyword) {
+        return { ok: true, value: false };
+    }
+    if (value.kind === ts.SyntaxKind.NullKeyword) {
+        return { ok: true, value: null };
+    }
+    if (ts.isArrayLiteralExpression(value)) {
+        const entries = [];
+        for (const element of value.elements) {
+            const read = readJsonValue(element);
+            if (!read.ok) {
+                return UNREADABLE;
+            }
+            entries.push(read.value);
+        }
+        return { ok: true, value: entries };
+    }
+    if (ts.isObjectLiteralExpression(value)) {
+        const record = {};
+        for (const property of value.properties) {
+            if (!ts.isPropertyAssignment(property)) {
+                return UNREADABLE;
+            }
+            const key = ts.isIdentifier(property.name)
+                ? property.name.text
+                : ts.isStringLiteralLike(property.name)
+                    ? property.name.text
+                    : ts.isNumericLiteral(property.name)
+                        ? property.name.text
+                        : null;
+            if (key === null) {
+                return UNREADABLE;
+            }
+            const read = readJsonValue(property.initializer);
+            if (!read.ok) {
+                return UNREADABLE;
+            }
+            record[key] = read.value;
+        }
+        return { ok: true, value: record };
+    }
+    return UNREADABLE;
+};

package/dist/utils/load-addon-functions-meta.js

@@ -188,6 +188,15 @@ export async function loadAddonFunctionsMeta(logger, state) {
                     }
                 }
             }
+            // Same reasoning as mcp: a listed name the addon does not publish is a
+            // function the app believes callable and never is.
+            if (Array.isArray(decl.expose)) {
+                for (const funcName of decl.expose) {
+                    if (!Object.hasOwn(meta, funcName)) {
+                        logger.critical(ErrorCode.ADDON_EXPOSE_FUNCTION_NOT_FOUND, `wireAddon('${namespace}') lists '${funcName}' under expose, but ${decl.package} publishes no such function.`);
+                    }
+                }
+            }
             // Load addon secrets meta
             try {
                 const secretsMetaPath = require.resolve(`${decl.package}/.pikku/secrets/pikku-secrets-meta.gen.json`);

package/dist/utils/post-process.d.ts

@@ -129,6 +129,31 @@ export declare const proseOpensWithActor: (prose: string, actor: string) => bool
  * singletons the step actually needs.
  */
 export declare function validateScenarioSteps(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Reports scenarios that no `pikkuFeature` lists.
+ *
+ * A feature is what a run stamps onto each result, and the only handle anything
+ * downstream has on a scenario: the console groups by it and the guide cites it.
+ * A scenario in no feature still runs and still passes — it simply files its
+ * results, and any screenshot or recording it took, where nothing can reach
+ * them. That is not a style violation, it is work being thrown away, and it is
+ * invisible precisely because the suite is green.
+ *
+ * It is an `error` rather than a `critical` because every suite written before
+ * the rule has some, and a hard failure on a CLI bump would strand them with no
+ * way to defer. `--fail-on-error` is how a project opts in once it has bound
+ * what it has.
+ *
+ * Membership reads the scenario each entry names, not the entry itself: a
+ * `data` the AST cannot evaluate leaves the entry partial for the console but
+ * says nothing about who owns the scenario.
+ *
+ * An entry that names no scenario at all (a spread, a `.map()`) does leave
+ * membership unknown. That only matters when something is already unowned, so
+ * the check reports it then and downgrades to a warn naming both sides, rather
+ * than accusing a scenario that may well be in that array.
+ */
+export declare function validateScenarioFeatures(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never

package/dist/utils/post-process.js

@@ -943,6 +943,79 @@ export function validateScenarioSteps(logger, state) {
         }
     }
 }
+/**
+ * Reports scenarios that no `pikkuFeature` lists.
+ *
+ * A feature is what a run stamps onto each result, and the only handle anything
+ * downstream has on a scenario: the console groups by it and the guide cites it.
+ * A scenario in no feature still runs and still passes — it simply files its
+ * results, and any screenshot or recording it took, where nothing can reach
+ * them. That is not a style violation, it is work being thrown away, and it is
+ * invisible precisely because the suite is green.
+ *
+ * It is an `error` rather than a `critical` because every suite written before
+ * the rule has some, and a hard failure on a CLI bump would strand them with no
+ * way to defer. `--fail-on-error` is how a project opts in once it has bound
+ * what it has.
+ *
+ * Membership reads the scenario each entry names, not the entry itself: a
+ * `data` the AST cannot evaluate leaves the entry partial for the console but
+ * says nothing about who owns the scenario.
+ *
+ * An entry that names no scenario at all (a spread, a `.map()`) does leave
+ * membership unknown. That only matters when something is already unowned, so
+ * the check reports it then and downgrades to a warn naming both sides, rather
+ * than accusing a scenario that may well be in that array.
+ */
+export function validateScenarioFeatures(logger, state) {
+    const features = state.workflows.featureFiles;
+    if (!features) {
+        return;
+    }
+    const owned = new Set();
+    for (const feature of features.values()) {
+        for (const mention of feature.mentions) {
+            owned.add(mention);
+        }
+    }
+    const files = state.workflows.files;
+    const unowned = [];
+    for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+        if (!meta.scenario) {
+            continue;
+        }
+        const exported = files?.get(workflowName)?.exportedName;
+        if (owned.has(workflowName) || (exported && owned.has(exported))) {
+            continue;
+        }
+        unowned.push(workflowName);
+    }
+    if (unowned.length === 0) {
+        return;
+    }
+    const unreadable = [...features.values()]
+        .filter((feature) => feature.unnamedEntries > 0)
+        .map((feature) => feature.exportedName);
+    if (unreadable.length > 0) {
+        logger.diagnostic({
+            severity: 'warn',
+            code: ErrorCode.SCENARIO_HAS_NO_FEATURE,
+            message: `${unowned.map((name) => `'${name}'`).join(', ')} appear in no feature's \`scenarios\` array, ` +
+                `but ${unreadable.map((name) => `'${name}'`).join(', ')} build theirs with a spread or a call, so one of them may still be listed there. ` +
+                `List those scenarios literally and this becomes a definite answer either way.`,
+        });
+        return;
+    }
+    for (const name of unowned) {
+        logger.diagnostic({
+            severity: 'error',
+            code: ErrorCode.SCENARIO_HAS_NO_FEATURE,
+            message: `Scenario '${name}' is listed by no pikkuFeature, so nothing downstream can reach it — ` +
+                `a run stamps no feature onto its results, the console groups it under none, and a guide cannot cite it. ` +
+                `Add it to a feature's \`scenarios\` array.`,
+        });
+    }
+}
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never

package/dist/utils/validate-exposed-functions-gated.js

@@ -16,28 +16,32 @@ export function validateExposedFunctionsGated(logger, state) {
     for (const [funcName, meta] of Object.entries(state.functions.meta)) {
         if (!meta.expose)
             continue;
-        // A pikkuFunc always requires a session, on every path.
-        if (meta.sessionless === false)
+        if (gatesItself(meta))
             continue;
-        // Scenario steps are refused by rpcExposed regardless of `expose`.
-        if (meta.scenarioStep)
-            continue;
-        // The author declared that the body authorizes its own callers — a gate
-        // this check has no way to see. Taking the claim at face value is the
-        // point: without it the warning fires forever on functions that are fine,
-        // and a warning that is usually wrong stops being read.
-        if (meta.permissionsInBody === true)
-            continue;
-        // The function gates itself.
-        if (meta.auth === true)
+        if (isGatedByItsAddon(state, meta.packageName))
             continue;
-        if (meta.scopes && meta.scopes.length > 0)
+        ungated.push(funcName);
+    }
+    // A `wireAddon` expose list can open an addon function its author never
+    // exposed, so the app that listed it is the one to tell. The namespaced call
+    // is governed by that instance's config alone.
+    //
+    // knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+    for (const [namespace, declaration] of state.rpc?.wireAddonDeclarations ??
+        []) {
+        if (!Array.isArray(declaration.expose))
             continue;
-        if (meta.permissions && meta.permissions.length > 0)
+        if (declaration.auth === true)
             continue;
-        if (isGatedByItsAddon(state, meta.packageName))
+        if (declaration.scopes && declaration.scopes.length > 0)
             continue;
-        ungated.push(funcName);
+        const addonMeta = state.addonFunctions?.[namespace] ?? {};
+        for (const funcName of declaration.expose) {
+            const meta = addonMeta[funcName];
+            if (!meta || gatesItself(meta))
+                continue;
+            ungated.push(`${namespace}:${funcName}`);
+        }
     }
     if (ungated.length === 0)
         return;
@@ -64,6 +68,19 @@ export function validateExposedFunctionsGated(logger, state) {
             `${one ? 'it was' : 'they were'} not meant to be callable from outside.`,
     });
 }
+const gatesItself = (meta) => 
+// A pikkuFunc always requires a session, on every path.
+meta.sessionless === false ||
+    // Scenario steps are refused by rpcExposed regardless of `expose`.
+    meta.scenarioStep === true ||
+    // The author declared that the body authorizes its own callers — a gate
+    // this check has no way to see. Taking the claim at face value is the
+    // point: without it the warning fires forever on functions that are fine,
+    // and a warning that is usually wrong stops being read.
+    meta.permissionsInBody === true ||
+    meta.auth === true ||
+    (meta.scopes?.length ?? 0) > 0 ||
+    (meta.permissions?.length ?? 0) > 0;
 /**
  * Whether every function in this package is already gated by its `wireAddon`.
  * Those gates are applied by `runPikkuFunc` on every wiring path, so a function

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.85",
+  "version": "0.12.87",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -55,10 +55,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.116"
+    "@pikku/core": "^0.12.120"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.116",
+    "@pikku/core": "^0.12.120",
     "@types/node": "^24.13.3"
   },
   "engines": {