auriga-cli 1.15.1 → 1.16.0

package/README.md

@@ -50,6 +50,18 @@ npx -y auriga-cli --help                     # full catalog + flags
 
 Exit codes: `0` success, `1` fatal (precheck / parse / fetch), `2` partial success — `stderr` lists per-category `[OK]/[FAIL]` and a `Retry:` hint. After install, reload the Claude Code or Codex session so the new `CLAUDE.md` / skills / plugins / hook registrations are picked up.
 
+### Web UI (opt-in)
+
+For a browser-based view of what's installed and one-click apply, run:
+
+```bash
+npx auriga-cli web-ui
+```
+
+This boots a local server on `127.0.0.1`, opens your default browser, and serves a dashboard that scans the current project, shows each module's status (installed / update-available / not-installed), and applies install / update / uninstall in a queue with live SSE progress. The server shuts down on its own ~15 s after the browser closes.
+
+The UI is opt-in — `npx auriga-cli` still launches the TTY menu below.
+
 ### Interactive menu
 
 ```bash
@@ -99,6 +111,7 @@ Installs selected skills via `npx skills add`, targeting both Claude Code and Co
 | Skill | Source | Description |
 |---|---|---|
 | claude-code-agent | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | Delegate coding, review, diagnosis, and planning to standalone Claude Code sessions |
+| code-simplification | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | Refactor for clarity without changing behavior — trim accumulated complexity |
 | codex-agent | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | Delegate to Codex sessions for cross-model coverage |
 | design-taste-frontend | [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) | Senior UI/UX engineer with metric-based design rules and strict component architecture |
 | frontend-design | [anthropics/skills](https://github.com/anthropics/skills) | Distinctive, production-grade frontend UI generation that avoids generic AI aesthetics |

package/README.zh-CN.md

@@ -50,6 +50,18 @@ npx -y auriga-cli --help                     # 完整 catalog + flag 说明
 
 退出码：`0` 成功；`1` 致命错误（前置检查 / 解析 / 拉取失败）；`2` 部分成功——`stderr` 会列出逐类 `[OK]/[FAIL]` 和 `Retry:` 提示。装完后请重启 Claude Code 或 Codex 会话，让新的 `CLAUDE.md` / skills / plugins / hook 注册生效。
 
+### Web UI（可选）
+
+如果想在浏览器里看到“已装 / 可更新 / 未装”全景并一键 apply，跑：
+
+```bash
+npx auriga-cli web-ui
+```
+
+它会在 `127.0.0.1` 起一个本地 server、自动开浏览器，扫描当前项目并展示 5 个分类的状态。勾选要安装/更新/卸载的项目后点 Apply，SSE 实时回传执行进度。关浏览器后约 15 秒 server 自动退出。
+
+Web UI 是显式入口；`npx auriga-cli` 仍然走下面的 TTY 菜单。
+
 ### 交互式菜单
 
 ```bash
@@ -99,6 +111,7 @@ npx auriga-cli
 | Skill | 来源 | 说明 |
 |---|---|---|
 | claude-code-agent | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | 通过 Claude Code Agent SDK 把任务委派给独立 Claude Code 会话 |
