ashlr-plugin 1.36.4

package/scripts/upgrade-flow.ts

@@ -0,0 +1,775 @@
+#!/usr/bin/env bun
+/**
+ * ashlr upgrade-flow.ts — terminal-native free-to-pro upgrade.
+ *
+ * Driven by the /ashlr-upgrade skill. Walks the user from free → pro/team
+ * entirely in the terminal, in under 90 seconds.
+ *
+ * Usage:
+ *   bun run scripts/upgrade-flow.ts
+ *   bun run scripts/upgrade-flow.ts --tier pro --annual
+ *   bun run scripts/upgrade-flow.ts --tier team --annual --email you@example.com
+ *   bun run scripts/upgrade-flow.ts --no-poll   # skip activation polling (testing)
+ *
+ * Env:
+ *   ASHLR_API_URL      — default https://api.ashlr.ai
+ *   ASHLR_PRO_TOKEN    — if set, skip sign-in and go straight to checkout
+ *   ASHLR_NO_BROWSER=1 — skip browser open (headless / CI / SSH)
+ *
+ * Stdout: the user-facing transcript.
+ * Exits: 0 on success or graceful timeout, 1 on fatal error.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
+import { readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import { spawn } from "child_process";
+import * as readline from "readline";
+import { randomBytes } from "crypto";
+import { recordNudgeClicked, maybeSyncToCloud as maybeSyncNudgeEvents } from "../servers/_nudge-events.ts";
+import { validateProToken } from "../servers/_pro.ts";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const API_URL = process.env["ASHLR_API_URL"] ?? "https://api.ashlr.ai";
+const SITE_URL = process.env["ASHLR_SITE_URL"] ?? "https://plugin.ashlr.ai";
+const ASHLR_DIR = join(homedir(), ".ashlr");
+const TOKEN_FILE = join(ASHLR_DIR, "pro-token");
+const ENV_FILE = join(ASHLR_DIR, "env");
+const NO_BROWSER = process.env["ASHLR_NO_BROWSER"] === "1";
+
+// Poll intervals / timeouts
+const AUTH_POLL_INTERVAL_MS = 3_000;
+const AUTH_POLL_TIMEOUT_MS = 3 * 60 * 1_000; // 3 minutes
+const BILLING_POLL_INTERVAL_MS = 5_000;
+const BILLING_POLL_TIMEOUT_MS = 10 * 60 * 1_000; // 10 minutes
+
+// Brand colors (truecolor)
+const TTY = process.stdout.isTTY;
+const GREEN  = TTY ? "\x1b[38;2;0;200;120m" : "";
+const BOLD   = TTY ? "\x1b[1m" : "";
+const DIM    = TTY ? "\x1b[2m" : "";
+const RESET  = TTY ? "\x1b[0m" : "";
+const CYAN   = TTY ? "\x1b[38;2;100;210;255m" : "";
+const YELLOW = TTY ? "\x1b[38;2;255;200;80m" : "";
+
+// ---------------------------------------------------------------------------
+// CLI flags
+// ---------------------------------------------------------------------------
+
+interface Flags {
+  tier: "pro" | "team" | null;
+  annual: boolean;
+  email: string | null;
+  noPoll: boolean;
+}
+
+function parseArgs(): Flags {
+  const args = process.argv.slice(2);
+  const flags: Flags = { tier: null, annual: false, email: null, noPoll: false };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--annual") flags.annual = true;
+    if (a === "--no-poll") flags.noPoll = true;
+    if (a === "--tier" && args[i + 1]) {
+      const v = args[++i]!;
+      if (v === "pro" || v === "team") flags.tier = v;
+    }
+    if (a === "--email" && args[i + 1]) {
+      flags.email = args[++i]!;
+    }
+  }
+  return flags;
+}
+
+// ---------------------------------------------------------------------------
+// UI helpers
+// ---------------------------------------------------------------------------
+
+function print(msg: string): void {
+  process.stdout.write(msg + "\n");
+}
+
+function banner(): void {
+  print("");
+  print(`${BOLD}${GREEN}  ╔══════════════════════════════════╗${RESET}`);
+  print(`${BOLD}${GREEN}  ║      ashlr  ·  upgrade           ║${RESET}`);
+  print(`${BOLD}${GREEN}  ╚══════════════════════════════════╝${RESET}`);
+  print("");
+}
+
+function step(n: number, total: number, label: string): void {
+  print(`\n${CYAN}${BOLD}▬▬▬ STEP ${n}/${total}: ${label} ▬▬▬${RESET}`);
+}
+
+function ok(msg: string): void {
+  print(`${GREEN}${BOLD}  ✓${RESET}  ${msg}`);
+}
+
+function info(msg: string): void {
+  print(`${DIM}  ${msg}${RESET}`);
+}
+
+function warn(msg: string): void {
+  print(`${YELLOW}  !  ${msg}${RESET}`);
+}
+
+// Animated dots on one line, returns a stopper function.
+function startDots(prefix: string): () => void {
+  const frames = [".", "..", "..."];
+  let i = 0;
+  if (!TTY) {
+    process.stdout.write(prefix + "   ");
+    return () => { process.stdout.write("\n"); };
+  }
+
+  process.stdout.write(prefix);
+  const timer = setInterval(() => {
+    readline.clearLine(process.stdout, 0);
+    readline.cursorTo(process.stdout, 0);
+    process.stdout.write(prefix + " " + frames[i % 3]!);
+    i++;
+  }, 500);
+
+  return () => {
+    clearInterval(timer);
+    readline.clearLine(process.stdout, 0);
+    readline.cursorTo(process.stdout, 0);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Stdin input with timeout
+// ---------------------------------------------------------------------------
+
+async function prompt(question: string, timeoutMs = 60_000): Promise<string> {
+  process.stdout.write(`  ${BOLD}${question}${RESET} `);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      rl.close();
+      reject(new Error("Input timed out"));
+    }, timeoutMs);
+
+    rl.once("line", (line) => {
+      clearTimeout(timer);
+      rl.close();
+      resolve(line.trim());
+    });
+
+    rl.once("close", () => {
+      clearTimeout(timer);
+      resolve("");
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Token storage
+// ---------------------------------------------------------------------------
+
+function ensureAshlrDir(): void {
+  if (!existsSync(ASHLR_DIR)) {
+    mkdirSync(ASHLR_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function saveToken(token: string): void {
+  ensureAshlrDir();
+  writeFileSync(TOKEN_FILE, token, { encoding: "utf8", mode: 0o600 });
+  // Try to set mode 0600 explicitly (belt-and-suspenders for older bun)
+  try { chmodSync(TOKEN_FILE, 0o600); } catch { /* best-effort */ }
+}
+
+async function writeEnvFile(token: string): Promise<void> {
+  ensureAshlrDir();
+  let existing = "";
+  try { existing = await readFile(ENV_FILE, "utf8"); } catch { /* new file */ }
+
+  // Remove any prior ASHLR_PRO_TOKEN line, then append the fresh one
+  const lines = existing
+    .split("\n")
+    .filter((l) => !l.startsWith("export ASHLR_PRO_TOKEN="));
+  lines.push(`export ASHLR_PRO_TOKEN=${token}`);
+
+  await writeFile(ENV_FILE, lines.join("\n").trimStart() + "\n", { encoding: "utf8", mode: 0o600 });
+  try { chmodSync(ENV_FILE, 0o600); } catch { /* best-effort */ }
+}
+
+function readStoredToken(): string | null {
+  try {
+    const t = readFileSync(TOKEN_FILE, "utf8").trim();
+    return t || null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+async function apiFetch(
+  path: string,
+  opts: { method?: string; body?: unknown; token?: string },
+): Promise<{ ok: boolean; status: number; data: unknown }> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (opts.token) headers["Authorization"] = `Bearer ${opts.token}`;
+
+  const res = await fetch(`${API_URL}${path}`, {
+    method: opts.method ?? "GET",
+    headers,
+    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+  });
+
+  let data: unknown;
+  try { data = await res.json(); } catch { data = {}; }
+  return { ok: res.ok, status: res.status, data };
+}
+
+// ---------------------------------------------------------------------------
+// Browser open — cross-platform
+// ---------------------------------------------------------------------------
+
+async function openBrowser(url: string): Promise<void> {
+  if (NO_BROWSER) {
+    warn("ASHLR_NO_BROWSER=1 — skipping browser open.");
+    print(`\n  Open this URL manually:\n\n  ${BOLD}${url}${RESET}\n`);
+    return;
+  }
+
+  let cmd: string;
+  let args: string[];
+
+  switch (process.platform) {
+    case "darwin":
+      cmd = "open"; args = [url]; break;
+    case "win32":
+      cmd = "cmd"; args = ["/c", "start", '""', url]; break;
+    default: // linux + others
+      cmd = "xdg-open"; args = [url]; break;
+  }
+
+  const fallbackToUrl = () => {
+    warn("Could not open a browser automatically.");
+    print(`\n  Open this URL manually:\n\n  ${BOLD}${url}${RESET}\n`);
+  };
+
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+    // Attach the error listener BEFORE detaching — spawn() can reach the
+    // "spawned successfully" callback and then emit 'error' asynchronously
+    // (e.g. when the child exits with ENOENT on Windows, or xdg-open is
+    // missing on a minimal Linux). Without this listener the error would
+    // crash the process or be silently swallowed and the user would see
+    // "Opened checkout" when nothing actually opened.
+    let errored = false;
+    child.once("error", () => { errored = true; fallbackToUrl(); });
+    child.unref();
+    // Give the child time to surface immediate spawn errors before we claim
+    // success. Windows' `cmd /c start` emits ENOENT / URL-handler failures
+    // noticeably later than POSIX `open` / `xdg-open`, so we wait longer
+    // there to avoid a false "Opened checkout" message.
+    const settleMs = process.platform === "win32" ? 500 : 50;
+    await new Promise((resolve) => setTimeout(resolve, settleMs));
+    if (!errored) {
+      ok("Opened checkout in your browser. Complete payment to activate Pro.");
+    }
+  } catch {
+    fallbackToUrl();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 1 — Check current tier
+// ---------------------------------------------------------------------------
+
+async function checkCurrentTier(): Promise<{ token: string; tier: string } | null> {
+  const envToken = process.env["ASHLR_PRO_TOKEN"];
+  const storedToken = readStoredToken();
+  const token = envToken ?? storedToken;
+  if (!token) return null;
+
+  try {
+    const { ok: ok_, data } = await apiFetch("/billing/status", { token });
+    if (ok_) {
+      const d = data as { tier?: string };
+      return { token, tier: d.tier ?? "free" };
+    }
+  } catch {
+    // network error — treat as unauthenticated
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 — Sign in (GitHub or magic-link)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure, injectable polling function for GitHub OAuth session completion.
+ * Exported for unit testing — does not touch UI, browser, or file system.
+ */
+export async function pollAuthStatusBySid(
+  sid: string,
+  opts: {
+    apiUrl: string;
+    timeoutMs: number;
+    intervalMs: number;
+    fetch?: typeof globalThis.fetch;
+  },
+): Promise<{ apiToken: string }> {
+  const fetcher = opts.fetch ?? globalThis.fetch;
+  const deadline = Date.now() + opts.timeoutMs;
+
+  while (Date.now() < deadline) {
+    await sleep(opts.intervalMs);
+
+    const res = await fetcher(
+      `${opts.apiUrl}/auth/status?session=${encodeURIComponent(sid)}`,
+      { headers: { "Content-Type": "application/json" } },
+    );
+
+    if (!res.ok) {
+      // 4xx → immediate throw, not retried
+      let body: unknown;
+      try { body = await res.json(); } catch { body = {}; }
+      const msg = (body as { error?: string }).error ?? `auth/status returned HTTP ${res.status}`;
+      throw new Error(msg);
+    }
+
+    let data: unknown;
+    try { data = await res.json(); } catch { data = {}; }
+    const d = data as { ready?: boolean; apiToken?: string };
+    if (d.ready && d.apiToken) {
+      return { apiToken: d.apiToken };
+    }
+  }
+
+  throw new Error(
+    "GitHub sign-in timed out. Complete the browser flow and run /ashlr-upgrade again.",
+  );
+}
+
+async function signInWithGitHub(): Promise<string> {
+  const sid = randomBytes(16).toString("hex");
+  const url = `${SITE_URL}/auth/github?sid=${sid}`;
+
+  await openBrowser(url);
+  ok("Opened GitHub sign-in in your browser. Approve access to complete.");
+  info("Waiting for GitHub authorisation (up to 3 minutes)...");
+  print("");
+
+  const stopDots = startDots("  Waiting");
+  try {
+    const { apiToken } = await pollAuthStatusBySid(sid, {
+      apiUrl: API_URL,
+      timeoutMs: AUTH_POLL_TIMEOUT_MS,
+      intervalMs: AUTH_POLL_INTERVAL_MS,
+    });
+    stopDots();
+
+    // Best-effort: display github login. If /auth/whoami doesn't exist yet, skip.
+    try {
+      const whoami = await apiFetch("/auth/whoami", { token: apiToken });
+      if (whoami.ok) {
+        const d = whoami.data as { login?: string };
+        if (d.login) ok(`Signed in as @${d.login}`);
+        else ok("Signed in ✓");
+      } else {
+        ok("Signed in ✓");
+      }
+    } catch {
+      ok("Signed in ✓");
+    }
+
+    return apiToken;
+  } catch (err) {
+    stopDots();
+    throw err;
+  }
+}
+
+async function signInWithMagicLink(emailArg: string | null): Promise<string> {
+  let email = emailArg;
+  if (!email) {
+    try {
+      email = await prompt("[ASHLR_PROMPT: Email to sign in?]");
+    } catch {
+      throw new Error("No email provided.");
+    }
+  } else {
+    print(`  Using email: ${BOLD}${email}${RESET}`);
+  }
+
+  if (!email || !email.includes("@")) {
+    throw new Error("Invalid email address.");
+  }
+
+  // POST /auth/send
+  const sendRes = await apiFetch("/auth/send", { method: "POST", body: { email } });
+  if (!sendRes.ok) {
+    const d = sendRes.data as { error?: string };
+    throw new Error(d.error ?? `Failed to send magic link (HTTP ${sendRes.status})`);
+  }
+
+  ok(`Magic link sent to ${BOLD}${email}${RESET}. Check your inbox — click the link to continue.`);
+  info("Waiting for you to click the link (up to 3 minutes)...");
+  print("");
+
+  // Poll /auth/status
+  const stopDots = startDots("  Waiting");
+  const deadline = Date.now() + AUTH_POLL_TIMEOUT_MS;
+
+  try {
+    while (Date.now() < deadline) {
+      await sleep(AUTH_POLL_INTERVAL_MS);
+      try {
+        const res = await apiFetch(`/auth/status?email=${encodeURIComponent(email)}`, {});
+        if (res.ok) {
+          const d = res.data as { ready?: boolean; apiToken?: string };
+          if (d.ready && d.apiToken) {
+            stopDots();
+            ok("Sign-in confirmed.");
+            return d.apiToken;
+          }
+        }
+      } catch {
+        // network hiccup — keep polling
+      }
+    }
+  } finally {
+    stopDots();
+  }
+
+  throw new Error(
+    "Sign-in timed out. Check your email and try again, or run /ashlr-upgrade once you've clicked the link.",
+  );
+}
+
+/** Present auth-method menu and route to the right flow. */
+async function pickAuthMethod(emailFlag: string | null): Promise<string> {
+  print("");
+  print(`${DIM}  No active Pro token found. Let's sign you in first.${RESET}`);
+
+  // --email flag → skip menu, go straight to magic-link (back-compat)
+  if (emailFlag !== null) {
+    return signInWithMagicLink(emailFlag);
+  }
+
+  print("");
+  print(`  Sign in with:`);
+  print(`    ${BOLD}1)${RESET} GitHub ${DIM}(recommended)${RESET} — one click in your browser`);
+  print(`    ${BOLD}2)${RESET} Email magic-link`);
+  print(`  ${DIM}Choice [1]:${RESET}`);
+  print("");
+
+  let choice: string;
+  try {
+    choice = await prompt("[ASHLR_PROMPT: Choice [1]:]");
+  } catch {
+    choice = "1";
+  }
+
+  if (choice === "2") {
+    return signInWithMagicLink(null);
+  }
+
+  // Default: GitHub (Enter or "1")
+  return signInWithGitHub();
+}
+
+// ---------------------------------------------------------------------------
+// Step 3 — Pick a tier
+// ---------------------------------------------------------------------------
+
+type TierKey = "pro" | "pro-annual" | "team" | "team-annual";
+
+interface TierOption {
+  key: TierKey;
+  label: string;
+}
+
+const TIER_OPTIONS: TierOption[] = [
+  { key: "pro",         label: "Pro  ·  $12/mo" },
+  { key: "pro-annual",  label: "Pro  ·  $120/yr  (save 17%)" },
+  { key: "team",        label: "Team ·  $24/user/mo" },
+  { key: "team-annual", label: "Team ·  $240/user/yr  (save 17%)" },
+];
+
+async function pickTier(flags: Flags): Promise<TierKey> {
+  // If fully specified by flags, skip interactive prompt
+  if (flags.tier) {
+    const key: TierKey = flags.annual
+      ? `${flags.tier}-annual`
+      : flags.tier;
+    const opt = TIER_OPTIONS.find((o) => o.key === key);
+    if (opt) {
+      info(`Using tier: ${opt.label}`);
+      return key;
+    }
+  }
+
+  print("");
+  TIER_OPTIONS.forEach((o, i) => {
+    const isDefault = i === 0;
+    print(`  ${BOLD}${i + 1}${RESET})  ${o.label}${isDefault ? DIM + "  [default]" + RESET : ""}`);
+  });
+  print("");
+
+  let choice: string;
+  try {
+    choice = await prompt("[ASHLR_PROMPT: Choose a plan (1-4, default 1):]");
+  } catch {
+    choice = "1";
+  }
+
+  const idx = parseInt(choice || "1", 10) - 1;
+  if (idx < 0 || idx >= TIER_OPTIONS.length) {
+    info("Invalid selection — defaulting to Pro monthly.");
+    return "pro";
+  }
+  return TIER_OPTIONS[idx]!.key;
+}
+
+// ---------------------------------------------------------------------------
+// Step 4 — Open checkout
+// ---------------------------------------------------------------------------
+
+async function openCheckout(tier: TierKey, token: string): Promise<void> {
+  const isTeam = tier.startsWith("team");
+
+  let seats = 1;
+  if (isTeam) {
+    let seatsStr: string;
+    try {
+      seatsStr = await prompt("[ASHLR_PROMPT: How many seats (default 3):]");
+    } catch {
+      seatsStr = "3";
+    }
+    seats = Math.max(1, parseInt(seatsStr || "3", 10) || 3);
+  }
+
+  const res = await apiFetch("/billing/checkout", {
+    method: "POST",
+    body: { tier, seats },
+    token,
+  });
+
+  if (!res.ok) {
+    const d = res.data as { error?: string };
+    throw new Error(d.error ?? `Checkout failed (HTTP ${res.status})`);
+  }
+
+  const d = res.data as { url?: string; trial?: { days?: number } | null };
+  if (!d.url) throw new Error("No checkout URL returned from server.");
+
+  if (d.trial?.days && d.trial.days > 0) {
+    info(
+      `First-time upgrade: ${d.trial.days}-day free trial included. ` +
+        `No card charged until day ${d.trial.days}; cancel anytime before then.`,
+    );
+  }
+
+  await openBrowser(d.url);
+}
+
+// ---------------------------------------------------------------------------
+// Step 5 — Poll for activation
+// ---------------------------------------------------------------------------
+
+async function pollActivation(token: string): Promise<boolean> {
+  info("Polling for payment confirmation (up to 10 minutes)...");
+  const stopDots = startDots("  Waiting");
+  const deadline = Date.now() + BILLING_POLL_TIMEOUT_MS;
+
+  try {
+    while (Date.now() < deadline) {
+      await sleep(BILLING_POLL_INTERVAL_MS);
+      try {
+        const res = await apiFetch("/billing/status", { token });
+        if (res.ok) {
+          const d = res.data as { tier?: string };
+          if (d.tier === "pro" || d.tier === "team") {
+            stopDots();
+            return true;
+          }
+        }
+      } catch {
+        // keep polling
+      }
+    }
+  } finally {
+    stopDots();
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function printActivationSuccess(
+  tier: string,
+  opts: { trialEndsAt?: string | null } = {},
+): void {
+  const tierLabel = tier.charAt(0).toUpperCase() + tier.slice(1);
+  const trialSuffix = opts.trialEndsAt
+    ? ` (trial ends ${new Date(opts.trialEndsAt).toLocaleDateString()})`
+    : "";
+  print("");
+  print(`${GREEN}${BOLD}  ✓ Pro activated! Plan: ${tierLabel}${trialSuffix}${RESET}`);
+  print(`  Your API token is saved locally. All Pro features are unlocked.`);
+  print("");
+  print(`  What just changed:`);
+  print(`  - Hosted LLM summarizer — Ollama not required`);
+  print(`  - Cross-machine stats sync`);
+  print(`  - Leaderboard participation`);
+  print(`  - Priority support at support@ashlr.ai`);
+  print("");
+  print(`${DIM}  Next: run /ashlr-dashboard to see your usage.${RESET}`);
+  print("");
+}
+
+// ---------------------------------------------------------------------------
+// Main flow
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<number> {
+  const flags = parseArgs();
+  const totalSteps = 5;
+
+  // Record the click as early as possible — before any network I/O — so even
+  // an aborted run still counts toward conversion. Correlates to the most
+  // recent nudge_shown in the same session (within 30 min). Fire-and-forget.
+  void recordNudgeClicked({}).catch(() => {});
+  maybeSyncNudgeEvents();
+
+  banner();
+
+  // ── Step 1: Check current tier ──────────────────────────────────────────
+  step(1, totalSteps, "Checking current tier");
+
+  let token: string | null = null;
+  let currentTier = "free";
+
+  const existing = await checkCurrentTier();
+  if (existing) {
+    token = existing.token;
+    currentTier = existing.tier;
+  }
+
+  if (currentTier === "pro" || currentTier === "team") {
+    ok(`You're already on ${currentTier.charAt(0).toUpperCase() + currentTier.slice(1)}.`);
+    info("Run /ashlr-dashboard to see usage.");
+    return 0;
+  }
+
+  ok(currentTier === "free" && token ? "Authenticated as free user." : "Not signed in yet.");
+
+  // ── Step 2: Sign in if needed ────────────────────────────────────────────
+  if (!token) {
+    step(2, totalSteps, "Sign in");
+
+    try {
+      token = await pickAuthMethod(flags.email);
+    } catch (err) {
+      warn(err instanceof Error ? err.message : String(err));
+      return 1;
+    }
+
+    // Persist token
+    saveToken(token);
+    await writeEnvFile(token);
+    process.env["ASHLR_PRO_TOKEN"] = token;
+    ok("Token saved to ~/.ashlr/pro-token and ~/.ashlr/env (auto-loaded on next session).");
+  } else {
+    step(2, totalSteps, "Sign in");
+    ok("Already authenticated — skipping sign-in.");
+  }
+
+  // ── Step 3: Pick a tier ──────────────────────────────────────────────────
+  step(3, totalSteps, "Choose your plan");
+
+  let chosenTier: TierKey;
+  try {
+    chosenTier = await pickTier(flags);
+  } catch (err) {
+    warn(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  ok(`Selected: ${TIER_OPTIONS.find((o) => o.key === chosenTier)?.label ?? chosenTier}`);
+
+  // ── Step 4: Open checkout ────────────────────────────────────────────────
+  step(4, totalSteps, "Open Stripe checkout");
+
+  try {
+    await openCheckout(chosenTier, token);
+  } catch (err) {
+    warn(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  // ── Step 5: Poll for activation ──────────────────────────────────────────
+  if (flags.noPoll) {
+    step(5, totalSteps, "Activate Pro");
+    info("--no-poll set — skipping activation check.");
+    return 0;
+  }
+
+  step(5, totalSteps, "Waiting for payment confirmation");
+
+  const activated = await pollActivation(token);
+
+  if (activated) {
+    // Validate the token to get the real tier + trial info, and seed the cache
+    // so the user doesn't have to wait for a network round-trip on next launch.
+    let finalTier = "pro";
+    let trialEndsAt: string | null = null;
+    try {
+      const validation = await validateProToken();
+      if (validation.valid && validation.plan) {
+        finalTier = validation.plan;
+        trialEndsAt = validation.trialEndsAt ?? null;
+      }
+    } catch { /* fall back to billing/status */ }
+
+    if (!trialEndsAt) {
+      try {
+        const r = await apiFetch("/billing/status", { token });
+        if (r.ok) {
+          const d = r.data as { tier?: string; trialEndsAt?: string | null };
+          finalTier = d.tier ?? finalTier;
+          trialEndsAt = d.trialEndsAt ?? null;
+        }
+      } catch { /* use defaults */ }
+    }
+
+    printActivationSuccess(finalTier, { trialEndsAt });
+  } else {
+    print("");
+    warn("Haven't detected payment yet.");
+    info("Once you complete checkout, run /ashlr-upgrade again to verify and activate.");
+    print("");
+  }
+
+  return 0;
+}
+
+if (import.meta.main) {
+  main().then((code) => process.exit(code)).catch((err) => {
+    process.stderr.write(`upgrade-flow: fatal — ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  });
+}