@pikku/inspector 0.12.50 → 0.12.54

package/src/utils/extract-secret-usage.test.ts

@@ -0,0 +1,81 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import ts from 'typescript'
+import { extractSecretUsage } from './extract-secret-usage.js'
+
+const usageOf = (source: string) =>
+  extractSecretUsage(
+    ts.createSourceFile('/services.ts', source, ts.ScriptTarget.ESNext, true)
+  )
+
+describe('extractSecretUsage', () => {
+  test('collects a literal getSecret key', () => {
+    const usage = usageOf(`await secrets.getSecret('STRIPE_KEY')`)
+    assert.deepEqual(usage.keys, ['STRIPE_KEY'])
+    assert.deepEqual(usage.dynamic, [])
+  })
+
+  test('collects hasSecret and template literals with no substitutions', () => {
+    const usage = usageOf(
+      'await secrets.hasSecret(`NOTION_TOKEN`)\nawait secrets.getSecret("A")'
+    )
+    assert.deepEqual(usage.keys, ['A', 'NOTION_TOKEN'])
+  })
+
+  test('collects every key of a getSecrets array', () => {
+    const usage = usageOf(`await secrets.getSecrets(['B', 'A'])`)
+    assert.deepEqual(usage.keys, ['A', 'B'])
+  })
+
+  test('flags a computed key as dynamic', () => {
+    const usage = usageOf(`await secrets.getSecret(name)`)
+    assert.deepEqual(usage.keys, [])
+    assert.equal(usage.dynamic.length, 1)
+    assert.match(usage.dynamic[0]!, /^1:name$/)
+  })
+
+  test('flags a template literal with a substitution as dynamic', () => {
+    const usage = usageOf('await secrets.getSecret(`PREFIX_${suffix}`)')
+    assert.deepEqual(usage.keys, [])
+    assert.equal(usage.dynamic.length, 1)
+  })
+
+  test('flags a non-array getSecrets argument as dynamic', () => {
+    const usage = usageOf(`await secrets.getSecrets(keys)`)
+    assert.equal(usage.dynamic.length, 1)
+  })
+
+  test('records both the literal and the dynamic keys of one call', () => {
+    const usage = usageOf(`await secrets.getSecrets(['A', other])`)
+    assert.deepEqual(usage.keys, ['A'])
+    assert.equal(usage.dynamic.length, 1)
+  })
+
+  test('finds reads nested inside a factory body', () => {
+    const usage = usageOf(`
+      export const createSingletonServices = async ({ secrets }) => {
+        const key = await secrets.getSecret('DEEP_KEY')
+        return { thing: new Thing(key) }
+      }
+    `)
+    assert.deepEqual(usage.keys, ['DEEP_KEY'])
+  })
+
+  test('deduplicates a key read twice', () => {
+    const usage = usageOf(
+      `await secrets.getSecret('A'); await secrets.getSecret('A')`
+    )
+    assert.deepEqual(usage.keys, ['A'])
+  })
+
+  test('ignores unrelated calls', () => {
+    const usage = usageOf(`await variables.get('HOME'); logger.info('hi')`)
+    assert.deepEqual(usage.keys, [])
+    assert.deepEqual(usage.dynamic, [])
+  })
+
+  test('reports the line a dynamic read is on', () => {
+    const usage = usageOf(`const a = 1\nconst b = 2\nsecrets.getSecret(name)`)
+    assert.match(usage.dynamic[0]!, /^3:/)
+  })
+})

package/src/utils/extract-secret-usage.ts

