@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-project-secrets.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { allTargets } from './local-dev-sync'
+import { functionSecretNames, hasSecretValue, type SecretPresence, workflowSecretNames } from './local-secrets'
+
+/**
+ * The secrets a project needs, by name: `secrets.json` at its root.
+ *
+ *   {
+ *     "secrets": [
+ *       { "name": "INTAKE_WEBHOOK_TOKEN", "description": "The token the intake webhook checks" }
+ *     ]
+ *   }
+ *
+ * Names and descriptions only, never values: a value is set on each computer
+ * with `frontera secret set NAME` and stays on that runtime. The file makes a
+ * project reproducible from its files: after `local reset`, or on another
+ * computer, `local dev` and `local check` say which secrets the runtime still
+ * needs a value for, and why each one is there. A `value` in the file is
+ * refused (said, and ignored), so a value is never written into a commit by
+ * mistake.
+ */
+
+export const PROJECT_SECRETS_FILE = 'secrets.json'
+
+export interface ProjectSecret {
+  name: string
+  description?: string
+}
+
+export interface ProjectSecrets {
+  secrets: ProjectSecret[]
+  /** What is wrong with the file, one line each: said as warnings. */
+  problems: string[]
+}
+
+const NAME = /^[A-Z][A-Z0-9_]*$/
+
+/** The project's `secrets.json`, or null when it has none. Never throws: a bad file is its problems. */
+export function readProjectSecrets(root: string): ProjectSecrets | null {
+  const path = join(root, PROJECT_SECRETS_FILE)
+  if (!existsSync(path)) return null
+  let doc: unknown
+  try {
+    doc = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (err) {
+    return { secrets: [], problems: [`${PROJECT_SECRETS_FILE} is not valid JSON: ${(err as Error).message}`] }
+  }
+  const raw = (doc as { secrets?: unknown } | null)?.secrets
+  if (!Array.isArray(raw)) return { secrets: [], problems: [`${PROJECT_SECRETS_FILE} has no \`secrets\` list: { "secrets": [ { "name": "API_TOKEN", "description": "…" } ] }`] }
+  const secrets: ProjectSecret[] = []
+  const problems: string[] = []
+  for (const [i, entry] of raw.entries()) {
+    const o = (entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : {}) as Record<string, unknown>
+    const name = typeof o.name === 'string' ? o.name.trim() : ''
+    if (!NAME.test(name)) {
+      problems.push(`${PROJECT_SECRETS_FILE}: secret ${i + 1} needs a \`name\` in capitals, digits and underscores (API_TOKEN)`)
+      continue
+    }
+    if ('value' in o) problems.push(`${PROJECT_SECRETS_FILE}: ${name} has a \`value\`, which is ignored and must not be committed: remove it, and set the value with \`frontera secret set ${name}\``)
+    if (secrets.some((s) => s.name === name)) continue
+    secrets.push({ name, ...(typeof o.description === 'string' && o.description.trim() ? { description: o.description.trim() } : {}) })
+  }
+  return { secrets, problems }
+}
+
+/**
+ * The secret names the project's Functions and workflows name in their files,
+ * each with the first file that names it: a Function's `secret:NAME` grants
+ * (a single-file Function, or a folder's entry) and a workflow's `auth`.
+ */
+export function secretsNamedInFiles(root: string): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const target of allTargets(root)) {
+    if (target.kind !== 'function' && target.kind !== 'workflow') continue
+    let names: string[] = []
+    try {
+      const text = readFileSync(join(root, target.file), 'utf8')
+      names = target.kind === 'function' ? functionSecretNames(text) : workflowSecretNames(parseYaml(text))
+    } catch {
+      // Unreadable: it names nothing here.
+    }
+    for (const name of names) if (!out.has(name)) out.set(name, target.file)
+  }
+  return out
+}
+
+/** The warning for a secret the runtime has no value for; a listed one says it lost its value. */
+function needsValue(name: string, who: string, listed: boolean): string {
+  return listed
+    ? `  warning: Needs a value for ${name} (${who}): the runtime lists it, but has no value for it (restoring the database can leave a secret without one); set it again with \`frontera secret set ${name}\` in this folder`
+    : `  warning: Needs a value for ${name} (${who}): set it with \`frontera secret set ${name}\` in this folder`
+}
+
+/**
+ * What to say about the secrets the project needs against what the runtime
+ * holds (`have`: the names it has a value for, or what its secrets list says;
+ * null when it could not say): each secret `secrets.json` declares or a
+ * workflow or Function names that has no value here, said for every item on
+ * each call (not only for an item an apply changed, so a value lost to a
+ * restore is said), each secret a file names that `secrets.json` leaves out,
+ * and the file's own problems. `warning:` lines, as `local dev` says them.
+ */
+export function projectSecretLines(root: string, have: ReadonlySet<string> | SecretPresence | null): string[] {
+  const declared = readProjectSecrets(root)
+  const named = secretsNamedInFiles(root)
+  if (!declared && !named.size) return []
+  const lines = (declared?.problems ?? []).map((p) => `  warning: ${p}`)
+  if (have) {
+    const presence: SecretPresence = have instanceof Set ? { names: new Set(have), withoutValue: new Set() } : (have as SecretPresence)
+    const said = new Set<string>()
+    for (const s of declared?.secrets ?? []) {
+      if (hasSecretValue(presence, s.name)) continue
+      said.add(s.name)
+      lines.push(needsValue(s.name, `${PROJECT_SECRETS_FILE}${s.description ? `: ${s.description}` : ''}`, presence.names.has(s.name)))
+    }
+    for (const [name, file] of named) {
+      if (said.has(name) || hasSecretValue(presence, name)) continue
+      said.add(name)
+      lines.push(needsValue(name, file, presence.names.has(name)))
+    }
+  }
+  if (declared) {
+    const names = new Set(declared.secrets.map((s) => s.name))
+    for (const [name, file] of named) {
+      if (!names.has(name)) lines.push(`  warning: ${file} names the secret ${name}, which ${PROJECT_SECRETS_FILE} doesn't list: add { "name": "${name}", "description": "…" } so the project says what it needs`)
+    }
+  }
+  return lines
+}

