@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/commands/workflow/run.ts

@@ -1,4 +1,4 @@
-import { WorkflowApi, type RunRequest, type RunTree, type RunTreeNode } from '../../api/workflow-api'
+import { WorkflowApi, type RunRequest, type RunTree, type RunTreeNode, type VersionSummary } from '../../api/workflow-api'
 import { CliError, UsageError } from '../../errors'
 import { readSecretValue } from '../../secrets'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
@@ -85,22 +85,54 @@ export async function parseInputFlag(ctx: CommandContext): Promise<Record<string
 }
 
 /**
- * `--version N`, or undefined for the live one.
+ * `--version N`, `--version draft`, or undefined for the live one.
  *
  * Rejected here rather than forwarded for the reason `promote` rejects its
  * argument: `--version abc` arriving as `NaN` comes back naming a field the
  * author never typed.
+ *
+ * `draft` (and its synonym `latest`) is the alias the MCP `workflow_run` and
+ * `frontera local test` already take: the newest version that is not retired,
+ * which `resolveVersion` looks up. Without it an author had to read the number
+ * from `workflow get` first, and that number moves on every push or apply.
  */
-export function parseVersionFlag(ctx: CommandContext): number | undefined {
+export function parseVersionFlag(ctx: CommandContext): number | 'draft' | undefined {
   const raw = flagString(ctx, 'version')
   if (raw === undefined) return undefined
+  const word = raw.trim().toLowerCase()
+  if (word === 'draft' || word === 'latest') return 'draft'
   const parsed = Number(raw)
   if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new UsageError(`"${raw}" is not a version number`, 'frontera workflow get <slug> lists the versions')
+    throw new UsageError(`"${raw}" is not a version number or "draft"`, 'frontera workflow get <slug> lists the versions; `--version draft` runs the newest')
   }
   return parsed
 }
 
