@frontera-sdk/cli 1.53.6 → 1.53.8

package/src/blueprint/publish-plan.ts

@@ -0,0 +1,253 @@
+/**
+ * What a publish needs before anything is posted, read from one validation report.
+ *
+ * The service records every refused publish as a failed attempt, kept and shown in
+ * Blueprint > Changes. So `blueprint publish` reads the report `validate` answers,
+ * which already carries the blockers and the change ids, and posts only a publish
+ * that can pass: one with no blockers, and an instruction for every change that
+ * needs one.
+ */
+
+/** A change between the active release and the draft (`evolution.changes[]`). */
+export interface EvolutionChange {
+  id: string
+  code: string
+  classification: string
+  subject: { kind: string; id: string; label: string }
+  message: string
+  /** The value the draft holds at the change's path; a new Action's whole definition. */
+  after?: unknown
+}
+
+/** `POST /v1/blueprint/lifecycle/validate`, the parts a publish reads. */
+export interface ValidationReport {
+  id: string
+  draftRevision: number
+  status: string
+  blockers?: Array<{ code: string; message: string; path?: string; changeId?: string }>
+  evolution?: { changes?: EvolutionChange[] }
+  bindingReadiness?: { actions?: Array<{ actionDefinitionId: string; actionApiName: string; reason: string }> }
+}
+
+export interface PublishBlocker {
+  code: string
+  /** The Action or object it is about, by name; absent when the report names none. */
+  subject?: string
+  message: string
+  /** What to do about it, and the commands that do it, in order. */
+  next?: { why: string; commands: string[] }
+}
+
+export interface NewAction {
+  apiName: string
+  /** The `action_added_environment_validation` change the publish answers for it. */
+  changeId: string
+  invokeCapability?: string
+  /** Its effect only edits Blueprint records (create, update, delete); absent when the report does not say. */
+  editsBlueprint?: boolean
+}
+
+/** A published Action this release changes and carries switched off. */
+export interface ChangedAction {
+  apiName: string
+  /** As on `NewAction`: known when the release changes the Action's effect kind. */
+  editsBlueprint?: boolean
+}
+
+export interface PublishPlan {
+  reportId: string
+  draftRevision: number
+  blockers: PublishBlocker[]
+  /** Actions with no deployment decision: the publish records that each ships switched off. */
+  autoFixable: string[]
+  /** Non-additive changes a person explains with `--instruction`. */
+  instructionsNeeded: EvolutionChange[]
+  newActions: NewAction[]
+  /** Published Actions this release changes and carries switched off: each runs again only after a new write path. */
+  changedSwitchedOff: ChangedAction[]
+  /** The report lists no changes at all: the draft is the active release. */
+  unchanged: boolean
+}
+
+/** A new Action's own environment change, which its ships-switched-off decision answers. */
+const NEW_ACTION_ENVIRONMENT_CHANGE = 'action_added_environment_validation'
+
+/** The effect kinds whose write path `action deploy` builds (`ontology_edit`), which its author may review. */
+const BLUEPRINT_EDIT_EFFECTS = new Set(['create', 'update', 'delete'])
+
+/** Whether each Action's effect only edits Blueprint records, by Action id, where a change says: a new Action's definition, or a changed effect kind. */
+function editsBlueprintById(changes: EvolutionChange[]): Map<string, boolean> {
+  const edits = new Map<string, boolean>()
+  for (const change of changes) {
+    if (change.subject.kind !== 'action') continue
+    const kind = change.code === 'action_effect_kind_changed'
+      ? change.after
+      : (change.after as { effect?: { kind?: unknown } } | undefined)?.effect?.kind
+    if (typeof kind === 'string') edits.set(change.subject.id, BLUEPRINT_EDIT_EFFECTS.has(kind))
+  }
+  return edits
+}
+
+/** The words the change-request Apply records for the same change. */
+function newActionInstruction(apiName: string): string {
+  return `New Action ${apiName}: it ships switched off with no write path. A person deploys it, binds it for this environment and turns it on after publish.`
+}
+
+/** A printed command aimed at the profile the publish ran with, so it acts where the publish did. */
+const aimed = (command: string, profile: string | undefined) => (profile ? `${command} --profile ${profile}` : command)
+
+/** What clears a changed Action's old deployment, the running one included (`action retire`); `signIn` is `signInStep`'s answer. */
+const retireTheOldDeployment = (name: string, signIn: string | null) => ({
+  why: 'The Action changed after its deployment was decided, and a deployment cannot follow a new contract. A signed-in person retires the old one, switching it off if it runs; the next publish records a decision for the Action as it is now and prints the deploy step that turns it on.',
+  commands: [
+    ...(signIn ? [signIn] : []),
+    `frontera action retire ${name} --reason "the Action changed" --yes`,
+    'frontera blueprint publish',
+  ],
+})
+
+/** Blocker code to the step that clears it. A code not listed gets the service's message alone. */
+const NEXT_STEPS: Record<string, (name: string, signIn: string | null) => { why: string; commands: string[] }> = {
+  ACTION_UNBOUND: (name) => ({
+    why: 'Record that it ships switched off. That takes a key allowed to create Action deployments.',
+    commands: [`frontera action prepare ${name}`],
+  }),
+  ACTION_BINDING_DIGEST_MISMATCH: retireTheOldDeployment,
+  ACTION_BINDING_CONSUMER_INVALID: retireTheOldDeployment,
+  ACTION_BINDING_SUSPENDED: () => ({ why: 'Its deployment is suspended.', commands: ['frontera action list'] }),
+  ACTION_BINDING_REVOKED: () => ({ why: 'Its deployment is revoked.', commands: ['frontera action list'] }),
+  ACTION_BINDING_VALIDATION_STALE: () => ({ why: 'Its deployment needs a fresh validation.', commands: ['frontera action list'] }),
+  ACTION_BINDING_STATE_CONTRADICTORY: () => ({ why: 'Its deployment state does not add up.', commands: ['frontera action list'] }),
+}
+
+export function publishPlan(report: ValidationReport, signIn: string | null, profile?: string): PublishPlan {
+  const changes = report.evolution?.changes ?? []
+  const actions = report.bindingReadiness?.actions ?? []
+  // Ids to names: a blocker names its subject only by an id in its path.
+  const names = new Map<string, string>([
+    ...changes.map((change) => [change.subject.id, change.subject.label] as const),
+    ...actions.map((action) => [action.actionDefinitionId, action.actionApiName] as const),
+  ])
+  const blockers = (report.blockers ?? []).map((blocker): PublishBlocker => {
+    const subject = (blocker.path ?? '').split('.').map((segment) => names.get(segment)).find(Boolean)
+    const next = NEXT_STEPS[blocker.code]?.(subject ?? '<action>', signIn)
+    return {
+      code: blocker.code,
+      ...(subject ? { subject } : {}),
+      message: blocker.message,
+      ...(next ? { next: { ...next, commands: next.commands.map((command) => aimed(command, profile)) } } : {}),
+    }
+  })
+  const newActionIds = new Set(changes.filter((change) => change.code === NEW_ACTION_ENVIRONMENT_CHANGE).map((change) => change.subject.id))
+  const changedActionIds = new Set(changes.filter((change) => change.subject.kind === 'action').map((change) => change.subject.id))
+  const editsBlueprint = editsBlueprintById(changes)
+  return {
+    reportId: report.id,
+    draftRevision: report.draftRevision,
+    blockers,
+    autoFixable: actions.filter((action) => action.reason === 'ACTION_UNBOUND').map((action) => action.actionApiName),
+    instructionsNeeded: changes.filter((change) => change.classification !== 'additive' && change.code !== NEW_ACTION_ENVIRONMENT_CHANGE),
+    newActions: changes.filter((change) => change.code === NEW_ACTION_ENVIRONMENT_CHANGE).map((change) => {
+      const capability = (change.after as { governance?: { invokeCapability?: unknown } } | undefined)?.governance?.invokeCapability
+      const edits = editsBlueprint.get(change.subject.id)
+      return {
+        apiName: change.subject.label,
+        changeId: change.id,
+        ...(typeof capability === 'string' ? { invokeCapability: capability } : {}),
+        ...(edits === undefined ? {} : { editsBlueprint: edits }),
+      }
+    }),
+    changedSwitchedOff: actions
+      .filter((action) => action.reason === 'ACTION_DISABLED' && changedActionIds.has(action.actionDefinitionId) && !newActionIds.has(action.actionDefinitionId))
+      .map((action) => {
+        const edits = editsBlueprint.get(action.actionDefinitionId)
+        return { apiName: action.actionApiName, ...(edits === undefined ? {} : { editsBlueprint: edits }) }
+      }),
+    // Only a report that carries the list: one without it says nothing either way.
+    unchanged: Array.isArray(report.evolution?.changes) && changes.length === 0,
+  }
+}
+
+/** One instruction per change the publish must explain: the person's text, and a new Action's own. */
+export function migrationInstructions(plan: PublishPlan, instruction: string | undefined): Array<{ changeId: string; instruction: string }> {
+  return [
+    ...plan.newActions.map((action) => ({ changeId: action.changeId, instruction: newActionInstruction(action.apiName) })),
+    ...(instruction ? plan.instructionsNeeded.map((change) => ({ changeId: change.id, instruction })) : []),
+  ]
+}
+
+const KIND_WORDS: Record<string, [string, string]> = {
+  object: ['object type', 'object types'],
+  action: ['Action', 'Actions'],
+  relationship: ['link type', 'link types'],
+  metric: ['metric', 'metrics'],
+  shared_property: ['shared field', 'shared fields'],
+  semantic_type: ['semantic type', 'semantic types'],
+  source_system: ['source system', 'source systems'],
+}
+
+/** `source_mapping_changed on 3 object types: Customer, Order, Ticket`, one line per code and kind. */
+export function groupedChanges(changes: EvolutionChange[]): string[] {
+  const groups = new Map<string, EvolutionChange[]>()
+  for (const change of changes) {
+    const key = `${change.code}\u0000${change.subject.kind}`
+    groups.set(key, [...(groups.get(key) ?? []), change])
+  }
+  return [...groups.values()].map((group) => {
+    const labels = [...new Set(group.map((change) => change.subject.label))]
+    const [one, many] = KIND_WORDS[group[0]!.subject.kind] ?? [group[0]!.subject.kind, group[0]!.subject.kind]
+    const messages = new Set(group.map((change) => change.message))
+    return `${group[0]!.code} on ${labels.length} ${labels.length === 1 ? one : many}: ${labels.join(', ')}`
+      + (messages.size === 1 ? ` (${group[0]!.message.replace(/\.$/, '')})` : '')
+  })
+}
+
+/** `✕ escalateTicket: <message>`, then the step that clears it, indented under it; a step two blockers share is said once. */
+export function blockerLines(blockers: PublishBlocker[]): string[] {
+  const said = new Set<string>()
+  return blockers.flatMap((blocker) => {
+    const key = JSON.stringify([blocker.subject, blocker.next])
+    const next = blocker.next && !said.has(key) ? blocker.next : undefined
+    said.add(key)
+    return [
+      `  ✕ ${blocker.subject ? `${blocker.subject}: ` : ''}${blocker.message}`,
+      ...(next ? [`    ${next.why}`, ...next.commands.map((command) => `      ${command}`)] : []),
+    ]
+  })
+}
+
+/**
+ * The step that gives an Action a write path, worded for who reviews it: its
+ * author may for one that only edits Blueprint records, which `action deploy`
+ * builds; one that calls another system is built for that system, outside the
+ * CLI, and a second person reviews it.
+ */
+function deployStep(apiName: string, editsBlueprint: boolean | undefined, what: string): { step: string; command?: string } {
+  if (editsBlueprint === false) {
+    return { step: `It calls another system, so \`frontera action deploy\` does not build ${what}: one is built for that system, and a second person reviews it and turns it on` }
+  }
+  const who = editsBlueprint ? 'it only edits Blueprint records, so you may review your own' : 'you may review your own when it only edits Blueprint records; one that calls another system needs a second person'
+  return { step: `Build, review and turn on ${what}; ${who}`, command: `frontera action deploy ${apiName}` }
+}
+
+const aimedSteps = (steps: Array<{ step: string; command?: string }>, profile: string | undefined) =>
+  steps.map((step) => (step.command ? { ...step, command: aimed(step.command, profile) } : step))
+
+/** What turns a changed Action on again: a fresh write path for the contract it has now. */
+export function changedActionSteps(action: ChangedAction, signIn: string | null, profile?: string): Array<{ step: string; command?: string }> {
+  return aimedSteps([
+    ...(signIn ? [{ step: 'Sign in as yourself, if you have not', command: signIn }] : []),
+    deployStep(action.apiName, action.editsBlueprint, 'a write path for what it is now'),
+  ], profile)
+}
+
+/** What turns a new Action on, in order, with who runs each step. */
+export function newActionSteps(action: NewAction, signIn: string | null, profile?: string): Array<{ step: string; command?: string }> {
+  return aimedSteps([
+    ...(signIn ? [{ step: 'Sign in as yourself, if you have not', command: signIn }] : []),
+    deployStep(action.apiName, action.editsBlueprint, 'its write path'),
+    ...(action.invokeCapability
+      ? [{ step: 'Let a role run it', command: `frontera action grant ${action.invokeCapability} --role <role>` }]
+      : []),
+  ], profile)
+}

