@frontera-sdk/cli 0.1.0

package/src/main.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+import { parseArgs } from './args'
+import { resolveCredential } from './config'
+import { findProjectRoot } from './context'
+import { CliError, UsageError } from './errors'
+import { EXIT } from './exit'
+import { createOutput, type OutputMode } from './output'
+import { readProject } from './project'
+import {
+  aliasesFor,
+  describeCommand,
+  describeCommands,
+  findCommand,
+  flagsFor,
+  nouns,
+  renderCommandHelp,
+  renderHelp,
+  renderNounHelp,
+  unknownCommand,
+} from './commands/registry'
+import type { AppProject } from './context'
+
+/**
+ * The shell: parse, resolve context, dispatch, render, exit.
+ *
+ * It is deliberately the only place that knows about process streams and exit
+ * codes. Commands return data; `output` decides how it is shown and where it
+ * goes. That is what makes `--json` uniform across every command by
+ * construction rather than by each one remembering to branch.
+ */
+/**
+ * What `--version` reports.
+ *
+ * A released binary is stamped at build time with the tag it shipped from
+ * (`scripts/build-release.ts`), because that is the number a caller can
+ * actually act on: it names the platform release this client was built
+ * against, so a bug report says which server contract it expects. Running from
+ * source there is no tag, and the package version is the honest answer.
+ */
+async function resolveVersion(): Promise<string> {
+  const stamped = process.env.FRONTERA_CLI_VERSION
+  if (stamped) return stamped
+  const pkg = await import('../package.json', { with: { type: 'json' } })
+  return `${(pkg.default as { version: string }).version}-dev`
+}
+
+async function main(): Promise<number> {
+  const argv = process.argv.slice(2)
+
+  /**
+   * Help is available as DATA wherever it is available as text.
+   *
+   * `--help` is how a caller discovers the surface, and an agent discovering it
+   * had to parse aligned prose. Checked against raw argv because the help
+   * paths below run before any flag parsing — help has to work when the
+   * command is unknown, which is exactly when a caller needs it most.
+   */
+  const wantsJson = argv.includes('--json')
+  const emit = (data: unknown, text: () => string): number => {
+    process.stdout.write(wantsJson ? `${JSON.stringify(data, null, 2)}\n` : `${text()}\n`)
+    return EXIT.OK
+  }
+
+  // A leading global flag is not a command name. `frontera --api-url X` used
+  // to fail with "unknown command: --api-url", which reads as a typo rather
+  // than as a missing command — so flags are lifted out before the noun is
+  // read, and re-appended afterwards.
+  const leadingFlags: string[] = []
+  let cursor = 0
+  while (cursor < argv.length && argv[cursor]!.startsWith('--')) {
+    const flag = argv[cursor]!
+    if (flag === '--help' || flag === '--version') break
+    leadingFlags.push(flag)
+    cursor += 1
+    // A `--key value` pair moves together; `--key=value` is already one token.
+    if (!flag.includes('=') && cursor < argv.length && !argv[cursor]!.startsWith('--')) {
+      leadingFlags.push(argv[cursor]!)
+      cursor += 1
+    }
+  }
+
+  const remaining = argv.slice(cursor)
+
+  // Flags but no command. Showing help beats "unknown command: --api-url",
+  // which reads as a typo in the flag rather than as a missing command.
+  if (leadingFlags.length > 0 && remaining.length === 0) {
+    process.stderr.write('error [USAGE]: no command given\n')
+    process.stdout.write(`${renderHelp()}\n`)
+    return EXIT.USAGE
+  }
+
+  const [noun, maybeVerb, ...rest] = [...remaining, ...leadingFlags]
+
+  // Bare `frontera`, `help`, `--help`, `--version` before anything that could
+  // fail — help has to work with no credential and no project.
+  if (!noun || noun === 'help' || noun === '--help' || noun === '-h') {
+    return emit(describeCommands(), renderHelp)
+  }
+  if (noun === '--version' || noun === 'version') {
+    const version = await resolveVersion()
+    return emit({ version }, () => version)
+  }
+
+  // Nouns with no verb (`frontera init`) take their arguments directly.
+  const direct = findCommand(noun, '')
+  const command = direct ?? findCommand(noun, maybeVerb)
+
+  // `frontera agent --help`, or a bare `frontera agent`: list the noun's
+  // commands. Without this the CLI's own hints dead-ended, since a reserved
+  // verb tells the caller to run exactly this.
+  if (!command && nouns().includes(noun)) {
+    const askedForHelp =
+      maybeVerb === undefined ||
+      maybeVerb === '--help' ||
+      maybeVerb === '-h' ||
+      // `frontera app --json` is a help request too: the noun alone is not a
+      // command, so there is nothing else it could mean.
+      maybeVerb === '--json'
+    if (askedForHelp) {
+      return emit(describeCommands(noun), () => renderNounHelp(noun))
+    }
+  }
+
+  if (!command) throw unknownCommand(noun, maybeVerb)
+
+  const args = direct ? [maybeVerb, ...rest].filter((a): a is string => a !== undefined) : rest
+  const spec = flagsFor(command.meta)
+  const { positional, flags } = parseArgs(args, spec, aliasesFor(command.meta))
+
+  if (flags.help === true) {
+    return emit(describeCommand(command.meta), () => renderCommandHelp(command.meta))
+  }
+
+  const mode: OutputMode = flags.json === true ? 'json' : 'human'
+  const output = createOutput(mode, { quiet: flags.quiet === true })
+
+  try {
+    // Reserved commands fail BEFORE anything else — no credential is
+    // required to be told a verb does not exist yet.
+    if (command.meta.reserved) {
+      throw new CliError(command.meta.reserved, {
+        code: 'BAD_REQUEST',
+        hint: `run \`frontera ${command.meta.noun} --help\` to see what this noun supports today`,
+      })
+    }
+
+    const dirFlag = typeof flags.dir === 'string' ? flags.dir : undefined
+    const cwd = dirFlag ?? process.cwd()
+
+    let project: AppProject | null = null
+    if (command.meta.needsProject || command.meta.optionalProject) {
+      const root = findProjectRoot(cwd)
+      if (!root && command.meta.needsProject) {
+        throw new UsageError(
+          'not in a Frontera app directory',
+          'cd into an app project, or run `frontera app init <name>`',
+        )
+      }
+      if (root) project = { ...readProject(root), root }
+    }
+
+    // Offline commands scaffold before a credential exists, so resolving one
+    // would make `frontera init` impossible on a fresh machine.
+    const credential = command.meta.offline
+      ? { apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : (process.env.FRONTERA_API_URL ?? ''), token: '' }
+      : resolveCredential({ apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : undefined })
+
+    const result = await command.run({
+      cwd,
+      apiUrl: credential.apiUrl,
+      token: credential.token,
+      positional,
+      flags,
+      output,
+      project,
+    })
+
+    output.render(result.data, () => result.text)
+    return EXIT.OK
+  } catch (err) {
+    return output.fail(err)
+  }
+}
+
+main()
+  .then((code) => {
+    // `process.exitCode`, NOT `process.exit(code)`.
+    //
+    // stdout is a pipe when anything reads this — an agent, `jq`, a shell
+    // redirect — and writes to a pipe are asynchronous. `process.exit()` tears
+    // the process down before the buffer drains, so a large `--json` payload
+    // arrived TRUNCATED: valid-looking output that fails to parse partway
+    // through. Setting the code lets the runtime flush and exit on its own.
+    process.exitCode = code
+  })
+  .catch((err) => {
+    // Only reachable for a throw outside the try — argument parsing, or help
+    // rendering. Rendered as human text because the mode is not known yet.
+    const message = err instanceof Error ? err.message : String(err)
+    const code = err instanceof CliError ? err.code : 'INTERNAL_ERROR'
+    process.stderr.write(`error [${code}]: ${message}\n`)
+    if (err instanceof CliError && err.hint) process.stderr.write(`  ${err.hint}\n`)
+    process.exitCode = code === 'USAGE' ? EXIT.USAGE : EXIT.FAILURE
+  })

