@frontera-sdk/cli 1.52.23 → 1.52.24

package/src/commands/local/index-commands.ts

@@ -0,0 +1,477 @@
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, rmSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { CliError, UsageError } from '../../errors'
+import { writeFileAtomic } from '../../fs-atomic'
+import { solutionStatus } from '../../local/local-applied'
+import { dockerAvailable } from '../../local/local-docker'
+import { readConfig, writeConfig, type LocalConfig } from '../../local/local-env'
+import { configuredProviders } from '../../local/local-keys'
+import { claimPorts, isPortFree, portHolder, releasePorts } from '../../local/local-ports'
+import { localProject, type LocalProject } from '../../local/local-project'
+import {
+  destroyRuntimeData,
+  detectPlatformSource,
+  isPlatformSource,
+  localProfileName,
+  registerLocalProfile,
+  spawnSupervisor,
+  stopRuntime,
+  waitForPhase,
+} from '../../local/local-control'
+import { clearState, ensureStateDir, isAlive, logPath, readState, type ComponentName, type LocalState } from '../../local/local-state'
+import { newSessionToken } from '../../local/local-studio-server'
+import { DEFAULT_REGISTRY, runSupervisor } from '../../local/local-supervisor'
+import { findCaseFiles, runCases } from '../../local/local-test-runner'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
+import { localCheck } from './check'
+import { localDev } from './dev'
+import { localDocsMcp } from './docs-mcp'
+import { localInit } from './init'
+import { localKeyList, localKeyRemove, localKeySet } from './key'
+import { localModelAdd, localModelDefault, localModelRemove, localModelsAvailable, localProviderAdd, localProviderRemove, localProviders } from './providers'
+import { localSchema } from './schema'
+
+/**
+ * `frontera local …`: Frontera's runtimes on this machine, for internal FDEs.
+ *
+ * Modelled on `supabase start`: one command brings up only the runtimes a
+ * solution needs (no product UI, no kernel), seeds an owner, organization,
+ * workspace and keys, and prints where everything is. `frontera local ui` opens
+ * Frontera Studio on top of it. Nothing here talks to a Frontera deployment.
+ */
+
+const COMPONENTS: ComponentName[] = ['postgres', 'storage', 'service', 'jobs', 'runner', 'studio']
+const OPTIONAL: ComponentName[] = ['jobs', 'runner', 'storage']
+
+const sessionFile = (project: LocalProject) => join(project.stateDir, 'studio-session')
+
+function readSession(project: LocalProject): string | null {
+  const path = sessionFile(project)
+  return existsSync(path) ? readFileSync(path, 'utf8').trim() : null
+}
+
+function cliVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(import.meta.dir, '..', '..', '..', 'package.json'), 'utf8')) as { version: string }
+    return pkg.version
+  } catch {
+    return 'latest'
+  }
+}
+
+function studioUrl(state: LocalState, project: LocalProject): string {
+  const token = readSession(project)
+  return `http://127.0.0.1:${state.ports.studio}/${token ? `?token=${token}` : ''}`
+}
+
+const DOT: Record<string, string> = { running: '●', starting: '◐', off: '○', stopped: '○', failed: '✕' }
+
+function renderStatus(state: LocalState, project: LocalProject, profile?: { profile: string; bound: boolean }): string {
+  const lines: string[] = []
+  const phase = state.supervisorPid && !isAlive(state.supervisorPid) && state.phase !== 'stopped' ? 'stopped (supervisor exited)' : state.phase
+  lines.push(`Frontera local runtime · ${project.root.split('/').pop()} · ${phase}`)
+  if (state.error) lines.push(`  ${state.error}`)
+  lines.push('')
+  if (state.phase === 'ready') {
+    lines.push(`  Studio       ${studioUrl(state, project)}`)
+    lines.push(`  API          http://127.0.0.1:${state.ports.service}`)
+    lines.push(`  API docs     http://127.0.0.1:${state.ports.service}/docs`)
+    if (state.components.find((c) => c.name === 'jobs')?.status === 'running') {
+      lines.push(`  Job engine   http://127.0.0.1:${state.ports.jobs}`)
+    }
+    lines.push(`  Postgres     postgresql://frontera:•••@127.0.0.1:${state.ports.postgres}/frontera`)
+    lines.push('')
+  }
+  for (const c of state.components) {
+    const where = c.kind === 'container' ? 'container' : c.kind === 'process' ? 'process' : 'supervisor'
+    lines.push(`  ${DOT[c.status] ?? '·'} ${c.name.padEnd(9)} ${c.status.padEnd(9)} ${c.status === 'off' ? (c.detail ?? '') : where}${c.status === 'failed' && c.detail ? ` — ${c.detail}` : ''}`)
+  }
+  if (state.credentials) {
+    lines.push('')
+    lines.push(`  Signed in as ${state.credentials.email}`)
+    const name = profile?.profile ?? localProfileName(project)
+    lines.push(
+      profile?.bound === false
+        ? `  CLI profile  ${name} — this directory is bound to another profile; pass \`--profile ${name}\``
+        : `  CLI profile  ${name} (this directory uses it)`,
+    )
+    lines.push(`  Blueprint    pass \`--profile ${name}-org\` (Blueprint commands need an organization key)`)
+    const files = solutionStatus(project, state.credentials.organizationId)
+    if (files.length) {
+      const behind = files.filter((f) => f.state !== 'applied')
+      lines.push(
+        behind.length
+          ? `  Project      ${behind.length} of ${files.length} files not on the runtime (${behind.map((f) => f.name).join(', ')}) — run \`frontera local dev\``
+          : `  Project      all ${files.length} files applied`,
+      )
+    }
+  }
+  const providers = configuredProviders()
+  lines.push(`  Model keys   ${providers.length ? providers.join(', ') : 'none — run `frontera local key-set <provider>`'}`)
+  if (state.credentials?.modelProviders?.includes('local-embeddings')) {
+    lines.push('  Embeddings   local: words hashed into vectors, no key (an OpenAI or OpenRouter key replaces it)')
+  }
+  return lines.join('\n')
+}
+
+/** A registry host and namespace, such as `registry.example.com/frontera`; undefined keeps the default. */
+export function normalizeRegistry(raw: string | undefined): string | undefined {
+  const value = raw?.trim().replace(/^[a-z]+:\/\//i, '').replace(/\/+$/, '')
+  if (!value) return undefined
+  if (!/^[a-z0-9.-]+(:\d+)?(\/[a-z0-9._-]+)*$/i.test(value)) {
+    throw new UsageError(`\`${raw}\` is not a registry address`, 'pass a registry host and namespace, such as `registry.example.com/frontera` or `localhost:5000/frontera`')
+  }
+  return value
+}
+
+function parseList(raw: string | undefined): ComponentName[] {
+  if (!raw) return []
+  const names = raw.split(',').map((s) => s.trim()).filter(Boolean) as ComponentName[]
+  for (const n of names) {
+    if (!OPTIONAL.includes(n)) {
+      throw new UsageError(`\`${n}\` cannot be excluded`, `only ${OPTIONAL.join(', ')} are optional; postgres, service and studio always run`)
+    }
+  }
+  return names
+}
+
+async function start(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
+  const project = localProject(ctx.cwd)
+  const existing = readState(project)
+  if (existing?.supervisorPid && isAlive(existing.supervisorPid) && existing.phase !== 'stopped') {
+    const profile = existing.credentials ? await registerLocalProfile(project, existing) : undefined
+    return { data: existing, text: `Already running.\n\n${renderStatus(existing, project, profile)}` }
+  }
+
+  const docker = dockerAvailable()
+  if (!docker.ok) {
+    throw new CliError(`no container runtime answered: ${docker.reason}`, {
+      code: 'LOCAL_DOCKER',
+      hint: 'start Docker Desktop or OrbStack (`open -a OrbStack`), then run `frontera local start` again',
+    })
+  }
+
+  const sourceFlag = flagString(ctx, 'source')
+  const useImage = flagBool(ctx, 'image')
+  const source = sourceFlag ? resolve(ctx.cwd, sourceFlag) : useImage ? null : (process.env.FRONTERA_PLATFORM_SOURCE ?? detectPlatformSource())
+  if (sourceFlag && !isPlatformSource(source!)) {
+    throw new UsageError(`${source} is not a Frontera platform checkout`, 'point --source at the repository root that holds packages/service')
+  }
+  const exclude = parseList(flagString(ctx, 'exclude'))
+  const previous = readConfig(project)
+  const config: LocalConfig = {
+    mode: source ? 'source' : 'image',
+    platformSource: source ?? undefined,
+    platformVersion: flagString(ctx, 'version') ?? previous?.platformVersion ?? cliVersion(),
+    registry: normalizeRegistry(flagString(ctx, 'registry') ?? process.env.FRONTERA_LOCAL_REGISTRY ?? previous?.registry),
+    exclude,
+  }
+  ensureStateDir(project)
+  writeConfig(project, config)
+
+  const ports = claimPorts(project.id, project.root)
+  for (const name of [...COMPONENTS, 'cache', 'embeddings', 'traces'] as const) {
+    if (exclude.includes(name as ComponentName)) continue
+    if (!(await isPortFree(ports[name]))) {
+      const holder = portHolder(ports[name])
+      throw new CliError(`port ${ports[name]} (${name}) is already in use${holder ? ` by ${holder}` : ''}`, {
+        code: 'LOCAL_PORT',
+        hint: holder?.includes('docker') || holder?.includes('OrbStack') ? 'a container from an earlier run may still hold it; run `frontera local stop`' : 'stop that process, then start again',
+      })
+    }
+  }
+
+  const session = newSessionToken()
+  writeFileAtomic(sessionFile(project), `${session}\n`, 0o600)
+  const supervisorPid = spawnSupervisor(project, session)
+
+  const seen = new Set<string>()
+  const state = await ctx.output.task(
+    config.mode === 'source' ? 'Starting the local runtime from this platform checkout' : `Starting the local runtime (release ${config.platformVersion} from ${config.registry ?? DEFAULT_REGISTRY})`,
+    () =>
+      waitForPhase(project, supervisorPid, (s) => {
+        for (const c of s.components) {
+          const key = `${c.name}:${c.status}`
+          if (c.status === 'running' && !seen.has(key)) {
+            seen.add(key)
+            ctx.output.note(`  ● ${c.name} running`)
+          }
+        }
+        if (s.phase === 'seeding' && !seen.has('seed')) {
+          seen.add('seed')
+          ctx.output.note('  Seeding an owner, organization, workspace and keys')
+        }
+      }),
+  )
+  if (state.phase !== 'ready') {
+    throw new CliError(`the local runtime did not start: ${state.error ?? state.phase}`, {
+      code: 'LOCAL_START',
+      hint: 'see `frontera local logs <component>`; fix the cause and run `frontera local start` again',
+    })
+  }
+  const profile = await registerLocalProfile(project, state)
+  return { data: { ...state, credentials: state.credentials ? { ...state.credentials, orgKey: undefined, workspaceKey: undefined } : undefined, profile }, text: renderStatus(state, project, profile) }
+}
+
+const startMeta = {
+  args: [],
+  flags: { source: 'string', image: 'boolean', version: 'string', registry: 'string', exclude: 'string' },
+  summary: 'Start Frontera\'s runtimes on this machine and seed an owner, workspace and keys',
+  examples: ['frontera local start', 'frontera local start --exclude runner', 'frontera local start --image --version 1.52.19', 'frontera local start --image --registry registry.example.com/frontera'],
+  offline: true,
+  internal: true,
+} as const
+
+export const localStart: Command = { meta: { noun: 'local', verb: 'start', ...startMeta }, run: start }
+
+async function stop(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const state = readState(project)
+  if (!state) return { data: { stopped: false }, text: 'No local runtime here.' }
+  await ctx.output.task('Stopping the local runtime', () => stopRuntime(project))
+  if (flagBool(ctx, 'no-backup')) {
+    destroyRuntimeData(project)
+    clearState(project)
+    rmSync(join(project.stateDir, 'secrets.json'), { force: true })
+    releasePorts(project.id)
+    return { data: { stopped: true, dataRemoved: true }, text: 'Stopped, and removed the database and local secrets.' }
+  }
+  return { data: { stopped: true }, text: 'Stopped. Data is kept; `frontera local start` brings it back.' }
+}
+
+export const localStop: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'stop',
+    args: [],
+    flags: { 'no-backup': 'boolean' },
+    summary: 'Stop the local runtime (keeps its data unless --no-backup)',
+    examples: ['frontera local stop', 'frontera local stop --no-backup'],
+    offline: true,
+    internal: true,
+  },
+  run: stop,
+}
+
+async function status(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const state = readState(project)
+  if (!state) {
+    return { data: null, text: 'No local runtime here. Run `frontera local start`.' }
+  }
+  if (flagString(ctx, 'output') === 'env') {
+    const lines = [
+      `FRONTERA_API_URL=http://127.0.0.1:${state.ports.service}`,
+      `FRONTERA_STUDIO_URL=http://127.0.0.1:${state.ports.studio}`,
+      `FRONTERA_LOCAL_PROFILE=${localProfileName(project)}`,
+      ...(state.credentials
+        ? [
+            `FRONTERA_LOCAL_KEY=${state.credentials.orgKey}`,
+            ...(state.credentials.workspaceKey ? [`FRONTERA_WORKSPACE_KEY=${state.credentials.workspaceKey}`] : []),
+            `FRONTERA_ORG_ID=${state.credentials.organizationId}`,
+            `FRONTERA_WORKSPACE_ID=${state.credentials.workspaceId}`,
+          ]
+        : []),
+    ]
+    return { data: Object.fromEntries(lines.map((l) => l.split(/=(.*)/s).slice(0, 2))), text: lines.join('\n') }
+  }
+  const { credentials, ...rest } = state
+  return {
+    data: { ...rest, credentials: credentials ? { email: credentials.email, organizationId: credentials.organizationId, workspaceId: credentials.workspaceId } : null },
+    text: renderStatus(state, project),
+  }
+}
+
+export const localStatus: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'status',
+    args: [],
+    flags: { output: 'string' },
+    aliases: { o: 'output' },
+    summary: 'Show the local runtime: components, URLs and credentials (-o env for scripts)',
+    examples: ['frontera local status', 'eval "$(frontera local status -o env)"'],
+    offline: true,
+    internal: true,
+  },
+  run: status,
+}
+
+async function logs(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const component = (ctx.positional[0] ?? 'service') as ComponentName
+  if (!COMPONENTS.includes(component)) {
+    throw new UsageError(`unknown component \`${component}\``, `use one of: ${COMPONENTS.join(', ')}`)
+  }
+  const file = logPath(project, component)
+  if (!existsSync(file)) return { data: { lines: [] }, text: `No ${component} log yet.` }
+  if (flagBool(ctx, 'follow')) {
+    await new Promise<void>((r) => {
+      const child = spawn('tail', ['-n', '100', '-f', file], { stdio: 'inherit' })
+      child.on('exit', () => r())
+    })
+    return { data: null, text: '' }
+  }
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean).slice(-Number(flagString(ctx, 'lines') ?? 100))
+  return { data: { component, lines }, text: lines.join('\n') }
+}
+
+export const localLogs: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'logs',
+    args: [{ name: 'component', required: false, description: COMPONENTS.join(' | ') }],
+    flags: { follow: 'boolean', lines: 'string' },
+    aliases: { f: 'follow', n: 'lines' },
+    summary: 'Print a component\'s log (service by default)',
+    examples: ['frontera local logs', 'frontera local logs jobs -f'],
+    offline: true,
+    internal: true,
+  },
+  run: logs,
+}
+
+async function reset(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  await ctx.output.task('Stopping the local runtime', () => stopRuntime(project))
+  destroyRuntimeData(project)
+  clearState(project)
+  rmSync(join(project.stateDir, 'secrets.json'), { force: true })
+  // Traces of the wiped runtime would point at conversations that are gone.
+  rmSync(join(project.stateDir, 'traces.jsonl'), { force: true })
+  const result = await start(ctx)
+  return { data: result.data, text: `Reset to a clean runtime.\n\n${result.text}` }
+}
+
+export const localReset: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'reset',
+    ...startMeta,
+    summary: 'Wipe the local database and secrets, then start a clean, freshly seeded runtime',
+    examples: ['frontera local reset'],
+  },
+  run: reset,
+}
+
+async function ui(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.supervisorPid || !isAlive(state.supervisorPid)) {
+    throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'run `frontera local start` first' })
+  }
+  const url = studioUrl(state, project)
+  if (!flagBool(ctx, 'no-open') && process.platform === 'darwin') spawn('open', [url], { stdio: 'ignore', detached: true }).unref()
+  else if (!flagBool(ctx, 'no-open') && process.platform === 'linux') spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref()
+  return { data: { url }, text: `Frontera Studio: ${url}` }
+}
+
+export const localUi: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'ui',
+    args: [],
+    flags: { 'no-open': 'boolean' },
+    summary: 'Open Frontera Studio for the running local runtime',
+    examples: ['frontera local ui', 'frontera local ui --no-open'],
+    offline: true,
+    internal: true,
+  },
+  run: ui,
+}
+
+async function test(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.credentials?.session) {
+    throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'run `frontera local start` first' })
+  }
+  const files = findCaseFiles(project.root, flagString(ctx, 'agent'))
+  const total = files.reduce((n, f) => n + f.cases.length, 0)
+  if (total === 0) {
+    return {
+      data: { passed: 0, failed: 0, results: [] },
+      text: 'No test cases. Save one from Studio (Agents → Save as test case) or add agents/<slug>/evals/*.yaml.',
+    }
+  }
+  const results = await runCases({
+    serviceUrl: `http://127.0.0.1:${state.ports.service}`,
+    creds: state.credentials,
+    files,
+    live: flagBool(ctx, 'live'),
+    onResult: (r) => ctx.output.note(`  ${r.passed ? '✓' : '✕'} ${r.agent} · ${r.name}${r.passed ? '' : ` — ${r.reason}`} (${r.ms} ms)`),
+  })
+  const failed = results.filter((r) => !r.passed)
+  const summary = `${results.length - failed.length} passed, ${failed.length} failed`
+  if (failed.length) {
+    throw new CliError(`${summary}: ${failed.map((f) => `${f.agent} · ${f.name}`).join('; ')}`, {
+      code: 'LOCAL_TESTS_FAILED',
+      hint: 'open the Agent in Studio (`frontera local ui`) to see the conversation, then fix the Agent or the case',
+    })
+  }
+  return { data: { passed: results.length, failed: 0, results }, text: summary }
+}
+
+export const localTest: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'test',
+    args: [],
+    flags: { agent: 'string', live: 'boolean' },
+    summary: 'Run the project\'s saved Agent test cases against the local runtime',
+    examples: ['frontera local test', 'frontera local test --agent claims-triage', 'frontera local test --live'],
+    offline: true,
+    internal: true,
+  },
+  run: test,
+}
+
+/** The supervisor itself. Spawned detached by `start`; not for direct use. */
+export const localDaemon: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'daemon',
+    args: [],
+    flags: {},
+    summary: 'Run the local runtime supervisor (started by `frontera local start`)',
+    examples: ['frontera local start'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const project = localProject(ctx.cwd)
+    const ports = claimPorts(project.id, project.root)
+    await runSupervisor(project, ports, process.env.FRONTERA_LOCAL_SESSION ?? readSession(project) ?? newSessionToken())
+    // Keep the supervisor alive: the Studio server and child watchers run on the event loop.
+    await new Promise(() => {})
+    return { data: null, text: '' }
+  },
+}
+
+export const localCommands: readonly Command[] = [
+  localInit,
+  localStart,
+  localStop,
+  localStatus,
+  localLogs,
+  localReset,
+  localUi,
+  localDev,
+  localTest,
+  localCheck,
+  localKeySet,
+  localKeyList,
+  localKeyRemove,
+  localProviders,
+  localProviderAdd,
+  localProviderRemove,
+  localModelsAvailable,
+  localModelAdd,
+  localModelRemove,
+  localModelDefault,
+  localDocsMcp,
+  localSchema,
+  localDaemon,
+]

