@sun-asterisk/sungen 3.2.3 → 3.2.4

package/src/orchestrator/templates/ai-src/commands/locale.md

@@ -1,8 +1,8 @@
 ---
-description: "Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright, generate test-data overlay so `sungen:run-test --env <locale>` works."
+description: "Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright (web) or device locale (mobile), generate test-data overlay so `sungen:run-test --env <locale>` works."
 argument-hint: "<name> <locale> [--base-locale <code>] [--offline]"
 order: 45
-claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_click, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state"
+claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_click, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state, mcp__appium-mcp__select_device, mcp__appium-mcp__appium_session_management, mcp__appium-mcp__appium_get_page_source, mcp__appium-mcp__appium_screenshot, mcp__appium-mcp__generate_locators"
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*]"
 codex-trigger: "Run when the user asks to bootstrap i18n/localization for a screen. Runs before run-test --env <locale>."
 ---
@@ -33,6 +33,27 @@ Reject if name == locale (common typo).
 Reject if name == locale.
 {{/cap}}
 
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → switch to the **mobile path** (below).
+- If `platform: web` or field absent → follow the **web path** (existing behavior below, unchanged).
+
+### Mobile path
+
+When `platform: mobile`, mobile follows the **device locale** — there is no URL prefix, query param, or browser-storage mechanism to detect. Key differences from web (full detail in the `sungen-locale` skill):
+
+- **Live capture**: use **Appium MCP** (`select_device` → `appium_session_management(create)` with the device at base locale → `appium_get_page_source` / `appium_screenshot`) — not Playwright browser tools.
+- **Locale-switch mechanism**: `appium:language` / `appium:locale` capabilities + `noReset:false`, resolved automatically at runtime by `wdio.conf.ts`'s `resolveLocaleCaps()`. No fixture files needed.
+- **Phases skipped**: 3.5/3.6 (browser storage diff/verify) and 6d/6f (Pages URL update, locale-config.json) are web-only — skip them. Phase 6 (mobile) writes only selectors `{{var}}`, the base `test-data/<feature>.yaml`, and the overlay `test-data/<feature>.<locale>.yaml`.
+- **Compile**: `sungen generate --screen <name>` (the Appium adapter auto-selects for a mobile project).
+- **Hand-off**: after a locale run, print `SUNGEN_ENV=<locale> npm run test:mobile` (or the `--flow` equivalent). If the device's locale code differs from the overlay's env name, set `SUNGEN_LOCALE=<code>` — `resolveLocaleCaps()` reads it as an override.
+- **Reset after a locale run**: run once with `SUNGEN_LOCALE=en npm run test:mobile` to bring the device/app back to the base language before the next non-locale run.
+- **iOS data-wipe**: `wdio.conf.ts`'s `beforeSession` hook already wipes the app's data container on iOS before any locale run (XCUITest's `noReset:false` alone doesn't clear a persisted in-app language). If an older mobile project's `wdio.conf.ts` predates this hook and iOS keeps the previous language, re-run `sungen init --mobile` to refresh it.
+
+Stop here for mobile — do not continue to the web path below. Everything else (the 7-phase strategy, selector/test-data output shape, `{{var}}` overlay pattern) matches web; see the `sungen-locale` skill for the full mobile phase table.
+
 ## Auto-detect context
 
 Same as `/sungen:run-test`:
