@frontera-sdk/cli 1.50.19 → 1.50.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.50.19",
+  "version": "1.50.20",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -39,14 +39,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
-    "@frontera-sdk/functions": "1.50.19",
-    "@frontera-sdk/core": "1.50.19",
+    "@frontera-sdk/functions": "1.50.20",
+    "@frontera-sdk/core": "1.50.20",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.50.19",
+    "@frontera-sdk/forge-contracts": "1.50.20",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/workflow-api.ts

@@ -0,0 +1,272 @@
+import { CliError } from '../errors'
+import { credentialFailure } from './credential-failure'
+
+/**
+ * `/v1/workflows`.
+ *
+ * The routes were built for this client and shipped without it: the router's
+ * own header says "a workspace key can push from the CLI", and
+ * `pushWorkflowVersion` defaults `createdVia` to `'cli'` — a value nothing
+ * could produce. Everything here is workspace-grain; organization keys are
+ * closed at the service by decision, so there is no org lane to carry.
+ */
+
+interface Envelope<T> { error?: boolean; data?: T; message?: string }
+
+/** A row of `GET /v1/workflows`. */
+export interface WorkflowSummary {
+  id: string
+  slug: string
+  enabled: boolean
+  description: string | null
+  liveVersion: number | null
+  latestDraftNumber: number | null
+  versionCount: number
+  runCount: number
+  lastRunAt: string | null
+  lastRunStatus: string | null
+  triggerKinds: string[]
+  cron: string | null
+  subjectApiName: string | null
+  subjectLabel: string | null
+}
+
+/** A row of `GET /v1/workflows/:slug/versions`. */
+export interface VersionSummary {
+  id: string
+  number: number
+  status: string
+  createdAt: string
+  createdVia?: string | null
+}
+
+/**
+ * What a push answers with.
+ *
+ * `ok: false` is a RESULT, not a transport failure — but only on a dry run.
+ * A real push that fails validation comes back as a 400, so `push` and
+ * `validate` read the same errors from two different places. Modelling both
+ * here keeps that asymmetry in one file instead of in every caller.
+ */
+export interface PushResult {
+  ok: boolean
+  errors?: string[]
+  workflowId?: string
+  version?: { id: string; number: number; status: string }
+  grants?: string[]
+  lineage?: LineageEdge[]
+}
+
+export interface LineageEdge {
+  kind: string
+  resourceKind: string
+  resourceId: string
+  label?: string | null
+  property?: string | null
+  nodeId?: string | null
+}
+
+export interface VersionLineage {
+  version: number
+  status: string
+  grants: string[]
+  lineage: LineageEdge[]
+}
+
+/** A row of `GET /v1/workflows/:slug/runs`. */
+export interface RunSummary {
+  id: string
+  status: string
+  versionNumber: number
+  workflowSlug: string
+  triggerSource: string
+  triggeredByName: string | null
+  subjectPk: string | null
+  subjectLabel: string | null
+  nodeCalls: number
+  startedAt: string
+  endedAt: string | null
+  error: unknown
+}
+
+export interface RunTreeNode {
+  nodeId: string
+  nodePath: string
+  kind: string
+  status: string
+  attempt: number
+  output: unknown
+  error: unknown
+  startedAt: string
+  endedAt: string | null
+  childRun?: RunTree | null
+}
+
+export interface RunTree {
+  id: string
+  slug: string
+  status: string
+  versionNumber: number | null
+  triggerSource: string
+  subject: { pk: string; apiName: string | null; label: string | null } | null
+  input: Record<string, unknown>
+  output: unknown
+  error: unknown
+  nodeCalls: number
+  startedAt: string
+  endedAt: string | null
+  nodes: RunTreeNode[]
+}
+
+export interface RunRequest {
+  input?: Record<string, unknown>
+  subject?: { pk: string }
+  version?: number
+}
+
+export class WorkflowApi {
+  constructor(
+    private readonly apiUrl: string,
+    private readonly token: string,
+    private readonly workspaceId?: string,
+  ) {}
+
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    return {
+      authorization: `Bearer ${this.token}`,
+      ...(this.workspaceId ? { 'x-workspace-id': this.workspaceId } : {}),
+      ...extra,
+    }
+  }
+
+  private async call<T>(path: string, init: { method?: string; body?: unknown } = {}): Promise<T> {
+    const response = await fetch(`${this.apiUrl}${path}`, {
+      method: init.method ?? 'GET',
+      headers: this.headers(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+      ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    })
+    const text = await response.text()
+    let payload: unknown
+    try { payload = text ? JSON.parse(text) : null } catch { payload = null }
+
+    if (!response.ok) {
+      const body = payload as { message?: string; code?: string; details?: unknown; detail?: string } | null
+      // The lane refusal, worded before the generic credential one gets it.
+      // `/v1/workflows` is closed to organization keys by decision, and the
+      // shared `credentialFailure` renders that 403 as "check the key carries
+      // the capability … its workspace list" — advice that cannot work, since
+      // no grant reopens a closed lane. The service names the case in
+      // `detail`; nothing read it until now.
+      if (body?.detail === 'org-key-route-closed') {
+        throw new CliError('workflows are closed to organization keys', {
+          code: 'FORBIDDEN',
+          hint: 'use a workspace key (sk-ws-) — `frontera auth list` shows which kind each profile holds. '
+            + 'A manual run executes the workflow\'s derived grants, and which principal a machine '
+            + 'credential runs as is still open, so no capability on an organization key opens this.',
+        })
+      }
+      const credential = credentialFailure(response.status, body?.message, { token: this.token })
+      if (credential) throw credential
+      // A rejected definition carries its reasons in `details.errors`, and they
+      // are the whole answer — a caller told only "Invalid workflow definition"
+      // has to re-push with `validate` to find out what was wrong.
+      const errors = readDefinitionErrors(body?.details)
+      if (errors) throw new CliError(body?.message ?? 'Invalid workflow definition', {
+        code: 'INVALID_DEFINITION',
+        hint: errors.join('\n  '),
+      })
+      throw new CliError(body?.message ?? `${response.status} from ${path}`, {
+        code: body?.code ?? 'FAILURE',
+        ...(body?.details ? { hint: JSON.stringify(body.details) } : {}),
+      })
+    }
+    const envelope = payload as Envelope<T>
+    return (envelope && envelope.error === false && 'data' in envelope
+      ? envelope.data
+      : payload) as T
+  }
+
+  list(): Promise<WorkflowSummary[]> {
+    return this.call<WorkflowSummary[]>('/v1/workflows')
+  }
+
+  get(slug: string): Promise<WorkflowSummary> {
+    return this.call<WorkflowSummary>(`/v1/workflows/${encodeURIComponent(slug)}`)
+  }
+
+  /**
+   * The version list, narrowed to the fields the CLI shows.
+   *
+   * The route answers with whole `workflow_versions` rows — `definition`,
+   * `grants`, `lineage` and `inputSchema` for EVERY version — so returning
+   * them unchanged would make `workflow get <slug> --json` dump every
+   * definition the workflow has ever had. Projected here rather than at the
+   * render site, so the `--json` contract is the same shape the table is.
+   * `workflow lineage <slug> <n>` is the verb for reading one version's body.
+   */
+  async versions(slug: string): Promise<VersionSummary[]> {
+    const rows = await this.call<VersionSummary[]>(`/v1/workflows/${encodeURIComponent(slug)}/versions`)
+    return rows.map((v) => ({
+      id: v.id,
+      number: v.number,
+      status: v.status,
+      createdAt: v.createdAt,
+      createdVia: v.createdVia ?? null,
+    }))
+  }
+
+  /**
+   * Push a definition as a new draft, or — with `dryRun` — validate it and
+   * write nothing.
+   *
+   * The definition goes up as the raw body. There is no `{ definition: … }`
+   * wrapper: the route passes `ctx.body` straight to the parser, so a wrapper
+   * would fail validation on every field at once.
+   */
+  push(slug: string, definition: unknown, opts: { dryRun?: boolean } = {}): Promise<PushResult> {
+    const query = opts.dryRun ? '?dryRun=true' : ''
+    return this.call<PushResult>(`/v1/workflows/${encodeURIComponent(slug)}/versions${query}`, {
+      method: 'PUT',
+      body: definition,
+    })
+  }
+
+  promote(slug: string, number: number): Promise<{ id: string; number: number; status: string }> {
+    return this.call(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/promote`, { method: 'POST' })
+  }
+
+  lineage(slug: string, number: number): Promise<VersionLineage> {
+    return this.call<VersionLineage>(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/lineage`)
+  }
+
+  run(slug: string, body: RunRequest): Promise<{ runId: string; versionNumber: number; reused?: boolean }> {
+    return this.call(`/v1/workflows/${encodeURIComponent(slug)}/run`, { method: 'POST', body })
+  }
+
+  /**
+   * The newest runs, at the service's default page size.
+   *
+   * The route also takes `limit` and a `before` keyset cursor; neither is
+   * 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`)
+  }
+
+  /** One run and, with `depth: 'all'`, the child runs beneath it. */
+  runById(id: string, depth: 'run' | 'all' = 'all'): Promise<RunTree> {
+    return this.call<RunTree>(`/v1/workflows/runs/${encodeURIComponent(id)}?depth=${depth}`)
+  }
+
+  cancel(id: string): Promise<{ status: string }> {
+    return this.call(`/v1/workflows/runs/${encodeURIComponent(id)}/cancel`, { method: 'POST' })
+  }
+}
+
+/** `details.errors` from a 400, when the failure was the definition itself. */
+function readDefinitionErrors(details: unknown): string[] | null {
+  const errors = (details as { errors?: unknown } | null)?.errors
+  if (!Array.isArray(errors) || errors.length === 0) return null
+  return errors.map((e) => (typeof e === 'string' ? e : JSON.stringify(e)))
+}

