@pikku/inspector 0.10.2 → 0.11.1

package/dist/add/add-workflow.js

@@ -0,0 +1,178 @@
+import * as ts from 'typescript';
+import { extractFunctionName } from '../utils/extract-function-name.js';
+import { extractFunctionNode } from '../utils/extract-function-node.js';
+import { ErrorCode } from '../error-codes.js';
+import { extractStringLiteral, isStringLike, isFunctionLike, extractDescription, extractDuration, } from '../utils/extract-node-value.js';
+import { extractSimpleWorkflow } from '../workflow/extract-simple-workflow.js';
+import { getCommonWireMetaData } from '../utils/get-property-value.js';
+/**
+ * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
+ */
+function getWorkflowInvocations(node, checker, state, workflowName, steps) {
+    // Look for property access expressions: workflow.do or workflow.sleep
+    if (ts.isPropertyAccessExpression(node)) {
+        const { name } = node;
+        // Check if this is accessing 'do' or 'sleep' property
+        if (name.text === 'do' || name.text === 'sleep' || name.text === 'cancel') {
+            // Check if the parent is a call expression
+            const parent = node.parent;
+            if (ts.isCallExpression(parent) && parent.expression === node) {
+                const args = parent.arguments;
+                if (name.text === 'do' && args.length >= 2) {
+                    // workflow.do(stepName, rpcName|fn, data?, options?)
+                    const stepNameArg = args[0];
+                    const secondArg = args[1];
+                    const optionsArg = args.length >= 3 ? args[args.length - 1] : undefined;
+                    const stepName = extractStringLiteral(stepNameArg, checker);
+                    const description = extractDescription(optionsArg, checker) ?? undefined;
+                    // Determine form by checking 2nd argument type
+                    if (isStringLike(secondArg, checker)) {
+                        // RPC form: workflow.do(stepName, rpcName, data, options?)
+                        const rpcName = extractStringLiteral(secondArg, checker);
+                        steps.push({
+                            type: 'rpc',
+                            stepName,
+                            rpcName,
+                        });
+                        state.rpc.invokedFunctions.add(rpcName);
+                    }
+                    else if (isFunctionLike(secondArg)) {
+                        // Inline form: workflow.do(stepName, fn, options?)
+                        steps.push({
+                            type: 'inline',
+                            stepName: stepName || '<dynamic>',
+                            description: description || '<dynamic>',
+                        });
+                    }
+                }
+                else if (name.text === 'sleep' && args.length >= 2) {
+                    // workflow.sleep(stepName, duration)
+                    const stepNameArg = args[0];
+                    const durationArg = args[1];
+                    const stepName = extractStringLiteral(stepNameArg, checker);
+                    const duration = extractDuration(durationArg, checker);
+                    steps.push({
+                        type: 'sleep',
+                        stepName: stepName || '<dynamic>',
+                        duration: duration || '<dynamic>',
+                    });
+                }
+                else if (name.text === 'cancel') {
+                    // workflow.cancel(reason?)
+                    steps.push({
+                        type: 'cancel',
+                    });
+                }
+            }
+        }
+    }
+    // Don't recurse into nested functions - only look at top-level workflow calls
+    ts.forEachChild(node, (child) => {
+        if (ts.isFunctionDeclaration(child) ||
+            ts.isFunctionExpression(child) ||
+            ts.isArrowFunction(child)) {
+            return;
+        }
+        getWorkflowInvocations(child, checker, state, workflowName, steps);
+    });
+}
+/**
+ * Inspector for pikkuWorkflow() and pikkuSimpleWorkflow() calls
+ * Detects workflow registration and extracts metadata
+ */
+export const addWorkflow = (logger, node, checker, state) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const args = node.arguments;
+    const firstArg = args[0];
+    const expression = node.expression;
+    if (!ts.isIdentifier(expression)) {
+        return;
+    }
+    let wrapperType = null;
+    if (expression.text === 'pikkuWorkflowFunc') {
+        wrapperType = 'regular';
+    }
+    else if (expression.text === 'pikkuSimpleWorkflowFunc') {
+        wrapperType = 'simple';
+    }
+    else {
+        return;
+    }
+    if (!firstArg) {
+        return;
+    }
+    // Extract workflow name and metadata using same logic as add-functions
+    const { pikkuFuncName, name, exportedName } = extractFunctionName(node, checker, state.rootDir);
+    const workflowName = exportedName || name;
+    if (!workflowName) {
+        logger.critical(ErrorCode.MISSING_NAME, `Could not determine workflow name from export.`);
+        return;
+    }
+    // Extract the function node (either direct function or from config.func)
+    const { funcNode, resolvedFunc } = extractFunctionNode(firstArg, checker);
+    // Extract metadata if using object form
+    let tags;
+    let summary;
+    let description;
+    let errors;
+    if (ts.isObjectLiteralExpression(firstArg)) {
+        const metadata = getCommonWireMetaData(firstArg, 'Workflow', workflowName, logger);
+        tags = metadata.tags;
+        summary = metadata.summary;
+        description = metadata.description;
+        errors = metadata.errors;
+    }
+    // Validate that we got a valid function
+    if (ts.isObjectLiteralExpression(firstArg) &&
+        (!funcNode || funcNode === firstArg)) {
+        logger.critical(ErrorCode.MISSING_FUNC, `No valid 'func' property for workflow '${workflowName}'.`);
+        return;
+    }
+    if (!resolvedFunc) {
+        logger.critical(ErrorCode.MISSING_FUNC, `Could not resolve workflow function for '${workflowName}'.`);
+        return;
+    }
+    // Track workflow file for wiring generation
+    if (exportedName) {
+        state.workflows.files.set(pikkuFuncName, {
+            path: node.getSourceFile().fileName,
+            exportedName,
+        });
+    }
+    let steps = [];
+    let simple = undefined;
+    // Try simple workflow extraction first
+    // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
+    const result = extractSimpleWorkflow(node, checker);
+    if (result.status === 'ok' && result.steps) {
+        // Simple extraction succeeded
+        steps = result.steps;
+        simple = true;
+    }
+    else {
+        // Simple extraction failed
+        if (wrapperType === 'simple') {
+            // For pikkuSimpleWorkflowFunc, this is a critical error
+            logger.critical(ErrorCode.INVALID_SIMPLE_WORKFLOW, `Workflow '${workflowName}' uses pikkuSimpleWorkflowFunc but does not conform to simple workflow DSL:\n${result.reason || 'Unknown error'}`);
+            return;
+        }
+        else {
+            // For pikkuWorkflowFunc, fall back to basic extraction
+            logger.debug(`Workflow '${workflowName}' could not be extracted as simple workflow: ${result.reason || 'Unknown error'}. Falling back to basic extraction.`);
+            simple = false;
+        }
+    }
+    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps);
+    state.workflows.meta[workflowName] = {
+        pikkuFuncName,
+        workflowName,
+        steps,
+        simple,
+        summary,
+        description,
+        errors,
+        tags,
+    };
+};