package/src/manifest.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { CliError } from './errors'
+import type { ProjectConfig } from './project'
+
+/**
+ * The version manifest — what the SERVER needs to know about a build that the
+ * bundle itself cannot tell it.
+ *
+ * Today that is one thing: which origins the app may reach, which becomes the
+ * `connect-src` and `img-src`/`font-src` of the CSP served with every asset.
+ * The design of record had a Vite plugin emit this at build time. Emitting it
+ * here instead means it also covers an app built by any other toolchain, and
+ * `connectDomains` reaches the CSP for every app rather than only scaffolded
+ * ones — which is the gap this closes.
+ *
+ * A build that DOES emit `dist/frontera.manifest.json` still wins, so a future
+ * plugin can add pages and an app-state schema without changing this.
+ */
+export interface AppManifest {
+  schemaVersion: 1
+  displayName: string
+  connectDomains: string[]
+  resourceDomains: string[]
+}
+
+/**
+ * A CSP source expression, conservatively.
+ *
+ * These strings are joined with spaces into a `Content-Security-Policy` header.
+ * A value carrying a `;` would close its directive and open a new one, so it is
+ * refused HERE with a message naming the offender rather than silently
+ * rewriting a header on the serving side. The server sanitises as well — this
+ * is the layer that can explain the problem.
+ */
+const CSP_SOURCE = /^(?:https?:\/\/)?(?:\*\.)?[a-z0-9][a-z0-9.-]*(?::\d+)?$/i
+
+function assertDomains(field: string, values: string[]): string[] {
+  for (const value of values) {
+    if (!CSP_SOURCE.test(value)) {
+      throw new CliError(`invalid ${field} entry: ${JSON.stringify(value)}`, {
+        code: 'VALIDATION_ERROR',
+        hint: 'use a host, optionally with a scheme, port or leading `*.` — e.g. https://api.example.com',
+      })
+    }
+  }
+  return values
+}
+
+export function buildManifest(project: ProjectConfig): AppManifest {
+  return {
+    schemaVersion: 1,
+    displayName: project.displayName,
+    connectDomains: assertDomains('connectDomains', project.connectDomains),
+    resourceDomains: assertDomains('resourceDomains', project.resourceDomains),
+  }
+}
+
+/**
+ * The manifest to publish with this build.
+ *
+ * Read from `dist/` when the build produced one; otherwise synthesised from
+ * `package.json`. A malformed `dist/frontera.manifest.json` is an error rather
+ * than a silent fallback: the build meant to say something, and quietly
+ * publishing different rules than the author declared is worse than refusing.
+ */
+export function resolveManifest(distDir: string, project: ProjectConfig): AppManifest {
+  const emitted = join(distDir, 'frontera.manifest.json')
+  if (!existsSync(emitted)) return buildManifest(project)
+
+  try {
+    return JSON.parse(readFileSync(emitted, 'utf8')) as AppManifest
+  } catch (err) {
+    throw new CliError(`dist/frontera.manifest.json is not valid JSON: ${(err as Error).message}`, {
+      code: 'VALIDATION_ERROR',
+      hint: 'delete it to fall back to the `frontera` key in package.json',
+    })
+  }
+}