package/src/commands/registry.ts

@@ -34,6 +34,7 @@ import { knowledgeCommands } from './knowledge/index-commands'
 import { packCommands } from './pack/index-commands'
 import { secretCommands } from './secret/index-commands'
 import { automationCommands } from './automation/index-commands'
+import { workflowCommands } from './workflow/index-commands'
 import { completionCommand } from './completion'
 import { initCommand } from './init'
 import { loginCommand } from './login'
@@ -98,6 +99,7 @@ export const COMMANDS: readonly Command[] = [
   ...packCommands,
   ...secretCommands,
   ...automationCommands,
+  ...workflowCommands,
 
   blueprintList,
   blueprintGet,
@@ -157,6 +159,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   pack: 'Reusable skill bundles — author once, install per workspace',
   secret: 'Workspace secrets — named here, never printed back',
   function: 'Functions — TypeScript deployed here, run on a schedule',
+  workflow: 'Workflows — declared steps, versioned, promoted, then run',
   blueprint: 'The shared model of the organization — what an app can read',
   action: 'Governed Actions — arm the write path a published Action runs',
   capability: 'What an agent may DO — plugin operations granted to it',

package/src/commands/workflow/cancel.ts

@@ -0,0 +1,37 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import type { Command } from '../types'
+import { requireRunId } from './run'
+
+/**
+ * Stop a run that is still going.
+ *
+ * Takes a run id and not a slug: cancelling "the workflow" is not a thing the
+ * engine can do — each run is cancelled on its own root id, and a slug would
+ * have to pick one silently.
+ *
+ * Cancellation propagates to child runs at the service, and a run that has
+ * already finished is a no-op rather than an error, so this is safe to call on
+ * an id read from a stale listing.
+ */
+export const workflowCancel: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'cancel',
+    args: [{ name: 'runId', required: true, description: 'the run to stop' }],
+    flags: {},
+    summary: 'Stop a running workflow run, and the child runs beneath it',
+    examples: ['frontera workflow cancel 0f2c8b1e-7a41-4c96-9d3e-52b0c4a7e118'],
+  },
+
+  async run(ctx) {
+    const runId = requireRunId(ctx.positional[0])
+    const result = await new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId).cancel(runId)
+    return {
+      data: result,
+      // The status is reported rather than assumed: a run that had already
+      // succeeded comes back `succeeded`, and printing "canceled" there would
+      // be a lie the caller acts on.
+      text: `${runId}: ${result.status}`,
+    }
+  },
+}

