@pikku/inspector 0.12.41 → 0.12.43

package/src/add/inline-wiring-function.test.ts

@@ -0,0 +1,104 @@
+import { strict as assert } from '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 type { ErrorCode, InspectorLogger } from '../types.js'
+
+const silentLogger = (): InspectorLogger => ({
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  diagnostic: () => {},
+  critical: (_code: ErrorCode, _message: string) => {},
+  hasCriticalErrors: () => false,
+})
+
+// A `func:` inlined into a wiring has no exported name, so addFunctions skips
+// it and only the wiring's context-based id exists. The wiring visitor must
+// register the function metadata under that id (via ensureInlineWiringFunction)
+// or the transport resolves to nothing at runtime ("Missing generated metadata
+// for ...") and, once registered, every invocation would 403 unless the
+// sessionless flag is carried across from the helper used.
+const WIRINGS = [
+  {
+    label: 'wireQueueWorker',
+    wire: 'wireQueueWorker',
+    props: "name: 'inline-queue',",
+    expectedId: 'queue:inline-queue',
+  },
+  {
+    label: 'wireScheduler',
+    wire: 'wireScheduler',
+    props: "name: 'inline-cron', schedule: '* * * * *',",
+    expectedId: 'scheduler:inline-cron',
+  },
+  {
+    label: 'wireTrigger',
+    wire: 'wireTrigger',
+    props: "name: 'inline-trigger',",
+    expectedId: 'trigger:inline-trigger',
+  },
+  {
+    label: 'wireGateway',
+    wire: 'wireGateway',
+    props: "name: 'inline-gw', type: 'slack',",
+    expectedId: 'gateway:inline-gw',
+  },
+]
+
+const write = (wire: string, props: string, helper: string) =>
+  [
+    `import { ${helper}, ${wire} } from '@pikku/core'`,
+    `${wire}({`,
+    `  ${props}`,
+    `  func: ${helper}<{ url: string }, void>({ func: async () => {} }),`,
+    '})',
+  ].join('\n')
+
+describe('inline wiring functions register metadata', () => {
+  for (const { label, wire, props, expectedId } of WIRINGS) {
+    test(`${label} registers a sessionless func inlined into it`, async () => {
+      const rootDir = await mkdtemp(join(tmpdir(), 'pikku-inline-'))
+      const file = join(rootDir, 'wire.ts')
+      await writeFile(file, write(wire, props, 'pikkuSessionlessFunc'))
+
+      try {
+        const state = await inspect(silentLogger(), [file], { rootDir })
+        const funcMeta = state.functions.meta[expectedId]
+        assert.ok(
+          funcMeta,
+          `${label}: metadata must exist under the id the wiring references`
+        )
+        assert.equal(
+          funcMeta!.sessionless,
+          true,
+          `${label}: pikkuSessionlessFunc must stay sessionless when inlined`
+        )
+      } finally {
+        await rm(rootDir, { recursive: true, force: true })
+      }
+    })
+
+    test(`${label} keeps an inlined pikkuFunc session-required`, async () => {
+      const rootDir = await mkdtemp(join(tmpdir(), 'pikku-inline-auth-'))
+      const file = join(rootDir, 'wire.ts')
+      await writeFile(file, write(wire, props, 'pikkuFunc'))
+
+      try {
+        const state = await inspect(silentLogger(), [file], { rootDir })
+        const funcMeta = state.functions.meta[expectedId]
+        assert.ok(funcMeta, `${label}: metadata must exist`)
+        assert.equal(
+          funcMeta!.sessionless,
+          false,
+          `${label}: pikkuFunc must not be marked sessionless`
+        )
+      } finally {
+        await rm(rootDir, { recursive: true, force: true })
+      }
+    })
+  }
+})

package/src/add/validate-workflow-graph-addons.test.ts

