@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/local/local-workflow-tests.ts

@@ -0,0 +1,482 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+
+import { parse } from 'yaml'
+
+import { allTargets } from './local-dev-sync'
+import { contentHash, loadBuild, type BuildEntry } from './local-applied'
+import type { LocalProject } from './local-project'
+import { call, type Api } from './local-test-runner'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * A workflow's test cases, run on the local runtime by `frontera local test`.
+ *
+ *   workflows/tests/<slug>.yaml      cases for workflows/<slug>.yaml
+ *
+ *   workflow: claim-intake           optional; the file's name when absent
+ *   cases:
+ *     - name: approves a small claim
+ *       input: { amount: 120 }       the run's input, as its trigger declares it
+ *       subject: CLM-0001            optional: the record a record-bound workflow runs on
+ *       timeoutSeconds: 120          optional; 120 when absent
+ *       expect:
+ *         status: succeeded          succeeded (the default), failed or canceled
+ *         failedStep: check-limit    the step that must fail (implies failed); a `stop` with status failed counts
+ *         failedCode: CONFIRM_UNAVAILABLE   the error code a failed step (or the run) must carry (implies failed)
+ *         output:                    checks on what the run returned, each one must pass
+ *           - path: decision                       a dot path into what the run returned (`output.decision` too, unless it returned a key named `output`)
+ *             equals: approved
+ *           - path: steps.score.output.reasons     `steps.<id>.` reads a step's own output
+ *           - path: steps.each.output.0.submit.requestId   a forEach step's output is its list of iterations, `{ <innerStepId>: <its output> }`
+ *             contains: under limit
+ *           - path: note
+ *             exists: false
+ *
+ * Each case runs exactly the version `local dev` pushed the workflow's file
+ * as (the build record keeps it, with the file's hash): as a test run when it
+ * is a draft, so it never counts as a live run, or as a run of the live
+ * version once a binding promoted it. When the file changed since it was
+ * applied, or its apply failed, the cases are refused with what to run, never
+ * run on code that is neither the file nor live. A workflow the project has
+ * no file for runs its newest draft (else its newest version). The run is
+ * waited for, then judged.
+ *
+ * The folder sits beside the workflows, one level down, so `local dev`
+ * never takes a test file for a workflow.
+ */
+
+export interface WorkflowOutputCheck {
+  path: string
+  equals?: unknown
+  contains?: unknown
+  exists?: boolean
+}
+
+export interface WorkflowTestCase {
+  name: string
+  input?: Record<string, unknown>
+  subject?: string
+  timeoutSeconds?: number
+  expect?: {
+    status?: 'succeeded' | 'failed' | 'canceled'
+    failedStep?: string
+    /** The error code a failed step, or the run, must carry (`CONFIRM_UNAVAILABLE`). */
+    failedCode?: string
+    output?: WorkflowOutputCheck[]
+  }
+}
+
+export interface WorkflowTestFile {
+  workflow: string
+  file: string
+  cases: WorkflowTestCase[]
+  /** Why the file cannot run, said once per case. */
+  problem?: string
+}
+
+export interface WorkflowTestResult {
+  workflow: string
+  file: string
+  name: string
+  passed: boolean
+  reason?: string
+  ms: number
+  runId?: string
+  version?: number
+  status?: string
+}
+
+/** The test folder, relative to the project root. */
+export const WORKFLOW_TESTS_DIR = join('workflows', 'tests')
+
+/** What a case file must hold, said as a problem rather than thrown, so one bad file fails only its own cases. */
+function readCases(doc: unknown): { cases: WorkflowTestCase[]; problem?: string } {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return { cases: [], problem: 'the file is not a mapping with `cases:`' }
+  const raw = (doc as { cases?: unknown }).cases
+  if (!Array.isArray(raw)) return { cases: [], problem: '`cases` is not a list' }
+  const cases: WorkflowTestCase[] = []
+  for (const [i, c] of raw.entries()) {
+    if (!c || typeof c !== 'object' || Array.isArray(c)) return { cases, problem: `case ${i + 1} is not a mapping` }
+    const o = c as Record<string, unknown>
+    if (typeof o.name !== 'string' || !o.name.trim()) return { cases, problem: `case ${i + 1} has no \`name\`` }
+    if (o.input !== undefined && (!o.input || typeof o.input !== 'object' || Array.isArray(o.input))) return { cases, problem: `case "${o.name}": \`input\` must be a mapping` }
+    if (o.subject !== undefined && typeof o.subject !== 'string') return { cases, problem: `case "${o.name}": \`subject\` must be the record's primary key, as text` }
+    cases.push(o as unknown as WorkflowTestCase)
+  }
+  return { cases }
+}
+
+/** Every workflow test file in the project, optionally only one workflow's. */
+export function findWorkflowTestFiles(root: string, workflow?: string): WorkflowTestFile[] {
+  const dir = join(root, WORKFLOW_TESTS_DIR)
+  if (!existsSync(dir)) return []
+  const out: WorkflowTestFile[] = []
+  for (const name of readdirSync(dir).sort()) {
+    if (!/\.ya?ml$/.test(name) || name.startsWith('.')) continue
+    const path = join(dir, name)
+    const file = relative(root, path)
+    let doc: unknown
+    try {
+      doc = parse(readFileSync(path, 'utf8'))
+    } catch (err) {
+      out.push({ workflow: name.replace(/\.ya?ml$/, ''), file, cases: [], problem: `the file is not YAML: ${(err as Error).message.split('\n')[0]}` })
+      continue
+    }
+    const named = (doc as { workflow?: unknown } | null)?.workflow
+    const slug = typeof named === 'string' && named ? named : name.replace(/\.ya?ml$/, '')
+    if (workflow && slug !== workflow) continue
+    const { cases, problem } = readCases(doc)
+    out.push({ workflow: slug, file, cases, ...(problem ? { problem } : {}) })
+  }
+  return out
+}
+
+/** A forEach step's output as the run keeps it: `{ mode, count, results }`, where `$steps` gives the list. */
+function isForEachView(v: unknown): v is { results: unknown[]; count?: number; mode?: string } {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) && Array.isArray((v as { results?: unknown }).results) && typeof (v as { count?: unknown }).count === 'number' && typeof (v as { mode?: unknown }).mode === 'string'
+}
+
+/**
+ * `decision`, `items.0.id`, `steps.score.output.reasons`: a value in the run,
+ * or `undefined` when the path leads nowhere. A path reads what the run
+ * returned; a leading `output.` names that too (`output.decision` is
+ * `decision`), except when what it returned has a key named `output`, which
+ * the path then reads (`output.withdrawn` of `{ runId, output: { withdrawn } }`). A forEach step's output reads
+ * as `$steps` gives it, the list of its iterations (`steps.each.output.0.x`,
+ * `steps.each.output.length`); the run's own view of it (`.results.0.x`,
+ * `.count`, `.mode`) reads too. An iteration is `{ <innerStepId>: <its output> }`,
+ * so `steps.each.output.0.submit.requestId` reads an inner step's output; the
+ * older `steps.each.output.0.submit.output.requestId` form reads the same value.
+ */
+export function valueAt(run: { output: unknown; nodes?: Array<{ nodeId: string; output?: unknown; status?: string; error?: unknown }> }, path: string): unknown {
+  const parts = path.split('.').filter(Boolean)
+  let at: unknown = run.output
+  // Where, in `parts`, an iteration's inner step `output` segment may sit (forEach only).
+  let innerOutputAt = -1
+  if (parts[0] === 'steps' && parts.length >= 2) {
+    const node = (run.nodes ?? []).find((n) => n.nodeId === parts[1])
+    if (!node) return undefined
+    at = node
+    parts.splice(0, 2)
+    const head: string | undefined = parts[0]
+    if (head === 'output' && isForEachView(node.output)) {
+      const view = node.output
+      parts.shift()
+      const next: string | undefined = parts[0]
+      at = next === 'results' || next === 'count' || next === 'mode' ? view : view.results
+      // `<index>.<innerStepId>.output.<path>` (or `results.<index>.…`)
+      innerOutputAt = next === 'results' ? 3 : 2
+    }
+  } else if (parts[0] === 'output' && !(isRecord(run.output) && 'output' in run.output)) {
+    // `output.decision` and `decision` are the same path, unless what the run returned has a key named
+    // `output` (`{ runId, output }`, a Function step's result returned whole): then the path reads that key.
+    parts.shift()
+  }
+  for (const [i, part] of parts.entries()) {
+    // An iteration holds each inner step's output directly (`{ escalate: { lifecycle } }`), so
+    // `0.escalate.output.lifecycle` and `0.escalate.lifecycle` are the same path.
+    if (i === innerOutputAt && part === 'output' && isRecord(at) && !('output' in at)) continue
+    if (Array.isArray(at) && /^\d+$/.test(part)) at = at[Number(part)]
+    else if (Array.isArray(at) && part === 'length') at = at.length
+    else if (at && typeof at === 'object') at = (at as Record<string, unknown>)[part]
+    else return undefined
+  }
+  return at
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  // A number written in YAML and the same number the run returned as text are not equal: types count.
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]))
+  if (isRecord(a) && isRecord(b)) {
+    const keys = Object.keys(a)
+    return keys.length === Object.keys(b).length && keys.every((k) => deepEqual(a[k], b[k]))
+  }
+  return false
+}
+
+/** Whether `actual` contains `expected`: text holds it (ignoring case), a list has an equal item, a mapping holds its keys. */
+export function containsValue(actual: unknown, expected: unknown): boolean {
+  if (typeof actual === 'string' && typeof expected === 'string') return actual.toLowerCase().includes(expected.toLowerCase())
+  if (Array.isArray(actual)) return actual.some((item) => deepEqual(item, expected) || (isRecord(item) && isRecord(expected) && containsValue(item, expected)))
+  if (isRecord(actual) && isRecord(expected)) return Object.entries(expected).every(([k, v]) => k in actual && (deepEqual(actual[k], v) || containsValue(actual[k], v)))
+  return false
+}
+
+const show = (v: unknown) => (v === undefined ? 'nothing' : JSON.stringify(v))
+
+/** Why one output check failed, or null when it passed. */
+export function runOutputCheck(check: WorkflowOutputCheck, run: Parameters<typeof valueAt>[0]): string | null {
+  if (typeof check.path !== 'string' || !check.path) return 'an output check has no `path`'
+  const actual = valueAt(run, check.path)
+  if (check.exists !== undefined) {
+    const present = actual !== undefined && actual !== null
+    if (present !== check.exists) return check.exists ? `${check.path} is missing` : `${check.path} is ${show(actual)}, and the case expects nothing there`
+  }
+  if ('equals' in check && !deepEqual(actual, check.equals)) return `${check.path} is ${show(actual)}, not ${show(check.equals)}`
+  if ('contains' in check && !containsValue(actual, check.contains)) return `${check.path} is ${show(actual)}, which does not contain ${show(check.contains)}`
+  if (check.exists === undefined && !('equals' in check) && !('contains' in check)) return `the check on ${check.path} says neither equals, contains nor exists`
+  return null
+}
+
+export interface JudgedRun {
+  status: string
+  error?: unknown
+  output: unknown
+  nodes?: Array<{ nodeId: string; kind?: string; status?: string; output?: unknown; error?: unknown; childRun?: JudgedRun | null }>
+}
+
+/**
+ * The steps that failed, nested ones included, in the order the run holds
+ * them. A `stop` step with `status: failed` is recorded as succeeded (it did
+ * what it says) while it fails its run: in a failed run, the stop that ended
+ * it counts as the step that failed, so `failedStep` can name it.
+ */
+function failedSteps(run: JudgedRun): string[] {
+  const nodes = run.nodes ?? []
+  const own = nodes.flatMap((n) => [...(n.status === 'failed' ? [n.nodeId] : []), ...(n.childRun ? failedSteps(n.childRun) : [])])
+  if (run.status !== 'failed') return own
+  // The last stop that ran is the one that ended the run.
+  const stop = [...nodes].reverse().find((n) => n.kind === 'stop' && n.status === 'succeeded')
+  return stop && !own.includes(stop.nodeId) ? [...own, stop.nodeId] : own
+}
+
+function errorText(error: unknown): string {
+  if (!error) return ''
+  if (typeof error === 'string') return error
+  const { message, issues } = error as { message?: unknown; issues?: unknown }
+  if (typeof message !== 'string') return JSON.stringify(error)
+  // Each input the step's error names (`issues`), unless the message says them already.
+  const named = (Array.isArray(issues) ? issues : []).flatMap((i) => {
+    const issue = (i && typeof i === 'object' ? i : {}) as { path?: unknown; message?: unknown }
+    return typeof issue.message === 'string' && !message.includes(issue.message) ? [`${typeof issue.path === 'string' && issue.path ? `${issue.path}: ` : ''}${issue.message}`] : []
+  })
+  return named.length ? `${message} (${named.join('; ')})` : message
+}
+
+/** An error's code: `{ code }`, or `CODE: message` as text. */
+function errorCode(error: unknown): string | null {
+  if (!error) return null
+  if (typeof error === 'string') return /^([A-Z][A-Z0-9_]{2,})\b/.exec(error)?.[1] ?? null
+  const code = (error as { code?: unknown }).code
+  return typeof code === 'string' ? code : null
+}
+
+/** The error codes the run's failed steps (nested ones included) and the run itself carry. */
+function failureCodes(run: JudgedRun): string[] {
+  const nodes = (run.nodes ?? []).flatMap((n) => [...(n.status === 'failed' ? [errorCode(n.error)] : []), ...(n.childRun ? failureCodes(n.childRun) : [])])
+  return [...new Set([...nodes, errorCode(run.error)].filter((c): c is string => !!c))]
+}
+
+/** Whether a finished run is what the case expects; the first thing that differs when it is not. */
+export function judgeRun(c: WorkflowTestCase, run: JudgedRun): { passed: boolean; reason?: string } {
+  const failedStep = c.expect?.failedStep
+  const failedCode = c.expect?.failedCode
+  const want = c.expect?.status ?? (failedStep || failedCode ? 'failed' : 'succeeded')
+  if (run.status !== want) {
+    const failed = failedSteps(run)
+    const why = run.status === 'failed' ? `${failed.length ? ` at ${failed.join(', ')}` : ''}${run.error ? `: ${errorText(run.error).slice(0, 300)}` : ''}` : ''
+    return { passed: false, reason: `the run ${run.status}${why}; the case expects ${want}` }
+  }
+  if (failedStep) {
+    const failed = failedSteps(run)
+    if (!failed.includes(failedStep)) return { passed: false, reason: `step ${failedStep} did not fail; ${failed.length ? `${failed.join(', ')} did` : 'no step failed'}` }
+  }
+  if (failedCode) {
+    const codes = failureCodes(run)
+    if (!codes.includes(failedCode)) return { passed: false, reason: `no step failed with ${failedCode}; ${codes.length ? `the codes were ${codes.join(', ')}` : 'no failure carried a code'}` }
+  }
+  for (const check of c.expect?.output ?? []) {
+    const why = runOutputCheck(check, run)
+    if (why) return { passed: false, reason: why }
+  }
+  return { passed: true }
+}
+
+const POLL_MS = 1_500
+const DEFAULT_TIMEOUT_S = 120
+
+/** The version a case runs: the newest draft, else the newest version, else none (never pushed). */
+export function versionToTest(versions: Array<{ number: number; status: string }>): { number: number; draft: boolean } | null {
+  const sorted = [...versions].sort((a, b) => b.number - a.number)
+  const draft = sorted.find((v) => v.status === 'draft')
+  if (draft) return { number: draft.number, draft: true }
+  const newest = sorted.find((v) => v.status !== 'retired')
+  return newest ? { number: newest.number, draft: false } : null
+}
+
+/** A workflow's file in the project and what `local dev` last did with it (the build record). */
+export interface WorkflowFileState {
+  /** `workflows/<slug>.yaml`. */
+  file: string
+  /** The file's content hash now. */
+  hash: string | null
+  /** The build record's entry for it; absent when it was never applied to this runtime. */
+  applied?: Pick<BuildEntry, 'hash' | 'status' | 'version' | 'error'>
+}
+
+/** The project's file for a workflow and its build record, or null when the project has no file for the slug. */
+export function workflowFileState(project: LocalProject, organizationId: string | null, slug: string): WorkflowFileState | null {
+  const target = allTargets(project.root).find((t) => t.kind === 'workflow' && t.slug === slug)
+  if (!target || target.kind !== 'workflow') return null
+  const entry = loadBuild(project, organizationId)[target.key]
+  return { file: target.file, hash: contentHash(project, target), ...(entry ? { applied: entry } : {}) }
+}
+
+const APPLY_AGAIN = 'run `frontera local dev --once` (or keep `frontera local dev` running), then test again'
+
+/**
+ * The version a case runs when the project has the workflow's file: the one
+ * `local dev` pushed that file as, live or draft, provided the runtime still
+ * has it and the file has not changed since. Anything else is a problem to
+ * say, not a version to guess.
+ */
+export function versionForFile(slug: string, state: WorkflowFileState, versions: Array<{ number: number; status: string }>): { number: number; draft: boolean } | { problem: string } {
+  const { applied, file } = state
+  if (!applied) return { problem: `${file} is not applied to the local runtime yet: ${APPLY_AGAIN}` }
+  if (applied.status === 'failed' || applied.status === 'blocked') {
+    return { problem: `${file} did not apply (${applied.status}${applied.error ? `: ${applied.error}` : ''}), so the runtime does not run it: fix it, ${APPLY_AGAIN}` }
+  }
+  if (applied.hash !== state.hash) return { problem: `${file} changed since \`local dev\` applied it${applied.version ? ` (as v${applied.version})` : ''}, so the runtime does not run what the file says: ${APPLY_AGAIN}` }
+  if (!applied.version) return { problem: `the build record does not say which version ${file} was pushed as (it was applied by an earlier release): ${APPLY_AGAIN}` }
+  const found = versions.find((v) => v.number === applied.version)
+  if (!found) return { problem: `workflow ${slug} v${applied.version}, which \`local dev\` pushed ${file} as, is not on the runtime: run \`frontera local dev --once --reapply\`, then test again` }
+  if (found.status === 'retired') return { problem: `workflow ${slug} v${applied.version}, which \`local dev\` pushed ${file} as, is retired: run \`frontera local dev --once --reapply\`, then test again` }
+  return { number: found.number, draft: found.status === 'draft' }
+}
+
+export async function runWorkflowTests(args: {
+  serviceUrl: string
+  creds: LocalCredentials
+  files: WorkflowTestFile[]
+  onResult: (r: WorkflowTestResult) => void
+  wait?: (ms: number) => Promise<void>
+  /**
+   * The project's file for a workflow and its build record (`workflowFileState`):
+   * its cases run the version the file was pushed as. Null (or absent) for a
+   * workflow the project has no file for: its newest draft runs.
+   */
+  fileState?: (slug: string) => WorkflowFileState | null
+}): Promise<WorkflowTestResult[]> {
+  const api: Api = { serviceUrl: args.serviceUrl, creds: args.creds }
+  const wait = args.wait ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+  const results: WorkflowTestResult[] = []
+  const done = (r: WorkflowTestResult) => {
+    results.push(r)
+    args.onResult(r)
+  }
+  for (const file of args.files) {
+    const base = { workflow: file.workflow, file: file.file }
+    if (file.problem) {
+      done({ ...base, name: file.cases[0]?.name ?? file.file, passed: false, reason: `${file.file}: ${file.problem}`, ms: 0 })
+      continue
+    }
+    let version: { number: number; draft: boolean } | null = null
+    let setup: string | undefined
+    try {
+      const versions = await call<Array<{ number: number; status: string }>>(api, `/v1/workflows/${encodeURIComponent(file.workflow)}/versions`)
+      const state = args.fileState?.(file.workflow) ?? null
+      const pinned = state ? versionForFile(file.workflow, state, versions) : versionToTest(versions)
+      if (pinned && 'problem' in pinned) setup = pinned.problem
+      else version = pinned
+      if (!version && !setup) setup = `workflow ${file.workflow} has no version on the runtime: run \`frontera local dev\``
+    } catch (err) {
+      setup = /answered 404/.test((err as Error).message) ? `workflow ${file.workflow} is not on the runtime: add workflows/${file.workflow}.yaml and run \`frontera local dev\`` : (err as Error).message
+    }
+    for (const c of file.cases) {
+      const started = Date.now()
+      if (setup || !version) {
+        done({ ...base, name: c.name, passed: false, reason: setup ?? 'no version to run', ms: 0 })
+        continue
+      }
+      try {
+        const run = await call<{ runId: string; versionNumber: number }>(api, `/v1/workflows/${encodeURIComponent(file.workflow)}/run`, {
+          body: {
+            input: c.input ?? {},
+            ...(c.subject ? { subject: { pk: c.subject } } : {}),
+            version: version.number,
+            // A draft's run is a test run: it never counts as a live one.
+            ...(version.draft ? { source: 'test' } : {}),
+          },
+        })
+        const deadline = started + Math.max(1, c.timeoutSeconds ?? DEFAULT_TIMEOUT_S) * 1000
+        let seen: (JudgedRun & { id?: string }) | null = null
+        for (;;) {
+          seen = await call<JudgedRun & { id?: string }>(api, `/v1/workflows/runs/${encodeURIComponent(run.runId)}?depth=all`)
+          if (['succeeded', 'failed', 'canceled', 'cancelled'].includes(seen.status)) break
+          if (Date.now() >= deadline) break
+          await wait(POLL_MS)
+        }
+        const finished = ['succeeded', 'failed', 'canceled', 'cancelled'].includes(seen.status)
+        const verdict = finished ? judgeRun(c, { ...seen, status: seen.status === 'cancelled' ? 'canceled' : seen.status }) : { passed: false, reason: `the run was still ${seen.status} after ${c.timeoutSeconds ?? DEFAULT_TIMEOUT_S}s` }
+        done({ ...base, name: c.name, passed: verdict.passed, ...(verdict.reason ? { reason: verdict.reason } : {}), ms: Date.now() - started, runId: run.runId, version: run.versionNumber, status: seen.status })
+      } catch (err) {
+        done({ ...base, name: c.name, passed: false, reason: (err as Error).message, ms: Date.now() - started })
+      }
+    }
+  }
+  return results
+}
+
+/** A workflow test case's last local run: what Studio's Evaluations and Forge's home show beside it. */
+export interface WorkflowCaseOutcome {
+  passed: boolean
+  at: string
+  reason?: string
+  runId?: string
+}
+
+/** Last runs by case: `<workflow>\u0000<file>\u0000<name>`. */
+export type WorkflowTestRun = Record<string, WorkflowCaseOutcome>
+
+export function workflowCaseKey(r: { workflow: string; file: string; name: string }): string {
+  return `${r.workflow}\u0000${r.file}\u0000${r.name}`
+}
+
+const workflowRunPath = (stateDir: string) => join(stateDir, 'workflow-test-results.json')
+
+/** Each workflow case's last run, as `frontera local test` and `local check` left it; none before one ran. */
+export function readWorkflowTestRun(stateDir: string): WorkflowTestRun {
+  try {
+    return JSON.parse(readFileSync(workflowRunPath(stateDir), 'utf8')) as WorkflowTestRun
+  } catch {
+    return {}
+  }
+}
+
+/** Keep these results as each case's last run; cases that did not run keep theirs. Never throws. */
+export function recordWorkflowTestRun(project: LocalProject, results: WorkflowTestResult[], at = new Date().toISOString()): void {
+  if (!results.length) return
+  try {
+    const last = readWorkflowTestRun(project.stateDir)
+    for (const r of results) last[workflowCaseKey(r)] = { passed: r.passed, at, ...(r.passed || !r.reason ? {} : { reason: r.reason.slice(0, 300) }), ...(r.runId ? { runId: r.runId } : {}) }
+    writeFileAtomic(workflowRunPath(project.stateDir), `${JSON.stringify(last, null, 2)}\n`, 0o644)
+  } catch {
+    // The run's results were said; keeping them is a convenience.
+  }
+}
+
+/** A workflow's test file with each case's name and its last run, for Studio's Evaluations. */
+export interface WorkflowTestListing {
+  workflow: string
+  file: string
+  cases: number
+  list: Array<{ name: string; last: WorkflowCaseOutcome | null }>
+  problem?: string
+}
+
+export function workflowTestListing(root: string, stateDir: string): WorkflowTestListing[] {
+  const last = readWorkflowTestRun(stateDir)
+  return findWorkflowTestFiles(root).map((f) => ({
+    workflow: f.workflow,
+    file: f.file,
+    cases: f.cases.length,
+    list: f.cases.map((c) => ({ name: c.name, last: last[workflowCaseKey({ workflow: f.workflow, file: f.file, name: c.name })] ?? null })),
+    ...(f.problem ? { problem: f.problem } : {}),
+  }))
+}