package/src/commands/workflow/get.ts

@@ -0,0 +1,57 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+import { requireSlug } from './push'
+
+/**
+ * One workflow: what is live, what is drafted, and what it is bound to.
+ *
+ * The version table is here rather than under a separate `versions` verb
+ * because the two questions are never asked apart — "what is live" is only
+ * meaningful beside "what else exists", and `promote` needs a number from this
+ * list.
+ */
+export const workflowGet: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'get',
+    args: [{ name: 'slug', required: true, description: 'workflow slug' }],
+    flags: {},
+    summary: 'Show one workflow, its versions and which is live',
+    examples: ['frontera workflow get invoice-intake'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const [workflow, versions] = await Promise.all([client.get(slug), client.versions(slug)])
+
+    const facts = [
+      `${workflow.slug}${workflow.enabled ? '' : '  (disabled)'}`,
+      workflow.description ? `  ${workflow.description}` : '',
+      `  live       ${workflow.liveVersion === null ? 'nothing — no version has been promoted' : `v${workflow.liveVersion}`}`,
+      `  triggers   ${(workflow.triggerKinds ?? []).join(', ') || 'none'}`,
+      // Only when bound. An unbound workflow has no subject line to print, and
+      // an empty one reads as a missing value rather than an absent concept.
+      workflow.subjectApiName ? `  subject    ${workflow.subjectLabel ?? workflow.subjectApiName}` : '',
+      `  runs       ${workflow.runCount ?? 0}${workflow.lastRunStatus ? `, last ${workflow.lastRunStatus}` : ''}`,
+    ].filter(Boolean)
+
+    const versionTable = versions.length === 0
+      ? '  (none — `frontera workflow push` stores the first)'
+      : table(
+          ['VERSION', 'STATUS', 'PUSHED', 'VIA'],
+          versions.map((v) => [
+            `v${v.number}`,
+            v.status,
+            v.createdAt,
+            v.createdVia ?? '',
+          ]),
+        )
+
+    return {
+      data: { workflow, versions },
+      text: `${facts.join('\n')}\n\nVersions\n${versionTable}`,
+    }
+  },
+}

