@frontera-sdk/cli 1.52.38 → 1.52.40

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

@@ -3,8 +3,9 @@ import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync
 import { tmpdir } from 'node:os'
 import { join, posix, relative } from 'node:path'
 
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { Document as YamlDocument, isSeq, parse as parseYaml, stringify as stringifyYaml, type YAMLMap, type YAMLSeq } from 'yaml'
 
+import { semanticFactsOf } from '../blueprint/action-semantic-fit'
 import { toFiles } from '../blueprint/projection'
 import { serialize } from '../blueprint/tree'
 import { assetFilename, toSkillMd, type SkillDoc } from '../commands/skill/bundle-commands'
@@ -20,11 +21,15 @@ import { readChatApps, type ChatAppRow } from './local-chat-apps'
 import { readApps, type AppRow as CustomAppRow } from './local-apps'
 import { readBrand, type BrandRow } from './local-brand'
 import { readLibrary, type LibraryRow } from './local-library'
+import { fromOutsidePath, outsidePath } from '../function-outside-imports'
 import { isSharedFunctionFile } from './local-function-shared'
+import { hardCodedObjectTypeIds, platformObjectTypeIds } from './local-function-ids'
+import { missingImportNote, missingImportWarning, recoverMissingImports, type MissingImports } from './local-function-recovery'
 import { attachDefinitions, type ObjectDefinitionRow } from './local-objects'
 import { checksFromFixtures, fixtureRows, qualityChecksPath, qualityChecksText, sourcePaths, sourceRows } from './local-quality-checks'
 import { readableName } from './local-sync-names'