@@ -0,0 +1,102 @@
+import { strict as assert } from '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 type { InspectorLogger } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+function makeLogger(
+  criticals: Array<{ code: string; message: string }>
+): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: (code, message) => criticals.push({ code, message }),
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+}
+
+describe('validateWorkflowGraphAddons', () => {
+  test('a graph node referencing graph: without @pikku/addon-graph wired raises PKU642', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-addon-'))
+    const stepFile = join(rootDir, 'my.steps.ts')
+    const graphFile = join(rootDir, 'my.graph.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const notify = pikkuSessionlessFunc({ func: async () => ({ sent: true }) })',
+      ].join('\n')
+    )
+    await writeFile(
+      graphFile,
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'my-graph',",
+        '  nodes: {',
+        "    setFields: 'graph:editFields',",
+        "    notify: 'notify',",
+        '  },',
+        "  config: { setFields: { next: 'notify' }, notify: {} },",
+        '})',
+      ].join('\n')
+    )
+
+    try {
+      const criticals: Array<{ code: string; message: string }> = []
+      await inspect(makeLogger(criticals), [stepFile, graphFile], { rootDir })
+      const hit = criticals.find(
+        (c) => c.code === ErrorCode.WORKFLOW_GRAPH_ADDON_NOT_WIRED
+      )
+      assert.ok(hit, 'expected a WORKFLOW_GRAPH_ADDON_NOT_WIRED critical')
+      assert.match(hit!.message, /@pikku\/addon-graph is not wired/)
+      assert.match(hit!.message, /scaffold/)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('a graph with only user RPCs raises no addon-graph critical', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-addon-ok-'))
+    const stepFile = join(rootDir, 'my.steps.ts')
+    const graphFile = join(rootDir, 'my.graph.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const assess = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+        'export const notify = pikkuSessionlessFunc({ func: async () => ({ sent: true }) })',
+      ].join('\n')
+    )
+    await writeFile(
+      graphFile,
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'my-graph',",
+        "  nodes: { assess: 'assess', notify: 'notify' },",
+        "  config: { assess: { next: 'notify' }, notify: {} },",
+        '})',
+      ].join('\n')
+    )
+
+    try {
+      const criticals: Array<{ code: string; message: string }> = []
+      await inspect(makeLogger(criticals), [stepFile, graphFile], { rootDir })
+      const hit = criticals.find(
+        (c) => c.code === ErrorCode.WORKFLOW_GRAPH_ADDON_NOT_WIRED
+      )
+      assert.equal(hit, undefined, 'no addon-graph critical expected')
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/error-codes.ts

@@ -24,6 +24,11 @@ export enum ErrorCode {
   EXPECT_EVENTUALLY_SCENARIO_ONLY = 'PKU675',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',
+  WORKFLOW_GRAPH_ADDON_NOT_WIRED = 'PKU642',
+
+  // Remote addon (wireRemoteAddon) validation
+  REMOTE_ADDON_NOT_DEV_DEPENDENCY = 'PKU338',
+  REMOTE_ADDON_AUTH_UNRESOLVED = 'PKU339',
 
   // Database schema codegen warnings
   DB_COLUMN_NAME_TYPE_CONTRADICTION = 'PKU480',

package/src/inspector.ts

@@ -10,6 +10,7 @@ import type {
 } from './types.js'
 import { getFilesAndMethods } from './utils/get-files-and-methods.js'
 import { findCommonAncestor } from './utils/find-root-dir.js'
+import { createNestedProjectFilter } from './utils/nested-project-filter.js'
 import {
   aggregateRequiredServices,
   stampAuthHandlerServices,
@@ -17,12 +18,16 @@ import {
   validateSecretOverrides,
   validateVariableOverrides,
   validateCredentialOverrides,
+  validateRemoteAddonDependencies,
+  validateRemoteAddonAuth,
+  validateScopeReferences,
   computeResolvedIOTypes,
   computeMiddlewareGroupsMeta,
   computePermissionsGroupsMeta,
   computeRequiredSchemas,
   computeDiagnostics,
   validateSchemaWiringSeparation,
+  validateWorkflowGraphAddons,
 } from './utils/post-process.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
 import { pikkuState } from '@pikku/core/internal'
@@ -89,7 +94,6 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       },
       files: new Set(),
       routeMiddleware: new Map(),
-      routePermissions: new Map(),
     },
     channels: {
       files: new Set(),
@@ -124,6 +128,8 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       internalFiles: new Map(),
       exposedMeta: {},
       exposedFiles: new Map(),
+      remoteMeta: {},
+      remoteFiles: new Map(),
       invokedFunctions: new Set(),
       invokedFunctionsByFile: new Map(),
       usedAddons: new Set(),
@@ -165,6 +171,10 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       definitions: [],
       files: new Set(),
     },
+    scopes: {
+      definitions: [],
+      files: new Set(),
+    },
     variables: {
       definitions: [],
       files: new Set(),
@@ -190,7 +200,6 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     permissions: {
       definitions: {},
       instances: {},
-      tagPermissions: new Map(),
     },
     serviceAggregation: {
       requiredServices: new Set(),
@@ -214,8 +223,6 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     },
     permissionsGroupsMeta: {
       definitions: {},
-      httpGroups: {},
-      tagGroups: {},
     },
     requiredSchemas: new Set(),
     openAPISpec: null,
@@ -272,19 +279,24 @@ export const inspect = async (
   const startSourceFiles = performance.now()
   // node_modules under rootDir (e.g. a locally-installed addon) is a
   // dependency, not project source — scanning it double-counts the addon's
-  // own application types (CoreConfig/Services/SingletonServices).
+  // own application types (CoreConfig/Services/SingletonServices). Nested
+  // pikku projects (a workspace addon at packages/<addon>) are the same case:
+  // TS resolves the node_modules symlink to its realpath under rootDir, so
+  // the node_modules check alone misses them.
   // Sort by file name so the sweeps populate state in a stable order. The
   // program's own file order depends on glob + import-graph resolution, which
   // varies run to run — leaving generated meta keys (and anything serialized
   // in insertion order) non-reproducible across identical `pikku all` runs.
   // Safe because function registration is a dedicated pass (visitFunctions)
   // that completes before any order-sensitive wiring resolution in visitRoutes.
+  const isNestedProjectFile = createNestedProjectFilter(rootDir)
   const sourceFiles = program
     .getSourceFiles()
     .filter(
       (sf) =>
         sf.fileName.startsWith(rootDir) &&
-        !sf.fileName.includes('/node_modules/')
+        !sf.fileName.includes('/node_modules/') &&
+        !isNestedProjectFile(sf.fileName)
     )
     .sort((a, b) =>
       a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0
@@ -394,6 +406,7 @@ export const inspect = async (
     computePermissionsGroupsMeta(state)
     computeDiagnostics(state)
     validateSchemaWiringSeparation(logger, state)
+    validateWorkflowGraphAddons(logger, state)
 
     if (options.openAPI) {
       state.openAPISpec = await generateOpenAPISpec(
@@ -410,6 +423,9 @@ export const inspect = async (
     validateSecretOverrides(logger, state)
     validateVariableOverrides(logger, state)
     validateCredentialOverrides(logger, state)
+    validateRemoteAddonDependencies(logger, state)
+    validateRemoteAddonAuth(logger, state)
+    validateScopeReferences(logger, state)
   }
 
   state.program = program

package/src/types.ts

@@ -17,6 +17,7 @@ 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'
+import type { ScopeDefinitions } from '@pikku/core/scope'
 import type { VariableDefinitions } from '@pikku/core/variable'
 import type { TypesMap } from './types-map.js'
 import type {
@@ -57,16 +58,6 @@ export interface MiddlewareGroupMeta {
   isFactory: boolean // true if wrapped in () => add...()
 }
 
-export interface PermissionGroupMeta {
-  exportName: string | null // null if not exported
-  sourceFile: string
-  position: number
-  services: FunctionServicesMeta
-  count: number
-  instanceIds: string[]
-  isFactory: boolean // true if wrapped in () => add...()
-}
-
 export interface InspectorHTTPState {
   metaInputTypes: MetaInputTypes
   meta: HTTPWiringsMeta
@@ -75,10 +66,6 @@ export interface InspectorHTTPState {
   // Pattern '*' matches all routes (from addHTTPMiddleware('*', [...]))
   // Pattern '/api/*' matches specific routes (from addHTTPMiddleware('/api/*', [...]))
   routeMiddleware: Map<string, MiddlewareGroupMeta>
-  // HTTP permission calls tracking - route pattern -> group metadata
-  // Pattern '*' matches all routes (from addHTTPPermission('*', [...]))
-  // Pattern '/api/*' matches specific routes (from addHTTPPermission('/api/*', [...]))
-  routePermissions: Map<string, PermissionGroupMeta>
 }
 
 /**
@@ -241,7 +228,6 @@ export interface InspectorPermissionInstance {
 export interface InspectorPermissionState {
   definitions: Record<string, InspectorPermissionDefinition>
   instances: Record<string, InspectorPermissionInstance>
-  tagPermissions: Map<string, PermissionGroupMeta>
 }
 
 export type InspectorFilters = {
@@ -487,6 +473,9 @@ export interface InspectorState {
     internalFiles: Map<string, { path: string; exportedName: string }>
     exposedMeta: Record<string, string>
     exposedFiles: Map<string, { path: string; exportedName: string }>
+    /** Functions marked `remote: true` — the surface a wireRemoteAddon consumer imports */
+    remoteMeta: Record<string, string>
+    remoteFiles: Map<string, { path: string; exportedName: string }>
     invokedFunctions: Set<string>
     invokedFunctionsByFile: Map<string, Set<string>>
     usedAddons: Set<string>
@@ -496,6 +485,14 @@ export interface InspectorState {
         package: string
         rpcEndpoint?: string
         mcp?: boolean
+        /** True when declared via `wireRemoteAddon` — import the addon's `.remote.gen` map, not `.internal.gen` */
+        remote?: boolean
+        /** wireRemoteAddon: whether an `auth` binding was supplied (vs a public surface) */
+        hasAuth?: boolean
+        /** wireRemoteAddon: statically-known `auth.credentialId`, for verify */
+        authCredentialId?: string
+        /** wireRemoteAddon: statically-known `auth.secretId`, for verify */
+        authSecretId?: string
         secretOverrides?: Record<string, string>
         variableOverrides?: Record<string, string>
         credentialOverrides?: Record<string, string>
@@ -549,6 +546,10 @@ export interface InspectorState {
     definitions: CredentialDefinitions
     files: Set<string>
   }
+  scopes: {
+    definitions: ScopeDefinitions
+    files: Set<string>
+  }
   variables: {
     definitions: VariableDefinitions
     files: Set<string>
@@ -584,8 +585,6 @@ export interface InspectorState {
   }
   permissionsGroupsMeta: {
     definitions: Record<string, InspectorPermissionDefinition>
-    httpGroups: Record<string, PermissionGroupMeta>
-    tagGroups: Record<string, PermissionGroupMeta>
   }
   requiredSchemas: Set<string>
   openAPISpec: Record<string, any> | null

package/src/utils/custom-types-generator.test.ts

@@ -1,6 +1,9 @@
 import { test, describe } from 'node:test'
 import { strict as assert } from 'node:assert'
-import { generateCustomTypes } from './custom-types-generator.js'
+import {
+  generateCustomTypes,
+  sanitizeTypeName,
+} from './custom-types-generator.js'
 import { TypesMap } from '../types-map.js'
 
 function makeTypesMap(
@@ -97,3 +100,25 @@ describe('generateCustomTypes — classification wrapper stripping', () => {
     )
   })
 })
+
+describe('sanitizeTypeName — valid JS identifier', () => {
+  test('replaces disallowed characters with underscores', () => {
+    assert.equal(
+      sanitizeTypeName('Add Beehiiv subscribers'),
+      'Add_Beehiiv_subscribers'
+    )
+  })
+
+  test('prefixes an underscore when the name starts with a digit', () => {
+    // A name like "2. Add Beehiiv newsletter subscribers" otherwise produces
+    // `2__Add_...`, an invalid JS identifier that breaks the generated
+    // `import <ident> from ...` in pikku-workflow-wirings-meta.gen.ts.
+    const id = sanitizeTypeName('2. Add Beehiiv newsletter subscribers')
+    assert.equal(id, '_2__Add_Beehiiv_newsletter_subscribers')
+    assert.match(id, /^[A-Za-z_$]/, 'must start with a valid identifier char')
+  })
+
+  test('leaves an already-valid identifier unchanged', () => {
+    assert.equal(sanitizeTypeName('UserEmail'), 'UserEmail')
+  })
+})

package/src/utils/custom-types-generator.ts

@@ -8,7 +8,8 @@ import type { TypesMap } from '../types-map.js'
  */
 
 export function sanitizeTypeName(name: string): string {
-  return name.replace(/[^a-zA-Z0-9_$]/g, '_')
+  const sanitized = name.replace(/[^a-zA-Z0-9_$]/g, '_')
+  return /^[0-9]/.test(sanitized) ? `_${sanitized}` : sanitized
 }
 
 const CLASSIFICATION_WRAPPERS = new Set(['Private', 'Pii', 'Secret'])

package/src/utils/ensure-function-metadata.ts

@@ -309,6 +309,48 @@ export function ensureFunctionMetadata(
   }
 }
 
+/**
+ * Register metadata for a `func:` inlined into a wiring (queue/scheduler/
+ * trigger/gateway/…).
+ *
+ * An inline function has no exported name, so `addFunctions` skips it (it bails
+ * on `__temp_` ids) and only the wiring's context-based id exists. Without this
+ * the wiring points at a function that was never registered and the worker
+ * resolves to nothing at runtime ("Missing generated metadata for ...").
+ *
+ * The stub also carries no session info, so the runtime would treat it as
+ * session-required and every invocation would fail with "Authentication
+ * required". Derive `sessionless` from the helper the function was built with —
+ * the same rule `addFunctions` applies to named ones (`!== 'pikkuFunc'`).
+ */
+export function ensureInlineWiringFunction(
+  state: InspectorState,
+  pikkuFuncId: string,
+  fallbackName: string | undefined,
+  funcInitializer: ts.Node,
+  checker: ts.TypeChecker,
+  isHelper?: boolean
+): void {
+  ensureFunctionMetadata(
+    state,
+    pikkuFuncId,
+    fallbackName,
+    funcInitializer,
+    checker,
+    isHelper
+  )
+
+  const meta = state.functions.meta[pikkuFuncId]
+  if (
+    meta &&
+    meta.sessionless === undefined &&
+    ts.isCallExpression(funcInitializer) &&
+    ts.isIdentifier(funcInitializer.expression)
+  ) {
+    meta.sessionless = funcInitializer.expression.text !== 'pikkuFunc'
+  }
+}
+
 function populateTypesLookup(
   state: InspectorState,
   pikkuFuncId: string,

package/src/utils/filter-inspector-state.test.ts

@@ -82,7 +82,6 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
       },
       files: new Set(['/test/project/src/api/users.ts']),
       routeMiddleware: new Map(),
-      routePermissions: new Map(),
     },
     functions: {
       typesMap: new Map(),
@@ -332,7 +331,6 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
     permissions: {
       definitions: {},
       instances: {},
-      tagPermissions: new Map(),
     },
     serviceAggregation: {
       requiredServices: new Set(),

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

@@ -425,6 +425,8 @@ export function filterInspectorState(
       internalFiles: new Map(state.rpc.internalFiles),
       exposedMeta: { ...state.rpc.exposedMeta },
       exposedFiles: new Map(state.rpc.exposedFiles),
+      remoteMeta: { ...state.rpc.remoteMeta },
+      remoteFiles: new Map(state.rpc.remoteFiles),
       invokedFunctions: new Set(state.rpc.invokedFunctions),
     },
     cli: {
@@ -1052,6 +1054,13 @@ export function filterInspectorState(
         filteredState.rpc.exposedFiles.delete(key)
       }
     }
+    for (const key of Object.keys(filteredState.rpc.remoteMeta)) {
+      const targetFuncId = filteredState.rpc.remoteMeta[key]
+      if (!survivingFuncIds.has(targetFuncId) && !survivingFuncIds.has(key)) {
+        delete filteredState.rpc.remoteMeta[key]
+        filteredState.rpc.remoteFiles.delete(key)
+      }
+    }
     // Prune invokedFunctions to match surviving functions
     for (const funcId of filteredState.rpc.invokedFunctions) {
       if (!survivingFuncIds.has(funcId)) {