@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/commands/blueprint/bind.ts

@@ -0,0 +1,228 @@
+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 { readTree, writeTree } from '../../blueprint/tree'
+import { CliError } from '../../errors'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * Bind an object type to a Dataset revision.
+ *
+ * Two things about the route this uses are worth stating, because both were chosen
+ * against a plausible alternative:
+ *
+ *   It is the `update_source_binding` DRAFT COMMAND, not
+ *   `POST /object-types/:apiName/dataset-binding`. That route writes the ACTIVE
+ *   catalog; the draft is a separate document, and authoring is draft-side end to
+ *   end. Binding through the active route inside an authoring session would bind a
+ *   different thing to everything around it.
+ *
+ *   The mapping is reviewed, never guessed. The service refuses a property left
+ *   unmapped rather than matching on name (ADR 0008), so `--plan` writes a skeleton
+ *   with every live property in it and name matches pre-filled as SUGGESTIONS. The
+ *   guess happens where a person can see and edit it.
+ */
+
+function api(ctx: CommandContext): BlueprintAuthoringApi {
+  return new BlueprintAuthoringApi(ctx.apiUrl, ctx.token)
+}
+
+interface MappingFile {
+  dataset: string
+  mapping: Record<string, string | { column: string; field?: string | null } | null>
+}
+
+async function datasetRevision(client: BlueprintAuthoringApi, name: string) {
+  const datasets = await client.listDatasets()
+  const dataset = datasets.find((candidate) => candidate.name === name)
+  if (!dataset?.id) {
+    throw new CliError(`No dataset named "${name}" in this organization.`, {
+      code: 'NOT_FOUND',
+      hint: datasets.length === 0
+        // An empty list and a refusal look identical to a caller. Naming the
+        // capability is the difference between a five-minute fix and an afternoon.
+        ? 'No datasets are visible at all — the key may have been minted without dataset:read.'
+        : `Visible datasets: ${datasets.map((entry) => entry.name).filter(Boolean).join(', ')}`,
+    })
+  }
+  const revisions = await client.datasetRevisions(dataset.id)
+  // The revision the DATASET calls current, not the highest-numbered one. After a
+  // rollback those are different revisions, and pinning by sort bound the type to a
+  // contract the organization had already stepped off.
+  const current = pickCurrentRevision(dataset, revisions)
+  if (!current?.id) {
+    throw new CliError(`Dataset "${name}" has no published revision.`, {
+      code: 'FAILURE',
+      hint: 'Publish a revision of the dataset, then bind.',
+    })
+  }
+  return current
+}
+
+export const blueprintBind: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'bind',
+    args: [{ name: 'objectType', required: true, description: 'The object type’s API name' }],
+    flags: {
+      dir: 'string',
+      dataset: 'string',
+      plan: 'string',
+      file: 'string',
+      'accept-contract-change': 'boolean',
+    },
+    aliases: { f: 'file' },
+    summary: 'Bind an object type to a Dataset revision, through a reviewed mapping',
+    examples: [
+      'frontera blueprint bind Customer --dataset customers --plan ./map.json',
+      'frontera blueprint bind Customer --dataset customers --file ./map.json',
+    ],
+  },
+  async run(ctx) {
+    const apiName = ctx.positional[0]
+    if (!apiName) {
+      throw new CliError('An object type apiName is required.', {
+        code: 'USAGE',
+        hint: 'frontera blueprint bind <objectType> --dataset <name> --plan <file>',
+      })
+    }
+    const datasetName = ctx.flags.dataset as string | undefined
+    if (!datasetName) {
+      throw new CliError('A dataset is required: pass --dataset <name>.', {
+        code: 'USAGE',
+        hint: 'frontera blueprint bind Customer --dataset customers --plan ./mapping.yaml',
+      })
+    }
+
+    const client = api(ctx)
+    const detail = await client.getObjectTypeDetail(apiName)
+    if (!detail?.id) {
+      throw new CliError(`No object type "${apiName}" on the draft.`, {
+        code: 'NOT_FOUND',
+        hint: 'frontera blueprint catalog',
+      })
+    }
+    const properties = detail.properties
+    const revision = await datasetRevision(client, datasetName)
+
+    const planPath = ctx.flags.plan as string | undefined
+    if (planPath) {
+      const columns = (revision.columns ?? []).map((column) => column.name).filter(Boolean)
+      const suggestions: MappingFile['mapping'] = {}
+      for (const property of properties) {
+        const name = property.apiName
+        if (!name) continue
+        // A suggestion, and marked as one by being editable rather than applied: an
+        // exact name match is the only guess offered, and `null` says plainly that
+        // the tool has nothing to suggest rather than inventing something.
+        suggestions[name] = columns.includes(name) ? name : null
+      }
+      const body: MappingFile = { dataset: datasetName, mapping: suggestions }
+      const target = resolve(ctx.cwd, planPath)
+      writeFileSync(target, `${JSON.stringify(body, null, 2)}\n`)
+      const unmapped = Object.values(suggestions).filter((value) => value === null).length
+      return {
+        data: { path: target, unmapped, columns },
+        text: `Wrote a mapping skeleton to ${target}.\n`
+          + `${properties.length} propert${properties.length === 1 ? 'y' : 'ies'}, `
+          + `${unmapped} still to map. Available columns: ${columns.join(', ')}`,
+      }
+    }
+
+    const filePath = ctx.flags.file as string | undefined
+    if (!filePath) {
+      throw new CliError('A mapping is required: pass --plan <file> to draft one, then --file <file>.', {
+        code: 'USAGE',
+        hint: `frontera blueprint bind ${apiName} --dataset ${datasetName} --plan ./map.json`,
+      })
+    }
+    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
+      if (!name) 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 }),
+      })
+    }
+    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
+      // first one the server happens to reach.
+      throw new CliError(
+        `${missing.length} propert${missing.length === 1 ? 'y is' : 'ies are'} unmapped: ${missing.join(', ')}.`,
+        {
+          code: 'USAGE',
+          hint: 'Every property names the column it reads. There is no name-match fallback.',
+        },
+      )
+    }
+
+    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())
+
+    // 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`.
+    const treeRoot = resolve(ctx.cwd, (ctx.flags.dir as string) ?? 'blueprint')
+    let treeUpdated = false
+    if (existsSync(join(treeRoot, 'object-types'))) {
+      const file = readTree(treeRoot).find(
+        (candidate) => candidate.kind === 'object-type' && candidate.apiName === apiName,
+      )
+      if (file) {
+        const written: Record<string, unknown> = {}
+        for (const entry of columnMappings) {
+          const name = properties.find((property) => property.id === entry.propertyId)?.apiName
+          if (!name) continue
+          written[name] = entry.field === undefined || entry.field === null
+            ? entry.column
+            : { column: entry.column, field: entry.field }
+        }
+        writeTree(treeRoot, [{
+          ...file,
+          document: { ...file.document, backing: { dataset: datasetName, mapping: written } },
+        }])
+        treeUpdated = true
+      }
+    }
+
+    return {
+      data: { ...result, treeUpdated },
+      text: `Bound "${apiName}" to dataset "${datasetName}" `
+        + `(revision ${revision.revision ?? revision.id}), ${columnMappings.length} properties mapped.`
+        + (treeUpdated ? ` Updated ${apiName}.yaml to match.` : ''),
+    }
+  },
+}