@frontera-sdk/cli 1.43.10 → 1.44.1

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

@@ -162,13 +162,24 @@ export class BlueprintAuthoringApi {
   async getObjectTypeDetail(apiName: string): Promise<{
     id?: string
     properties: Array<{ id?: string; apiName?: string }>
+    /**
+     * Property API NAMES — the draft stores ids, and the catalog resolves them
+     * before it answers. Carried here rather than read back through a second
+     * call because `editable` has to show the current set before it can add to
+     * or remove from it.
+     */
+    editableProperties: string[]
   } | null> {
     const payload = await this.call<{
-      objectType?: { id?: string }
+      objectType?: { id?: string; editableProperties?: string[] }
       properties?: Array<{ id?: string; apiName?: string }>
     }>(`/v1/blueprint/object-types/${encodeURIComponent(apiName)}?view=draft`)
     if (!payload?.objectType?.id) return null
-    return { id: payload.objectType.id, properties: payload.properties ?? [] }
+    return {
+      id: payload.objectType.id,
+      properties: payload.properties ?? [],
+      editableProperties: payload.objectType.editableProperties ?? [],
+    }
   }
 
   /** The draft catalog — what an organization key can actually see. */

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

@@ -0,0 +1,192 @@
+import { CliError } from '../errors'
+import type { ObjectTypeShape, PublishedActionDefinition } from '../blueprint/ontology-edit-plan'
+
+/**
+ * The Action deployment plane.
+ *
+ * Separate from `BlueprintAuthoringApi` because it is a separate plane: the
+ * Blueprint draft-and-release lifecycle publishes the CONTRACT, and these
+ * routes arm the WRITE. They carry their own capability family
+ * (`actionMutationPlan`, `actionBinding`), their own revisions, and their own
+ * state machine, and a credential holding one says nothing about the other.
+ */
+
+interface Envelope<T> { error?: boolean; data?: T }
+
+export class GovernedActionApi {
+  constructor(private readonly apiUrl: string, private readonly token: string) {}
+
+  private async call<T>(path: string, init: { method?: string; body?: unknown } = {}): Promise<T> {
+    const response = await fetch(`${this.apiUrl}${path}`, {
+      method: init.method ?? 'GET',
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    })
+    const text = await response.text()
+    let payload: unknown
+    try { payload = text ? JSON.parse(text) : null } catch { payload = null }
+
+    if (!response.ok) {
+      const body = payload as { message?: string; code?: string; details?: unknown } | null
+      throw new CliError(body?.message ?? `${response.status} from ${path}`, {
+        code: body?.code ?? 'FAILURE',
+        ...(body?.details ? { hint: JSON.stringify(body.details) } : {}),
+      })
+    }
+    const envelope = payload as Envelope<T>
+    return (envelope && envelope.error === false && 'data' in envelope
+      ? envelope.data
+      : payload) as T
+  }
+
+  /** The published Action: its definition and the digest a Binding pins. */
+  publishedAction(apiName: string): Promise<{
+    definition: PublishedActionDefinition
+    contractDigest: string
+    availability?: string
+    deploymentStatus?: string
+    reason?: string
+  }> {
+    return this.call(`/v1/blueprint/actions/${encodeURIComponent(apiName)}`)
+  }
+
+  listPublishedActions(): Promise<Array<{
+    definition: { apiName: string; displayName?: string }
+    deploymentStatus?: string
+    availability?: string
+    reason?: string
+  }>> {
+    return this.call('/v1/blueprint/actions')
+  }
+
+  /**
+   * The ACTIVE view, never the draft: a deployment is checked against the
+   * release the write path will actually read, and a draft-only property would
+   * validate here and fail at dispatch.
+   */
+  async activeObjectType(apiName: string): Promise<ObjectTypeShape | null> {
+    const payload = await this.call<{
+      objectType?: { id?: string; apiName?: string; primaryKeyPropertyId?: string | null }
+      properties?: Array<{ id?: string; apiName?: string }>
+    }>(`/v1/blueprint/object-types/${encodeURIComponent(apiName)}`)
+    if (!payload?.objectType?.id) return null
+    return {
+      id: payload.objectType.id,
+      apiName: payload.objectType.apiName ?? apiName,
+      primaryKeyPropertyId: payload.objectType.primaryKeyPropertyId ?? null,
+      properties: payload.properties ?? [],
+    }
+  }
+
+  /**
+   * The first deployment decision, taken against the DRAFT — the only place an
+   * Action lives before it has ever published.
+   */
+  recordDeploymentDecision(actionApiName: string, reason: string): Promise<{
+    stateId: string
+    bindingId: string
+    actionDefinitionId: string
+    actionContractDigest: string
+    state: string
+    generation: number
+  }> {
+    return this.call('/v1/blueprint/governed-actions/admin/deployments', {
+      method: 'POST',
+      body: { actionApiName, reason },
+    })
+  }
+
+  /**
+   * One Action's invoke capability on one role. Not role editing: the service
+   * refuses a platform resource, and refuses a capability no published Action
+   * declares.
+   */
+  setCapabilityGrant(capability: string, role: string, revoke: boolean): Promise<{
+    role: string
+    capability: string
+    actions: string[]
+    granted: boolean
+    roleMaySubmit: boolean
+  }> {
+    return this.call('/v1/blueprint/governed-actions/admin/capability-grants', {
+      method: 'POST',
+      body: { capability, role, revoke },
+    })
+  }
+
+  /** The active catalog, for turning the subject's id into the name routes take. */
+  listActiveObjectTypes(): Promise<Array<{ id?: string; apiName?: string }>> {
+    return this.call('/v1/blueprint/object-types')
+  }
+
+  createMutationPlanRevision(planId: string, plan: unknown): Promise<{ id: string }> {
+    return this.call(`/v1/blueprint/governed-actions/admin/mutation-plans/${planId}/revisions`, {
+      method: 'POST',
+      body: { expectedRevision: 0, parentRevisionId: null, plan },
+    })
+  }
+
+  /**
+   * No `connectorRevisionId`: an ontology edit writes through an internal
+   * identity the deployment mints for itself, and the service provisions it
+   * precisely when the field is absent.
+   */
+  createBindingRevision(bindingId: string, input: {
+    actionDefinitionId: string
+    actionContractDigest: string
+    mutationPlanRevisionId: string
+  }): Promise<{ id: string; stateId: string }> {
+    return this.call(`/v1/blueprint/governed-actions/admin/bindings/${bindingId}/revisions`, {
+      method: 'POST',
+      body: { expectedRevision: 0, parentRevisionId: null, ...input },
+    })
+  }
+
+  validateBindingRevision(revisionId: string, expectedStateGeneration: number): Promise<{
+    id: string
+    status: string
+    findings?: unknown
+  }> {
+    return this.call(
+      `/v1/blueprint/governed-actions/admin/binding-revisions/${revisionId}/validate`,
+      { method: 'POST', body: { expectedStateGeneration } },
+    )
+  }
+
+  reviewBindingRevision(revisionId: string, input: {
+    validationReportId: string
+    expectedStateGeneration: number
+  }): Promise<unknown> {
+    return this.call(
+      `/v1/blueprint/governed-actions/admin/binding-revisions/${revisionId}/review`,
+      { method: 'POST', body: input },
+    )
+  }
+
+  activateDeployment(stateId: string, input: {
+    expectedGeneration: number
+    expectedCurrentStateId: string
+    expectedCurrentGeneration: number
+    reason: string
+  }): Promise<unknown> {
+    return this.call(
+      `/v1/blueprint/governed-actions/admin/deployments/${stateId}/activate`,
+      { method: 'POST', body: input },
+    )
+  }
+
+  listBindings(): Promise<{
+    entries: Array<{
+      bindingId: string
+      revisionId: string
+      actionDefinitionId: string
+      deployment?: { stateId?: string; state?: string; generation?: number }
+    }>
+    hasMore?: boolean
+  }> {
+    return this.call('/v1/blueprint/governed-actions/admin/bindings')
+  }
+}

package/src/api/platform-api.ts

@@ -79,6 +79,10 @@ export class PlatformApi {
     return this.getList<unknown>('/v1/blueprint/object-types')
   }
 
+  blueprintSchema() {
+    return this.get<unknown>('/v1/blueprint/schema')
+  }
+
   blueprintObjectType(apiName: string) {
     return this.get<unknown>(`/v1/blueprint/object-types/${encodeURIComponent(apiName)}`)
   }

package/src/blueprint/ontology-edit-plan.ts

@@ -0,0 +1,195 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Derive an `ontology_edit` mutation plan from a published Action.
+ *
+ * The plan is not authored: everything in it is already stated by the Action
+ * and the object type it acts on. The Action says which properties it sets and
+ * which parameter feeds each one (`businessOutcomes[].expectedChanges`); the
+ * object type says which property is the key. Asking an operator to restate
+ * that in a hand-written JSON file would be asking them to reproduce, by hand,
+ * a mapping the platform can already read — and a typo there binds the write
+ * path to the wrong column.
+ *
+ * Pure and separately tested, because this is the one part of `action deploy`
+ * whose output is a contract rather than a call.
+ */
+
+export interface PublishedActionDefinition {
+  id: string
+  apiName: string
+  subject: { objectTypeId: string; mode: 'existing' | 'create' }
+  effect: { kind: 'create' | 'update' | 'delete' | 'transition' | 'command' }
+  inputs: Array<{ id: string; apiName: string }>
+  concurrency: { strategy: string }
+  businessOutcomes: Array<{
+    expectedChanges?: Array<Record<string, unknown>>
+  }>
+}
+
+export interface ObjectTypeShape {
+  id: string
+  apiName: string
+  primaryKeyPropertyId: string | null
+  properties: Array<{ id?: string; apiName?: string }>
+}
+
+export interface OntologyEditPlan {
+  schemaVersion: 1
+  kind: 'ontology_edit'
+  targetCompatibility: { kind: 'ontology_edit'; expectedFingerprint: string }
+  objectTypeId: string
+  objectTypeApiName: string
+  op: 'patch' | 'create' | 'delete'
+  /** property apiName → parameter apiName. */
+  set: Record<string, string>
+  pkParameter: string
+  expectedVersionParameter?: string
+  impactBounds: { maxAffectedRows: number; maxTouchedRows: number }
+  capabilities: Record<string, unknown>
+}
+
+export class PlanDerivationError extends Error {
+  constructor(message: string, readonly hint: string) {
+    super(message)
+    this.name = 'PlanDerivationError'
+  }
+}
+
+/**
+ * The service's `ontologyEditCompatibilityFingerprint`, reproduced.
+ *
+ * Duplicated rather than imported because the CLI ships as a standalone binary
+ * and cannot reach into the service. The shape is two fields — a string and a
+ * sorted unique string array — so canonical JSON here is ordinary
+ * `JSON.stringify` with the keys already in lexicographic order. A fixture in
+ * both test suites pins the same literal digest, so a change to either side
+ * fails a test rather than silently deploying a binding the inspector will
+ * refuse.
+ */
+export function ontologyEditCompatibilityFingerprint(
+  objectTypeId: string,
+  usedProperties: readonly string[],
+): string {
+  const canonical = JSON.stringify({
+    objectTypeId,
+    usedProperties: [...new Set(usedProperties)].sort(),
+  })
+  return `sha256:${createHash('sha256').update(canonical).digest('hex')}`
+}
+
+const OP_FOR_EFFECT: Readonly<Record<string, OntologyEditPlan['op']>> = {
+  update: 'patch',
+  create: 'create',
+  delete: 'delete',
+}
+
+export function deriveOntologyEditPlan(
+  action: PublishedActionDefinition,
+  objectType: ObjectTypeShape,
+): OntologyEditPlan {
+  const op = OP_FOR_EFFECT[action.effect.kind]
+  if (!op) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" has effect kind "${action.effect.kind}", which is not an ontology edit.`,
+      'Only create, update and delete write to the Blueprint. transition and command are external effects.',
+    )
+  }
+  if (action.subject.objectTypeId !== objectType.id) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" acts on a different object type than "${objectType.apiName}".`,
+      'Re-read the Action; its subject moved.',
+    )
+  }
+
+  const propertyApiNameById = new Map(
+    objectType.properties.flatMap((p) => (p.id && p.apiName ? [[p.id, p.apiName] as const] : [])),
+  )
+  const inputApiNameById = new Map(action.inputs.map((i) => [i.id, i.apiName] as const))
+
+  // Every property this Action declares it sets, and the parameter that feeds
+  // it. Read from the Action rather than from a flag: this IS the rule, and a
+  // deployment that wrote a different set would be executing something other
+  // than what was published and reviewed.
+  const set: Record<string, string> = {}
+  for (const outcome of action.businessOutcomes) {
+    for (const change of outcome.expectedChanges ?? []) {
+      if (change.kind !== 'property_set') continue
+      const value = change.value as { kind?: string; fieldId?: string } | undefined
+      if (value?.kind !== 'input' || !value.fieldId) continue
+      const property = propertyApiNameById.get(String(change.propertyId))
+      const parameter = inputApiNameById.get(value.fieldId)
+      if (!property || !parameter) continue
+      set[property] = parameter
+    }
+  }
+
+  if (op !== 'delete' && Object.keys(set).length === 0) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" sets no properties, so there is nothing to deploy.`,
+      'Open the Action and tick at least one property under "What it changes".',
+    )
+  }
+
+  // The key is addressed, never set — an editable key could move a row out from
+  // under its own identity, and the service refuses one.
+  const pkApiName = objectType.primaryKeyPropertyId
+    ? propertyApiNameById.get(objectType.primaryKeyPropertyId)
+    : undefined
+  if (!pkApiName) {
+    throw new PlanDerivationError(
+      `Object type "${objectType.apiName}" has no primary key.`,
+      'Set one with `frontera blueprint update object-type`, then publish.',
+    )
+  }
+  const pkParameter = action.inputs.find((i) => i.apiName === pkApiName)?.apiName
+  if (!pkParameter) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" takes no "${pkApiName}" parameter, so an edit has no address.`,
+      `Add a required "${pkApiName}" parameter to the Action, then publish.`,
+    )
+  }
+
+  // Only when the Action asked for it. Compare-and-set is the Action's
+  // concurrency contract, not a deployment preference.
+  const expectedVersionParameter = action.concurrency.strategy === 'expected_version'
+    ? action.inputs.find((i) => i.apiName === 'expectedVersion')?.apiName
+    : undefined
+  if (action.concurrency.strategy === 'expected_version' && !expectedVersionParameter) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" declares expected_version concurrency but takes no "expectedVersion" parameter.`,
+      'Add it to the Action, or change the concurrency strategy.',
+    )
+  }
+
+  return {
+    schemaVersion: 1,
+    kind: 'ontology_edit',
+    targetCompatibility: {
+      kind: 'ontology_edit',
+      expectedFingerprint: ontologyEditCompatibilityFingerprint(
+        objectType.id,
+        Object.keys(set),
+      ),
+    },
+    objectTypeId: objectType.id,
+    objectTypeApiName: objectType.apiName,
+    op,
+    set,
+    pkParameter,
+    ...(expectedVersionParameter ? { expectedVersionParameter } : {}),
+    // One subject, because the Action itself declares `impact.maxSubjects: 1`
+    // and the schema admits no other value.
+    impactBounds: { maxAffectedRows: 1, maxTouchedRows: 1 },
+    // Properties of the in-process edit path, not choices: it runs in one
+    // transaction against our own store, so every one of these is true by
+    // construction. They are stated because the inspector checks them.
+    capabilities: {
+      conditionalMutation: true,
+      targetIdempotency: 'transactional_ledger',
+      authoritativeReconciliation: true,
+      atomicEffect: true,
+      readYourWrites: true,
+    },
+  }
+}