package/src/output.ts

@@ -0,0 +1,65 @@
+import { exitCodeFor, toEnvelope, type ExitCode } from './exit'
+
+export type OutputMode = 'human' | 'json'
+
+export interface Streams {
+  out(chunk: string): void
+  err(chunk: string): void
+}
+
+export interface Output {
+  /** The command's data. The ONLY thing that ever reaches stdout. */
+  render(data: unknown, toText: (data: unknown) => string): void
+  /** Progress and warnings. Always stderr, so piping stays clean. */
+  note(message: string): void
+  /** Report a failure and return the exit code the shell should use. */
+  fail(err: unknown): ExitCode
+}
+
+const defaultStreams: Streams = {
+  out: (chunk) => process.stdout.write(chunk),
+  err: (chunk) => process.stderr.write(chunk),
+}
+
+/**
+ * The one module that writes to a stream.
+ *
+ * Commands return data; this decides how it is shown and where it goes. That
+ * split is what makes `--json` uniform by construction rather than by every
+ * command remembering to branch — and it is why nothing else in the CLI may
+ * call `console.*`.
+ *
+ * The contract a caller relies on: stdout carries data and nothing else, so
+ * exit 0 means stdout is parseable. On failure stdout stays EMPTY — a partial
+ * document followed by an error is worse than no document, because it parses.
+ */
+export function createOutput(
+  mode: OutputMode,
+  opts: { quiet?: boolean; streams?: Streams } = {},
+): Output {
+  const streams = opts.streams ?? defaultStreams
+  const quiet = opts.quiet ?? false
+
+  return {
+    render(data, toText) {
+      const text = mode === 'json' ? JSON.stringify(data, null, 2) : toText(data)
+      streams.out(`${text}\n`)
+    },
+
+    note(message) {
+      if (quiet) return
+      streams.err(`${message}\n`)
+    },
+
+    fail(err) {
+      const envelope = toEnvelope(err)
+      if (mode === 'json') {
+        streams.err(`${JSON.stringify(envelope, null, 2)}\n`)
+      } else {
+        streams.err(`error [${envelope.code}]: ${envelope.message}\n`)
+        if (envelope.hint) streams.err(`  ${envelope.hint}\n`)
+      }
+      return exitCodeFor(envelope.code)
+    },
+  }
+}

