@frontera-sdk/cli 1.44.0 → 1.45.0

package/src/commands/types.ts

@@ -31,6 +31,20 @@ export interface CommandMeta {
   optionalProject?: boolean
   /** No credential needed — scaffolding runs before a key exists. */
   offline?: boolean
+  /**
+   * Which credential actually reaches this command's endpoints.
+   *
+   * `requiresCredential` says WHETHER one is needed and nothing about which,
+   * so a caller holding an `sk-org-` key could not tell `blueprint list` from
+   * `action deploy` — the second reaches routers mounted on session-only auth
+   * and answers 401 no matter how valid the key is. That failure is
+   * indistinguishable from an expired credential at the call site, so the
+   * distinction has to be discoverable before the call.
+   *
+   * Default `api-key`: the programmatic surface is the norm, and a command
+   * that forgets to declare this is far more likely to be on it.
+   */
+  authLane?: 'api-key' | 'session'
   /**
    * Present → the command is planned but unbuilt, and fails with this message.
    * Reserved in the table rather than omitted: a caller reading "unknown

package/src/config.ts

@@ -1,142 +1,239 @@
-import { spawnSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { existsSync } from 'node:fs'
 
+import { credentialStore, type CredentialSource } from './credential-store'
 import { CliError, UsageError } from './errors'
+import { migrateLegacyConfig } from './profile-migration'
+import { configPath, type Env } from './paths'
+import { findContext } from './project-context'
+import {
+  assertOriginMatches,
+  isLegacyConfig,
+  listProfiles,
+  normalizeOrigin,
+  readLegacyConfig,
+  requireProfile,
+  type CredentialKind,
+  type ProfileMetadata,
+} from './profiles'
+
+export { cacheDir, configDir, configPath, type Env } from './paths'
 
 export interface Credential {
   apiUrl: string
   token: string
 }
 
-type Env = Record<string, string | undefined>
+export type ProfileSource = 'flag' | 'environment' | 'directory' | 'none'
+export type OriginSource = 'flag' | 'environment' | 'profile'
 
-interface StoredConfig {
-  /**
-   * The origin `frontera login` last verified.
-   *
-   * Without it, logging in successfully still left every following command
-   * failing on "no API origin configured" — the credential was stored under a
-   * key nothing knew to look up. Storing the origin is what makes `login` a
-   * complete act rather than half of one.
-   */
-  defaultOrigin?: string
-  origins?: Record<string, { token?: string }>
+/**
+ * What was resolved, and where each part came from — with no secret in it.
+ *
+ * Provenance is not decoration. "Which key is this command about to use" is the
+ * question an FDE has to answer before running anything against a customer, and
+ * an answer that says only "a key" is not one. `auth current --json` returns
+ * exactly this.
+ */
+export interface CredentialResolution {
+  profile: string | null
+  profileSource: ProfileSource
+  profileSourcePath?: string
+  apiUrl: string
+  apiUrlSource: OriginSource
+  credentialSource: CredentialSource
+  credentialKind: CredentialKind | null
+  workspaceId: string | null
+  orgId: string | null
+  fingerprint?: string
 }
 
-const KEYCHAIN_SERVICE = 'frontera-cli'
+export interface ResolvedCredential extends CredentialResolution {
+  token: string
+}
 
 /**
- * XDG, not `~/.frontera`.
+ * The narrow slice of the credential store resolution needs.
  *
- * The spec assigns credentials to `$XDG_CONFIG_HOME` and disposable data to
- * `$XDG_CACHE_HOME`; `gh` follows it, and Supabase's `~/.supabase` is its
- * fallback rather than its design. A bare dotfile directory is the shape
- * nobody chose deliberately.
+ * Structural rather than the concrete store so a test can supply two profiles
+ * without a keychain, which is the only way the multi-profile cases are
+ * testable on a machine that has one.
  */
-export function configPath(env: Env = process.env): string {
-  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config')
-  return join(base, 'frontera', 'config.json')
+export interface ResolutionStore {
+  locate(profile: string): Promise<{ token: string; source: CredentialSource } | null>
 }
 
-/** Disposable, keyed by API origin because the registry is per-deployment. */
-export function cacheDir(apiUrl: string, env: Env = process.env): string {
-  const base = env.XDG_CACHE_HOME || join(env.HOME || homedir(), '.cache')
-  const key = createHash('sha256').update(apiUrl).digest('hex').slice(0, 16)
-  return join(base, 'frontera', key)
+export interface CredentialDeps {
+  env?: Env
+  /** The directory the command is acting on — `--dir` when given, else cwd. */
+  cwd?: string
+  store?: ResolutionStore
 }
 
-function readStored(env: Env): StoredConfig {
-  const path = configPath(env)
-  if (!existsSync(path)) return {}
-  try {
-    return JSON.parse(readFileSync(path, 'utf8')) as StoredConfig
-  } catch {
-    // A corrupt config must not brick every command — treat it as absent and
-    // let the missing-credential error say what to do.
-    return {}
-  }
+export interface ResolveOptions {
+  apiUrl?: string
+  profile?: string
 }
 
 /**
- * macOS keychain read. Returns null on any failure, including "not macOS" and
- * "no keychain in this sandbox" — both ordinary, since the file fallback is
- * the hot path in CI and inside the Computer.
+ * Stage one: which profile.
+ *
+ * Explicit outranks inferred, and there is deliberately NO most-recently-used
+ * fallback. A machine-wide "last profile" is what makes a command in one
+ * customer's repository inherit another customer's key, which is the failure
+ * this whole model exists to remove — so a directory with nothing selected in
+ * its ancestry is an error naming the fix, not a guess.
  */
-function readKeychain(apiUrl: string): string | null {
-  try {
-    const res = spawnSync(
-      'security',
-      ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', apiUrl, '-w'],
-      { encoding: 'utf8' },
-    )
-    if (res.status !== 0) return null
-    const value = res.stdout.trim()
-    return value || null
-  } catch {
-    return null
+export function resolveProfileName(
+  opts: ResolveOptions,
+  deps: CredentialDeps = {},
+): { profile: string | null; source: ProfileSource; path?: string } {
+  const env = deps.env ?? process.env
+  if (opts.profile) return { profile: opts.profile, source: 'flag' }
+  if (env.FRONTERA_PROFILE) return { profile: env.FRONTERA_PROFILE, source: 'environment' }
+
+  const found = findContext(deps.cwd ?? process.cwd(), env)
+  if (found) {
+    /**
+     * Selection is answered by the file; PROVENANCE is not.
+     *
+     * The upward walk cannot tell who wrote the context it found, and a
+     * repository may commit one — naming `default`, which every migrated
+     * machine has. Acting on it would run a customer's key inside a checkout
+     * the user merely cloned. So a binding this machine did not make is a
+     * question rather than an answer, and `auth use` is how it gets answered.
+     */
+    if (!found.trusted) {
+      throw new CliError(
+        `${found.path} selects "${found.profile}", but this machine never bound that directory`,
+        {
+          code: 'PROJECT_CONTEXT_UNTRUSTED',
+          hint:
+            `if you meant to use it, run \`frontera auth use ${found.profile}\` in ${found.root} — `
+            + 'a context file committed to a repository is not proof that you chose it',
+        },
+      )
+    }
+    return { profile: found.profile, source: 'directory', path: found.path }
   }
+
+  return { profile: null, source: 'none' }
 }
 
-export interface CredentialDeps {
-  env?: Env
-  keychain?: (apiUrl: string) => string | null
+/** Version-1 configuration is upgraded on first access, then never again. */
+export async function ensureMigrated(env: Env): Promise<void> {
+  if (!existsSync(configPath(env))) return
+  if (!readLegacyConfig(env)) return
+  await migrateLegacyConfig(env)
 }
 
 /**
- * Resolve the API origin and token.
+ * Resolve profile, origin and key — in that order, each with its own rules.
  *
- * Order: `--api-url` → environment → OS keychain → XDG config file. The
- * environment keeps precedence over stored credentials so that adding storage
- * changes nothing for the Computer or CI, both of which set the variable.
- *
- * The token is never read from a flag. A secret in a flag lands in process
- * listings and shell history, and a CLI that offers the option will have it
- * used.
+ * The three stages are separate because they fail differently. A missing
+ * profile is a selection problem the caller fixes with `auth use`; a mismatched
+ * origin is a mistake that must never reach the network; a missing key is an
+ * authorization problem no retry helps with. Collapsing them into one
+ * "unauthorized" was the old behaviour and it sent every case to the same
+ * unhelpful hint.
  */
-export function resolveCredential(
-  opts: { apiUrl?: string } = {},
+export async function resolveCredential(
+  opts: ResolveOptions = {},
   deps: CredentialDeps = {},
-): Credential {
+): Promise<ResolvedCredential> {
   const env = deps.env ?? process.env
-  const keychain = deps.keychain ?? readKeychain
-
-  const stored = readStored(env)
-  const apiUrl = opts.apiUrl || env.FRONTERA_API_URL || stored.defaultOrigin
-  if (!apiUrl) {
-    throw new UsageError(
-      'no API origin configured',
-      'run `frontera login --api-url <origin>`, set FRONTERA_API_URL, or pass --api-url',
-    )
+  await ensureMigrated(env)
+
+  const store = deps.store ?? credentialStore(env)
+  const selection = resolveProfileName(opts, deps)
+
+  const explicitOrigin = opts.apiUrl ?? env.FRONTERA_API_URL
+  const originSource: OriginSource = opts.apiUrl ? 'flag' : env.FRONTERA_API_URL ? 'environment' : 'profile'
+
+  /**
+   * A raw token in the environment is the CI and Computer path, and it is
+   * deliberately origin-strict: without a required explicit origin, a CI secret
+   * would be sent to whatever deployment the checked-out directory happens to
+   * select. That is a cross-customer credential leak with no visible symptom.
+   */
+  const envToken = env.FRONTERA_TOKEN?.trim()
+  if (envToken) {
+    if (!explicitOrigin) {
+      throw new UsageError(
+        'FRONTERA_TOKEN is set but no API origin is',
+        'set FRONTERA_API_URL, or pass --api-url <origin> — a raw token is never sent to a directory-selected origin',
+      )
+    }
+    return {
+      profile: selection.profile,
+      profileSource: selection.source,
+      ...(selection.path ? { profileSourcePath: selection.path } : {}),
+      apiUrl: explicitOrigin,
+      apiUrlSource: originSource,
+      credentialSource: 'environment',
+      credentialKind: envToken.startsWith('sk-org-') ? 'organization' : 'workspace',
+      workspaceId: null,
+      orgId: null,
+      token: envToken,
+    }
   }
 
-  const token = env.FRONTERA_TOKEN || keychain(apiUrl) || stored.origins?.[apiUrl]?.token
+  if (!selection.profile) throw noProfileSelected(env)
+
+  const metadata = requireProfile(selection.profile, env)
+  if (explicitOrigin) assertOriginMatches(selection.profile, metadata.apiUrl, explicitOrigin)
 
-  if (!token) {
-    throw new CliError(`no credential for ${apiUrl}`, {
-      code: 'UNAUTHORIZED',
-      hint: `set FRONTERA_TOKEN to an sk-ws- workspace key, or store one at ${configPath(env)}`,
+  const located = await store.locate(selection.profile)
+  if (!located) {
+    throw new CliError(`profile "${selection.profile}" has no stored key`, {
+      code: 'PROFILE_SECRET_MISSING',
+      hint: `re-add it with \`frontera auth add ${selection.profile} --api-url ${metadata.apiUrl}\``,
     })
   }
 
-  return { apiUrl, token }
+  return {
+    profile: selection.profile,
+    profileSource: selection.source,
+    ...(selection.path ? { profileSourcePath: selection.path } : {}),
+    apiUrl: metadata.apiUrl,
+    apiUrlSource: originSource === 'profile' ? 'profile' : originSource,
+    credentialSource: located.source,
+    credentialKind: metadata.credentialKind,
+    workspaceId: metadata.workspaceId,
+    orgId: metadata.orgId,
+    fingerprint: metadata.fingerprint,
+    token: located.token,
+  }
 }
 
-/** Persist a token for one origin, leaving any other origin's untouched. */
-export function writeStoredToken(apiUrl: string, token: string, env: Env = process.env): void {
-  const path = configPath(env)
-  const current = readStored(env)
-  const next: StoredConfig = {
-    ...current,
-    // The most recent successful login becomes the default, so the next
-    // command needs no environment at all.
-    defaultOrigin: apiUrl,
-    origins: { ...current.origins, [apiUrl]: { token } },
-  }
-  mkdirSync(dirname(path), { recursive: true })
-  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`)
-  // 0600 because this holds a key with full workspace write.
-  chmodSync(path, 0o600)
+function noProfileSelected(env: Env): CliError {
+  const known = listProfiles(env).map((p) => p.name)
+  return new CliError('no Frontera profile is selected for this directory', {
+    code: 'PROFILE_NOT_SELECTED',
+    hint: known.length
+      ? `run \`frontera auth use <profile>\` here — you have: ${known.join(', ')}`
+      : 'run `frontera auth add <profile> --api-url <origin>`, then `frontera auth use <profile>`',
+  })
 }
+
+/**
+ * The same resolution WITHOUT reading a secret.
+ *
+ * `auth current` has to work when the key is missing — that is one of the
+ * states it exists to report — and `auth use` has no reason to touch the
+ * keychain at all.
+ */
+export async function describeSelection(
+  opts: ResolveOptions = {},
+  deps: CredentialDeps = {},
+): Promise<{
+  selection: ReturnType<typeof resolveProfileName>
+  metadata: ProfileMetadata | null
+}> {
+  const env = deps.env ?? process.env
+  await ensureMigrated(env)
+  const selection = resolveProfileName(opts, deps)
+  const metadata = selection.profile ? requireProfile(selection.profile, env) : null
+  return { selection, metadata }
+}
+
+export { isLegacyConfig, normalizeOrigin }

package/src/credential-store.ts

@@ -0,0 +1,273 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { configDir, type Env } from './paths'
+import { CliError } from './errors'
+import { writeFileAtomic } from './fs-atomic'
+
+/**
+ * Where key bytes live.
+ *
+ * Addressed by PROFILE, not by API origin. That single change is what lets two
+ * keys for the same deployment coexist: the old keychain record was keyed by
+ * origin, so the second one overwrote the first and an FDE could hold exactly
+ * one customer at a time.
+ *
+ * The logical identifier is:
+ *
+ *     service: frontera-cli
+ *     account: profile:<profile-name>
+ */
+export interface CredentialStore {
+  readonly kind: CredentialSource
+  get(profile: string): Promise<string | null>
+  set(profile: string, token: string): Promise<void>
+  delete(profile: string): Promise<void>
+}
+
+export type CredentialSource = 'keychain' | 'file' | 'environment'
+
+export const KEYCHAIN_SERVICE = 'frontera-cli'
+
+export function accountFor(profile: string): string {
+  return `profile:${profile}`
+}
+
+/**
+ * macOS Keychain, through the `security` command already used here.
+ *
+ * The token is passed as an argument to `security`, which is the only write
+ * form it has: with `-w` omitted it does not read the value from stdin, it
+ * stores an EMPTY password — an entry that looks stored and authenticates
+ * nothing. The exposure is one short-lived child process on the user's own
+ * machine, which is a materially smaller surface than the Frontera CLI itself
+ * accepting `--token`, and that remains refused.
+ */
+export class KeychainStore implements CredentialStore {
+  readonly kind = 'keychain' as const
+
+  async get(profile: string): Promise<string | null> {
+    const res = run(['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', accountFor(profile), '-w'])
+    if (!res || res.status !== 0) return null
+    const value = res.stdout.trim()
+    return value || null
+  }
+
+  async set(profile: string, token: string): Promise<void> {
+    const res = run([
+      'add-generic-password',
+      '-s', KEYCHAIN_SERVICE,
+      '-a', accountFor(profile),
+      '-w', token,
+      // Update in place. Without it a second write fails with "already exists",
+      // which would make rotating a key mean deleting one first.
+      '-U',
+    ])
+    if (!res || res.status !== 0) {
+      throw new CliError('the macOS Keychain refused to store the key', {
+        code: 'SECURE_STORE_UNAVAILABLE',
+        hint: 'unlock the login keychain and retry, or set FRONTERA_SECRET_STORE=file to use a 0600 file instead',
+      })
+    }
+  }
+
+  async delete(profile: string): Promise<void> {
+    // A missing record is the desired end state, so a non-zero status here is
+    // not a failure worth raising.
+    run(['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', accountFor(profile)])
+  }
+}
+
+function run(args: string[]): { status: number | null; stdout: string } | null {
+  try {
+    const res = spawnSync('security', args, { encoding: 'utf8' })
+    if (res.error) return null
+    return { status: res.status, stdout: res.stdout ?? '' }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A 0600 file beside the profile metadata.
+ *
+ * Present because the keychain does not exist in CI, in the Frontera Computer,
+ * or on Linux — the two places the CLI runs most often unattended. It is
+ * readable always and writable only on request, which is the line the design
+ * draws: a secret already on disk keeps working, and a NEW secret is never
+ * written in plaintext without the user having said so.
+ */
+export class FileStore implements CredentialStore {
+  readonly kind = 'file' as const
+
+  constructor(
+    private readonly env: Env,
+    private readonly writable: boolean,
+  ) {}
+
+  private path(): string {
+    return join(configDir(this.env), 'credentials.json')
+  }
+
+  /**
+   * Absent and unreadable are DIFFERENT answers.
+   *
+   * Swallowing every failure into `{}` reads as "no keys stored", and the next
+   * `set()` — an ordinary `auth add` — then rebuilds the map from that assumed
+   * emptiness and writes back a file containing only the new entry. Every other
+   * profile's key is gone, and these are last copies: `auth remove` says as much
+   * itself.
+   *
+   * A permission error from a file a `sudo` run left behind is enough to trigger
+   * it. So this raises, exactly as `profiles.ts` does for the metadata file —
+   * and the file holding the actual secrets has more reason to hold that line,
+   * not less.
+   */
+  private read(): Record<string, string> {
+    const path = this.path()
+    if (!existsSync(path)) return {}
+
+    let raw: string
+    try {
+      raw = readFileSync(path, 'utf8')
+    } catch (err) {
+      throw unreadable(path, (err as NodeJS.ErrnoException).code === 'EACCES' ? 'it is not readable' : 'it could not be read')
+    }
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw) as unknown
+    } catch {
+      throw unreadable(path, 'it is not valid JSON')
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw unreadable(path, 'it is not a JSON object')
+    }
+    return parsed as Record<string, string>
+  }
+
+  async get(profile: string): Promise<string | null> {
+    return this.read()[accountFor(profile)] ?? null
+  }
+
+  async set(profile: string, token: string): Promise<void> {
+    if (!this.writable) throw unavailable()
+    // Reads BEFORE deciding to write, so an unreadable store aborts here rather
+    // than silently becoming a one-entry file.
+    const current = this.read()
+    current[accountFor(profile)] = token
+    writeFileAtomic(this.path(), `${JSON.stringify(current, null, 2)}\n`, 0o600)
+  }
+
+  async delete(profile: string): Promise<void> {
+    const current = this.read()
+    if (!(accountFor(profile) in current)) return
+    delete current[accountFor(profile)]
+    writeFileAtomic(this.path(), `${JSON.stringify(current, null, 2)}\n`, 0o600)
+  }
+}
+
+function unreadable(path: string, why: string): CliError {
+  return new CliError(`the credential file at ${path} is unusable — ${why}`, {
+    code: 'SECURE_STORE_UNAVAILABLE',
+    hint:
+      `fix or move ${path} — every profile's key lives in it, and writing over it `
+      + 'from here would discard the ones that are still good',
+  })
+}
+
+function unavailable(): CliError {
+  return new CliError('no secure credential store is available on this platform', {
+    code: 'SECURE_STORE_UNAVAILABLE',
+    hint:
+      'export FRONTERA_TOKEN with FRONTERA_API_URL for this session, '
+      + 'or set FRONTERA_SECRET_STORE=file to accept a 0600 file on disk',
+  })
+}
+
+/**
+ * Read from every provider, write to the preferred one.
+ *
+ * Reads have to span providers because a machine can hold both: a key stored
+ * in the keychain today and one migrated into the file before the keychain
+ * existed. Writes must not, or "where is my key" becomes unanswerable.
+ */
+class ChainStore implements CredentialStore {
+  constructor(private readonly providers: CredentialStore[], private readonly writer: CredentialStore | null) {}
+
+  get kind(): CredentialSource {
+    return this.writer?.kind ?? 'file'
+  }
+
+  async get(profile: string): Promise<string | null> {
+    for (const provider of this.providers) {
+      const value = await provider.get(profile)
+      if (value) return value
+    }
+    return null
+  }
+
+  /** Which provider actually answered — reported as `credentialSource`. */
+  async locate(profile: string): Promise<{ token: string; source: CredentialSource } | null> {
+    for (const provider of this.providers) {
+      const value = await provider.get(profile)
+      if (value) return { token: value, source: provider.kind }
+    }
+    return null
+  }
+
+  async set(profile: string, token: string): Promise<void> {
+    if (!this.writer) throw unavailable()
+    await this.writer.set(profile, token)
+  }
+
+  async delete(profile: string): Promise<void> {
+    // Every provider, because a rotation may have left a stale copy behind in
+    // one of them and a half-deleted credential is the worst of both.
+    for (const provider of this.providers) await provider.delete(profile)
+  }
+}
+
+export interface StoreOptions {
+  /**
+   * Allow a plaintext file to be the WRITE target without the user opting in.
+   *
+   * Used by migration alone: the legacy config already held that key in
+   * plaintext, so relocating it is not a new disclosure — and refusing would
+   * strand the only copy of a working credential.
+   */
+  allowPlaintext?: boolean
+}
+
+/**
+ * The store this machine should use.
+ *
+ * `FRONTERA_SECRET_STORE` pins it (`keychain` or `file`); otherwise macOS gets
+ * the Keychain and everything else gets a readable-but-not-writable file, so
+ * an unsupported platform fails with a named remedy instead of quietly
+ * inventing a plaintext secret.
+ */
+export function credentialStore(env: Env = process.env, opts: StoreOptions = {}): ChainStore {
+  const pinned = env.FRONTERA_SECRET_STORE
+  const plaintextAllowed = opts.allowPlaintext === true || pinned === 'file'
+
+  const keychainUsable = pinned !== 'file' && (pinned === 'keychain' || process.platform === 'darwin')
+
+  const providers: CredentialStore[] = []
+  let writer: CredentialStore | null = null
+
+  if (keychainUsable) {
+    const keychain = new KeychainStore()
+    providers.push(keychain)
+    writer = keychain
+  }
+
+  const file = new FileStore(env, plaintextAllowed)
+  providers.push(file)
+  if (!writer && plaintextAllowed) writer = file
+
+  return new ChainStore(providers, writer)
+}
+
+export { ChainStore }

package/src/dev-env.ts

@@ -53,7 +53,7 @@ export interface DevEnvResult {
 interface DevEnvDeps {
   env?: NodeJS.ProcessEnv
   /** Seam: lets the no-credential path be exercised on a machine that has one. */
-  credential?: () => { apiUrl: string; token: string }
+  credential?: () => { apiUrl: string; token: string } | Promise<{ apiUrl: string; token: string }>
 }
 
 /**
@@ -64,13 +64,13 @@ interface DevEnvDeps {
  * and silently replacing a credential file is the kind of help nobody asks for
  * twice.
  */
-export function writeDevEnv(root: string, deps: DevEnvDeps = {}): DevEnvResult {
+export async function writeDevEnv(root: string, deps: DevEnvDeps = {}): Promise<DevEnvResult> {
   const path = join(root, DEV_ENV_FILE)
   if (existsSync(path)) return { written: false, reason: 'exists' }
 
   let credential: { apiUrl: string; token: string }
   try {
-    credential = (deps.credential ?? (() => resolveCredential({}, { env: deps.env })))()
+    credential = await (deps.credential ?? (() => resolveCredential({}, { env: deps.env, cwd: root })))()
   } catch {
     // No origin, no token, no keychain — the ordinary state before a login.
     return { written: false, reason: 'no-credential' }