@series-a/cli 0.23.1 → 1.0.0

package/bin/setu.mjs

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+/**
+ * setu — internal CLI for building claimable practice and dentist profiles.
+ *
+ *   setu login
+ *   setu practice create --url https://smiledental.co.uk
+ *   setu practice create --name "Smile Dental" --town Portsmouth
+ *   setu practice import practices.csv
+ *   setu practice review <draft-id>
+ *   setu practice publish <draft-id>
+ *   setu practice claim-link <practice-id>
+ *   setu dentist create --practice <id> --name "Dr Jane Roe"
+ *   setu status [<practice-id>]
+ *
+ * Global flags: --json (machine-readable output), --operator <name>
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { call } from "../lib/api.mjs";
+import { loadConfig, saveConfig, clearConfig, configPath, DEFAULT_API } from "../lib/config.mjs";
+
+const VERSION = JSON.parse(
+  readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),
+).version;
+import { ask, confirm, log, ok, fail, warn, heading, table, spinner, c } from "../lib/ui.mjs";
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (!next || next.startsWith("--")) flags[key] = true;
+      else { flags[key] = next; i++; }
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+const { positional, flags } = parseArgs(process.argv.slice(2));
+const JSON_OUT = !!flags.json;
+const out = (obj) => { if (JSON_OUT) log(JSON.stringify(obj, null, 2)); };
+
+function usage() {
+  log(`
+${c.bold("setu")} — build claimable Setu profiles
+
+${c.bold("Commands")}
+  login                                  Store your internal CLI key
+  logout                                 Remove the stored key from this machine
+  whoami                                 Show the signed-in operator
+  practice create                        Build a profile draft with AI
+      --url <website>                      from a website, or
+      --name <name> --town <town>          from a name + town (found on Google)
+      [--pricing <url>] [--booking <url>] [--email <contact email>]
+  practice review <draft-id>             Show everything the AI extracted
+  practice publish <draft-id>            Publish as an unclaimed listing
+      [--no-dentists]                      don't seed detected clinicians
+  practice import <file.csv>             Bulk build + optionally publish
+      [--publish] [--concurrency 2] [--dry-run]
+      [--out results.json] [--resume results.json] [--limit N]
+  practice claim-link <practice-id>      Outreach link for the owner
+      [--rotate]
+  practice delete <practice-id>          Remove an unclaimed seeded profile
+      [--unpublish] [--yes]
+  dentist create --name "Dr Jane Roe"    Seed one clinician
+      [--practice <id>] [--profile-url <url>] [--town <town>]
+  status [<practice-id>]                 List or inspect seeded profiles
+
+${c.bold("Global")}  --json  --yes  --verbose  --operator <name>  --version
+`);
+}
+
+async function cmdLogin() {
+  const cfg = loadConfig();
+  const api = (await ask(`API base ${c.dim(`[${cfg.api || DEFAULT_API}]`)}: `)) || cfg.api || DEFAULT_API;
+  const key = await ask("Internal CLI key: ", { silent: true });
+  const operator = (await ask(`Your name (for attribution) ${c.dim(`[${cfg.operator || ""}]`)}: `)) || cfg.operator || "cli";
+  const res = await call("cli-auth", {}, { api, key, operator });
+  saveConfig({ api, key, operator });
+  ok(`Signed in as ${c.bold(operator)} — ${res.site}`);
+}
+
+function cmdLogout() {
+  clearConfig();
+  ok(`Signed out — removed ${configPath()}`);
+}
+
+async function cmdPracticeDelete(id) {
+  if (!id) { fail("Usage: setu practice delete <practice-id> [--unpublish]"); process.exit(1); }
+  const unpublishOnly = !!flags.unpublish;
+  if (!JSON_OUT && !flags.yes) {
+    const proceed = await confirm(
+      unpublishOnly
+        ? "Hide this seeded profile from patients?"
+        : "Permanently delete this unclaimed seeded profile (and its seeded clinicians)?",
+    );
+    if (!proceed) { warn("Cancelled."); return; }
+  }
+  const res = await call("cli-profile-delete", {
+    id,
+    profile_type: flags.dentist ? "dentist" : "practice",
+    unpublish_only: unpublishOnly,
+  });
+  if (JSON_OUT) return out(res);
+  ok(`${res.name} — ${res.action}`);
+}
+
+async function cmdWhoami() {
+  const res = await call("cli-auth", {});
+  const cfg = loadConfig();
+  if (JSON_OUT) return out({ ...res, api: cfg.api });
+  table([["Operator", res.operator], ["Site", res.site], ["API", cfg.api]]);
+}
+
+function summarise(res) {
+  table([
+    ["Draft", res.draft_id],
+    ["Name", res.name],
+    ["Status", res.status],
+    ["Readiness", `${res.readiness_score}/100`],
+    ["Services", res.services],
+    ["Priced items", res.pricing_rows],
+    ["Clinicians found", res.dentists_found],
+    ["Google reviews", res.google_reviews],
+  ]);
+  if (Array.isArray(res.missing) && res.missing.length) {
+    warn(`Missing: ${res.missing.slice(0, 6).map((m) => (typeof m === "string" ? m : m.field ?? "")).join(", ")}`);
+  }
+}
+
+async function cmdPracticeCreate() {
+  const payload = {
+    website: typeof flags.url === "string" ? flags.url : undefined,
+    name: typeof flags.name === "string" ? flags.name : undefined,
+    town: typeof flags.town === "string" ? flags.town : undefined,
+    postcode: typeof flags.postcode === "string" ? flags.postcode : undefined,
+    contact_email: typeof flags.email === "string" ? flags.email : undefined,
+    booking_url: typeof flags.booking === "string" ? flags.booking : undefined,
+    pricing_urls: typeof flags.pricing === "string" ? [flags.pricing] : undefined,
+  };
+  if (!payload.website && !payload.name) {
+    fail("Pass --url, or --name with --town.");
+    process.exit(1);
+  }
+  const s = spinner("Finding and reading the practice online");
+  try {
+    const res = await call("cli-profile-create", payload);
+    s.stop();
+    if (JSON_OUT) return out(res);
+    heading("Draft built");
+    summarise(res);
+    log(`\n${c.dim("Next:")} setu practice publish ${res.draft_id}`);
+  } catch (e) {
+    s.stop();
+    throw e;
+  }
+}
+
+async function cmdPracticeReview(draftId) {
+  if (!draftId) { fail("Usage: setu practice review <draft-id>"); process.exit(1); }
+  const res = await call("cli-profile-review", { draft_id: draftId });
+  if (JSON_OUT) return out(res);
+  heading(res.identity.name || "Draft");
+  table([
+    ["Status", res.status],
+    ["Readiness", `${res.readiness_score}/100`],
+    ["Tagline", res.identity.tagline],
+    ["Phone", res.identity.contact?.phone],
+    ["Email", res.identity.contact?.email],
+    ["Published as", res.published_practice_id],
+  ]);
+  heading(`Services (${res.services.length})`);
+  log("  " + (res.services.join(", ") || c.dim("none found")));
+  heading(`Pricing (${res.service_pricing.length})`);
+  for (const p of res.service_pricing.slice(0, 12)) {
+    log(`  ${String(p.label || p.service).padEnd(34)} £${p.amount_from}${p.amount_to ? `–£${p.amount_to}` : ""}`);
+  }
+  heading(`Clinicians (${res.dentist_candidates.length})`);
+  for (const d of res.dentist_candidates.slice(0, 12)) log(`  ${d.name}${d.role ? c.dim(` — ${d.role}`) : ""}`);
+  if (res.errors) warn(`Notes: ${JSON.stringify(res.errors).slice(0, 300)}`);
+}
+
+async function cmdPracticePublish(draftId) {
+  if (!draftId) { fail("Usage: setu practice publish <draft-id>"); process.exit(1); }
+  if (!JSON_OUT && !flags.yes) {
+    const proceed = await confirm("Publish this profile as an unclaimed public listing?");
+    if (!proceed) { warn("Cancelled."); return; }
+  }
+  const res = await call("cli-profile-publish", {
+    draft_id: draftId,
+    create_dentists: !flags["no-dentists"],
+  });
+  if (JSON_OUT) return out(res);
+  ok("Published as an unclaimed listing");
+  table([
+    ["Practice", res.practice_id],
+    ["Profile", res.profile_url],
+    ["Claim link", res.claim_url],
+    ["Clinicians", res.dentists_created],
+  ]);
+}
+
+function parseCsv(text) {
+  const lines = text.split(/\r?\n/).filter((l) => l.trim());
+  if (!lines.length) return [];
+  const split = (line) => {
+    const cells = [];
+    let cur = "", inQ = false;
+    for (const ch of line) {
+      if (ch === '"') inQ = !inQ;
+      else if (ch === "," && !inQ) { cells.push(cur); cur = ""; }
+      else cur += ch;
+    }
+    cells.push(cur);
+    return cells.map((s) => s.trim());
+  };
+  const header = split(lines[0]).map((h) => h.toLowerCase());
+  return lines.slice(1).map((line) => {
+    const cells = split(line);
+    const row = {};
+    header.forEach((h, i) => { if (cells[i]) row[h] = cells[i]; });
+    return row;
+  });
+}
+
+async function cmdPracticeImport(file) {
+  if (!file) { fail("Usage: setu practice import <file.csv>"); process.exit(1); }
+  let rows;
+  try {
+    rows = parseCsv(readFileSync(file, "utf8"));
+  } catch (e) {
+    fail(`Could not read ${file}: ${e.message}`);
+    process.exit(1);
+  }
+  if (!rows.length) { fail("No rows found in that CSV."); process.exit(1); }
+
+  // Validate before spending any API calls.
+  const invalid = [];
+  rows = rows.map((row, i) => ({ ...row, __line: i + 2 }));
+  const valid = rows.filter((row) => {
+    const hasSite = !!(row.website || row.url);
+    const hasNameTown = !!(row.name && (row.town || row.city));
+    if (!hasSite && !hasNameTown) {
+      invalid.push(`line ${row.__line}: needs a website/url, or a name plus town`);
+      return false;
+    }
+    return true;
+  });
+  if (invalid.length) {
+    warn(`Skipping ${invalid.length} unusable row(s):`);
+    for (const m of invalid.slice(0, 10)) log(`    ${c.dim(m)}`);
+  }
+
+  // Resume: skip anything already completed in a previous results file.
+  let done = new Map();
+  if (typeof flags.resume === "string") {
+    try {
+      const prev = JSON.parse(readFileSync(flags.resume, "utf8"));
+      for (const r of prev.results ?? []) if (r.ok) done.set(r.label, r);
+    } catch (e) { warn(`Could not read resume file: ${e.message}`); }
+  }
+
+  const labelOf = (row, i) => row.name || row.website || row.url || `row ${i + 1}`;
+  let queue = valid.filter((row, i) => !done.has(labelOf(row, i)));
+  if (flags.limit) queue = queue.slice(0, Number(flags.limit));
+
+  if (flags["dry-run"]) {
+    heading(`Dry run — ${queue.length} practice(s) would be built${flags.publish ? " and published" : ""}`);
+    for (const row of queue.slice(0, 50)) log(`  ${labelOf(row, 0)} ${c.dim(row.website || row.url || row.town || "")}`);
+    if (JSON_OUT) out({ dry_run: true, total: queue.length, skipped: invalid.length, already_done: done.size });
+    return;
+  }
+
+  const concurrency = Math.max(1, Math.min(5, Number(flags.concurrency) || 2));
+  log(`Importing ${c.bold(queue.length)} practices (${concurrency} at a time)…\n`);
+
+  const results = [...done.values()];
+  let index = 0;
+  let completed = 0;
+
+  async function worker() {
+    while (index < queue.length) {
+      const i = index++;
+      const row = queue[i];
+      const label = labelOf(row, i);
+      try {
+        const created = await call("cli-profile-create", {
+          website: row.website || row.url,
+          name: row.name,
+          town: row.town || row.city,
+          postcode: row.postcode,
+          contact_email: row.email,
+          contact_phone: row.phone,
+        });
+        let published = null;
+        if (flags.publish && created.status !== "failed") {
+          published = await call("cli-profile-publish", { draft_id: created.draft_id });
+        }
+        completed++;
+        log(`${c.green("✔")} [${completed}/${queue.length}] ${label} ${c.dim(`(${created.readiness_score}/100)`)}${published ? ` → ${published.claim_url}` : ""}`);
+        results.push({
+          label, ok: true, draft_id: created.draft_id,
+          practice_id: published?.practice_id ?? null,
+          claim_url: published?.claim_url ?? null,
+        });
+      } catch (e) {
+        completed++;
+        log(`${c.red("✖")} [${completed}/${queue.length}] ${label} — ${e.message}`);
+        results.push({ label, ok: false, error: e.message, line: row.__line });
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, worker));
+
+  const failed = results.filter((r) => !r.ok);
+  const payload = {
+    total: results.length,
+    built: results.length - failed.length,
+    failed: failed.length,
+    skipped_invalid: invalid.length,
+    results,
+  };
+
+  if (typeof flags.out === "string") {
+    try {
+      writeFileSync(flags.out, JSON.stringify(payload, null, 2));
+      ok(`Results written to ${flags.out}${failed.length ? ` — rerun with --resume ${flags.out}` : ""}`);
+    } catch (e) { warn(`Could not write results file: ${e.message}`); }
+  }
+
+  if (JSON_OUT) { out(payload); }
+  else {
+    heading(`Done — ${payload.built} built, ${failed.length} failed`);
+    for (const f of failed) log(`  ${c.red("✖")} ${f.label}: ${f.error}`);
+  }
+  if (failed.length) process.exitCode = 1;
+}
+
+async function cmdClaimLink(id) {
+  if (!id) { fail("Usage: setu practice claim-link <practice-id>"); process.exit(1); }
+  const res = await call("cli-claim-link", {
+    id,
+    profile_type: flags.dentist ? "dentist" : "practice",
+    rotate: !!flags.rotate,
+  });
+  if (JSON_OUT) return out(res);
+  ok(res.name);
+  log(`  ${res.claim_url}`);
+}
+
+async function cmdDentistCreate() {
+  if (typeof flags.name !== "string") { fail("Pass --name \"Dr Jane Roe\"."); process.exit(1); }
+  const s = spinner("Building the clinician profile");
+  try {
+    const res = await call("cli-dentist-create", {
+      name: flags.name,
+      practice_id: typeof flags.practice === "string" ? flags.practice : undefined,
+      profile_url: typeof flags["profile-url"] === "string" ? flags["profile-url"] : undefined,
+      town: typeof flags.town === "string" ? flags.town : undefined,
+      postcode: typeof flags.postcode === "string" ? flags.postcode : undefined,
+      email: typeof flags.email === "string" ? flags.email : undefined,
+    });
+    s.stop();
+    if (JSON_OUT) return out(res);
+    ok("Clinician seeded as unclaimed");
+    table([["Dentist", res.dentist_id], ["AI enriched", res.enriched ? "yes" : "no"], ["Claim link", res.claim_url]]);
+  } catch (e) { s.stop(); throw e; }
+}
+
+async function cmdStatus(id) {
+  const res = await call("cli-profile-status", id ? { id } : { list: true, limit: flags.limit });
+  if (JSON_OUT) return out(res);
+  if (res.items) {
+    heading(`Seeded profiles (${res.items.length})`);
+    for (const p of res.items) {
+      const state = p.claim_status === "claimed" ? c.green("claimed") : p.is_live ? c.green("live") : c.yellow(p.claim_status);
+      log(`  ${state.padEnd(20)} ${String(p.name).slice(0, 38).padEnd(40)} ${c.dim(p.id)}`);
+    }
+    return;
+  }
+  heading(res.practice.name);
+  table([
+    ["Status", res.practice.claim_status],
+    ["Live", res.practice.is_live ? "yes" : "no"],
+    ["Source", `${res.practice.source} (${res.practice.created_by_operator ?? "—"})`],
+    ["Claim link", res.practice.claim_url],
+  ]);
+  heading(`Claims (${res.claims.length})`);
+  for (const cl of res.claims) log(`  ${cl.status.padEnd(10)} ${cl.claimant_email} ${c.dim(cl.method)}`);
+}
+
+async function main() {
+  if (typeof flags.operator === "string") {
+    const cfg = loadConfig();
+    saveConfig({ ...cfg, operator: flags.operator });
+  }
+  if (flags.version) { log(`setu ${VERSION}`); return; }
+  const [group, sub, arg] = positional;
+  if (!group || flags.help || group === "help") { usage(); return; }
+  switch (group) {
+    case "login": return cmdLogin();
+    case "logout": return cmdLogout();
+    case "whoami": return cmdWhoami();
+    case "status": return cmdStatus(sub);
+    case "practice":
+      switch (sub) {
+        case "create": return cmdPracticeCreate();
+        case "review": return cmdPracticeReview(arg);
+        case "publish": return cmdPracticePublish(arg);
+        case "import": return cmdPracticeImport(arg);
+        case "claim-link": return cmdClaimLink(arg);
+        case "delete": return cmdPracticeDelete(arg);
+        default:
+          fail(`Unknown command: practice ${sub ?? ""}`.trim());
+          usage();
+          process.exitCode = 1;
+          return;
+      }
+    case "dentist":
+      if (sub === "create") return cmdDentistCreate();
+      fail(`Unknown command: dentist ${sub ?? ""}`.trim());
+      usage();
+      process.exitCode = 1;
+      return;
+    default:
+      fail(`Unknown command: ${group}`);
+      usage();
+      process.exitCode = 1;
+      return;
+  }
+}
+
+main().catch((e) => {
+  fail(e.message);
+  if (flags.verbose && e.stack) log(c.dim(e.stack));
+  if (e.data && !JSON_OUT && e.data.practice_id) log(c.dim(`  existing: ${e.data.practice_id}`));
+  process.exit(1);
+});

package/lib/api.mjs

@@ -0,0 +1,84 @@
+import { loadConfig } from "./config.mjs";
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const VERBOSE = process.argv.includes("--verbose");
+
+/**
+ * Call an internal Setu edge function.
+ *
+ * Hardened for unattended/bulk use: every request has a timeout, transient
+ * failures (network drops, 429s, 5xx) are retried with exponential backoff,
+ * and a `Retry-After` header is honoured when the server sends one.
+ */
+export async function call(fn, body = {}, overrides = {}) {
+  const cfg = { ...loadConfig(), ...overrides };
+  if (!cfg.key) {
+    throw new Error("Not signed in. Run `setu login` first (or set SETU_CLI_API_KEY).");
+  }
+
+  const timeoutMs = Number(overrides.timeoutMs || process.env.SETU_TIMEOUT_MS || 240_000);
+  const maxAttempts = Number(overrides.retries ?? process.env.SETU_RETRIES ?? 3);
+  let lastError;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${cfg.api}/${fn}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-setu-cli-key": cfg.key,
+          "x-setu-operator": cfg.operator || "cli",
+          "x-setu-request-id": crypto.randomUUID(),
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      clearTimeout(timer);
+
+      const text = await res.text();
+      let data;
+      try { data = text ? JSON.parse(text) : {}; } catch { data = { error: text }; }
+
+      if (res.ok) return data;
+
+      const err = new Error(data.message || data.error || `${fn} failed (${res.status})`);
+      err.status = res.status;
+      err.data = data;
+
+      if (RETRYABLE_STATUS.has(res.status) && attempt < maxAttempts) {
+        const retryAfter = Number(res.headers.get("retry-after")) * 1000;
+        const wait = Number.isFinite(retryAfter) && retryAfter > 0
+          ? retryAfter
+          : Math.min(30_000, 1000 * 2 ** (attempt - 1)) + Math.random() * 500;
+        if (VERBOSE) console.error(`  retry ${attempt}/${maxAttempts - 1} on ${fn} (${res.status}) in ${Math.round(wait)}ms`);
+        await sleep(wait);
+        lastError = err;
+        continue;
+      }
+      throw err;
+    } catch (e) {
+      clearTimeout(timer);
+      if (e.status && !RETRYABLE_STATUS.has(e.status)) throw e;
+
+      const aborted = e.name === "AbortError";
+      const message = aborted
+        ? `${fn} timed out after ${Math.round(timeoutMs / 1000)}s`
+        : e.message;
+
+      if (attempt < maxAttempts) {
+        const wait = Math.min(30_000, 1000 * 2 ** (attempt - 1)) + Math.random() * 500;
+        if (VERBOSE) console.error(`  retry ${attempt}/${maxAttempts - 1} on ${fn} (${message}) in ${Math.round(wait)}ms`);
+        await sleep(wait);
+        lastError = Object.assign(new Error(message), { status: e.status, data: e.data });
+        continue;
+      }
+      throw Object.assign(new Error(message), { status: e.status, data: e.data });
+    }
+  }
+
+  throw lastError ?? new Error(`${fn} failed`);
+}

