@pikku/inspector 0.12.49 → 0.12.52

package/src/add/add-functions.test.ts

@@ -1,6 +1,6 @@
 import { strict as assert } from 'assert'
 import { describe, test } from 'node:test'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { inspect } from '../inspector.js'
@@ -381,3 +381,265 @@ describe('pikkuChannelConnectionFunc generic mapping', () => {
     }
   })
 })
+
+describe('pikkuRemoteChannelFunc', () => {
+  const quietLogger = (): InspectorLogger & {
+    errors: string[]
+    criticals: Array<{ code: ErrorCode; message: string }>
+  } => {
+    const errors: string[] = []
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    return {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: (message: string) => {
+        errors.push(message)
+      },
+      diagnostic: ({ code, message }) => {
+        criticals.push({ code, message })
+      },
+      critical: (code: ErrorCode, message: string) => {
+        criticals.push({ code, message })
+      },
+      hasCriticalErrors: () => criticals.length > 0,
+      errors,
+      criticals,
+    } as any
+  }
+
+  /**
+   * The vendor check keys off the declaration file's path, so a stub under
+   * `node_modules/zod` is indistinguishable from the real thing and costs this
+   * suite no dependency.
+   */
+  const writeZodStub = async (rootDir: string) => {
+    const dir = join(rootDir, 'node_modules', 'zod')
+    await mkdir(dir, { recursive: true })
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: 'zod', version: '3.0.0', types: 'index.d.ts' })
+    )
+    await writeFile(
+      join(dir, 'index.d.ts'),
+      [
+        'export interface ZodType<Output = unknown> {',
+        '  _output: Output',
+        '}',
+        'export declare const z: {',
+        '  object(shape: Record<string, ZodType>): ZodType<Record<string, unknown>>',
+        '  string(): ZodType<string>',
+        '}',
+        '',
+      ].join('\n')
+    )
+  }
+
+  const DECLARE_WRAPPER = [
+    "import { z } from 'zod'",
+    'declare function pikkuRemoteChannelFunc(config: any): any',
+    'declare function pikkuSessionlessFunc(config: any): any',
+  ]
+
+  const withProject = async (
+    label: string,
+    files: Record<string, string[]>,
+    assertions: (
+      state: Awaited<ReturnType<typeof inspect>>,
+      logger: ReturnType<typeof quietLogger>
+    ) => void
+  ) => {
+    const rootDir = await mkdtemp(join(tmpdir(), `pikku-${label}-`))
+    await writeZodStub(rootDir)
+    const paths: string[] = []
+    for (const [name, lines] of Object.entries(files)) {
+      const path = join(rootDir, name)
+      await writeFile(path, [...DECLARE_WRAPPER, ...lines, ''].join('\n'))
+      paths.push(path)
+    }
+    const logger = quietLogger()
+    try {
+      assertions(await inspect(logger, paths, { rootDir }), logger)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  }
+
+  test('a declaration with no func is registered rather than rejected', async () => {
+    await withProject(
+      'remote-channel-registers',
+      {
+        'capabilities.ts': [
+          'export const localCheckoutOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          "  title: 'localCheckout',",
+          "  description: 'Read the current commit of your working tree',",
+          '  output: localCheckoutOutput,',
+          '})',
+        ],
+      },
+      (state, logger) => {
+        // The ordinary path logs "No valid 'func' property" for a config with
+        // no callable func, which is what a contract-only declaration is.
+        assert.deepStrictEqual(logger.errors, [])
+        assert.deepStrictEqual(logger.criticals, [])
+
+        const meta = state.functions.meta['localCheckout']
+        assert.ok(meta, 'the declaration should be registered')
+        assert.strictEqual(meta!.functionType, 'remote')
+        assert.strictEqual(meta!.funcWrapper, 'pikkuRemoteChannelFunc')
+        assert.strictEqual(
+          meta!.description,
+          'Read the current commit of your working tree'
+        )
+      }
+    )
+  })
+
+  test('the declared schemas are what each side gets checked against', async () => {
+    await withProject(
+      'remote-channel-schemas',
+      {
+        'capabilities.ts': [
+          'export const runCommandInput = z.object({ argv: z.string() })',
+          'export const runCommandOutput = z.object({ stdout: z.string() })',
+          'export const runCommand = pikkuRemoteChannelFunc({',
+          '  input: runCommandInput,',
+          '  output: runCommandOutput,',
+          '})',
+        ],
+      },
+      (state) => {
+        const meta = state.functions.meta['runCommand']
+        assert.strictEqual(meta!.inputSchemaName, 'RunCommandInput')
+        assert.strictEqual(meta!.outputSchemaName, 'RunCommandOutput')
+        assert.deepStrictEqual(meta!.outputs, ['RunCommandOutput'])
+        assert.strictEqual(
+          state.schemaLookup.get('RunCommandOutput')?.variableName,
+          'runCommandOutput'
+        )
+      }
+    )
+  })
+
+  test('the name resolves through the RPC map, which is what channel.remote reads', async () => {
+    await withProject(
+      'remote-channel-rpc-map',
+      {
+        'capabilities.ts': [
+          'export const localCheckoutOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: localCheckoutOutput,',
+          '})',
+        ],
+      },
+      (state) => {
+        // Both validators look the name up here and skip validation on a miss,
+        // so an unregistered name silently disables the schema check.
+        assert.strictEqual(
+          state.rpc.internalMeta['localCheckout'],
+          'localCheckout'
+        )
+        // Imported, so a local call reaches the factory's thrower rather than
+        // missing the registry.
+        assert.strictEqual(
+          state.rpc.internalFiles.get('localCheckout')?.exportedName,
+          'localCheckout'
+        )
+      }
+    )
+  })
+
+  test('an unexported declaration is skipped, the way any unexported function is', async () => {
+    await withProject(
+      'remote-channel-unexported',
+      {
+        'capabilities.ts': [
+          'const localCheckoutOutput = z.object({ sha: z.string() })',
+          'const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: localCheckoutOutput,',
+          '})',
+          'void localCheckout',
+        ],
+      },
+      (state) => {
+        // No export and no `override` leaves nothing to name it by, so it is
+        // dropped upstream and never reaches the remote-channel path.
+        assert.strictEqual(state.rpc.internalMeta['localCheckout'], undefined)
+        assert.strictEqual(state.functions.meta['localCheckout'], undefined)
+      }
+    )
+  })
+
+  test('a name claimed by override still has to be exported for the server to import it', async () => {
+    await withProject(
+      'remote-channel-override-unexported',
+      {
+        'capabilities.ts': [
+          'const localCheckoutOutput = z.object({ sha: z.string() })',
+          'const localCheckout = pikkuRemoteChannelFunc({',
+          "  override: 'localCheckout',",
+          '  output: localCheckoutOutput,',
+          '})',
+          'void localCheckout',
+        ],
+      },
+      (state, logger) => {
+        assert.strictEqual(
+          logger.errors.length,
+          1,
+          `expected one error, got ${JSON.stringify(logger.errors)}`
+        )
+        assert.match(logger.errors[0]!, /not exported/)
+        assert.strictEqual(state.rpc.internalMeta['localCheckout'], undefined)
+      }
+    )
+  })
+
+  test('two capabilities cannot share a name', async () => {
+    await withProject(
+      'remote-channel-duplicate',
+      {
+        'a.ts': [
+          'export const aOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: aOutput,',
+          '})',
+        ],
+        'b.ts': [
+          'export const bOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: bOutput,',
+          '})',
+        ],
+      },
+      (_state, logger) => {
+        const collision = logger.criticals.find(
+          (entry) => entry.code === ErrorCode.DUPLICATE_FUNCTION_NAME
+        )
+        assert.ok(collision, 'a name collision should be reported')
+        assert.match(collision!.message, /not unique/)
+      }
+    )
+  })
+
+  test('the ordinary path still rejects a config with no callable func', async () => {
+    await withProject(
+      'remote-channel-ordinary-path',
+      {
+        'capabilities.ts': [
+          'export const broken = pikkuSessionlessFunc({ auth: false })',
+        ],
+      },
+      (state, logger) => {
+        assert.strictEqual(
+          logger.errors.length,
+          1,
+          `expected one error, got ${JSON.stringify(logger.errors)}`
+        )
+        assert.match(logger.errors[0]!, /No valid 'func' property/)
+        assert.strictEqual(state.functions.meta['broken']?.functionType, 'user')
+      }
+    )
+  })
+})