package/src/pack.ts

@@ -0,0 +1,18 @@
+import { collectSourceFiles, formatBytes } from './packaging'
+import { createTarGz } from './tar'
+import type { Output } from './output'
+
+/**
+ * Package a directory for upload, reporting its size.
+ *
+ * The count and size line is kept — it is how a stray 200MB asset directory
+ * becomes visible the moment it happens rather than months later as a storage
+ * bill — but it moves to stderr via `note`. It is commentary about the work,
+ * not the work's result, and mixing it into stdout broke piping.
+ */
+export function packDirectory(dir: string, output: Output, label: string) {
+  const files = collectSourceFiles(dir)
+  const totalBytes = files.reduce((n, f) => n + f.bytes.byteLength, 0)
+  output.note(`  ${label} ${files.length} files, ${formatBytes(totalBytes)}`)
+  return { tgz: createTarGz(files), fileCount: files.length, totalBytes }
+}

package/src/packaging.ts

@@ -0,0 +1,116 @@
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+/**
+ * Paths that are NEVER packaged, whatever any config says.
+ *
+ * `.env` is the reason this set is non-overridable rather than a default: an
+ * app project may hold an API key, and stored source is readable by anyone with
+ * `apps:deploy` — so a packaged `.env` leaks credentials to every deployer in
+ * the workspace. An author who *could* opt back in would eventually do so by
+ * accident, so the option does not exist.
+ *
+ * The rest is build output and noise: shipping it bloats every pull for no
+ * benefit, since `dist/` is rebuilt and `node_modules/` reinstalled from the
+ * lockfile.
+ */
+export const HARD_EXCLUDED = Object.freeze([
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  '.git',
+  'coverage',
+  '.turbo',
+  '.cache',
+  '.vscode',
+  '.idea',
+] as const)
+
+const HARD_EXCLUDED_SET = new Set<string>(HARD_EXCLUDED)
+
+/** Is this project-relative path excluded by the hard set? */
+export function isExcluded(rel: string): boolean {
+  const segments = rel.split('/')
+  for (const seg of segments) {
+    if (HARD_EXCLUDED_SET.has(seg)) return true
+    // `.env`, `.env.local`, `.env.production`, … at any depth.
+    if (seg === '.env' || seg.startsWith('.env.')) return true
+    if (seg === '.DS_Store') return true
+    if (seg.endsWith('.log')) return true
+  }
+  return false
+}
+
+/**
+ * Minimal `.gitignore` matcher.
+ *
+ * Deliberately simple — it handles the literal names and `dir/` and `*.ext`
+ * forms that cover real app projects. Negation (`!rule`) is parsed and then
+ * IGNORED for anything in the hard set, so a permissive `.gitignore` can never
+ * widen packaging past §6.2.
+ */
+function gitignoreMatcher(root: string): (rel: string) => boolean {
+  const path = join(root, '.gitignore')
+  if (!existsSync(path)) return () => false
+
+  const rules = readFileSync(path, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#') && !l.startsWith('!'))
+    .map((l) => l.replace(/\/$/, ''))
+
+  return (rel: string) => {
+    const segments = rel.split('/')
+    return rules.some((rule) => {
+      if (rule.startsWith('*.')) {
+        const ext = rule.slice(1)
+        return rel.endsWith(ext)
+      }
+      return segments.includes(rule) || rel === rule
+    })
+  }
+}
+
+export interface SourceFile {
+  /** Project-relative path, POSIX separators. */
+  rel: string
+  bytes: Uint8Array
+}
+
+/**
+ * Walk a project directory and collect what belongs in `src.tgz`.
+ *
+ * The hard set is applied first and unconditionally; `.gitignore` is applied on
+ * top of it, never instead of it.
+ */
+export function collectSourceFiles(root: string): SourceFile[] {
+  const ignored = gitignoreMatcher(root)
+  const out: SourceFile[] = []
+
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry)
+      const rel = relative(root, full).split(sep).join('/')
+      if (isExcluded(rel)) continue
+
+      const stat = statSync(full)
+      if (stat.isDirectory()) {
+        walk(full)
+        continue
+      }
+      if (ignored(rel)) continue
+      out.push({ rel, bytes: new Uint8Array(readFileSync(full)) })
+    }
+  }
+
+  walk(root)
+  return out
+}
+
+/** Human-readable size, for the count+size line printed on save and deploy. */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`
+  return `${(n / 1048576).toFixed(1)}MB`
+}

package/src/project.ts

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { execSync } from 'node:child_process'
+
+import { collectSourceFiles, isExcluded } from './packaging'
+
+export interface ProjectConfig {
+  /** The app's real identifier; null until the first ensure. */
+  appId: string | null
+  /** Bootstrap name for the first deploy only — the platform owns it after. */
+  slug: string
+  displayName: string
+  description?: string
+  /** Version the working tree was pulled from — feeds parentVersion. */
+  parentVersion?: string | null
+  /** Origins the app may reach at runtime; become the served CSP. */
+  connectDomains: string[]
+  resourceDomains: string[]
+}
+
+const STATE_FILE = '.frontera/state.json'
+
+/**
+ * Read app identity and runtime configuration.
+ *
+ * All of it lives in `package.json` under a `frontera` key — the same key that
+ * marks a directory as an app project. A separate `frontera.config.ts` was
+ * specified originally and is deliberately not used: it would force the CLI to
+ * evaluate TypeScript to learn a slug, and it would put an app's identity in
+ * two files that can disagree. JSON is also what an agent can patch safely.
+ */
+export function readProject(dir: string): ProjectConfig {
+  const pkgPath = join(dir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    throw new Error(`no package.json in ${dir} — is this a Frontera app project?`)
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {
+    name?: string
+    version?: string
+    frontera?: {
+      appId?: string
+      slug?: string
+      displayName?: string
+      description?: string
+      connectDomains?: unknown
+      resourceDomains?: unknown
+    }
+  }
+
+  // Bootstrap only: the name to CREATE the app under, on the one deploy where
+  // it does not exist yet. Never written back, because the platform owns the
+  // slug from that point on and can rename it — a committed copy would be
+  // stale the moment someone did, and would still look authoritative.
+  // `frontera.slug` is read for projects scaffolded before this changed.
+  const slug = pkg.frontera?.slug ?? pkg.name
+  if (!slug) throw new Error('package.json needs a "name"')
+
+  return {
+    // The real identifier. In package.json rather than `.frontera/state.json`
+    // because state is gitignored, so a colleague who clones the repo would
+    // otherwise have nothing durable — and would deploy to a new app.
+    appId: pkg.frontera?.appId ?? readState(dir).appId ?? null,
+    slug,
+    displayName: pkg.frontera?.displayName ?? slug,
+    description: pkg.frontera?.description,
+    parentVersion: readState(dir).parentVersion ?? null,
+    connectDomains: stringList(pkg.frontera?.connectDomains),
+    resourceDomains: stringList(pkg.frontera?.resourceDomains),
+  }
+}
+
+/** Tolerate a missing or malformed list rather than failing a whole read. */
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : []
+}
+
+/**
+ * Record the app's id in package.json, so it is committed alongside the code.
+ *
+ * Also DROPS any `frontera.slug`. Once the id is known the slug is dead weight
+ * — the platform owns it and can rename it, so a committed copy only survives
+ * to go stale and mislead the next person who reads the file.
+ *
+ * Idempotent: when nothing would change, the file is left untouched rather
+ * than rewritten, so this never shows up as a spurious diff.
+ */
+export function writeAppId(dir: string, appId: string): void {
+  const pkgPath = join(dir, 'package.json')
+  const raw = readFileSync(pkgPath, 'utf8')
+  const pkg = JSON.parse(raw) as { frontera?: Record<string, unknown> }
+  const frontera = pkg.frontera ?? {}
+  if (frontera.appId === appId && frontera.slug === undefined) return
+
+  const { slug: _dropped, ...rest } = frontera
+  pkg.frontera = { appId, ...rest }
+  const indent = /^\{\n(\s+)"/.exec(raw)?.[1]?.length ?? 2
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`)
+}
+
+export function readPackageVersion(dir: string): string {
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }
+  if (!pkg.version) throw new Error('package.json has no "version" — pass --version explicitly')
+  return pkg.version
+}
+
+interface ProjectState {
+  parentVersion?: string | null
+  appId?: string
+}
+
+export function readState(dir: string): ProjectState {
+  const p = join(dir, STATE_FILE)
+  if (!existsSync(p)) return {}
+  try {
+    return JSON.parse(readFileSync(p, 'utf8')) as ProjectState
+  } catch {
+    return {}
+  }
+}
+
+export function writeState(dir: string, patch: ProjectState): void {
+  const p = join(dir, STATE_FILE)
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, `${JSON.stringify({ ...readState(dir), ...patch }, null, 2)}\n`)
+}
+
+/**
+ * Files a pull would overwrite.
+ *
+ * `pull` unpacks over an existing tree, so proceeding past uncommitted work
+ * would destroy it — and inside a Computer sandbox there is often no git to
+ * recover from. When the project is a git repo we trust `git status`; otherwise
+ * any packageable file already present counts as dirty. Erring toward refusal
+ * costs one `--force` flag; erring the other way costs someone's afternoon.
+ */
+export function dirtyFiles(dir: string): string[] {
+  if (existsSync(join(dir, '.git'))) {
+    try {
+      const out = execSync('git status --porcelain', { cwd: dir, encoding: 'utf8' })
+      return out
+        .split('\n')
+        .map((l) => l.slice(3).trim())
+        .filter((l) => l && !isExcluded(l))
+    } catch {
+      // Fall through to the conservative check below.
+    }
+  }
+  return collectSourceFiles(dir)
+    .map((f) => f.rel)
+    .filter((f) => f !== 'package.json')
+}

