@pikku/inspector 0.12.50 → 0.12.54

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

@@ -0,0 +1,297 @@
+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 })
+  }
+}
+
+/** Inspects several files at once, keyed by basename. */
+const inspectSources = async (sources: Record<string, string>) => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-role-multi-'))
+  const files: Record<string, string> = {}
+  for (const [name, source] of Object.entries(sources)) {
+    files[name] = join(rootDir, name)
+    await writeFile(files[name]!, source)
+  }
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  try {
+    const state = await inspect(makeLogger(criticals), Object.values(files), {
+      rootDir,
+    })
+    return { state, criticals, files }
+  } 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('extracts roles from several calls in one file', async () => {
+    const { state } = await inspectSource(
+      withScopes(
+        "defineSystemRole({ buyer: { scopes: ['catalogue:read'] } })",
+        "defineSystemRole({ admin: { scopes: ['admin'] } })"
+      )
+    )
+
+    assert.deepEqual(
+      state.systemRoles.definitions.map((r) => r.name).sort(),
+      ['admin', 'buyer']
+    )
+  })
+
+  // Roles follow scopes: a project scaffolding user-admin has a generated
+  // declaration beside its own, so every file's roles have to survive.
+  test('declarations in separate files all survive', async () => {
+    const { state, criticals } = await inspectSources({
+      'roles.ts': withScopes(
+        "defineSystemRole({ buyer: { scopes: ['catalogue:read'] } })"
+      ),
+      'more-roles.ts': [
+        "import { defineSystemRole } from '@pikku/core/role'",
+        "defineSystemRole({ admin: { scopes: ['admin'] } })",
+      ].join('\n'),
+    })
+
+    assert.deepEqual(
+      criticals.filter((c) => /Only one defineSystemRole/.test(c.message)),
+      [],
+      `expected no duplicate critical, got ${JSON.stringify(criticals)}`
+    )
+    assert.deepEqual(
+      state.systemRoles.definitions.map((r) => r.name).sort(),
+      ['admin', 'buyer']
+    )
+  })
+
+  // A generated file is not the one place a person adds a role to, so it neither
+  // takes the single slot nor collides with the app's own declaration.
+  test('a generated declaration neither claims the slot nor conflicts', async () => {
+    const { state, criticals } = await inspectSources({
+      'roles.gen.ts': [
+        "import { defineSystemRole } from '@pikku/core/role'",
+        'defineSystemRole({ admin: { scopes: [] } })',
+      ].join('\n'),
+      'roles.ts': withScopes(
+        "defineSystemRole({ buyer: { scopes: ['catalogue:read'] } })"
+      ),
+    })
+
+    assert.deepEqual(
+      criticals.filter(
+        (c) => c.code === ErrorCode.DUPLICATE_SYSTEM_ROLE_DEFINITION
+      ),
+      [],
+      `expected no duplicate critical, got ${JSON.stringify(criticals)}`
+    )
+    assert.deepEqual(state.systemRoles.definitions.map((r) => r.name).sort(), [
+      'admin',
+      'buyer',
+    ])
+  })
+
+  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, [])
+  })
+})

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/add-workflow.ts

@@ -229,7 +229,13 @@ function getWorkflowInvocations(
  * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
  * pikkuScenario() calls. Detects workflow registration and extracts metadata.
  */
-export const addWorkflow: AddWiring = (logger, node, checker, state) => {
+export const addWorkflow: AddWiring = (
+  logger,
+  node,
+  checker,
+  state,
+  options
+) => {
   if (!ts.isCallExpression(node)) {
     return
   }
@@ -246,6 +252,17 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   if (expression.text === 'pikkuWorkflowFunc') {
     wrapperType = 'dsl'
   } else if (expression.text === 'pikkuWorkflowComplexFunc') {
+    if (!options.allow?.complexWorkflows) {
+      logger.critical(
+        ErrorCode.COMPLEX_WORKFLOW_NOT_ALLOWED,
+        `'${expression.text}' is used here, but this project has not enabled complex workflows. ` +
+          `Their inline steps cannot be serialized, so they are absent from the workflow graph and ` +
+          `cannot be replayed or migrated across a definition change. Express the workflow with ` +
+          `pikkuWorkflowFunc and the step DSL, or set \`allow: { complexWorkflows: true }\` in ` +
+          `pikku.config.json if the project accepts that trade.`
+      )
+      return
+    }
     wrapperType = 'complex'
   } else if (expression.text === 'pikkuScenario') {
     // A scenario is a complex workflow whose steps run as actors over the
@@ -351,6 +368,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   let steps: WorkflowStepMeta[] = []
   let context: WorkflowContext | undefined = undefined
   let dsl: boolean | undefined = undefined
+  let asserts: boolean | undefined = undefined
 
   // Try DSL workflow extraction first
   // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
@@ -362,6 +380,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     // Extraction succeeded
     steps = result.steps
     context = result.context
+    asserts = result.asserts
 
     // Check if workflow contains inline steps (non-serializable)
     if (hasInlineSteps(steps)) {
@@ -449,6 +468,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     expose,
     skip,
     scenario: wrapperType === 'scenario' ? true : undefined,
+    asserts,
     actors: actorNames.length > 0 ? actorNames : undefined,
   }