@frontera-sdk/cli 0.1.0 → 1.43.6

package/src/commands/automation/run.ts

@@ -0,0 +1,271 @@
+import { CliError, UsageError } from '../../errors'
+import {
+  AutomationApi,
+  type AutomationRunStep,
+  type AutomationRunSummary,
+  type RegistryStatus,
+} from '../../api/automation-api'
+import { flagBool, type Command, type CommandContext } from '../types'
+
+/**
+ * How long to wait for a queued run to reach a terminal state.
+ *
+ * Shorter than the runner's own 10m ceiling on purpose. A CLI that blocks for
+ * ten minutes reads as hung, and the run is not lost when this gives up — it is
+ * still recorded, and the timeout message says where to look. Bounding the WAIT
+ * is not the same as bounding the RUN.
+ */
+const WAIT_TIMEOUT_MS = 120_000
+const POLL_INTERVAL_MS = 2_000
+
+/**
+ * How long to wait for a runner to register the current generation.
+ *
+ * A separate, shorter budget than the run wait: this one is bounded by a poll
+ * interval and a PUT, not by how long an automation takes.
+ */
+const CATCHUP_TIMEOUT_MS = 45_000
+
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled'])
+
+/**
+ * Can the broker invoke what the service has deployed?
+ *
+ * The whole reason this check exists: an invoke event matches functions at
+ * INGEST, so one sent before the runner has registered the new generation
+ * matches nothing and is dropped. The run never appears and no amount of waiting
+ * recovers it, because the event is gone. `deploy` then `run` is the most
+ * natural pair of commands an author types, and it hit this every time.
+ *
+ * A null `registeredGeneration` means no runner has ever registered — a
+ * different failure, and one worth naming differently.
+ */
+export function isRunnerCaughtUp(status: RegistryStatus): boolean {
+  return status.registeredGeneration !== null
+    && status.registeredGeneration >= status.generation
+}
+
+/** Has this run stopped, or might it still change? */
+export function isTerminal(status: string): boolean {
+  return TERMINAL.has(status)
+}
+
+/**
+ * Is `latest` the run this invoke started, or one that already existed?
+ *
+ * By ID and not by count. Counting rows would call a concurrently-firing cron's
+ * run "mine" and report ITS outcome as the outcome of this command — and on an
+ * automation whose cron is every five minutes that is not a rare race. A null
+ * baseline means the automation had never run, so any row is new.
+ */
+export function isNewRun(priorId: string | null, latest: { id: string } | undefined): boolean {
+  return latest !== undefined && latest.id !== priorId
+}
+
+function requireSlug(ctx: CommandContext): string {
+  const slug = ctx.positional[0]
+  if (!slug) {
+    throw new UsageError(
+      'missing <slug>',
+      'run `frontera automation list` — then pass the slug of the one you mean',
+    )
+  }
+  return slug
+}
+
+/** ms as something short enough to sit at the end of a trail line. */
+function duration(ms: number | null): string {
+  if (ms === null) return ''
+  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`
+}
+
+/**
+ * A run's steps, nested under the step each `ctx` call ran inside.
+ *
+ * Rows arrive in `seq` order — the order they were written — which interleaves
+ * two steps' children once a run has more than one. Walking the parent map is
+ * what keeps each step with its own calls.
+ *
+ * Exported for its own test: the ordering is the part that is easy to get
+ * subtly wrong and impossible to notice by eye.
+ */
+export function describeTrail(steps: AutomationRunStep[]): string[] {
+  const byParent = new Map<string | null, AutomationRunStep[]>()
+  const known = new Set(steps.map((s) => s.id))
+  for (const step of steps) {
+    // A parent outside this list is treated as top level rather than dropped —
+    // losing a row from the trail is worse than losing its indent.
+    const parent = step.parentStepId && known.has(step.parentStepId) ? step.parentStepId : null
+    byParent.set(parent, [...(byParent.get(parent) ?? []), step])
+  }
+
+  const lines: string[] = []
+  const walk = (parent: string | null, depth: number): void => {
+    for (const step of byParent.get(parent) ?? []) {
+      const indent = '  '.repeat(depth + 1)
+      const kind = step.stepName !== null ? 'step' : step.kind
+      const failed = step.status === 'error' ? ' ✗' : ''
+      const took = duration(step.durationMs)
+      lines.push(`${indent}${step.label}  ${kind}${failed}${took ? `  ${took}` : ''}`)
+      walk(step.id, depth + 1)
+    }
+  }
+  walk(null, 0)
+  return lines
+}
+
+/** One line describing a finished run, its trail, and its output. */
+export function describeRun(run: AutomationRunSummary, steps: AutomationRunStep[] = []): string {
+  const lines = [`${run.status} — v${run.version}, ${run.ctxCalls} ctx call(s)`]
+  if (run.errorMessage) lines.push(`  ${run.errorMessage}`)
+  // The trail is why an author ran this by hand: which steps executed, in what
+  // order, and where the time went. Without it the CLI reported an outcome and
+  // sent them to the Console to find out what happened.
+  lines.push(...describeTrail(steps))
+  if (run.result !== null && run.result !== undefined) {
+    lines.push(`  returned ${JSON.stringify(run.result)}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Start a run and, by default, wait for it.
+ *
+ * Waiting is the default because the reason to run an automation by hand is to
+ * find out what it does. A verb that printed "queued" and exited would leave the
+ * author to discover the answer some other way — and until now there was no
+ * other way from the CLI at all.
+ *
+ * The run is identified by taking the newest run id BEFORE the invoke and
+ * waiting for a different one to appear. Comparing ids rather than counting
+ * rows, because a cron firing concurrently also adds a row; and reading the
+ * baseline first, because a run that finishes before the first poll would
+ * otherwise look like it never started.
+ */
+export const automationRun: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'run',
+    args: [{ name: 'slug', required: true, description: 'automation slug' }],
+    flags: { 'no-wait': 'boolean' },
+    summary: 'Run the live version now and report what it did',
+    examples: [
+      'frontera automation run daily-digest',
+      'frontera automation run daily-digest --no-wait',
+    ],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+
+    // Wait for the runner BEFORE invoking, not after. An event sent early is
+    // dropped rather than queued, so there is nothing to wait for afterwards.
+    const catchupDeadline = Date.now() + CATCHUP_TIMEOUT_MS
+    let status = await client.registryStatus()
+    while (!isRunnerCaughtUp(status) && Date.now() < catchupDeadline) {
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
+      status = await client.registryStatus()
+    }
+    if (!isRunnerCaughtUp(status)) {
+      throw new CliError(
+        status.registeredGeneration === null
+          ? 'no automation runner has ever registered with the broker, so nothing '
+            + 'can execute this automation'
+          : `the runner is still on registry generation ${status.registeredGeneration} `
+            + `and the service is on ${status.generation} — a version deployed since `
+            + 'then is not invocable yet',
+        {
+          code: 'REQUEST_FAILED',
+          // Refusing BEFORE sending is the point: an invoke event sent now would
+          // match no function and vanish, and the author would be told their run
+          // never appeared without being told why.
+          hint: 'wait for the runner to pick up the deploy, then run this again',
+        },
+      )
+    }
+
+    const before = await client.runs(slug, 1)
+    const priorId = before[0]?.id ?? null
+
+    const queued = await client.run(slug)
+
+    if (flagBool(ctx, 'no-wait')) {
+      return {
+        data: queued,
+        text: `Queued a run of ${slug} v${queued.version}.\n`
+          + `  frontera automation runs ${slug}   # to see how it went`,
+      }
+    }
+
+    const deadline = Date.now() + WAIT_TIMEOUT_MS
+    let seen: AutomationRunSummary | undefined
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
+      const [latest] = await client.runs(slug, 1)
+      if (isNewRun(priorId, latest) && latest) {
+        seen = latest
+        if (isTerminal(latest.status)) {
+          // Best-effort: a run that finished is the answer, and failing to read
+          // its trail must not turn a successful run into a failed command.
+          const steps = await client.runSteps(latest.id).catch(() => [])
+          return { data: { ...latest, steps }, text: `${slug}: ${describeRun(latest, steps)}` }
+        }
+      }
+    }
+
+    // NOT an error about the automation — an error about the wait. The
+    // distinction matters: the run may yet succeed, and telling an author their
+    // automation failed when it is merely slow would send them to debug working
+    // code.
+    throw new CliError(
+      seen
+        ? `the run started but was still ${seen.status} after ${WAIT_TIMEOUT_MS / 1000}s`
+        : `no run appeared within ${WAIT_TIMEOUT_MS / 1000}s — the invoke was accepted, `
+          + 'so either no runner is polling or it has not picked the event up',
+      {
+        code: 'REQUEST_FAILED',
+        hint: `frontera automation runs ${slug}`,
+      },
+    )
+  },
+}
+
+/** Recent runs, newest first — the pull-visibility half of "did it work". */
+export const automationRuns: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'runs',
+    args: [{ name: 'slug', required: true, description: 'automation slug' }],
+    flags: {},
+    summary: 'List recent runs, newest first, with what each one returned',
+    examples: ['frontera automation runs daily-digest'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).runs(slug)
+
+    if (rows.length === 0) {
+      return {
+        data: rows,
+        text: `No runs recorded for ${slug}.\n`
+          + `  frontera automation run ${slug}   # to start one`,
+      }
+    }
+
+    return {
+      data: rows,
+      text: rows
+        .map((r) => {
+          // The MESSAGE, not a truncation of it: a budget refusal or a missing
+          // grant names its own remedy, and cutting it at 40 columns to fit a
+          // table is how the remedy gets lost. One block per run instead.
+          const head = `${r.startedAt}  ${r.status}  v${r.version}`
+            + `  ${r.triggerSource}  ${r.ctxCalls} ctx call(s)`
+          return [head, ...describeRun(r).split('\n').slice(1)].join('\n')
+        })
+        .join('\n'),
+    }
+  },
+}

