@frontera-sdk/cli 1.52.23 → 1.52.25

package/src/local/local-keys.ts

@@ -0,0 +1,115 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { configDir } from '../paths'
+
+/**
+ * Each FDE's own model-provider keys for the local runtime.
+ *
+ * They live in the OS keychain on macOS (`security`), so a key never sits in a
+ * solution repo, a shell profile or the runtime's state directory. Elsewhere
+ * they fall back to a 0600 file under the CLI's config directory. The local
+ * service receives them as the same environment variables a deployment's
+ * service reads, so a local turn calls the provider exactly the way a deployed
+ * one does.
+ */
+
+const SERVICE = 'frontera-local-model-key'
+
+export interface ProviderSpec {
+  id: string
+  label: string
+  /** The variable the service reads for this provider. */
+  envVar: string
+}
+
+/** Providers the local runtime can pass a key to; mirrors the service's built-in providers. */
+export const LOCAL_PROVIDERS: readonly ProviderSpec[] = [
+  { id: 'anthropic', label: 'Anthropic', envVar: 'ANTHROPIC_API_KEY' },
+  { id: 'openai', label: 'OpenAI', envVar: 'OPENAI_API_KEY' },
+  { id: 'openrouter', label: 'OpenRouter', envVar: 'OPENROUTER_API_KEY' },
+  { id: 'google', label: 'Google Gemini', envVar: 'GOOGLE_GENERATIVE_AI_API_KEY' },
+  { id: 'cohere', label: 'Cohere (reranking)', envVar: 'COHERE_API_KEY' },
+]
+
+export function findProvider(id: string): ProviderSpec | undefined {
+  return LOCAL_PROVIDERS.find((p) => p.id === id)
+}
+
+function useKeychain(): boolean {
+  return process.platform === 'darwin' && !process.env.FRONTERA_LOCAL_KEYS_FILE
+}
+
+function filePath(): string {
+  return process.env.FRONTERA_LOCAL_KEYS_FILE ?? join(configDir(), 'local-model-keys.json')
+}
+
+function readFile(): Record<string, string> {
+  const path = filePath()
+  if (!existsSync(path)) return {}
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Record<string, string>
+  } catch {
+    return {}
+  }
+}
+
+export function setKey(provider: string, key: string): void {
+  if (useKeychain()) {
+    // -U updates an existing item instead of failing on a duplicate.
+    const res = spawnSync('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', provider, '-w', key], {
+      stdio: 'ignore',
+    })
+    if (res.status !== 0) throw new Error('the macOS keychain refused the key')
+    return
+  }
+  writeFileAtomic(filePath(), `${JSON.stringify({ ...readFile(), [provider]: key }, null, 2)}\n`, 0o600)
+}
+
+export function getKey(provider: string): string | null {
+  if (useKeychain()) {
+    const res = spawnSync('security', ['find-generic-password', '-s', SERVICE, '-a', provider, '-w'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return res.status === 0 ? res.stdout.trim() || null : null
+  }
+  return readFile()[provider] ?? null
+}
+
+export function removeKey(provider: string): boolean {
+  if (useKeychain()) {
+    return spawnSync('security', ['delete-generic-password', '-s', SERVICE, '-a', provider], { stdio: 'ignore' }).status === 0
+  }
+  const keys = readFile()
+  if (!(provider in keys)) return false
+  delete keys[provider]
+  writeFileAtomic(filePath(), `${JSON.stringify(keys, null, 2)}\n`, 0o600)
+  return true
+}
+
+/** Which providers have a key, without reading the keys themselves into output. */
+export function configuredProviders(): string[] {
+  return LOCAL_PROVIDERS.filter((p) => getKey(p.id) !== null).map((p) => p.id)
+}
+
+/** The environment variables for every configured provider. */
+export function providerEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const p of LOCAL_PROVIDERS) {
+    const key = getKey(p.id)
+    if (key) env[p.envVar] = key
+  }
+  return env
+}
+
+/**
+ * With no OpenAI or OpenRouter key, the runtime embeds with the local model:
+ * the service's OpenAI client is pointed at it, and the organization gets a
+ * placeholder OpenAI credential. A real key of either turns this off.
+ */
+export function keylessEmbeddings(): boolean {
+  return !getKey('openai') && !getKey('openrouter')
+}