+/**
+ * The version number a `--version` flag names: a number as given, and `draft` as
+ * the newest version that is not retired. That is the draft just pushed, or the
+ * live version when a person promoted it (promoting retires the older drafts),
+ * the same rule as the MCP `workflow_run`'s `pickVersion`.
+ */
+export async function resolveVersion(
+  requested: number | 'draft' | undefined,
+  versions: () => Promise<VersionSummary[]>,
+  slug: string,
+): Promise<number | undefined> {
+  if (requested !== 'draft') return requested
+  const rows = await versions()
+  const newest = [...rows].sort((a, b) => b.number - a.number).find((v) => v.status !== 'retired')
+  if (!newest) {
+    throw new CliError(
+      rows.length
+        ? `workflow "${slug}" has only retired versions (${rows.map((v) => `v${v.number}`).join(', ')}), so there is no draft to run`
+        : `workflow "${slug}" has no version yet, so there is no draft to run`,
+      { code: 'NOT_FOUND', hint: `push its definition first: \`frontera workflow push ${slug} <file>\`, or in a local project \`frontera local dev --once\`` },
+    )
+  }
+  return newest.number
+}
+
 /** One line per node, nested under the run each child step started. */
 export function describeNodes(nodes: RunTreeNode[], depth = 1): string[] {
   const lines: string[] = []
@@ -108,6 +140,8 @@ export function describeNodes(nodes: RunTreeNode[], depth = 1): string[] {
     const indent = '  '.repeat(depth)
     const failed = node.status === 'failed' ? ' ✗' : ''
     lines.push(`${indent}${node.nodeId}  ${node.kind}  ${node.status}${failed}`)
+    // A failed step's error, and each input it named (`issues`): the reason, where it happened.
+    if (node.error) lines.push(...stepErrorLines(node.error, `${indent}  `))
     // A `forEach` or a `workflow` step is a run of its own, and its steps are
     // where its failure is explained — flattening them would report a failed
     // parent with no reason anywhere in the output.
@@ -116,6 +150,26 @@ export function describeNodes(nodes: RunTreeNode[], depth = 1): string[] {
   return lines
 }
 
+/**
+ * A step's recorded error as lines: `{ code, message }`, then each of its
+ * `issues` (`{ path, message }`, the input it named and the rule it broke).
+ */
+export function stepErrorLines(error: unknown, indent: string): string[] {
+  if (typeof error === 'string') return [`${indent}error ${error}`]
+  if (!error || typeof error !== 'object') return []
+  const e = error as { code?: unknown; message?: unknown; issues?: unknown }
+  const head = [typeof e.code === 'string' ? e.code : '', typeof e.message === 'string' ? e.message : ''].filter(Boolean).join(': ')
+  const issues = Array.isArray(e.issues)
+    ? e.issues.flatMap((i) => {
+        const issue = (i && typeof i === 'object' ? i : {}) as { path?: unknown; message?: unknown }
+        const message = typeof issue.message === 'string' ? issue.message : ''
+        if (!message) return []
+        return [`${indent}  · ${typeof issue.path === 'string' && issue.path ? `${issue.path}: ` : ''}${message}`]
+      })
+    : []
+  return [`${indent}error ${head || JSON.stringify(error)}`, ...issues]
+}
+
 /**
  * The subject of a bound run, as "<type> <pk>".
  *
@@ -136,7 +190,7 @@ export function describeRun(run: RunTree): string {
   if (run.subject) lines.push(`  subject ${describeSubject(run.subject)}`)
   // The error before the steps: it is the reason the reader opened this, and
   // burying it under a trail of successful steps is how it gets missed.
-  if (run.error) lines.push(`  error ${typeof run.error === 'string' ? run.error : JSON.stringify(run.error)}`)
+  if (run.error) lines.push(...stepErrorLines(run.error, '  '))
   lines.push(...describeNodes(run.nodes))
   if (run.output !== null && run.output !== undefined) lines.push(`  returned ${JSON.stringify(run.output)}`)
   return lines.join('\n')
@@ -166,13 +220,17 @@ export const workflowRun: Command = {
     verb: 'run',
     args: [{ name: 'slug', required: true, description: 'workflow slug' }],
     flags: { 'no-wait': 'boolean', input: 'string', subject: 'string', version: 'string' },
-    summary: 'Run the live version now — or a named one — and report what it did',
+    summary: 'Run the live version now — or a named one, or the newest draft — and report what it did',
+    details: [
+      '`--version <n>` runs that version. `--version draft` runs the newest version that is not retired: the draft you last pushed or applied, or the live version once a person promoted it (`latest` means the same). Without `--version`, the live version runs.',
+    ],
     examples: [
       'frontera workflow run invoice-intake',
       'frontera workflow run invoice-intake --input \'{"threshold": 500}\'',
       'frontera workflow run invoice-intake --input @input.json',
       'frontera workflow run shipment-review --subject SHP-0000001',
       'frontera workflow run invoice-intake --version 3 --no-wait',
+      'frontera workflow run invoice-intake --version draft --input @input.json',
     ],
   },
 
@@ -188,7 +246,7 @@ export const workflowRun: Command = {
     // pk and nothing else, and asking for `{"pk":"…"}` on a command line would
     // be quoting ceremony around a single value.
     if (subject) body.subject = { pk: subject }
-    const version = parseVersionFlag(ctx)
+    const version = await resolveVersion(parseVersionFlag(ctx), () => client.versions(slug), slug)
     if (version !== undefined) body.version = version
 
     const started = await client.run(slug, body)

package/src/commands/workflow/runs.ts

@@ -1,7 +1,7 @@
 import { WorkflowApi } from '../../api/workflow-api'
-import { CliError } from '../../errors'
+import { CliError, UsageError } from '../../errors'
 import { table } from '../../table'
-import type { Command } from '../types'
+import { flagString, type Command } from '../types'
 import { describeRun, describeSubject, requireRunId } from './run'
 import { requireSlug } from './push'
 
@@ -25,10 +25,11 @@ export const workflowRuns: Command = {
         description: 'one run to open, with its steps; omit to list recent runs',
       },
     ],
-    flags: {},
-    summary: 'List recent runs, newest first — or open one run and its steps',
+    flags: { only: 'string' },
+    summary: 'List recent runs, newest first — or open one run and its steps (--only live|test: live runs, or test runs)',
     examples: [
       'frontera workflow runs invoice-intake',
+      'frontera workflow runs invoice-intake --only live',
       'frontera workflow runs invoice-intake 0f2c8b1e-7a41-4c96-9d3e-52b0c4a7e118',
     ],
   },
@@ -56,11 +57,13 @@ export const workflowRuns: Command = {
       return { data: run, text: describeRun(run) }
     }
 
-    const rows = await client.runs(slug)
+    const source = flagString(ctx, 'only')
+    if (source !== undefined && source !== 'live' && source !== 'test') throw new UsageError(`--only takes live or test, not "${source}"`, `e.g. \`frontera workflow runs ${slug} --only live\``)
+    const rows = await client.runs(slug, source)
     if (rows.length === 0) {
       return {
         data: { runs: [] },
-        text: `No runs recorded for ${slug}.\n  frontera workflow run ${slug}   # to start one`,
+        text: `No ${source ? `${source} ` : ''}runs recorded for ${slug}.\n  frontera workflow run ${slug}   # to start one`,
       }
     }
 

package/src/commands/workflow/webhook-test.ts

@@ -0,0 +1,166 @@
+import { readFileSync } from 'node:fs'
+
+import { WorkflowApi, type RunSummary, type WebhookListen } from '../../api/workflow-api'
+import { CliError, UsageError } from '../../errors'
+import { flagString, type Command } from '../types'
+
+/**
+ * Send one delivery to a workflow's webhook on its DRAFT, and show what came
+ * back: the run the mapping (`$request.body`, headers, query) produced.
+ *
+ * The draft's test door (`/v1/hooks-test/…`) answers only while a Listen is
+ * armed, which was Studio's button alone, so a webhook's mapping could not be
+ * tried before a version went live. This arms it (`POST
+ * /v1/workflows/:slug/listen`: one delivery, within 120 seconds) and delivers
+ * straight away. The trigger's own auth still applies: pass what the sender
+ * would send with `--header`.
+ */
+
+/** The door to send to: the one at `path`, or the only one. */
+export function pickDoor(listen: WebhookListen, path: string | undefined, slug: string): WebhookListen['doors'][number] {
+  const doors = listen.doors
+  if (!doors.length) throw new CliError(`workflow ${slug} v${listen.version} has no webhook trigger`, { code: 'USAGE', hint: 'add a `kind: webhook` trigger to its file, or run it with `frontera workflow run`' })
+  const wanted = path?.replace(/^\/+/, '')
+  if (wanted !== undefined) {
+    const door = doors.find((d) => d.path.replace(/^\/+/, '') === wanted)
+    if (!door) throw new UsageError(`workflow ${slug} has no webhook at "${wanted}"`, `its webhooks: ${doors.map((d) => d.path || '(no path)').join(', ')}`)
+    return door
+  }
+  if (doors.length > 1) throw new UsageError(`workflow ${slug} has ${doors.length} webhooks; say which with --path`, `its webhooks: ${doors.map((d) => d.path || '(no path)').join(', ')}`)
+  return doors[0]!
+}
+
+/** The test door on the address this CLI talks to: the service names its public address, which a local runtime may not answer on. */
+export function doorUrl(test: string, apiUrl: string, query: string | undefined): string {
+  const url = new URL(test)
+  const at = new URL(url.pathname, apiUrl.replace(/\/+$/, '') + '/')
+  if (query) for (const [k, v] of new URLSearchParams(query.replace(/^\?/, ''))) at.searchParams.append(k, v)
+  return at.toString()
+}
+
+/** `Name: value`, as a sender's header. */
+export function parseHeader(raw: string | undefined): Record<string, string> {
+  if (!raw) return {}
+  const at = raw.indexOf(':')
+  if (at <= 0) throw new UsageError('--header takes `Name: value`', "e.g. --header 'X-Signature: abc123'")
+  return { [raw.slice(0, at).trim()]: raw.slice(at + 1).trim() }
+}
+
+/** `--version`: a draft's number, or `draft` (and `latest`) for the latest draft, as the MCP tool takes it. */
+export function readVersionFlag(raw: string | undefined): number | undefined {
+  if (raw === undefined || /^(draft|latest)$/i.test(raw.trim())) return undefined
+  const version = Number(raw)
+  if (!Number.isInteger(version) || version < 1) throw new UsageError('--version takes a draft’s number, or draft for the latest one', 'e.g. --version 3 or --version draft; leave it out for the latest draft')
+  return version
+}
+
+/**
+ * The run a delivery started: the id the door answered with (`respond:
+ * immediately` gives it), else the newest test run of that version since the
+ * delivery was sent. Null when none shows up within a few seconds.
+ */
+export async function findDeliveredRun(list: () => Promise<RunSummary[] | unknown>, version: number, sentAt: number, answered: unknown, tries = 6, waitMs = 500): Promise<string | null> {
+  const fromBody = answered && typeof answered === 'object' && typeof (answered as { runId?: unknown }).runId === 'string' ? (answered as { runId: string }).runId : null
+  if (fromBody) return fromBody
+  for (let attempt = 0; attempt < tries; attempt++) {
+    const page = await Promise.resolve().then(list).catch(() => null)
+    const rows = (Array.isArray(page) ? page : ((page as { items?: unknown[] } | null)?.items ?? [])) as Array<Partial<RunSummary>>
+    const mine = rows
+      .filter((r) => typeof r.id === 'string' && (r.versionNumber === undefined || r.versionNumber === null || r.versionNumber === version) && Date.parse(r.startedAt ?? '') >= sentAt)
+      .sort((a, b) => Date.parse(b.startedAt ?? '') - Date.parse(a.startedAt ?? ''))
+    if (mine[0]) return mine[0].id!
+    if (attempt < tries - 1) await new Promise((r) => setTimeout(r, waitMs))
+  }
+  return null
+}
+
+function readBody(from: string | undefined): string | undefined {
+  if (from === undefined) return undefined
+  if (from === '-') return readFileSync(0, 'utf8')
+  try {
+    return readFileSync(from, 'utf8')
+  } catch {
+    throw new UsageError(`could not read ${from}`, 'pass a JSON file with --body, or - for standard input')
+  }
+}
+
+export const workflowWebhookTest: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'webhook-test',
+    args: [{ name: 'workflow', required: true, description: 'the workflow’s slug' }],
+    flags: { body: 'string', path: 'string', method: 'string', header: 'string', query: 'string', version: 'string' },
+    summary: 'Send one test delivery to a workflow’s webhook on its draft, and show the run it made',
+    examples: [
+      'frontera workflow webhook-test work-order-intake --body fault.json',
+      'frontera workflow webhook-test intake --path fault-reports --body -',
+      "frontera workflow webhook-test intake --body a.json --header 'X-Key: k1'",
+      'frontera workflow webhook-test intake --body a.json --version draft --json',
+    ],
+  },
+
+  async run(ctx) {
+    const slug = ctx.positional[0]
+    if (!slug) throw new UsageError('missing <workflow>', 'frontera workflow webhook-test <slug> --body payload.json')
+    const version = readVersionFlag(flagString(ctx, 'version'))
+    const body = readBody(flagString(ctx, 'body'))
+    if (body !== undefined) {
+      try {
+        JSON.parse(body)
+      } catch {
+        // A sender may post text or a form: sent as it is, said here.
+        ctx.output.note('[webhook-test] the body is not JSON: it is sent as text')
+      }
+    }
+    const headers = parseHeader(flagString(ctx, 'header'))
+
+    const api = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const listen = await api.listen(slug, version).catch((err: unknown) => {
+      if (err instanceof CliError && /not.?found|404/i.test(`${err.code} ${err.message}`) && /listen/i.test(err.message)) {
+        throw new CliError('this platform release cannot arm a draft’s webhook from the CLI', { code: 'UNSUPPORTED', hint: 'use Listen on the workflow’s page, or update to a release that supports `frontera workflow webhook-test`' })
+      }
+      throw err
+    })
+    const door = pickDoor(listen, flagString(ctx, 'path'), slug)
+    const method = (flagString(ctx, 'method') ?? (door.methods.includes('POST') ? 'POST' : door.methods[0] ?? 'POST')).toUpperCase()
+    if (door.methods.length && !door.methods.includes(method)) throw new UsageError(`the webhook at "${door.path}" takes ${door.methods.join(', ')}, not ${method}`, `--method ${door.methods[0]}`)
+    const url = doorUrl(door.test, ctx.apiUrl, flagString(ctx, 'query'))
+    const sent = method === 'GET' || method === 'HEAD' ? undefined : body
+    // A second back, so a run the runtime stamps a moment before the delivery returns still counts.
+    const sentAt = Date.now() - 1_000
+    const res = await fetch(url, {
+      method,
+      headers: { ...(sent !== undefined ? { 'content-type': 'application/json' } : {}), ...headers },
+      ...(sent !== undefined ? { body: sent } : {}),
+    })
+    const text = await res.text()
+    let answer: unknown = text
+    try {
+      answer = text ? JSON.parse(text) : null
+    } catch {
+      // Kept as text.
+    }
+    // The run the delivery made, so `--json` shows it (a refused delivery made none).
+    const runId = res.status === 401 || res.status === 403 || res.status === 404 ? null : await findDeliveredRun(() => api.runs(slug, 'test'), listen.version, sentAt, answer)
+    const data = { workflow: slug, version: listen.version, path: door.path, method, status: res.status, response: answer, runId }
+    if (!res.ok) {
+      throw new CliError(`the webhook answered ${res.status} on the draft (v${listen.version})`, {
+        code: 'WEBHOOK_TEST_FAILED',
+        hint: res.status === 401 || res.status === 403
+          ? 'the trigger’s auth refused the delivery: pass what the sender sends with --header'
+          : res.status === 404
+            ? 'the test door did not answer: the Listen may have ended, or the path or method differs from the trigger’s'
+            : `${typeof answer === 'string' ? answer.slice(0, 300) : JSON.stringify(answer).slice(0, 300)}`,
+        details: data,
+      })
+    }
+    return {
+      data,
+      text: [
+        `${method} ${door.path ? `/${door.path.replace(/^\/+/, '')}` : '(no path)'} on workflow ${slug} v${listen.version} (draft): ${res.status}`,
+        typeof answer === 'string' ? answer : JSON.stringify(answer, null, 2),
+        runId ? `  the run: frontera workflow runs ${slug} ${runId}` : `  the run: frontera workflow runs ${slug} --only test`,
+      ].join('\n'),
+    }
+  },
+}

