@frontera-sdk/cli 1.52.22 → 1.52.24

package/src/local/local-state.ts

@@ -0,0 +1,165 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import type { LocalProject } from './local-project'
+
+/**
+ * The one document that says what a local runtime is doing.
+ *
+ * The supervisor owns it and rewrites it on every transition; every other
+ * command only reads it. That single-writer rule is what lets `status`,
+ * `stop` and Studio agree without talking to each other: they all look at the
+ * same file, and the supervisor's pid in it says whether anyone is home.
+ */
+
+export type ComponentName = 'postgres' | 'storage' | 'service' | 'jobs' | 'runner' | 'studio'
+
+export type ComponentStatus = 'off' | 'starting' | 'running' | 'stopped' | 'failed'
+
+export interface ComponentState {
+  name: ComponentName
+  status: ComponentStatus
+  /** How it runs: a container, a native process from source, or the supervisor itself. */
+  kind: 'container' | 'process' | 'supervisor'
+  port?: number
+  pid?: number
+  container?: string
+  /** Why it is off or failed, in words a person can act on. */
+  detail?: string
+  startedAt?: string
+}
+
+export interface LocalCredentials {
+  email: string
+  organizationId: string
+  workspaceId: string
+  workspaceSlug?: string
+  /** `sk-org-…`: the CLI's organization profile (Blueprint, datasets) uses it. */
+  orgKey: string
+  /**
+   * `owner` when `orgKey` carries every capability the owner may delegate.
+   * Runtimes seeded before that have a narrower key, replaced on next start.
+   */
+  orgKeyGrant?: 'owner'
+  /** `sk-ws-…` scoped to the seeded workspace. */
+  workspaceKey?: string
+  /** The owner's session, refreshed on every start; Studio's API proxy acts as this person. */
+  session?: string
+  /** Providers whose keys were stored on the organization at the last start. */
+  modelProviders?: string[]
+}
+
+export interface LocalState {
+  version: 1
+  projectId: string
+  root: string
+  /** `source` runs the platform from a checkout; `image` runs release images. */
+  mode: 'source' | 'image'
+  platformVersion: string
+  supervisorPid?: number
+  phase: 'starting' | 'seeding' | 'ready' | 'stopping' | 'stopped' | 'failed'
+  error?: string
+  startedAt: string
+  updatedAt: string
+  ports: Record<'postgres' | 'service' | 'jobs' | 'runner' | 'studio' | 'cache' | 'embeddings' | 'storage' | 'traces', number>
+  components: ComponentState[]
+  credentials?: LocalCredentials
+}
+
+export function statePath(project: LocalProject): string {
+  return join(project.stateDir, 'state.json')
+}
+
+export function logsDir(project: LocalProject): string {
+  return join(project.stateDir, 'logs')
+}
+
+export function logPath(project: LocalProject, component: ComponentName): string {
+  return join(logsDir(project), `${component}.log`)
+}
+
+export function ensureStateDir(project: LocalProject): void {
+  mkdirSync(logsDir(project), { recursive: true })
+  // The state dir holds a password and keys for a disposable local runtime.
+  // Not production secrets, but nobody else on the machine needs to read them.
+  try {
+    chmodSync(project.stateDir, 0o700)
+  } catch {
+    // Best effort; a filesystem without modes still works.
+  }
+  const ignore = join(project.root, '.frontera', '.gitignore')
+  if (!existsSync(ignore)) writeFileAtomic(ignore, 'local/\n', 0o644)
+}
+
+export function readState(project: LocalProject): LocalState | null {
+  const path = statePath(project)
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as LocalState
+  } catch {
+    return null
+  }
+}
+
+export function writeState(project: LocalProject, state: LocalState): void {
+  ensureStateDir(project)
+  writeFileAtomic(statePath(project), `${JSON.stringify({ ...state, updatedAt: new Date().toISOString() }, null, 2)}\n`, 0o600)
+}
+
+export function updateComponent(state: LocalState, next: ComponentState): LocalState {
+  const others = state.components.filter((c) => c.name !== next.name)
+  return { ...state, components: [...others, next].sort(byOrder) }
+}
+
+const ORDER: ComponentName[] = ['postgres', 'storage', 'service', 'jobs', 'runner', 'studio']
+
+function byOrder(a: ComponentState, b: ComponentState): number {
+  return ORDER.indexOf(a.name) - ORDER.indexOf(b.name)
+}
+
+/** Whether a pid names a live process. Signal 0 checks without delivering anything. */
+export function isAlive(pid: number | undefined): boolean {
+  if (!pid) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+export function clearState(project: LocalProject): void {
+  rmSync(statePath(project), { force: true })
+}
+
+/**
+ * The last thing `frontera local dev` applied. Its own file rather than a
+ * field in `state.json`, which only the supervisor writes; Studio reads it with
+ * the state and refreshes its pages when it changes.
+ */
+export interface LastApplied {
+  at: string
+  what: string
+  ok: boolean
+}
+
+function appliedPath(project: LocalProject): string {
+  return join(project.stateDir, 'last-applied.json')
+}
+
+export function recordApplied(project: LocalProject, entry: LastApplied): void {
+  try {
+    writeFileAtomic(appliedPath(project), `${JSON.stringify(entry)}\n`, 0o600)
+  } catch {
+    // A missed refresh hint must never fail an apply.
+  }
+}
+
+export function readApplied(project: LocalProject): LastApplied | null {
+  try {
+    return JSON.parse(readFileSync(appliedPath(project), 'utf8')) as LastApplied
+  } catch {
+    return null
+  }
+}

package/src/local/local-studio-assets.ts

@@ -0,0 +1,68 @@
+import { spawn } from 'node:child_process'
+import { existsSync, openSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import type { LocalConfig } from './local-env'
+
+/**
+ * Where the built Studio app is.
+ *
+ * In order: an explicit override, the CLI's own vendored copy (a release
+ * build places it next to the CLI), then the platform checkout the runtime
+ * runs from. `null` makes the server answer with how to build it.
+ */
+export function studioAssetsDir(config: LocalConfig | null): string | null {
+  const candidates = [
+    process.env.FRONTERA_STUDIO_DIST,
+    resolve(import.meta.dir, '..', 'vendor', 'studio'),
+    config?.platformSource ? join(config.platformSource, 'packages', 'studio', 'dist') : undefined,
+    resolve(import.meta.dir, '..', '..', '..', 'studio', 'dist'),
+  ]
+  for (const dir of candidates) {
+    if (dir && existsSync(join(dir, 'index.html'))) return dir
+  }
+  return null
+}
+
+/** The packages a Studio build bundles from a platform checkout. */
+const STUDIO_SOURCES = ['packages/studio/src', 'packages/studio/index.html', 'packages/chat/src', 'packages/blueprint/src', 'packages/platform-kit/src']
+
+function newestChange(path: string): number {
+  if (!existsSync(path)) return 0
+  const stat = statSync(path)
+  if (!stat.isDirectory()) return stat.mtimeMs
+  let newest = stat.mtimeMs
+  for (const entry of readdirSync(path, { recursive: true, withFileTypes: true })) {
+    if (!entry.isFile()) continue
+    const mtime = statSync(join(entry.parentPath, entry.name)).mtimeMs
+    if (mtime > newest) newest = mtime
+  }
+  return newest
+}
+
+/**
+ * True when the checkout's Studio build is missing or older than its sources,
+ * so a runtime started from the checkout would serve a stale Studio. Only for
+ * the checkout's own build: an override or a vendored copy is used as it is.
+ */
+export function studioBuildStale(config: LocalConfig): boolean {
+  if (config.mode !== 'source' || !config.platformSource) return false
+  if (process.env.FRONTERA_STUDIO_DIST || existsSync(resolve(import.meta.dir, '..', 'vendor', 'studio', 'index.html'))) return false
+  const built = join(config.platformSource, 'packages', 'studio', 'dist', 'index.html')
+  if (!existsSync(built)) return true
+  const builtAt = statSync(built).mtimeMs
+  return STUDIO_SOURCES.some((source) => newestChange(join(config.platformSource!, source)) > builtAt)
+}
+
+/** Build Studio in the checkout at low priority, logging to `logFile`; resolves whether it built. */
+export function buildStudio(platformSource: string, logFile: string): Promise<boolean> {
+  return new Promise((done) => {
+    const fd = openSync(logFile, 'a')
+    const child = spawn('nice', ['-n', '10', 'bun', 'run', 'build'], {
+      cwd: join(platformSource, 'packages', 'studio'),
+      stdio: ['ignore', fd, fd],
+    })
+    child.on('error', () => done(false))
+    child.on('exit', (code) => done(code === 0))
+  })
+}

package/src/local/local-studio-server.ts

@@ -0,0 +1,304 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { extname, join, normalize } from 'node:path'
+
+import type { LocalProject } from './local-project'
+import { AgentFileError, saveAgentEdit, type AgentFileEdit } from './local-agent-files'
+import { solutionStatus } from './local-applied'
+import { logPath, readApplied, readState, type ComponentName } from './local-state'
+import { appendTestCase, renderTestCase } from './local-test-cases'
+import { findCaseFiles } from './local-test-runner'
+import { createTestRuns } from './local-test-runs'
+
+/**
+ * Frontera Studio's server: the static app, the API, and the runtime's own
+ * status — one origin, served by the supervisor, as `mastra dev` serves Studio
+ * beside its API.
+ *
+ * Three rules shape it:
+ * - It binds to 127.0.0.1 only, and every request needs the session cookie
+ *   that the printed `?token=` link sets. "No auth configured means public" is
+ *   the pattern we are deliberately not copying.
+ * - The browser never sees a credential. `/api/*` is proxied to the local
+ *   service with the seeded owner's session added here, so the API explorer
+ *   and every Studio view call the real API exactly as the platform does.
+ * - The runtime's own data (`/__local/*`) is read from the supervisor's state
+ *   file and log files, never from the service, so Studio still explains what
+ *   is wrong when the service is the thing that is down.
+ */
+
+const COOKIE = 'frontera_studio'
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ico': 'image/x-icon',
+  '.map': 'application/json; charset=utf-8',
+}
+
+export interface StudioServerOptions {
+  project: LocalProject
+  port: number
+  serviceUrl: string
+  /** Where the built Studio app is (`index.html` + assets); asked per request, so a rebuild needs no restart. */
+  assetsDir: () => string | null
+  /** The session secret printed in the Studio link. */
+  sessionToken: string
+}
+
+export function newSessionToken(): string {
+  return randomBytes(24).toString('base64url')
+}
+
+function sameToken(a: string, b: string): boolean {
+  const ab = Buffer.from(a)
+  const bb = Buffer.from(b)
+  return ab.length === bb.length && timingSafeEqual(ab, bb)
+}
+
+function cookieToken(req: Request): string | null {
+  const header = req.headers.get('cookie') ?? ''
+  for (const part of header.split(';')) {
+    const [k, ...v] = part.trim().split('=')
+    if (k === COOKIE) return v.join('=')
+  }
+  return null
+}
+
+const LOG_COMPONENTS: ComponentName[] = ['postgres', 'storage', 'service', 'jobs', 'runner', 'studio']
+
+function tail(path: string, lines: number): string[] {
+  if (!existsSync(path)) return []
+  const size = statSync(path).size
+  // Read at most the last 512 KiB: a long-running log must not be loaded whole.
+  const start = Math.max(0, size - 512 * 1024)
+  const buf = readFileSync(path).subarray(start)
+  return buf.toString('utf8').split('\n').filter(Boolean).slice(-lines)
+}
+
+export function startStudioServer(opts: StudioServerOptions) {
+  const { project } = opts
+  const testRuns = createTestRuns(project, opts.serviceUrl)
+
+  const json = (data: unknown, status = 200) =>
+    new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json; charset=utf-8' } })
+
+  const localRoute = (url: URL): Response => {
+    if (url.pathname === '/__local/state') {
+      const state = readState(project)
+      if (!state) return json({ error: 'no local runtime state' }, 404)
+      const { credentials, ...rest } = state
+      return json({
+        ...rest,
+        serviceUrl: opts.serviceUrl,
+        lastApplied: readApplied(project),
+        credentials: credentials
+          ? {
+              email: credentials.email,
+              organizationId: credentials.organizationId,
+              workspaceId: credentials.workspaceId,
+              workspaceSlug: credentials.workspaceSlug,
+              modelProviders: credentials.modelProviders ?? [],
+            }
+          : null,
+      })
+    }
+    // Each file `local dev` applies, and whether the runtime has its current content.
+    if (url.pathname === '/__local/solution') {
+      return json({ items: solutionStatus(project, readState(project)?.credentials?.organizationId ?? null) })
+    }
+    // The solution's saved cases (`agents/<slug>/evals/*.yaml`), read fresh each time.
+    if (url.pathname === '/__local/test-cases') {
+      try {
+        return json({ files: findCaseFiles(project.root) })
+      } catch (err) {
+        return json({ error: `a case file could not be read: ${(err as Error).message}` }, 422)
+      }
+    }
+    if (url.pathname === '/__local/test-runs') return json({ runs: testRuns.list() })
+    const runMatch = /^\/__local\/test-runs\/([0-9a-f-]+)$/.exec(url.pathname)
+    if (runMatch) {
+      const run = testRuns.get(runMatch[1]!)
+      return run ? json(run) : json({ error: 'no such test run' }, 404)
+    }
+    const logMatch = /^\/__local\/logs\/([a-z]+)$/.exec(url.pathname)
+    if (logMatch) {
+      const component = logMatch[1] as ComponentName
+      if (!LOG_COMPONENTS.includes(component)) return json({ error: 'unknown component' }, 404)
+      const lines = Math.min(Number(url.searchParams.get('lines') ?? 300) || 300, 2000)
+      return json({ component, lines: tail(logPath(project, component), lines) })
+    }
+    return json({ error: 'not found' }, 404)
+  }
+
+  /** Save a conversation into the solution as a regression case (`agents/<slug>/evals/regression.yaml`). */
+  const saveTestCase = async (req: Request): Promise<Response> => {
+    const state = readState(project)
+    const creds = state?.credentials
+    if (!creds?.session) return json({ error: 'the runtime is not seeded yet' }, 409)
+    const body = (await req.json().catch(() => null)) as { agentId?: string; conversationId?: string } | null
+    if (!body?.agentId || !body.conversationId) return json({ error: 'agentId and conversationId are required' }, 400)
+    const headers = { authorization: `Bearer ${creds.session}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId }
+    const get = async (path: string) => {
+      const res = await fetch(new URL(path, opts.serviceUrl), { headers })
+      if (!res.ok) throw new Error(`${path} answered ${res.status}`)
+      const parsed = (await res.json()) as { data?: unknown }
+      return parsed.data
+    }
+    try {
+      const agent = (await get(`/v1/config/agents/${encodeURIComponent(body.agentId)}`)) as { agentId?: string }
+      const messages = (await get(`/v1/sessions/${encodeURIComponent(body.conversationId)}/messages`)) as unknown
+      const list = Array.isArray(messages) ? messages : ((messages as { messages?: unknown[] })?.messages ?? [])
+      const yaml = renderTestCase({ conversationId: body.conversationId, messages: list as never[], savedAt: new Date().toISOString() })
+      const path = appendTestCase(project.root, agent.agentId ?? body.agentId, yaml)
+      return json({ path })
+    } catch (err) {
+      return json({ error: (err as Error).message }, 502)
+    }
+  }
+
+  /**
+   * The service's API reference on Studio's origin. The OpenAPI document's
+   * server is rewritten to `/api`, so the reference's "Send request" runs
+   * through the proxy as the local owner instead of asking for a key.
+   */
+  const apiReference = async (url: URL): Promise<Response> => {
+    const target = new URL(url.pathname + url.search, opts.serviceUrl)
+    try {
+      const res = await fetch(target)
+      if (url.pathname === '/docs/json' && res.ok) {
+        const spec = (await res.json()) as Record<string, unknown>
+        spec.servers = [{ url: `${url.origin}/api`, description: 'Local runtime, signed in as the local owner' }]
+        return json(spec)
+      }
+      const out = new Headers(res.headers)
+      out.delete('content-encoding')
+      out.delete('content-length')
+      return new Response(res.body, { status: res.status, headers: out })
+    } catch (err) {
+      return json({ error: 'the local service did not answer', detail: (err as Error).message }, 502)
+    }
+  }
+
+  const proxy = async (req: Request, url: URL): Promise<Response> => {
+    const state = readState(project)
+    // The shared packages give Better Auth's client `<origin>/api` as its base,
+    // which it reads as the auth base path; on a deployment those endpoints
+    // live under `/api/auth/`. Every other service route is `/v1/…`, `/api/…`,
+    // `/health` or `/docs`, so anything else is an auth endpoint.
+    let path = url.pathname.replace(/^\/api/, '') || '/'
+    if (!/^\/(v1|api|health|docs)(\/|$)/.test(path)) path = `/api/auth${path}`
+    const target = new URL(path + url.search, opts.serviceUrl)
+    const headers = new Headers(req.headers)
+    headers.delete('cookie')
+    headers.delete('host')
+    headers.delete('origin')
+    headers.delete('referer')
+    // Studio acts as the seeded owner: a session reaches every route a person
+    // can use, including the session-only ones an API key is refused on.
+    const bearer = state?.credentials?.session ?? state?.credentials?.workspaceKey
+    if (bearer && !headers.has('authorization')) headers.set('authorization', `Bearer ${bearer}`)
+    if (state?.credentials?.organizationId && !headers.has('x-org-id')) headers.set('x-org-id', state.credentials.organizationId)
+    if (state?.credentials?.workspaceId && !headers.has('x-workspace-id')) {
+      headers.set('x-workspace-id', state.credentials.workspaceId)
+    }
+    try {
+      const res = await fetch(target, {
+        method: req.method,
+        headers,
+        body: req.method === 'GET' || req.method === 'HEAD' ? undefined : req.body,
+        redirect: 'manual',
+        duplex: 'half',
+      })
+      const out = new Headers(res.headers)
+      out.delete('content-encoding')
+      out.delete('content-length')
+      return new Response(res.body, { status: res.status, statusText: res.statusText, headers: out })
+    } catch (err) {
+      return json({ error: 'the local service did not answer', detail: (err as Error).message }, 502)
+    }
+  }
+
+  const asset = (url: URL): Response => {
+    const assetsDir = opts.assetsDir()
+    if (!assetsDir) {
+      return new Response(
+        '<!doctype html><title>Frontera Studio</title><body style="font-family:system-ui;padding:40px">' +
+          '<h1>Studio is not built</h1><p>Run <code>bun run --cwd packages/studio build</code> in the platform repository, then reload.</p>',
+        { status: 503, headers: { 'content-type': 'text/html; charset=utf-8' } },
+      )
+    }
+    const rel = normalize(decodeURIComponent(url.pathname)).replace(/^(\.\.[/\\])+/, '')
+    let file = join(assetsDir, rel)
+    if (!file.startsWith(assetsDir) || !existsSync(file) || statSync(file).isDirectory()) {
+      file = join(assetsDir, 'index.html')
+    }
+    const type = MIME[extname(file)] ?? 'application/octet-stream'
+    const cache = file.endsWith('index.html') ? 'no-cache' : 'public, max-age=31536000, immutable'
+    return new Response(Bun.file(file), { headers: { 'content-type': type, 'cache-control': cache } })
+  }
+
+  return Bun.serve({
+    hostname: '127.0.0.1',
+    port: opts.port,
+    idleTimeout: 120,
+    async fetch(req) {
+      const url = new URL(req.url)
+
+      const offered = url.searchParams.get('token')
+      if (offered) {
+        if (!sameToken(offered, opts.sessionToken)) return new Response('Invalid Studio link', { status: 401 })
+        url.searchParams.delete('token')
+        return new Response(null, {
+          status: 302,
+          headers: {
+            location: url.pathname + (url.search || ''),
+            'set-cookie': `${COOKIE}=${opts.sessionToken}; HttpOnly; SameSite=Strict; Path=/`,
+          },
+        })
+      }
+
+      if (url.pathname === '/__local/health') return json({ ok: true })
+
+      const cookie = cookieToken(req)
+      if (!cookie || !sameToken(cookie, opts.sessionToken)) {
+        return new Response(
+          '<!doctype html><title>Frontera Studio</title><body style="font-family:system-ui;padding:40px">' +
+            '<h1>Open Studio from the CLI</h1><p>Run <code>frontera local ui</code>. It prints a link that signs this browser in.</p>',
+          { status: 401, headers: { 'content-type': 'text/html; charset=utf-8' } },
+        )
+      }
+
+      if (url.pathname === '/docs' || url.pathname.startsWith('/docs/')) return apiReference(url)
+      if (url.pathname === '/__local/test-cases' && req.method === 'POST') return saveTestCase(req)
+      const editMatch = /^\/__local\/agents\/([^/]+)\/file$/.exec(url.pathname)
+      if (editMatch && req.method === 'PUT') {
+        const organizationId = readState(project)?.credentials?.organizationId
+        if (!organizationId) return json({ error: 'the runtime is not seeded yet' }, 409)
+        const edit = (await req.json().catch(() => null)) as AgentFileEdit | null
+        if (!edit || typeof edit !== 'object') return json({ error: 'the edit must be a JSON object' }, 400)
+        try {
+          return json(await saveAgentEdit(project, organizationId, decodeURIComponent(editMatch[1]!), edit))
+        } catch (err) {
+          if (err instanceof AgentFileError) return json({ error: err.message }, err.status)
+          return json({ error: (err as Error).message }, 500)
+        }
+      }
+      if (url.pathname === '/__local/test-runs' && req.method === 'POST') {
+        const body = (await req.json().catch(() => ({}))) as { agent?: string; live?: boolean }
+        const started = testRuns.start({ agent: typeof body.agent === 'string' ? body.agent : undefined, live: body.live === true })
+        return 'run' in started ? json(started.run, 202) : json({ error: started.error }, started.status)
+      }
+      if (url.pathname.startsWith('/__local/')) return localRoute(url)
+      // `/api/…` is the service; `/api` alone is Studio's API page.
+      if (url.pathname.startsWith('/api/')) return proxy(req, url)
+      return asset(url)
+    },
+  })
+}