@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-dev-sync.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 
 import { agentIdentity, createFlags } from './local-agent-name'
+import { widerGrants, type WorkspaceGrant } from './local-workspace-grants'
 
 /**
  * What `frontera local dev` applies when a file in the solution changes.
@@ -196,7 +197,9 @@ export function allTargets(root: string): SyncTarget[] {
     if (depth > 6 || !existsSync(dir)) return
     let names: string[]
     try {
-      names = readdirSync(dir)
+      // Sorted: the order a directory lists its files in is the file system's (macOS sorts, Linux does not),
+      // and items of one kind are applied, and listed, in this order.
+      names = readdirSync(dir).sort()
     } catch {
       return
     }
@@ -309,9 +312,11 @@ export interface Fallback {
  * as a new snapshot (`dataset create` refuses a name in use). A dataset with
  * no CSV that exists already has nothing more to load: an empty `then`.
  *
- * Only rows reach an existing dataset. A changed definition (columns, keys)
- * is a new revision of the dataset, which `local dev` does not make; after a
- * `frontera local reset` the definition is created as written.
+ * Only rows reach an existing dataset. A CSV with empty values a column of its
+ * revision does not allow is refused; `local dev` then cuts the dataset's next
+ * revision from it (`dataset revise`, which only widens nullability), binds the
+ * object types reading it to that revision and applies the Blueprint again. A
+ * column added, dropped or retyped is a new dataset, and stays refused.
  */
 export function fallbackFor(target: SyncTarget, profiles: SyncProfiles, root: string): Fallback | null {
   if (target.kind === 'agent') {
@@ -319,6 +324,8 @@ export function fallbackFor(target: SyncTarget, profiles: SyncProfiles, root: st
     const named = createFlags(agentIdentity(root, target.file))
     return { when: /NOT_FOUND/, then: [['agent', 'create', target.slug, ...named, '--profile', profiles.workspace], commandFor(target, profiles)] }
   }
+  // A workflow archived on the runtime takes no new version: restored, then pushed (the files say it is in service).
+  if (target.kind === 'workflow') return { when: /is archived, so it cannot/i, then: [['workflow', 'restore', target.slug, '--profile', profiles.workspace], commandFor(target, profiles)] }
   if (target.kind === 'dataset') {
     const doc = datasetDocument(root, target)
     const upload = doc?.csv ? [['dataset', 'upload', doc.apiName, doc.csv, '--profile', profiles.organization]] : []
@@ -342,7 +349,7 @@ export interface FollowUp {
 export function followUpsFor(
   target: SyncTarget,
   profiles: SyncProfiles,
-  opts: { publish: boolean; workspaceId: string; objectTypes: string[] },
+  opts: { publish: boolean; workspaceId: string; objectTypes: string[]; grants?: WorkspaceGrant[] },
 ): FollowUp[] {
   if (target.kind !== 'blueprint' || !opts.publish) return []
   const steps: FollowUp[] = [{
@@ -357,8 +364,24 @@ export function followUpsFor(
     ],
     alreadyDone: /no unpublished changes/i,
   }]
-  if (opts.objectTypes.length) {
-    steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...opts.objectTypes, '--profile', profiles.organization] })
+  // `blueprint/workspace-grants.yaml`: a type granted more than `read` is granted that, after the
+  // plain grants (each grant sets its whole permission list, so the plain one would undo it). A
+  // plain grant keeps what the type's grant already holds; a type the file lists as `[read]` is
+  // granted exactly that, which is how the file takes `read_sensitive` away.
+  const wider = widerGrants(opts.grants ?? [])
+  const widened = new Set([...wider.values()].flat())
+  const onlyRead = new Set((opts.grants ?? []).filter((g) => g.permissions.length <= 1).map((g) => g.objectType))
+  const plain = opts.objectTypes.filter((t) => !widened.has(t) && !onlyRead.has(t))
+  if (plain.length) {
+    steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...plain, '--profile', profiles.organization] })
+  }
+  const exactlyRead = opts.objectTypes.filter((t) => onlyRead.has(t) && !widened.has(t))
+  if (exactlyRead.length) {
+    steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...exactlyRead, '--permissions', 'read', '--profile', profiles.organization] })
+  }
+  for (const [permissions, types] of wider) {
+    const present = types.filter((t) => opts.objectTypes.includes(t))
+    if (present.length) steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...present, '--permissions', permissions, '--profile', profiles.organization] })
   }
   return steps
 }