package/src/local/local-operating.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs'
+
+import type { LocalCredentials } from './local-state'
+
+/**
+ * An Agent's behavior settings (`agents/<slug>/operating.json`: harness,
+ * procedures, variables, focus, reply checks) staged onto its draft.
+ *
+ * There is no CLI command for these: the route takes a person's session, not
+ * an API key. The local runtime has the owner's session, as Studio does, so
+ * `local dev` stages them over the API directly. Publishing applies them,
+ * like the rest of the draft.
+ */
+
+interface Result {
+  ok: boolean
+  output: string
+}
+
+function describeError(status: number, body: unknown): string {
+  const b = (body ?? {}) as { message?: string; code?: string; details?: unknown; issues?: unknown }
+  const lines = [`error [${b.code ?? status}]: ${b.message ?? 'the behavior settings were refused'}`]
+  const issues = (b.details as { issues?: unknown } | undefined)?.issues ?? b.issues ?? b.details
+  if (Array.isArray(issues)) {
+    for (const issue of issues.slice(0, 6)) {
+      const i = issue as { path?: unknown; message?: string }
+      const path = Array.isArray(i.path) ? i.path.join('.') : typeof i.path === 'string' ? i.path : ''
+      lines.push(`  ${path ? `${path}: ` : ''}${i.message ?? JSON.stringify(issue)}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+export async function applyOperatingConfig(args: {
+  serviceUrl: string
+  creds: LocalCredentials
+  slug: string
+  file: string
+}): Promise<Result> {
+  let operatingConfig: unknown
+  try {
+    operatingConfig = JSON.parse(readFileSync(args.file, 'utf8'))
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${args.file} is not valid JSON: ${(err as Error).message}` }
+  }
+  if (!args.creds.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime has no owner session; restart it' }
+  const headers = {
+    authorization: `Bearer ${args.creds.session}`,
+    'x-org-id': args.creds.organizationId,
+    'x-workspace-id': args.creds.workspaceId,
+    'content-type': 'application/json',
+  }
+  const call = async (path: string, init: { method?: string; body?: unknown } = {}) => {
+    const res = await fetch(new URL(path, args.serviceUrl), {
+      method: init.method ?? 'GET',
+      headers,
+      body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    })
+    const text = await res.text()
+    let body: unknown = text
+    try {
+      body = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body }
+  }
+
+  try {
+    const agent = await call(`/v1/config/agents/${encodeURIComponent(args.slug)}`)
+    const id = ((agent.body as { data?: { id?: string } })?.data ?? (agent.body as { id?: string }))?.id
+    if (agent.status === 404) {
+      return { ok: false, output: `error [NOT_FOUND]: no Agent ${args.slug}; add agents/${args.slug}/agent.json first` }
+    }
+    if (agent.status !== 200 || !id) return { ok: false, output: describeError(agent.status, agent.body) }
+    const put = await call(`/v1/config/agents/${id}/operating`, { method: 'PUT', body: { operatingConfig } })
+    if (put.status >= 400) return { ok: false, output: describeError(put.status, put.body) }
+    return { ok: true, output: '' }
+  } catch (err) {
+    return { ok: false, output: `error [UNAVAILABLE]: the local service did not answer: ${(err as Error).message}` }
+  }
+}

package/src/local/local-ports.ts

@@ -0,0 +1,111 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { dataDir } from '../paths'
+
+/**
+ * Sticky ports, one block per local runtime.
+ *
+ * Supabase's fixed defaults allow one project per machine; its newer stack
+ * keeps a per-user port registry instead, so a project's URLs stay the same
+ * across restarts while two projects can run side by side. Same here: each
+ * runtime claims a block of ten consecutive ports starting at 54100 and keeps
+ * it, recorded in `~/.local/share/frontera/local-ports.json`.
+ */
+
+export type PortName = 'postgres' | 'service' | 'jobs' | 'runner' | 'studio' | 'cache' | 'embeddings' | 'storage' | 'traces'
+
+export type PortBlock = Record<PortName, number>
+
+const BASE = 54100
+const BLOCK = 10
+const MAX_BLOCKS = 40
+const OFFSETS: Record<PortName, number> = { studio: 0, service: 1, jobs: 2, runner: 3, postgres: 4, cache: 5, embeddings: 6, storage: 7, traces: 8 }
+
+interface Registry {
+  version: 1
+  blocks: Record<string, { start: number; root: string }>
+}
+
+function registryPath(): string {
+  return join(dataDir(), 'local-ports.json')
+}
+
+function readRegistry(): Registry {
+  const path = registryPath()
+  if (!existsSync(path)) return { version: 1, blocks: {} }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Registry
+  } catch {
+    return { version: 1, blocks: {} }
+  }
+}
+
+function blockFrom(start: number): PortBlock {
+  return {
+    studio: start + OFFSETS.studio,
+    service: start + OFFSETS.service,
+    jobs: start + OFFSETS.jobs,
+    runner: start + OFFSETS.runner,
+    postgres: start + OFFSETS.postgres,
+    cache: start + OFFSETS.cache,
+    embeddings: start + OFFSETS.embeddings,
+    storage: start + OFFSETS.storage,
+    traces: start + OFFSETS.traces,
+  }
+}
+
+/** The block this project already owns, or a fresh one nobody else has claimed. */
+export function claimPorts(projectId: string, root: string): PortBlock {
+  const registry = readRegistry()
+  const existing = registry.blocks[projectId]
+  if (existing) return blockFrom(existing.start)
+  const taken = new Set(Object.values(registry.blocks).map((b) => b.start))
+  for (let i = 0; i < MAX_BLOCKS; i++) {
+    const start = BASE + i * BLOCK
+    if (taken.has(start)) continue
+    registry.blocks[projectId] = { start, root }
+    writeFileAtomic(registryPath(), `${JSON.stringify(registry, null, 2)}\n`, 0o644)
+    return blockFrom(start)
+  }
+  throw new Error('no free local port block left; remove stale entries from ~/.local/share/frontera/local-ports.json')
+}
+
+export function releasePorts(projectId: string): void {
+  const registry = readRegistry()
+  if (!registry.blocks[projectId]) return
+  delete registry.blocks[projectId]
+  writeFileAtomic(registryPath(), `${JSON.stringify(registry, null, 2)}\n`, 0o644)
+}
+
+/** Whether nothing is listening on 127.0.0.1:<port>. */
+export function isPortFree(port: number): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    const server = createServer()
+    server.once('error', () => resolvePromise(false))
+    server.once('listening', () => server.close(() => resolvePromise(true)))
+    server.listen(port, '127.0.0.1')
+  })
+}
+
+/**
+ * Who holds a port, as `command (pid N)`, so a conflict names its cause.
+ * Best effort: `lsof` is on every macOS and most Linux machines.
+ */
+export function portHolder(port: number): string | null {
+  try {
+    const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpc'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const pid = /^p(\d+)/m.exec(out)?.[1]
+    const cmd = /^c(.+)$/m.exec(out)?.[1]
+    if (!pid) return null
+    return `${cmd ?? 'unknown'} (pid ${pid})`
+  } catch {
+    return null
+  }
+}