package/src/local/local-project.ts

@@ -56,3 +56,15 @@ export function localProject(cwd: string): LocalProject {
     stateDir: join(root, '.frontera', 'local'),
   }
 }
+
+/**
+ * The CLI profile of the local runtime this directory owns
+ * (`local-<id>`, as `local status` names it), or null when the directory has
+ * never started one. The profile name only: whether it is registered on this
+ * machine is the caller's to check.
+ */
+export function localRuntimeProfileOf(root: string): string | null {
+  const project = localProject(root)
+  if (!existsSync(join(project.stateDir, 'state.json'))) return null
+  return `local-${project.id}`.slice(0, 64)
+}

package/src/local/local-provider-refusal.ts

@@ -0,0 +1,66 @@
+import { caseCouldNotRun, notRunFix, withDirectModel, type NotRunKind } from './local-case-not-run'
+import { findProvider } from './local-keys'
+import { directModelFor } from './local-seed'
+
+/**
+ * A model provider's refusal met outside a test case: an `agent_chat` turn,
+ * or a Function run whose Agent call the provider refused. Said as the cause
+ * (the provider account, named when its words name it) and the fix, the way
+ * `test_run` says a case that couldn't run, instead of the provider's raw
+ * words. Only the provider's refusals are turned into this: a timeout or a
+ * runtime that does not answer keeps its own message.
+ */
+export interface ProviderRefusal {
+  cause: 'provider'
+  kind: Extract<NotRunKind, 'credits' | 'rate-limit' | 'key' | 'provider-error'>
+  /** The refusing provider's id and label, when its words name it. */
+  provider?: string
+  providerLabel?: string
+  /** "the OpenRouter account refused the request: it is out of credit (402)". */
+  what: string
+  fix: string
+  /** A model the runtime offers directly from another provider whose key it holds, for a credit refusal. */
+  directModel?: { slug: string; name: string; provider: string }
+  /** The provider's own words, for the record. */
+  providerSaid: string
+}
+
+const WHAT: Record<ProviderRefusal['kind'], (account: string, status: string) => string> = {
+  credits: (account, status) => `the ${account} refused the request: it is out of credit (${status || '402'})`,
+  'rate-limit': (account, status) => `the ${account} is limiting requests (${status || '429'})`,
+  key: (account, status) => `the ${account} refused the key${status ? ` (${status})` : ''}`,
+  'provider-error': (account, status) => `the ${account.replace(/ account$/, '')} failed to answer${status ? ` (${status})` : ''}`,
+}
+
+/**
+ * The refusal in `message`, or null when it is not the model provider's.
+ * `providers` are the ids the local runtime applied keys for (never a key),
+ * so a credit refusal can name a model another held key runs; `again` is
+ * what the person does once it is fixed ("send the message again").
+ */
+export function providerRefusal(message: string, opts: { providers?: readonly string[]; again: string }): ProviderRefusal | null {
+  const n = caseCouldNotRun(message)
+  if (!n || n.cause !== 'provider') return null
+  const kind = n.kind as ProviderRefusal['kind']
+  const label = n.provider ? (findProvider(n.provider)?.label ?? n.provider) : null
+  const status = /\((\d{3})/.exec(n.what)?.[1] ?? ''
+  const account = label ? `${label} account` : 'model provider account'
+  const direct = kind === 'credits' ? directModelFor(opts.providers, n.provider) : null
+  const base = { ...n, fix: notRunFix(n.kind, opts.again) }
+  const fix = withDirectModel(base, direct, opts.again).fix
+  const named = label ? fix.replace(/^the model provider account is out of credit/, `the ${label} account is out of credit`) : fix
+  return {
+    cause: 'provider',
+    kind,
+    ...(n.provider ? { provider: n.provider, providerLabel: label! } : {}),
+    what: WHAT[kind](account, status),
+    fix: named,
+    ...(direct ? { directModel: { slug: direct.slug, name: direct.name, provider: direct.provider } } : {}),
+    providerSaid: message.replace(/\s+/g, ' ').trim().slice(0, 400),
+  }
+}
+
+/** One line for a person: "couldn't run: <what>. Fix: <fix>". */
+export function refusalLine(r: ProviderRefusal): string {
+  return `couldn’t run: ${r.what}. Fix: ${r.fix}`
+}

package/src/local/local-request-evidence.ts

@@ -0,0 +1,112 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { caseKey, compareWithLastRun, type LastRun } from './local-test-baseline'
+import type { CaseFile, CaseResult } from './local-test-runner'
+
+/**
+ * Evidence a change request carries (design 2026-10-18 §6): an Agent's gated
+ * evals against its last applied run, an App's last render, screenshots
+ * from a Forge session. Pure where it can be; the command attaches what
+ * these build.
+ */
+
+/** What the platform's gate reads from an Agent's evals (`change-request-gate.ts`). */
+export interface EvalsDetail {
+  gated: number
+  passed: number
+  failed: number
+  newlyFailing: Array<{ name: string; file: string; reason: string | null }>
+  /**
+   * Cases that couldn't run (the model provider refused them, the runtime did
+   * not answer): evidence with any is not attached, since none newly failing
+   * would then say nothing about them.
+   */
+  couldNotRun: Array<{ name: string; what: string; fix: string }>
+  fixed: string[]
+  stillFailing: string[]
+  firstRun: number
+  passRate: number | null
+  baselinePassRate: number | null
+  efficiency: { latencyMs: number | null; toolCalls: number | null; baseline: { latencyMs: number | null; toolCalls: number | null } | null }
+  judged: { ran: boolean; reason: string | null }
+  ranAt: string
+  /** Where they ran. */
+  runtime: string
+}
+
+const mean = (values: Array<number | undefined>): number | null => {
+  const known = values.filter((v): v is number => typeof v === 'number')
+  return known.length ? known.reduce((a, b) => a + b, 0) / known.length : null
+}
+
+/**
+ * One Agent's gated cases, compared with its applied baseline (or its last
+ * run, when it was never applied from here): what the gate holds Apply on
+ * (newly failing cases), the pass rate either side, and efficiency per case,
+ * which is reported and never gates.
+ */
+export function evalsDetail(input: { files: CaseFile[]; results: CaseResult[]; baseline: LastRun; runtime: string; now?: Date }): EvalsDetail {
+  const { results, baseline } = input
+  const compared = compareWithLastRun(results, baseline)
+  const before = results.map((r) => baseline[caseKey(r)]).filter((b) => b !== undefined)
+  const judgedCases = input.files.some((f) => f.cases.some((c) => c.judged?.length))
+  return {
+    gated: results.length,
+    passed: results.filter((r) => r.passed).length,
+    failed: results.filter((r) => !r.passed && !r.notRun).length,
+    newlyFailing: compared.newlyFailing.map((r) => ({ name: r.name, file: r.file, reason: r.reason ?? null })),
+    couldNotRun: compared.couldNotRun.map((r) => ({ name: r.name, what: r.notRun!.what, fix: r.notRun!.fix })),
+    fixed: compared.fixed.map((r) => r.name),
+    stillFailing: compared.stillFailing.map((r) => r.name),
+    firstRun: compared.firstRun.length,
+    passRate: results.length ? results.filter((r) => r.passed).length / results.length : null,
+    baselinePassRate: before.length ? before.filter((b) => b!.passed).length / before.length : null,
+    efficiency: {
+      latencyMs: mean(results.map((r) => r.ms)),
+      toolCalls: mean(results.map((r) => r.toolCalls)),
+      baseline: before.length ? { latencyMs: mean(before.map((b) => b!.ms)), toolCalls: mean(before.map((b) => b!.toolCalls)) } : null,
+    },
+    // Judged expectations are graded by the platform's judge model; a local run grades the rest.
+    judged: { ran: false, reason: judgedCases ? 'judged expectations are graded on the platform, with its judge model' : null },
+    ranAt: (input.now ?? new Date()).toISOString(),
+    runtime: input.runtime,
+  }
+}
+
+/** A short line for the person: how the gated cases went. */
+export function evalsLine(title: string, d: EvalsDetail): string {
+  if (!d.gated) return `${title}: no gated cases (mark the ones that guard it with gate: true)`
+  if (d.couldNotRun.length) return `${title}: ${d.couldNotRun.length} of ${d.gated} gated case${d.gated === 1 ? '' : 's'} couldn’t run: ${[...new Set(d.couldNotRun.map((c) => c.what))].join('; ')}; ${d.couldNotRun[0]!.fix}`
+  const rate = d.passRate === null ? '' : `, ${Math.round(d.passRate * 100)}% pass${d.baselinePassRate === null ? '' : ` (was ${Math.round(d.baselinePassRate * 100)}%)`}`
+  return `${title}: ${d.gated} gated case${d.gated === 1 ? '' : 's'}, ${d.newlyFailing.length ? `${d.newlyFailing.length} newly failing (${d.newlyFailing.map((c) => c.name).join(', ')})` : 'none newly failing'}${rate}`
+}
+
+/** The newest pictures a session saved (`.frontera/evidence/<session>/`), newest first, at most `limit`. */
+export function sessionScreenshots(root: string, session: string, limit = 6): Array<{ path: string; name: string; bytes: number; at: number }> {
+  if (!/^[\w.-]{1,120}$/.test(session)) return []
+  const dir = join(root, '.frontera', 'evidence', session)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((n) => /\.(png|jpe?g|webp)$/i.test(n))
+    .map((n) => {
+      const st = statSync(join(dir, n))
+      return { path: join(dir, n), name: n, bytes: st.size, at: st.mtimeMs }
+    })
+    .sort((a, b) => b.at - a.at)
+    .slice(0, limit)
+}
+
+/** An App's last render, as `app_render` and `frontera app dev` keep it in its folder. */
+export function lastRender(appRoot: string): { detail: Record<string, unknown>; image: Buffer | null } | null {
+  const json = join(appRoot, '.frontera', 'last-render.json')
+  if (!existsSync(json)) return null
+  let detail: Record<string, unknown>
+  try {
+    detail = JSON.parse(readFileSync(json, 'utf8')) as Record<string, unknown>
+  } catch {
+    return null
+  }
+  const png = join(appRoot, '.frontera', 'last-render.png')
+  return { detail, image: existsSync(png) ? readFileSync(png) : null }
+}

package/src/local/local-runtime-health.ts

@@ -0,0 +1,123 @@
+import { portAnswers } from './local-component-health'
+import { snapshotInProgress } from './local-db-snapshot'
+import type { LocalProject } from './local-project'
+import { isAlive, readState } from './local-state'
+
+/**
+ * Whether the local runtime answers, for telling an apply that failed for its
+ * files from one that failed because the runtime went away under it (stopped,
+ * restarting, Postgres going down, a database snapshot being restored).
+ */
+
+/** What an item's error says when the runtime wasn't answering. */
+export const RUNTIME_DOWN_ERROR = 'the local runtime isn’t answering (start it with `frontera local start`)'
+/** What `local dev` says when the runtime went down during an apply. */
+export const RUNTIME_STOPPED_LINE = 'runtime stopped mid-apply; the next apply retries it'
+
+/** Output a command prints when it could not reach the service at all. */
+const CONNECTION_ERROR = /ECONNREFUSED|ECONNRESET|EPIPE|Unable to connect|fetch failed|socket connection was closed|connection (?:was )?(?:refused|reset|closed)|ConnectionRefused|ConnectionClosed|FailedToOpenSocket|network error/i
+
+export function isConnectionError(output: string): boolean {
+  return CONNECTION_ERROR.test(output)
+}
+
+export interface HealthDeps {
+  fetch?: (url: string, init?: RequestInit) => Promise<Response>
+  /** Whether something accepts a connection on a local port (Postgres's). */
+  portAnswers?: (port: number) => Promise<boolean>
+}
+
+/**
+ * The runtime answers: its supervisor is up and says it is ready, no database
+ * snapshot holds the database, Postgres takes connections, and the service's
+ * health check answers. The service's `/health` answers from memory, so a
+ * Postgres that went down under it is asked on its own port.
+ */
+export async function runtimeAnswering(project: LocalProject, deps: HealthDeps = {}): Promise<boolean> {
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.supervisorPid || !isAlive(state.supervisorPid)) return false
+  if (snapshotInProgress(project)) return false
+  if (state.ports.postgres && !(await (deps.portAnswers ?? portAnswers)(state.ports.postgres))) return false
+  try {
+    const res = await (deps.fetch ?? fetch)(`http://127.0.0.1:${state.ports.service}/health`, { signal: AbortSignal.timeout(3000) })
+    return res.ok
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Whether a failed apply failed because the runtime wasn't answering: checked
+ * once, now. A runtime that answers again was down for the moment only when
+ * the command itself couldn't reach it; a refusal it answered (a 500
+ * included) is the item's own failure.
+ */
+export async function failedForRuntime(project: LocalProject, output: string, deps: HealthDeps = {}): Promise<boolean> {
+  if (!(await runtimeAnswering(project, deps))) return true
+  const first = output.split('\n').find((l) => /^error/i.test(l.trim())) ?? ''
+  return /\[INTERNAL_ERROR\]/.test(first) && isConnectionError(first)
+}
+
+export interface DatabaseReadyOptions {
+  /** How long to keep asking, in all (30 s). */
+  timeoutMs?: number
+  /** Rounds in a row in which every request found the database (2). */
+  rounds?: number
+  /** Requests sent at once in a round, so more than one of the service's pooled connections answers (4). */
+  parallel?: number
+  /** Pause between rounds (250 ms). */
+  intervalMs?: number
+  fetch?: (url: string, init?: RequestInit) => Promise<Response>
+  sleep?: (ms: number) => Promise<void>
+  now?: () => number
+}
+
+/**
+ * Whether the service reaches its database again after the database was
+ * dropped and made again (a snapshot restore), or its connections ended (a
+ * save): `/health` answers from memory, so the service's database-backed
+ * health route (`/v1/health`, which runs a query) is asked instead, several
+ * requests at once and several rounds in a row, until every request says the
+ * database is connected. A pooled connection ended under the service fails
+ * its next query, so one answer alone is not enough. A runtime from before
+ * that route answers 404 there; its `/health` is taken instead.
+ */
+export async function waitForDatabaseReady(serviceUrl: string, options: DatabaseReadyOptions = {}): Promise<boolean> {
+  const doFetch = options.fetch ?? fetch
+  const sleep = options.sleep ?? ((ms: number) => Bun.sleep(ms))
+  const now = options.now ?? Date.now
+  const rounds = options.rounds ?? 2
+  const parallel = Math.max(1, options.parallel ?? 4)
+  const interval = options.intervalMs ?? 250
+  const deadline = now() + (options.timeoutMs ?? 30_000)
+  const base = serviceUrl.replace(/\/+$/, '')
+  const ask = async (): Promise<'connected' | 'no-route' | 'not-yet'> => {
+    try {
+      const res = await doFetch(`${base}/v1/health`, { signal: AbortSignal.timeout(3000) })
+      if (res.status === 404) return 'no-route'
+      if (!res.ok) return 'not-yet'
+      const body = (await res.json().catch(() => null)) as { data?: { database?: unknown } } | null
+      return body?.data?.database === 'connected' ? 'connected' : 'not-yet'
+    } catch {
+      return 'not-yet'
+    }
+  }
+  let inARow = 0
+  while (now() < deadline) {
+    const answers = await Promise.all(Array.from({ length: parallel }, ask))
+    if (answers.every((a) => a === 'no-route')) {
+      try {
+        const res = await doFetch(`${base}/health`, { signal: AbortSignal.timeout(3000) })
+        if (res.ok) return true
+      } catch {
+        // Not up yet.
+      }
+      inARow = 0
+    } else if (answers.every((a) => a === 'connected')) {
+      inARow += 1
+      if (inARow >= rounds) return true
+    } else inARow = 0
+    await sleep(interval)
+  }
+  return false
+}

package/src/local/local-runtime-history.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import type { LocalProject } from './local-project'
+
+/**
+ * Each time the project's runtime started or stopped, newest last: Forge's
+ * Activity lists them beside the applies, so "Applied 290 items: runtime
+ * started" has the start it follows, and a stop explains why nothing ran
+ * after it. Written by the supervisor; a missed record never fails a start
+ * or a stop.
+ */
+
+export interface RuntimeRecord {
+  event: 'started' | 'stopped' | 'failed'
+  /** When it happened: a start when the runtime was ready, a stop when it had stopped. */
+  at: string
+  /** A start: when it began starting, so its duration can be said. */
+  since?: string
+  /** A failed start: which part, and why. */
+  detail?: string
+}
+
+/** How many are kept: Activity shows the recent ones. */
+const KEEP = 30
+
+const historyPath = (stateDir: string) => join(stateDir, 'runtime-history.json')
+
+/** The records kept, oldest first; none when the file is missing or unreadable. */
+export function readRuntimeHistory(stateDir: string): RuntimeRecord[] {
+  try {
+    const list = JSON.parse(readFileSync(historyPath(stateDir), 'utf8')) as unknown
+    return Array.isArray(list)
+      ? list.filter((r): r is RuntimeRecord => !!r && typeof (r as RuntimeRecord).at === 'string' && ['started', 'stopped', 'failed'].includes((r as RuntimeRecord).event))
+      : []
+  } catch {
+    return []
+  }
+}
+
+/** Keep one record. Never throws. */
+export function recordRuntime(project: Pick<LocalProject, 'stateDir'>, record: RuntimeRecord): void {
+  try {
+    const list = [...readRuntimeHistory(project.stateDir), record].slice(-KEEP)
+    writeFileAtomic(historyPath(project.stateDir), `${JSON.stringify(list, null, 2)}\n`, 0o644)
+  } catch {
+    // The runtime itself is what matters.
+  }
+}

package/src/local/local-runtime-target.ts

@@ -0,0 +1,42 @@
+import { localProject, type LocalProject } from './local-project'
+import { isAlive, readState, type LocalCredentials, type LocalState } from './local-state'
+
+/**
+ * The local runtime a command reaches, when it reaches one: the project the
+ * working directory is in has a ready runtime, and the command's API address
+ * is that runtime's service. Commands that behave differently on the local
+ * runtime (resolving a project file's names, acting as a seeded persona) ask
+ * this, so nothing local-only ever reaches a hosted deployment.
+ */
+export interface LocalRuntimeTarget {
+  project: LocalProject
+  state: LocalState
+  creds: LocalCredentials
+  serviceUrl: string
+}
+
+/** `http://localhost:4100/` and `http://127.0.0.1:4100` are the same service. */
+function sameService(a: string, b: string): boolean {
+  try {
+    const x = new URL(a)
+    const y = new URL(b)
+    const host = (h: string) => (h === 'localhost' || h === '[::1]' ? '127.0.0.1' : h)
+    return x.protocol === y.protocol && host(x.hostname) === host(y.hostname) && x.port === y.port
+  } catch {
+    return false
+  }
+}
+
+export function localRuntimeAt(cwd: string, apiUrl: string): LocalRuntimeTarget | null {
+  let project: LocalProject
+  try {
+    project = localProject(cwd)
+  } catch {
+    return null
+  }
+  const state = readState(project)
+  if (!state?.credentials || state.phase !== 'ready' || !isAlive(state.supervisorPid)) return null
+  const serviceUrl = `http://127.0.0.1:${state.ports.service}`
+  if (!sameService(serviceUrl, apiUrl)) return null
+  return { project, state, creds: state.credentials, serviceUrl }
+}