@pikku/inspector 0.12.22 → 0.12.24

package/src/add/addon-contracts.test.ts

@@ -0,0 +1,221 @@
+import { strict as assert } from 'node:assert'
+import { describe, test } from 'node:test'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { InspectorLogger } from '../types.js'
+
+const logger: InspectorLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  critical: () => {},
+  hasCriticalErrors: () => false,
+}
+
+describe('addon contract metadata', () => {
+  test('collects exported local define contracts', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-exported-contracts-'))
+    const file = join(rootDir, 'contracts.ts')
+
+    await writeFile(
+      join(rootDir, 'package.json'),
+      JSON.stringify({ name: 'test-app', type: 'module' }, null, 2)
+    )
+
+    await writeFile(
+      file,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        "import { defineHTTPRoutes } from '@pikku/core/http'",
+        "import { defineChannelRoutes } from '@pikku/core/channel'",
+        "import { defineCLICommands } from '@pikku/core/cli'",
+        'export const listTodos = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+        'export const subscribeTodo = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+        'export const runSync = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+        "export const httpRoutes = defineHTTPRoutes({ basePath: '/todos', routes: { list: { method: 'get', route: '/', func: listTodos } } })",
+        'export const channelRoutes = defineChannelRoutes({ subscribe: { func: subscribeTodo } })',
+        'export const cliCommands = defineCLICommands({ sync: { func: runSync, options: {} } })',
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(logger, [file], { rootDir })
+      assert.equal(
+        state.exportedContracts.http.httpRoutes?.routes.list?.func.pikkuFuncId,
+        'listTodos'
+      )
+      assert.equal(
+        state.exportedContracts.channel.channelRoutes?.subscribe?.pikkuFuncId,
+        'subscribeTodo'
+      )
+      assert.equal(
+        state.exportedContracts.cli.cliCommands?.sync?.pikkuFuncId,
+        'runSync'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('expands addon contracts referenced via refHTTP/refChannel/refCLI', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-addon-refs-app-'))
+    const nodeModulesDir = join(rootDir, 'node_modules', '@test', 'addon')
+    const appFile = join(rootDir, 'app.ts')
+
+    await mkdir(join(nodeModulesDir, '.pikku', 'function'), { recursive: true })
+    await mkdir(join(nodeModulesDir, '.pikku', 'http'), { recursive: true })
+    await mkdir(join(nodeModulesDir, '.pikku', 'cli'), { recursive: true })
+    await mkdir(join(nodeModulesDir, '.pikku', 'channel'), { recursive: true })
+
+    await writeFile(
+      join(rootDir, 'package.json'),
+      JSON.stringify({ name: 'test-app', type: 'module' }, null, 2)
+    )
+    await writeFile(
+      join(nodeModulesDir, 'package.json'),
+      JSON.stringify({ name: '@test/addon', type: 'module' }, null, 2)
+    )
+    await writeFile(
+      join(
+        nodeModulesDir,
+        '.pikku',
+        'function',
+        'pikku-functions-meta.gen.json'
+      ),
+      JSON.stringify(
+        {
+          listTodos: {
+            pikkuFuncId: 'listTodos',
+            inputSchemaName: null,
+            outputSchemaName: null,
+            sessionless: true,
+          },
+          runSync: {
+            pikkuFuncId: 'runSync',
+            inputSchemaName: null,
+            outputSchemaName: null,
+            sessionless: true,
+          },
+          subscribeTodo: {
+            pikkuFuncId: 'subscribeTodo',
+            inputSchemaName: null,
+            outputSchemaName: null,
+            sessionless: true,
+          },
+        },
+        null,
+        2
+      )
+    )
+    await writeFile(
+      join(
+        nodeModulesDir,
+        '.pikku',
+        'http',
+        'pikku-http-contracts-meta.gen.json'
+      ),
+      JSON.stringify(
+        {
+          httpRoutes: {
+            basePath: '/addon',
+            routes: {
+              list: {
+                method: 'get',
+                route: '/todos',
+                func: { pikkuFuncId: 'listTodos' },
+              },
+            },
+          },
+        },
+        null,
+        2
+      )
+    )
+    await writeFile(
+      join(
+        nodeModulesDir,
+        '.pikku',
+        'cli',
+        'pikku-cli-contracts-meta.gen.json'
+      ),
+      JSON.stringify(
+        {
+          cliCommands: {
+            sync: {
+              pikkuFuncId: 'runSync',
+              positionals: [],
+              options: {},
+            },
+          },
+        },
+        null,
+        2
+      )
+    )
+    await writeFile(
+      join(
+        nodeModulesDir,
+        '.pikku',
+        'channel',
+        'pikku-channel-contracts-meta.gen.json'
+      ),
+      JSON.stringify(
+        {
+          channelRoutes: {
+            subscribe: {
+              pikkuFuncId: 'subscribeTodo',
+            },
+          },
+        },
+        null,
+        2
+      )
+    )
+
+    await writeFile(
+      appFile,
+      [
+        "import { wireAddon } from '@pikku/core/rpc'",
+        "import { wireHTTPRoutes } from '@pikku/core/http'",
+        "import { wireChannel } from '@pikku/core/channel'",
+        "import { wireCLI } from '@pikku/core/cli'",
+        'declare const refHTTP: (name: string) => any',
+        'declare const refChannel: (name: string) => any',
+        'declare const refCLI: (name: string) => any',
+        "wireAddon({ name: 'addon', package: '@test/addon' })",
+        "wireHTTPRoutes({ basePath: '/api', routes: { keep: refHTTP('addon:httpRoutes'), moved: refHTTP('addon:httpRoutes', { basePath: '/ext' }) } })",
+        "wireChannel({ name: 'live', route: '/live', auth: false, onMessageWiring: { action: refChannel('addon:channelRoutes') } })",
+        "wireCLI({ program: 'app', commands: { ...refCLI('addon:cliCommands') } })",
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(logger, [appFile], { rootDir })
+
+      // Default: the addon contract's own basePath ('/addon') is preserved —
+      // the cosmetic slot key ('keep') does not affect the path.
+      const httpEntry = state.http.meta.get['/api/addon/todos']
+      assert.equal(httpEntry?.packageName, '@test/addon')
+      assert.equal(httpEntry?.pikkuFuncId, 'addon:listTodos')
+
+      // Override: the second-arg basePath ('/ext') replaces the addon's own.
+      const overridden = state.http.meta.get['/api/ext/todos']
+      assert.equal(overridden?.packageName, '@test/addon')
+      assert.equal(overridden?.pikkuFuncId, 'addon:listTodos')
+
+      const channelEntry =
+        state.channels.meta.live?.messageWirings.action?.subscribe
+      assert.equal(channelEntry?.packageName, '@test/addon')
+      assert.equal(channelEntry?.pikkuFuncId, 'addon:subscribeTodo')
+
+      const cliEntry = state.cli.meta.programs.app?.commands.sync
+      assert.equal(cliEntry?.packageName, '@test/addon')
+      assert.equal(cliEntry?.pikkuFuncId, 'addon:runSync')
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/error-codes.ts

@@ -84,6 +84,10 @@ export enum ErrorCode {
 
   // Data classification errors
   PII_IN_OUTPUT = 'PKU910',
+
+  // Addon authoring errors
+  ADDON_WIRING_NOT_ALLOWED = 'PKU920',
+  ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = 'PKU921',
 }
 
 /**

package/src/inspector.ts

@@ -1,5 +1,6 @@
 import * as ts from 'typescript'
 import { performance } from 'perf_hooks'
+import { resolve } from 'path'
 import { visitSetup, visitRoutes } from './visit.js'
 import { TypesMap } from './types-map.js'
 import type {
@@ -216,6 +217,14 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     openAPISpec: null,
     diagnostics: [],
     addonFunctions: {},
+    exportedContracts: {
+      http: {},
+      cli: {},
+      channel: {},
+      addonHttp: {},
+      addonCli: {},
+      addonChannel: {},
+    },
     program: null,
   }
 }
@@ -225,6 +234,7 @@ export const inspect = async (
   routeFiles: string[],
   options: InspectorOptions = {}
 ): Promise<InspectorState> => {
+  const normalizedRouteFiles = routeFiles.map((file) => resolve(file))
   const compilerOptions: ts.CompilerOptions = {
     target: ts.ScriptTarget.ESNext,
     module: ts.ModuleKind.Node16,
@@ -237,13 +247,13 @@ export const inspect = async (
   }
   const startProgram = performance.now()
   const program = ts.createProgram(
-    routeFiles,
+    normalizedRouteFiles,
     compilerOptions,
     undefined, // host
     options.oldProgram
   )
   logger.debug(
-    `Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${routeFiles.length} files${options.oldProgram ? ', incremental' : ''})`
+    `Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files${options.oldProgram ? ', incremental' : ''})`
   )
 
   const startChecker = performance.now()
@@ -253,7 +263,7 @@ export const inspect = async (
   )
 
   // Use provided rootDir or infer from source files
-  const rootDir = options.rootDir || findCommonAncestor(routeFiles)
+  const rootDir = options.rootDir || findCommonAncestor(normalizedRouteFiles)
 
   const startSourceFiles = performance.now()
   // node_modules under rootDir (e.g. a locally-installed addon) is a
@@ -275,8 +285,9 @@ export const inspect = async (
   // First sweep: add all functions
   const startSetup = performance.now()
   for (const sourceFile of sourceFiles) {
+    const sourceOptions = { ...options, sourceFile }
     ts.forEachChild(sourceFile, (child) =>
-      visitSetup(logger, checker, child, state, options)
+      visitSetup(logger, checker, child, state, sourceOptions)
     )
   }
   logger.debug(
@@ -290,8 +301,9 @@ export const inspect = async (
     // Second sweep: add all transports
     const startRoutes = performance.now()
     for (const sourceFile of sourceFiles) {
+      const sourceOptions = { ...options, sourceFile }
       ts.forEachChild(sourceFile, (child) =>
-        visitRoutes(logger, checker, child, state, options)
+        visitRoutes(logger, checker, child, state, sourceOptions)
       )
     }
     logger.debug(

package/src/types.ts

@@ -1,5 +1,5 @@
 import type * as ts from 'typescript'
-import type { ChannelsMeta } from '@pikku/core/channel'
+import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel'
 import type { GatewaysMeta } from '@pikku/core/gateway'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
 import type { ScheduledTasksMeta } from '@pikku/core/scheduler'
@@ -13,6 +13,7 @@ import type {
 } from '@pikku/core/mcp'
 import type { AIAgentMeta } from '@pikku/core/ai-agent'
 import type { CLIMeta } from '@pikku/core/cli'
+import type { CLICommandMeta } from '@pikku/core/cli'
 import type { NodesMeta } from '@pikku/core/node'
 import type { SecretDefinitions } from '@pikku/core/secret'
 import type { CredentialDefinitions } from '@pikku/core/credential'
@@ -107,6 +108,67 @@ export interface InspectorChannelState {
   files: Set<string>
 }
 
+export interface ExportedHTTPRouteFunctionMeta {
+  pikkuFuncId: string
+  packageName?: string
+}
+
+export interface ExportedHTTPRouteConfigMeta {
+  method: string
+  route: string
+  func: ExportedHTTPRouteFunctionMeta
+  auth?: boolean
+  tags?: string[]
+  sse?: boolean
+  contentType?: string
+  timeout?: number
+  headers?: Record<string, string>
+}
+
+export interface ExportedHTTPRoutesGroupMeta {
+  basePath?: string
+  tags?: string[]
+  auth?: boolean
+  routes: ExportedHTTPRouteMapMeta
+}
+
+export type ExportedHTTPRouteEntryMeta =
+  | ExportedHTTPRouteConfigMeta
+  | ExportedHTTPRoutesGroupMeta
+  | ExportedHTTPRouteMapMeta
+
+export interface ExportedHTTPRouteMapMeta {
+  [key: string]: ExportedHTTPRouteEntryMeta
+}
+
+export type ExportedHTTPContractsMeta = Record<
+  string,
+  ExportedHTTPRoutesGroupMeta
+>
+
+export interface ExportedChannelRouteMeta extends ChannelMessageMeta {
+  auth?: boolean
+}
+
+export type ExportedChannelContractsMeta = Record<
+  string,
+  Record<string, ExportedChannelRouteMeta>
+>
+
+export type ExportedCLIContractsMeta = Record<
+  string,
+  Record<string, CLICommandMeta>
+>
+
+export interface InspectorExportedContractsState {
+  http: ExportedHTTPContractsMeta
+  cli: ExportedCLIContractsMeta
+  channel: ExportedChannelContractsMeta
+  addonHttp: Record<string, ExportedHTTPContractsMeta>
+  addonCli: Record<string, ExportedCLIContractsMeta>
+  addonChannel: Record<string, ExportedChannelContractsMeta>
+}
+
 export interface InspectorMiddlewareDefinition {
   services: FunctionServicesMeta
   wires?: FunctionWiresMeta
@@ -214,6 +276,7 @@ export type InspectorOptions = Partial<{
   setupOnly: boolean
   rootDir: string
   isAddon: boolean
+  sourceFile: ts.SourceFile
   types: Partial<{
     configFileType: string
     userSessionType: string
@@ -434,6 +497,11 @@ export interface InspectorState {
      *  codebase, if any. The CLI generates the `/auth/*` HTTP wiring from it.
      *  More than one `pikkuBetterAuth` is a critical error. */
     definition: AuthDefinition | null
+    /** True when a user (non-generated) file already registers
+     *  `betterAuthStatelessSession(...)`. The CLI then skips auto-generating its
+     *  own default-map stateless middleware, which would otherwise pre-empt the
+     *  user's custom mapSession (pikkujs/pikku#754). */
+    userStatelessSession?: boolean
   }
   secrets: {
     definitions: SecretDefinitions
@@ -485,5 +553,6 @@ export interface InspectorState {
   openAPISpec: Record<string, any> | null
   diagnostics: InspectorDiagnostic[]
   addonFunctions: Record<string, FunctionsMeta> // namespace -> addon's function metadata
+  exportedContracts: InspectorExportedContractsState
   program: ts.Program | null // Retained for incremental re-inspection
 }

package/src/utils/get-exported-variable-name.ts

@@ -0,0 +1,48 @@
+import * as ts from 'typescript'
+
+const isExportedVariableStatement = (
+  statement: ts.Statement
+): statement is ts.VariableStatement =>
+  ts.isVariableStatement(statement) &&
+  (statement.modifiers?.some(
+    (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword
+  ) ??
+    false)
+
+export const getExportedVariableName = (
+  node: ts.Node,
+  sourceFile: ts.SourceFile | undefined
+): string | null => {
+  if (!sourceFile) {
+    return null
+  }
+
+  if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+    for (const statement of sourceFile.statements) {
+      if (!isExportedVariableStatement(statement)) continue
+      for (const declaration of statement.declarationList.declarations) {
+        if (declaration === node) {
+          return node.name.text
+        }
+      }
+    }
+  }
+
+  if (!ts.isCallExpression(node)) {
+    return null
+  }
+
+  for (const statement of sourceFile.statements) {
+    if (!isExportedVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (
+        ts.isIdentifier(declaration.name) &&
+        declaration.initializer === node
+      ) {
+        return declaration.name.text
+      }
+    }
+  }
+
+  return null
+}

package/src/utils/load-addon-functions-meta.ts

@@ -2,6 +2,121 @@ import { readFile, readdir } from 'fs/promises'
 import { createRequire } from 'module'
 import { join, dirname } from 'path'
 import type { InspectorState, InspectorLogger } from '../types.js'
+import type {
+  ExportedChannelContractsMeta,
+  ExportedHTTPRouteConfigMeta,
+  ExportedHTTPRouteEntryMeta,
+  ExportedHTTPRoutesGroupMeta,
+  ExportedCLIContractsMeta,
+  ExportedHTTPContractsMeta,
+  ExportedHTTPRouteMapMeta,
+} from '../types.js'
+
+const isHTTPRouteConfig = (
+  value: ExportedHTTPRouteEntryMeta
+): value is ExportedHTTPRouteConfigMeta =>
+  typeof value === 'object' &&
+  value !== null &&
+  'method' in value &&
+  'func' in value &&
+  'route' in value
+
+const isHTTPRouteGroup = (
+  value: ExportedHTTPRouteEntryMeta
+): value is ExportedHTTPRoutesGroupMeta =>
+  typeof value === 'object' &&
+  value !== null &&
+  'routes' in value &&
+  !('method' in value)
+
+const applyPackageToHTTPRouteMap = (
+  routes: ExportedHTTPRouteMapMeta,
+  packageName: string,
+  namespace?: string
+) => {
+  for (const value of Object.values(routes)) {
+    if (!value || typeof value !== 'object') continue
+    if (isHTTPRouteConfig(value)) {
+      if (!value.func.packageName) {
+        value.func.packageName = packageName
+      }
+      if (namespace && !value.func.pikkuFuncId.includes(':')) {
+        value.func.pikkuFuncId = `${namespace}:${value.func.pikkuFuncId}`
+      }
+      continue
+    }
+    if (isHTTPRouteGroup(value)) {
+      applyPackageToHTTPRouteMap(value.routes, packageName, namespace)
+      continue
+    }
+    applyPackageToHTTPRouteMap(
+      value as ExportedHTTPRouteMapMeta,
+      packageName,
+      namespace
+    )
+  }
+}
+
+const applyPackageToHTTPContracts = (
+  contracts: ExportedHTTPContractsMeta,
+  packageName: string,
+  namespace: string
+) => {
+  for (const contract of Object.values(contracts)) {
+    applyPackageToHTTPRouteMap(contract.routes, packageName, namespace)
+  }
+}
+
+const applyPackageToCLICommands = (
+  commands: Record<string, any>,
+  packageName: string,
+  namespace?: string
+) => {
+  for (const command of Object.values(commands)) {
+    if (command && typeof command === 'object') {
+      if (!command.packageName && command.pikkuFuncId) {
+        command.packageName = packageName
+      }
+      if (
+        namespace &&
+        typeof command.pikkuFuncId === 'string' &&
+        !command.pikkuFuncId.includes(':')
+      ) {
+        command.pikkuFuncId = `${namespace}:${command.pikkuFuncId}`
+      }
+      if (command.subcommands) {
+        applyPackageToCLICommands(command.subcommands, packageName, namespace)
+      }
+    }
+  }
+}
+
+const applyPackageToCLIContracts = (
+  contracts: ExportedCLIContractsMeta,
+  packageName: string,
+  namespace: string
+) => {
+  for (const commands of Object.values(contracts)) {
+    applyPackageToCLICommands(commands, packageName, namespace)
+  }
+}
+
+const applyPackageToChannelContracts = (
+  contracts: ExportedChannelContractsMeta,
+  packageName: string,
+  namespace: string
+) => {
+  for (const routes of Object.values(contracts)) {
+    for (const route of Object.values(routes)) {
+      if (!route.packageName) {
+        route.packageName = packageName
+      }
+      if (!route.pikkuFuncId.includes(':')) {
+        route.pikkuFuncId = `${namespace}:${route.pikkuFuncId}`
+      }
+    }
+  }
+}
 
 /**
  * After the setup sweep discovers wireAddon() declarations, load each addon
@@ -104,6 +219,55 @@ export async function loadAddonFunctionsMeta(
       } catch {
         // No services gen — addon may not have requiredParentServices
       }
+
+      try {
+        const httpContractsPath = require.resolve(
+          `${decl.package}/.pikku/http/pikku-http-contracts-meta.gen.json`
+        )
+        const httpContractsRaw = await readFile(httpContractsPath, 'utf-8')
+        const httpContracts = JSON.parse(
+          httpContractsRaw
+        ) as ExportedHTTPContractsMeta
+        applyPackageToHTTPContracts(httpContracts, decl.package, namespace)
+        state.exportedContracts.addonHttp[namespace] = httpContracts
+      } catch {
+        // No addon HTTP contracts metadata
+      }
+
+      try {
+        const cliContractsPath = require.resolve(
+          `${decl.package}/.pikku/cli/pikku-cli-contracts-meta.gen.json`
+        )
+        const cliContractsRaw = await readFile(cliContractsPath, 'utf-8')
+        const cliContracts = JSON.parse(
+          cliContractsRaw
+        ) as ExportedCLIContractsMeta
+        applyPackageToCLIContracts(cliContracts, decl.package, namespace)
+        state.exportedContracts.addonCli[namespace] = cliContracts
+      } catch {
+        // No addon CLI contracts metadata
+      }
+
+      try {
+        const channelContractsPath = require.resolve(
+          `${decl.package}/.pikku/channel/pikku-channel-contracts-meta.gen.json`
+        )
+        const channelContractsRaw = await readFile(
+          channelContractsPath,
+          'utf-8'
+        )
+        const channelContracts = JSON.parse(
+          channelContractsRaw
+        ) as ExportedChannelContractsMeta
+        applyPackageToChannelContracts(
+          channelContracts,
+          decl.package,
+          namespace
+        )
+        state.exportedContracts.addonChannel[namespace] = channelContracts
+      } catch {
+        // No addon channel contracts metadata
+      }
     } catch (error: any) {
       logger.warn(
         `Failed to load addon function metadata for '${namespace}' (${decl.package}): ${error.message}`

package/src/utils/post-process.ts

@@ -317,9 +317,23 @@ export function aggregateRequiredServices(
     requiredServices.add('eventHub')
   }
 
-  // 7. Services that addons need from the parent project
-  for (const service of state.addonRequiredParentServices ?? []) {
-    requiredServices.add(service)
+  // 7. Services that consumed addons need from the parent project.
+  // These are required ONLY by units that actually deploy an addon function;
+  // a unit that merely calls the addon over RPC (or never touches it) must not
+  // carry them, or every per-unit bundle would over-include the addon's
+  // parent-service dependencies (e.g. aiAgentRunner, deploymentService) and
+  // defeat per-unit tree-shaking.
+  const addonFuncIds = new Set<string>()
+  for (const fns of Object.values(state.addonFunctions ?? {})) {
+    for (const id of Object.keys(fns)) addonFuncIds.add(id)
+  }
+  const unitDeploysAddonFn = [...usedFunctions].some((fn) =>
+    addonFuncIds.has(fn)
+  )
+  if (unitDeploysAddonFn) {
+    for (const service of state.addonRequiredParentServices ?? []) {
+      requiredServices.add(service)
+    }
   }
 }
 

package/src/utils/resolve-addon-package.ts

@@ -80,7 +80,12 @@ export const resolveAddonName = (
   // Bare package import path
   if (candidatePackage && !candidatePackage.startsWith('.')) {
     for (const addonDecl of wireAddonDeclarations.values()) {
-      if (addonDecl.package === candidatePackage) return addonDecl.package
+      if (
+        addonDecl.package === candidatePackage ||
+        candidatePackage.startsWith(`${addonDecl.package}/`)
+      ) {
+        return addonDecl.package
+      }
     }
   }