@@ -418,3 +441,109 @@ export function describeTarget(target: SyncTarget): string {
       return 'the library installations'
   }
 }
+
+/** The Blueprint's folders: `blueprint apply` reads the model's, `local dev` saves the object sets. */
+const BLUEPRINT_FOLDERS = new Set(['object-types', 'link-types', 'shared-fields', 'semantic-types', 'metrics', 'actions', 'object-sets'])
+
+/** What an Agent's folder holds that something reads: `local dev` applies the files, `local test` the cases. */
+const AGENT_FILES = new Set(['agent.json', 'operating.json', 'bindings.json', 'lessons.yaml'])
+
+/**
+ * Why a file in one of the folders `local dev` applies is not applied, or null
+ * when it is (or is read by something else: test cases, fixtures, a
+ * Function's helpers, a knowledge base's documents). Said instead of ignoring
+ * the file in silence: `themes/acme.json` is not a theme, `themes/acme/theme.json` is.
+ */
+export function unappliedReason(root: string, rel: string): string | null {
+  const parts = rel.split(sep)
+  if (parts.some((p) => IGNORED_DIRS.has(p) || isIgnoredName(p))) return null
+  const [top, second, third] = parts
+  const name = parts[parts.length - 1]!
+  if (/^(readme|agents|claude)\.md$/i.test(name)) return null
+  // Any YAML under blueprint/ queues a Blueprint apply, which reads only the kinds' folders.
+  if (top !== 'blueprint' && targetFor(root, join(root, rel))) return null
+  switch (top) {
+    case 'themes':
+      if (parts.length === 2) return `a slide theme is themes/<name>/theme.json, with its images beside it (\`frontera local schema theme\`): move it to themes/${name.replace(/\.(json|ya?ml)$/, '')}/theme.json`
+      return `themes/${second}/ has no theme.json, so nothing in it is applied (\`frontera local schema theme\`)`
+    case 'agents':
+      if (parts.length === 2) return 'an Agent is a folder: agents/<slug>/agent.json'
+      if (third === 'evals' || third === 'fixtures') return null
+      if (parts.length === 3 && !AGENT_FILES.has(name)) {
+        return `an Agent's files are agent.json, operating.json, bindings.json (the Functions and workflows it may start, the object types it may read) and lessons.yaml, with its test cases in evals/`
+      }
+      return null
+    case 'blueprint':
+      // The workspace's own grants beyond read, applied after each publish (`local-workspace-grants.ts`).
+      if (parts.length === 2 && name === 'workspace-grants.yaml') return null
+      if (parts.length === 2) return 'a Blueprint file lives in its kind’s folder: blueprint/object-types/, link-types/, shared-fields/, semantic-types/, metrics/, actions/ or object-sets/, or is blueprint/workspace-grants.yaml (`frontera local schema` lists each)'
+      if (!BLUEPRINT_FOLDERS.has(second!)) return `blueprint/${second}/ is not a Blueprint folder; the folders are ${[...BLUEPRINT_FOLDERS].join(', ')}`
+      if (!/\.(ya?ml|json)$/.test(name)) return 'a Blueprint file is YAML or JSON'
+      if (parts.length > 3) return `a Blueprint file sits directly in blueprint/${second}/`
+      return null
+    case 'workflows':
+      if (second === 'tests') return null
+      if (parts.length > 2) return 'a workflow is workflows/<slug>.yaml, directly in workflows/ (its tests go in workflows/tests/)'
+      return 'a workflow is workflows/<slug>.yaml (or .yml, .json)'
+    case 'datasets':
+      if (parts.length > 2) return 'a dataset is datasets/<apiName>.json with its CSV beside it, directly in datasets/'
+      return 'a dataset is datasets/<apiName>.json, with datasets/<apiName>.csv beside it for a file dataset'
+    case 'knowledge':
+      if (parts.length === 2) return 'a knowledge base is a folder: knowledge/<name>/knowledge.json ({ "name": "…", "description": "…" }) with its documents beside it'
+      return `knowledge/${second}/ has no knowledge.json ({ "name": "…", "description": "…" }), so its documents are not uploaded`
+    case 'skills':
+      if (parts.length === 2) return 'a skill is a folder: skills/<name>/SKILL.md'
+      return `skills/${second}/ has no SKILL.md, so it is not pushed`
+    case 'chat-apps':
+      return 'a Chat App is chat-apps/<slug>.json, directly in chat-apps/'
+    case 'mcp':
+      return 'a Plugin is mcp/<name>.plugin.json (a stand-in mcp/<name>.stand-in.json)'
+    default:
+      return null
+  }
+}
+
+/** Every file in the applied folders that `local dev` does not apply, with why: one line each. */
+export function unappliedFiles(root: string): string[] {
+  const out: string[] = []
+  const walk = (dir: string, depth: number) => {
+    if (depth > 4 || !existsSync(dir)) return
+    let names: string[]
+    try {
+      names = readdirSync(dir).sort()
+    } catch {
+      return
+    }
+    for (const name of names) {
+      if (IGNORED_DIRS.has(name) || isIgnoredName(name)) continue
+      const path = join(dir, name)
+      let stat
+      try {
+        stat = lstatSync(path)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) {
+        const rel = relative(root, path)
+        const [top, second] = rel.split(sep)
+        // Folders whose files are not each applied: a Function's helpers, a knowledge base's documents, an App's code.
+        if (top === 'functions' || top === 'apps' || (top === 'knowledge' && second && existsSync(join(root, 'knowledge', second, 'knowledge.json')))) continue
+        if (top === 'skills' && second && existsSync(join(root, 'skills', second, 'SKILL.md'))) continue
+        if (top === 'themes' && second && existsSync(join(root, 'themes', second, 'theme.json'))) continue
+        if (top === 'knowledge' || top === 'skills' || top === 'themes') {
+          // One line for the folder, not one per document in it.
+          const why = unappliedReason(root, join(rel, '_'))
+          if (why && rel.split(sep).length === 2) out.push(`${rel}/: ${why}`)
+          continue
+        }
+        walk(path, depth + 1)
+      } else if (stat.isFile()) {
+        const rel = relative(root, path)
+        const why = unappliedReason(root, rel)
+        if (why) out.push(`${rel}: ${why}`)
+      }
+    }
+  }
+  for (const top of ['agents', 'blueprint', 'chat-apps', 'datasets', 'knowledge', 'mcp', 'skills', 'themes', 'workflows']) walk(join(root, top), 1)
+  return out
+}

package/src/local/local-docker.ts

@@ -29,7 +29,18 @@ export interface DockerRunSpec {
 
 export class DockerError extends Error {}
 
-function docker(args: string[], opts: { input?: string } = {}): { ok: boolean; out: string; err: string } {
+export type DockerResult = { ok: boolean; out: string; err: string }
+export type DockerExec = (args: string[], opts: { input?: string }) => DockerResult
+
+let dockerExec: DockerExec | null = null
+
+/** Answer every docker call with `exec` instead of the docker CLI; null restores it. For tests. */
+export function setDockerExecForTests(exec: DockerExec | null): void {
+  dockerExec = exec
+}
+
+function docker(args: string[], opts: { input?: string } = {}): DockerResult {
+  if (dockerExec) return dockerExec(args, opts)
   const res = spawnSync('docker', args, { encoding: 'utf8', input: opts.input })
   if (res.error) {
     throw new DockerError(
@@ -133,6 +144,12 @@ export function execInContainer(name: string, cmd: string[]): boolean {
   return docker(['exec', name, ...cmd]).ok
 }
 
+/** As `execInContainer`, with `input` on the command's stdin when given, and what it printed. */
+export function queryInContainer(name: string, cmd: string[], input?: string): { ok: boolean; out: string } {
+  const res = docker(['exec', ...(input === undefined ? [] : ['-i']), name, ...cmd], input === undefined ? {} : { input })
+  return { ok: res.ok, out: res.out }
+}
+
 /** Follow a container's logs into a file for as long as the container lives. */
 export function followLogs(name: string, logFile: string): void {
   const fd = openSync(logFile, 'a')
@@ -144,3 +161,20 @@ export function containersForProject(projectId: string): string[] {
   const r = docker(['ps', '-a', '--filter', `label=${PROJECT_LABEL}=${projectId}`, '--format', '{{.Names}}'])
   return r.ok && r.out ? r.out.split('\n') : []
 }
+
+/** A local runtime's database volume, by its id (the key of its port block). */
+export const dbVolumeName = (projectId: string) => `frontera-${projectId}-db`
+
+/** A local runtime's file storage volume, by its id. */
+export const storageVolumeName = (projectId: string) => `frontera-${projectId}-storage`
+
+/**
+ * Delete a local runtime's containers and volumes, by its id: the containers
+ * labelled for it, running or not, and its database and storage volumes. Its
+ * data is gone afterwards.
+ */
+export function removeRuntimeResources(projectId: string): void {
+  for (const name of containersForProject(projectId)) removeContainer(name)
+  removeVolume(dbVolumeName(projectId))
+  removeVolume(storageVolumeName(projectId))
+}

package/src/local/local-docs-search.ts

@@ -1,5 +1,5 @@
 /**
- * Full-text search over a documentation publication, for `local docs-mcp`.
+ * Full-text search over a documentation publication, for `frontera mcp`.
  * The same ranking the platform's documentation search uses (title, aliases,
  * description, the best matching section, prefix matches), kept here because
  * the CLI is published on its own and cannot import the service.

package/src/local/local-docs.ts

@@ -1,4 +1,5 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs'
+import { spawn } from 'node:child_process'
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { createInterface } from 'node:readline'
 
@@ -10,7 +11,7 @@ import { isSchemaKind, SCHEMA_FILES, SCHEMA_KINDS, type SchemaKind } from './loc
  * Frontera's documentation for the coding agents working in a project
  * (Claude Code, Codex, Cursor). `local start` copies the customer publication
  * of the release the runtime runs into the runtime's state, and
- * `frontera local docs-mcp` serves it over MCP on stdio, straight from that
+ * `frontera mcp` serves it over MCP on stdio, straight from that
  * file: no key, no request to the runtime, and it keeps working while the
  * runtime is stopped. The formats of the project's files (`local-schemas.ts`)
  * are served the same way, from the copies `local start` keeps.
@@ -28,6 +29,284 @@ export function customerDocsBundle(platformSource: string | undefined): string |
   return existsSync(path) ? path : null
 }
 
+/** What `local status` says about the documentation a project's coding agents read. */
+export interface DocsStatus {
+  /** The copy is there and readable. */
+  present: boolean
+  /** The product version the copy documents (`productVersion`). */
+  version: string | null
+  /** The runtime's version: the checkout's in source mode, the release's in image mode. */
+  runtimeVersion: string
+  builtAt: string | null
+  /** The copy documents another version, or (source mode) the checkout's guides changed since it was built. */
+  stale: boolean
+  /** `local start` is rebuilding the checkout's documentation now; the copy is refreshed when it is done. */
+  rebuilding?: boolean
+  /** The last rebuild at start failed: the copy stays as it was. */
+  rebuildFailed?: boolean
+  /** In words, when there is something to say: why it is stale, or that there is none. */
+  note: string | null
+}
+
+/**
+ * The version a platform checkout is at (its root `package.json`): what a
+ * runtime started from it runs, recorded as the runtime's version at start.
+ */
+export function checkoutVersion(platformSource: string): string | null {
+  return readVersion(join(platformSource, 'package.json'))
+}
+
+/**
+ * The version a runtime records at start, which the Runtime page, `local
+ * status` and the Docs note all say: from a checkout, the checkout's version
+ * at this start, never one kept from an earlier start (run 8: started from a
+ * 1.52.33 checkout, the runtime said 1.52.31, its first start's version); from
+ * a release image, the release asked for, else the one an earlier image start
+ * used, else this CLI's.
+ */
+export function versionAtStart(o: { checkout: string | null; flag: string | undefined; previous: { mode: 'source' | 'image'; platformVersion: string } | null; cli: string }): string {
+  if (o.checkout) return o.checkout
+  return o.flag ?? (o.previous?.mode === 'image' ? o.previous.platformVersion : undefined) ?? o.cli
+}
+
+function readVersion(path: string): string | null {
+  try {
+    const v = (JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown }).version
+    return typeof v === 'string' ? v : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The guides' sources the customer publication is built from. The internal
+ * pages (`content/internal`) ship only in the internal distribution, so a
+ * change there never makes the customer copy out of date.
+ */
+const GUIDE_PATHS = ['packages/docs-content/content', 'packages/docs-content/catalog', 'packages/docs-content/identity', ':(exclude)packages/docs-content/content/internal']
+
+/**
+ * Whether the guides in a platform checkout changed since the commit a
+ * publication was built from (committed or not, new files included). A
+ * build reads the working tree, not the commit, so with `builtAt` a file
+ * that differs from the commit counts only when it changed after the build
+ * (by its modification time): an edit already in the build is not a reason
+ * to say the copy is behind. Null when it cannot tell (no git, a commit the
+ * checkout does not have).
+ */
+export function guidesChangedSince(platformSource: string, commit: string, builtAt?: string | null): boolean | null {
+  if (!/^[0-9a-f]{7,64}$/i.test(commit)) return null
+  const known = Bun.spawnSync(['git', '-C', platformSource, 'cat-file', '-e', `${commit}^{commit}`], { stdout: 'ignore', stderr: 'ignore' })
+  if (known.exitCode !== 0) return null
+  const diff = Bun.spawnSync(['git', '-C', platformSource, 'diff', '--name-only', commit, '--', ...GUIDE_PATHS], { stdout: 'pipe', stderr: 'ignore' })
+  if (diff.exitCode !== 0) return null
+  const added = Bun.spawnSync(['git', '-C', platformSource, 'ls-files', '--others', '--exclude-standard', '--', ...GUIDE_PATHS], { stdout: 'pipe', stderr: 'ignore' })
+  const paths = [...diff.stdout.toString().split('\n'), ...(added.exitCode === 0 ? added.stdout.toString().split('\n') : [])].map((l) => l.trim()).filter(Boolean)
+  if (!paths.length) return false
+  const built = builtAt ? Date.parse(builtAt) : NaN
+  if (!Number.isFinite(built)) return true
+  return paths.some((rel) => changedAfter(join(platformSource, rel), built))
+}
+
+/** A file changed after `at` (ms): its modification time, or, removed, its folder's. */
+function changedAfter(path: string, at: number): boolean {
+  try {
+    return statSync(path).mtimeMs > at
+  } catch {
+    try {
+      return statSync(dirname(path)).mtimeMs > at
+    } catch {
+      return true
+    }
+  }
+}
+
+/** Where `local start` says how its rebuild of the checkout's documentation is going: building, or failed. */
+export function docsBuildMarkerPath(project: LocalProject): string {
+  return join(project.stateDir, 'docs', 'rebuild.json')
+}
+
+export interface DocsBuildMarker {
+  state: 'building' | 'failed'
+  /** When the rebuild started, or failed. */
+  at: string
+  /** The process building it (the runtime's supervisor): a marker whose process is gone is not building. */
+  pid?: number
+  /** Why it was rebuilt. */
+  why?: string
+}
+
+export function readDocsBuildMarker(project: LocalProject): DocsBuildMarker | null {
+  try {
+    const m = JSON.parse(readFileSync(docsBuildMarkerPath(project), 'utf8')) as DocsBuildMarker
+    return m && (m.state === 'building' || m.state === 'failed') && typeof m.at === 'string' ? m : null
+  } catch {
+    return null
+  }
+}
+
+/** Say a rebuild is under way or failed; null clears it (it built). Never throws: the marker is only for what status says. */
+export function writeDocsBuildMarker(project: LocalProject, marker: DocsBuildMarker | null): void {
+  const path = docsBuildMarkerPath(project)
+  try {
+    if (!marker) return rmSync(path, { force: true })
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, `${JSON.stringify(marker)}\n`)
+  } catch {
+    // Status falls back to what the copy says.
+  }
+}
+
+function processAlive(pid: number | undefined): boolean {
+  if (!pid) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/**
+ * A current build in the checkout that is newer than the project's copy
+ * (someone ran `bun run docs:build` there after the runtime started): copy
+ * it in, as the next start would, so the copy and its status follow the
+ * checkout. Returns whether it copied.
+ */
+export function refreshDocsFromCheckout(project: LocalProject, platformSource: string | undefined, changedSince: typeof guidesChangedSince = guidesChangedSince): boolean {
+  const bundle = customerDocsBundle(platformSource)
+  if (!bundle || !platformSource) return false
+  const builtAtOf = (path: string): number => {
+    try {
+      const at = (JSON.parse(readFileSync(path, 'utf8')) as { builtAt?: unknown }).builtAt
+      return typeof at === 'string' ? Date.parse(at) : NaN
+    } catch {
+      return NaN
+    }
+  }
+  const theirs = builtAtOf(bundle)
+  const ours = builtAtOf(docsCopyPath(project))
+  if (!Number.isFinite(theirs) || (Number.isFinite(ours) && theirs <= ours)) return false
+  if (checkoutDocsStale(platformSource, changedSince)) return false
+  return copyDocs({ project, bundle }) === null
+}
+
+/**
+ * The documentation copy against the runtime it was copied for. `local
+ * start` copies what the checkout last built and, when that build is
+ * behind the checkout, rebuilds it in the background and copies it again;
+ * this says plainly when the copy documents another version, or guides
+ * changed since, instead of serving it silently, and whether that rebuild
+ * is running or failed. A newer current build in the checkout is copied in
+ * first (`refreshDocsFromCheckout`). The fix it names fits the runtime: a
+ * platform checkout's build only in source mode. Versions compare like with
+ * like: the copy's against the version the running runtime recorded at start.
+ */
+export function docsStatus(project: LocalProject, runtime: { mode: 'source' | 'image'; platformVersion: string; platformSource?: string }, changedSince: typeof guidesChangedSince = guidesChangedSince): DocsStatus {
+  // The runtime's version is the one it recorded when it started (`state.platformVersion`), as the Runtime page and
+  // `local status` say it: never the checkout's version now, which a pull can move while the runtime runs (run 8 said
+  // "the runtime is 1.52.33" beside a Runtime page saying 1.52.31).
+  const runtimeVersion = runtime.platformVersion
+  if (runtime.mode === 'source') refreshDocsFromCheckout(project, runtime.platformSource, changedSince)
+  const publication = loadDocs(docsCopyPath(project)) as (DocsPublication & { productVersion?: string; sourceCommit?: string; builtAt?: string }) | null
+  const marker = runtime.mode === 'source' ? readDocsBuildMarker(project) : null
+  const rebuilding = marker?.state === 'building' && processAlive(marker.pid)
+  const rebuildFailed = marker?.state === 'failed'
+  const restart = '`frontera local stop`, then `frontera local start`'
+  if (!publication) {
+    return {
+      present: false,
+      version: null,
+      runtimeVersion,
+      builtAt: null,
+      stale: false,
+      ...(rebuilding ? { rebuilding: true } : {}),
+      note: rebuilding
+        ? 'rebuilding — `frontera local start` is building it in the background; it is here when that is done'
+        : runtime.mode === 'source'
+          ? `none: build it in the platform checkout (\`bun run docs:build\`), then ${restart}`
+          : 'none: this release’s service image carries no documentation',
+    }
+  }
+  const version = typeof publication.productVersion === 'string' ? publication.productVersion : null
+  const builtAt = typeof publication.builtAt === 'string' ? publication.builtAt : null
+  const reasons: string[] = []
+  if (version && version !== runtimeVersion) reasons.push(`it documents ${version}, and the runtime is ${runtimeVersion}`)
+  if (runtime.mode === 'source' && runtime.platformSource && typeof publication.sourceCommit === 'string' && changedSince(runtime.platformSource, publication.sourceCommit, builtAt)) {
+    reasons.push(`the checkout’s guides changed since it was built (from ${publication.sourceCommit.slice(0, 9)})`)
+  }
+  const stale = reasons.length > 0
+  if (stale && rebuilding) {
+    return { present: true, version, runtimeVersion, builtAt, stale, rebuilding: true, note: `rebuilding — ${reasons.join('; ')}: \`frontera local start\` is building it in the background and refreshes the copy when it is done; the copy here serves until then` }
+  }
+  const fix =
+    runtime.mode === 'image'
+      ? `: ${restart} copies this release’s documentation`
+      : rebuildFailed
+        ? `: the rebuild at start failed (\`frontera local logs service\` shows why); run \`bun run docs:build\` in the platform checkout, then ${restart}`
+        : `: ${restart} rebuilds it in the background and refreshes the copy (see \`frontera local logs service\`), or run \`bun run docs:build\` in the platform checkout`
+  return { present: true, version, runtimeVersion, builtAt, stale, ...(stale && rebuildFailed ? { rebuildFailed: true } : {}), note: stale ? `out of date — ${reasons.join('; ')}${fix}` : null }
+}
+
+/**
+ * Why a platform checkout's customer publication is behind the checkout, or
+ * null when it is current (or that cannot be told): no build yet, guides
+ * changed since the commit it was built from, or another version.
+ */
+export function checkoutDocsStale(platformSource: string, changedSince: typeof guidesChangedSince = guidesChangedSince): string | null {
+  const bundle = join(platformSource, 'packages', 'docs-content', 'dist', 'customer', 'publication.json')
+  if (!existsSync(bundle)) return 'the checkout has no documentation build'
+  let publication: { productVersion?: unknown; sourceCommit?: unknown; builtAt?: unknown } | null = null
+  try {
+    publication = JSON.parse(readFileSync(bundle, 'utf8')) as { productVersion?: unknown; sourceCommit?: unknown; builtAt?: unknown }
+  } catch {
+    return 'the checkout’s documentation build could not be read'
+  }
+  const version = readVersion(join(platformSource, 'package.json'))
+  if (typeof publication?.productVersion === 'string' && version && publication.productVersion !== version) return `the checkout’s documentation build documents ${publication.productVersion}, and the checkout is ${version}`
+  if (typeof publication?.sourceCommit === 'string' && changedSince(platformSource, publication.sourceCommit, typeof publication.builtAt === 'string' ? publication.builtAt : null)) return `the checkout’s guides changed since its documentation was built (from ${publication.sourceCommit.slice(0, 9)})`
+  return null
+}
+
+/** Marks a documentation build in a checkout, so two runtimes started from it don't build at once. */
+const DOCS_BUILD_LOCK = ['packages', 'docs-content', 'dist', '.frontera-docs-build']
+
+function lockHolder(path: string): number | null {
+  try {
+    const pid = Number(readFileSync(path, 'utf8').trim())
+    if (!Number.isInteger(pid) || pid <= 0) return null
+    process.kill(pid, 0)
+    return pid
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build the checkout's documentation at low priority (`nice -n 10 bun run
+ * docs:build`), logging to `logFile`; resolves whether it built. Resolves
+ * false at once when another build of this checkout is running.
+ */
+export function buildDocs(platformSource: string, logFile: string): Promise<boolean> {
+  const lock = join(platformSource, ...DOCS_BUILD_LOCK)
+  if (lockHolder(lock)) {
+    appendFileSync(logFile, '[docs] another runtime is building this checkout’s documentation; the copy is refreshed at the next start\n')
+    return Promise.resolve(false)
+  }
+  mkdirSync(dirname(lock), { recursive: true })
+  return new Promise((done) => {
+    const fd = openSync(logFile, 'a')
+    const child = spawn('nice', ['-n', '10', 'bun', 'run', 'docs:build'], { cwd: platformSource, stdio: ['ignore', fd, fd] })
+    if (child.pid) writeFileSync(lock, String(child.pid))
+    const finish = (ok: boolean) => {
+      rmSync(lock, { force: true })
+      done(ok)
+    }
+    child.on('error', () => finish(false))
+    child.on('exit', (code) => finish(code === 0))
+  })
+}
+
 /** Where the service image carries its customer publication. */
 export const IMAGE_DOCS_PATH = '/app/documentation/publication.json'
 

package/src/local/local-empty-workflows.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { allTargets } from './local-dev-sync'
+import { readSnapshot } from './local-sync-snapshot'
+
+/**
+ * Workflows with no steps. One applies (the runtime takes an empty workflow
+ * as written) and every surface would mark it Applied, but a run does
+ * nothing: a placeholder made in Studio and never filled in, or a pull of
+ * one. Said as a warning beside its state, with what fixes it, by
+ * `local status`, `local dev`, Forge's home and Activity alike.
+ */
+export function emptyWorkflows(root: string): string[] {
+  const slugs = new Set<string>()
+  for (const target of allTargets(root)) {
+    if (target.kind !== 'workflow') continue
+    try {
+      const text = readFileSync(join(root, target.file), 'utf8')
+      const doc = (target.file.endsWith('.json') ? JSON.parse(text) : parseYaml(text)) as { nodes?: unknown; steps?: unknown } | null
+      if (!doc || typeof doc !== 'object') continue
+      const steps = doc.nodes ?? doc.steps
+      if (steps === undefined || steps === null || (Array.isArray(steps) && steps.length === 0)) slugs.add(target.slug)
+    } catch {
+      // A file that doesn't parse fails its apply, which says why.
+    }
+  }
+  return [...slugs].sort()
+}
+
+/**
+ * The workflows of the workspace this project was pulled from, as its pull
+ * index (`.frontera/sync/remote.json`) knows them at the last fetch: how
+ * many it has (archived ones aside) and which are not in the project. Null
+ * when there is no index, or it never read workflows: then nothing is said.
+ */
+export interface WorkspaceWorkflows {
+  total: number
+  pulled: number
+  /** How many workflows the project holds now, pulled or made here: the count its home lists. */
+  here: number
+  /** Listed by the index without their file here, by slug; with no definition to file (`empty`) or not pulled. */
+  notHere: Array<{ slug: string; why: 'not-pulled' | 'no-definition' }>
+  fetchedAt: string
+}
+
+export function workspaceWorkflows(root: string): WorkspaceWorkflows | null {
+  const snap = readSnapshot(root)
+  if (!snap || !snap.kinds?.includes('workflow')) return null
+  const notHere: WorkspaceWorkflows['notHere'] = []
+  let pulled = 0
+  for (const [ref, item] of Object.entries(snap.items)) {
+    if (item.kind !== 'workflow') continue
+    if (item.files.length && item.files.every((f) => existsSync(join(root, f)))) pulled++
+    else notHere.push({ slug: ref.replace(/^workflow\//, ''), why: 'not-pulled' })
+  }
+  for (const ref of Object.keys(snap.skipped ?? {})) if (ref.startsWith('workflow/') && !snap.items[ref]) notHere.push({ slug: ref.slice('workflow/'.length), why: 'no-definition' })
+  const here = Math.max(pulled, new Set(allTargets(root).filter((t) => t.kind === 'workflow').map((t) => t.slug)).size)
+  return { total: pulled + notHere.length, pulled, here, notHere: notHere.sort((a, b) => a.slug.localeCompare(b.slug)), fetchedAt: snap.fetchedAt }
+}
+
+/**
+ * Where the project's workflows came from, counted from the project's side so
+ * the number matches the home's ("Workflows 2"): "1 of this project's 2
+ * workflows came from the workspace it was pulled from (at the last fetch,
+ * …); the other was made here, and the workspace has no other workflow to
+ * pull." Run 8 read "has 1 workflow …; 1 is in this project" as a wrong count
+ * beside a home listing 2.
+ */
+export function workspaceWorkflowsWords(w: WorkspaceWorkflows): string {
+  const fetched = `(at the last fetch, ${w.fetchedAt.slice(0, 10)})`
+  const made = w.here - w.pulled
+  const from = 'came from the workspace it was pulled from'
+  const lead =
+    w.pulled === w.here
+      ? `${w.here === 1 ? 'This project’s workflow' : `All ${w.here} of this project’s workflows`} ${from} ${fetched}`
+      : `${w.pulled === 0 ? 'None' : w.pulled} of this project’s ${w.here} workflows ${from} ${fetched}; ${made === 1 ? 'the other was' : `the other ${made} were`} made here`
+  if (!w.notHere.length) return `${lead}, and the workspace has no other workflow to pull.`
+  const notPulled = w.notHere.filter((n) => n.why === 'not-pulled').map((n) => n.slug)
+  const empty = w.notHere.filter((n) => n.why === 'no-definition').map((n) => n.slug)
+  return `${lead}. ${[
+    notPulled.length ? `Not pulled from the workspace: ${notPulled.join(', ')} (\`frontera local sync pull ${notPulled.map((s) => `workflow/${s}`).join(' ')}\` brings ${notPulled.length === 1 ? 'it' : 'them'})` : '',
+    empty.length ? `${notPulled.length ? 'listed' : 'Listed'} there without a definition to file: ${empty.join(', ')}` : '',
+  ].filter(Boolean).join('; ')}.`
+}
+
+/** The warning for one, as a row's warning line: "workflow/x: … Fix: …", with the workspace's other workflows when the pull index knows them. */
+export function emptyWorkflowLine(slug: string, workspace: WorkspaceWorkflows | null = null): string {
+  return `workflow/${slug}: has no steps, so it does nothing when it runs. Fix: add its steps (Studio's Workflows page, or nodes: in its file under workflows/), or delete the file if it is a placeholder${workspace ? `. ${workspaceWorkflowsWords(workspace)}` : ''}`
+}