@pikku/inspector 0.12.41 → 0.12.43

package/src/add/add-scope.ts

@@ -0,0 +1,225 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from '../utils/get-property-value.js'
+import type { AddWiring, InspectorLogger } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+import type { ScopeNodeMeta } from '@pikku/core/scope'
+
+const SEPARATOR = ':'
+const WILDCARD = '*'
+
+/**
+ * Validates a single scope segment, reporting rather than throwing so the
+ * inspector can surface every problem in one pass.
+ *
+ * @returns true when the segment is usable.
+ */
+const isValidSegment = (
+  segment: string,
+  scopeName: string,
+  logger: InspectorLogger
+): boolean => {
+  if (segment.length === 0) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `Scope '${scopeName}' contains an empty segment.`
+    )
+    return false
+  }
+  if (segment.includes(SEPARATOR)) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `Scope segment '${segment}' in '${scopeName}' contains the '${SEPARATOR}' separator. ` +
+        `Nest scopes with the 'scopes' property instead of embedding '${SEPARATOR}' in a name.`
+    )
+    return false
+  }
+  if (segment === WILDCARD) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `Scope segment '${segment}' in '${scopeName}' is the wildcard. ` +
+        `'${WILDCARD}' is reserved for granting a scope and its descendants, and cannot be declared.`
+    )
+    return false
+  }
+  return true
+}
+
+/**
+ * Recursively extracts a `scopes: { ... }` object literal into nested metadata.
+ */
+const extractScopeNodes = (
+  obj: ts.ObjectLiteralExpression,
+  scopeName: string,
+  logger: InspectorLogger
+): Record<string, ScopeNodeMeta> | undefined => {
+  const nodes: Record<string, ScopeNodeMeta> = {}
+
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue
+    }
+
+    let segment: string | undefined
+    if (ts.isIdentifier(prop.name)) {
+      segment = prop.name.text
+    } else if (ts.isStringLiteral(prop.name)) {
+      segment = prop.name.text
+    }
+
+    if (segment === undefined) {
+      logger.critical(
+        ErrorCode.NON_LITERAL_WIRE_NAME,
+        `Scope '${scopeName}' has a nested scope whose key is not a literal.`
+      )
+      continue
+    }
+
+    if (!isValidSegment(segment, scopeName, logger)) {
+      continue
+    }
+
+    if (!ts.isObjectLiteralExpression(prop.initializer)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Nested scope '${segment}' in '${scopeName}' must be an object literal.`
+      )
+      continue
+    }
+
+    const node: ScopeNodeMeta = {}
+    const displayName = getPropertyValue(prop.initializer, 'displayName') as
+      | string
+      | null
+    if (displayName) {
+      node.displayName = displayName
+    }
+    const description = getPropertyValue(prop.initializer, 'description') as
+      | string
+      | null
+    if (description) {
+      node.description = description
+    }
+
+    const nestedProp = prop.initializer.properties.find(
+      (p) =>
+        ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'scopes'
+    )
+    if (
+      nestedProp &&
+      ts.isPropertyAssignment(nestedProp) &&
+      ts.isObjectLiteralExpression(nestedProp.initializer)
+    ) {
+      const nested = extractScopeNodes(
+        nestedProp.initializer,
+        scopeName,
+        logger
+      )
+      if (nested) {
+        node.scopes = nested
+      }
+    }
+
+    nodes[segment] = node
+  }
+
+  return Object.keys(nodes).length > 0 ? nodes : undefined
+}
+
+/**
+ * Unwraps `x as const` / `x as any` so a cast declaration is still extracted
+ * rather than silently skipped.
+ */
+const unwrapAs = (node: ts.Expression): ts.Expression =>
+  ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node
+
+export const addScope: AddWiring = (logger, node, checker, state, _options) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const expression = node.expression
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireScope') {
+    return
+  }
+
+  const firstArg = node.arguments[0]
+  if (!firstArg) {
+    return
+  }
+
+  const unwrapped = unwrapAs(firstArg)
+  if (!ts.isObjectLiteralExpression(unwrapped)) {
+    return
+  }
+
+  const sourceFile = node.getSourceFile().fileName
+
+  // Roots are keyed exactly like the nodes beneath them, so each property of
+  // the call's single argument is one tree.
+  for (const prop of unwrapped.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue
+    }
+
+    let name: string | undefined
+    if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
+      name = prop.name.text
+    }
+
+    if (name === undefined) {
+      logger.critical(
+        ErrorCode.NON_LITERAL_WIRE_NAME,
+        'A scope is declared with a key that is not a literal.'
+      )
+      continue
+    }
+
+    if (!isValidSegment(name, name, logger)) {
+      continue
+    }
+
+    if (!ts.isObjectLiteralExpression(prop.initializer)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Scope '${name}' must be an object literal.`
+      )
+      continue
+    }
+
+    const root = prop.initializer
+    const displayNameValue = getPropertyValue(root, 'displayName') as
+      | string
+      | null
+    const descriptionValue = getPropertyValue(root, 'description') as
+      | string
+      | null
+
+    let scopes: Record<string, ScopeNodeMeta> | undefined
+    const scopesProp = root.properties.find(
+      (p) =>
+        ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'scopes'
+    )
+    if (
+      scopesProp &&
+      ts.isPropertyAssignment(scopesProp) &&
+      ts.isObjectLiteralExpression(scopesProp.initializer)
+    ) {
+      scopes = extractScopeNodes(scopesProp.initializer, name, logger)
+    }
+
+    state.scopes.files.add(sourceFile)
+    state.scopes.definitions.push({
+      name,
+      displayName: displayNameValue || undefined,
+      description: descriptionValue || undefined,
+      scopes,
+      sourceFile,
+    })
+  }
+}