@@ -0,0 +1,73 @@
+import ts from 'typescript'
+
+export type SecretUsage = {
+  /** Secret ids read with a string literal, so statically known. */
+  keys: string[]
+  /** Reads whose key could not be resolved statically, as `line:source`. */
+  dynamic: string[]
+}
+
+const SINGLE_KEY_METHODS = new Set(['getSecret', 'hasSecret'])
+const KEY_LIST_METHODS = new Set(['getSecrets'])
+
+const literalKey = (node: ts.Expression): string | undefined => {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text
+  }
+  return undefined
+}
+
+/** Secret reads in a file, whether the key is statically known or not. */
+export const extractSecretUsage = (sourceFile: ts.SourceFile): SecretUsage => {
+  const keys = new Set<string>()
+  const dynamic = new Set<string>()
+
+  const record = (node: ts.CallExpression, argument?: ts.Expression) => {
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
+    dynamic.add(`${line + 1}:${(argument ?? node).getText()}`)
+  }
+
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression)
+    ) {
+      const method = node.expression.name.text
+      const [firstArgument] = node.arguments
+
+      if (SINGLE_KEY_METHODS.has(method)) {
+        if (!firstArgument) {
+          record(node)
+        } else {
+          const key = literalKey(firstArgument)
+          if (key === undefined) {
+            record(node, firstArgument)
+          } else {
+            keys.add(key)
+          }
+        }
+      } else if (KEY_LIST_METHODS.has(method)) {
+        if (firstArgument && ts.isArrayLiteralExpression(firstArgument)) {
+          for (const element of firstArgument.elements) {
+            const key = literalKey(element)
+            if (key === undefined) {
+              record(node, element)
+            } else {
+              keys.add(key)
+            }
+          }
+        } else {
+          record(node, firstArgument)
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+
+  visit(sourceFile)
+
+  return {
+    keys: [...keys].sort(),
+    dynamic: [...dynamic].sort(),
+  }
+}

package/src/utils/literal-properties.ts

@@ -0,0 +1,97 @@
+import * as ts from 'typescript'
+
+/**
+ * Readers for object-literal properties that must be statically knowable.
+ *
+ * Declarations extracted this way are never evaluated — the CLI reads them from
+ * source and writes them to JSON that a deployed stage carries without the app.
+ * So a computed value is not "unsupported", it is unreadable, and every reader
+ * here returns `undefined` for one rather than guessing.
+ */
+
+export const getProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): ts.Expression | undefined => {
+  const property = config.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === name
+  )
+  return property && ts.isPropertyAssignment(property)
+    ? property.initializer
+    : undefined
+}
+
+export const stringProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): string | undefined => {
+  const value = getProperty(config, name)
+  return value && ts.isStringLiteralLike(value) ? value.text : undefined
+}
+
+export const numberProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): number | undefined => {
+  const value = getProperty(config, name)
+  if (!value) {
+    return undefined
+  }
+  // `-1` parses as a unary minus over a literal, not as a literal. Reading it
+  // rather than ignoring it is what lets a negative be *rejected* by the caller
+  // instead of silently dropped and defaulted.
+  if (
+    ts.isPrefixUnaryExpression(value) &&
+    value.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(value.operand)
+  ) {
+    return -Number(value.operand.text)
+  }
+  return ts.isNumericLiteral(value) ? Number(value.text) : undefined
+}
+
+export const booleanProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): boolean | undefined => {
+  const value = getProperty(config, name)
+  if (!value) {
+    return undefined
+  }
+  if (value.kind === ts.SyntaxKind.TrueKeyword) {
+    return true
+  }
+  if (value.kind === ts.SyntaxKind.FalseKeyword) {
+    return false
+  }
+  return undefined
+}
+
+/**
+ * All-or-nothing: an array with one computed entry reads as unreadable rather
+ * than as the entries that happened to be literals. A half-read `roles` or
+ * `scopes` array is worse than none — it typechecks, runs, and grants less
+ * than the source says.
+ */
+export const stringArrayProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): string[] | undefined => {
+  const value = getProperty(config, name)
+  if (!value || !ts.isArrayLiteralExpression(value)) {
+    return undefined
+  }
+  const values = value.elements
+    .filter(ts.isStringLiteralLike)
+    .map((e) => e.text)
+  return values.length === value.elements.length ? values : undefined
+}
+
+/** Unwraps `x as const` / `x satisfies T` so a cast is still extracted. */
+export const unwrapAs = (node: ts.Expression): ts.Expression =>
+  ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node

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

@@ -118,6 +118,29 @@ const applyPackageToChannelContracts = (
   }
 }
 
