auriga-cli 1.15.1 → 1.16.0

package/dist/ui-fetch.js

@@ -0,0 +1,267 @@
+// Fetches the Web UI bundle for the current CLI version from GitHub Releases,
+// verifies its SHA256, and extracts it into a per-version cache directory.
+// Subsequent CLI invocations reuse the cache instead of re-downloading.
+//
+// Spec: docs/architecture/web-ui.md §4.1 (boot), §9 (release pipeline + checksum +
+// cache policy). Tests inject a fake `fetcher` so the unit suite never
+// touches the network.
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readdir, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { request as httpsRequest } from "node:https";
+import { request as httpRequest } from "node:http";
+import { gunzipSync } from "node:zlib";
+const RELEASE_BASE = "https://github.com/Ben2pc/auriga-cli/releases/download";
+const BUNDLE_FILE = "ui-bundle.tar.gz";
+const SHA_FILE = "ui-bundle.sha256";
+/** How many cached versions to keep before LRU-evicting older ones. */
+const CACHE_KEEP_COUNT = 3;
+/**
+ * Resolve / populate the per-version cache dir; return its absolute path.
+ *
+ * Algorithm:
+ *   1. If `<cacheRoot>/ui-v<version>/index.html` exists → cache hit, return.
+ *   2. Fetch tar.gz + .sha256 in parallel; verify hash.
+ *   3. Extract to a sibling tmp dir; rename atomically into place.
+ *   4. Evict older versions beyond CACHE_KEEP_COUNT.
+ *
+ * Any failure path cleans up its own scratch state and rejects with a
+ * descriptive Error so the CLI can surface "try `npx auriga-cli`" guidance.
+ */
+export async function ensureUiBundle(opts) {
+    const cacheRoot = opts.cacheRoot ?? defaultCacheRoot();
+    const versionDir = path.join(cacheRoot, `ui-v${opts.version}`);
+    const fetcher = opts.fetcher ?? builtinHttpsFetcher;
+    const emit = (line) => opts.onLog?.(line);
+    // 1. Cache hit.
+    if (existsSync(path.join(versionDir, "index.html"))) {
+        emit(`ui bundle cache hit: ${versionDir}`);
+        return versionDir;
+    }
+    await mkdir(cacheRoot, { recursive: true });
+    // 2. Fetch.
+    const bundleUrl = `${RELEASE_BASE}/v${opts.version}/${BUNDLE_FILE}`;
+    const shaUrl = `${RELEASE_BASE}/v${opts.version}/${SHA_FILE}`;
+    emit(`fetching ${bundleUrl}`);
+    const [bundleRes, shaRes] = await Promise.all([
+        fetcher(bundleUrl),
+        fetcher(shaUrl),
+    ]);
+    if (bundleRes.status !== 200) {
+        throw new Error(`ui bundle download failed: HTTP ${bundleRes.status} ${bundleUrl}`);
+    }
+    if (shaRes.status !== 200) {
+        throw new Error(`ui bundle SHA256 download failed: HTTP ${shaRes.status} ${shaUrl}`);
+    }
+    const expectedHash = parseShaFile(shaRes.body.toString("utf8"));
+    const actualHash = createHash("sha256").update(bundleRes.body).digest("hex");
+    if (actualHash.toLowerCase() !== expectedHash.toLowerCase()) {
+        throw new Error(`ui bundle SHA256 mismatch: expected ${expectedHash}, got ${actualHash}`);
+    }
+    emit(`sha256 verified (${actualHash.slice(0, 12)}…)`);
+    // 3. Extract to a sibling scratch dir.
+    const scratch = await mkdtemp(path.join(cacheRoot, `.ui-extract-`));
+    try {
+        // Verify gzip header before paying for `tar` — gives a clearer error.
+        let raw;
+        try {
+            raw = gunzipSync(bundleRes.body);
+        }
+        catch (err) {
+            throw new Error(`ui bundle gzip decode failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const tarPath = path.join(scratch, "bundle.tar");
+        await writeFile(tarPath, raw);
+        await extractTar(tarPath, scratch);
+        // Sanity: extracted contents must include an `index.html` somewhere
+        // immediately under scratch. tar archives created with `tar -czf …
+        // -C dist .` place files at the root; some manual archives nest under
+        // a subdir. Handle both.
+        const indexLoc = await findIndexHtml(scratch);
+        if (!indexLoc) {
+            throw new Error("ui bundle archive missing index.html");
+        }
+        const extractRoot = path.dirname(indexLoc);
+        // 4. Atomic move into the per-version dir. If versionDir already exists
+        //    (race with another invocation), prefer the existing one.
+        try {
+            await rename(extractRoot, versionDir);
+        }
+        catch (err) {
+            if (existsSync(versionDir)) {
+                // Lost the race — somebody else extracted. Use theirs.
+                emit(`cache populated concurrently; reusing ${versionDir}`);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    catch (err) {
+        await rm(scratch, { recursive: true, force: true });
+        // Defensive: make sure versionDir doesn't survive partial state.
+        await rm(versionDir, { recursive: true, force: true });
+        throw err;
+    }
+    finally {
+        // Best-effort scratch cleanup; the rename above usually consumed it.
+        await rm(scratch, { recursive: true, force: true });
+    }
+    await evictOldCacheDirs(cacheRoot, opts.version);
+    return versionDir;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function defaultCacheRoot() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? tmpdir();
+    return path.join(home, ".cache", "auriga-cli");
+}
+function parseShaFile(text) {
+    // `shasum -a 256` output: `<hex>  <filename>\n`. We accept either the bare
+    // 64-char hex string (e.g. produced by `openssl dgst -sha256 | head`) or
+    // the `<hex>  <file>` form.
+    const trimmed = text.trim();
+    const m = /^([0-9a-fA-F]{64})\b/.exec(trimmed);
+    if (!m) {
+        throw new Error(`ui bundle SHA256 file is not parseable: ${trimmed.slice(0, 80)}`);
+    }
+    return m[1];
+}
+/** Spawn `tar -xf` to extract into `dest`. Throws on non-zero exit. */
+function extractTar(tarPath, dest) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("tar", ["-xf", tarPath, "-C", dest], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stderrChunks = [];
+        proc.stderr.on("data", (c) => stderrChunks.push(c));
+        proc.on("error", reject);
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                const msg = Buffer.concat(stderrChunks).toString("utf8").trim();
+                reject(new Error(`ui bundle tar extract failed (exit ${code}): ${msg || "(no stderr)"}`));
+            }
+        });
+    });
+}
+/** Locate `index.html` under `root` (depth ≤ 2). Returns absolute path or null. */
+async function findIndexHtml(root) {
+    const direct = path.join(root, "index.html");
+    if (existsSync(direct))
+        return direct;
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const nested = path.join(root, e.name, "index.html");
+        if (existsSync(nested))
+            return nested;
+    }
+    return null;
+}
+/** Overall request timeout. A hung GitHub edge would otherwise block
+ *  `npx auriga-cli web-ui` before the URL line ever prints. */
+const FETCH_TIMEOUT_MS = 30_000;
+/** Built-in fetcher using Node's https client. Follows up to 5 redirects
+ *  (GitHub Release assets bounce through a signed objects URL). Buffers the
+ *  whole response — bundles are well under 5 MB — and hard-times-out after
+ *  FETCH_TIMEOUT_MS so a hung peer can't deadlock the CLI. */
+async function builtinHttpsFetcher(url) {
+    return await new Promise((resolve, reject) => {
+        let redirectsLeft = 5;
+        let settled = false;
+        const finish = (err, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const timer = setTimeout(() => {
+            finish(new Error(`ui bundle fetch timeout after ${FETCH_TIMEOUT_MS}ms: ${url}`));
+        }, FETCH_TIMEOUT_MS);
+        timer.unref?.();
+        const go = (target) => {
+            const u = new URL(target);
+            const fn = u.protocol === "http:" ? httpRequest : httpsRequest;
+            const req = fn(u, { method: "GET" }, (res) => {
+                const status = res.statusCode ?? 0;
+                if ([301, 302, 303, 307, 308].includes(status) &&
+                    res.headers.location &&
+                    redirectsLeft > 0) {
+                    redirectsLeft--;
+                    res.resume();
+                    const next = new URL(res.headers.location, target).toString();
+                    go(next);
+                    return;
+                }
+                const chunks = [];
+                res.on("data", (c) => chunks.push(c));
+                res.on("end", () => finish(null, { status, body: Buffer.concat(chunks) }));
+                res.on("error", (err) => finish(err));
+            });
+            req.on("error", (err) => finish(err));
+            req.end();
+        };
+        go(url);
+    });
+}
+/** Keep at most CACHE_KEEP_COUNT `ui-v*` dirs (newest by mtime). The
+ *  just-fetched version is always retained. */
+async function evictOldCacheDirs(cacheRoot, currentVersion) {
+    let all;
+    try {
+        all = await readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch {
+        // Cache dir was already deleted by another process — nothing to evict.
+        return;
+    }
+    const versionDirs = all.filter((e) => e.isDirectory() && e.name.startsWith("ui-v"));
+    if (versionDirs.length <= CACHE_KEEP_COUNT)
+        return;
+    // stat each dir individually; a permission/dangling entry must not block
+    // eviction of the rest. Entries that fail to stat are excluded from the
+    // keep set so they're considered fair game for removal.
+    const withMtime = [];
+    for (const d of versionDirs) {
+        try {
+            const s = await stat(path.join(cacheRoot, d.name));
+            withMtime.push({ name: d.name, mtime: s.mtimeMs });
+        }
+        catch {
+            withMtime.push({ name: d.name, mtime: 0 });
+        }
+    }
+    withMtime.sort((a, b) => b.mtime - a.mtime); // newest first
+    const keep = new Set();
+    keep.add(`ui-v${currentVersion}`);
+    for (const entry of withMtime) {
+        if (keep.size >= CACHE_KEEP_COUNT)
+            break;
+        keep.add(entry.name);
+    }
+    for (const entry of withMtime) {
+        if (keep.has(entry.name))
+            continue;
+        try {
+            await rm(path.join(cacheRoot, entry.name), {
+                recursive: true,
+                force: true,
+            });
+        }
+        catch {
+            // Best-effort: leave the dir; next eviction round will retry.
+        }
+    }
+}

package/dist/utils.d.ts

@@ -45,6 +45,14 @@ export interface InstallOpts {
     /** `true` = drive via inquirer prompts (existing interactive UX);
      *  `false` = non-interactive, use only the fields above. */
     interactive: boolean;
+    /**
+     * Optional per-line callback for installer stdout/stderr. When set,
+     * exec uses spawn under the hood and forwards each line. Used by the
+     * Web UI server's /api/apply path to stream installer output through
+     * SSE item:log events (spec §6.4). When omitted, installers fall back
+     * to inherit-style exec which writes to the parent process terminal.
+     */
+    onLog?: (line: string, stream: "stdout" | "stderr") => void;
 }
 /**
  * Whether the current process should be treated as non-interactive.
@@ -58,6 +66,20 @@ export declare function exec(cmd: string, opts?: {
     cwd?: string;
     inherit?: boolean;
 }): string;
+/**
+ * Async variant of `exec`: spawns the command, captures stdout/stderr
+ * line-by-line via the per-line callback, and resolves on exit code 0.
+ * Non-zero exit rejects with an Error whose `stderr` field carries the
+ * buffered stderr and whose message mirrors execSync's "Command failed:"
+ * shape — so the existing `isSkillsRemoveUnsupported` matcher still works.
+ *
+ * Used by Web UI install paths to forward installer output through SSE.
+ * Synchronous callers continue to use `exec`.
+ */
+export declare function execAsync(cmd: string, opts: {
+    cwd?: string;
+    onLine?: (line: string, stream: "stdout" | "stderr") => void;
+}): Promise<string>;
 export interface LangOption {
     value: string;
     label: string;

package/dist/utils.js

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -43,6 +43,63 @@ export function exec(cmd, opts) {
         encoding: "utf-8",
     });
 }
+/**
+ * Async variant of `exec`: spawns the command, captures stdout/stderr
+ * line-by-line via the per-line callback, and resolves on exit code 0.
+ * Non-zero exit rejects with an Error whose `stderr` field carries the
+ * buffered stderr and whose message mirrors execSync's "Command failed:"
+ * shape — so the existing `isSkillsRemoveUnsupported` matcher still works.
+ *
+ * Used by Web UI install paths to forward installer output through SSE.
+ * Synchronous callers continue to use `exec`.
+ */
+export function execAsync(cmd, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, { cwd: opts.cwd, shell: true });
+        let stdout = "";
+        let stderr = "";
+        const lineBuffers = {
+            stdout: "",
+            stderr: "",
+        };
+        const drain = (stream, chunk) => {
+            const text = chunk.toString("utf-8");
+            if (stream === "stdout")
+                stdout += text;
+            else
+                stderr += text;
+            lineBuffers[stream] += text;
+            let idx;
+            while ((idx = lineBuffers[stream].indexOf("\n")) !== -1) {
+                const line = lineBuffers[stream].slice(0, idx).replace(/\r$/, "");
+                lineBuffers[stream] = lineBuffers[stream].slice(idx + 1);
+                if (opts.onLine && line.length > 0)
+                    opts.onLine(line, stream);
+            }
+        };
+        child.stdout?.on("data", (chunk) => drain("stdout", chunk));
+        child.stderr?.on("data", (chunk) => drain("stderr", chunk));
+        child.on("error", (err) => reject(err));
+        child.on("close", (code) => {
+            // Flush trailing partial lines (no final newline).
+            for (const s of ["stdout", "stderr"]) {
+                if (lineBuffers[s].length > 0 && opts.onLine) {
+                    opts.onLine(lineBuffers[s], s);
+                }
+            }
+            if (code === 0) {
+                resolve(stdout);
+            }
+            else {
+                const err = new Error(`Command failed: ${cmd}`);
+                err.stderr = stderr;
+                err.stdout = stdout;
+                err.status = code;
+                reject(err);
+            }
+        });
+    });
+}
 export const LANGUAGES = [
     { value: "en", label: "English", file: "CLAUDE.md" },
     { value: "zh-CN", label: "中文", file: "CLAUDE.zh-CN.md" },

package/dist/workflow.d.ts

@@ -1,2 +1,24 @@
 import { type InstallOpts } from "./utils.js";
 export declare function installWorkflow(packageRoot: string, opts: InstallOpts): Promise<void>;
+/**
+ * Uninstall the workflow (CLAUDE.md + AGENTS.md) from `opts.cwd`.
+ *
+ * Safety contract:
+ * - `opts.force` MUST be true. The CLI / server caller is responsible for
+ *   confirming user intent BEFORE invoking this; we refuse otherwise.
+ * - `AGENTS.md` is removed ONLY if it's a symlink (the install-time shape).
+ *   A real-file AGENTS.md is left in place with a warning — the user has
+ *   diverged from the install pattern and probably hand-edited it.
+ * - Missing files are a no-op: callers can re-run uninstall idempotently.
+ * - `.claude/` is not touched; skills / plugins / hooks have their own
+ *   uninstall paths.
+ *
+ * `onLog`, when provided, receives one human-readable line per action so
+ * the SSE caller (server.ts) can stream progress to the browser. Internal
+ * `log.ok / warn / error` calls still go to stderr for the CLI path.
+ */
+export declare function uninstallWorkflow(opts: {
+    force?: boolean;
+    cwd: string;
+    onLog?: (line: string) => void;
+}): Promise<void>;

package/dist/workflow.js

@@ -53,3 +53,66 @@ export async function installWorkflow(packageRoot, opts) {
     fs.symlinkSync("CLAUDE.md", targetAgents);
     log.ok("AGENTS.md -> CLAUDE.md symlink created");
 }
+/**
+ * Uninstall the workflow (CLAUDE.md + AGENTS.md) from `opts.cwd`.
+ *
+ * Safety contract:
+ * - `opts.force` MUST be true. The CLI / server caller is responsible for
+ *   confirming user intent BEFORE invoking this; we refuse otherwise.
+ * - `AGENTS.md` is removed ONLY if it's a symlink (the install-time shape).
+ *   A real-file AGENTS.md is left in place with a warning — the user has
+ *   diverged from the install pattern and probably hand-edited it.
+ * - Missing files are a no-op: callers can re-run uninstall idempotently.
+ * - `.claude/` is not touched; skills / plugins / hooks have their own
+ *   uninstall paths.
+ *
+ * `onLog`, when provided, receives one human-readable line per action so
+ * the SSE caller (server.ts) can stream progress to the browser. Internal
+ * `log.ok / warn / error` calls still go to stderr for the CLI path.
+ */
+export async function uninstallWorkflow(opts) {
+    if (opts.force !== true) {
+        throw new Error("workflow uninstall requires force=true");
+    }
+    const resolved = path.resolve(opts.cwd);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+        throw new Error(`Not a valid directory: ${resolved}`);
+    }
+    const emit = (line) => {
+        opts.onLog?.(line);
+    };
+    const targetClaude = path.join(resolved, "CLAUDE.md");
+    const targetAgents = path.join(resolved, "AGENTS.md");
+    // CLAUDE.md — flat file. lstat to avoid following a symlink (would be
+    // unusual but we'd rather refuse to traverse than chase one out).
+    if (fs.existsSync(targetClaude)) {
+        fs.unlinkSync(targetClaude);
+        log.ok("CLAUDE.md removed");
+        emit("removed CLAUDE.md");
+    }
+    else {
+        log.skip("CLAUDE.md not present");
+        emit("CLAUDE.md not present");
+    }
+    // AGENTS.md — only remove symlinks (our install shape). lstatSync
+    // refuses to follow the link so we inspect the link itself.
+    try {
+        const stat = fs.lstatSync(targetAgents);
+        if (stat.isSymbolicLink()) {
+            fs.unlinkSync(targetAgents);
+            log.ok("AGENTS.md symlink removed");
+            emit("removed AGENTS.md symlink");
+        }
+        else {
+            // Real file (or directory) — user diverged from install. Don't
+            // silently destroy their content; warn and leave it.
+            log.warn("AGENTS.md is not a symlink; left in place");
+            emit("AGENTS.md is not a symlink; left in place");
+        }
+    }
+    catch {
+        // ENOENT — already gone, idempotent no-op.
+        log.skip("AGENTS.md not present");
+        emit("AGENTS.md not present");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins, Hooks)",
   "license": "MIT",
   "repository": {
@@ -25,10 +25,12 @@
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "pretest": "npm run build",
-    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/skills.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js",
-    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/skills.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js",
+    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-uninstall.test.js",
+    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-uninstall.test.js",
     "pretest:e2e": "npm run build",
     "test:e2e": "tsc -p tsconfig.test.json && node --test dist-test/tests/e2e-install.test.js",
+    "pretest:web-ui-e2e": "npm run build && npm --prefix ui ci && npm --prefix ui run build",
+    "test:web-ui-e2e": "tsc -p tsconfig.test.json && node --test dist-test/tests/web-ui-e2e.test.js",
     "test:session-instructions-loader": "node tests/session-instructions-loader.test.mjs",
     "test:git-guards": "node tests/commit-reminder.test.mjs && node tests/pr-create-guard.test.mjs && node tests/pr-ready-guard.test.mjs"
   },