-import { governedActionIds, invert, itemRef, referencesIn, toNames, type Directory, type RefKind } from './local-sync-refs'
+import { WORKSPACE_GRANTS_FILE, WORKSPACE_GRANTS_NAME } from './local-workspace-grants'
+import { governedActionIds, invert, itemRef, referencesIn, refName as refNameOf, toNames, type Directory, type RefKind } from './local-sync-refs'
 
 /**
  * Reading a workspace as the files a project holds. Each kind lists what the
@@ -57,9 +62,9 @@ function one<T>(body: unknown): T {
   return v as T
 }
 
-/** A resource's name as a reference can hold it: knowledge bases are named in words. */
+/** A resource's name as a reference can hold it: knowledge bases are named in words (`local-sync-refs.ts`). */
 export function refName(name: string): string {
-  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) ? name : slugify(name) || 'unnamed'
+  return refNameOf(name)
 }
 
 async function quietly<T>(warnings: string[], what: string, read: () => Promise<T>, empty: T): Promise<T> {
@@ -382,9 +387,11 @@ export interface AgentBindings {
   /**
    * Its Context and data: the object types it may read through its Blueprint
    * tools (`objectType/Incident`), with the permissions granted. Absent when
-   * it has none, or they could not be read (no organization key).
+   * it has none, or they could not be read (no organization key). An entry
+   * without `permissions` was read by name only: `local dev` and a change
+   * request then keep what the grant holds (`act`, `read_sensitive`).
    */
-  blueprint?: Array<{ objectType: string; permissions: string[] }>
+  blueprint?: Array<{ objectType: string; permissions?: string[] }>
   /**
    * Its Context and data could not be read on the platform with the project's
    * keys. `local dev` then gives it read access to the object types the
@@ -439,8 +446,10 @@ export async function readAgentContext(source: SyncSource, row: AgentRow): Promi
   // An empty answer may only mean the key can't see the Agent there, so it is not taken for "none".
   if (listed.length) {
     return {
-      grants: listed.map((n) => ({ objectType: `objectType/${n}`, permissions: ['read'] })).sort((a, b) => a.objectType.localeCompare(b.objectType)),
-      note: 'Its Context and data was read as the object types it may use: this platform doesn’t give their permissions to this key, so read is taken for each',
+      // No `permissions`: the file doesn't state what it didn't read, so applying it keeps what each grant
+      // holds. Written as `["read"]`, a change request or local dev would take a held `act` away.
+      grants: listed.map((n) => ({ objectType: `objectType/${n}` })).sort((a, b) => a.objectType.localeCompare(b.objectType)),
+      note: 'Its Context and data was read as the object types it may use: this platform doesn’t give their permissions to this key, so each is written without permissions, and applying the file keeps what each grant holds (read, and act or read_sensitive where it has them)',
     }
   }
   return { unread: refused ?? `this platform gives it only to an organization key. ${STEWARD_FIX}` }
@@ -473,6 +482,81 @@ async function readBindings(source: SyncSource, lists: Lists, warnings: string[]
   return out
 }
 
+const NO_SETTINGS = ': it runs on the defaults there, and the same defaults here; `frontera local schema operating` says what the file can set'
+
+/** Settings an Agent has: an object with at least one key. */
+function settingsIn(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length ? (value as Record<string, unknown>) : null
+}
+
+/**
+ * An Agent's behavior settings from their own route (`/v1/config/agents/:id/operating`):
+ * the live ones, or the draft's when the draft is what was read. The last
+ * place a pull looks, after the snapshot and the Agent's own record (both of
+ * which a released platform gives a workspace key, scrubbed). A note in every
+ * case: where they came from, that the Agent has none (so it is pulled
+ * without operating.json, and `local dev` uses the runtime's defaults), or why
+ * they could not be read. A released platform keeps the route to a signed-in
+ * person, so its refusal (or a platform without it) is taken for what the
+ * snapshot said: none.
+ */
+export async function readOperatingConfig(source: SyncSource, agentId: string, draft: boolean): Promise<{ config: Record<string, unknown>; note: string } | { note: string }> {
+  try {
+    const view = one<{ configured?: boolean; live?: unknown; draft?: unknown }>(await source.workspace.get(`/v1/config/agents/${encodeURIComponent(agentId)}/operating`))
+    const chosen = settingsIn(draft ? view?.draft ?? view?.live : view?.live)
+    if (chosen) return { config: chosen, note: `Its behavior settings were read from the platform${draft && view?.draft ? '’s draft' : ''} into operating.json` }
+    return { note: `Has no behavior settings in the workspace (operating.json)${NO_SETTINGS}` }
+  } catch (err) {
+    const code = err instanceof CliError ? err.code : null
+    if (code === 'UNAUTHORIZED' || code === 'FORBIDDEN' || code === 'NOT_FOUND') return { note: `Has no behavior settings in its snapshot on the platform (operating.json)${NO_SETTINGS}` }
+    return { note: `Its behavior settings couldn’t be read on the platform (${(err as Error).message.slice(0, 160)}), so no operating.json was pulled: if it has some there, they aren’t here` }
+  }
+}
+
+/**
+ * What a pull says of behavior settings without `execution.toolScopes` (as a
+ * released platform gives them): they keep the meaning tool ids had before
+ * Blueprint Actions were their own choice, here as there, and `local dev`
+ * warns about it. Null when the marker is there.
+ */
+export function legacyToolScopesNote(config: Record<string, unknown>): string | null {
+  const execution = settingsIn(config.execution) ?? {}
+  if (execution.toolScopes === 2) return null
+  return 'Its behavior settings have no `execution.toolScopes`, as the workspace keeps them, so they keep the meaning tool ids had before Blueprint Actions were their own choice (`tool:blueprint` keeps the Action tools, and a service Agent has them outside procedures), here as there; `frontera local dev` warns about it until "toolScopes": 2 is added to "execution"'
+}
+
+/**
+ * An Agent's behavior settings, from the first place that has them:
+ * 1. the snapshot that was read (`draft-v2` for a draft, else `snapshot/live`), its `config.operatingConfig`;
+ * 2. for a live read, the Agent's record (`/v1/config/agents/:id`), then the listing's row;
+ * 3. for a draft read with none, none: the draft is the whole of them;
+ * 4. only then their own route (`readOperatingConfig`).
+ */
+export async function agentOperatingConfig(
+  source: SyncSource,
+  agent: { id: string; operatingConfig?: unknown },
+  read: { snapshot: Record<string, unknown>; fromDraft: boolean; detail?: { operatingConfig?: unknown } | null },
+): Promise<{ config: Record<string, unknown> | null; notes: string[] }> {
+  const fromSnapshot = settingsIn((read.snapshot.config as Record<string, unknown> | undefined)?.operatingConfig)
+  const found = fromSnapshot ?? (read.fromDraft ? null : settingsIn(read.detail?.operatingConfig) ?? settingsIn(agent.operatingConfig))
+  const notes: string[] = []
+  let config = found
+  if (!config) {
+    if (read.fromDraft) notes.push(`Has no behavior settings in its draft (operating.json)${NO_SETTINGS}`)
+    else {
+      const route = await readOperatingConfig(source, agent.id, false)
+      if ('config' in route) config = route.config
+      notes.push(route.note)
+    }
+  }
+  const legacy = config ? legacyToolScopesNote(config) : null
+  if (legacy) notes.push(legacy)
+  return { config, notes }
+}
+
+/** An Agent's record (`/v1/config/agents/:id`): its published version, and its behavior settings, scrubbed. */
+interface AgentDetail { currentVersion?: { versionNumber?: number } | null; operatingConfig?: unknown }
+
 async function readAgents(source: SyncSource, lists: Lists, directory: Directory, opts: ReadOptions, warnings: string[], tools: () => Promise<PluginTools>): Promise<RemoteItem[]> {
   const out: RemoteItem[] = []
   const agents = lists.agents.filter((row) => wanted(opts, `agent/${row.agentId}`))
@@ -483,30 +567,36 @@ async function readAgents(source: SyncSource, lists: Lists, directory: Directory
     const wantDraft = opts.drafts?.has(ref) || !row.currentVersionId
     const it = item('agent', row.agentId, row.name, {}, { id: row.id })
     let snapshot: Record<string, unknown> | null = null
+    let detail: AgentDetail | null = null
+    let fromDraft = false
     try {
       if (wantDraft) {
         const draft = one<{ snapshot?: Record<string, unknown>; revision?: number } | null>(await source.workspace.get(`/v1/config/agents/${row.id}/draft-v2`))
         snapshot = draft?.snapshot ?? null
+        fromDraft = !!snapshot
         if (!row.currentVersionId) it.notes.push('Not published on the platform: its draft was read')
         else it.notes.push('Read from its draft, as asked')
         if (draft?.revision !== undefined) it.version = `draft ${draft.revision}`
       }
       if (!snapshot) {
         snapshot = one<Record<string, unknown>>(await source.workspace.get(`/v1/config/agents/${row.id}/snapshot/live`))
-        const detail = one<{ currentVersion?: { versionNumber?: number } | null }>(await source.workspace.get(`/v1/config/agents/${row.id}`))
+        detail = one<AgentDetail | null>(await source.workspace.get(`/v1/config/agents/${row.id}`))
         if (detail?.currentVersion?.versionNumber) it.version = `v${detail.currentVersion.versionNumber}`
       }
     } catch (err) {
       warnings.push(`Agent ${row.agentId}: ${(err as Error).message}`)
       continue
     }
-    const operating = ((snapshot.config as Record<string, unknown> | undefined)?.operatingConfig ?? (wantDraft ? null : row.operatingConfig)) as Record<string, unknown> | null
+    // Where its behavior settings are (the snapshot, the Agent's record, their own route), or that it has none, said.
+    const behavior = await agentOperatingConfig(source, row, { snapshot, fromDraft, detail })
+    const operating = behavior.config
+    it.notes.push(...behavior.notes)
     const toolSettings = Array.isArray(snapshot.appCapabilities) && snapshot.appCapabilities.length ? { apps: lists.apps, tools: await tools() } : undefined
     const agentDoc = projectAgent(snapshot, it.notes, toolSettings)
     // Its object tools carry the definitions they work on, named by slug below.
     it.notes.push(...attachDefinitions(agentDoc, lists.objectDefinitions ?? null))
     const docs: Array<{ path: string; doc: unknown; format: 'json' }> = [{ path: `agents/${row.agentId}/agent.json`, doc: agentDoc, format: 'json' }]
-    if (operating && typeof operating === 'object' && Object.keys(operating).length) docs.push({ path: `agents/${row.agentId}/operating.json`, doc: operating, format: 'json' })
+    if (operating) docs.push({ path: `agents/${row.agentId}/operating.json`, doc: operating, format: 'json' })
     const bound: AgentBindings = { ...(bindings.get(row.agentId) ?? { functions: [], workflows: [] }) }
     // Context and data comes as the Agent's dependency: each object type it names is pulled with it.
     const context = await readAgentContext(source, row)
@@ -583,15 +673,129 @@ function unpack(bytes: Uint8Array): Map<string, string> {
   }
 }
 
-/** The file and the relative files it imports, transitively, within the archive. */
-function withImports(files: Map<string, string>, entry: string): string[] {
+/** The project files a Function's folder keeps beside its code. */
+const FOLDER_PROJECT_FILES = ['package.json', 'tsconfig.json', 'bunfig.toml', 'README.md']
+
+/** The SDK's own copy inside a Function project (`function init` vendors it there); the solution keeps one in vendor/. */
+const FOLDER_SDK = /^(src\/)?frontera\//
+
+/**
+ * The entry in a folder Function's source archive: the file whose
+ * `automation({ name })` is this Function (one archive can hold every
+ * Function of a project), else `<slug>.ts`, `src/<slug>.ts`, `index.ts`,
+ * `src/index.ts`; the rule `functionEntry` applies to a project folder.
+ */
+export function archiveEntry(files: ReadonlyMap<string, string>, slug: string): string | null {
+  const code = [...files.keys()].filter((p) => p.endsWith('.ts') && !p.endsWith('.test.ts') && !p.endsWith('.d.ts') && !FOLDER_SDK.test(p)).sort()
+  const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const declares = new RegExp(`['"]?name['"]?\\s*:\\s*['"\`]${escaped}['"\`]`)
+  const named = code.find((p) => /automation\s*\(/.test(files.get(p)!) && declares.test(files.get(p)!))
+  return named ?? [`${slug}.ts`, `src/${slug}.ts`, 'index.ts', 'src/index.ts'].find((p) => files.has(p)) ?? null
+}
+
+/**
+ * What a folder Function's pull writes, relative to `functions/<slug>/`: its
+ * entry and the files it imports, its test, and the folder's project files,
+ * with the tsconfig's SDK paths pointed at the solution's `vendor/frontera/`.
+ * Without an entry, every file but the SDK copy (and `entry` is null).
+ */
+export function folderFunctionFiles(
+  files: ReadonlyMap<string, string>,
+  slug: string,
+): { entry: string | null; files: Record<string, string>; outside: Record<string, string>; missing: string[] } {
+  const entry = archiveEntry(files, slug)
+  const out: Record<string, string> = {}
+  // What it imports from outside its folder, by its path from the folder (`../shared/x.ts`): kept in
+  // the archive under `frontera-imports/` by a current deploy; `missing` when the archive lacks it.
+  const outside: Record<string, string> = {}
+  const missing: string[] = []
+  if (!entry) {
+    for (const [p, content] of files) if (!p.startsWith('.') && !FOLDER_SDK.test(p) && !fromOutsidePath(p)) out[p] = content
+  } else {
+    const code = withImports(files as Map<string, string>, entry, missing).filter((p) => !FOLDER_SDK.test(p))
+    const test = entry.replace(/\.ts$/, '.test.ts')
+    for (const p of [...code, ...(files.has(test) ? [test] : []), ...FOLDER_PROJECT_FILES.filter((f) => files.has(f))]) {
+      const beyond = fromOutsidePath(p)
+      if (beyond) outside[beyond] = files.get(p)!
+      else out[p] = files.get(p)!
+    }
+  }
+  if (out['tsconfig.json']) out['tsconfig.json'] = vendorPaths(out['tsconfig.json'])
+  Object.assign(out, sdkShims(out))
+  return { entry, files: out, outside, missing: [...new Set(missing)].sort() }
+}
+
+/** The first line of a file a pull writes to point a folder's own SDK path at the solution's copy. */
+export const SDK_SHIM_HEADER = '// Written by `frontera local sync pull`: this Function imports its folder’s own copy of the SDK, which the project keeps once, in vendor/frontera/.'
+
+/**
+ * Files that point a Function folder's own SDK copy (`./frontera/automation/testing`,
+ * which `function init` vendored beside its code) at the solution's `vendor/frontera/`.
+ * A pull leaves the folder's copy out (the project keeps one), and a relative
+ * import cannot be mapped by tsconfig `paths`; so each such import gets a file
+ * that re-exports the solution's module, and the pulled code stays as it was.
+ * Keyed by path in the folder (`src/frontera/automation/testing.ts`).
+ */
+export function sdkShims(files: Readonly<Record<string, string>>): Record<string, string> {
+  const shims: Record<string, string> = {}
+  for (const [path, text] of Object.entries(files)) {
+    if (!/\.(ts|tsx|mts)$/.test(path)) continue
+    for (const m of text.matchAll(/(?:from|import)\s*\(?\s*['"](\.{1,2}\/[^'"]+)['"]/g)) {
+      const target = posix.normalize(posix.join(posix.dirname(path), m[1]!)).replace(/\.(ts|js)$/, '')
+      if (!FOLDER_SDK.test(target) || target.startsWith('../')) continue
+      const shim = `${target}.ts`
+      if (files[shim] || files[`${target}/index.ts`] || shims[shim]) continue
+      // From functions/<slug>/<shim's folder> up to the project root, then into vendor/.
+      const up = posix.relative(posix.join('functions', '_', posix.dirname(shim)), '.')
+      const module = target.replace(/^(src\/)?/, '')
+      shims[shim] = `${SDK_SHIM_HEADER}\nexport * from '${up}/vendor/${module}'\n`
+    }
+  }
+  return shims
+}
+
+/** A Function folder's tsconfig with its `@frontera-sdk/*` paths at the solution's vendor/frontera/ (two folders up). */
+export function vendorPaths(tsconfig: string): string {
+  let doc: { compilerOptions?: { baseUrl?: string; paths?: Record<string, string[]> } }
+  try {
+    doc = JSON.parse(tsconfig)
+  } catch {
+    return tsconfig
+  }
+  const paths = doc.compilerOptions?.paths
+  if (!paths) return tsconfig
+  const base = doc.compilerOptions!.baseUrl ?? '.'
+  const up = posix.relative(posix.normalize(base), '../..') || '.'
+  for (const [alias, targets] of Object.entries(paths)) {
+    if (!alias.startsWith('@frontera-sdk/')) continue
+    paths[alias] = targets.map((t) => t.replace(/^(\.\/)?(src\/)?frontera\//, `${up}/vendor/frontera/`))
+  }
+  return `${JSON.stringify(doc, null, 2)}\n`
+}
+
+/**
+ * The file and the relative files it imports, transitively, within the
+ * archive. An import that leaves the archive's folder (`../shared/x`) is
+ * found under `frontera-imports/` (`outsidePath`), where a current deploy
+ * keeps it; one the archive lacks is added to `missing`, by its path from
+ * the folder.
+ */
+function withImports(files: Map<string, string>, entry: string, missing: string[] = []): string[] {
   const seen = new Set<string>()
   const visit = (path: string) => {
     if (seen.has(path) || !files.has(path)) return
     seen.add(path)
+    // A file kept from outside the folder imports by its own place there.
+    const here = fromOutsidePath(path) ?? path
     for (const m of files.get(path)!.matchAll(/from\s+['"](\.{1,2}\/[^'"]+)['"]/g)) {
-      const base = posix.normalize(posix.join(posix.dirname(path), m[1]!))
-      for (const candidate of [base, `${base}.ts`, `${base}/index.ts`]) if (files.has(candidate)) visit(candidate)
+      const base = posix.normalize(posix.join(posix.dirname(here), m[1]!))
+      const candidates = [base, `${base}.ts`, `${base}/index.ts`, `${base}.js`, `${base}/index.js`].map((c) => (c.startsWith('../') ? outsidePath(c) : c))
+      const found = candidates.find((c) => files.has(c))
+      if (found) {
+        visit(found)
+        // A JavaScript file's types beside it (a module a pull recovered from a deployed bundle).
+        if (found.endsWith('.js')) visit(`${found.slice(0, -'.js'.length)}.d.ts`)
+      } else if (base.startsWith('../')) missing.push(base)
     }
   }
   visit(entry)
@@ -622,6 +826,7 @@ async function readEditorDraft(source: SyncSource, row: FunctionRow, it: RemoteI
 
 async function readFunctions(source: SyncSource, lists: Lists, opts: ReadOptions, warnings: string[]): Promise<RemoteItem[]> {
   const out: RemoteItem[] = []
+  const missingImports: MissingImports[] = []
   for (const row of lists.functions) {
     const ref = `function/${row.slug}`
     if (!wanted(opts, ref)) continue
@@ -672,15 +877,50 @@ async function readFunctions(source: SyncSource, lists: Lists, opts: ReadOptions
         warnings.push(`Function ${row.slug}: imports ${list(outside)}, which a pull does not write into a folder of the project’s own items`)
       }
     } else {
-      // A Function deployed from its own folder: the folder, under functions/<slug>/.
-      for (const [p, content] of files) if (!p.startsWith('.')) it.files[`functions/${row.slug}/${p}`] = content
+      // A Function deployed from its own folder: its entry, what that imports, its test and the
+      // folder's project files, under functions/<slug>/; never its siblings or the SDK copy.
+      const folder = folderFunctionFiles(files, row.slug)
+      for (const [p, content] of Object.entries(folder.files)) it.files[`functions/${row.slug}/${p}`] = content
       if (!Object.keys(it.files).length) continue
       it.notes.push('Deployed from its own folder; pulled as functions/' + row.slug + '/')
+      // What it imports from beside its folder, written where the import finds it: a shared file of the
+      // solution (`functions/shared/…`, `lib/…`), never inside another Function's folder or above the project.
+      const folders = new Set(lists.functions.map((f) => f.slug))
+      const beside = (fromFolder: string) => {
+        const path = posix.normalize(posix.join('functions', row.slug, fromFolder))
+        const parts = path.split('/')
+        if (path.startsWith('../') || parts.some((p) => p.startsWith('.'))) return null
+        if (parts[0] === 'functions') return parts.length >= 3 && !folders.has(parts[1]!) ? path : null
+        return isSharedFunctionFile(path) ? path : null
+      }
+      const brought: string[] = []
+      for (const [rel, content] of Object.entries(folder.outside)) {
+        const path = beside(rel)
+        if (!path) continue
+        it.files[path] = content
+        brought.push(path)
+      }
+      const list = (paths: string[]) => (paths.length > 3 ? `${paths.slice(0, 3).join(', ')} and ${paths.length - 3} more` : paths.length > 1 ? `${paths.slice(0, -1).join(', ')} and ${paths[paths.length - 1]}` : paths.join(''))
+      if (brought.length) it.notes.push(`Brings ${list(brought.sort())}, which it imports from beside its folder, so it builds as in the workspace`)
+      // What its source lacks: from another Function's source, else cut back out of its deployed
+      // bundle once every Function is read (`recoverMissingImports`), else said.
+      if (folder.missing.length && folder.entry) {
+        missingImports.push({ it, slug: row.slug, version: row.liveVersion, files, entry: folder.entry, missing: folder.missing, writable: (path) => beside(posix.relative(posix.join('functions', row.slug), `${path}.js`)) === `${path}.js` })
+      } else if (folder.missing.length) {
+        const lacking = folder.missing.map((m) => posix.normalize(posix.join('functions', row.slug, m)))
+        it.notes.push(missingImportNote(lacking))
+        warnings.push(missingImportWarning(row.slug, lacking))
+      }
+      if (!folder.entry) {
+        it.notes.push('Its source names no entry for it, so every file of its folder was pulled')
+        warnings.push(`Function ${row.slug}: no file in its source declares \`automation({ name: '${row.slug}' })\`; its whole folder was pulled`)
+      }
     }
     // Functions name other resources only in their code, if at all; nothing to rewrite.
     it.requires = []
     out.push(it)
   }
+  if (missingImports.length) await recoverMissingImports(missingImports, out, (path) => source.workspace.getBytes(path), warnings)
   noteSharedFunctionFiles(out, warnings)
   return out
 }
@@ -771,6 +1011,13 @@ async function readSkills(source: SyncSource, lists: Lists, opts: ReadOptions, w
   return out
 }
 
+/** A number a file holds as one: `"0.5"` (a decimal the platform answers as text) is 0.5; anything else is left out or kept as it is. */
+export function fileNumber(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined
+  if (typeof value === 'string' && value.trim() && Number.isFinite(Number(value))) return Number(value)
+  return value === null || value === undefined ? undefined : (value as number)
+}
+
 async function readKnowledge(source: SyncSource, lists: Lists, opts: ReadOptions, warnings: string[]): Promise<RemoteItem[]> {
   const out: RemoteItem[] = []
   for (const k of lists.knowledge.filter((x) => wanted(opts, `knowledge/${refName(x.name)}`))) {
@@ -780,17 +1027,18 @@ async function readKnowledge(source: SyncSource, lists: Lists, opts: ReadOptions
       description: k.description ?? undefined,
       retrieval: k.retrieval ?? undefined,
       chunker: k.chunker ?? undefined,
-      chunkSize: k.chunkSize ?? undefined,
-      chunkOverlap: k.chunkOverlap ?? undefined,
-      similarityThreshold: k.similarityThreshold ?? undefined,
-      topK: k.topK ?? undefined,
+      // Numbers as the file format has them: the platform reads a decimal column back as text ("0.5").
+      chunkSize: fileNumber(k.chunkSize),
+      chunkOverlap: fileNumber(k.chunkOverlap),
+      similarityThreshold: fileNumber(k.similarityThreshold),
+      topK: fileNumber(k.topK),
       // How it searches and reads documents: hybrid search and reranking, extraction, OCR.
       hybridConfig: k.hybridConfig ?? undefined,
       extractorConfig: k.extractorConfig ?? undefined,
       ocrConfig: k.ocrConfig ?? undefined,
     }).filter(([, v]) => v !== undefined))
     const it = item('knowledge', name, k.name, { [`knowledge/${name}/knowledge.json`]: json(doc) }, {
-      notes: ['Its documents stay on the platform: add them as Markdown or text files in this folder and `local dev` uploads them'],
+      notes: ['Its documents come with it when it is pulled (unless `--no-documents`), and `local dev` uploads them; Markdown or text files added to this folder are uploaded too'],
       requires: [],
       id: k.id,
     })
@@ -898,7 +1146,36 @@ async function readPlugins(lists: Lists, opts: ReadOptions, tools: PluginTools):
   return out
 }
 
-interface BundleAnswer { definition: Parameters<typeof toFiles>[0] | null; datasetNames: Record<string, string> }
+interface BundleAnswer {
+  definition: Parameters<typeof toFiles>[0] | null
+  datasetNames: Record<string, string>
+  /** The workspace's own grants beyond read (the workspace's slice only): `blueprint/workspace-grants.yaml`. */
+  workspaceGrants?: Array<{ objectType?: unknown; permissions?: unknown }>
+}
+
+/**
+ * `blueprint/workspace-grants.yaml` as the workspace's slice answers it: the
+ * types the workspace holds more than `read` on (today, `read_sensitive`), in
+ * the file's own shape (`local-workspace-grants.ts`). None: no item, so a
+ * pull writes no file.
+ */
+export function workspaceGrantsItem(grants: BundleAnswer['workspaceGrants']): RemoteItem | null {
+  const entries = (Array.isArray(grants) ? grants : []).flatMap((g) => {
+    const type = typeof g?.objectType === 'string' ? g.objectType.replace(/^objectType\//, '') : ''
+    const permissions = Array.isArray(g?.permissions) ? g.permissions.filter((p): p is string => typeof p === 'string') : []
+    return type && permissions.length ? [{ objectType: `objectType/${type}`, permissions }] : []
+  })
+  if (!entries.length) return null
+  const doc = new YamlDocument({ grants: entries })
+  // `permissions: [read, read_sensitive]`, as the file is written by hand.
+  for (const entry of (doc.get('grants') as YAMLSeq<YAMLMap>).items) {
+    const permissions = entry.get('permissions', true)
+    if (isSeq(permissions)) permissions.flow = true
+  }
+  const it = item('blueprint', WORKSPACE_GRANTS_NAME, 'Workspace grants', { [WORKSPACE_GRANTS_FILE]: doc.toString({ lineWidth: 0, flowCollectionPadding: false }) })
+  it.requires = entries.map((e) => itemRef('objectType', e.objectType.slice('objectType/'.length))).sort()
+  return it
+}
 
 /**
  * The saved object sets as Blueprint files (`blueprint/object-sets/<name>.yaml`):
@@ -971,6 +1248,8 @@ async function readBlueprint(
   let answer: BundleAnswer | null = null
   // The draft read in place of the release, already holding its Actions.
   let fromDraft = false
+  // The workspace's grants beyond read, from its slice (the organization's model has none of a workspace's).
+  let grants: RemoteItem | null = null
   if (mode === 'organization' && source.organization) {
     const lifecycle = one<Lifecycle>(await source.organization.get('/v1/blueprint/lifecycle'))
     fromDraft = !!lifecycle.draft?.definition && (!!opts.draft || !lifecycle.activeRelease?.definition)
@@ -978,8 +1257,10 @@ async function readBlueprint(
     if (fromDraft) notes.push(opts.draft ? 'The Blueprint was read from its unpublished draft, as asked' : 'The Blueprint has no published release; its draft was read')
   } else {
     const sliced = await source.workspace.find<unknown>('/v1/sync/blueprint')
-    if (sliced) answer = one<BundleAnswer>(sliced)
-    else if (source.organization) {
+    if (sliced) {
+      answer = one<BundleAnswer>(sliced)
+      grants = workspaceGrantsItem(answer.workspaceGrants)
+    } else if (source.organization) {
       notes.push('This platform cannot cut the Blueprint to the workspace yet; the organization key read the whole model')
       return readBlueprint(source, 'organization', warnings, notes, sets, opts)
     } else {
@@ -994,7 +1275,7 @@ async function readBlueprint(
       if (lifecycle.draft?.definition) {
         answer = { definition: sliceDraft(lifecycle.draft.definition, granted), datasetNames: { ...(answer.datasetNames ?? {}), ...(await datasetNames(source.organization)) } }
         fromDraft = true
-        notes.push('The Blueprint was read from its unpublished draft, as asked, cut to the object types this workspace is granted')
+        notes.push('The Blueprint was read from its unpublished draft, as asked, cut to the object types the workspace is granted')
       }
     }
   }
@@ -1003,6 +1284,8 @@ async function readBlueprint(
   // With the organization key, the published Actions on the slice's object types come along.
   const definition = mode === 'workspace' && source.organization && !fromDraft ? await withActions(source.organization, answer.definition, warnings, notes) : answer.definition
   const model = toFiles(definition, new Map(Object.entries(answer.datasetNames ?? {})))
+  // What an Action is checked against, as the local runtime checks it when `local dev` writes it.
+  const semantic = semanticFactsOf(model.files.map((f) => ({ path: f.path, document: f.document as Record<string, unknown> })))
   const objectTypes = new Set(model.files.flatMap((f) => (f.path.startsWith('object-types/') ? [f.apiName] : [])))
   const saved = objectSetItems(sets.lists.objectSets ?? [], sets.directory, objectTypes)
   return [...model.files.map((file) => {
@@ -1013,12 +1296,20 @@ async function readBlueprint(
     if (file.path.startsWith('actions/')) {
       // An Action brings the object types it acts on, and says what it does on the local runtime.
       const doc = file.document as Record<string, any>
-      const fit = actionFit(doc)
+      const fit = actionFit(doc, semantic)
       if (fit.subject) it.requires = [itemRef('objectType', fit.subject)]
-      it.notes.push(fit.runsLocally ? `Deployed on the local runtime when it applies: it writes ${fit.subject ?? 'its object'}’s records there` : `Published switched off on the local runtime: ${fit.reason}`)
+      it.notes.push(
+        fit.refused
+          ? `Won’t run on the local runtime: ${fit.reason!.replace(/^the local runtime refuses it: /, 'it refuses it as written. ')} The fix is the Blueprint author’s, in the workspace: change the Action or the semantic type so they agree, then pull it`
+          : fit.runsLocally
+            ? `Deployed on the local runtime when it applies: it writes ${fit.subject ?? 'its object'}’s records there`
+            : `Published switched off on the local runtime: ${fit.reason}`,
+      )
+      // As the workspace runs it, a value it offers that the type it writes refuses: inherited, not refused here.
+      if (fit.inheritedWarnings?.length) it.notes.push(`Runs with a warning inherited from the workspace: ${fit.inheritedWarnings.join(' ')} A request with such a value is refused when it is submitted, here as in the workspace; the Blueprint author fixes the Action’s contract there, then you pull it`)
     }
     return it
-  }), ...saved]
+  }), ...saved, ...(grants ? [grants] : [])]
 }
 
 type Bundle = NonNullable<BundleAnswer['definition']>
@@ -1048,7 +1339,7 @@ async function withActions(org: SyncClient, sliced: Bundle, warnings: string[],
     if (touched.every((id) => ids.has(id))) kept.push(action)
     else outside.push(String(action.apiName))
   }
-  if (outside.length) notes.push(`${outside.length} governed Action${outside.length === 1 ? ' acts' : 's act'} on object types this workspace isn’t granted, so ${outside.length === 1 ? 'it stays' : 'they stay'} out: ${outside.join(', ')}`)
+  if (outside.length) notes.push(`${outside.length} governed Action${outside.length === 1 ? ' acts' : 's act'} on object types the workspace isn’t granted, so ${outside.length === 1 ? 'it stays' : 'they stay'} out: ${outside.join(', ')}`)
   return { ...def, actions: kept } as Bundle
 }
 
@@ -1375,9 +1666,29 @@ export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}):
   noteConnections(items, lists)
   noteActions(items, directory)
   // What each item needs against what the local runtime can do (§8), with the Actions this read brought.
-  const actions = new Map(items.filter((i) => i.kind === 'blueprint' && i.name.startsWith('actions/')).flatMap((i) => Object.values(i.files).map((text) => [i.name.slice('actions/'.length), actionFit((parseYaml(text) ?? {}) as Record<string, unknown>)] as const)))
+  // The checks `local dev` will apply, run here so the index says what won't run before anything is applied:
+  // an Action's values against the semantic types it writes, and the files a Function's code imports.
+  const semantic = semanticFactsOf(items.filter((i) => i.kind === 'blueprint').flatMap((i) => Object.entries(i.files).flatMap(([path, text]) => {
+    try {
+      const document = parseYaml(text)
+      return document && typeof document === 'object' ? [{ path, document: document as Record<string, unknown> }] : []
+    } catch {
+      return []
+    }
+  })))
+  const actions = new Map(items.filter((i) => i.kind === 'blueprint' && i.name.startsWith('actions/')).flatMap((i) => Object.values(i.files).map((text) => [i.name.slice('actions/'.length), actionFit((parseYaml(text) ?? {}) as Record<string, unknown>, semantic)] as const)))
   const titles = new Map(lists.apps.flatMap((a) => (a.install && a.catalog?.displayName ? [[a.install.installName, a.catalog.displayName] as const] : [])))
-  for (const it of items) it.portability = portabilityOf(it.kind, it.files, { connections: connectionNames(lists), builtIns: builtInKinds(lists), context: { actions, titles } })
+  const pulledFiles = new Set(items.flatMap((i) => Object.keys(i.files)))
+  const hasFile = (path: string) => pulledFiles.has(path)
+  for (const it of items) it.portability = portabilityOf(it.kind, it.files, { connections: connectionNames(lists), builtIns: builtInKinds(lists), context: { actions, titles }, semantic, hasFile })
+  // A Function's code that names an object type by the workspace's id: the local runtime's ids differ.
+  const platformIds = platformObjectTypeIds(directory)
+  for (const it of items) {
+    if (it.kind !== 'function') continue
+    const hits = hardCodedObjectTypeIds(it.files, platformIds)
+    if (!hits.length) continue
+    it.notes.push(`Hard-codes the workspace’s object type ids, which the local runtime doesn’t share: ${hits.map((h) => `${h.file}:${h.line} (${h.objectType})`).join(', ')}. \`local dev\` deploys it here with this runtime’s ids in their place and leaves the files as they are; take the id from the query result (\`subjectOf\`, or \`result.objectTypeId\`) so the code holds on any runtime`)
+  }
   if (!source.organization && items.some((i) => i.unresolved.length)) {
     notes.push(directory.model?.size
       ? 'Governed Actions are named only with an organization key (they are organization-wide); an Action step shows as an id until you connect one'

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

@@ -1,6 +1,7 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
+import { ignoreInFronteraDir } from '../project-context'
 import { CliError } from '../errors'
 import { writeFileAtomic } from '../fs-atomic'
 import { hash, itemHash, safePath, SYNC_KINDS, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
@@ -53,6 +54,8 @@ export interface SnapshotItem {
   state?: RemoteItem['state']
   /** Its binary files (a skill's assets), by project path, kept under `.frontera/sync/remote-assets/`. */
   assets?: string[]
+  /** Its files recovered from the deployed bundle, not its source (`RemoteItem.recovered`). */
+  recovered?: string[]
 }
 
 export interface RemoteSnapshot {
@@ -122,9 +125,14 @@ export interface RemoteSnapshot {
  * 10: a Plugin's description and icon. 11: Custom Apps, the brand and the
  * library. 12: an Agent's object tools carry their object definitions,
  * named by slug (`object/<slug>`). 13: a knowledge base's quality checks
- * (`quality-checks.yaml`).
+ * (`quality-checks.yaml`). 14: a Function's imports its source lacks,
+ * recovered from its deployed bundle. 15: an Agent's behavior settings read
+ * from its snapshot or record, as a released platform gives them. 16: an
+ * item's portability runs the checks `local dev` applies: a Function whose
+ * imports the pull can't bring, and an Action whose values the semantic types
+ * it writes refuse, are said not to run here.
  */
-export const SNAPSHOT_READER = 13
+export const SNAPSHOT_READER = 16
 
 /** The directory the snapshot recorded, as the reference rewriter reads it. */
 export function directoryOf(snap: RemoteSnapshot | null): Directory | undefined {
@@ -182,7 +190,7 @@ export function snapshotItems(root: string, snap: RemoteSnapshot): RemoteItem[]
       files[path] = content
     }
     const assets = (s.assets ?? []).map((path) => ({ path, from: underDir(root, ASSETS_DIR, path) }))
-    return [{ ref, kind: s.kind, name: s.name, title: s.title, files, version: s.version, id: s.id, revision: s.revision, unresolved: s.unresolved, notes: s.notes, requires: s.requires, ...(s.portability ? { portability: s.portability } : {}), ...(s.state ? { state: s.state } : {}), ...(assets.length ? { assets } : {}) }]
+    return [{ ref, kind: s.kind, name: s.name, title: s.title, files, version: s.version, id: s.id, revision: s.revision, unresolved: s.unresolved, notes: s.notes, requires: s.requires, ...(s.portability ? { portability: s.portability } : {}), ...(s.state ? { state: s.state } : {}), ...(assets.length ? { assets } : {}), ...(s.recovered?.length ? { recovered: s.recovered } : {}) }]
   })
 }
 
@@ -208,12 +216,8 @@ export function knownGone(snap: RemoteSnapshot | null): (ref: string) => boolean
 
 /** `.frontera/` keeps the runtime's state out of git; the snapshot and the base stay out too. */
 function ignoreSyncDir(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/'])
 }
 
 function toSnapshotItem(item: RemoteItem, revision?: string): SnapshotItem {
@@ -232,6 +236,7 @@ function toSnapshotItem(item: RemoteItem, revision?: string): SnapshotItem {
     ...(item.portability ? { portability: item.portability } : {}),
     ...(item.state ? { state: item.state } : {}),
     ...(item.assets?.length ? { assets: item.assets.map((a) => a.path).sort() } : {}),
+    ...(item.recovered?.length ? { recovered: [...item.recovered].sort() } : {}),
   }
 }