@pikku/inspector 0.12.50 → 0.12.54

package/dist/add/add-personas.js

@@ -0,0 +1,216 @@
+import * as ts from 'typescript';
+import { DISPOSITIONS } from '@pikku/core/virtual-user';
+import { isRunnablePersona } from '@pikku/core/persona';
+import { ErrorCode } from '../error-codes.js';
+import { claimSingleDeclaration } from '../utils/single-declaration.js';
+import { booleanProperty, getProperty, numberProperty, stringArrayProperty, stringProperty, unwrapAs, } from '../utils/literal-properties.js';
+/** A dial and the range outside which it is a mistake rather than a choice. */
+const RATES = [
+    ['temperature', 0, 2],
+    ['repeatRate', 0, 1],
+    ['reReadRate', 0, 1],
+];
+/**
+ * `{ moves, temperature, repeatRate, … }` — a disposition's dials, overridden.
+ *
+ * The ranges are checked here rather than at run time because these are the
+ * kind of typo that does not throw: `repeatRate: 18` meaning 18% would silently
+ * double every call the persona makes, and you would read the run as a product
+ * bug.
+ */
+const tuningProperty = (config, onError) => {
+    const value = getProperty(config, 'tuning');
+    if (!value || !ts.isObjectLiteralExpression(value)) {
+        return undefined;
+    }
+    const tuning = {};
+    const movesValue = getProperty(value, 'moves');
+    if (movesValue && ts.isObjectLiteralExpression(movesValue)) {
+        const moves = {};
+        for (const move of ['continue', 'suspend', 'resume', 'abandon']) {
+            const weight = numberProperty(movesValue, move);
+            if (weight === undefined) {
+                continue;
+            }
+            if (weight < 0) {
+                onError(`tuning.moves.${move} must not be negative (got ${weight}).`);
+                continue;
+            }
+            moves[move] = weight;
+        }
+        if (Object.keys(moves).length) {
+            tuning.moves = moves;
+        }
+    }
+    for (const [name, min, max] of RATES) {
+        const rate = numberProperty(value, name);
+        if (rate === undefined) {
+            continue;
+        }
+        if (rate < min || rate > max) {
+            onError(`tuning.${name} must be between ${min} and ${max} (got ${rate}).`);
+            continue;
+        }
+        Object.assign(tuning, { [name]: rate });
+    }
+    for (const flag of ['emptyMemory', 'readOnly', 'invertedOracle']) {
+        const declared = booleanProperty(value, flag);
+        if (declared !== undefined) {
+            tuning[flag] = declared;
+        }
+    }
+    const instructions = stringProperty(value, 'instructions');
+    if (instructions !== undefined) {
+        tuning.instructions = instructions;
+    }
+    return Object.keys(tuning).length ? tuning : undefined;
+};
+const accountProperty = (value) => {
+    if (!value || !ts.isObjectLiteralExpression(value)) {
+        return undefined;
+    }
+    const provider = stringProperty(value, 'provider');
+    return provider === undefined ? {} : { provider };
+};
+const linkedAccountsProperty = (config, personaId, logger) => {
+    const value = getProperty(config, 'linkedAccounts');
+    if (!value || !ts.isObjectLiteralExpression(value)) {
+        return undefined;
+    }
+    const accounts = {};
+    for (const prop of value.properties) {
+        if (!ts.isPropertyAssignment(prop)) {
+            continue;
+        }
+        if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) {
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, `Persona '${personaId}' has a linked account whose key is not a literal.`);
+            continue;
+        }
+        const account = accountProperty(prop.initializer);
+        if (!account) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${personaId}' linked account '${prop.name.text}' must be an object literal.`);
+            continue;
+        }
+        accounts[prop.name.text] = account;
+    }
+    return Object.keys(accounts).length ? accounts : undefined;
+};
+/**
+ * Inspector for `definePersonas()` calls.
+ *
+ * A persona is entirely declaration — a person, their roles, what they want —
+ * so there is no code body and nothing to resolve at runtime. What is read here
+ * is the whole thing, and it is generated straight to `personas.gen.json` for
+ * the CLI and the console to read without loading the app.
+ *
+ * `name` is the one field that cannot be defaulted. A persona without one is
+ * not a person, and the console has nothing to show.
+ */
+export const addPersonas = (logger, node, _checker, state) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const expression = node.expression;
+    if (!ts.isIdentifier(expression) || expression.text !== 'definePersonas') {
+        return;
+    }
+    const firstArg = node.arguments[0];
+    if (!firstArg) {
+        return;
+    }
+    const unwrapped = unwrapAs(firstArg);
+    if (!ts.isObjectLiteralExpression(unwrapped)) {
+        logger.critical(ErrorCode.INVALID_VALUE, 'definePersonas() needs an inline object — personas are read statically, never evaluated.');
+        return;
+    }
+    const sourceFile = node.getSourceFile().fileName;
+    if (!claimSingleDeclaration(logger, state.personas.files, ErrorCode.DUPLICATE_PERSONAS_DEFINITION, 'definePersonas', sourceFile)) {
+        return;
+    }
+    const known = Object.keys(DISPOSITIONS);
+    for (const prop of unwrapped.properties) {
+        if (!ts.isPropertyAssignment(prop)) {
+            continue;
+        }
+        if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) {
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'A persona is declared with a key that is not a literal.');
+            continue;
+        }
+        const id = prop.name.text;
+        if (!ts.isObjectLiteralExpression(prop.initializer)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}' must be an object literal.`);
+            continue;
+        }
+        const config = prop.initializer;
+        const name = stringProperty(config, 'name');
+        if (!name) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}' needs a literal 'name' — a persona is a person, and the console has nothing to show without one.`);
+            continue;
+        }
+        // The generated `definePersonas` types this as a union, so a bad value only
+        // reaches here in source that does not compile. Caught anyway: a
+        // disposition is the entire behaviour, and defaulting a typo to `realistic`
+        // would run a different person than the one that was written.
+        const disposition = stringProperty(config, 'disposition');
+        if (disposition !== undefined && !known.includes(disposition)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}' has an unknown disposition '${disposition}'. One of: ${known.join(', ')}`);
+            continue;
+        }
+        let tuningFailed = false;
+        const tuning = tuningProperty(config, (message) => {
+            tuningFailed = true;
+            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}': ${message}`);
+        });
+        if (tuningFailed) {
+            continue;
+        }
+        const account = accountProperty(getProperty(config, 'account'));
+        const declaredRunnable = booleanProperty(config, 'runnable');
+        const persona = {
+            id,
+            name,
+            roles: stringArrayProperty(config, 'roles') ?? [],
+            goals: stringArrayProperty(config, 'goals') ?? [],
+            tags: stringArrayProperty(config, 'tags') ?? [],
+            runnable: isRunnablePersona({
+                ...(declaredRunnable !== undefined
+                    ? { runnable: declaredRunnable }
+                    : {}),
+                ...(account ? { account } : {}),
+            }),
+            sourceFile,
+        };
+        const jobTitle = stringProperty(config, 'jobTitle');
+        if (jobTitle !== undefined)
+            persona.jobTitle = jobTitle;
+        const description = stringProperty(config, 'description');
+        if (description !== undefined)
+            persona.description = description;
+        const avatarUrl = stringProperty(config, 'avatarUrl');
+        if (avatarUrl !== undefined)
+            persona.avatarUrl = avatarUrl;
+        const personality = stringProperty(config, 'personality');
+        if (personality !== undefined)
+            persona.personality = personality;
+        if (disposition !== undefined) {
+            persona.disposition = disposition;
+        }
+        if (tuning !== undefined)
+            persona.tuning = tuning;
+        const fixtures = stringArrayProperty(config, 'fixtures');
+        if (fixtures !== undefined)
+            persona.fixtures = fixtures;
+        // Left absent rather than resolved here: "everywhere but production" is a
+        // fact about the config, and the inspector has no business baking today's
+        // environment list into a meta file that outlives it.
+        const environments = stringArrayProperty(config, 'environments');
+        if (environments !== undefined)
+            persona.environments = environments;
+        if (account !== undefined)
+            persona.account = account;
+        const linkedAccounts = linkedAccountsProperty(config, id, logger);
+        if (linkedAccounts !== undefined)
+            persona.linkedAccounts = linkedAccounts;
+        state.personas.definitions.push(persona);
+    }
+};