package/src/add/add-trigger.ts

@@ -9,6 +9,7 @@ import {
   makeContextBasedId,
 } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
+import { ensureInlineWiringFunction } from '../utils/ensure-function-metadata.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
@@ -83,6 +84,16 @@ const addWireTrigger: (
     return
   }
 
+  // Register metadata for a func inlined into the wiring (see helper).
+  ensureInlineWiringFunction(
+    state,
+    pikkuFuncId,
+    nameValue,
+    funcInitializer,
+    checker,
+    extracted.isHelper
+  )
+
   // --- resolve middleware ---
   const middleware = resolveMiddleware(state, obj, tags, checker)
 

package/src/add/add-wire-remote-addon.ts

@@ -0,0 +1,77 @@
+import * as ts from 'typescript'
+import type { InspectorState, InspectorLogger } from '../types.js'
+
+/**
+ * Detect wireRemoteAddon({ name: '...', package: '...' }) call expressions and
+ * record the namespace as a **remote** addon declaration. Only name + package
+ * are needed for codegen (serverUrl/auth are runtime closures resolved by the
+ * RPC runner); the `remote` marker tells the consumer's RPC-map generator to
+ * import the addon's `.remote.gen` map instead of `.internal.gen`.
+ */
+export function addWireRemoteAddon(
+  node: ts.Node,
+  state: InspectorState,
+  logger: InspectorLogger
+) {
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args } = node
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireRemoteAddon')
+    return
+
+  const [firstArg] = args
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
+
+  let name: string | undefined
+  let pkg: string | undefined
+  // The auth binding is a runtime closure; we only extract the statically
+  // knowable slot names so `pikku verify` can check they exist in the
+  // consumer's own wirings. `hasAuth` distinguishes "public" (omitted) from
+  // "bound via a custom resolve()" (present but no static id).
+  let hasAuth = false
+  let authCredentialId: string | undefined
+  let authSecretId: string | undefined
+
+  for (const prop of firstArg.properties) {
+    if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue
+    const key = prop.name.text
+    if (key === 'name' && ts.isStringLiteral(prop.initializer)) {
+      name = prop.initializer.text
+    } else if (key === 'package' && ts.isStringLiteral(prop.initializer)) {
+      pkg = prop.initializer.text
+    } else if (
+      key === 'auth' &&
+      ts.isObjectLiteralExpression(prop.initializer)
+    ) {
+      hasAuth = true
+      for (const authProp of prop.initializer.properties) {
+        if (!ts.isPropertyAssignment(authProp) || !ts.isIdentifier(authProp.name))
+          continue
+        if (
+          authProp.name.text === 'credentialId' &&
+          ts.isStringLiteral(authProp.initializer)
+        ) {
+          authCredentialId = authProp.initializer.text
+        } else if (
+          authProp.name.text === 'secretId' &&
+          ts.isStringLiteral(authProp.initializer)
+        ) {
+          authSecretId = authProp.initializer.text
+        }
+      }
+    }
+  }
+
+  if (!name || !pkg) return
+
+  logger.debug(`• Found wireRemoteAddon: ${name} → ${pkg} (remote)`)
+  state.rpc.wireAddonDeclarations.set(name, {
+    package: pkg,
+    remote: true,
+    hasAuth,
+    authCredentialId,
+    authSecretId,
+  })
+  state.rpc.usedAddons.add(name)
+  state.rpc.wireAddonFiles.add(node.getSourceFile().fileName)
+}

