auriga-cli 1.18.3 → 1.18.4

package/dist/api-types.d.ts

@@ -63,6 +63,12 @@ export interface PluginState {
      *  "user" (Codex has no project-scope plugin concept). See WorkflowState
      *  comment on why this is typed optional. */
     observedScope?: ScanScope;
+    /** True for plugins whose source lives in an upstream marketplace, not in
+     *  this repo (skill-creator / claude-md-management / codex). The scanner
+     *  short-circuits update-available reporting for these — upgrades go
+     *  through `claude plugins update`, not us. The UI renders an EXTERNAL
+     *  badge to make the "not our jurisdiction" signal explicit. */
+    external?: boolean;
 }
 export interface HookState {
     name: string;

package/dist/catalog.d.ts

@@ -9,9 +9,29 @@ export interface CatalogEntry {
      *  because `plugins/<name>/.claude-plugin/plugin.json` is NOT shipped in
      *  the npm tarball (see `package.json` `files` field). */
     expectedVersion?: string;
+    /** Build-time-baked agent map for plugin entries. Derived from
+     *  `.claude/plugins.json` ∪ `.agents/plugins/install.json` — those config
+     *  files are NOT shipped in the npm tarball, so the scanner can't read
+     *  them at runtime. Baking here lets `/api/state` correctly classify
+     *  dual-Agent plugins as `["claude","codex"]` for installed users.
+     *  Absent on skill / hook entries. */
+    agents?: ("claude" | "codex")[];
+    /** True for plugins whose source lives in an UPSTREAM marketplace
+     *  (skill-creator / claude-md-management / codex), not in this repo. The
+     *  scanner uses this to disable update-available reporting — those
+     *  plugins update through `claude plugins update`, not through us. UI
+     *  surfaces an EXTERNAL badge so users know where to look. */
+    external?: boolean;
 }
 export interface Catalog {
     generatedAt: string;
+    /** Workflow content version baked from `CLAUDE.md`'s `# auriga Workflow (vX.Y.Z)`
+     *  header at build time. MUST live here rather than be read at runtime
+     *  because `CLAUDE.md` is NOT in the npm tarball — `package.json` `files`
+     *  allowlists only `dist/`. Empty string when the header is unparseable;
+     *  the scanner then degrades to "trust whatever the user has" rather than
+     *  forcing phantom update-available against an empty expected value. */
+    workflowVersion: string;
     workflowSkills: CatalogEntry[];
     recommendedSkills: CatalogEntry[];
     plugins: CatalogEntry[];

package/dist/catalog.json

@@ -1,5 +1,6 @@
 {
-  "generatedAt": "2026-05-12T13:58:42.583Z",
+  "generatedAt": "2026-05-12T15:14:34.188Z",
+  "workflowVersion": "1.7.0",
   "workflowSkills": [
     {
       "name": "brainstorming",
@@ -75,34 +76,61 @@
   "plugins": [
     {
       "name": "skill-creator",
-      "description": "Create and manage custom skills"
+      "description": "Create and manage custom skills",
+      "agents": [
+        "claude"
+      ],
+      "external": true
     },
     {
       "name": "claude-md-management",
-      "description": "Audit and improve CLAUDE.md files"
+      "description": "Audit and improve CLAUDE.md files",
+      "agents": [
+        "claude"
+      ],
+      "external": true
     },
     {
       "name": "codex",
-      "description": "Cross-model collaboration with Codex"
+      "description": "Cross-model collaboration with Codex",
+      "agents": [
+        "claude"
+      ],
+      "external": true
     },
     {
       "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.",
+      "agents": [
+        "claude",
+        "codex"
+      ],
       "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).",
+      "agents": [
+        "claude",
+        "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.",
+      "agents": [
+        "claude",
+        "codex"
+      ],
       "expectedVersion": "0.3.1"
     },
     {
       "name": "session-instructions-loader",
       "description": "(Codex) Injects extra instruction files on session start",
+      "agents": [
+        "codex"
+      ],
       "expectedVersion": "1.0.0"
     }
   ],

package/dist/scan-catalog.js

@@ -1,37 +1,28 @@
-// Build the scan-time Catalog (the shape src/state.ts consumes) from
-// auriga-cli's installed package state. This bridges the build-time
-// `dist/catalog.json` (which carries names + descriptions for the menu)
-// and the runtime scanner's need for expected hashes + versions.
+// Build the scan-time Catalog (the shape src/state.ts consumes) from the
+// build-time `dist/catalog.json`. This module is intentionally a *thin
+// adapter* — it must NOT read any file outside `dist/catalog.json`, because
+// the npm tarball's `files` field allowlists only `dist/`. Reading from
+// `packageRoot/CLAUDE.md`, `packageRoot/.claude/plugins.json`, or
+// `packageRoot/.agents/skills/<name>/SKILL.md` succeeds in dev (where
+// packageRoot === repoRoot) but silently returns empty for npm-installed
+// users, leaving the scanner unable to surface real update signals.
 //
-// Inputs (all under packageRoot):
-//   dist/catalog.json     — names + descriptions for 5 categories
-//   skills-lock.json      — expected SHA256 for every vendored skill
-//   .claude/plugins.json  — Claude plugin entries (agent = "claude")
-//   .agents/plugins/install.json — Codex plugin entries (agent = "codex")
-//   .claude/hooks/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
+// Anything the scanner needs beyond what's already in catalog.json must
+// first be baked at build time in `src/build/generate-catalog.ts`.
 //
-// Anything missing is treated as "no expectation" (empty hash / version)
-// rather than throwing; scanState will still produce a structurally valid
-// StateReport — items just classify as not-installed or installed
-// depending on whether the user-side data exists.
-import { createHash } from "node:crypto";
+// Scope of the current bake (covered fields):
+//   - workflowVersion         — from CLAUDE.md header
+//   - plugin agents map       — from .claude/plugins.json ∪ .agents/plugins/install.json
+//   - plugin expectedVersion  — from plugins/<name>/.claude-plugin/plugin.json
+//   - plugin external flag    — derived (no in-tree manifest = external)
+//
+// Out of scope for v1.18.4 (follow-up PRs):
+//   - hook expectedEvent / expectedMatcher / expectedIf (from .claude/hooks/hooks.json)
+//   - apply-time installer config (the install path reads .claude/plugins.json
+//     directly — that needs runWebUi → fetchContentRoot rewire, not bake).
 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 {
         return await readFile(p, "utf8");
@@ -42,24 +33,21 @@ async function tryReadFile(p) {
 }
 export async function buildScanCatalog(packageRoot) {
     const dist = loadCatalog(packageRoot);
-    // Workflow version: parse from auriga-cli's own CLAUDE.md template.
-    // If missing, leave as empty string so workflow always classifies as
-    // not-installed (no expectation set).
-    const claudeMd = await tryReadFile(path.join(packageRoot, "CLAUDE.md"));
-    const m = claudeMd ? WORKFLOW_VERSION_RE.exec(claudeMd) : null;
-    const workflowVersion = m ? m[1] : "";
-    // Skills + recommended: 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");
+    // Workflow version — baked from CLAUDE.md header at build time. See
+    // module comment for the "no runtime reads outside dist/" rule.
+    const workflowVersion = dist.workflowVersion ?? "";
+    // Skills: drift detection deliberately deferred to `npx skills update
+    // --project`, which already compares against the skill's own upstream
+    // repo HEAD. Our catalog snapshot would only know "what auriga-cli
+    // shipped at this CLI release" — at best a stale proxy that mis-reports
+    // legitimate user-side updates as drift. Setting expectedHash to "" puts
+    // classifySkillByFile into wildcard mode: row reports installed if
+    // SKILL.md exists, not-installed otherwise; never update-available.
     const skills = {};
     for (const entry of dist.workflowSkills) {
         skills[entry.name] = {
             description: entry.description,
-            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
+            expectedHash: "",
             isWorkflow: true,
         };
     }
@@ -67,73 +55,37 @@ export async function buildScanCatalog(packageRoot) {
     for (const entry of dist.recommendedSkills) {
         recommendedSkills[entry.name] = {
             description: entry.description,
-            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
+            expectedHash: "",
         };
     }
-    // Plugins: split by agent based on which config file lists them. A
-    // plugin can appear in both registries (cross-agent plugins like
-    // auriga-go); we represent it once per agent.
+    // Plugins: agents + expectedVersion + external all come from
+    // dist/catalog.json now (baked in src/build/generate-catalog.ts). The
+    // previous version of this module read .claude/plugins.json +
+    // .agents/plugins/install.json at runtime — those files are NOT in the
+    // npm tarball, so for installed users every plugin defaulted to a
+    // ["claude"] agent classification (root cause of dual-Agent plugin
+    // mis-classification in v1.18.x).
     const plugins = {};
-    const claudePluginsText = await tryReadFile(path.join(packageRoot, ".claude", "plugins.json"));
-    const claudeNames = new Set();
-    if (claudePluginsText) {
-        try {
-            const parsed = JSON.parse(claudePluginsText);
-            for (const p of parsed.plugins ?? []) {
-                if (p.name)
-                    claudeNames.add(p.name);
-            }
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    const codexInstallText = await tryReadFile(path.join(packageRoot, ".agents", "plugins", "install.json"));
-    const codexNames = new Set();
-    if (codexInstallText) {
-        try {
-            const parsed = JSON.parse(codexInstallText);
-            for (const p of parsed.plugins ?? []) {
-                if (p.name)
-                    codexNames.add(p.name);
-            }
-        }
-        catch {
-            /* ignore */
-        }
-    }
     for (const entry of dist.plugins) {
-        // Collect every agent that registers this plugin. A plugin can ship in
-        // both registries (cross-agent plugins like auriga-go); we emit it as
-        // a single multi-agent record so the UI shows one row + BOTH badge and
-        // Apply installs to each side.
-        const agents = [];
-        if (claudeNames.has(entry.name))
-            agents.push("claude");
-        if (codexNames.has(entry.name))
-            agents.push("codex");
-        if (agents.length === 0)
-            agents.push("claude"); // unknown defaults to claude
-        // 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.
+        const agents = Array.isArray(entry.agents) && entry.agents.length > 0
+            ? [...entry.agents]
+            : ["claude"]; // safety fallback: unknown shape defaults to claude
         plugins[entry.name] = {
             description: entry.description,
             agents,
             ...(typeof entry.expectedVersion === "string" && entry.expectedVersion.length > 0
                 ? { expectedVersion: entry.expectedVersion }
                 : {}),
+            ...(entry.external === true ? { external: true } : {}),
         };
     }
-    // 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.
+    // Hooks: TODO follow-up — bake expectedEvent / expectedMatcher / expectedIf
+    // into dist/catalog.json the same way agents are baked. Currently the
+    // runtime read of packageRoot/.claude/hooks/hooks.json works in dev
+    // (packageRoot === repoRoot) but fails silently for npm-installed users
+    // — `package.json` `files` allowlist doesn't ship `.claude/`. So hook
+    // drift detection is correct in dev and degraded (always "installed" if
+    // marker present) in production. Follow-up bake closes the dev/prod gap.
     const hooksJsonPath = path.join(packageRoot, ".claude", "hooks", "hooks.json");
     const hooksJsonRaw = await tryReadFile(hooksJsonPath);
     const hooksJson = hooksJsonRaw ? JSON.parse(hooksJsonRaw) : {};

package/dist/state.d.ts

@@ -15,6 +15,12 @@ export interface Catalog {
         /** Agents this plugin can install into. Length 1 or 2. */
         agents: ("claude" | "codex")[];
         expectedVersion?: string;
+        /** When true, this plugin is published in an UPSTREAM marketplace
+         *  (skill-creator / claude-md-management / codex), not in this repo.
+         *  Classifier MUST NOT report `update-available` for external plugins —
+         *  those upgrade through `claude plugins update`, not us. The UI surfaces
+         *  an EXTERNAL badge so users know to defer to the upstream tool. */
+        external?: boolean;
     }>;
     hooks: Record<string, {
         description: string;

package/dist/state.js

@@ -373,9 +373,13 @@ function degradedClaudeRow(id, def, scope) {
         expectedVersion: def.expectedVersion,
         versionSource: "upstream-live",
         observedScope: scope,
+        ...(def.external === true ? { external: true } : {}),
     };
 }
 function classifyClaudePlugin(id, def, installed, available, scope) {
+    // `external` propagates onto every return below so the UI can surface the
+    // EXTERNAL badge regardless of install state.
+    const externalFlag = def.external === true ? { external: true } : {};
     if (!installed || typeof installed.version !== "string") {
         return {
             id,
@@ -385,9 +389,31 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
             expectedVersion: typeof available?.source?.ref === "string" ? available.source.ref : def.expectedVersion,
             versionSource: "upstream-live",
             observedScope: scope,
+            ...externalFlag,
         };
     }
     const installedVersion = installed.version;
+    // External plugin short-circuit: we don't own these, so we don't claim
+    // authority on "what version they should be at". `claude plugins update`
+    // is the right channel — the scanner just confirms presence. Status stays
+    // "installed" even if installed.version differs from any signal we have.
+    // The catalog deliberately omits `expectedVersion` for externals, but we
+    // double-down with this guard so a future regression that accidentally
+    // populates expectedVersion still can't flip externals to update-available.
+    if (def.external === true) {
+        return {
+            id,
+            description: def.description,
+            status: "installed",
+            agents: ["claude"],
+            currentVersion: installedVersion,
+            // Don't surface any "expected" on externals — the upstream tool owns
+            // the version conversation.
+            versionSource: "upstream-live",
+            observedScope: scope,
+            ...externalFlag,
+        };
+    }
     const ref = available?.source?.ref;
     const normalizedAvailable = parseRef(typeof ref === "string" ? ref : undefined);
     const normalizedInstalled = parseRef(installedVersion);
@@ -421,6 +447,7 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
             expectedVersion: expectedRaw,
             versionSource,
             observedScope: scope,
+            ...externalFlag,
         };
     }
     if (normalizedInstalled !== null && normalizedInstalled === expectedNormalized) {
@@ -433,6 +460,7 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
             expectedVersion: expectedRaw,
             versionSource,
             observedScope: scope,
+            ...externalFlag,
         };
     }
     return {
@@ -444,6 +472,7 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
         expectedVersion: expectedRaw,
         versionSource,
         observedScope: scope,
+        ...externalFlag,
     };
 }
 // ---------------------------------------------------------------------------
@@ -529,10 +558,12 @@ function degradedCodexRow(id, def) {
         expectedVersion: def.expectedVersion,
         versionSource: "catalog",
         observedScope: "user",
+        ...(def.external === true ? { external: true } : {}),
     };
 }
 function classifyCodexPlugin(id, def, enabled, fsVersion) {
     const expectedVersion = def.expectedVersion;
+    const externalFlag = def.external === true ? { external: true } : {};
     if (!enabled) {
         return {
             id,
@@ -542,6 +573,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             expectedVersion,
             versionSource: "catalog",
             observedScope: "user",
+            ...externalFlag,
         };
     }
     if (!fsVersion) {
@@ -553,6 +585,22 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             expectedVersion,
             versionSource: "catalog",
             observedScope: "user",
+            ...externalFlag,
+        };
+    }
+    // External plugin short-circuit, same rationale as classifyClaudePlugin:
+    // we defer authority to `codex plugin marketplace update` and never flag
+    // update-available for upstream-owned plugins.
+    if (def.external === true) {
+        return {
+            id,
+            description: def.description,
+            status: "installed",
+            agents: ["codex"],
+            currentVersion: fsVersion,
+            versionSource: "catalog",
+            observedScope: "user",
+            ...externalFlag,
         };
     }
     if (!expectedVersion || fsVersion === expectedVersion) {
@@ -565,6 +613,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             expectedVersion,
             versionSource: "catalog",
             observedScope: "user",
+            ...externalFlag,
         };
     }
     return {
@@ -576,6 +625,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
         expectedVersion,
         versionSource: "catalog",
         observedScope: "user",
+        ...externalFlag,
     };
 }
 /** Return the set of plugin ids whose `[plugins."<id>"]` table has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.18.3",
+  "version": "1.18.4",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins, Hooks)",
   "license": "MIT",
   "repository": {
@@ -25,8 +25,8 @@
     "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/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",
+    "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 dist-test/tests/tarball-shape.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 dist-test/tests/tarball-shape.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",