package/src/blueprint/render.ts

@@ -39,6 +39,25 @@ export function renderPlan(plan: Plan, options: { prune: boolean } = { prune: fa
       detail: options.prune ? 'delete' : 'delete — needs --prune, skipped',
     })
   }
+  for (const change of plan.editable) {
+    const dropped = change.from.filter((name) => !change.to.includes(name))
+    rows.push({
+      marker: MARKER.update,
+      kind: 'object-type',
+      apiName: change.objectApiName,
+      // Narrowing is named, because an edit already stored against a dropped
+      // property stops being read: the one consequence the new set cannot show.
+      detail: `editable: ${change.to.length ? change.to.join(', ') : '(none)'}`
+        + (dropped.length ? ` — no longer editable: ${dropped.join(', ')}` : ''),
+    })
+  }
+
+  for (const change of plan.rebind) {
+    const move = `dataset: ${change.from ?? '(none)'} → ${change.to}`
+    rows.push('refused' in change
+      ? { marker: '✕', kind: 'object-type', apiName: change.objectApiName, detail: `${move} — cannot apply: ${change.refused}. Next: ${change.next}` }
+      : { marker: MARKER.update, kind: 'object-type', apiName: change.objectApiName, detail: move })
+  }
 
   const withheld = withheldNote(plan)
 

