voroa-cli 0.0.0-stage → 0.2.0

package/src/status.js

@@ -0,0 +1,178 @@
+// Status classify - the CLI's copy of the SPA's status vocabulary.
+//
+// WHY A COPY AND NOT AN IMPORT: `frontend/src/status.js` is a Vite/ESM module inside the SPA's
+// package; this package ships with zero dependencies and is installed on its own. It cannot reach
+// across into the frontend tree at runtime. So the two `classify` / `statusLabel` bodies below are
+// a DELIBERATE, PINNED duplicate - the same arrangement `shared/planGate.mjs` has with
+// `frontend/src/lib/planGate.js`.
+//
+// PINNED REGION - `classify` and `statusLabel` are byte-identical to the SPA's, and
+// `backend/tests/cliStatusParity.test.js` fails CI the moment one side drifts from the other. It
+// pins them two ways: the extracted function bodies must match character for character, AND both
+// implementations must answer an adversarial case table identically. If you change a status label,
+// change it in `frontend/src/status.js` and copy it here in the SAME commit.
+//
+// The SPA's other exports (`isStoppedStatus`, `serviceBucket`, `parseDomains`, `primaryDomain`) are
+// deliberately NOT copied - the CLI has no tab filter and no domain chip row, and an unused copy is
+// a copy that drifts unnoticed.
+//
+// Anything outside this file that decides a state from a raw status or verdict token is a rule #10
+// violation and is caught by the deny-list in the same test. Import from here.
+
+// Platform raw status "state:health" format me deta hai (e.g. "running:healthy",
+// "running:unknown", "exited:unhealthy"). Raw string user ko dikhana confusing hai
+// (jaise "running:unknown" -> lagta hai kuch galat hai, jabki app theek chal raha).
+// Isliye saaf human label + rang me map karte hain.
+//
+// deploymentStatus (backend se) agar 'queued'/'in_progress' hai to build chal raha hai -
+// container ka transient status (jaise "exited:unhealthy") galat hota hai, isliye usko
+// override karke "Deploying..." dikhate hain.
+export function classify(status, deploymentStatus, verdict) {
+  if (deploymentStatus === 'in_progress' || deploymentStatus === 'queued') {
+    return { label: 'Deploying…', tone: 'amber', live: true };
+  }
+
+  // Honest Deploy Verdict (build finish ke baad ka runtime gate). CONTRACT-AGNOSTIC by design: verdict
+  // chahe alag `verdict` field me aaye ya EXISTING `status` field me overlay ho - dono handle. `v` =
+  // verdict (agar diya) warna status; extended enum building|live|failed|starting|failed_to_start.
+  // 'starting'/'failed_to_start'/'failed' ko explicit map karo, state:health split se PEHLE.
+  // Render-style: runtime-fail (build theek par app up nahi hua) = "Failed" (subject = deploy);
+  // build-stage fail = "Build failed". Dono distinct, warna dono includes('fail') -> generic "Failed".
+  const v = verdict || status;
+  // Idle-sleep (ADR-0010): ek SLEEPABLE free app idle par so gaya (backend `verdict:'sleeping'` bhejta jab
+  // apps.slept_at set). NEUTRAL "Sleeping" - crash/fail NAHI (red nahi). Agle request par khud jaag jaata.
+  if (v === 'sleeping') return { label: 'Sleeping', tone: 'gray', live: true };
+  // Crash-loop suspend (ADR-0124): humne rok di kyunki wo baar-baar mar rahi thi. Ye 'failed_to_start'
+  // (laal) se alag hai aur 'sleeping' (gray, khud jaag jaata) se bhi - isliye AMBER: kuch toota nahi hai
+  // is waqt, par jab tak customer khud start nahi karta tab tak kuch chalega bhi nahi. Ek hi laal badge me
+  // "aapka app crash hua" aur "humne aapka app rok diya" ko mila dena customer se agla kadam chhupa deta.
+  if (v === 'suspended') return { label: 'Stopped by Voroa', tone: 'amber' };
+  if (v === 'paused_free_hours') return { label: 'Paused: free hours used', tone: 'amber' };
+  // ADR-0314 zero setup: service ka pehla deploy uske add-on database ka intezaar kar raha hai. Amber -
+  // kuch toota nahi, ek kadam baaki hai (payment ya database ka banna); service page par do button.
+  if (v === 'waiting_for_addon') return { label: 'Waiting for database', tone: 'amber' };
+  // `unknown` (ADR-0243) - EXPLICIT, not a fallthrough. The deploy is past every deadline and the
+  // container that could have answered is gone, so we cannot say whether the service came up. It looks
+  // the same as the catch-all below and must not BE the catch-all: `status.test.js` forbids any backend
+  // verdict reaching that line, because a verdict nobody wrote a branch for renders as an unexplained
+  // grey badge. This one is explained - grey and honest, not amber (nothing is pending) and not red
+  // (nothing is wrong). A container status, when we have one, still wins over it below.
+  if (v === 'unknown') return { label: 'Unknown', tone: 'gray' };
+  if (v === 'starting') return { label: 'Starting…', tone: 'amber', live: true };
+  if (v === 'failed_to_start') return { label: 'Failed', tone: 'red' };
+  if (v === 'failed') return { label: 'Build failed', tone: 'red' };
+
+  // Koi container status hai hi nahi. Ye NORMAL hai: platform ka apna runtime read fail ho sakta
+  // hai (ya container abhi swap ho raha ho) aur tab status null aata hai - wo best-effort hai.
+  // `verdict` ek ALAG axis pe banta hai, isliye wo abhi bhi sach hota hai - use padho, "Unknown"
+  // mat bolo. (Wording yahan jaan-boojh ke SPA se alag hai: ye file customer ki disk pe as-is
+  // install hoti hai, to yahan platform ke substrate ka naam nahi jaa sakta - golden rule 6.)
+  // NOTE: ye branch SIRF tab chalti hai jab status missing ho. Ek MAUJOOD status hamesha jeetta hai
+  // (neeche state:health parse) - warna verdict:'live' ek 'restarting:unhealthy' container ko green
+  // "Running" bana deta aur bug #30 ki poori honesty ulti ho jaati.
+  if (!status) {
+    if (v === 'live') return { label: 'Running', tone: 'green' };
+    if (v === 'building') return { label: 'Deploying…', tone: 'amber', live: true };
+    return { label: 'Unknown', tone: 'gray' };
+  }
+
+  // trim() bhi (backend lib/runtimeState.js jaisa) - engine spacing me consistent nahi hai, aur ek
+  // untrimmed ' unhealthy ' crash-loop branch ko chupchaap miss kar deta tha (parity guard ne pakda).
+  const [stateRaw, healthRaw] = String(status).split(':');
+  const state = (stateRaw || '').trim().toLowerCase();
+  const health = (healthRaw || '').trim().toLowerCase();
+
+  if (state.includes('running')) {
+    // "unknown"/missing health ka matlab sirf health-check off hai - app chal raha hai.
+    if (health === 'unhealthy') return { label: 'Unhealthy', tone: 'amber' };
+    return { label: 'Running', tone: 'green' };
+  }
+  if (state.includes('start') || state.includes('restart')) {
+    // Crash-loop honestly (bug #30): ek container jo BAAR-BAAR restart ho raha hai wo "Starting…" nahi
+    // hai - wo gir raha hai. Backend ise `restarting:unhealthy` bhejta hai (native container ka apna
+    // healthcheck FAIL, ya restart-flap detect hua). Sirf tab red - `restarting:unknown` (ek transient
+    // restart, health-check off) pehle jaisa "Starting…" hi rehta hai.
+    if (state.includes('restart') && health === 'unhealthy') {
+      return { label: 'Crash looping', tone: 'red' };
+    }
+    return { label: 'Starting…', tone: 'amber', live: true };
+  }
+  if (state.includes('build') || state.includes('deploy') || state.includes('queue')) {
+    return { label: 'Deploying…', tone: 'amber', live: true };
+  }
+  if (state.includes('degraded')) {
+    return { label: 'Degraded', tone: 'red' };
+  }
+  if (state.includes('error') || state.includes('fail')) {
+    return { label: 'Failed', tone: 'red' };
+  }
+  if (state.includes('exit') || state.includes('stop') || state.includes('dead')) {
+    return { label: 'Stopped', tone: 'gray' };
+  }
+  // Anjaan state - raw dikha do par clean
+  return { label: stateRaw || 'Unknown', tone: 'gray' };
+}
+
+// Pure label mapper (bug #3) - raw "state:health" (e.g. "running:unknown") ko kabhi user ko
+// NAHI dikhate; hamesha saaf label. classify() pe delegate karta hai (single source of truth),
+// sirf string label deta hai. Regression test isi ko pin karta hai.
+export function statusLabel(status, deploymentStatus) {
+  return classify(status, deploymentStatus).label;
+}
+
+// ---------------------------------------------------------------------------------------------
+// END OF THE PINNED REGION. Everything below is CLI-only and has no counterpart in the SPA - the
+// parity test extracts the two functions above by name, so additions here never affect it.
+// ---------------------------------------------------------------------------------------------
+
+// Verdict -> process exit code. This is the CLI's published contract (README "Exit codes") and it
+// lives here, next to the vocabulary it reads, so no command file ever compares a verdict token
+// itself.
+//
+// The input is ALWAYS the honest `verdict` field, NEVER the raw build `status` (bug #24: `status`
+// stays the raw build state - 'live' there means "the image built and the start job returned", which
+// is exactly the lie the verdict field was added to stop telling).
+//
+//   done:true  -> stop waiting, exit with `code`
+//   done:false -> the deploy has not resolved yet; keep polling
+//
+// A verdict we do not recognise is treated as unresolved rather than as success. The failure mode
+// then is "we waited and timed out", which is honest, instead of "we called an unknown state a
+// green deploy".
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_TIMEOUT = 2;
+
+// "Is there more build log coming?" This reads the RAW build status on purpose, and only for that
+// one question - the build stream ends when the build ends, which is exactly what the raw field
+// describes. It is never turned into a state shown to a user; `classify` and `verdictOutcome` own
+// that, and the difference is the whole point of bug #24.
+// isBuildRunning - the OTHER half of isBuildFinished, and deliberately not its negation. `!isBuildFinished`
+// is TRUE for a null status, which is the "we could not read it" answer - a caller that follows on that
+// waits out its own deadline instead of saying the honest thing. Callers that must keep following a live
+// build (the build-log follow loop) need "we KNOW it is running", which is only this.
+export function isBuildRunning(buildStatus) {
+  return buildStatus === 'building';
+}
+
+export function isBuildFinished(buildStatus) {
+  return buildStatus != null && buildStatus !== 'building';
+}
+
+export function verdictOutcome(verdict) {
+  if (verdict === 'live') return { done: true, code: EXIT_OK, message: 'Live.' };
+  if (verdict === 'failed_to_start') {
+    return { done: true, code: EXIT_FAILED, message: 'The build finished but the service did not start.' };
+  }
+  if (verdict === 'failed') return { done: true, code: EXIT_FAILED, message: 'The build failed.' };
+  // UNKNOWN IS TERMINAL, and that is the whole point of handling it here. The fallback below is
+  // `{done:false}`, so without this line `--wait` would poll forever on a deploy we can never judge - and
+  // that is not a corner case: a long build plus a wait crosses the verdict window routinely.
+  // EXIT_OK, not EXIT_FAILED: the same aged-out deploy exits 0 today, and failing a customer's pipeline
+  // over OUR missing evidence would turn our gap into their red build. The message must not reuse "Live."
+  // - saying nothing happened is exactly the claim we cannot make.
+  if (verdict === 'unknown') {
+    return { done: true, code: EXIT_OK, message: 'Deploy finished. We could not confirm the service came up.' };
+  }
+  return { done: false, code: null, message: null };
+}

