auriga-cli 1.18.0 → 1.18.3

package/dist/api-types.d.ts

@@ -1,4 +1,13 @@
 export type ItemStatus = "installed" | "update-available" | "not-installed";
+/**
+ * Per-category scan scope. Each category (workflow / skills / plugins / hooks)
+ * can be independently scanned in either user scope (~/.claude/, ~/.codex/)
+ * or project scope (<proj>/.claude/). The Web UI's per-column scope picker
+ * carries these through the `/api/state` query so the scanner reads the
+ * right truth source per category. Codex plugins are user-scope only by
+ * design and ignore this field.
+ */
+export type ScanScope = "user" | "project";
 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
@@ -16,6 +25,13 @@ export interface WorkflowState {
     status: ItemStatus;
     currentVersion?: string;
     expectedVersion: string;
+    /** Which scope the scanner read to produce this row. Reflects the scope
+     *  scanned, not where the file was found — e.g. when scope=user and
+     *  ~/.claude/CLAUDE.md is absent, observedScope is still "user". The
+     *  scanner ALWAYS sets this field at runtime; it is typed optional only
+     *  so the mergePluginsById regression helper (which carries over from the
+     *  pre-rewrite suite without an explicit scope) continues to compile. */
+    observedScope?: ScanScope;
 }
 export interface SkillState {
     name: string;
@@ -24,6 +40,8 @@ export interface SkillState {
     isWorkflow: boolean;
     currentHash?: string;
     expectedHash: string;
+    /** Scope the scanner read to produce this row. See WorkflowState comment. */
+    observedScope?: ScanScope;
 }
 export type ApplyAgent = "claude" | "codex";
 export interface PluginState {
@@ -41,6 +59,10 @@ export interface PluginState {
     currentVersion?: string;
     expectedVersion?: string;
     versionSource: "upstream-live" | "catalog";
+    /** Scope the scanner read to produce this row. Codex plugins are always
+     *  "user" (Codex has no project-scope plugin concept). See WorkflowState
+     *  comment on why this is typed optional. */
+    observedScope?: ScanScope;
 }
 export interface HookState {
     name: string;
@@ -48,9 +70,11 @@ export interface HookState {
     status: ItemStatus;
     currentHash?: string;
     expectedHash: string;
+    /** Scope the scanner read to produce this row. See WorkflowState comment. */
+    observedScope?: ScanScope;
 }
 export interface StateWarning {
-    code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline";
+    code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline" | "claude-code-not-installed" | "settings-unreadable" | "skill-malformed" | "workflow-unknown-version";
     message: string;
 }
 export type ApplyCategory = "workflow" | "skill" | "recommended-skill" | "plugin" | "hook";

package/dist/catalog.d.ts

@@ -1,6 +1,14 @@
 export interface CatalogEntry {
     name: string;
     description: string;
+    /** Build-time-baked plugin version. Set ONLY for plugin entries whose
+     *  source lives in this repo's `plugins/<name>/` directory — the scanner
+     *  uses it to surface "update-available" when the user's installed copy
+     *  is older. Absent for skill / hook entries and for external-marketplace
+     *  plugins (whose manifest lives upstream). Must be baked at build time
+     *  because `plugins/<name>/.claude-plugin/plugin.json` is NOT shipped in
+     *  the npm tarball (see `package.json` `files` field). */
+    expectedVersion?: string;
 }
 export interface Catalog {
     generatedAt: string;

package/dist/catalog.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-12T11:46:16.926Z",
+  "generatedAt": "2026-05-12T13:58:42.583Z",
   "workflowSkills": [
     {
       "name": "brainstorming",
@@ -87,19 +87,23 @@
     },
     {
       "name": "auriga-go",
-      "description": "(Claude/Codex) Workflow autopilot for the auriga workflow. Reminder-based navigation across CLAUDE.md's phases. Bundles a /goalify skill that plans an autonomous goal from a spec or work-in-progress and dispatches it via Claude Code's built-in /goal command."
+      "description": "(Claude/Codex) Workflow autopilot for the auriga workflow. Reminder-based navigation across CLAUDE.md's phases. Bundles a /goalify skill that plans an autonomous goal from a spec or work-in-progress and dispatches it via Claude Code's built-in /goal command.",
+      "expectedVersion": "1.1.0"
     },
     {
       "name": "auriga-git-guards",
-      "description": "(Claude/Codex) Git lifecycle guardrails: commit-reminder + PR-create snapshot inject + PR-ready structural block. Bundles the git-workflow skill (Claude Code + Codex)."
+      "description": "(Claude/Codex) Git lifecycle guardrails: commit-reminder + PR-create snapshot inject + PR-ready structural block. Bundles the git-workflow skill (Claude Code + Codex).",
+      "expectedVersion": "1.1.0"
     },
     {
       "name": "deep-review",
-      "description": "(Claude/Codex) Multi-dimensional PR review orchestrator. Dispatches parallel reviewers (spec-conformance, correctness, test-quality, docs-sync, robustness, security, ux, performance, structure, code-quality, skill-plugin-quality) and synthesizes findings into an actionable punch list. Supports project-level custom reviewers via docs/rules/review/ and ships a reviewer-creator skill for scaffolding them."
+      "description": "(Claude/Codex) Multi-dimensional PR review orchestrator. Dispatches parallel reviewers (spec-conformance, correctness, test-quality, docs-sync, robustness, security, ux, performance, structure, code-quality, skill-plugin-quality) and synthesizes findings into an actionable punch list. Supports project-level custom reviewers via docs/rules/review/ and ships a reviewer-creator skill for scaffolding them.",
+      "expectedVersion": "0.3.1"
     },
     {
       "name": "session-instructions-loader",
-      "description": "(Codex) Injects extra instruction files on session start"
+      "description": "(Codex) Injects extra instruction files on session start",
+      "expectedVersion": "1.0.0"
     }
   ],
   "hooks": [

package/dist/cli.js

@@ -562,7 +562,12 @@ async function dispatchInstaller(category, packageRoot, opts) {
 // ---------------------------------------------------------------------------
 const UI_DEFAULT_PORT = 4747;
 const UI_PORT_RANGE = 10; // 4747..4756
-const UI_HEARTBEAT_TIMEOUT_MS = 15_000;
+// 2 minutes covers Chrome's "intensive throttling" of background tabs
+// (kicks in after ~5 min of being hidden, drops setInterval to ~1 ping/min).
+// At 15s the browser tab being switched away for a moment would tear down
+// the server — bad UX. Closing the browser now takes up to 2 min to release
+// the port; users who care can ctrl+C the CLI for immediate exit.
+const UI_HEARTBEAT_TIMEOUT_MS = 120_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");

package/dist/scan-catalog.js

@@ -8,7 +8,9 @@
 //   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/hooks/hooks.json — registers settingsEvents per hook (event /
+//                           matcher / if) used by state.ts for drift
+//                           detection in <scope>/.claude/settings.json
 //   CLAUDE.md             — `# auriga Workflow (vX.Y.Z)` provides
 //                           workflowVersion
 //
@@ -20,6 +22,15 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { loadCatalog } from "./catalog.js";
+async function sha256SkillMd(skillsRoot, name) {
+    try {
+        const buf = await readFile(path.join(skillsRoot, name, "SKILL.md"));
+        return createHash("sha256").update(buf).digest("hex");
+    }
+    catch {
+        return "";
+    }
+}
 const WORKFLOW_VERSION_RE = /^#\s*auriga Workflow\s*\(v([\d.]+)\)/m;
 async function tryReadFile(p) {
     try {
@@ -29,10 +40,6 @@ async function tryReadFile(p) {
         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.
@@ -41,22 +48,18 @@ export async function buildScanCatalog(packageRoot) {
     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
-        }
-    }
+    // Skills + recommended: sha256 of each shipped SKILL.md. This is the same
+    // hash the scanner computes for `<scope>/.claude/skills/<name>/SKILL.md`
+    // at scan time, so a match means "user's installed copy is identical to
+    // the version auriga-cli ships". skills-lock.json's `computedHash` field
+    // hashes the entire skill directory (every file, sorted), which doesn't
+    // line up with the scanner's per-file model — we deliberately ignore it.
+    const skillsRoot = path.join(packageRoot, ".agents", "skills");
     const skills = {};
     for (const entry of dist.workflowSkills) {
         skills[entry.name] = {
             description: entry.description,
-            expectedHash: lock.skills?.[entry.name]?.computedHash ?? "",
+            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
             isWorkflow: true,
         };
     }
@@ -64,7 +67,7 @@ export async function buildScanCatalog(packageRoot) {
     for (const entry of dist.recommendedSkills) {
         recommendedSkills[entry.name] = {
             description: entry.description,
-            expectedHash: lock.skills?.[entry.name]?.computedHash ?? "",
+            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
         };
     }
     // Plugins: split by agent based on which config file lists them. A
@@ -111,22 +114,48 @@ export async function buildScanCatalog(packageRoot) {
             agents.push("codex");
         if (agents.length === 0)
             agents.push("claude"); // unknown defaults to claude
-        plugins[entry.name] = { description: entry.description, agents };
+        // expectedVersion comes from the build-time-baked field in dist/catalog.json
+        // (populated by `src/build/generate-catalog.ts` from
+        // `plugins/<name>/.claude-plugin/plugin.json`). It MUST be baked at build
+        // time because `plugins/<name>/` is NOT shipped in the npm tarball
+        // (`package.json` `files` field allowlists only `dist/`), so reading it
+        // at runtime from packageRoot would silently fail for npm-installed users.
+        plugins[entry.name] = {
+            description: entry.description,
+            agents,
+            ...(typeof entry.expectedVersion === "string" && entry.expectedVersion.length > 0
+                ? { expectedVersion: entry.expectedVersion }
+                : {}),
+        };
+    }
+    // Hooks: the scanner reads <scope>/.claude/settings.json and matches by
+    // `_marker` (see state.ts scanHooks). Drift detection compares the
+    // registered event / matcher / if values against the hook's canonical
+    // settingsEvents[0] from .claude/hooks/hooks.json. We deliberately do NOT
+    // hash index.mjs — the user's installed index.mjs lives at <scope>/.claude/
+    // hooks/<name>/index.mjs and isn't part of the settings.json drift signal.
+    const hooksJsonPath = path.join(packageRoot, ".claude", "hooks", "hooks.json");
+    const hooksJsonRaw = await tryReadFile(hooksJsonPath);
+    const hooksJson = hooksJsonRaw ? JSON.parse(hooksJsonRaw) : {};
+    const settingsEventsByName = new Map();
+    for (const h of hooksJson.hooks ?? []) {
+        if (typeof h.name === "string" && h.settingsEvents?.length) {
+            settingsEventsByName.set(h.name, h.settingsEvents[0]);
+        }
     }
-    // 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 };
+        const ev = settingsEventsByName.get(entry.name);
+        hooks[entry.name] = {
+            description: entry.description,
+            // Empty expectedHash flips state.ts into wildcard mode — drift judged
+            // purely from the structured expected* fields below, not from a
+            // settings-entry content hash.
+            expectedHash: "",
+            ...(typeof ev?.event === "string" ? { expectedEvent: ev.event } : {}),
+            ...(typeof ev?.matcher === "string" ? { expectedMatcher: ev.matcher } : {}),
+            ...(typeof ev?.if === "string" ? { expectedIf: ev.if } : {}),
+        };
     }
     return {
         workflowVersion,

package/dist/server.js

@@ -7,13 +7,14 @@
 //
 // Public contract is anchored in docs/architecture/web-ui.md §4 (server
 // surface), §6 (data flow + types), §7 (errors).
+import { spawnSync } from "node:child_process";
 import { createServer } from "node:http";
 import { Buffer } from "node:buffer";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { buildScanCatalog } from "./scan-catalog.js";
-import { scanState } from "./state.js";
+import { defaultExecPluginList, scanState } from "./state.js";
 // Body parsing cap. /api/apply payloads are tiny (an array of item refs);
 // 1 MiB is generously above the largest realistic batch and small enough that
 // abusive clients can't pin memory.
@@ -576,7 +577,7 @@ export async function startServer(opts) {
             return;
         }
         if (pathname === "/api/state" && method === "GET") {
-            await routeState(opts.cwd, opts.packageRoot ?? opts.cwd, res);
+            await routeState(opts.cwd, opts.packageRoot ?? opts.cwd, searchParams, res);
             return;
         }
         if (pathname === "/api/apply" && method === "POST") {
@@ -705,10 +706,21 @@ export async function startServer(opts) {
 // ---------------------------------------------------------------------------
 // Route: GET /api/state
 // ---------------------------------------------------------------------------
-async function routeState(cwd, packageRoot, res) {
+async function routeState(cwd, packageRoot, searchParams, res) {
     try {
         const catalog = await buildScanCatalog(packageRoot);
-        const report = await scanState(cwd, catalog);
+        const scopes = parseScopesParam(searchParams);
+        // Only wire `defaultExecPluginList` if the `claude` CLI is on PATH —
+        // otherwise the scanner's degraded-path warning ("claude-cli-missing")
+        // is what we want the UI to surface. Cache the result per process so we
+        // don't re-`which` on every /api/state poll.
+        const execPluginList = isClaudeOnPath()
+            ? (scope) => defaultExecPluginList(scope, cwd)
+            : undefined;
+        const report = await scanState(cwd, catalog, {
+            ...(scopes ? { scopes } : {}),
+            ...(execPluginList ? { execPluginList } : {}),
+        });
         sendJson(res, 200, report);
     }
     catch {
@@ -717,6 +729,40 @@ async function routeState(cwd, packageRoot, res) {
         sendJson(res, 500, { error: "scan-failed" });
     }
 }
+let claudeOnPathCache = null;
+function isClaudeOnPath() {
+    if (claudeOnPathCache !== null)
+        return claudeOnPathCache;
+    const res = spawnSync("which", ["claude"], { stdio: "ignore" });
+    claudeOnPathCache = res.status === 0;
+    return claudeOnPathCache;
+}
+/**
+ * Parses the /api/state `scopes` query into a per-category map for
+ * `scanState`. The query string shape is comma-separated `category:scope`
+ * pairs, e.g. `?scopes=workflow:user,skills:project,plugins:user`. Unknown
+ * categories and unknown scope values are dropped (rather than throwing) so
+ * the scanner falls back to install defaults on garbled input — keeps the
+ * Web UI degraded-but-functional rather than 500-ing on a stale link.
+ *
+ * Returns `null` when the param is absent so the caller can omit `opts.scopes`
+ * entirely and let `scanState` apply its built-in defaults.
+ */
+function parseScopesParam(searchParams) {
+    const raw = searchParams.get("scopes");
+    if (!raw)
+        return null;
+    const allowedCategories = new Set(["workflow", "skills", "plugins", "hooks"]);
+    const allowedScopes = new Set(["user", "project"]);
+    const out = {};
+    for (const pair of raw.split(",")) {
+        const [cat, scope] = pair.split(":");
+        if (allowedCategories.has(cat) && allowedScopes.has(scope)) {
+            out[cat] = scope;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 // ---------------------------------------------------------------------------
 // Route: GET /api/catalog
 // ---------------------------------------------------------------------------

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import type { PluginState, StateReport } from "./api-types.js";
+import type { PluginState, ScanScope, StateReport } from "./api-types.js";
 export interface Catalog {
     workflowVersion: string;
     skills: Record<string, {
@@ -18,16 +18,51 @@ export interface Catalog {
     }>;
     hooks: Record<string, {
         description: string;
+        /** Coarse drift signal. The current production scan-catalog still
+         *  populates this with sha256(index.mjs) for back-compat with the v0.x
+         *  scanner that hashed the user's installed script. The new
+         *  settings.json-based scanner ignores it for drift comparison unless
+         *  the catalog also exposes the structured expected* fields below. */
         expectedHash: string;
+        /** Settings.json event name (e.g. "PostToolUse", "Notification"). When
+         *  set, the scanner flags drift if the on-disk settings entry registers
+         *  under a different event. Optional; left undefined the scanner trusts
+         *  whatever event the marker was found under. */
+        expectedEvent?: string;
+        /** Settings.json `matcher` field (e.g. "Write|Edit" for PostToolUse).
+         *  Empty string means "no matcher" (e.g. Notification hooks). When set,
+         *  the scanner flags drift if the on-disk value differs. */
+        expectedMatcher?: string;
+        /** Settings.json `if` field (Claude-Code-specific filter expression).
+         *  Same drift semantics as expectedMatcher. */
+        expectedIf?: string;
     }>;
 }
 export interface ScanOptions {
-    execPluginList?: () => Promise<{
+    /** Run `claude plugins list` for the given scope. The scope argument is
+     *  required so server.ts can pass --user / --project through to the CLI
+     *  per opts.scopes.plugins. Implementations may accept a zero-arg legacy
+     *  form for back-compat but MUST honor a scope argument when given. */
+    execPluginList?: (scope: ScanScope) => Promise<{
         installed: any[];
         available: any[];
     }>;
     readCodexConfig?: () => Promise<string | null>;
     readCodexPluginsDir?: () => Promise<Map<string, string>>;
+    /** Per-category scope picker. Each field is independently routed to the
+     *  right truth source. Defaults match the Web UI's per-column picker:
+     *    workflow = 'project', skills = 'project',
+     *    plugins  = 'user',    hooks  = 'user'. */
+    scopes?: {
+        workflow?: ScanScope;
+        skills?: ScanScope;
+        plugins?: ScanScope;
+        hooks?: ScanScope;
+    };
+    /** Test-time HOME override. When unset the scanner reads os.homedir()
+     *  (which itself consults process.env.HOME / USERPROFILE), so tests that
+     *  redirect HOME via env vars also work. */
+    homeDir?: string;
 }
 export declare function scanState(projectRoot: string, catalog: Catalog, opts?: ScanOptions): Promise<StateReport>;
 /**
@@ -48,10 +83,12 @@ export declare function scanState(projectRoot: string, catalog: Catalog, opts?:
  * we'll need a deliberate merge policy.
  */
 export declare function mergePluginsById(records: PluginState[]): PluginState[];
-/** Default: run `claude plugins list --json` and `claude plugins list
- *  --available --json`. Returns null is NOT an option here — server.ts
- *  decides whether to pass this function based on `which claude`. */
-export declare function defaultExecPluginList(): Promise<{
+/** Default: run `claude plugins list --json` (no scope flag — the CLI
+ *  doesn't expose one) plus the `--available` variant, then filter the
+ *  installed records to the requested scope (and current projectRoot for
+ *  project-scope) client-side. Server.ts decides whether to pass this
+ *  function based on `which claude`. */
+export declare function defaultExecPluginList(scope?: ScanScope, projectRoot?: string): Promise<{
     installed: any[];
     available: any[];
 }>;