package/src/local/local-process.ts

@@ -0,0 +1,106 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import { openSync } from 'node:fs'
+
+/**
+ * Native child processes owned by the supervisor.
+ *
+ * Each one writes stdout and stderr to its own log file, starts in its own
+ * process group so a stop reaches anything it spawned, and runs at a lower
+ * scheduling priority: a local runtime shares the laptop with an editor, a
+ * browser and whatever else the FDE is doing, and should never be the reason
+ * those stutter.
+ */
+
+export interface ProcessSpec {
+  name: string
+  command: string
+  args: string[]
+  cwd: string
+  env: Record<string, string>
+  logFile: string
+  /** `nice` increment; 10 keeps the runtime behind interactive work. */
+  niceness?: number
+}
+
+export function startProcess(spec: ProcessSpec): ChildProcess {
+  const fd = openSync(spec.logFile, 'a')
+  const niceness = spec.niceness ?? 10
+  const useNice = process.platform !== 'win32' && niceness > 0
+  const child = spawn(
+    useNice ? 'nice' : spec.command,
+    useNice ? ['-n', String(niceness), spec.command, ...spec.args] : spec.args,
+    {
+      cwd: spec.cwd,
+      env: { ...minimalEnv(), ...spec.env },
+      stdio: ['ignore', fd, fd],
+      detached: true,
+    },
+  )
+  return child
+}
+
+/** Stop a process group: SIGTERM, then SIGKILL after a grace period. */
+export async function stopProcess(pid: number | undefined, graceMs = 8000): Promise<void> {
+  if (!pid) return
+  const signal = (sig: NodeJS.Signals) => {
+    try {
+      process.kill(-pid, sig)
+    } catch {
+      try {
+        process.kill(pid, sig)
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+  signal('SIGTERM')
+  const deadline = Date.now() + graceMs
+  while (Date.now() < deadline) {
+    if (!alive(pid)) return
+    await Bun.sleep(200)
+  }
+  signal('SIGKILL')
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The environment a runtime process inherits.
+ *
+ * Deliberately not the whole parent environment: an FDE's shell carries
+ * DATABASE_URL, NODE_ENV and provider keys for other projects, and a local
+ * runtime that silently picked those up would test against the wrong database.
+ * Only what a process needs to find its tools crosses over.
+ */
+function minimalEnv(): Record<string, string> {
+  const keep = ['PATH', 'HOME', 'USER', 'LANG', 'TMPDIR', 'SHELL', 'TERM', 'BUN_INSTALL']
+  const env: Record<string, string> = {}
+  for (const key of keep) {
+    const value = process.env[key]
+    if (value) env[key] = value
+  }
+  return env
+}
+
+/** Poll an HTTP URL until it answers 2xx or the deadline passes. */
+export async function waitForHttp(url: string, timeoutMs: number, isAliveCheck?: () => boolean): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (isAliveCheck && !isAliveCheck()) return false
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(2000) })
+      if (res.ok) return true
+    } catch {
+      // Not up yet.
+    }
+    await Bun.sleep(500)
+  }
+  return false
+}

