voroa-cli 0.0.0-stage → 0.2.0

package/src/commands/deploy.js

@@ -0,0 +1,104 @@
+// `voroa deploy <service> [--wait] [--timeout <minutes>]`
+//
+// THE EXIT CODE IS THE PRODUCT HERE. A CLI that a pipeline calls has to answer "did it work" with a
+// number, and two of the three answers are easy to get wrong:
+//
+//   0  the service is live
+//   1  the deploy failed, or built and then failed to start
+//   2  we ran out of time while it was still going
+//
+// 2 is deliberately NOT 0. A timeout means we stopped watching; it does not mean the deploy worked,
+// and a pipeline that treats it as success ships on a coin flip.
+//
+// The poller reads the honest `verdict` field and nothing else. It never looks at the raw build
+// status: 'live' there means the image built and the start job returned, which is precisely the lie
+// known bug #24 exists to record - two of three deploys once showed "Deploy failed" while the
+// container was healthy and serving, and earlier a container crash-looped for the better part of an
+// hour behind a green badge.
+import { redeploy, appStatus, ApiError, triggeredDeploymentUuid } from '../api.js';
+import { showBuildLog } from './logs.js';
+import { verdictOutcome, EXIT_TIMEOUT } from '../status.js';
+import { resolveService } from '../resolve.js';
+import { numberFlag } from '../flags.js';
+import { out } from '../output.js';
+import { CliError } from '../errors.js';
+
+const DEFAULT_TIMEOUT_MIN = 10;
+const POLL_MS = 5000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function deploy(ctx, { positionals, flags }) {
+  // VALIDATE BEFORE ANY SIDE EFFECT. `--timeout abc` used to be caught further down, after the
+  // deploy had already been triggered - so a typo in a flag about WAITING would still start a real
+  // deploy and then fail, which is worse than the silent default it replaced. A refusal has to come
+  // before the thing it might refuse. (Refuses rather than defaulting - see cli/src/flags.js.)
+  const minutes = numberFlag('--timeout', flags.timeout, { fallback: DEFAULT_TIMEOUT_MIN, min: 0 });
+
+  const app = await resolveService(ctx, positionals[0]);
+
+  const triggered = await redeploy(ctx, app.uuid);
+  out(`Deploy triggered for ${app.name}.`);
+
+  // --follow = the build log as it happens, then the same verdict wait as --wait (same exit codes).
+  // Only the uuid THIS trigger returned is followed: "the latest deploy" could be the previous one for
+  // a moment, and streaming someone the wrong build log is worse than streaming none.
+  // The deadline starts at the trigger and covers the log phase too, so --timeout means one thing.
+  const deadline = Date.now() + minutes * 60_000;
+
+  if (flags.follow) {
+    const deploymentUuid = triggeredDeploymentUuid(triggered);
+    if (deploymentUuid) {
+      // Ctrl-C while following ends the command - the deploy itself keeps running on the server.
+      if (await showBuildLog(ctx, app, deploymentUuid, { deadline })) {
+        out(`Stopped following. The deploy is still running - check \`voroa status ${app.name}\`.`);
+        return 0;
+      }
+    } else {
+      out('The build log is not available yet for this deploy - waiting for the outcome instead.');
+    }
+  }
+
+  if (!flags.wait && !flags.follow) {
+    out('Run `voroa status ' + app.name + '` to check on it, or add --wait next time.');
+    return 0;
+  }
+
+  out('Waiting for the deploy to finish...');
+
+  for (;;) {
+    // A read failure mid-wait is not a verdict - a network blip must not be reported as a failed
+    // deploy. But "we could not ask" and "it has not resolved yet" are DIFFERENT answers, and
+    // collapsing them is the mistake bug #39 records: swallowing an expired session here would spin
+    // out the full timeout and then report exit 2, telling a pipeline the deploy was still running
+    // when in fact we stopped being allowed to look. So a permanent refusal stops with its own
+    // sentence, and only the transient failures (network, 429, 5xx) keep the poll going.
+    let verdict = null;
+    try {
+      const st = await appStatus(ctx, app.uuid);
+      verdict = st ? st.verdict : null;
+    } catch (e) {
+      if (e instanceof ApiError && (e.httpStatus === 401 || e.httpStatus === 403 || e.httpStatus === 404)) {
+        throw new CliError(`${e.message} The deploy was triggered and is still running - check it from the dashboard.`);
+      }
+      verdict = null;
+    }
+
+    const outcome = verdictOutcome(verdict);
+    if (outcome.done) {
+      out(outcome.message);
+      return outcome.code;
+    }
+
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      out(`Timed out after ${minutes} minute${minutes === 1 ? '' : 's'}. The deploy has not finished.`);
+      out(`This is not a failure and not a success - check \`voroa status ${app.name}\`.`);
+      return EXIT_TIMEOUT;
+    }
+
+    // Never sleep past the deadline: a --timeout is a promise about when we stop, and overshooting
+    // it by a poll interval makes the number in the flag a lie.
+    await sleep(Math.min(POLL_MS, remaining));
+  }
+}