package/src/config.ts

@@ -4,9 +4,11 @@ import { credentialStore, type CredentialSource } from './credential-store'
 import { CliError, UsageError } from './errors'
 import { migrateLegacyConfig } from './profile-migration'
 import { configPath, type Env } from './paths'
+import { localRuntimeProfileOf } from './local/local-project'
 import { findContext } from './project-context'
 import {
   assertOriginMatches,
+  getProfile,
   isLegacyConfig,
   listProfiles,
   normalizeOrigin,
@@ -72,6 +74,25 @@ export interface CredentialDeps {
 export interface ResolveOptions {
   apiUrl?: string
   profile?: string
+  /**
+   * The command acts at organization grain. In a directory bound to a local
+   * runtime's workspace profile (`local-<project>`), the runtime's
+   * organization profile beside it (`local-<project>-org`) is selected
+   * instead: the same runtime, the key its organization commands need.
+   */
+  organization?: boolean
+}
+
+/**
+ * The organization profile `local start` registers beside a local runtime's
+ * workspace profile, when this is one and it has one.
+ */
+export function localOrganizationCompanion(profile: string, env: Env = process.env): string | null {
+  if (!profile.startsWith('local-')) return null
+  const org = `${profile}-org`.slice(0, 64)
+  if (org === profile || getProfile(profile, env)?.credentialKind !== 'workspace') return null
+  const companion = getProfile(org, env)
+  return companion?.credentialKind === 'organization' && companion.apiUrl === getProfile(profile, env)?.apiUrl ? org : null
 }
 
 /**
@@ -103,16 +124,24 @@ export function resolveProfileName(
      * question rather than an answer, and `auth use` is how it gets answered.
      */
     if (!found.trusted) {
+      // A copied or pulled project carries the machine it came from's selection. When this directory
+      // has its own local runtime, ITS profile is the one to bind: the named one belongs to another
+      // directory (another project's runtime, or another machine's).
+      const own = localRuntimeProfileOf(found.root)
+      const ownHere = own && own !== found.profile && getProfile(own, env) ? own : null
       throw new CliError(
         `${found.path} selects "${found.profile}", but this machine never bound that directory`,
         {
           code: 'PROJECT_CONTEXT_UNTRUSTED',
-          hint:
-            `if you meant to use it, run \`frontera auth use ${found.profile}\` in ${found.root} — `
-            + 'a context file committed to a repository is not proof that you chose it',
+          hint: ownHere
+            ? `this directory has its own local runtime, whose profile is ${ownHere} (\`frontera local status\` names it): run \`frontera auth use ${ownHere}\` in ${found.root}. "${found.profile}" was bound where this project came from, and would reach that runtime instead`
+            : `if you meant to use it, run \`frontera auth use ${found.profile}\` in ${found.root} — `
+              + 'a context file committed to a repository is not proof that you chose it',
         },
       )
     }
+    const companion = opts.organization ? localOrganizationCompanion(found.profile, env) : null
+    if (companion) return { profile: companion, source: 'directory', path: found.path }
     return { profile: found.profile, source: 'directory', path: found.path }
   }
 
@@ -144,9 +173,18 @@ export async function resolveCredential(
   await ensureMigrated(env)
 
   const store = deps.store ?? credentialStore(env)
-  const selection = resolveProfileName(opts, deps)
-
   const explicitOrigin = opts.apiUrl ?? env.FRONTERA_API_URL
+  const envToken = env.FRONTERA_TOKEN?.trim()
+  // A raw token with its own origin uses no stored key, so a context file this machine did not
+  // bind is nothing to refuse: it only names the profile the result reports (none, here).
+  let selection: ReturnType<typeof resolveProfileName>
+  try {
+    selection = resolveProfileName(opts, deps)
+  } catch (err) {
+    if (!(envToken && explicitOrigin && err instanceof CliError && err.code === 'PROJECT_CONTEXT_UNTRUSTED')) throw err
+    selection = { profile: null, source: 'none' }
+  }
+
   const originSource: OriginSource = opts.apiUrl ? 'flag' : env.FRONTERA_API_URL ? 'environment' : 'profile'
 
   /**
@@ -155,7 +193,6 @@ export async function resolveCredential(
    * would be sent to whatever deployment the checked-out directory happens to
    * select. That is a cross-customer credential leak with no visible symptom.
    */
-  const envToken = env.FRONTERA_TOKEN?.trim()
   if (envToken) {
     if (!explicitOrigin) {
       throw new UsageError(

package/src/dev-broker.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from 'node:crypto'
+import { createServer } from 'node:net'
 
 import type { BridgeInit } from '@frontera-sdk/core/bridge-protocol'
 
@@ -69,3 +70,54 @@ export function createDevSessionBroker(options: {
 
   return { endpoint: `http://127.0.0.1:${server.port}${path}`, server }
 }
+
+/** The addresses an App's port must be free on: the browser resolves `localhost` to either loopback, and a wildcard listener answers both. */
+export const LOOPBACK_ADDRESSES = ['127.0.0.1', '::1', '0.0.0.0', '::'] as const
+
+function freeOn(port: number, host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer()
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      // No IPv6 on this machine: nothing can hold the port there either.
+      resolve(err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')
+    })
+    server.listen({ port, host, exclusive: true, ...(host === '::' ? { ipv6Only: true } : {}) }, () => server.close(() => resolve(true)))
+  })
+}
+
+/**
+ * Whether nothing listens on `port` on either loopback, IPv4 or IPv6, nor on
+ * a wildcard. Probing 127.0.0.1 alone let a dev server start beside another
+ * process holding the port on ::1, and `localhost` and `127.0.0.1` then
+ * served two different Apps.
+ */
+export async function isLoopbackPortFree(port: number, hosts: readonly string[] = LOOPBACK_ADDRESSES): Promise<boolean> {
+  for (const host of hosts) if (!(await freeOn(port, host))) return false
+  return true
+}
+
+/** A port the system hands out on 127.0.0.1 (`listen(0)`), closed again at once. */
+function systemPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen({ port: 0, host: '127.0.0.1', exclusive: true }, () => {
+      const address = server.address()
+      const port = typeof address === 'object' && address ? address.port : 0
+      server.close(() => (port ? resolve(port) : reject(new Error('the system gave no port'))))
+    })
+  })
+}
+
+/**
+ * A port free on every loopback address (`isLoopbackPortFree`), for `--port 0`:
+ * the system picks it on 127.0.0.1, and one something holds on ::1 or a
+ * wildcard is passed over for the next.
+ */
+export async function freeLoopbackPort(isFree: (port: number) => Promise<boolean> = isLoopbackPortFree): Promise<number> {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const port = await systemPort()
+    if (await isFree(port)) return port
+  }
+  throw new Error('no port was free on every loopback address after 20 tries')
+}