package/dist/error-codes.d.ts

@@ -17,6 +17,9 @@ export declare enum ErrorCode {
     MISSING_QUEUE_NAME = "PKU384",
     MISSING_CHANNEL_NAME = "PKU400",
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
+    DYNAMIC_STEP_NAME = "PKU529",
+    WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
+    INVALID_SIMPLE_WORKFLOW = "PKU641",
     CONFIG_TYPE_NOT_FOUND = "PKU426",
     CONFIG_TYPE_UNDEFINED = "PKU427",
     SCHEMA_NO_ROOT = "PKU431",
@@ -31,5 +34,6 @@ export declare enum ErrorCode {
     PERMISSION_HANDLER_INVALID = "PKU835",
     PERMISSION_TAG_INVALID = "PKU836",
     PERMISSION_EMPTY_ARRAY = "PKU937",
-    PERMISSION_PATTERN_INVALID = "PKU975"
+    PERMISSION_PATTERN_INVALID = "PKU975",
+    WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = "PKU901"
 }

package/dist/error-codes.js

@@ -19,6 +19,9 @@ export var ErrorCode;
     ErrorCode["MISSING_QUEUE_NAME"] = "PKU384";
     ErrorCode["MISSING_CHANNEL_NAME"] = "PKU400";
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
+    ErrorCode["DYNAMIC_STEP_NAME"] = "PKU529";
+    ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
+    ErrorCode["INVALID_SIMPLE_WORKFLOW"] = "PKU641";
     // Configuration errors
     ErrorCode["CONFIG_TYPE_NOT_FOUND"] = "PKU426";
     ErrorCode["CONFIG_TYPE_UNDEFINED"] = "PKU427";
@@ -37,4 +40,6 @@ export var ErrorCode;
     ErrorCode["PERMISSION_TAG_INVALID"] = "PKU836";
     ErrorCode["PERMISSION_EMPTY_ARRAY"] = "PKU937";
     ErrorCode["PERMISSION_PATTERN_INVALID"] = "PKU975";
+    // Feature Flag
+    ErrorCode["WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED"] = "PKU901";
 })(ErrorCode || (ErrorCode = {}));

