@frontera-sdk/cli 1.53.6 → 1.53.8

package/src/commands/action/retire.ts

@@ -1,21 +1,29 @@
-import { GovernedActionApi } from '../../api/governed-action-api'
+import { randomUUID } from 'node:crypto'
+
+import { GovernedActionApi, type ExternalWritePath } from '../../api/governed-action-api'
 import { CliError, UsageError } from '../../errors'
-import { flagString, type Command } from '../types'
+import { canPrompt, promptConfirm } from '../../prompt'
+import { flagBool, flagString, type Command } from '../types'
 
 /**
- * Retire an Action's deployment decision (Forge improvement plan X11).
+ * Retire an Action's deployment, so a changed Action can publish (Forge
+ * improvement plan X11).
  *
- * `action prepare` records that a drafted Action ships switched off, and the
- * decision pins the Action's contract as it was then: editing the drafted
- * Action after preparing it left it stranded, since publish refuses the
- * changed contract and a second prepare refuses a second decision. Retiring
- * the decision stands it down, so `action prepare` can record one for the
- * contract as it is now.
+ * A deployment pins the Action's contract as it was when it was decided:
+ * prepared, or deployed and turned on. Publish refuses a changed contract while
+ * a deployment still pins the old one, and a deployment cannot follow a new
+ * contract. Retiring stands it down, and the next `blueprint publish` records
+ * that the Action as it is now ships switched off.
  *
- * Only a decision that was never bound, or one already draining, retires:
- * the service refuses an active deployment, which is switched off first. It
- * arms nothing and removes nothing from the Blueprint. It takes a signed-in
- * person with `actionBinding: retire`.
+ * A running deployment is switched off first, as the service's `disable` does
+ * it: the running one drains and a disabled decision takes its place. Then
+ * every draining deployment of the Action and the decision are retired. A run
+ * cut short is finished by running it again. It takes a signed-in person with
+ * `actionBinding: activate` and `retire`, and removes nothing from the Blueprint.
+ * Switching off a running deployment is asked first, naming the Action and the
+ * host; `--yes` answers for a caller with no terminal. When the write path the
+ * Action last ran calls another system, it says that a second person reviews
+ * the one that replaces it, which retiring does not change.
  */
 export const actionRetire: Command = {
   meta: {
@@ -24,14 +32,17 @@ export const actionRetire: Command = {
     authLane: 'session',
     args: [{ name: 'action', required: true, description: 'The Action’s API name' }],
     flags: { reason: 'string' },
-    summary: 'Retire an Action’s deployment decision, so a changed draft can be prepared again',
+    summary: 'Switch off and retire an Action’s deployment, so a changed Action can publish',
     details: [
-      'For an Action prepared before its draft changed: retire, then `frontera action prepare <action>` records a decision for the contract as it is now.',
-      'An active deployment is refused: switch it off in Console first.',
+      'For an Action changed after it was prepared or deployed: retire, then `frontera blueprint publish` records a decision for the Action as it is now.',
+      'A running deployment is switched off first; the Action does not run again until `frontera action deploy <action>` turns it on.',
+      'It asks before switching off a running deployment, naming the Action and the host; --yes switches it off without asking.',
     ],
     examples: [
-      'frontera action retire escalateTicket --reason "draft changed"',
-      'frontera action prepare escalateTicket',
+      'frontera action retire escalateTicket --reason "the Action changed"',
+      'frontera action retire escalateTicket --reason "the Action changed" --yes',
+      'frontera blueprint publish',
+      'frontera action deploy escalateTicket',
     ],
   },
 
@@ -39,22 +50,63 @@ export const actionRetire: Command = {
     const apiName = ctx.positional[0]
     if (!apiName) throw new UsageError('missing <action>', 'frontera action retire escalateTicket --reason "…"')
     const reason = flagString(ctx, 'reason')?.trim()
-    if (!reason) throw new UsageError('say why with --reason', 'the reason is kept with the deployment’s history: frontera action retire escalateTicket --reason "the draft changed after it was prepared"')
+    if (!reason) throw new UsageError('say why with --reason', 'the reason is kept with the deployment’s history: frontera action retire escalateTicket --reason "the Action changed"')
 
     const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const definitionId = await client.actionDefinitionId(apiName)
     if (!definitionId) throw new CliError(`No Action "${apiName}" on the draft or in the release.`, { code: 'ACTION_NOT_FOUND', hint: 'frontera action list' })
     const current = await client.currentDeployment(definitionId)
-    if (!current) {
-      return { data: { action: apiName, retired: false }, text: `"${apiName}" carries no deployment decision: nothing to retire. \`frontera action prepare ${apiName}\` records one.` }
+    const running = current?.state === 'active'
+    const at = typeof ctx.flags.profile === 'string' ? ` --profile ${ctx.flags.profile}` : ''
+    if (running && !flagBool(ctx, 'yes')) {
+      const said = `"${apiName}" is running on ${new URL(ctx.apiUrl).host}; retiring it switches it off until it is deployed again`
+      const go = (ctx.interactive ?? canPrompt()) && ctx.flags['no-input'] !== true ? await promptConfirm(`${said}. Switch it off?`) : false
+      if (!go) {
+        throw new CliError(`${said}, so nothing was retired.`, {
+          code: 'USAGE',
+          hint: `to switch it off, add --yes: frontera action retire ${apiName} --reason ${JSON.stringify(reason)} --yes${at}`,
+        })
+      }
+    }
+    const decision = current?.state === 'active'
+      ? await client.disableDeployment(randomUUID(), {
+        bindingId: randomUUID(),
+        actionDefinitionId: definitionId,
+        actionContractDigest: current.actionContractDigest,
+        expectedCurrentStateId: current.stateId,
+        expectedCurrentGeneration: current.generation,
+        reason,
+      })
+      : current
+    const draining = await client.drainingDeployments(definitionId)
+    for (const deployment of draining) await client.retireDeployment(deployment.stateId, deployment.generation, reason)
+    const retired = decision ? await client.retireDeployment(decision.stateId, decision.generation, reason) : null
+
+    if (!current && draining.length === 0) {
+      return { data: { action: apiName, retired: false }, text: `"${apiName}" carries no deployment decision: nothing to retire. \`frontera blueprint publish\` records one.` }
     }
-    if (current.state === 'active') {
-      throw new CliError(`"${apiName}" is deployed and switched on; an active deployment isn't retired.`, { code: 'CONFLICT', hint: 'switch it off in Console (the Action’s deployment) first, then retire it' })
+    // Read after the writes landed, so a failure here is reported as a note, not as a failed retire.
+    let external: ExternalWritePath | null = null
+    let unread: string | null = null
+    try {
+      external = await client.externalWritePath(definitionId)
+    } catch (err) {
+      unread = err instanceof Error ? err.message : String(err)
     }
-    const retired = await client.retireDeployment(current.stateId, current.generation, reason)
+    const secondPerson = unread !== null
+      ? `Could not read whether the last write path "${apiName}" ran calls another system (${unread}). If it does, a second person reviews the one that replaces it; \`frontera action deploy ${apiName}${at}\` reads it again before it builds.\n\n`
+      : external
+        ? `The last write path "${apiName}" ran calls another system (${external.planKind ?? 'a kind the platform cannot read'}), which a second person reviewed, so a second person reviews the one that replaces it. `
+          + `\`frontera action deploy ${apiName}${at}\` builds it and prints the command they run.\n\n`
+        : ''
+    const what = running
+      ? `Switched off the running deployment of "${apiName}" and retired it. "${apiName}" does not run until it is deployed again.`
+      : current
+        ? `Retired the ${current.state} deployment decision of "${apiName}".`
+        : `Retired the deployment of "${apiName}" that was still draining.`
     return {
-      data: { action: apiName, retired: true, from: current.state, deployment: retired },
-      text: `Retired the ${current.state} deployment decision of "${apiName}".\n\nNext:\n  frontera action prepare ${apiName}`,
+      data: { action: apiName, retired: true, from: current?.state ?? 'draining', switchedOff: running, deployment: retired, externalWritePath: external, ...(unread !== null ? { externalWritePathError: unread } : {}) },
+      text: `${what}\n\n${secondPerson}Next:\n  frontera blueprint publish${at}${running ? `\n  frontera action deploy ${apiName}${at}` : ''}`,
     }
   },
 }

package/src/commands/action/review.ts

@@ -1,16 +1,18 @@
-import { GovernedActionApi } from '../../api/governed-action-api'
+import { GovernedActionApi, type ExternalWritePath } from '../../api/governed-action-api'
 import { CliError, UsageError } from '../../errors'
 import { flagString, type Command, type CommandContext } from '../types'
 
 /**
  * Approve a validated write path, and switch it on.
  *
- * Its own verb because it must run as a DIFFERENT principal: the service
- * refuses a reviewer who authored the Binding, the connector or the plan. An
- * organization key's principal is `orgkey:<org>:<key>`, so a second key is a
- * second reviewer — no second human required to arm a deployment in a
- * non-production organization, and a real one required wherever the roles are
- * held by people.
+ * Its own verb because only a person's session may review, and `action
+ * deploy` may have built the write path with an organization key. The person
+ * who built a write path that only edits Blueprint records may review it; one
+ * that calls another system needs a second person, and the service refuses
+ * its author. So does one that replaces a write path calling another system,
+ * and nobody's review turns that one on when an API key built it, so it asks
+ * before it reviews. `action deploy` run as a person does both and ends with
+ * the same two steps.
  *
  * Review and activate are one command because the bookkeeping between them is
  * not a decision: activation names the generation review left the revision's
@@ -35,15 +37,50 @@ const READ_REFUSED_HINT =
  * longer switch on. The message stays the service's; the hint says which step
  * refused and what did not happen.
  */
-async function requireReadableRevision(client: GovernedActionApi, bindingRevisionId: string): Promise<void> {
+async function requireReadableRevision(client: GovernedActionApi, bindingRevisionId: string) {
   try {
-    await client.getBindingRevision(bindingRevisionId)
+    return await client.getBindingRevision(bindingRevisionId)
   } catch (err) {
     if (!(err instanceof CliError) || err.code !== 'FORBIDDEN') throw err
     throw new CliError(err.message, { code: 'FORBIDDEN', hint: READ_REFUSED_HINT, cause: err })
   }
 }
 
+/** What the Action does on a write path that calls another system, said of `subject`. */
+export function externalWritePathSentence(subject: string, external: ExternalWritePath): string {
+  const where = external.state === 'active' ? 'runs on' : external.state === 'draining' ? 'is still finishing requests on' : 'last ran on'
+  return `${subject} ${where} a write path that calls another system (${external.planKind ?? 'a kind the platform cannot read'}), which a second person reviewed.`
+}
+
+/**
+ * Asked before a review that activation follows. While the Action runs,
+ * drains or last ran a write path that calls another system, activation turns
+ * a new one on only for a reviewer who built none of it, and never one an API
+ * key built, so a review it would refuse is not recorded.
+ */
+async function requireReviewTurnsItOn(
+  client: GovernedActionApi,
+  revision: { id: string; actionDefinitionId: string },
+  validationReportId: string,
+): Promise<void> {
+  const external = await client.externalWritePath(revision.actionDefinitionId, revision.id)
+  if (!external?.reviewRefusal) return
+  const keyBuilt = external.reviewRefusal === 'key_built'
+  throw new CliError(
+    `${externalWritePathSentence('The Action', external)} `
+    + (keyBuilt
+      ? 'This one was built with an API key, so no review turns it on in its place, and nothing was reviewed.'
+      : 'You built this one, so a second person reviews it, and nothing was reviewed.'),
+    {
+      code: 'CONFLICT',
+      hint: keyBuilt
+        ? 'a person signed in as themselves runs `frontera action deploy` for this Action, which builds a new one as them, and a second person reviews it with the command it prints'
+        : `a second person who may review Actions turns it on with: frontera action review ${revision.id} --report ${validationReportId}`,
+      details: { reviewRefusal: external.reviewRefusal, replacedPlanKind: external.planKind, replacedState: external.state },
+    },
+  )
+}
+
 /** The review has landed and the states activation names could not be read. */
 function notReadable(cause?: unknown): CliError {
   return new CliError('Reviewed, but the deployment state for this revision is not readable.', {
@@ -83,6 +120,43 @@ async function readActivation(client: GovernedActionApi, bindingRevisionId: stri
   }
 }
 
+/**
+ * Review the revision at the exact validation it read. When it will be
+ * activated next, a reviewer who may not read it, or whose review activation
+ * would refuse, is refused first, with nothing reviewed.
+ */
+export async function reviewRevision(client: GovernedActionApi, input: {
+  bindingRevisionId: string
+  validationReportId: string
+  activating: boolean
+}): Promise<void> {
+  if (input.activating) {
+    const revision = await requireReadableRevision(client, input.bindingRevisionId)
+    await requireReviewTurnsItOn(client, revision, input.validationReportId)
+  }
+  // The generation is the service's, not ours: validation left the state at 2.
+  await client.reviewBindingRevision(input.bindingRevisionId, {
+    validationReportId: input.validationReportId,
+    expectedStateGeneration: 2,
+  })
+}
+
+/** Switch a reviewed revision on over whatever its Action is on now. */
+export async function activateReviewed(
+  client: GovernedActionApi,
+  bindingRevisionId: string,
+  reason = 'Activated from the CLI after review.',
+): Promise<{ stateId: string }> {
+  const { target, current } = await readActivation(client, bindingRevisionId)
+  await client.activateDeployment(target.stateId, {
+    expectedGeneration: target.generation,
+    expectedCurrentStateId: current?.stateId ?? null,
+    expectedCurrentGeneration: current?.generation ?? null,
+    reason,
+  })
+  return { stateId: target.stateId }
+}
+
 export const actionReview: Command = {
   meta: {
     noun: 'action',
@@ -113,13 +187,7 @@ export const actionReview: Command = {
     const client = api(ctx)
     const activate = ctx.flags['no-activate'] !== true
 
-    if (activate) await requireReadableRevision(client, bindingRevisionId)
-
-    // The generation is the service's, not ours: validation left the state at 2.
-    await client.reviewBindingRevision(bindingRevisionId, {
-      validationReportId,
-      expectedStateGeneration: 2,
-    })
+    await reviewRevision(client, { bindingRevisionId, validationReportId, activating: activate })
 
     if (!activate) {
       return {
@@ -128,17 +196,10 @@ export const actionReview: Command = {
       }
     }
 
-    const { target, current } = await readActivation(client, bindingRevisionId)
-
-    await client.activateDeployment(target.stateId, {
-      expectedGeneration: target.generation,
-      expectedCurrentStateId: current?.stateId ?? null,
-      expectedCurrentGeneration: current?.generation ?? null,
-      reason: flagString(ctx, 'reason') ?? 'Activated from the CLI after review.',
-    })
+    const { stateId } = await activateReviewed(client, bindingRevisionId, flagString(ctx, 'reason'))
 
     return {
-      data: { bindingRevisionId, stateId: target.stateId, reviewed: true, activated: true },
+      data: { bindingRevisionId, stateId, reviewed: true, activated: true },
       text: 'Reviewed and activated. The Action can now be invoked.',
     }
   },

package/src/commands/blueprint/authoring.ts

@@ -2,6 +2,16 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import { GovernedActionApi } from '../../api/governed-action-api'
+import {
+  blockerLines,
+  groupedChanges,
+  migrationInstructions,
+  newActionSteps,
+  changedActionSteps,
+  publishPlan,
+} from '../../blueprint/publish-plan'
+import { signInStep } from '../../device-login'
 import { CliError } from '../../errors'
 import type { Command, CommandContext } from '../types'
 
@@ -301,7 +311,7 @@ type ValidationReport = Awaited<ReturnType<BlueprintAuthoringApi['validate']>>
  * release to the validation that cleared it rather than to whatever the draft
  * holds later.
  */
-export function renderValidationReport(report: ValidationReport): string {
+export function renderValidationReport(report: Partial<ValidationReport>): string {
   const id = report?.id ?? report?.reportId
   const objectTypes = report?.catalogProjection?.objectTypes?.length ?? 0
   const linkTypes = report?.catalogProjection?.linkTypes?.length ?? 0
@@ -327,7 +337,16 @@ export const blueprintPublish: Command = {
     verb: 'publish',
     args: [],
     flags: { label: 'string', notes: 'string', report: 'string', instruction: 'string' },
+    flagHelp: {
+      instruction: 'how existing data and environments take the changes that need a migration instruction; sent with each of them (a new Action’s own is written for you)',
+      report: 'the draft’s latest validation report to publish against; without it, publish validates the draft first',
+    },
     summary: 'Publish the shared draft as a release',
+    details: [
+      'Validates the draft first and posts nothing that would be refused: each blocker is listed with the command that clears it.',
+      'A new governed Action with no deployment decision is recorded as shipping switched off, as `frontera action prepare` does.',
+      'A change that needs a migration instruction (other than a new Action\'s) is listed by kind and name; --instruction explains every one of them.',
+    ],
     examples: [
       'frontera blueprint publish --label v3 --notes "Adds Customer"',
       'frontera blueprint publish --label v4 --instruction "Backfilled"',
@@ -337,39 +356,106 @@ export const blueprintPublish: Command = {
     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
+    const instruction = (ctx.flags.instruction as string | undefined)?.trim() || undefined
+    const profile = typeof ctx.flags.profile === 'string' ? ctx.flags.profile : undefined
+
+    // `--report` is the validation the person read; without it, the draft is validated now.
+    let report: ValidationReport
+    const reportId = ctx.flags.report as string | undefined
+    if (reportId) {
+      const latest = (await client.lifecycle() as { latestValidation?: ValidationReport | null }).latestValidation
+      if (latest?.id !== reportId) {
+        throw new CliError(`Report ${reportId} is not the draft's latest validation, so a release from it would not be what was checked.`, {
+          code: 'VALIDATION_STALE',
+          hint: 'drop --report (publish validates the draft itself), or run `frontera blueprint validate` and pass its report',
+        })
+      }
+      report = latest
+    } else {
+      report = await client.validate()
+    }
+    const signIn = await signInStep({ profile: ctx.profile, apiUrl: ctx.apiUrl })
+    let plan = publishPlan(report, signIn, profile)
+
+    // What `action prepare` records, for each Action that has no decision yet.
+    const prepared: string[] = []
+    if (plan.autoFixable.length) {
+      const actions = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+      for (const name of plan.autoFixable) {
+        await actions.recordDeploymentDecision(name, `Published with the Frontera CLI ("${label}"): ships switched off until a person deploys it and turns it on.`)
+        prepared.push(name)
+      }
+      plan = publishPlan(await client.validate(), signIn, profile)
+    }
+    const preparedLines = prepared.map((name) => `Recorded that Action ${name} ships switched off: a person deploys it and turns it on after publish.`)
+
+    if (plan.blockers.length) {
+      throw new CliError([
+        ...preparedLines,
+        `The draft can't be published yet, so nothing was published. ${plan.blockers.length} blocker${plan.blockers.length === 1 ? '' : 's'}:`,
+        ...blockerLines(plan.blockers),
+      ].join('\n'), {
+        code: 'RELEASE_BLOCKED',
+        hint: 'clear each blocker above, then publish again',
+        details: { prepared, plan },
+      })
     }
-    if (!validationReportId) {
-      throw new CliError('Validation produced no report id; cannot publish.', {
-        code: 'FAILURE',
-        hint: 'frontera blueprint validate',
+
+    if (plan.instructionsNeeded.length && !instruction) {
+      const quote = (value: string) => (/^[\w.:-]+$/.test(value) ? value : JSON.stringify(value))
+      const rerun = ['frontera blueprint publish', `--label ${quote(label)}`, ...(ctx.flags.notes ? [`--notes ${quote(notes)}`] : []), '--instruction "<how existing data and environments take these changes>"', ...(profile ? [`--profile ${profile}`] : [])].join(' ')
+      const count = plan.instructionsNeeded.length
+      throw new CliError([
+        ...preparedLines,
+        `${count} change${count === 1 ? '' : 's'} in this release need${count === 1 ? 's' : ''} a migration instruction, so nothing was published:`,
+        ...groupedChanges(plan.instructionsNeeded).map((line) => `  ${line}`),
+      ].join('\n'), {
+        code: 'MIGRATION_INSTRUCTION_REQUIRED',
+        hint: `say how existing data and environments take these changes; the instruction is kept with each change in the release:\n    ${rerun}`,
+        details: { prepared, plan },
       })
     }
 
+    // Refused by the service, and kept as a failed attempt, if posted.
+    if (plan.unchanged) {
+      return { data: { release: null, prepared, newActions: [] }, text: [...preparedLines, 'The draft has no unpublished changes, so nothing was published.'].join('\n') }
+    }
+
     const released = await client.publish({
-      expectedRevision: await client.revision(),
-      validationReportId,
+      expectedRevision: plan.draftRevision,
+      validationReportId: plan.reportId,
       releaseLabel: label,
       releaseNotes: notes,
-      // A release that discards changes needs an instruction per discarded change.
-      instruction: ctx.flags.instruction as string | undefined,
+      migrationInstructions: migrationInstructions(plan, instruction),
     })
     const lifecycle = released as { activeRelease?: { releaseLabel?: string }; alreadyPublished?: boolean } | null
-    if (!lifecycle?.alreadyPublished) {
-      return { data: released, text: `Published release "${label}".` }
+    if (lifecycle?.alreadyPublished) {
+      // A retry of a publish that already went through is answered with the release
+      // that is live, which carries the label it was published with, not this run's.
+      // One made after newer Draft edits is refused by the service as stale.
+      const activeReleaseLabel = lifecycle.activeRelease?.releaseLabel ?? label
+      return { data: { release: released, prepared, newActions: [] }, text: `Release "${activeReleaseLabel}" is already active; nothing was published.` }
+    }
+    const newActions = plan.newActions.map((action) => ({ ...action, nextSteps: newActionSteps(action, signIn, profile) }))
+    const changedActions = plan.changedSwitchedOff.map((action) => ({ apiName: action.apiName, nextSteps: changedActionSteps(action, signIn, profile) }))
+    const numbered = (steps: Array<{ step: string; command?: string }>) => steps.flatMap((step, index) => (step.command ? [`  ${index + 1}. ${step.step}:`, `       ${step.command}`] : [`  ${index + 1}. ${step.step}.`]))
+    return {
+      data: { release: released, prepared, newActions, changedActions },
+      text: [
+        ...preparedLines,
+        `Published release "${label}".`,
+        ...newActions.flatMap((action) => [
+          '',
+          `New Action ${action.apiName} is published switched off, with no write path. To turn it on:`,
+          ...numbered(action.nextSteps),
+        ]),
+        ...changedActions.flatMap((action) => [
+          '',
+          `Action ${action.apiName} changed and is published switched off; its old write path does not run the new version. To turn it on again:`,
+          ...numbered(action.nextSteps),
+        ]),
+      ].join('\n'),
     }
-    // A retry of a publish that already went through is answered with the release
-    // that is live, which carries the label it was published with, not this run's.
-    // One made after newer Draft edits is refused by the service as stale.
-    const activeReleaseLabel = lifecycle.activeRelease?.releaseLabel ?? label
-    const nothingPublished = `Release "${activeReleaseLabel}" is already active; nothing was published.`
-    return { data: released, text: nothingPublished }
   },
 }
 

package/src/commands/blueprint/bind.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
-import { pickCurrentRevision } from '../../blueprint/dataset-revision'
+import { columnMappingsFrom, datasetBindingCommand, pickCurrentRevision, type MappingEntry } from '../../blueprint/dataset-revision'
 import { readTree, writeTree } from '../../blueprint/tree'
 import { CliError } from '../../errors'
 import type { Command, CommandContext } from '../types'
@@ -31,7 +31,7 @@ function api(ctx: CommandContext): BlueprintAuthoringApi {
 
 interface MappingFile {
   dataset: string
-  mapping: Record<string, string | { column: string; field?: string | null } | null>
+  mapping: Record<string, MappingEntry | null>
 }
 
 async function datasetRevision(client: BlueprintAuthoringApi, name: string) {
@@ -58,7 +58,7 @@ async function datasetRevision(client: BlueprintAuthoringApi, name: string) {
       hint: 'Publish a revision of the dataset, then bind.',
     })
   }
-  return current
+  return { ...current, id: current.id }
 }
 
 /**
@@ -150,36 +150,7 @@ export const blueprintBind: Command = {
       })
     }
     const mapping = JSON.parse(readFileSync(resolve(ctx.cwd, filePath), 'utf8')) as MappingFile
-    const idByApiName = new Map(properties.map((property) => [property.apiName, property.id]))
-
-    const columnMappings: Array<{ propertyId: string; column: string; field?: string | null }> = []
-    const missing: string[] = []
-    for (const property of properties) {
-      const name = property.apiName
-      // A calculated field (a location from latitude and longitude) reads no column.
-      if (!name || (property as { calculation?: unknown }).calculation) continue
-      const entry = mapping.mapping?.[name]
-      if (entry === undefined || entry === null) {
-        missing.push(name)
-        continue
-      }
-      const resolved = typeof entry === 'string' ? { column: entry } : entry
-      const propertyId = idByApiName.get(name)
-      if (!propertyId) {
-        // `!` sent `propertyId: undefined` and let the service answer for it. The
-        // property came from the same read as the mapping, so this means the draft
-        // moved mid-command.
-        throw new CliError(`Property "${name}" is no longer on "${apiName}".`, {
-          code: 'CONFLICT',
-          hint: 'Re-run `frontera blueprint bind … --plan` against the current draft.',
-        })
-      }
-      columnMappings.push({
-        propertyId,
-        column: resolved.column,
-        ...(resolved.field === undefined || resolved.field === null ? {} : { field: resolved.field }),
-      })
-    }
+    const { columnMappings, unmapped: missing } = columnMappingsFrom(properties, mapping.mapping ?? {})
     if (missing.length > 0) {
       // Refused here rather than at the service: the same refusal, one round trip
       // earlier, and it can name every unmapped property at once instead of the
@@ -193,20 +164,13 @@ export const blueprintBind: Command = {
       )
     }
 
-    const result = await client.draftCommand({
-      kind: 'update_source_binding',
-      objectId: detail.id,
-      binding: {
-        kind: 'dataset',
-        datasetRevisionId: revision.id,
-        columnMappings,
-        ...(ctx.flags['accept-contract-change'] === true ? { acceptContractChange: true } : {}),
-      },
-    }, await client.revision())
+    const result = await client.draftCommand(
+      datasetBindingCommand(detail.id, revision.id, columnMappings, ctx.flags['accept-contract-change'] === true),
+      await client.revision(),
+    )
 
-    // The tree is told what the draft now says. `backing` is excluded from the diff
-    // — a rebind is this command's act, not `apply`'s — so nothing else would ever
-    // reconcile the file, and it would sit stale until the next `pull`.
+    // The tree is told what the draft now says, or the next `apply` would read the
+    // file's old Dataset as a rebind back to it.
     const treeRoot = resolve(ctx.cwd, (ctx.flags.dir as string) ?? 'blueprint')
     let treeUpdated = false
     if (existsSync(join(treeRoot, 'object-types'))) {