package/src/exit.ts

@@ -16,7 +16,12 @@ export const EXIT = {
   FAILURE: 1,
   /** Bad invocation or bad input. Fix the command. */
   USAGE: 2,
-  /** Someone else changed it first. Re-fetch, reapply. */
+  /**
+   * Someone else changed it first, or the state of the record or the request
+   * refuses it (a governed Action's submission criteria, a request whose
+   * outcome is unknown). Re-read, then change the input or the record; the
+   * same request is refused again, so never retry it as it is.
+   */
   CONFLICT: 3,
   /** Credentials or permission. Neither retry nor rewording helps. */
   AUTH: 4,
@@ -58,8 +63,75 @@ const USAGE_CODES = new Set([
   // Authoring kit. Both are resolved by running a named command, not by retry.
   'KIT_VERSION_MISMATCH',
   'GENERATED_FILE_CONFLICT',
+  // The Idempotency-Key was used for a different request: a new key fixes it,
+  // re-reading does not. (An effect another request already made is a
+  // conflict: see CONFLICT_REASONS.)
+  'ACTION_IDEMPOTENCY_CONFLICT',
+  // An Action that isn't there to submit, or a submit without the key it needs.
+  'ACTION_NOT_FOUND',
+  'ACTION_IDEMPOTENCY_KEY_REQUIRED',
 ])
-const CONFLICT_CODES = new Set(['DRAFT_CONFLICT', 'CONFLICT', 'VALIDATION_STALE'])
+/**
+ * Someone changed it first: re-read, then decide or submit again. Each of
+ * these is fixed by re-reading the record or the request, which a retry of
+ * the same body never does.
+ */
+const CONFLICT_CODES = new Set([
+  'DRAFT_CONFLICT',
+  'CONFLICT',
+  'VALIDATION_STALE',
+  // The record moved past `expectedVersion`: read it again, submit with the new one.
+  'ACTION_SOURCE_VERSION_STALE',
+  // The request changed under its approvals: read the request again.
+  'ACTION_APPROVAL_STALE',
+  // The record already has an open request of this Action (`openRequests: one_per_subject`):
+  // read that request (`details.openRequest`) instead of submitting another.
+  'ACTION_REQUEST_ALREADY_OPEN',
+  // Refused by the state of the record, the Action or the request: the same
+  // request is refused every time, so exit 1 ("retry") would send a caller
+  // round a loop. Each is fixed by re-reading and changing something first.
+  // The record or the input fails the Action's submission criteria.
+  'ACTION_CRITERIA_FAILED',
+  // The Action is switched off, has no binding, its binding is revoked or
+  // suspended, or it has no deployment (`ACTION_NOT_DEPLOYED`, the CLI's word
+  // for that 409): nothing changes until someone turns it back on or deploys it.
+  'ACTION_DISABLED',
+  'ACTION_UNBOUND',
+  'ACTION_BINDING_REVOKED',
+  'ACTION_BINDING_SUSPENDED',
+  'ACTION_NOT_DEPLOYED',
+  // It needs an approval first, or affects more records than the Action allows.
+  'ACTION_APPROVAL_REQUIRED',
+  'ACTION_EFFECT_LIMIT_EXCEEDED',
+  // The outcome is settled or unknown: read the request (`action requests`),
+  // never submit again — a second submit could make the change twice.
+  'ACTION_CONFIRMED_NOT_APPLIED',
+  'ACTION_OUTCOME_UNKNOWN',
+  'ACTION_RESOLUTION_REQUIRED',
+  'AUTOMATION_PUBLISH_UNCERTAIN',
+  // The dataset's rows are written somewhere else now.
+  'DATASET_AUTHORITY_MOVED',
+])
+/**
+ * Refusals the service sends under another code with a `reason` that is a
+ * conflict: the approval step moved on, or another request already made the
+ * effect. They exit 3 whatever their code.
+ */
+const CONFLICT_REASONS = new Set([
+  'ACTION_APPROVAL_STEP_CHANGED',
+  'ACTION_LOGICAL_EFFECT_CONFLICT',
+  'ACTION_SOURCE_VERSION_STALE',
+  'ACTION_REQUEST_ALREADY_OPEN',
+])
+
+/** A refusal's `reason`, at the top of its details or nested one level under `details`. */
+export function reasonOf(details: unknown): string | undefined {
+  if (typeof details !== 'object' || details === null) return undefined
+  const body = details as { reason?: unknown; details?: unknown }
+  if (typeof body.reason === 'string') return body.reason
+  const nested = body.details
+  return typeof nested === 'object' && nested !== null && typeof (nested as { reason?: unknown }).reason === 'string' ? (nested as { reason: string }).reason : undefined
+}
 const AUTH_CODES = new Set([
   'UNAUTHORIZED',
   'FORBIDDEN',
@@ -78,7 +150,9 @@ const AUTH_CODES = new Set([
  * an SDK release — which means this function must treat "never seen it" as
  * ordinary, not exceptional.
  */
-export function exitCodeFor(code: string): ExitCode {
+export function exitCodeFor(code: string, details?: unknown): ExitCode {
+  const reason = reasonOf(details)
+  if (reason && CONFLICT_REASONS.has(reason)) return EXIT.CONFLICT
   if (USAGE_CODES.has(code)) return EXIT.USAGE
   if (CONFLICT_CODES.has(code)) return EXIT.CONFLICT
   if (AUTH_CODES.has(code)) return EXIT.AUTH
@@ -98,6 +172,10 @@ const SERVICE_HINTS: Record<string, string> = {
   // which case they are in throw a CliError with a specific hint instead.
   CONFLICT: 'the message above names what conflicted — resolve that, then retry',
   VALIDATION_STALE: 're-fetch the resource and re-run validation against the current revision',
+  ACTION_SOURCE_VERSION_STALE: 'the record changed first — read it again (`frontera blueprint query`), then submit with its current version as expectedVersion',
+  ACTION_APPROVAL_STALE: 'the request changed under its approvals — read it again (`frontera action requests`), then decide',
+  ACTION_IDEMPOTENCY_CONFLICT: 'that Idempotency-Key belongs to another request — submit with a new key',
+  ACTION_REQUEST_ALREADY_OPEN: 'this record already has an open request of this Action — follow it (`frontera action requests <requestId>`, the id in the details) instead of submitting another',
   // Names neither kind. Both are valid here — a workspace key for agents,
   // skills, plugins and knowledge; an organization key for Blueprint authoring,
   // datasets and Sources — and naming only one sent holders of the other
@@ -223,6 +301,19 @@ function hintFor(code: string, details: unknown): string | undefined {
   return SERVICE_HINTS[code]
 }
 
+/**
+ * A refusal that names what it refused only in its details (`invalid_plugins`
+ * with `{ invalid: ['decision'] }`), said with the names: the message alone
+ * leaves nobody able to tell which entry to take out.
+ */
+export function withRefusedNames(message: string, details: unknown): string {
+  if (!/^invalid_[a-z_]+$/.test(message) || typeof details !== 'object' || details === null) return message
+  const body = details as { invalid?: unknown; details?: { invalid?: unknown } }
+  const invalid = Array.isArray(body.invalid) ? body.invalid : Array.isArray(body.details?.invalid) ? body.details.invalid : null
+  const names = invalid?.filter((n): n is string => typeof n === 'string') ?? []
+  return names.length ? `${message}: ${names.join(', ')}` : message
+}
+
 function isFronteraError(
   err: unknown,
 ): err is { code: string; message: string; details?: unknown } {
@@ -246,8 +337,16 @@ export function toEnvelope(err: unknown): ErrorEnvelope {
   }
 
   if (isFronteraError(err)) {
+    // Invoking an Action that has no deployment, through any client: said as that.
+    const details = err.details as { details?: { reason?: unknown; readinessReason?: unknown; deploymentStatus?: unknown } ; reason?: unknown; readinessReason?: unknown; deploymentStatus?: unknown } | undefined
+    const nd = details?.reason === 'ACTION_NOT_DEPLOYED' ? details : details?.details?.reason === 'ACTION_NOT_DEPLOYED' ? details.details : null
+    if (nd) {
+      const why = typeof nd.readinessReason === 'string' ? nd.readinessReason : typeof nd.deploymentStatus === 'string' ? `its deployment is ${nd.deploymentStatus}` : 'it has no active deployment'
+      return { error: true, code: 'ACTION_NOT_DEPLOYED', message: `${err.message.replace(/[.]$/, '')}: the Action isn't deployed: ${why}`, hint: '`frontera action list` shows why each Action cannot run; `frontera action deploy <name>` builds its write path' }
+    }
     const hint = hintFor(err.code, err.details)
-    return { error: true, code: err.code, message: err.message, ...(hint ? { hint } : {}) }
+    const reason = reasonOf(err.details)
+    return { error: true, code: err.code, message: withRefusedNames(err.message, err.details), ...(hint ? { hint } : {}), ...(reason ? { details: { reason } } : {}) }
   }
 
   return {