@pikku/inspector 0.11.1 → 0.11.2

package/dist/utils/workflow/graph/serialize-workflow-graph.js

@@ -0,0 +1,152 @@
+/**
+ * Convert a RefValue (from runtime) to DataRef (serialized)
+ */
+function convertRef(ref) {
+    return {
+        $ref: ref.nodeId,
+        path: ref.path,
+    };
+}
+/**
+ * Check if a value is a runtime RefValue
+ */
+function isRefValue(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__isRef' in value &&
+        value.__isRef === true);
+}
+/**
+ * Convert input mapping from runtime format to serialized format
+ */
+function serializeInputMapping(input) {
+    const result = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (isRefValue(value)) {
+            result[key] = convertRef(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Convert next config from runtime format to serialized format
+ * Runtime uses Record<string, string | string[]> for branching with graph.branch()
+ * Serialized uses { conditions: [...], default: ... } for UI-friendly branching
+ */
+function serializeNext(next) {
+    if (!next)
+        return undefined;
+    if (typeof next === 'string')
+        return next;
+    if (Array.isArray(next))
+        return next;
+    // Record format - convert to conditions format
+    // For now, treat keys as branch identifiers (from graph.branch())
+    // UI can display these as condition labels
+    const conditions = Object.entries(next).map(([key, target]) => ({
+        expression: key, // The branch key becomes the expression
+        target,
+    }));
+    return { conditions };
+}
+/**
+ * Serialize a workflow graph definition (from runtime) to JSON format
+ *
+ * @param definition - The runtime definition (with callbacks evaluated)
+ * @param rpcNameLookup - Function to get RPC name from a node's func
+ */
+export function serializeWorkflowGraph(definition, options) {
+    const nodes = {};
+    const entryNodeIds = [];
+    // Create a ref function that captures refs
+    const createRef = (nodeId, path) => ({
+        __isRef: true,
+        nodeId,
+        path,
+    });
+    // Track which nodes have incoming edges
+    const hasIncomingEdge = new Set();
+    // First pass: identify nodes with incoming edges
+    for (const [_nodeId, node] of Object.entries(definition.graph)) {
+        const next = node.next;
+        if (!next)
+            continue;
+        if (typeof next === 'string') {
+            hasIncomingEdge.add(next);
+        }
+        else if (Array.isArray(next)) {
+            next.forEach((n) => hasIncomingEdge.add(n));
+        }
+        else {
+            for (const targets of Object.values(next)) {
+                if (typeof targets === 'string') {
+                    hasIncomingEdge.add(targets);
+                }
+                else {
+                    targets.forEach((n) => hasIncomingEdge.add(n));
+                }
+            }
+        }
+    }
+    // Second pass: serialize nodes
+    for (const [nodeId, node] of Object.entries(definition.graph)) {
+        // Evaluate input callback to get the mapping
+        let input = {};
+        if (node.input) {
+            const rawInput = node.input(createRef);
+            input = serializeInputMapping(rawInput);
+        }
+        // Get RPC name from func
+        const rpcName = node.func?.name || 'unknown';
+        const funcNode = {
+            nodeId,
+            rpcName,
+            input,
+            next: serializeNext(node.next),
+            onError: node.onError,
+        };
+        nodes[nodeId] = funcNode;
+        // Entry nodes have no incoming edges
+        if (!hasIncomingEdge.has(nodeId)) {
+            entryNodeIds.push(nodeId);
+        }
+    }
+    return {
+        name: definition.name,
+        pikkuFuncName: definition.name, // For graph workflows, pikkuFuncName is the workflow name
+        source: 'graph',
+        description: options?.description,
+        tags: options?.tags,
+        wires: definition.wires,
+        nodes,
+        entryNodeIds,
+    };
+}
+/**
+ * Deserialize a workflow graph from JSON to runtime format
+ * This re-hydrates the JSON so it can be executed
+ */
+export function deserializeWorkflowGraph(serialized) {
+    const graph = {};
+    for (const [nodeId, node] of Object.entries(serialized.nodes)) {
+        // Only include FunctionNode properties (nodes with rpcName)
+        if ('rpcName' in node) {
+            const funcNode = node;
+            graph[nodeId] = {
+                rpcName: funcNode.rpcName,
+                input: funcNode.input ?? {},
+                next: funcNode.next,
+                onError: funcNode.onError,
+            };
+        }
+    }
+    return {
+        name: serialized.name,
+        wires: serialized.wires,
+        graph,
+        entryNodeIds: serialized.entryNodeIds,
+    };
+}

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Serialized types for workflow graphs
+ * These are extracted by the inspector and stored as JSON
+ * Can be created from code (wireWorkflow) or UI
+ */
+/**
+ * Reference to data from another node or trigger
+ */
+export interface DataRef {
+    /** Source: 'trigger' for trigger input, or node ID for node output */
+    $ref: string;
+    /** Optional path into the data (dot notation: 'body.orderId') */
+    path?: string;
+}
+/**
+ * Check if value is a DataRef
+ */
+export declare const isDataRef: (value: unknown) => value is DataRef;
+/**
+ * Reference to a context/state variable
+ */
+export interface StateRef {
+    /** Context variable name */
+    $state: string;
+    /** Optional path into the value (dot notation for nested objects) */
+    path?: string;
+}
+/**
+ * Check if value is a StateRef
+ */
+export declare const isStateRef: (value: unknown) => value is StateRef;
+/**
+ * Helper functions for building input mappings
+ */
+export declare const ref: (nodeId: string, path?: string) => DataRef;
+export declare const state: (name: string, path?: string) => StateRef;
+/**
+ * Condition for branching
+ */
+export interface BranchCondition {
+    /** Expression to evaluate (uses node output references) */
+    expression: string;
+    /** Target node(s) if condition is true */
+    target: string | string[];
+}
+/**
+ * Next node configuration
+ */
+export type SerializedNext = string | string[] | {
+    /** Conditions evaluated in order, first match wins */
+    conditions: BranchCondition[];
+    /** Default target if no conditions match */
+    default?: string | string[];
+};
+/**
+ * Node execution options
+ */
+export interface NodeOptions {
+    /** Number of retry attempts on failure */
+    retries?: number;
+    /** Delay between retries (e.g., '1s', '5s') */
+    retryDelay?: string;
+    /** Timeout for node execution (e.g., '30s', '5m') */
+    timeout?: string;
+    /** If true, execute via queue (async). Default: false (inline) */
+    async?: boolean;
+}
+/**
+ * Flow node types for control flow (no RPC call)
+ */
+export type FlowType = 'sleep' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
+import type { ContextVariable, WorkflowContext } from '@pikku/core/workflow';
+export type { ContextVariable, WorkflowContext };
+/**
+ * Base node properties shared by all node types
+ */
+interface BaseNode {
+    /** Node ID */
+    nodeId: string;
+    /** Step name/description */
+    stepName?: string;
+    /** Next node(s) - simple, parallel, or conditional */
+    next?: SerializedNext;
+    /** Error routing - node(s) to execute on error */
+    onError?: string | string[];
+    /** Execution options */
+    options?: NodeOptions;
+}
+/**
+ * Function node - calls an RPC
+ */
+export interface FunctionNode extends BaseNode {
+    /** RPC function name */
+    rpcName: string;
+    /** Input mapping - values can be literals or DataRefs */
+    input?: Record<string, unknown | DataRef>;
+    /** Output variable name for storing result */
+    outputVar?: string;
+}
+/**
+ * Flow node - control flow only, no RPC call
+ */
+export interface FlowNode extends BaseNode {
+    /** Flow type */
+    flow: FlowType;
+    /** Flow-specific properties */
+    [key: string]: unknown;
+}
+/**
+ * Serialized graph node - either a function node or flow node
+ */
+export type SerializedGraphNode = FunctionNode | FlowNode;
+/**
+ * Type guard for function nodes
+ */
+export declare const isFunctionNode: (node: SerializedGraphNode) => node is FunctionNode;
+/**
+ * Type guard for flow nodes
+ */
+export declare const isFlowNode: (node: SerializedGraphNode) => node is FlowNode;
+/**
+ * HTTP wire configuration with startNode
+ */
+export interface HttpWire {
+    route: string;
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    startNode: string;
+}
+/**
+ * Channel wire configuration
+ */
+export interface ChannelWire {
+    name: string;
+    onConnect?: string;
+    onDisconnect?: string;
+    onMessage?: string;
+}
+/**
+ * Queue wire configuration
+ */
+export interface QueueWire {
+    name: string;
+    startNode: string;
+}
+/**
+ * CLI wire configuration
+ */
+export interface CliWire {
+    command: string;
+    startNode: string;
+}
+/**
+ * MCP wire configurations
+ */
+export interface McpWires {
+    tool?: Array<{
+        name: string;
+        startNode: string;
+    }>;
+    prompt?: Array<{
+        name: string;
+        startNode: string;
+    }>;
+    resource?: Array<{
+        uri: string;
+        startNode: string;
+    }>;
+}
+/**
+ * Schedule wire configuration
+ */
+export interface ScheduleWire {
+    cron?: string;
+    interval?: string;
+    startNode: string;
+}
+/**
+ * Trigger wire configuration
+ */
+export interface TriggerWire {
+    name: string;
+    startNode: string;
+}
+/**
+ * All wire configurations for workflows
+ */
+export interface WorkflowWiresConfig {
+    http?: HttpWire[];
+    channel?: ChannelWire[];
+    queue?: QueueWire[];
+    cli?: CliWire[];
+    mcp?: McpWires;
+    schedule?: ScheduleWire[];
+    trigger?: TriggerWire[];
+}
+/**
+ * Workflow source type
+ * - 'dsl': Pure DSL workflow (pikkuWorkflowFunc) - can be round-tripped to code
+ * - 'complex': Complex workflow (pikkuWorkflowComplexFunc) - contains inline steps, not serializable
+ * - 'graph': Graph-based workflow (pikkuWorkflowGraph)
+ */
+export type WorkflowSourceType = 'dsl' | 'complex' | 'graph';
+/**
+ * Serialized workflow graph - the canonical JSON format
+ */
+export interface SerializedWorkflowGraph {
+    /** Workflow name */
+    name: string;
+    /** Pikku function name (for runtime registration) */
+    pikkuFuncName: string;
+    /** Source type: 'dsl' for pikkuWorkflowFunc, 'graph' for pikkuWorkflowGraph */
+    source: WorkflowSourceType;
+    /** Optional description */
+    description?: string;
+    /** Tags for organization */
+    tags?: string[];
+    /** Workflow context/state variables (from Zod schema) */
+    context?: WorkflowContext;
+    /** Wires - how the workflow is triggered */
+    wires: WorkflowWiresConfig;
+    /** Serialized nodes */
+    nodes: Record<string, SerializedGraphNode>;
+    /** Entry node(s) - first nodes to execute */
+    entryNodeIds: string[];
+}
+/**
+ * All workflow graphs (serialized)
+ */
+export type SerializedWorkflowGraphs = Record<string, SerializedWorkflowGraph>;

package/dist/utils/workflow/graph/workflow-graph.types.js

@@ -0,0 +1,38 @@
+/**
+ * Serialized types for workflow graphs
+ * These are extracted by the inspector and stored as JSON
+ * Can be created from code (wireWorkflow) or UI
+ */
+/**
+ * Check if value is a DataRef
+ */
+export const isDataRef = (value) => typeof value === 'object' &&
+    value !== null &&
+    '$ref' in value &&
+    typeof value.$ref === 'string';
+/**
+ * Check if value is a StateRef
+ */
+export const isStateRef = (value) => typeof value === 'object' &&
+    value !== null &&
+    '$state' in value &&
+    typeof value.$state === 'string';
+/**
+ * Helper functions for building input mappings
+ */
+export const ref = (nodeId, path) => ({
+    $ref: nodeId,
+    path,
+});
+export const state = (name, path) => ({
+    $state: name,
+    path,
+});
+/**
+ * Type guard for function nodes
+ */
+export const isFunctionNode = (node) => 'rpcName' in node;
+/**
+ * Type guard for flow nodes
+ */
+export const isFlowNode = (node) => 'flow' in node;

package/dist/visit.js

@@ -14,6 +14,9 @@ import { addRPCInvocations } from './add/add-rpc-invocations.js';
 import { addMiddleware } from './add/add-middleware.js';
 import { addPermission } from './add/add-permission.js';
 import { addCLI, addCLIRenderers } from './add/add-cli.js';
+import { addForgeNode } from './add/add-forge-node.js';
+import { addForgeCredential } from './add/add-forge-credential.js';
+import { addWorkflowGraph } from './add/add-workflow-graph.js';
 export const visitSetup = (logger, checker, node, state, options) => {
     addFileExtendsCoreType(node, checker, state.singletonServicesTypeImportMap, 'CoreSingletonServices', state);
     addFileExtendsCoreType(node, checker, state.wireServicesTypeImportMap, 'CoreServices', state);
@@ -39,5 +42,8 @@ export const visitRoutes = (logger, checker, node, state, options) => {
     addMCPResource(logger, node, checker, state, options);
     addMCPTool(logger, node, checker, state, options);
     addMCPPrompt(logger, node, checker, state, options);
+    addForgeNode(logger, node, checker, state, options);
+    addForgeCredential(logger, node, checker, state, options);
+    addWorkflowGraph(logger, node, checker, state, options);
     ts.forEachChild(node, (child) => visitRoutes(logger, checker, child, state, options));
 };

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
   "module": "dist/index.js",
   "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./workflow-graph": {
+      "types": "./dist/utils/workflow/graph/index.d.ts",
+      "import": "./dist/utils/workflow/graph/index.js",
+      "default": "./dist/utils/workflow/graph/index.js"
+    }
+  },
   "scripts": {
     "tsc": "tsc",
     "build": "tsc -b",
@@ -16,7 +28,7 @@
     "test:coverage": "bash run-tests.sh --coverage"
   },
   "dependencies": {
-    "@pikku/core": "^0.11.1",
+    "@pikku/core": "^0.11.2",
     "path-to-regexp": "^8.3.0",
     "typescript": "^5.9"
   },

package/src/add/add-forge-credential.ts

@@ -0,0 +1,119 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from '../utils/get-property-value.js'
+import { AddWiring } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+/**
+ * Inspector for wireForgeCredential calls.
+ * Extracts metadata for Forge package credential declarations.
+ * Note: wireForgeCredential is metadata-only - no runtime behavior.
+ * Schema is stored as the variable name reference; actual Zod→JSON Schema conversion happens at CLI build time.
+ */
+export const addForgeCredential: AddWiring = (
+  logger,
+  node,
+  _checker,
+  state,
+  _options
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to wireForgeCredential
+  if (
+    !ts.isIdentifier(expression) ||
+    expression.text !== 'wireForgeCredential'
+  ) {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const nameValue = getPropertyValue(obj, 'name') as string | null
+    const displayNameValue = getPropertyValue(obj, 'displayName') as
+      | string
+      | null
+    const descriptionValue = getPropertyValue(obj, 'description') as
+      | string
+      | null
+    const secretIdValue = getPropertyValue(obj, 'secretId') as string | null
+
+    // Get schema variable name for later runtime import
+    let schemaVariableName: string | null = null
+    for (const prop of obj.properties) {
+      if (
+        ts.isPropertyAssignment(prop) &&
+        ts.isIdentifier(prop.name) &&
+        prop.name.text === 'schema'
+      ) {
+        if (ts.isIdentifier(prop.initializer)) {
+          schemaVariableName = prop.initializer.text
+        }
+        break
+      }
+    }
+
+    // Validate required fields
+    if (!nameValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        "Forge credential is missing the required 'name' property."
+      )
+      return
+    }
+
+    if (!displayNameValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge credential '${nameValue}' is missing the required 'displayName' property.`
+      )
+      return
+    }
+
+    if (!secretIdValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge credential '${nameValue}' is missing the required 'secretId' property.`
+      )
+      return
+    }
+
+    if (!schemaVariableName) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge credential '${nameValue}' is missing the required 'schema' property or schema is not a variable reference.`
+      )
+      return
+    }
+
+    const sourceFile = node.getSourceFile().fileName
+
+    state.forgeCredentials.files.add(sourceFile)
+
+    // Register the zod schema in the central zodLookup for deferred conversion
+    const schemaLookupName = `ForgeCredential_${nameValue}`
+    state.zodLookup.set(schemaLookupName, {
+      variableName: schemaVariableName,
+      sourceFile,
+    })
+
+    // Store metadata - schema conversion happens later in schema-generator
+    state.forgeCredentials.meta[nameValue] = {
+      name: nameValue,
+      displayName: displayNameValue,
+      description: descriptionValue || undefined,
+      secretId: secretIdValue,
+      schema: schemaLookupName,
+    }
+  }
+}