@frontera-sdk/cli 0.1.0 → 1.43.6

package/src/commands/blueprint/declarative.ts

@@ -0,0 +1,1052 @@
+import { existsSync, mkdirSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import {
+  linkTypeCreateBody,
+  linkTypeStructure,
+  objectTypeCreateBody,
+  metricCreateBody,
+  metricPatchBody,
+  readBacking,
+  resolveSharedProperty,
+  sharedPropertyCreateBody,
+  sharedPropertyPatchBody,
+} from '../../blueprint/compile'
+import { pickCurrentRevision } from '../../blueprint/dataset-revision'
+import { diff, isEmpty, satisfies, type ModelOperation, type Plan } from '../../blueprint/diff'
+import {
+  API_NAME_RULE,
+  ARTIFACT_KINDS,
+  KIND_DIRECTORY,
+  describeApiNameRule,
+  indexBundle,
+  type ArtifactKind,
+  type AuthoredFile,
+  type DefinitionBundle,
+} from '../../blueprint/model'
+import { toFiles } from '../../blueprint/projection'
+import { renderDrift, renderPlan } from '../../blueprint/render'
+import { scaffold } from '../../blueprint/scaffold'
+import { pathFor, readTree, removeFromTree, writeTree } from '../../blueprint/tree'
+import { CliError } from '../../errors'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * Declarative Blueprint authoring: the Blueprint as files, applied to a draft.
+ *
+ * The imperative verbs beside this one (`create`, `update`, `delete`) stay, and stay
+ * supported, for exploring an organization interactively. This is the path for
+ * DEPLOYING one — re-runnable, reviewable as a diff, and the same tree on every
+ * environment because nothing environment-shaped is in it.
+ */
+
+function api(ctx: CommandContext): BlueprintAuthoringApi {
+  return new BlueprintAuthoringApi(ctx.apiUrl, ctx.token)
+}
+
+/** Any uuid at all. The tree is portable only when it contains none. */
+const UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i
+
+function root(ctx: CommandContext): string {
+  return resolve(ctx.cwd, (ctx.flags.dir as string) ?? 'blueprint')
+}
+
+/**
+ * Datasets, or nothing if this credential cannot read them.
+ *
+ * Reading datasets needs `dataset: ['read']`, which a key minted only to author the
+ * MODEL will not carry — and authoring the model does not need it. So a refusal here
+ * is a fact about the credential, not a failure of the command: `pull` still writes
+ * every artifact and simply omits `backing`, and `plan` still diffs. Only `bind`
+ * genuinely requires the capability, and it says so by name when it is missing.
+ *
+ * Letting the 403 escape made `pull` unusable for a model-only key, which is the
+ * common case for a key scoped to exactly what it needs.
+ */
+async function readableDatasets(
+  client: BlueprintAuthoringApi,
+): Promise<Array<{ id?: string; name?: string; currentRevisionId?: string }> | null> {
+  try {
+    return await client.listDatasets()
+  } catch (err) {
+    if (err instanceof CliError && (err.code === 'FORBIDDEN' || err.code === 'UNAUTHORIZED')) return null
+    throw err
+  }
+}
+
+/** Dataset name → id, read once per command that needs it. */
+async function datasetsByName(client: BlueprintAuthoringApi): Promise<Map<string, string>> {
+  const datasets = await readableDatasets(client) ?? []
+  const byName = new Map<string, string>()
+  for (const dataset of datasets) {
+    if (dataset.name && dataset.id) byName.set(dataset.name, dataset.id)
+  }
+  return byName
+}
+
+/**
+ * Dataset revision id → dataset name, for `pull`.
+ *
+ * One request per dataset rather than per bound object type: a hundred types sharing
+ * one dataset is one lookup.
+ */
+async function datasetNamesByRevision(
+  client: BlueprintAuthoringApi,
+): Promise<Map<string, string>> {
+  const names = new Map<string, string>()
+  for (const dataset of await readableDatasets(client) ?? []) {
+    if (!dataset.id || !dataset.name) continue
+    for (const revision of await client.datasetRevisions(dataset.id)) {
+      if (revision.id) names.set(revision.id, dataset.name)
+    }
+  }
+  return names
+}
+
+async function resolveRevision(
+  client: BlueprintAuthoringApi,
+  name: string,
+): Promise<{ revisionId: string; schemaDigest: string }> {
+  const datasets = await readableDatasets(client) ?? []
+  const dataset = datasets.find((candidate) => candidate.name === name)
+  const datasetId = dataset?.id
+  if (!datasetId) {
+    throw new CliError(`No dataset named "${name}" in this organization.`, {
+      code: 'NOT_FOUND',
+      // The 403 shape is worth naming: a key minted without `dataset:read` sees an
+      // empty list rather than a refusal, which reads as "the dataset is missing".
+      hint: `frontera blueprint plan lists what is reachable. If nothing is, the key may not carry dataset:read.`,
+    })
+  }
+  const revisions = await client.datasetRevisions(datasetId)
+  // The dataset names its current revision; the sorted list is only the fallback for
+  // a payload that does not carry it. Shared with `bind` — see `dataset-revision.ts`.
+  const current = pickCurrentRevision(dataset, revisions)
+  if (!current?.id || !current.schemaDigest) {
+    throw new CliError(`Dataset "${name}" has no published revision to bind to.`, {
+      code: 'FAILURE',
+      hint: 'Publish a revision of the dataset first.',
+    })
+  }
+  return { revisionId: current.id, schemaDigest: current.schemaDigest }
+}
+
+export const blueprintPull: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'pull',
+    args: [],
+    flags: { dir: 'string', force: 'boolean' },
+    summary: 'Write the shared draft to a file tree you can commit',
+    examples: ['frontera blueprint pull', 'frontera blueprint pull --dir ./blueprint'],
+  },
+  async run(ctx) {
+    const client = api(ctx)
+    const { definition } = await client.draft()
+    const directory = root(ctx)
+
+    if (!ctx.flags.force && existsSync(directory) && readTree(directory).length > 0) {
+      throw new CliError(`${directory} already holds a Blueprint tree.`, {
+        code: 'USAGE',
+        // A round trip makes overwriting easy and silent, which is exactly when a
+        // confirmation earns its place.
+        hint: 'Commit or move what is there, then re-run with --force to overwrite it.',
+      })
+    }
+
+    const names = await datasetNamesByRevision(client)
+    const model = toFiles(definition, names)
+    // The root is created even when the draft is empty. An empty Blueprint is a
+    // legitimate state — a freshly adopted organization, or one rolled back to its
+    // baseline — and leaving no directory behind made the next `plan` report "no
+    // Blueprint tree" for what is really "no artifacts yet".
+    mkdirSync(directory, { recursive: true })
+    // Anything the tree holds that the draft no longer has is deleted, not left
+    // behind: `pull` writes what the draft IS, and a leftover file would be read back
+    // by the next `plan` as an artifact somebody wants created.
+    const keep = new Set(model.files.map((file) => file.path))
+    // `--force` exists to overwrite a tree that is wrong, so reading it must not be
+    // able to refuse the overwrite. A filename/apiName mismatch throws from
+    // `readTree`, which made the broken tree the one case `--force` could not fix.
+    const stale = existingPaths(directory)
+      .filter((path) => !keep.has(path))
+    const dropped = removeFromTree(directory, stale)
+    const written = writeTree(directory, model.files)
+    // A written file may still carry identifiers the projection cannot turn into
+    // names — validation ids, lifecycle state ids. Such a tree round-trips against the
+    // SAME draft and is not portable to another deployment, and saying so here is the
+    // difference between a documented limit and a surprise at the second deployment.
+    const unportable = model.files
+      .filter((file) => UUID_PATTERN.test(JSON.stringify(file.document)))
+      .map((file) => file.path)
+    const bound = definition.objects.filter((object) =>
+      (object.governance.sourceMappings[0] as { datasetRevisionId?: string } | undefined)?.datasetRevisionId,
+    ).length
+    // Said plainly rather than left to be discovered: a tree pulled without dataset
+    // access is complete as a MODEL and cannot recreate the bindings elsewhere.
+    const omitted = bound > 0 && names.size === 0
+      ? ' Dataset names were not readable with this credential, so `backing` is omitted —'
+        + ' this tree describes the model, not what it reads.'
+      : ''
+    return {
+      data: {
+        directory,
+        files: written,
+        removed: dropped,
+        backingsOmitted: omitted !== '',
+        unportable,
+      },
+      text: `Wrote ${written.length} artifact${written.length === 1 ? '' : 's'} to ${directory}.`
+        + (dropped.length ? ` Removed ${dropped.length} no longer on the draft.` : '')
+        + omitted
+        + (unportable.length
+          ? `\n${unportable.length} carr${unportable.length === 1 ? 'ies' : 'y'} identifiers that name `
+            + `nothing in another deployment (${unportable.join(', ')}) — this tree round-trips here, `
+            + 'but is not portable as it stands.'
+          : ''),
+    }
+  },
+}
+
+/** Paths already in the tree, tolerating files this CLI would refuse to read. */
+function existingPaths(directory: string): string[] {
+  if (!existsSync(directory)) return []
+  try {
+    return readTree(directory).map((file) => file.path)
+  } catch {
+    // A tree that cannot be parsed still has files, and `--force` is how they get
+    // replaced. Enumerated directly rather than through the reader that rejected it.
+    return ARTIFACT_KINDS.flatMap((kind) => {
+      const sub = join(directory, KIND_DIRECTORY[kind])
+      if (!existsSync(sub)) return []
+      return readdirSync(sub)
+        .filter((entry) => /\.(ya?ml|json)$/.test(entry))
+        .map((entry) => `${KIND_DIRECTORY[kind]}/${entry}`)
+    })
+  }
+}
+
+async function computePlan(ctx: CommandContext): Promise<{
+  plan: Plan
+  files: AuthoredFile[]
+  /** The draft the plan was computed against — `apply` indexes it for id resolution. */
+  definition: DefinitionBundle
+  drift: Array<{ objectApiName: string; datasetName: string; currentDigest: string }>
+}> {
+  const client = api(ctx)
+  const directory = root(ctx)
+  if (!existsSync(directory)) {
+    throw new CliError(`No Blueprint tree at ${directory}.`, {
+      code: 'USAGE',
+      hint: 'frontera blueprint pull, or frontera blueprint new object-type <ApiName>',
+    })
+  }
+  const files = readTree(directory)
+  const { definition, revision } = await client.draft()
+  const plan = diff(files, definition, revision)
+
+  // Per DISTINCT dataset, which is what the design promised and what the previous
+  // loop did not do: it called `datasetRevisions` once per BOUND TYPE, after
+  // `datasetNamesByRevision` had already read every dataset's revisions. A hundred
+  // types on one dataset cost a hundred redundant round trips.
+  const drift: Array<{ objectApiName: string; datasetName: string; currentDigest: string }> = []
+  if (plan.drift.length > 0) {
+    // One pass over the datasets, not two: the revisions are read once and both the
+    // revision→name map and the current-revision map are built from the same reads.
+    const names = new Map<string, string>()
+    const currentByDataset = new Map<string, { id: string; schemaDigest?: string }>()
+    for (const dataset of await readableDatasets(client) ?? []) {
+      if (!dataset.id || !dataset.name) continue
+      const revisions = await client.datasetRevisions(dataset.id)
+      for (const revision of revisions) {
+        if (revision.id) names.set(revision.id, dataset.name)
+      }
+      const current = pickCurrentRevision(dataset, revisions)
+      if (current?.id) currentByDataset.set(dataset.name, { id: current.id, schemaDigest: current.schemaDigest })
+    }
+    for (const pin of plan.drift) {
+      const datasetName = names.get(pin.datasetRevisionId)
+      if (!datasetName) continue
+      const current = currentByDataset.get(datasetName)
+      if (!current?.schemaDigest || current.schemaDigest === pin.pinnedDigest) continue
+      drift.push({ objectApiName: pin.objectApiName, datasetName, currentDigest: current.schemaDigest })
+    }
+  }
+  return { plan, files, definition, drift }
+}
+
+export const blueprintPlan: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'plan',
+    args: [],
+    flags: { dir: 'string', prune: 'boolean' },
+    summary: 'Show what applying the file tree would change, and write nothing',
+    examples: ['frontera blueprint plan', 'frontera blueprint plan --json'],
+  },
+  async run(ctx) {
+    const { plan, drift } = await computePlan(ctx)
+    const body = [renderPlan(plan, { prune: ctx.flags.prune === true }), renderDrift(drift)]
+      .filter(Boolean)
+      .join('\n')
+    return { data: { ...plan, drift }, text: body }
+  },
+}
+
+/**
+ * Apply one operation, on the route that carries its guard.
+ *
+ * Creations go to the per-artifact POST rather than to a whole-bundle write: the
+ * create route mints every id, derives each property's base type from the pinned
+ * column, and writes the `governance.sourceMappings` shell that a later `bind`
+ * requires. An object type inserted any other way can never afterwards be bound.
+ */
+async function applyOperation(
+  client: BlueprintAuthoringApi,
+  operation: ModelOperation,
+  file: AuthoredFile,
+  revision: number,
+  sharedPropertyIds: Map<string, string>,
+): Promise<number> {
+  const resolveDataset = (name: string) => resolveRevision(client, name)
+
+  if (operation.kind === 'shared-field') {
+    if (operation.operation === 'create') {
+      const created = await client.createSharedProperty(
+        sharedPropertyCreateBody(file, revision),
+        revision,
+      )
+      // The minted id, threaded into the property writes that follow in THIS run —
+      // the same way `expectedRevision` is threaded. Without it a tree that creates a
+      // shared field and its implementer together can only work on a second apply.
+      const id = created?.sharedProperty?.id
+      if (!id) {
+        throw new CliError(
+          `Creating shared field "${operation.apiName}" returned no id, so nothing can reference it.`,
+          {
+            code: 'FAILURE',
+            hint: 'The service is expected to answer with the created row. Re-run `frontera blueprint plan`.',
+          },
+        )
+      }
+      sharedPropertyIds.set(operation.apiName, id)
+      return nextRevision(created, revision)
+    }
+    assertApplicable('shared-field', file, operation.liveDocument)
+    const updated = await client.updateSharedProperty(
+      operation.apiName, sharedPropertyPatchBody(file, revision), revision,
+    )
+    return nextRevision(updated, revision)
+  }
+
+  if (operation.kind === 'object-type') {
+    if (operation.operation === 'create') {
+      const created = await client.createObjectType(
+        await objectTypeCreateBody(file, revision, resolveDataset, sharedPropertyIds),
+        revision,
+      )
+      return nextRevision(created, revision)
+    }
+    // Refused BEFORE the first write, not after some of them. Everything this
+    // executor can express is enumerated below; a difference outside that set has no
+    // route to travel, and reporting it as applied is the defect this whole review
+    // round keeps finding at a new level. Naming the field beats a silent no-op.
+    assertApplicable('object-type', file, operation.liveDocument)
+
+    // Sent only when the metadata actually differs. The service refuses a command
+    // that would not change the draft — "Blueprint Draft command does not change the
+    // Shared Draft" — so an unconditional PUT turned a pure property change into a
+    // failed run that had applied nothing.
+    let current = revision
+    const patch = objectTypeMetadataChanges(file, operation.liveDocument)
+    if (Object.keys(patch).length > 0) {
+      const updated = await client.updateObjectType(
+        operation.apiName, { ...patch, expectedRevision: revision }, revision,
+      )
+      current = nextRevision(updated, revision)
+    }
+    current = await applyObjectKeys(client, operation.apiName, file, operation.liveDocument, current)
+    return applyPropertyPlan(
+      client, operation.apiName, file, operation.liveDocument, current, sharedPropertyIds,
+    )
+  }
+
+  if (operation.kind === 'link-type') {
+    if (operation.operation !== 'create') assertApplicable('link-type', file, operation.liveDocument)
+    const body = operation.operation === 'create'
+      ? await client.createLinkType(linkTypeCreateBody(file, revision), revision)
+      : await client.updateLinkType(operation.apiName, linkTypeStructure(file, revision), revision)
+    return nextRevision(body, revision)
+  }
+
+  if (operation.operation !== 'create') assertApplicable('metric', file, operation.liveDocument)
+  const result = operation.operation === 'create'
+    ? await client.createMetric(metricCreateBody(file, revision), revision)
+    : await client.updateMetric(operation.apiName, metricPatchBody(file, revision), revision)
+  return nextRevision(result, revision)
+}
+
+/**
+ * The revision a write produced, so the next write can declare it.
+ *
+ * `apply` must never re-read the revision mid-run. Re-reading was the whole defect:
+ * every write then declared "expectedRevision = whatever it is right now", so a
+ * colleague editing the shared draft between two of our writes could never produce a
+ * 409 — the one guard the shared draft depends on, and the same shared-ness that makes
+ * `--prune` opt-in. Threading it forward means a concurrent edit makes OUR next
+ * expectation stale, which is exactly when the service should refuse us.
+ *
+ * The `+ 1` fallback is for a route that does not echo the revision; it stays strict,
+ * because guessing a revision the server did not confirm still gets refused if the
+ * draft moved.
+ */
+function nextRevision(response: unknown, previous: number): number {
+  const echoed = (response as { draftRevision?: unknown } | null)?.draftRevision
+  return typeof echoed === 'number' ? echoed : previous + 1
+}
+
+/**
+ * What each kind's update routes can actually express, named as the FILE names them.
+ *
+ * Per kind rather than for object types alone, because the defect is not about object
+ * types: an update reported as applied and not applied is the same lie whichever route
+ * dropped it, and every kind has fields outside what its route takes.
+ *
+ * OBJECT TYPE — `metadata` travels the PUT, the keys travel `set_object_keys`,
+ * `properties` travels the field commands. `governance`, `validations` and `lifecycle`
+ * have no command at all.
+ *
+ * LINK TYPE — `PUT /link-types/:apiName` takes the whole structure, so nearly
+ * everything a file states is expressible. `status` is not: the bundle carries it and
+ * the route has no field for it.
+ *
+ * METRIC — `PUT /metrics/:apiName` takes `displayName`, `description`, `definition`
+ * and `formatConfig`. `objectType` is deliberately absent: the subject is fixed at
+ * creation, the patch body has no channel for it, and editing it in a file was planned,
+ * counted as applied, and re-planned identically on every run afterwards.
+ *
+ * SHARED FIELD — its patch route takes every authored field, including `valueType`,
+ * which is a breaking change the release gate reports rather than something the
+ * route refuses.
+ */
+const APPLICABLE_FIELDS: Record<ArtifactKind, Set<string>> = {
+  'shared-field': new Set([
+    'apiName', 'displayName', 'description', 'valueType', 'propertyType', 'formatConfig',
+    'status', 'visibility',
+  ]),
+  'object-type': new Set([
+    'apiName', 'displayName', 'pluralDisplayName', 'description', 'icon', 'color',
+    'status', 'visibility', 'groups', 'primaryKey', 'title', 'properties', 'backing',
+  ]),
+  'link-type': new Set(['apiName', 'cardinality', 'description', 'from', 'to']),
+  metric: new Set(['apiName', 'displayName', 'description', 'definition', 'formatConfig']),
+}
+
+export function assertApplicable(
+  kind: ArtifactKind,
+  file: AuthoredFile,
+  live: Record<string, unknown> | undefined,
+): void {
+  if (!live) return
+  const applicable = APPLICABLE_FIELDS[kind]
+  // The SAME predicate the plan used to decide this artifact changed. An equality
+  // comparison here would disagree with it about key order and about the fields a file
+  // omits, and refuse the run naming a field the plan never called changed.
+  const unmappable = Object.keys(file.document).filter((field) =>
+    !applicable.has(field) && !satisfies(file.document[field], live[field], field))
+  if (unmappable.length === 0) return
+  throw new CliError(
+    `${file.path}: ${unmappable.join(', ')} ${unmappable.length === 1 ? 'differs' : 'differ'} from the draft, `
+    + 'and no authoring route can apply that.',
+    {
+      code: 'USAGE',
+      hint: kind === 'metric' && unmappable.includes('objectType')
+        ? 'A metric measures one object type for its lifetime. To move it, delete the file and '
+          + '`apply --prune`, then write it again against the new object type.'
+        : 'Revert those fields to match the draft, or change them in the Console. '
+          + 'Applying would report a change that did not happen.',
+    },
+  )
+}
+
+/**
+ * `primaryKey` and `title` — the two references a file states by property apiName.
+ *
+ * Structural, so they travel `set_object_keys` rather than the metadata PUT. Without
+ * this, editing either was planned, counted as applied, and never written.
+ */
+async function applyObjectKeys(
+  client: BlueprintAuthoringApi,
+  apiName: string,
+  file: AuthoredFile,
+  live: Record<string, unknown> | undefined,
+  revision: number,
+): Promise<number> {
+  const wantedKey = file.document.primaryKey
+  const wantedTitle = file.document.title
+  const keyChanged = wantedKey !== undefined && wantedKey !== live?.primaryKey
+  const titleChanged = wantedTitle !== undefined && wantedTitle !== live?.title
+  if (!keyChanged && !titleChanged) return revision
+
+  const detail = await client.getObjectTypeDetail(apiName)
+  if (!detail?.id) return revision
+  const idByApiName = new Map(
+    detail.properties
+      .filter((property) => property.apiName && property.id)
+      .map((property) => [String(property.apiName), String(property.id)]),
+  )
+  const resolve = (name: unknown, field: string) => {
+    const id = idByApiName.get(String(name))
+    if (!id) {
+      throw new CliError(`${file.path}: ${field} names "${name}", which is not one of its properties.`, {
+        code: 'USAGE',
+        hint: 'Both keys name a property by apiName.',
+      })
+    }
+    return id
+  }
+  // Both ids are required by the command, so the unchanged one is restated from the
+  // file rather than omitted — `set_object_keys` sets the pair, it does not patch one.
+  const result = await client.draftCommand({
+    kind: 'set_object_keys',
+    objectId: detail.id,
+    primaryKeyPropertyId: resolve(wantedKey ?? live?.primaryKey, 'primaryKey'),
+    titlePropertyId: resolve(wantedTitle ?? live?.title, 'title'),
+  }, revision)
+  return result.revision
+}
+
+/** Object-level metadata the file states and the draft does not already agree with. */
+function objectTypeMetadataChanges(
+  file: AuthoredFile,
+  live: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const document = file.document
+  const patch: Record<string, unknown> = {}
+  const pairs: Array<[string, string]> = [
+    ['displayName', 'displayName'],
+    ['pluralDisplayName', 'pluralName'],
+    ['description', 'description'],
+    ['icon', 'icon'],
+    ['color', 'color'],
+    ['status', 'status'],
+    ['visibility', 'visibility'],
+  ]
+  for (const [fileField, wireField] of pairs) {
+    const value = document[fileField]
+    if (value !== undefined && value !== live?.[fileField]) patch[wireField] = value
+  }
+  const groups = document.groups
+  if (Array.isArray(groups) && JSON.stringify(groups) !== JSON.stringify(live?.groups ?? [])) {
+    patch.groups = groups
+  }
+  return patch
+}
+
+/**
+ * Reconcile one object type's properties.
+ *
+ * `PUT /object-types/:apiName` takes METADATA only and ignores `properties`, so every
+ * field change has to travel a draft command. Additions were wired first and the rest
+ * were left with a comment claiming they were "refused by name" — they were not; they
+ * were dropped, counted as applied, and re-reported by the next `plan` forever. A
+ * planning tool that says it did something it did not is the one failure worth
+ * refusing outright, so anything this cannot map now aborts BEFORE the first write.
+ *
+ * Mapped: add, remove, and a change to any field the file can state. Unmapped: a
+ * property rename, which is indistinguishable from a remove plus an add for the same
+ * reason an object-type rename is (`rename` exists for that, and there is no
+ * per-property equivalent).
+ */
+interface PropertyPlan {
+  adds: Array<Record<string, unknown>>
+  removes: Array<{ id: string; apiName: string }>
+  schemaChanges: Array<{ id: string; apiName: string; patch: Record<string, unknown> }>
+  metadataChanges: Array<{ id: string; apiName: string; patch: Record<string, unknown> }>
+}
+
+/** Fields a file states that live on `update_field_schema`. */
+const SCHEMA_FIELDS = ['valueType', 'propertyType', 'required', 'unique'] as const
+/** …and on `update_field_metadata`. */
+const METADATA_FIELDS = ['displayName', 'description', 'status', 'visibility'] as const
+
+/**
+ * @param live the projected live artifact — the same shape the FILE is written in.
+ *
+ * Not the route payload. The route answers properties in the catalog's own vocabulary,
+ * where the bundle's `valueType` does not exist; comparing against it made every
+ * declared `valueType` read as a change and produced a patch per property that changed
+ * nothing. The service refuses a command that changes nothing, so a pure removal
+ * failed with "does not change the Shared Draft" and applied none of it.
+ *
+ * @param idByApiName the route payload's ids, which the projection deliberately omits.
+ */
+function planProperties(
+  file: AuthoredFile,
+  live: Array<Record<string, unknown>>,
+  backing: ReturnType<typeof readBacking>,
+  idByApiName: Map<string, string>,
+): PropertyPlan {
+  const declared = Array.isArray(file.document.properties)
+    ? (file.document.properties as Array<Record<string, unknown>>)
+    : []
+  const liveByName = new Map(live.map((property) => [String(property.apiName), property]))
+  const declaredNames = new Set(declared.map((property) => String(property.apiName)))
+
+  const plan: PropertyPlan = { adds: [], removes: [], schemaChanges: [], metadataChanges: [] }
+
+  for (const property of declared) {
+    const name = String(property.apiName)
+    const counterpart = liveByName.get(name)
+    if (!counterpart) {
+      plan.adds.push(property)
+      continue
+    }
+    const schemaPatch: Record<string, unknown> = {}
+    for (const field of SCHEMA_FIELDS) {
+      if (property[field] !== undefined && property[field] !== counterpart[field]) {
+        schemaPatch[field] = property[field]
+      }
+    }
+    // The column a property reads lives in `backing.mapping`, not beside the property.
+    const mapped = backing?.mapping?.[name]
+    const column = mapped === undefined ? undefined : typeof mapped === 'string' ? mapped : mapped.column
+    if (column !== undefined && column !== counterpart.column) schemaPatch.sourceColumn = column
+
+    const metadataPatch: Record<string, unknown> = {}
+    for (const field of METADATA_FIELDS) {
+      if (property[field] !== undefined && property[field] !== counterpart[field]) {
+        metadataPatch[field] = property[field]
+      }
+    }
+    // Carried by NAME through the plan and resolved to an id at write time: the
+    // shared field may not exist yet when the plan is computed. Attaching to a
+    // shared field is `update_field_metadata`'s job, so it travels that patch.
+    //
+    // An authored `null` means detached, and a live field with no reference is
+    // ALREADY that — so the two are compared as the same state. Treating them as
+    // different made a file that says `sharedField: null` re-plan a detach on
+    // every run and then fail it, because the applied command changes nothing and
+    // the service refuses a command that does not change the Shared Draft.
+    if (property.sharedField !== undefined) {
+      const wanted = property.sharedField === null ? null : property.sharedField
+      const current = counterpart.sharedField ?? null
+      if (wanted !== current) metadataPatch.sharedField = wanted
+    }
+    const id = idByApiName.get(name)
+    // A declared property with no live id is either brand new (handled above) or the
+    // draft moved; skipping it quietly is how a change goes missing.
+    if (!id) continue
+    if (Object.keys(schemaPatch).length > 0) plan.schemaChanges.push({ id, apiName: name, patch: schemaPatch })
+    if (Object.keys(metadataPatch).length > 0) {
+      plan.metadataChanges.push({ id, apiName: name, patch: metadataPatch })
+    }
+  }
+
+  for (const property of live) {
+    const name = String(property.apiName)
+    const id = idByApiName.get(name)
+    if (!declaredNames.has(name) && id) plan.removes.push({ id, apiName: name })
+  }
+
+  return plan
+}
+
+async function applyPropertyPlan(
+  client: BlueprintAuthoringApi,
+  apiName: string,
+  file: AuthoredFile,
+  liveDocument: Record<string, unknown> | undefined,
+  revision: number,
+  sharedPropertyIds: Map<string, string>,
+): Promise<number> {
+  const detail = await client.getObjectTypeDetail(apiName)
+  if (!detail?.id) {
+    // Silently returning here reported the operation as applied. The plan said this
+    // type exists; if it does not, the plan is stale and saying so is the answer.
+    throw new CliError(`"${apiName}" is no longer on the draft.`, {
+      code: 'CONFLICT',
+      hint: 'frontera blueprint plan — the draft moved under this run.',
+    })
+  }
+  const backing = readBacking(file)
+  const idByApiName = new Map(
+    detail.properties
+      .filter((property) => property.apiName && property.id)
+      .map((property) => [String(property.apiName), String(property.id)]),
+  )
+  const liveProperties = Array.isArray(liveDocument?.properties)
+    ? (liveDocument.properties as Array<Record<string, unknown>>)
+    : []
+  const plan = planProperties(file, liveProperties, backing, idByApiName)
+
+  // Every add needs a column, and the service offers no name-match fallback. Checked
+  // for ALL of them before the first write, so a partial run cannot start.
+  for (const property of plan.adds) {
+    const name = String(property.apiName)
+    if (backing?.mapping?.[name] === undefined) {
+      throw new CliError(
+        `${file.path}: new property "${name}" has no column in \`backing.mapping\`.`,
+        {
+          code: 'USAGE',
+          hint: 'A property reads a column, and there is no name-match fallback. Add it to backing.mapping.',
+        },
+      )
+    }
+  }
+
+  // A property that leaves AND one that arrives in the same edit is the shape a
+  // rename takes, and it is indistinguishable from a genuine replacement — the two
+  // have opposite consequences for the data behind the field. The earlier guard only
+  // caught it when `backing.mapping` lacked the new name; update the mapping too and
+  // it silently ran remove_field + add_field, which is the data drop the refusal was
+  // supposed to prevent.
+  if (plan.adds.length > 0 && plan.removes.length > 0) {
+    throw new CliError(
+      `${file.path}: this edit removes ${plan.removes.map((entry) => entry.apiName).join(', ')} and adds `
+      + `${plan.adds.map((entry) => String(entry.apiName)).join(', ')} at once.`,
+      {
+        code: 'USAGE',
+        hint: 'If that is a rename, there is no per-property rename command — do the removal and the '
+          + 'addition in separate applies, so the data consequence is a decision rather than a side effect.',
+      },
+    )
+  }
+
+  let current = revision
+  for (const property of plan.adds) {
+    const name = String(property.apiName)
+    const mapped = backing!.mapping[name]!
+    const column = typeof mapped === 'string' ? mapped : mapped.column
+    const sourceField = typeof mapped === 'string' ? undefined : mapped.field
+    // Resolved here rather than at plan time: a shared field created earlier in
+    // this same run only entered the map when its create answered.
+    const sharedPropertyId = resolveSharedProperty(
+      file, name, property.sharedField, sharedPropertyIds,
+    )
+    const result = await client.draftCommand({
+      kind: 'add_field',
+      objectId: detail.id,
+      field: {
+        // The one identifier the CLI generates, and it never reaches a file: the
+        // command addresses a field that does not exist yet, so there is nothing on
+        // the draft to resolve a name against. It lives for one request.
+        id: crypto.randomUUID(),
+        apiName: name,
+        displayName: String(property.displayName ?? name),
+        propertyType: (property.propertyType as string | undefined) ?? 'attribute',
+        valueType: String(property.valueType ?? 'string'),
+        sourceColumn: column,
+        ...(sourceField === undefined || sourceField === null ? {} : { sourceField }),
+        required: Boolean(property.required ?? false),
+        unique: Boolean(property.unique ?? false),
+        status: 'active',
+        visibility: 'normal',
+        // A field being ADDED has no reference to detach, so an authored `null`
+        // is simply "no shared field" — `add_field`'s uuid is not nullable, and a
+        // detach command on a field that is being created makes no sense anyway.
+        ...(typeof sharedPropertyId === 'string' ? { sharedPropertyId } : {}),
+      },
+    }, current)
+    current = result.revision
+  }
+  for (const change of plan.schemaChanges) {
+    const result = await client.draftCommand({
+      kind: 'update_field_schema', objectId: detail.id, fieldId: change.id, patch: change.patch,
+    }, current)
+    current = result.revision
+  }
+  for (const change of plan.metadataChanges) {
+    // `sharedField` is the file's name for it and `sharedPropertyId` the wire's.
+    // `null` survives the resolution and travels as `null`: that is the detach
+    // signal on both sides, and dropping it left this patch empty.
+    const { sharedField, ...patch } = change.patch
+    const sharedPropertyId = resolveSharedProperty(
+      file, change.apiName, sharedField, sharedPropertyIds,
+    )
+    const result = await client.draftCommand({
+      kind: 'update_field_metadata',
+      objectId: detail.id,
+      fieldId: change.id,
+      patch: {
+        ...patch,
+        ...(sharedPropertyId === undefined ? {} : { sharedPropertyId }),
+      },
+    }, current)
+    current = result.revision
+  }
+  for (const removal of plan.removes) {
+    const result = await client.draftCommand({
+      kind: 'remove_field', objectId: detail.id, fieldId: removal.id,
+    }, current)
+    current = result.revision
+  }
+  return current
+}
+
+async function pruneOperation(
+  client: BlueprintAuthoringApi,
+  operation: ModelOperation,
+  revision: number,
+): Promise<number> {
+  if (operation.kind === 'object-type') {
+    const objectType = await client.getObjectType(operation.apiName)
+    if (!objectType?.id) return revision
+    // Structural: preview, then apply the exact preview. Migration blockers the
+    // preview reports abort the run with them printed — never bypassed.
+    const removed = await client.removeObject(objectType.id, revision)
+    return removed.revision
+  }
+  // Deleting a shared field DEGRADES its implementers rather than being refused:
+  // each keeps the description and format it was inheriting. Deleting a label must
+  // not delete the mappings underneath it.
+  const result = operation.kind === 'link-type'
+    ? await client.deleteLinkType(operation.apiName, revision)
+    : operation.kind === 'shared-field'
+      ? await client.deleteSharedProperty(operation.apiName, revision)
+      : await client.deleteMetric(operation.apiName, revision)
+  return nextRevision(result, revision)
+}
+
+export const blueprintApply: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'apply',
+    args: [],
+    flags: { dir: 'string', prune: 'boolean', yes: 'boolean' },
+    aliases: { y: 'yes' },
+    summary: 'Reconcile the shared draft with the file tree',
+    examples: [
+      'frontera blueprint apply --yes',
+      'frontera blueprint apply --prune --yes',
+    ],
+  },
+  async run(ctx) {
+    const client = api(ctx)
+    const prune = ctx.flags.prune === true
+    const { plan, files, definition, drift } = await computePlan(ctx)
+
+    if (isEmpty(plan)) {
+      return { data: { ...plan, applied: [] }, text: renderPlan(plan) }
+    }
+
+    // Drift is REPORTED, and blocks only the artifacts it is about. It used to throw
+    // before the plan was even shown, so a colleague's type reading a moved dataset
+    // refused an unrelated creation and hid what the run would have done. A rebind is
+    // `bind`'s act either way — the plan says so on the line.
+    const driftingNames = new Set(drift.map((entry) => entry.objectApiName))
+    const blocked = plan.operations.filter((operation) =>
+      operation.kind === 'object-type' && driftingNames.has(operation.apiName))
+    if (blocked.length > 0) {
+      throw new CliError(
+        `${blocked.map((operation) => operation.apiName).join(', ')} read a dataset that now publishes a `
+        + 'different column contract. Re-bind before applying those.',
+        { code: 'CONFLICT', hint: renderDrift(drift) || 'frontera blueprint plan' },
+      )
+    }
+
+    if (ctx.flags.yes !== true) {
+      throw new CliError(
+        `This would apply ${plan.operations.length} change${plan.operations.length === 1 ? '' : 's'}.\n`
+        + `${renderPlan(plan, { prune })}\n\nRe-run with --yes to apply.`,
+        { code: 'USAGE', hint: 'frontera blueprint apply --yes' },
+      )
+    }
+
+    const byKey = new Map(files.map((file) => [`${file.kind}:${file.apiName}`, file]))
+    const applied: string[] = []
+    try {
+      // Creations before updates, and object types before the kinds that reference
+      // them: a link names both of its endpoints, and a metric names the type it
+      // measures. `ARTIFACT_KINDS` fixes that order.
+      const ordered = [...plan.operations].sort(byKindThenCreateFirst)
+      // Seeded from the revision the PLAN was computed against, then advanced by what
+      // each write returns. Never re-read — see `nextRevision`.
+      let revision = plan.revision
+      // Shared field apiName → id: what the draft already had, plus what this run
+      // creates. A file references a shared field by name and the wire takes an
+      // id, and one created in this run has no id until its create answers.
+      const sharedPropertyIds = indexBundle(definition).sharedPropertyIdByApiName
+      for (const operation of ordered) {
+        const file = byKey.get(`${operation.kind}:${operation.apiName}`)!
+        revision = await applyOperation(client, operation, file, revision, sharedPropertyIds)
+        applied.push(`${operation.operation} ${operation.kind} ${operation.apiName}`)
+      }
+      if (prune) {
+        for (const operation of plan.prunes) {
+          revision = await pruneOperation(client, operation, revision)
+          applied.push(`delete ${operation.kind} ${operation.apiName}`)
+        }
+      }
+    } catch (err) {
+      // What landed is as important as what failed: the draft is shared, and a
+      // partial run that does not say where it stopped cannot be resumed safely.
+      const done = applied.length
+        ? `Applied before failing:\n${applied.map((line) => `  ${line}`).join('\n')}\n`
+        : 'Nothing was applied.\n'
+      throw new CliError(`${done}${(err as Error).message}`, {
+        code: err instanceof CliError ? err.code : 'FAILURE',
+        hint: 'frontera blueprint plan — re-plan against the current draft, then re-apply.',
+      })
+    }
+
+    const revision = await client.revision()
+    return {
+      data: { applied, revision },
+      text: `${renderPlan(plan, { prune })}\n\nApplied ${applied.length} change`
+        + `${applied.length === 1 ? '' : 's'}. Draft is at revision ${revision}.`,
+    }
+  },
+}
+
+function byKindThenCreateFirst(left: ModelOperation, right: ModelOperation): number {
+  const kindOrder = ARTIFACT_KINDS.indexOf(left.kind) - ARTIFACT_KINDS.indexOf(right.kind)
+  if (kindOrder !== 0) return kindOrder
+  const rank = (operation: ModelOperation) => (operation.operation === 'create' ? 0 : 1)
+  return rank(left) - rank(right)
+}
+
+export const blueprintNew: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'new',
+    args: [
+      { name: 'kind', required: true, description: `One of: ${ARTIFACT_KINDS.join(', ')}` },
+      { name: 'apiName', required: true, description: 'The artifact’s API name' },
+    ],
+    flags: { dir: 'string' },
+    offline: true,
+    summary: 'Scaffold an artifact file that validates as written',
+    examples: [
+      'frontera blueprint new object-type Customer',
+      'frontera blueprint new link-type customerHoldsPolicy',
+      'frontera blueprint new shared-field accountCode',
+    ],
+  },
+  async run(ctx) {
+    const kind = ctx.positional[0] as ArtifactKind
+    if (!ARTIFACT_KINDS.includes(kind)) {
+      throw new CliError(
+        `Unknown kind "${ctx.positional[0] ?? ''}". Expected one of: ${ARTIFACT_KINDS.join(', ')}.`,
+        { code: 'USAGE', hint: 'frontera blueprint new --help' },
+      )
+    }
+    const apiName = ctx.positional[1]
+    if (!apiName) {
+      throw new CliError('An apiName is required.', {
+        code: 'USAGE',
+        hint: `frontera blueprint new ${kind} <apiName>`,
+      })
+    }
+    if (!API_NAME_RULE[kind].test(apiName)) {
+      throw new CliError(`"${apiName}" is not a valid ${kind} apiName.`, {
+        code: 'USAGE',
+        hint: `${describeApiNameRule(kind)} — and it becomes the file name, so nothing else fits.`,
+      })
+    }
+    const directory = root(ctx)
+    const relative = pathFor(kind, apiName)
+    if (existsSync(resolve(directory, relative))) {
+      throw new CliError(`${relative} already exists.`, {
+        code: 'USAGE',
+        hint: 'Edit it, or choose another apiName.',
+      })
+    }
+    const file: AuthoredFile = {
+      kind,
+      apiName,
+      path: relative,
+      document: scaffold(kind, apiName),
+    }
+    writeTree(directory, [file])
+    return {
+      data: { path: relative },
+      text: `Wrote ${relative}. Edit it, then \`frontera blueprint plan\`.`,
+    }
+  },
+}
+
+export const blueprintRename: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'rename',
+    args: [
+      { name: 'kind', required: true, description: 'object-type' },
+      { name: 'from', required: true, description: 'Current apiName' },
+      { name: 'to', required: true, description: 'New apiName' },
+    ],
+    flags: { dir: 'string' },
+    summary: 'Rename an object type, and its file, as one act',
+    examples: ['frontera blueprint rename object-type Client Customer'],
+  },
+  async run(ctx) {
+    const [kind, from, to] = ctx.positional
+    if (kind === 'object-type' && to && !API_NAME_RULE['object-type'].test(to)) {
+      throw new CliError(`"${to}" is not a valid object-type apiName.`, {
+        code: 'USAGE',
+        hint: `${describeApiNameRule('object-type')} — and it becomes the file name.`,
+      })
+    }
+    if (kind !== 'object-type') {
+      throw new CliError('Only object types can be renamed in place.', {
+        code: 'USAGE',
+        // Being specific about the alternative rather than just refusing: for the
+        // other kinds a delete-and-create is genuinely equivalent, because nothing
+        // hangs off their identity the way data hangs off an object type's.
+        hint: 'For a link type, metric or action, rename the file and apply with --prune. '
+          + 'A shared field renamed that way is DELETED and recreated, which detaches every '
+          + 'field implementing it — rename it in the Console instead.',
+      })
+    }
+    if (!from || !to) {
+      throw new CliError('Both the current and the new apiName are required.', {
+        code: 'USAGE',
+        hint: 'frontera blueprint rename object-type <from> <to>',
+      })
+    }
+    const client = api(ctx)
+    const objectType = await client.getObjectType(from)
+    if (!objectType?.id) {
+      throw new CliError(`No object type "${from}" on the draft.`, {
+        code: 'NOT_FOUND',
+        hint: 'frontera blueprint catalog',
+      })
+    }
+    await client.draftCommand(
+      { kind: 'rename_object_api', objectId: objectType.id, apiName: to },
+      await client.revision(),
+    )
+
+    // The file moves with it. Leaving the tree behind would make the next `plan`
+    // report a create plus a prune — the exact pair this command exists to avoid.
+    const directory = root(ctx)
+    const files = existsSync(directory) ? readTree(directory) : []
+    const existing = files.find((file) => file.kind === 'object-type' && file.apiName === from)
+    if (existing) {
+      writeTree(directory, [{
+        kind: 'object-type',
+        apiName: to,
+        path: pathFor('object-type', to),
+        document: { ...existing.document, apiName: to },
+      }])
+      // The old file is DELETED, not left for the reader to tidy. Leaving it produced
+      // exactly the create-plus-prune pair this command exists to avoid, which made
+      // the instruction to delete it a step you had to obey for the rename to hold.
+      removeFromTree(directory, [existing.path])
+    }
+    return {
+      data: { from, to, movedFile: Boolean(existing) },
+      text: `Renamed object type "${from}" to "${to}".`
+        + (existing ? ` Moved ${existing.path} to ${pathFor('object-type', to)}.` : ''),
+    }
+  },
+}
+
+export const blueprintDeclarativeCommands: Command[] = [
+  blueprintPull,
+  blueprintPlan,
+  blueprintApply,
+  blueprintNew,
+  blueprintRename,
+]