package/src/commands/domains.js

@@ -0,0 +1,122 @@
+// `voroa domains list|add|verify [service]`
+import { listDomains, addDomain, reprovisionDomain } from '../api.js';
+import { resolveService } from '../resolve.js';
+import { renderTable, out, json } from '../output.js';
+import { CliError } from '../errors.js';
+
+// verify: 0 live, 2 not live YET - distinct from 1 (a real error), so a script can wait on 2 only.
+const EXIT_NOT_LIVE = 2;
+
+function stateOf(d) {
+  // A pending wildcard routes nothing until its ownership record is checked (dashboard Verify).
+  if (d.ownership === 'pending') return 'waiting for ownership check';
+  if (d.serving) return 'serving';
+  if (d.routing === 'unrouted') return 'DNS ok, not serving yet';
+  return 'waiting for DNS';
+}
+
+// A domain's own edge state (ADR-0264), in the dashboard's words. White-label: "edge" only.
+const EDGE_LABEL = { protected: 'protected', switching: 'switching on', waiting_for_dns: 'ready - change DNS',
+  pending: 'preparing', leaving: 'off - change DNS back', off: 'off' };
+function edgeOf(d) {
+  return (d.edgeProtection && EDGE_LABEL[d.edgeProtection.state]) || '-';
+}
+
+function recordLine(r, suffix = '') {
+  // A record with no value (the service has no default address yet) would print a literal "null".
+  return r && r.value ? `  ${r.type}  ${r.name}  ${r.value}${suffix}` : null;
+}
+
+function dnsLines(d) {
+  if (!d.dns) return [];
+  // A wildcard needs TWO records (ownership + traffic) and both are required.
+  if (Array.isArray(d.dns)) {
+    const lines = d.dns.map((r) => recordLine(r)).filter(Boolean);
+    return lines.length ? lines : ['  The DNS records are not available yet - try again once the service has deployed.'];
+  }
+  // An apex domain gets an ALIAS as the record that never goes stale; the A record is for providers without one.
+  const lines = [recordLine(d.dns.alias, '   (preferred, if your DNS provider supports it)'), recordLine(d.dns)].filter(Boolean);
+  return lines.length ? lines : ['  The DNS record is not available yet - try again once the service has deployed.'];
+}
+
+export async function domains(ctx, { positionals, flags }) {
+  const sub = positionals[0];
+
+  if (!sub || sub === 'list') {
+    const app = await resolveService(ctx, positionals[1]);
+    const d = await listDomains(ctx, app.uuid);
+    if (flags.json) {
+      json({ service: app.name, ...d });
+      return 0;
+    }
+    if (d.defaultDomain) out(`Default: https://${d.defaultDomain}`);
+    if (!d.custom.length) out('No custom domains.');
+    // EDGE column only once any domain has an edge state (ADR-0264) - output is unchanged until then.
+    else if (d.custom.some((c) => c.edgeProtection)) {
+      out(renderTable(['DOMAIN', 'STATE', 'EDGE', 'ID'], d.custom.map((c) => [c.domain, stateOf(c), edgeOf(c), c.id])));
+    } else out(renderTable(['DOMAIN', 'STATE', 'ID'], d.custom.map((c) => [c.domain, stateOf(c), c.id])));
+    return 0;
+  }
+
+  if (sub === 'add') {
+    const name = positionals[1];
+    if (!name) throw new CliError('Which domain? `voroa domains add <domain> [service]`.');
+    const app = await resolveService(ctx, positionals[2]);
+    const added = await addDomain(ctx, app.uuid, name);
+    if (flags.json) {
+      json({ service: app.name, ...added });
+      return 0;
+    }
+    out(`Added ${added.domain} to ${app.name}. Create this DNS record at your DNS provider:`);
+    for (const l of dnsLines(added)) out(l);
+    out(`Then run \`voroa domains verify ${added.domain}\`. The certificate is issued automatically once DNS points here.`);
+    return 0;
+  }
+
+  if (sub === 'verify') {
+    const name = positionals[1];
+    if (!name) throw new CliError('Which domain? `voroa domains verify <domain> [service]`.');
+    const app = await resolveService(ctx, positionals[2]);
+    const d = await listDomains(ctx, app.uuid);
+    const row = d.custom.find((c) => c.domain.toLowerCase() === name.toLowerCase());
+    if (!row) throw new CliError(`${name} is not a custom domain on ${app.name}. Run \`voroa domains list\`.`);
+
+    // DNS already points here but nothing serves it: re-apply the routing and certificate, once, when
+    // asked. Otherwise this state never resolves on its own and verify would report it for ever.
+    let reprovisioned = false;
+    // A pending wildcard claim has no route to re-apply - its id is not a domain id - so --fix never
+    // touches it. Verifying ownership is a dashboard action.
+    if (row.ownership === 'pending') {
+      if (flags.json) {
+        json({ service: app.name, ...row, state: stateOf(row), reprovisioned });
+        return EXIT_NOT_LIVE;
+      }
+      out(`${row.domain}: ${stateOf(row)}`);
+      out('Create both records at your DNS provider, then press Verify next to the domain in your Voroa dashboard:');
+      for (const l of dnsLines(row)) out(l);
+      return EXIT_NOT_LIVE;
+    }
+    if (row.routing === 'unrouted' && flags.fix) {
+      await reprovisionDomain(ctx, app.uuid, row.id);
+      reprovisioned = true;
+    }
+    const code = row.serving ? 0 : EXIT_NOT_LIVE;
+    if (flags.json) {
+      json({ service: app.name, ...row, state: stateOf(row), reprovisioned });
+      return code;
+    }
+    out(`${row.domain}: ${stateOf(row)}`);
+    if (row.routing === 'dns_pending') {
+      out('DNS does not point here yet. The record to create:');
+      for (const l of dnsLines(row)) out(l);
+      out('DNS changes can take a while to spread. Run this again in a few minutes.');
+    } else if (reprovisioned) {
+      out('Routing and certificate re-applied, and the service redeploys. Run this again in a minute or two.');
+    } else if (row.routing === 'unrouted') {
+      out(`DNS is correct but the domain is not being served. Run \`voroa domains verify ${row.domain} --fix\` to re-apply it.`);
+    }
+    return code;
+  }
+
+  throw new CliError(`Unknown domains command "${sub}". Try \`voroa domains list\`, \`add <domain>\` or \`verify <domain>\`.`);
+}