@@ -114,10 +135,11 @@ Offer the user:
 {{#cap parallel-subagents}}
 - Do NOT run tests yourself. `/sungen:run-test` is the executor. This command only PREPS files.
 - Do NOT modify `.feature` files. Localization happens entirely through `selectors/*.yaml` + `test-data/*.yaml`.
-- Auth blocker on SAA staging? Use `--offline`. See [[saa-auth-blocker]] memory.
+- Auth blocker on SAA staging (web)? Use `--offline`. See [[saa-auth-blocker]] memory.
+- Mobile device/emulator unreachable? Use `--offline` — same fallback as web.
 {{/cap}}
 {{^cap parallel-subagents}}
 - Do NOT run tests yourself. `/sungen:run-test` is the executor; this command only PREPS files.
 - Do NOT modify `.feature` files. Localization lives in `selectors/*.yaml` + `test-data/*.yaml` only.
-- Auth blocked? Use `--offline`.
+- Auth blocked (web)? Use `--offline`. Mobile device unreachable? Same fallback.
 {{/cap}}

package/src/orchestrator/templates/ai-src/skills/sungen-delivery/SKILL.md

@@ -78,19 +78,20 @@ The CLI reads the **per-target result file first** (co-located with `.spec.ts`),
 
 ---
 
-## XLSX sheets — Auto / Manual split
+## XLSX sheets — Overview + Auto / Manual split
 
-The `.xlsx` is split into two sheets so QA manages the sets separately:
+The `.xlsx` leads with an **`Overview`** roll-up sheet, then splits the test cases into detail sheets so QA manages the sets separately:
+- **`Overview`** — first sheet. Same masthead (Sun\* logo, `<SCREEN> TESTCASE` title, No/Version/Issue-Date, ISO band) as the others, then a summary table: one row per following sheet with `# · Sheet name · Passed · Failed · Pending · N/A · Remain · Total`, plus a grand-total row. `Remain = Total − Passed − N/A` (i.e. Failed + Pending), reconciling with each detail sheet's own summary band.
 - **`Auto`** — automatable test cases (`Auto` + `Not compiled`).
 - **`Manual`** — `@manual` test cases (always present, header-only when there are none).
 
-Multi-locale (no `SUNGEN_ENV`): one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual.
+Multi-locale (no `SUNGEN_ENV`): `Overview` + one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual. The Overview lists every detail sheet, so each locale's counts appear on its own row.
 
 ---
 
 ## API delivery — extra worksheet
 
-For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a third worksheet **`API detail`** (appended after Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
+For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a final worksheet **`API detail`** (appended after Overview/Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
 
 ### Required sources (API detail sheet only)
 

package/src/orchestrator/templates/wdio.conf.ts

@@ -25,6 +25,7 @@ import dotenv from 'dotenv';
 dotenv.config({ path: '.env.appium' });
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { execSync } from 'node:child_process';
 import PwShapeReporter from './specs/reporters/pw-shape-reporter';
 
 /**
@@ -104,13 +105,34 @@ const RUN_ANDROID = MOBILE_PLATFORM === 'android' || MOBILE_PLATFORM === 'both';
 const RUN_IOS = MOBILE_PLATFORM === 'ios' || MOBILE_PLATFORM === 'both';
 const IOS_APP = process.env.IOS_APP;
 const IOS_BUNDLE_ID = process.env.IOS_BUNDLE_ID || '__IOS_BUNDLE_ID__';
-const IOS_DEVICE = process.env.IOS_DEVICE || '__IOS_DEVICE__';
-const IOS_VERSION = process.env.IOS_VERSION || '__IOS_VERSION__';
+const IOS_UDID = process.env.IOS_UDID;
+// When a specific Simulator is targeted by IOS_UDID, XCUITest uses THAT device and IGNORES the
+// deviceName/platformVersion caps — so a stale IOS_DEVICE/IOS_VERSION would MISLABEL the deliverable's
+// "Test Environment". Resolve the real device name + iOS runtime from the UDID via simctl so the caps
+// (and the reporter's label) reflect reality. Explicit IOS_DEVICE/IOS_VERSION still win; on a real
+// device / non-mac, simctl fails → fall back to the provided/scaffold values.
+function resolveSimDevice(udid: string): { name?: string; version?: string } {
+  try {
+    const data = JSON.parse(execSync('xcrun simctl list devices --json', { encoding: 'utf-8' })) as {
+      devices?: Record<string, Array<{ udid: string; name: string }>>;
+    };
+    for (const [runtime, devs] of Object.entries(data.devices || {})) {
+      const hit = devs.find((d) => d.udid === udid);
+      if (hit) {
+        const vm = /iOS-(\d+)-(\d+)/.exec(runtime); // com.apple.CoreSimulator.SimRuntime.iOS-26-3
+        return { name: hit.name, version: vm ? `${vm[1]}.${vm[2]}` : undefined };
+      }
+    }
+  } catch { /* simctl unavailable (real device / non-mac) → keep provided values */ }
+  return {};
+}
+const IOS_SIM = IOS_UDID ? resolveSimDevice(IOS_UDID) : {};
+const IOS_DEVICE = process.env.IOS_DEVICE || IOS_SIM.name || '__IOS_DEVICE__';
+const IOS_VERSION = process.env.IOS_VERSION || IOS_SIM.version || '__IOS_VERSION__';
 // platformVersion is OPTIONAL on a real device: with IOS_UDID set, XCUITest reads the iOS version off
 // the connected device. Only pass the cap when IOS_VERSION is a real value (not the unfilled scaffold
 // placeholder). On a Simulator set it (or IOS_DEVICE) so Appium picks a matching runtime.
 const HAS_REAL_IOS_VERSION = !!IOS_VERSION && IOS_VERSION !== '__IOS_VERSION__';
-const IOS_UDID = process.env.IOS_UDID;
 // Real iPhone (device) — WebDriverAgent must be code-signed onto it. Set IOS_TEAM_ID (your Apple
 // Team ID) to switch the iOS cap into real-device mode; the Simulator ignores these (they're only
 // emitted when IOS_TEAM_ID is present, so Simulator runs are unchanged). For a real device also set
@@ -208,6 +230,13 @@ export const config: WebdriverIO.Config = {
           {
             platformName: 'iOS',
             'appium:automationName': 'XCUITest',
+            // Flutter apps NEVER report "idle" to XCUITest, so WDA always waits the FULL
+            // waitForIdleTimeout before EVERY interaction. The default (~10s) makes gesture
+            // loops blow the mocha timeout; 0 removes the wait entirely but then taps fire
+            // mid-transition/mid-launch and randomly miss (measured: ~2 flaky scenarios per
+            // run). 2s is the working balance — a universal settle that covers Flutter
+            // transitions while keeping bounded scroll/error paths well inside the budget.
+            'appium:waitForIdleTimeout': 2,
             'appium:deviceName': IOS_DEVICE,
             // Omit when unknown (real device, no IOS_VERSION) → XCUITest reads it from the device by udid.
             ...(HAS_REAL_IOS_VERSION ? { 'appium:platformVersion': IOS_VERSION } : {}),
@@ -253,6 +282,13 @@ export const config: WebdriverIO.Config = {
   mochaOpts: {
     ui: 'bdd',
     timeout: 120000,
+    // One retry per test: the relaunch-per-scenario pattern on a Flutter sim has a residual
+    // launch race (~10%/scenario — the first interaction can fire before the app routes
+    // touches), with a RANDOM victim each run. A retry re-runs the full beforeEach (fresh
+    // relaunch), so race victims recover on attempt 2 while real failures (wrong expected
+    // value, missing element) fail both attempts and still report Failed. The reporter and
+    // delivery already take the LAST attempt.
+    retries: 1,
   },
 
   // iOS + locale: XCUITest's `noReset:false` does NOT actually clear the app's data container

package/src/tools/sungen-api/edit-in-editor.ts

@@ -0,0 +1,48 @@
+/**
+ * Open the user's editor to compose feedback text, à la `git commit`.
+ *
+ * The feedback body is MARKDOWN, so the editor buffer is left completely
+ * untouched — no comment/instruction lines are injected or stripped (that would
+ * clobber markdown `#` headings). Guidance is printed to the terminal before the
+ * editor launches instead. Returns the trimmed body, or null when it is empty
+ * (caller treats that as "abort").
+ */
+
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+/** Resolve the editor command, mirroring git's precedence. */
+function resolveEditor(): string {
+  return (
+    process.env.VISUAL ||
+    process.env.EDITOR ||
+    (process.platform === 'win32' ? 'notepad' : 'vi')
+  );
+}
+
+/**
+ * Open the editor and return the composed feedback (verbatim, trimmed), or null
+ * if empty/aborted. Throws if the editor cannot be launched or exits non-zero.
+ */
+export function composeInEditor(): string | null {
+  const file = path.join(os.tmpdir(), `sungen-feedback-${process.pid}-${Date.now()}.md`);
+  fs.writeFileSync(file, '', 'utf8');
+  try {
+    const editor = resolveEditor();
+    console.error('Composing feedback in your editor (markdown supported). Save & close to submit; leave empty to abort.');
+    // shell:true so editors with args work (e.g. VISUAL="code --wait").
+    const result = spawnSync(`${editor} "${file}"`, { shell: true, stdio: 'inherit' });
+    if (result.error) throw new Error(`Could not launch editor "${editor}": ${result.error.message}`);
+    if (typeof result.status === 'number' && result.status !== 0) {
+      throw new Error(`Editor "${editor}" exited with code ${result.status}.`);
+    }
+    // Verbatim — only trim outer whitespace so markdown (headings, lists, code
+    // fences, HTML comments) is preserved exactly as written.
+    const body = fs.readFileSync(file, 'utf8').trim();
+    return body.length > 0 ? body : null;
+  } finally {
+    try { fs.unlinkSync(file); } catch { /* best effort */ }
+  }
+}

package/src/tools/sungen-api/feedback-client.ts

@@ -0,0 +1,62 @@
+/**
+ * Thin client for submitting product feedback to the FastSchema backend.
+ * Raw fetch (the fastschema npm SDK is browser/cookie-oriented and has no
+ * bearer-token content client). author is NEVER sent — the server stamps it.
+ */
+
+/** Thrown on 401 so the caller can prompt a re-login and retry once. */
+export class AuthExpiredError extends Error {
+  constructor(message = 'Authentication expired.') {
+    super(message);
+    this.name = 'AuthExpiredError';
+  }
+}
+
+export interface FeedbackPayload {
+  content: string;
+  category: string;
+  sungen_version?: string;
+  os?: string;
+  source: string;
+}
+
+function normalizeBase(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+/**
+ * POST one feedback record. Returns the created row id.
+ * @throws AuthExpiredError on 401; Error (scrubbed) on any other non-2xx.
+ */
+export async function submitFeedback(
+  apiBaseUrl: string,
+  token: string,
+  payload: FeedbackPayload,
+): Promise<{ id: number | string }> {
+  let res: Response;
+  try {
+    res = await fetch(`${normalizeBase(apiBaseUrl)}/api/content/feedback`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(payload),
+    });
+  } catch (err: any) {
+    throw new Error(`Network error reaching the feedback backend: ${err?.message ?? 'unknown'}`);
+  }
+
+  if (res.status === 401) throw new AuthExpiredError();
+  if (!res.ok) {
+    // Scrub the body — never echo a raw server error that might carry internals.
+    throw new Error(`Feedback submission failed (HTTP ${res.status}).`);
+  }
+
+  const body = (await res.json().catch(() => ({}))) as any;
+  // FastSchema content create returns the row (id at top level or under .data).
+  // Only accept an actual id value — never fall back to the whole object (would
+  // print "[object Object]").
+  const id = body?.id ?? body?.data?.id ?? 'unknown';
+  return { id };
+}

package/src/tools/sungen-api/read-stdin.ts

@@ -0,0 +1,15 @@
+/**
+ * Read piped stdin to a string. Returns null when stdin is a TTY (interactive),
+ * so callers can distinguish "no piped input" from "empty pipe".
+ */
+
+export function readStdin(): Promise<string | null> {
+  if (process.stdin.isTTY) return Promise.resolve(null);
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}

package/src/tools/sungen-auth/api-base-url.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolves the feedback backend base URL with a fixed precedence so `login` and
+ * `feedback` agree on where to talk.
+ *
+ * Precedence: explicit flag > SUNGEN_API_BASE_URL env > stored credential's
+ * api_base_url > DEFAULT_API_BASE_URL.
+ *
+ * DEFAULT_API_BASE_URL is the deployed production host, so the common case needs
+ * no config; override via --api-base-url / SUNGEN_API_BASE_URL for dev/staging.
+ */
+
+import { loadCredentials } from './credentials-store';
+
+/** Deployed feedback backend (production). Override with SUNGEN_API_BASE_URL locally. */
+export const DEFAULT_API_BASE_URL = 'https://sungen.sun-asterisk.vn';
+
+export function resolveApiBaseUrl(flagValue?: string): string {
+  if (flagValue) return flagValue;
+  if (process.env.SUNGEN_API_BASE_URL) return process.env.SUNGEN_API_BASE_URL;
+  const stored = loadCredentials();
+  if (stored?.api_base_url) return stored.api_base_url;
+  return DEFAULT_API_BASE_URL;
+}

package/src/tools/sungen-auth/credentials-store.ts

@@ -0,0 +1,57 @@
+/**
+ * User-level credential storage at ~/.sungen/credentials.json.
+ *
+ * Deliberately user-scoped (not project-local like the Figma PAT in .env): the
+ * login token is tied to the person and works across every sungen project.
+ * File mode 0600, parent dir 0700 — the token is a bearer secret.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import type { Credentials } from './sungen-auth-types';
+
+const DIR_NAME = '.sungen';
+const FILE_NAME = 'credentials.json';
+
+/** Absolute path to the credentials file (~/.sungen/credentials.json). */
+export function credentialsPath(): string {
+  return path.join(os.homedir(), DIR_NAME, FILE_NAME);
+}
+
+/** Load stored credentials, or null when absent / unreadable / malformed. */
+export function loadCredentials(): Credentials | null {
+  try {
+    const raw = fs.readFileSync(credentialsPath(), 'utf8');
+    const parsed = JSON.parse(raw) as Credentials;
+    if (!parsed || typeof parsed.token !== 'string') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist credentials with restrictive permissions (dir 0700, file 0600). */
+export function saveCredentials(creds: Credentials): void {
+  const dir = path.join(os.homedir(), DIR_NAME);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const fp = credentialsPath();
+  // Write then chmod so an existing looser-mode file is tightened too.
+  fs.writeFileSync(fp, JSON.stringify(creds, null, 2), { mode: 0o600 });
+  fs.chmodSync(fp, 0o600);
+}
+
+/** Remove the credentials file; no-op when absent. */
+export function clearCredentials(): void {
+  try {
+    fs.unlinkSync(credentialsPath());
+  } catch {
+    /* already gone */
+  }
+}
+
+/** True when the credential carries an expiry that is already past (no refresh token — prompt re-login on expiry). */
+export function isExpired(creds: Credentials): boolean {
+  if (typeof creds.expires_at !== 'number') return false;
+  return creds.expires_at * 1000 <= Date.now();
+}

package/src/tools/sungen-auth/login-flow.ts

@@ -0,0 +1,135 @@
+/**
+ * The 6-call RFC 8252 CLI login flow against FastSchema v0.13.0.
+ *
+ * Base path is /api/auth (verified live against the running v0.13.0 server;
+ * the earlier /api/user/auth contract was wrong). PKCE-S256 + single-use
+ * one-time code; the JWT is minted server-side
+ * and only delivered via the server-to-server `exchange` — it never appears in
+ * the browser. This module does NO disk I/O so it stays unit-testable.
+ */
+
+import type {
+  ExchangeResponse,
+  InitiateResponse,
+  MeResponse,
+  PkceMaterial,
+} from './sungen-auth-types';
+
+export interface LoginFlowDeps {
+  apiBaseUrl: string;
+  pkce: PkceMaterial;
+  correlation: string;
+  redirectUri: string;
+  /** Open the authorize URL; return false to trigger the manual-paste fallback. */
+  openBrowser: (url: string) => boolean;
+  /** Resolve with the one-time code once the loopback callback fires. */
+  waitForCode: (correlation: string, timeoutMs?: number) => Promise<string>;
+  /** Optional sink for user-facing progress lines (defaults to console.log). */
+  log?: (msg: string) => void;
+}
+
+export interface LoginResult {
+  token: string;
+  email: string;
+  expires_at?: number;
+}
+
+/** Strip a trailing slash so path joins never double up. */
+function normalizeBase(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+async function postJson<T>(url: string, body: unknown): Promise<{ ok: boolean; status: number; data: T | null }> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  } catch (err: any) {
+    throw new Error(`Network error reaching ${url}: ${err?.message ?? 'unknown'}`);
+  }
+  let data: T | null = null;
+  try {
+    const json: any = await res.json();
+    // FastSchema wraps success payloads in { data: ... } and errors in { error: ... }.
+    data = (json && json.data !== undefined ? json.data : json) as T;
+  } catch {
+    /* non-JSON body */
+  }
+  return { ok: res.ok, status: res.status, data };
+}
+
+/**
+ * Run the full login flow. Throws with a clear, distinct message for each
+ * failure mode (feature-off, missing challenge, exchange-401, etc.).
+ */
+export async function runLoginFlow(deps: LoginFlowDeps): Promise<LoginResult> {
+  const base = normalizeBase(deps.apiBaseUrl);
+  const log = deps.log ?? ((m: string) => console.log(m));
+
+  // 1. initiate — exchange PKCE challenge + loopback redirect for a carrier.
+  const init = await postJson<InitiateResponse>(`${base}/api/auth/cli/initiate`, {
+    redirect_uri: deps.redirectUri,
+    correlation: deps.correlation,
+    code_challenge: deps.pkce.challenge,
+  });
+  if (init.status === 403) {
+    throw new Error('CLI login is disabled on the server (AUTH_CLI_LOGIN_ENABLED=false).');
+  }
+  if (init.status === 400) {
+    throw new Error('Server rejected the login request (missing/invalid PKCE challenge or redirect).');
+  }
+  if (!init.ok || !init.data?.authorize_url) {
+    throw new Error(`Login initiate failed (HTTP ${init.status}).`);
+  }
+
+  // 2. open the dashboard login page (authorize_url is a path → join with base).
+  const authorizeUrl = `${base}${init.data.authorize_url}`;
+  // Always print the URL: openBrowser reports success even when the launcher
+  // fails asynchronously (e.g. headless box with no xdg-open), so the paste
+  // path must stay visible regardless.
+  const opened = deps.openBrowser(authorizeUrl);
+  if (opened) {
+    log(`Opened your browser to complete login. Waiting…\nIf it didn't open, visit:\n  ${authorizeUrl}`);
+  } else {
+    log(`Open this URL in your browser to continue login:\n  ${authorizeUrl}`);
+  }
+
+  // 3. wait for the loopback callback (asserts state===correlation inside).
+  const code = await deps.waitForCode(deps.correlation);
+
+  // 4. exchange the one-time code + verifier for the JWT.
+  const exch = await postJson<ExchangeResponse>(`${base}/api/auth/exchange`, {
+    code,
+    code_verifier: deps.pkce.verifier,
+  });
+  if (exch.status === 401) {
+    throw new Error('Token exchange rejected (code expired or verifier mismatch). Try `sungen login` again.');
+  }
+  if (!exch.ok || !exch.data?.token) {
+    throw new Error(`Token exchange failed (HTTP ${exch.status}).`);
+  }
+  const token = exch.data.token;
+  // Backend reports expiry as an ISO `expires` string; accept a numeric
+  // `expires_at` epoch too. Absent → rely on 401-on-expiry (single token, no refresh).
+  const expires_at =
+    exch.data.expires_at ??
+    (exch.data.expires ? Math.floor(Date.parse(exch.data.expires) / 1000) : undefined);
+
+  // 5. confirm identity (Bearer) and capture the email.
+  let me: Response;
+  try {
+    me = await fetch(`${base}/api/auth/me`, { headers: { Authorization: `Bearer ${token}` } });
+  } catch (err: any) {
+    throw new Error(`Network error confirming identity: ${err?.message ?? 'unknown'}`);
+  }
+  if (!me.ok) {
+    throw new Error(`Logged in but identity check failed (HTTP ${me.status}).`);
+  }
+  const meJson: any = await me.json();
+  const meBody = (meJson && meJson.data !== undefined ? meJson.data : meJson) as MeResponse;
+
+  return { token, email: meBody.email, expires_at };
+}

package/src/tools/sungen-auth/loopback-server.ts

@@ -0,0 +1,113 @@
+/**
+ * Single-shot loopback HTTP listener for the CLI login redirect.
+ *
+ * Binds 127.0.0.1 on an ephemeral port, waits for exactly one
+ * GET /callback?code=<otc>&state=<correlation>, asserts state===correlation
+ * (CSRF guard), shows a "you may close this tab" page, then closes.
+ */
+
+import * as http from 'http';
+import { AddressInfo, Socket } from 'net';
+
+export interface Loopback {
+  /** The ephemeral port the listener bound to. */
+  port: number;
+  /** Full redirect_uri to hand to the backend (http://127.0.0.1:<port>/callback). */
+  redirectUri: string;
+  /** Resolve with the one-time code once the browser hits /callback; reject on timeout/mismatch. */
+  waitForCode(correlation: string, timeoutMs?: number): Promise<string>;
+  /** Force-close the listener (idempotent). */
+  close(): void;
+}
+
+const CLOSE_PAGE =
+  '<!doctype html><meta charset="utf-8"><title>sungen login</title>' +
+  '<body style="font-family:system-ui;padding:3rem;text-align:center">' +
+  '<h2>Login complete</h2><p>You may close this tab and return to the terminal.</p></body>';
+
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+/** Start the loopback listener. Resolves once it is bound and ready. */
+export function startLoopback(): Promise<Loopback> {
+  return new Promise((resolve, reject) => {
+    let resolveCode: ((code: string) => void) | null = null;
+    let rejectCode: ((err: Error) => void) | null = null;
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+      if (url.pathname !== '/callback') {
+        res.writeHead(404, { Connection: 'close' }).end('not found');
+        return;
+      }
+      // Connection: close so the browser doesn't hold a keep-alive socket open —
+      // otherwise server.close() would never fire and the CLI would hang after login.
+      res.writeHead(200, { 'Content-Type': 'text/html', Connection: 'close' }).end(CLOSE_PAGE);
+      const code = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+      // Hand the parsed values to the pending waitForCode promise.
+      pending = { code, state };
+      drain();
+    });
+
+    // Track live sockets so shutdown() can destroy any keep-alive stragglers.
+    const sockets = new Set<Socket>();
+    server.on('connection', (s) => {
+      sockets.add(s);
+      s.on('close', () => sockets.delete(s));
+    });
+
+    /** Close the server AND destroy lingering sockets so the event loop can drain. */
+    function shutdown(): void {
+      if (server.listening) server.close();
+      for (const s of sockets) s.destroy();
+      sockets.clear();
+    }
+
+    // Buffer the callback result until a waiter (with its correlation) arrives.
+    let pending: { code: string | null; state: string | null } | null = null;
+    let expectedCorrelation: string | null = null;
+
+    function drain(): void {
+      if (!pending || !resolveCode || !rejectCode || expectedCorrelation == null) return;
+      const { code, state } = pending;
+      if (state !== expectedCorrelation) {
+        rejectCode(new Error('Login state mismatch — possible CSRF; aborting.'));
+      } else if (!code) {
+        rejectCode(new Error('Login callback missing authorization code.'));
+      } else {
+        resolveCode(code);
+      }
+      // Let the response flush first, then tear everything down.
+      setImmediate(shutdown);
+    }
+
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const port = (server.address() as AddressInfo).port;
+      resolve({
+        port,
+        redirectUri: `http://127.0.0.1:${port}/callback`,
+        waitForCode(correlation, timeoutMs = DEFAULT_TIMEOUT_MS) {
+          expectedCorrelation = correlation;
+          return new Promise<string>((res, rej) => {
+            resolveCode = res;
+            rejectCode = rej;
+            const timer = setTimeout(() => {
+              shutdown();
+              rej(new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for browser login.`));
+            }, timeoutMs);
+            timer.unref?.();
+            // Wrap to always clear the timer.
+            const origRes = resolveCode, origRej = rejectCode;
+            resolveCode = (c) => { clearTimeout(timer); origRes!(c); };
+            rejectCode = (e) => { clearTimeout(timer); origRej!(e); };
+            drain();
+          });
+        },
+        close() {
+          shutdown();
+        },
+      });
+    });
+  });
+}

package/src/tools/sungen-auth/open-browser.ts

@@ -0,0 +1,42 @@
+/**
+ * Cross-platform "open this URL in the default browser" helper.
+ *
+ * Deliberately dependency-free — a small platform switch instead of pulling in
+ * the `open` npm package. Returns false on failure so the caller can fall back
+ * to printing the URL for manual paste.
+ */
+
+import { spawn } from 'child_process';
+
+/** Attempt to open `url` in the system browser. Returns true if a launcher was spawned. */
+export function openBrowser(url: string): boolean {
+  let command: string;
+  let args: string[];
+
+  switch (process.platform) {
+    case 'darwin':
+      command = 'open';
+      args = [url];
+      break;
+    case 'win32':
+      // `start` is a cmd builtin; the empty "" is the window-title placeholder.
+      command = 'cmd';
+      args = ['/c', 'start', '', url];
+      break;
+    default:
+      command = 'xdg-open';
+      args = [url];
+      break;
+  }
+
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    // A missing launcher fails asynchronously here, after we've already returned
+    // true; that's why callers also print the URL rather than relying on this.
+    child.on('error', () => { /* best-effort launch */ });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}