@pikku/inspector 0.11.0 → 0.11.2

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/utils/write-service-metadata.d.ts

@@ -0,0 +1,13 @@
+import { ServiceMetadata } from './extract-service-metadata.js';
+/**
+ * Write service metadata to a JSON file in .pikku/services directory
+ */
+export declare function writeServiceMetadata(serviceMeta: ServiceMetadata, outDir: string): void;
+/**
+ * Write all service metadata files
+ */
+export declare function writeAllServiceMetadata(servicesMetadata: ServiceMetadata[], outDir: string): void;
+/**
+ * Clean up services directory (remove old service JSON files)
+ */
+export declare function cleanServicesDirectory(outDir: string): void;

package/dist/utils/write-service-metadata.js

@@ -0,0 +1,37 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Write service metadata to a JSON file in .pikku/services directory
+ */
+export function writeServiceMetadata(serviceMeta, outDir) {
+    const servicesDir = path.join(outDir, 'services');
+    if (!fs.existsSync(servicesDir)) {
+        fs.mkdirSync(servicesDir, { recursive: true });
+    }
+    const fileName = `${serviceMeta.name}.gen.json`;
+    const filePath = path.join(servicesDir, fileName);
+    const jsonContent = JSON.stringify(serviceMeta, null, 2);
+    fs.writeFileSync(filePath, jsonContent, 'utf-8');
+}
+/**
+ * Write all service metadata files
+ */
+export function writeAllServiceMetadata(servicesMetadata, outDir) {
+    for (const serviceMeta of servicesMetadata) {
+        writeServiceMetadata(serviceMeta, outDir);
+    }
+}
+/**
+ * Clean up services directory (remove old service JSON files)
+ */
+export function cleanServicesDirectory(outDir) {
+    const servicesDir = path.join(outDir, 'services');
+    if (fs.existsSync(servicesDir)) {
+        const files = fs.readdirSync(servicesDir);
+        for (const file of files) {
+            if (file.endsWith('.gen.json')) {
+                fs.unlinkSync(path.join(servicesDir, file));
+            }
+        }
+    }
+}

package/dist/visit.js

@@ -14,13 +14,16 @@ 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.sessionServicesTypeImportMap, 'CoreServices', state);
+    addFileExtendsCoreType(node, checker, state.wireServicesTypeImportMap, 'CoreServices', state);
     addFileExtendsCoreType(node, checker, state.userSessionTypeImportMap, 'CoreUserSession', state);
     addFileExtendsCoreType(node, checker, state.configTypeImportMap, 'CoreConfig', state);
     addFileWithFactory(node, checker, state.singletonServicesFactories, 'CreateSingletonServices');
-    addFileWithFactory(node, checker, state.sessionServicesFactories, 'CreateSessionServices', state);
+    addFileWithFactory(node, checker, state.wireServicesFactories, 'CreateWireServices', state);
     addFileWithFactory(node, checker, state.configFactories, 'CreateConfig');
     addRPCInvocations(node, state, logger);
     addMiddleware(logger, node, checker, state, options);
@@ -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.0",
+  "version": "0.11.2",
   "author": "yasser.fadl@gmail.com",
