auriga-cli 1.17.0 → 1.18.2

package/dist/state.js

@@ -1,9 +1,19 @@
-// scanState — read the user's project + (optionally) live CLIs to produce
-// a tri-state report per category. Pure-ish: all external I/O is either
-// injected via `ScanOptions` (for tests) or done through the default
-// filesystem / child-process implementations declared at the bottom of
-// this file. See docs/architecture/web-ui.md §6.3 + §10.4 for the judgment rules
-// and tests/state.test.ts for the full behavioral contract.
+// scanState — produce a tri-state install report (installed / update-available /
+// not-installed) for every category, reading the *actual* Claude Code install
+// locations rather than auriga-cli's own dev-repo layout. The truth sources
+// (per docs/specs/web-ui-scanner-redesign.md):
+//
+//   Workflow:  ~/.claude/CLAUDE.md                          (user scope)
+//              <proj>/CLAUDE.md, fallback .claude/CLAUDE.md (project scope)
+//   Skills:    ~/.claude/skills/<name>/SKILL.md             (user scope)
+//              <proj>/.claude/skills/<name>/SKILL.md        (project scope)
+//   Plugins(Claude): execPluginList(scope) + settings.json enabledPlugins
+//   Plugins(Codex):  ~/.codex/config.toml + ~/.codex/plugins/cache (user only)
+//   Hooks:     <scope>/.claude/settings.json `hooks` segment, matched by _marker
+//
+// External I/O is either injected via ScanOptions (tests) or done through the
+// default implementations at the bottom of the file (server.ts production
+// wiring). See tests/state.test.ts for the full behavioral contract.
 import { createHash } from "node:crypto";
 import { exec as execCallback } from "node:child_process";
 import { promisify } from "node:util";
@@ -12,14 +22,19 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parse as parseToml } from "smol-toml";
+/** Wildcard sentinel for the catalog hook `expectedHash` field. A value
+ *  equal to this string (or the empty string) is treated as "no drift
+ *  expectation, trust marker presence" — useful when the catalog hasn't yet
+ *  been populated with a real settings-entry signature. The test suite uses
+ *  this sentinel explicitly (see tests/state.test.ts assumption A7). */
+const WILDCARD_EXPECTED_HASH = "any";
 /**
  * Shorten an absolute path by replacing the user's $HOME with `~`. Avoids
  * leaking the full username in screenshots and keeps the TopBar label
  * readable. Falls back to the original path when HOME is unset or the path
  * doesn't sit under it.
  */
