@pikku/inspector 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -1,4 +1,19 @@
-## 0.11.0
+## 0.11.2
+
+## 0.11.2
+
+### Patch Changes
+
+- db9c7bf: Add workflow graph inspection and DSL extraction
+- Updated dependencies [db9c7bf]
+  - @pikku/core@0.11.2
+
+### Features
+
+- f35e89da: Add workflow graph inspection and DSL extraction
+  - Workflow graph inspection with `add-workflow-graph.ts`
+  - DSL workflow extraction utilities (extract, deserialize, validate)
+  - DSL to graph conversion for metadata generation
 
 ## 0.11.1
 

package/dist/add/add-forge-credential.d.ts

@@ -0,0 +1,8 @@
+import { AddWiring } from '../types.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 declare const addForgeCredential: AddWiring;

package/dist/add/add-forge-credential.js

@@ -0,0 +1,77 @@
+import * as ts from 'typescript';
+import { getPropertyValue } from '../utils/get-property-value.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 = (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');
+        const displayNameValue = getPropertyValue(obj, 'displayName');
+        const descriptionValue = getPropertyValue(obj, 'description');
+        const secretIdValue = getPropertyValue(obj, 'secretId');
+        // Get schema variable name for later runtime import
+        let schemaVariableName = 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,
+        };
+    }
+};

package/dist/add/add-forge-node.d.ts

@@ -0,0 +1,7 @@
+import { AddWiring } from '../types.js';
+/**
+ * Inspector for wireForgeNode calls.
+ * Extracts metadata for Forge workflow builder nodes.
+ * Note: wireForgeNode is metadata-only - no runtime behavior.
+ */
+export declare const addForgeNode: AddWiring;

package/dist/add/add-forge-node.js

