@frontera-sdk/cli 1.52.28 → 1.52.29

package/src/local/local-applied.ts

@@ -1,10 +1,12 @@
 import { createHash } from 'node:crypto'
-import { lstatSync, readdirSync, readFileSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, relative } from 'node:path'
 
 import { writeFileAtomic } from '../fs-atomic'
 import { allTargets, describeTarget, datasetDocument, isIgnoredName, type SyncTarget } from './local-dev-sync'
 import type { LocalProject } from './local-project'
+import { standInTools } from './local-stand-ins'
+import { importedFiles } from './local-function-shared'
 
 /**
  * What `frontera local dev` has applied to this runtime, by content hash. It
@@ -71,6 +73,10 @@ function treeHash(dir: string): string | null {
 export function contentHash(project: LocalProject, target: SyncTarget): string | null {
   // The Blueprint is applied as one tree, so it changes when any file in it does.
   if (target.kind === 'blueprint') return treeHash(join(project.root, 'blueprint'))
+  // A knowledge base, a skill and a slide theme are folders: a new document, reference or image changes them.
+  if (target.kind === 'knowledge' || target.kind === 'skill' || target.kind === 'theme' || target.kind === 'brand') return treeHash(join(project.root, dirname(target.file)))
+  // A stand-in lists the connection's tools and those the project's files name on it: either changing re-applies it.
+  if (target.kind === 'plugin' && target.file.endsWith('.stand-in.json')) return createHash('sha256').update(JSON.stringify(standInTools(project.root, target.name))).update(fileDigest(join(project.root, target.file)) ?? '').digest('hex')
   const own = fileDigest(join(project.root, target.file))
   if (!own) return null
   const hash = createHash('sha256').update(own)
@@ -80,9 +86,15 @@ export function contentHash(project: LocalProject, target: SyncTarget): string |
     const rows = csv ? fileDigest(join(project.root, csv)) : null
     if (rows) hash.update(rows)
   }
-  // A Function is bundled with what it imports: the other files in functions/ and the vendored SDK.
+  // A Function is bundled with what it imports: the other files in functions/, the vendored SDK, and the
+  // shared files it imports from outside functions/.
   if (target.kind === 'function') {
     hash.update(treeHash(join(project.root, 'functions')) ?? '').update(treeHash(join(project.root, 'vendor')) ?? '')
+    for (const path of importedFiles(project.root, target.file).filter((p) => !p.startsWith('functions/')).sort()) hash.update(path).update('\0').update(fileDigest(join(project.root, path)) ?? '')
+  }
+  // Context and data the pull could not read is assumed on the project's object types: a new one changes it.
+  if (target.kind === 'bindings' && /"blueprintUnread"\s*:\s*true/.test(readFileSync(join(project.root, target.file), 'utf8'))) {
+    hash.update(treeHash(join(project.root, 'blueprint', 'object-types')) ?? '')
   }
   return hash.digest('hex')
 }
@@ -119,6 +131,18 @@ export interface SolutionItem {
   state: 'applied' | 'changed' | 'new'
 }
 
+/**
+ * Whether the runtime has the Blueprint's current files: the tree hash `local
+ * dev` recorded after its last successful publish, against the files now. Null
+ * when the project has no Blueprint.
+ */
+export function blueprintApplyState(project: LocalProject, organizationId: string | null): SolutionItem['state'] | null {
+  const now = treeHash(join(project.root, 'blueprint'))
+  if (!now) return null
+  const was = organizationId ? loadHashes(project, organizationId).get('blueprint') : undefined
+  return was === undefined ? 'new' : was === now ? 'applied' : 'changed'
+}
+
 /** Each file `local dev` applies, and whether the runtime has its current content. */
 export function solutionStatus(project: LocalProject, organizationId: string | null): SolutionItem[] {
   const applied = organizationId ? loadHashes(project, organizationId) : new Map<string, string | null>()
@@ -133,3 +157,310 @@ export function solutionStatus(project: LocalProject, organizationId: string | n
     }
   })
 }