package/dist/add/add-scope.js

@@ -89,7 +89,7 @@ export const addScope = (logger, node, checker, state, _options) => {
         return;
     }
     const expression = node.expression;
-    if (!ts.isIdentifier(expression) || expression.text !== 'wireScope') {
+    if (!ts.isIdentifier(expression) || expression.text !== 'defineScope') {
         return;
     }
     const firstArg = node.arguments[0];

package/dist/add/add-secret.js

@@ -1,6 +1,6 @@
 import { createAddKeyedWiring } from './add-keyed-wiring.js';
 export const addSecret = createAddKeyedWiring({
-    functionName: 'wireSecret',
+    functionName: 'defineSecret',
     idField: 'secretId',
     label: 'Secret',
     schemaPrefix: 'SecretSchema',

package/dist/add/add-system-role.d.ts

@@ -0,0 +1,2 @@
+import type { AddWiring } from '../types.js';
+export declare const addSystemRole: AddWiring;

package/dist/add/add-system-role.js

@@ -0,0 +1,102 @@
+import * as ts from 'typescript';
+import { getPropertyValue } from '../utils/get-property-value.js';
+import { ErrorCode } from '../error-codes.js';
+const SEPARATOR = ':';
+/**
+ * Unwraps `x as const` / `x satisfies T` so a cast declaration is still
+ * extracted rather than silently skipped.
+ */
+const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node;
+/**
+ * Reads a `scopes: [...]` array of string literals.
+ *
+ * Returns `undefined` rather than an empty array when the property is absent
+ * or unreadable, so the caller can tell "declared no scopes" from "we could
+ * not see the scopes" — the first is a legitimate placeholder role, the second
+ * would silently produce one.
+ */
+const extractScopes = (obj, roleName, logger) => {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === 'scopes');
+    if (!prop) {
+        logger.critical(ErrorCode.INVALID_VALUE, `System role '${roleName}' has no 'scopes'. A role that grants nothing should say so with 'scopes: []'.`);
+        return undefined;
+    }
+    if (!ts.isPropertyAssignment(prop) ||
+        !ts.isArrayLiteralExpression(prop.initializer)) {
+        logger.critical(ErrorCode.INVALID_VALUE, `System role '${roleName}' must declare 'scopes' as an array literal.`);
+        return undefined;
+    }
+    const scopes = [];
+    for (const element of prop.initializer.elements) {
+        const unwrapped = unwrapAs(element);
+        if (!ts.isStringLiteral(unwrapped)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `System role '${roleName}' lists a scope that is not a string literal. ` +
+                `Scopes are extracted by AST, so a computed value cannot be checked against the declared set.`);
+            continue;
+        }
+        scopes.push(unwrapped.text);
+    }
+    return scopes;
+};
+export const addSystemRole = (logger, node, _checker, state, _options) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const expression = node.expression;
+    if (!ts.isIdentifier(expression) || expression.text !== 'defineSystemRole') {
+        return;
+    }
+    const firstArg = node.arguments[0];
+    if (!firstArg) {
+        return;
+    }
+    const unwrapped = unwrapAs(firstArg);
+    if (!ts.isObjectLiteralExpression(unwrapped)) {
+        return;
+    }
+    const sourceFile = node.getSourceFile().fileName;
+    for (const prop of unwrapped.properties) {
+        if (!ts.isPropertyAssignment(prop)) {
+            continue;
+        }
+        let name;
+        if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
+            name = prop.name.text;
+        }
+        if (name === undefined) {
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'A system role is declared with a key that is not a literal.');
+            continue;
+        }
+        if (name.length === 0) {
+            logger.critical(ErrorCode.INVALID_VALUE, 'A system role is declared with an empty name.');
+            continue;
+        }
+        if (name.includes(SEPARATOR)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `System role '${name}' contains the '${SEPARATOR}' separator. ` +
+                `'${SEPARATOR}' delimits scope ids; a role named like a scope reads as one.`);
+            continue;
+        }
+        if (!ts.isObjectLiteralExpression(prop.initializer)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `System role '${name}' must be an object literal.`);
+            continue;
+        }
+        const scopes = extractScopes(prop.initializer, name, logger);
+        if (scopes === undefined) {
+            continue;
+        }
+        const displayName = getPropertyValue(prop.initializer, 'displayName');
+        const description = getPropertyValue(prop.initializer, 'description');
+        state.systemRoles.files.add(sourceFile);
+        state.systemRoles.definitions.push({
+            name,
+            displayName: displayName || undefined,
+            description: description || undefined,
+            scopes,
+            sourceFile,
+        });
+    }
+};

