@frontera-sdk/cli 1.46.6 → 1.46.7

package/src/forge/projects.ts

@@ -0,0 +1,349 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, join, relative, resolve, sep } from 'node:path'
+
+import type { ForgeChangeStatus, ForgeChangedFile, ForgeChanges, ForgeFileEntry } from '@frontera-sdk/forge-contracts'
+
+import { findProjectRoot } from '../context'
+import { readProject } from '../project'
+import { applyClaudeImport, applyManagedBlock, type BlockMarkers } from '../kit'
+import { ensureGitignored, findContext, writeContext } from '../project-context'
+import { listProfiles, normalizeOrigin } from '../profiles'
+import { badRequest } from './http'
+import type { NewProject } from './store'
+
+/** Directories nobody browses by hand, and that would swamp a listing. */
+const SKIPPED_DIRS = new Set(['node_modules', '.git'])
+
+/** Untracked files above this are counted as "large", not read line by line. */
+const MAX_COUNTED_BYTES = 1024 * 1024
+
+function git(root: string, args: string[]): { ok: boolean; out: string } {
+  const res = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  if (res.error || res.status !== 0) return { ok: false, out: '' }
+  return { ok: true, out: res.stdout ?? '' }
+}
+
+export function isGitWorkTree(root: string): boolean {
+  const res = git(root, ['rev-parse', '--is-inside-work-tree'])
+  return res.ok && res.out.trim() === 'true'
+}
+
+/** What a root is, detected fresh: a git tree, a Frontera App, a bound profile. */
+export function inspectRoot(rawRoot: string): NewProject {
+  if (typeof rawRoot !== 'string' || rawRoot.trim() === '') throw badRequest('root is required')
+  const root = resolve(rawRoot)
+  let stat
+  try {
+    stat = statSync(root)
+  } catch {
+    throw badRequest(`${root} does not exist`)
+  }
+  if (!stat.isDirectory()) throw badRequest(`${root} is not a directory`)
+
+  let appSlug: string | null = null
+  if (findProjectRoot(root) === root) {
+    try {
+      appSlug = readProject(root).slug
+    } catch {
+      appSlug = null
+    }
+  }
+
+  let profile: string | null = null
+  try {
+    profile = findContext(root)?.profile ?? null
+  } catch {
+    // A corrupt context file is the CLI's problem to report, not a reason to
+    // refuse opening the folder.
+    profile = null
+  }
+
+  return { root, name: basename(root) || root, git: isGitWorkTree(root), appSlug, profile }
+}
+
+/**
+ * What is already true in this folder, written where both hosts read it.
+ *
+ * Codex reads `AGENTS.md` and Claude Code reads `CLAUDE.md` (which imports it)
+ * before the first turn, with no prompt injection and no per-turn cost — so
+ * this is the harness-native place to hand over the situation. It survives the
+ * developer running `claude` here from their own terminal, which a per-turn
+ * brief would not.
+ *
+ * FACTS, not instructions. The skills say what to do; a brief that argues with
+ * them produces a model that argues with both. Everything here is something
+ * Forge arranged and the agent would otherwise have to derive: which
+ * deployment, which workspace, which credential, what is already connected.
+ *
+ * Written as a managed block, so anything the developer adds to the same file
+ * stays where they put it.
+ */
+const FORGE_MARKERS: BlockMarkers = {
+  begin: '<!-- frontera:forge:begin — managed by Frontera Forge; edits here are replaced -->',
+  end: '<!-- frontera:forge:end -->',
+}
+
+function situationBlock(input: {
+  workspaceName: string
+  workspaceId: string
+  apiUrl: string | null
+  profile: string | null
+  root: string
+}): string {
+  const lines = [
+    '## Frontera Forge',
+    '',
+    `This folder is managed by Frontera Forge for the **${input.workspaceName}** workspace`
+      + `${input.apiUrl ? ` on ${input.apiUrl}` : ''}. It is not a checkout of a`
+      + " product repository — it is where this workspace's local work lives.",
+    '',
+    '- The `frontera` CLI is on PATH.'
+      + (input.profile
+        ? ` This directory is bound to the \`${input.profile}\` profile (\`.frontera/context.json\`), so commands here need no \`--profile\` or \`--api-url\`.`
+        : ' No profile is bound to this directory yet, so commands need `--profile` or `--api-url`.'),
+    '- The platform\'s tools are connected as the `frontera` MCP server: Apps,'
+      + ' Agents, Blueprint, Skills, Knowledge, Packs and navigation are available'
+      + ' as `mcp__frontera__*` tools. Prefer them over guessing at platform state,'
+      + ' and over shelling out for something a tool already answers.',
+    '- The Frontera plugin is installed in this host, so the `frontera:*` skills'
+      + ' (what the artifacts are, how to author and publish them) load on demand.',
+    '- App source belongs at `./<slug>`, pulled with'
+      + ' `frontera app pull <slug> --dir ./<slug>`.',
+    '',
+    `Workspace id \`${input.workspaceId}\`.`,
+  ]
+  return lines.join('\n')
+}
+
+/**
+ * Write (or refresh) the situation into `AGENTS.md` + `CLAUDE.md`.
+ *
+ * Idempotent and cheap: both hosts re-read the files each session, so keeping
+ * them current on every folder resolve is how a workspace rename or a
+ * re-binding reaches the agent without anyone remembering to do it.
+ */
+function writeSituationFiles(root: string, body: string): void {
+  try {
+    const agentsPath = join(root, 'AGENTS.md')
+    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : null
+    const next = applyManagedBlock(existing, body, FORGE_MARKERS)
+    if (next !== existing) writeFileSync(agentsPath, next)
+
+    const claudePath = join(root, 'CLAUDE.md')
+    const claudeExisting = existsSync(claudePath) ? readFileSync(claudePath, 'utf8') : null
+    const { content } = applyClaudeImport(claudeExisting, '@AGENTS.md')
+    if (content !== claudeExisting) writeFileSync(claudePath, content)
+  } catch {
+    // A read-only folder is the developer's business; the session still works.
+  }
+}
+
+/** Where Forge keeps a workspace's folder. Visible on purpose: developers open it in editors. */
+export function workspaceRoot(workspaceSlug: string): string {
+  const safe = workspaceSlug.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '') || 'workspace'
+  return join(homedir(), 'Frontera', safe)
+}
+
+/** The profile bound to this deployment's API origin, if the CLI has one. */
+function profileForOrigin(apiUrl: string | null): string | null {
+  if (!apiUrl) return null
+  let origin: string
+  try {
+    origin = normalizeOrigin(apiUrl)
+  } catch {
+    return null
+  }
+  try {
+    const match = listProfiles().find((p) => {
+      try {
+        return normalizeOrigin(p.profile.apiUrl) === origin
+      } catch {
+        return false
+      }
+    })
+    return match?.name ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Create-or-adopt the managed folder for a workspace: mkdir, `git init` so
+ * Changes has a baseline, and bind the deployment's profile so `frontera`
+ * and the host's Frontera MCP resolve there without anyone choosing.
+ * Idempotent; a folder the developer already turned into a repo or bound
+ * to a profile is left as it is.
+ */
+export function ensureWorkspaceProject(
+  input: { workspaceId: string; workspaceSlug: string; workspaceName?: string },
+  apiUrl: string | null,
+  warn: (message: string) => void = () => {},
+): NewProject {
+  const root = workspaceRoot(input.workspaceSlug)
+  mkdirSync(root, { recursive: true })
+  if (!isGitWorkTree(root)) {
+    spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' })
+  }
+  let bound: string | null = null
+  try {
+    bound = findContext(root)?.profile ?? null
+  } catch {
+    bound = null
+  }
+  if (!bound) {
+    const profile = profileForOrigin(apiUrl)
+    if (!profile) {
+      warn(`no CLI profile for ${apiUrl ?? '(no api url)'}; ${root} left unbound`)
+    } else {
+      try {
+        writeContext(root, profile)
+        if (existsSync(join(root, '.git'))) ensureGitignored(root)
+      } catch (error) {
+        // Binding is a convenience; the folder still works without it.
+        warn(`could not bind ${root} to profile ${profile}: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
+  const detected = inspectRoot(root)
+  const name = input.workspaceName?.trim() || detected.name
+  writeSituationFiles(
+    root,
+    situationBlock({
+      workspaceName: name,
+      workspaceId: input.workspaceId,
+      apiUrl,
+      profile: detected.profile,
+      root,
+    }),
+  )
+  return { ...detected, name, workspaceId: input.workspaceId }
+}
+
+/** One level of a project tree, directories first. Never escapes the root. */
+export function listFiles(root: string, rel: string): ForgeFileEntry[] {
+  const target = resolve(root, rel || '.')
+  const inside = target === root || target.startsWith(root + sep)
+  if (!inside) throw badRequest('path escapes the project root')
+  let entries
+  try {
+    entries = readdirSync(target, { withFileTypes: true })
+  } catch {
+    throw badRequest(`${relative(root, target) || '.'} is not a readable directory`)
+  }
+  const out: ForgeFileEntry[] = []
+  for (const entry of entries) {
+    if (SKIPPED_DIRS.has(entry.name)) continue
+    const abs = join(target, entry.name)
+    const path = relative(root, abs).split(sep).join('/')
+    if (entry.isDirectory()) {
+      out.push({ name: entry.name, path, kind: 'dir' })
+    } else {
+      let size: number | undefined
+      try {
+        size = statSync(abs).size
+      } catch {
+        size = undefined
+      }
+      out.push({ name: entry.name, path, kind: 'file', ...(size !== undefined ? { size } : {}) })
+    }
+  }
+  return out.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === 'dir' ? -1 : 1))
+}
+
+function statusFor(xy: string): ForgeChangeStatus | null {
+  if (xy === '??') return 'untracked'
+  const x = xy[0] ?? ' '
+  const y = xy[1] ?? ' '
+  const code = x !== ' ' ? x : y
+  switch (code) {
+    case 'A':
+      return 'added'
+    case 'D':
+      return 'deleted'
+    case 'R':
+    case 'C':
+      return 'renamed'
+    case 'M':
+    case 'T':
+    case 'U':
+      return 'modified'
+    default:
+      return null
+  }
+}
+
+function countLines(abs: string): number {
+  try {
+    const stat = statSync(abs)
+    if (!stat.isFile() || stat.size > MAX_COUNTED_BYTES) return 0
+    const buf = readFileSync(abs)
+    // A NUL in the first block is the same heuristic git uses for "binary".
+    if (buf.subarray(0, 8000).includes(0)) return 0
+    let n = 0
+    for (const byte of buf) if (byte === 10) n += 1
+    if (buf.length > 0 && buf[buf.length - 1] !== 10) n += 1
+    return n
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Parse `git diff --numstat`: `added\tdeleted\tpath`, with `-` for binary and
+ * `old => new` (or `{a => b}/rest`) paths for renames. The rename form is
+ * folded to the new path so it matches the status listing.
+ */
+function parseNumstat(out: string): Map<string, { additions: number; deletions: number }> {
+  const map = new Map<string, { additions: number; deletions: number }>()
+  for (const line of out.split('\n')) {
+    if (!line) continue
+    const [a, d, ...rest] = line.split('\t')
+    const rawPath = rest.join('\t')
+    if (!rawPath) continue
+    const path = rawPath.includes(' => ')
+      ? rawPath.replace(/\{([^{}]*) => ([^{}]*)\}/g, '$2').replace(/^.* => /, '')
+      : rawPath
+    map.set(path, { additions: a === '-' ? 0 : Number(a) || 0, deletions: d === '-' ? 0 : Number(d) || 0 })
+  }
+  return map
+}
+
+/** Working tree vs HEAD. Not a git tree, or no commits yet: as much as exists. */
+export function readChanges(root: string): ForgeChanges {
+  if (!isGitWorkTree(root)) return { files: [], patch: '', head: null, branch: null }
+
+  const headRes = git(root, ['rev-parse', 'HEAD'])
+  const head = headRes.ok ? headRes.out.trim() : null
+  const branchRes = git(root, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  const branch = branchRes.ok ? branchRes.out.trim() : null
+
+  // Before the first commit there is no HEAD to diff against; the index is
+  // the closest thing to a baseline.
+  const base = head ? ['HEAD'] : []
+  const numstat = parseNumstat(git(root, ['diff', ...base, '--numstat']).out)
+  const patch = git(root, ['diff', ...base]).out
+
+  const files: ForgeChangedFile[] = []
+  const status = git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])
+  const entries = status.out.split('\0')
+  for (let i = 0; i < entries.length; i += 1) {
+    const entry = entries[i]
+    if (!entry || entry.length < 4) continue
+    const xy = entry.slice(0, 2)
+    const path = entry.slice(3)
+    const kind = statusFor(xy)
+    // A rename carries its origin as the next NUL-separated field.
+    if (xy[0] === 'R' || xy[0] === 'C') i += 1
+    if (!kind) continue
+    if (kind === 'untracked') {
+      files.push({ path, status: kind, additions: countLines(join(root, path)), deletions: 0 })
+      continue
+    }
+    const counts = numstat.get(path) ?? { additions: 0, deletions: 0 }
+    files.push({ path, status: kind, ...counts })
+  }
+
+  return { files, patch, head, branch }
+}

package/src/forge/protocol.ts

@@ -0,0 +1,38 @@
+/**
+ * The handful of wire constants the daemon needs at RUNTIME.
+ *
+ * They are duplicated from `@frontera-sdk/forge-contracts` on purpose. That
+ * package is private and internal — it is the shared type surface for the
+ * desktop shell and the web surface — while this CLI is published to npm. A
+ * published package that depends on an unpublished one resolves nowhere:
+ * `bunx @frontera-sdk/cli` would fail for every consumer, which is the exact
+ * breakage the release workflow's `workspace:` gate exists to catch.
+ *
+ * So the contracts package stays a devDependency here, imported for types
+ * only (erased at build), and the four values live here. `protocol.test.ts`
+ * asserts the two agree, so the duplication cannot drift silently.
+ */
+
+/** Response headers the platform's chat client reads. */
+export const FORGE_HEADERS = {
+  conversationId: 'X-Conversation-Id',
+  runId: 'x-workflow-run-id',
+  agentRuntime: 'x-agent-runtime',
+} as const
+
+/** Unauthenticated readiness probe the desktop shell polls. */
+export const FORGE_WELL_KNOWN_PATH = '/.well-known/frontera/forge'
+
+/** Run ids carry this so the web treats them as non-steerable runs. */
+export const FORGE_RUN_ID_PREFIX = 'forge_'
+
+/** Platform chat affordances that have no meaning against a local harness. */
+export const FORGE_DISABLED_CAPABILITIES = [
+  'fork',
+  'share',
+  'export',
+  'schedule',
+  'labels',
+  'canvas',
+  'overview',
+] as const

package/src/forge/runs.ts

@@ -0,0 +1,250 @@
+import type { ForgeProject } from '@frontera-sdk/forge-contracts'
+
+import { FORGE_RUN_ID_PREFIX } from './protocol'
+import { readUIMessageStream, type UIMessage, type UIMessageChunk } from 'ai'
+
+import type { AdapterFactory, ApprovalDecision, HostAdapter } from './adapter'
+import type { Logger } from './log'
+import type { ForgeStore, StoredThread } from './store'
+
+/**
+ * Live turns. Each run keeps an append-only chunk journal in memory and fans
+ * every chunk out to whoever is streaming it — the response to `POST /v1/chat`
+ * and any `GET /v1/chat/:runId/stream` that reconnected after a reload. When
+ * the host finishes, the journal is folded into one assistant `UIMessage`
+ * and persisted; the journal itself is dropped.
+ */
+
+interface Subscriber {
+  push(chunk: UIMessageChunk): void
+  close(): void
+}
+
+interface LiveRun {
+  id: string
+  threadId: string
+  messageId: string
+  journal: UIMessageChunk[]
+  subscribers: Set<Subscriber>
+  finished: boolean
+  adapter: HostAdapter
+  abort: AbortController
+}
+
+/** Thread titles are the first line of the first message, cut short. */
+const TITLE_LENGTH = 60
+
+export function titleFrom(text: string): string {
+  const line = text.split('\n').find((l) => l.trim() !== '') ?? text
+  const trimmed = line.trim()
+  return trimmed.length > TITLE_LENGTH ? `${trimmed.slice(0, TITLE_LENGTH - 1)}…` : trimmed
+}
+
+/**
+ * Fold a chunk journal into the message the AI SDK would have built on the
+ * client. The reducer throws on a malformed sequence (a result for a call it
+ * never saw); the fallback keeps the text so a turn is never lost entirely.
+ */
+export async function assembleMessage(messageId: string, journal: UIMessageChunk[]): Promise<UIMessage> {
+  const stream = new ReadableStream<UIMessageChunk>({
+    start(controller) {
+      for (const chunk of journal) controller.enqueue(chunk)
+      controller.close()
+    },
+  })
+  let last: UIMessage = { id: messageId, role: 'assistant', parts: [] }
+  try {
+    for await (const message of readUIMessageStream({ message: last, stream, onError: () => {}, terminateOnError: false })) {
+      last = message
+    }
+    return { ...last, id: messageId, role: 'assistant' }
+  } catch {
+    return fallbackMessage(messageId, journal)
+  }
+}
+
+function fallbackMessage(messageId: string, journal: UIMessageChunk[]): UIMessage {
+  const text = journal
+    .map((chunk) => (chunk.type === 'text-delta' ? chunk.delta : ''))
+    .join('')
+  const error = journal.find((chunk) => chunk.type === 'error')
+  const parts: UIMessage['parts'] = []
+  if (text) parts.push({ type: 'text', text, state: 'done' })
+  if (error && error.type === 'error') parts.push({ type: 'text', text: `Error: ${error.errorText}`, state: 'done' })
+  return { id: messageId, role: 'assistant', parts }
+}
+
+export class RunManager {
+  private readonly live = new Map<string, LiveRun>()
+
+  constructor(
+    private readonly store: ForgeStore,
+    private readonly adapters: AdapterFactory,
+    private readonly log: Logger,
+    private readonly apiUrl: string,
+  ) {}
+
+  activeRunFor(threadId: string): string | null {
+    for (const run of this.live.values()) if (run.threadId === threadId && !run.finished) return run.id
+    return null
+  }
+
+  /** Persist the user's message, open a run, start the host. Returns the live stream. */
+  start(thread: StoredThread, project: ForgeProject, text: string): { runId: string; stream: ReadableStream<UIMessageChunk> } {
+    const runId = `${FORGE_RUN_ID_PREFIX}${crypto.randomUUID()}`
+    const messageId = crypto.randomUUID()
+
+    this.store.appendMessage(thread.id, {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text }],
+    })
+    this.store.insertRun(runId, thread.id)
+    const running = this.store.updateThread(thread.id, {
+      status: 'running',
+      activeRunId: runId,
+      ...(thread.title === null ? { title: titleFrom(text) } : {}),
+    })
+
+    const run: LiveRun = {
+      id: runId,
+      threadId: thread.id,
+      messageId,
+      journal: [],
+      subscribers: new Set(),
+      finished: false,
+      adapter: this.adapters(thread.host),
+      abort: new AbortController(),
+    }
+    this.live.set(runId, run)
+
+    void this.execute(run, running, project, text)
+    return { runId, stream: this.streamFrom(run, 0) }
+  }
+
+  /** Replay from `startIndex`, then live until the run finishes. Null when the run is not live. */
+  subscribe(runId: string, startIndex: number): ReadableStream<UIMessageChunk> | null {
+    const run = this.live.get(runId)
+    if (!run) return null
+    return this.streamFrom(run, Math.max(0, startIndex))
+  }
+
+  async cancel(runId: string): Promise<boolean> {
+    const run = this.live.get(runId)
+    if (!run || run.finished) return false
+    run.abort.abort()
+    await run.adapter.interrupt()
+    return true
+  }
+
+  respondApproval(threadId: string, approvalId: string, decision: ApprovalDecision): boolean {
+    for (const run of this.live.values()) {
+      if (run.threadId !== threadId || run.finished) continue
+      if (run.adapter.respondApproval(approvalId, decision)) return true
+    }
+    return false
+  }
+
+  /** Interrupt every live run — daemon shutdown. */
+  async stopAll(): Promise<void> {
+    await Promise.all([...this.live.keys()].map((id) => this.cancel(id)))
+  }
+
+  private streamFrom(run: LiveRun, startIndex: number): ReadableStream<UIMessageChunk> {
+    let subscriber: Subscriber | null = null
+    return new ReadableStream<UIMessageChunk>({
+      start(controller) {
+        // Replay and subscribe in one synchronous step, so no chunk can land
+        // between the slice and the subscription.
+        for (const chunk of run.journal.slice(startIndex)) controller.enqueue(chunk)
+        if (run.finished) {
+          controller.close()
+          return
+        }
+        subscriber = {
+          push: (chunk) => {
+            try {
+              controller.enqueue(chunk)
+            } catch {
+              // Consumer went away; the close below removes us.
+            }
+          },
+          close: () => {
+            try {
+              controller.close()
+            } catch {
+              // Already closed.
+            }
+          },
+        }
+        run.subscribers.add(subscriber)
+      },
+      cancel() {
+        if (subscriber) run.subscribers.delete(subscriber)
+      },
+    })
+  }
+
+  private async execute(run: LiveRun, thread: StoredThread, project: ForgeProject, text: string): Promise<void> {
+    const emit = (chunk: UIMessageChunk) => {
+      if (run.finished) return
+      run.journal.push(chunk)
+      for (const sub of run.subscribers) sub.push(chunk)
+    }
+
+    let outcome: { error: string | null }
+    try {
+      outcome = await run.adapter.startTurn(
+        {
+          runId: run.id,
+          threadId: thread.id,
+          messageId: run.messageId,
+          text,
+          project,
+          thread,
+          apiUrl: this.apiUrl,
+          signal: run.abort.signal,
+          setHostSessionId: (id) => {
+            this.store.updateThread(thread.id, { hostSessionId: id })
+          },
+          setThreadStatus: (status) => {
+            if (this.store.getThread(thread.id)) this.store.updateThread(thread.id, { status })
+          },
+        },
+        emit,
+      )
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      this.log.error(`run ${run.id} crashed: ${message}`)
+      outcome = { error: message }
+      if (!run.journal.some((c) => c.type === 'start')) emit({ type: 'start', messageId: run.messageId } as UIMessageChunk)
+      emit({ type: 'error', errorText: message } as UIMessageChunk)
+      emit({ type: 'finish' } as UIMessageChunk)
+    }
+
+    if (!run.journal.some((c) => c.type === 'finish')) emit({ type: 'finish' } as UIMessageChunk)
+    run.finished = true
+    for (const sub of run.subscribers) sub.close()
+    run.subscribers.clear()
+
+    const cancelled = run.abort.signal.aborted
+    try {
+      const message = await assembleMessage(run.messageId, run.journal)
+      // A thread deleted mid-run has nowhere to put the message.
+      if (this.store.getThread(thread.id)) {
+        this.store.appendMessage(thread.id, message)
+        this.store.updateThread(thread.id, {
+          status: outcome.error && !cancelled ? 'error' : 'idle',
+          activeRunId: null,
+        })
+      }
+      this.store.finishRun(run.id, cancelled ? 'cancelled' : outcome.error ? 'error' : 'completed', outcome.error)
+    } catch (err) {
+      this.log.error(`run ${run.id} could not be persisted: ${err instanceof Error ? err.message : String(err)}`)
+    } finally {
+      // Keep the journal briefly so a client that reconnects right at the end
+      // can still replay the tail, then let it go.
+      setTimeout(() => this.live.delete(run.id), 30_000).unref()
+    }
+  }
+}