package/src/commands/blueprint/authoring.ts

@@ -0,0 +1,410 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import { CliError } from '../../errors'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * Blueprint authoring from the CLI.
+ *
+ * These verbs were reserved in the command table until the organization-level shared
+ * draft had a credential that could reach it. It does now: an organization API key
+ * (`sk-org-`) satisfies an organization-scoped permission check, which a workspace key
+ * is refused by design because Blueprint's draft is shared across every workspace in
+ * the organization.
+ *
+ * Every mutation reads the current draft revision first and sends it back as
+ * `expectedRevision`. The draft is shared, so a blind write is a lost update; the
+ * service answers 409 when it has moved and the command says so rather than retrying
+ * over someone else's change.
+ */
+
+function api(ctx: CommandContext): BlueprintAuthoringApi {
+  return new BlueprintAuthoringApi(ctx.apiUrl, ctx.token)
+}
+
+/** Object sets are addressed by id; a person types the name they can see. */
+async function objectSetId(client: BlueprintAuthoringApi, name: string): Promise<string> {
+  const sets = await client.listObjectSets()
+  const matches = sets.filter((set) => set.name === name || set.id === name)
+  const only = matches.length === 1 ? matches[0] : undefined
+  if (only?.id) return only.id
+  if (matches.length > 1) {
+    throw new CliError(`"${name}" names ${matches.length} object sets.`, {
+      code: 'USAGE',
+      hint: `Use the id: ${matches.map((match) => match.id).join(', ')}`,
+    })
+  }
+  throw new CliError(`No object set named "${name}".`, {
+    code: 'NOT_FOUND',
+    hint: 'frontera blueprint catalog',
+  })
+}
+
+/** Read a JSON document from `--file`, or from the positional path. */
+function readDocument(ctx: CommandContext, positionalIndex = 0): Record<string, unknown> {
+  const path = (ctx.flags.file as string) ?? ctx.positional[positionalIndex]
+  if (!path) {
+    throw new CliError('A JSON document is required: pass --file <path>.', {
+      code: 'USAGE',
+      hint: 'frontera blueprint create object-type --file ./object-type.json',
+    })
+  }
+  const full = resolve(ctx.cwd, path)
+  let raw: string
+  try {
+    raw = readFileSync(full, 'utf8')
+  } catch {
+    throw new CliError(`Cannot read ${full}`, {
+      code: 'USAGE',
+      hint: 'Check the path, or pass --file with a path relative to the current directory.',
+    })
+  }
+  try {
+    return JSON.parse(raw) as Record<string, unknown>
+  } catch (err) {
+    throw new CliError(`${full} is not valid JSON: ${(err as Error).message}`, {
+      code: 'USAGE',
+      hint: 'Validate the document, e.g. `jq . < ' + full + '`.',
+    })
+  }
+}
+
+/**
+ * `object-set` is here rather than in the file tree on purpose: a static set names
+ * individual data rows and a set may carry a workspaceId, neither of which survives a
+ * move between deployments. It is curation, not Blueprint.
+ */
+const KINDS = ['object-type', 'link-type', 'metric', 'action', 'object-set'] as const
+type Kind = (typeof KINDS)[number]
+
+function readKind(ctx: CommandContext): Kind {
+  const kind = ctx.positional[0] as Kind
+  if (!KINDS.includes(kind)) {
+    throw new CliError(
+      `Unknown kind "${ctx.positional[0] ?? ''}". Expected one of: ${KINDS.join(', ')}.`,
+      { code: 'USAGE', hint: 'frontera blueprint create --help' },
+    )
+  }
+  return kind
+}
+
+export const blueprintAdopt: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'adopt',
+    args: [],
+    flags: {},
+    summary: 'Create this organization’s shared Blueprint draft',
+    examples: ['frontera blueprint adopt'],
+  },
+  async run(ctx) {
+    const result = await api(ctx).adopt()
+    return { data: result, text: 'Shared Blueprint draft adopted.' }
+  },
+}
+
+export const blueprintCreate: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'create',
+    args: [
+      { name: 'kind', required: true, description: `One of: ${KINDS.join(', ')}` },
+    ],
+    flags: { file: 'string' },
+    aliases: { f: 'file' },
+    summary: 'Create an object type, link type or metric on the shared draft',
+    examples: [
+      'frontera blueprint create object-type --file customer.json',
+      'frontera blueprint create metric --file revenue.json',
+    ],
+  },
+  async run(ctx) {
+    const kind = readKind(ctx)
+    const client = api(ctx)
+    const document = readDocument(ctx, 1)
+    const revision = await client.revision()
+
+    const created =
+      kind === 'object-type' ? await client.createObjectType(document, revision)
+      : kind === 'link-type' ? await client.createLinkType(document, revision)
+      : kind === 'action' ? await client.createAction(document, revision)
+      // Object sets are not draft artifacts, so they carry no expectedRevision.
+      : kind === 'object-set' ? await client.createObjectSet(document)
+      : await client.createMetric(document, revision)
+
+    return { data: created, text: `Created ${kind} "${document.apiName}" on draft revision ${revision}.` }
+  },
+}
+
+export const blueprintUpdate: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'update',
+    args: [
+      { name: 'kind', required: true, description: `One of: ${KINDS.join(', ')}` },
+      { name: 'apiName', required: true, description: 'The artifact’s API name' },
+    ],
+    flags: { file: 'string' },
+    aliases: { f: 'file' },
+    summary: 'Update an artifact on the shared draft',
+    examples: ['frontera blueprint update object-type Customer --file customer.json'],
+  },
+  async run(ctx) {
+    const kind = readKind(ctx)
+    const apiName = ctx.positional[1]
+    if (!apiName) {
+      throw new CliError('An apiName is required.', {
+        code: 'USAGE',
+        hint: 'frontera blueprint update object-type <apiName> --file ./patch.json',
+      })
+    }
+    const client = api(ctx)
+    const document = readDocument(ctx, 2)
+    const revision = await client.revision()
+
+    const updated =
+      kind === 'object-type' ? await client.updateObjectType(apiName, document, revision)
+      : kind === 'link-type' ? await client.updateLinkType(apiName, document, revision)
+      : kind === 'action' ? await client.updateAction(apiName, document, revision)
+      : kind === 'object-set' ? await client.updateObjectSet(await objectSetId(client, apiName), document)
+      : await client.updateMetric(apiName, document, revision)
+
+    return { data: updated, text: `Updated ${kind} "${apiName}" on draft revision ${revision}.` }
+  },
+}
+
+export const blueprintDelete: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'delete',
+    args: [
+      { name: 'kind', required: true, description: `One of: ${KINDS.join(', ')}` },
+      { name: 'apiName', required: true, description: 'The artifact’s API name' },
+    ],
+    flags: {},
+    summary: 'Remove an artifact from the shared draft',
+    examples: ['frontera blueprint delete metric revenuePerCustomer'],
+  },
+  async run(ctx) {
+    const kind = readKind(ctx)
+    const apiName = ctx.positional[1]
+    if (!apiName) {
+      throw new CliError('An apiName is required.', {
+        code: 'USAGE',
+        hint: 'frontera blueprint delete metric <apiName>',
+      })
+    }
+    const client = api(ctx)
+
+    if (kind === 'object-type') {
+      // Removing an object is structural: preview, then apply the exact preview. The
+      // service refuses an apply whose digest does not match what it showed.
+      const objectType = await client.getObjectType(apiName)
+      if (!objectType?.id) {
+        throw new CliError(`No object type "${apiName}" on the draft.`, {
+          code: 'NOT_FOUND',
+          hint: 'frontera blueprint list',
+        })
+      }
+      const result = await client.removeObject(objectType.id, await client.revision())
+      return { data: result, text: `Removed object type "${apiName}" (previewed, then applied).` }
+    }
+
+    if (kind === 'object-set') {
+      const removed = await client.deleteObjectSet(await objectSetId(client, apiName))
+      return { data: removed, text: `Removed object set "${apiName}".` }
+    }
+
+    const revision = await client.revision()
+    const removed = kind === 'link-type'
+      ? await client.deleteLinkType(apiName, revision)
+      : kind === 'action'
+        ? await client.deleteAction(apiName, revision)
+        : await client.deleteMetric(apiName, revision)
+    return { data: removed, text: `Removed ${kind} "${apiName}" on draft revision ${revision}.` }
+  },
+}
+
+export const blueprintValidate: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'validate',
+    args: [],
+    flags: {},
+    summary: 'Validate the shared draft and produce a report',
+    examples: ['frontera blueprint validate'],
+  },
+  async run(ctx) {
+    const report = await api(ctx).validate()
+    const id = report?.id ?? report?.reportId
+    return {
+      data: report,
+      // The id matters: `publish` takes it, which is what ties a release to the
+      // validation that cleared it rather than to whatever the draft holds later.
+      text: `Draft validated. Report ${id} — pass it to \`frontera blueprint publish\`.`,
+    }
+  },
+}
+
+export const blueprintPublish: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'publish',
+    args: [],
+    flags: { label: 'string', notes: 'string', report: 'string', instruction: 'string' },
+    summary: 'Publish the shared draft as a release',
+    examples: [
+      'frontera blueprint publish --label v3 --notes "Adds Customer"',
+      'frontera blueprint publish --label v4 --instruction "Backfilled"',
+    ],
+  },
+  async run(ctx) {
+    const client = api(ctx)
+    const label = (ctx.flags.label as string) ?? 'cli-release'
+    const notes = (ctx.flags.notes as string) ?? 'Published with the Frontera CLI.'
+
+    // Validate first when no report was given: publishing against a stale report
+    // would release something nobody checked.
+    let validationReportId = ctx.flags.report as string | undefined
+    if (!validationReportId) {
+      const report = await client.validate()
+      validationReportId = report?.id ?? report?.reportId
+    }
+    if (!validationReportId) {
+      throw new CliError('Validation produced no report id; cannot publish.', {
+        code: 'FAILURE',
+        hint: 'frontera blueprint validate',
+      })
+    }
+
+    const released = await client.publish({
+      expectedRevision: await client.revision(),
+      validationReportId,
+      releaseLabel: label,
+      releaseNotes: notes,
+      // A release that discards changes needs an instruction per discarded change.
+      instruction: ctx.flags.instruction as string | undefined,
+    })
+    return { data: released, text: `Published release "${label}".` }
+  },
+}
+
+export const blueprintRollback: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'rollback',
+    args: [
+      { name: 'releaseId', required: true, description: 'The release to roll back to' },
+    ],
+    flags: { label: 'string', notes: 'string', instruction: 'string' },
+    summary: 'Roll the organization back to an earlier release',
+    examples: ['frontera blueprint rollback <releaseId> --label revert'],
+  },
+  async run(ctx) {
+    const releaseId = ctx.positional[0]
+    if (!releaseId) {
+      throw new CliError('A releaseId is required.', {
+        code: 'USAGE',
+        hint: 'frontera blueprint status',
+      })
+    }
+    const result = await api(ctx).rollback(releaseId, {
+      releaseLabel: (ctx.flags.label as string) ?? 'cli-rollback',
+      releaseNotes: (ctx.flags.notes as string) ?? 'Rolled back with the Frontera CLI.',
+      instruction: ctx.flags.instruction as string | undefined,
+    })
+    return { data: result, text: `Rolled back to release ${releaseId}.` }
+  },
+}
+
+export const blueprintStatus: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'status',
+    args: [],
+    flags: {},
+    summary: 'Show the draft revision and the active release',
+    examples: ['frontera blueprint status'],
+  },
+  async run(ctx) {
+    const lifecycle = await api(ctx).lifecycleOrNull()
+    if (!lifecycle) {
+      // Not an error: every organization starts here.
+      return {
+        data: { adopted: false },
+        text: 'This organization has no Blueprint yet.\n  Run `frontera blueprint adopt` to create the shared draft.',
+      }
+    }
+    const revision = lifecycle?.draft?.revision
+    const active = lifecycle?.activeRelease
+    return {
+      data: lifecycle,
+      text: [
+        `Draft revision: ${revision ?? '(no draft)'}`,
+        active?.id
+          ? `Active release: ${active.releaseLabel ?? `#${active.releaseNumber ?? '?'}`} (${active.id})`
+          : 'Active release: (none)',
+      ].join('\n'),
+    }
+  },
+}
+
+export const blueprintCatalog: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'catalog',
+    args: [],
+    flags: {},
+    summary: 'List what is on the shared draft: object types, links and metrics',
+    examples: ['frontera blueprint catalog', 'frontera blueprint catalog --json'],
+  },
+  async run(ctx) {
+    // `blueprint list` reads the WORKSPACE's granted slice, which an organization key
+    // has no grant for — it authors the org's draft rather than reading one workspace's
+    // view of it. This is the equivalent read for that credential.
+    const client = api(ctx)
+    const [objectTypes, linkTypes, metrics] = await Promise.all([
+      client.listObjectTypes(),
+      client.listLinkTypes(),
+      client.listMetrics(),
+    ])
+
+    // Links and metrics reference object types by ID, not by API name. Rendering the
+    // raw field would print nothing useful, so resolve through the list already
+    // fetched rather than showing a blank column.
+    const nameById = new Map<string, string>()
+    for (const o of objectTypes) {
+      if (o.id && o.apiName) nameById.set(o.id, o.apiName)
+    }
+    const resolve = (id?: string) => (id ? (nameById.get(id) ?? id) : '?')
+
+    const lines = [
+      `Object types (${objectTypes.length})`,
+      ...objectTypes.map((o) => `  ${o.apiName ?? '?'}${o.displayName ? ` — ${o.displayName}` : ''}`),
+      '',
+      `Link types (${linkTypes.length})`,
+      ...linkTypes.map(
+        (l) => `  ${l.apiName ?? '?'} — ${resolve(l.fromObjectTypeId)} → ${resolve(l.toObjectTypeId)}`,
+      ),
+      '',
+      `Metrics (${metrics.length})`,
+      ...metrics.map((m) => `  ${m.apiName ?? '?'} — on ${resolve(m.objectTypeId)}`),
+    ]
+
+    return { data: { objectTypes, linkTypes, metrics }, text: lines.join('\n') }
+  },
+}
+
+export const blueprintAuthoringCommands: Command[] = [
+  blueprintCatalog,
+  blueprintAdopt,
+  blueprintStatus,
+  blueprintCreate,
+  blueprintUpdate,
+  blueprintDelete,
+  blueprintValidate,
+  blueprintPublish,
+  blueprintRollback,
+]