auriga-cli 1.15.1 → 1.16.0

package/dist/help.js

@@ -15,6 +15,8 @@ USAGE
                                                          (excludes recommended — install separately)
   npx auriga-cli install <type> [type-specific flags]    single category
   npx auriga-cli install <type> --help                   per-category help + catalog subset
+  npx auriga-cli web-ui [--port <n>] [--ui-dir <path>] [--no-open]
+                                                         open the local Web UI (spec §4)
   npx auriga-cli --help
 
   For non-interactive (Agent) use, prepend npx's own -y flag:

package/dist/hooks.d.ts

@@ -203,4 +203,34 @@ export declare function resolveHookSelection(compatible: HookDef[], selected: st
  */
 export declare function findIncompatibleExplicit(all: HookDef[], compatible: HookDef[], selected: string[]): string[];
 export declare function installHooks(packageRoot: string, opts: InstallOpts): Promise<void>;
+/**
+ * Uninstall a single hook. Defaults to project scope; explicit
+ * `scope:"user"` cleans `~/.claude/...` instead.
+ *
+ * Project scope (default):
+ *   - rm `<cwd>/.claude/hooks/<name>/` directory.
+ *   - Strip the hook's marker from `<cwd>/.claude/settings.json` AND
+ *     `<cwd>/.claude/settings.local.json` (project + project-local share
+ *     the on-disk hook dir, so cleaning both settings files keeps users
+ *     who switched scopes from accumulating dangling registrations).
+ *
+ * User scope:
+ *   - rm `~/.claude/hooks/<name>/` directory.
+ *   - Strip the hook's marker from `~/.claude/settings.json`.
+ *   - Project files are NOT touched.
+ *
+ * Marker discovery: tries the live registry at `<cwd>` (or the npx
+ * package root if that fails) so we use the same marker the install path
+ * stamped in. If the registry can't resolve the hook (renamed / removed
+ * upstream), we fall back to a `auriga:<name>` convention — every shipped
+ * hook to date follows it, so the fallback is reliable for the common
+ * case.
+ *
+ * Idempotent: missing hook dir / missing settings / absent marker → no-op.
+ */
+export declare function uninstallHook(name: string, opts: {
+    cwd: string;
+    scope?: "project" | "user";
+    onLog?: (line: string) => void;
+}): Promise<void>;
 export {};

package/dist/hooks.js

@@ -868,3 +868,92 @@ export async function installHooks(packageRoot, opts) {
         throw new Error(`${failures.length} hook(s) failed to install: ${failures.join(", ")}`);
     }
 }
