@orchid-labs/pluxx 0.1.7 → 0.1.8

package/dist/index.js

@@ -8670,6 +8670,110 @@ import { createHash } from "crypto";
 import { resolve as resolve2 } from "path";
 import { spawnSync } from "child_process";
 import { tmpdir } from "os";
+
+// src/user-config.ts
+var ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var PLACEHOLDER_SECRET_PATTERNS = [
+  /\bdummy\b/i,
+  /\bplaceholder\b/i,
+  /\bexample\b/i,
+  /\bchangeme\b/i,
+  /\breplace[_ -]?me\b/i,
+  /\byour[_ -]?(api[_ -]?)?key\b/i,
+  /\bapi[_ -]?key[_ -]?here\b/i,
+  /\btoken[_ -]?here\b/i
+];
+function normalizeUserConfigKey(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/[._/\s]+/g, "-").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+}
+function humanizeUserConfigLabel(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/[._/]+/g, " ").replace(/-/g, " ").split(/\s+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join(" ");
+}
+function defaultUserConfigEnvVar(key) {
+  return key.replace(/[^A-Za-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
+}
+function extractEnvReference(value) {
+  if (!value) return void 0;
+  const match = value.match(/^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/);
+  return match?.[1];
+}
+function isPlaceholderSecretValue(value) {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim();
+  if (normalized === "") return false;
+  return PLACEHOLDER_SECRET_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+function isRuntimePlatformManaged(config, target, server) {
+  if (server.transport === "stdio") return false;
+  if (server.auth?.type === "platform") {
+    return true;
+  }
+  if (target === "claude-code") {
+    return config.platforms?.["claude-code"]?.mcpAuth === "platform";
+  }
+  if (target === "cursor") {
+    return config.platforms?.cursor?.mcpAuth === "platform";
+  }
+  return false;
+}
+function dedupeUserConfigEntries(entries) {
+  const deduped = [];
+  const seenKeys = /* @__PURE__ */ new Set();
+  const seenEnvVars = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const envVar = entry.envVar?.trim();
+    if (seenKeys.has(entry.key)) continue;
+    if (envVar && seenEnvVars.has(envVar)) continue;
+    deduped.push(entry);
+    seenKeys.add(entry.key);
+    if (envVar) seenEnvVars.add(envVar);
+  }
+  return deduped;
+}
+function collectUserConfigEntries(config, platforms = config.targets) {
+  const explicitEntries = (config.userConfig ?? []).filter((entry) => !entry.targets || entry.targets.some((target) => platforms.includes(target))).map((entry) => ({ ...entry, source: "explicit" }));
+  const derivedEntries = [];
+  for (const [serverName, server] of Object.entries(config.mcp ?? {})) {
+    const applicableTargets = platforms.filter((target) => !isRuntimePlatformManaged(config, target, server));
+    if (server.auth?.type && server.auth.type !== "none" && server.auth.type !== "platform" && ENV_VAR_NAME.test(server.auth.envVar) && applicableTargets.length > 0) {
+      derivedEntries.push({
+        key: normalizeUserConfigKey(server.auth.envVar),
+        title: humanizeUserConfigLabel(server.auth.envVar),
+        description: `Authentication credential for the ${serverName} MCP server.`,
+        type: "secret",
+        required: true,
+        envVar: server.auth.envVar,
+        targets: applicableTargets,
+        source: "mcp-auth"
+      });
+    }
+    if (server.transport === "stdio") {
+      for (const [key, rawValue] of Object.entries(server.env ?? {})) {
+        const envVar = extractEnvReference(rawValue) ?? (ENV_VAR_NAME.test(key) ? key : void 0);
+        if (!envVar || !ENV_VAR_NAME.test(envVar)) continue;
+        if (extractEnvReference(rawValue) === void 0 && rawValue !== "") {
+          continue;
+        }
+        derivedEntries.push({
+          key: normalizeUserConfigKey(envVar),
+          title: humanizeUserConfigLabel(envVar),
+          description: `Environment value required to launch the ${serverName} stdio MCP server.`,
+          type: "secret",
+          required: true,
+          envVar,
+          targets: applicableTargets.length > 0 ? applicableTargets : platforms,
+          source: "mcp-env"
+        });
+      }
+    }
+  }
+  return dedupeUserConfigEntries([
+    ...explicitEntries,
+    ...derivedEntries
+  ]);
+}
+
+// src/cli/publish.ts
 var INSTALLER_TARGETS = ["claude-code", "cursor", "codex", "opencode"];
 function runCommandDefault(command, args, options) {
   const result = spawnSync(command, args, {
@@ -8968,6 +9072,175 @@ echo
 echo "Installed __DISPLAY_NAME__ across ${installerTargets.join(", ")}."
 `.replaceAll("__REPO__", "REPO_PLACEHOLDER").replaceAll("__DISPLAY_NAME__", "DISPLAY_PLACEHOLDER");
 }
+function renderInstallerUserConfigSnippet(config, platform, installDirVariable) {
+  const entries = collectUserConfigEntries(config, [platform]).map((entry) => ({
+    key: entry.key,
+    title: entry.title,
+    type: entry.type ?? "string",
+    required: entry.required !== false,
+    envVar: entry.envVar ?? defaultUserConfigEnvVar(entry.key)
+  }));
+  if (entries.length === 0) return "";
+  const promptLines = entries.map((entry) => {
+    const functionName = entry.type === "secret" ? "pluxx_prompt_secret_config" : "pluxx_prompt_text_config";
+    return `${functionName} ${JSON.stringify(entry.envVar)} ${JSON.stringify(entry.title)} ${entry.required ? "1" : "0"}`;
+  });
+  return `
+PLUXX_USER_CONFIG_SPEC="$(cat <<'PLUXX_USER_CONFIG_JSON'
+${JSON.stringify(entries)}
+PLUXX_USER_CONFIG_JSON
+)"
+
+pluxx_is_placeholder_secret() {
+  case "$1" in
+    *dummy*|*Dummy*|*DUMMY*|*placeholder*|*Placeholder*|*PLACEHOLDER*|*changeme*|*CHANGE_ME*|*replace*me*|*Replace*Me*|*your*key*|*YOUR*KEY*|*api*key*here*|*API*KEY*HERE*|*token*here*|*TOKEN*HERE*)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+pluxx_prompt_secret_config() {
+  local env_var="$1"
+  local label="$2"
+  local required="$3"
+  local current_value="\${!env_var:-}"
+
+  if [[ -z "$current_value" && "$required" == "1" ]]; then
+    if [[ -t 0 || -r /dev/tty ]]; then
+      read -r -s -p "$label [$env_var]: " current_value </dev/tty
+      echo >/dev/tty
+    else
+      echo "Missing required config: export $env_var before running this installer." >&2
+      exit 1
+    fi
+  fi
+
+  if [[ -n "$current_value" ]] && pluxx_is_placeholder_secret "$current_value"; then
+    echo "Refusing placeholder-looking secret for $env_var. Set a real value and rerun the installer." >&2
+    exit 1
+  fi
+
+  export "$env_var=$current_value"
+}
+
+pluxx_prompt_text_config() {
+  local env_var="$1"
+  local label="$2"
+  local required="$3"
+  local current_value="\${!env_var:-}"
+
+  if [[ -z "$current_value" && "$required" == "1" ]]; then
+    if [[ -t 0 || -r /dev/tty ]]; then
+      read -r -p "$label [$env_var]: " current_value </dev/tty
+    else
+      echo "Missing required config: export $env_var before running this installer." >&2
+      exit 1
+    fi
+  fi
+
+  export "$env_var=$current_value"
+}
+
+${promptLines.join("\n")}
+
+export PLUXX_USER_CONFIG_SPEC
+export PLUXX_INSTALL_DIR="${installDirVariable}"
+
+node <<'NODE'
+const fs = require('fs')
+const path = require('path')
+
+const installDir = process.env.PLUXX_INSTALL_DIR
+const spec = JSON.parse(process.env.PLUXX_USER_CONFIG_SPEC || '[]')
+
+if (installDir && spec.length > 0) {
+  const env = {}
+  const values = {}
+
+  for (const entry of spec) {
+    const value = process.env[entry.envVar]
+    if (value === undefined || value === '') continue
+    values[entry.key] = value
+    env[entry.envVar] = value
+  }
+
+  fs.writeFileSync(
+    path.join(installDir, '.pluxx-user.json'),
+    JSON.stringify({ values, env }, null, 2) + '\\n',
+  )
+
+  const envScriptPath = path.join(installDir, 'scripts/check-env.sh')
+  if (fs.existsSync(envScriptPath)) {
+    fs.writeFileSync(
+      envScriptPath,
+      '#!/usr/bin/env bash\\nset -euo pipefail\\n# pluxx install materialized required config for this local plugin install.\\nexit 0\\n',
+    )
+  }
+
+  const materialize = (value) =>
+    typeof value === 'string'
+      ? value.replace(/\\$\\{([A-Za-z_][A-Za-z0-9_]*)\\}/g, (_match, name) => env[name] || '${" + name + "}')
+      : value
+
+  const materializeRecord = (record) => {
+    if (!record || typeof record !== 'object') return record
+    const next = {}
+    for (const [key, value] of Object.entries(record)) {
+      next[key] = materialize(value)
+    }
+    return next
+  }
+
+  for (const relativePath of ['.mcp.json', 'mcp.json']) {
+    const filepath = path.join(installDir, relativePath)
+    if (!fs.existsSync(filepath)) continue
+
+    const payload = JSON.parse(fs.readFileSync(filepath, 'utf8'))
+    for (const server of Object.values(payload.mcpServers || {})) {
+      if (!server || typeof server !== 'object') continue
+
+      if (server.env) {
+        server.env = materializeRecord(server.env)
+      }
+
+      if (server.bearer_token_env_var && env[server.bearer_token_env_var]) {
+        server.http_headers = {
+          ...(server.http_headers || {}),
+          Authorization: 'Bearer ' + env[server.bearer_token_env_var],
+        }
+        delete server.bearer_token_env_var
+      }
+
+      if (server.env_http_headers && typeof server.env_http_headers === 'object') {
+        server.http_headers = {
+          ...(server.http_headers || {}),
+        }
+        for (const [headerName, envVar] of Object.entries(server.env_http_headers)) {
+          if (env[envVar]) server.http_headers[headerName] = env[envVar]
+        }
+        delete server.env_http_headers
+      }
+
+      if (server.headers) {
+        server.headers = materializeRecord(server.headers)
+      }
+      if (server.http_headers) {
+        server.http_headers = materializeRecord(server.http_headers)
+      }
+    }
+
+    fs.writeFileSync(filepath, JSON.stringify(payload, null, 2) + '\\n')
+  }
+}
+NODE
+`;
+}
+function hasInstallerUserConfig(config, platform) {
+  return collectUserConfigEntries(config, [platform]).length > 0;
+}
 function renderInstallClaudeCodeScript(config) {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -8994,6 +9267,7 @@ need_cmd tar
 need_cmd mktemp
 need_cmd grep
 need_cmd sed
+${hasInstallerUserConfig(config, "claude-code") ? "need_cmd node" : ""}
 
 if [[ "$SKIP_INSTALL" != "1" ]]; then
   need_cmd curl
@@ -9030,6 +9304,7 @@ DESCRIPTION="$(grep -E '"description"' "$PLUGIN_MANIFEST" | head -n1 | sed -E 's
 mkdir -p "$INSTALL_ROOT/.claude-plugin" "$INSTALL_ROOT/plugins"
 rm -rf "$INSTALL_ROOT/plugins/$PLUGIN_NAME"
 cp -R "$BUNDLE_DIR" "$INSTALL_ROOT/plugins/$PLUGIN_NAME"
+${renderInstallerUserConfigSnippet(config, "claude-code", "$INSTALL_ROOT/plugins/$PLUGIN_NAME")}
 
 cat > "$INSTALL_ROOT/.claude-plugin/marketplace.json" <<JSON
 {
@@ -9093,6 +9368,7 @@ need_cmd() {
 need_cmd tar
 need_cmd mktemp
 need_cmd curl
+${hasInstallerUserConfig(config, "cursor") ? "need_cmd node" : ""}
 
 TMP_DIR="$(mktemp -d)"
 cleanup() {
@@ -9121,6 +9397,7 @@ fi
 mkdir -p "$(dirname "$INSTALL_DIR")"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
+${renderInstallerUserConfigSnippet(config, "cursor", "$INSTALL_DIR")}
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
 echo "If Cursor is already open, use Developer: Reload Window or restart Cursor so the plugin is picked up."
@@ -9178,6 +9455,7 @@ fi
 mkdir -p "$(dirname "$INSTALL_DIR")"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
+${renderInstallerUserConfigSnippet(config, "codex", "$INSTALL_DIR")}
 
 mkdir -p "$(dirname "$MARKETPLACE_PATH")"
 
@@ -9292,6 +9570,7 @@ fi
 mkdir -p "$(dirname "$INSTALL_DIR")" "$SKILLS_ROOT"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
+${renderInstallerUserConfigSnippet(config, "opencode", "$INSTALL_DIR")}
 
 export ENTRY_PATH
 export PLUGIN_NAME
@@ -9573,7 +9852,7 @@ function runPublish(config, options = {}) {
 }
 
 // src/cli/verify-install.ts
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync5, lstatSync as lstatSync2, readdirSync as readdirSync3, readFileSync as readFileSync5, readlinkSync, realpathSync, statSync } from "fs";
 import { resolve as resolve5 } from "path";
 
 // src/cli/doctor.ts
@@ -9656,16 +9935,144 @@ function getInstallTargets(pluginName) {
 function getClaudeMarketplaceName(pluginName) {
   return `pluxx-local-${pluginName}`;
 }
-function getClaudeMarketplaceRoot(pluginName) {
-  const home = process.env.HOME ?? "~";
-  return resolve3(home, ".claude/plugins/data", getClaudeMarketplaceName(pluginName));
-}
 function resolveInstalledConsumerPath(target, pluginName) {
-  if (target.platform === "claude-code") {
-    return resolve3(getClaudeMarketplaceRoot(pluginName), "plugins", pluginName);
+  if (target.platform === "claude-code" && pluginName !== "") {
+    return target.pluginDir;
   }
   return target.pluginDir;
 }
+function manifestPathForPlatform(platform) {
+  switch (platform) {
+    case "claude-code":
+      return ".claude-plugin/plugin.json";
+    case "cursor":
+      return ".cursor-plugin/plugin.json";
+    case "codex":
+      return ".codex-plugin/plugin.json";
+    case "opencode":
+      return "package.json";
+    default:
+      return void 0;
+  }
+}
+function isRelativeBundlePath(value) {
+  return value.startsWith("./") || value.startsWith("../") || value.startsWith(".\\") || value.startsWith("..\\");
+}
+function resolveBundleReference(rootDir, value) {
+  if (isRelativeBundlePath(value)) {
+    return resolve3(rootDir, value);
+  }
+  const pluginRootMatch = value.match(/^\$\{(?:CLAUDE_PLUGIN_ROOT|CURSOR_PLUGIN_ROOT|PLUGIN_ROOT)\}[\\/](.+)$/);
+  if (pluginRootMatch) {
+    return resolve3(rootDir, pluginRootMatch[1]);
+  }
+  return void 0;
+}
+function readBundleManifestReferences(manifest) {
+  const references = [];
+  for (const key of ["commands", "skills", "hooks", "mcpServers"]) {
+    const value = manifest[key];
+    if (typeof value === "string") {
+      references.push(value);
+    }
+  }
+  const agents = manifest.agents;
+  if (typeof agents === "string") {
+    references.push(agents);
+  } else if (Array.isArray(agents)) {
+    for (const entry of agents) {
+      if (typeof entry === "string") {
+        references.push(entry);
+      }
+    }
+  }
+  return references;
+}
+function collectHookCommandStrings(value, commands) {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectHookCommandStrings(entry, commands);
+    }
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "command" && typeof child === "string") {
+      commands.push(child);
+      continue;
+    }
+    collectHookCommandStrings(child, commands);
+  }
+}
+function extractBundleCommandTargets(command) {
+  const matches = command.match(/\$\{(?:CLAUDE_PLUGIN_ROOT|CURSOR_PLUGIN_ROOT|PLUGIN_ROOT)\}[\\/][^\s"'`;$|&<>]+|\.\.?[\\/][^\s"'`;$|&<>]+/g);
+  return matches ?? [];
+}
+function findInstalledBundleIntegrityIssues(rootDir, platform) {
+  const manifestPath = manifestPathForPlatform(platform);
+  if (!manifestPath) {
+    return {
+      missingManifestPaths: [],
+      missingHookTargets: []
+    };
+  }
+  const manifestFile = resolve3(rootDir, manifestPath);
+  if (!existsSync3(manifestFile)) {
+    return {
+      manifestIssue: `missing plugin manifest at ${manifestPath}`,
+      missingManifestPaths: [],
+      missingHookTargets: []
+    };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync3(manifestFile, "utf-8"));
+  } catch (error) {
+    return {
+      manifestIssue: `plugin manifest at ${manifestPath} is not parseable: ${error instanceof Error ? error.message : String(error)}`,
+      missingManifestPaths: [],
+      missingHookTargets: []
+    };
+  }
+  const missingManifestPaths = readBundleManifestReferences(manifest).filter((value) => {
+    const resolved = resolveBundleReference(rootDir, value);
+    return resolved !== void 0 && !existsSync3(resolved);
+  }).sort();
+  const hooksReference = typeof manifest.hooks === "string" ? manifest.hooks : void 0;
+  if (!hooksReference) {
+    return {
+      missingManifestPaths,
+      missingHookTargets: []
+    };
+  }
+  const hooksPath = resolveBundleReference(rootDir, hooksReference);
+  if (!hooksPath || !existsSync3(hooksPath)) {
+    return {
+      missingManifestPaths,
+      missingHookTargets: []
+    };
+  }
+  try {
+    const hooks = JSON.parse(readFileSync3(hooksPath, "utf-8"));
+    const commands = [];
+    collectHookCommandStrings(hooks, commands);
+    const missingHookTargets = [...new Set(
+      commands.flatMap(extractBundleCommandTargets).filter((value) => {
+        const resolved = resolveBundleReference(rootDir, value);
+        return resolved !== void 0 && !existsSync3(resolved);
+      })
+    )].sort();
+    return {
+      missingManifestPaths,
+      missingHookTargets
+    };
+  } catch {
+    return {
+      missingManifestPaths,
+      missingHookTargets: []
+    };
+  }
+}
 function planInstallPlugin(distDir, pluginName, platforms) {
   const targets = getInstallTargets(pluginName);
   const filtered = platforms ? targets.filter((t) => platforms.includes(t.platform)) : targets;
@@ -9753,6 +10160,42 @@ var WORKFLOW_SKILL_DEFINITIONS = [
     title: "General Research",
     description: "Handle broad search and query workflows when there is not a more specific product surface match.",
     match: ["search", "query", "lookup", "look up", "discover", "find"]
+  },
+  {
+    key: "web-research",
+    title: "Web Research",
+    description: "Search the web, fetch pages, and synthesize public source-backed research.",
+    match: ["web", "website", "url", "page", "fetch", "crawl", "scrape", "search", "result", "source"]
+  },
+  {
+    key: "source-review",
+    title: "Source Review",
+    description: "Audit sources, citations, evidence quality, and duplicate or weak research results.",
+    match: ["source", "citation", "evidence", "audit", "review", "quality", "rank", "dedupe", "duplicate"]
+  },
+  {
+    key: "content-extraction",
+    title: "Content Extraction",
+    description: "Extract structured content, entities, and summaries from pages, documents, or search results.",
+    match: ["extract", "parse", "content", "summary", "summarize", "document", "html", "markdown"]
+  },
+  {
+    key: "knowledge-search",
+    title: "Knowledge Search",
+    description: "Search docs, knowledge bases, papers, repositories, and internal reference material.",
+    match: ["docs", "documentation", "knowledge", "paper", "papers", "repo", "repository", "api", "reference"]
+  },
+  {
+    key: "news-monitoring",
+    title: "News Monitoring",
+    description: "Find recent news, launches, announcements, and time-bounded developments.",
+    match: ["news", "recent", "latest", "launch", "announcement", "announced", "date", "published"]
+  },
+  {
+    key: "code-research",
+    title: "Code Research",
+    description: "Find implementation docs, code examples, API usage, migration notes, and troubleshooting context.",
+    match: ["code", "sdk", "api", "github", "example", "migration", "error", "troubleshoot", "implementation"]
   }
 ];
 var WORKFLOW_SKILL_DEFINITION_BY_KEY = new Map(
@@ -9945,6 +10388,10 @@ function checkInstalledUserConfig(checks, rootDir) {
     const payload = JSON.parse(readFileSync4(resolvedPath, "utf-8"));
     const valueCount = Object.keys(payload.values ?? {}).length;
     const envCount = Object.keys(payload.env ?? {}).length;
+    const placeholderKeys = [
+      ...Object.entries(payload.values ?? {}).filter(([, value]) => isPlaceholderSecretValue(value)).map(([key]) => key),
+      ...Object.entries(payload.env ?? {}).filter(([, value]) => isPlaceholderSecretValue(value)).map(([key]) => key)
+    ];
     addCheck(checks, {
       level: "success",
       code: "consumer-user-config-valid",
@@ -9953,6 +10400,16 @@ function checkInstalledUserConfig(checks, rootDir) {
       fix: "No action needed.",
       path: userConfigPath
     });
+    if (placeholderKeys.length > 0) {
+      addCheck(checks, {
+        level: "warning",
+        code: "consumer-user-config-placeholder-secret",
+        title: "Local install config contains placeholder-looking secret values",
+        detail: `.pluxx-user.json contains placeholder-looking value${placeholderKeys.length === 1 ? "" : "s"} for ${placeholderKeys.join(", ")}.`,
+        fix: "Reinstall the plugin with real secret values, or edit .pluxx-user.json and refresh/restart the host.",
+        path: userConfigPath
+      });
+    }
   } catch (error) {
     addCheck(checks, {
       level: "error",
@@ -10037,6 +10494,16 @@ function checkInstalledMcpConfig(checks, rootDir, layout) {
     if (servers.length === 0) {
       return;
     }
+    if (layout.platform === "codex") {
+      addCheck(checks, {
+        level: "info",
+        code: "consumer-codex-mcp-bundled-visibility",
+        title: "Codex plugin-bundled MCP visibility clarified",
+        detail: `This Codex plugin bundle includes ${servers.length} MCP server${servers.length === 1 ? "" : "s"} through ${layout.mcpConfigPath}. Codex may show this on the plugin detail page without listing it on the global MCP servers settings page.`,
+        fix: "Use the plugin detail page, tool availability in chat, and `pluxx verify-install --target codex` as the source of truth for plugin-bundled MCP wiring. If the MCP remains unavailable after install, use Plugins > Refresh if present or restart Codex.",
+        path: layout.mcpConfigPath
+      });
+    }
     const remoteEntries = servers.filter((server) => "url" in server);
     const stdioEntries = servers.filter((server) => "command" in server);
     const inlineHeaderEntries = servers.filter((server) => {
@@ -10098,6 +10565,38 @@ function checkInstalledMcpConfig(checks, rootDir, layout) {
     });
   }
 }
+function checkInstalledBundleIntegrity(checks, rootDir, layout) {
+  const issues = findInstalledBundleIntegrityIssues(rootDir, layout.platform);
+  const details = [];
+  if (issues.manifestIssue) {
+    details.push(issues.manifestIssue);
+  }
+  if (issues.missingManifestPaths.length > 0) {
+    details.push(`manifest references missing path${issues.missingManifestPaths.length === 1 ? "" : "s"}: ${issues.missingManifestPaths.join(", ")}`);
+  }
+  if (issues.missingHookTargets.length > 0) {
+    details.push(`hook commands reference missing bundle target${issues.missingHookTargets.length === 1 ? "" : "s"}: ${issues.missingHookTargets.join(", ")}`);
+  }
+  if (details.length === 0) {
+    addCheck(checks, {
+      level: "success",
+      code: "consumer-bundle-integrity-valid",
+      title: "Installed bundle references resolve inside the plugin",
+      detail: "Every manifest-declared path and bundle-relative hook target exists in this installed bundle.",
+      fix: "No action needed.",
+      path: layout.manifestPath
+    });
+    return;
+  }
+  addCheck(checks, {
+    level: "error",
+    code: "consumer-bundle-integrity-invalid",
+    title: "Installed bundle is missing referenced files",
+    detail: details.join("; "),
+    fix: "Reinstall the plugin or rebuild the bundle so every manifest path and hook target exists in the installed plugin.",
+    path: layout.manifestPath
+  });
+}
 function findMissingInstalledStdioRuntimePaths(rootDir, stdioEntries) {
   const missing = /* @__PURE__ */ new Set();
   for (const server of stdioEntries) {
@@ -10283,6 +10782,7 @@ async function doctorConsumer(rootDir = process.cwd()) {
     path: layout.manifestPath
   });
   checkConsumerManifest(checks, rootDir, layout);
+  checkInstalledBundleIntegrity(checks, rootDir, layout);
   checkInstalledUserConfig(checks, rootDir);
   checkInstalledEnvValidation(checks, rootDir);
   checkInstalledMcpConfig(checks, rootDir, layout);
@@ -10296,18 +10796,103 @@ async function doctorConsumer(rootDir = process.cwd()) {
 // src/cli/verify-install.ts
 function buildCheckFromReport(target, pluginName, report) {
   const consumerPath = resolveInstalledConsumerPath(target, pluginName);
+  const staleReason = target.built && existsSync5(consumerPath) ? detectStaleInstall(target, pluginName, consumerPath) : void 0;
+  const stale = staleReason !== void 0;
   return {
     platform: target.platform,
     installPath: target.pluginDir,
     consumerPath,
     built: target.built,
     installed: existsSync5(consumerPath),
-    ok: report.errors === 0,
-    errors: report.errors,
+    stale,
+    ...staleReason ? { staleReason } : {},
+    ok: report.errors === 0 && !stale,
+    errors: report.errors + (stale ? 1 : 0),
     warnings: report.warnings,
     infos: report.infos
   };
 }
+function manifestPathForPlatform2(platform) {
+  switch (platform) {
+    case "claude-code":
+      return ".claude-plugin/plugin.json";
+    case "cursor":
+      return ".cursor-plugin/plugin.json";
+    case "codex":
+      return ".codex-plugin/plugin.json";
+    case "opencode":
+      return "package.json";
+    default:
+      return void 0;
+  }
+}
+function readInstalledManifestVersion(rootDir, platform) {
+  const manifestPath = manifestPathForPlatform2(platform);
+  if (!manifestPath) return void 0;
+  const filepath = resolve5(rootDir, manifestPath);
+  if (!existsSync5(filepath)) return void 0;
+  try {
+    const manifest = JSON.parse(readFileSync5(filepath, "utf-8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function findCodexCacheCandidates(pluginName) {
+  const home = process.env.HOME ?? "~";
+  const cacheRoot = resolve5(home, ".codex/plugins/cache");
+  if (!existsSync5(cacheRoot)) return [];
+  const candidates = [];
+  for (const marketplace of readdirSync3(cacheRoot)) {
+    const pluginRoot = resolve5(cacheRoot, marketplace, pluginName);
+    if (!existsSync5(pluginRoot)) continue;
+    for (const versionDir of readdirSync3(pluginRoot)) {
+      const candidatePath = resolve5(pluginRoot, versionDir);
+      try {
+        const stats = statSync(candidatePath);
+        if (!stats.isDirectory()) continue;
+        candidates.push({
+          path: candidatePath,
+          version: readInstalledManifestVersion(candidatePath, "codex") ?? versionDir,
+          mtimeMs: stats.mtimeMs
+        });
+      } catch {
+      }
+    }
+  }
+  return candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+function detectCodexCacheStaleness(pluginName, builtVersion) {
+  if (!builtVersion) return void 0;
+  const candidates = findCodexCacheCandidates(pluginName);
+  if (candidates.length === 0) return void 0;
+  if (candidates.some((candidate) => candidate.version === builtVersion)) return void 0;
+  const newest = candidates[0];
+  return `Codex active cache appears stale at ${newest.path}; cached version ${newest.version ?? "unknown"} does not match built version ${builtVersion}. Use Plugins > Refresh if available, or restart/reinstall Codex to load the current plugin bundle.`;
+}
+function detectStaleInstall(target, pluginName, consumerPath) {
+  try {
+    const details = lstatSync2(consumerPath);
+    if (details.isSymbolicLink()) {
+      const installedRealPath = realpathSync(consumerPath);
+      const builtRealPath = realpathSync(target.sourceDir);
+      if (installedRealPath !== builtRealPath) {
+        return `installed symlink points to ${readlinkSync(consumerPath)}, not the current build at ${target.sourceDir}`;
+      }
+    }
+  } catch {
+    return void 0;
+  }
+  const builtVersion = readInstalledManifestVersion(target.sourceDir, target.platform);
+  const installedVersion = readInstalledManifestVersion(consumerPath, target.platform);
+  if (builtVersion && installedVersion && builtVersion !== installedVersion) {
+    return `installed version ${installedVersion} does not match built version ${builtVersion}`;
+  }
+  if (target.platform === "codex") {
+    return detectCodexCacheStaleness(pluginName, builtVersion);
+  }
+  return void 0;
+}
 async function verifyInstall(config, options = {}) {
   const rootDir = options.rootDir ?? process.cwd();
   const distDir = resolve5(rootDir, config.outDir);
@@ -10335,9 +10920,36 @@ function printVerifyInstallResult(result) {
     console.log(`${prefix} ${check.platform}: ${check.consumerPath}`);
     console.log(`  install path: ${check.installPath}`);
     console.log(`  built: ${check.built ? "yes" : "no"}; installed: ${check.installed ? "yes" : "no"}; errors: ${check.errors}; warnings: ${check.warnings}; infos: ${check.infos}`);
+    if (check.stale) {
+      console.log(`  stale install: ${check.staleReason}`);
+    }
+    if (!check.ok) {
+      for (const action of getVerifyInstallRecoveryActions(check)) {
+        console.log(`  fix: ${action}`);
+      }
+    }
   }
   console.log(result.ok ? "pluxx verify-install passed." : "pluxx verify-install failed.");
 }
+function getVerifyInstallRecoveryActions(check) {
+  const actions = [];
+  if (!check.built) {
+    actions.push(`run pluxx build --target ${check.platform}`);
+  }
+  if (check.built && !check.installed) {
+    actions.push(`run pluxx install --target ${check.platform}${check.platform === "claude-code" ? " and accept/trust any hook prompt if expected" : ""}`);
+  }
+  if (check.stale) {
+    actions.push(`rerun pluxx install --target ${check.platform} to replace the stale local install`);
+    if (check.platform === "codex") {
+      actions.push("in Codex, use Plugins > Refresh if available, or restart Codex so the plugin cache reloads");
+    }
+  }
+  if (check.errors > 0 && actions.length === 0) {
+    actions.push(`run pluxx doctor --consumer "${check.consumerPath}" for the detailed host-specific failure`);
+  }
+  return actions;
+}
 export {
   CORE_FOUR_PRIMITIVE_CAPABILITIES,
   PLATFORM_LIMITS,