@frontera-sdk/cli 1.53.5 → 1.53.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.53.5",
+  "version": "1.53.7",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.53.5",
-    "@frontera-sdk/functions": "1.53.5",
+    "@frontera-sdk/core": "1.53.7",
+    "@frontera-sdk/functions": "1.53.7",
     "ai": "^6.0.116",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.53.5",
+    "@frontera-sdk/forge-contracts": "1.53.7",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/apps-api.ts

@@ -159,8 +159,8 @@ export class AppsApi {
    * `pull` used `ensureApp`, so a typo or a slug the platform had since
    * renamed produced a brand new empty app instead of an error.
    */
-  resolveApp(slugOrId: string): Promise<{ id: string; slug: string; displayName: string }> {
-    return this.client.request<{ id: string; slug: string; displayName: string }>(
+  resolveApp(slugOrId: string): Promise<{ id: string; slug: string; displayName: string; kind?: 'code' | 'chat' }> {
+    return this.client.request<{ id: string; slug: string; displayName: string; kind?: 'code' | 'chat' }>(
       `/v1/platform-apps/resolve/${encodeURIComponent(slugOrId)}`,
     )
   }

package/src/api/blueprint-authoring-api.ts

@@ -3,6 +3,8 @@ import { organizationHeaders } from '../organization'
 import { credentialFailure } from './credential-failure'
 import { formatValidationDetails } from './validation-detail'
 import type { DefinitionBundle } from '../blueprint/model'
+import type { ValidationReport } from '../blueprint/publish-plan'
+import { withBlockers } from '../exit'
 
 /** A row of `GET /v1/blueprint/markings`. */
 export interface MarkingRow {
@@ -75,10 +77,14 @@ export class BlueprintAuthoringApi {
       })
       if (credential) throw credential
       if (res.status === 409) {
+        // The blockers ride in `details`: printed under the message, and kept whole for `--json`.
         throw new CliError(
-          payload?.message
-            ?? 'The shared draft moved since this change was computed. Re-run to pick up the current revision.',
-          { code: 'CONFLICT', hint: 'frontera blueprint status' },
+          withBlockers(
+            payload?.message
+              ?? 'The shared draft moved since this change was computed. Re-run to pick up the current revision.',
+            payload?.details,
+          ),
+          { code: 'CONFLICT', hint: 'frontera blueprint status', ...(payload?.details !== undefined ? { details: payload.details } : {}) },
         )
       }
       if (res.status === 404) {
@@ -351,42 +357,36 @@ export class BlueprintAuthoringApi {
 
   // ── release lifecycle ─────────────────────────────────────────────────────
 
-  validate(): Promise<{
-    id?: string
+  validate(): Promise<ValidationReport & {
     reportId?: string
-    draftRevision?: number
     draftDigest?: string
     baseReleaseDigest?: string
     catalogProjection?: { objectTypes?: unknown[]; linkTypes?: unknown[] }
-    evolution?: { changes?: unknown[] }
   }> {
     return this.call('/v1/blueprint/lifecycle/validate', { method: 'POST', body: {} })
   }
 
+  /**
+   * One POST, with every instruction already in it. Publish never asks the service
+   * which changes need one: each refused publish is kept as a failed attempt, so the
+   * change ids come from the validation report (`publish-plan.ts`).
+   */
   publish(input: {
     expectedRevision: number
     validationReportId: string
     releaseLabel: string
     releaseNotes: string
-    instruction?: string
-  }) {
-    const { instruction, ...body } = input
-    // Publish REQUIRES the field even when empty; rollback treats it as optional.
-    // Dropping the default here failed typebox before authorization ever ran.
-    return this.postWithMigrations(
-      '/v1/blueprint/lifecycle/publish',
-      { migrationInstructions: [], ...body },
-      instruction,
-    )
+    migrationInstructions: Array<{ changeId: string; instruction: string }>
+  }): Promise<unknown> {
+    return this.call('/v1/blueprint/lifecycle/publish', { method: 'POST', body: input })
   }
 
   /**
-   * POST a release operation, negotiating migration instructions once.
+   * POST a rollback, negotiating migration instructions once.
    *
    * A release that discards changes is refused until each discarded change carries an
    * explanation, and the service names the change ids it wants. Rather than make the
    * caller guess them, this asks, then retries with one instruction per named change.
-   * Shared by publish and rollback because the refusal is identical for both.
    */
   private async postWithMigrations(
     path: string,

package/src/api/governed-action-api.ts

@@ -74,6 +74,31 @@ export interface DeployableActionEntry {
   warnings?: Array<{ code: string; path?: string; message: string }>
 }
 
+/** An Action's current deployment, as `GET …/admin/deployments?actionDefinitionId=` answers it. */
+export interface CurrentDeployment {
+  stateId: string
+  state: string
+  generation: number
+  bindingId: string
+  bindingRevisionId: string | null
+  /** The contract the deployment was decided for; a later edit of the Action does not move it. */
+  actionContractDigest: string
+}
+
+/** The write path calling another system an Action runs, drains or last ran; `planKind` is null when the service cannot read it. */
+export interface ExternalWritePath {
+  stateId: string
+  state: string
+  planKind: string | null
+  /** The organization it was read in, which a person's calls then name. */
+  organizationId?: string
+  /**
+   * Asked with one of the Action's Binding revisions: why the caller's review
+   * would not turn that one on in this one's place, or null when it would.
+   */
+  reviewRefusal?: 'key_built' | 'reviewer_built' | null
+}
+
 export interface ActionDiscovery {
   actionDefinitionId: string
   apiName: string
@@ -414,7 +439,7 @@ export class GovernedActionApi {
     actionDefinitionId: string
     actionContractDigest: string
     mutationPlanRevisionId: string
-  }): Promise<{ id: string; stateId: string }> {
+  }): Promise<{ id: string; stateId: string; organizationId?: string }> {
     return this.call(`/v1/blueprint/governed-actions/admin/bindings/${bindingId}/revisions`, {
       method: 'POST',
       body: { expectedRevision: 0, parentRevisionId: null, ...input },
@@ -453,6 +478,7 @@ export class GovernedActionApi {
     id: string
     bindingId: string
     actionDefinitionId: string
+    mutationPlanRevisionId: string
     stateId: string
     state: string
     stateGeneration: number
@@ -486,14 +512,63 @@ export class GovernedActionApi {
     return (published?.definition as { id?: string } | undefined)?.id ?? null
   }
 
+  /**
+   * The write path calling another system that the Action runs, drains or last
+   * ran, or null. While there is one, the service turns a new one on only
+   * after a second person reviews it, and never one an API key built. An
+   * older platform has no such route and no such rule, so it answers null.
+   */
+  async externalWritePath(actionDefinitionId: string, bindingRevisionId?: string): Promise<ExternalWritePath | null> {
+    const revision = bindingRevisionId ? `&bindingRevisionId=${encodeURIComponent(bindingRevisionId)}` : ''
+    try {
+      return await this.call(`/v1/blueprint/governed-actions/admin/deployments/external-write-path?actionDefinitionId=${encodeURIComponent(actionDefinitionId)}${revision}`)
+    } catch (err) {
+      if (err instanceof CliError && err.code === 'NOT_FOUND') return null
+      throw err
+    }
+  }
+
   /** The Action's current deployment decision, or null when it has none. */
-  async currentDeployment(actionDefinitionId: string): Promise<{ stateId: string; state: string; generation: number; bindingRevisionId: string | null } | null> {
-    const page = await this.call<{ entries?: Array<{ stateId: string; state: string; generation: number; bindingRevisionId: string | null }> }>(
+  async currentDeployment(actionDefinitionId: string): Promise<CurrentDeployment | null> {
+    const page = await this.call<{ entries?: CurrentDeployment[] }>(
       `/v1/blueprint/governed-actions/admin/deployments?actionDefinitionId=${encodeURIComponent(actionDefinitionId)}`,
     )
     return page?.entries?.[0] ?? null
   }
 
+  /**
+   * Switch the Action's current deployment off: the service records a NEW
+   * disabled deployment under the fresh `stateId` and `bindingId`, and the one
+   * it replaces stops being current (a running one drains).
+   */
+  disableDeployment(stateId: string, input: {
+    bindingId: string
+    actionDefinitionId: string
+    actionContractDigest: string
+    expectedCurrentStateId: string | null
+    expectedCurrentGeneration: number | null
+    reason: string
+  }): Promise<{ stateId: string; state: string; generation: number }> {
+    return this.call(`/v1/blueprint/governed-actions/admin/deployments/${encodeURIComponent(stateId)}/disable`, {
+      method: 'POST',
+      body: input,
+    })
+  }
+
+  /**
+   * The Action's draining deployments. None is current, so the deployment list
+   * omits them, while publish still refuses a changed Action until each is
+   * retired. Read per binding, from the state of its newest revision.
+   */
+  async drainingDeployments(actionDefinitionId: string): Promise<Array<{ stateId: string; generation: number }>> {
+    // ponytail: the first page of bindings only (50, in id order), so an Action deployed more than 50 times may hide one; page the list, or let the service filter by state, when that happens.
+    const { entries } = await this.listBindings(actionDefinitionId)
+    const states = await Promise.all(entries.map((entry) => this.getBindingRevision(entry.revisionId)))
+    return states
+      .filter((revision) => revision.state === 'draining' && revision.actionDefinitionId === actionDefinitionId)
+      .map((revision) => ({ stateId: revision.stateId, generation: revision.stateGeneration }))
+  }
+
   /** Stand a deployment decision down: one that was never bound, or a draining one (the service refuses the rest). */
   retireDeployment(stateId: string, expectedGeneration: number, reason: string): Promise<{ stateId?: string; state?: string; generation?: number }> {
     return this.call(`/v1/blueprint/governed-actions/admin/deployments/${encodeURIComponent(stateId)}/retire`, {

package/src/api/platform-api.ts

@@ -4,6 +4,7 @@ import type { MetricQueryBody, MetricQueryResult } from '../blueprint/metric-que
 import { organizationHeaders, selectedOrganization } from '../organization'
 
 import { CliError } from '../errors'
+import type { SavedServer } from '../local/local-mcp-servers'
 import { BLUEPRINT_SCHEMA_CAPABILITIES } from '../blueprint-types'
 
 /**
@@ -291,6 +292,11 @@ export class PlatformApi {
     return this.get<{ server: unknown }>(`/v1/mcp-servers/${encodeURIComponent(slug)}`)
   }
 
+  /** Created, or replaced in place: `created` says which. */
+  saveMcpServer(slug: string, definition: Record<string, unknown>): Promise<SavedServer> {
+    return this.client.request<SavedServer>(`/v1/mcp-servers/${encodeURIComponent(slug)}`, { method: 'PUT', body: definition })
+  }
+
   /** Archived, not deleted: the Function runs its tools started still name it. */
   archiveMcpServer(slug: string): Promise<{ slug: string; archived: boolean }> {
     return this.client.request<{ slug: string; archived: boolean }>(`/v1/mcp-servers/${encodeURIComponent(slug)}`, { method: 'DELETE' })
@@ -721,6 +727,20 @@ export class PlatformApi {
 
   // ── Knowledge ─────────────────────────────────────────────────────────────
 
+  /**
+   * Whether the platform runs the Knowledge app. Its routes answer 404 before any sign-in check where it does not, so
+   * any other answer, a refusal of this key included, means it runs. No answer counts as not running.
+   */
+  async knowledgeAppRuns(): Promise<boolean> {
+    try {
+      await this.get<unknown>('/v1/knowledge-app/me')
+      return true
+    } catch (err) {
+      const status = (err as { status?: number }).status
+      return status !== undefined && status !== 404
+    }
+  }
+
   knowledgeBases(workspaceId: string) {
     return this.getList<unknown>(`/v1/workspace-knowledge?workspaceId=${encodeURIComponent(workspaceId)}`)
   }

package/src/blueprint/dataset-revision.ts

@@ -1,3 +1,5 @@
+import { CliError } from '../errors'
+
 /**
  * Which revision of a dataset is CURRENT.
  *
@@ -31,3 +33,67 @@ export function pickCurrentRevision<T extends { id?: string }>(
   }
   return revisions[0]
 }
+
+/** A file's `backing.mapping` entry: a column, or a struct field within one. */
+export type MappingEntry = string | { column: string; field?: string | null }
+
+export interface ColumnMapping {
+  propertyId: string
+  column: string
+  field?: string
+}
+
+/**
+ * Every property that reads a column, paired with the column the mapping names.
+ * Shared by `bind` and by `apply`'s rebind, which send the same draft command.
+ */
+export function columnMappingsFrom(
+  properties: ReadonlyArray<{ id?: string; apiName?: string; calculation?: unknown }>,
+  mapping: Readonly<Record<string, MappingEntry | null | undefined>>,
+): { columnMappings: ColumnMapping[]; unmapped: string[] } {
+  const columnMappings: ColumnMapping[] = []
+  const unmapped: 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.calculation) continue
+    const entry = mapping[name]
+    if (entry === undefined || entry === null) {
+      unmapped.push(name)
+      continue
+    }
+    // Read in the same call as the names, so a property without an id means the draft moved mid-command.
+    if (!property.id) {
+      throw new CliError(`Property "${name}" is no longer on the draft.`, {
+        code: 'CONFLICT',
+        hint: 'Re-run the command against the current draft.',
+      })
+    }
+    const resolved = typeof entry === 'string' ? { column: entry } : entry
+    columnMappings.push({
+      propertyId: property.id,
+      column: resolved.column,
+      ...(resolved.field === undefined || resolved.field === null ? {} : { field: resolved.field }),
+    })
+  }
+  return { columnMappings, unmapped }
+}
+
+/** The `update_source_binding` draft command that pins a type to a Dataset revision. */
+export function datasetBindingCommand(
+  objectId: string,
+  datasetRevisionId: string,
+  columnMappings: ColumnMapping[],
+  acceptContractChange: boolean,
+): Record<string, unknown> {
+  return {
+    kind: 'update_source_binding',
+    objectId,
+    binding: {
+      kind: 'dataset',
+      datasetRevisionId,
+      columnMappings,
+      ...(acceptContractChange ? { acceptContractChange: true } : {}),
+    },
+  }
+}

package/src/blueprint/diff.ts

@@ -1,4 +1,5 @@
 import { actionWithoutMintedIds } from './compile'
+import { columnMappingsFrom, type ColumnMapping, type MappingEntry } from './dataset-revision'
 import { toFiles, withoutImpliedTiming } from './projection'
 import {
   ARTIFACT_KINDS,
@@ -61,11 +62,132 @@ export interface Plan {
    */
   withheld?: ModelOperation[]
   drift: BindingDrift[]
+  /** Object types whose `backing.editable` differs from the draft's editable set. */
+  editable: EditableChange[]
+  /** Object types whose `backing.dataset` names another Dataset than the draft reads. */
+  rebind: RebindChange[]
   unchanged: number
 }
 
+/**
+ * One object type moving to the Dataset its file names.
+ *
+ * Its own list for the reason `EditableChange` is: it travels its own draft command
+ * (`update_source_binding`, the one `bind` sends). Either it carries that command's
+ * pin and mapping, or the reason it cannot be sent and what to run instead.
+ */
+export type RebindChange = {
+  objectApiName: string
+  objectId: string
+  /** The Dataset the draft reads; null for a type with no Dataset yet. */
+  from: string | null
+  to: string
+} & (
+  | { datasetRevisionId: string; columnMappings: ColumnMapping[] }
+  | { refused: string; next: string }
+)
+
+/** What the Datasets say, read once per plan. */
+export interface DatasetIndex {
+  nameByRevisionId: Map<string, string>
+  /** Dataset name → its current revision; `columns` absent when the revision list did not carry them. */
+  current: Map<string, { id: string; schemaDigest?: string; columns?: string[] }>
+}
+
+/**
+ * The object types whose file names a Dataset the draft does not read.
+ *
+ * Each property keeps the column it reads: the file's `backing.mapping` first, then
+ * the draft's current mapping. A mapped column the new revision does not publish is
+ * refused here, before any write; a column whose type moved is the service's refusal.
+ * A pin whose Dataset this credential cannot name is left alone, never guessed.
+ */
+export function rebindChanges(files: AuthoredFile[], live: DefinitionBundle, datasets: DatasetIndex): RebindChange[] {
+  const changes: RebindChange[] = []
+  for (const file of files) {
+    if (file.kind !== 'object-type') continue
+    const backing = file.document.backing as { dataset?: unknown; mapping?: Record<string, MappingEntry | null> } | undefined
+    const to = backing?.dataset
+    if (typeof to !== 'string' || !to) continue
+    const object = live.objects.find((candidate) => candidate.apiName === file.apiName)
+    if (!object) continue
+    const pin = object.governance.sourceMappings[0] as
+      | { datasetRevisionId?: string; propertyMappings?: Array<{ propertyId: string; sourcePath: string; sourceField?: string | null }> }
+      | undefined
+    const from = pin?.datasetRevisionId ? datasets.nameByRevisionId.get(pin.datasetRevisionId) : null
+    if (from === undefined || from === to) continue
+
+    const base = { objectApiName: file.apiName, objectId: object.id, from, to }
+    const next = `frontera blueprint bind ${file.apiName} --dataset ${to} --plan ./map.json`
+    const target = datasets.current.get(to)
+    if (!target) {
+      changes.push({ ...base, refused: `no Dataset named "${to}" is visible`, next: 'frontera dataset list' })
+      continue
+    }
+    const kept: Record<string, MappingEntry> = {}
+    for (const entry of pin?.propertyMappings ?? []) {
+      const name = object.properties.find((property) => property.id === entry.propertyId)?.apiName
+      if (name) kept[name] = entry.sourceField ? { column: entry.sourcePath, field: entry.sourceField } : entry.sourcePath
+    }
+    const { columnMappings, unmapped } = columnMappingsFrom(object.properties, { ...kept, ...backing?.mapping })
+    if (unmapped.length) {
+      changes.push({ ...base, refused: `no column mapped for ${unmapped.join(', ')}`, next })
+      continue
+    }
+    const published = target.columns ? new Set(target.columns) : null
+    const missing = published ? columnMappings.filter((mapping) => !published.has(mapping.column)) : []
+    if (missing.length) {
+      const nameOf = (id: string) => object.properties.find((property) => property.id === id)?.apiName ?? id
+      changes.push({
+        ...base,
+        refused: `"${to}" does not publish ${missing.map((mapping) => `${mapping.column} (read by ${nameOf(mapping.propertyId)})`).join(', ')}`,
+        next,
+      })
+      continue
+    }
+    changes.push({ ...base, datasetRevisionId: target.id, columnMappings })
+  }
+  return changes
+}
+
+/**
+ * One object type's editable set, as its file declares it and as the draft has it.
+ *
+ * Its own list rather than an object-type update, because it travels its own draft
+ * command (`set_editable_properties`), not the object-type patch, and because a type
+ * created in this run has an editable set only after its create answers.
+ */
+export interface EditableChange {
+  objectApiName: string
+  /** API names, sorted. Empty for a type the draft does not have yet. */
+  from: string[]
+  to: string[]
+}
+
 export function isEmpty(plan: Plan): boolean {
-  return plan.operations.length === 0 && plan.prunes.length === 0
+  return plan.operations.length === 0 && plan.prunes.length === 0 && plan.editable.length === 0 && plan.rebind.length === 0
+}
+
+/**
+ * The editable sets the files declare that the draft does not have.
+ *
+ * Only a file that states `backing.editable` has an opinion, as for every other
+ * field: one that leaves the key out keeps whatever the draft holds, and
+ * `editable: []` asks for none.
+ */
+export function editableChanges(files: AuthoredFile[], live: DefinitionBundle): EditableChange[] {
+  const changes: EditableChange[] = []
+  for (const file of files) {
+    if (file.kind !== 'object-type') continue
+    const declared = (file.document.backing as { editable?: unknown } | undefined)?.editable
+    if (!Array.isArray(declared)) continue
+    const to = [...new Set(declared.map(String))].sort()
+    const object = live.objects.find((candidate) => candidate.apiName === file.apiName)
+    const ids = (object?.governance.sourceMappings[0] as { editableProperties?: string[] } | undefined)?.editableProperties ?? []
+    const from = ids.flatMap((id) => object?.properties.find((property) => property.id === id)?.apiName ?? []).sort()
+    if (from.join('\n') !== to.join('\n')) changes.push({ objectApiName: file.apiName, from, to })
+  }
+  return changes
 }
 
 /**
@@ -91,9 +213,9 @@ export function isEmpty(plan: Plan): boolean {
  * field the plan never called changed.
  */
 export function satisfies(local: unknown, live: unknown, key?: string): boolean {
-  // `backing` is owned by `bind`, which travels the probe and the contract-change
-  // gate. Letting it into the plan would mean `apply` silently rebinding a type
-  // because somebody edited a column name in a file.
+  // `backing` is compared on its own: `editableChanges` and `rebindChanges` plan
+  // the editable set and a new Dataset. A column edited in place stays `bind`'s,
+  // so `apply` never repoints a property because a mapping line changed.
   if (key === 'backing') return true
 
   if (Array.isArray(local)) {
@@ -227,6 +349,8 @@ export function diff(
   localFiles: AuthoredFile[],
   live: DefinitionBundle,
   revision: number,
+  /** Absent when the Datasets were not read: no rebind is planned. */
+  datasets?: DatasetIndex,
 ): Plan {
   const liveModel = toFiles(live)
   const liveByKey = new Map(liveModel.files.map((file) => [`${file.kind}:${file.apiName}`, file]))
@@ -234,6 +358,10 @@ export function diff(
 
   const operations: ModelOperation[] = []
   const prunes: ModelOperation[] = []
+  const editable = editableChanges(localFiles, live)
+  const rebind = datasets ? rebindChanges(localFiles, live, datasets) : []
+  // A type whose only difference is its editable set or its Dataset is listed there, not as unchanged.
+  const editableNames = new Set([...editable, ...rebind].map((change) => change.objectApiName))
   let unchanged = 0
 
   // Fixed kind order so the plan reads the same way every run, and so creations of
@@ -255,7 +383,7 @@ export function diff(
         continue
       }
       if (matches(kind, file.document, existing.document)) {
-        unchanged += 1
+        if (kind !== 'object-type' || !editableNames.has(file.apiName)) unchanged += 1
         continue
       }
       operations.push({
@@ -278,7 +406,7 @@ export function diff(
     }
   }
 
-  return { revision, operations, prunes, drift: driftOf(live), unchanged }
+  return { revision, operations, prunes, drift: driftOf(live), editable, rebind, unchanged }
 }
 
 /**