+// --- Uninstall ----------------------------------------------------------------
+const HOOK_NAME_RE_STRICT = /^[a-z][a-z0-9-]*$/;
+/**
+ * Uninstall a single hook. Defaults to project scope; explicit
+ * `scope:"user"` cleans `~/.claude/...` instead.
+ *
+ * Project scope (default):
+ *   - rm `<cwd>/.claude/hooks/<name>/` directory.
+ *   - Strip the hook's marker from `<cwd>/.claude/settings.json` AND
+ *     `<cwd>/.claude/settings.local.json` (project + project-local share
+ *     the on-disk hook dir, so cleaning both settings files keeps users
+ *     who switched scopes from accumulating dangling registrations).
+ *
+ * User scope:
+ *   - rm `~/.claude/hooks/<name>/` directory.
+ *   - Strip the hook's marker from `~/.claude/settings.json`.
+ *   - Project files are NOT touched.
+ *
+ * Marker discovery: tries the live registry at `<cwd>` (or the npx
+ * package root if that fails) so we use the same marker the install path
+ * stamped in. If the registry can't resolve the hook (renamed / removed
+ * upstream), we fall back to a `auriga:<name>` convention — every shipped
+ * hook to date follows it, so the fallback is reliable for the common
+ * case.
+ *
+ * Idempotent: missing hook dir / missing settings / absent marker → no-op.
+ */
+export async function uninstallHook(name, opts) {
+    if (!HOOK_NAME_RE_STRICT.test(name)) {
+        throw new Error(`uninstallHook: invalid hook name ${JSON.stringify(name)}`);
+    }
+    const cwd = path.resolve(opts.cwd);
+    const scope = opts.scope ?? "project";
+    const emit = (line) => { opts.onLog?.(line); };
+    // Look up marker from the registry. If the registry is absent or the
+    // hook isn't listed, fall back to `auriga:<name>` (the shipped naming
+    // convention for every hook in this repo).
+    let marker = `auriga:${name}`;
+    try {
+        const cfg = loadHooksConfig(cwd);
+        const def = cfg.hooks.find((h) => h.name === name);
+        if (def)
+            marker = def.marker;
+    }
+    catch {
+        // No registry at cwd — fine, fall back to the convention.
+    }
+    // Build a minimal HookDef stub for cleanHookFromScope. It only reads
+    // `marker` and `name` (via resolveScope), both of which we have.
+    const stub = {
+        name,
+        description: "",
+        runtimePlatforms: [],
+        settingsEvents: [],
+        command: 'node "$HOOK_DIR/index.mjs"',
+        files: [],
+        marker,
+    };
+    // resolveScope picks the settings/hooks paths based on scope.
+    // Project scope covers both project + project-local settings (shared
+    // on-disk hook dir); user scope covers only ~/.claude/settings.json.
+    const cleanScopes = scope === "user" ? ["user"] : ["project", "project-local"];
+    let totalRemoved = 0;
+    for (const s of cleanScopes) {
+        const r = cleanHookFromScope(stub, s, cwd);
+        if (r.removed > 0) {
+            totalRemoved += r.removed;
+            log.ok(`${name}: removed ${r.removed} entr${r.removed === 1 ? "y" : "ies"} from ${r.settingsPath}`);
+            emit(`removed ${r.removed} entr${r.removed === 1 ? "y" : "ies"} from ${r.settingsPath}`);
+        }
+    }
+    if (totalRemoved === 0) {
+        log.skip(`${name}: no settings entries found`);
+        emit(`${name}: no settings entries found`);
+    }
+    // Hook directory: user → ~/.claude/hooks/<name>; project → <cwd>/.claude/hooks/<name>.
+    const hookDir = scope === "user"
+        ? path.join(os.homedir(), ".claude", "hooks", name)
+        : path.join(cwd, ".claude", "hooks", name);
+    if (fs.existsSync(hookDir)) {
+        fs.rmSync(hookDir, { recursive: true, force: true });
+        log.ok(`${name}: directory removed`);
+        emit(`removed ${hookDir}`);
+    }
+    else {
+        log.skip(`${name}: directory not present`);
+        emit(`${name}: directory not present`);
+    }
+}

package/dist/plugins.d.ts

@@ -1,3 +1,32 @@
 import type { InstallOpts, PluginsConfig } from "./utils.js";
 export declare function validatePluginsConfig(raw: unknown): asserts raw is PluginsConfig;
 export declare function installPlugins(packageRoot: string, opts: InstallOpts): Promise<void>;
+/**
+ * Uninstall a single plugin.
+ *
+ *   Claude side: shells out to `claude plugins uninstall <id>` (the
+ *     canonical CLI path). Errors are propagated — the CLI sometimes
+ *     surfaces nuanced failure modes (marketplace gone, network) that
+ *     the caller needs to see verbatim.
+ *
+ *   Codex side: no `codex plugin uninstall` exists today (spec §10.4
+ *     flagged this as v0.1 needs-confirm). We mimic the install path
+ *     in reverse:
+ *       1. Read + parse `~/.codex/config.toml`, delete `[plugins."<id>"]`,
+ *          atomic write back. Throws on parse error (don't half-corrupt).
+ *       2. rm `~/.codex/plugins/cache/<marketplace>/<plugin>/` directory.
+ *     Both steps are idempotent — missing config / missing cache dir is
+ *     a no-op (the user may have manually cleaned half of the install).
+ *
+ *     Caveat: we deliberately do NOT remove the marketplace itself. A
+ *     single marketplace may host multiple plugins; tearing it down
+ *     because one plugin left would break others. The user can
+ *     `codex plugin marketplace remove` separately when they want.
+ *
+ * Validation happens before any I/O — a malformed id throws cleanly with
+ * no side effects, so retries are safe.
+ */
+export declare function uninstallPlugin(id: string, agent: "claude" | "codex", opts: {
+    cwd: string;
+    onLog?: (line: string) => void;
+}): Promise<void>;

package/dist/plugins.js

