@pikku/inspector 0.12.50 → 0.12.52

package/src/add/add-system-role.ts

@@ -0,0 +1,164 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from '../utils/get-property-value.js'
+import type { AddWiring } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+const SEPARATOR = ':'
+
+/**
+ * Unwraps `x as const` / `x satisfies T` 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
+
+/**
+ * Reads a `scopes: [...]` array of string literals.
+ *
+ * Returns `undefined` rather than an empty array when the property is absent
+ * or unreadable, so the caller can tell "declared no scopes" from "we could
+ * not see the scopes" — the first is a legitimate placeholder role, the second
+ * would silently produce one.
+ */
+const extractScopes = (
+  obj: ts.ObjectLiteralExpression,
+  roleName: string,
+  logger: Parameters<AddWiring>[0]
+): string[] | undefined => {
+  const prop = obj.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === 'scopes'
+  )
+
+  if (!prop) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `System role '${roleName}' has no 'scopes'. A role that grants nothing should say so with 'scopes: []'.`
+    )
+    return undefined
+  }
+
+  if (
+    !ts.isPropertyAssignment(prop) ||
+    !ts.isArrayLiteralExpression(prop.initializer)
+  ) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `System role '${roleName}' must declare 'scopes' as an array literal.`
+    )
+    return undefined
+  }
+
+  const scopes: string[] = []
+  for (const element of prop.initializer.elements) {
+    const unwrapped = unwrapAs(element)
+    if (!ts.isStringLiteral(unwrapped)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `System role '${roleName}' lists a scope that is not a string literal. ` +
+          `Scopes are extracted by AST, so a computed value cannot be checked against the declared set.`
+      )
+      continue
+    }
+    scopes.push(unwrapped.text)
+  }
+  return scopes
+}
+
+export const addSystemRole: AddWiring = (
+  logger,
+  node,
+  _checker,
+  state,
+  _options
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const expression = node.expression
+  if (!ts.isIdentifier(expression) || expression.text !== 'defineSystemRole') {
+    return
+  }
+
+  const firstArg = node.arguments[0]
+  if (!firstArg) {
+    return
+  }
+
+  const unwrapped = unwrapAs(firstArg)
+  if (!ts.isObjectLiteralExpression(unwrapped)) {
+    return
+  }
+
+  const sourceFile = node.getSourceFile().fileName
+
+  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 system role is declared with a key that is not a literal.'
+      )
+      continue
+    }
+
+    if (name.length === 0) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        'A system role is declared with an empty name.'
+      )
+      continue
+    }
+
+    if (name.includes(SEPARATOR)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `System role '${name}' contains the '${SEPARATOR}' separator. ` +
+          `'${SEPARATOR}' delimits scope ids; a role named like a scope reads as one.`
+      )
+      continue
+    }
+
+    if (!ts.isObjectLiteralExpression(prop.initializer)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `System role '${name}' must be an object literal.`
+      )
+      continue
+    }
+
+    const scopes = extractScopes(prop.initializer, name, logger)
+    if (scopes === undefined) {
+      continue
+    }
+
+    const displayName = getPropertyValue(prop.initializer, 'displayName') as
+      | string
+      | null
+    const description = getPropertyValue(prop.initializer, 'description') as
+      | string
+      | null
+
+    state.systemRoles.files.add(sourceFile)
+    state.systemRoles.definitions.push({
+      name,
+      displayName: displayName || undefined,
+      description: description || undefined,
+      scopes,
+      sourceFile,
+    })
+  }
+}

package/src/add/add-variable.ts

