@pikku/inspector 0.11.0 → 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,
@@ -114,7 +114,7 @@ export interface SerializableInspectorState {
   }
   workflows: {
     meta: InspectorState['workflows']['meta']
-    files: string[]
+    files: Array<[string, { path: string; exportedName: string }]>
   }
   rpc: {
     internalMeta: InspectorState['rpc']['internalMeta']
@@ -167,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>
+  }>
 }
 
 /**
@@ -204,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()
@@ -214,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(
@@ -249,7 +257,7 @@ export function serializeInspectorState(
     },
     workflows: {
       meta: state.workflows.meta,
-      files: Array.from(state.workflows.files),
+      files: Array.from(state.workflows.files.entries()),
     },
     rpc: {
       internalMeta: state.rpc.internalMeta,
@@ -282,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,
   }
 }
 
@@ -314,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(
@@ -354,7 +363,7 @@ export function deserializeInspectorState(
     },
     workflows: {
       meta: data.workflows.meta,
-      files: new Set(data.workflows.files),
+      files: new Map(data.workflows.files),
     },
     rpc: {
       internalMeta: data.rpc.internalMeta,
@@ -387,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"
     }
   },

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

@@ -34,7 +34,7 @@ export const visitSetup = (
   addFileExtendsCoreType(
     node,
     checker,
-    state.sessionServicesTypeImportMap,
+    state.wireServicesTypeImportMap,
     'CoreServices',
     state
   )
@@ -65,8 +65,8 @@ export const visitSetup = (
   addFileWithFactory(
     node,
     checker,
-    state.sessionServicesFactories,
-    'CreateSessionServices',
+    state.wireServicesFactories,
+    'CreateWireServices',
     state
   )