package/dist/index.d.ts

@@ -8,3 +8,5 @@ export { ErrorCode } from './error-codes.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
+export { writeAllServiceMetadata } from './utils/write-service-metadata.js';
+export type { ServiceMetadata } from './utils/extract-service-metadata.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
+export { writeAllServiceMetadata } from './utils/write-service-metadata.js';

package/dist/inspector.js

@@ -4,7 +4,7 @@ import { visitSetup, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
-import { aggregateRequiredServices } from './utils/post-process.js';
+import { aggregateRequiredServices, extractServiceInterfaceMetadata, } from './utils/post-process.js';
 /**
  * Creates an initial/empty inspector state with all required properties initialized
  * @param rootDir - The root directory for the project
@@ -14,12 +14,12 @@ export function getInitialInspectorState(rootDir) {
     return {
         rootDir,
         singletonServicesTypeImportMap: new Map(),
-        sessionServicesTypeImportMap: new Map(),
+        wireServicesTypeImportMap: new Map(),
         userSessionTypeImportMap: new Map(),
         configTypeImportMap: new Map(),
         singletonServicesFactories: new Map(),
-        sessionServicesFactories: new Map(),
-        sessionServicesMeta: new Map(),
+        wireServicesFactories: new Map(),
+        wireServicesMeta: new Map(),
         configFactories: new Map(),
         filesAndMethods: {},
         filesAndMethodsErrors: new Map(),
@@ -56,6 +56,10 @@ export function getInitialInspectorState(rootDir) {
             meta: {},
             files: new Set(),
         },
+        workflows: {
+            meta: {},
+            files: new Map(),
+        },
         rpc: {
             internalMeta: {},
             internalFiles: new Map(),
@@ -90,8 +94,9 @@ export function getInitialInspectorState(rootDir) {
             usedMiddleware: new Set(),
             usedPermissions: new Set(),
             allSingletonServices: [],
-            allSessionServices: [],
+            allWireServices: [],
         },
+        serviceMetadata: [],
     };
 }
 export const inspect = (logger, routeFiles, options = {}) => {
@@ -140,6 +145,9 @@ export const inspect = (logger, routeFiles, options = {}) => {
         const startAggregate = performance.now();
         aggregateRequiredServices(state);
         logger.debug(`Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`);
+        const startServiceMeta = performance.now();
+        extractServiceInterfaceMetadata(state, checker);
+        logger.debug(`Extract service metadata completed in ${(performance.now() - startServiceMeta).toFixed(2)}ms`);
     }
     return state;
 };

package/dist/types.d.ts

@@ -2,7 +2,8 @@ import * as ts from 'typescript';
 import { ChannelsMeta } from '@pikku/core/channel';
 import { HTTPWiringsMeta } from '@pikku/core/http';
 import { ScheduledTasksMeta } from '@pikku/core/scheduler';
-import { queueWorkersMeta } from '@pikku/core/queue';
+import { QueueWorkersMeta } from '@pikku/core/queue';
+import { WorkflowsMeta } from '@pikku/core/workflow';
 import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp';
 import { CLIMeta } from '@pikku/core/cli';
 import { TypesMap } from './types-map.js';
@@ -91,7 +92,7 @@ export type InspectorOptions = Partial<{
         configFileType: string;
         userSessionType: string;
         singletonServicesFactoryType: string;
-        sessionServicesFactoryType: string;
+        wireServicesFactoryType: string;
     }>;
 }>;
 export interface InspectorLogger {
@@ -110,7 +111,7 @@ export interface InspectorFilesAndMethods {
         type: string;
         typePath: string;
     };
-    sessionServicesType?: {
+    wireServicesType?: {
         file: string;
         variable: string;
         type: string;
@@ -140,7 +141,7 @@ export interface InspectorFilesAndMethods {
         type: string;
         typePath: string;
     };
-    sessionServicesFactory?: {
+    wireServicesFactory?: {
         file: string;
         variable: string;
         type: string;
@@ -150,12 +151,12 @@ export interface InspectorFilesAndMethods {
 export interface InspectorState {
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
-    sessionServicesTypeImportMap: PathToNameAndType;
+    wireServicesTypeImportMap: PathToNameAndType;
     userSessionTypeImportMap: PathToNameAndType;
     configTypeImportMap: PathToNameAndType;
     singletonServicesFactories: PathToNameAndType;
-    sessionServicesFactories: PathToNameAndType;
-    sessionServicesMeta: Map<string, string[]>;
+    wireServicesFactories: PathToNameAndType;
+    wireServicesMeta: Map<string, string[]>;
     configFactories: PathToNameAndType;
     filesAndMethods: InspectorFilesAndMethods;
     filesAndMethodsErrors: Map<string, PathToNameAndType>;
@@ -168,9 +169,16 @@ export interface InspectorState {
         files: Set<string>;
     };
     queueWorkers: {
-        meta: queueWorkersMeta;
+        meta: QueueWorkersMeta;
         files: Set<string>;
     };
+    workflows: {
+        meta: WorkflowsMeta;
+        files: Map<string, {
+            path: string;
+            exportedName: string;
+        }>;
+    };
     rpc: {
         internalMeta: Record<string, string>;
         internalFiles: Map<string, {
@@ -202,6 +210,16 @@ export interface InspectorState {
         usedMiddleware: Set<string>;
         usedPermissions: Set<string>;
         allSingletonServices: string[];
-        allSessionServices: string[];
+        allWireServices: string[];
     };
+    serviceMetadata: Array<{
+        name: string;
+        summary: string;
+        description: string;
+        package: string;
+        path: string;
+        version: string;
+        interface: string;
+        expandedProperties: Record<string, string>;
+    }>;
 }

package/dist/utils/extract-function-node.d.ts

@@ -0,0 +1,10 @@
+import * as ts from 'typescript';
+/**
+ * Extracts the actual function node from a pikkuFunc/pikkuWorkflowFunc call
+ * Handles both direct function form and config object form { func: ... }
+ */
+export declare function extractFunctionNode(firstArg: ts.Expression, checker: ts.TypeChecker): {
+    funcNode: ts.Node;
+    resolvedFunc: ts.Node | null;
+    isDirectFunction: boolean;
+};

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

@@ -0,0 +1,38 @@
+import * as ts from 'typescript';
+import { getPropertyAssignmentInitializer, resolveFunctionDeclaration, } from './type-utils.js';
+/**
+ * Extracts the actual function node from a pikkuFunc/pikkuWorkflowFunc call
+ * Handles both direct function form and config object form { func: ... }
+ */
+export function extractFunctionNode(firstArg, checker) {
+    let funcNode = firstArg;
+    let isDirectFunction = true;
+    // Check if first argument is a config object with 'func' property
+    if (ts.isObjectLiteralExpression(firstArg)) {
+        isDirectFunction = false;
+        const funcInitializer = getPropertyAssignmentInitializer(firstArg, 'func', true, checker);
+        if (funcInitializer) {
+            funcNode = funcInitializer;
+        }
+        else {
+            // Return the original node if no func property found
+            // Caller should handle validation
+            funcNode = firstArg;
+        }
+    }
+    // Resolve identifier to get the actual function node
+    if (ts.isIdentifier(funcNode)) {
+        const symbol = checker.getSymbolAtLocation(funcNode);
+        const decl = symbol?.valueDeclaration || symbol?.declarations?.[0];
+        if (decl && ts.isVariableDeclaration(decl) && decl.initializer) {
+            funcNode = decl.initializer;
+        }
+    }
+    // Resolve function declaration for deeper analysis
+    const resolvedFunc = resolveFunctionDeclaration(funcNode, checker);
+    return {
+        funcNode,
+        resolvedFunc,
+        isDirectFunction,
+    };
+}

package/dist/utils/extract-node-value.d.ts

@@ -0,0 +1,32 @@
+import * as ts from 'typescript';
+/**
+ * Extract string literal value from a TypeScript node.
+ * Handles string literals, template literals (including placeholders),
+ * and constant variable references.
+ */
+export declare function extractStringLiteral(node: ts.Node, checker: ts.TypeChecker): string;
+/**
+ * Check if node is string-like (string literal or template expression)
+ */
+export declare function isStringLike(node: ts.Node, _checker: ts.TypeChecker): boolean;
+/**
+ * Check if node is function-like (arrow, function expression, or function declaration)
+ */
+export declare function isFunctionLike(node: ts.Node): boolean;
+/**
+ * Extract number literal value from a node
+ */
+export declare function extractNumberLiteral(node: ts.Node): number | null;
+/**
+ * Extract a property value from an object literal expression
+ * Returns the extracted value or null if not found/cannot extract
+ */
+export declare function extractPropertyString(objNode: ts.ObjectLiteralExpression, propertyName: string, checker: ts.TypeChecker): string | null;
+/**
+ * Extract description from options object
+ */
+export declare function extractDescription(optionsNode: ts.Node | undefined, checker: ts.TypeChecker): string | null;
+/**
+ * Extract duration value (number or string)
+ */
+export declare function extractDuration(node: ts.Node, checker: ts.TypeChecker): string | number | null;

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

@@ -0,0 +1,103 @@
+import * as ts from 'typescript';
+/**
+ * Extract string literal value from a TypeScript node.
+ * Handles string literals, template literals (including placeholders),
+ * and constant variable references.
+ */
+export function extractStringLiteral(node, checker) {
+    if (ts.isStringLiteral(node)) {
+        return node.text;
+    }
+    if (ts.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    if (ts.isTemplateExpression(node)) {
+        // reconstruct: `head + ${expr} + middle + ${expr} + tail`
+        let result = node.head.text;
+        for (const span of node.templateSpans) {
+            const exprText = span.expression.getText();
+            result += '${' + exprText + '}' + span.literal.text;
+        }
+        return result;
+    }
+    // Try to evaluate constant identifiers
+    if (ts.isIdentifier(node)) {
+        const symbol = checker.getSymbolAtLocation(node);
+        if (symbol?.valueDeclaration &&
+            ts.isVariableDeclaration(symbol.valueDeclaration)) {
+            const init = symbol.valueDeclaration.initializer;
+            if (init) {
+                return extractStringLiteral(init, checker);
+            }
+        }
+    }
+    throw new Error('Unable to extract string literal from node');
+}
+/**
+ * Check if node is string-like (string literal or template expression)
+ */
+export function isStringLike(node, _checker) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return true;
+    }
+    // Check if it's a template string with substitutions
+    if (ts.isTemplateExpression(node)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if node is function-like (arrow, function expression, or function declaration)
+ */
+export function isFunctionLike(node) {
+    return (ts.isArrowFunction(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isFunctionDeclaration(node));
+}
+/**
+ * Extract number literal value from a node
+ */
+export function extractNumberLiteral(node) {
+    if (ts.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    return null;
+}
+/**
+ * Extract a property value from an object literal expression
+ * Returns the extracted value or null if not found/cannot extract
+ */
+export function extractPropertyString(objNode, propertyName, checker) {
+    for (const prop of objNode.properties) {
+        if (ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === propertyName) {
+            return extractStringLiteral(prop.initializer, checker);
+        }
+    }
+    return null;
+}
+/**
+ * Extract description from options object
+ */
+export function extractDescription(optionsNode, checker) {
+    if (!optionsNode || !ts.isObjectLiteralExpression(optionsNode)) {
+        return null;
+    }
+    return extractPropertyString(optionsNode, 'description', checker);
+}
+/**
+ * Extract duration value (number or string)
+ */
+export function extractDuration(node, checker) {
+    const numValue = extractNumberLiteral(node);
+    if (numValue !== null) {
+        return numValue;
+    }
+    try {
+        return extractStringLiteral(node, checker);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/extract-service-metadata.d.ts

@@ -0,0 +1,19 @@
+import * as ts from 'typescript';
+export interface ServiceMetadata {
+    name: string;
+    summary: string;
+    description: string;
+    package: string;
+    path: string;
+    version: string;
+    interface: string;
+    expandedProperties: Record<string, string>;
+}
+/**
+ * Extract metadata for a service from its TypeScript declaration
+ */
+export declare function extractServiceMetadata(serviceName: string, type: ts.Type, checker: ts.TypeChecker, rootDir: string): ServiceMetadata | null;
+/**
+ * Extract metadata for all services in a type
+ */
+export declare function extractAllServiceMetadata(servicesType: ts.Type, checker: ts.TypeChecker, rootDir: string): ServiceMetadata[];