package/src/prompt.ts

@@ -0,0 +1,48 @@
+import { createInterface } from 'node:readline'
+
+/**
+ * Ask for a secret, with the answer hidden.
+ *
+ * The CLI does not prompt — with one exception, and this is the guard that
+ * makes it safe: a prompt happens ONLY when stdin is an interactive TTY. An
+ * agent's stdin never is (it is a pipe or /dev/null), so an agent cannot hang
+ * here. Callers must still check `canPrompt()` first, so the decision is
+ * visible at the call site rather than buried.
+ *
+ * The answer is not echoed. A key pasted into a terminal would otherwise sit
+ * in scrollback, which is the same objection that keeps secrets out of flags.
+ */
+export function canPrompt(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+export function promptSecret(question: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const input = process.stdin
+    const output = process.stdout
+
+    const rl = createInterface({ input, output, terminal: true })
+    // `_writeToOutput` is readline's single seam for suppressing echo. Writing
+    // the prompt once and nothing after keeps the cursor where the user
+    // expects while their keystrokes stay off the screen.
+    let promptWritten = false
+    ;(rl as unknown as { _writeToOutput(s: string): void })._writeToOutput = (chunk: string) => {
+      if (!promptWritten) {
+        output.write(question)
+        promptWritten = true
+      }
+      // Preserve the newline when the user submits, so the next line is clean.
+      if (chunk.includes('\n')) output.write('\n')
+    }
+
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(answer.trim())
+    })
+    rl.on('SIGINT', () => {
+      rl.close()
+      output.write('\n')
+      reject(new Error('cancelled'))
+    })
+  })
+}