package/src/commands/env.js

@@ -0,0 +1,143 @@
+// `voroa env list|set|unset [service]`
+//
+// GOLDEN RULE 4 SHAPES THIS WHOLE FILE. A stored value is encrypted and write-only: it can be
+// replaced, never read back - not by the dashboard, not by an API token, not by this CLI. So:
+//   * `list` shows NAMES. There is no value to show.
+//   * there is no `env pull`, and the help says why instead of leaving people to look for it.
+//   * `set` never takes the value from argv. A value on the command line lands in shell history and
+//     in the process list for every user on the box. It comes from stdin (CI) or a hidden prompt.
+//   * replacing an existing key needs --overwrite. Once replaced, the old value is gone for everyone.
+import fs from 'node:fs';
+import { listEnv, setEnv, deleteEnv, isApiToken } from '../api.js';
+import { resolveService } from '../resolve.js';
+import { askHidden } from '../prompt.js';
+import { renderTable, out, json } from '../output.js';
+import { CliError } from '../errors.js';
+
+export const ENV_HELP = `voroa env - environment variables for a service
+
+  voroa env list [service]                        variable names (values are never readable)
+  voroa env set <KEY> [service] [--overwrite]     value from stdin, or a hidden prompt
+            [--build-time]                        also available while the app builds
+  voroa env unset <KEY> [service]
+
+Setting or removing a variable redeploys the service.
+
+Values are write-only by design: they can be replaced, never displayed or downloaded.
+There is no \`env pull\`. Keep the source of truth for a value wherever you created it.
+
+  echo "$DATABASE_URL" | voroa env set DATABASE_URL --overwrite`;
+
+// The platform's own name rule (backend lib/envVars.js envEntryProblem) and no stricter - a stricter
+// one would make an existing, valid variable impossible to remove from here.
+function keyArg(raw) {
+  if (!raw) throw new CliError('Which variable? `voroa env set <KEY>`.');
+  if (raw.includes('=')) {
+    throw new CliError('Do not put the value on the command line - it would be saved in your shell history. Pipe it in: `echo "$VALUE" | voroa env set KEY`.');
+  }
+  if (/\s/.test(raw) || raw.startsWith('#')) throw new CliError('That is not a valid variable name: no spaces, and it cannot start with "#".');
+  return raw;
+}
+
+// The platform sets these itself and silently ignores a write to them (golden rule 7). Refused here so
+// the CLI never reports "Set PORT" for a change that did not happen.
+const RESERVED_KEYS = new Set(['PORT', 'NIXPACKS_NODE_VERSION']);
+
+// Piped or redirected -> stdin, minus ONE trailing newline that `echo` adds. A terminal -> a hidden
+// prompt, so the value is never echoed. Anything else (Git Bash's mintty reports "not a terminal"
+// while a person is typing; a CI runner can leave stdin open with no writer) would block for ever on a
+// read, so it is refused with the way forward instead.
+async function readValue(key) {
+  if (process.stdin.isTTY) return askHidden(`Value for ${key}: `, { timeoutMs: 5 * 60_000 });
+  let kind;
+  try {
+    const st = fs.fstatSync(0);
+    // Raw mode bits, not isFIFO(): on Windows a pipe reports mode S_IFIFO (0o010000) while isFIFO() is
+    // false (measured on Node 24).
+    const type = st.mode & 0o170000;
+    // A socket counts too: Node's child_process stdin pipe on Linux/macOS is a socketpair, and so is
+    // stdin under some CI runners - refusing it failed every piped value there (caught by Linux CI).
+    kind = type === 0o010000 || type === 0o140000 || st.isFile() ? 'readable' : 'other';
+  } catch {
+    kind = 'other';
+  }
+  if (kind !== 'readable') {
+    throw new CliError(`No value to read. Pipe it in: \`echo "$VALUE" | voroa env set ${key}\` (in Git Bash, run it through \`winpty\` to be prompted instead).`);
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(0, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'EOF') raw = ''; // Windows reports an empty pipe this way
+    else throw new CliError('Could not read the value from stdin.');
+  }
+  return raw.replace(/\r?\n$/, '');
+}
+
+export async function env(ctx, { positionals, flags }) {
+  const sub = positionals[0];
+
+  if (!sub || flags.help) {
+    out(ENV_HELP);
+    return sub ? 0 : 1;
+  }
+  if (sub === 'pull') {
+    throw new CliError('There is no `env pull`: stored values are write-only and cannot be read back. Run `voroa env --help`.');
+  }
+
+  if (sub === 'list') {
+    const app = await resolveService(ctx, positionals[1]);
+    const rows = await listEnv(ctx, app.uuid);
+    if (flags.json) {
+      json({ service: app.name, variables: rows.map((r) => ({ key: r.key, buildTime: r.buildTime, hasValue: true })) });
+      return 0;
+    }
+    if (!rows.length) {
+      out(`${app.name} has no environment variables.`);
+      return 0;
+    }
+    out(renderTable(['NAME', 'BUILD TIME'], rows.map((r) => [r.key, r.buildTime ? 'yes' : ''])));
+    return 0;
+  }
+
+  if (sub === 'set') {
+    const key = keyArg(positionals[1]);
+    if (RESERVED_KEYS.has(key)) throw new CliError(`${key} is set by the platform and cannot be changed.`);
+    const app = await resolveService(ctx, positionals[2]);
+    // Check-then-write: a key created by someone else between this read and the write below is replaced
+    // on a login session (the dashboard's route has no overwrite check). The API-token door does check,
+    // server-side. Accepted - the window is one round trip.
+    const existing = await listEnv(ctx, app.uuid);
+    const current = existing.find((r) => r.key === key);
+    if (current && current.platformManaged) throw new CliError(`${key} is managed by the platform and cannot be set here.`);
+    if (current && !flags.overwrite) {
+      throw new CliError(`${key} already has a value on ${app.name}. Replacing it discards the old value for good - add --overwrite if that is what you want.`);
+    }
+    const value = await readValue(key);
+    if (value === '') throw new CliError('No value given - nothing was changed.');
+    // The platform strips line breaks from a variable and still answers OK, so a multi-line value (a
+    // private key, pretty-printed JSON) would be stored mangled - and with --overwrite, the good one lost.
+    if (/[\r\n]/.test(value)) {
+      throw new CliError('That value spans more than one line, which an environment variable cannot hold. Store it as a secret file in the dashboard instead.');
+    }
+    await setEnv(ctx, app.uuid, [{ key, value, isBuildTime: !!flags.buildTime }], { overwrite: !!current });
+    if (flags.json) json({ service: app.name, key, replaced: !!current, redeployed: true });
+    else out(`${current ? 'Replaced' : 'Set'} ${key} on ${app.name}. A redeploy has started.`);
+    return 0;
+  }
+
+  if (sub === 'unset') {
+    const key = keyArg(positionals[1]);
+    // Removing a variable is not among what an API token may do.
+    if (isApiToken(ctx.token)) throw new CliError('An API token cannot remove variables. Sign in with `voroa login` to do that.');
+    const app = await resolveService(ctx, positionals[2]);
+    const row = (await listEnv(ctx, app.uuid)).find((r) => r.key === key);
+    if (!row) throw new CliError(`${app.name} has no variable called ${key}.`);
+    await deleteEnv(ctx, app.uuid, row.id);
+    if (flags.json) json({ service: app.name, key, removed: true });
+    else out(`Removed ${key} from ${app.name}.`);
+    return 0;
+  }
+
+  throw new CliError(`Unknown env command "${sub}". Run \`voroa env --help\`.`);
+}

