@frontera-sdk/cli 1.44.1 → 1.45.1

package/src/profiles.ts

@@ -0,0 +1,240 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+
+import { configPath, type Env } from './paths'
+import { CliError, UsageError } from './errors'
+import { writeFileAtomic } from './fs-atomic'
+
+/**
+ * Named credential profiles.
+ *
+ * One machine, many customers. The previous shape stored one token per API
+ * origin, which made two keys for the SAME deployment impossible to hold at
+ * once — the second login overwrote the first, and an FDE moving between two
+ * workspaces on one Frontera install had no way to keep both. A profile is the
+ * name that separates them.
+ *
+ * This file owns METADATA only. Key bytes live in a credential store
+ * (`credential-store.ts`), addressed by profile name, so a profile file can be
+ * read, diffed and printed without ever holding a secret.
+ */
+
+export type CredentialKind = 'workspace' | 'organization'
+
+export interface ProfileMetadata {
+  apiUrl: string
+  credentialKind: CredentialKind
+  /**
+   * Nullable because organization-key verification answers neither field —
+   * `whoami` has no workspace to report for a key that belongs to none. Absent
+   * scope never makes an otherwise verified profile unusable; it is
+   * descriptive, and the service re-derives real scope on every request.
+   */
+  workspaceId: string | null
+  orgId: string | null
+  /** Short SHA-256 of the key, for recognition and diagnostics. Not the key. */
+  fingerprint: string
+  createdAt: string
+  lastVerifiedAt: string
+}
+
+export interface ProfileConfig {
+  schemaVersion: 2
+  profiles: Record<string, ProfileMetadata>
+}
+
+/** The shape written before profiles existed. Read for migration, never written. */
+export interface LegacyConfig {
+  defaultOrigin?: string
+  origins?: Record<string, { token?: string }>
+}
+
+export const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+
+/**
+ * Reserved so a future resolver can add them without breaking a machine that
+ * already has a profile by that name. `none` and `auto` are the two words a
+ * `--profile` flag would plausibly grow a meaning for; a path-like value is
+ * reserved because `--profile ./x` should never become a file reference by
+ * accident.
+ */
+const RESERVED_NAMES = new Set(['none', 'auto'])
+
+export function assertProfileName(name: string): void {
+  if (RESERVED_NAMES.has(name.toLowerCase())) {
+    throw new CliError(`"${name}" is a reserved profile name`, {
+      code: 'PROFILE_INVALID',
+      hint: 'pick another name — `none` and `auto` are reserved for future selectors',
+    })
+  }
+  if (name.includes('/') || name.includes('\\')) {
+    throw new CliError(`"${name}" looks like a path, not a profile name`, {
+      code: 'PROFILE_INVALID',
+      hint: 'profile names are plain identifiers, e.g. acme-prod',
+    })
+  }
+  if (!PROFILE_NAME_PATTERN.test(name)) {
+    throw new CliError(`"${name}" is not a valid profile name`, {
+      code: 'PROFILE_INVALID',
+      hint: 'use letters, digits, dot, dash or underscore, starting with a letter or digit (max 64)',
+    })
+  }
+}
+
+/**
+ * A recognisable stand-in for the key.
+ *
+ * Twelve hex characters is enough to tell two keys apart by eye when
+ * `auth list` prints them side by side, and far too little to attack the key
+ * it came from. It exists so a person can answer "is this the key I rotated?"
+ * without the CLI ever printing one.
+ */
+export function fingerprint(token: string): string {
+  return `sha256:${createHash('sha256').update(token).digest('hex').slice(0, 12)}`
+}
+
+function readRaw(env: Env): unknown {
+  const path = configPath(env)
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as unknown
+  } catch {
+    // Deliberately NOT silent. The old reader treated a corrupt config as
+    // absent, which turned "your profiles are unreadable" into "you have no
+    // credential" — a true statement about a completely different problem.
+    throw new CliError(`the Frontera configuration at ${path} is not readable JSON`, {
+      code: 'PROFILE_INVALID',
+      hint: `inspect ${path}, or move it aside and re-add your profiles with \`frontera auth add\``,
+    })
+  }
+}
+
+export function isLegacyConfig(raw: unknown): raw is LegacyConfig {
+  if (!raw || typeof raw !== 'object') return false
+  const rec = raw as Record<string, unknown>
+  if (rec.schemaVersion === 2) return false
+  return 'origins' in rec || 'defaultOrigin' in rec
+}
+
+/**
+ * Profiles as stored, with no migration and no derivation.
+ *
+ * A caller that needs legacy credentials to be visible calls
+ * `migrateLegacyConfig` first — separated so that reading is a pure operation
+ * and the one place that rewrites a user's credentials is explicit.
+ */
+export function readProfileConfig(env: Env = process.env): ProfileConfig {
+  const raw = readRaw(env)
+  if (!raw || typeof raw !== 'object') return { schemaVersion: 2, profiles: {} }
+  const rec = raw as Record<string, unknown>
+  if (rec.schemaVersion !== 2) return { schemaVersion: 2, profiles: {} }
+  const profiles = (rec.profiles ?? {}) as Record<string, ProfileMetadata>
+  return { schemaVersion: 2, profiles }
+}
+
+export function readLegacyConfig(env: Env = process.env): LegacyConfig | null {
+  const raw = readRaw(env)
+  return isLegacyConfig(raw) ? raw : null
+}
+
+export function writeProfileConfig(config: ProfileConfig, env: Env = process.env): void {
+  writeFileAtomic(configPath(env), `${JSON.stringify(config, null, 2)}\n`, 0o600)
+}
+
+export function listProfiles(env: Env = process.env): Array<{ name: string; profile: ProfileMetadata }> {
+  const { profiles } = readProfileConfig(env)
+  return Object.entries(profiles)
+    .map(([name, profile]) => ({ name, profile }))
+    .sort((a, b) => a.name.localeCompare(b.name))
+}
+
+export function getProfile(name: string, env: Env = process.env): ProfileMetadata | null {
+  return readProfileConfig(env).profiles[name] ?? null
+}
+
+export function requireProfile(name: string, env: Env = process.env): ProfileMetadata {
+  const profile = getProfile(name, env)
+  if (!profile) {
+    const known = listProfiles(env).map((p) => p.name)
+    throw new CliError(`no profile named "${name}"`, {
+      code: 'PROFILE_NOT_FOUND',
+      hint: known.length
+        ? `known profiles: ${known.join(', ')} — or add one with \`frontera auth add ${name} --api-url <origin>\``
+        : `add one with \`frontera auth add ${name} --api-url <origin>\``,
+    })
+  }
+  return profile
+}
+
+export function putProfile(name: string, profile: ProfileMetadata, env: Env = process.env): void {
+  const config = readProfileConfig(env)
+  config.profiles[name] = profile
+  writeProfileConfig(config, env)
+}
+
+export function deleteProfile(name: string, env: Env = process.env): void {
+  const config = readProfileConfig(env)
+  delete config.profiles[name]
+  writeProfileConfig(config, env)
+}
+
+/**
+ * A key is only meaningful at the deployment that issued it, so an explicit
+ * origin that disagrees with the profile's is a mistake worth catching BEFORE
+ * a request — sending a customer's key to another customer's deployment is not
+ * something to discover from a 401.
+ */
+export function assertOriginMatches(name: string, stored: string, supplied: string): void {
+  if (normalizeOrigin(stored) === normalizeOrigin(supplied)) return
+  throw new CliError(
+    `profile "${name}" belongs to ${stored}, not ${supplied}`,
+    {
+      code: 'PROFILE_ORIGIN_MISMATCH',
+      hint: `drop --api-url to use ${stored}, or add a separate profile for ${supplied}`,
+    },
+  )
+}
+
+/** Trailing slashes and case in the host are not a different deployment. */
+export function normalizeOrigin(origin: string): string {
+  try {
+    const url = new URL(origin)
+    return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, '')}`
+  } catch {
+    return origin.replace(/\/+$/, '')
+  }
+}
+
+export function assertApiUrl(origin: string): void {
+  try {
+    const url = new URL(origin)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('scheme')
+  } catch {
+    throw new UsageError(
+      `"${origin}" is not an API origin`,
+      'pass a full origin, e.g. --api-url https://api.frontera.example',
+    )
+  }
+}
+
+/**
+ * A stable, readable profile name for a legacy origin.
+ *
+ * Derived from the host so a migrated machine gets `api-frontera-example`
+ * rather than `origin-2`, which nobody could match back to a customer.
+ */
+export function nameFromOrigin(origin: string, taken: Set<string>): string {
+  let base: string
+  try {
+    base = new URL(origin).host.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  } catch {
+    base = origin.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  }
+  if (!base || !PROFILE_NAME_PATTERN.test(base)) base = 'imported'
+  base = base.slice(0, 56)
+  if (!taken.has(base)) return base
+  for (let n = 2; ; n += 1) {
+    const candidate = `${base}-${n}`
+    if (!taken.has(candidate)) return candidate
+  }
+}

package/src/project-context.ts

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import { isTrustedBinding, recordBinding } from './binding-registry'
+import { findProjectRoot } from './context'
+import { CliError } from './errors'
+import { writeFileAtomic } from './fs-atomic'
+import type { Env } from './paths'
+
+/**
+ * The working directory selects the profile.
+ *
+ * The rejected alternative was a machine-wide "current customer" that
+ * `frontera auth use` mutated. It is one line to implement and it silently
+ * misroutes the next command run in a different repository — which, for an FDE
+ * holding two customers open in two terminals, is the exact failure the whole
+ * design exists to prevent. Binding lives in the directory instead, and the
+ * NEAREST binding wins, so a nested project may safely override its parent.
+ *
+ * The file holds a profile NAME. Never a token, never an origin — the origin
+ * belongs to the profile, so a repository cannot redirect a key to another
+ * deployment by editing a checked-out file.
+ */
+
+export const CONTEXT_DIR = '.frontera'
+export const CONTEXT_FILE = 'context.json'
+
+export interface ProjectContext {
+  schemaVersion: 1
+  profile: string
+}
+
+export interface FoundContext {
+  profile: string
+  /** Absolute path of the `context.json` that supplied it. */
+  path: string
+  /** The directory that owns it — the binding root. */
+  root: string
+  /**
+   * Did THIS machine bind this root to this profile?
+   *
+   * A context file can be committed to a repository, and the upward walk cannot
+   * tell who wrote it. Reported rather than enforced here, so listings can show
+   * a binding while the resolver refuses to act on one nobody here made.
+   */
+  trusted: boolean
+}
+
+export function contextPath(root: string): string {
+  return join(root, CONTEXT_DIR, CONTEXT_FILE)
+}
+
+function readContextAt(root: string, env: Env): FoundContext | null {
+  const path = contextPath(root)
+  if (!existsSync(path)) return null
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+  } catch {
+    throw corrupt(path, 'it is not readable JSON')
+  }
+
+  const profile = (parsed as { profile?: unknown } | null)?.profile
+  if (typeof profile !== 'string' || profile.length === 0) {
+    throw corrupt(path, 'it names no profile')
+  }
+  return { profile, path, root, trusted: isTrustedBinding(root, profile, env) }
+}
+
+/**
+ * Corrupt context is an ERROR, not a miss.
+ *
+ * Falling through to the parent directory would silently run a customer's
+ * command against a different customer's profile — the one outcome this design
+ * treats as unacceptable. Better to stop and name the file.
+ */
+function corrupt(path: string, why: string): CliError {
+  return new CliError(`the profile context at ${path} is unusable — ${why}`, {
+    code: 'PROJECT_CONTEXT_CORRUPT',
+    hint: `delete ${path} and run \`frontera auth use <profile>\` again`,
+  })
+}
+
+/** Nearest wins: walk up from `from` to the filesystem root. */
+export function findContext(from: string, env: Env = process.env): FoundContext | null {
+  let dir = resolve(from)
+  for (;;) {
+    const found = readContextAt(dir, env)
+    if (found) return found
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function findGitRoot(from: string): string | null {
+  let dir = resolve(from)
+  for (;;) {
+    // A file, not only a directory: a worktree and a submodule both write
+    // `.git` as a file pointing elsewhere, and both are real repository roots.
+    if (existsSync(join(dir, '.git'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+export type BindingRootSource = 'flag' | 'project' | 'git' | 'cwd'
+
+/**
+ * Where `auth use` writes.
+ *
+ * `--dir` binds that exact directory and searches no further, matching how
+ * `--dir` already behaves for App projects. Otherwise the nearest Frontera
+ * project root, then the Git root, then the working directory — so the command
+ * needs no initialization of any kind and still lands somewhere a whole
+ * customer tree inherits from.
+ */
+export function resolveBindingRoot(
+  cwd: string,
+  dirFlag?: string,
+): { root: string; source: BindingRootSource } {
+  if (dirFlag) return { root: resolve(dirFlag), source: 'flag' }
+  const project = findProjectRoot(cwd)
+  if (project) return { root: project, source: 'project' }
+  const git = findGitRoot(cwd)
+  if (git) return { root: git, source: 'git' }
+  return { root: resolve(cwd), source: 'cwd' }
+}
+
+/**
+ * Write the selection AND record that this machine made it.
+ *
+ * One function rather than two, because a context written without its binding
+ * is a selection the resolver will refuse — a failure mode nobody would connect
+ * to having called only half of the pair.
+ */
+export function writeContext(root: string, profile: string, env: Env = process.env): string {
+  const path = contextPath(root)
+  const body: ProjectContext = { schemaVersion: 1, profile }
+  writeFileAtomic(path, `${JSON.stringify(body, null, 2)}\n`, 0o600)
+  recordBinding(root, profile, env)
+  return path
+}
+
+/**
+ * Add `.frontera/` to the root's `.gitignore` without touching anything else.
+ *
+ * Appended, never rewritten. A `.gitignore` is a file the team owns; replacing
+ * it to add one line is the kind of help that gets a tool removed from a repo.
+ * The name is gitignored even though it holds no secret, because a profile name
+ * can reveal a customer or an environment, and it is personal machine
+ * configuration rather than a property of the code.
+ */
+export function ensureGitignored(root: string): 'added' | 'present' | 'created' {
+  const path = join(root, '.gitignore')
+  const entry = `${CONTEXT_DIR}/`
+
+  if (!existsSync(path)) {
+    writeFileAtomic(path, `# Frontera profile selection — personal, not shared\n${entry}\n`, 0o644)
+    return 'created'
+  }
+
+  const current = readFileSync(path, 'utf8')
+  const lines = current.split('\n').map((l) => l.trim())
+  if (lines.includes(entry) || lines.includes(CONTEXT_DIR) || lines.includes(`/${entry}`)) return 'present'
+
+  const separator = current.endsWith('\n') ? '' : '\n'
+  writeFileAtomic(
+    path,
+    `${current}${separator}\n# Frontera profile selection — personal, not shared\n${entry}\n`,
+    // The file's own mode, not ours. An atomic write replaces the inode, so a
+    // fixed mode here would quietly re-permission a file the team owns.
+    statSync(path).mode & 0o777,
+  )
+  return 'added'
+}

package/src/prompt.ts

@@ -46,3 +46,26 @@ export function promptSecret(question: string): Promise<string> {
     })
   })
 }
+
+/**
+ * A yes/no question, asked only on an interactive terminal.
+ *
+ * Same guard as `promptSecret`: an agent's stdin is a pipe or /dev/null, so it
+ * never reaches this and never hangs. Callers check `canPrompt()` first and
+ * raise a usage error naming the explicit flag instead — which is why every
+ * confirmation in this CLI has a flag form.
+ */
+export function promptConfirm(question: string): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close()
+      resolve(/^y(es)?$/i.test(answer.trim()))
+    })
+    rl.on('SIGINT', () => {
+      rl.close()
+      process.stdout.write('\n')
+      reject(new Error('cancelled'))
+    })
+  })
+}

package/src/templates/next-app-files.ts

@@ -979,7 +979,10 @@ thing that proves the static export still works. For anything touching data,
 also run it against real data with \`frontera app dev\`.
 `,
 
-    'CLAUDE.md': `./AGENTS.md
+    // `@AGENTS.md`, not `./AGENTS.md`. The latter is a relative path Claude
+    // Code does not import — it reads as prose, so the project contract
+    // silently never loads.
+    'CLAUDE.md': `@AGENTS.md
 `,
 
     'README.md': `# ${name}