-  "license": "MIT",
+  "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,12 +28,12 @@
     "test:coverage": "bash run-tests.sh --coverage"
   },
   "dependencies": {
-    "@pikku/core": "^0.11.0",
+    "@pikku/core": "^0.11.2",
     "path-to-regexp": "^8.3.0",
     "typescript": "^5.9"
   },
   "devDependencies": {
-    "@types/node": "^24.9.1"
+    "@types/node": "^24.10.1"
   },
   "engines": {
     "node": ">=18"

package/src/add/add-channel.ts

@@ -2,10 +2,9 @@ import * as ts from 'typescript'
 import { ErrorCode } from '../error-codes.js'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { pathToRegexp } from 'path-to-regexp'
-import { PikkuDocs } from '@pikku/core'
 import { extractFunctionName } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 import type { ChannelMessageMeta, ChannelMeta } from '@pikku/core/channel'
@@ -206,7 +205,12 @@ export function addMessagesRoutes(
                     if (fnMeta) {
                       // Resolve middleware for this route
                       const routeTags = ts.isObjectLiteralExpression(init)
-                        ? getPropertyTags(init, 'channel', channelKey, logger)
+                        ? getCommonWireMetaData(
+                            init,
+                            'Channel message',
+                            routeKey,
+                            logger
+                          ).tags
                         : undefined
                       const routeMiddleware = ts.isObjectLiteralExpression(init)
                         ? resolveMiddleware(state, init, routeTags, checker)
@@ -233,7 +237,12 @@ export function addMessagesRoutes(
                   if (fnMeta) {
                     // Resolve middleware for this route
                     const routeTags = ts.isObjectLiteralExpression(init)
-                      ? getPropertyTags(init, 'channel', channelKey, logger)
+                      ? getCommonWireMetaData(
+                          init,
+                          'Channel message',
+                          routeKey,
+                          logger
+                        ).tags
                       : undefined
                     const routeMiddleware = ts.isObjectLiteralExpression(init)
                       ? resolveMiddleware(state, init, routeTags, checker)
@@ -277,12 +286,12 @@ export function addMessagesRoutes(
                         if (fnMeta) {
                           // Resolve middleware for this route
                           const routeTags = ts.isObjectLiteralExpression(init)
-                            ? getPropertyTags(
+                            ? getCommonWireMetaData(
                                 init,
-                                'channel',
-                                channelKey,
+                                'Channel message',
+                                routeKey,
                                 logger
-                              )
+                              ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
                             init
@@ -308,12 +317,12 @@ export function addMessagesRoutes(
                         if (fnMeta) {
                           // Resolve middleware for this route
                           const routeTags = ts.isObjectLiteralExpression(init)
-                            ? getPropertyTags(
+                            ? getCommonWireMetaData(
                                 init,
-                                'channel',
-                                channelKey,
+                                'Channel message',
+                                routeKey,
                                 logger
-                              )
+                              ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
                             init
@@ -396,7 +405,12 @@ export function addMessagesRoutes(
               if (fnMeta) {
                 // Resolve middleware for this route
                 const routeTags = ts.isObjectLiteralExpression(init)
-                  ? getPropertyTags(init, 'channel', channelKey, logger)
+                  ? getCommonWireMetaData(
+                      init,
+                      'Channel message',
+                      routeKey,
+                      logger
+                    ).tags
                   : undefined
                 const routeMiddleware = ts.isObjectLiteralExpression(init)
                   ? resolveMiddleware(state, init, routeTags, checker)
@@ -438,7 +452,7 @@ export function addMessagesRoutes(
       // Resolve middleware and permissions for this route
       // Check if the route config is an object literal with middleware/permissions
       const routeTags = ts.isObjectLiteralExpression(init)
-        ? getPropertyTags(init, 'channel', channelKey, logger)
+        ? getCommonWireMetaData(init, 'Channel message', routeKey, logger).tags
         : undefined
       const routeMiddleware = ts.isObjectLiteralExpression(init)
         ? resolveMiddleware(state, init, routeTags, checker)
@@ -487,8 +501,12 @@ export const addChannel: AddWiring = (
         .map((k) => k.name)
     : []
 
-  const docs = getPropertyValue(obj, 'docs') as PikkuDocs | undefined
-  const tags = getPropertyTags(obj, 'Channel', route, logger)
+  const { tags, summary, description, errors } = getCommonWireMetaData(
+    obj,
+    'Channel',
+    name,
+    logger
+  )
   const query = getPropertyValue(obj, 'query') as string[] | []
 
   const connect = getPropertyAssignmentInitializer(
@@ -602,7 +620,9 @@ export const addChannel: AddWiring = (
       : null,
     message,
     messageWirings,
-    docs: docs ?? undefined,
+    summary,
+    description,
+    errors,
     tags: tags ?? undefined,
     middleware,
   }

package/src/add/add-file-with-factory.ts

@@ -6,7 +6,7 @@ import { extractServicesFromFunction } from '../utils/extract-services.js'
 const wrapperFunctionMap: Record<string, string> = {
   pikkuConfig: 'CreateConfig',
   pikkuServices: 'CreateSingletonServices',
-  pikkuSessionServices: 'CreateSessionServices',
+  pikkuWireServices: 'CreateWireServices',
 }
 
 export const addFileWithFactory = (
@@ -54,9 +54,9 @@ export const addFileWithFactory = (
           })
           methods.set(fileName, variables)
 
-          // Extract singleton services for CreateSessionServices factories
+          // Extract singleton services for CreateWireServices factories
           if (
-            expectedTypeName === 'CreateSessionServices' &&
+            expectedTypeName === 'CreateWireServices' &&
             state &&
             callExpression.arguments.length > 0
           ) {
@@ -74,7 +74,7 @@ export const addFileWithFactory = (
 
             if (functionNode) {
               const servicesMeta = extractServicesFromFunction(functionNode)
-              state.sessionServicesMeta.set(variableName, servicesMeta.services)
+              state.wireServicesMeta.set(variableName, servicesMeta.services)
             }
           }
 
@@ -109,9 +109,9 @@ export const addFileWithFactory = (
         })
         methods.set(fileName, variables)
 
-        // Extract singleton services for CreateSessionServices factories
+        // Extract singleton services for CreateWireServices factories
         if (
-          expectedTypeName === 'CreateSessionServices' &&
+          expectedTypeName === 'CreateWireServices' &&
           state &&
           node.initializer
         ) {
@@ -124,7 +124,7 @@ export const addFileWithFactory = (
 
           if (functionNode) {
             const servicesMeta = extractServicesFromFunction(functionNode)
-            state.sessionServicesMeta.set(variableName, servicesMeta.services)
+            state.wireServicesMeta.set(variableName, servicesMeta.services)
           }
         }
       }
@@ -149,9 +149,9 @@ export const addFileWithFactory = (
           })
           methods.set(fileName, variables)
 
-          // Extract singleton services for CreateSessionServices factories
+          // Extract singleton services for CreateWireServices factories
           if (
-            expectedTypeName === 'CreateSessionServices' &&
+            expectedTypeName === 'CreateWireServices' &&
             state &&
             node.initializer
           ) {
@@ -167,7 +167,7 @@ export const addFileWithFactory = (
 
             if (functionNode) {
               const servicesMeta = extractServicesFromFunction(functionNode)
-              state.sessionServicesMeta.set(variableName, servicesMeta.services)
+              state.wireServicesMeta.set(variableName, servicesMeta.services)
             }
           }
         }