package/src/commands/lifecycle.js

@@ -0,0 +1,40 @@
+// `voroa restart|stop|start [service]` and `voroa rollback [service] [--to <deploy id>]`
+import { lifecycle, rollback as rollbackCall, deployHistory } from '../api.js';
+import { resolveService } from '../resolve.js';
+import { out, json } from '../output.js';
+import { CliError } from '../errors.js';
+
+const DONE = { restart: 'Restarted', stop: 'Stopped', start: 'Started' };
+
+function action(name) {
+  return async function run(ctx, { positionals, flags }) {
+    const app = await resolveService(ctx, positionals[0]);
+    await lifecycle(ctx, app.uuid, name);
+    if (flags.json) json({ service: app.name, action: name, ok: true });
+    else out(`${DONE[name]} ${app.name}.`);
+    return 0;
+  };
+}
+
+export const restart = action('restart');
+export const stop = action('stop');
+export const start = action('start');
+
+export async function rollback(ctx, { positionals, flags }) {
+  const app = await resolveService(ctx, positionals[0]);
+  let target = null;
+  if (flags.to !== undefined) {
+    if (flags.to === true || !flags.to) throw new CliError('--to needs a deploy id. See `voroa logs <service> --build` or the dashboard.');
+    // Checked against this service's own history, so a typo is a sentence, not a server round-trip -
+    // the server still resolves the artifact from its own row either way.
+    const history = await deployHistory(ctx, app.uuid);
+    if (!history.some((d) => d.deploymentUuid === flags.to)) {
+      throw new CliError(`No deploy "${flags.to}" in ${app.name}'s history.`);
+    }
+    target = flags.to;
+  }
+  await rollbackCall(ctx, app.uuid, target);
+  if (flags.json) json({ service: app.name, rolledBackTo: target || 'previous', ok: true });
+  else out(`Rolling ${app.name} back to ${target ? `deploy ${target}` : 'the previous version'}. Check it with \`voroa status\`.`);
+  return 0;
+}