+/**
+ * Resolves an addon's generated metadata, preferring the verbose copy.
+ *
+ * An addon publishes both: the minimal one its own bootstrap imports, and the
+ * verbose one for anything that needs the fields stripped out of it. A consumer
+ * is squarely in the second category — it is reading the addon to describe it,
+ * not to run it.
+ */
+const resolveAddonMeta = (
+  require: NodeRequire,
+  packageName: string,
+  baseName: string
+): string | null => {
+  for (const suffix of ['-verbose.gen.json', '.gen.json']) {
+    try {
+      return require.resolve(`${packageName}/.pikku/${baseName}${suffix}`)
+    } catch {
+      continue
+    }
+  }
+  return null
+}
+
 /**
  * After the setup sweep discovers wireAddon() declarations, load each addon
  * package's function metadata so that wiring handlers (channels, HTTP routes,
@@ -138,9 +161,16 @@ export async function loadAddonFunctionsMeta(
     // HOST that runs them — never load or require any of that here.
     if (decl.remote) continue
     try {
-      const metaPath = require.resolve(
-        `${decl.package}/.pikku/function/pikku-functions-meta.gen.json`
+      // Verbose first. `description` is one of the fields stripped from the
+      // minimal copy, and it is what an addon's function is offered to a model
+      // under — both as an MCP tool below and as an agent tool. Read the minimal
+      // one and every addon function looks undescribed.
+      const metaPath = resolveAddonMeta(
+        require,
+        decl.package,
+        'function/pikku-functions-meta'
       )
+      if (!metaPath) throw new Error('no function metadata')
       const raw = await readFile(metaPath, 'utf-8')
       const meta = JSON.parse(raw)
       state.addonFunctions[namespace] = meta

package/src/utils/permissions-shorthand.test.ts

@@ -0,0 +1,79 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import * as ts from 'typescript'
+import { extractPermissionPikkuNames } from './permissions.js'
+
+/**
+ * A checker stub. With no symbols to resolve, every reference falls back to a
+ * deterministic `__temp_` id — which is fine, because the question here is
+ * whether a declared permission is *seen*, not what it resolves to. A dropped
+ * property yields nothing at all, and that is the bug being pinned.
+ */
+const checker = {
+  getSymbolAtLocation: () => undefined,
+  getAliasedSymbol: () => undefined,
+  getShorthandAssignmentValueSymbol: () => undefined,
+} as unknown as ts.TypeChecker
+
+/** Parses `permissions: <expr>` and counts the references the inspector records. */
+const countFor = (permissionsExpression: string): number => {
+  const file = ts.createSourceFile(
+    'fn.ts',
+    `const config = { permissions: ${permissionsExpression} }`,
+    ts.ScriptTarget.Latest,
+    true
+  )
+  let node: ts.Expression | undefined
+  const visit = (n: ts.Node) => {
+    if (
+      ts.isPropertyAssignment(n) &&
+      ts.isIdentifier(n.name) &&
+      n.name.text === 'permissions'
+    ) {
+      node = n.initializer
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(file)
+  assert.ok(node, 'failed to find the permissions node')
+  return extractPermissionPikkuNames(node, checker, '/root').length
+}
+
+describe('extractPermissionPikkuNames', () => {
+  test('records a permission declared with object shorthand', () => {
+    // `permissions: { canAdminOrg }` is enforced identically to the longhand
+    // form at runtime — verifyPermissions has a non-array branch — but was
+    // dropped here, so meta reported a guarded function as carrying no
+    // permissions at all. An audit reading meta saw an open door where one
+    // was shut.
+    assert.equal(countFor('{ canAdminOrg }'), 1)
+  })
+
+  test('records the longhand form', () => {
+    assert.equal(countFor('{ org: canAdminOrg }'), 1)
+  })
+
+  test('records shorthand and longhand together', () => {
+    assert.equal(countFor('{ canAdminOrg, billing: canBill }'), 2)
+  })
+
+  test('records several shorthands', () => {
+    assert.equal(countFor('{ canAdminOrg, canBill }'), 2)
+  })
+
+  test('records the array form', () => {
+    assert.equal(countFor('[canAdminOrg, canBill]'), 2)
+  })
+
+  test('records a group whose value is an array', () => {
+    assert.equal(countFor('{ org: [canAdminOrg, canBill] }'), 2)
+  })
+
+  test('records a call expression, shorthand-adjacent', () => {
+    assert.equal(countFor('{ quota: hasEmailQuota(100) }'), 1)
+  })
+
+  test('records nothing for an empty object', () => {
+    assert.equal(countFor('{}'), 0)
+  })
+})

package/src/utils/permissions.ts

@@ -51,6 +51,13 @@ export function extractPermissionPikkuNames(
     for (const prop of node.properties) {
       if (ts.isPropertyAssignment(prop)) {
         extractFromElement(prop.initializer)
+      } else if (ts.isShorthandPropertyAssignment(prop)) {
+        // `permissions: { canAdminOrg }`. The runtime resolves this exactly
+        // like the longhand form — `verifyPermissions` has a non-array branch —
+        // so dropping it here reported a guarded function as having no
+        // permissions at all, which is the most dangerous direction to be wrong
+        // in: an audit reading meta sees an open door where one is shut.
+        extractFromElement(prop.name)
       }
     }
   }

package/src/utils/post-process.test.ts

@@ -10,6 +10,7 @@ import {
   validateVariableOverrides,
   validateRemoteAddonDependencies,
   validateRemoteAddonAuth,
+  validateAgentToolReferences,
 } from './post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import type { InspectorState, InspectorLogger } from '../types.js'
@@ -580,3 +581,135 @@ describe('validateRemoteAddonAuth (bound credential/secret must exist)', () => {
     assert.equal(criticals[0]!.code, ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED)
   })
 })
