@sun-asterisk/sungen 3.2.3 → 3.2.5

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;
+  }
+}

package/src/tools/sungen-auth/pkce.ts

@@ -0,0 +1,27 @@
+/**
+ * PKCE-S256 + correlation generation for the CLI login flow.
+ *
+ * The backend mandates S256 (plain is rejected). The verifier never leaves the
+ * process except inside the server-to-server `exchange` POST; the challenge is
+ * what travels to the browser side.
+ */
+
+import { randomBytes, createHash } from 'crypto';
+import type { PkceMaterial } from './sungen-auth-types';
+
+/** base64url with padding stripped, per RFC 7636 §A. */
+function base64url(buf: Buffer): string {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Generate a fresh PKCE verifier + S256 challenge pair. */
+export function generatePkce(): PkceMaterial {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash('sha256').update(verifier).digest());
+  return { verifier, challenge };
+}
+
+/** Random opaque value used to bind the loopback callback to this attempt (CSRF guard). */
+export function randomCorrelation(): string {
+  return randomBytes(16).toString('hex');
+}

package/src/tools/sungen-auth/sungen-auth-types.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared types for the sungen CLI login flow (RFC 8252 native-app login against
+ * a FastSchema v0.13.0 backend: PKCE-S256 + loopback redirect + one-time code).
+ */
+
+/** Persisted, user-level credentials at ~/.sungen/credentials.json (mode 0600). */
+export interface Credentials {
+  /** Bearer JWT minted by the backend exchange step. */
+  token: string;
+  /** Authenticated account email (from /api/auth/me). */
+  email: string;
+  /** Backend base URL the token was issued against (so `feedback` knows where to POST). */
+  api_base_url: string;
+  /** Unix epoch seconds when the token expires, if the backend reports it (single token, no refresh). */
+  expires_at?: number;
+}
+
+/** Response of POST /api/auth/cli/initiate (unwrapped from the {data} envelope). */
+export interface InitiateResponse {
+  /** Signed carrier the dashboard login page consumes. */
+  carrier: string;
+  /** Path (not absolute) to open in the browser, e.g. /dash/login?cli=<carrier>. */
+  authorize_url: string;
+}
+
+/** Response of POST /api/auth/exchange (unwrapped from the {data} envelope). */
+export interface ExchangeResponse {
+  /** Bearer JWT. */
+  token: string;
+  /** ISO expiry string the backend returns (e.g. "2026-07-08T06:42:30Z"). */
+  expires?: string;
+  /** Numeric epoch-seconds expiry, if a build reports it instead. */
+  expires_at?: number;
+}
+
+/** Response of GET /api/auth/me (subset we rely on, unwrapped from {data}). */
+export interface MeResponse {
+  email: string;
+}
+
+/** PKCE material generated per login attempt; never persisted to disk. */
+export interface PkceMaterial {
+  verifier: string;
+  challenge: string;
+}