@pikku/inspector 0.12.50 → 0.12.54

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type * as ts from 'typescript';
+import type { SecretUsage } from './utils/extract-secret-usage.js';
 import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel';
 import type { GatewaysMeta } from '@pikku/core/gateway';
 import type { HTTPWiringsMeta } from '@pikku/core/http';
@@ -14,6 +15,8 @@ import type { NodesMeta } from '@pikku/core/node';
 import type { SecretDefinitions } from '@pikku/core/secret';
 import type { CredentialDefinitions } from '@pikku/core/credential';
 import type { ScopeDefinitions } from '@pikku/core/scope';
+import type { SystemRoleDefinitions } from '@pikku/core/role';
+import type { PersonaDefinitions } from '@pikku/core/persona';
 import type { VariableDefinitions } from '@pikku/core/variable';
 import type { TypesMap } from './types-map.js';
 import type { FunctionsMeta, FunctionServicesMeta, FunctionWiresMeta, JSONValue } from '@pikku/core';
@@ -31,14 +34,30 @@ export type MetaInputTypes = Map<string, {
     params: string[] | undefined;
     body: string[] | undefined;
 }>;
-export interface MiddlewareGroupMeta {
+/** One `addHTTPMiddleware`/`addTagMiddleware`/`addChannelMiddleware` call. */
+export interface MiddlewareRegistration {
     exportName: string | null;
     sourceFile: string;
     position: number;
+    isFactory: boolean;
+}
+export interface MiddlewareGroupMeta extends MiddlewareRegistration {
     services: FunctionServicesMeta;
     count: number;
     instanceIds: string[];
-    isFactory: boolean;
+    /**
+     * The registrations after the first, when several files add middleware for
+     * the same pattern or tag.
+     *
+     * A group is keyed by its pattern/tag, so without this a second file's call
+     * overwrote the first's and only the survivor got an import emitted into
+     * pikku-middleware.gen.ts — the losing file was never imported, so its
+     * registration never ran. The runtime composes repeated registrations for a
+     * pattern happily; only codegen dropped one, which is how an app could lose
+     * its session-bridge middleware to an unrelated `'*'` group and see nothing
+     * go wrong until a request arrived without a session.
+     */
+    additionalRegistrations?: MiddlewareRegistration[];
 }
 export interface InspectorHTTPState {
     metaInputTypes: MetaInputTypes;
@@ -204,6 +223,12 @@ export type InspectorOptions = Partial<{
     setupOnly: boolean;
     rootDir: string;
     isAddon: boolean;
+    /**
+     * Fail the build on metadata that only an agent needs — currently an agent
+     * tool with no description. Off by default: the runtime falls back to the
+     * tool's own name, so this is a quality gate rather than a correctness one.
+     */
+    strictMeta: boolean;
     sourceFile: ts.SourceFile;
     /**
      * The project's tsconfig, read for its path mappings only. The inspector's
@@ -243,6 +268,15 @@ export type InspectorOptions = Partial<{
      * function, which is expensive. Enabled via `pikku all --security`.
      */
     classificationCheck: boolean;
+    /**
+     * Escape hatches the project has opted into, from `allow` in
+     * `pikku.config.json`. Absent or false means the feature is refused with a
+     * critical naming the flag that would permit it.
+     */
+    allow: Partial<{
+        permissionsInBody: boolean;
+        complexWorkflows: boolean;
+    }>;
 }>;
 export interface InspectorLogger {
     info: (message: string) => void;
@@ -464,6 +498,15 @@ export interface InspectorState {
             package: string;
             rpcEndpoint?: string;
             mcp?: boolean;
+            /**
+             * The addon's own gates. `runPikkuFunc` applies these to every function
+             * in the package, on every wiring path — not just `namespace:function`.
+             * Absent when the declared value was not a statically-knowable literal,
+             * which must be read as "unknown", never as "ungated".
+             */
+            auth?: boolean;
+            tags?: string[];
+            scopes?: string[];
             /** True when declared via `wireRemoteAddon` — import the addon's `.remote.gen` map, not `.internal.gen` */
             remote?: boolean;
             /** wireRemoteAddon: whether an `auth` binding was supplied (vs a public surface) */
@@ -522,6 +565,8 @@ export interface InspectorState {
     secrets: {
         definitions: SecretDefinitions;
         files: Set<string>;
+        /** Secret reads found per source file, keyed by absolute path. */
+        usage: Map<string, SecretUsage>;
     };
     credentials: {
         definitions: CredentialDefinitions;
@@ -531,6 +576,14 @@ export interface InspectorState {
         definitions: ScopeDefinitions;
         files: Set<string>;
     };
+    systemRoles: {
+        definitions: SystemRoleDefinitions;
+        files: Set<string>;
+    };
+    personas: {
+        definitions: PersonaDefinitions;
+        files: Set<string>;
+    };
     variables: {
         definitions: VariableDefinitions;
         files: Set<string>;

package/dist/utils/annotate-http-route-auth.d.ts

@@ -0,0 +1,22 @@
+import type { InspectorState } from '../types.js';
+/**
+ * Resolve, per HTTP route, whether reaching it requires a session.
+ *
+ * Four separate places can demand one — the function's `sessionless`, the
+ * function's own `auth`, the route's (or its group's) `auth`, and the addon the
+ * function belongs to — and they combine with OR: any of them is enough. Until
+ * this was written down, "which routes are open?" could only be answered by
+ * joining all four by hand, and getting the join wrong reads an open route as a
+ * closed one, which is the direction that costs something.
+ *
+ * A scope gate counts as requiring a session. Scopes are checked against the
+ * session's and fail closed, so an anonymous caller is rejected either way; not
+ * counting them would mark a route open that nobody can reach anonymously.
+ *
+ * Anything not statically knowable resolves to requiring a session, matching
+ * `validateExposedFunctionsGated`: an over-cautious `true` costs a route that
+ * looks stricter than it is, a wrong `false` costs an audit.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export declare function annotateHttpRouteAuth(state: InspectorState): void;

package/dist/utils/annotate-http-route-auth.js

@@ -0,0 +1,48 @@
+/**
+ * Resolve, per HTTP route, whether reaching it requires a session.
+ *
+ * Four separate places can demand one — the function's `sessionless`, the
+ * function's own `auth`, the route's (or its group's) `auth`, and the addon the
+ * function belongs to — and they combine with OR: any of them is enough. Until
+ * this was written down, "which routes are open?" could only be answered by
+ * joining all four by hand, and getting the join wrong reads an open route as a
+ * closed one, which is the direction that costs something.
+ *
+ * A scope gate counts as requiring a session. Scopes are checked against the
+ * session's and fail closed, so an anonymous caller is rejected either way; not
+ * counting them would mark a route open that nobody can reach anonymously.
+ *
+ * Anything not statically knowable resolves to requiring a session, matching
+ * `validateExposedFunctionsGated`: an over-cautious `true` costs a route that
+ * looks stricter than it is, a wrong `false` costs an audit.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export function annotateHttpRouteAuth(state) {
+    const gatedPackages = packagesGatedByTheirAddon(state);
+    for (const routes of Object.values(state.http?.meta ?? {})) {
+        for (const route of Object.values(routes)) {
+            const meta = state.functions.meta[route.refTarget ?? route.pikkuFuncId];
+            route.requiresSession =
+                // A pikkuFunc always requires a session, on every path.
+                meta?.sessionless === false ||
+                    meta?.auth === true ||
+                    (meta?.scopes?.length ?? 0) > 0 ||
+                    route.auth === true ||
+                    (route.packageName !== undefined &&
+                        gatedPackages.has(route.packageName));
+        }
+    }
+}
+/** Packages whose `wireAddon` demands a session from everything inside them. */
+function packagesGatedByTheirAddon(state) {
+    const gated = new Set();
+    for (const declaration of state.rpc?.wireAddonDeclarations?.values() ?? []) {
+        if (!declaration.package)
+            continue;
+        if (declaration.auth === true || (declaration.scopes?.length ?? 0) > 0) {
+            gated.add(declaration.package);
+        }
+    }
+    return gated;
+}

package/dist/utils/check-secret-sinks.d.ts

@@ -0,0 +1,31 @@
+import * as ts from 'typescript';
+export type SecretSinkViolation = {
+    /** How the value reaches the outside world, e.g. `logger.info`. */
+    sink: string;
+    /** Dotted path to the secret inside the argument, or `<argument>` when bare. */
+    path: string;
+    /** Position of the offending argument, for the diagnostic message. */
+    line: number;
+};
+/**
+ * Finds revealed vault secrets that flow into a sink.
+ *
+ * `SecretValue` is nominally typed, so the type system alone stops it reaching
+ * any of these. `.reveal()` is the deliberate escape hatch, and it hands back
+ * `Secret<T>` — the erasable classification brand. That brand is what this scan
+ * follows, which means it catches the revealed value both inline
+ * (`logger.info(s.reveal())`) and through a local binding, because the local's
+ * inferred type carries the brand too.
+ *
+ * The brand is optional by design, so an explicit annotation (`const t: string =
+ * s.reveal()`) erases it and this scan goes quiet. That is the documented limit
+ * of a structural marker: it catches the mistake, not someone determined to
+ * silence it.
+ *
+ * Sinks are matched on the receiver's resolved core interface, which means the
+ * scan needs the services parameter to be typed. Real projects get that from
+ * the generated `#pikku` factory; a hand-rolled file that calls the raw core
+ * factory without annotating its services leaves the parameter `any`, and an
+ * `any` receiver matches nothing.
+ */
+export declare function findRevealedSecretSinks(checker: ts.TypeChecker, handler: ts.Node): SecretSinkViolation[];

package/dist/utils/check-secret-sinks.js

@@ -0,0 +1,117 @@
+import * as ts from 'typescript';
+import { findPiiPaths } from './check-pii-output.js';
+import { doesTypeExtendsCore } from './does-type-extend-core-type.js';
+/**
+ * A method that writes its arguments somewhere a secret must never land, keyed
+ * by the core interface that owns it. `'*'` means every method on the type is a
+ * sink, which is true of a logger.
+ */
+const SINKS = [
+    { coreType: 'Logger', methods: '*' },
+    { coreType: 'QueueService', methods: ['add'] },
+    { coreType: 'EmailService', methods: ['send'] },
+    { coreType: 'WebhookService', methods: ['send'] },
+    { coreType: 'AuditService', methods: ['audit', 'write'] },
+    { coreType: 'AuditLog', methods: ['write'] },
+];
+/**
+ * Finds revealed vault secrets that flow into a sink.
+ *
+ * `SecretValue` is nominally typed, so the type system alone stops it reaching
+ * any of these. `.reveal()` is the deliberate escape hatch, and it hands back
+ * `Secret<T>` — the erasable classification brand. That brand is what this scan
+ * follows, which means it catches the revealed value both inline
+ * (`logger.info(s.reveal())`) and through a local binding, because the local's
+ * inferred type carries the brand too.
+ *
+ * The brand is optional by design, so an explicit annotation (`const t: string =
+ * s.reveal()`) erases it and this scan goes quiet. That is the documented limit
+ * of a structural marker: it catches the mistake, not someone determined to
+ * silence it.
+ *
+ * Sinks are matched on the receiver's resolved core interface, which means the
+ * scan needs the services parameter to be typed. Real projects get that from
+ * the generated `#pikku` factory; a hand-rolled file that calls the raw core
+ * factory without annotating its services leaves the parameter `any`, and an
+ * `any` receiver matches nothing.
+ */
+export function findRevealedSecretSinks(checker, handler) {
+    const violations = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const sink = describeSink(checker, node.expression);
+            if (sink) {
+                for (const arg of node.arguments) {
+                    const found = findSecretExpression(checker, arg);
+                    if (found) {
+                        violations.push({
+                            sink,
+                            path: found.getText(),
+                            line: found
+                                .getSourceFile()
+                                .getLineAndCharacterOfPosition(found.getStart()).line + 1,
+                        });
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(handler);
+    return violations;
+}
+/**
+ * Finds the first expression inside a sink argument whose own type carries the
+ * secret brand, and returns it so the diagnostic can quote it.
+ *
+ * This walks the argument rather than typing it whole, because an object
+ * literal in an argument position is contextually typed by the parameter — for
+ * a guarded sink that parameter is `Safe<M>`, and resolving the literal against
+ * it drops the optional brand before it can be read. Each inner expression
+ * (`token.reveal()`, or a reference to a local holding it) carries its own type
+ * regardless of the surrounding context, so reading those is what actually
+ * sees the secret.
+ */
+function findSecretExpression(checker, node) {
+    // Descend first, so an object literal wrapping the secret reports the
+    // expression that actually holds it (`token.reveal()`) rather than the whole
+    // literal. Nothing inside a `SecretValue` receiver is itself branded, so a
+    // bare `token.reveal()` still falls through to the self-check below.
+    for (const child of node.getChildren()) {
+        // A property name is not a value, and typing it re-resolves the property.
+        if (ts.isPropertyAssignment(node) && child === node.name)
+            continue;
+        const found = findSecretExpression(checker, child);
+        if (found)
+            return found;
+    }
+    if (ts.isExpression(node) && !ts.isStringLiteralLike(node)) {
+        const type = checker.getTypeAtLocation(node);
+        const isSecret = findPiiPaths(checker, type).some((f) => f.classification === 'secret');
+        if (isSecret)
+            return node;
+    }
+    return undefined;
+}
+/**
+ * Names the sink a call writes to, or undefined when the call is not one.
+ * `console` is matched by identifier because it is a global with no Pikku type;
+ * everything else is matched on its resolved core interface so a renamed
+ * service or a decorator still counts.
+ */
+function describeSink(checker, callee) {
+    const method = callee.name.text;
+    const receiver = callee.expression;
+    if (ts.isIdentifier(receiver) && receiver.text === 'console') {
+        return `console.${method}`;
+    }
+    const receiverType = checker.getTypeAtLocation(receiver);
+    for (const { coreType, methods } of SINKS) {
+        if (methods !== '*' && !methods.includes(method))
+            continue;
+        if (doesTypeExtendsCore(receiverType, checker, new Set(), coreType)) {
+            return `${receiver.getText()}.${method}`;
+        }
+    }
+    return undefined;
+}

package/dist/utils/extract-function-name.js

@@ -29,15 +29,24 @@ export function funcIdToTypeName(id) {
         .join('');
 }
 /**
- * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
- * scenarios reference a step by that string, so it must become the pikkuFuncId
- * (and hence the generated step map's key), not just a cosmetic label the way
+ * The step wrappers, whichever kind of subject acts in them. A scenario calls a
+ * platform or addon step by name exactly as it calls a persona one.
+ */
+const SCENARIO_STEP_WRAPPERS = new Set([
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+]);
+/**
+ * A scenario step is the one wrapper whose `name` is its identity: scenarios
+ * reference a step by that string, so it must become the pikkuFuncId (and hence
+ * the generated step map's key), not just a cosmetic label the way
  * `pikkuMiddleware`/`pikkuAgent` use it.
  */
 function extractScenarioStepName(callExpr, result) {
     if (!ts.isCallExpression(callExpr) ||
         !ts.isIdentifier(callExpr.expression) ||
-        callExpr.expression.text !== 'pikkuScenarioStep') {
+        !SCENARIO_STEP_WRAPPERS.has(callExpr.expression.text)) {
         return;
     }
     const firstArg = callExpr.arguments[0];

package/dist/utils/extract-function-node.js

@@ -1,5 +1,15 @@
 import * as ts from 'typescript';
 import { getPropertyAssignmentInitializer, resolveFunctionDeclaration, } from './type-utils.js';
+/**
+ * Where a config object's implementation can live, in the order it is looked for.
+ *
+ * `func` is the ordinary case. A `pikkuScenarioStep` instead declares one
+ * implementation per surface, and every binding shares the step's input and
+ * output — that is what makes them interchangeable — so any one of them types
+ * the step. `default` is preferred because it is the binding every step is
+ * expected to have.
+ */
+const IMPLEMENTATION_KEYS = ['func', 'default', 'browser', 'cli'];
 /**
  * Extracts the actual function node from a pikkuFunc/pikkuWorkflowFunc call
  * Handles both direct function form and config object form { func: ... }
@@ -10,7 +20,14 @@ export function extractFunctionNode(firstArg, checker) {
     // Check if first argument is a config object with 'func' property
     if (ts.isObjectLiteralExpression(firstArg)) {
         isDirectFunction = false;
-        const funcInitializer = getPropertyAssignmentInitializer(firstArg, 'func', true, checker);
+        let funcInitializer;
+        for (const key of IMPLEMENTATION_KEYS) {
+            funcInitializer =
+                getPropertyAssignmentInitializer(firstArg, key, true, checker) ??
+                    undefined;
+            if (funcInitializer)
+                break;
+        }
         if (funcInitializer) {
             funcNode = funcInitializer;
         }

package/dist/utils/extract-secret-usage.d.ts

@@ -0,0 +1,9 @@
+import ts from 'typescript';
+export type SecretUsage = {
+    /** Secret ids read with a string literal, so statically known. */
+    keys: string[];
+    /** Reads whose key could not be resolved statically, as `line:source`. */
+    dynamic: string[];
+};
+/** Secret reads in a file, whether the key is statically known or not. */
+export declare const extractSecretUsage: (sourceFile: ts.SourceFile) => SecretUsage;

package/dist/utils/extract-secret-usage.js

@@ -0,0 +1,61 @@
+import ts from 'typescript';
+const SINGLE_KEY_METHODS = new Set(['getSecret', 'hasSecret']);
+const KEY_LIST_METHODS = new Set(['getSecrets']);
+const literalKey = (node) => {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    return undefined;
+};
+/** Secret reads in a file, whether the key is statically known or not. */
+export const extractSecretUsage = (sourceFile) => {
+    const keys = new Set();
+    const dynamic = new Set();
+    const record = (node, argument) => {
+        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        dynamic.add(`${line + 1}:${(argument ?? node).getText()}`);
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression)) {
+            const method = node.expression.name.text;
+            const [firstArgument] = node.arguments;
+            if (SINGLE_KEY_METHODS.has(method)) {
+                if (!firstArgument) {
+                    record(node);
+                }
+                else {
+                    const key = literalKey(firstArgument);
+                    if (key === undefined) {
+                        record(node, firstArgument);
+                    }
+                    else {
+                        keys.add(key);
+                    }
+                }
+            }
+            else if (KEY_LIST_METHODS.has(method)) {
+                if (firstArgument && ts.isArrayLiteralExpression(firstArgument)) {
+                    for (const element of firstArgument.elements) {
+                        const key = literalKey(element);
+                        if (key === undefined) {
+                            record(node, element);
+                        }
+                        else {
+                            keys.add(key);
+                        }
+                    }
+                }
+                else {
+                    record(node, firstArgument);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return {
+        keys: [...keys].sort(),
+        dynamic: [...dynamic].sort(),
+    };
+};

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

@@ -0,0 +1,22 @@
+import * as ts from 'typescript';
+/**
+ * Readers for object-literal properties that must be statically knowable.
+ *
+ * Declarations extracted this way are never evaluated — the CLI reads them from
+ * source and writes them to JSON that a deployed stage carries without the app.
+ * So a computed value is not "unsupported", it is unreadable, and every reader
+ * here returns `undefined` for one rather than guessing.
+ */
+export declare const getProperty: (config: ts.ObjectLiteralExpression, name: string) => ts.Expression | undefined;
+export declare const stringProperty: (config: ts.ObjectLiteralExpression, name: string) => string | undefined;
+export declare const numberProperty: (config: ts.ObjectLiteralExpression, name: string) => number | undefined;
+export declare const booleanProperty: (config: ts.ObjectLiteralExpression, name: string) => boolean | undefined;
+/**
+ * All-or-nothing: an array with one computed entry reads as unreadable rather
+ * than as the entries that happened to be literals. A half-read `roles` or
+ * `scopes` array is worse than none — it typechecks, runs, and grants less
+ * than the source says.
+ */
+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;

package/dist/utils/literal-properties.js

@@ -0,0 +1,69 @@
+import * as ts from 'typescript';
+/**
+ * Readers for object-literal properties that must be statically knowable.
+ *
+ * Declarations extracted this way are never evaluated — the CLI reads them from
+ * source and writes them to JSON that a deployed stage carries without the app.
+ * So a computed value is not "unsupported", it is unreadable, and every reader
+ * here returns `undefined` for one rather than guessing.
+ */
+export const getProperty = (config, name) => {
+    const property = config.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === name);
+    return property && ts.isPropertyAssignment(property)
+        ? property.initializer
+        : undefined;
+};
+export const stringProperty = (config, name) => {
+    const value = getProperty(config, name);
+    return value && ts.isStringLiteralLike(value) ? value.text : undefined;
+};
+export const numberProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value) {
+        return undefined;
+    }
+    // `-1` parses as a unary minus over a literal, not as a literal. Reading it
+    // rather than ignoring it is what lets a negative be *rejected* by the caller
+    // instead of silently dropped and defaulted.
+    if (ts.isPrefixUnaryExpression(value) &&
+        value.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(value.operand)) {
+        return -Number(value.operand.text);
+    }
+    return ts.isNumericLiteral(value) ? Number(value.text) : undefined;
+};
+export const booleanProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value) {
+        return undefined;
+    }
+    if (value.kind === ts.SyntaxKind.TrueKeyword) {
+        return true;
+    }
+    if (value.kind === ts.SyntaxKind.FalseKeyword) {
+        return false;
+    }
+    return undefined;
+};
+/**
+ * All-or-nothing: an array with one computed entry reads as unreadable rather
+ * than as the entries that happened to be literals. A half-read `roles` or
+ * `scopes` array is worse than none — it typechecks, runs, and grants less
+ * than the source says.
+ */
+export const stringArrayProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value || !ts.isArrayLiteralExpression(value)) {
+        return undefined;
+    }
+    const values = value.elements
+        .filter(ts.isStringLiteralLike)
+        .map((e) => e.text);
+    return values.length === value.elements.length ? values : undefined;
+};
+/** Unwraps `x as const` / `x satisfies T` so a cast is still extracted. */
+export const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node;

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

@@ -69,6 +69,25 @@ const applyPackageToChannelContracts = (contracts, packageName, namespace) => {
         }
     }
 };
+/**
+ * Resolves an addon's generated metadata, preferring the verbose copy.
+ *
+ * An addon publishes both: the minimal one its own bootstrap imports, and the
+ * verbose one for anything that needs the fields stripped out of it. A consumer
+ * is squarely in the second category — it is reading the addon to describe it,
+ * not to run it.
+ */
+const resolveAddonMeta = (require, packageName, baseName) => {
+    for (const suffix of ['-verbose.gen.json', '.gen.json']) {
+        try {
+            return require.resolve(`${packageName}/.pikku/${baseName}${suffix}`);
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+};
 /**
  * After the setup sweep discovers wireAddon() declarations, load each addon
  * package's function metadata so that wiring handlers (channels, HTTP routes,
@@ -86,7 +105,13 @@ export async function loadAddonFunctionsMeta(logger, state) {
         if (decl.remote)
             continue;
         try {
-            const metaPath = require.resolve(`${decl.package}/.pikku/function/pikku-functions-meta.gen.json`);
+            // Verbose first. `description` is one of the fields stripped from the
+            // minimal copy, and it is what an addon's function is offered to a model
+            // under — both as an MCP tool below and as an agent tool. Read the minimal
+            // one and every addon function looks undescribed.
+            const metaPath = resolveAddonMeta(require, decl.package, 'function/pikku-functions-meta');
+            if (!metaPath)
+                throw new Error('no function metadata');
             const raw = await readFile(metaPath, 'utf-8');
             const meta = JSON.parse(raw);
             state.addonFunctions[namespace] = meta;

package/dist/utils/permissions.js

@@ -42,6 +42,14 @@ export function extractPermissionPikkuNames(node, checker, rootDir) {
             if (ts.isPropertyAssignment(prop)) {
                 extractFromElement(prop.initializer);
             }
+            else if (ts.isShorthandPropertyAssignment(prop)) {
+                // `permissions: { canAdminOrg }`. The runtime resolves this exactly
+                // like the longhand form — `verifyPermissions` has a non-array branch —
+                // so dropping it here reported a guarded function as having no
+                // permissions at all, which is the most dangerous direction to be wrong
+                // in: an audit reading meta sees an open door where one is shut.
+                extractFromElement(prop.name);
+            }
         }
     }
     return names;