package/src/local/local-project.ts

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+/**
+ * Which local runtime a directory belongs to.
+ *
+ * A local runtime is owned by a project directory, the way a Supabase stack is
+ * owned by the directory holding `supabase/config.toml`. The marker is a
+ * `.frontera/` folder (written by `frontera init`, `auth use` and `start`) or a
+ * `frontera.yaml` (`frontera.solution.yaml` in projects made before it was
+ * renamed); the nearest one walking up wins, so running a
+ * command from a sub-folder reaches the same runtime. With neither present the
+ * current directory becomes the root — `frontera start` in an empty folder is a
+ * valid way to begin.
+ */
+export interface LocalProject {
+  /** Absolute path of the project directory. */
+  root: string
+  /** Stable, filesystem- and docker-safe id: `<slug>-<hash8>`. */
+  id: string
+  /** `<root>/.frontera/local`: state, logs, secrets for this runtime. */
+  stateDir: string
+}
+
+/** The project file, under its current name first and its earlier one after. */
+export const PROJECT_FILES = ['frontera.yaml', 'frontera.solution.yaml'] as const
+const MARKERS = [...PROJECT_FILES, '.frontera'] as const
+
+export function findSolutionRoot(cwd: string): string {
+  let dir = resolve(cwd)
+  for (;;) {
+    if (MARKERS.some((m) => existsSync(join(dir, m)))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return resolve(cwd)
+    dir = parent
+  }
+}
+
+export function slugify(name: string): string {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  // Part of a runtime's id and container names: keep it stable across releases.
+  return (slug || 'solution').slice(0, 24)
+}
+
+export function localProject(cwd: string): LocalProject {
+  const root = findSolutionRoot(cwd)
+  const hash = createHash('sha256').update(root).digest('hex').slice(0, 8)
+  return {
+    root,
+    id: `${slugify(basename(root))}-${hash}`,
+    stateDir: join(root, '.frontera', 'local'),
+  }
+}