+
+// ── The build: what each target's last apply came to (design §9) ─────────────
+
+/**
+ * `local dev` records each target's outcome in `.frontera/local/build.json`,
+ * beside the hashes, so Forge and Studio say on the item itself whether it
+ * runs, and why not, without the runtime running and without a log:
+ *
+ *   built     the runtime has it as the files define it
+ *   adapted   it has it with listed adaptations (no computer, a model swapped, an Action switched off)
+ *   stubbed   it has it with a stand-in for what only the platform reaches (a built-in connection)
+ *   blocked   it waits for another item, named (`workflow/telco-fault-triage`); it is applied
+ *             again once that one builds (the retry fixpoint in `local dev`)
+ *   failed    the runtime refused it; its error, cleaned to one line
+ *
+ * Like the hashes, it is kept per local organization.
+ */
+export type BuildStatus = 'built' | 'adapted' | 'stubbed' | 'blocked' | 'failed'
+
+export interface BuildEntry {
+  /** What `local dev` calls it: "workflow telco-fault-triage". */
+  what: string
+  status: BuildStatus
+  /** adapted, stubbed: each adaptation in words. */
+  adaptations?: string[]
+  /** blocked: what it waits for, as references (`workflow/telco-fault-triage`, `action/resetLine`). */
+  needs?: string[]
+  /** blocked: it names governed Actions only by the platform's id. */
+  unnamedActions?: number
+  /** failed: the runtime's error, one line. */
+  error?: string
+  /** The content hash the outcome is for. */
+  hash: string | null
+  at: string
+  /** The Blueprint: each object type as the runtime holds it. */
+  objects?: Record<string, { status: 'built' | 'adapted' | 'stubbed' | 'left-off'; adaptations?: string[] }>
+  /** The Blueprint: each governed Action, deployed (`runs`) or not, with why. */
+  actions?: Record<string, { status: 'runs' | 'switched-off' | 'failed' | 'left-off'; reason?: string }>
+}
+
+interface BuildFile {
+  version: 1
+  organizationId: string
+  updatedAt: string
+  items: Record<string, BuildEntry>
+  /** Where the runtime's organization settings differ from the workspace's, in words (`local-org-settings.ts`). */
+  settings?: { differences: string[]; at: string }
+}
+
+function readBuildFile(project: LocalProject, organizationId: string): Partial<BuildFile> | null {
+  try {
+    const saved = JSON.parse(readFileSync(buildPath(project), 'utf8')) as Partial<BuildFile>
+    return saved.version === 1 && saved.organizationId === organizationId ? saved : null
+  } catch {
+    return null
+  }
+}
+
+/** The settings the runtime holds differently from the workspace, as `local dev` last compared them. */
+export function loadSettingsDifferences(project: LocalProject, organizationId: string | null): string[] {
+  return (organizationId ? readBuildFile(project, organizationId)?.settings?.differences : undefined) ?? []
+}
+
+/** Record where the runtime's settings differ from the workspace's. Never throws. */
+export function recordSettingsDifferences(project: LocalProject, organizationId: string, differences: string[]): void {
+  const saved = readBuildFile(project, organizationId)
+  try {
+    const file: BuildFile = { version: 1, organizationId, updatedAt: new Date().toISOString(), items: saved?.items ?? {}, settings: { differences, at: new Date().toISOString() } }
+    writeFileAtomic(buildPath(project), `${JSON.stringify(file, null, 2)}\n`, 0o644)
+  } catch {
+    // The summary only misses the line until the next \`local dev\`.
+  }
+}
+
+function buildPath(project: LocalProject): string {
+  return join(project.stateDir, 'build.json')
+}
+
+/** The last build's outcome per target key; empty for another organization (after a reset) or none. */
+export function loadBuild(project: LocalProject, organizationId: string | null): Record<string, BuildEntry> {
+  if (!organizationId) return {}
+  try {
+    const saved = JSON.parse(readFileSync(buildPath(project), 'utf8')) as Partial<BuildFile>
+    if (saved.version === 1 && saved.organizationId === organizationId && saved.items) return saved.items
+  } catch {
+    // Missing or unreadable: nothing built yet.
+  }
+  return {}
+}
+
+/** Record one target's outcome (or forget it, `null`). Never throws: the build must not stop on its record. */
+export function recordBuild(project: LocalProject, organizationId: string, key: string, entry: BuildEntry | null): void {
+  const items = { ...loadBuild(project, organizationId) }
+  if (entry) items[key] = entry
+  else delete items[key]
+  const settings = readBuildFile(project, organizationId)?.settings
+  try {
+    const file: BuildFile = { version: 1, organizationId, updatedAt: new Date().toISOString(), items, ...(settings ? { settings } : {}) }
+    writeFileAtomic(buildPath(project), `${JSON.stringify(file, null, 2)}\n`, 0o644)
+  } catch {
+    // Losing it only means the home shows "not applied yet" until the next apply.
+  }
+}
+
+/** Forget the outcomes of targets the project no longer has. */
+export function pruneBuild(project: LocalProject, organizationId: string, keep: ReadonlySet<string>): void {
+  const items = loadBuild(project, organizationId)
+  for (const key of Object.keys(items)) if (!keep.has(key)) recordBuild(project, organizationId, key, null)
+}
+
+/** The reference a target is: what other files name it by. Behavior settings, tools and lessons are their Agent. */
+export function refOfTarget(target: SyncTarget): string {
+  switch (target.kind) {
+    case 'agent':
+    case 'operating':
+    case 'bindings':
+    case 'lessons':
+      return `agent/${target.slug}`
+    case 'workflow':
+      return `workflow/${target.slug}`
+    case 'function':
+      return `function/${target.key.endsWith('/') ? target.key.slice('function:'.length, -1) : basename(target.file).replace(/\.ts$/, '')}`
+    case 'dataset':
+      return `dataset/${target.apiName}`
+    case 'knowledge':
+      return `knowledge/${target.name}`
+    case 'skill':
+      return `skill/${target.name}`
+    case 'plugin':
+      return `plugin/${target.name}`
+    case 'theme':
+      return `theme/${target.name}`
+    case 'chat-app':
+      return `chat-app/${target.name}`
+    case 'app':
+      return `app/${target.name}`
+    case 'brand':
+      return 'brand'
+    case 'library':
+      return 'library'
+    case 'blueprint':
+      return 'blueprint'
+  }
+}
+
+const KIND_WORDS: Record<string, string> = {
+  agent: 'Agent',
+  workflow: 'workflow',
+  function: 'Function',
+  action: 'governed Action',
+  objectType: 'object type',
+  knowledge: 'knowledge base',
+  skill: 'skill',
+  plugin: 'Plugin',
+  model: 'model',
+  dataset: 'dataset',
+}
+
+/** `workflow/telco-fault-triage` → "workflow telco-fault-triage". */
+export function refWords(ref: string): string {
+  const at = ref.indexOf('/')
+  return at < 0 ? ref : `${KIND_WORDS[ref.slice(0, at)] ?? ref.slice(0, at)} ${ref.slice(at + 1)}`
+}
+
+/** A refusal as one line, starting with a capital: the build's own record of it. */
+export function oneLine(text: string): string {
+  const line = text.split('\n').map((l) => l.trim()).find((l) => l && !/^warning:/i.test(l)) ?? 'failed with no output'
+  const cleaned = line.replace(/^error(\s*\[[A-Z_]+\])?:\s*/i, '').replace(/\s+/g, ' ').trim()
+  const short = cleaned.length > 180 ? `${cleaned.slice(0, 177)}…` : cleaned
+  return short.charAt(0).toUpperCase() + short.slice(1)
+}
+
+/** `  warning: agents/x/agent.json names the model y…` → "Names the model y…", for the list of adaptations. */
+export function adaptationOf(warning: string): string {
+  const text = warning.replace(/^\s*warning:\s*/i, '').replace(/^(agents|workflows|functions)\/\S+\s+/, '').trim()
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+export type ItemBuildState = BuildStatus | 'not-applied'
+
+export interface ItemBuild {
+  state: ItemBuildState
+  /** A few words for the pill: "Built", "Adapted", "Blocked", "Failed", "Not applied yet". */
+  label: string
+  /** The one line that says why, when there is one: "Needs workflow telco-fault-triage". */
+  reason: string | null
+  adaptations: string[]
+}
+
+const BUILD_RANK: Record<ItemBuildState, number> = { built: 0, adapted: 1, stubbed: 2, 'not-applied': 3, blocked: 4, failed: 5 }
+const BUILD_LABEL: Record<ItemBuildState, string> = { built: 'Built', adapted: 'Adapted', stubbed: 'Stubbed', 'not-applied': 'Not applied yet', blocked: 'Blocked', failed: 'Failed' }
+
+function lower(text: string): string {
+  return text ? text.charAt(0).toLowerCase() + text.slice(1) : text
+}
+
+/**
+ * Each target's build as the home shows it, read from the project alone:
+ * the recorded outcome when it is for the files as they are now, else "not
+ * applied yet". A blocked target's reason follows what it waits for, so a
+ * chain reads as one line: "Needs workflow telco-fault-triage, which is
+ * blocked: needs governed Action resetLine, which isn’t in the project’s
+ * Blueprint".
+ */
+export function buildView(project: LocalProject, organizationId: string | null): Map<string, ItemBuild> {
+  const build = loadBuild(project, organizationId)
+  const applied = organizationId ? loadHashes(project, organizationId) : new Map<string, string | null>()
+  const targets = allTargets(project.root)
+  const byRef = new Map<string, SyncTarget[]>()
+  for (const t of targets) byRef.set(refOfTarget(t), [...(byRef.get(refOfTarget(t)) ?? []), t])
+  const hashes = new Map(targets.map((t) => [t.key, contentHash(project, t)]))
+  const blueprint = build.blueprint
+
+  const stateOf = (t: SyncTarget): { state: ItemBuildState; entry?: BuildEntry } => {
+    const entry = build[t.key]
+    const now = hashes.get(t.key) ?? null
+    if (entry && entry.hash === now) return { state: entry.status, entry }
+    // Applied before the build was recorded: it is built.
+    if (!entry && now && applied.get(t.key) === now) return { state: 'built' }
+    return { state: 'not-applied' }
+  }
+
+  /** Why a reference holds something up, in words, following at most two more links. */
+  const needWords = (ref: string, depth: number): string => {
+    const words = refWords(ref)
+    if (ref.startsWith('action/')) {
+      const action = blueprint?.actions?.[ref.slice('action/'.length)]
+      if (!action) return `${words}, which isn’t in the project’s Blueprint`
+      if (action.status === 'left-off') return `${words}, which the local runtime leaves off: ${action.reason}`
+      if (action.status === 'failed') return `${words}, which didn’t deploy: ${action.reason}`
+      return words
+    }
+    if (ref.startsWith('objectType/')) {
+      const obj = blueprint?.objects?.[ref.slice('objectType/'.length)]
+      // The Blueprint not built (failed, waiting, or never applied) holds every object type back.
+      if (blueprint && blueprint.status !== 'built' && blueprint.status !== 'adapted') return `${words}: the Blueprint ${blueprint.status === 'failed' ? 'didn’t build' : 'isn’t built yet'}`
+      if (!blueprint && existsSync(join(project.root, 'blueprint'))) return `${words}: the Blueprint isn’t built yet`
+      if (!obj) return `${words}, which isn’t in the project’s Blueprint`
+      return obj.status === 'left-off' ? `${words}, which the local runtime leaves off` : words
+    }
+    const held = byRef.get(ref)
+    if (!held?.length) return `${words}, which isn’t in this project`
+    if (depth >= 2) return words
+    const worst = held.map((t) => ({ t, ...stateOf(t) })).sort((a, b) => BUILD_RANK[b.state] - BUILD_RANK[a.state])[0]!
+    if (worst.state === 'blocked' && worst.entry) return `${words}, which is blocked: ${lower(reasonOf(worst.entry, depth + 1))}`
+    if (worst.state === 'failed') return `${words}, which failed`
+    if (worst.state === 'not-applied') return `${words}, which isn’t applied yet`
+    return words
+  }
+  const reasonOf = (entry: BuildEntry, depth: number): string => {
+    if (entry.status === 'failed') return entry.error ?? 'The runtime refused it'
+    if (entry.status === 'blocked') {
+      const needs = entry.needs ?? []
+      if (!needs.length) {
+        const n = entry.unnamedActions ?? 0
+        return `Runs ${n === 1 ? 'a governed Action' : `${n} governed Actions`} named only by the platform’s id: add an organization key and pull it again`
+      }
+      return `Needs ${needWords(needs[0]!, depth)}${needs.length > 1 ? ` (and ${needs.length - 1} more)` : ''}`
+    }
+    if (entry.status === 'adapted' || entry.status === 'stubbed') return entry.adaptations?.join('; ') ?? ''
+    return ''
+  }
+
+  const out = new Map<string, ItemBuild>()
+  for (const t of targets) {
+    const found = stateOf(t)
+    const { entry } = found
+    // Adapted only by what the runtime is missing (no runner has polled yet): it is built as its files say, with a note.
+    const state = found.state === 'adapted' && entry?.adaptations?.length && entry.adaptations.every(isEnvironmentNote) ? 'built' : found.state
+    const reason = entry ? reasonOf(entry, 0) || null : null
+    out.set(t.key, { state, label: BUILD_LABEL[state], reason, adaptations: state === 'adapted' || state === 'stubbed' ? (entry?.adaptations ?? []) : [] })
+  }
+  return out
+}
+
+/** A warning about the runtime rather than the item: it says nothing about how the item runs differently here. */
+export function isEnvironmentNote(text: string): boolean {
+  return /no automation runner has (ever )?polled/i.test(text)
+}
+
+/** Several targets as one item (an Agent: its file, its behavior settings and its tools): the worst one speaks. */
+export function combineBuilds(builds: Array<ItemBuild | undefined>): ItemBuild {
+  const present = builds.filter((b): b is ItemBuild => !!b)
+  if (!present.length) return { state: 'not-applied', label: BUILD_LABEL['not-applied'], reason: null, adaptations: [] }
+  const worst = [...present].sort((a, b) => BUILD_RANK[b.state] - BUILD_RANK[a.state])[0]!
+  const adaptations = [...new Set(present.flatMap((b) => b.adaptations))]
+  return { ...worst, adaptations, reason: worst.reason ?? (worst.state === 'adapted' || worst.state === 'stubbed' ? adaptations.join('; ') || null : null) }
+}
+
+/** How many items the home lists are in each state, for "49 built · 2 adapted · 3 blocked". */
+export function buildCounts(states: ItemBuildState[]): Record<ItemBuildState, number> {
+  const counts: Record<ItemBuildState, number> = { built: 0, adapted: 0, stubbed: 0, 'not-applied': 0, blocked: 0, failed: 0 }
+  for (const s of states) counts[s] += 1
+  return counts
+}
+
+/** The counts as one line, the problems first after what is built: "49 built · 2 adapted · 3 blocked". */
+export function buildSummaryLine(counts: Record<ItemBuildState, number>): string {
+  return [
+    counts.built ? `${counts.built} built` : '',
+    counts.adapted ? `${counts.adapted} adapted` : '',
+    counts.stubbed ? `${counts.stubbed} stubbed` : '',
+    counts.blocked ? `${counts.blocked} blocked` : '',
+    counts.failed ? `${counts.failed} failed` : '',
+    counts['not-applied'] ? `${counts['not-applied']} not applied yet` : '',
+  ].filter(Boolean).join(' · ')
+}

package/src/local/local-apps.ts

@@ -0,0 +1,156 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { RemoteItem } from './local-sync-plan'
+
+/**
+ * Custom Apps: the workspace's code Apps (a Chat App is `chat-apps/`). A
+ * pull writes each as `apps/<slug>.json`: what it is (name, description,
+ * where it is hosted), its live version's number and manifest (routing and
+ * the hosts it may reach), and the Functions it may start, by name, each
+ * with its switch. `local dev` makes the App on the local runtime and binds
+ * those Functions, so the App's calls to them are allowed here as there.
+ *
+ * Its code is its own project (a folder `frontera app pull` fills and
+ * `frontera app deploy` ships), and is not brought: the App is saved here
+ * without it, which its portability says (Adapted). Who may open it, its
+ * sign-in (audiences, roles, keys) and its addresses are the platform's:
+ * people and deployment (sync v2 design §8). Never proposed back.
+ */
+
+/** A Custom App as `/v1/sync/apps` lists it. */
+export interface AppRow {
+  id: string
+  slug: string
+  name: string
+  description?: string | null
+  hosting?: 'platform' | 'external' | null
+  version?: string | null
+  manifest?: { routing?: unknown; connectDomains?: unknown; resourceDomains?: unknown } | null
+  functions?: Array<{ function: string; enabled?: boolean }>
+}
+
+/** The project's file for one App. */
+export interface AppFile {
+  name: string
+  description?: string
+  hosting?: 'external'
+  version?: string
+  routing?: string
+  connectDomains?: string[]
+  resourceDomains?: string[]
+  functions: Array<{ function: string; enabled: boolean }>
+}
+
+export const appPath = (slug: string) => `apps/${slug}.json`
+
+/** Why an App is Adapted here, as the build and the Pull dialog say it. */
+export const APP_WITHOUT_CODE = 'Saved here with the Functions it may start, without its code: an App’s code is its own project, deployed to this runtime on its own'
+
+const strings = (v: unknown): string[] | undefined => (Array.isArray(v) && v.every((x) => typeof x === 'string') && v.length ? (v as string[]) : undefined)
+
+export function appDocument(row: AppRow): AppFile {
+  const m = row.manifest ?? null
+  return {
+    name: row.name,
+    ...(row.description ? { description: row.description } : {}),
+    ...(row.hosting === 'external' ? { hosting: 'external' as const } : {}),
+    ...(row.version ? { version: row.version } : {}),
+    ...(m && typeof m.routing === 'string' && m.routing !== 'spa' ? { routing: m.routing } : {}),
+    ...(strings(m?.connectDomains) ? { connectDomains: strings(m?.connectDomains) } : {}),
+    ...(strings(m?.resourceDomains) ? { resourceDomains: strings(m?.resourceDomains) } : {}),
+    functions: (row.functions ?? []).map((b) => ({ function: `function/${b.function}`, enabled: b.enabled !== false })),
+  }
+}
+
+/** The workspace's Custom Apps as project items. */
+export function readApps(rows: AppRow[], wanted: (ref: string) => boolean): RemoteItem[] {
+  const out: RemoteItem[] = []
+  for (const row of rows) {
+    const ref = `app/${row.slug}`
+    if (!wanted(ref)) continue
+    const doc = appDocument(row)
+    const notes = [
+      row.version ? `Its code (version ${row.version}) is its own project and stays on the platform; this file is what the App is and the Functions it may start` : 'Never deployed in the workspace; this file is what the App is and the Functions it may start',
+      row.hosting === 'external' ? 'Hosted on its own domain: its sign-in, roles and keys stay on the platform' : 'Who may open it and its addresses stay on the platform',
+    ]
+    out.push({ ref, kind: 'app', name: row.slug, title: row.name, files: { [appPath(row.slug)]: `${JSON.stringify(doc, null, 2)}\n` }, unresolved: [], notes, requires: doc.functions.map((f) => f.function), id: row.id, ...(row.version ? { version: `v${row.version}` } : {}) })
+  }
+  return out
+}
+
+type Call = (method: string, path: string, body?: unknown) => 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)}`
+}
+
+/** The Functions a project holds, by name (a file or a folder of their own). */
+function projectFunctions(root: string): string[] {
+  try {
+    return readdirSync(join(root, 'functions'))
+      .flatMap((f) => (/\.ts$/.test(f) && !/\.(test|d)\.ts$/.test(f) ? [f.replace(/\.ts$/, '')] : existsSync(join(root, 'functions', f, 'package.json')) ? [f] : []))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Save a project's App on the runtime: made (or found) by slug, named, and
+ * given the Functions its file names, each switched as the file says; a
+ * project Function the file no longer names is unbound from it. A Function
+ * the project holds but the runtime has not deployed yet holds the App back;
+ * one the project does not hold is said and left out.
+ */
+export async function applyApp(root: string, slug: string, call: Call, provides: (ref: string) => boolean): Promise<{ ok: boolean; output: string; missing?: string[] }> {
+  const path = join(root, appPath(slug))
+  if (!existsSync(path)) return { ok: false, output: `error [APP]: ${appPath(slug)} is missing` }
+  let doc: AppFile
+  try {
+    doc = JSON.parse(readFileSync(path, 'utf8')) as AppFile
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${appPath(slug)} is not valid JSON: ${(err as Error).message}` }
+  }
+  const name = typeof doc.name === 'string' && doc.name.trim() ? doc.name.trim() : slug
+  const description = typeof doc.description === 'string' ? doc.description : null
+  const ensured = await call('POST', '/v1/platform-apps/ensure', { slug, displayName: name, kind: 'code', ...(description ? { description } : {}) })
+  if (ensured.status >= 400) return { ok: false, output: `error [APP]: ${errorOf(ensured)}` }
+  const lines: string[] = []
+  if (!dataOf(ensured.body)?.created) {
+    const renamed = await call('PATCH', `/v1/platform-apps/${encodeURIComponent(String(dataOf(ensured.body)?.id ?? ''))}`, { displayName: name, description })
+    if (renamed.status >= 400) lines.push(`  warning: Its name and description could not be set here (${errorOf(renamed)})`)
+  }
+  const bindings = Array.isArray(doc.functions) ? doc.functions : []
+  const named = new Set<string>()
+  const waiting: string[] = []
+  for (const b of bindings) {
+    const fn = String(b.function ?? '').replace(/^function\//, '')
+    if (!fn) continue
+    named.add(fn)
+    const put = await call('PUT', `/v1/functions/${encodeURIComponent(fn)}/app-bindings/${encodeURIComponent(slug)}`, { enabled: b.enabled !== false })
+    if (put.status === 404) {
+      if (provides(`function/${fn}`)) waiting.push(`function/${fn}`)
+      else lines.push(`  warning: It may start Function ${fn}, which isn’t in this project: left out here`)
+      continue
+    }
+    if (put.status >= 400) return { ok: false, output: `error [APP]: Function ${fn}: ${errorOf(put)}` }
+  }
+  if (waiting.length) {
+    return { ok: false, missing: waiting, output: [`error [UNRESOLVED_REFERENCE]: ${appPath(slug)} names what this runtime does not have`, ...waiting.map((w) => `  ${w}: in the project, not applied yet`)].join('\n') }
+  }
+  // A project Function the file no longer names stops being startable by the App.
+  for (const fn of projectFunctions(root).filter((f) => !named.has(f))) {
+    const listed = await call('GET', `/v1/functions/${encodeURIComponent(fn)}/app-bindings`)
+    if (listed.status >= 400) continue
+    const rows = (dataOf(listed.body) as unknown as Array<{ appSlug?: string }> | null) ?? []
+    if (!Array.isArray(rows) || !rows.some((r) => r.appSlug === slug)) continue
+    const gone = await call('DELETE', `/v1/functions/${encodeURIComponent(fn)}/app-bindings/${encodeURIComponent(slug)}`)
+    if (gone.status >= 400 && gone.status !== 404) lines.push(`  warning: Function ${fn} could not be unbound from it (${errorOf(gone)})`)
+  }
+  lines.unshift(`  saved App ${name}${named.size ? ` (may start ${[...named].sort().join(', ')})` : ''}`)
+  return { ok: true, output: lines.join('\n') }
+}