@pikku/inspector 0.12.22 → 0.12.23

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

@@ -0,0 +1,121 @@
+import { strict as assert } from 'node:assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+const recordingLogger = () => {
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  const logger: InspectorLogger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    critical: (code, message) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+  return { logger, criticals }
+}
+
+const withTempApp = async (
+  source: string,
+  run: (file: string, rootDir: string) => Promise<void>
+) => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-addon-bans-'))
+  const file = join(rootDir, 'app.ts')
+  await writeFile(
+    join(rootDir, 'package.json'),
+    JSON.stringify({ name: 'test-addon', type: 'module' }, null, 2)
+  )
+  await writeFile(file, source)
+  try {
+    await run(file, rootDir)
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('addon authoring bans', () => {
+  const wireHTTPSource = [
+    "import { wireHTTP } from '@pikku/core/http'",
+    "import { pikkuSessionlessFunc } from '@pikku/core'",
+    'const f = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+    "wireHTTP({ method: 'get', route: '/a', func: f })",
+  ].join('\n')
+
+  const defineWithMiddlewareSource = [
+    "import { defineHTTPRoutes } from '@pikku/core/http'",
+    "import { pikkuSessionlessFunc } from '@pikku/core'",
+    'const f = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+    'const mw = (async (_s: any, _w: any, next: any) => next()) as any',
+    "export const routes = defineHTTPRoutes({ basePath: '/x', routes: { a: { method: 'get', route: '/a', func: f, middleware: [mw] } } })",
+  ].join('\n')
+
+  test('wire* inside an addon is a critical error', async () => {
+    await withTempApp(wireHTTPSource, async (file, rootDir) => {
+      const { logger, criticals } = recordingLogger()
+      await inspect(logger, [file], { rootDir, isAddon: true })
+      assert.ok(
+        criticals.some((c) => c.code === ErrorCode.ADDON_WIRING_NOT_ALLOWED),
+        `expected ADDON_WIRING_NOT_ALLOWED, got ${JSON.stringify(criticals)}`
+      )
+    })
+  })
+
+  test('wire* outside an addon is allowed', async () => {
+    await withTempApp(wireHTTPSource, async (file, rootDir) => {
+      const { logger, criticals } = recordingLogger()
+      await inspect(logger, [file], { rootDir })
+      assert.ok(
+        !criticals.some((c) => c.code === ErrorCode.ADDON_WIRING_NOT_ALLOWED),
+        `expected no addon-wiring ban, got ${JSON.stringify(criticals)}`
+      )
+    })
+  })
+
+  test('define* carrying middleware inside an addon is a critical error', async () => {
+    await withTempApp(defineWithMiddlewareSource, async (file, rootDir) => {
+      const { logger, criticals } = recordingLogger()
+      await inspect(logger, [file], { rootDir, isAddon: true })
+      assert.ok(
+        criticals.some(
+          (c) => c.code === ErrorCode.ADDON_CONTRACT_HANDLERS_NOT_ALLOWED
+        ),
+        `expected ADDON_CONTRACT_HANDLERS_NOT_ALLOWED, got ${JSON.stringify(criticals)}`
+      )
+    })
+  })
+
+  test('define* carrying middleware outside an addon is allowed', async () => {
+    await withTempApp(defineWithMiddlewareSource, async (file, rootDir) => {
+      const { logger, criticals } = recordingLogger()
+      await inspect(logger, [file], { rootDir })
+      assert.ok(
+        !criticals.some(
+          (c) => c.code === ErrorCode.ADDON_CONTRACT_HANDLERS_NOT_ALLOWED
+        ),
+        `expected no contract-handlers ban, got ${JSON.stringify(criticals)}`
+      )
+    })
+  })
+
+  test('wireSecret inside an addon is allowed', async () => {
+    const source = [
+      "import { wireSecret } from '@pikku/core'",
+      "wireSecret({ name: 'example', secretId: 'EXAMPLE' } as any)",
+    ].join('\n')
+    await withTempApp(source, async (file, rootDir) => {
+      const { logger, criticals } = recordingLogger()
+      await inspect(logger, [file], { rootDir, isAddon: true })
+      assert.ok(
+        !criticals.some((c) => c.code === ErrorCode.ADDON_WIRING_NOT_ALLOWED),
+        `expected wireSecret to be allowed, got ${JSON.stringify(criticals)}`
+      )
+    })
+  })
+})

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
@@ -485,5 +548,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
+}