package/dist/add/add-variable.js

@@ -1,6 +1,6 @@
 import { createAddKeyedWiring } from './add-keyed-wiring.js';
 export const addVariable = createAddKeyedWiring({
-    functionName: 'wireVariable',
+    functionName: 'defineVariable',
     idField: 'variableId',
     label: 'Variable',
     schemaPrefix: 'VariableSchema',

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

@@ -1,4 +1,18 @@
 import * as ts from 'typescript';
+function parseStringArray(node) {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const values = [];
+    for (const element of node.elements) {
+        // A non-literal entry (a spread, a const reference) is not statically
+        // knowable. Dropping the whole array rather than a silent partial keeps a
+        // consumer from reading a short list as the complete set of gates.
+        if (!ts.isStringLiteral(element))
+            return undefined;
+        values.push(element.text);
+    }
+    return values;
+}
 function parseStringRecord(obj) {
     const result = {};
     for (const prop of obj.properties) {
@@ -33,6 +47,9 @@ export function addWireAddon(node, state, logger) {
     let pkg;
     let rpcEndpoint;
     let mcp;
+    let auth;
+    let tags;
+    let scopes;
     let secretOverrides;
     let variableOverrides;
     let credentialOverrides;
@@ -54,6 +71,17 @@ export function addWireAddon(node, state, logger) {
                 prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
             mcp = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
         }
+        else if (key === 'auth' &&
+            (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
+            auth = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
+        }
+        else if (key === 'tags') {
+            tags = parseStringArray(prop.initializer);
+        }
+        else if (key === 'scopes') {
+            scopes = parseStringArray(prop.initializer);
+        }
         else if (key === 'secretOverrides' &&
             ts.isObjectLiteralExpression(prop.initializer)) {
             secretOverrides = parseStringRecord(prop.initializer);
@@ -74,6 +102,9 @@ export function addWireAddon(node, state, logger) {
         package: pkg,
         rpcEndpoint,
         mcp,
+        auth,
+        tags,
+        scopes,
         secretOverrides,
         variableOverrides,
         credentialOverrides,

package/dist/add/add-workflow.js

@@ -208,7 +208,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
  * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
  * pikkuScenario() calls. Detects workflow registration and extracts metadata.
  */
-export const addWorkflow = (logger, node, checker, state) => {
+export const addWorkflow = (logger, node, checker, state, options) => {
     if (!ts.isCallExpression(node)) {
         return;
     }
@@ -223,6 +223,14 @@ export const addWorkflow = (logger, node, checker, state) => {
         wrapperType = 'dsl';
     }
     else if (expression.text === 'pikkuWorkflowComplexFunc') {
+        if (!options.allow?.complexWorkflows) {
+            logger.critical(ErrorCode.COMPLEX_WORKFLOW_NOT_ALLOWED, `'${expression.text}' is used here, but this project has not enabled complex workflows. ` +
+                `Their inline steps cannot be serialized, so they are absent from the workflow graph and ` +
+                `cannot be replayed or migrated across a definition change. Express the workflow with ` +
+                `pikkuWorkflowFunc and the step DSL, or set \`allow: { complexWorkflows: true }\` in ` +
+                `pikku.config.json if the project accepts that trade.`);
+            return;
+        }
         wrapperType = 'complex';
     }
     else if (expression.text === 'pikkuScenario') {
@@ -292,6 +300,7 @@ export const addWorkflow = (logger, node, checker, state) => {
     let steps = [];
     let context = undefined;
     let dsl = undefined;
+    let asserts = undefined;
     // Try DSL workflow extraction first
     // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
     const result = extractDSLWorkflow(node, checker, {
@@ -301,6 +310,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         // Extraction succeeded
         steps = result.steps;
         context = result.context;
+        asserts = result.asserts;
         // Check if workflow contains inline steps (non-serializable)
         if (hasInlineSteps(steps)) {
             if (wrapperType === 'dsl') {
@@ -374,6 +384,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         expose,
         skip,
         scenario: wrapperType === 'scenario' ? true : undefined,
+        asserts,
         actors: actorNames.length > 0 ? actorNames : undefined,
     };
     // The scenario "logger/config only" rule (PKU673) and the implicit

package/dist/error-codes.d.ts

@@ -23,22 +23,31 @@ export declare enum ErrorCode {
     SCENARIO_BROWSER_STEP_NEEDS_ACTOR = "PKU677",
     SCENARIO_STEP_TARGET_NOT_STATIC = "PKU678",
     SCENARIO_NOT_EXTRACTABLE = "PKU679",
+    SCENARIO_HAS_NO_ASSERTION = "PKU680",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",
     WORKFLOW_GRAPH_ADDON_NOT_WIRED = "PKU642",
+    COMPLEX_WORKFLOW_NOT_ALLOWED = "PKU643",
     REMOTE_ADDON_NOT_DEV_DEPENDENCY = "PKU338",
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
+    DB_SECRET_COLUMN_STORED_PLAIN = "PKU483",
+    DB_FORM_ON_NON_STRING = "PKU484",
+    DB_DEFAULT_SCHEMA_NAME_COLLISION = "PKU485",
     SCHEMA_GENERATION_ERROR = "PKU456",
     INLINE_SCHEMA = "PKU489",
     FUNCTION_METADATA_NOT_FOUND = "PKU559",
     DUPLICATE_AUTH_DEFINITION = "PKU581",
     AUTH_NOT_EXPORTED = "PKU582",
+    DUPLICATE_PERSONAS_DEFINITION = "PKU585",
     ROUTE_PARAM_MISMATCH = "PKU571",
     ROUTE_QUERY_MISMATCH = "PKU572",
     AUTH_DISABLED_REQUIRES_SESSIONLESS = "PKU573",
+    EXPOSED_FUNCTION_HAS_NO_GATE = "PKU574",
+    TAG_RESOLVES_TO_NO_MIDDLEWARE = "PKU575",
+    PERMISSIONS_IN_BODY_NOT_ALLOWED = "PKU576",
     DUPLICATE_FUNCTION_VERSION = "PKU850",
     DUPLICATE_FUNCTION_NAME = "PKU851",
     MANIFEST_MISSING = "PKU860",
@@ -49,6 +58,9 @@ export declare enum ErrorCode {
     MANIFEST_INTEGRITY_ERROR = "PKU865",
     MISSING_MODEL = "PKU145",
     INVALID_MODEL = "PKU146",
+    AGENT_TOOL_UNKNOWN_NAMESPACE = "PKU152",
+    AGENT_TOOL_NOT_FOUND = "PKU153",
+    AGENT_TOOL_MISSING_DESCRIPTION = "PKU154",
     SCHEMA_AND_WIRING_COLOCATED = "PKU490",
     SERVICES_NOT_DESTRUCTURED = "PKU410",
     WIRES_NOT_DESTRUCTURED = "PKU411",
@@ -58,7 +70,11 @@ export declare enum ErrorCode {
     PII_IN_OUTPUT = "PKU910",
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
     ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",
-    RPC_INVOCATION_TYPE_CAST = "PKU940"
+    RPC_INVOCATION_TYPE_CAST = "PKU940",
+    SECRET_SERVICE_ALIASED = "PKU950",
+    SECRET_NOT_DECLARED = "PKU951",
+    SECRET_KEY_NOT_STATIC = "PKU952",
+    SECRET_REVEALED_INTO_SINK = "PKU953"
 }
 /**
  * Severity of a tracked, coded diagnostic. `critical` always blocks the build;

package/dist/error-codes.js

@@ -25,9 +25,11 @@ export var ErrorCode;
     ErrorCode["SCENARIO_BROWSER_STEP_NEEDS_ACTOR"] = "PKU677";
     ErrorCode["SCENARIO_STEP_TARGET_NOT_STATIC"] = "PKU678";
     ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
+    ErrorCode["SCENARIO_HAS_NO_ASSERTION"] = "PKU680";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";
+    ErrorCode["COMPLEX_WORKFLOW_NOT_ALLOWED"] = "PKU643";
     // Remote addon (wireRemoteAddon) validation
     ErrorCode["REMOTE_ADDON_NOT_DEV_DEPENDENCY"] = "PKU338";
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
@@ -35,6 +37,9 @@ export var ErrorCode;
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
     ErrorCode["DB_FORMAT_ON_NON_STRING"] = "PKU482";
+    ErrorCode["DB_SECRET_COLUMN_STORED_PLAIN"] = "PKU483";
+    ErrorCode["DB_FORM_ON_NON_STRING"] = "PKU484";
+    ErrorCode["DB_DEFAULT_SCHEMA_NAME_COLLISION"] = "PKU485";
     // Configuration errors
     ErrorCode["SCHEMA_GENERATION_ERROR"] = "PKU456";
     ErrorCode["INLINE_SCHEMA"] = "PKU489";
@@ -43,10 +48,19 @@ export var ErrorCode;
     // Auth errors
     ErrorCode["DUPLICATE_AUTH_DEFINITION"] = "PKU581";
     ErrorCode["AUTH_NOT_EXPORTED"] = "PKU582";
+    // Single-declaration constructs — one call site per codebase.
+    // PKU583 (defineScope) and PKU584 (defineSystemRole) are retired, not free:
+    // scopes and roles held this rule until the generated `admin` tree made it
+    // unsatisfiable, and get it back once `admin` is a default scope nobody
+    // declares. Do not reuse those two numbers for anything else.
+    ErrorCode["DUPLICATE_PERSONAS_DEFINITION"] = "PKU585";
     // HTTP Route errors
     ErrorCode["ROUTE_PARAM_MISMATCH"] = "PKU571";
     ErrorCode["ROUTE_QUERY_MISMATCH"] = "PKU572";
     ErrorCode["AUTH_DISABLED_REQUIRES_SESSIONLESS"] = "PKU573";
+    ErrorCode["EXPOSED_FUNCTION_HAS_NO_GATE"] = "PKU574";
+    ErrorCode["TAG_RESOLVES_TO_NO_MIDDLEWARE"] = "PKU575";
+    ErrorCode["PERMISSIONS_IN_BODY_NOT_ALLOWED"] = "PKU576";
     // Versioning errors
     ErrorCode["DUPLICATE_FUNCTION_VERSION"] = "PKU850";
     ErrorCode["DUPLICATE_FUNCTION_NAME"] = "PKU851";
@@ -60,6 +74,10 @@ export var ErrorCode;
     // Model configuration errors
     ErrorCode["MISSING_MODEL"] = "PKU145";
     ErrorCode["INVALID_MODEL"] = "PKU146";
+    // Agent tool reference errors
+    ErrorCode["AGENT_TOOL_UNKNOWN_NAMESPACE"] = "PKU152";
+    ErrorCode["AGENT_TOOL_NOT_FOUND"] = "PKU153";
+    ErrorCode["AGENT_TOOL_MISSING_DESCRIPTION"] = "PKU154";
     // File structure errors
     ErrorCode["SCHEMA_AND_WIRING_COLOCATED"] = "PKU490";
     // Optimization diagnostics
@@ -75,4 +93,9 @@ export var ErrorCode;
     ErrorCode["ADDON_WIRING_NOT_ALLOWED"] = "PKU920";
     ErrorCode["ADDON_CONTRACT_HANDLERS_NOT_ALLOWED"] = "PKU921";
     ErrorCode["RPC_INVOCATION_TYPE_CAST"] = "PKU940";
+    // Secret boundary errors
+    ErrorCode["SECRET_SERVICE_ALIASED"] = "PKU950";
+    ErrorCode["SECRET_NOT_DECLARED"] = "PKU951";
+    ErrorCode["SECRET_KEY_NOT_STATIC"] = "PKU952";
+    ErrorCode["SECRET_REVEALED_INTO_SINK"] = "PKU953";
 })(ErrorCode || (ErrorCode = {}));

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export type { ContractEntry, VersionHashEntry, VersionValidateError, VersionManifest, VersionManifestEntry, } from './utils/contract-hashes.js';
-export type { InspectorFeature, InspectorFeatureEntry } from './types.js';
+export type { InspectorFeature, InspectorFeatureEntry, } from './types.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';

package/dist/inspector.js

@@ -6,13 +6,17 @@ import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeSecretBrokers, validateNoSecretAliasServices, validateSecretUsage, computeDiagnostics, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, 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';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
 import { pikkuState } from '@pikku/core/internal';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
 import { finalizeWorkflowHelperTypes, finalizeWorkflowWires, } from './utils/workflow/graph/finalize-workflow-wires.js';
 import { generateAllSchemas } from './utils/schema-generator.js';
+import { extractSecretUsage } from './utils/extract-secret-usage.js';
 import { loadAddonFunctionsMeta, loadAddonSchemas, } from './utils/load-addon-functions-meta.js';
 import { computeContractHashes, extractContractsFromMeta, updateManifest, createEmptyManifest, validateContracts, } from './utils/contract-hashes.js';
 /**
@@ -132,6 +136,7 @@ export function getInitialInspectorState(rootDir) {
         secrets: {
             definitions: [],
             files: new Set(),
+            usage: new Map(),
         },
         credentials: {
             definitions: [],
@@ -141,6 +146,14 @@ export function getInitialInspectorState(rootDir) {
             definitions: [],
             files: new Set(),
         },
+        systemRoles: {
+            definitions: [],
+            files: new Set(),
+        },
+        personas: {
+            definitions: [],
+            files: new Set(),
+        },
         variables: {
             definitions: [],
             files: new Set(),
@@ -282,6 +295,12 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         .sort((a, b) => a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0);
     logger.debug(`Got source files in ${(performance.now() - startSourceFiles).toFixed(2)}ms`);
     const state = getInitialInspectorState(rootDir);
+    for (const sourceFile of sourceFiles) {
+        const usage = extractSecretUsage(sourceFile);
+        if (usage.keys.length > 0 || usage.dynamic.length > 0) {
+            state.secrets.usage.set(sourceFile.fileName, usage);
+        }
+    }
     // First sweep: add all functions
     const startSetup = performance.now();
     for (const sourceFile of sourceFiles) {
@@ -342,21 +361,34 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         computeResolvedIOTypes(state);
         computeMiddlewareGroupsMeta(state);
         computePermissionsGroupsMeta(state);
+        computeSecretBrokers(state);
+        validateNoSecretAliasServices(logger, checker, state);
+        validateSecretUsage(logger, state);
         computeDiagnostics(state);
         validateSchemaWiringSeparation(logger, state);
         validateWorkflowGraphAddons(logger, state);
         validateScenarioServices(logger, state);
         validateScenarioSteps(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);
+        // Last of the validators: they read function meta and every wireAddon
+        // declaration together, so they need the whole program inspected.
+        validateExposedFunctionsGated(logger, state);
+        validateTagsResolveToMiddleware(logger, state);
         if (options.openAPI) {
             state.openAPISpec = await generateOpenAPISpec(logger, state.functions.meta, state.http.meta, state.schemas, options.openAPI.additionalInfo, pikkuState(null, 'misc', 'errors'));
         }
         validateAgentModels(logger, state);
+        validateAgentToolReferences(logger, state, options);
         validateSecretOverrides(logger, state);
         validateVariableOverrides(logger, state);
         validateCredentialOverrides(logger, state);
         validateRemoteAddonDependencies(logger, state);
         validateRemoteAddonAuth(logger, state);
         validateScopeReferences(logger, state);
+        validateSystemRoleScopes(logger, state);
+        validatePersonaRoles(logger, state);
     }
     state.program = program;
     return state;