@pikku/inspector 0.12.50 → 0.12.54

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

@@ -1,5 +1,6 @@
 import type { InspectorState, InspectorLogger, InspectorOptions } from '../types.js';
 import type { MiddlewareMetadata, PermissionMetadata } from '@pikku/core';
+import type ts from 'typescript';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -69,8 +70,11 @@ export declare function validateScenarioServices(logger: InspectorLogger, state:
  *
  * - the step target must be a static string literal (PKU678) — otherwise it
  *   can't be bundled, typed or drawn;
- * - a `browser: true` step must be given an actor (PKU677), since the browser
- *   context signs in as that persona.
+ * - a step declaring a `browser` binding must be given an actor (PKU677), since
+ *   the browser context signs in as that persona. It is checked statically even
+ *   though the binding only runs on a browser run: a step that can never be
+ *   driven by a human is a latent failure, not a passing default run.
+ * - a scenario written as a step ladder must assert something (PKU680).
  *
  * It also marks the step's function as used, so `scenario run` boots the
  * singletons the step actually needs.
@@ -92,12 +96,73 @@ export declare function validateWorkflowGraphAddons(logger: InspectorLogger, sta
  * because the pikku state metadata doesn't exist in the CLI context.
  */
 export declare function validateSchemaWiringSeparation(logger: InspectorLogger, state: InspectorState): void;
+/** Marks the functions that keep the full `SecretService`. */
+export declare function computeSecretBrokers(state: InspectorState): void;
+/**
+ * Refuses a singleton service that is a `SecretService` under another name.
+ *
+ * `secrets` is omitted from every function-facing services type, but
+ * `pikkuServices(async ({ secrets }) => ({ cfg: secrets }))` re-exposes it under
+ * a name the omit does not cover. A name-based rule misses this; the type does
+ * not.
+ */
+export declare function validateNoSecretAliasServices(logger: InspectorLogger, checker: ts.TypeChecker, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Reports secret reads the catalogue does not account for.
+ *
+ * `getSecret('X')` with no matching `defineSecret` is a value that will be missing
+ * at first request rather than at deploy; a non-literal key is a read the
+ * manifest cannot cover, so a per-unit scope cannot be narrowed around it.
+ */
+export declare function validateSecretUsage(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function computeDiagnostics(state: InspectorState): void;
 /**
  * Validates that every scope referenced by a function is declared via
- * `wireScope`. Runs after all visitors, so declaration order does not matter.
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
  *
  * A `*` suffix is a wildcard requirement: `admin:*` requires the `admin` scope
  * to be declared, and grants its whole subtree.
  */
 export declare function validateScopeReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Resolves every `tools:` entry on every agent and reports the ones that do not
+ * land on a real function, or that land on one with nothing to tell the model.
+ *
+ * `ref('todos:listTodos')` is a bare string to the inspector — `ref` is not
+ * resolved, only unwrapped — so until now a reference to a function that never
+ * existed generated cleanly and failed at agent-run time. Addon namespaces come
+ * from `wireAddon`, and each addon's generated metadata is read off disk, which
+ * is the only view of it this project has.
+ *
+ * The description check is separate and opt-in (`--strict-meta`), because the
+ * description is what the model is told the tool does: without one, the tool is
+ * offered to it under its own name (`ai-agent-prepare.ts`), which is a silent
+ * quality loss rather than a failure. A title deliberately does not satisfy it —
+ * a title labels a tool in a UI, it does not tell a model when to reach for it.
+ */
+export declare function validateAgentToolReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>, options?: InspectorOptions): void;
+/**
+ * Validates that every scope granted by a system role is declared via
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
+ *
+ * The same rule functions get, for a sharper reason: a role granting an
+ * undeclared scope is not merely useless, it is *invisibly* useless. No
+ * function checks the scope, so the role appears to work — every call a
+ * persona holding it makes succeeds or fails for unrelated reasons, and the
+ * authorization boundary it was written to describe is never exercised.
+ *
+ * A `*` suffix grants a subtree; the node it hangs off must exist.
+ */
+export declare function validateSystemRoleScopes(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Validates that every role a persona names is declared with
+ * `defineSystemRole`. Runs after all visitors, so declaration order does not
+ * matter.
+ *
+ * Custom roles are refused rather than tolerated. A role composed in the
+ * console does not exist at build time and can be deleted after it, so a
+ * persona pinned to one silently stops testing what it claims to — and the
+ * symptom is a scatter of 403s that read like authorization findings rather
+ * than like a deleted role.
+ */
+export declare function validatePersonaRoles(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;

package/dist/utils/post-process.js

@@ -2,6 +2,9 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { extractTypeKeys } from './type-utils.js';
 import { ErrorCode } from '../error-codes.js';
+import { isSecretBrokerFunction } from './secret-brokers.js';
+import { findSecretAliasServices } from './secret-alias-services.js';
+import { relative } from 'node:path';
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js';
 import { flattenScopeDefinitions } from '@pikku/core/scope';
 import { DYNAMIC_SCENARIO_STEP_TARGET } from './workflow/dsl/patterns.js';
@@ -484,6 +487,9 @@ const serializeGroupMap = (groupMap) => {
             count: meta.count,
             instanceIds: meta.instanceIds,
             isFactory: meta.isFactory,
+            ...(meta.additionalRegistrations && {
+                additionalRegistrations: meta.additionalRegistrations,
+            }),
         };
     }
     return result;
@@ -594,16 +600,21 @@ export function validateScenarioServices(logger, state) {
  *
  * - the step target must be a static string literal (PKU678) — otherwise it
  *   can't be bundled, typed or drawn;
- * - a `browser: true` step must be given an actor (PKU677), since the browser
- *   context signs in as that persona.
+ * - a step declaring a `browser` binding must be given an actor (PKU677), since
+ *   the browser context signs in as that persona. It is checked statically even
+ *   though the binding only runs on a browser run: a step that can never be
+ *   driven by a human is a latent failure, not a passing default run.
+ * - a scenario written as a step ladder must assert something (PKU680).
  *
  * It also marks the step's function as used, so `scenario run` boots the
  * singletons the step actually needs.
  */
 export function validateScenarioSteps(logger, state) {
+    const phasesSeen = new Set();
     const visit = (workflowName, steps) => {
         for (const step of steps) {
             if (step.type === 'scenarioStep') {
+                phasesSeen.add(step.phase);
                 if (step.stepFunc === DYNAMIC_SCENARIO_STEP_TARGET) {
                     logger.critical(ErrorCode.SCENARIO_STEP_TARGET_NOT_STATIC, `Scenario '${workflowName}' calls step '${step.stepName}' with a target that isn't a string literal. ` +
                         `A step target must be statically resolvable so it can be bundled, typed and drawn — ` +
@@ -612,8 +623,9 @@ export function validateScenarioSteps(logger, state) {
                 }
                 state.serviceAggregation.usedFunctions.add(step.stepFunc);
                 const stepMeta = state.functions.meta[step.stepFunc];
-                if (stepMeta?.scenarioStepBrowser && !step.actor) {
-                    logger.critical(ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR, `Scenario '${workflowName}' calls browser step '${step.stepFunc}' without an actor. ` +
+                if (stepMeta?.scenarioStepSurfaces?.includes('browser') &&
+                    !step.actor) {
+                    logger.critical(ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR, `Scenario '${workflowName}' calls step '${step.stepFunc}', which declares a browser binding, without an actor. ` +
                         `Pass { actor: actors.<name> } so the browser context signs in as that persona.`);
                 }
                 continue;
@@ -641,7 +653,20 @@ export function validateScenarioSteps(logger, state) {
         }
     };
     for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+        phasesSeen.clear();
         visit(workflowName, meta.steps ?? []);
+        // A scenario written as a step ladder but with no `then` proves only that
+        // nothing threw. It is also invisible to witness coverage — it contributes
+        // 0/0, so it can never lower the number — which makes an assertion-free
+        // flow the cheapest way to make a suite look better covered than it is.
+        // `asserts` is the escape for a flow whose witness is an expectation helper
+        // instead: those are inline steps and leave no phase behind, but a recorded
+        // service call or a refusal is an assertion all the same.
+        if (phasesSeen.size > 0 && !phasesSeen.has('then') && !meta.asserts) {
+            logger.critical(ErrorCode.SCENARIO_HAS_NO_ASSERTION, `Scenario '${workflowName}' has ${[...phasesSeen].join('/')} steps but never asserts. ` +
+                `Add a scenario.then(...) naming what the actor should now see — a flow with no 'then' ` +
+                `only proves nothing threw, and contributes nothing to witness coverage.`);
+        }
     }
 }
 /**
@@ -692,13 +717,18 @@ export function validateSchemaWiringSeparation(logger, state) {
     for (const file of state.http.files) {
         wiringFiles.add(file);
     }
-    // Middleware wirings (addHTTPMiddleware calls)
-    for (const meta of state.http.routeMiddleware.values()) {
-        wiringFiles.add(meta.sourceFile);
-    }
-    for (const meta of state.middleware.tagMiddleware.values()) {
-        wiringFiles.add(meta.sourceFile);
-    }
+    // Middleware wirings (addHTTPMiddleware calls). A group can be registered
+    // from more than one file, and every one of them is a wiring file.
+    const addGroupFiles = (groups) => {
+        for (const meta of groups.values()) {
+            wiringFiles.add(meta.sourceFile);
+            for (const registration of meta.additionalRegistrations ?? []) {
+                wiringFiles.add(registration.sourceFile);
+            }
+        }
+    };
+    addGroupFiles(state.http.routeMiddleware);
+    addGroupFiles(state.middleware.tagMiddleware);
     // Check for overlap
     for (const file of schemaFiles) {
         if (wiringFiles.has(file)) {
@@ -711,6 +741,85 @@ export function validateSchemaWiringSeparation(logger, state) {
         }
     }
 }
+/** Marks the functions that keep the full `SecretService`. */
+export function computeSecretBrokers(state) {
+    for (const [id, meta] of Object.entries(state.functions.meta)) {
+        if (isSecretBrokerFunction(meta.pikkuFuncId ?? id)) {
+            meta.secretBroker = true;
+        }
+    }
+}
+/**
+ * Refuses a singleton service that is a `SecretService` under another name.
+ *
+ * `secrets` is omitted from every function-facing services type, but
+ * `pikkuServices(async ({ secrets }) => ({ cfg: secrets }))` re-exposes it under
+ * a name the omit does not cover. A name-based rule misses this; the type does
+ * not.
+ */
+export function validateNoSecretAliasServices(logger, checker, state) {
+    if (!('typesLookup' in state)) {
+        return;
+    }
+    const singletonServicesTypes = state.typesLookup.get('SingletonServices');
+    if (!singletonServicesTypes?.length) {
+        return;
+    }
+    const aliases = findSecretAliasServices(singletonServicesTypes[0], checker);
+    if (aliases.length === 0) {
+        return;
+    }
+    const report = (kind, id, services) => {
+        const used = services.filter((service) => aliases.includes(service));
+        if (used.length === 0) {
+            return;
+        }
+        logger.critical(ErrorCode.SECRET_SERVICE_ALIASED, `${kind} '${id}' receives ${used.map((s) => `'${s}'`).join(', ')}, which ${used.length === 1 ? 'is' : 'are'} a SecretService under another name. ` +
+            `SecretService is confined to pikkuServices, pikkuWireServices, addon service factories and middleware — give a service the secret value when you construct it and expose only what the function needs.`);
+    };
+    for (const [id, meta] of Object.entries(state.functions.meta)) {
+        if (meta.secretBroker) {
+            continue;
+        }
+        report('Function', id, meta.services?.services ?? []);
+    }
+    for (const [id, def] of Object.entries(state.permissions.definitions)) {
+        report('Permission', id, def.services?.services ?? []);
+    }
+}
+/**
+ * Reports secret reads the catalogue does not account for.
+ *
+ * `getSecret('X')` with no matching `defineSecret` is a value that will be missing
+ * at first request rather than at deploy; a non-literal key is a read the
+ * manifest cannot cover, so a per-unit scope cannot be narrowed around it.
+ */
+export function validateSecretUsage(logger, state) {
+    const declared = new Set(state.secrets.definitions.map((d) => d.secretId));
+    for (const definition of state.secrets.definitions) {
+        if (definition.oauth2?.tokenSecretId) {
+            declared.add(definition.oauth2.tokenSecretId);
+        }
+    }
+    for (const [file, usage] of state.secrets.usage) {
+        const relativeFile = relative(state.rootDir, file);
+        const undeclared = usage.keys.filter((key) => !declared.has(key));
+        if (undeclared.length > 0) {
+            logger.diagnostic({
+                severity: 'warn',
+                code: ErrorCode.SECRET_NOT_DECLARED,
+                message: `${relativeFile} reads ${undeclared.map((k) => `'${k}'`).join(', ')}, which no defineSecret declares. Declare it so it is validated at deploy time and shown to whoever has to provision it.`,
+            });
+        }
+        if (usage.dynamic.length > 0) {
+            logger.diagnostic({
+                severity: 'warn',
+                code: ErrorCode.SECRET_KEY_NOT_STATIC,
+                message: `${relativeFile} reads a secret with a non-literal key (${usage.dynamic.join(', ')}). The deployment cannot narrow its secret scope around a key it cannot see.`,
+            });
+        }
+    }
+}
 export function computeDiagnostics(state) {
     const diagnostics = [];
     for (const [id, meta] of Object.entries(state.functions.meta)) {
@@ -787,7 +896,7 @@ export function computeDiagnostics(state) {
 }
 /**
  * Validates that every scope referenced by a function is declared via
- * `wireScope`. Runs after all visitors, so declaration order does not matter.
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
  *
  * A `*` suffix is a wildcard requirement: `admin:*` requires the `admin` scope
  * to be declared, and grants its whole subtree.
@@ -806,7 +915,131 @@ export function validateScopeReferences(logger, state) {
             }
             if (!declared.has(declaredForm)) {
                 const available = Array.from(declared);
-                logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires scope '${scope}' which is not declared. Declare it with wireScope. Available scopes: ${available.join(', ') || 'none'}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(', ') || 'none'}`);
+            }
+        }
+    }
+}
+/**
+ * Resolves every `tools:` entry on every agent and reports the ones that do not
+ * land on a real function, or that land on one with nothing to tell the model.
+ *
+ * `ref('todos:listTodos')` is a bare string to the inspector — `ref` is not
+ * resolved, only unwrapped — so until now a reference to a function that never
+ * existed generated cleanly and failed at agent-run time. Addon namespaces come
+ * from `wireAddon`, and each addon's generated metadata is read off disk, which
+ * is the only view of it this project has.
+ *
+ * The description check is separate and opt-in (`--strict-meta`), because the
+ * description is what the model is told the tool does: without one, the tool is
+ * offered to it under its own name (`ai-agent-prepare.ts`), which is a silent
+ * quality loss rather than a failure. A title deliberately does not satisfy it —
+ * a title labels a tool in a UI, it does not tell a model when to reach for it.
+ */
+export function validateAgentToolReferences(logger, state, options = {}) {
+    const agents = Object.entries(state.agents.agentsMeta);
+    if (agents.length === 0)
+        return;
+    const { wireAddonDeclarations } = state.rpc;
+    for (const [agentKey, agent] of agents) {
+        const where = agent.sourceFile ? ` (${agent.sourceFile})` : '';
+        for (const tool of agent.tools ?? []) {
+            // A workflow reference is resolved against the workflow map, not here.
+            if (tool.startsWith('workflow:'))
+                continue;
+            const separator = tool.indexOf(':');
+            let meta;
+            if (separator === -1) {
+                const funcId = state.rpc.internalMeta[tool] ?? tool;
+                meta = state.functions.meta[funcId];
+                if (!meta) {
+                    logger.critical(ErrorCode.AGENT_TOOL_NOT_FOUND, `AI agent '${agentKey}'${where} references tool '${tool}', which is not a function in this project.`);
+                    continue;
+                }
+            }
+            else {
+                const namespace = tool.slice(0, separator);
+                const funcName = tool.slice(separator + 1);
+                const addon = wireAddonDeclarations?.get(namespace);
+                if (!addon) {
+                    const known = Array.from(wireAddonDeclarations?.keys() ?? []);
+                    logger.critical(ErrorCode.AGENT_TOOL_UNKNOWN_NAMESPACE, `AI agent '${agentKey}'${where} references tool '${tool}', but no addon is wired under the namespace '${namespace}'. ` +
+                        `Wired namespaces: ${known.join(', ') || 'none'}.`);
+                    continue;
+                }
+                // An addon that has not been built yet contributed no metadata, which
+                // is not the same as one whose function is missing.
+                const addonMeta = state.addonFunctions[namespace];
+                if (!addonMeta)
+                    continue;
+                meta = addonMeta[funcName];
+                if (!meta) {
+                    logger.critical(ErrorCode.AGENT_TOOL_NOT_FOUND, `AI agent '${agentKey}'${where} references tool '${tool}', but addon '${namespace}' ('${addon.package}') exposes no function '${funcName}'.`);
+                    continue;
+                }
+            }
+            if (options.strictMeta && !meta.description) {
+                logger.critical(ErrorCode.AGENT_TOOL_MISSING_DESCRIPTION, `AI agent '${agentKey}'${where} uses tool '${tool}', which has no description. ` +
+                    `An agent tool's description is what the model is told it does; without one it is offered the tool under its own name. ` +
+                    `Add a 'description' to '${tool}'${meta.title ? " (a 'title' does not count — it labels the tool, it does not explain it)" : ''}.`);
+            }
+        }
+    }
+}
+/**
+ * Validates that every scope granted by a system role is declared via
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
+ *
+ * The same rule functions get, for a sharper reason: a role granting an
+ * undeclared scope is not merely useless, it is *invisibly* useless. No
+ * function checks the scope, so the role appears to work — every call a
+ * persona holding it makes succeeds or fails for unrelated reasons, and the
+ * authorization boundary it was written to describe is never exercised.
+ *
+ * A `*` suffix grants a subtree; the node it hangs off must exist.
+ */
+export function validateSystemRoleScopes(logger, state) {
+    if (!state.systemRoles.definitions.length) {
+        return;
+    }
+    const declared = new Set(flattenScopeDefinitions(state.scopes.definitions).map((s) => s.id));
+    for (const role of state.systemRoles.definitions) {
+        for (const scope of role.scopes) {
+            if (scope === '*') {
+                logger.critical(ErrorCode.INVALID_VALUE, `System role '${role.name}' grants the bare wildcard scope '*'. Grant the roots it should cover instead — '*' hides what the role actually confers.`);
+                continue;
+            }
+            const declaredForm = scope.endsWith(':*') ? scope.slice(0, -2) : scope;
+            if (!declared.has(declaredForm)) {
+                const available = Array.from(declared);
+                logger.critical(ErrorCode.INVALID_VALUE, `System role '${role.name}' grants scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(', ') || 'none'}`);
+            }
+        }
+    }
+}
+/**
+ * Validates that every role a persona names is declared with
+ * `defineSystemRole`. Runs after all visitors, so declaration order does not
+ * matter.
+ *
+ * Custom roles are refused rather than tolerated. A role composed in the
+ * console does not exist at build time and can be deleted after it, so a
+ * persona pinned to one silently stops testing what it claims to — and the
+ * symptom is a scatter of 403s that read like authorization findings rather
+ * than like a deleted role.
+ */
+export function validatePersonaRoles(logger, state) {
+    if (!state.personas.definitions.length) {
+        return;
+    }
+    const declared = new Set(state.systemRoles.definitions.map((r) => r.name));
+    for (const persona of state.personas.definitions) {
+        for (const role of persona.roles) {
+            if (!declared.has(role)) {
+                const available = Array.from(declared).sort();
+                logger.critical(ErrorCode.INVALID_VALUE, `Persona '${persona.id}' holds role '${role}', which is not declared with defineSystemRole. ` +
+                    `A persona may only name a system role — a role composed in the console can be deleted, and the persona would go on claiming to test it. ` +
+                    `Declared roles: ${available.join(', ') || 'none'}`);
             }
         }
     }

package/dist/utils/secret-alias-services.d.ts

@@ -0,0 +1,8 @@
+import type ts from 'typescript';
+/** Whether a type structurally satisfies `SecretService`. */
+export declare const isSecretServiceType: (type: ts.Type, checker: ts.TypeChecker) => boolean;
+/**
+ * Singleton service names, other than `secrets`, whose type is a
+ * `SecretService`.
+ */
+export declare const findSecretAliasServices: (singletonServicesType: ts.Type, checker: ts.TypeChecker) => string[];

package/dist/utils/secret-alias-services.js

@@ -0,0 +1,45 @@
+const SECRET_SERVICE_METHODS = [
+    'getSecret',
+    'hasSecret',
+    'setSecret',
+    'deleteSecret',
+    'getSecrets',
+];
+/** Whether a type structurally satisfies `SecretService`. */
+export const isSecretServiceType = (type, checker) => {
+    const nonNullable = checker.getNonNullableType(type);
+    return SECRET_SERVICE_METHODS.every((method) => {
+        const property = nonNullable.getProperty(method);
+        if (!property) {
+            return false;
+        }
+        const declaration = property.valueDeclaration ?? property.declarations?.[0];
+        if (!declaration) {
+            return false;
+        }
+        const propertyType = checker.getTypeOfSymbolAtLocation(property, declaration);
+        return propertyType.getCallSignatures().length > 0;
+    });
+};
+/**
+ * Singleton service names, other than `secrets`, whose type is a
+ * `SecretService`.
+ */
+export const findSecretAliasServices = (singletonServicesType, checker) => {
+    const aliases = [];
+    for (const property of singletonServicesType.getProperties()) {
+        const name = property.getName();
+        if (name === 'secrets') {
+            continue;
+        }
+        const declaration = property.valueDeclaration ?? property.declarations?.[0];
+        if (!declaration) {
+            continue;
+        }
+        const type = checker.getTypeOfSymbolAtLocation(property, declaration);
+        if (isSecretServiceType(type, checker)) {
+            aliases.push(name);
+        }
+    }
+    return aliases.sort();
+};

package/dist/utils/secret-brokers.d.ts

@@ -0,0 +1,2 @@
+/** Whether this function keeps the full `SecretService`. */
+export declare const isSecretBrokerFunction: (functionId: string) => boolean;

package/dist/utils/secret-brokers.js

@@ -0,0 +1,9 @@
+/** The console's secret administration functions, and nothing else. */
+const SECRET_BROKER_FUNCTIONS = new Set([
+    'pikkuConsoleSetSecret',
+    'pikkuConsoleGetSecret',
+    'pikkuConsoleHasSecret',
+]);
+/** Whether this function keeps the full `SecretService`. */
+export const isSecretBrokerFunction = (functionId) => SECRET_BROKER_FUNCTIONS.has(functionId) ||
+    SECRET_BROKER_FUNCTIONS.has(functionId.split(':').pop() ?? '');

package/dist/utils/serialize-inspector-state.d.ts

@@ -1,3 +1,4 @@
+import type { SecretUsage } from './extract-secret-usage.js';
 import type { JSONValue } from '@pikku/core';
 import type { InspectorDiagnostic, InspectorFeature, InspectorState } from '../types.js';
 /**
@@ -228,6 +229,7 @@ export interface SerializableInspectorState {
     secrets: {
         definitions: InspectorState['secrets']['definitions'];
         files: string[];
+        usage: Record<string, SecretUsage>;
     };
     credentials: {
         definitions: InspectorState['credentials']['definitions'];
@@ -237,6 +239,14 @@ export interface SerializableInspectorState {
         definitions: InspectorState['scopes']['definitions'];
         files: string[];
     };
+    systemRoles: {
+        definitions: InspectorState['systemRoles']['definitions'];
+        files: string[];
+    };
+    personas: {
+        definitions: InspectorState['personas']['definitions'];
+        files: string[];
+    };
     variables: {
         definitions: InspectorState['variables']['definitions'];
         files: string[];

package/dist/utils/serialize-inspector-state.js

@@ -112,6 +112,7 @@ export function serializeInspectorState(state) {
         secrets: {
             definitions: state.secrets.definitions,
             files: Array.from(state.secrets.files),
+            usage: Object.fromEntries(state.secrets.usage),
         },
         credentials: {
             definitions: state.credentials.definitions,
@@ -121,6 +122,14 @@ export function serializeInspectorState(state) {
             definitions: state.scopes.definitions,
             files: Array.from(state.scopes.files),
         },
+        systemRoles: {
+            definitions: state.systemRoles.definitions,
+            files: Array.from(state.systemRoles.files),
+        },
+        personas: {
+            definitions: state.personas.definitions,
+            files: Array.from(state.personas.files),
+        },
         variables: {
             definitions: state.variables.definitions,
             files: Array.from(state.variables.files),
@@ -276,6 +285,7 @@ export function deserializeInspectorState(data) {
         secrets: {
             definitions: data.secrets?.definitions || [],
             files: new Set(data.secrets?.files || []),
+            usage: new Map(Object.entries(data.secrets?.usage || {})),
         },
         credentials: {
             definitions: data.credentials?.definitions || [],
@@ -285,6 +295,14 @@ export function deserializeInspectorState(data) {
             definitions: data.scopes?.definitions || [],
             files: new Set(data.scopes?.files || []),
         },
+        systemRoles: {
+            definitions: data.systemRoles?.definitions || [],
+            files: new Set(data.systemRoles?.files || []),
+        },
+        personas: {
+            definitions: data.personas?.definitions || [],
+            files: new Set(data.personas?.files || []),
+        },
         variables: {
             definitions: data.variables?.definitions || [],
             files: new Set(data.variables?.files || []),

package/dist/utils/serialize-middleware-groups-meta.js

@@ -9,6 +9,9 @@ const serializeGroupMap = (groupMap) => {
             count: meta.count,
             instanceIds: meta.instanceIds,
             isFactory: meta.isFactory,
+            ...(meta.additionalRegistrations && {
+                additionalRegistrations: meta.additionalRegistrations,
+            }),
         };
     }
     return result;

package/dist/utils/single-declaration.d.ts

@@ -0,0 +1,32 @@
+import type { ErrorCode } from '../error-codes.js';
+import type { InspectorLogger } from '../types.js';
+/**
+ * Claims the one call site a single-declaration construct is allowed.
+ *
+ * `definePersonas` takes a keyed object, so one call already declares as many
+ * entries as you like. Letting the call itself repeat buys nothing and costs
+ * the thing that matters: a single place to read the declared set from, and a
+ * single place to add to it. The same rule `pikkuBetterAuth` has had all along.
+ *
+ * A second call in the SAME file is refused too — "the file" is not an answer
+ * to "where do I add a persona?" when the file holds two calls, so allowing it
+ * would keep the ambiguity the rule exists to remove.
+ *
+ * A generated file is exempt, and never claims the slot either. The rule exists
+ * to name the one place a person adds to, and nobody adds to a file the CLI
+ * rewrites on the next run — `pikku-personas.gen.ts` would otherwise make every
+ * project that scaffolds one unbuildable, and take the app's own declaration
+ * down with it.
+ *
+ * `defineScope` and `defineSystemRole` held this rule too, briefly, and do not
+ * until the `admin` tree stops being app-declared. The exemption above is not
+ * enough for them: the CLI generates a `defineScope` in `user-admin.gen.ts` and
+ * `@pikku/addon-console` spells the same tree out again in a hand-written file,
+ * so two non-generated declarations remain and the build still fails. The fix
+ * is for `admin` to be a default scope nobody declares, and the rule comes back
+ * for scopes and roles once that lands.
+ *
+ * @param files - The construct's `files` set, which doubles as the claim.
+ * @returns true when the caller holds the claim and should carry on.
+ */
+export declare const claimSingleDeclaration: (logger: InspectorLogger, files: Set<string>, code: ErrorCode, helper: string, sourceFile: string) => boolean;

package/dist/utils/single-declaration.js

@@ -0,0 +1,43 @@
+/**
+ * Claims the one call site a single-declaration construct is allowed.
+ *
+ * `definePersonas` takes a keyed object, so one call already declares as many
+ * entries as you like. Letting the call itself repeat buys nothing and costs
+ * the thing that matters: a single place to read the declared set from, and a
+ * single place to add to it. The same rule `pikkuBetterAuth` has had all along.
+ *
+ * A second call in the SAME file is refused too — "the file" is not an answer
+ * to "where do I add a persona?" when the file holds two calls, so allowing it
+ * would keep the ambiguity the rule exists to remove.
+ *
+ * A generated file is exempt, and never claims the slot either. The rule exists
+ * to name the one place a person adds to, and nobody adds to a file the CLI
+ * rewrites on the next run — `pikku-personas.gen.ts` would otherwise make every
+ * project that scaffolds one unbuildable, and take the app's own declaration
+ * down with it.
+ *
+ * `defineScope` and `defineSystemRole` held this rule too, briefly, and do not
+ * until the `admin` tree stops being app-declared. The exemption above is not
+ * enough for them: the CLI generates a `defineScope` in `user-admin.gen.ts` and
+ * `@pikku/addon-console` spells the same tree out again in a hand-written file,
+ * so two non-generated declarations remain and the build still fails. The fix
+ * is for `admin` to be a default scope nobody declares, and the rule comes back
+ * for scopes and roles once that lands.
+ *
+ * @param files - The construct's `files` set, which doubles as the claim.
+ * @returns true when the caller holds the claim and should carry on.
+ */
+export const claimSingleDeclaration = (logger, files, code, helper, sourceFile) => {
+    if (sourceFile.endsWith('.gen.ts')) {
+        return true;
+    }
+    const [first] = files;
+    if (first === undefined) {
+        files.add(sourceFile);
+        return true;
+    }
+    logger.critical(code, first === sourceFile
+        ? `Only one ${helper}(...) is allowed per codebase, so there is one place to read the declarations from and one place to add to. Found a second call in ${sourceFile}. Declare them all in one call.`
+        : `Only one ${helper}(...) is allowed per codebase, so there is one place to read the declarations from and one place to add to. Found a second in ${sourceFile} (first: ${first}). Declare them all in one call.`);
+    return false;
+};