-function homeReducedPath(p) {
-    const home = os.homedir();
+function homeReducedPath(p, home) {
     if (!home)
         return p;
     if (p === home)
@@ -30,19 +45,39 @@ function homeReducedPath(p) {
     }
     return p;
 }
+const DEFAULT_SCOPES = {
+    workflow: "project",
+    skills: "project",
+    plugins: "user",
+    hooks: "user",
+};
 export async function scanState(projectRoot, catalog, opts = {}) {
     const warnings = [];
-    const workflow = scanWorkflow(projectRoot, catalog);
-    const lock = readSkillsLock(projectRoot);
-    const skills = scanSkills(catalog.skills, lock);
-    const recommendedSkills = scanRecommendedSkills(catalog.recommendedSkills, lock);
-    const hooks = scanHooks(projectRoot, catalog.hooks);
+    const home = opts.homeDir ?? os.homedir();
+    const scopes = { ...DEFAULT_SCOPES, ...(opts.scopes ?? {}) };
+    const workflow = scanWorkflow(scopes.workflow, projectRoot, home, catalog, warnings);
+    const skills = scanSkills(scopes.skills, projectRoot, home, catalog.skills, 
+    /* recommended */ false, warnings);
+    const recommendedSkills = scanRecommendedSkills(scopes.skills, projectRoot, home, catalog.recommendedSkills, warnings);
+    const hooks = scanHooks(scopes.hooks, projectRoot, home, catalog.hooks, warnings);
     const claudePluginEntries = filterPluginsByAgent(catalog.plugins, "claude");
     const codexPluginEntries = filterPluginsByAgent(catalog.plugins, "codex");
-    const claudePlugins = await scanClaudePlugins(claudePluginEntries, opts.execPluginList, warnings);
+    const claudePlugins = await scanClaudePlugins(scopes.plugins, claudePluginEntries, opts.execPluginList, warnings);
     const codexPlugins = await scanCodexPlugins(codexPluginEntries, opts.readCodexConfig ?? defaultReadCodexConfig, opts.readCodexPluginsDir ?? defaultReadCodexPluginsDir, warnings);
+    // Aggregate `claude-code-not-installed`: emit ONCE if neither ~/.claude/
+    // nor <proj>/.claude/ exists, regardless of how many user-scope categories
+    // were scanned. We check after the per-category scans so we can detect the
+    // condition just once at the end.
+    if (!dirExists(path.join(home, ".claude")) && !dirExists(path.join(projectRoot, ".claude"))) {
+        if (!warnings.some((w) => w.code === "claude-code-not-installed")) {
+            warnings.push({
+                code: "claude-code-not-installed",
+                message: "No Claude Code install detected (~/.claude/ and <project>/.claude/ both absent). Install Claude Code first.",
+            });
+        }
+    }
     return {
-        cwd: homeReducedPath(projectRoot),
+        cwd: homeReducedPath(projectRoot, home),
         workflow,
         skills,
         recommendedSkills,
@@ -51,6 +86,14 @@ export async function scanState(projectRoot, catalog, opts = {}) {
         warnings,
     };
 }
+function dirExists(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Dedupe plugins by `id`, merging dual-Agent records into a single
  * multi-agent row. Aggregation rules:
@@ -106,81 +149,108 @@ function aggregateStatus(statuses) {
         return "not-installed";
     // Anything else — partial install, pending updates on any agent, mixed
     // — falls through to update-available so a single Apply backfills the
-    // missing pieces. This is the boundary the user asked for: "一边装一边
-    // 没装" surfaces as a yellow UPDATE pill rather than a misleading green.
+    // missing pieces.
     return "update-available";
 }
 // ---------------------------------------------------------------------------
 // Workflow
 // ---------------------------------------------------------------------------
 const WORKFLOW_HEADER_RE = /^#\s+auriga\s+Workflow\s*\(v(\d+\.\d+\.\d+)\)/;
-function scanWorkflow(projectRoot, catalog) {
+function workflowPathsForScope(scope, projectRoot, home) {
+    if (scope === "user") {
+        return [path.join(home, ".claude", "CLAUDE.md")];
+    }
+    // Project: <proj>/CLAUDE.md preferred, .claude/CLAUDE.md as fallback.
+    return [
+        path.join(projectRoot, "CLAUDE.md"),
+        path.join(projectRoot, ".claude", "CLAUDE.md"),
+    ];
+}
+function scanWorkflow(scope, projectRoot, home, catalog, warnings) {
     const expectedVersion = catalog.workflowVersion;
-    const claudeMdPath = path.join(projectRoot, "CLAUDE.md");
-    let content;
-    try {
-        content = fs.readFileSync(claudeMdPath, "utf8");
+    const candidates = workflowPathsForScope(scope, projectRoot, home);
+    let content = null;
+    for (const candidate of candidates) {
+        try {
+            content = fs.readFileSync(candidate, "utf8");
+            break;
+        }
+        catch {
+            // try next candidate
+        }
     }
-    catch {
-        return { status: "not-installed", expectedVersion };
+    if (content === null) {
+        return { status: "not-installed", expectedVersion, observedScope: scope };
     }
-    // Match the canonical header anywhere in the first few lines; the spec
-    // and tests put it on the first line, but tolerate leading blank lines /
-    // BOM by scanning every line until we either find a match or run out.
+    // Walk the first non-blank lines looking for the auriga header.
     for (const line of content.split(/\r?\n/)) {
         const m = WORKFLOW_HEADER_RE.exec(line);
         if (m) {
             const currentVersion = m[1];
-            const status = currentVersion === expectedVersion ? "installed" : "update-available";
-            return { status, expectedVersion, currentVersion };
+            // Empty expectedVersion means scan-catalog couldn't extract the
+            // shipped workflow's header (auriga-cli's own CLAUDE.md missing or
+            // malformed at build time). Trust the installed version rather than
+            // forcing a phantom "update-available" against the empty string.
+            const status = !expectedVersion || currentVersion === expectedVersion ? "installed" : "update-available";
+            return { status, expectedVersion, currentVersion, observedScope: scope };
         }
-        // Bail at the first non-blank line — the header must be a top heading.
         if (line.trim().length > 0)
             break;
     }
-    // File exists but no parseable header → assumption #1 in state.test.ts:
-    // prefer reinstall over false-positive "installed" with unknown version.
-    return { status: "not-installed", expectedVersion };
+    // CLAUDE.md exists but no recognizable auriga marker. Per spec degraded
+    // path: status remains "installed" (don't clobber user content on apply)
+    // and emit a workflow-unknown-version warning.
+    warnings.push({
+        code: "workflow-unknown-version",
+        message: `CLAUDE.md present but no auriga-workflow header found; cannot determine installed version.`,
+    });
+    return { status: "installed", expectedVersion, observedScope: scope };
 }
-/** Return the parsed lockfile, or null if absent / unparseable. The "null"
- *  path is the degraded mode: skills still show up as catalog rows but their
- *  `currentHash` is undefined and they are reported as not-installed. */
-function readSkillsLock(projectRoot) {
-    const lockPath = path.join(projectRoot, "skills-lock.json");
-    let text;
+// ---------------------------------------------------------------------------
+// Skills + recommendedSkills
+// ---------------------------------------------------------------------------
+function skillsRoot(scope, projectRoot, home) {
+    if (scope === "user")
+        return path.join(home, ".claude", "skills");
+    return path.join(projectRoot, ".claude", "skills");
+}
+/** Classify a single skill by reading its SKILL.md from the scope's skills
+ *  dir. Returns the status + (when readable) the on-disk content hash. The
+ *  `malformedSeen` set is mutated when a skill dir exists but SKILL.md is
+ *  missing/unreadable — the caller emits ONE skill-malformed warning per
+ *  scan. */
+function classifySkillByFile(name, expectedHash, rootDir, malformedSeen) {
+    const skillDir = path.join(rootDir, name);
+    const skillMd = path.join(skillDir, "SKILL.md");
+    let buf;
     try {
-        text = fs.readFileSync(lockPath, "utf8");
+        buf = fs.readFileSync(skillMd);
     }
     catch {
-        return null;
-    }
-    try {
-        const parsed = JSON.parse(text);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
+        // SKILL.md unreadable. Two sub-cases:
+        //   (a) skill dir also missing → simply not installed.
+        //   (b) skill dir present but SKILL.md missing → malformed; row stays
+        //       "installed" so the user can repair, plus a warning.
+        if (dirExists(skillDir)) {
+            malformedSeen.add(name);
+            return { status: "installed" };
         }
-        return null;
-    }
-    catch {
-        // Per state.test.ts "corrupt skills-lock" case: don't throw; degrade.
-        return null;
-    }
-}
-function classifySkill(expectedHash, lock, name) {
-    const entry = lock?.skills?.[name];
-    const currentHash = entry?.computedHash;
-    if (typeof currentHash !== "string" || currentHash.length === 0) {
         return { status: "not-installed" };
     }
-    if (currentHash === expectedHash) {
+    const currentHash = createHash("sha256").update(buf).digest("hex");
+    if (expectedHash === "" ||
+        expectedHash === WILDCARD_EXPECTED_HASH ||
+        currentHash === expectedHash) {
         return { status: "installed", currentHash };
     }
     return { status: "update-available", currentHash };
 }
-function scanSkills(catalogSkills, lock) {
+function scanSkills(scope, projectRoot, home, catalogSkills, _recommended, warnings) {
+    const rootDir = skillsRoot(scope, projectRoot, home);
+    const malformed = new Set();
     const out = [];
     for (const [name, entry] of Object.entries(catalogSkills)) {
-        const cls = classifySkill(entry.expectedHash, lock, name);
+        const cls = classifySkillByFile(name, entry.expectedHash, rootDir, malformed);
         out.push({
             name,
             description: entry.description,
@@ -188,21 +258,37 @@ function scanSkills(catalogSkills, lock) {
             isWorkflow: entry.isWorkflow,
             currentHash: cls.currentHash,
             expectedHash: entry.expectedHash,
+            observedScope: scope,
+        });
+    }
+    if (malformed.size > 0) {
+        warnings.push({
+            code: "skill-malformed",
+            message: `Skill directory present but SKILL.md missing or unreadable: ${[...malformed].join(", ")}`,
         });
     }
     return out;
 }
-function scanRecommendedSkills(catalogRec, lock) {
+function scanRecommendedSkills(scope, projectRoot, home, catalogRec, warnings) {
+    const rootDir = skillsRoot(scope, projectRoot, home);
+    const malformed = new Set();
     const out = [];
     for (const [name, entry] of Object.entries(catalogRec)) {
-        const cls = classifySkill(entry.expectedHash, lock, name);
+        const cls = classifySkillByFile(name, entry.expectedHash, rootDir, malformed);
         out.push({
             name,
             description: entry.description,
             status: cls.status,
-            isWorkflow: false, // recommended skills are by definition opt-in utilities
+            isWorkflow: false,
             currentHash: cls.currentHash,
             expectedHash: entry.expectedHash,
+            observedScope: scope,
+        });
+    }
+    if (malformed.size > 0) {
+        warnings.push({
+            code: "skill-malformed",
+            message: `Skill directory present but SKILL.md missing or unreadable: ${[...malformed].join(", ")}`,
         });
     }
     return out;
@@ -222,50 +308,63 @@ function parseRef(ref) {
     const m = /^v?(\d+\.\d+\.\d+(?:[-+][\w.]+)?)$/.exec(ref);
     return m ? m[1] : null;
 }
-async function scanClaudePlugins(entries, execPluginList, warnings) {
+async function scanClaudePlugins(scope, entries, execPluginList, warnings) {
     if (entries.length === 0)
         return [];
-    // Degraded path 1: no exec injected AND no default. We expose a default
-    // implementation below that wraps `claude plugins list --available --json`,
-    // but the test contract treats "execPluginList undefined" as "Claude CLI
-    // missing" — we honor that by NOT silently falling back to the default
-    // when the caller leaves it undefined. (server.ts will pass the default
-    // explicitly when it confirms `claude` is on PATH.)
+    // Degraded path 1: no exec injected. The default implementation runs
+    // `claude plugins list`; server.ts decides whether to pass it based on
+    // `which claude`. When undefined → assume `claude` is missing.
     if (!execPluginList) {
         warnings.push({
             code: "claude-cli-missing",
             message: "Claude CLI not available — plugin update detection disabled. Install `claude` to enable update checks.",
         });
-        return entries.map(([id, def]) => degradedClaudeRow(id, def));
+        return entries.map(([id, def]) => degradedClaudeRow(id, def, scope));
     }
     let payload;
     try {
-        payload = await execPluginList();
+        payload = await execPluginList(scope);
     }
     catch (err) {
         warnings.push({
             code: "claude-cli-missing",
             message: `Claude CLI plugin list failed: ${err.message}`,
         });
-        return entries.map(([id, def]) => degradedClaudeRow(id, def));
-    }
+        return entries.map(([id, def]) => degradedClaudeRow(id, def, scope));
+    }
+    // claude plugins list emits ids in `<plugin>@<marketplace>` form (e.g.
+    // `auriga-go@auriga-cli`). The auriga-cli catalog tracks plugins by bare
+    // name. Index both forms so lookups succeed regardless of which side the
+    // suffix is on. Same trick for availables — note that the `--available`
+    // payload uses `pluginId` rather than `id`, so accept both as the key.
+    const indexBoth = (map, item) => {
+        if (!item || typeof item !== "object")
+            return;
+        const key = typeof item.id === "string"
+            ? item.id
+            : typeof item.pluginId === "string"
+                ? item.pluginId
+                : null;
+        if (!key)
+            return;
+        map.set(key, item);
+        const at = key.indexOf("@");
+        if (at > 0)
+            map.set(key.slice(0, at), item);
+    };
     const installedById = new Map();
-    for (const item of payload.installed ?? []) {
-        if (item && typeof item.id === "string")
-            installedById.set(item.id, item);
-    }
+    for (const item of payload.installed ?? [])
+        indexBoth(installedById, item);
     const availableById = new Map();
-    for (const item of payload.available ?? []) {
-        if (item && typeof item.id === "string")
-            availableById.set(item.id, item);
-    }
+    for (const item of payload.available ?? [])
+        indexBoth(availableById, item);
     const out = [];
     for (const [id, def] of entries) {
-        out.push(classifyClaudePlugin(id, def, installedById.get(id), availableById.get(id)));
+        out.push(classifyClaudePlugin(id, def, installedById.get(id), availableById.get(id), scope));
     }
     return out;
 }
-function degradedClaudeRow(id, def) {
+function degradedClaudeRow(id, def, scope) {
     return {
         id,
         description: def.description,
@@ -273,10 +372,10 @@ function degradedClaudeRow(id, def) {
         agents: ["claude"],
         expectedVersion: def.expectedVersion,
         versionSource: "upstream-live",
+        observedScope: scope,
     };
 }
-function classifyClaudePlugin(id, def, installed, available) {
-    // Not installed at all — easy case.
+function classifyClaudePlugin(id, def, installed, available, scope) {
     if (!installed || typeof installed.version !== "string") {
         return {
             id,
@@ -285,39 +384,55 @@ function classifyClaudePlugin(id, def, installed, available) {
             agents: ["claude"],
             expectedVersion: typeof available?.source?.ref === "string" ? available.source.ref : def.expectedVersion,
             versionSource: "upstream-live",
+            observedScope: scope,
         };
     }
     const installedVersion = installed.version;
     const ref = available?.source?.ref;
     const normalizedAvailable = parseRef(typeof ref === "string" ? ref : undefined);
     const normalizedInstalled = parseRef(installedVersion);
-    // Fallback rule 1: installed version "unknown" → trust it's installed.
-    // Fallback rule 2: available.ref is a branch / non-semver → trust it.
-    // Fallback rule 3: available info is missing entirely → trust it (we know
-    //   it's installed, we just can't say if there's a newer one).
-    if (installedVersion === "unknown" ||
-        normalizedAvailable === null ||
-        !available) {
+    // Pick the comparison target. The marketplace-live ref wins when it's a
+    // parseable semver — that's the freshest signal. Otherwise fall back to
+    // the build-time-baked `def.expectedVersion` (populated from
+    // plugins/<name>/.claude-plugin/plugin.json by scan-catalog for owned
+    // plugins). Without the fallback, the common upgrade case is invisible:
+    // `claude plugins list --available --json` excludes already-installed
+    // plugins from `.available[]`, so for any plugin the user already has,
+    // `ref` is undefined and the scanner can't tell whether a newer version
+    // ships in the marketplace.
+    const hasLiveRef = normalizedAvailable !== null && typeof ref === "string";
+    const expectedRaw = hasLiveRef ? ref : def.expectedVersion;
+    const expectedNormalized = hasLiveRef
+        ? normalizedAvailable
+        : parseRef(def.expectedVersion);
+    const versionSource = hasLiveRef
+        ? "upstream-live"
+        : "catalog";
+    // Fallback rules (no comparable expected version, or unknown installed):
+    //   - installed version "unknown" → trust it's installed.
+    //   - effective expected is null (branch ref + no baked version) → trust installed.
+    if (installedVersion === "unknown" || expectedNormalized === null) {
         return {
             id,
             description: def.description,
             status: "installed",
             agents: ["claude"],
             currentVersion: installedVersion,
-            expectedVersion: typeof ref === "string" ? ref : def.expectedVersion,
-            versionSource: "upstream-live",
+            expectedVersion: expectedRaw,
+            versionSource,
+            observedScope: scope,
         };
     }
-    // Both sides comparable.
-    if (normalizedInstalled !== null && normalizedInstalled === normalizedAvailable) {
+    if (normalizedInstalled !== null && normalizedInstalled === expectedNormalized) {
         return {
             id,
             description: def.description,
             status: "installed",
             agents: ["claude"],
             currentVersion: installedVersion,
-            expectedVersion: typeof ref === "string" ? ref : undefined,
-            versionSource: "upstream-live",
+            expectedVersion: expectedRaw,
+            versionSource,
+            observedScope: scope,
         };
     }
     return {
@@ -326,8 +441,9 @@ function classifyClaudePlugin(id, def, installed, available) {
         status: "update-available",
         agents: ["claude"],
         currentVersion: installedVersion,
-        expectedVersion: typeof ref === "string" ? ref : undefined,
-        versionSource: "upstream-live",
+        expectedVersion: expectedRaw,
+        versionSource,
+        observedScope: scope,
     };
 }
 // ---------------------------------------------------------------------------
@@ -359,8 +475,6 @@ async function scanCodexPlugins(entries, readCodexConfig, readCodexPluginsDir, w
         enabledIds = parseCodexEnabledPluginIds(tomlContent);
     }
     catch {
-        // Corrupt TOML — surface a warning but keep classifying as not-installed
-        // for each catalog entry rather than dropping rows.
         warnings.push({
             code: "codex-cli-missing",
             message: "Codex config.toml is unparseable — treating no plugins as installed",
@@ -373,9 +487,36 @@ async function scanCodexPlugins(entries, readCodexConfig, readCodexPluginsDir, w
     catch {
         fsVersions = new Map();
     }
+    // Mirror the Claude side: catalog tracks bare names (e.g. "auriga-go") but
+    // ~/.codex/config.toml [plugins.*] sections and defaultReadCodexPluginsDir
+    // both emit `<plugin>@<marketplace>` keys (e.g. "auriga-go@auriga-cli").
+    // Without dual indexing every dual-Agent plugin reports `not-installed` on
+    // the Codex side, which `mergePluginsById` then folds into a permanent
+    // `update-available` even when both sides are genuinely installed.
+    const lookupEnabled = (catalogId) => {
+        if (enabledIds.has(catalogId))
+            return true;
+        for (const id of enabledIds) {
+            const at = id.indexOf("@");
+            if (at > 0 && id.slice(0, at) === catalogId)
+                return true;
+        }
+        return false;
+    };
+    const lookupFsVersion = (catalogId) => {
+        const direct = fsVersions.get(catalogId);
+        if (direct)
+            return direct;
+        for (const [id, v] of fsVersions) {
+            const at = id.indexOf("@");
+            if (at > 0 && id.slice(0, at) === catalogId)
+                return v;
+        }
+        return undefined;
+    };
     const out = [];
     for (const [id, def] of entries) {
-        out.push(classifyCodexPlugin(id, def, enabledIds.has(id), fsVersions.get(id)));
+        out.push(classifyCodexPlugin(id, def, lookupEnabled(id), lookupFsVersion(id)));
     }
     return out;
 }
@@ -387,6 +528,7 @@ function degradedCodexRow(id, def) {
         agents: ["codex"],
         expectedVersion: def.expectedVersion,
         versionSource: "catalog",
+        observedScope: "user",
     };
 }
 function classifyCodexPlugin(id, def, enabled, fsVersion) {
@@ -399,10 +541,9 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             agents: ["codex"],
             expectedVersion,
             versionSource: "catalog",
+            observedScope: "user",
         };
     }
-    // Enabled in config but missing from fs — assumption #2 row contract:
-    // row present, status is NOT "installed".
     if (!fsVersion) {
         return {
             id,
@@ -411,10 +552,9 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             agents: ["codex"],
             expectedVersion,
             versionSource: "catalog",
+            observedScope: "user",
         };
     }
-    // Compare fs version to catalog expectation. If catalog gives no
-    // expectedVersion, trust it as installed.
     if (!expectedVersion || fsVersion === expectedVersion) {
         return {
             id,
@@ -424,6 +564,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             currentVersion: fsVersion,
             expectedVersion,
             versionSource: "catalog",
+            observedScope: "user",
         };
     }
     return {
@@ -434,6 +575,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
         currentVersion: fsVersion,
         expectedVersion,
         versionSource: "catalog",
+        observedScope: "user",
     };
 }
 /** Return the set of plugin ids whose `[plugins."<id>"]` table has
@@ -454,75 +596,173 @@ function parseCodexEnabledPluginIds(tomlContent) {
     }
     return ids;
 }
-function readHooksConfig(projectRoot) {
-    const configPath = path.join(projectRoot, ".claude", "hooks", "hooks.json");
-    let text;
-    try {
-        text = fs.readFileSync(configPath, "utf8");
-    }
-    catch {
-        return { config: null, corrupt: false };
-    }
-    try {
-        const parsed = JSON.parse(text);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return { config: parsed, corrupt: false };
+// ---------------------------------------------------------------------------
+// Hooks — read from <scope>/.claude/settings.json `hooks` segment, matched by
+// `_marker` sentinel against catalog hook names. Settings.json shape (Claude
+// Code convention):
+//
+//   {
+//     "hooks": {
+//       "<EventName>": [
+//         {
+//           "matcher": "<pattern>",
+//           "if": "<optional Claude-Code filter>",
+//           "hooks": [
+//             { "type": "command", "command": "...", "_marker": "<name>" }
+//           ]
+//         }
+//       ]
+//     }
+//   }
+//
+// ---------------------------------------------------------------------------
+function settingsPathForScope(scope, projectRoot, home) {
+    if (scope === "user")
+        return path.join(home, ".claude", "settings.json");
+    return path.join(projectRoot, ".claude", "settings.json");
+}
+/** Walk every settings hook action, returning a map keyed by the action's
+ *  `_marker` sentinel value. Malformed sub-shapes are skipped silently. */
+function indexSettingsHooksByMarker(settings) {
+    const out = new Map();
+    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+        return out;
+    const hooksSeg = settings.hooks;
+    if (!hooksSeg || typeof hooksSeg !== "object" || Array.isArray(hooksSeg))
+        return out;
+    for (const [event, blocks] of Object.entries(hooksSeg)) {
+        if (!Array.isArray(blocks))
+            continue;
+        for (const block of blocks) {
+            if (!block || typeof block !== "object" || Array.isArray(block))
+                continue;
+            const b = block;
+            const matcher = typeof b.matcher === "string" ? b.matcher : undefined;
+            const ifExpr = typeof b.if === "string" ? b.if : undefined;
+            const actions = b.hooks;
+            if (!Array.isArray(actions))
+                continue;
+            for (const action of actions) {
+                if (!action || typeof action !== "object" || Array.isArray(action))
+                    continue;
+                const a = action;
+                const marker = typeof a._marker === "string" ? a._marker : undefined;
+                if (!marker)
+                    continue;
+                out.set(marker, {
+                    event,
+                    matcher,
+                    ifExpr,
+                    command: typeof a.command === "string" ? a.command : undefined,
+                });
+            }
         }
-        return { config: null, corrupt: true };
-    }
-    catch {
-        return { config: null, corrupt: true };
     }
+    return out;
+}
+/** Compute a coarse sha256 signature over a settings hook entry's drift-
+ *  relevant fields (event, matcher, if). Used to fall back to a single-
+ *  field comparison when the catalog hasn't been upgraded to expose
+ *  structured expectedMatcher / expectedEvent / expectedIf. */
+function signatureForSettingsEntry(entry) {
+    const canonical = JSON.stringify({
+        event: entry.event,
+        matcher: entry.matcher ?? "",
+        if: entry.ifExpr ?? "",
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/** Returns true when the catalog's expectedHash is a wildcard sentinel
+ *  (empty string or the literal "any" placeholder). Wildcard means "no
+ *  drift expectation for this hook — trust marker presence." */
+function isWildcardExpectedHash(expectedHash) {
+    return expectedHash === "" || expectedHash === WILDCARD_EXPECTED_HASH;
+}
+function detectHookDrift(catalogEntry, settingsEntry) {
+    // Preferred drift path: structured expectations from catalog.
+    if (typeof catalogEntry.expectedMatcher === "string" &&
+        (settingsEntry.matcher ?? "") !== catalogEntry.expectedMatcher) {
+        return true;
+    }
+    if (typeof catalogEntry.expectedEvent === "string" &&
+        settingsEntry.event !== catalogEntry.expectedEvent) {
+        return true;
+    }
+    if (typeof catalogEntry.expectedIf === "string" &&
+        (settingsEntry.ifExpr ?? "") !== catalogEntry.expectedIf) {
+        return true;
+    }
+    // Fallback drift signal via expectedHash. When the catalog hasn't been
+    // populated with structured expected* fields (yet), expectedHash doubles
+    // as a coarse signature: if non-empty and non-wildcard, the implementation
+    // computes its own signature over the settings entry and treats any
+    // divergence as drift. Production scan-catalog.ts can populate this with
+    // a real settings-entry signature; until then, an explicit non-wildcard
+    // placeholder in tests (e.g. "expected-new-matcher-signature") deliberately
+    // triggers drift since it can never equal a sha256 hex digest.
+    if (!isWildcardExpectedHash(catalogEntry.expectedHash)) {
+        const sig = signatureForSettingsEntry(settingsEntry);
+        if (sig !== catalogEntry.expectedHash)
+            return true;
+    }
+    return false;
 }
-function hashHookIndex(projectRoot, name) {
-    const indexPath = path.join(projectRoot, ".claude", "hooks", name, "index.mjs");
+function scanHooks(scope, projectRoot, home, catalogHooks, warnings) {
+    const settingsPath = settingsPathForScope(scope, projectRoot, home);
+    let settingsRaw = null;
+    let settingsErr = null;
     try {
-        const buf = fs.readFileSync(indexPath);
-        return createHash("sha256").update(buf).digest("hex");
+        settingsRaw = fs.readFileSync(settingsPath, "utf8");
     }
-    catch {
-        return undefined;
+    catch (err) {
+        if (err && err.code === "ENOENT") {
+            settingsErr = "absent";
+        }
+        else {
+            settingsErr = "unreadable";
+        }
     }
-}
-function scanHooks(projectRoot, catalogHooks) {
-    const { config } = readHooksConfig(projectRoot);
-    const registeredNames = new Set();
-    if (config?.hooks && Array.isArray(config.hooks)) {
-        for (const entry of config.hooks) {
-            if (entry && typeof entry.name === "string")
-                registeredNames.add(entry.name);
+    let parsed = null;
+    if (settingsRaw !== null) {
+        try {
+            parsed = JSON.parse(settingsRaw);
+        }
+        catch {
+            settingsErr = "unreadable";
+            parsed = null;
         }
     }
+    if (settingsErr === "unreadable") {
+        warnings.push({
+            code: "settings-unreadable",
+            message: `Settings file unreadable or corrupt JSON: ${settingsPath}`,
+        });
+    }
+    const byMarker = indexSettingsHooksByMarker(parsed);
     const out = [];
     for (const [name, def] of Object.entries(catalogHooks)) {
-        if (!registeredNames.has(name)) {
+        const settingsEntry = byMarker.get(name);
+        if (!settingsEntry) {
             out.push({
                 name,
                 description: def.description,
                 status: "not-installed",
                 expectedHash: def.expectedHash,
+                observedScope: scope,
             });
             continue;
         }
-        const currentHash = hashHookIndex(projectRoot, name);
-        if (currentHash === undefined) {
-            // Registered but index.mjs missing — assumption #2: row present, not
-            // "installed", currentHash undefined so the UI can prompt repair.
-            out.push({
-                name,
-                description: def.description,
-                status: "not-installed",
-                expectedHash: def.expectedHash,
-            });
-            continue;
-        }
-        const status = currentHash === def.expectedHash ? "installed" : "update-available";
+        const drift = detectHookDrift(def, settingsEntry);
         out.push({
             name,
             description: def.description,
-            status,
-            currentHash,
+            status: drift ? "update-available" : "installed",
+            // Surface a coarse current signature so the UI can show diff details
+            // if it wants. The exact format is "sha256 of normalized settings
+            // entry" — opaque to the UI, used only for drift detection.
+            currentHash: signatureForSettingsEntry(settingsEntry),
             expectedHash: def.expectedHash,
+            observedScope: scope,
         });
     }
     return out;
@@ -531,20 +771,45 @@ function scanHooks(projectRoot, catalogHooks) {
 // Default external-I/O implementations (used when ScanOptions are not
 // injected — server.ts wires these up in production).
 // ---------------------------------------------------------------------------
-/** 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 async function defaultExecPluginList() {
+/** 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 async function defaultExecPluginList(scope = "user", projectRoot) {
     // Run both lookups in parallel via async exec so /api/state doesn't block
     // the event loop. `claude plugins list` can take several seconds on cold
     // marketplace fetches; sync exec would freeze heartbeats and other
-    // concurrent /api requests.
+    // concurrent /api requests. Note: `claude plugins list` does NOT support
+    // `--user` / `--project`; each record carries its own `scope` field which
+    // we filter on below.
     const [installedRes, availableRes] = await Promise.all([
-        execAsync("claude plugins list --json", { encoding: "utf8" }),
-        execAsync("claude plugins list --available --json", { encoding: "utf8" }),
+        execAsync(`claude plugins list --json`, { encoding: "utf8" }),
+        execAsync(`claude plugins list --available --json`, { encoding: "utf8" }),
     ]);
-    const installed = parseJsonArray(installedRes.stdout);
-    const available = parseJsonArray(availableRes.stdout);
+    const allInstalled = parseJsonArray(installedRes.stdout);
+    // `claude plugins list --available --json` returns a wrapped object
+    // `{ installed: [...], available: [...] }`, NOT a flat array. parseJsonArray
+    // alone would return `[]` and silently lose every marketplace ref → the
+    // scanner could never surface "update-available" from upstream-live data.
+    // Pull `.available` out of the wrapper; tolerate the flat-array form too
+    // in case Claude CLI's shape regresses.
+    const available = extractAvailableArray(availableRes.stdout);
+    const installed = allInstalled.filter((rec) => {
+        if (!rec || typeof rec !== "object")
+            return false;
+        if (rec.scope !== scope)
+            return false;
+        // Project-scope records may match multiple projects (`projectPath`
+        // differs). If projectRoot was provided, narrow to records bound to
+        // the current cwd. When omitted, fall back to "any project-scope
+        // record" — better than dropping all project records on a malformed
+        // call.
+        if (scope === "project" && projectRoot && typeof rec.projectPath === "string") {
+            return path.resolve(rec.projectPath) === path.resolve(projectRoot);
+        }
+        return true;
+    });
     return { installed, available };
 }
 function parseJsonArray(text) {
@@ -556,6 +821,24 @@ function parseJsonArray(text) {
         return [];
     }
 }
+/** Pull the available-plugins array out of `claude plugins list --available
+ *  --json`'s response. Empirically the CLI returns `{ installed, available }`;
+ *  if a future version regresses to a flat array we keep working. Returns
+ *  `[]` on malformed JSON. */
+function extractAvailableArray(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (parsed && typeof parsed === "object" && Array.isArray(parsed.available)) {
+            return parsed.available;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
 function codexHome() {
     return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }