@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-supervisor.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path'
 import {
   containerState,
   copyFromContainer,
+  dbVolumeName,
   execInContainer,
   followLogs,
   imagePresent,
@@ -13,6 +14,7 @@ import {
   runContainer,
   startContainer,
   stopContainer,
+  storageVolumeName,
 } from './local-docker'
 import {
   CATALOG_DB,
@@ -30,14 +32,15 @@ import {
   type LocalConfig,
   type LocalSecrets,
 } from './local-env'
-import { keylessEmbeddings, providerEnv } from './local-keys'
+import { localEmbeddingsReachable, providerEnv } from './local-keys'
 import { applyProviderSetup, readProviderSetup, rememberSlugs, writeProviderSetup } from './local-providers'
 import type { PortBlock } from './local-ports'
 import { startProcess, stopProcess, waitForHttp } from './local-process'
 import type { LocalProject } from './local-project'
 import { startLocalEmbeddings } from './local-embeddings'
 import { LOCAL_TRACE_KEYS, startLocalTraces } from './local-traces'
-import { copyDocs, customerDocsBundle, IMAGE_DOCS_PATH } from './local-docs'
+import { recordRuntime } from './local-runtime-history'
+import { buildDocs, checkoutDocsStale, copyDocs, customerDocsBundle, IMAGE_DOCS_PATH, writeDocsBuildMarker } from './local-docs'
 import { keepSchemas, type SchemaSource } from './local-schemas'
 import { applyModelKeys, ensureBlueprint, ensureOrgKey, ensureProviderModels, retireLocalModel, seedLocalRuntime, signIn } from './local-seed'
 import {
@@ -80,7 +83,7 @@ export const IMAGES = {
 export const containerName = (project: LocalProject, component: ComponentName) =>
   `frontera-${project.id}-${component}`
 
-export const volumeName = (project: LocalProject) => `frontera-${project.id}-db`
+export const volumeName = (project: LocalProject) => dbVolumeName(project.id)
 
 interface Running {
   children: Map<ComponentName, ChildProcess>
@@ -144,6 +147,8 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
     }
     for (const name of [...running.containers].reverse()) stopContainer(name)
     for (const c of state.components) if (c.status === 'running' || c.status === 'starting') set(c.name, { status: 'stopped' })
+    // A failed start says so where it failed (`fail`); this is the stop of a runtime that was up.
+    if (code === 0) recordRuntime(project, { event: 'stopped', at: new Date().toISOString() })
     state = { ...state, phase: 'stopped', supervisorPid: undefined }
     save()
     process.exit(code)
@@ -155,6 +160,7 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
     set(name, { status: 'failed', detail })
     state = { ...state, phase: 'failed', error: `${name}: ${detail}` }
     save()
+    recordRuntime(project, { event: 'failed', at: new Date().toISOString(), since: state.startedAt, detail: `${name}: ${detail}` })
     await shutdown(1)
   }
 
@@ -278,6 +284,7 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
     set('studio', { status: 'running', startedAt: new Date().toISOString(), pid: process.pid })
     state = { ...state, phase: 'ready', error: undefined }
     save()
+    recordRuntime(project, { event: 'started', at: new Date().toISOString(), since: state.startedAt })
   } catch (err) {
     const failing = state.components.find((c) => c.status === 'starting')?.name ?? 'service'
     await fail(failing, (err as Error).message)
@@ -393,7 +400,7 @@ async function startStorage(project: LocalProject, ports: PortBlock, secrets: Lo
       projectId: project.id,
       ports: [{ host: ports.storage, container: 9000 }],
       env: { RUSTFS_ACCESS_KEY: secrets.storageAccessKey, RUSTFS_SECRET_KEY: secrets.storageSecretKey },
-      volumes: [{ name: `frontera-${project.id}-storage`, path: '/data' }],
+      volumes: [{ name: storageVolumeName(project.id), path: '/data' }],
       memory: '256m',
       cpus: '0.5',
       args: ['server', '/data'],
@@ -462,7 +469,7 @@ async function startService(
     runnerEnabled,
     jobsEnabled,
     storageEnabled,
-    keylessEmbeddings: keylessEmbeddings(),
+    keylessEmbeddings: localEmbeddingsReachable(),
     documentationBundle: config.mode === 'source' ? customerDocsBundle(config.platformSource) : null,
   })
   const log = logPath(project, 'service')
@@ -479,6 +486,7 @@ async function startService(
     if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
     set('service', { status: 'running', pid: child.pid, startedAt: new Date().toISOString() })
     keepDocs(project, { bundle: customerDocsBundle(config.platformSource) }, log)
+    refreshCheckoutDocs(project, config.platformSource, log)
     return
   }
   const name = containerName(project, 'service')
@@ -504,7 +512,7 @@ async function startService(
   keepDocs(project, { fromContainer: (dest) => copyFromContainer(name, IMAGE_DOCS_PATH, dest) }, log)
 }
 
-/** The release's documentation, for the solution's coding agents (`local docs-mcp`). */
+/** The release's documentation, for the solution's coding agents (`frontera mcp`). */
 function keepDocs(project: LocalProject, from: { bundle?: string | null; fromContainer?: (dest: string) => boolean }, log: string): void {
   if (!from.bundle && !from.fromContainer) {
     appendFileSync(log, '[docs] no customer documentation in the platform checkout; run `bun run docs:build` there\n')
@@ -514,6 +522,36 @@ function keepDocs(project: LocalProject, from: { bundle?: string | null; fromCon
   if (problem) appendFileSync(log, `[docs] the documentation for coding agents was not copied: ${problem}\n`)
 }
 
+/**
+ * From a checkout whose documentation build is behind it (no build, guides
+ * changed since, another version): build it in the background, at low
+ * priority, and refresh the copy when it is done. Start never waits for it:
+ * the copy from the previous build serves until then, and the service rereads
+ * the checkout's publication when it changes on disk.
+ */
+function refreshCheckoutDocs(project: LocalProject, platformSource: string | undefined, log: string): void {
+  if (!platformSource) return
+  const why = checkoutDocsStale(platformSource)
+  if (!why) {
+    // Current: a failure an earlier start recorded no longer applies.
+    writeDocsBuildMarker(project, null)
+    return
+  }
+  appendFileSync(log, `[docs] ${why}; building it in the background (nice -n 10 bun run docs:build); the previous copy serves until it is done\n`)
+  // What `local status` and Forge's Docs say while it builds ("rebuilding"), and if it fails.
+  writeDocsBuildMarker(project, { state: 'building', at: new Date().toISOString(), pid: process.pid, why })
+  void buildDocs(platformSource, log).then((built) => {
+    if (!built) {
+      writeDocsBuildMarker(project, { state: 'failed', at: new Date().toISOString(), why })
+      appendFileSync(log, '[docs] the documentation build did not finish; coding agents keep the previous copy (`bun run docs:build` in the checkout shows why)\n')
+      return
+    }
+    keepDocs(project, { bundle: customerDocsBundle(platformSource) }, log)
+    writeDocsBuildMarker(project, null)
+    appendFileSync(log, '[docs] built the documentation and refreshed the copy for coding agents\n')
+  })
+}
+
 /** The formats of the project's files, for its coding agents and editors (`local schema`). Logged, never a reason to fail start. */
 async function keepFileSchemas(project: LocalProject, source: SchemaSource, log: string): Promise<void> {
   for (const problem of await keepSchemas(project, source)) appendFileSync(log, `[schemas] not kept: ${problem}\n`)

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

@@ -131,6 +131,8 @@ export function itemTitle(kind: string, name: string, files: Record<string, stri
     const own = declared(doc?.config, 'name') ?? declared(doc, 'name')
     if (own) return own
   }
+  // The workspace's own grants beyond read (`blueprint/workspace-grants.yaml`): one file, no display name.
+  if (kind === 'blueprint' && name === 'workspace-grants') return 'Workspace grants'
   if (kind === 'blueprint') {
     const [dir, apiName] = name.split('/')
     const file = Object.entries(files).find(([p]) => p.startsWith(`blueprint/${dir}/${apiName}.`))?.[1]

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

@@ -84,6 +84,13 @@ export interface RemoteItem {
    * is being read; `from`, the snapshot's copy, once fetched.
    */
   assets?: ItemAsset[]
+  /**
+   * Files the pull recovered from the item's deployed bundle because its
+   * source lacks them (a Function's imports from beside its folder), by
+   * project path. Pulled like any other file; listed so it is never mistaken
+   * for the original source.
+   */
+  recovered?: string[]
 }
 
 export interface ItemAsset {
@@ -193,6 +200,8 @@ export interface LockEntry {
   pulledAt: string
   /** Pulled with conflicts not yet resolved; the base above is still the last clean pull. */
   conflict?: LockConflict
+  /** Its files the pull recovered from the deployed bundle, not its source (`RemoteItem.recovered`). */
+  recovered?: string[]
 }
 
 /**
@@ -245,6 +254,7 @@ function sortEntry(entry: LockEntry): LockEntry {
     ...(entry.state ? { state: entry.state } : {}),
     pulledAt: entry.pulledAt,
     ...(entry.conflict ? { conflict: sortConflict(entry.conflict) } : {}),
+    ...(entry.recovered?.length ? { recovered: [...entry.recovered].sort() } : {}),
   }
 }
 
@@ -475,6 +485,7 @@ function entryFor(item: RemoteItem, now: string): LockEntry {
     ...(item.version ? { version: item.version } : {}),
     ...(item.state ? { state: item.state } : {}),
     pulledAt: now,
+    ...(item.recovered?.length ? { recovered: [...item.recovered].sort() } : {}),
   }
 }
 

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

@@ -1,13 +1,15 @@
 import { createHash } from 'node:crypto'
-import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join, posix } from 'node:path'
 
+import { ignoreInFronteraDir } from '../project-context'
 import matter from 'gray-matter'
 import { parse as parseYaml } from 'yaml'
 
 import { mimeFromPath } from '../commands/skill/bundle-commands'
 import { writeFileAtomic } from '../fs-atomic'
 import { CliError } from '../errors'
+import { readWorkspaceGrants, WORKSPACE_GRANTS_FILE, WORKSPACE_GRANTS_NAME, WORKSPACE_GRANTS_REF } from './local-workspace-grants'
 import { documentChanges, localDocuments, splitDocumentPath, type PulledDocument } from './local-knowledge-documents'
 import { QUALITY_CHECKS_FILE, qualityChecksPath, readQualityChecks } from './local-quality-checks'
 import { lessonsPath, lessonsProposal } from './local-lessons'
@@ -266,6 +268,8 @@ export function projectRefs(root: string): Map<string, { kind: SyncKind; name: s
   for (const n of dirs('skills')) if (existsSync(join(root, 'skills', n, 'SKILL.md'))) add('skill', n)
   for (const n of dirs('knowledge')) if (existsSync(join(root, 'knowledge', n, 'knowledge.json'))) add('knowledge', n)
   for (const dir of BLUEPRINT_DIRS) for (const f of dirs(`blueprint/${dir}`)) if (/\.(ya?ml|json)$/.test(f)) add('blueprint', `${dir}/${f.replace(/\.(ya?ml|json)$/, '')}`)
+  // The workspace's own grants beyond read: one Blueprint item, `blueprint/workspace-grants`.
+  if (existsSync(join(root, WORKSPACE_GRANTS_FILE))) add('blueprint', WORKSPACE_GRANTS_NAME)
   for (const f of dirs('mcp')) if (f.endsWith('.plugin.json') && f !== '.plugin.json') add('plugin', f.slice(0, -'.plugin.json'.length))
   for (const f of dirs('chat-apps')) if (f.endsWith('.json') && f !== '.json') add('chat-app', f.slice(0, -'.json'.length))
   for (const slug of dirs('agents')) if (existsSync(join(root, lessonsPath(slug)))) add('lessons', slug)
@@ -441,12 +445,15 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     else if (status === 'conflict') block('moved', BLOCK_REASON.moved)
     else if (status === 'unresolved') block('conflicts', BLOCK_REASON.conflicts)
     else if (deleted && NOT_DELETED[kind]) block('shape', NOT_DELETED[kind]!)
+    // Never proposed as a deletion: the platform refuses one, since deleting the file changes no grant.
+    else if (deleted && ref === WORKSPACE_GRANTS_REF) block('shape', `Deleting ${WORKSPACE_GRANTS_FILE} changes no grant: to take read_sensitive away, put the file back and list the type with \`permissions: [read]\``)
     else if (status === 'deleted-remote') block('workspace-deleted', BLOCK_REASON['workspace-deleted'])
     else if (deleted) {
       // Proposable: Apply deletes it there, after everything that names it is updated.
     } else if (problem) block('shape', problem)
     else if (!Object.keys(files).length) block('shape', 'No files to propose')
     else if (kind === 'blueprint' && Object.keys(files).length > 1) block('shape', `${Object.keys(files).join(' and ')}: keep one file per Blueprint artifact`)
+    else if (ref === WORKSPACE_GRANTS_REF && readWorkspaceGrants(root)?.problems.length) block('shape', readWorkspaceGrants(root)!.problems.join('; '))
     else if (assetState?.changed && entry?.revision && theirs?.revision && entry.revision !== theirs.revision && textSame) {
       // A pull never writes over an asset the folder has, so one the workspace changed since reads as a change here.
       block('moved', 'Its assets changed in the workspace since your last pull: delete the copies here to bring the workspace’s, then propose')
@@ -577,12 +584,8 @@ const REQUESTS_DIR = join(SYNC_DIR, 'requests')
 
 /** `.frontera/sync/` stays out of git, the requests with it. */
 function ignoreSync(root: string): void {
-  const ignore = join(root, '.frontera', '.gitignore')
-  mkdirSync(dirname(ignore), { recursive: true })
-  const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : ''
-  if (text.split(/\r?\n/).some((l) => l.trim() === 'sync/' || l.trim() === 'sync')) return
-  if (text) appendFileSync(ignore, `${text.endsWith('\n') ? '' : '\n'}sync/\n`)
-  else writeFileSync(ignore, 'local/\nsync/\n')
+  // A pulled or linked project: its sync state, and this machine's profile binding, stay out of git.
+  ignoreInFronteraDir(root, ['local/', 'sync/'])
 }
 
 /** The requests file for this workspace; another workspace's (a relinked project) reads as none. */

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

@@ -15,6 +15,8 @@
  * directory knows, is rewritten.
  */
 
+import { slugify } from './local-project'
+
 /**
  * `object` is an object definition an Agent's object tools work on
  * (`object/claim_ticket`), by slug; its fields travel in the Agent's file.
@@ -24,7 +26,50 @@ export type RefKind = (typeof REF_KINDS)[number]
 
 /** Names as resources are named: slugs, API names, install names. */
 const NAME = '[A-Za-z0-9][A-Za-z0-9._-]*'
-const REF = new RegExp(`^(${REF_KINDS.join('|')})/(${NAME})$`)
+/**
+ * Kinds people name in words: a saved object set ("Open work orders") and a
+ * knowledge base. A reference to one may hold the name as people say it,
+ * spaces and all (`objectSet/Open work orders`), or its name as a reference
+ * holds it (`objectSet/open-work-orders`, `refName`); both resolve.
+ */
+export const WORDED_KINDS: readonly RefKind[] = ['objectSet', 'knowledge']
+/** A worded name: no leading or trailing space, no slash, no line break. */
+const WORDS = '[A-Za-z0-9](?:[A-Za-z0-9 ._()&\'’,-]*[A-Za-z0-9._)])?'
+const PLAIN_KINDS = REF_KINDS.filter((k) => !WORDED_KINDS.includes(k))
+const REF = new RegExp(`^(?:(${PLAIN_KINDS.join('|')})/(${NAME})|(${WORDED_KINDS.join('|')})/(${WORDS}))$`)
+
+/**
+ * The pattern a whole-value reference of these kinds matches (`^(function|workflow)/<name>$`),
+ * the same one `parseRef` reads: what `local schema` tells an editor a project file may write
+ * where the runtime wants an id.
+ */
+export function refPattern(kinds: readonly RefKind[] = REF_KINDS): string {
+  const plain = kinds.filter((k) => !WORDED_KINDS.includes(k))
+  const worded = kinds.filter((k) => WORDED_KINDS.includes(k))
+  const parts = [...(plain.length ? [`(${plain.join('|')})/${NAME}`] : []), ...(worded.length ? [`(${worded.join('|')})/${WORDS}`] : [])]
+  return parts.length === 1 ? `^${parts[0]}$` : `^(?:${parts.join('|')})$`
+}
+
+/**
+ * A resource's name as a reference holds it: as it is when it is already a
+ * slug or API name, else its words made a slug (`Open work orders` →
+ * `open-work-orders`, as `slugify` makes one, at most 24 characters).
+ */
+export function refName(name: string): string {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) ? name : slugify(name) || 'unnamed'
+}
+
+/**
+ * A name's id in one kind's map: as written, or for a kind named in words,
+ * by its name as a reference holds it (`objectSet/Open work orders` finds the
+ * set the directory lists as `open-work-orders`).
+ */
+export function lookupRef(names: ReadonlyMap<string, string> | undefined, kind: RefKind, name: string): string | undefined {
+  if (!names) return undefined
+  const exact = names.get(name)
+  if (exact !== undefined || !WORDED_KINDS.includes(kind)) return exact
+  return names.get(refName(name))
+}
 /** `[[function:<id or name>]]` in guidance text, the platform's link form. */
 const LINK = new RegExp(`\\[\\[(${REF_KINDS.join('|')}):([^\\]\\s]+)\\]\\]`, 'g')
 /** `function:<id or name>` as a whole value: a procedure's tool list names its tools this way. */
@@ -37,7 +82,8 @@ export function isUuid(value: string): boolean {
 
 export function parseRef(value: string): { kind: RefKind; name: string } | null {
   const m = REF.exec(value)
-  return m ? { kind: m[1] as RefKind, name: m[2]! } : null
+  if (!m) return null
+  return m[1] ? { kind: m[1] as RefKind, name: m[2]! } : { kind: m[3] as RefKind, name: m[4]! }
 }
 
 export function formatRef(kind: RefKind, name: string): string {
@@ -147,7 +193,7 @@ export function toIds<T>(doc: T, directory: Directory): { doc: T; unresolved: Un
   const out = walk(doc, [], (s, path) => {
     const ref = parseRef(s)
     if (ref) {
-      const id = directory[ref.kind]?.get(ref.name)
+      const id = lookupRef(directory[ref.kind], ref.kind, ref.name)
       if (id) return id
       unresolved.push({ path: path.join('.'), value: s, kind: ref.kind })
       return s