@@ -5,7 +5,7 @@ import { checkbox, select } from "@inquirer/prompts";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { codexManifestPath, validateCodexInstallConfig, validateCodexMarketplace, } from "./codex-plugin-config.js";
 import { validateMarketplaceField } from "./marketplace.js";
-import { atomicWriteFile, exec, fetchExtraContent, log, withEsc } from "./utils.js";
+import { atomicWriteFile, exec, execAsync, fetchExtraContent, log, withEsc } from "./utils.js";
 // Plugin names and plugin-package names end up in `claude plugins ...`
 // shell commands via string interpolation. .claude/plugins.json is
 // fetched from raw GitHub at runtime, so every value must pass a
@@ -531,7 +531,14 @@ export async function installPlugins(packageRoot, opts) {
             for (const [name, source] of marketplacesToAdd) {
                 console.log(`\nAdding marketplace: ${name}...`);
                 try {
-                    exec(`claude plugins marketplace add ${source}`, { inherit: true });
+                    const cmd = `claude plugins marketplace add ${source}`;
+                    if (opts.onLog) {
+                        opts.onLog(`▸ ${cmd}`, "stdout");
+                        await execAsync(cmd, { onLine: opts.onLog });
+                    }
+                    else {
+                        exec(cmd, { inherit: true });
+                    }
                     log.ok(`Marketplace ${name} added`);
                 }
                 catch {
@@ -542,7 +549,14 @@ export async function installPlugins(packageRoot, opts) {
             for (const name of marketplacesToUpdate) {
                 console.log(`\nUpdating marketplace: ${name}...`);
                 try {
-                    exec(`claude plugins marketplace update ${name}`, { inherit: true });
+                    const cmd = `claude plugins marketplace update ${name}`;
+                    if (opts.onLog) {
+                        opts.onLog(`▸ ${cmd}`, "stdout");
+                        await execAsync(cmd, { onLine: opts.onLog });
+                    }
+                    else {
+                        exec(cmd, { inherit: true });
+                    }
                     log.ok(`Marketplace ${name} updated`);
                 }
                 catch (e) {
@@ -557,9 +571,14 @@ export async function installPlugins(packageRoot, opts) {
             for (const plugin of selected) {
                 console.log(`\nInstalling ${plugin.name}...`);
                 try {
-                    exec(`claude plugins install ${plugin.package} --scope ${scope}`, {
-                        inherit: true,
-                    });
+                    const cmd = `claude plugins install ${plugin.package} --scope ${scope}`;
+                    if (opts.onLog) {
+                        opts.onLog(`▸ ${cmd}`, "stdout");
+                        await execAsync(cmd, { onLine: opts.onLog });
+                    }
+                    else {
+                        exec(cmd, { inherit: true });
+                    }
                     log.ok(`${plugin.name} installed`);
                 }
                 catch {
@@ -584,3 +603,115 @@ export async function installPlugins(packageRoot, opts) {
         }
     }
 }
+// --- Uninstall ----------------------------------------------------------------
+// Plugin id format: `<plugin>@<marketplace>` (matches the Codex config.toml
+// key shape and Claude Code's `claude plugins install ...` argument).
+// Tightened with the same name regex used everywhere else in this file
+// (PLUGIN_NAME_RE on the plugin side, MARKETPLACE_NAME_RE on the
+// marketplace side, both anchored). `name` is interpolated into a shell
+// command (Claude path) and used as a filesystem segment (Codex path);
+// rejecting unsafe shapes here closes both attack surfaces in one place.
+const PLUGIN_ID_RE = /^([A-Za-z0-9][A-Za-z0-9._-]{0,127})@([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/;
+function parsePluginId(id) {
+    const m = PLUGIN_ID_RE.exec(id);
+    if (!m) {
+        throw new Error(`uninstallPlugin: invalid plugin id ${JSON.stringify(id)}; expected <plugin>@<marketplace>`);
+    }
+    return { plugin: m[1], marketplace: m[2] };
+}
+/**
+ * Remove `[plugins."<id>"]` from a parsed Codex config TOML tree.
+ * Returns true if anything was removed. Idempotent: missing key → false.
+ *
+ * Pure function operating on the parsed tree — no I/O. Lets the test
+ * harness assert tree shape without touching disk + lets the I/O wrapper
+ * skip the atomic write when nothing changed.
+ */
+function removeCodexPluginFromConfig(parsed, pluginId) {
+    const plugins = parsed.plugins;
+    if (!isTomlTable(plugins))
+        return false;
+    if (!(pluginId in plugins))
+        return false;
+    delete plugins[pluginId];
+    return true;
+}
+/**
+ * Uninstall a single plugin.
+ *
+ *   Claude side: shells out to `claude plugins uninstall <id>` (the
+ *     canonical CLI path). Errors are propagated — the CLI sometimes
+ *     surfaces nuanced failure modes (marketplace gone, network) that
+ *     the caller needs to see verbatim.
+ *
+ *   Codex side: no `codex plugin uninstall` exists today (spec §10.4
+ *     flagged this as v0.1 needs-confirm). We mimic the install path
+ *     in reverse:
+ *       1. Read + parse `~/.codex/config.toml`, delete `[plugins."<id>"]`,
+ *          atomic write back. Throws on parse error (don't half-corrupt).
+ *       2. rm `~/.codex/plugins/cache/<marketplace>/<plugin>/` directory.
+ *     Both steps are idempotent — missing config / missing cache dir is
+ *     a no-op (the user may have manually cleaned half of the install).
+ *
+ *     Caveat: we deliberately do NOT remove the marketplace itself. A
+ *     single marketplace may host multiple plugins; tearing it down
+ *     because one plugin left would break others. The user can
+ *     `codex plugin marketplace remove` separately when they want.
+ *
+ * Validation happens before any I/O — a malformed id throws cleanly with
+ * no side effects, so retries are safe.
+ */
+export async function uninstallPlugin(id, agent, opts) {
+    const { plugin, marketplace } = parsePluginId(id);
+    const emit = (line) => { opts.onLog?.(line); };
+    if (agent === "claude") {
+        // Note: scope is intentionally NOT specified. `claude plugins
+        // uninstall <id>` operates against whatever scope the plugin is
+        // installed in (user / project) — letting the CLI find it is
+        // more robust than guessing wrong and silently no-op'ing.
+        exec(`claude plugins uninstall ${id}`, { cwd: opts.cwd, inherit: true });
+        log.ok(`${id} uninstalled from Claude Code`);
+        emit(`uninstalled ${id} from Claude Code`);
+        return;
+    }
+    // Codex path.
+    const home = codexHome();
+    const configPath = path.join(home, "config.toml");
+    if (fs.existsSync(configPath)) {
+        const content = fs.readFileSync(configPath, "utf-8");
+        // Parse-then-mutate: any parse failure aborts BEFORE we touch the
+        // filesystem (cache dir removal also gets skipped) so a damaged
+        // config doesn't end up half-uninstalled. The test "config.toml
+        // damaged → throw before mutation" locks this in.
+        const parsed = parseCodexConfigToml(content, configPath);
+        const removed = removeCodexPluginFromConfig(parsed, id);
+        if (removed) {
+            const next = stringifyToml(parsed);
+            atomicWriteFile(configPath, next.endsWith("\n") ? next : `${next}\n`);
+            log.ok(`${id} disabled in Codex config.toml`);
+            emit(`removed ${id} from Codex config.toml`);
+        }
+        else {
+            log.skip(`${id} not present in Codex config.toml`);
+            emit(`${id} not present in Codex config.toml`);
+        }
+    }
+    else {
+        log.skip(`Codex config.toml not present`);
+        emit(`Codex config.toml not present`);
+    }
+    // Cache dir: ~/.codex/plugins/cache/<marketplace>/<plugin>/
+    // PLUGIN_ID_RE constrains both segments to a safe charset, so the
+    // path can't escape via injection. rmSync with recursive+force is
+    // the standard rm-rf idiom; missing dir is a no-op.
+    const cacheDir = path.join(home, "plugins", "cache", marketplace, plugin);
+    if (fs.existsSync(cacheDir)) {
+        fs.rmSync(cacheDir, { recursive: true, force: true });
+        log.ok(`${id} cache directory removed`);
+        emit(`removed Codex cache directory for ${id}`);
+    }
+    else {
+        log.skip(`${id} cache directory not present`);
+        emit(`Codex cache directory for ${id} not present`);
+    }
+}

package/dist/scan-catalog.d.ts

@@ -0,0 +1,2 @@
+import type { Catalog as ScanCatalog } from "./state.js";
+export declare function buildScanCatalog(packageRoot: string): Promise<ScanCatalog>;

package/dist/scan-catalog.js

@@ -0,0 +1,138 @@
+// Build the scan-time Catalog (the shape src/state.ts consumes) from
+// auriga-cli's installed package state. This bridges the build-time
+// `dist/catalog.json` (which carries names + descriptions for the menu)
+// and the runtime scanner's need for expected hashes + versions.
+//
+// Inputs (all under packageRoot):
+//   dist/catalog.json     — names + descriptions for 5 categories
+//   skills-lock.json      — expected SHA256 for every vendored skill
+//   .claude/plugins.json  — Claude plugin entries (agent = "claude")
+//   .agents/plugins/install.json — Codex plugin entries (agent = "codex")
+//   .claude/hooks/<name>/index.mjs — runtime SHA256 = expected hash
+//   CLAUDE.md             — `# auriga Workflow (vX.Y.Z)` provides
+//                           workflowVersion
+//
+// Anything missing is treated as "no expectation" (empty hash / version)
+// rather than throwing; scanState will still produce a structurally valid
+// StateReport — items just classify as not-installed or installed
+// depending on whether the user-side data exists.
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { loadCatalog } from "./catalog.js";
+const WORKFLOW_VERSION_RE = /^#\s*auriga Workflow\s*\(v([\d.]+)\)/m;
+async function tryReadFile(p) {
+    try {
+        return await readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function sha256File(p) {
+    const bytes = await readFile(p);
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export async function buildScanCatalog(packageRoot) {
+    const dist = loadCatalog(packageRoot);
+    // Workflow version: parse from auriga-cli's own CLAUDE.md template.
+    // If missing, leave as empty string so workflow always classifies as
+    // not-installed (no expectation set).
+    const claudeMd = await tryReadFile(path.join(packageRoot, "CLAUDE.md"));
+    const m = claudeMd ? WORKFLOW_VERSION_RE.exec(claudeMd) : null;
+    const workflowVersion = m ? m[1] : "";
+    // Skills + recommended: hashes from skills-lock.json.
+    let lock = {};
+    const lockText = await tryReadFile(path.join(packageRoot, "skills-lock.json"));
+    if (lockText) {
+        try {
+            lock = JSON.parse(lockText);
+        }
+        catch {
+            // corrupted lock → no expectations; user state still classifies safely
+        }
+    }
+    const skills = {};
+    for (const entry of dist.workflowSkills) {
+        skills[entry.name] = {
+            description: entry.description,
+            expectedHash: lock.skills?.[entry.name]?.computedHash ?? "",
+            isWorkflow: true,
+        };
+    }
+    const recommendedSkills = {};
+    for (const entry of dist.recommendedSkills) {
+        recommendedSkills[entry.name] = {
+            description: entry.description,
+            expectedHash: lock.skills?.[entry.name]?.computedHash ?? "",
+        };
+    }
+    // Plugins: split by agent based on which config file lists them. A
+    // plugin can appear in both registries (cross-agent plugins like
+    // auriga-go); we represent it once per agent.
+    const plugins = {};
+    const claudePluginsText = await tryReadFile(path.join(packageRoot, ".claude", "plugins.json"));
+    const claudeNames = new Set();
+    if (claudePluginsText) {
+        try {
+            const parsed = JSON.parse(claudePluginsText);
+            for (const p of parsed.plugins ?? []) {
+                if (p.name)
+                    claudeNames.add(p.name);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const codexInstallText = await tryReadFile(path.join(packageRoot, ".agents", "plugins", "install.json"));
+    const codexNames = new Set();
+    if (codexInstallText) {
+        try {
+            const parsed = JSON.parse(codexInstallText);
+            for (const p of parsed.plugins ?? []) {
+                if (p.name)
+                    codexNames.add(p.name);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    for (const entry of dist.plugins) {
+        // Collect every agent that registers this plugin. A plugin can ship in
+        // both registries (cross-agent plugins like auriga-go); we emit it as
+        // a single multi-agent record so the UI shows one row + BOTH badge and
+        // Apply installs to each side.
+        const agents = [];
+        if (claudeNames.has(entry.name))
+            agents.push("claude");
+        if (codexNames.has(entry.name))
+            agents.push("codex");
+        if (agents.length === 0)
+            agents.push("claude"); // unknown defaults to claude
+        plugins[entry.name] = { description: entry.description, agents };
+    }
+    // Hooks: runtime SHA256 of each hook's index.mjs serves as the expected
+    // hash. If the file can't be read, leave the expectation empty so the
+    // hook classifies as not-installed.
+    const hooks = {};
+    for (const entry of dist.hooks) {
+        const hookEntry = path.join(packageRoot, ".claude", "hooks", entry.name, "index.mjs");
+        let expectedHash = "";
+        try {
+            expectedHash = await sha256File(hookEntry);
+        }
+        catch {
+            /* missing or unreadable hook payload; leave hash empty */
+        }
+        hooks[entry.name] = { description: entry.description, expectedHash };
+    }
+    return {
+        workflowVersion,
+        skills,
+        recommendedSkills,
+        plugins,
+        hooks,
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,71 @@
+export type LogLevel = "info" | "warn" | "error";
+export interface ApplyHandlerOptions {
+    onLog: (line: string, level: LogLevel) => void;
+    /** Installer scope from the ApplyItemRef. Forwarded as-is — handlers
+     *  translate into the per-installer flag (`--scope project|user`). The
+     *  workflow handler ignores it (workflow has no scope concept). */
+    scope?: "project" | "user";
+    /** Workflow CLAUDE.md language variant. Only meaningful for the workflow
+     *  handler; other handlers ignore it. Omitted = "en". */
+    lang?: "en" | "zh-CN";
+}
+export type ApplyHandler = (action: ApplyAction, name: string, opts: ApplyHandlerOptions) => Promise<void>;
+export interface ApplyHandlers {
+    workflow: ApplyHandler;
+    skill: ApplyHandler;
+    "recommended-skill": ApplyHandler;
+    plugin: ApplyHandler;
+    hook: ApplyHandler;
+}
+export interface ApplyCatalog {
+    workflow: Set<string>;
+    skill: Set<string>;
+    "recommended-skill": Set<string>;
+    plugin: Set<string>;
+    hook: Set<string>;
+}
+export interface StartServerOptions {
+    port?: number;
+    token: string;
+    cwd: string;
+    /** Where auriga-cli itself lives — source of dist/catalog.json,
+     *  skills-lock.json, hook payloads, etc. Defaults to cwd, which is
+     *  correct when running tests from the auriga-cli checkout. CLI mode
+     *  must pass getPackageRoot() so the server uses the installed package
+     *  rather than the user's project. */
+    packageRoot?: string;
+    /** Idle-shutdown timeout in ms. The browser POSTs /api/ping every 5s;
+     *  if no ping arrives for this duration, the server shuts down
+     *  gracefully (closing-browser-closes-server UX). `0` disables the
+     *  heartbeat (used by tests so a single suite doesn't time-bomb). */
+    heartbeatTimeoutMs?: number;
+    /** Apply handlers per category. When omitted, /api/apply falls back to
+     *  built-in installers wired by the CLI. Tests inject mocks to make apply
+     *  behavior deterministic without touching real installers. */
+    applyHandlers?: ApplyHandlers;
+    /** Per-category name whitelist. When set, /api/apply rejects (400) any
+     *  item whose name is not present in the matching category's Set. When
+     *  omitted, name membership is not enforced (CLI builds a default
+     *  catalog at boot time). */
+    applyCatalog?: ApplyCatalog;
+    /** Directory whose contents are served for non-/api paths (the extracted
+     *  UI bundle). When undefined, every static path returns 404 — useful in
+     *  tests and the M1 server smoke checks. */
+    uiDir?: string;
+    /** Max time to wait for an in-flight job during graceful shutdown before
+     *  force-closing sockets (spec §4.3 / §6.6). Defaults to 30000 ms in
+     *  production; tests override to a small value (e.g. 200 ms) so they
+     *  don't time-bomb. */
+    shutdownGraceMs?: number;
+}
+export interface RunningServer {
+    port: number;
+    /** Explicit shutdown. Idempotent. */
+    close(): Promise<void>;
+    /** Resolves when the server has fully stopped — either via close() or the
+     *  heartbeat-driven shutdown. CLI callers await this to block their event
+     *  loop until "browser was closed" actually fires. */
+    closed: Promise<void>;
+}
+import type { ApplyAction } from "./api-types.js";
+export declare function startServer(opts: StartServerOptions): Promise<RunningServer>;