package/src/commands/link.js

@@ -0,0 +1,92 @@
+// `voroa link <service>` / `voroa unlink` / `voroa open [service]`
+import { spawn } from 'node:child_process';
+import { resolveService } from '../resolve.js';
+import { findLink, writeLink, removeLink, LINK_FILE } from '../link.js';
+import { DEFAULT_API_URL } from '../config.js';
+import { isApiToken } from '../api.js';
+import { out, json } from '../output.js';
+import { CliError } from '../errors.js';
+
+export async function link(ctx, { positionals, flags }) {
+  if (!positionals[0]) throw new CliError('Which service? `voroa link <service>` - run `voroa services` to see them.');
+  // Resolved through the server's scoped listing, so only a service the caller owns here can be linked.
+  const app = await resolveService(ctx, positionals[0], { useLink: false });
+  // A token carries no workspace of its own on the client, so nothing is recorded for it.
+  const workspaceId = isApiToken(ctx.token) ? null : ctx.workspaceId;
+  const file = writeLink({ serviceId: app.uuid, serviceName: app.name, workspaceId });
+  if (flags.json) {
+    json({ linked: true, serviceId: app.uuid, serviceName: app.name, file });
+  } else {
+    out(`Linked this folder to ${app.name}. Commands here no longer need a service name.`);
+    out(`${LINK_FILE} holds ids only - it is safe to commit.`);
+  }
+  return 0;
+}
+
+export async function unlink(ctx, { flags }) {
+  const file = removeLink();
+  if (flags.json) {
+    json({ unlinked: !!file });
+    return 0;
+  }
+  if (file) {
+    out('Unlinked this folder.');
+    return 0;
+  }
+  const above = findLink();
+  out(above ? `No ${LINK_FILE} in this folder. The link in effect is ${above.file} - run \`voroa unlink\` there.` : 'This folder is not linked.');
+  return 0;
+}
+
+const DEFAULT_DASHBOARD_URL = 'https://app.getvoroa.com';
+
+// The dashboard address is known only for the default API. For any other endpoint, guessing one
+// would send the user's browser to a host we made up - so it must be given.
+function dashboardUrl(ctx) {
+  const explicit = process.env.VOROA_DASHBOARD_URL;
+  if (explicit) {
+    let parsed;
+    try {
+      parsed = new URL(explicit);
+    } catch {
+      /* refused below */
+    }
+    if (!parsed || !['https:', 'http:'].includes(parsed.protocol)) {
+      throw new CliError('VOROA_DASHBOARD_URL must be an http(s) address.');
+    }
+    return explicit.replace(/\/+$/, '');
+  }
+  if (String(ctx.apiUrl).replace(/\/+$/, '').toLowerCase() === DEFAULT_API_URL) return DEFAULT_DASHBOARD_URL;
+  throw new CliError('The dashboard address for this API is not known. Set VOROA_DASHBOARD_URL.');
+}
+
+function launch(url) {
+  // NO SHELL on any platform. Windows uses the URL handler directly rather than `cmd /c start`: through
+  // cmd, an `&` in the URL (VOROA_DASHBOARD_URL is user-supplied) is a command separator.
+  const [cmd, args] =
+    process.platform === 'win32'
+      ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+      : process.platform === 'darwin'
+        ? ['open', [url]]
+        : ['xdg-open', [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {}); // no browser / headless box: the printed URL is the answer
+    child.unref();
+  } catch {
+    /* same */
+  }
+}
+
+export async function open(ctx, { positionals, flags }) {
+  const app = await resolveService(ctx, positionals[0]);
+  // The uuid is from the server's scoped listing and URL-encoded, so nothing a user typed reaches the shell.
+  const url = `${dashboardUrl(ctx)}/services/${encodeURIComponent(app.uuid)}`;
+  if (flags.json) {
+    json({ url });
+    return 0;
+  }
+  out(url);
+  if (!flags.print) launch(url);
+  return 0;
+}