package/src/commands/workflow/index-commands.ts

@@ -0,0 +1,41 @@
+import { workflowCancel } from './cancel'
+import { workflowGet } from './get'
+import { workflowLineage } from './lineage'
+import { workflowList } from './list'
+import { workflowPromote } from './promote'
+import { workflowPush, workflowValidate } from './push'
+import { workflowRun } from './run'
+import { workflowRuns } from './runs'
+import type { Command } from '../types'
+
+/**
+ * Workflows, which had no client at all.
+ *
+ * The routes were written for this: `/v1/workflows` authenticates through the
+ * same programmatic middleware Functions use so a workspace key can push, and
+ * `pushWorkflowVersion` stamps `createdVia: 'cli'` by default — an origin no
+ * caller could produce. Until now the only way to author a workflow was the
+ * Console, which means a definition could not be reviewed in a pull request or
+ * promoted from CI.
+ *
+ * Organization keys are deliberately absent, and that is the service's
+ * decision rather than an omission here: a manual run executes the workflow's
+ * derived grants, and which principal a machine credential runs as is the same
+ * open question that keeps `POST /v1/functions/:slug/run` undeclared. A key
+ * that pushed and promoted but could not run would be the more confusing half.
+ *
+ * Bindings are absent for a different reason: an agent binding is a standing
+ * permission for a model to start runs, it gates on `edit`, and it belongs
+ * beside the agent it grants — not beside the definition it points at.
+ */
+export const workflowCommands: readonly Command[] = [
+  workflowList,
+  workflowGet,
+  workflowValidate,
+  workflowPush,
+  workflowPromote,
+  workflowRun,
+  workflowRuns,
+  workflowCancel,
+  workflowLineage,
+]

package/src/commands/workflow/lineage.ts

@@ -0,0 +1,58 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+import { requireSlug } from './push'
+import { requireVersionNumber } from './promote'
+
+/**
+ * What one version reads, writes and invokes.
+ *
+ * Derived from the definition at push time, never authored — which is exactly
+ * why it is worth printing. An author reads their own steps and sees intent;
+ * this reads the same steps and reports reach, and the two differ whenever a
+ * step touches something through a reference the author did not follow.
+ *
+ * The version is required rather than defaulting to live: "what does this
+ * touch" asked of a workflow with an unpromoted draft has two different
+ * answers, and guessing which one was meant is how a review misses a change.
+ */
+export const workflowLineage: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'lineage',
+    args: [
+      { name: 'slug', required: true, description: 'workflow slug' },
+      { name: 'version', required: true, description: 'version number' },
+    ],
+    flags: {},
+    summary: 'What one version reads, writes and invokes — and the grants it runs with',
+    examples: ['frontera workflow lineage invoice-intake 3'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const number = requireVersionNumber(ctx)
+    const lineage = await new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId).lineage(slug, number)
+
+    const head = `${slug} v${lineage.version} (${lineage.status})\n`
+      + `  grants  ${lineage.grants.length > 0 ? lineage.grants.join(', ') : 'none'}`
+
+    if (lineage.lineage.length === 0) {
+      return { data: lineage, text: `${head}\n\n  This version touches nothing outside itself.` }
+    }
+
+    return {
+      data: lineage,
+      text: `${head}\n\n${table(
+        ['EDGE', 'KIND', 'RESOURCE', 'PROPERTY', 'STEP'],
+        lineage.lineage.map((e) => [
+          e.kind,
+          e.resourceKind,
+          e.label ?? e.resourceId,
+          e.property ?? '',
+          e.nodeId ?? '',
+        ]),
+      )}`,
+    }
+  },
+}

package/src/commands/workflow/list.ts

