@pikku/inspector 0.12.49 → 0.12.52

package/src/add/add-subject-scenario-steps.test.ts

@@ -0,0 +1,161 @@
+/**
+ * The two step kinds whose subject is not a person: the app acting on itself,
+ * and a third-party system acting on it.
+ *
+ * What is being pinned here is mostly negative — that neither can declare a
+ * surface, and that both are marked in a way the virtual-user catalogue can
+ * refuse. The second is not tidiness: a virtual user that could invoke "Stripe's
+ * webhook arrives" would forge its own payment success, and every finding
+ * downstream of that is worthless.
+ */
+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'
+
+async function run(source: string) {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-subject-step-'))
+  const file = join(rootDir, 'subjects.steps.ts')
+  await writeFile(file, source)
+  const errors: string[] = []
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: (message: string) => {
+      errors.push(message)
+    },
+    diagnostic: () => {},
+    critical: (_code: any, message: string) => {
+      errors.push(message)
+    },
+    hasCriticalErrors: () => false,
+  } as unknown as InspectorLogger
+
+  const state = await inspect(logger, [file], { rootDir })
+  return {
+    state,
+    errors,
+    cleanup: () => rm(rootDir, { recursive: true, force: true }),
+  }
+}
+
+const IMPORTS =
+  "import { pikkuPlatformScenarioStep, pikkuAddonScenarioStep } from '@pikku/core/workflow'"
+
+describe('pikkuPlatformScenarioStep', () => {
+  test('registers under its declared name, marked as the platform acting', async () => {
+    const { state, errors, cleanup } = await run(
+      [
+        IMPORTS,
+        'export const trialHasExpired = pikkuPlatformScenarioStep({',
+        "  name: 'trialHasExpired',",
+        "  description: 'the platform has expired the trial',",
+        '  func: async ({ logger }, data: { orgId: string }) => ({ ok: !!data.orgId }),',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(errors, [])
+      const meta = state.functions.meta['trialHasExpired']
+      assert.ok(meta, 'expected a function registered as trialHasExpired')
+      assert.equal(meta.scenarioStepKind, 'platform')
+      // Held out of every deployed unit, exactly like a persona step.
+      assert.equal(meta.scenarioStep, true)
+      assert.equal(state.rpc.exposedMeta['trialHasExpired'], undefined)
+      assert.equal(state.rpc.internalMeta['trialHasExpired'], undefined)
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('has exactly one witness: a surface binding is refused', async () => {
+    const { state, errors, cleanup } = await run(
+      [
+        IMPORTS,
+        'export const trialHasExpired = pikkuPlatformScenarioStep({',
+        "  name: 'trialHasExpired',",
+        '  browser: async ({ logger }) => ({ ok: true }),',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.ok(
+        errors.some((message) => message.includes('browser')),
+        `expected the browser binding to be refused, got: ${errors.join(' | ')}`
+      )
+      assert.equal(state.functions.meta['trialHasExpired'], undefined)
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('declares one surface, so a browser run never demands an actor for it', async () => {
+    const { state, cleanup } = await run(
+      [
+        IMPORTS,
+        'export const trialHasExpired = pikkuPlatformScenarioStep({',
+        "  name: 'trialHasExpired',",
+        '  func: async ({ logger }) => ({ ok: true }),',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(
+        state.functions.meta['trialHasExpired']?.scenarioStepSurfaces,
+        ['default']
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+})
+
+describe('pikkuAddonScenarioStep', () => {
+  test('records the addon whose system acts', async () => {
+    const { state, errors, cleanup } = await run(
+      [
+        IMPORTS,
+        'export const stripeWebhookArrives = pikkuAddonScenarioStep({',
+        "  name: 'stripeWebhookArrives',",
+        "  addon: 'stripe',",
+        "  template: 'Stripe sends {event}',",
+        '  func: async ({ logger }, data: { event: string }) => ({ ok: !!data.event }),',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(errors, [])
+      const meta = state.functions.meta['stripeWebhookArrives']
+      assert.equal(meta?.scenarioStepKind, 'addon')
+      assert.equal(meta?.scenarioStepAddon, 'stripe')
+      assert.equal(meta?.scenarioStepTemplate, 'Stripe sends {event}')
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('without an addon it is refused — nobody can say whose system acted', async () => {
+    const { state, errors, cleanup } = await run(
+      [
+        IMPORTS,
+        'export const stripeWebhookArrives = pikkuAddonScenarioStep({',
+        "  name: 'stripeWebhookArrives',",
+        '  func: async ({ logger }) => ({ ok: true }),',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.ok(
+        errors.some((message) => message.includes('addon')),
+        `expected a missing-addon error, got: ${errors.join(' | ')}`
+      )
+      assert.equal(state.functions.meta['stripeWebhookArrives'], undefined)
+    } finally {
+      await cleanup()
+    }
+  })
+})

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

@@ -0,0 +1,214 @@
+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 } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: ErrorCode, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }) satisfies InspectorLogger
+
+const inspectSource = async (source: string) => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-role-'))
+  const file = join(rootDir, 'roles.ts')
+  await writeFile(file, source)
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  try {
+    const state = await inspect(makeLogger(criticals), [file], { rootDir })
+    return { state, criticals, file }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+const IMPORTS = [
+  "import { defineScope } from '@pikku/core/scope'",
+  "import { defineSystemRole } from '@pikku/core/role'",
+]
+
+const withScopes = (...lines: string[]) =>
+  [
+    ...IMPORTS,
+    'defineScope({',
+    '  catalogue: { scopes: { read: {} } },',
+    '  orders: { scopes: { create: {} } },',
+    '  admin: { scopes: { users: { scopes: { ban: {} } } } },',
+    '})',
+    ...lines,
+  ].join('\n')
+
+describe('addSystemRole inspector', () => {
+  test('extracts a role with its scopes', async () => {
+    const { state, criticals } = await inspectSource(
+      withScopes(
+        'defineSystemRole({',
+        '  buyer: {',
+        "    displayName: 'Buyer',",
+        "    description: 'Browses and orders',",
+        "    scopes: ['catalogue:read', 'orders:create'],",
+        '  },',
+        '})'
+      )
+    )
+
+    assert.deepEqual(criticals, [])
+    assert.equal(state.systemRoles.definitions.length, 1)
+    const role = state.systemRoles.definitions[0]!
+    assert.equal(role.name, 'buyer')
+    assert.equal(role.displayName, 'Buyer')
+    assert.equal(role.description, 'Browses and orders')
+    assert.deepEqual(role.scopes, ['catalogue:read', 'orders:create'])
+  })
+
+  test('extracts several roles from one call', async () => {
+    const { state, criticals } = await inspectSource(
+      withScopes(
+        'defineSystemRole({',
+        "  buyer: { scopes: ['catalogue:read'] },",
+        "  admin: { scopes: ['admin'] },",
+        '})'
+      )
+    )
+
+    assert.deepEqual(criticals, [])
+    assert.deepEqual(
+      state.systemRoles.definitions.map((r) => r.name),
+      ['buyer', 'admin']
+    )
+  })
+
+  test('a role granting nothing is legitimate, said explicitly', async () => {
+    const { state, criticals } = await inspectSource(
+      withScopes('defineSystemRole({', '  guest: { scopes: [] },', '})')
+    )
+
+    assert.deepEqual(criticals, [])
+    assert.deepEqual(state.systemRoles.definitions[0]!.scopes, [])
+  })
+
+  // Omitting `scopes` is not the same as declaring none — one is a decision,
+  // the other is a role nobody finished writing.
+  test('omitting scopes entirely is refused', async () => {
+    const { state, criticals } = await inspectSource(
+      withScopes('defineSystemRole({', "  guest: { description: 'x' },", '})')
+    )
+
+    assert.equal(state.systemRoles.definitions.length, 0)
+    assert.ok(criticals.some((c) => /has no 'scopes'/.test(c.message)))
+  })
+
+  test('a name containing the scope separator is refused', async () => {
+    const { state, criticals } = await inspectSource(
+      withScopes('defineSystemRole({', "  'admin:users': { scopes: [] },", '})')
+    )
+
+    assert.equal(state.systemRoles.definitions.length, 0)
+    assert.ok(criticals.some((c) => /separator/.test(c.message)))
+  })
+
+  // Scopes are read by AST, so a computed entry cannot be checked against the
+  // declared set — accepting it silently would let a role grant anything.
+  test('a computed scope entry is refused', async () => {
+    const { criticals } = await inspectSource(
+      withScopes(
+        'const s = "catalogue:read"',
+        'defineSystemRole({',
+        '  buyer: { scopes: [s] },',
+        '})'
+      )
+    )
+
+    assert.ok(criticals.some((c) => /not a string literal/.test(c.message)))
+  })
+
+  test('`as const` does not hide the declaration', async () => {
+    const { state, criticals } = await inspectSource(
+      withScopes(
+        'defineSystemRole({',
+        "  buyer: { scopes: ['catalogue:read'] },",
+        '} as const)'
+      )
+    )
+
+    assert.deepEqual(criticals, [])
+    assert.equal(state.systemRoles.definitions.length, 1)
+  })
+})
+
+describe('validateSystemRoleScopes', () => {
+  test('accepts declared scopes, including an intermediate node', async () => {
+    const { criticals } = await inspectSource(
+      withScopes(
+        'defineSystemRole({',
+        "  admin: { scopes: ['admin', 'admin:users:ban'] },",
+        '})'
+      )
+    )
+
+    assert.deepEqual(criticals, [])
+  })
+
+  test('accepts a subtree wildcard whose node exists', async () => {
+    const { criticals } = await inspectSource(
+      withScopes(
+        'defineSystemRole({',
+        "  admin: { scopes: ['admin:*'] },",
+        '})'
+      )
+    )
+
+    assert.deepEqual(criticals, [])
+  })
+
+  // The failure this exists to prevent: no function checks `orders:refund`, so
+  // a persona holding the role passes every call and the boundary the role
+  // describes is never exercised.
+  test('an undeclared scope fails the build and lists what is available', async () => {
+    const { criticals } = await inspectSource(
+      withScopes(
+        'defineSystemRole({',
+        "  buyer: { scopes: ['orders:refund'] },",
+        '})'
+      )
+    )
+
+    const critical = criticals.find((c) => /orders:refund/.test(c.message))
+    assert.ok(critical, `expected a critical, got ${JSON.stringify(criticals)}`)
+    assert.match(critical!.message, /is not declared/)
+    assert.match(critical!.message, /catalogue:read/)
+  })
+
+  test('a subtree wildcard on an undeclared node fails', async () => {
+    const { criticals } = await inspectSource(
+      withScopes(
+        'defineSystemRole({',
+        "  buyer: { scopes: ['nonsense:*'] },",
+        '})'
+      )
+    )
+
+    assert.ok(criticals.some((c) => /nonsense:\*/.test(c.message)))
+  })
+
+  test('the bare wildcard is refused — it hides what the role confers', async () => {
+    const { criticals } = await inspectSource(
+      withScopes('defineSystemRole({', "  god: { scopes: ['*'] },", '})')
+    )
+
+    assert.ok(criticals.some((c) => /bare wildcard/.test(c.message)))
+  })
+})

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, [])
+  })
+})