@@ -1,7 +1,7 @@
 import { createAddKeyedWiring } from './add-keyed-wiring.js'
 
 export const addVariable = createAddKeyedWiring({
-  functionName: 'wireVariable',
+  functionName: 'defineVariable',
   idField: 'variableId',
   label: 'Variable',
   schemaPrefix: 'VariableSchema',

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

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict'
+import { describe, test, beforeEach } from 'node:test'
+import * as ts from 'typescript'
+import { addWireAddon } from './add-wire-addon.js'
+
+let state: any
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as any
+
+/** Parses a source snippet and runs addWireAddon over every call expression. */
+const inspect = (source: string) => {
+  const file = ts.createSourceFile(
+    'wiring.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true
+  )
+  const visit = (node: ts.Node) => {
+    addWireAddon(node, state, logger)
+    ts.forEachChild(node, visit)
+  }
+  visit(file)
+  return state.rpc.wireAddonDeclarations
+}
+
+beforeEach(() => {
+  state = {
+    rpc: {
+      wireAddonDeclarations: new Map(),
+      usedAddons: new Set(),
+      wireAddonFiles: new Set(),
+    },
+  }
+})
+
+describe('addWireAddon', () => {
+  test('captures the addon gates alongside its plumbing', () => {
+    const declarations = inspect(`
+      wireAddon({
+        name: 'console',
+        package: '@pikku/addon-console',
+        rpcEndpoint: '/rpc',
+        auth: true,
+        tags: ['admin', 'internal'],
+        scopes: ['admin'],
+      })
+    `)
+
+    assert.deepEqual(declarations.get('console'), {
+      package: '@pikku/addon-console',
+      rpcEndpoint: '/rpc',
+      mcp: undefined,
+      auth: true,
+      tags: ['admin', 'internal'],
+      scopes: ['admin'],
+      secretOverrides: undefined,
+      variableOverrides: undefined,
+      credentialOverrides: undefined,
+    })
+  })
+
+  test('leaves the gates undefined when none are declared', () => {
+    const declarations = inspect(`
+      wireAddon({ name: 'console', package: '@pikku/addon-console' })
+    `)
+
+    const declaration = declarations.get('console')
+    assert.equal(declaration.auth, undefined)
+    assert.equal(declaration.tags, undefined)
+    assert.equal(declaration.scopes, undefined)
+  })
+
+  test('records auth: false rather than dropping it', () => {
+    const declarations = inspect(`
+      wireAddon({ name: 'console', package: '@x/y', auth: false })
+    `)
+
+    assert.equal(declarations.get('console').auth, false)
+  })
+
+  test('drops a scopes array that is not statically knowable', () => {
+    // A partial list would read as the complete set of gates, so an array with
+    // any non-literal entry is reported as unknown instead.
+    const declarations = inspect(`
+      wireAddon({ name: 'console', package: '@x/y', scopes: ['admin', ...EXTRA] })
+    `)
+
+    assert.equal(declarations.get('console').scopes, undefined)
+  })
+
+  test('drops a scopes value that is a reference rather than an array', () => {
+    const declarations = inspect(`
+      wireAddon({ name: 'console', package: '@x/y', scopes: ADMIN_SCOPES })
+    `)
+
+    assert.equal(declarations.get('console').scopes, undefined)
+  })
+
+  test('keeps an explicitly empty scopes array distinct from an absent one', () => {
+    const declarations = inspect(`
+      wireAddon({ name: 'console', package: '@x/y', scopes: [] })
+    `)
+
+    assert.deepEqual(declarations.get('console').scopes, [])
+  })
+})

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

@@ -1,6 +1,19 @@
 import * as ts from 'typescript'
 import type { InspectorState, InspectorLogger } from '../types.js'
 
+function parseStringArray(node: ts.Expression): string[] | undefined {
+  if (!ts.isArrayLiteralExpression(node)) return undefined
+  const values: string[] = []
+  for (const element of node.elements) {
+    // A non-literal entry (a spread, a const reference) is not statically
+    // knowable. Dropping the whole array rather than a silent partial keeps a
+    // consumer from reading a short list as the complete set of gates.
+    if (!ts.isStringLiteral(element)) return undefined
+    values.push(element.text)
+  }
+  return values
+}
+
 function parseStringRecord(
   obj: ts.ObjectLiteralExpression
 ): Record<string, string> {
@@ -41,6 +54,9 @@ export function addWireAddon(
   let pkg: string | undefined
   let rpcEndpoint: string | undefined
   let mcp: boolean | undefined
+  let auth: boolean | undefined
+  let tags: string[] | undefined
+  let scopes: string[] | undefined
   let secretOverrides: Record<string, string> | undefined
   let variableOverrides: Record<string, string> | undefined
   let credentialOverrides: Record<string, string> | undefined
@@ -61,6 +77,16 @@ export function addWireAddon(
         prop.initializer.kind === ts.SyntaxKind.FalseKeyword)
     ) {
       mcp = prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+    } else if (
+      key === 'auth' &&
+      (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+        prop.initializer.kind === ts.SyntaxKind.FalseKeyword)
+    ) {
+      auth = prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+    } else if (key === 'tags') {
+      tags = parseStringArray(prop.initializer)
+    } else if (key === 'scopes') {
+      scopes = parseStringArray(prop.initializer)
     } else if (
       key === 'secretOverrides' &&
       ts.isObjectLiteralExpression(prop.initializer)
@@ -86,6 +112,9 @@ export function addWireAddon(
     package: pkg,
     rpcEndpoint,
     mcp,
+    auth,
+    tags,
+    scopes,
     secretOverrides,
     variableOverrides,
     credentialOverrides,

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

@@ -104,17 +104,17 @@ describe('addon authoring bans', () => {
     })
   })
 
-  test('wireSecret inside an addon is allowed', async () => {
+  test('defineSecret inside an addon is allowed', async () => {
     const source = [
-      "import { wireSecret } from '@pikku/core'",
-      "wireSecret({ name: 'example', secretId: 'EXAMPLE' } as any)",
+      "import { defineSecret } from '@pikku/core'",
+      "defineSecret({ 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)}`
+        `expected defineSecret to be allowed, got ${JSON.stringify(criticals)}`
       )
     })
   })

package/src/add/config-value-metadata.test.ts

@@ -36,17 +36,17 @@ const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
  * downstream, which is exactly how `displayName` went unused.
  */
 describe('config value metadata (docsUrl)', () => {
-  test('carries docsUrl from wireSecret into the definition', async () => {
+  test('carries docsUrl from defineSecret into the definition', async () => {
     const rootDir = await mkdtemp(`${fixtureRoot}-secret-`)
     const file = join(rootDir, 'secret.ts')
 
     await writeFile(
       file,
       [
-        "import { wireSecret } from '@pikku/core'",
+        "import { defineSecret } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const StripeKeySchema = z.string()',
-        'wireSecret({',
+        'defineSecret({',
         "  name: 'stripeKey',",
         "  displayName: 'Stripe Secret Key',",
         "  secretId: 'STRIPE_SECRET_KEY',",
@@ -76,10 +76,10 @@ describe('config value metadata (docsUrl)', () => {
     await writeFile(
       file,
       [
-        "import { wireSecret } from '@pikku/core'",
+        "import { defineSecret } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const ApiKeySchema = z.string()',
-        'wireSecret({',
+        'defineSecret({',
         "  name: 'apiKey',",
         "  displayName: 'API Key',",
         "  secretId: 'API_KEY',",
@@ -101,17 +101,17 @@ describe('config value metadata (docsUrl)', () => {
     }
   })
 
-  test('carries docsUrl from wireVariable into the definition', async () => {
+  test('carries docsUrl from defineVariable into the definition', async () => {
     const rootDir = await mkdtemp(`${fixtureRoot}-variable-`)
     const file = join(rootDir, 'variable.ts')
 
     await writeFile(
       file,
       [
-        "import { wireVariable } from '@pikku/core'",
+        "import { defineVariable } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const ConsoleUrlSchema = z.string()',
-        'wireVariable({',
+        'defineVariable({',
         "  name: 'consoleUrl',",
         "  displayName: 'Console URL',",
         "  variableId: 'CONSOLE_URL',",
@@ -134,17 +134,17 @@ describe('config value metadata (docsUrl)', () => {
     }
   })
 
-  test('carries docsUrl from wireCredential into the definition', async () => {
+  test('carries docsUrl from defineCredential into the definition', async () => {
     const rootDir = await mkdtemp(`${fixtureRoot}-credential-`)
     const file = join(rootDir, 'credential.ts')
 
     await writeFile(
       file,
       [
-        "import { wireCredential } from '@pikku/core'",
+        "import { defineCredential } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const TokenSchema = z.object({ token: z.string() })',
-        'wireCredential({',
+        'defineCredential({',
         "  name: 'githubToken',",
         "  displayName: 'GitHub Token',",
         "  type: 'wire',",

package/src/add/wire-name-literal.test.ts

@@ -62,9 +62,9 @@ describe('wiring name must be a string literal', () => {
     await writeFile(
       file,
       [
-        "import { wireSecret } from '@pikku/core'",
+        "import { defineSecret } from '@pikku/core'",
         'const SECRET_ID = "STRIPE_SECRET_KEY"',
-        'wireSecret({',
+        'defineSecret({',
         '  secretId: SECRET_ID,',
         "  name: 'Stripe secret key',",
         "  displayName: 'Stripe secret key',",

package/src/error-codes.ts

@@ -25,6 +25,7 @@ export enum ErrorCode {
   SCENARIO_BROWSER_STEP_NEEDS_ACTOR = 'PKU677',
   SCENARIO_STEP_TARGET_NOT_STATIC = 'PKU678',
   SCENARIO_NOT_EXTRACTABLE = 'PKU679',
+  SCENARIO_HAS_NO_ASSERTION = 'PKU680',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',
   WORKFLOW_GRAPH_ADDON_NOT_WIRED = 'PKU642',
@@ -53,6 +54,8 @@ export enum ErrorCode {
   ROUTE_PARAM_MISMATCH = 'PKU571',
   ROUTE_QUERY_MISMATCH = 'PKU572',
   AUTH_DISABLED_REQUIRES_SESSIONLESS = 'PKU573',
+  EXPOSED_FUNCTION_HAS_NO_GATE = 'PKU574',
+  TAG_RESOLVES_TO_NO_MIDDLEWARE = 'PKU575',
 
   // Versioning errors
   DUPLICATE_FUNCTION_VERSION = 'PKU850',
@@ -70,6 +73,11 @@ export enum ErrorCode {
   MISSING_MODEL = 'PKU145',
   INVALID_MODEL = 'PKU146',
 
+  // Agent tool reference errors
+  AGENT_TOOL_UNKNOWN_NAMESPACE = 'PKU152',
+  AGENT_TOOL_NOT_FOUND = 'PKU153',
+  AGENT_TOOL_MISSING_DESCRIPTION = 'PKU154',
+
   // File structure errors
   SCHEMA_AND_WIRING_COLOCATED = 'PKU490',
 
@@ -90,6 +98,11 @@ export enum ErrorCode {
   ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = 'PKU921',
 
   RPC_INVOCATION_TYPE_CAST = 'PKU940',
+
+  // Secret boundary errors
+  SECRET_SERVICE_ALIASED = 'PKU950',
+  SECRET_NOT_DECLARED = 'PKU951',
+  SECRET_KEY_NOT_STATIC = 'PKU952',
 }
 
 /**

package/src/index.ts

@@ -32,7 +32,10 @@ export type {
   VersionManifest,
   VersionManifestEntry,
 } from './utils/contract-hashes.js'
-export type { InspectorFeature, InspectorFeatureEntry } from './types.js'
+export type {
+  InspectorFeature,
+  InspectorFeatureEntry,
+} from './types.js'
 export { serializeMCPJson } from './utils/serialize-mcp-json.js'
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js'
 export {

package/src/inspector.ts

@@ -15,22 +15,31 @@ import {
   aggregateRequiredServices,
   stampAuthHandlerServices,
   validateAgentModels,
+  validateAgentToolReferences,
   validateSecretOverrides,
   validateVariableOverrides,
   validateCredentialOverrides,
   validateRemoteAddonDependencies,
   validateRemoteAddonAuth,
   validateScopeReferences,
+  validateSystemRoleScopes,
+  validatePersonaRoles,
   computeResolvedIOTypes,
   computeMiddlewareGroupsMeta,
   computePermissionsGroupsMeta,
   computeRequiredSchemas,
+  computeSecretBrokers,
+  validateNoSecretAliasServices,
+  validateSecretUsage,
   computeDiagnostics,
   validateSchemaWiringSeparation,
   validateScenarioServices,
   validateScenarioSteps,
   validateWorkflowGraphAddons,
 } from './utils/post-process.js'
+import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js'
+import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js'
+import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
 import { pikkuState } from '@pikku/core/internal'
 import { resolveLatestVersions } from './utils/resolve-versions.js'
@@ -40,6 +49,7 @@ import {
   finalizeWorkflowWires,
 } from './utils/workflow/graph/finalize-workflow-wires.js'
 import { generateAllSchemas } from './utils/schema-generator.js'
+import { extractSecretUsage } from './utils/extract-secret-usage.js'
 import {
   loadAddonFunctionsMeta,
   loadAddonSchemas,
@@ -169,6 +179,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     secrets: {
       definitions: [],
       files: new Set(),
+      usage: new Map(),
     },
     credentials: {
       definitions: [],
@@ -178,6 +189,14 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       definitions: [],
       files: new Set(),
     },
+    systemRoles: {
+      definitions: [],
+      files: new Set(),
+    },
+    personas: {
+      definitions: [],
+      files: new Set(),
+    },
     variables: {
       definitions: [],
       files: new Set(),
@@ -354,6 +373,13 @@ export const inspect = async (
 
   const state = getInitialInspectorState(rootDir)
 
+  for (const sourceFile of sourceFiles) {
+    const usage = extractSecretUsage(sourceFile)
+    if (usage.keys.length > 0 || usage.dynamic.length > 0) {
+      state.secrets.usage.set(sourceFile.fileName, usage)
+    }
+  }
+
   // First sweep: add all functions
   const startSetup = performance.now()
   for (const sourceFile of sourceFiles) {
@@ -451,11 +477,21 @@ export const inspect = async (
     computeResolvedIOTypes(state)
     computeMiddlewareGroupsMeta(state)
     computePermissionsGroupsMeta(state)
+    computeSecretBrokers(state)
+    validateNoSecretAliasServices(logger, checker, state)
+    validateSecretUsage(logger, state)
     computeDiagnostics(state)
     validateSchemaWiringSeparation(logger, state)
     validateWorkflowGraphAddons(logger, state)
     validateScenarioServices(logger, state)
     validateScenarioSteps(logger, state)
+    // Needs every route, every function and every wireAddon declaration
+    // together, so it can only run once the whole program is inspected.
+    annotateHttpRouteAuth(state)
+    // Last of the validators: they read function meta and every wireAddon
+    // declaration together, so they need the whole program inspected.
+    validateExposedFunctionsGated(logger, state)
+    validateTagsResolveToMiddleware(logger, state)
 
     if (options.openAPI) {
       state.openAPISpec = await generateOpenAPISpec(
@@ -469,12 +505,15 @@ export const inspect = async (
     }
 
     validateAgentModels(logger, state)
+    validateAgentToolReferences(logger, state, options)
     validateSecretOverrides(logger, state)
     validateVariableOverrides(logger, state)
     validateCredentialOverrides(logger, state)
     validateRemoteAddonDependencies(logger, state)
     validateRemoteAddonAuth(logger, state)
     validateScopeReferences(logger, state)
+    validateSystemRoleScopes(logger, state)
+    validatePersonaRoles(logger, state)
   }
 
   state.program = program