@frontera-sdk/cli 1.52.28 → 1.52.30

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

@@ -0,0 +1,237 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { stringify as stringifyYaml } from 'yaml'
+
+import { toFiles } from '../blueprint/projection'
+import { serialize } from '../blueprint/tree'
+import { hash, readLocal, safePath, type LockEntry, type SyncKind } from './local-sync-plan'
+import { projectAgent, type SyncSource } from './local-sync-remote'
+import { toNames, type Directory } from './local-sync-refs'
+import { readBase, SYNC_DIR } from './local-sync-snapshot'
+
+/**
+ * Rebuilding a merge base the project lost. `.frontera/sync/base/` is not
+ * committed and the lock is, so a fresh clone, a cleaned folder or a pull
+ * by an older CLI leaves a merge with the lock's hashes and no content: it
+ * then merges only what both sides agree on and conflicts on the rest.
+ *
+ * Before such a merge, each base file is looked for where it may still be,
+ * and kept only when it hashes to what the lock recorded:
+ *
+ *   1. the fetched snapshot or the working file, when either still is the base
+ *      (the workspace or this project did not change that file);
+ *   2. the platform, at the revision the lock records (`GET /v1/sync/item`,
+ *      feature `item-revision`), turned into files as a pull would write them.
+ *
+ * The platform keeps earlier versions of Agents (published versions),
+ * workflows, Functions and the Blueprint (releases); not of Knowledge,
+ * Skills, Plugins or evaluations. Where nothing is found, the merge falls
+ * back as before, and the result says why.
+ */
+
+/** Kinds the platform keeps earlier versions of. */
+export const HISTORY_KINDS: readonly SyncKind[] = ['agent', 'workflow', 'function', 'blueprint']
+
+export type BaseGap = 'offline' | 'no-route' | 'no-history' | 'no-revision' | 'not-kept' | 'differs' | 'failed'
+
+export interface BaseRepair {
+  ref: string
+  /** Base files written back, each matching the lock. */
+  restored: string[]
+  /** Base files still missing: the merge has no base for them. */
+  missing: string[]
+  /** Read from the platform at this revision. */
+  revision?: string
+  /** Why the missing ones could not be found. */
+  gap?: BaseGap
+  /** The platform's message when the read failed. */
+  error?: string
+}
+
+export interface RepairOptions {
+  /** The platform, with the project's keys; without it only local copies are tried. */
+  source?: SyncSource
+  /** The sync features the platform said it has at the last fetch. */
+  capabilities?: string[]
+  /** The workspace's names at the last fetch, to write ids as names as a pull does. */
+  directory?: Directory
+}
+
+export interface RepairTarget {
+  ref: string
+  entry: LockEntry
+  /** The fetched snapshot's files for the item. */
+  remote?: Record<string, string>
+}
+
+/** The lock's paths whose base content is gone or no longer matches. */
+export function missingBase(root: string, entry: LockEntry | undefined): string[] {
+  return Object.entries(entry?.files ?? {}).flatMap(([path, wrote]) => {
+    const content = readBase(root, path)
+    return content !== null && hash(content) === wrote ? [] : [path]
+  })
+}
+
+function writeBaseFile(root: string, path: string, content: string): void {
+  // Inside the project, and inside the base folder, as every base write is.
+  safePath(root, path)
+  const full = safePath(join(root, SYNC_DIR, 'base'), path)
+  mkdirSync(dirname(full), { recursive: true })
+  writeFileSync(full, content)
+}
+
+/** What to ask the platform for: the Agent's version number, otherwise the lock's revision. */
+export function revisionFor(kind: SyncKind, entry: LockEntry): string | null {
+  // An Agent's index revision is a hash; its version (`v12`) names the published version.
+  if (kind === 'agent') return entry.version && /^v\d+$/.test(entry.version) ? entry.version : null
+  return entry.revision ?? null
+}
+
+interface ItemAnswer { ref: string; kind: string; revision: string; version?: string; content: Record<string, unknown> }
+
+const json = (value: unknown) => `${JSON.stringify(value, null, 2)}\n`
+
+/** Only the paths asked for, out of a Function's source archive: `functions/<slug>.ts` as it is, or a folder's files under `functions/<slug>/`. */
+function fromArchive(bytes: Uint8Array, slug: string, paths: string[]): Record<string, string> {
+  const dir = mkdtempSync(join(tmpdir(), 'frontera-sync-base-'))
+  try {
+    const archive = join(dir, 'src.tgz')
+    writeFileSync(archive, bytes)
+    const out = join(dir, 'out')
+    mkdirSync(out)
+    if (spawnSync('tar', ['-xzf', archive, '-C', out], { stdio: 'ignore' }).status !== 0) throw new Error('the source archive could not be unpacked')
+    const files: Record<string, string> = {}
+    for (const path of paths) {
+      const folder = `functions/${slug}/`
+      for (const inside of path.startsWith(folder) ? [path.slice(folder.length), path] : [path]) {
+        const full = join(out, inside)
+        if (!full.startsWith(`${out}/`) || !existsSync(full)) continue
+        files[path] = readFileSync(full, 'utf8')
+        break
+      }
+    }
+    return files
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+/**
+ * An item's files at a revision, as a pull writes them: the same projection
+ * (`projectAgent`, ids written as names, YAML for workflows, the Blueprint's
+ * files), from the platform's raw kept version. What the platform does not
+ * version (an Agent's `bindings.json`) is not produced.
+ */
+export async function projectAtRevision(source: SyncSource, ref: string, answer: ItemAnswer, paths: string[], directory: Directory = {}): Promise<Record<string, string>> {
+  const [kind, ...rest] = ref.split('/')
+  const name = rest.join('/')
+  const c = answer.content
+  if (kind === 'agent') {
+    const snapshot = (c.snapshot ?? {}) as Record<string, unknown>
+    const files: Record<string, string> = { [`agents/${name}/agent.json`]: json(toNames(projectAgent(snapshot, []), directory).doc) }
+    const operating = (snapshot.config as Record<string, unknown> | undefined)?.operatingConfig
+    if (operating && typeof operating === 'object' && Object.keys(operating).length) files[`agents/${name}/operating.json`] = json(toNames(operating, directory).doc)
+    return files
+  }
+  if (kind === 'workflow') {
+    const definition = (c.definition ?? {}) as Record<string, unknown>
+    const doc = c.layout ? { ...definition, layout: c.layout } : definition
+    return { [`workflows/${name}.yaml`]: stringifyYaml(toNames(doc, directory).doc, { lineWidth: 0 }) }
+  }
+  if (kind === 'function') {
+    if (typeof c.source !== 'string' || !c.source.startsWith('/v1/functions/')) return {}
+    return fromArchive(await source.workspace.getBytes(c.source), name, paths)
+  }
+  if (kind === 'blueprint') {
+    if (!c.definition) return {}
+    const model = toFiles(c.definition as Parameters<typeof toFiles>[0], new Map(Object.entries((c.datasetNames ?? {}) as Record<string, string>)))
+    return Object.fromEntries(model.files.filter((f) => !f.path.startsWith('actions/')).map((f) => [`blueprint/${f.path}`, serialize(f.path, f.document as Record<string, unknown>)]))
+  }
+  return {}
+}
+
+/**
+ * Find and write back the base of each item whose base is missing, as far
+ * as it can be found. Items whose base is whole are left out of the answer.
+ */
+export async function repairBases(root: string, targets: RepairTarget[], opts: RepairOptions = {}): Promise<BaseRepair[]> {
+  const out: BaseRepair[] = []
+  // The Blueprint's items share one release: read it once per revision.
+  const answers = new Map<string, Promise<ItemAnswer | null>>()
+  for (const { ref, entry, remote } of targets) {
+    let missing = missingBase(root, entry)
+    if (!missing.length) continue
+    const restored: string[] = []
+    const take = (path: string, content: string | null | undefined) => {
+      if (content === null || content === undefined || hash(content) !== entry.files[path]) return false
+      writeBaseFile(root, path, content)
+      restored.push(path)
+      return true
+    }
+    // 1. A copy that still is the base: the workspace's or this project's file, unchanged since the pull.
+    missing = missing.filter((path) => !(take(path, remote?.[path]) || take(path, readLocal(root, path))))
+    const report: BaseRepair = { ref, restored, missing }
+    out.push(report)
+    if (!missing.length) continue
+
+    // 2. The platform, at the revision the lock records.
+    const kind = ref.split('/')[0] as SyncKind
+    const revision = revisionFor(kind, entry)
+    if (!opts.source) {
+      report.gap = 'offline'
+      continue
+    }
+    if (!(opts.capabilities ?? []).includes('item-revision')) {
+      report.gap = 'no-route'
+      continue
+    }
+    if (!HISTORY_KINDS.includes(kind)) {
+      report.gap = 'no-history'
+      continue
+    }
+    if (!revision) {
+      report.gap = 'no-revision'
+      continue
+    }
+    report.revision = revision
+    const asked = kind === 'blueprint' ? 'blueprint' : ref
+    const key = `${asked}@${revision}`
+    if (!answers.has(key)) answers.set(key, opts.source.workspace.find<ItemAnswer>(`/v1/sync/item?ref=${encodeURIComponent(asked)}&revision=${encodeURIComponent(revision)}`))
+    try {
+      const answer = await answers.get(key)!
+      if (!answer) {
+        report.gap = 'not-kept'
+        continue
+      }
+      const files = await projectAtRevision(opts.source, ref, answer, missing, opts.directory)
+      missing = missing.filter((path) => !take(path, files[path]))
+      report.missing = missing
+      if (missing.length) report.gap = 'differs'
+    } catch (err) {
+      report.gap = 'failed'
+      report.error = (err as Error).message
+    }
+  }
+  return out
+}
+
+const KIND_WORD: Partial<Record<SyncKind, string>> = { knowledge: 'Knowledge', skill: 'Skills', plugin: 'Plugins', evaluation: 'evaluations', dataset: 'datasets' }
+
+/** One line on what happened to an item's base, for `pull` and `diff`. */
+export function describeRepair(r: BaseRepair): string {
+  if (!r.missing.length) return `${r.ref}: its base was missing; ${r.revision ? `re-read at ${r.revision} from the workspace` : 'recovered from an unchanged copy'}.`
+  const kind = r.ref.split('/')[0] as SyncKind
+  const why: Record<BaseGap, string> = {
+    offline: 'not read from the platform here',
+    'no-route': 'this platform cannot return earlier versions yet',
+    'no-history': `the platform keeps no earlier versions of ${KIND_WORD[kind] ?? kind}`,
+    'no-revision': 'the lock records no revision to read it at',
+    'not-kept': `the platform no longer keeps ${r.revision}`,
+    differs: `the version read at ${r.revision} differs from what was pulled`,
+    failed: `the platform did not answer (${r.error ?? 'error'})`,
+  }
+  return `${r.ref}: no base for ${r.missing.length === 1 ? r.missing[0] : `${r.missing.length} files`} (${why[r.gap ?? 'failed']}); it merges from what both sides agree on.`
+}

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

@@ -0,0 +1,93 @@
+import { CliError } from '../errors'
+
+/**
+ * The calls a sync makes: to the platform with the project's workspace (or
+ * organization) key, and to the local runtime with its own keys. Plain
+ * `fetch` with an explicit origin and key, never a CLI profile, so a pull
+ * cannot read from or write to whatever deployment a folder happens to be
+ * bound to.
+ */
+
+export interface SyncClient {
+  origin: string
+  get<T>(path: string): Promise<T>
+  /** Like `get`, but a 404 is `null` rather than an error. */
+  find<T>(path: string): Promise<T | null>
+  getBytes(path: string): Promise<Uint8Array>
+  post<T>(path: string, body: unknown): Promise<T>
+}
+
+/** Responses come as `{ data }` envelopes or bare; callers want what is inside. */
+export function unwrap<T>(body: unknown): T {
+  if (body && typeof body === 'object' && 'data' in (body as Record<string, unknown>) && Object.keys(body as object).every((k) => ['data', 'message', 'error', 'success', 'ok', 'meta', 'pagination', 'total', 'nextCursor'].includes(k))) {
+    return (body as { data: T }).data
+  }
+  return body as T
+}
+
+export function normalizeOrigin(raw: string): string {
+  let url: URL
+  try {
+    url = new URL(raw.includes('://') ? raw : `https://${raw}`)
+  } catch {
+    throw new CliError(`"${raw}" is not a platform address`, { code: 'USAGE', hint: 'give the platform API origin, e.g. https://api.acme.frontera.example' })
+  }
+  if (url.protocol !== 'https:' && !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)) {
+    throw new CliError('a platform key is only sent over https', { code: 'USAGE', hint: `use https://${url.host}` })
+  }
+  return url.origin
+}
+
+export function syncClient(origin: string, key: string, headers: Record<string, string> = {}): SyncClient {
+  const call = async (path: string, init: { method?: string; body?: unknown } = {}): Promise<Response> => {
+    let res: Response
+    try {
+      res = await fetch(new URL(path, origin), {
+        method: init.method ?? 'GET',
+        headers: { authorization: `Bearer ${key}`, accept: 'application/json', ...(init.body !== undefined ? { 'content-type': 'application/json' } : {}), ...headers },
+        body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        signal: AbortSignal.timeout(30_000),
+      })
+    } catch (err) {
+      throw new CliError(`${origin} did not answer: ${(err as Error).message}`, { code: 'UNAVAILABLE', hint: 'check the address and your network' })
+    }
+    return res
+  }
+  const fail = async (res: Response, path: string): Promise<never> => {
+    const text = await res.text().catch(() => '')
+    let message = text.slice(0, 300)
+    try {
+      const body = JSON.parse(text) as { message?: string; error?: string | { message?: string } }
+      message = body.message ?? (typeof body.error === 'string' ? body.error : body.error?.message) ?? message
+    } catch {
+      // Keep the text.
+    }
+    if (res.status === 401) throw new CliError('the platform refused the key', { code: 'UNAUTHORIZED', hint: 'check it is a current workspace key (sk-ws-…) for this platform' })
+    if (res.status === 403) throw new CliError(`the key may not read ${path}: ${message}`, { code: 'FORBIDDEN', hint: 'the key’s role decides what it reads; ask a workspace admin for a key that can read it' })
+    throw new CliError(`${path} answered ${res.status}: ${message}`, { code: res.status === 404 ? 'NOT_FOUND' : 'UNAVAILABLE', hint: 'check the platform is reachable, then run the command again' })
+  }
+  const json = async <T>(res: Response, path: string): Promise<T> => {
+    if (!res.ok) return fail(res, path)
+    const text = await res.text()
+    return unwrap<T>(text ? JSON.parse(text) : null)
+  }
+  return {
+    origin,
+    async get<T>(path: string) {
+      return json<T>(await call(path), path)
+    },
+    async find<T>(path: string) {
+      const res = await call(path)
+      if (res.status === 404) return null
+      return json<T>(res, path)
+    },
+    async getBytes(path: string) {
+      const res = await call(path)
+      if (!res.ok) return fail(res, path)
+      return new Uint8Array(await res.arrayBuffer())
+    },
+    async post<T>(path: string, body: unknown) {
+      return json<T>(await call(path, { method: 'POST', body }), path)
+    },
+  }
+}

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

@@ -0,0 +1,122 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parseDocument } from 'yaml'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { configDir } from '../paths'
+import { PROJECT_FILES, type LocalProject } from './local-project'
+
+/**
+ * A project's link to one platform workspace, and the keys that read it.
+ *
+ * The link is committed in `frontera.yaml` (`sync:`), so a teammate who
+ * clones the project sees which workspace it came from. The keys are not:
+ * they live in the macOS keychain under the project's id (a 0600 file
+ * elsewhere), as model provider keys do, and never in the folder.
+ */
+
+export interface SyncLink {
+  /** The platform's API origin, e.g. `https://acme.frontera.example`. */
+  platform: string
+  workspace: string
+  /** Set when an organization key was given. */
+  organization?: string
+  /** `workspace`: the workspace's slice of the Blueprint (default). `organization`: the whole model. */
+  blueprint: 'workspace' | 'organization'
+  /** Names shown in Forge and `sync status`; refreshed on connect. */
+  workspaceName?: string
+  organizationName?: string
+}
+
+export function projectFile(root: string): string {
+  return join(root, PROJECT_FILES.find((f) => existsSync(join(root, f))) ?? PROJECT_FILES[0])
+}
+
+export function readLink(root: string): SyncLink | null {
+  const file = projectFile(root)
+  if (!existsSync(file)) return null
+  const doc = parseDocument(readFileSync(file, 'utf8')).toJS() as { sync?: Partial<SyncLink> } | null
+  const s = doc?.sync
+  if (!s || typeof s.platform !== 'string' || typeof s.workspace !== 'string') return null
+  return {
+    platform: s.platform,
+    workspace: s.workspace,
+    organization: typeof s.organization === 'string' ? s.organization : undefined,
+    blueprint: s.blueprint === 'organization' ? 'organization' : 'workspace',
+    workspaceName: typeof s.workspaceName === 'string' ? s.workspaceName : undefined,
+    organizationName: typeof s.organizationName === 'string' ? s.organizationName : undefined,
+  }
+}
+
+/** Write the link into `frontera.yaml`, keeping the rest of the file and its comments. */
+export function writeLink(root: string, link: SyncLink | null): void {
+  const file = projectFile(root)
+  const doc = parseDocument(existsSync(file) ? readFileSync(file, 'utf8') : '')
+  if (!doc.contents) doc.contents = doc.createNode({}) as never
+  if (!link) {
+    doc.delete('sync')
+  } else {
+    const value: Record<string, string> = { platform: link.platform, workspace: link.workspace }
+    if (link.workspaceName) value.workspaceName = link.workspaceName
+    if (link.organization) value.organization = link.organization
+    if (link.organizationName) value.organizationName = link.organizationName
+    value.blueprint = link.blueprint
+    const existing = doc.get('sync', true) as { commentBefore?: string } | undefined
+    const node = doc.createNode(value) as unknown as { commentBefore?: string }
+    node.commentBefore = existing?.commentBefore ?? ' The platform workspace this project pulls from (`frontera local sync`). Keys are in your keychain, not here.'
+    doc.set('sync', node)
+  }
+  writeFileSync(file, doc.toString())
+}
+
+// ── Keys ─────────────────────────────────────────────────────────────────────
+
+const SERVICE = 'frontera-sync-key'
+export type KeyRole = 'workspace' | 'organization'
+
+function useKeychain(): boolean {
+  return process.platform === 'darwin' && !process.env.FRONTERA_SYNC_KEYS_FILE
+}
+
+function keysFile(): string {
+  return process.env.FRONTERA_SYNC_KEYS_FILE ?? join(configDir(), 'sync-keys.json')
+}
+
+function readKeysFile(): Record<string, string> {
+  try {
+    return existsSync(keysFile()) ? (JSON.parse(readFileSync(keysFile(), 'utf8')) as Record<string, string>) : {}
+  } catch {
+    return {}
+  }
+}
+
+const account = (project: LocalProject, role: KeyRole) => `${project.id}:${role}`
+
+export function setSyncKey(project: LocalProject, role: KeyRole, key: string): void {
+  if (useKeychain()) {
+    const res = spawnSync('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', account(project, role), '-w', key], { stdio: 'ignore' })
+    if (res.status !== 0) throw new Error('the macOS keychain refused the key')
+    return
+  }
+  writeFileAtomic(keysFile(), `${JSON.stringify({ ...readKeysFile(), [account(project, role)]: key }, null, 2)}\n`, 0o600)
+}
+
+export function getSyncKey(project: LocalProject, role: KeyRole): string | null {
+  if (useKeychain()) {
+    const res = spawnSync('security', ['find-generic-password', '-s', SERVICE, '-a', account(project, role), '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    return res.status === 0 ? res.stdout.trim() || null : null
+  }
+  return readKeysFile()[account(project, role)] ?? null
+}
+
+export function removeSyncKey(project: LocalProject, role: KeyRole): void {
+  if (useKeychain()) {
+    spawnSync('security', ['delete-generic-password', '-s', SERVICE, '-a', account(project, role)], { stdio: 'ignore' })
+    return
+  }
+  const keys = readKeysFile()
+  delete keys[account(project, role)]
+  writeFileAtomic(keysFile(), `${JSON.stringify(keys, null, 2)}\n`, 0o600)
+}