package/src/add/add-workflow-graph-input.test.ts

@@ -0,0 +1,94 @@
+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'
+
+function makeLogger(): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  }
+}
+
+describe('addWorkflowGraph — node input extraction', () => {
+  test('`as const` and imported template() values survive into the serialized input', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-input-'))
+    const stepFile = join(rootDir, 'my.steps.ts')
+    const graphFile = join(rootDir, 'my.graph.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const edit = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+      ].join('\n')
+    )
+
+    await writeFile(
+      graphFile,
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        "import { template } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'input-graph',",
+        "  nodes: { edit: 'edit' },",
+        '  config: {',
+        '    edit: {',
+        '      input: (ref) => ({',
+        "        method: 'GET' as const,",
+        '        operations: [',
+        "          { field: 'product', operation: 'set' as const, value: 'widget' },",
+        "          { field: 'email', operation: 'set' as const, value: ref('trigger', 'body.email') },",
+        "          { field: 'greeting', operation: 'set' as const, value: template('Hi $0', [ref('trigger', 'body.name')]) },",
+        '        ],',
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(makeLogger(), [stepFile, graphFile], {
+        rootDir,
+      })
+      const graph = state.workflows.graphMeta['input-graph']
+      assert.ok(graph, 'graph meta should be registered')
+      const input = (graph.nodes['edit'] as { input?: any }).input
+      assert.ok(input, 'node input should be extracted')
+
+      // Bug 1 — top-level `X as const` must not be dropped.
+      assert.equal(input.method, 'GET', 'top-level `as const` value preserved')
+
+      // Bug 1 — nested `as const` inside an array element must not be dropped.
+      assert.equal(input.operations[0].operation, 'set')
+      assert.equal(input.operations[0].value, 'widget')
+      assert.equal(input.operations[1].operation, 'set')
+
+      // ref() still works alongside the fix.
+      assert.deepEqual(input.operations[1].value, {
+        $ref: 'trigger',
+        path: 'body.email',
+      })
+
+      // Bug 2 — imported template() (arrow has only `ref`, no 2nd param) preserved.
+      assert.equal(input.operations[2].operation, 'set')
+      assert.deepEqual(input.operations[2].value, {
+        $template: {
+          parts: ['Hi ', ''],
+          expressions: [{ $ref: 'trigger', path: 'body.name' }],
+        },
+      })
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-workflow-graph-notes.test.ts

@@ -0,0 +1,74 @@
+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'
+
+function makeLogger(): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  }
+}
+
+describe('addWorkflowGraph — notes extraction', () => {
+  test('node-level and graph-level notes are carried into the serialized graph', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-notes-'))
+    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',",
+        "  notes: ['imported sticky note'],",
+        '  nodes: {',
+        "    assess: 'assess',",
+        "    notify: 'notify',",
+        '  },',
+        '  config: {',
+        "    assess: { next: 'notify', notes: 'STUB — generated from node \"Assess\"' },",
+        '    notify: {},',
+        '  },',
+        '})',
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(makeLogger(), [stepFile, graphFile], {
+        rootDir,
+      })
+      const graph = state.workflows.graphMeta['my-graph']
+      assert.ok(graph, 'graph meta should be registered')
+      assert.deepEqual(graph.notes, ['imported sticky note'])
+      assert.equal(
+        (graph.nodes['assess'] as { notes?: string }).notes,
+        'STUB — generated from node "Assess"'
+      )
+      assert.equal(
+        (graph.nodes['notify'] as { notes?: string }).notes,
+        undefined
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-workflow-graph.ts

@@ -12,6 +12,11 @@ function extractAstValue(
   refParamName: string,
   templateParamName: string | undefined
 ): unknown {
+  // `'GET' as const` / parenthesised values wrap the real initializer — see
+  // through them or the whole property is silently dropped from the meta.
+  while (ts.isAsExpression(expr) || ts.isParenthesizedExpression(expr)) {
+    expr = expr.expression
+  }
   if (ts.isStringLiteral(expr)) {
     return expr.text
   }
@@ -146,10 +151,14 @@ function extractInputMapping(
       ? node.parameters[0].name.text
       : 'ref'
 
+  // The canonical form imports `template` from '@pikku/core/workflow' and calls
+  // it inside a single-param `(ref) => (...)` arrow; the older form passes it as
+  // a second arrow parameter. Support both — default to the imported name so a
+  // `template(...)` value is never dropped just because it isn't a 2nd param.
   const templateParamName =
     node.parameters.length > 1 && ts.isIdentifier(node.parameters[1].name)
       ? node.parameters[1].name.text
-      : undefined
+      : 'template'
 
   const input: Record<string, unknown | DataRef> = {}
 
@@ -184,6 +193,13 @@ function extractNextConfig(
   node: ts.Node,
   _checker: ts.TypeChecker
 ): string | string[] | Record<string, string | string[]> | undefined {
+  // Key-based branch `next` (`{ key: [targets] }`) is authored with an `as any`
+  // cast because the graph's NextConfig can't narrow record targets to node-id
+  // literals; see through that (and parens) so the routing survives into the meta.
+  while (ts.isAsExpression(node) || ts.isParenthesizedExpression(node)) {
+    node = node.expression
+  }
+
   if (ts.isStringLiteral(node)) {
     return node.text
   }
@@ -254,6 +270,7 @@ interface PikkuWorkflowGraphExtract {
   name?: string
   description?: string
   tags?: string[]
+  notes?: string[]
   disabled?: true
   nodesNode?: ts.ObjectLiteralExpression
   configNode?: ts.ObjectLiteralExpression
@@ -270,6 +287,7 @@ function extractWorkflowGraphConfig(
   let name: string | undefined
   let description: string | undefined
   let tags: string[] | undefined
+  let notes: string[] | undefined
   let disabled: true | undefined
   let nodesNode: ts.ObjectLiteralExpression | undefined
   let configNode: ts.ObjectLiteralExpression | undefined
@@ -293,6 +311,13 @@ function extractWorkflowGraphConfig(
       tags = prop.initializer.elements
         .filter(ts.isStringLiteral)
         .map((el) => (el as ts.StringLiteral).text)
+    } else if (
+      propName === 'notes' &&
+      ts.isArrayLiteralExpression(prop.initializer)
+    ) {
+      notes = prop.initializer.elements
+        .filter(ts.isStringLiteral)
+        .map((el) => (el as ts.StringLiteral).text)
     } else if (
       propName === 'nodes' &&
       ts.isObjectLiteralExpression(prop.initializer)
@@ -306,7 +331,7 @@ function extractWorkflowGraphConfig(
     }
   }
 
-  return { name, description, tags, disabled, nodesNode, configNode }
+  return { name, description, tags, notes, disabled, nodesNode, configNode }
 }
 
 /**
@@ -359,6 +384,7 @@ function extractGraphFromNewFormat(
       onError: undefined,
       retries: undefined,
       retryDelay: undefined,
+      notes: undefined,
     }
   }
 
@@ -386,6 +412,7 @@ function extractGraphFromNewFormat(
           nodes[nodeId].input = nodeConfig.input
           nodes[nodeId].retries = nodeConfig.retries
           nodes[nodeId].retryDelay = nodeConfig.retryDelay
+          nodes[nodeId].notes = nodeConfig.notes
         }
       }
     }
@@ -406,12 +433,14 @@ function extractNodeConfigFromObject(
   input: Record<string, any>
   retries: number | undefined
   retryDelay: string | number | undefined
+  notes: string | undefined
 } {
   let next: any = undefined
   let onError: any = undefined
   let input: Record<string, any> = {}
   let retries: number | undefined = undefined
   let retryDelay: string | number | undefined = undefined
+  let notes: string | undefined = undefined
 
   for (const prop of obj.properties) {
     if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue
@@ -434,10 +463,12 @@ function extractNodeConfigFromObject(
       } else if (ts.isStringLiteral(prop.initializer)) {
         retryDelay = prop.initializer.text
       }
+    } else if (propName === 'notes') {
+      notes = extractStringLiteral(prop.initializer, checker)
     }
   }
 
-  return { next, onError, input, retries, retryDelay }
+  return { next, onError, input, retries, retryDelay, notes }
 }
 
 /**
@@ -526,6 +557,7 @@ export const addWorkflowGraph: AddWiring = (logger, node, checker, state) => {
     source: 'graph',
     description: graphConfig.description,
     tags: graphConfig.tags,
+    notes: graphConfig.notes,
     nodes: graphNodes,
     entryNodeIds,
   }