+| code-simplification | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | 不改变行为前提下重构代码以提升可读性 —— 清掉累积的不必要复杂度 |
 | codex-agent | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | 委派给 Codex 会话，做跨模型覆盖 |
 | design-taste-frontend | [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) | 高阶 UI/UX 工程师 —— 度量化设计规则与严格的组件架构约束 |
 | frontend-design | [anthropics/skills](https://github.com/anthropics/skills) | 生成有辨识度、production 级的前端界面，避开常见 AI 同质化美学 |

package/dist/api-types.d.ts

@@ -0,0 +1,115 @@
+export type ItemStatus = "installed" | "update-available" | "not-installed";
+export interface StateReport {
+    /** Absolute path to the project the server was launched against. Surfaced
+     *  in the UI's top bar so users know where Apply will write project-scope
+     *  changes. The path may be redacted (e.g. `~/...` home expansion) but the
+     *  contract is "human-readable identifier for the current cwd". */
+    cwd: string;
+    workflow: WorkflowState;
+    skills: SkillState[];
+    recommendedSkills: SkillState[];
+    plugins: PluginState[];
+    hooks: HookState[];
+    warnings: StateWarning[];
+}
+export interface WorkflowState {
+    status: ItemStatus;
+    currentVersion?: string;
+    expectedVersion: string;
+}
+export interface SkillState {
+    name: string;
+    description: string;
+    status: ItemStatus;
+    isWorkflow: boolean;
+    currentHash?: string;
+    expectedHash: string;
+}
+export type ApplyAgent = "claude" | "codex";
+export interface PluginState {
+    id: string;
+    description: string;
+    status: ItemStatus;
+    /** Which Agent runtimes this plugin can install into. Most plugins target
+     *  a single agent; dual-Agent plugins (e.g. auriga-go) have both. When
+     *  `agents.length === 2` the UI shows a BOTH badge and Apply installs to
+     *  each agent in turn. Status is aggregated across all targeted agents:
+     *  `installed` ⇔ all agents installed; `not-installed` ⇔ all not-installed;
+     *  any partial state (one side installed, other not) → `update-available`
+     *  so a single Apply backfills the missing side. */
+    agents: ApplyAgent[];
+    currentVersion?: string;
+    expectedVersion?: string;
+    versionSource: "upstream-live" | "catalog";
+}
+export interface HookState {
+    name: string;
+    description: string;
+    status: ItemStatus;
+    currentHash?: string;
+    expectedHash: string;
+}
+export interface StateWarning {
+    code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline";
+    message: string;
+}
+export type ApplyCategory = "workflow" | "skill" | "recommended-skill" | "plugin" | "hook";
+export type ApplyAction = "install" | "update" | "uninstall";
+/**
+ * Installer scope. Carried per-item so the Web UI can mix scopes within a
+ * single apply batch.
+ *
+ * - workflow: no scope; field MUST be omitted.
+ * - skill / recommended-skill / plugin: "project" | "user". Default project.
+ * - hook: "project" | "user" for v0.1 (project-local deferred to v0.2).
+ */
+export type ApplyScope = "project" | "user";
+/**
+ * Workflow CLAUDE.md language variant.
+ *
+ * - "en":    English CLAUDE.md (the default).
+ * - "zh-CN": Simplified Chinese CLAUDE.md (the localized variant).
+ *
+ * Only meaningful for `category === "workflow"`; rejected for other
+ * categories so the API surface stays explicit.
+ */
+export type ApplyLang = "en" | "zh-CN";
+export interface ApplyItemRef {
+    category: ApplyCategory;
+    name: string;
+    action: ApplyAction;
+    /** Installer scope. Omitted = "project" (back-compat default). The server
+     *  rejects this field for category="workflow" because workflow has no
+     *  scope concept (it's a single file at the project root). */
+    scope?: ApplyScope;
+    /** Workflow CLAUDE.md language variant. Omitted = "en" (back-compat
+     *  default). The server rejects this field for any non-workflow
+     *  category. */
+    lang?: ApplyLang;
+}
+export interface ApplyRequest {
+    items: ApplyItemRef[];
+}
+export interface ApplyResponse {
+    jobId: string;
+}
+export type ProgressEvent = {
+    type: "item:start";
+    index: number;
+    total: number;
+    item: ApplyItemRef;
+} | {
+    type: "item:log";
+    index: number;
+    line: string;
+    level: "info" | "warn" | "error";
+} | {
+    type: "item:done";
+    index: number;
+    success: boolean;
+    error?: string;
+} | {
+    type: "all-done";
+    success: boolean;
+    failedCount: number;
+};

package/dist/api-types.js

@@ -0,0 +1,4 @@
+// Shared API types between server (src/server.ts) and the Web UI frontend
+// (ui/). All /api/* endpoints carry token + Origin auth. See spec
+// docs/architecture/web-ui.md §6.2 for the contract these types encode.
+export {};

package/dist/apply-handlers.d.ts

@@ -0,0 +1,17 @@
+import type { ApplyLang } from "./api-types.js";
+import type { ApplyHandlers } from "./server.js";
+export interface ApplyHandlerContext {
+    /** Where auriga-cli lives — source of skills-lock.json + .claude config. */
+    packageRoot: string;
+    /** Target project directory. Installers write here. */
+    cwd: string;
+    /** Resolves plugin name → the list of agents this plugin can install
+     *  into. Built at boot from the same scan catalog the /api/state route
+     *  uses. dual-Agent plugins (e.g. `auriga-go`) yield `["claude","codex"]`
+     *  and the handler iterates the list, installing to each agent in turn.
+     *  Names not in the map default to `["claude"]` (existing CLI default). */
+    pluginAgentsByName: Map<string, ("claude" | "codex")[]>;
+    /** Workflow language for install. Defaults to "en". */
+    workflowLang?: ApplyLang;
+}
+export declare function buildDefaultApplyHandlers(ctx: ApplyHandlerContext): ApplyHandlers;

package/dist/apply-handlers.js

@@ -0,0 +1,186 @@
+// Builds the default ApplyHandlers map that wires the Web UI's /api/apply
+// route to the real installers in workflow.ts / skills.ts / plugins.ts /
+// hooks.ts. Tests inject their own mock handlers; CLI mode (the `web-ui`
+// subcommand) calls `buildDefaultApplyHandlers` at boot.
+//
+// Per-item dispatch is layered on top of the existing bulk installers via
+// `opts.selected = [name]`. The recipe per category:
+//
+//   workflow:           installWorkflow(packageRoot, …) ─┐
+//   workflow:           uninstallWorkflow({force:true,…})│  no name needed
+//   skill:              installSkills(…, selected:[name])│
+//   skill:              uninstallSkill(name, …)          │
+//   recommended-skill:  installRecommendedSkills(…)      │
+//   recommended-skill:  uninstallSkill(name, …)          │  same store
+//   plugin:             installPlugins(…, agent, sel:[]) │  per-name
+//   plugin:             uninstallPlugin(name, agent, …)  │
+//   hook:               installHook(hookDef, "project",…)│  needs HookDef
+//   hook:               uninstallHook(name, …)           │
+//
+// Spec: docs/architecture/web-ui.md §6.4 (apply execution model).
+import { installHook, loadHooksConfig, uninstallHook } from "./hooks.js";
+import { installPlugins, uninstallPlugin, } from "./plugins.js";
+import { installRecommendedSkills, installSkills, uninstallSkill, } from "./skills.js";
+import { installWorkflow, uninstallWorkflow } from "./workflow.js";
+const ALL_ACTIONS = new Set([
+    "install",
+    "update",
+    "uninstall",
+]);
+function assertAction(action) {
+    // Defense in depth — the server validates the shape already, but the
+    // adapter must not silently fall through if a new action is added later.
+    if (!ALL_ACTIONS.has(action)) {
+        throw new Error(`unsupported action: ${action}`);
+    }
+}
+export function buildDefaultApplyHandlers(ctx) {
+    const { packageRoot, cwd, pluginAgentsByName } = ctx;
+    const lang = ctx.workflowLang ?? "en";
+    const workflow = async (action, _name, { onLog, lang: requestedLang }) => {
+        assertAction(action);
+        // Per-item lang overrides the ctx default (the UI now drives this via
+        // the Workflow column's EN/ZH-CN picker). Falls back to ctx lang for
+        // CLI-mode callers that don't pass it.
+        const installLang = requestedLang ?? lang;
+        if (action === "install" || action === "update") {
+            await installWorkflow(packageRoot, {
+                interactive: false,
+                cwd,
+                lang: installLang,
+            });
+            onLog(`workflow installed (${installLang})`, "info");
+            return;
+        }
+        // uninstall
+        await uninstallWorkflow({
+            force: true,
+            cwd,
+            onLog: (line) => onLog(line, "info"),
+        });
+    };
+    // Adapter from InstallOpts.onLog (stdout|stderr) → handler's onLog
+    // (info|warn|error). stderr lines surface as warnings; the SSE consumer
+    // can decide whether to render them differently.
+    const streamLog = (onLog) => (line, stream) => {
+        onLog(line, stream === "stderr" ? "warn" : "info");
+    };
+    const skill = async (action, name, { onLog, scope }) => {
+        assertAction(action);
+        const installScope = scope ?? "project";
+        if (action === "install" || action === "update") {
+            await installSkills(packageRoot, {
+                interactive: false,
+                cwd,
+                selected: [name],
+                scope: installScope,
+                onLog: streamLog(onLog),
+            });
+            onLog(`skill ${name} installed (${installScope})`, "info");
+            return;
+        }
+        await uninstallSkill(name, {
+            cwd,
+            scope: installScope,
+            onLog: (line) => onLog(line, "info"),
+        });
+    };
+    const recommendedSkill = async (action, name, { onLog, scope }) => {
+        assertAction(action);
+        const installScope = scope ?? "project";
+        if (action === "install" || action === "update") {
+            await installRecommendedSkills(packageRoot, {
+                interactive: false,
+                cwd,
+                selected: [name],
+                scope: installScope,
+                onLog: streamLog(onLog),
+            });
+            onLog(`recommended skill ${name} installed (${installScope})`, "info");
+            return;
+        }
+        // Uninstall path is the same regardless of workflow vs recommended —
+        // both live in skills-lock.json + .claude/skills/<name>.
+        await uninstallSkill(name, {
+            cwd,
+            scope: installScope,
+            onLog: (line) => onLog(line, "info"),
+        });
+    };
+    const plugin = async (action, name, { onLog, scope }) => {
+        assertAction(action);
+        const agents = pluginAgentsByName.get(name) ?? ["claude"];
+        const installScope = scope ?? "project";
+        // dual-Agent plugins (length === 2) install into each agent in turn.
+        // Per-agent try/catch: if Claude install fails, still try Codex so
+        // partial coverage is visible to the user. Failures are aggregated
+        // and thrown at the end → SSE marks the item failed but onLog
+        // shows both agent outcomes.
+        const failures = [];
+        for (const agent of agents) {
+            try {
+                if (action === "install" || action === "update") {
+                    await installPlugins(packageRoot, {
+                        interactive: false,
+                        cwd,
+                        agent,
+                        selected: [name],
+                        scope: installScope,
+                        onLog: streamLog(onLog),
+                    });
+                    onLog(`plugin ${name} installed (${agent}, ${installScope})`, "info");
+                }
+                else {
+                    await uninstallPlugin(name, agent, {
+                        cwd,
+                        onLog: (line) => onLog(`[${agent}] ${line}`, "info"),
+                    });
+                    onLog(`plugin ${name} uninstalled (${agent})`, "info");
+                }
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                failures.push({ agent, error });
+                onLog(`plugin ${name} ${action} failed (${agent}): ${error.message}`, "error");
+            }
+        }
+        if (failures.length > 0) {
+            const summary = failures
+                .map((f) => `${f.agent}: ${f.error.message}`)
+                .join("; ");
+            throw new Error(`plugin ${name} ${action} failed for ${failures.length} agent(s) — ${summary}`);
+        }
+    };
+    const hook = async (action, name, { onLog, scope }) => {
+        assertAction(action);
+        const installScope = scope ?? "project";
+        if (action === "uninstall") {
+            await uninstallHook(name, {
+                cwd,
+                scope: installScope,
+                onLog: (line) => onLog(line, "info"),
+            });
+            return;
+        }
+        // install + update both run installHook with the requested scope. The
+        // hook installer is idempotent — re-running == "update". Look up the
+        // HookDef in the bundled registry; unknown name → loud throw so the
+        // SSE caller surfaces it as item:done success=false.
+        const config = loadHooksConfig(packageRoot);
+        const hookDef = config.hooks.find((h) => h.name === name);
+        if (!hookDef) {
+            throw new Error(`hook not found in registry: ${name}`);
+        }
+        // installHook takes a wider Scope union ("project"|"user"|"project-local");
+        // v0.1 only exposes "project"|"user" via the API. Cast is safe.
+        await installHook(hookDef, scope ?? "project", cwd, packageRoot);
+        onLog(`hook ${name} installed (${scope ?? "project"})`, "info");
+    };
+    return {
+        workflow,
+        skill,
+        "recommended-skill": recommendedSkill,
+        plugin,
+        hook,
+    };
+}

package/dist/catalog.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-12T03:42:55.011Z",
+  "generatedAt": "2026-05-12T10:18:53.130Z",
   "workflowSkills": [
     {
       "name": "brainstorming",
@@ -43,6 +43,10 @@
       "name": "claude-code-agent",
       "description": "Delegate coding, review, diagnosis, planning, and structured-output tasks to an independent Claude Code session via `claude -p` (Agent SDK)."
     },
+    {
+      "name": "code-simplification",
+      "description": "Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity."
+    },
     {
       "name": "codex-agent",
       "description": "Delegate coding, review, diagnosis, planning, and browser tasks to an independent Codex session via `codex exec` / resume / review."

package/dist/cli.d.ts

@@ -11,6 +11,16 @@ export interface InstallParsed {
     scope?: "project" | "user";
     agent?: PluginAgent;
 }
+export interface UiParsed {
+    /** Override the default port (4747). When set, the fallback range is
+     *  also skipped — we either succeed on this port or fail. */
+    port?: number;
+    /** Override ui-fetch; serve from this local directory instead. Useful
+     *  for development against `ui/dist` without a release tag. */
+    uiDir?: string;
+    /** Skip opening the browser. Prints the URL only. */
+    noOpen?: boolean;
+}
 export type ParsedArgs = {
     command: "help";
     helpType?: CategoryName;
@@ -21,6 +31,9 @@ export type ParsedArgs = {
 } | {
     command: "install";
     install: InstallParsed;
+} | {
+    command: "web-ui";
+    ui: UiParsed;
 };
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -102,6 +102,16 @@ export function parseArgs(argv) {
         }
         return { command: "guide" };
     }
+    if (head === "web-ui") {
+        try {
+            return { command: "web-ui", ui: parseUi(argv.slice(1)) };
+        }
+        catch (e) {
+            if (e instanceof PerTypeHelpRequest)
+                return { command: "help" };
+            throw e;
+        }
+    }
     if (head !== "install") {
         parseErr(`unknown argument '${head}'. Run 'npx auriga-cli --help' for usage.`);
     }
@@ -115,6 +125,43 @@ export function parseArgs(argv) {
         throw e;
     }
 }
+function parseUi(argv) {
+    const out = {};
+    let i = 0;
+    while (i < argv.length) {
+        const t = argv[i];
+        if (t === "--help" || t === "-h") {
+            // ui --help routes to the top-level help — keeps the parser narrow
+            // and avoids a per-command help renderer for one subcommand.
+            throw new PerTypeHelpRequest(undefined);
+        }
+        if (t === "--port" || t.startsWith("--port=")) {
+            const [v, adv] = readSingleValue(argv, i, "--port");
+            const n = Number.parseInt(v, 10);
+            // 0 is a deliberate "OS-assigned ephemeral port" affordance used by
+            // hermetic e2e tests (spec §8.1). Real users pass a normal port.
+            if (!Number.isFinite(n) || n < 0 || n > 65535) {
+                parseErr(`--port must be a port number in [0, 65535], got '${v}'`);
+            }
+            out.port = n;
+            i += adv;
+            continue;
+        }
+        if (t === "--ui-dir" || t.startsWith("--ui-dir=")) {
+            const [v, adv] = readSingleValue(argv, i, "--ui-dir");
+            out.uiDir = v;
+            i += adv;
+            continue;
+        }
+        if (t === "--no-open") {
+            out.noOpen = true;
+            i += 1;
+            continue;
+        }
+        parseErr(`unknown argument '${t}' for 'web-ui'. Run 'npx auriga-cli --help' for usage.`);
+    }
+    return out;
+}
 function parseInstall(argv) {
     const out = { all: false };
     let filterFlag = null;
@@ -326,6 +373,9 @@ export async function main(argv) {
         process.stdout.write(renderGuide({ color, version }));
         return 0;
     }
+    if (parsed.command === "web-ui") {
+        return runUi(parsed.ui, version);
+    }
     // install — catalog is required for filter validation and for the TTY
     // menu's category descriptions; fail-fast at entry rather than produce
     // a cryptic error mid-dispatch (spec §7 / §11 acceptance).
@@ -508,6 +558,176 @@ async function dispatchInstaller(category, packageRoot, opts) {
     }
 }
 // ---------------------------------------------------------------------------
+// `web-ui` subcommand — boots the local Web UI server (spec §4)
+// ---------------------------------------------------------------------------
+const UI_DEFAULT_PORT = 4747;
+const UI_PORT_RANGE = 10; // 4747..4756
+const UI_HEARTBEAT_TIMEOUT_MS = 15_000;
+async function runUi(p, version) {
+    // Lazy-load the server-side deps so the install / guide paths stay light.
+    const { randomBytes } = await import("node:crypto");
+    const { startServer } = await import("./server.js");
+    const { buildDefaultApplyHandlers } = await import("./apply-handlers.js");
+    const { buildScanCatalog } = await import("./scan-catalog.js");
+    const { ensureUiBundle } = await import("./ui-fetch.js");
+    const cwd = process.cwd();
+    const packageRoot = getPackageRoot();
+    // 1. Resolve UI bundle directory.
+    let uiDir;
+    if (p.uiDir) {
+        uiDir = path.resolve(p.uiDir);
+        if (!fs.existsSync(path.join(uiDir, "index.html"))) {
+            log.error(`--ui-dir does not contain index.html: ${uiDir}`);
+            return 3;
+        }
+    }
+    else if (process.env.DEV === "1") {
+        // Dev convenience: prefer the locally-built ui/dist over a network fetch.
+        const localDist = path.join(packageRoot, "ui", "dist");
+        if (fs.existsSync(path.join(localDist, "index.html"))) {
+            uiDir = localDist;
+        }
+        else {
+            log.error("DEV mode: ui/dist not built. Run 'npm --prefix ui run build' or unset DEV to fetch from GitHub.");
+            return 3;
+        }
+    }
+    else {
+        try {
+            uiDir = await ensureUiBundle({
+                version,
+                onLog: (line) => log.ok(line),
+            });
+        }
+        catch (e) {
+            log.error(`Failed to fetch UI bundle: ${e.message}\n` +
+                `  Try again or pass --ui-dir <path> with a locally-built bundle.`);
+            return 3;
+        }
+    }
+    // 2. Build scan catalog → ApplyCatalog + pluginAgentsByName.
+    let scanCatalog;
+    try {
+        scanCatalog = await buildScanCatalog(packageRoot);
+    }
+    catch (e) {
+        log.error(`Failed to build catalog: ${e.message}`);
+        return 1;
+    }
+    const applyCatalog = {
+        // Workflow is a singleton (one CLAUDE.md per project); we pick the
+        // sentinel name "workflow" to match what the Web UI's Dashboard sends
+        // and to remain semantically self-describing. The handler ignores the
+        // name argument either way.
+        workflow: new Set(["workflow"]),
+        skill: new Set(Object.keys(scanCatalog.skills)),
+        "recommended-skill": new Set(Object.keys(scanCatalog.recommendedSkills)),
+        plugin: new Set(Object.keys(scanCatalog.plugins)),
+        hook: new Set(Object.keys(scanCatalog.hooks)),
+    };
+    const pluginAgentsByName = new Map();
+    for (const [name, def] of Object.entries(scanCatalog.plugins)) {
+        pluginAgentsByName.set(name, def.agents);
+    }
+    const applyHandlers = buildDefaultApplyHandlers({
+        packageRoot,
+        cwd,
+        pluginAgentsByName,
+    });
+    // 3. Token: 32 bytes hex per spec §4.4.
+    const token = randomBytes(32).toString("hex");
+    // 4. Bind port: try requested → otherwise 4747..4756 in sequence.
+    // Use `!== undefined` so `--port 0` (OS-ephemeral) is honored. `0` is
+    // falsy in JS; `p.port ? [p.port] : range` would silently fall back to
+    // the default range and break hermetic e2e isolation.
+    const ports = p.port !== undefined
+        ? [p.port]
+        : Array.from({ length: UI_PORT_RANGE }, (_, i) => UI_DEFAULT_PORT + i);
+    let server = null;
+    let lastErr = null;
+    for (const port of ports) {
+        try {
+            server = await startServer({
+                port,
+                token,
+                cwd,
+                packageRoot,
+                heartbeatTimeoutMs: UI_HEARTBEAT_TIMEOUT_MS,
+                applyHandlers,
+                applyCatalog,
+                uiDir,
+            });
+            break;
+        }
+        catch (e) {
+            lastErr = e;
+            // Only swallow address-in-use; everything else propagates.
+            if (!/EADDRINUSE|EACCES/i.test(lastErr.message)) {
+                log.error(`Failed to start server on port ${port}: ${lastErr.message}`);
+                return 1;
+            }
+        }
+    }
+    if (!server) {
+        log.error(`All ports occupied in range (${ports[0]}..${ports[ports.length - 1]}). ` +
+            `Try '--port <n>' or 'npx auriga-cli' for the TTY menu. Last error: ${lastErr?.message ?? "unknown"}`);
+        return 2;
+    }
+    // 5. URL + browser open.
+    const url = `http://127.0.0.1:${server.port}/?token=${token}`;
+    process.stdout.write(`\n${highlight("auriga UI is live:")}  ${url}\n` +
+        `   (closing the browser shuts the server down after ~${Math.round(UI_HEARTBEAT_TIMEOUT_MS / 1000)}s of inactivity)\n` +
+        `   Note: the URL contains a per-session token — don't paste it into chats, CI logs, or screenshots.\n\n`);
+    if (!p.noOpen) {
+        await openBrowser(url);
+    }
+    // 6. Block until the server fully stops. The heartbeat closes it after
+    //    UI_HEARTBEAT_TIMEOUT_MS without a /api/ping; SIGINT triggers an
+    //    explicit close().
+    const onSig = () => {
+        void server.close();
+    };
+    process.once("SIGINT", onSig);
+    process.once("SIGTERM", onSig);
+    try {
+        await server.closed;
+    }
+    finally {
+        process.off("SIGINT", onSig);
+        process.off("SIGTERM", onSig);
+    }
+    return 0;
+}
+/** Best-effort cross-platform browser open. Failure is non-fatal — the
+ *  printed URL is still actionable. */
+async function openBrowser(url) {
+    const opener = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const { spawn } = await import("node:child_process");
+        const proc = spawn(opener[0], opener[1], {
+            stdio: "ignore",
+            detached: true,
+        });
+        proc.on("error", () => {
+            /* swallow: URL was already printed */
+        });
+        proc.unref();
+    }
+    catch {
+        /* swallow */
+    }
+}
+/** Bold + cyan when stdout is a TTY; otherwise plain. */
+function highlight(text) {
+    if (!process.stdout.isTTY || process.env.NO_COLOR)
+        return text;
+    return `\x1b[1;36m${text}\x1b[0m`;
+}
+// ---------------------------------------------------------------------------
 // Legacy checkbox menu — preserved for `npx auriga-cli install` in TTY
 // and `npx auriga-cli` with no args.
 // ---------------------------------------------------------------------------