@frontera-sdk/cli 1.52.28 → 1.52.30

package/src/local/local-build-summary.ts

@@ -0,0 +1,106 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { buildCounts, buildSummaryLine, buildView, combineBuilds, loadSettingsDifferences, refOfTarget, type ItemBuild, type ItemBuildState } from './local-applied'
+import { blueprintBuild, localOrganizationId, objectStatus, projectBlueprintOutline } from './local-blueprint-outline'
+import { allTargets } from './local-dev-sync'
+
+/**
+ * How the last `local dev` left the project, counted one way for every
+ * surface that says it: `local sync status`, Forge's project home and the
+ * Agent page in Studio. Read from the project alone (`.frontera/local/`
+ * against the files now), so it answers whether or not the runtime runs.
+ */
+
+function entries(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((name) => !name.startsWith('.'))
+  } catch {
+    return []
+  }
+}
+
+const projectOf = (root: string, id = '') => ({ root, id, stateDir: join(root, '.frontera', 'local') })
+
+/**
+ * How each Agent (its file, behavior settings, tools and lessons together),
+ * workflow and Function was built, by the reference other files name it by
+ * (`agent/desk`). Null before the project's runtime first started.
+ */
+export function projectItemBuilds(root: string, id = ''): Record<string, ItemBuild> | null {
+  const org = localOrganizationId(root)
+  if (!org) return null
+  const view = buildView(projectOf(root, id), org)
+  const byRef = new Map<string, ItemBuild[]>()
+  for (const target of allTargets(root)) {
+    // Every kind the project home lists rows of; datasets and the Blueprint as a whole are not rows.
+    if (target.kind === 'dataset' || target.kind === 'blueprint') continue
+    const ref = refOfTarget(target)
+    byRef.set(ref, [...(byRef.get(ref) ?? []), view.get(target.key)!])
+  }
+  return Object.fromEntries([...byRef].map(([ref, list]) => [ref, combineBuilds(list)]))
+}
+
+/** One item's build, with each adaptation in words: what an Agent's page says about how it runs here. */
+export function itemBuild(root: string, ref: string, id = ''): ItemBuild | null {
+  return projectItemBuilds(root, id)?.[ref] ?? null
+}
+
+export interface ProjectBuildSummary {
+  /** "49 built · 2 adapted · 3 blocked", with the settings that differ from the workspace. */
+  line: string
+  /** Short: "2 problems", or "All 12 built" — what to say first. */
+  headline: string
+  /** Blocked and failed together: what does not run. */
+  problems: number
+  counts: Record<ItemBuildState, number>
+  /** Where the runtime's organization settings differ from the workspace's, one line each. */
+  settings: string[]
+}
+
+/**
+ * The project's build in a few numbers, over every Agent, workflow, Function
+ * and Blueprint object type the project holds. An object type left off by
+ * design (it reads the platform's media) is not counted: it is not a problem
+ * to fix. Null before the runtime first started, or when there is nothing.
+ */
+export function projectBuildSummary(root: string, id = ''): ProjectBuildSummary | null {
+  const builds = projectItemBuilds(root, id)
+  if (!builds) return null
+  const agents = entries(join(root, 'agents')).filter((slug) => existsSync(join(root, 'agents', slug, 'agent.json')))
+  const workflows = entries(join(root, 'workflows')).filter((f) => /\.ya?ml$/.test(f)).map((f) => f.replace(/\.ya?ml$/, ''))
+  const functions = entries(join(root, 'functions')).flatMap((f) => {
+    const at = join(root, 'functions', f)
+    if (/\.ts$/.test(f) && !/\.(test|d)\.ts$/.test(f) && statSync(at).isFile()) return [f.replace(/\.ts$/, '')]
+    return existsSync(join(at, 'package.json')) ? [f] : []
+  })
+  const blueprint = blueprintBuild(root)
+  const objects = projectBlueprintOutline(root, blueprint.actions).flatMap((t): ItemBuildState[] => {
+    const kind = objectStatus(t, blueprint).kind
+    return kind === 'platform-only' ? [] : [kind as ItemBuildState]
+  })
+  const listed = new Set([...agents.map((a) => `agent/${a}`), ...workflows.map((w) => `workflow/${w}`), ...functions.map((f) => `function/${f}`)])
+  const states: ItemBuildState[] = [
+    ...[...listed].map((ref) => builds[ref]?.state ?? 'not-applied'),
+    // The other kinds the runtime applies (skills, knowledge, Plugins, Chat Apps…); evaluations are run, not applied.
+    ...Object.entries(builds).filter(([ref]) => !listed.has(ref) && !ref.startsWith('evaluation/')).map(([, b]) => b.state),
+    ...objects,
+  ]
+  if (!states.length) return null
+  const counts = buildCounts(states)
+  const org = localOrganizationId(root)
+  const settings = org ? loadSettingsDifferences(projectOf(root, id), org) : []
+  const problems = counts.blocked + counts.failed
+  const line = settings.length ? `${buildSummaryLine(counts)} · ${settings.length} setting${settings.length === 1 ? ' differs' : 's differ'} from the workspace` : buildSummaryLine(counts)
+  const headline = problems ? `${problems} problem${problems === 1 ? '' : 's'}` : counts['not-applied'] ? `${counts['not-applied']} not applied yet` : `All ${states.length} built`
+  return { line, headline, problems, counts, settings }
+}
+
+/** The CLI's line for the build: the problems first, then the rest, short ("2 problems: 1 failed, 1 blocked · 7 built, 3 adapted"). */
+export function buildStatusText(summary: ProjectBuildSummary): string {
+  const c = summary.counts
+  const problems = [c.failed ? `${c.failed} failed` : '', c.blocked ? `${c.blocked} blocked` : ''].filter(Boolean).join(', ')
+  const rest = [c.built ? `${c.built} built` : '', c.adapted ? `${c.adapted} adapted` : '', c.stubbed ? `${c.stubbed} stubbed` : '', c['not-applied'] ? `${c['not-applied']} not applied yet` : ''].filter(Boolean).join(', ')
+  const settings = summary.settings.length ? `${summary.settings.length} setting${summary.settings.length === 1 ? ' differs' : 's differ'} from the workspace` : ''
+  return [summary.problems ? `${summary.headline}: ${problems}` : rest, summary.problems ? rest : '', settings].filter(Boolean).join(' · ')
+}