package/src/commands/action/deploy.ts

@@ -1,23 +1,45 @@
 import { randomUUID } from 'node:crypto'
 
 import { GovernedActionApi } from '../../api/governed-action-api'
+import { credentialStore } from '../../credential-store'
+import { readDeviceSession } from '../../device-login'
 import { CliError, UsageError } from '../../errors'
 import { deriveOntologyEditPlan, PlanDerivationError } from '../../blueprint/ontology-edit-plan'
 import { validationFindings } from '../../local/local-actions'
+import { selectedOrganization, setSelectedOrganization } from '../../organization'
+import { canPrompt, promptConfirm } from '../../prompt'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
+import { activateReviewed, externalWritePathSentence, reviewRevision } from './review'
 
 /**
  * Arm the write path for one published Action.
  *
- * Stops at VALIDATED, deliberately. Review must be performed by someone who
- * authored none of the material — the service refuses a reviewer who did — so
- * a single command that also reviewed would either be refused or would be
- * pretending the separation happened. `action review` is the second half, run
- * with a second credential.
+ * It builds and validates the write path with the command's credential, which
+ * an organization key may be. Turning it on takes a person: the review and the
+ * activation run as the person's token, or the browser sign-in stored for the
+ * profile, and only after a go (a yes at the terminal to a question naming the
+ * Action and the host, or `--yes`). Without one it stops at VALIDATED and
+ * prints the command that turns it on. The plan it builds only edits Blueprint
+ * records (`ontology_edit`), which the person who built it may review; the
+ * service keeps the second-person review for a plan that calls another system,
+ * and its refusal stops here, naming the review command a second person runs.
+ * While the Action runs, drains or last ran a write path that calls another
+ * system, which a second person reviewed, it stops once the new one is
+ * validated and names the review a second person runs; the service refuses to
+ * turn the new one on otherwise, even after the old one is retired. There it
+ * builds as the person, since the service turns on no write path an API key
+ * built in that one's place.
  */
 