package/src/stepup.js

@@ -0,0 +1,69 @@
+// "Confirm it is you" from a terminal.
+//
+// A few routes (revealing a database password, minting an API token) need a FRESH proof of identity
+// on the session - ten minutes old at most - on top of being signed in. The server answers
+// 403 { code: 'step_up_required' } when it is missing. We react to exactly that answer, ask for the
+// proof, and retry the call ONCE. We never ask up front: the server decides what needs it, and a
+// prompt the server did not ask for teaches people to type secrets on reflex.
+//
+// What can be used here, in the server's own order (services/mfa.js verifyForStepUp):
+//   * 2FA on  -> an authenticator code, or a recovery code with --recovery. A passkey cannot be used
+//                from a terminal - the dashboard is the answer for a passkey-only account.
+//   * 2FA off -> the password, or an emailed code for an account without one.
+// None of these is ever echoed, and none is kept after the call.
+import { ApiError, isApiToken, securityState, reauth, reauthEmailCode } from './api.js';
+import { askHidden } from './prompt.js';
+import { err } from './output.js';
+import { CliError } from './errors.js';
+
+const PROMPT_MS = 5 * 60_000;
+
+function isStepUpRequired(e) {
+  return e instanceof ApiError && e.httpStatus === 403 && e.code === 'step_up_required';
+}
+
+async function confirmIdentity(ctx, { recovery = false } = {}) {
+  const state = await securityState(ctx);
+  const mfa = (state && state.mfa) || {};
+  // stderr: stdout may be JSON or a URL a script is capturing.
+  err('Please confirm it is you to continue.');
+
+  let body;
+  if (mfa.enabled) {
+    if (recovery) {
+      body = { method: 'recovery', code: await askHidden('Recovery code: ', { timeoutMs: PROMPT_MS }) };
+    } else if (mfa.totp && mfa.totp.confirmed) {
+      body = { method: 'totp', code: await askHidden('Authenticator code: ', { timeoutMs: PROMPT_MS }) };
+    } else {
+      throw new CliError('Your account confirms with a passkey, which cannot be used from a terminal. Use --recovery with a recovery code, or do this in the dashboard.');
+    }
+  } else if (mfa.hasPassword) {
+    body = { method: 'password', password: await askHidden('Password: ', { timeoutMs: PROMPT_MS }) };
+  } else {
+    await reauthEmailCode(ctx);
+    err('We have emailed you a 6-digit code.');
+    body = { method: 'email_code', code: await askHidden('Code: ', { timeoutMs: PROMPT_MS }) };
+  }
+  if (!body.code && !body.password) throw new CliError('Nothing was entered - stopped.');
+  await reauth(ctx, body);
+}
+
+export async function withStepUp(ctx, fn, { recovery = false } = {}) {
+  try {
+    return await fn();
+  } catch (e) {
+    if (!isStepUpRequired(e)) throw e;
+    // A token has no session to step up on. The server refuses these routes to a token anyway; this
+    // just says it in words.
+    if (isApiToken(ctx.token)) throw new CliError('This needs a signed-in session, not an API token. Run `voroa login`.');
+    await confirmIdentity(ctx, { recovery });
+    try {
+      return await fn();
+    } catch (again) {
+      // Retried exactly once. A second demand means the confirmation did not stick - say that, not the
+      // generic "you do not have access", which would read as a permissions problem.
+      if (isStepUpRequired(again)) throw new CliError('The confirmation did not go through. Please try again.');
+      throw again;
+    }
+  }
+}