+
+const makeAgentState = (
+  tools: string[],
+  {
+    functions = {},
+    addonFunctions = {},
+    addons = [],
+    internalMeta = {},
+  }: {
+    functions?: Record<string, any>
+    addonFunctions?: Record<string, Record<string, any>>
+    addons?: string[]
+    internalMeta?: Record<string, string>
+  } = {}
+): Omit<InspectorState, 'typesLookup'> =>
+  ({
+    agents: {
+      agentsMeta: {
+        triage: { tools, sourceFile: 'src/triage.agent.ts' },
+      },
+    },
+    rpc: {
+      internalMeta,
+      wireAddonDeclarations: new Map(
+        addons.map((name) => [name, { package: `@addon/${name}` }])
+      ),
+    },
+    functions: { meta: functions },
+    addonFunctions,
+  }) as unknown as Omit<InspectorState, 'typesLookup'>
+
+describe('validateAgentToolReferences (ref() resolved at build time)', () => {
+  test('a local tool that does not exist is an error', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentToolReferences(
+      logger,
+      makeAgentState(['doesNotExist'], {
+        functions: { realTool: { description: 'A real one' } },
+      })
+    )
+    assert.equal(criticals.length, 1)
+    assert.equal(criticals[0]!.code, ErrorCode.AGENT_TOOL_NOT_FOUND)
+  })
+
+  test('an addon namespace that is not wired is an error, and lists the ones that are', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentToolReferences(
+      logger,
+      makeAgentState(['nope:thing'], { addons: ['todos'] })
+    )
+    assert.equal(criticals.length, 1)
+    assert.equal(criticals[0]!.code, ErrorCode.AGENT_TOOL_UNKNOWN_NAMESPACE)
+    assert.match(criticals[0]!.message, /Wired namespaces: todos/)
+  })
+
+  test('a wired addon that does not export the function is an error', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentToolReferences(
+      logger,
+      makeAgentState(['todos:noSuchFn'], {
+        addons: ['todos'],
+        addonFunctions: { todos: { addTodo: { description: 'Adds a todo' } } },
+      })
+    )
+    assert.equal(criticals.length, 1)
+    assert.equal(criticals[0]!.code, ErrorCode.AGENT_TOOL_NOT_FOUND)
+  })
+
+  test('an addon that has not been built yet is not treated as a missing function', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentToolReferences(
+      logger,
+      makeAgentState(['todos:addTodo'], { addons: ['todos'] })
+    )
+    assert.deepEqual(criticals, [])
+  })
+
+  test('a workflow reference is resolved elsewhere and left alone', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentToolReferences(
+      logger,
+      makeAgentState(['workflow:onboarding']),
+      { strictMeta: true }
+    )
+    assert.deepEqual(criticals, [])
+  })
+
+  test('a missing description is only an error under strictMeta', () => {
+    const state = makeAgentState(['bareTool'], {
+      functions: { bareTool: {} },
+    })
+
+    const lenient = makeCriticalLogger()
+    validateAgentToolReferences(lenient.logger, state)
+    assert.deepEqual(lenient.criticals, [])
+
+    const strict = makeCriticalLogger()
+    validateAgentToolReferences(strict.logger, state, { strictMeta: true })
+    assert.equal(strict.criticals.length, 1)
+    assert.equal(
+      strict.criticals[0]!.code,
+      ErrorCode.AGENT_TOOL_MISSING_DESCRIPTION
+    )
+  })
+
+  test('a title does not satisfy strictMeta, and the message says so', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentToolReferences(
+      logger,
+      makeAgentState(['titledTool'], {
+        functions: { titledTool: { title: 'Titled Tool' } },
+      }),
+      { strictMeta: true }
+    )
+    assert.equal(criticals.length, 1)
+    assert.equal(criticals[0]!.code, ErrorCode.AGENT_TOOL_MISSING_DESCRIPTION)
+    assert.match(criticals[0]!.message, /a 'title' does not count/)
+  })
+
+  test('an addon function is checked against the addon’s own meta', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentToolReferences(
+      logger,
+      makeAgentState(['todos:addTodo'], {
+        addons: ['todos'],
+        addonFunctions: { todos: { addTodo: { description: 'Adds a todo' } } },
+      }),
+      { strictMeta: true }
+    )
+    assert.deepEqual(criticals, [])
+  })
+})