package/lib/config.mjs

@@ -0,0 +1,42 @@
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync, rmSync } from "node:fs";
+
+const DEFAULT_API =
+  process.env.SETU_API_URL || "https://vaanfxluxietcicoikcg.supabase.co/functions/v1";
+
+function configPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "setu", "config.json");
+}
+
+export function loadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return { api: DEFAULT_API, key: process.env.SETU_CLI_API_KEY || "", operator: "" };
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return {
+      api: process.env.SETU_API_URL || raw.api || DEFAULT_API,
+      key: process.env.SETU_CLI_API_KEY || raw.key || "",
+      operator: raw.operator || "",
+    };
+  } catch {
+    return { api: DEFAULT_API, key: process.env.SETU_CLI_API_KEY || "", operator: "" };
+  }
+}
+
+export function saveConfig(cfg) {
+  const path = configPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(cfg, null, 2));
+  try { chmodSync(path, 0o600); } catch { /* windows */ }
+  return path;
+}
+
+export function clearConfig() {
+  const path = configPath();
+  try { rmSync(path, { force: true }); } catch { /* ignore */ }
+  return path;
+}
+
+export { DEFAULT_API, configPath };

package/lib/ui.mjs

@@ -0,0 +1,68 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+const useColor = stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (useColor ? `\u001b[${code}m${s}\u001b[0m` : String(s));
+
+export const c = {
+  bold: wrap("1"),
+  dim: wrap("2"),
+  blue: wrap("36"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  red: wrap("31"),
+};
+
+export function log(...args) { console.log(...args); }
+export function ok(msg) { log(`${c.green("✔")} ${msg}`); }
+export function warn(msg) { log(`${c.yellow("!")} ${msg}`); }
+export function fail(msg) { console.error(`${c.red("✖")} ${msg}`); }
+
+export function heading(msg) { log(`\n${c.bold(msg)}`); }
+
+export function table(rows) {
+  for (const [k, v] of rows) {
+    log(`  ${c.dim(String(k).padEnd(18))} ${v ?? c.dim("—")}`);
+  }
+}
+
+export async function ask(question, { silent = false } = {}) {
+  const rl = createInterface({ input: stdin, output: stdout, terminal: true });
+  if (!silent) {
+    const answer = await rl.question(question);
+    rl.close();
+    return answer.trim();
+  }
+  // Hidden input for secrets.
+  const onData = (char) => {
+    if (["\n", "\r", "\u0004"].includes(char.toString())) return;
+    stdout.write("\u001b[2K\u001b[200D" + question + "*".repeat(rl.line.length));
+  };
+  stdin.on("data", onData);
+  const answer = await rl.question(question);
+  stdin.off("data", onData);
+  rl.close();
+  stdout.write("\n");
+  return answer.trim();
+}
+
+export async function confirm(question) {
+  const a = await ask(`${question} ${c.dim("(y/N)")} `);
+  return /^y(es)?$/i.test(a);
+}
+
+export function spinner(label) {
+  if (!stdout.isTTY) { log(`${label}…`); return { stop: () => {} }; }
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let i = 0;
+  const timer = setInterval(() => {
+    stdout.write(`\r${c.blue(frames[i++ % frames.length])} ${label}   `);
+  }, 80);
+  return {
+    stop: (final) => {
+      clearInterval(timer);
+      stdout.write("\r\u001b[2K");
+      if (final) log(final);
+    },
+  };
+}