@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/api/workflow-api.ts

@@ -23,7 +23,10 @@ export interface WorkflowSummary {
   liveVersion: number | null
   latestDraftNumber: number | null
   versionCount: number
+  /** Live top-level runs only: test runs and a workflow's child runs are not counted. */
   runCount: number
+  /** Test runs (a draft run from `local test`, Studio or `workflow_run`); absent from a service that does not count them. */
+  testRunCount?: number
   lastRunAt: string | null
   lastRunStatus: string | null
   triggerKinds: string[]
@@ -67,6 +70,8 @@ export interface PushResult {
   version?: { id: string; number: number; status: string }
   grants?: string[]
   lineage?: LineageEdge[]
+  /** What the service accepted but says, one sentence each (a step that may not be able to run here). */
+  warnings?: string[]
 }
 
 export interface LineageEdge {
@@ -263,8 +268,8 @@ export class WorkflowApi {
    * carried here, because no verb pages yet and a parameter no caller passes
    * reads as a capability the CLI has. `function runs` is capped the same way.
    */
-  runs(slug: string): Promise<RunSummary[]> {
-    return this.call<RunSummary[]>(`/v1/workflows/${encodeURIComponent(slug)}/runs`)
+  runs(slug: string, source?: 'live' | 'test'): Promise<RunSummary[]> {
+    return this.call<RunSummary[]>(`/v1/workflows/${encodeURIComponent(slug)}/runs${source ? `?source=${source}` : ''}`)
   }
 
   /** One run and, with `depth: 'all'`, the child runs beneath it. */
@@ -272,9 +277,35 @@ export class WorkflowApi {
     return this.call<RunTree>(`/v1/workflows/runs/${encodeURIComponent(id)}?depth=${depth}`)
   }
 
+  /** Take a workflow out of service, every version and run kept: nothing starts it, and it takes no new version until restored. */
+  archive(slug: string): Promise<{ id: string; slug: string; archivedAt: string | null }> {
+    return this.call(`/v1/workflows/${encodeURIComponent(slug)}/archive`, { method: 'POST' })
+  }
+
+  /** Put an archived workflow back as it was. */
+  restore(slug: string): Promise<{ id: string; slug: string; archivedAt: string | null }> {
+    return this.call(`/v1/workflows/${encodeURIComponent(slug)}/restore`, { method: 'POST' })
+  }
+
   cancel(id: string): Promise<{ status: string }> {
     return this.call(`/v1/workflows/runs/${encodeURIComponent(id)}/cancel`, { method: 'POST' })
   }
+
+  /**
+   * Arm the test door of a workflow's draft for one delivery, as Studio's
+   * Listen does: the latest draft unless `version` names one. Answers each
+   * webhook door's test URL and when the Listen ends.
+   */
+  listen(slug: string, version?: number): Promise<WebhookListen> {
+    return this.call(`/v1/workflows/${encodeURIComponent(slug)}/listen`, { method: 'POST', body: version === undefined ? {} : { version } })
+  }
+}
+
+/** `POST /v1/workflows/:slug/listen`. */
+export interface WebhookListen {
+  version: number
+  until: string
+  doors: Array<{ path: string; methods: string[]; test: string }>
 }
 
 /** `details.errors` from a 400, when the failure was the definition itself. */

package/src/app-contract.ts

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { DEFAULT_BLUEPRINT_TYPES_OUTPUT } from './blueprint-types'
+import { collectSourceFiles } from './packaging'
+import { APP_SDK_PACKAGES } from './template'
+
+/**
+ * What a Custom App calls on the platform, read from its source at deploy
+ * (design 2026-10-18 §6, the Blueprint contract): the object types it reads
+ * with the properties its generated types give them, the governed Actions it
+ * submits and the Functions it starts. The platform checks it against the
+ * workspace a deployment would go live in. Best effort by construction: a
+ * name built at run time is not seen, and nothing here is authority.
+ */
+
+export interface AppContract {
+  /** The Blueprint schema digest the App's generated types came from. */
+  digest?: string
+  objectTypes: Record<string, string[]>
+  actions: string[]
+  functions: string[]
+}
+
+const CODE = /\.(tsx?|jsx?|mjs|cjs)$/
+
+const OBJECT_READ = [
+  /\buse(?:Objects|ObjectInstance)\s*(?:<[^>]*>)?\(\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]/g,
+  /\bobjectType\s*:\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]/g,
+  /\/v1\/blueprint\/object-types\/([A-Za-z_][A-Za-z0-9_]*)\//g,
+]
+const ACTION = [/\buseAction\s*\(\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]/g, /governed-actions\/actions\/([A-Za-z_][A-Za-z0-9_]*)\/requests/g]
+const FUNCTION = [/\/v1\/(?:functions|automations)\/([a-z0-9][a-z0-9-]*)\/app-run/g, /\b(?:runFunction|startFunction)\s*\(\s*['"]([a-z0-9][a-z0-9-]*)['"]/g]
+
+/**
+ * The SDK copy a pulled App carries under src/frontera/ (`APP_SDK_PACKAGES`):
+ * the platform's code, not the App's. It names no object type of the App's
+ * except in its examples, so it is not read.
+ */
+const SDK_COPY_DIRS = Object.values(APP_SDK_PACKAGES).map((p) => `${p.dir}/`)
+const isSdkCopy = (rel: string) => SDK_COPY_DIRS.some((dir) => rel.startsWith(dir))
+
+/** Before a token, a `/` starts a regular expression rather than a division. */
+const REGEX_BEFORE = /(?:^|[(,=:[!&|?{};+\-*%~^]|\b(?:return|typeof|case|do|else|in|of|new|delete|void|throw|yield|await))\s*$/
+
+/**
+ * The code with its comments blanked out (the same length, line breaks kept):
+ * a doc comment's example, such as `useObjects('SupportTicket')` in the SDK's
+ * own docs, is not a call. Strings, template literals and regular
+ * expressions are read as such, so a `//` in a URL is not a comment.
+ */
+export function withoutComments(text: string): string {
+  let out = ''
+  let i = 0
+  // Template literals nest through `${…}`: each open one, and the brace depth its expression is at.
+  const templates: number[] = []
+  let depth = 0
+  const blank = (s: string) => s.replace(/[^\n]/g, ' ')
+  while (i < text.length) {
+    const c = text[i]!
+    const next = text[i + 1]
+    if (c === '/' && next === '/') {
+      const end = text.indexOf('\n', i)
+      const stop = end < 0 ? text.length : end
+      out += blank(text.slice(i, stop))
+      i = stop
+      continue
+    }
+    if (c === '/' && next === '*') {
+      const end = text.indexOf('*/', i + 2)
+      const stop = end < 0 ? text.length : end + 2
+      out += blank(text.slice(i, stop))
+      i = stop
+      continue
+    }
+    if (c === '/' && REGEX_BEFORE.test(out.slice(-40))) {
+      let j = i + 1
+      let inClass = false
+      while (j < text.length && text[j] !== '\n') {
+        const d = text[j]!
+        if (d === '\\') j += 1
+        else if (d === '[') inClass = true
+        else if (d === ']') inClass = false
+        else if (d === '/' && !inClass) break
+        j += 1
+      }
+      out += text.slice(i, j + 1)
+      i = j + 1
+      continue
+    }
+    if (c === "'" || c === '"') {
+      let j = i + 1
+      while (j < text.length && text[j] !== c && text[j] !== '\n') j += text[j] === '\\' ? 2 : 1
+      out += text.slice(i, j + 1)
+      i = j + 1
+      continue
+    }
+    if (c === '`' || (c === '}' && templates.length && templates.at(-1) === depth)) {
+      // A template literal's text, from its start or the end of a `${…}` up to its end or the next `${`.
+      if (c === '}') templates.pop()
+      let j = i + 1
+      while (j < text.length && text[j] !== '`' && !(text[j] === '$' && text[j + 1] === '{')) j += text[j] === '\\' ? 2 : 1
+      if (text[j] === '$') {
+        templates.push(depth)
+        out += text.slice(i, j + 2)
+        i = j + 2
+      } else {
+        out += text.slice(i, j + 1)
+        i = j + 1
+      }
+      continue
+    }
+    if (c === '{') depth += 1
+    else if (c === '}') depth -= 1
+    out += c
+    i += 1
+  }
+  return out
+}
+
+function matches(text: string, patterns: RegExp[], into: Set<string>): void {
+  for (const pattern of patterns) for (const m of text.matchAll(pattern)) if (m[1]) into.add(m[1])
+}
+
+/** Each object type's properties as the App's generated Blueprint types declare them. */
+export function generatedProperties(text: string): { digest?: string; types: Map<string, string[]> } {
+  const digest = text.match(/Blueprint schema digest: (sha256:[0-9a-f]{64})/)?.[1]
+  const types = new Map<string, string[]>()
+  for (const block of text.matchAll(/export interface ([A-Za-z_][A-Za-z0-9_]*) \{\n([\s\S]*?)\n\}/g)) {
+    const props = [...block[2]!.matchAll(/^ {2}([A-Za-z_][A-Za-z0-9_]*)\??:/gm)].map((m) => m[1]!)
+    types.set(block[1]!, props)
+  }
+  return { ...(digest ? { digest } : {}), types }
+}
+
+export function collectAppContract(root: string): AppContract {
+  const objects = new Set<string>()
+  const actions = new Set<string>()
+  const functions = new Set<string>()
+  const generated = join(root, DEFAULT_BLUEPRINT_TYPES_OUTPUT)
+  for (const file of collectSourceFiles(root)) {
+    if (!CODE.test(file.rel) || file.rel.startsWith('.frontera/') || isSdkCopy(file.rel) || join(root, file.rel) === generated || /(^|\/)(__tests__|tests?)\//.test(file.rel) || /\.(test|spec)\.[jt]sx?$/.test(file.rel)) continue
+    // What the code calls, not what its comments show.
+    const text = withoutComments(new TextDecoder().decode(file.bytes))
+    matches(text, OBJECT_READ, objects)
+    matches(text, ACTION, actions)
+    matches(text, FUNCTION, functions)
+  }
+  const types = existsSync(generated) ? generatedProperties(readFileSync(generated, 'utf8')) : { types: new Map<string, string[]>() }
+  return {
+    ...('digest' in types && types.digest ? { digest: types.digest } : {}),
+    objectTypes: Object.fromEntries([...objects].sort().map((name) => [name, types.types.get(name) ?? []])),
+    actions: [...actions].sort(),
+    functions: [...functions].sort(),
+  }
+}

package/src/app-lock.ts

@@ -0,0 +1,125 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The `@frontera-sdk/*` versions an App's own lockfile resolved from the
+ * registry: what its code was written and checked against. A pulled App's
+ * `bun.lock` (or `package-lock.json`) is the best record of that, better than
+ * whatever SDK this CLI carries, so a repair goes back to it instead of
+ * swapping in another SDK the code was never built with.
+ *
+ * Only registry resolutions count (`1.50.61`): a `file:`, `link:` or
+ * `workspace:` entry records a copy that may not exist anywhere else.
+ */
+export interface LockedSdk {
+  /** The version the lockfile installed, e.g. `1.50.61`. */
+  version: string
+  /** The range package.json asked for when the lockfile was written (`^1.43.10`), when it was a registry range. */
+  range?: string
+}
+
+const REGISTRY_VERSION = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/
+const REGISTRY_RANGE = /^[\^~]?\d+(?:\.\d+){0,2}(?:[-+][\w.-]+)?$/
+
+/** Whether a package.json spec is a registry version or range (`^1.50.61`, `1.50.61`), not a `file:`, `link:` or `workspace:` one. */
+export const isRegistryRange = (spec: string | undefined): boolean => !!spec && REGISTRY_RANGE.test(spec)
+
+export function lockedSdkVersions(appRoot: string): Map<string, LockedSdk> {
+  const out = new Map<string, LockedSdk>()
+  let bun: string | null = null
+  try {
+    bun = readFileSync(join(appRoot, 'bun.lock'), 'utf8')
+  } catch {
+    bun = null
+  }
+  if (bun) {
+    // `"@frontera-sdk/blueprint": ["@frontera-sdk/blueprint@1.50.61", …]` under `packages`.
+    for (const m of bun.matchAll(/"(@frontera-sdk\/[a-z0-9-]+)":\s*\[\s*"(@frontera-sdk\/[a-z0-9-]+)@([^"]+)"/g)) {
+      if (m[1] !== m[2] || !REGISTRY_VERSION.test(m[3]!) || out.has(m[1]!)) continue
+      out.set(m[1]!, { version: m[3]! })
+    }
+    // `"@frontera-sdk/blueprint": "^1.43.10"` under the root workspace's dependencies.
+    for (const m of bun.matchAll(/"(@frontera-sdk\/[a-z0-9-]+)":\s*"([^"]+)"/g)) {
+      const locked = out.get(m[1]!)
+      if (locked && !locked.range && REGISTRY_RANGE.test(m[2]!)) locked.range = m[2]!
+    }
+    return out
+  }
+  try {
+    const npm = JSON.parse(readFileSync(join(appRoot, 'package-lock.json'), 'utf8')) as {
+      packages?: Record<string, { version?: string; resolved?: string; dependencies?: Record<string, string> }>
+    }
+    const root = npm.packages?.[''] ?? {}
+    for (const [key, entry] of Object.entries(npm.packages ?? {})) {
+      const m = /^node_modules\/(@frontera-sdk\/[a-z0-9-]+)$/.exec(key)
+      if (!m || !entry.version || !REGISTRY_VERSION.test(entry.version) || (entry.resolved && !/^https?:/.test(entry.resolved))) continue
+      const range = root.dependencies?.[m[1]!]
+      out.set(m[1]!, { version: entry.version, ...(range && REGISTRY_RANGE.test(range) ? { range } : {}) })
+    }
+  } catch {
+    // No lockfile: nothing recorded.
+  }
+  return out
+}
+
+/**
+ * The spec that brings the locked version back: a caret on the release the
+ * lockfile installed (`^1.50.61`), never the older range the lockfile was
+ * written for (`^1.43.10`), so package.json names the SDK the code was
+ * checked against even where an install runs without the lockfile.
+ */
+export function lockedSpec(locked: LockedSdk): string {
+  return `^${locked.version}`
+}
+
+/**
+ * Record in the App's lockfile that package.json now asks for `specs`, so a
+ * frozen install (`bun install --frozen-lockfile`, CI, `app deploy`) accepts
+ * the restored package.json: only the root workspace's own dependency ranges
+ * change, never a resolution, and each spec still matches the release the
+ * lockfile installed. Returns whether the lockfile changed.
+ */
+export function recordLockedRanges(appRoot: string, specs: Record<string, string>): boolean {
+  const names = Object.keys(specs)
+  if (!names.length) return false
+  const bunPath = join(appRoot, 'bun.lock')
+  let bun: string | null = null
+  try {
+    bun = readFileSync(bunPath, 'utf8')
+  } catch {
+    bun = null
+  }
+  if (bun !== null) {
+    // The root workspace's ranges sit between `"workspaces": {` and the top-level `"packages": {`.
+    const start = bun.indexOf('"workspaces"')
+    const end = start < 0 ? -1 : bun.indexOf('\n  "packages"', start)
+    if (start < 0 || end < 0) return false
+    let section = bun.slice(start, end)
+    for (const pkg of names) {
+      const escaped = pkg.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+      section = section.replace(new RegExp(`("${escaped}":\\s*)"[^"]*"`, 'g'), (_m, head: string) => `${head}"${specs[pkg]}"`)
+    }
+    const next = bun.slice(0, start) + section + bun.slice(end)
+    if (next === bun) return false
+    writeFileSync(bunPath, next)
+    return true
+  }
+  const npmPath = join(appRoot, 'package-lock.json')
+  try {
+    const text = readFileSync(npmPath, 'utf8')
+    const npm = JSON.parse(text) as { packages?: Record<string, { dependencies?: Record<string, string> }> }
+    const root = npm.packages?.['']
+    if (!root?.dependencies) return false
+    let changed = false
+    for (const pkg of names) {
+      if (pkg in root.dependencies && root.dependencies[pkg] !== specs[pkg]) {
+        root.dependencies[pkg] = specs[pkg]!
+        changed = true
+      }
+    }
+    if (changed) writeFileSync(npmPath, `${JSON.stringify(npm, null, /^(\s+)"/m.exec(text)?.[1] ?? 2)}\n`)
+    return changed
+  } catch {
+    return false
+  }
+}

package/src/args.ts

@@ -6,6 +6,12 @@ export type FlagSpec = Readonly<Record<string, FlagKind>>
 export interface ParsedArgs {
   positional: string[]
   flags: Record<string, string | boolean>
+  /**
+   * Every value of a string flag given more than once, in order. `flags`
+   * keeps the last; a command that ANDs repeated values (`--where`) reads
+   * them all here.
+   */
+  repeated: Record<string, string[]>
 }
 
 /**
@@ -28,6 +34,11 @@ export function parseArgs(
 ): ParsedArgs {
   const positional: string[] = []
   const flags: Record<string, string | boolean> = {}
+  const repeated: Record<string, string[]> = {}
+  const setString = (name: string, value: string) => {
+    if (typeof flags[name] === 'string') (repeated[name] ??= [flags[name] as string]).push(value)
+    flags[name] = value
+  }
 
   for (let i = 0; i < argv.length; i += 1) {
     let token = argv[i]!
@@ -86,7 +97,7 @@ export function parseArgs(
 
     if (eq !== -1) {
       // `--dir=` is a deliberate empty string, not a missing value.
-      flags[name] = token.slice(eq + 1)
+      setString(name, token.slice(eq + 1))
       continue
     }
 
@@ -100,9 +111,9 @@ export function parseArgs(
         `pass it as --${name} <value> or --${name}=<value>`,
       )
     }
-    flags[name] = value
+    setString(name, value)
     i += 1
   }
 
-  return { positional, flags }
+  return { positional, flags, repeated }
 }

package/src/auth-verify.ts

@@ -29,6 +29,16 @@ export function classifyKey(token: string): CredentialKind {
   )
 }
 
+/**
+ * Whether a token is a key rather than a person's session, by its prefix:
+ * workspace (`sk-ws-`), organization (`sk-org-`) and every other `sk-` key
+ * the platform issues, and an Agent key (`sak_`), which a profile does not
+ * store but `FRONTERA_TOKEN` can carry. A person's session token has neither.
+ */
+export function isKeyToken(token: string): boolean {
+  return token.startsWith('sk-') || token.startsWith('sak_')
+}
+
 /**
  * Prove the key works BEFORE it is stored.
  *

package/src/automation-template.ts

@@ -38,12 +38,20 @@ export const AUTOMATION_SDK_FILES = [
   // `testing.ts` imports the file-handle helpers from it; without it every
   // scaffolded project failed to build with `Could not resolve: "./runtime-context"`.
   'frontera/automation/runtime-context.ts',
+  // `FronteraCallError`, which every `ctx.*` refusal throws and `index.ts`,
+  // `testing.ts` and `runtime-context.ts` import.
+  'frontera/automation/errors.ts',
   // `inputs.ts` is authoring surface too: `validateInputValue` is what a
   // handler's own tests and the Console call to check a value against the
   // manifest's `inputs` schema, and `index.ts` re-exports it — so omitting it
   // breaks a scaffolded project's typecheck the same way skipping `testing.ts`
   // would.
   'frontera/automation/inputs.ts',
+  // `subjectOf` (an Action's subject and version from a query row) is exported
+  // by `index.ts`; `test-check.ts` is how `define.ts` checks a handler the way
+  // the platform will when `testing.ts` runs it.
+  'frontera/automation/subject.ts',
+  'frontera/automation/test-check.ts',
   'frontera/blueprint/types.ts',
 ] as const
 
@@ -187,8 +195,10 @@ import automation, { OBJECT_TYPE } from './index'
 // A handler is just a function, so it can be tested without deploying. The
 // context refuses what the platform refuses — a grant the manifest does not
 // declare, a step name used twice — so a passing test means something.
+// \`replay: true\` runs it as the platform does, again from the top after each
+// step, so a read outside a step that a later step changes fails here too.
 test('handles an empty result', async () => {
-  const { ctx, steps } = createTestContext({ grants: ['blueprint:read'] })
+  const { ctx, steps } = createTestContext({ replay: true, grants: ['blueprint:read'] })
 
   const result = await automation.handler(ctx)
 
@@ -199,6 +209,7 @@ test('handles an empty result', async () => {
 
 test('handles rows', async () => {
   const { ctx, steps } = createTestContext({
+    replay: true,
     grants: ['blueprint:read'],
     // Stub only what this test is about; an object type you do not stub returns
     // no rows, which is a real answer.