-function api(ctx: CommandContext): GovernedActionApi {
-  return new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+function api(ctx: CommandContext, token = ctx.token): GovernedActionApi {
+  return new GovernedActionApi(ctx.apiUrl, token, ctx.workspaceId)
+}
+
+/** Who turns the write path on: the command's own person token, else the profile's browser sign-in. */
+async function personOf(ctx: CommandContext): Promise<{ token: string; email?: string } | null> {
+  if (!ctx.token.startsWith('sk-')) return { token: ctx.token }
+  if (!ctx.profile || process.env.FRONTERA_TOKEN?.trim()) return null
+  return readDeviceSession(credentialStore(), ctx.profile, ctx.apiUrl)
 }
 
 export const actionDeploy: Command = {
@@ -30,10 +52,15 @@ export const actionDeploy: Command = {
     authLane: 'api-key',
     args: [{ name: 'action', required: true, description: 'The published Action’s API name' }],
     flags: { 'dry-run': 'boolean', 'plan-id': 'string', 'binding-id': 'string', attach: 'string', 'attach-item-id': 'string', 'file-input': 'string', 'media-set': 'string' },
-    summary: 'Build and validate the write path for a published Action',
+    summary: 'Build the write path for a published Action and, as a signed-in person, turn it on',
+    details: [
+      'It asks before turning the write path on, naming the Action and the host; --yes turns it on without asking. With no terminal and no --yes, it stops once the write path is validated.',
+      'When the Action runs, is still finishing requests on, or last ran a write path that calls another system, it builds the new one as the signed-in person rather than with an API key, stops once it is validated and prints the review a second person runs. Retiring the old one first does not change that.',
+    ],
     examples: [
       'frontera action deploy escalateTicket --dry-run',
       'frontera action deploy escalateTicket',
+      'frontera action deploy escalateTicket --yes',
       'frontera action deploy attachPhoto --attach photo --file-input upload',
     ],
   },
@@ -96,18 +123,39 @@ export const actionDeploy: Command = {
       }
     }
 
+    // A deploy aimed with --profile (a change request's step, from a folder bound to its local runtime) aims what it prints too.
+    const at = typeof ctx.flags.profile === 'string' ? ` --profile ${ctx.flags.profile}` : ''
+    const external = await client.externalWritePath(definition.id)
+    const person = await personOf(ctx)
+    // A key in FRONTERA_TOKEN wins over a browser sign-in, so signing in changes nothing while it is set.
+    const keyInEnvironment = Boolean(process.env.FRONTERA_TOKEN?.trim())
+    if (external && !person) {
+      throw new CliError(`${externalWritePathSentence(`"${apiName}"`, external)} A write path built with an API key cannot replace it, and ${keyInEnvironment ? 'FRONTERA_TOKEN holds an API key' : 'nobody is signed in here'}, so nothing was built.`, {
+        code: 'CONFLICT',
+        hint: keyInEnvironment
+          ? 'unset FRONTERA_TOKEN or set it to a person\'s token, and deploy again; it builds the new one as that person, and a second person reviews it'
+          : `sign in with \`frontera auth login --browser${at}\` and deploy again; it builds the new one as you, and a second person reviews it`,
+        details: { action: apiName, replacedPlanKind: external.planKind, replacedState: external.state },
+      })
+    }
+    if (external && person && ctx.token !== person.token) {
+      if (!selectedOrganization() && external.organizationId) setSelectedOrganization(external.organizationId)
+      ctx.output.note(`building it as ${person.email ?? 'you'} (browser sign-in), since no write path an API key built replaces one that calls another system`)
+    }
+    const builder = external && person ? api(ctx, person.token) : client
+
     // Client-minted, so a retry after a network failure can name the same
     // artifact instead of orphaning a half-built one.
     const planId = flagString(ctx, 'plan-id') ?? randomUUID()
     const bindingId = flagString(ctx, 'binding-id') ?? randomUUID()
 
-    const planRevision = await client.createMutationPlanRevision(planId, plan)
-    const binding = await client.createBindingRevision(bindingId, {
+    const planRevision = await builder.createMutationPlanRevision(planId, plan)
+    const binding = await builder.createBindingRevision(bindingId, {
       actionDefinitionId: definition.id,
       actionContractDigest: published.contractDigest,
       mutationPlanRevisionId: planRevision.id,
     })
-    const validation = await client.validateBindingRevision(binding.id, 1)
+    const validation = await builder.validateBindingRevision(binding.id, 1)
 
     if (validation.status !== 'valid') {
       // Each failed check, by its code and the platform's message, one per line; the full report in `--json` details.
@@ -124,21 +172,91 @@ export const actionDeploy: Command = {
       )
     }
 
+    const built = {
+      action: apiName,
+      planId,
+      planRevisionId: planRevision.id,
+      bindingId,
+      bindingRevisionId: binding.id,
+      stateId: binding.stateId,
+      validationReportId: validation.id,
+    }
+    const summary = `  ${plan.op} ${plan.objectTypeApiName} — sets ${writes}`
+    const review = `frontera action review ${binding.id} --report ${validation.id}${at}`
+    const again = `frontera action deploy ${apiName} --yes${at}`
+    const secondPerson = `a second person who may review Actions turns it on with: ${review}`
+
+    if (external) {
+      throw new CliError(
+        `${externalWritePathSentence(`"${apiName}"`, external)} `
+        + 'The one just built only edits Blueprint records, and a second person reviews it before it is turned on.',
+        {
+          code: 'CONFLICT',
+          hint: secondPerson,
+          details: { ...built, status: validation.status, replacedPlanKind: external.planKind, replacedState: external.state },
+        },
+      )
+    }
+
+    if (!person) {
+      return {
+        data: { ...built, status: validation.status, activated: false, next: review },
+        text: `Built and validated the write path for "${apiName}".\n${summary}\n\n`
+          + 'An API key cannot turn it on; a signed-in person can, and because it only edits Blueprint records, that may be you. '
+          + (keyInEnvironment ? 'Unset FRONTERA_TOKEN, which holds an API key, or set it to a person\'s token, then run:\n' : `Sign in with \`frontera auth login --browser${at}\`, then run:\n`)
+          + `  ${review}`,
+      }
+    }
+    // The build named the key's organization; the person's calls name the same one.
+    if (!selectedOrganization() && binding.organizationId) setSelectedOrganization(binding.organizationId)
+    const asPerson = api(ctx, person.token)
+
+    if (!flagBool(ctx, 'yes')) {
+      const current = await asPerson.currentDeployment(definition.id)
+      const host = new URL(ctx.apiUrl).host
+      const question = `Turn on the write path for "${apiName}" on ${host}${current?.state === 'active' ? ', replacing the one that runs now' : ''}?`
+      const go = (ctx.interactive ?? canPrompt()) && ctx.flags['no-input'] !== true ? await promptConfirm(question) : false
+      if (!go) {
+        return {
+          data: { ...built, status: validation.status, activated: false, next: again },
+          text: `Built and validated the write path for "${apiName}", and did not turn it on.\n${summary}\n\n`
+            + `To build it again and turn it on, run:\n  ${again}`,
+        }
+      }
+    }
+    if (person.email) ctx.output.note(`turning it on as ${person.email} (browser sign-in)`)
+
+    try {
+      await reviewRevision(asPerson, { bindingRevisionId: binding.id, validationReportId: validation.id, activating: true })
+    } catch (err) {
+      if (!(err instanceof CliError)) throw err
+      throw new CliError(`Built and validated the write path for "${apiName}", but did not review it: ${err.message}`, {
+        code: err.code,
+        hint: `another person who may review Actions turns it on with: ${review}`,
+        details: { ...built, status: validation.status },
+        cause: err,
+      })
+    }
+    let stateId: string
+    try {
+      stateId = (await activateReviewed(asPerson, binding.id)).stateId
+    } catch (err) {
+      if (!(err instanceof CliError)) throw err
+      const needsSecondPerson = (err.details as { reason?: string } | undefined)?.reason === 'ACTION_DEPLOYMENT_REPLACES_EXTERNAL_WRITE_PATH'
+      throw new CliError(`Reviewed the write path for "${apiName}", but did not turn it on: ${err.message}`, {
+        code: err.code,
+        hint: needsSecondPerson
+          ? `build a fresh write path with \`frontera action deploy ${apiName}${at}\`; a second person reviews it with the command it prints`
+          : `run \`${again}\` to build a fresh write path and turn it on`,
+        details: { ...built, status: validation.status, reviewed: true },
+        cause: err,
+      })
+    }
+
     return {
-      data: {
-        action: apiName,
-        planId,
-        planRevisionId: planRevision.id,
-        bindingId,
-        bindingRevisionId: binding.id,
-        stateId: binding.stateId,
-        validationReportId: validation.id,
-        status: validation.status,
-      },
-      text: `Built and validated the write path for "${apiName}".\n`
-        + `  ${plan.op} ${plan.objectTypeApiName} — sets ${writes}\n\n`
-        + 'Next, as a DIFFERENT user — the service refuses a reviewer who authored the material:\n'
-        + `  frontera action review ${binding.id} --report ${validation.id}`,
+      data: { ...built, stateId, status: validation.status, activated: true },
+      text: `Built, reviewed and turned on the write path for "${apiName}".\n${summary}\n\n`
+        + 'A role that holds its capability can now invoke it.',
     }
   },
 }

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

@@ -17,9 +17,9 @@ import type { Command } from '../types'
  * Blueprint authoring reaches the Action's CONTRACT — `blueprint create action`
  * and `blueprint apply` both write it, and `blueprint publish` releases it. What
  * had no verb anywhere was arming the write: a mutation plan, a Binding pinned
- * to the contract digest, a validation against the live target, an independent
- * review and a state-machine activation. Five admin calls with hand-minted
- * UUIDs, or nothing.
+ * to the contract digest, a validation against the live target, a review and a
+ * state-machine activation. Five admin calls with hand-minted UUIDs, or
+ * nothing.
  *
  * Invoking — `available`, `submit`, `approve`, `reject`, `cancel` — is
  * session-lane. Both key kinds present a non-member principal — `wskey:…` and

package/src/commands/action/list.ts

@@ -46,11 +46,11 @@ export function whyNot(apiName: string, entry: { published: boolean; deploymentS
   const code = entry.reason && entry.reason !== 'ACTION_AVAILABLE' ? ` (${entry.reason})` : ''
   switch (entry.deploymentStatus) {
     case 'unbound':
-      return `no write path${code} — \`frontera action deploy ${apiName}\`, then \`action review\``
+      return `no write path${code} — \`frontera action deploy ${apiName}\``
     case 'disabled':
-      return `ships switched off${code} — \`frontera action deploy ${apiName}\`, then \`action review\``
+      return `ships switched off${code} — \`frontera action deploy ${apiName}\``
     case 'suspended':
-      return `its deployment is suspended${code} — review it again with \`frontera action review\``
+      return `its deployment is suspended${code} — review it again with \`frontera action review\` (a second person, if it calls another system)`
     case 'revoked':
       return `its deployment was revoked${code} — \`frontera action deploy ${apiName}\` again`
     case 'active':

package/src/commands/action/prepare.ts

@@ -8,6 +8,8 @@ import { flagString, type Command } from '../types'
  * Publish refuses an Action with no deployment decision, and every other
  * deployment route acts on a state that already exists — so without this the
  * two requirements are circular and the first row has to be written by hand.
+ * `blueprint publish` records the same decision for each Action that has none,
+ * so this is the step on its own, before a publish.
  *
  * It arms nothing. `action deploy` is still the only thing that builds a write
  * path, and it runs AFTER the release, because a Binding is validated against
@@ -22,7 +24,7 @@ export const actionPrepare: Command = {
     authLane: 'api-key',
     args: [{ name: 'action', required: true, description: 'The drafted Action’s API name' }],
     flags: { reason: 'string' },
-    summary: 'Record that a drafted Action ships disabled, so it can be published',
+    summary: 'Record that a drafted Action ships disabled (blueprint publish also does this)',
     examples: [
       'frontera action prepare escalateTicket',
       'frontera action prepare escalateTicket --reason "ships off"',
@@ -43,8 +45,8 @@ export const actionPrepare: Command = {
       data: decision,
       text: `"${apiName}" will publish disabled.\n`
         + `  state ${decision.stateId} · generation ${decision.generation}\n\n`
-        + 'Next:\n'
-        + '  frontera blueprint publish --label "…" \n'
+        + 'Next (`blueprint publish` records this decision itself, so this step is optional):\n'
+        + '  frontera blueprint publish --label "…"\n'
         + `  frontera action deploy ${apiName}`,
     }
   },