@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-build-summary.ts

@@ -1,9 +1,23 @@
-import { existsSync, readdirSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { buildCounts, buildSummaryLine, buildView, combineBuilds, loadSettingsDifferences, refOfTarget, type ItemBuild, type ItemBuildState } from './local-applied'
+import { parse as parseYaml } from 'yaml'
+
+import { BUILD_LABEL, buildCounts, buildSummaryLine, buildView, combineBuilds, failureFix, loadBuild, loadSettingsDifferences, NEEDS_VALUE, refOfTarget, withSetupNeeded, type ItemBuild, type ItemBuildState, type SolutionItem } from './local-applied'
+import { agentActionGapLine, agentActionGaps } from './local-agent-action-grants'
+import { agentLeanPlugins, agentLeanPluginsLine } from './local-agent-lean-plugins'
+import { agentMissingTools, isMissingToolAdaptation, missingToolsLine } from './local-agent-missing-tools'
+import { blueprintFile } from './local-blueprint-errors'
+import { emptyWorkflowLine, emptyWorkflows, workspaceWorkflows } from './local-empty-workflows'
 import { blueprintBuild, localOrganizationId, objectStatus, projectBlueprintOutline } from './local-blueprint-outline'
+import { liveActionRuns, type LiveAction } from './local-actions'
+import type { LiveApp } from './local-app-runtime'
+import { appCodeStates, appPath, customAppFolder, type AppCodeState, type CustomAppFolder } from './local-apps'
 import { allTargets } from './local-dev-sync'
+import { functionSecretNames, hasSecretValue, type SecretPresence, workflowSecretNames } from './local-secrets'
+import { settingEffect } from './local-org-settings'
+import { readLock } from './local-sync-plan'
+import { readSnapshot } from './local-sync-snapshot'
 
 /**
  * How the last `local dev` left the project, counted one way for every
@@ -30,6 +44,11 @@ const projectOf = (root: string, id = '') => ({ root, id, stateDir: join(root, '
 export function projectItemBuilds(root: string, id = ''): Record<string, ItemBuild> | null {
   const org = localOrganizationId(root)
   if (!org) return null
+  return itemBuildsFor(root, id, org)
+}
+
+/** Each item's build by reference; with no organization (never started), every item is not applied yet. */
+function itemBuildsFor(root: string, id: string, org: string | null): Record<string, ItemBuild> {
   const view = buildView(projectOf(root, id), org)
   const byRef = new Map<string, ItemBuild[]>()
   for (const target of allTargets(root)) {
@@ -38,7 +57,39 @@ export function projectItemBuilds(root: string, id = ''): Record<string, ItemBui
     const ref = refOfTarget(target)
     byRef.set(ref, [...(byRef.get(ref) ?? []), view.get(target.key)!])
   }
-  return Object.fromEntries([...byRef].map(([ref, list]) => [ref, combineBuilds(list)]))
+  // An Agent whose instructions name Actions its grants never offer: said on its row, its state unchanged.
+  const warned = new Map<string, string[]>()
+  for (const gap of agentActionGaps(root)) warned.set(`agent/${gap.agent}`, [...(warned.get(`agent/${gap.agent}`) ?? []), agentActionGapLine(gap)])
+  // An Agent whose Plugins the lean profile leaves out (behavior, no computer): said on its row, its state unchanged.
+  for (const g of agentLeanPlugins(root)) warned.set(`agent/${g.agent}`, [...(warned.get(`agent/${g.agent}`) ?? []), agentLeanPluginsLine(g)])
+  // A workflow with no steps applies, but does nothing: said on its row, its state unchanged.
+  const empty = emptyWorkflows(root)
+  const inWorkspace = empty.length ? workspaceWorkflows(root) : null
+  for (const slug of empty) warned.set(`workflow/${slug}`, [...(warned.get(`workflow/${slug}`) ?? []), emptyWorkflowLine(slug, inWorkspace)])
+  const combined = Object.fromEntries([...byRef].map(([ref, list]) => [ref, combineBuilds(list)] as const))
+  // An Agent whose bound Functions or workflows failed to apply runs without them: a warning on its row, not an adaptation.
+  const agents = [...byRef.keys()].filter((r) => r.startsWith('agent/')).map((r) => r.slice('agent/'.length))
+  const missing = new Set<string>()
+  for (const m of agentMissingTools(root, agents, combined)) {
+    const ref = `agent/${m.agent}`
+    missing.add(ref)
+    warned.set(ref, [missingToolsLine(m), ...(warned.get(ref) ?? [])])
+  }
+  return Object.fromEntries(Object.entries(combined).map(([ref, built]) => {
+    const own = missing.has(ref) ? withoutMissingTools(built) : built
+    const warnings = warned.get(ref)
+    return [ref, warnings ? { ...own, warnings } : own]
+  }))
+}
+
+/** An Agent's build without the adaptations its missing tools recorded: they are its warning now. Adapted by nothing else, it is built. */
+function withoutMissingTools(b: ItemBuild): ItemBuild {
+  const adaptations = b.adaptations.filter((a) => !isMissingToolAdaptation(a))
+  if (adaptations.length === b.adaptations.length) return b
+  if (b.state !== 'adapted') return { ...b, adaptations }
+  // A reason that was the adaptations, said together, follows them; one of its own stays.
+  const reason = b.reason === b.adaptations.join('; ') ? adaptations.join('; ') || null : b.reason
+  return adaptations.length ? { ...b, adaptations, reason } : { ...b, state: 'built', label: BUILD_LABEL.built, reason: null, adaptations }
 }
 
 /** One item's build, with each adaptation in words: what an Agent's page says about how it runs here. */
@@ -51,22 +102,64 @@ export interface ProjectBuildSummary {
   line: string
   /** Short: "2 problems", or "All 12 built" — what to say first. */
   headline: string
-  /** Blocked and failed together: what does not run. */
+  /** Blocked, failed and needing setup together: what does not run, or fails when used. */
   problems: number
+  /** Every row but the Custom Apps not deployed here, by state: what `local dev` applies. */
   counts: Record<ItemBuildState, number>
+  /** The Custom Apps not deployed here, by their own status (`appStatus`): counted apart, as `local dev` doesn't deploy them. */
+  apps: Partial<Record<AppStatus, number>>
   /** Where the runtime's organization settings differ from the workspace's, one line each. */
   settings: string[]
+  /** Each of `settings`, with what it changes when testing here and whether it can be aligned (`settingEffect`). */
+  settingDetails: Array<{ line: string; effect: string | null; align: string | null }>
+}
+
+/** One item the build is counted over: what `status` lists, and what the summary counts, the same rows. */
+export interface BuildRow extends ItemBuild {
+  /** `agent/desk`, `workflow/claim-intake`, `objectType/Ticket`. */
+  ref: string
+  /** A Custom App's code (`app/<name>`): its folder, its last deployment here and its dev server. */
+  app?: CustomAppFolder
+  /** A Custom App's one status (`app/<name>`): deployed to this runtime, built, not built, no code, or code not pulled. */
+  appStatus?: AppStatus
+  /** A saved object set (`objectSet/<ref>`): its id on the runtime, what an App's code keeps. */
+  id?: string
+  /**
+   * A Custom App the folder says is deployed that the runtime does not have
+   * (a database restore, a reset): why, in a line. Its status is then
+   * `built` (or `not-built`), not `deployed`.
+   */
+  notOnRuntime?: string
+}
+
+/**
+ * Every item the project's build is said over, once: each item the runtime
+ * applies (Agents, workflows, Functions, skills, knowledge, Plugins, Chat
+ * Apps…), an Agent, workflow or Function whose folder is there but which was
+ * never applied, and each Blueprint object type (`objectType/<ApiName>`), as
+ * `objectStatus` judges it, `stubbed` included. An object type left off by
+ * design (it reads the platform's media) is not a row: it is not a problem to
+ * fix. Null before the runtime first started.
+ */
+export function projectBuildRows(root: string, id = '', live: ReadonlyMap<string, LiveAction> | null = null, objectSetIds: Readonly<Record<string, string>> | null = null, secrets: SecretPresence | null = null, apps: ReadonlyMap<string, LiveApp> | null = null): BuildRow[] | null {
+  const built = projectItemBuilds(root, id)
+  if (!built) return null
+  return buildRowsFrom(root, id, built, live, objectSetIds, secrets, apps)
 }
 
 /**
- * The project's build in a few numbers, over every Agent, workflow, Function
- * and Blueprint object type the project holds. An object type left off by
- * design (it reads the platform's media) is not counted: it is not a problem
- * to fix. Null before the runtime first started, or when there is nothing.
+ * The rows the first apply will be counted over, before the runtime ever
+ * started: the same rows `projectBuildRows` gives once it has, so "start the
+ * runtime to apply 290 items" and the count after it say one number.
  */
-export function projectBuildSummary(root: string, id = ''): ProjectBuildSummary | null {
-  const builds = projectItemBuilds(root, id)
-  if (!builds) return null
+export function projectRowsBeforeApply(root: string): BuildRow[] {
+  return buildRowsFrom(root, '', itemBuildsFor(root, '', null), null, null, null, null)
+}
+
+function buildRowsFrom(root: string, id: string, built: Record<string, ItemBuild>, live: ReadonlyMap<string, LiveAction> | null, objectSetIds: Readonly<Record<string, string>> | null, secrets: SecretPresence | null, liveApps: ReadonlyMap<string, LiveApp> | null): BuildRow[] {
+  // With the runtime's secrets read (`secrets`), a "Needs a value" follows the secret now, not the last apply.
+  const needs = secrets ? secretsByRef(root) : null
+  const builds = secrets && needs ? Object.fromEntries(Object.entries(built).map(([ref, b]) => [ref, withSecretsNow(b, needs.get(ref) ?? [], secrets)])) : built
   const agents = entries(join(root, 'agents')).filter((slug) => existsSync(join(root, 'agents', slug, 'agent.json')))
   const workflows = entries(join(root, 'workflows')).filter((f) => /\.ya?ml$/.test(f)).map((f) => f.replace(/\.ya?ml$/, ''))
   const functions = entries(join(root, 'functions')).flatMap((f) => {
@@ -74,33 +167,407 @@ export function projectBuildSummary(root: string, id = ''): ProjectBuildSummary
     if (/\.ts$/.test(f) && !/\.(test|d)\.ts$/.test(f) && statSync(at).isFile()) return [f.replace(/\.ts$/, '')]
     return existsSync(join(at, 'package.json')) ? [f] : []
   })
+  const rows: BuildRow[] = []
+  const seen = new Set<string>()
+  // Evaluations are run, not applied.
+  for (const [ref, b] of Object.entries(builds)) {
+    if (ref.startsWith('evaluation/')) continue
+    rows.push({ ref, ...b })
+    seen.add(ref)
+  }
+  for (const ref of [...agents.map((a) => `agent/${a}`), ...workflows.map((w) => `workflow/${w}`), ...functions.map((f) => `function/${f}`)]) {
+    if (seen.has(ref)) continue
+    rows.push({ ref, state: 'not-applied', label: 'Not applied yet', reason: null, adaptations: [] })
+    seen.add(ref)
+  }
+  // The datasets, as their own applies left them.
+  const org = localOrganizationId(root)
+  const view = buildView(projectOf(root, id), org)
+  for (const target of allTargets(root)) {
+    if (target.kind !== 'dataset') continue
+    const b = view.get(target.key)
+    if (b) rows.push({ ref: `dataset/${target.apiName}`, ...b })
+  }
   const blueprint = blueprintBuild(root)
-  const objects = projectBlueprintOutline(root, blueprint.actions).flatMap((t): ItemBuildState[] => {
-    const kind = objectStatus(t, blueprint).kind
-    return kind === 'platform-only' ? [] : [kind as ItemBuildState]
+  for (const t of projectBlueprintOutline(root, blueprint.actions)) {
+    const status = objectStatus(t, blueprint)
+    if (status.kind === 'platform-only') continue
+    const state = status.kind as ItemBuildState
+    rows.push({
+      ref: `objectType/${t.apiName}`,
+      state,
+      label: status.label,
+      reason: status.reason ?? null,
+      adaptations: state === 'adapted' || state === 'stubbed' ? [status.reason ?? status.label] : [],
+    })
+  }
+  // The rest of the Blueprint goes as the Blueprint went: each link type, metric, semantic
+  // type, shared field and saved object set is built when it applied, and fails with it.
+  const whole: Omit<ItemBuild, 'adaptations'> = blueprint.failed
+    ? { state: 'failed', label: 'Failed', reason: blueprint.failed }
+    : blueprint.applied
+      ? { state: 'built', label: 'Built', reason: null }
+      : { state: 'not-applied', label: 'Not applied yet', reason: null }
+  // A saved set's id: read from the runtime when given, else as the last Blueprint apply saved it.
+  const setIds = objectSetIds ?? loadBuild(projectOf(root, id), org).blueprint?.objectSetIds ?? {}
+  for (const [folder, kind] of BLUEPRINT_PARTS) {
+    for (const name of blueprintNames(root, folder)) {
+      const setId = kind === 'objectSet' ? setIds[name] : undefined
+      // Left off this runtime: refused (a failure, with the runtime's words) or naming a type left off.
+      const part = blueprint.parts?.[`${kind}/${name}`]
+      if (part) {
+        const reason = `Left off here: ${part.reason}`
+        rows.push(part.refused
+          ? { ref: `${kind}/${name}`, state: 'failed', label: 'Left off: the runtime refused it', reason: part.reason.replace(/^the local runtime refused it: /, ''), adaptations: [], fix: failureFix({}, blueprintFile(root, folder, name)) }
+          : { ref: `${kind}/${name}`, state: 'adapted', label: 'Left off here', reason, adaptations: [reason] })
+        continue
+      }
+      rows.push({ ref: `${kind}/${name}`, ...whole, adaptations: [], ...(setId ? { id: setId } : {}) })
+    }
+  }
+  // Each governed Action, as it was deployed here: running, switched off, or not deployed.
+  // With the runtime read (`live`, what `frontera action list` reads), its deployment decides, not the last build.
+  for (const name of blueprintNames(root, 'actions')) {
+    // Refused at the last apply, and a Blueprint file changed since: still a failure (unless the runtime runs it now),
+    // so the count doesn't drop while the change waits for `local dev`, in status and Studio alike.
+    const before = blueprint.refusedBefore?.[name]
+    const row = before && !liveActionRuns(live?.get(name))
+      ? changedSinceFailure(actionRow(before, whole))
+      : live ? liveActionRow(live.get(name), blueprint.actions?.[name], whole) : actionRow(blueprint.actions?.[name], whole)
+    // A refused or undeployed Action is fixed in its own file, as any failed item is.
+    // One deployed as the workspace runs it says what its owner fixes there, its state unchanged.
+    const inherited = row.state === 'failed' ? [] : blueprint.actions?.[name]?.inherited ?? []
+    rows.push({ ref: `action/${name}`, ...row, ...(row.state === 'failed' && !row.fix && blueprint.actions?.[name] ? { fix: failureFix({}, blueprintFile(root, 'actions', name)) } : {}), ...(inherited.length ? { warnings: inherited.map((w) => `action/${name}: ${w}`) } : {}) })
+  }
+  // Each Custom App, with one status: its code deployed to this runtime, built and not deployed, not built, not in the
+  // project, or none at all. `local dev` saves only what the App is (its file, and the Functions it may start): its
+  // code is deployed on its own, so that save is not the App's status. A save that failed is, until it is fixed.
+  for (const code of appCodeStates(root)) {
+    const ref = `app/${code.slug}`
+    const at = rows.findIndex((r) => r.ref === ref)
+    const saved = at >= 0 ? rows[at]! : null
+    const own = appStatusRow(root, code, liveApps)
+    const failed = saved && (saved.state === 'failed' || saved.state === 'blocked' || saved.state === 'needs-setup')
+    const row: BuildRow = failed ? { ...saved, appStatus: own.appStatus, ...(own.app ? { app: own.app } : {}) } : { ref, ...own, ...(saved?.warnings?.length ? { warnings: saved.warnings } : {}) }
+    if (at >= 0) rows[at] = row
+    else rows.push(row)
+  }
+  return rows
+}
+
+/** The secrets each workflow and Function names in its file, by reference (`workflow/intake`). */
+export function secretsByRef(root: string): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  for (const target of allTargets(root)) {
+    if (target.kind !== 'workflow' && target.kind !== 'function') continue
+    try {
+      const text = readFileSync(join(root, target.file), 'utf8')
+      const names = target.kind === 'function' ? functionSecretNames(text) : workflowSecretNames(parseYaml(text))
+      const ref = refOfTarget(target)
+      out.set(ref, [...new Set([...(out.get(ref) ?? []), ...names])])
+    } catch {
+      // Unreadable: it names nothing here.
+    }
+  }
+  return out
+}
+
+/**
+ * An item's build with its secrets as the runtime holds them now: a "Needs a
+ * value for X" the last apply recorded goes once X has a value, and one is
+ * added for a secret the item names that has none now (a database restore can
+ * leave a secret listed without its value). An item with nothing else
+ * adapted is built again. Only built and adapted items change: what failed or
+ * is blocked says its own reason.
+ */
+export function withSecretsNow(build: ItemBuild, needs: readonly string[], secrets: SecretPresence): ItemBuild {
+  if (build.state !== 'built' && build.state !== 'adapted' && build.state !== 'needs-setup') return build
+  const kept = build.adaptations.filter((a) => {
+    const name = NEEDS_VALUE.exec(a)?.[1]
+    return !name || !hasSecretValue(secrets, name)
   })
-  const listed = new Set([...agents.map((a) => `agent/${a}`), ...workflows.map((w) => `workflow/${w}`), ...functions.map((f) => `function/${f}`)])
-  const states: ItemBuildState[] = [
-    ...[...listed].map((ref) => builds[ref]?.state ?? 'not-applied'),
-    // The other kinds the runtime applies (skills, knowledge, Plugins, Chat Apps…); evaluations are run, not applied.
-    ...Object.entries(builds).filter(([ref]) => !listed.has(ref) && !ref.startsWith('evaluation/')).map(([, b]) => b.state),
-    ...objects,
-  ]
-  if (!states.length) return null
+  const said = new Set(kept.flatMap((a) => NEEDS_VALUE.exec(a)?.[1] ?? []))
+  const added = needs
+    .filter((n) => !said.has(n) && !hasSecretValue(secrets, n))
+    .map((n) => `Needs a value for ${n}${secrets.names.has(n) ? ': listed, but this runtime has no value for it' : ''}: set it with \`frontera secret set ${n}\` in the project folder`)
+  if (kept.length === build.adaptations.length && !added.length) return build
+  const adaptations = [...kept, ...added]
+  if (!adaptations.length) return { state: 'built', label: 'Built', reason: null, adaptations: [] }
+  // A secret still without a value: it needs setup; the rest is adapted.
+  const setup = withSetupNeeded('adapted', adaptations)
+  const state = setup?.state ?? 'adapted'
+  return { state, label: BUILD_LABEL[state], reason: setup?.reason ?? adaptations.join('; '), adaptations }
+}
+
+/**
+ * The project's files against the runtime, for `local status`: `local dev`
+ * is the next step only for files changed since their last apply. A file
+ * whose apply failed as it is now, or that waits for another item, is
+ * counted with a pointer to its Build row, which says its own reason and fix:
+ * applying the same files again changes nothing.
+ */
+export function projectFilesLines(files: SolutionItem[]): string[] {
+  // A Blueprint that applied with refused items is on the runtime: the Build lines below name what it refused.
+  const changed = files.filter((f) => (f.state === 'new' || f.state === 'changed') && !f.waiting)
+  const failed = files.filter((f) => f.state === 'failed')
+  const waiting = files.filter((f) => f.waiting)
+  const behind = changed.length + failed.length + waiting.length
+  if (!behind) return [`  Project      all ${files.length} files applied`]
+  const names = (list: SolutionItem[]) => `${list.slice(0, 6).map((f) => f.name).join(', ')}${list.length > 6 ? ` and ${list.length - 6} more` : ''}`
+  const lines = [`  Project      ${behind} of ${files.length} files not on the runtime`]
+  if (changed.length) lines.push(`    ${changed.length} changed since the last apply (${names(changed)}) — run \`frontera local dev\``)
+  // A failure that is the runtime's (no embedding model that runs), not the file's, applies again once that is fixed.
+  const notTheFile = failed.filter((f) => f.fix?.startsWith('not its file'))
+  if (failed.length) lines.push(`    ${failed.length} didn’t apply as ${failed.length === 1 ? 'it is' : 'they are'} (${names(failed)}): each one’s reason and fix are under Build; \`frontera local dev\` changes nothing until ${failed.length === 1 ? 'its file changes' : 'their files change'}${notTheFile.length ? `, except ${names(notTheFile)}: ${notTheFile.length === 1 ? 'it applies' : 'they apply'} once the runtime is fixed as ${notTheFile.length === 1 ? 'its' : 'their'} fix says` : ''}`)
+  if (waiting.length) lines.push(`    ${waiting.length} wait${waiting.length === 1 ? 's' : ''} for another item (${names(waiting)}): ${waiting.length === 1 ? 'it applies' : 'they apply'} once that one does (under Build)`)
+  return lines
+}
+
+/**
+ * A Custom App's one status, said alike by `frontera local status`, Forge
+ * and Studio: its code deployed to this runtime; built (its `out/`) and not
+ * deployed; not built; not in the project (pulled without it); or none at
+ * all (it was never deployed in the workspace). Each but the first says the
+ * command that moves it on.
+ */
+export type AppStatus = 'deployed' | 'built' | 'not-built' | 'no-code' | 'not-pulled'
+
+export const APP_STATUS_LABEL: Record<AppStatus, string> = {
+  deployed: 'Deployed to this runtime',
+  built: 'Built, not deployed',
+  'not-built': 'Not built',
+  'no-code': 'No code',
+  'not-pulled': 'Code not pulled',
+}
+
+type AppStatusRow = ItemBuild & { appStatus: AppStatus; app?: CustomAppFolder; notOnRuntime?: string }
+
+/** Why the runtime doesn't have the deployment the folder names, or null when it has it (or wasn't asked). */
+function notOnRuntimeReason(app: CustomAppFolder, live: LiveApp | undefined): string | null {
+  if (app.away) return `its deployment ${app.away.deployment} went with the database restore (${app.away.restoredAt.slice(0, 16).replace('T', ' ')})${app.deployment ? `; the runtime has ${app.deployment.id}` : ''}`
+  if (!app.deployment || !live) return null
+  if (!live.app) return `the runtime has no App by this folder's id, so deployment ${app.deployment.id} isn't there (a restore of its database, or a reset?)`
+  if (live.deployment === false) return `the runtime's App has no deployment ${app.deployment.id} (a restore of its database?)`
+  return null
+}
+
+/** A dev server that could not open the browser's session: said with what fixes it. */
+function devSessionWords(app: CustomAppFolder): string {
+  return app.devSessionError ? `; its dev server at ${app.devServer} couldn't open a session (${app.devSessionError}): reload the page, and if it still fails, restart it (\`app_dev\` stop, then start)` : ''
+}
+
+/** A Custom App with its code in the project: deployed here (and whether its code moved since), built, or not built. */
+export function customAppRow(app: CustomAppFolder, live?: LiveApp): AppStatusRow {
+  const dev = app.devServer ? `; its dev server runs at ${app.devServer}${devSessionWords(app)}` : ''
+  const gone = notOnRuntimeReason(app, live)
+  if (gone) {
+    const fix = `\`frontera app deploy\` in ${app.dir} deploys it again (\`frontera local dev\` does after a restore)`
+    return { state: 'not-applied', appStatus: app.built ? 'built' : 'not-built', label: 'Not on the runtime', reason: `Not on the runtime: ${gone}${dev}`, adaptations: [], fix, notOnRuntime: gone }
+  }
+  if (app.deployment) {
+    const moved = app.changedSinceDeploy
+    return { state: 'built', appStatus: 'deployed', label: APP_STATUS_LABEL.deployed, reason: `Deployment ${app.deployment.id}${moved ? ', and its code changed since' : ''}${dev}`, adaptations: [], ...(moved ? { fix: `\`frontera app deploy\` in ${app.dir} deploys the change` } : {}) }
+  }
+  const pulled = app.pulled ? `Pulled at version ${app.pulled.version}; ` : ''
+  if (app.built) return { state: 'not-applied', appStatus: 'built', label: APP_STATUS_LABEL.built, reason: `${pulled}${pulled ? 'its' : 'Its'} build is in ${app.dir}/out${dev}`, adaptations: [], fix: `\`frontera app deploy\` in ${app.dir}` }
+  return { state: 'not-applied', appStatus: 'not-built', label: APP_STATUS_LABEL['not-built'], reason: `${pulled}${pulled ? 'its' : 'Its'} code is in ${app.dir}${dev || ': `frontera app dev` there runs it against this runtime'}`, adaptations: [], fix: `\`frontera app deploy\` in ${app.dir} builds and deploys it` }
+}
+
+/** Any Custom App the project names, by where its code is: in its folder, not pulled, or none. */
+export function appStatusRow(root: string, code: AppCodeState, live: ReadonlyMap<string, LiveApp> | null = null): AppStatusRow {
+  if (code.code === 'folder') {
+    const app = customAppFolder(root, code.dir)
+    return { ...customAppRow(app, live?.get(app.name)), app }
+  }
+  if (code.code === 'not-pulled') {
+    return { state: 'not-applied', appStatus: 'not-pulled', label: APP_STATUS_LABEL['not-pulled'], reason: `Its code (version ${code.version}) isn’t in the project; ${appPath(code.slug)} is what the App is`, adaptations: [], fix: `\`frontera local sync pull app/${code.slug}\` brings it into apps/${code.slug}/` }
+  }
+  return { state: 'not-applied', appStatus: 'no-code', label: APP_STATUS_LABEL['no-code'], reason: `${appPath(code.slug)} describes it only: it was never deployed in the workspace, so it has no code`, adaptations: [], fix: '`frontera app init` in apps/ starts its code' }
+}
+
+/** A Custom App counted by its own status, apart from what `local dev` applies: one whose code isn't deployed here. */
+export const appNotDeployed = (r: Pick<BuildRow, 'appStatus' | 'state'>): boolean => !!r.appStatus && r.appStatus !== 'deployed' && r.state === 'not-applied'
+
+/** "2 Custom Apps not deployed here (1 built, not deployed, 1 no code)": null when every App is deployed, or there is none. */
+export function appsNotDeployedText(apps: Partial<Record<AppStatus, number>>): string | null {
+  const parts = (['built', 'not-built', 'not-pulled', 'no-code'] as const).filter((s) => apps[s]).map((s) => `${apps[s]} ${APP_STATUS_LABEL[s].charAt(0).toLowerCase()}${APP_STATUS_LABEL[s].slice(1)}`)
+  const n = (['built', 'not-built', 'not-pulled', 'no-code'] as const).reduce((sum, s) => sum + (apps[s] ?? 0), 0)
+  return n ? `${n} Custom App${n === 1 ? '' : 's'} not deployed here (${parts.join(', ')})` : null
+}
+
+/** The Custom Apps in a line, each with its status and what moves it on; null when the project has none. */
+export function appsStatusText(rows: BuildRow[]): string | null {
+  const apps = rows.filter((r) => r.appStatus)
+  if (!apps.length) return null
+  return apps
+    .map((r) => {
+      const name = r.ref.slice('app/'.length)
+      // A save of what the App is that failed here is its status until fixed, with its reason.
+      if (r.state !== 'not-applied' && r.state !== 'built') return `${name} ${r.label.toLowerCase()}${r.reason ? ` (${r.reason})` : ''}${r.fix ? `: ${r.fix}` : ''}`
+      if (r.notOnRuntime) return `${name} not on the runtime (${r.notOnRuntime})${r.app?.devSessionError ? `, its dev server can't open a session: restart it` : ''}${r.fix ? `: ${r.fix}` : ''}`
+      const status = APP_STATUS_LABEL[r.appStatus!].toLowerCase()
+      const d = r.app?.deployment
+      const deployed = d ? ` (${d.id}${d.at ? `, ${d.at.slice(0, 16).replace('T', ' ')}` : ''})${r.app!.changedSinceDeploy ? ', code changed since' : ''}` : ''
+      const pulled = r.app?.pulled && !d ? `, pulled at version ${r.app.pulled.version}` : ''
+      return `${name} ${status}${deployed}${pulled}${r.app?.devServer ? `, dev server ${r.app.devServer}${r.app.devSessionError ? ` (it couldn't open a session: reload the page, else restart it)` : ''}` : ''}${r.fix ? `: ${r.fix}` : ''}`
+    })
+    .join('; ')
+}
+
+/** The Blueprint's folders whose files are rows of their own, and the reference each is named by. */
+const BLUEPRINT_PARTS: Array<[string, string]> = [
+  ['link-types', 'linkType'],
+  ['metrics', 'metric'],
+  ['semantic-types', 'semanticType'],
+  ['shared-fields', 'sharedField'],
+  ['object-sets', 'objectSet'],
+]
+
+/** The names of a Blueprint folder's files: each file's apiName (an object set's file name). */
+function blueprintNames(root: string, folder: string): string[] {
+  return entries(join(root, 'blueprint', folder))
+    .filter((f) => /\.(ya?ml|json)$/.test(f))
+    .map((f) => f.replace(/\.(ya?ml|json)$/, ''))
+    .sort()
+}
+
+/** One governed Action's row, from how the last Blueprint build deployed it. */
+function actionRow(build: { status: string; reason?: string; refused?: boolean } | undefined, whole: Omit<ItemBuild, 'adaptations'>): ItemBuild {
+  if (!build) return { ...whole, ...(whole.state === 'built' ? { state: 'not-applied' as const, label: 'Not deployed yet' } : {}), adaptations: [] }
+  if (build.status === 'runs') return { state: 'built', label: 'Runs here', reason: null, adaptations: [] }
+  if (build.status === 'switched-off') {
+    const reason = `Switched off here: ${build.reason ?? 'it changes a system outside the local runtime'}`
+    return { state: 'stubbed', label: 'Switched off here', reason, adaptations: [reason] }
+  }
+  // The runtime refused the Action's own file: a failure to fix, with the runtime's words.
+  if (build.status === 'left-off' && build.refused) return { state: 'failed', label: 'Left off: the runtime refused it', reason: (build.reason ?? 'the local runtime refused it').replace(/^the local runtime refused it: /, ''), adaptations: [] }
+  if (build.status === 'left-off') {
+    const reason = `Left off here: ${build.reason ?? 'its object type is left off'}`
+    return { state: 'adapted', label: 'Left off here', reason, adaptations: [reason] }
+  }
+  return { state: 'failed', label: 'Didn’t deploy', reason: build.reason ?? null, adaptations: [] }
+}
+
+/** A failure from the last apply whose files changed since: still failed, said as at its last apply. */
+function changedSinceFailure(row: ItemBuild): ItemBuild {
+  return { ...row, reason: `${row.reason ?? 'The runtime refused it'} (at its last apply; its files changed since, and \`frontera local dev\` applies it again)` }
+}
+
+/**
+ * One governed Action's row from its deployment on the runtime. One the last
+ * build switched off or left off by design keeps that row when the runtime
+ * agrees; anything else not running is a failure, said with the runtime's state.
+ */
+export function liveActionRow(live: LiveAction | undefined, build: { status: string; reason?: string; refused?: boolean } | undefined, whole: Omit<ItemBuild, 'adaptations'>): ItemBuild {
+  if (build && (build.status === 'switched-off' || build.status === 'left-off') && (!live || live.deploymentStatus !== 'active')) return actionRow(build, whole)
+  if (!live) return whole.state === 'built' ? { state: 'not-applied', label: 'Not published here', reason: null, adaptations: [] } : { ...whole, adaptations: [] }
+  if (live.deploymentStatus === 'active' && (!live.availability || live.availability === 'available')) return { state: 'built', label: 'Runs here', reason: null, adaptations: [] }
+  const why = `Its deployment here is ${live.deploymentStatus}${live.availability && live.availability !== live.deploymentStatus ? ` (${live.availability})` : ''}${live.reason ? `: ${live.reason}` : ''}; \`frontera local dev\` deploys it again`
+  return { state: 'failed', label: 'Doesn’t run here', reason: build?.status === 'failed' && build.reason ? `${why} (last apply: ${build.reason})` : why, adaptations: [] }
+}
+
+/** The rows by kind, in a line: "3 Agents, 6 object types, 6 datasets, 6 link types…". */
+export function itemKindsText(rows: BuildRow[]): string {
+  const WORDS: Record<string, [string, string]> = {
+    agent: ['Agent', 'Agents'], workflow: ['workflow', 'workflows'], function: ['Function', 'Functions'], dataset: ['dataset', 'datasets'],
+    objectType: ['object type', 'object types'], linkType: ['link type', 'link types'], metric: ['metric', 'metrics'], semanticType: ['semantic type', 'semantic types'],
+    sharedField: ['shared field', 'shared fields'], objectSet: ['saved object set', 'saved object sets'], action: ['governed Action', 'governed Actions'],
+    knowledge: ['knowledge base', 'knowledge bases'], skill: ['skill', 'skills'], plugin: ['Plugin', 'Plugins'], theme: ['slide theme', 'slide themes'],
+    'chat-app': ['Chat App', 'Chat Apps'], app: ['Custom App', 'Custom Apps'],
+  }
+  const counts = new Map<string, number>()
+  for (const r of rows) {
+    const kind = r.ref.includes('/') ? r.ref.slice(0, r.ref.indexOf('/')) : r.ref
+    counts.set(kind, (counts.get(kind) ?? 0) + 1)
+  }
+  return `${rows.length} in all: ${[...counts].map(([k, n]) => `${n} ${(WORDS[k] ?? [k, k])[n === 1 ? 0 : 1]}`).join(', ')}`
+}
+
+/** The saved object sets in a line, each with its id when known: "open-work-orders 48536fc6-…"; null when the project has none. */
+export function objectSetsStatusText(rows: BuildRow[]): string | null {
+  const sets = rows.filter((r) => r.ref.startsWith('objectSet/'))
+  if (!sets.length) return null
+  return sets.map((r) => `${r.ref.slice('objectSet/'.length)} ${r.id ?? `(${r.label.toLowerCase()}, no id yet)`}`).join('; ')
+}
+
+/**
+ * The governed Actions in a line: how many, and how each was deployed here;
+ * `none` when the project has none, which the status says outright.
+ */
+export function actionsStatusText(rows: BuildRow[]): string {
+  const actions = rows.filter((r) => r.ref.startsWith('action/'))
+  if (!actions.length) return 'none (blueprint/actions/ is empty: nothing writes the Blueprint’s records)'
+  const by = (state: ItemBuildState) => actions.filter((a) => a.state === state).map((a) => a.ref.slice('action/'.length))
+  const parts = [
+    by('built').length ? `${by('built').length} run here` : '',
+    by('stubbed').length ? `${by('stubbed').length} switched off (${by('stubbed').join(', ')})` : '',
+    by('adapted').length ? `${by('adapted').length} left off (${by('adapted').join(', ')})` : '',
+    by('failed').length ? `${by('failed').length} didn’t deploy (${by('failed').join(', ')})` : '',
+    by('blocked').length ? `${by('blocked').length} blocked (${by('blocked').join(', ')})` : '',
+    by('not-applied').length ? `${by('not-applied').length} not deployed yet (${by('not-applied').join(', ')})` : '',
+  ].filter(Boolean)
+  return `${actions.length}: ${parts.join(', ')}`
+}
+
+/**
+ * The project's build in a few numbers, counted over exactly the rows
+ * `projectBuildRows` gives, so a count always matches the list beside it.
+ * Null before the runtime first started, or when there is nothing.
+ */
+export function projectBuildSummary(root: string, id = '', live: ReadonlyMap<string, LiveAction> | null = null, secrets: SecretPresence | null = null, liveApps: ReadonlyMap<string, LiveApp> | null = null): ProjectBuildSummary | null {
+  const rows = projectBuildRows(root, id, live, null, secrets, liveApps)
+  if (!rows?.length) return null
+  // A Custom App whose code isn't deployed here is counted by its own status: `local dev` doesn't deploy it.
+  const states = rows.filter((r) => !appNotDeployed(r)).map((r) => r.state)
   const counts = buildCounts(states)
+  const apps: Partial<Record<AppStatus, number>> = {}
+  for (const r of rows) if (appNotDeployed(r)) apps[r.appStatus!] = (apps[r.appStatus!] ?? 0) + 1
   const org = localOrganizationId(root)
   const settings = org ? loadSettingsDifferences(projectOf(root, id), org) : []
-  const problems = counts.blocked + counts.failed
-  const line = settings.length ? `${buildSummaryLine(counts)} · ${settings.length} setting${settings.length === 1 ? ' differs' : 's differ'} from the workspace` : buildSummaryLine(counts)
+  const problems = counts.blocked + counts.failed + counts['needs-setup']
+  const appsLine = appsNotDeployedText(apps)
+  const line = [buildSummaryLine(counts), appsLine ?? '', settings.length ? `${settings.length} setting${settings.length === 1 ? ' differs' : 's differ'} from the workspace` : ''].filter(Boolean).join(' · ')
   const headline = problems ? `${problems} problem${problems === 1 ? '' : 's'}` : counts['not-applied'] ? `${counts['not-applied']} not applied yet` : `All ${states.length} built`
-  return { line, headline, problems, counts, settings }
+  const settingDetails = settings.map((l) => {
+    const e = settingEffect(l)
+    return { line: l, effect: e?.effect ?? null, align: e?.align ?? null }
+  })
+  return { line, headline, problems, counts, apps, settings, settingDetails }
 }
 
-/** The CLI's line for the build: the problems first, then the rest, short ("2 problems: 1 failed, 1 blocked · 7 built, 3 adapted"). */
+/** The CLI's line for the build: the problems first, then the rest, short ("3 problems: 1 failed, 1 blocked, 1 needs setup · 7 built, 3 adapted"). */
 export function buildStatusText(summary: ProjectBuildSummary): string {
   const c = summary.counts
-  const problems = [c.failed ? `${c.failed} failed` : '', c.blocked ? `${c.blocked} blocked` : ''].filter(Boolean).join(', ')
+  const problems = [c.failed ? `${c.failed} failed` : '', c.blocked ? `${c.blocked} blocked` : '', c['needs-setup'] ? `${c['needs-setup']} need${c['needs-setup'] === 1 ? 's' : ''} setup` : ''].filter(Boolean).join(', ')
   const rest = [c.built ? `${c.built} built` : '', c.adapted ? `${c.adapted} adapted` : '', c.stubbed ? `${c.stubbed} stubbed` : '', c['not-applied'] ? `${c['not-applied']} not applied yet` : ''].filter(Boolean).join(', ')
   const settings = summary.settings.length ? `${summary.settings.length} setting${summary.settings.length === 1 ? ' differs' : 's differ'} from the workspace` : ''
-  return [summary.problems ? `${summary.headline}: ${problems}` : rest, summary.problems ? rest : '', settings].filter(Boolean).join(' · ')
+  const apps = appsNotDeployedText(summary.apps ?? {}) ?? ''
+  return [summary.problems ? `${summary.headline}: ${problems}` : rest, summary.problems ? rest : '', apps, settings].filter(Boolean).join(' · ')
+}
+
+/**
+ * What the linked workspace lists that the project never pulled, by kind,
+ * with the command that brings it: an App the pull index names but no
+ * `apps/<slug>.json` holds is said, not silent. Datasets (the workspace's
+ * records) never come. Empty for a project with no fetched workspace.
+ */
+export function notPulledLines(root: string): string[] {
+  const snap = readSnapshot(root)
+  if (!snap) return []
+  const held = new Set(Object.keys(readLock(root)?.items ?? {}))
+  const missing = Object.keys(snap.items).filter((ref) => !held.has(ref) && !ref.startsWith('dataset/') && !ref.startsWith('lessons/') && !ref.startsWith('blueprint/'))
+  if (!missing.length) return []
+  const byKind = new Map<string, string[]>()
+  for (const ref of missing.sort()) {
+    const kind = ref.slice(0, ref.indexOf('/'))
+    byKind.set(kind, [...(byKind.get(kind) ?? []), ref])
+  }
+  // `--kinds` takes the plural, but knowledge is its own.
+  const flagWord = (kind: string) => (kind === 'knowledge' ? kind : `${kind}s`)
+  return [...byKind].map(([kind, refs]) => `${refs.length} ${refs.length === 1 ? kind : flagWord(kind)} (${refs.slice(0, 4).join(', ')}${refs.length > 4 ? ', …' : ''}): \`frontera local sync pull ${refs.length > 4 ? `--kinds ${flagWord(kind)}` : refs.join(' ')}\``)
+}
+
+/** The knowledge bases with no documents here, each with the command that brings them (`emptyKnowledgeNote`). */
+export function emptyKnowledgeLines(rows: BuildRow[]): string[] {
+  return rows.filter((r) => r.ref.startsWith('knowledge/') && /has no documents/.test(r.reason ?? '')).map((r) => r.reason!)
 }