auriga-cli 1.17.0 → 1.18.2

package/README.md

@@ -113,7 +113,9 @@ Installs selected skills via `npx skills add`, targeting both Claude Code and Co
 | 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 |
+| deprecation-and-migration | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | Sunset, replace, or migrate legacy code — deprecation discipline |
 | 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 |
+| documentation-and-adrs | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | Record architectural decisions and the *why* — context for future engineers / agents |
 | frontend-design | [anthropics/skills](https://github.com/anthropics/skills) | Distinctive, production-grade frontend UI generation that avoids generic AI aesthetics |
 | make-interfaces-feel-better | [jakubkrehel/make-interfaces-feel-better](https://github.com/jakubkrehel/make-interfaces-feel-better) | Polish principles — animations, surfaces, typography, performance |
 

package/README.zh-CN.md

@@ -113,7 +113,9 @@ npx auriga-cli
 | 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 会话，做跨模型覆盖 |
+| deprecation-and-migration | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | 废弃与迁移流程 —— 安全地下线、替换或迁移遗留代码 |
 | design-taste-frontend | [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) | 高阶 UI/UX 工程师 —— 度量化设计规则与严格的组件架构约束 |
+| documentation-and-adrs | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | 记录架构决策与"为什么" —— 为后来的工程师和 Agent 沉淀上下文 |
 | frontend-design | [anthropics/skills](https://github.com/anthropics/skills) | 生成有辨识度、production 级的前端界面，避开常见 AI 同质化美学 |
 | make-interfaces-feel-better | [jakubkrehel/make-interfaces-feel-better](https://github.com/jakubkrehel/make-interfaces-feel-better) | 界面打磨原则 —— 动画、表面、排版、性能 |
 

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.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-12T11:30:47.843Z",
+  "generatedAt": "2026-05-12T13:41:34.719Z",
   "workflowSkills": [
     {
       "name": "brainstorming",
@@ -51,10 +51,18 @@
       "name": "codex-agent",
       "description": "Delegate coding, review, diagnosis, planning, and browser tasks to an independent Codex session via `codex exec` / resume / review."
     },
+    {
+      "name": "deprecation-and-migration",
+      "description": "Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code."
+    },
     {
       "name": "design-taste-frontend",
       "description": "Senior UI/UX Engineer. Architect digital interfaces overriding default LLM biases. Enforces metric-based rules, strict component architecture, CSS hardware acceleration, and balanced design engineering."
     },
+    {
+      "name": "documentation-and-adrs",
+      "description": "Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase."
+    },
     {
       "name": "frontend-design",
       "description": "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics."

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,39 @@ 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 "";
+    }
+}
+/** Read `plugins/<name>/.claude-plugin/plugin.json` (or `.codex-plugin/plugin.json`
+ *  as fallback) and return the `version` field. Returns "" when no manifest
+ *  exists or the JSON is malformed — the scanner then leaves expectedVersion
+ *  unset, which means external-marketplace plugins (whose source lives
+ *  upstream, not in this repo) get the "trust installed" classification. */
+async function readPluginManifestVersion(packageRoot, name) {
+    const candidates = [
+        path.join(packageRoot, "plugins", name, ".claude-plugin", "plugin.json"),
+        path.join(packageRoot, "plugins", name, ".codex-plugin", "plugin.json"),
+    ];
+    for (const p of candidates) {
+        try {
+            const raw = await readFile(p, "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.version === "string" && parsed.version.length > 0) {
+                return parsed.version;
+            }
+        }
+        catch {
+            /* try next candidate */
+        }
+    }
+    return "";
+}
 const WORKFLOW_VERSION_RE = /^#\s*auriga Workflow\s*\(v([\d.]+)\)/m;
 async function tryReadFile(p) {
     try {
@@ -29,10 +64,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 +72,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 +91,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 +138,49 @@ 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 };
+        // Bake expectedVersion from the owned plugin's manifest. For Claude-side
+        // plugins prefer plugins/<name>/.claude-plugin/plugin.json; fall back to
+        // .codex-plugin/plugin.json for codex-only plugins (e.g.
+        // session-instructions-loader). External-marketplace plugins (skill-creator,
+        // claude-md-management, codex) have no local manifest — they install from
+        // their upstream marketplace, so we deliberately leave expectedVersion
+        // undefined. The scanner then falls through to "trust whatever is installed",
+        // which matches what the user agreed to when they registered the upstream.
+        const expectedVersion = await readPluginManifestVersion(packageRoot, entry.name);
+        plugins[entry.name] = {
+            description: entry.description,
+            agents,
+            ...(expectedVersion ? { 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[];
 }>;