package/src/blueprint-types.ts

@@ -0,0 +1,252 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+
+import { CliError, UsageError } from './errors'
+
+export const BLUEPRINT_TYPES_MARKER = '// Generated by `frontera blueprint generate-types`. Do not edit.'
+export const DEFAULT_BLUEPRINT_TYPES_OUTPUT = 'src/generated/frontera-blueprint.ts'
+
+export type BlueprintDataType = 'string' | 'number' | 'boolean' | 'date' | 'timestamp' | 'json'
+export type BlueprintPropertyType = 'attribute' | 'measure' | 'time'
+
+export interface BlueprintSchemaProperty {
+  apiName: string
+  displayName: string
+  description: string | null
+  propertyType: BlueprintPropertyType
+  dataType: BlueprintDataType
+  nullable: boolean
+  filterable: boolean
+  sortable: boolean
+}
+
+export interface BlueprintSchemaObject {
+  apiName: string
+  displayName: string
+  description: string | null
+  properties: BlueprintSchemaProperty[]
+}
+
+export interface BlueprintSchemaResponse {
+  schemaVersion: 1
+  digest: `sha256:${string}`
+  objectTypes: BlueprintSchemaObject[]
+}
+
+const DATA_TYPES = new Set<BlueprintDataType>(['string', 'number', 'boolean', 'date', 'timestamp', 'json'])
+const PROPERTY_TYPES = new Set<BlueprintPropertyType>(['attribute', 'measure', 'time'])
+
+function schemaContractError(detail: string): never {
+  throw new CliError(`invalid Blueprint schema response: ${detail}`, {
+    code: 'BAD_REQUEST',
+    hint: 'upgrade the Frontera CLI or confirm the API origin is running a compatible service',
+  })
+}
+
+export function parseBlueprintSchema(input: unknown): BlueprintSchemaResponse {
+  if (!input || typeof input !== 'object') return schemaContractError('expected an object')
+  const schema = input as Record<string, unknown>
+  if (schema.schemaVersion !== 1) {
+    return schemaContractError(`unsupported schema version ${String(schema.schemaVersion)}`)
+  }
+  if (typeof schema.digest !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(schema.digest)) {
+    return schemaContractError('digest must be a sha256 value')
+  }
+  if (!Array.isArray(schema.objectTypes)) return schemaContractError('objectTypes must be an array')
+
+  const objectNames = new Set<string>()
+  for (const [objectIndex, candidate] of schema.objectTypes.entries()) {
+    if (!candidate || typeof candidate !== 'object') return schemaContractError(`objectTypes[${objectIndex}] must be an object`)
+    const objectType = candidate as Record<string, unknown>
+    if (typeof objectType.apiName !== 'string' || !/^[A-Z][A-Za-z0-9]{0,99}$/.test(objectType.apiName)) {
+      return schemaContractError(`objectTypes[${objectIndex}].apiName is invalid`)
+    }
+    if (
+      typeof objectType.displayName !== 'string'
+      || !(objectType.description === null || typeof objectType.description === 'string')
+      || !Array.isArray(objectType.properties)
+    ) {
+      return schemaContractError(`objectTypes[${objectIndex}] is malformed`)
+    }
+    if (objectNames.has(objectType.apiName)) return schemaContractError(`duplicate object apiName ${objectType.apiName}`)
+    objectNames.add(objectType.apiName)
+    const propertyNames = new Set<string>()
+    for (const [propertyIndex, propertyCandidate] of objectType.properties.entries()) {
+      if (!propertyCandidate || typeof propertyCandidate !== 'object') {
+        return schemaContractError(`objectTypes[${objectIndex}].properties[${propertyIndex}] must be an object`)
+      }
+      const property = propertyCandidate as Record<string, unknown>
+      if (typeof property.apiName !== 'string' || !/^[a-z][A-Za-z0-9]{0,99}$/.test(property.apiName)) {
+        return schemaContractError(`objectTypes[${objectIndex}].properties[${propertyIndex}].apiName is invalid`)
+      }
+      if (
+        typeof property.displayName !== 'string'
+        || !(property.description === null || typeof property.description === 'string')
+        || !PROPERTY_TYPES.has(property.propertyType as BlueprintPropertyType)
+        || !DATA_TYPES.has(property.dataType as BlueprintDataType)
+        || typeof property.nullable !== 'boolean'
+        || typeof property.filterable !== 'boolean'
+        || typeof property.sortable !== 'boolean'
+      ) {
+        return schemaContractError(`objectTypes[${objectIndex}].properties[${propertyIndex}] is malformed`)
+      }
+      if (propertyNames.has(property.apiName)) {
+        return schemaContractError(`duplicate property apiName ${property.apiName} on ${objectType.apiName}`)
+      }
+      propertyNames.add(property.apiName)
+    }
+  }
+  return input as BlueprintSchemaResponse
+}
+
+const TYPE_BY_DATA_TYPE: Readonly<Record<BlueprintDataType, string>> = {
+  string: 'string',
+  number: 'number',
+  boolean: 'boolean',
+  date: 'string',
+  timestamp: 'string',
+  json: 'unknown',
+}
+
+function jsDoc(value: string | null): string[] {
+  if (!value) return []
+  const safe = value.replace(/\*\//g, '*\\/').replace(/\r?\n/g, ' ')
+  return [`/** ${safe} */`]
+}
+
+function stringUnion(values: string[]): string {
+  return values.length === 0 ? 'never' : values.map((value) => JSON.stringify(value).replace(/^"|"$/g, "'")).join(' | ')
+}
+
+function compareApiName(left: { apiName: string }, right: { apiName: string }): number {
+  return left.apiName < right.apiName ? -1 : left.apiName > right.apiName ? 1 : 0
+}
+
+export function resolveBlueprintTypesOutputPath(
+  projectRoot: string,
+  output = DEFAULT_BLUEPRINT_TYPES_OUTPUT,
+): string {
+  const target = resolve(projectRoot, output)
+  const fromRoot = relative(resolve(projectRoot), target)
+  if (
+    !output
+    || isAbsolute(output)
+    || output.split(/[\\/]/).includes('..')
+    || fromRoot === '..'
+    || fromRoot.startsWith(`..${sep}`)
+  ) {
+    throw new UsageError(
+      'Blueprint types output must be a project-relative path without `..`',
+      'rerun with a path such as `--output src/generated/frontera-blueprint.ts`',
+    )
+  }
+  if (!output.endsWith('.ts') || output.endsWith('.d.ts')) {
+    throw new UsageError(
+      'Blueprint types output must be a .ts file',
+      'rerun with a path such as `--output src/generated/frontera-blueprint.ts`',
+    )
+  }
+  const realRoot = realpathSync(projectRoot)
+  let existingAncestor = target
+  while (!existsSync(existingAncestor)) {
+    const parent = dirname(existingAncestor)
+    if (parent === existingAncestor) break
+    existingAncestor = parent
+  }
+  const realAncestor = realpathSync(existingAncestor)
+  const fromRealRoot = relative(realRoot, realAncestor)
+  if (isAbsolute(fromRealRoot) || fromRealRoot === '..' || fromRealRoot.startsWith(`..${sep}`)) {
+    throw new UsageError(
+      'Blueprint types output resolves outside the App project',
+      'choose an output directory inside the current App project and rerun generation',
+    )
+  }
+  return target
+}
+
+export interface BlueprintTypesWriteResult {
+  path: string
+  changed: boolean
+}
+
+export function writeBlueprintTypesFile(
+  projectRoot: string,
+  output: string | undefined,
+  contents: string,
+  check: boolean,
+): BlueprintTypesWriteResult {
+  const path = resolveBlueprintTypesOutputPath(projectRoot, output)
+  const exists = existsSync(path)
+  const current = exists ? readFileSync(path, 'utf8') : null
+
+  if (current === contents) return { path, changed: false }
+  if (check) {
+    throw new CliError(
+      exists ? `Blueprint types are stale at ${path}` : `Blueprint types are missing at ${path}`,
+      { code: 'CONFLICT', hint: 'run `frontera blueprint generate-types` and commit the result' },
+    )
+  }
+  if (current !== null && !current.startsWith(`${BLUEPRINT_TYPES_MARKER}\n`)) {
+    throw new CliError(`refusing to overwrite ${path}: the file is not generated by Frontera`, {
+      code: 'BAD_REQUEST',
+      hint: 'choose another --output path or move the authored file yourself',
+    })
+  }
+
+  mkdirSync(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
+  try {
+    writeFileSync(temporary, contents)
+    renameSync(temporary, path)
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary)
+  }
+  return { path, changed: true }
+}
+
+export function generateBlueprintTypes(schema: BlueprintSchemaResponse): string {
+  if (schema.schemaVersion !== 1) {
+    throw new Error(`unsupported Blueprint schema version: ${String(schema.schemaVersion)}`)
+  }
+
+  const objects = [...schema.objectTypes]
+    .sort(compareApiName)
+    .map((objectType) => ({
+      ...objectType,
+      properties: [...objectType.properties].sort(compareApiName),
+    }))
+
+  const lines = [
+    BLUEPRINT_TYPES_MARKER,
+    `// Blueprint schema digest: ${schema.digest}`,
+    '',
+    "import type { BlueprintObjectSchema as __FronteraBlueprintObjectSchema } from '@frontera-sdk/blueprint/types'",
+    '',
+  ]
+
+  for (const objectType of objects) {
+    lines.push(...jsDoc(objectType.description), `export interface ${objectType.apiName} {`)
+    for (const property of objectType.properties) {
+      lines.push(...jsDoc(property.description).map((line) => `  ${line}`))
+      const base = TYPE_BY_DATA_TYPE[property.dataType]
+      lines.push(`  ${property.apiName}: ${base}${property.nullable ? ' | null' : ''}`)
+    }
+    lines.push('}', '')
+  }
+
+  lines.push("declare module '@frontera-sdk/blueprint/types' {", '  interface BlueprintRegistry {')
+  for (const objectType of objects) {
+    const filterable = stringUnion(objectType.properties.filter((property) => property.filterable).map((property) => property.apiName))
+    const sortable = stringUnion(objectType.properties.filter((property) => property.sortable).map((property) => property.apiName))
+    lines.push(
+      `    ${objectType.apiName}: __FronteraBlueprintObjectSchema<`,
+      `      ${objectType.apiName},`,
+      `      ${filterable},`,
+      `      ${sortable}`,
+      '    >',
+    )
+  }
+  lines.push('  }', '}', '')
+
+  return `${lines.join('\n')}\n`
+}