package/src/local/local-chat-apps.ts

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { RemoteItem } from './local-sync-plan'
+import { itemRef, referencesIn, toIds, toNames, type Directory } from './local-sync-refs'
+
+/**
+ * Chat Apps: the experience an Agent is used in on the platform. A Chat App
+ * holds what people see first (welcome, suggested prompts, the context it
+ * gives its Agents, an accent), its roster of Agents, which features it
+ * offers (file upload, web browsing, voice, sharing…, each a limit on what
+ * its Agents may do there), and its conversation and memory behaviour. A
+ * pull writes each published App as `chat-apps/<slug>.json`, its Agents
+ * named (`agent/support-concierge`); `local dev` saves it on the local
+ * runtime, and a change request proposes it back.
+ *
+ * Who may open an App and its endpoints (its address, the widget) are the
+ * platform's: people and deployment (design §8). The Agent versions a
+ * published App pins are the platform's too: locally every Agent is a draft,
+ * so the App is saved as the runtime owner's draft: its experience is on the
+ * runtime, and it opens once its Agents are published.
+ */
+
+/** A Chat App as `/v1/sync/chat-apps` lists it. */
+export interface ChatAppRow {
+  id: string
+  slug: string
+  name: string
+  description?: string | null
+  version?: string | null
+  configuration?: Record<string, unknown> | null
+}
+
+/** The configuration's sections a project file keeps, in this order. */
+const SECTIONS = ['presentation', 'roster', 'features', 'conversation', 'memory'] as const
+
+export const chatAppPath = (slug: string) => `chat-apps/${slug}.json`
+
+/** Why a Chat App stays a draft locally, as the build and the Pull dialog say it. */
+export const CHAT_APP_DRAFT = 'Saved as the owner’s draft here and opened as its preview, its Agents running their drafts: a Chat App publishes only published Agents, and the local runtime’s Agents are drafts'
+
+/**
+ * The project's file for an App's live configuration: its Agents by name,
+ * and without the Agent versions the platform pinned when it was published
+ * (a version number means nothing on another runtime).
+ */
+export function chatAppDocument(row: ChatAppRow, directory: Directory): { doc: Record<string, unknown>; unresolved: RemoteItem['unresolved'] } {
+  const config = (row.configuration ?? {}) as Record<string, unknown>
+  const roster = { ...((config.roster ?? {}) as Record<string, unknown>) }
+  if (Array.isArray(roster.agents)) {
+    roster.agents = (roster.agents as Array<Record<string, unknown>>).map(({ agentVersionNumber: _pinned, ...entry }) => entry)
+  }
+  const doc: Record<string, unknown> = {
+    name: row.name,
+    ...(row.description ? { description: row.description } : {}),
+    schemaVersion: config.schemaVersion ?? 1,
+  }
+  for (const key of SECTIONS) if (config[key] !== undefined) doc[key] = key === 'roster' ? roster : config[key]
+  const named = toNames(doc, directory)
+  return { doc: named.doc, unresolved: named.unresolved }
+}
+
+/** The workspace's published Chat Apps as project items; one never published is counted in the notes. */
+export function readChatApps(rows: ChatAppRow[], directory: Directory, wanted: (ref: string) => boolean, notes: string[]): RemoteItem[] {
+  const out: RemoteItem[] = []
+  let unpublished = 0
+  for (const row of rows) {
+    if (!row.version || !row.configuration) {
+      unpublished += 1
+      continue
+    }
+    const ref = `chat-app/${row.slug}`
+    if (!wanted(ref)) continue
+    const { doc, unresolved } = chatAppDocument(row, directory)
+    const requires = referencesIn(doc).map((r) => itemRef(r.kind, r.name))
+    const itemNotes = ['Who may open it and its addresses stay on the platform']
+    if (unresolved.length) itemNotes.push(`${unresolved.length === 1 ? 'An Agent on its roster is' : `${unresolved.length} Agents on its roster are`} not in this workspace’s list, so ${unresolved.length === 1 ? 'it keeps its' : 'they keep their'} platform id`)
+    out.push({ ref, kind: 'chat-app', name: row.slug, title: row.name, files: { [chatAppPath(row.slug)]: `${JSON.stringify(doc, null, 2)}\n` }, unresolved, notes: itemNotes, requires, id: row.id, version: `v${row.version}` })
+  }
+  if (unpublished) notes.push(`${unpublished} Chat App${unpublished === 1 ? ' was' : 's were'} never published, so ${unpublished === 1 ? 'it stays' : 'they stay'} on the platform: a draft is its author’s own`)
+  return out
+}
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as Record<string, unknown> | null
+
+const errorOf = (a: { status: number; body: unknown }) => {
+  const b = a.body as { message?: unknown } | null
+  return `${a.status} ${String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 200)}`
+}
+
+export interface ChatAppApplied {
+  ok: boolean
+  output: string
+  /** Not applied because it names these, which the project holds but the runtime does not have yet. */
+  missing?: string[]
+}
+
+/**
+ * Save a project's Chat App on the runtime: create it (or find it by slug),
+ * set its name and description, and save its configuration as the owner's
+ * draft, with the roster's Agents as this runtime's ids. Then publish it
+ * when the runtime allows: a Chat App publishes only published Agents, and
+ * locally every Agent is a draft, so it stays the owner's draft, which the
+ * build says. An Agent the project does not
+ * hold is left off the roster, and said; one it holds but the runtime does
+ * not have yet holds the App back until it does.
+ */
+export async function applyChatApp(root: string, slug: string, call: Call, directory: () => Promise<Directory>, provides: (ref: string) => boolean): Promise<ChatAppApplied> {
+  const path = join(root, chatAppPath(slug))
+  if (!existsSync(path)) return { ok: false, output: `error [CHAT_APP]: ${chatAppPath(slug)} is missing` }
+  let doc: Record<string, unknown>
+  try {
+    doc = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${chatAppPath(slug)} is not valid JSON: ${(err as Error).message}` }
+  }
+  const lines: string[] = []
+  const dir = await directory()
+  const roster = { ...((doc.roster ?? {}) as Record<string, unknown>) }
+  const entries = Array.isArray(roster.agents) ? (roster.agents as Array<Record<string, unknown>>) : []
+  const waiting: string[] = []
+  const kept = entries.filter((e) => {
+    const ref = typeof e.agentConfigId === 'string' ? e.agentConfigId : ''
+    if (!toIds(ref, dir).unresolved.length) return true
+    if (provides(ref)) waiting.push(ref)
+    else lines.push(`  warning: Its roster names ${ref.replace('/', ' ')}, which isn’t in this project: the App opens without it here`)
+    return false
+  })
+  if (waiting.length) {
+    return { ok: false, missing: waiting, output: [`error [UNRESOLVED_REFERENCE]: ${chatAppPath(slug)} names what this runtime does not have`, ...waiting.map((w) => `  ${w}: in the project, not applied yet`)].join('\n') }
+  }
+  // The live version when it is published (null), as the platform's editor drafts it.
+  roster.agents = kept.map((e) => ({ ...e, agentVersionNumber: null }))
+  const ids = new Set(kept.map((e) => e.agentConfigId))
+  if (typeof roster.defaultAgentConfigId === 'string' && !ids.has(roster.defaultAgentConfigId)) roster.defaultAgentConfigId = kept[0]?.agentConfigId ?? null
+  const { name: _name, description: _description, ...configuration } = { ...doc, roster } as Record<string, unknown>
+  const resolved = toIds(configuration, dir).doc as Record<string, unknown>
+  const name = typeof doc.name === 'string' && doc.name.trim() ? doc.name.trim() : slug
+  const description = typeof doc.description === 'string' ? doc.description : null
+  const accent = ((doc.presentation ?? {}) as { accent?: unknown }).accent
+
+  const ensured = await call('POST', '/v1/platform-apps/ensure', { slug, displayName: name, kind: 'chat', ...(description ? { description } : {}), ...(typeof accent === 'string' ? { accent } : {}) })
+  if (ensured.status >= 400) return { ok: false, output: `error [CHAT_APP]: ${errorOf(ensured)}` }
+  const appId = String(dataOf(ensured.body)?.id ?? '')
+  if (!appId) return { ok: false, output: 'error [CHAT_APP]: the runtime did not return the App' }
+  if (!dataOf(ensured.body)?.created) {
+    const renamed = await call('PATCH', `/v1/platform-apps/${encodeURIComponent(appId)}`, { displayName: name, description })
+    if (renamed.status >= 400) lines.push(`  warning: Its name and description could not be set here (${errorOf(renamed)})`)
+  }
+  const draft = await call('PUT', `/v1/chat-apps/${encodeURIComponent(appId)}/draft`, { configuration: resolved })
+  if (draft.status >= 400) return { ok: false, output: `error [CHAT_APP]: ${errorOf(draft)}` }
+  const published = await call('POST', `/v1/chat-apps/${encodeURIComponent(appId)}/publish`, { configuration: resolved })
+  if (published.status >= 400) {
+    const findings = ((dataOf(published.body)?.details ?? (published.body as { details?: unknown } | null)?.details) ?? []) as Array<{ code?: string; message?: string }>
+    const list = Array.isArray(findings) ? findings : []
+    if (list.length && list.every((f) => f.code === 'agent.unpublished' || f.code === 'agent.unavailable' || f.code === 'roster.empty')) {
+      lines.push(
+        list.some((f) => f.code === 'roster.empty')
+          ? '  warning: It has no Agent on its roster here, so it stays a draft'
+          : `  warning: ${CHAT_APP_DRAFT}`,
+      )
+    } else {
+      lines.push(`  warning: It stays a draft here: ${list.map((f) => f.message).filter(Boolean).join('; ') || errorOf(published)}`)
+    }
+  }
+  lines.unshift(`  saved Chat App ${name}`)
+  return { ok: true, output: lines.join('\n') }
+}