@frontera-sdk/cli 1.52.27 → 1.52.29

package/src/local/local-blueprint-outline.ts

@@ -0,0 +1,465 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { blueprintApplyState, contentHash, loadBuild, type BuildEntry } from './local-applied'
+import { actionFit, objectTypeFit, type ObjectTypeFit } from './local-portability'
+import { referencesIn } from './local-sync-refs'
+
+/**
+ * A project's Blueprint as people read it: one entry per object type, with
+ * its fields, the relations that touch it (from either end), the governed
+ * Actions whose subject it is and the metrics that measure it. Read from the
+ * `blueprint/` files only, so it answers whether or not a runtime is running.
+ *
+ * Forge's project home lists it and Studio's object definition page shows
+ * one entry; neither changes the files. `localAdaptation` is the rule
+ * `resolveBlueprint` applies when it makes the runtime's copy, kept here so
+ * what the home says about a type is what the runtime does with it.
+ */
+
+type Doc = Record<string, any>
+
+/** One parsed file, with its path from the project root. */
+export interface BlueprintFile {
+  path: string
+  doc: Doc
+}
+
+export interface BlueprintFiles {
+  objectTypes: BlueprintFile[]
+  linkTypes: BlueprintFile[]
+  metrics: BlueprintFile[]
+  actions: BlueprintFile[]
+}
+
+const KIND_DIRS = { objectTypes: 'object-types', linkTypes: 'link-types', metrics: 'metrics', actions: 'actions' } as const
+
+/** The `blueprint/` files of a project, parsed; a file that does not parse is skipped. */
+export function readBlueprintFiles(root: string): BlueprintFiles {
+  const read = (dir: string): BlueprintFile[] => {
+    const at = join(root, 'blueprint', dir)
+    if (!existsSync(at)) return []
+    const out: BlueprintFile[] = []
+    for (const name of readdirSync(at).filter((n) => /\.ya?ml$/.test(n) && !n.startsWith('.')).sort()) {
+      try {
+        const doc = parseYaml(readFileSync(join(at, name), 'utf8')) as unknown
+        if (doc && typeof doc === 'object' && !Array.isArray(doc)) out.push({ path: `blueprint/${dir}/${name}`, doc: doc as Doc })
+      } catch {
+        // A file being edited can be half-written; it shows again once it parses.
+      }
+    }
+    return out
+  }
+  return {
+    objectTypes: read(KIND_DIRS.objectTypes),
+    linkTypes: read(KIND_DIRS.linkTypes),
+    metrics: read(KIND_DIRS.metrics),
+    actions: read(KIND_DIRS.actions),
+  }
+}
+
+/** What the local runtime does with an object type: the rule lives with the other portability rules. */
+export type LocalAdaptation = ObjectTypeFit
+
+/**
+ * The rules `resolveBlueprint` applies to one object type. `hasLocalDataset`
+ * says whether the project has the dataset's local file (`datasets/<name>.json`).
+ */
+export function localAdaptation(doc: Doc, hasLocalDataset: (dataset: string) => boolean): LocalAdaptation {
+  return objectTypeFit(doc, hasLocalDataset)
+}
+
+/** A workflow or Agent whose files name a governed Action. */
+export interface ActionUser {
+  kind: 'workflow' | 'agent'
+  /** The workflow's slug or the Agent's folder. */
+  slug: string
+  name: string
+}
+
+function readable(slug: string): string {
+  const words = slug.replace(/[-_]+/g, ' ').trim()
+  return words ? words[0]!.toUpperCase() + words.slice(1) : slug
+}
+
+function readDoc(path: string): unknown {
+  try {
+    const text = readFileSync(path, 'utf8')
+    return /\.json$/.test(path) ? JSON.parse(text) : parseYaml(text)
+  } catch {
+    return null
+  }
+}
+
+function entries(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((n) => !n.startsWith('.')).sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Which workflows and Agents name each governed Action (`action/<apiName>`,
+ * as a pulled workflow names one): `workflows/*.yaml`, and each Agent's
+ * `agent.json`, `bindings.json` and `operating.json`. Keyed by apiName.
+ */
+export function actionUsage(root: string): Map<string, ActionUser[]> {
+  const usage = new Map<string, ActionUser[]>()
+  const note = (doc: unknown, user: ActionUser) => {
+    if (!doc) return
+    for (const ref of referencesIn(doc)) {
+      if (ref.kind !== 'action') continue
+      const users = usage.get(ref.name) ?? []
+      if (!users.some((u) => u.kind === user.kind && u.slug === user.slug)) users.push(user)
+      usage.set(ref.name, users)
+    }
+  }
+  for (const file of entries(join(root, 'workflows')).filter((f) => /\.ya?ml$/.test(f))) {
+    const slug = file.replace(/\.ya?ml$/, '')
+    note(readDoc(join(root, 'workflows', file)), { kind: 'workflow', slug, name: readable(slug) })
+  }
+  for (const slug of entries(join(root, 'agents'))) {
+    const dir = join(root, 'agents', slug)
+    const agent = readDoc(join(dir, 'agent.json')) as { config?: { name?: unknown } } | null
+    const name = typeof agent?.config?.name === 'string' && agent.config.name.trim() ? agent.config.name.trim() : readable(slug)
+    for (const file of ['agent.json', 'bindings.json', 'operating.json']) note(file === 'agent.json' ? agent : readDoc(join(dir, file)), { kind: 'agent', slug, name })
+  }
+  return usage
+}
+
+export interface OutlineField {
+  apiName: string
+  displayName: string
+  valueType: string
+  primaryKey: boolean
+  required: boolean
+  calculated: boolean
+}
+
+export type Cardinality = 'one to one' | 'one to many' | 'many to one' | 'many to many'
+
+export interface OutlineRelation {
+  apiName: string
+  /** What this object calls the objects at the other end. */
+  name: string
+  /** `out`: this object is the link's `from`; `in`: its `to`. */
+  direction: 'out' | 'in'
+  other: { apiName: string; displayName: string }
+  /** Read from this object's side. */
+  cardinality: Cardinality | null
+  path: string
+}
+
+export type ActionLocalStatus = 'runs' | 'switched-off' | 'failed' | 'left-off' | 'not-deployed'
+
+export interface OutlineAction {
+  apiName: string
+  displayName: string
+  /** `existing`: acts on one object of the type; `create`: creates one. */
+  mode: 'existing' | 'create'
+  /** Who approves, in a few words: "supervisor approves", "no approval". */
+  approval: string
+  description: string | null
+  /** Its parameters, by API name. */
+  parameters: string[]
+  /** Its parameters as the file declares them, for a reader that lists them. */
+  inputs: OutlineInput[]
+  /**
+   * The file's approval rule as written (`governance.approval`), for a reader
+   * that says it the platform's way ("Approval required · 2 steps"); `null`
+   * when the file has none.
+   */
+  approvalPolicy: Record<string, unknown> | null
+  usedBy: ActionUser[]
+  path: string
+  /** On the local runtime: "Runs locally", "Switched off here", "Didn’t deploy", "Not deployed yet". */
+  local: { status: ActionLocalStatus; label: string; reason: string | null }
+}
+
+/** One parameter of an Action, as its file declares it. */
+export interface OutlineInput {
+  apiName: string
+  displayName: string
+  description: string | null
+  required: boolean
+  /** Its value type as written: `kind`, and `integer`, `enum`, `minimum`, `maximum` where the file sets them. */
+  valueType: Record<string, unknown> | null
+  /** The file's default; absent when it sets none. */
+  default?: unknown
+}
+
+const ACTION_LABEL: Record<ActionLocalStatus, string> = {
+  runs: 'Runs locally',
+  'switched-off': 'Switched off here',
+  failed: 'Didn’t deploy',
+  'left-off': 'Platform only',
+  'not-deployed': 'Not deployed yet',
+}
+
+/**
+ * How the local runtime holds one Action: what the last Blueprint build
+ * recorded for the files as they are, or, before one, what it will do.
+ */
+export function actionLocal(doc: Doc, built: BuildEntry['actions'] | null): OutlineAction['local'] {
+  const recorded = built?.[doc.apiName as string]
+  if (recorded) return { status: recorded.status, label: ACTION_LABEL[recorded.status], reason: recorded.reason ?? null }
+  const fit = actionFit(doc)
+  return fit.runsLocally ? { status: 'not-deployed', label: ACTION_LABEL['not-deployed'], reason: null } : { status: 'switched-off', label: ACTION_LABEL['switched-off'], reason: fit.reason ?? null }
+}
+
+export interface OutlineMetric {
+  apiName: string
+  displayName: string
+  description: string | null
+  path: string
+}
+
+export interface ObjectOutline {
+  apiName: string
+  displayName: string
+  pluralDisplayName: string
+  description: string | null
+  /** The object's glyph and colour, as the file sets them. */
+  icon: string | null
+  color: string | null
+  path: string
+  /** Backed by the platform's media files. */
+  media: boolean
+  fields: OutlineField[]
+  relations: OutlineRelation[]
+  actions: OutlineAction[]
+  metrics: OutlineMetric[]
+  local: LocalAdaptation
+}
+
+const CARDINALITY: Record<string, Cardinality> = {
+  one_to_one: 'one to one',
+  one_to_many: 'one to many',
+  many_to_one: 'many to one',
+  many_to_many: 'many to many',
+}
+const FLIPPED: Record<string, string> = { one_to_many: 'many_to_one', many_to_one: 'one_to_many' }
+
+function text(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null
+}
+
+/** The approval rule of an Action file, as a reader says it. */
+export function approvalPhrase(action: Doc): string {
+  const approval = action.governance?.approval as { mode?: string; threshold?: number; stages?: Array<{ approver?: unknown; when?: unknown }> } | undefined
+  const mode = approval?.mode
+  if (!mode || mode === 'none') return 'no approval'
+  const count = (n: number | undefined) => (n && n > 1 ? `${n} approvals` : 'approval')
+  if (mode === 'required') return `needs ${count(approval.threshold)}`
+  if (mode === 'conditional') return `sometimes needs ${count(approval.threshold)}`
+  const stages = Array.isArray(approval.stages) ? approval.stages : []
+  if (stages.length === 1) {
+    const approver = stages[0]!.approver as { role?: unknown } | undefined
+    const who = typeof approver?.role === 'string' ? readable(approver.role).toLowerCase() : 'a member'
+    return stages[0]!.when && stages[0]!.when !== 'always' ? `${who} approves when it applies` : `${who} approves`
+  }
+  return stages.length ? `${stages.length} approval steps` : 'needs approval'
+}
+
+/**
+ * Each object type with what belongs to it, alphabetical by display name.
+ * A relation shows on both of its objects, written from each one's side.
+ */
+export function outlineBlueprint(files: BlueprintFiles, opts: { hasLocalDataset: (dataset: string) => boolean; usage: Map<string, ActionUser[]>; built?: BuildEntry['actions'] | null }): ObjectOutline[] {
+  const names = new Map<string, string>()
+  for (const f of files.objectTypes) if (text(f.doc.apiName)) names.set(f.doc.apiName, text(f.doc.displayName) ?? f.doc.apiName)
+  const displayOf = (apiName: string) => names.get(apiName) ?? apiName
+
+  const outlines = files.objectTypes
+    .filter((f) => text(f.doc.apiName))
+    .map((f): ObjectOutline => {
+      const doc = f.doc
+      const apiName = doc.apiName as string
+      const properties = (Array.isArray(doc.properties) ? doc.properties : []) as Doc[]
+      const fields = properties
+        .filter((p) => text(p.apiName))
+        .map((p) => ({
+          apiName: p.apiName as string,
+          displayName: text(p.displayName) ?? (p.apiName as string),
+          valueType: typeof p.valueType === 'string' ? p.valueType : (text(p.baseType?.kind) ?? 'unknown'),
+          primaryKey: doc.primaryKey === p.apiName,
+          required: p.required === true || doc.primaryKey === p.apiName,
+          calculated: !!p.calculation,
+        }))
+
+      const relations: OutlineRelation[] = []
+      for (const link of files.linkTypes) {
+        const l = link.doc
+        const from = text(l.from?.objectType)
+        const to = text(l.to?.objectType)
+        if (!from || !to || (from !== apiName && to !== apiName)) continue
+        const cardinality = typeof l.cardinality === 'string' ? l.cardinality : null
+        // Both ends on this object (a self link) shows twice: once each way.
+        for (const direction of ['out', 'in'] as const) {
+          if ((direction === 'out' ? from : to) !== apiName) continue
+          const end = direction === 'out' ? l.from : l.to
+          const other = direction === 'out' ? to : from
+          const read = cardinality ? (direction === 'out' ? cardinality : (FLIPPED[cardinality] ?? cardinality)) : null
+          relations.push({
+            apiName: text(l.apiName) ?? link.path,
+            name: text(end?.displayName) ?? displayOf(other),
+            direction,
+            other: { apiName: other, displayName: displayOf(other) },
+            cardinality: read ? (CARDINALITY[read] ?? null) : null,
+            path: link.path,
+          })
+        }
+      }
+
+      const actions = files.actions
+        .filter((a) => text(a.doc.apiName) && a.doc.subject?.objectType === apiName)
+        .map((a) => ({
+          apiName: a.doc.apiName as string,
+          displayName: text(a.doc.displayName) ?? (a.doc.apiName as string),
+          mode: a.doc.subject?.mode === 'create' ? ('create' as const) : ('existing' as const),
+          approval: approvalPhrase(a.doc),
+          description: text(a.doc.description),
+          parameters: (Array.isArray(a.doc.inputs) ? (a.doc.inputs as Doc[]) : []).map((input) => text(input?.apiName)).filter((name): name is string => !!name),
+          inputs: (Array.isArray(a.doc.inputs) ? (a.doc.inputs as Doc[]) : [])
+            .filter((input) => text(input?.apiName))
+            .map((input): OutlineInput => ({
+              apiName: input.apiName as string,
+              displayName: text(input.displayName) ?? (input.apiName as string),
+              description: text(input.description),
+              required: input.required === true,
+              valueType: record(input.valueType),
+              ...(Object.prototype.hasOwnProperty.call(input, 'default') ? { default: input.default } : {}),
+            })),
+          approvalPolicy: record(a.doc.governance?.approval),
+          usedBy: opts.usage.get(a.doc.apiName) ?? [],
+          path: a.path,
+          local: actionLocal(a.doc, opts.built ?? null),
+        }))
+        .sort((a, b) => a.displayName.localeCompare(b.displayName))
+
+      const metrics = files.metrics
+        .filter((m) => text(m.doc.apiName) && m.doc.objectType === apiName)
+        .map((m) => ({ apiName: m.doc.apiName as string, displayName: text(m.doc.displayName) ?? (m.doc.apiName as string), description: text(m.doc.description), path: m.path }))
+        .sort((a, b) => a.displayName.localeCompare(b.displayName))
+
+      const local = localAdaptation(doc, opts.hasLocalDataset)
+      return {
+        apiName,
+        displayName: displayOf(apiName),
+        pluralDisplayName: text(doc.pluralDisplayName) ?? displayOf(apiName),
+        description: text(doc.description),
+        icon: text(doc.icon),
+        color: text(doc.color),
+        path: f.path,
+        media: local.leftOff,
+        fields,
+        relations,
+        actions,
+        metrics,
+        local,
+      }
+    })
+  return outlines.sort((a, b) => a.displayName.localeCompare(b.displayName))
+}
+
+function plural(n: number, one: string, many: string): string {
+  return `${n} ${n === 1 ? one : many}`
+}
+
+/** "12 fields · 4 relations · 3 actions · 1 metric", leaving out what the object has none of. */
+export function countsLine(o: Pick<ObjectOutline, 'fields' | 'relations' | 'actions' | 'metrics'>): string {
+  const parts = [
+    o.fields.length ? plural(o.fields.length, 'field', 'fields') : null,
+    o.relations.length ? plural(o.relations.length, 'relation', 'relations') : null,
+    o.actions.length ? plural(o.actions.length, 'action', 'actions') : null,
+    o.metrics.length ? plural(o.metrics.length, 'metric', 'metrics') : null,
+  ].filter(Boolean)
+  return parts.length ? parts.join(' · ') : 'No fields yet'
+}
+
+export type ObjectStatusKind = 'platform-only' | 'failed' | 'adapted' | 'stubbed' | 'not-applied' | 'built'
+
+export interface ObjectStatus {
+  kind: ObjectStatusKind
+  label: string
+  /** The one line that says why, when the label does not: the error, or what is adapted. */
+  reason?: string
+}
+
+/** A field's name inside a sentence: "location", but "GPS position" keeps its capitals. */
+function inline(name: string): string {
+  return /^[A-Z][A-Z]/.test(name) ? name : name.charAt(0).toLowerCase() + name.slice(1)
+}
+
+/** What the runtime holds of the Blueprint: whether it has the current files, and the last build's record. */
+export interface BlueprintBuildState {
+  applied: boolean
+  /** The last Blueprint build failed for these files: its error. */
+  failed?: string | null
+}
+
+/**
+ * The one thing worth saying about an object type on this runtime, most
+ * important first: platform only > the Blueprint failed to build > not
+ * applied yet > adapted (an Action that does not run here, a calculated field
+ * off, every row read) > built. `state` (or `true`) says the runtime holds the
+ * project's current Blueprint.
+ */
+export function objectStatus(o: Pick<ObjectOutline, 'fields' | 'actions' | 'local'>, state: boolean | BlueprintBuildState): ObjectStatus {
+  const s: BlueprintBuildState = typeof state === 'boolean' ? { applied: state } : state
+  if (o.local.leftOff) return { kind: 'platform-only', label: 'Platform only' }
+  if (s.failed) return { kind: 'failed', label: 'Failed', reason: s.failed }
+  if (!s.applied) return { kind: 'not-applied', label: 'Not applied yet' }
+  const idle = o.actions.filter((a) => a.local.status === 'switched-off' || a.local.status === 'failed')
+  if (idle.length) {
+    const failed = idle.filter((a) => a.local.status === 'failed')
+    const label = failed.length
+      ? failed.length === 1 ? 'An action didn’t deploy' : `${failed.length} actions didn’t deploy`
+      : idle.length === 1 ? '1 action switched off here' : `${idle.length} actions switched off here`
+    return { kind: 'adapted', label, reason: idle.map((a) => `${a.displayName}: ${a.local.reason ?? a.local.label}`).join('; ') }
+  }
+  if (o.local.mediaStub) return { kind: 'stubbed', label: 'Stubbed: no files here', reason: `Its files stay on the platform: an empty Media Set, ${o.local.mediaStub}, stands in for them here` }
+  if (o.local.calculated.length) {
+    const names = o.local.calculated.map((api) => o.fields.find((f) => f.apiName === api)?.displayName ?? api)
+    return { kind: 'adapted', label: names.length === 1 ? `Adapted: ${inline(names[0]!)} off` : `Adapted: ${names.length} fields off` }
+  }
+  if (o.local.readsEveryRow) return { kind: 'adapted', label: 'Reads every row' }
+  return { kind: 'built', label: 'Built' }
+}
+
+/** The local organization of a project's runtime, from its state; null before one started. */
+export function localOrganizationId(root: string): string | null {
+  try {
+    const state = JSON.parse(readFileSync(join(root, '.frontera', 'local', 'state.json'), 'utf8')) as { credentials?: { organizationId?: unknown } }
+    return typeof state.credentials?.organizationId === 'string' ? state.credentials.organizationId : null
+  } catch {
+    return null
+  }
+}
+
+/** The Blueprint's build for the files as they are: applied or not, failed or not, and its Actions. */
+export function blueprintBuild(root: string): BlueprintBuildState & { actions: BuildEntry['actions'] | null } {
+  const project = { root, id: '', stateDir: join(root, '.frontera', 'local') }
+  const org = localOrganizationId(root)
+  const entry = loadBuild(project, org).blueprint
+  // The record speaks only for the files it was made from.
+  const current = !!entry && entry.hash === contentHash(project, { kind: 'blueprint', key: 'blueprint' })
+  const failed = current && entry.status === 'failed' ? (entry.error ?? 'The Blueprint didn’t apply') : null
+  return { applied: blueprintApplyState(project, org) === 'applied', failed, actions: current && !failed ? (entry.actions ?? null) : null }
+}
+
+/** The outline of a project folder: its files, its local datasets and what names its Actions. */
+export function projectBlueprintOutline(root: string, built: BuildEntry['actions'] | null = blueprintBuild(root).actions): ObjectOutline[] {
+  return outlineBlueprint(readBlueprintFiles(root), {
+    hasLocalDataset: (dataset) => existsSync(join(root, 'datasets', `${dataset}.json`)),
+    usage: actionUsage(root),
+    built,
+  })
+}

package/src/local/local-brand.ts

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { SyncClient } from './local-sync-client'
+import type { RemoteItem } from './local-sync-plan'
+
+/**
+ * The organization's brand: the colors it sets over the deployment's
+ * (light and dark primary) and its logo. A pull writes `brand/brand.json`
+ * with the logo beside it, and `local dev` gives the local runtime's
+ * organization the same, so the local Chat and Studio look like the
+ * workspace. Read-only: never proposed back (an organization's brand is an
+ * administrator's setting, not a project's change).
+ */
+
+/** What `/v1/sync/brand` returns. */
+export interface BrandRow {
+  colors?: { primary?: string | null; primaryDark?: string | null } | null
+  logo?: { file?: string | null } | null
+}
+
+/** The project's brand file. */
+export interface BrandFile {
+  colors: { primary: string | null; primaryDark: string | null }
+  logo?: string
+}
+
+export const BRAND_PATH = 'brand/brand.json'
+
+/** A logo larger than this stays on the platform, and the note says so. */
+const LOGO_LIMIT = 5 * 1024 * 1024
+
+/** The organization's brand as one project item, its logo an asset beside it. */
+export async function readBrand(ws: SyncClient, row: BrandRow, warnings: string[]): Promise<RemoteItem[]> {
+  const colors = { primary: row.colors?.primary ?? null, primaryDark: row.colors?.primaryDark ?? null }
+  const it: RemoteItem = { ref: 'brand', kind: 'brand', name: 'brand', title: 'Organization brand', files: {}, unresolved: [], notes: ['The organization’s colors and logo, so the local Chat and Studio look like the workspace; changed on the platform, never proposed from here'], requires: [], assets: [] }
+  const file = row.logo?.file && /^logo\.[a-z]+$/.test(row.logo.file) ? row.logo.file : null
+  let logo: string | undefined
+  if (file) {
+    try {
+      const bytes = await ws.getBytes('/v1/sync/brand/logo')
+      if (bytes.byteLength > LOGO_LIMIT) throw new Error('larger than 5 MB')
+      it.assets!.push({ path: `brand/${file}`, bytes })
+      logo = file
+    } catch (err) {
+      warnings.push(`Organization brand: its logo: ${(err as Error).message}`)
+      it.notes.push('Its logo could not be read, so the brand comes without it')
+    }
+  }
+  if (!colors.primary && !colors.primaryDark && !logo) return []
+  const doc: BrandFile = { colors, ...(logo ? { logo } : {}) }
+  it.files[BRAND_PATH] = `${JSON.stringify(doc, null, 2)}\n`
+  if (!it.assets!.length) delete it.assets
+  return [it]
+}
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+type Upload = (path: string, form: FormData) => Promise<{ status: number; body: unknown }>
+
+const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as Record<string, unknown> | null
+
+const errorOf = (a: { status: number; body: unknown }) => {
+  const b = a.body as { message?: unknown } | null
+  return `${a.status} ${String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 200)}`
+}
+
+/** A multipart upload to the runtime with the owner's session, as Settings uploads a logo. */
+export function brandUpload(serviceUrl: string, creds: { session?: string | null; organizationId: string; workspaceId: string }): Upload {
+  return async (path, form) => {
+    const res = await fetch(new URL(path, serviceUrl), { method: 'POST', headers: { authorization: `Bearer ${creds.session}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId }, body: form })
+    const text = await res.text()
+    let body: unknown = text
+    try {
+      body = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body }
+  }
+}
+
+const MIME: Record<string, string> = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', svg: 'image/svg+xml', webp: 'image/webp', gif: 'image/gif', ico: 'image/x-icon' }
+
+/**
+ * Give the runtime's organization the project's brand: its colors (the
+ * owner's session, as an administrator sets them in Settings) and its logo,
+ * uploaded and set as the organization's.
+ */
+export async function applyBrand(root: string, organizationId: string, call: Call, upload: Upload): Promise<{ ok: boolean; output: string }> {
+  const path = join(root, BRAND_PATH)
+  if (!existsSync(path)) return { ok: false, output: `error [BRAND]: ${BRAND_PATH} is missing` }
+  let doc: BrandFile
+  try {
+    doc = JSON.parse(readFileSync(path, 'utf8')) as BrandFile
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${BRAND_PATH} is not valid JSON: ${(err as Error).message}` }
+  }
+  const lines: string[] = []
+  const set = await call('PUT', '/v1/config/brand', { primary: doc.colors?.primary ?? null, primaryDark: doc.colors?.primaryDark ?? null })
+  if (set.status >= 400) return { ok: false, output: `error [BRAND]: ${errorOf(set)}` }
+  if (doc.logo) {
+    const file = join(root, 'brand', doc.logo)
+    if (!existsSync(file)) {
+      lines.push(`  warning: Its logo (brand/${doc.logo}) is not in the project, so the runtime keeps its own`)
+    } else {
+      const ext = doc.logo.split('.').pop()?.toLowerCase() ?? ''
+      const form = new FormData()
+      form.append('file', new File([readFileSync(file)], doc.logo, { type: MIME[ext] ?? 'application/octet-stream' }))
+      form.append('purpose', 'org-logo')
+      form.append('orgId', organizationId)
+      const sent = await upload('/v1/upload', form)
+      const storagePath = String(dataOf(sent.body)?.storagePath ?? '')
+      if (sent.status >= 400 || !storagePath) lines.push(`  warning: Its logo could not be uploaded here (${errorOf(sent)})`)
+      else {
+        const put = await call('PUT', '/v1/org/logo', { storagePath })
+        if (put.status >= 400) lines.push(`  warning: Its logo could not be set here (${errorOf(put)})`)
+      }
+    }
+  }
+  const parts = [doc.colors?.primary || doc.colors?.primaryDark ? 'colors' : '', doc.logo ? 'logo' : ''].filter(Boolean)
+  lines.unshift(`  set the organization’s ${parts.join(' and ') || 'brand'} as the workspace has ${parts.length > 1 ? 'them' : 'it'}`)
+  return { ok: true, output: lines.join('\n') }
+}