package/src/add/add-functions.ts

@@ -9,7 +9,28 @@ import {
 import { extractFunctionNode } from '../utils/extract-function-node.js'
 import { extractUsedWires } from '../utils/extract-services.js'
 import type { FunctionServicesMeta } from '@pikku/core'
+import type { ScenarioStepKind, ScenarioSurface } from '@pikku/core/workflow'
 import { formatVersionedId, parseVersionedId } from '@pikku/core'
+
+/** Binding keys a `pikkuScenarioStep` may declare, in report order. */
+const SCENARIO_SURFACE_KEYS: readonly ScenarioSurface[] = [
+  'browser',
+  'cli',
+  'default',
+]
+
+/**
+ * The step wrappers, and who acts in each.
+ *
+ * Which function was called *is* the kind. That is the whole reason these are
+ * three declarations rather than a `kind:` field on one: a string literal can be
+ * copied into an addon package by a consumer, a called identifier cannot.
+ */
+const SCENARIO_STEP_KINDS = new Map<string, ScenarioStepKind>([
+  ['pikkuScenarioStep', 'persona'],
+  ['pikkuPlatformScenarioStep', 'platform'],
+  ['pikkuAddonScenarioStep', 'addon'],
+])
 import {
   getPropertyValue,
   getArrayPropertyValue,
@@ -366,6 +387,112 @@ function computeImplementationHash(args: {
   )
 }
 
+/**
+ * Registers a `pikkuRemoteChannelFunc` declaration: a name, its schemas and its
+ * description, with no body to inspect. The name has to reach `rpc.internalMeta`
+ * for `channel.remote` to resolve the schemas it validates each call against.
+ */
+const addRemoteChannelFunc = ({
+  state,
+  logger,
+  node,
+  pikkuFuncId,
+  name,
+  exportedName,
+  inputSchemaRef,
+  outputSchemaRef,
+  meta,
+}: {
+  state: InspectorState
+  logger: Parameters<AddWiring>[0]
+  node: ts.CallExpression
+  pikkuFuncId: string
+  name: string
+  exportedName?: string | null
+  inputSchemaRef: SchemaRef | null
+  outputSchemaRef: SchemaRef | null
+  meta: {
+    version?: number
+    title?: string
+    tags?: string[]
+    summary?: string
+    description?: string
+    errors?: string[]
+  }
+}) => {
+  const sourceFile = node.getSourceFile().fileName
+
+  if (!exportedName) {
+    logger.error(
+      `• Remote channel function '${name}' is not exported, this is not allowed.`
+    )
+    return
+  }
+
+  // Two files declaring the same capability is the collision that matters:
+  // both ids are the bare name, so the id-compatibility check below reads them
+  // as the same function and lets the second overwrite the first.
+  const existingFunction = state.functions.meta[pikkuFuncId]
+  if (
+    existingFunction &&
+    existingFunction.sourceFile &&
+    existingFunction.sourceFile !== sourceFile
+  ) {
+    logger.critical(
+      ErrorCode.DUPLICATE_FUNCTION_NAME,
+      `Function name '${name}' is not unique. ` +
+        `'${pikkuFuncId}' is already defined in '${existingFunction.sourceFile}' and cannot be redefined in '${sourceFile}'.`
+    )
+    return
+  }
+
+  const existing = state.rpc.internalMeta[name]
+  if (existing && !areCompatibleFunctionIds(existing, pikkuFuncId)) {
+    logger.critical(
+      ErrorCode.DUPLICATE_FUNCTION_NAME,
+      `Function name '${name}' is not unique. ` +
+        `It already points to '${existing}' in '${resolveExistingFunctionSource(state, existing) || 'unknown file'}', but '${pikkuFuncId}' in '${sourceFile}' tried to use the same name.`
+    )
+    return
+  }
+
+  const capitalizedName = funcIdToTypeName(name)
+  const registerSchema = (
+    ref: SchemaRef | null,
+    suffix: 'Input' | 'Output'
+  ) => {
+    if (!ref) return null
+    const schemaName = `${capitalizedName}${suffix}`
+    state.schemaLookup.set(schemaName, ref)
+    state.functions.typesMap.addCustomType(schemaName, 'unknown', [])
+    return schemaName
+  }
+  const inputSchemaName = registerSchema(inputSchemaRef, 'Input')
+  const outputSchemaName = registerSchema(outputSchemaRef, 'Output')
+
+  state.functions.meta[pikkuFuncId] = {
+    pikkuFuncId,
+    functionType: 'remote',
+    funcWrapper: 'pikkuRemoteChannelFunc',
+    sessionless: true,
+    name,
+    services: { optimized: true, services: [] },
+    inputSchemaName,
+    outputSchemaName,
+    inputs: inputSchemaName ? [inputSchemaName] : [],
+    outputs: outputSchemaName ? [outputSchemaName] : [],
+    sourceFile,
+    exportedName,
+    ...meta,
+  }
+
+  state.functions.files.set(pikkuFuncId, { path: sourceFile, exportedName })
+  state.rpc.internalMeta[name] = pikkuFuncId
+  // Imported so a local call gets the factory's "this runs on the client"
+  // error rather than a bare lookup miss.
+  state.rpc.internalFiles.set(pikkuFuncId, { path: sourceFile, exportedName })
+}
+
 /**
  * Inspect pikkuFunc calls, extract input/output and first-arg destructuring,
  * then push into state.functions.meta.
@@ -387,13 +514,13 @@ export const addFunctions: AddWiring = (
   }
 
   // Match identifiers that contain both "pikku" and "func" (case insensitive),
-  // plus pikkuScenario and pikkuScenarioStep (workflow wrappers without "func"
-  // in their names)
+  // plus pikkuScenario and the three scenario step wrappers (workflow wrappers
+  // without "func" in their names)
   const pikkuFuncPattern = /pikku.*func/i
   if (
     !pikkuFuncPattern.test(expression.text) &&
     expression.text !== 'pikkuScenario' &&
-    expression.text !== 'pikkuScenarioStep'
+    !SCENARIO_STEP_KINDS.has(expression.text)
   ) {
     return
   }
@@ -401,7 +528,8 @@ export const addFunctions: AddWiring = (
   // A scenario step is bundled like any invoked function, but is deliberately
   // never RPC-registered: a step may drive a browser, so exposing it over the
   // network would put a test harness on the public API surface.
-  const isScenarioStep = expression.text === 'pikkuScenarioStep'
+  const scenarioStepKind = SCENARIO_STEP_KINDS.get(expression.text)
+  const isScenarioStep = scenarioStepKind !== undefined
 
   // A scenario's own body. Marked so the codegen partitions and the deploy
   // analyzer can tell it apart from an application workflow without having to
@@ -444,6 +572,15 @@ export const addFunctions: AddWiring = (
   let expose: boolean | undefined
   let remote: boolean | undefined
   let mcp: boolean | undefined
+  /**
+   * A sessionless function's own `auth: true`. `sessionless` records the
+   * baseline — a `pikkuFunc` always needs a session — while this records the
+   * tightening a `pikkuSessionlessFunc` applies to itself, which is otherwise
+   * invisible to anything reading meta.
+   */
+  let auth: boolean | undefined
+  /** The author's claim that the body authorizes its own callers. */
+  let selfAuthenticated: boolean | undefined
   let readonly_: boolean | undefined
   let deploy: 'serverless' | 'server' | 'auto' | undefined
   let approvalRequired: boolean | undefined
@@ -451,7 +588,8 @@ export const addFunctions: AddWiring = (
   let workflowQueued: boolean | undefined
   let workflowRetries: number | undefined
   let workflowTimeout: string | undefined
-  let scenarioStepBrowser: boolean | undefined
+  let scenarioStepSurfaces: ScenarioSurface[] | undefined
+  let scenarioStepAddon: string | undefined
   let scenarioStepTemplate: string | undefined
   let scopes: string[] | undefined
   let version: number | undefined
@@ -540,6 +678,10 @@ export const addFunctions: AddWiring = (
     expose = getPropertyValue(firstArg, 'expose') as boolean | undefined
     remote = getPropertyValue(firstArg, 'remote') as boolean | undefined
     mcp = getPropertyValue(firstArg, 'mcp') as boolean | undefined
+    auth = getPropertyValue(firstArg, 'auth') as boolean | undefined
+    selfAuthenticated = getPropertyValue(firstArg, 'selfAuthenticated') as
+      | boolean
+      | undefined
     readonly_ = getPropertyValue(firstArg, 'readonly') as boolean | undefined
     deploy = getPropertyValue(firstArg, 'deploy') as
       | 'serverless'
@@ -558,9 +700,50 @@ export const addFunctions: AddWiring = (
     workflowTimeout = getPropertyValue(firstArg, 'workflowTimeout') as
       | string
       | undefined
-    scenarioStepBrowser = getPropertyValue(firstArg, 'browser') as
-      | boolean
-      | undefined
+    // A step declares one implementation per surface it supports; the binding
+    // keys that are present ARE the declaration, so there is nothing to read a
+    // value from — only names to collect.
+    const declaredSurfaces = SCENARIO_SURFACE_KEYS.filter((surface) =>
+      firstArg.properties.some(
+        (prop) =>
+          (ts.isPropertyAssignment(prop) ||
+            ts.isMethodDeclaration(prop) ||
+            ts.isShorthandPropertyAssignment(prop)) &&
+          ts.isIdentifier(prop.name) &&
+          prop.name.text === surface
+      )
+    )
+    if (scenarioStepKind === 'platform' || scenarioStepKind === 'addon') {
+      // Neither kind has surfaces. Nobody clicks "Stripe's webhook arrives", and
+      // there is no human behind "the platform has expired the trial" — so both
+      // take a single `func`, and a binding key here is a coded error rather
+      // than a convention nobody reads.
+      if (declaredSurfaces.length > 0) {
+        logger.error(
+          `• ${expression.text}('${name}') declares ${declaredSurfaces.join('/')} — a ${scenarioStepKind} step has one implementation, declared as \`func\`. Surfaces are how a person drives the system, and nobody drives this one.`
+        )
+        return
+      }
+      // The phase rule depends on it: an assertion runs every witness it has and
+      // fails if they disagree, so a step with exactly one witness by
+      // construction has to be unable to look like it has several.
+      scenarioStepSurfaces = ['default']
+      if (scenarioStepKind === 'addon') {
+        scenarioStepAddon = getPropertyValue(firstArg, 'addon') as
+          | string
+          | undefined
+        if (!scenarioStepAddon) {
+          logger.error(
+            `• pikkuAddonScenarioStep('${name}') needs a string literal \`addon\` naming the addon whose system acts — the same name its wireAddon declares.`
+          )
+          return
+        }
+      }
+    } else {
+      scenarioStepSurfaces = declaredSurfaces.length
+        ? declaredSurfaces
+        : undefined
+    }
     scenarioStepTemplate = getPropertyValue(firstArg, 'template') as
       | string
       | undefined
@@ -684,6 +867,24 @@ export const addFunctions: AddWiring = (
     pikkuFuncId = formatVersionedId(baseName, version)
   }
 
+  // A remote channel capability is a contract with no body: the connected
+  // client answers it. Everything past this point reads the handler, so it gets
+  // its own path rather than a nullable handler threaded through all of it.
+  if (expression.text === 'pikkuRemoteChannelFunc') {
+    addRemoteChannelFunc({
+      state,
+      logger,
+      node,
+      pikkuFuncId,
+      name,
+      exportedName,
+      inputSchemaRef,
+      outputSchemaRef,
+      meta: { version, title, tags, summary, description, errors },
+    })
+    return
+  }
+
   const isMCPToolFunc = expression.text === 'pikkuMCPToolFunc'
   const isListFunc = expression.text === 'pikkuListFunc'
   const mcpEnabled = mcp || isMCPToolFunc
@@ -1109,6 +1310,8 @@ export const addFunctions: AddWiring = (
     inputs: inputNames.filter((n) => n !== 'void') ?? null,
     outputs: outputNames.filter((n) => n !== 'void') ?? null,
     expose: expose || undefined,
+    auth: auth || undefined,
+    selfAuthenticated: selfAuthenticated || undefined,
     remote: remote || undefined,
     scenarioStep: isScenarioStep || undefined,
     scenario: isScenario || undefined,
@@ -1120,7 +1323,14 @@ export const addFunctions: AddWiring = (
     workflowQueued: workflowQueued === true ? true : undefined,
     workflowRetries: workflowRetries ?? undefined,
     workflowTimeout: workflowTimeout ?? undefined,
-    scenarioStepBrowser: scenarioStepBrowser === true ? true : undefined,
+    scenarioStepSurfaces,
+    // `persona` is the default reading of an unmarked step, so it is left off
+    // rather than written into every step meta a project already has.
+    scenarioStepKind:
+      scenarioStepKind && scenarioStepKind !== 'persona'
+        ? scenarioStepKind
+        : undefined,
+    scenarioStepAddon,
     scenarioStepTemplate: scenarioStepTemplate || undefined,
     scopes: scopes ?? undefined,
     implementationHash,

package/src/add/add-http-route.ts

@@ -272,18 +272,27 @@ export function registerHTTPRoute({
     }
   }
 
+  // The route's own `auth`, falling back to the group's. Recorded on the meta
+  // below so an audit can answer "is this route open?" without re-reading the
+  // source: the route can tighten a sessionless function, and until this was
+  // written down that tightening existed only in the wiring.
+  const routeAuthProp = getPropertyValue(obj, 'auth')
+  const resolvedAuth =
+    routeAuthProp === true || routeAuthProp === false
+      ? routeAuthProp
+      : inheritedAuth
+
   // For inline functions (e.g. oauth2 handlers), propagate sessionless: true
   // when auth is explicitly disabled at the route or group level — the
   // developer opted out of auth so no session is required.
   {
     const inlineMeta = state.functions.meta[funcName]
-    if (inlineMeta && inlineMeta.sessionless === undefined) {
-      const routeAuth = getPropertyValue(obj, 'auth')
-      const resolvedAuth =
-        routeAuth === true || routeAuth === false ? routeAuth : inheritedAuth
-      if (resolvedAuth === false) {
-        inlineMeta.sessionless = true
-      }
+    if (
+      inlineMeta &&
+      inlineMeta.sessionless === undefined &&
+      resolvedAuth === false
+    ) {
+      inlineMeta.sessionless = true
     }
   }
 
@@ -416,6 +425,7 @@ export function registerHTTPRoute({
     route: fullRoute,
     sourceFile: sourceFile.fileName,
     method: method as HTTPMethod,
+    ...(resolvedAuth !== undefined && { auth: resolvedAuth }),
     params: params.length > 0 ? params : undefined,
     query: query.length > 0 ? query : undefined,
     inputTypes: undefined,
@@ -484,6 +494,9 @@ export function registerHTTPRouteMeta({
     route: fullRoute,
     sourceFile: sourceFile.fileName,
     method: method as HTTPMethod,
+    ...((route.auth ?? inheritedAuth) !== undefined && {
+      auth: route.auth ?? inheritedAuth,
+    }),
     params: params.length > 0 ? params : undefined,
     inputTypes: undefined,
     tags: tags.length > 0 ? tags : undefined,