package/src/commands/login.js

@@ -0,0 +1,104 @@
+// `voroa login` - email + a 6-digit code by default, email + password with --password.
+//
+// HONESTY ABOUT THROTTLING: the code-request endpoint is enumeration-safe. Whether the address has
+// an account, whether the send was throttled, whether mail delivery is even configured - it answers
+// the same generic 200 every time, on purpose. So the CLI cannot tell the user "sent" and be sure;
+// what it can do is say what a missing code most likely means, which is why the send limit is named
+// in the copy instead of leaving someone staring at an empty inbox blaming their spam filter.
+import { ask, askHidden, PromptTimeout } from '../prompt.js';
+import { otpAvailable, requestOtp, verifyOtp, passwordLogin, mfaVerify, ApiError } from '../api.js';
+import { saveSettings, readConfig } from '../config.js';
+import { out } from '../output.js';
+import { CliError } from '../errors.js';
+
+// The code lives for 10 minutes server-side. Waiting longer than half that is waiting for a code
+// that will have expired before it can be typed.
+const CODE_WAIT_MS = 5 * 60 * 1000;
+
+export async function login(ctx, { flags }) {
+  const email = (await ask('Email: ')).trim();
+  if (!email) throw new CliError('An email address is required.');
+
+  let session;
+  if (flags.password) {
+    const password = await askHidden('Password: ');
+    if (!password) throw new CliError('A password is required.');
+    session = await passwordLogin(ctx, email, password);
+  } else {
+    if (!(await otpAvailable(ctx))) {
+      throw new CliError('Sign-in codes are not available right now. Try `voroa login --password`.');
+    }
+    await requestOtp(ctx, email);
+    out(`We have asked Voroa to email a 6-digit code to ${email}. It expires in 10 minutes.`);
+    out('No code? Check the spam folder - or you may have hit the send limit, in which case wait a');
+    out('few minutes and try again.');
+    out('');
+
+    let code;
+    try {
+      code = await ask('Code: ', { timeoutMs: CODE_WAIT_MS });
+    } catch (e) {
+      if (e instanceof PromptTimeout) {
+        throw new CliError('Stopped waiting for the code. Run `voroa login` again when you have it.');
+      }
+      throw e;
+    }
+    if (!code) throw new CliError('A code is required.');
+    session = await verifyOtp(ctx, email, code);
+  }
+
+  // Two-step verification: the first step returned a CHALLENGE, not a session. Complete it with an
+  // authenticator or recovery code. A passkey needs a browser, so a passkey-only account is told that
+  // plainly rather than being sent round the loop again.
+  if (session && session.mfaRequired && session.challengeToken) {
+    const methods = Array.isArray(session.methods) ? session.methods : [];
+    const method = flags.recovery ? 'recovery' : methods.includes('totp') ? 'totp' : methods.includes('recovery') ? 'recovery' : null;
+    if (!method || !methods.includes(method)) {
+      if (flags.recovery && methods.includes('totp')) {
+        throw new CliError('Your account has no recovery codes left. Run `voroa login` without --recovery and use your authenticator app.');
+      }
+      throw new CliError(
+        methods.includes('recovery')
+          ? 'Your account confirms sign-in with a passkey, which a terminal cannot use. Run `voroa login --recovery` with a recovery code.'
+          : 'Your account confirms sign-in with a passkey, which a terminal cannot use. Sign in to the dashboard and create an API token for the CLI instead.'
+      );
+    }
+    const code = await askHidden(method === 'totp' ? 'Authenticator code: ' : 'Recovery code: ');
+    if (!code) throw new CliError('A code is required.');
+    try {
+      session = await mfaVerify(ctx, session.challengeToken, method, code);
+    } catch (e) {
+      // The generic 401 text says 'your session has expired' - wrong in the middle of signing in.
+      if (e instanceof ApiError && e.httpStatus === 401) throw new CliError('That code was not accepted, or sign-in took too long. Run `voroa login` again.');
+      if (e instanceof ApiError && e.httpStatus === 429) {
+        throw new CliError('Too many attempts with an authenticator code. Use a recovery code (`voroa login --recovery`), or try again later.');
+      }
+      throw e;
+    }
+  }
+
+  if (!session || !session.token) throw new CliError('Sign-in did not return a session. Try again.');
+
+  const who = (session.user && session.user.email) || email;
+
+  // Store the token and the endpoint it belongs to. A token is only valid against the API that
+  // issued it, so persisting them together stops a later `--api-url` change from silently sending
+  // this credential to a different host.
+  //
+  // AND drop the selected workspace when the account or the endpoint changes. A workspace id belongs
+  // to the account that could see it: keeping it across a login as somebody else sends a foreign id
+  // in X-Workspace-Id, and the server rightly answers 403 - an opaque one, because nothing in it
+  // says "the problem is a stale workspace from your last login". Clearing it falls back to the
+  // server's own default for the new account, which is always a valid answer.
+  const before = readConfig();
+  const sameAccount = before.email && before.email === who && before.apiUrl && before.apiUrl === ctx.apiUrl;
+  saveSettings({
+    apiUrl: ctx.apiUrl,
+    token: session.token,
+    email: who,
+    workspaceId: sameAccount ? before.workspaceId : undefined,
+  });
+  out(`Signed in as ${who}.`);
+  out('Run `voroa services` to see what is running, or `voroa workspace list` to switch workspace.');
+  return 0;
+}