@@ -0,0 +1,58 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+/**
+ * Every workflow in the workspace, and whether anything can start one.
+ *
+ * `LIVE` is the column that decides: a workflow with drafts and no live
+ * version parses, validates and never runs, and nothing else in the CLI says
+ * so. `TRIGGERS` is beside it because a live version whose only trigger is
+ * `manual` will also never fire on its own — the two facts are read together.
+ */
+export const workflowList: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List workflows, their live version and what can start them',
+    examples: ['frontera workflow list'],
+  },
+
+  async run(ctx) {
+    const rows = await new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId).list()
+
+    if (rows.length === 0) {
+      return {
+        data: { workflows: [] },
+        text: 'No workflows in this workspace.\n'
+          + '  frontera workflow push <slug> <file.yaml>   # to create one',
+      }
+    }
+
+    return {
+      data: { workflows: rows },
+      text: table(
+        ['SLUG', 'LIVE', 'DRAFT', 'TRIGGERS', 'RUNS', 'LAST'],
+        rows.map((r) => [
+          r.slug,
+          // A disabled workflow is skipped by the cron dispatcher
+          // (`workflow-cron.ts` filters on `enabled`), so one with a live
+          // version and a schedule still never fires. Rendered identically to
+          // an armed one, this column would answer the question wrongly.
+          // Both facts, because they are different: `v3 off` is armed-but-held,
+          // `— ` is nothing promoted. Collapsing them would lose which.
+          `${r.liveVersion === null ? '—' : `v${r.liveVersion}`}${r.enabled === false ? ' off' : ''}`,
+          r.latestDraftNumber === null ? '' : `v${r.latestDraftNumber}`,
+          // The cron expression rather than the word "cron": a schedule nobody
+          // can read is the most common reason a workflow fires at a surprising
+          // time, and it fits.
+          (r.triggerKinds ?? []).map((k) => (k === 'cron' && r.cron ? `cron(${r.cron})` : k)).join(' ') || '—',
+          String(r.runCount ?? 0),
+          r.lastRunStatus ?? '',
+        ]),
+      ),
+    }
+  },
+}

package/src/commands/workflow/promote.ts

@@ -0,0 +1,78 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import { UsageError } from '../../errors'
+import type { Command, CommandContext } from '../types'
+import { describeReach, requireSlug } from './push'
+
+/**
+ * `<n>`, rejected locally when it is not a version number.
+ *
+ * Forwarded as typed, `promote wf abc` reaches a route declared `t.Numeric()`
+ * and comes back as a schema violation naming a parameter the author never
+ * saw. The word they typed is the answer, so it is named here.
+ */
+export function requireVersionNumber(ctx: CommandContext): number {
+  const raw = ctx.positional[1]
+  if (!raw) {
+    throw new UsageError('missing <version>', 'frontera workflow get <slug> lists the versions')
+  }
+  const parsed = Number(raw)
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new UsageError(`"${raw}" is not a version number`, 'versions are whole numbers from 1')
+  }
+  return parsed
+}
+
+/**
+ * Make one version the live one.
+ *
+ * The verb that arms a definition, and the only one that changes what a
+ * trigger or an agent binding will execute. Separate from `push` on purpose:
+ * the draft an author is iterating on and the version their organization runs
+ * are not the same act, and collapsing them would make every save a deploy.
+ */
+export const workflowPromote: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'promote',
+    args: [
+      { name: 'slug', required: true, description: 'workflow slug' },
+      { name: 'version', required: true, description: 'version number to make live' },
+    ],
+    flags: {},
+    summary: 'Make one version live — what triggers and agents will run',
+    examples: ['frontera workflow promote invoice-intake 3'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const number = requireVersionNumber(ctx)
+    const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const promoted = await client.promote(slug, number)
+
+    // Read AFTER the promote, so the reach printed is the one now armed rather
+    // than the one the author last validated. On a workflow promoted from CI
+    // these are the same; on one promoted days after the push they need not be.
+    //
+    // The failure is REPORTED, not swallowed. Silently omitting the block on a
+    // 403 or a 5xx would show "v3 is live" with no reach, which reads as "it
+    // touches nothing" — the opposite of what this read exists to tell the
+    // person who just armed it. The promote itself already succeeded, so this
+    // must not throw.
+    let lineage = null
+    let lineageError: string | null = null
+    try {
+      lineage = await client.lineage(slug, number)
+    } catch (err) {
+      lineageError = (err as Error).message
+    }
+    const reach = lineage ? describeReach(lineage.grants, lineage.lineage) : ''
+
+    return {
+      data: { promoted, lineage, lineageError },
+      text: `${slug}: v${number} is live\n`
+        + (reach ? `${reach}\n` : '')
+        + (lineageError ? `  (could not read what it touches: ${lineageError})\n` : '')
+        + `  frontera workflow run ${slug}   # to start one now`,
+    }
+  },
+}