package/src/commands/local/init.ts

@@ -0,0 +1,78 @@
+import { spawnSync } from 'node:child_process'
+import { basename, resolve } from 'node:path'
+
+import { UsageError } from '../../errors'
+import { writeHarnessFiles } from '../../harness'
+import { slugify } from '../../local/local-project'
+import { readProviderSetup } from '../../local/local-providers'
+import { writeSolutionScaffold } from '../../local/local-scaffold'
+import { flagBool, type Command } from '../types'
+
+/**
+ * `frontera local init [name]`: a new project in the layout `local dev`
+ * applies, like `supabase init`. Into `<name>/`, or this folder when no name
+ * is given; files already there are kept unless `--force`.
+ */
+export const localInit: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'init',
+    args: [{ name: 'name', required: false, description: 'folder to create the project in (default: this folder)' }],
+    flags: { force: 'boolean', 'no-install': 'boolean' },
+    summary: 'Create a project: an Agent with a test case, a workflow, a Function and a Blueprint object type with its data',
+    examples: ['frontera local init claims-intake', 'frontera local init', 'frontera local init acme-support --no-install'],
+    offline: true,
+    internal: true,
+  },
+
+  async run(ctx) {
+    const given = ctx.positional[0]
+    const target = given ? resolve(ctx.cwd, given) : ctx.cwd
+    const name = slugify(basename(target))
+    if (!name) throw new UsageError('the project needs a name with letters or digits', 'frontera local init <name>')
+
+    const force = flagBool(ctx, 'force')
+    // The CLI skill and CLAUDE.md, so a coding agent here knows the CLI. First,
+    // so the scaffold's AGENTS.md (the generic one plus this project's loop)
+    // replaces the generic one rather than the other way round.
+    const harness = writeHarnessFiles(target, { force })
+    // The starter Agent takes the model the FDE chose for new Agents (`frontera local model-default`).
+    const scaffold = writeSolutionScaffold(target, name, force, { agentModel: readProviderSetup().defaults.agentModel })
+    const listed = (files: string[]) => files.filter((f) => !f.startsWith('vendor/'))
+    const written = [...new Set(listed([...scaffold.written, ...harness.written]))]
+    const skipped = listed([...scaffold.skipped, ...harness.skipped]).filter((f) => !written.includes(f))
+
+    let installed: boolean | null = null
+    if (!flagBool(ctx, 'no-install') && scaffold.written.includes('package.json')) {
+      ctx.output.note('Installing the Function dependencies (bun install)')
+      // Kept off stdout, which carries the command's own (possibly JSON) output.
+      const res = spawnSync('nice', ['-n', '10', 'bun', 'install', '--silent'], { cwd: target, stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8' })
+      installed = res.status === 0
+      if (!installed) {
+        const why = (res.stderr || res.error?.message || '').trim().split('\n')[0]
+        ctx.output.note(`  bun install failed${why ? `: ${why}` : ''}; run it in the folder before deploying Functions`)
+      }
+    }
+
+    const cd = given ? [`  cd ${given}`] : []
+    const sdkWritten = scaffold.written.some((f) => f.startsWith('vendor/'))
+    const heading = written.length
+      ? `Created the project ${name}`
+      : `${name} already has every file${sdkWritten ? '; the vendored Functions SDK was completed' : ''}`
+    return {
+      data: { name, path: target, written, skipped, installed },
+      text: [
+        heading,
+        ...written.map((f) => `  + ${f}`),
+        ...(written.length && sdkWritten ? ['  + vendor/frontera/ (the Functions SDK)'] : []),
+        ...skipped.map((f) => `  · ${f} (exists; --force replaces it)`),
+        '',
+        'Next:',
+        ...cd,
+        '  frontera local start',
+        '  frontera local dev',
+        '  frontera local ui',
+      ].join('\n'),
+    }
+  },
+}

package/src/commands/local/key.ts

@@ -0,0 +1,108 @@
+import { readFileSync } from 'node:fs'
+
+import { UsageError } from '../../errors'
+import { promptSecret } from '../../prompt'
+import { configuredProviders, findProvider, LOCAL_PROVIDERS, removeKey, setKey } from '../../local/local-keys'
+import { localProject } from '../../local/local-project'
+import { removeRuntimeKey, runningTarget } from '../../local/local-providers'
+import { applyModelKeys, ensureProviderModels } from '../../local/local-seed'
+import { logPath } from '../../local/local-state'
+import { flagBool, type Command } from '../types'
+
+/**
+ * `frontera local key …`: each FDE's own provider keys for the local runtime.
+ *
+ * The key arrives on stdin or at a hidden prompt, never as a flag: a flag lands
+ * in shell history and in the process list for anyone running `ps`. A running
+ * runtime takes a new or removed key at once; Cohere, read only from the
+ * service's environment, waits for the next start.
+ */
+
+function providerArg(raw: string | undefined) {
+  const provider = raw ? findProvider(raw) : undefined
+  if (!provider) {
+    throw new UsageError(
+      `unknown provider ${raw ? `\`${raw}\`` : '(none given)'}`,
+      `use one of: ${LOCAL_PROVIDERS.map((p) => p.id).join(', ')}`,
+    )
+  }
+  return provider
+}
+
+export const localKeySet: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'key-set',
+    args: [{ name: 'provider', required: true, description: LOCAL_PROVIDERS.map((p) => p.id).join(' | ') }],
+    flags: { stdin: 'boolean' },
+    summary: 'Store your model-provider key for the local runtime (OS keychain)',
+    examples: ['frontera local key-set anthropic', 'printf %s "$KEY" | frontera local key-set openrouter --stdin'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const provider = providerArg(ctx.positional[0])
+    const key = flagBool(ctx, 'stdin')
+      ? readFileSync(0, 'utf8').trim()
+      : (await promptSecret(`${provider.label} API key: `)).trim()
+    if (!key) throw new UsageError('no key given', 'pipe it with --stdin, or run in a terminal to be prompted')
+    setKey(provider.id, key)
+    const target = runningTarget(ctx.cwd)
+    let live = false
+    if (target && provider.id !== 'cohere') {
+      const logFile = logPath(localProject(ctx.cwd), 'service')
+      const applied = await applyModelKeys({ serviceUrl: target.serviceUrl, password: target.password, organizationId: target.organizationId, logFile })
+      await ensureProviderModels({ serviceUrl: target.serviceUrl, password: target.password, organizationId: target.organizationId, providers: applied, logFile })
+      live = applied.includes(provider.id)
+    }
+    return {
+      data: { provider: provider.id, stored: true, live },
+      text: live
+        ? `Stored your ${provider.label} key; the runtime uses it now.`
+        : target
+          ? `Stored your ${provider.label} key. Restart the runtime to use it: \`frontera local stop && frontera local start\`.`
+          : `Stored your ${provider.label} key. The runtime uses it from its next start.`,
+    }
+  },
+}
+
+export const localKeyList: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'key-list',
+    args: [],
+    flags: {},
+    summary: 'List which providers have a key for the local runtime',
+    examples: ['frontera local key-list'],
+    offline: true,
+    internal: true,
+  },
+  async run() {
+    const configured = new Set(configuredProviders())
+    const rows = LOCAL_PROVIDERS.map((p) => ({ provider: p.id, label: p.label, configured: configured.has(p.id) }))
+    return {
+      data: rows,
+      text: rows.map((r) => `  ${r.configured ? '●' : '○'} ${r.label.padEnd(16)} ${r.configured ? 'key stored' : '—'}`).join('\n'),
+    }
+  },
+}
+
+export const localKeyRemove: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'key-remove',
+    args: [{ name: 'provider', required: true, description: 'provider id' }],
+    flags: {},
+    summary: 'Remove a stored model-provider key',
+    examples: ['frontera local key-remove openai'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const provider = providerArg(ctx.positional[0])
+    const removed = removeKey(provider.id)
+    const target = runningTarget(ctx.cwd)
+    if (target && removed) await removeRuntimeKey(target, provider.id)
+    return { data: { provider: provider.id, removed }, text: removed ? `Removed your ${provider.label} key.` : `No ${provider.label} key was stored.` }
+  },
+}