@pikku/inspector 0.10.2 → 0.11.1

package/src/utils/post-process.ts

@@ -1,3 +1,4 @@
+import * as ts from 'typescript'
 import { InspectorState } from '../types.js'
 import {
   FunctionServicesMeta,
@@ -5,6 +6,10 @@ import {
   PermissionMetadata,
 } from '@pikku/core'
 import { extractTypeKeys } from './type-utils.js'
+import {
+  extractAllServiceMetadata,
+  ServiceMetadata,
+} from './extract-service-metadata.js'
 
 /**
  * Helper to extract wire-level middleware/permission names from metadata.
@@ -82,9 +87,9 @@ function extractAllServices(
   const servicesTypes = state.typesLookup.get('Services')
   if (servicesTypes && servicesTypes.length > 0) {
     const allServiceNames = extractTypeKeys(servicesTypes[0])
-    // Session services are those in Services but not in SingletonServices
+    // Wire services are those in Services but not in SingletonServices
     const singletonSet = new Set(state.serviceAggregation.allSingletonServices)
-    state.serviceAggregation.allSessionServices = allServiceNames
+    state.serviceAggregation.allWireServices = allServiceNames
       .filter((name) => !singletonSet.has(name))
       .sort()
   }
@@ -206,7 +211,7 @@ export function aggregateRequiredServices(
   }
 
   // 5. Services from session service factories
-  for (const singletonServices of state.sessionServicesMeta.values()) {
+  for (const singletonServices of state.wireServicesMeta.values()) {
     singletonServices.forEach((service) => {
       if (!internalServices.has(service)) {
         requiredServices.add(service)
@@ -214,3 +219,51 @@ export function aggregateRequiredServices(
     })
   }
 }
+
+/**
+ * Extract service interface metadata for all user-defined services.
+ * This extracts metadata for services in SingletonServices and Services types
+ * to generate documentation for AI consumption.
+ *
+ * Must be called after aggregateRequiredServices() to ensure types are loaded.
+ */
+export function extractServiceInterfaceMetadata(
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>,
+  checker: ts.TypeChecker
+): void {
+  if (!('typesLookup' in state)) {
+    return
+  }
+
+  const allMetadata: ServiceMetadata[] = []
+
+  const singletonServicesTypes = state.typesLookup.get('SingletonServices')
+  if (singletonServicesTypes && singletonServicesTypes.length > 0) {
+    const singletonMeta = extractAllServiceMetadata(
+      singletonServicesTypes[0],
+      checker,
+      state.rootDir
+    )
+    allMetadata.push(...singletonMeta)
+  }
+
+  const servicesTypes = state.typesLookup.get('Services')
+  if (servicesTypes && servicesTypes.length > 0) {
+    const wireServicesMeta = extractAllServiceMetadata(
+      servicesTypes[0],
+      checker,
+      state.rootDir
+    )
+
+    const singletonNames = new Set(
+      state.serviceAggregation.allSingletonServices
+    )
+    const uniqueWireServices = wireServicesMeta.filter(
+      (meta) => !singletonNames.has(meta.name)
+    )
+
+    allMetadata.push(...uniqueWireServices)
+  }
+
+  state.serviceMetadata = allMetadata
+}

package/src/utils/serialize-inspector-state.ts

@@ -13,7 +13,7 @@ export interface SerializableInspectorState {
       { variable: string; type: string | null; typePath: string | null }[],
     ]
   >
-  sessionServicesTypeImportMap: Array<
+  wireServicesTypeImportMap: Array<
     [
       string,
       { variable: string; type: string | null; typePath: string | null }[],
@@ -37,13 +37,13 @@ export interface SerializableInspectorState {
       { variable: string; type: string | null; typePath: string | null }[],
     ]
   >
-  sessionServicesFactories: Array<
+  wireServicesFactories: Array<
     [
       string,
       { variable: string; type: string | null; typePath: string | null }[],
     ]
   >
-  sessionServicesMeta: Array<[string, string[]]>
+  wireServicesMeta: Array<[string, string[]]>
   configFactories: Array<
     [
       string,
@@ -112,6 +112,10 @@ export interface SerializableInspectorState {
     meta: InspectorState['queueWorkers']['meta']
     files: string[]
   }
+  workflows: {
+    meta: InspectorState['workflows']['meta']
+    files: Array<[string, { path: string; exportedName: string }]>
+  }
   rpc: {
     internalMeta: InspectorState['rpc']['internalMeta']
     internalFiles: Array<[string, { path: string; exportedName: string }]>
@@ -163,8 +167,18 @@ export interface SerializableInspectorState {
     usedMiddleware: string[]
     usedPermissions: 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>
+  }>
 }
 
 /**
@@ -200,8 +214,8 @@ export function serializeInspectorState(
     singletonServicesTypeImportMap: Array.from(
       state.singletonServicesTypeImportMap.entries()
     ),
-    sessionServicesTypeImportMap: Array.from(
-      state.sessionServicesTypeImportMap.entries()
+    wireServicesTypeImportMap: Array.from(
+      state.wireServicesTypeImportMap.entries()
     ),
     userSessionTypeImportMap: Array.from(
       state.userSessionTypeImportMap.entries()
@@ -210,10 +224,8 @@ export function serializeInspectorState(
     singletonServicesFactories: Array.from(
       state.singletonServicesFactories.entries()
     ),
-    sessionServicesFactories: Array.from(
-      state.sessionServicesFactories.entries()
-    ),
-    sessionServicesMeta: Array.from(state.sessionServicesMeta.entries()),
+    wireServicesFactories: Array.from(state.wireServicesFactories.entries()),
+    wireServicesMeta: Array.from(state.wireServicesMeta.entries()),
     configFactories: Array.from(state.configFactories.entries()),
     filesAndMethods: state.filesAndMethods,
     filesAndMethodsErrors: Array.from(
@@ -243,6 +255,10 @@ export function serializeInspectorState(
       meta: state.queueWorkers.meta,
       files: Array.from(state.queueWorkers.files),
     },
+    workflows: {
+      meta: state.workflows.meta,
+      files: Array.from(state.workflows.files.entries()),
+    },
     rpc: {
       internalMeta: state.rpc.internalMeta,
       internalFiles: Array.from(state.rpc.internalFiles.entries()),
@@ -274,8 +290,9 @@ export function serializeInspectorState(
       usedMiddleware: Array.from(state.serviceAggregation.usedMiddleware),
       usedPermissions: Array.from(state.serviceAggregation.usedPermissions),
       allSingletonServices: state.serviceAggregation.allSingletonServices,
-      allSessionServices: state.serviceAggregation.allSessionServices,
+      allWireServices: state.serviceAggregation.allWireServices,
     },
+    serviceMetadata: state.serviceMetadata,
   }
 }
 
@@ -306,12 +323,12 @@ export function deserializeInspectorState(
     singletonServicesTypeImportMap: new Map(
       data.singletonServicesTypeImportMap
     ),
-    sessionServicesTypeImportMap: new Map(data.sessionServicesTypeImportMap),
+    wireServicesTypeImportMap: new Map(data.wireServicesTypeImportMap),
     userSessionTypeImportMap: new Map(data.userSessionTypeImportMap),
     configTypeImportMap: new Map(data.configTypeImportMap),
     singletonServicesFactories: new Map(data.singletonServicesFactories),
-    sessionServicesFactories: new Map(data.sessionServicesFactories),
-    sessionServicesMeta: new Map(data.sessionServicesMeta),
+    wireServicesFactories: new Map(data.wireServicesFactories),
+    wireServicesMeta: new Map(data.wireServicesMeta),
     configFactories: new Map(data.configFactories),
     filesAndMethods: data.filesAndMethods,
     filesAndMethodsErrors: new Map(
@@ -344,6 +361,10 @@ export function deserializeInspectorState(
       meta: data.queueWorkers.meta,
       files: new Set(data.queueWorkers.files),
     },
+    workflows: {
+      meta: data.workflows.meta,
+      files: new Map(data.workflows.files),
+    },
     rpc: {
       internalMeta: data.rpc.internalMeta,
       internalFiles: new Map(data.rpc.internalFiles),
@@ -375,7 +396,8 @@ export function deserializeInspectorState(
       usedMiddleware: new Set(data.serviceAggregation.usedMiddleware),
       usedPermissions: new Set(data.serviceAggregation.usedPermissions),
       allSingletonServices: data.serviceAggregation.allSingletonServices,
-      allSessionServices: data.serviceAggregation.allSessionServices,
+      allWireServices: data.serviceAggregation.allWireServices,
     },
+    serviceMetadata: data.serviceMetadata || [],
   }
 }

package/src/utils/test-data/inspector-state.json

@@ -12,7 +12,7 @@
       ]
     ]
   ],
-  "sessionServicesTypeImportMap": [
+  "wireServicesTypeImportMap": [
     [
       "/Users/yasser/git/pikku/pikku/templates/functions/types/application-types.d.ts",
       [
@@ -60,19 +60,19 @@
       ]
     ]
   ],
-  "sessionServicesFactories": [
+  "wireServicesFactories": [
     [
       "src/services.ts",
       [
         {
-          "variable": "createSessionServices",
-          "type": "CreateSessionServices",
+          "variable": "createWireServices",
+          "type": "CreateWireServices",
           "typePath": "src/services.ts"
         }
       ]
     ]
   ],
-  "sessionServicesMeta": [["createSessionServices", []]],
+  "wireServicesMeta": [["createWireServices", []]],
   "configFactories": [
     [
       "src/services.ts",
@@ -98,7 +98,7 @@
       "variable": "SingletonServices",
       "typePath": "/Users/yasser/git/pikku/pikku/templates/functions/types/application-types.d.ts"
     },
-    "sessionServicesType": {
+    "wireServicesType": {
       "file": "/Users/yasser/git/pikku/pikku/templates/functions/types/application-types.d.ts",
       "type": "Services",
       "variable": "Services",
@@ -122,10 +122,10 @@
       "variable": "createSingletonServices",
       "typePath": "src/services.ts"
     },
-    "sessionServicesFactory": {
+    "wireServicesFactory": {
       "file": "src/services.ts",
-      "type": "CreateSessionServices",
-      "variable": "createSessionServices",
+      "type": "CreateWireServices",
+      "variable": "createWireServices",
       "typePath": "src/services.ts"
     }
   },
@@ -1260,6 +1260,10 @@
     },
     "files": ["src/queue-worker.wiring.ts"]
   },
+  "workflows": {
+    "meta": {},
+    "files": []
+  },
   "rpc": {
     "internalMeta": {
       "onConnect": "onConnect",

package/src/utils/type-utils.ts

@@ -4,6 +4,75 @@ export const extractTypeKeys = (type: ts.Type): string[] => {
   return type.getProperties().map((symbol) => symbol.getName())
 }
 
+/**
+ * Resolve an identifier or call expression to the actual function declaration
+ */
+export function resolveFunctionDeclaration(
+  node: ts.Node,
+  checker: ts.TypeChecker
+): ts.Node | null {
+  // If it's already a function-like node, return it
+  if (
+    ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isArrowFunction(node)
+  ) {
+    return node
+  }
+
+  // If it's a call expression (e.g., pikkuWorkflowFunc(...)), get its first argument
+  if (ts.isCallExpression(node) && node.arguments.length > 0) {
+    const firstArg = node.arguments[0]
+    if (ts.isFunctionExpression(firstArg) || ts.isArrowFunction(firstArg)) {
+      return firstArg
+    }
+  }
+
+  // If it's an identifier, resolve to declaration
+  if (ts.isIdentifier(node)) {
+    const symbol = checker.getSymbolAtLocation(node)
+    if (!symbol) return null
+
+    // Try valueDeclaration first, then fallback to declarations[0]
+    const decl = symbol.valueDeclaration || symbol.declarations?.[0]
+    if (!decl) return null
+
+    // If it's an import specifier, resolve the aliased symbol
+    if (ts.isImportSpecifier(decl)) {
+      const aliasedSymbol = checker.getAliasedSymbol(symbol)
+      if (aliasedSymbol) {
+        const aliasedDecl =
+          aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0]
+        if (aliasedDecl) {
+          // For variable declarations, get the initializer
+          if (
+            ts.isVariableDeclaration(aliasedDecl) &&
+            aliasedDecl.initializer
+          ) {
+            return resolveFunctionDeclaration(aliasedDecl.initializer, checker)
+          }
+          // For function declarations, return directly
+          if (ts.isFunctionDeclaration(aliasedDecl)) {
+            return aliasedDecl
+          }
+        }
+      }
+    }
+
+    // If it's a variable declaration, get the initializer
+    if (ts.isVariableDeclaration(decl) && decl.initializer) {
+      return resolveFunctionDeclaration(decl.initializer, checker)
+    }
+
+    // If it's a function declaration
+    if (ts.isFunctionDeclaration(decl)) {
+      return decl
+    }
+  }
+
+  return null
+}
+
 export function getPropertyAssignmentInitializer(
   obj: ts.ObjectLiteralExpression,
   propName: string,

package/src/utils/write-service-metadata.ts

@@ -0,0 +1,51 @@
+import * as fs from 'fs'
+import * as path from 'path'
+import { ServiceMetadata } from './extract-service-metadata.js'
+
+/**
+ * Write service metadata to a JSON file in .pikku/services directory
+ */
+export function writeServiceMetadata(
+  serviceMeta: ServiceMetadata,
+  outDir: string
+): void {
+  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: ServiceMetadata[],
+  outDir: string
+): void {
+  for (const serviceMeta of servicesMetadata) {
+    writeServiceMetadata(serviceMeta, outDir)
+  }
+}
+
+/**
+ * Clean up services directory (remove old service JSON files)
+ */
+export function cleanServicesDirectory(outDir: string): void {
+  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/src/visit.ts

@@ -4,6 +4,7 @@ import { addFileExtendsCoreType } from './add/add-file-extends-core-type.js'
 import { addHTTPRoute } from './add/add-http-route.js'
 import { addSchedule } from './add/add-schedule.js'
 import { addQueueWorker } from './add/add-queue-worker.js'
+import { addWorkflow } from './add/add-workflow.js'
 import { addMCPResource } from './add/add-mcp-resource.js'
 import { addMCPTool } from './add/add-mcp-tool.js'
 import { addMCPPrompt } from './add/add-mcp-prompt.js'
@@ -33,7 +34,7 @@ export const visitSetup = (
   addFileExtendsCoreType(
     node,
     checker,
-    state.sessionServicesTypeImportMap,
+    state.wireServicesTypeImportMap,
     'CoreServices',
     state
   )
@@ -64,8 +65,8 @@ export const visitSetup = (
   addFileWithFactory(
     node,
     checker,
-    state.sessionServicesFactories,
-    'CreateSessionServices',
+    state.wireServicesFactories,
+    'CreateWireServices',
     state
   )
 
@@ -74,6 +75,7 @@ export const visitSetup = (
   addRPCInvocations(node, state, logger)
   addMiddleware(logger, node, checker, state, options)
   addPermission(logger, node, checker, state, options)
+  addWorkflow(logger, node, checker, state, options)
 
   ts.forEachChild(node, (child) =>
     visitSetup(logger, checker, child, state, options)