package/src/local/local-workspace-grants.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+/**
+ * `blueprint/workspace-grants.yaml`: what the workspace itself — its
+ * workflows, Functions and Apps, which read through the workspace rather
+ * than as an Agent — may read of an object type beyond plain `read`. Today
+ * that is `read_sensitive`, clearance over a type's `confidential` and
+ * `restricted` fields (an Agent's own clearance is in its bindings.json).
+ *
+ *   grants:
+ *     - objectType: objectType/Customer
+ *       permissions: [read, read_sensitive]
+ *
+ * `read` is always included; `read_sensitive` is the only other permission.
+ * `local dev` applies it after each Blueprint publish (every other object
+ * type is granted plain `read`). A pull writes it when the workspace holds
+ * `read_sensitive` on some type (none: no file), and a change request
+ * carries it as the Blueprint item `blueprint/workspace-grants`: each type
+ * it lists gets the listed grant, a type it leaves out keeps its own. A
+ * deletion is never proposed, since deleting the file changes no grant: to
+ * take `read_sensitive` away, list the type with `[read]`.
+ */
+export const WORKSPACE_GRANTS_FILE = 'blueprint/workspace-grants.yaml'
+/** The item's name under `blueprint/`: its ref is `blueprint/workspace-grants`. */
+export const WORKSPACE_GRANTS_NAME = 'workspace-grants'
+export const WORKSPACE_GRANTS_REF = `blueprint/${WORKSPACE_GRANTS_NAME}`
+export const WORKSPACE_PERMISSIONS = ['read', 'read_sensitive'] as const
+
+export interface WorkspaceGrant {
+  /** The object type's API name. */
+  objectType: string
+  permissions: string[]
+}
+
+/** The file's grants, and what is wrong with it; null when the project has none. */
+export function readWorkspaceGrants(root: string): { grants: WorkspaceGrant[]; problems: string[] } | null {
+  const path = join(root, WORKSPACE_GRANTS_FILE)
+  if (!existsSync(path)) return null
+  let doc: unknown
+  try {
+    doc = parseYaml(readFileSync(path, 'utf8'))
+  } catch (err) {
+    return { grants: [], problems: [`${WORKSPACE_GRANTS_FILE} is not YAML: ${(err as Error).message.split('\n')[0]}`] }
+  }
+  const list = (doc as { grants?: unknown } | null)?.grants
+  if (doc === null || doc === undefined) return { grants: [], problems: [] }
+  if (!Array.isArray(list)) return { grants: [], problems: [`${WORKSPACE_GRANTS_FILE} needs a \`grants:\` list (\`frontera local schema blueprint-workspace-grants\`)`] }
+  const grants: WorkspaceGrant[] = []
+  const problems: string[] = []
+  list.forEach((entry, i) => {
+    const at = `${WORKSPACE_GRANTS_FILE}: grants.${i}`
+    const e = (entry && typeof entry === 'object' ? entry : {}) as { objectType?: unknown; permissions?: unknown }
+    const ref = typeof e.objectType === 'string' ? e.objectType.replace(/^objectType\//, '') : ''
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(ref)) {
+      problems.push(`${at}: objectType names an object type, as objectType/<ApiName>`)
+      return
+    }
+    const given = Array.isArray(e.permissions) ? e.permissions.filter((p): p is string => typeof p === 'string') : []
+    const unknown = given.filter((p) => !(WORKSPACE_PERMISSIONS as readonly string[]).includes(p))
+    if (unknown.length) {
+      problems.push(`${at}: ${unknown.join(', ')} ${unknown.length === 1 ? 'is not a permission' : 'are not permissions'} a workspace grant takes (read, read_sensitive)`)
+      return
+    }
+    grants.push({ objectType: ref, permissions: ['read', ...(given.includes('read_sensitive') ? ['read_sensitive'] : [])] })
+  })
+  return { grants, problems }
+}
+
+/** The file's types granted more than `read`, by permission set: `read,read_sensitive` → [Customer]. */
+export function widerGrants(grants: WorkspaceGrant[]): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  for (const g of grants) {
+    if (g.permissions.length <= 1) continue
+    const key = g.permissions.join(',')
+    out.set(key, [...(out.get(key) ?? []), g.objectType])
+  }
+  return out
+}