@@ -0,0 +1,77 @@
+import * as ts from 'typescript';
+import { getPropertyValue, getCommonWireMetaData, } from '../utils/get-property-value.js';
+import { ErrorCode } from '../error-codes.js';
+/**
+ * Inspector for wireForgeNode calls.
+ * Extracts metadata for Forge workflow builder nodes.
+ * Note: wireForgeNode is metadata-only - no runtime behavior.
+ */
+export const addForgeNode = (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 wireForgeNode
+    if (!ts.isIdentifier(expression) || expression.text !== 'wireForgeNode') {
+        return;
+    }
+    if (!firstArg) {
+        return;
+    }
+    if (ts.isObjectLiteralExpression(firstArg)) {
+        const obj = firstArg;
+        const nameValue = getPropertyValue(obj, 'name');
+        const displayNameValue = getPropertyValue(obj, 'displayName');
+        const categoryValue = getPropertyValue(obj, 'category');
+        const typeValue = getPropertyValue(obj, 'type');
+        const rpcValue = getPropertyValue(obj, 'rpc');
+        const errorOutputValue = getPropertyValue(obj, 'errorOutput');
+        const { tags, description } = getCommonWireMetaData(obj, 'Forge node', nameValue, logger);
+        // Validate required fields
+        if (!nameValue) {
+            logger.critical(ErrorCode.MISSING_NAME, "Forge node is missing the required 'name' property.");
+            return;
+        }
+        if (!displayNameValue) {
+            logger.critical(ErrorCode.MISSING_NAME, `Forge node '${nameValue}' is missing the required 'displayName' property.`);
+            return;
+        }
+        if (!categoryValue) {
+            logger.critical(ErrorCode.MISSING_NAME, `Forge node '${nameValue}' is missing the required 'category' property.`);
+            return;
+        }
+        if (!typeValue) {
+            logger.critical(ErrorCode.MISSING_NAME, `Forge node '${nameValue}' is missing the required 'type' property.`);
+            return;
+        }
+        if (!['trigger', 'action', 'end'].includes(typeValue)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Forge node '${nameValue}' has invalid type '${typeValue}'. Must be 'trigger', 'action', or 'end'.`);
+            return;
+        }
+        if (!rpcValue) {
+            logger.critical(ErrorCode.MISSING_NAME, `Forge node '${nameValue}' is missing the required 'rpc' property.`);
+            return;
+        }
+        // Get function metadata for input/output schemas
+        const fnMeta = state.functions.meta[rpcValue];
+        const inputSchemaName = fnMeta?.inputs?.[0] || null;
+        const outputSchemaName = fnMeta?.outputs?.[0] || null;
+        // Note: Category validation against forge.node.categories config
+        // is done at CLI build time, not during inspection
+        state.forgeNodes.files.add(node.getSourceFile().fileName);
+        state.forgeNodes.meta[nameValue] = {
+            name: nameValue,
+            displayName: displayNameValue,
+            category: categoryValue,
+            type: typeValue,
+            rpc: rpcValue,
+            description,
+            errorOutput: errorOutputValue ?? false,
+            inputSchemaName,
+            outputSchemaName,
+            tags,
+        };
+    }
+};

package/dist/add/add-functions.js

@@ -3,6 +3,8 @@ import { extractFunctionName } from '../utils/extract-function-name.js';
 import { extractFunctionNode } from '../utils/extract-function-node.js';
 import { getPropertyValue, getCommonWireMetaData, } from '../utils/get-property-value.js';
 import { resolveMiddleware } from '../utils/middleware.js';
+import { resolvePermissions } from '../utils/permissions.js';
+import { ErrorCode } from '../error-codes.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
     return regex.test(name);
@@ -109,7 +111,7 @@ const resolveUnionTypes = (checker, type) => {
     // Check if it's a union type AND not part of an intersection
     if (type.isUnion() && !(type.flags & ts.TypeFlags.Intersection)) {
         for (const t of type.types) {
-            const name = nullifyTypes(checker.typeToString(t));
+            const name = nullifyTypes(checker.typeToString(t, undefined, ts.TypeFormatFlags.NoTruncation));
             if (name) {
                 types.push(t);
                 names.push(name);
@@ -117,7 +119,7 @@ const resolveUnionTypes = (checker, type) => {
         }
     }
     else {
-        const name = nullifyTypes(checker.typeToString(type));
+        const name = nullifyTypes(checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation));
         if (name) {
             types.push(type);
             names.push(name);
@@ -231,6 +233,7 @@ export const addFunctions = (logger, node, checker, state) => {
     if (args.length === 0)
         return;
     const { pikkuFuncName, name, explicitName, exportedName } = extractFunctionName(node, checker, state.rootDir);
+    let title;
     let tags;
     let summary;
     let description;
@@ -241,16 +244,75 @@ export const addFunctions = (logger, node, checker, state) => {
     // Extract the function node using shared utility
     const firstArg = args[0];
     const { funcNode: handlerNode, resolvedFunc, isDirectFunction, } = extractFunctionNode(firstArg, checker);
+    // Variables to hold zod schema references if provided
+    let inputZodSchemaRef = null;
+    let outputZodSchemaRef = null;
+    // Helper to resolve schema identifier to its actual source file
+    const resolveSchemaSourceFile = (identifier) => {
+        const symbol = checker.getSymbolAtLocation(identifier);
+        if (!symbol)
+            return null;
+        const decl = symbol.valueDeclaration || symbol.declarations?.[0];
+        if (!decl)
+            return null;
+        // If it's an import specifier, resolve the aliased symbol to get the actual source
+        if (ts.isImportSpecifier(decl)) {
+            const aliasedSymbol = checker.getAliasedSymbol(symbol);
+            if (aliasedSymbol) {
+                const aliasedDecl = aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0];
+                if (aliasedDecl) {
+                    return {
+                        variableName: identifier.text,
+                        sourceFile: aliasedDecl.getSourceFile().fileName,
+                    };
+                }
+            }
+        }
+        // Not an import - use the current source file
+        return {
+            variableName: identifier.text,
+            sourceFile: decl.getSourceFile().fileName,
+        };
+    };
     // Extract config properties if using object form
     if (ts.isObjectLiteralExpression(firstArg)) {
         objectNode = firstArg;
         const metadata = getCommonWireMetaData(firstArg, 'Function', name, logger);
+        title = metadata.title;
         tags = metadata.tags;
         summary = metadata.summary;
         description = metadata.description;
         errors = metadata.errors;
         expose = getPropertyValue(firstArg, 'expose');
         internal = getPropertyValue(firstArg, 'internal');
+        // Extract zod schema variable names from input/output properties
+        for (const prop of firstArg.properties) {
+            if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                const propName = prop.name.text;
+                if (propName === 'input' || propName === 'output') {
+                    if (ts.isIdentifier(prop.initializer)) {
+                        // Good - it's a variable reference, resolve its actual source file
+                        const ref = resolveSchemaSourceFile(prop.initializer);
+                        if (ref) {
+                            if (propName === 'input') {
+                                inputZodSchemaRef = ref;
+                            }
+                            else {
+                                outputZodSchemaRef = ref;
+                            }
+                        }
+                    }
+                    else if (ts.isCallExpression(prop.initializer)) {
+                        // Bad - it's an inline expression
+                        const schemaName = `${name.charAt(0).toUpperCase() + name.slice(1)}${propName.charAt(0).toUpperCase() + propName.slice(1)}`;
+                        logger.critical(ErrorCode.INLINE_ZOD_SCHEMA, `Inline Zod schemas are not supported for '${propName}' in '${name}'.\n` +
+                            `  Extract to an exported variable:\n` +
+                            `    export const ${schemaName} = ${prop.initializer.getText()}\n` +
+                            `  Then use: ${propName}: ${schemaName}`);
+                    }
+                }
+            }
+        }
     }
     // Pick the handler: use resolvedFunc when it exists and is a function, otherwise fall back to handlerNode
     const handler = resolvedFunc &&
@@ -314,16 +376,41 @@ export const addFunctions = (logger, node, checker, state) => {
     const genericTypes = (typeArguments ?? [])
         .map((tn) => checker.getTypeFromTypeNode(tn))
         .map((t) => unwrapPromise(checker, t));
+    const capitalizedName = name.charAt(0).toUpperCase() + name.slice(1);
     // --- Input Extraction ---
-    let { names: inputNames, types: inputTypes } = getNamesAndTypes(checker, state.functions.typesMap, 'Input', name, genericTypes[0]);
-    // if (inputTypes.length === 0) {
-    //   logger.debug(
-    //     `\x1b[31m• Unknown input type for '${name}', assuming void.\x1b[0m`
-    //   )
-    // }
+    let inputNames = [];
+    let inputTypes = [];
+    if (inputZodSchemaRef) {
+        const schemaName = `${capitalizedName}Input`;
+        inputNames = [schemaName];
+        state.zodLookup.set(schemaName, inputZodSchemaRef);
+        state.functions.typesMap.addCustomType(schemaName, 'unknown', []);
+    }
+    else if (genericTypes.length >= 1 && genericTypes[0]) {
+        // Fall back to extracting from generic type arguments
+        const result = getNamesAndTypes(checker, state.functions.typesMap, 'Input', name, genericTypes[0]);
+        inputNames = result.names;
+        inputTypes = result.types;
+    }
+    else {
+        // Fall back to extracting from the function's second parameter type
+        const secondParam = handler.parameters[1];
+        if (secondParam) {
+            const paramType = checker.getTypeAtLocation(secondParam);
+            const result = getNamesAndTypes(checker, state.functions.typesMap, 'Input', pikkuFuncName, paramType);
+            inputNames = result.names;
+            inputTypes = result.types;
+        }
+    }
     // --- Output Extraction ---
     let outputNames = [];
-    if (genericTypes.length >= 2) {
+    if (outputZodSchemaRef) {
+        const schemaName = `${capitalizedName}Output`;
+        outputNames = [schemaName];
+        state.zodLookup.set(schemaName, outputZodSchemaRef);
+        state.functions.typesMap.addCustomType(schemaName, 'unknown', []);
+    }
+    else if (genericTypes.length >= 2) {
         outputNames = getNamesAndTypes(checker, state.functions.typesMap, 'Output', name, genericTypes[1]).names;
     }
     else {
@@ -345,6 +432,10 @@ export const addFunctions = (logger, node, checker, state) => {
     const middleware = objectNode
         ? resolveMiddleware(state, objectNode, tags, checker)
         : undefined;
+    // --- resolve permissions ---
+    const permissions = objectNode
+        ? resolvePermissions(state, objectNode, tags, checker)
+        : undefined;
     state.functions.meta[pikkuFuncName] = {
         pikkuFuncName,
         name,
@@ -356,11 +447,13 @@ export const addFunctions = (logger, node, checker, state) => {
         outputs: outputNames.filter((n) => n !== 'void') ?? null,
         expose: expose || undefined,
         internal: internal || undefined,
+        title,
         tags: tags || undefined,
         summary,
         description,
         errors,
         middleware,
+        permissions,
         isDirectFunction,
     };
     // Store function file location for wiring generation

package/dist/add/add-http-route.js

@@ -47,8 +47,30 @@ export const addHTTPRoute = (logger, node, checker, state, options) => {
     const keys = pathToRegexp(route).keys;
     const params = keys.filter((k) => k.type === 'param').map((k) => k.name);
     const method = getPropertyValue(obj, 'method')?.toLowerCase() || 'get';
-    const { tags, summary, description, errors } = getCommonWireMetaData(obj, 'HTTP route', route, logger);
+    const { title, tags, summary, description, errors } = getCommonWireMetaData(obj, 'HTTP route', route, logger);
     const query = getPropertyValue(obj, 'query') || [];
+    // Check if this is a workflow trigger (workflow: true)
+    const isWorkflowTrigger = getPropertyValue(obj, 'workflow') === true;
+    if (isWorkflowTrigger) {
+        // Workflow triggers don't need func - they're handled by workflow-utils
+        // Just record the route for HTTP meta but skip function processing
+        state.http.files.add(node.getSourceFile().fileName);
+        state.http.meta[method][route] = {
+            pikkuFuncName: '', // No function - workflow handles it
+            route,
+            method: method,
+            params: params.length > 0 ? params : undefined,
+            query: query.length > 0 ? query : undefined,
+            inputTypes: undefined,
+            title,
+            summary,
+            description,
+            errors,
+            tags,
+            workflow: true,
+        };
+        return;
+    }
     // --- find the referenced function name first for filtering ---
     const funcInitializer = getPropertyAssignmentInitializer(obj, 'func', true, checker);
     if (!funcInitializer) {
@@ -84,6 +106,7 @@ export const addHTTPRoute = (logger, node, checker, state, options) => {
         params: params.length > 0 ? params : undefined,
         query: query.length > 0 ? query : undefined,
         inputTypes,
+        title,
         summary,
         description,
         errors,

package/dist/add/add-rpc-invocations.d.ts

@@ -2,5 +2,8 @@ import * as ts from 'typescript';
 import { InspectorState, InspectorLogger } from '../types.js';
 /**
  * Scan for rpc.invoke() calls to track which functions are actually being invoked
+ * Also detects external package usage via:
+ * - Namespaced calls: rpc.invoke('namespace:function')
+ * - External helper: external('namespace:function')
  */
 export declare function addRPCInvocations(node: ts.Node, state: InspectorState, logger: InspectorLogger): void;

package/dist/add/add-rpc-invocations.js

@@ -1,35 +1,61 @@
 import * as ts from 'typescript';
+/**
+ * Helper to extract namespace from a namespaced function reference like 'ext:hello'
+ */
+function extractNamespace(functionRef) {
+    const colonIndex = functionRef.indexOf(':');
+    if (colonIndex !== -1) {
+        return functionRef.substring(0, colonIndex);
+    }
+    return null;
+}
 /**
  * Scan for rpc.invoke() calls to track which functions are actually being invoked
+ * Also detects external package usage via:
+ * - Namespaced calls: rpc.invoke('namespace:function')
+ * - External helper: external('namespace:function')
  */
 export function addRPCInvocations(node, state, logger) {
-    // Look for property access expressions: rpc.invoke
-    if (ts.isPropertyAccessExpression(node)) {
-        const { expression, name } = node;
-        // Check if this is accessing 'invoke' property
-        if (name.text === 'invoke') {
-            // Check if the object is 'rpc' (or a variable containing rpc)
-            if (ts.isIdentifier(expression) && expression.text === 'rpc') {
-                // This is rpc.invoke - now we need to find the parent call expression
-                const parent = node.parent;
-                if (ts.isCallExpression(parent) && parent.expression === node) {
-                    // This is rpc.invoke('function-name')
-                    const [firstArg] = parent.arguments;
-                    if (firstArg) {
-                        // Extract the function name from string literal
-                        if (ts.isStringLiteral(firstArg)) {
-                            const functionName = firstArg.text;
-                            logger.debug(`• Found RPC invocation: ${functionName}`);
-                            state.rpc.invokedFunctions.add(functionName);
-                        }
-                        // Handle template literals like `function-${name}`
-                        else if (ts.isTemplateExpression(firstArg) ||
-                            ts.isNoSubstitutionTemplateLiteral(firstArg)) {
-                            logger.warn(`• Found dynamic RPC invocation: ${firstArg.getText()}`);
-                            logger.warn(`\tYou can only use string literals for RPC function names, with ' or " and not \``);
-                        }
+    // Look for call expressions: external('ext:hello') or rpc.invoke('...')
+    if (ts.isCallExpression(node)) {
+        const { expression, arguments: args } = node;
+        // Check for external('namespace:function') calls
+        if (ts.isIdentifier(expression) && expression.text === 'external') {
+            const [firstArg] = args;
+            if (firstArg && ts.isStringLiteral(firstArg)) {
+                const functionRef = firstArg.text;
+                logger.debug(`• Found external() call: ${functionRef}`);
+                state.rpc.invokedFunctions.add(functionRef);
+                const namespace = extractNamespace(functionRef);
+                if (namespace) {
+                    logger.debug(`  → External package detected: ${namespace}`);
+                    state.rpc.usedExternalPackages.add(namespace);
+                }
+            }
+        }
+        // Check for rpc.invoke('...') calls
+        if (ts.isPropertyAccessExpression(expression) &&
+            expression.name.text === 'invoke' &&
+            ts.isIdentifier(expression.expression) &&
+            expression.expression.text === 'rpc') {
+            const [firstArg] = args;
+            if (firstArg) {
+                if (ts.isStringLiteral(firstArg)) {
+                    const functionRef = firstArg.text;
+                    logger.debug(`• Found RPC invocation: ${functionRef}`);
+                    state.rpc.invokedFunctions.add(functionRef);
+                    const namespace = extractNamespace(functionRef);
+                    if (namespace) {
+                        logger.debug(`  → External package detected: ${namespace}`);
+                        state.rpc.usedExternalPackages.add(namespace);
                     }
                 }
+                // Handle template literals like `function-${name}`
+                else if (ts.isTemplateExpression(firstArg) ||
+                    ts.isNoSubstitutionTemplateLiteral(firstArg)) {
+                    logger.warn(`• Found dynamic RPC invocation: ${firstArg.getText()}`);
+                    logger.warn(`\tYou can only use string literals for RPC function names, with ' or " and not \``);
+                }
             }
         }
     }

package/dist/add/add-workflow-graph.d.ts

@@ -0,0 +1,6 @@
+import type { AddWiring } from '../types.js';
+/**
+ * Inspector for wireWorkflow() calls with graph definitions
+ * Detects: wireWorkflow({ wires: {...}, graph: pikkuWorkflowGraphResult })
+ */
+export declare const addWorkflowGraph: AddWiring;