@pikku/inspector 0.12.41 → 0.12.43

package/dist/utils/post-process.js

@@ -1,6 +1,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 { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js';
+import { flattenScopeDefinitions } from '@pikku/core/scope';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -39,28 +42,22 @@ export function extractWireNames(list) {
         .map((item) => item.name);
 }
 /**
- * Helper to expand middleware/permission groups into individual names
- * and add their services to the aggregation.
- * This handles tag-based and HTTP-pattern-based middleware/permission groups.
+ * Helper to expand middleware groups into individual names and add their
+ * services to the aggregation. Handles tag-based and HTTP-pattern-based
+ * middleware groups. Permissions are function-scoped only and carry no groups.
  */
-function expandAndAddGroupServices(list, state, addServices, isMiddleware) {
+function expandAndAddGroupServices(list, state, addServices) {
     if (!list)
         return;
     for (const item of list) {
         if (item.type === 'tag') {
-            // Expand tag-based group
-            const groupMeta = isMiddleware
-                ? state.middleware.tagMiddleware.get(item.tag)
-                : state.permissions.tagPermissions.get(item.tag);
+            const groupMeta = state.middleware.tagMiddleware.get(item.tag);
             if (groupMeta?.services) {
                 addServices(groupMeta.services);
             }
         }
         else if (item.type === 'http' && 'route' in item) {
-            // Expand HTTP-pattern-based group
-            const groupMeta = isMiddleware
-                ? state.http.routeMiddleware.get(item.route)
-                : state.http.routePermissions.get(item.route);
+            const groupMeta = state.http.routeMiddleware.get(item.route);
             if (groupMeta?.services) {
                 addServices(groupMeta.services);
             }
@@ -149,34 +146,27 @@ export function aggregateRequiredServices(state) {
         'options',
     ]) {
         for (const routeMeta of Object.values(state.http.meta[method])) {
-            expandAndAddGroupServices(routeMeta.middleware, state, addServices, true);
-            expandAndAddGroupServices(routeMeta.permissions, state, addServices, false);
+            expandAndAddGroupServices(routeMeta.middleware, state, addServices);
         }
     }
     // Also check other wiring types (channels, queues, schedulers, MCP)
     for (const channelMeta of Object.values(state.channels.meta)) {
-        expandAndAddGroupServices(channelMeta.middleware, state, addServices, true);
-        expandAndAddGroupServices(channelMeta.permissions, state, addServices, false);
+        expandAndAddGroupServices(channelMeta.middleware, state, addServices);
     }
     for (const queueMeta of Object.values(state.queueWorkers.meta)) {
-        expandAndAddGroupServices(queueMeta.middleware, state, addServices, true);
-        // expandAndAddGroupServices(queueMeta.permissions, state, addServices, false)
+        expandAndAddGroupServices(queueMeta.middleware, state, addServices);
     }
     for (const scheduleMeta of Object.values(state.scheduledTasks.meta)) {
-        expandAndAddGroupServices(scheduleMeta.middleware, state, addServices, true);
-        // expandAndAddGroupServices(scheduleMeta.permissions, state, addServices, false)
+        expandAndAddGroupServices(scheduleMeta.middleware, state, addServices);
     }
     for (const toolMeta of Object.values(state.mcpEndpoints.toolsMeta)) {
-        expandAndAddGroupServices(toolMeta.middleware, state, addServices, true);
-        expandAndAddGroupServices(toolMeta.permissions, state, addServices, false);
+        expandAndAddGroupServices(toolMeta.middleware, state, addServices);
     }
     for (const promptMeta of Object.values(state.mcpEndpoints.promptsMeta)) {
-        expandAndAddGroupServices(promptMeta.middleware, state, addServices, true);
-        expandAndAddGroupServices(promptMeta.permissions, state, addServices, false);
+        expandAndAddGroupServices(promptMeta.middleware, state, addServices);
     }
     for (const resourceMeta of Object.values(state.mcpEndpoints.resourcesMeta)) {
-        expandAndAddGroupServices(resourceMeta.middleware, state, addServices, true);
-        expandAndAddGroupServices(resourceMeta.permissions, state, addServices, false);
+        expandAndAddGroupServices(resourceMeta.middleware, state, addServices);
     }
     // 5. Services from session service factories
     for (const singletonServices of state.wireServicesMeta.values()) {
@@ -299,14 +289,17 @@ export function validateSecretOverrides(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
         return;
-    const secretNames = new Set(state.secrets.definitions.map((d) => d.name));
+    // secretOverrides key on (and resolve to) SECRET IDs — the string the addon
+    // passes to getSecret — so validate against secretId, falling back to name for
+    // older meta without a secretId field.
+    const secretIds = new Set(state.secrets.definitions.map((d) => d.secretId ?? d.name));
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
         if (!addonDecl.secretOverrides)
             continue;
-        for (const secretKey of Object.keys(addonDecl.secretOverrides)) {
-            if (!secretNames.has(secretKey)) {
-                const availableSecrets = Array.from(secretNames);
-                logger.critical(ErrorCode.INVALID_VALUE, `Secret override '${secretKey}' in addon '${namespace}' (${addonDecl.package}) does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`);
+        for (const [logicalName, resolvedName] of Object.entries(addonDecl.secretOverrides)) {
+            if (!secretIds.has(resolvedName)) {
+                const availableSecrets = Array.from(secretIds);
+                logger.critical(ErrorCode.INVALID_VALUE, `Secret override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`);
             }
         }
     }
@@ -319,10 +312,10 @@ export function validateCredentialOverrides(logger, state) {
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
         if (!addonDecl.credentialOverrides)
             continue;
-        for (const credentialKey of Object.keys(addonDecl.credentialOverrides)) {
-            if (!credentialNames.has(credentialKey)) {
+        for (const [logicalName, resolvedName] of Object.entries(addonDecl.credentialOverrides)) {
+            if (!credentialNames.has(resolvedName)) {
                 const availableCredentials = Array.from(credentialNames);
-                logger.critical(ErrorCode.INVALID_VALUE, `Credential override '${credentialKey}' in addon '${namespace}' (${addonDecl.package}) does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Credential override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
             }
         }
     }
@@ -331,18 +324,82 @@ export function validateVariableOverrides(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
         return;
-    const variableNames = new Set(state.variables.definitions.map((d) => d.name));
+    // variableOverrides key on (and resolve to) VARIABLE IDs, so validate against
+    // variableId, falling back to name for older meta without a variableId field.
+    const variableIds = new Set(state.variables.definitions.map((d) => d.variableId ?? d.name));
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
         if (!addonDecl.variableOverrides)
             continue;
-        for (const variableKey of Object.keys(addonDecl.variableOverrides)) {
-            if (!variableNames.has(variableKey)) {
-                const availableVariables = Array.from(variableNames);
-                logger.critical(ErrorCode.INVALID_VALUE, `Variable override '${variableKey}' in addon '${namespace}' (${addonDecl.package}) does not exist. Available variables: ${availableVariables.join(', ') || 'none'}`);
+        for (const [logicalName, resolvedName] of Object.entries(addonDecl.variableOverrides)) {
+            if (!variableIds.has(resolvedName)) {
+                const availableVariables = Array.from(variableIds);
+                logger.critical(ErrorCode.INVALID_VALUE, `Variable override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a variable that does not exist. Available variables: ${availableVariables.join(', ') || 'none'}`);
             }
         }
     }
 }
+/**
+ * A `wireRemoteAddon` package ships types only — its handlers run on the host —
+ * so it MUST be a devDependency, not a production dependency (a prod dep would
+ * drag in the runtime deps remote consumption exists to avoid). This is the
+ * mirror image of `wireAddon`, which requires a production dependency.
+ */
+export function validateRemoteAddonDependencies(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
+        return;
+    const hasRemote = Array.from(wireAddonDeclarations.values()).some((d) => d.remote);
+    if (!hasRemote)
+        return;
+    const pkgJsonPath = join(state.rootDir, 'package.json');
+    if (!existsSync(pkgJsonPath))
+        return; // no manifest to check (e.g. some tests)
+    let pkgJson;
+    try {
+        pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+    }
+    catch (e) {
+        logger.warn(`Could not read ${pkgJsonPath} to verify remote addon dependencies: ${e?.message ?? e}`);
+        return;
+    }
+    const prodDeps = pkgJson.dependencies ?? {};
+    const devDeps = pkgJson.devDependencies ?? {};
+    for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+        if (!decl.remote)
+            continue;
+        if (decl.package in devDeps)
+            continue; // correct
+        if (decl.package in prodDeps) {
+            logger.critical(ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY, `Remote addon '${namespace}' ('${decl.package}') is a production dependency, but wireRemoteAddon consumes it for types only — its handlers run on the host. Move '${decl.package}' from "dependencies" to "devDependencies".`);
+        }
+        else {
+            logger.critical(ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY, `Remote addon '${namespace}' ('${decl.package}') is wired with wireRemoteAddon but is not in "devDependencies". Add '${decl.package}' to "devDependencies" (types only).`);
+        }
+    }
+}
+/**
+ * The auth a `wireRemoteAddon` consumer binds must reference a slot the consumer
+ * actually declares: a `credentialId` must be a wired credential, a `secretId`
+ * a wired secret. A custom `resolve()` and a public (omitted) surface are not
+ * statically checkable and are left to runtime.
+ */
+export function validateRemoteAddonAuth(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
+        return;
+    const credentialNames = new Set(state.credentials?.definitions.map((d) => d.name) ?? []);
+    const secretNames = new Set(state.secrets.definitions.map((d) => d.name));
+    for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+        if (!decl.remote)
+            continue;
+        if (decl.authCredentialId && !credentialNames.has(decl.authCredentialId)) {
+            logger.critical(ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED, `Remote addon '${namespace}' binds auth.credentialId '${decl.authCredentialId}', but no such credential is wired. Available credentials: ${Array.from(credentialNames).join(', ') || 'none'}`);
+        }
+        if (decl.authSecretId && !secretNames.has(decl.authSecretId)) {
+            logger.critical(ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED, `Remote addon '${namespace}' binds auth.secretId '${decl.authSecretId}', but no such secret is wired. Available secrets: ${Array.from(secretNames).join(', ') || 'none'}`);
+        }
+    }
+}
 export function computeResolvedIOTypes(state) {
     const { functions } = state;
     for (const [pikkuFuncId, meta] of Object.entries(functions.meta)) {
@@ -424,34 +481,8 @@ export function computeMiddlewareGroupsMeta(state) {
     };
 }
 export function computePermissionsGroupsMeta(state) {
-    const httpGroups = {};
-    for (const [pattern, meta] of state.http.routePermissions.entries()) {
-        httpGroups[pattern] = {
-            exportName: meta.exportName,
-            sourceFile: meta.sourceFile,
-            position: meta.position,
-            services: meta.services,
-            count: meta.count,
-            instanceIds: meta.instanceIds,
-            isFactory: meta.isFactory,
-        };
-    }
-    const tagGroups = {};
-    for (const [tag, meta] of state.permissions.tagPermissions.entries()) {
-        tagGroups[tag] = {
-            exportName: meta.exportName,
-            sourceFile: meta.sourceFile,
-            position: meta.position,
-            services: meta.services,
-            count: meta.count,
-            instanceIds: meta.instanceIds,
-            isFactory: meta.isFactory,
-        };
-    }
     state.permissionsGroupsMeta = {
         definitions: state.permissions.definitions,
-        httpGroups,
-        tagGroups,
     };
 }
 const PRIMITIVE_TYPES = new Set([
@@ -508,6 +539,34 @@ export function validateAgentModels(logger, state) {
         }
     }
 }
+/**
+ * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
+ * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never
+ * registers and codegen fails deep in type-checking with an opaque error. Fail
+ * early with an actionable message pointing at `scaffold: { graph: true }`.
+ */
+export function validateWorkflowGraphAddons(logger, state) {
+    const addonGraphWired = Array.from(state.rpc.wireAddonDeclarations.values()).some((decl) => decl.package === '@pikku/addon-graph');
+    if (addonGraphWired) {
+        return;
+    }
+    for (const [name, graph] of Object.entries(state.workflows.graphMeta)) {
+        for (const node of Object.values(graph.nodes)) {
+            if (!('rpcName' in node) || typeof node.rpcName !== 'string') {
+                continue;
+            }
+            if (!node.rpcName.startsWith('graph:')) {
+                continue;
+            }
+            if (state.functions.meta[node.rpcName]) {
+                continue;
+            }
+            logger.critical(ErrorCode.WORKFLOW_GRAPH_ADDON_NOT_WIRED, `Workflow graph '${name}' references '${node.rpcName}' but @pikku/addon-graph is not wired. ` +
+                `Enable "scaffold": { "graph": true } in pikku.config.json (and install @pikku/addon-graph), ` +
+                `or wire it manually with wireAddon({ name: 'graph', package: '@pikku/addon-graph' }).`);
+        }
+    }
+}
 /**
  * Validates that Zod schemas and wiring side-effects (wireHTTPRoutes,
  * addPermission, addHTTPMiddleware, etc.) do not coexist in the same file.
@@ -528,13 +587,6 @@ export function validateSchemaWiringSeparation(logger, state) {
     for (const file of state.http.files) {
         wiringFiles.add(file);
     }
-    // Permission wirings (addPermission calls)
-    for (const meta of state.permissions.tagPermissions.values()) {
-        wiringFiles.add(meta.sourceFile);
-    }
-    for (const meta of state.http.routePermissions.values()) {
-        wiringFiles.add(meta.sourceFile);
-    }
     // Middleware wirings (addHTTPMiddleware calls)
     for (const meta of state.http.routeMiddleware.values()) {
         wiringFiles.add(meta.sourceFile);
@@ -628,3 +680,29 @@ export function computeDiagnostics(state) {
     }
     state.diagnostics = diagnostics;
 }
+/**
+ * Validates that every scope referenced by a function is declared via
+ * `wireScope`. 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 function validateScopeReferences(logger, state) {
+    const declared = new Set(flattenScopeDefinitions(state.scopes.definitions).map((s) => s.id));
+    for (const [funcName, meta] of Object.entries(state.functions.meta)) {
+        if (!meta.scopes?.length)
+            continue;
+        for (const scope of meta.scopes) {
+            // A trailing wildcard grants a subtree; the node it hangs off must exist.
+            const declaredForm = scope.endsWith(':*') ? scope.slice(0, -2) : scope;
+            if (scope === '*') {
+                logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires the bare wildcard scope '*'. A function must require a specific scope — '*' is only meaningful as a grant.`);
+                continue;
+            }
+            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'}`);
+            }
+        }
+    }
+}

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

@@ -127,10 +127,6 @@ export interface SerializableInspectorState {
             string,
             InspectorState['http']['routeMiddleware'] extends Map<string, infer V> ? V : never
         ]>;
-        routePermissions: Array<[
-            string,
-            InspectorState['http']['routePermissions'] extends Map<string, infer V> ? V : never
-        ]>;
     };
     channels: {
         files: string[];
@@ -177,6 +173,11 @@ export interface SerializableInspectorState {
             path: string;
             exportedName: string;
         }]>;
+        remoteMeta: InspectorState['rpc']['remoteMeta'];
+        remoteFiles: Array<[string, {
+            path: string;
+            exportedName: string;
+        }]>;
         invokedFunctions: string[];
         invokedFunctionsByFile?: Array<[string, string[]]>;
         usedAddons: string[];
@@ -185,6 +186,10 @@ export interface SerializableInspectorState {
             {
                 package: string;
                 rpcEndpoint?: string;
+                remote?: boolean;
+                hasAuth?: boolean;
+                authCredentialId?: string;
+                authSecretId?: string;
                 secretOverrides?: Record<string, string>;
                 variableOverrides?: Record<string, string>;
                 credentialOverrides?: Record<string, string>;
@@ -227,6 +232,10 @@ export interface SerializableInspectorState {
         definitions: InspectorState['credentials']['definitions'];
         files: string[];
     };
+    scopes: {
+        definitions: InspectorState['scopes']['definitions'];
+        files: string[];
+    };
     variables: {
         definitions: InspectorState['variables']['definitions'];
         files: string[];
@@ -254,10 +263,6 @@ export interface SerializableInspectorState {
     permissions: {
         definitions: InspectorState['permissions']['definitions'];
         instances: InspectorState['permissions']['instances'];
-        tagPermissions: Array<[
-            string,
-            InspectorState['permissions']['tagPermissions'] extends Map<string, infer V> ? V : never
-        ]>;
     };
     serviceAggregation: {
         requiredServices: string[];

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

@@ -42,7 +42,6 @@ export function serializeInspectorState(state) {
             meta: state.http.meta,
             files: Array.from(state.http.files),
             routeMiddleware: Array.from(state.http.routeMiddleware.entries()),
-            routePermissions: Array.from(state.http.routePermissions.entries()),
         },
         channels: {
             files: Array.from(state.channels.files),
@@ -77,6 +76,8 @@ export function serializeInspectorState(state) {
             internalFiles: Array.from(state.rpc.internalFiles.entries()),
             exposedMeta: state.rpc.exposedMeta,
             exposedFiles: Array.from(state.rpc.exposedFiles.entries()),
+            remoteMeta: state.rpc.remoteMeta,
+            remoteFiles: Array.from(state.rpc.remoteFiles.entries()),
             invokedFunctions: Array.from(state.rpc.invokedFunctions),
             invokedFunctionsByFile: Array.from((state.rpc.invokedFunctionsByFile ?? new Map()).entries()).map(([file, fns]) => [file, Array.from(fns)]),
             usedAddons: Array.from(state.rpc.usedAddons),
@@ -115,6 +116,10 @@ export function serializeInspectorState(state) {
             definitions: state.credentials.definitions,
             files: Array.from(state.credentials.files),
         },
+        scopes: {
+            definitions: state.scopes.definitions,
+            files: Array.from(state.scopes.files),
+        },
         variables: {
             definitions: state.variables.definitions,
             files: Array.from(state.variables.files),
@@ -136,7 +141,6 @@ export function serializeInspectorState(state) {
         permissions: {
             definitions: state.permissions.definitions,
             instances: state.permissions.instances,
-            tagPermissions: Array.from(state.permissions.tagPermissions.entries()),
         },
         serviceAggregation: {
             requiredServices: Array.from(state.serviceAggregation.requiredServices),
@@ -201,7 +205,6 @@ export function deserializeInspectorState(data) {
             meta: data.http.meta,
             files: new Set(data.http.files),
             routeMiddleware: new Map(data.http.routeMiddleware),
-            routePermissions: new Map(data.http.routePermissions),
         },
         channels: {
             files: new Set(data.channels.files),
@@ -236,6 +239,8 @@ export function deserializeInspectorState(data) {
             internalFiles: new Map(data.rpc.internalFiles),
             exposedMeta: data.rpc.exposedMeta,
             exposedFiles: new Map(data.rpc.exposedFiles),
+            remoteMeta: data.rpc.remoteMeta ?? {},
+            remoteFiles: new Map(data.rpc.remoteFiles ?? []),
             invokedFunctions: new Set(data.rpc.invokedFunctions),
             invokedFunctionsByFile: new Map((data.rpc.invokedFunctionsByFile || []).map(([file, fns]) => [file, new Set(fns)])),
             usedAddons: new Set(data.rpc.usedAddons || []),
@@ -274,6 +279,10 @@ export function deserializeInspectorState(data) {
             definitions: data.credentials?.definitions || [],
             files: new Set(data.credentials?.files || []),
         },
+        scopes: {
+            definitions: data.scopes?.definitions || [],
+            files: new Set(data.scopes?.files || []),
+        },
         variables: {
             definitions: data.variables?.definitions || [],
             files: new Set(data.variables?.files || []),
@@ -295,7 +304,6 @@ export function deserializeInspectorState(data) {
         permissions: {
             definitions: data.permissions.definitions,
             instances: data.permissions.instances || {},
-            tagPermissions: new Map(data.permissions.tagPermissions),
         },
         serviceAggregation: {
             requiredServices: new Set(data.serviceAggregation.requiredServices),
@@ -315,8 +323,6 @@ export function deserializeInspectorState(data) {
         },
         permissionsGroupsMeta: data.permissionsGroupsMeta || {
             definitions: {},
-            httpGroups: {},
-            tagGroups: {},
         },
         requiredSchemas: new Set(data.requiredSchemas || []),
         openAPISpec: data.openAPISpec || null,

package/dist/utils/serialize-permissions-groups-meta.d.ts

@@ -1,6 +1,4 @@
 import type { InspectorState } from '../types.js';
 export declare const serializePermissionsGroupsMeta: (state: InspectorState) => {
     definitions: Record<string, import("../types.js").InspectorPermissionDefinition>;
-    httpGroups: Record<string, any>;
-    tagGroups: Record<string, any>;
 };

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

@@ -1,31 +1,5 @@
 export const serializePermissionsGroupsMeta = (state) => {
-    const httpGroups = {};
-    for (const [pattern, meta] of state.http.routePermissions.entries()) {
-        httpGroups[pattern] = {
-            exportName: meta.exportName,
-            sourceFile: meta.sourceFile,
-            position: meta.position,
-            services: meta.services,
-            count: meta.count,
-            instanceIds: meta.instanceIds,
-            isFactory: meta.isFactory,
-        };
-    }
-    const tagGroups = {};
-    for (const [tag, meta] of state.permissions.tagPermissions.entries()) {
-        tagGroups[tag] = {
-            exportName: meta.exportName,
-            sourceFile: meta.sourceFile,
-            position: meta.position,
-            services: meta.services,
-            count: meta.count,
-            instanceIds: meta.instanceIds,
-            isFactory: meta.isFactory,
-        };
-    }
     return {
         definitions: state.permissions.definitions,
-        httpGroups,
-        tagGroups,
     };
 };

package/dist/utils/workflow/derive-workflow-plan.js

@@ -48,9 +48,7 @@ function containsConditional(steps) {
  * e.g. "awaiting_approval" → "Awaiting approval", "building-image" → "Building image"
  */
 function reasonToLabel(reason) {
-    return reason
-        .replace(/[-_]/g, ' ')
-        .replace(/^(.)/, (c) => c.toUpperCase());
+    return reason.replace(/[-_]/g, ' ').replace(/^(.)/, (c) => c.toUpperCase());
 }
 /** Flatten named steps (rpc/inline/sleep/parallel children) in source order. */
 function collectNamedSteps(steps) {
@@ -72,6 +70,14 @@ function collectNamedSteps(steps) {
                     displayName: reasonToLabel(step.reason),
                 });
                 break;
+            case 'approval':
+                // Same as suspend, but namespaced `__workflow_approval:` to match the
+                // runtime's separate step key.
+                planned.push({
+                    stepName: `__workflow_approval:${step.reason}`,
+                    displayName: reasonToLabel(step.reason),
+                });
+                break;
             case 'parallel':
                 for (const child of step.children) {
                     planned.push({ stepName: child.stepName });

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
 /**
@@ -363,6 +363,19 @@ function extractExpressionStatement(statement, context) {
         if (isWorkflowSuspendCall(call, context.checker)) {
             return extractSuspendStep(call, context);
         }
+        if (isWorkflowApprovalCall(call, context.checker)) {
+            const step = extractApprovalStep(call, context, outputVar);
+            // Unlike suspend, an approval yields a value, so a downstream step can
+            // reference it — track the binding the same way workflow.do() does.
+            if (outputVar && step) {
+                const type = context.checker.getTypeAtLocation(expr);
+                context.outputVars.set(outputVar, { type, node: expr });
+                if (isArrayType(type, context.checker)) {
+                    context.arrayVars.add(outputVar);
+                }
+            }
+            return step;
+        }
         // Check for parallel group or fanout
         if (isParallelFanout(call)) {
             return extractParallelFanout(call, context);
@@ -543,6 +556,48 @@ function extractSuspendStep(call, context) {
         return null;
     }
 }
+/**
+ * Extract approval step from workflow.approval() call
+ */
+function extractApprovalStep(call, context, outputVar) {
+    const args = call.arguments;
+    if (args.length < 1)
+        return null;
+    try {
+        const reason = extractStringLiteral(args[0], context.checker);
+        const step = {
+            type: 'approval',
+            reason,
+        };
+        if (outputVar) {
+            step.outputVar = outputVar;
+        }
+        // The `schema` option is a runtime value validated inside the workflow body,
+        // so it is deliberately not serialized here — only `expiry`, which the graph
+        // and planned-step ladder need in order to describe the gate.
+        const options = args[1];
+        if (options && ts.isObjectLiteralExpression(options)) {
+            for (const prop of options.properties) {
+                if (ts.isPropertyAssignment(prop) &&
+                    prop.name.getText() === 'expiry' &&
+                    (ts.isStringLiteral(prop.initializer) ||
+                        ts.isNumericLiteral(prop.initializer))) {
+                    step.expiry = ts.isNumericLiteral(prop.initializer)
+                        ? Number(prop.initializer.text)
+                        : prop.initializer.text;
+                }
+            }
+        }
+        return step;
+    }
+    catch (error) {
+        context.errors.push({
+            message: `Failed to extract approval step: ${error instanceof Error ? error.message : String(error)}`,
+            node: call,
+        });
+        return null;
+    }
+}
 /**
  * Extract cancel step from throw WorkflowCancelledException statement
  */

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -2,6 +2,12 @@ import * as ts from 'typescript';
 /**
  * Pattern detection helpers for DSL workflow extraction
  */
+/**
+ * The wire object handed to a DSL func is named `workflow` in a workflow and
+ * `scenario` in a scenario — both carry the same `do`/`sleep`/`suspend` DSL, so
+ * step extraction accepts either identifier.
+ */
+export declare function isWorkflowWireIdentifier(expr: ts.Expression): boolean;
 /**
  * Check if a call expression is workflow.do() or workflow.expectEventually()
  * (both are RPC steps; expectEventually is the polling variant used by scenarios)
@@ -25,6 +31,10 @@ export declare function isWorkflowSleepCall(node: ts.CallExpression, checker: ts
  * Check if a call expression is workflow.suspend()
  */
 export declare function isWorkflowSuspendCall(node: ts.CallExpression, _checker: ts.TypeChecker): boolean;
+/**
+ * Check if a call expression is workflow.approval()
+ */
+export declare function isWorkflowApprovalCall(node: ts.CallExpression, _checker: ts.TypeChecker): boolean;
 /**
  * Check if a throw statement throws WorkflowCancelledException
  * Matches: throw new WorkflowCancelledException(...) or throw WorkflowCancelledException(...)