@frontera-sdk/cli 1.52.42 → 1.52.44

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

@@ -16,8 +16,11 @@ import { lessonsPath, lessonsProposal } from './local-lessons'
 import { importedFiles } from './local-function-shared'
 import { isIgnoredName } from './local-dev-sync'
 import { comparableText, withoutSecrets } from './local-secrets'
+import { projectModels } from './local-sync-models'
 import { deepEqual } from './local-sync-merge'
+import { portableNotes, sameDocumentText, toLocal, toWorkspace } from './local-sync-portable'
 import { itemTitle } from './local-sync-names'
+import { isScaffoldSample } from './local-scaffold'
 import { hash, itemHash, readLocal, safePath, writeLock, type LockEntry, type PlanItem, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
 import { dropBase, SYNC_DIR, writeBase, type RemoteSnapshot } from './local-sync-snapshot'
 
@@ -55,8 +58,12 @@ const NOT_DELETED: Partial<Record<SyncKind, string>> = {
   lessons: 'An Agent’s rules are retired on the platform, where they are reviewed: a change request only proposes new ones',
 }
 
-/** Why an item cannot be proposed now. */
-export type BlockCode = 'moved' | 'conflicts' | 'deleted' | 'workspace-deleted' | 'kind' | 'shape'
+/**
+ * Why an item cannot be proposed now. `model`: it names a model the workspace
+ * lacks and `sync.models` maps to none; `refused`: the workspace's checks
+ * would refuse it (`POST /v1/change-requests/check`), said before proposing.
+ */
+export type BlockCode = 'moved' | 'conflicts' | 'deleted' | 'workspace-deleted' | 'kind' | 'shape' | 'model' | 'refused'
 
 /** A skill's file that is not text (an image, a font, a template): uploaded as a skill asset when proposed. */
 export interface PushAsset {
@@ -96,6 +103,15 @@ export interface PushItem {
   /** Why not, when it is not. */
   blocked: BlockCode | null
   reason: string | null
+  /** What makes it proposable, when something here can: the command or the choice. */
+  fix?: string | null
+  /**
+   * Still exactly the sample setting up the project wrote (`isScaffoldSample`):
+   * proposable, but left out unless named or ticked.
+   */
+  sample?: boolean
+  /** The models it names that the workspace lacks and `sync.models` maps to none, by local slug. */
+  missingModels?: string[]
   /** The platform's id, from the lock (or the snapshot). */
   id: string | null
   /** The revision the item was changed from; for a Blueprint file, the Blueprint's. */
@@ -165,7 +181,7 @@ function functionImports(root: string, entry: string): string[] {
  * service). The lock's paths that still exist come along, so nothing the
  * last pull wrote is left behind.
  */
-export function itemFiles(root: string, kind: SyncKind, name: string, entry?: LockEntry, opts: { documents?: boolean } = {}): { files: Record<string, string>; notes: string[]; problem?: string; assets?: string[] } {
+export function itemFiles(root: string, kind: SyncKind, name: string, entry?: LockEntry, opts: { documents?: boolean; upstream?: Record<string, string> } = {}): { files: Record<string, string>; notes: string[]; problem?: string; assets?: string[] } {
   const notes: string[] = []
   let paths: string[] = []
   const assets: string[] = []
@@ -228,6 +244,8 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
   // What the last pull wrote for it comes along when it is still here (an agent's files are fixed; the rest may not be).
   if (kind !== 'agent' && kind !== 'knowledge') for (const p of Object.keys(entry?.files ?? {})) if (!paths.includes(p)) paths.push(p)
   const files: Record<string, string> = {}
+  const here: Record<string, string> = {}
+  const models = projectModels(root)
   for (const path of [...new Set(paths)].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     if (path.endsWith('.workspace') || assets.includes(path)) continue
     const text = readLocal(root, path)
@@ -236,8 +254,13 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
       const clean = withoutSecrets(text)
       files[path] = clean.text
       notes.push(...clean.notes)
-    } else files[path] = text
+    } else {
+      // As the workspace will have it: a mapped model swapped, the multi-turn evaluation cases left here.
+      files[path] = toWorkspace(path, text, models, opts.upstream?.[path] ?? null).text
+      here[path] = text
+    }
   }
+  notes.push(...portableNotes(here, models, models.names, opts.upstream))
   return { files, notes, ...(kind === 'skill' ? { assets } : {}) }
 }
 
@@ -305,7 +328,7 @@ export interface CandidateInput {
   }
 }
 
-const BLOCK_REASON: Record<Exclude<BlockCode, 'kind' | 'shape'>, string> = {
+const BLOCK_REASON: Record<Exclude<BlockCode, 'kind' | 'shape' | 'model' | 'refused'>, string> = {
   moved: 'Changed in the workspace too since your last pull: pull and merge it first',
   conflicts: 'Has conflicts from a pull: resolve them first',
   deleted: 'Deleted here',
@@ -389,7 +412,7 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     if (status === 'new' || status === 'changed') continue
     const deleted = status === 'deleted-local'
     const bringDocuments = kind === 'knowledge' && !!input.documents?.names.has(name)
-    const { files, notes, problem, assets: assetPaths } = deleted ? { files: {} as Record<string, string>, notes: [] as string[], problem: undefined, assets: undefined } : itemFiles(root, kind, name, entry, { documents: bringDocuments })
+    const { files, notes, problem, assets: assetPaths } = deleted ? { files: {} as Record<string, string>, notes: [] as string[], problem: undefined, assets: undefined } : itemFiles(root, kind, name, entry, { documents: bringDocuments, ...(theirs ? { upstream: theirs.files } : {}) })
     // What a file hash does not cover: a skill's assets, and a knowledge base's documents when they are brought.
     const assetState = kind === 'skill' && !deleted && (assetPaths?.length || theirs?.assets?.length) ? skillAssets(root, name, assetPaths ?? [], theirs) : null
     const docs = bringDocuments && !deleted && input.documents
@@ -422,6 +445,10 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
       base: baseFiles,
       notes,
     }
+    if (!deleted && isScaffoldSample(files)) {
+      item.sample = true
+      notes.push('A sample from setting up the project, not your work: it stays here unless you tick it (or name it to `frontera local sync push`)')
+    }
     if (assetState) {
       item.assets = assetState.assets
       for (const a of assetState.assets) if (a.change !== 'same') notes.push(`Asset ${a.path}: ${a.change === 'new' ? 'new' : 'changed'} (${kb(a.bytes)})`)
@@ -770,9 +797,20 @@ export function adoptApplied(root: string, workspace: string, refs: string[], re
     if (!item) continue
     for (const [path, text] of Object.entries(item.files)) {
       const here = readLocal(root, path)
-      if (here !== null && here !== text && sameDocument(path, here, text)) {
+      if (here === null || here === text) continue
+      if (sameDocument(path, here, text)) {
         writeFileSync(safePath(root, path), text)
         rewritten.push(path)
+        continue
+      }
+      // What the workspace now holds, with this computer's parts kept (a mapped model, the multi-turn cases).
+      const portable = toWorkspace(path, here, projectModels(root), text).text
+      if (portable !== here && (sameDocument(path, portable, text) || sameDocumentText(path, portable, text))) {
+        const local = toLocal(path, text, here, projectModels(root))
+        if (local !== here) {
+          writeFileSync(safePath(root, path), local)
+          rewritten.push(path)
+        }
       }
     }
     next.items[ref] = {

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

@@ -164,7 +164,8 @@ async function listActions(org: SyncClient): Promise<ActionRow[]> {
     const d = ((row as { definition?: unknown } | null)?.definition ?? row) as Partial<ActionRow> | null
     return d && typeof d.id === 'string' && typeof d.apiName === 'string' ? [{ id: d.id, apiName: d.apiName }] : []
   }
-  const draft = rows<unknown>(await org.get('/v1/blueprint/actions?view=draft')).flatMap(pick)
+  // An organization that has never published a Blueprint has no draft to read: no Actions (404).
+  const draft = rows<unknown>(await org.find('/v1/blueprint/actions?view=draft')).flatMap(pick)
   const published = rows<unknown>(await org.get('/v1/blueprint/actions').catch(() => null)).flatMap(pick)
   return [...new Map([...published, ...draft].map((a) => [a.id, a])).values()]
 }
@@ -191,8 +192,8 @@ export async function buildDirectory(source: SyncSource, warnings: string[] = []
     quietly(warnings, 'Blueprint object types', async () => rows<{ id: string; apiName: string }>(await ws.get('/v1/blueprint/object-types')), []),
     // The model catalog is organization-grain: a workspace key reads its names only, where the platform offers them.
     source.organization
-      ? quietly(warnings, 'Models', async () => rows<{ id: string; slug: string }>(await source.organization!.get('/v1/config/models/catalog')), [])
-      : quietly(warnings, 'Models', async () => rows<{ id: string; slug: string }>(await ws.find<unknown>('/v1/sync/models')), []),
+      ? quietly(warnings, 'Models', async () => rows<CatalogModelRow>(await source.organization!.get('/v1/config/models/catalog')), [])
+      : quietly(warnings, 'Models', async () => rows<CatalogModelRow>(await ws.find<unknown>('/v1/sync/models')), []),
     // So are governed Actions' definitions: without the organization key they are not listed.
     source.organization ? quietly<ActionRow[] | null>(warnings, 'Governed Actions', () => listActions(source.organization!), null) : Promise.resolve(null),
     // A platform without the route has none to name: absent, as for Actions.
@@ -221,7 +222,28 @@ export async function buildDirectory(source: SyncSource, warnings: string[] = []
     ...(objectSets ? { objectSet: new Map((objectSets ?? []).map((o) => [setNames.get(o.id)!, o.id])) } : {}),
     ...(objectDefinitions ? { object: new Map(objectDefinitions.map((o) => [o.slug, o.id])) } : {}),
   }
-  return { directory, lists: { agents, workflows, functions, knowledge, apps, skills, objectSets: objectSets ?? [], objectDefinitions } }
+  const catalog = models.map((m) => ({ slug: m.slug, name: m.name ?? m.slug, kind: m.kind ?? 'text', ...(m.provider ? { provider: m.provider } : {}), ...(m.modelId ? { modelId: m.modelId } : {}) }))
+  return { directory, lists: { agents, workflows, functions, knowledge, apps, skills, objectSets: objectSets ?? [], objectDefinitions, models: catalog } }
+}
+
+/** A model of the organization's catalog as the workspace lists it; the provider's model id tells two slugs for one model apart. */
+interface CatalogModelRow {
+  id: string
+  slug: string
+  name?: string
+  kind?: string
+  provider?: string
+  modelId?: string
+}
+
+/** A model of the workspace's catalog, kept with the snapshot: what a project's model can be matched against. */
+export interface WorkspaceCatalogModel {
+  slug: string
+  name: string
+  kind: string
+  provider?: string
+  /** The provider's id for it (`deepseek/deepseek-v4.1-flash`): the same model under another slug has the same one. */
+  modelId?: string
 }
 
 export interface Lists {
@@ -235,6 +257,8 @@ export interface Lists {
   objectSets?: ObjectSetRow[]
   /** The object definitions an Agent's object tools work on; null when the platform doesn't list them. */
   objectDefinitions?: ObjectDefinitionRow[] | null
+  /** The organization's model catalog, as far as the key reads it. */
+  models?: WorkspaceCatalogModel[]
 }
 
 export interface ReadOptions {
@@ -1251,7 +1275,13 @@ async function readBlueprint(
   // 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'))
+    // None (404) for an organization that has never published or drafted a Blueprint: nothing to pull.
+    const found = await source.organization.find<unknown>('/v1/blueprint/lifecycle')
+    if (!found) {
+      notes.push('The organization has no Blueprint yet; nothing was pulled into blueprint/')
+      return []
+    }
+    const lifecycle = one<Lifecycle>(found)
     fromDraft = !!lifecycle.draft?.definition && (!!opts.draft || !lifecycle.activeRelease?.definition)
     answer = { definition: (fromDraft ? lifecycle.draft?.definition : lifecycle.activeRelease?.definition) ?? null, datasetNames: await datasetNames(source.organization) }
     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')
@@ -1270,7 +1300,8 @@ async function readBlueprint(
     if (opts.draft && !source.organization) notes.push('Reading the Blueprint’s unpublished draft takes an organization key; its published release was read')
     if (opts.draft && source.organization && answer) {
       // The draft, cut to the object types the workspace's slice holds now.
-      const lifecycle = one<Lifecycle>(await source.organization.get('/v1/blueprint/lifecycle'))
+      const found = await source.organization.find<unknown>('/v1/blueprint/lifecycle')
+      const lifecycle = found ? one<Lifecycle>(found) : ({} as Lifecycle)
       const granted = new Set(((answer.definition as { objects?: Array<{ apiName: string }> } | null)?.objects ?? []).map((o) => o.apiName))
       if (lifecycle.draft?.definition) {
         answer = { definition: sliceDraft(lifecycle.draft.definition, granted), datasetNames: { ...(answer.datasetNames ?? {}), ...(await datasetNames(source.organization)) } }
@@ -1606,7 +1637,7 @@ async function readEvaluations(source: SyncSource, lists: Lists, directory: Dire
  * collects what could not be read (a kind the key may not see, a platform
  * too old for an export), so the plan says so instead of failing.
  */
-export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}): Promise<{ items: RemoteItem[]; warnings: string[]; notes: string[]; directory: Directory }> {
+export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}): Promise<{ items: RemoteItem[]; warnings: string[]; notes: string[]; directory: Directory; models: WorkspaceCatalogModel[] }> {
   const warnings: string[] = []
   const notes: string[] = []
   const { directory, lists } = await buildDirectory(source, warnings)
@@ -1694,7 +1725,7 @@ export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}):
       ? 'Governed Actions are named only with an organization key (they are organization-wide); an Action step shows as an id until you connect one'
       : 'Models and governed Actions are named only with an organization key (both are organization-wide); an LLM step’s model or an Action step shows as an id until you connect one')
   }
-  return { items, warnings, notes, directory }
+  return { items, warnings, notes, directory, models: lists.models ?? [] }
 }
 
 /**

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

@@ -7,7 +7,7 @@ import { writeFileAtomic } from '../fs-atomic'
 import { hash, itemHash, safePath, SYNC_KINDS, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
 import { readOrgSettings, type OrgSettings } from './local-org-settings'
 import type { Portability } from './local-portability'
-import { readWorkspace, type SyncSource } from './local-sync-remote'
+import { readWorkspace, type SyncSource, type WorkspaceCatalogModel } from './local-sync-remote'
 import { REF_KINDS, type Directory, type RefKind, type Unresolved } from './local-sync-refs'
 
 /**
@@ -86,6 +86,12 @@ export interface RemoteSnapshot {
    * now written `action/resetLine`) from a change.
    */
   names?: Partial<Record<RefKind, Record<string, string>>>
+  /**
+   * The organization's model catalog as of the last read, with each model's
+   * provider id, so a model this computer names under another slug is known
+   * as the workspace's (`local-sync-models.ts`).
+   */
+  models?: WorkspaceCatalogModel[]
   /**
    * Read with an organization key as well: it brings governed Actions (and,
    * for older platforms, the Blueprint). A snapshot read with other keys is
@@ -423,6 +429,7 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
       warnings: read.warnings,
       notes: read.notes,
       names: namesOf(read.directory),
+      ...(read.models.length ? { models: read.models } : {}),
       organizationKey: !!source.organization,
       reader: SNAPSHOT_READER,
       ...(settings ? { settings } : {}),
@@ -522,6 +529,7 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
     warnings: read?.warnings ?? [],
     notes: read ? read.notes : previous?.notes ?? [],
     ...(read ? { names: namesOf(read.directory) } : previous?.names ? { names: previous.names } : {}),
+    ...(read?.models.length ? { models: read.models } : previous?.models ? { models: previous.models } : {}),
     organizationKey: !!source.organization,
     reader: SNAPSHOT_READER,
     ...(settings ? { settings } : previous?.settings ? { settings: previous.settings } : {}),