feat(doctor): expose plugin registry findings

giodl73-repo · giodl73-repo · commit 9c0d0fbdd2bb · 2026-06-27T08:37:30.000-07:00
diff --git a/src/commands/doctor-plugin-registry.test.ts b/src/commands/doctor-plugin-registry.test.ts
@@ -7,12 +7,18 @@ import type { PluginCandidate } from "../plugins/discovery.js";
 import { resolvePluginNpmProjectDir } from "../plugins/install-paths.js";
 import {
   readPersistedInstalledPluginIndex,
+  resolveInstalledPluginIndexStorePath,
   writePersistedInstalledPluginIndex,
 } from "../plugins/installed-plugin-index-store.js";
 import type { InstalledPluginIndex } from "../plugins/installed-plugin-index.js";
 import { markRetainedManagedNpmInstall } from "../plugins/managed-npm-retention.js";
 import { cleanupTrackedTempDirs, makeTrackedTempDir } from "../plugins/test-helpers/fs-fixtures.js";
-import { maybeRepairPluginRegistryState } from "./doctor-plugin-registry.js";
+import {
+  detectPluginRegistryHealthIssues,
+  maybeRepairPluginRegistryState,
+  pluginRegistryIssueToHealthFinding,
+  pluginRegistryIssueToRepairEffect,
+} from "./doctor-plugin-registry.js";
 import { DISABLE_PLUGIN_REGISTRY_MIGRATION_ENV } from "./doctor/shared/plugin-registry-migration.js";
 
 vi.mock("../../packages/terminal-core/src/note.js", () => ({
@@ -291,6 +297,151 @@ function expectedPluginIndexRecord(params: {
 }
 
 describe("maybeRepairPluginRegistryState", () => {
+  it("maps missing plugin registry state to a structured finding and dry-run effect", async () => {
+    const stateDir = makeTempDir();
+    const registryPath = resolveInstalledPluginIndexStorePath({ stateDir });
+
+    const [issue] = await detectPluginRegistryHealthIssues({
+      stateDir,
+      env: hermeticEnv(),
+      config: {},
+      prompter: { shouldRepair: false },
+    });
+
+    expect(issue).toEqual({
+      kind: "registry-missing-or-stale",
+      path: registryPath,
+    });
+    expect(pluginRegistryIssueToHealthFinding(issue)).toMatchObject({
+      checkId: "core/doctor/plugin-registry",
+      severity: "warning",
+      path: registryPath,
+      fixHint: "Run `openclaw doctor --fix` to rebuild the plugin registry from enabled plugins.",
+    });
+    expect(pluginRegistryIssueToRepairEffect(issue)).toEqual({
+      kind: "state",
+      action: "would-rebuild-plugin-registry",
+      target: registryPath,
+      dryRunSafe: false,
+    });
+  });
+
+  it("maps stale managed npm bundled plugin shadows to structured findings", async () => {
+    const stateDir = makeTempDir();
+    const bundledDir = path.join(stateDir, "bundled", "google-meet");
+    fs.mkdirSync(bundledDir, { recursive: true });
+    const managed = createManagedNpmPlugin({
+      stateDir,
+      id: "google-meet",
+      packageName: "@openclaw/google-meet",
+      version: "2026.5.2",
+    });
+    await writePersistedInstalledPluginIndex(createCurrentIndex(), { stateDir });
+
+    const issues = await detectPluginRegistryHealthIssues({
+      stateDir,
+      candidates: [
+        createBundledCandidate({
+          rootDir: bundledDir,
+          id: "google-meet",
+          packageName: "@openclaw/google-meet",
+          version: "2026.5.3",
+        }),
+      ],
+      env: hermeticEnv(),
+      config: {
+        plugins: {
+          allow: ["google-meet"],
+          entries: {
+            "google-meet": {
+              enabled: true,
+              config: {},
+            },
+          },
+        },
+      },
+      prompter: { shouldRepair: false },
+    });
+
+    const staleIssue = issues.find((issue) => issue.kind === "stale-managed-npm-bundled-plugin");
+    expect(staleIssue).toMatchObject({
+      kind: "stale-managed-npm-bundled-plugin",
+      pluginId: "google-meet",
+      packageName: "@openclaw/google-meet",
+      packageDir: managed.packageDir,
+      version: "2026.5.2",
+    });
+    expect(pluginRegistryIssueToHealthFinding(staleIssue!)).toMatchObject({
+      checkId: "core/doctor/plugin-registry",
+      severity: "warning",
+      path: managed.packageDir,
+      target: "google-meet",
+    });
+    expect(pluginRegistryIssueToRepairEffect(staleIssue!)).toEqual({
+      kind: "package",
+      action: "would-remove-stale-managed-npm-bundled-plugin",
+      target: managed.packageDir,
+      dryRunSafe: false,
+    });
+  });
+
+  it("maps stale local bundled install records to structured findings", async () => {
+    const stateDir = makeTempDir();
+    const bundledDir = path.join(stateDir, "current", "dist", "extensions", "discord");
+    const staleDir = path.join(stateDir, "old-checkout", "dist", "extensions", "discord");
+    fs.mkdirSync(bundledDir, { recursive: true });
+    fs.mkdirSync(staleDir, { recursive: true });
+    createCandidate(staleDir, "discord");
+    await writePersistedInstalledPluginIndex(
+      createCurrentIndexWithPathRecord({
+        pluginId: "discord",
+        installPath: staleDir,
+        version: "2026.5.4-beta.3",
+      }),
+      { stateDir },
+    );
+
+    const issues = await detectPluginRegistryHealthIssues({
+      stateDir,
+      candidates: [
+        createBundledCandidate({
+          rootDir: bundledDir,
+          id: "discord",
+          packageName: "@openclaw/discord",
+          version: "2026.5.20-beta.1",
+        }),
+      ],
+      env: hermeticEnv(),
+      config: {
+        plugins: {
+          allow: ["discord"],
+          entries: {
+            discord: {
+              enabled: true,
+              config: {},
+            },
+          },
+        },
+      },
+      prompter: { shouldRepair: false },
+    });
+
+    const staleIssue = issues.find(
+      (issue) => issue.kind === "stale-local-bundled-plugin-install-record",
+    );
+    expect(staleIssue).toEqual({
+      kind: "stale-local-bundled-plugin-install-record",
+      pluginId: "discord",
+      stalePath: staleDir,
+    });
+    expect(pluginRegistryIssueToHealthFinding(staleIssue!)).toMatchObject({
+      checkId: "core/doctor/plugin-registry",
+      severity: "warning",
+      path: staleDir,
+      target: "discord",
+    });
+  });
+
   it("refreshes an existing registry during repair", async () => {
     const stateDir = makeTempDir();
     const pluginDir = path.join(stateDir, "plugins", "demo");
diff --git a/src/commands/doctor-plugin-registry.ts b/src/commands/doctor-plugin-registry.ts
@@ -5,6 +5,7 @@ import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { note } from "../../packages/terminal-core/src/note.js";
 import { formatCliCommand } from "../cli/command-format.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import type { HealthFinding, HealthRepairEffect } from "../flows/health-checks.js";
 import { saveJsonFile } from "../infra/json-file.js";
 import { tryReadJsonSync } from "../infra/json-files.js";
 import type { BundledPluginSource } from "../plugins/bundled-sources.js";
@@ -18,6 +19,7 @@ import { hasRetainedManagedNpmInstallMarker } from "../plugins/managed-npm-reten
 import { listManagedPluginNpmRootsSync } from "../plugins/npm-project-roots.js";
 import {
   auditOpenClawPeerDependenciesInManagedNpmRoot,
+  type OpenClawPeerLinkAuditIssue,
   relinkOpenClawPeerDependenciesInManagedNpmRoot,
 } from "../plugins/plugin-peer-link.js";
 import { refreshPluginRegistry } from "../plugins/plugin-registry.js";
@@ -34,6 +36,8 @@ import {
   type PluginRegistryInstallMigrationParams,
 } from "./doctor/shared/plugin-registry-migration.js";
 
+const PLUGIN_REGISTRY_CHECK_ID = "core/doctor/plugin-registry";
+
 type PluginRegistryDoctorRepairParams = Omit<PluginRegistryInstallMigrationParams, "config"> &
   InstalledPluginIndexRecordStoreOptions & {
     config: OpenClawConfig;
@@ -53,6 +57,31 @@ type PluginRegistryDoctorNoteLogger = {
   warn: (message: string) => void;
 };
 
+export type PluginRegistryHealthIssue =
+  | {
+      kind: "registry-missing-or-stale";
+      path: string;
+    }
+  | {
+      kind: "stale-managed-npm-bundled-plugin";
+      pluginId: string;
+      packageName: string;
+      packageDir: string;
+      npmRoot: string;
+      version?: string;
+    }
+  | {
+      kind: "stale-local-bundled-plugin-install-record";
+      pluginId: string;
+      stalePath: string;
+    }
+  | {
+      kind: "managed-npm-openclaw-peer-link";
+      packageName: string;
+      packageDir: string;
+      reason: string;
+    };
+
 function readJsonObject(filePath: string): Record<string, unknown> | null {
   const parsed = tryReadJsonSync(filePath);
   return isRecord(parsed) ? parsed : null;
@@ -390,6 +419,137 @@ async function loadInstallRecordsWithoutPluginIds(
   return records;
 }
 
+async function listManagedNpmOpenClawPeerLinkIssues(
+  params: PluginRegistryDoctorRepairParams,
+): Promise<OpenClawPeerLinkAuditIssue[]> {
+  const audits = await Promise.all(
+    listManagedPluginNpmRoots(params).map((npmRoot) =>
+      auditOpenClawPeerDependenciesInManagedNpmRoot({ npmRoot }),
+    ),
+  );
+  return audits.flatMap((audit) => audit.issues);
+}
+
+export async function detectPluginRegistryHealthIssues(
+  params: PluginRegistryDoctorRepairParams,
+): Promise<PluginRegistryHealthIssue[]> {
+  const preflight = preflightPluginRegistryInstallMigration(params);
+  const issues: PluginRegistryHealthIssue[] = [];
+  if (preflight.action === "migrate") {
+    issues.push({
+      kind: "registry-missing-or-stale",
+      path: preflight.filePath,
+    });
+  }
+  for (const plugin of listStaleManagedNpmBundledPlugins(params)) {
+    issues.push({
+      kind: "stale-managed-npm-bundled-plugin",
+      pluginId: plugin.pluginId,
+      packageName: plugin.packageName,
+      packageDir: plugin.packageDir,
+      npmRoot: plugin.npmRoot,
+      ...(plugin.version ? { version: plugin.version } : {}),
+    });
+  }
+  for (const record of await listStaleLocalBundledPluginInstallRecordShadows(params)) {
+    issues.push({
+      kind: "stale-local-bundled-plugin-install-record",
+      pluginId: record.pluginId,
+      stalePath: record.stalePath,
+    });
+  }
+  for (const issue of await listManagedNpmOpenClawPeerLinkIssues(params)) {
+    issues.push({
+      kind: "managed-npm-openclaw-peer-link",
+      packageName: issue.packageName,
+      packageDir: issue.packageDir,
+      reason: issue.reason,
+    });
+  }
+  return issues;
+}
+
+export function pluginRegistryIssueToHealthFinding(
+  issue: PluginRegistryHealthIssue,
+): HealthFinding {
+  switch (issue.kind) {
+    case "registry-missing-or-stale":
+      return {
+        checkId: PLUGIN_REGISTRY_CHECK_ID,
+        severity: "warning",
+        message: "Persisted plugin registry is missing or stale.",
+        path: issue.path,
+        fixHint: "Run `openclaw doctor --fix` to rebuild the plugin registry from enabled plugins.",
+      };
+    case "stale-managed-npm-bundled-plugin":
+      return {
+        checkId: PLUGIN_REGISTRY_CHECK_ID,
+        severity: "warning",
+        message: `Managed npm package ${issue.packageName}${
+          issue.version ? `@${issue.version}` : ""
+        } shadows bundled plugin ${issue.pluginId}.`,
+        path: issue.packageDir,
+        target: issue.pluginId,
+        fixHint:
+          "Run `openclaw doctor --fix` to remove stale managed npm packages and rebuild the plugin registry.",
+      };
+    case "stale-local-bundled-plugin-install-record":
+      return {
+        checkId: PLUGIN_REGISTRY_CHECK_ID,
+        severity: "warning",
+        message: `Local install record for bundled plugin ${issue.pluginId} points at a stale path.`,
+        path: issue.stalePath,
+        target: issue.pluginId,
+        fixHint:
+          "Run `openclaw doctor --fix` to remove stale local install records and rebuild the plugin registry.",
+      };
+    case "managed-npm-openclaw-peer-link":
+      return {
+        checkId: PLUGIN_REGISTRY_CHECK_ID,
+        severity: "warning",
+        message: `Managed npm package ${issue.packageName} has a broken OpenClaw peer link: ${issue.reason}.`,
+        path: issue.packageDir,
+        target: issue.packageName,
+        fixHint: "Run `openclaw doctor --fix` to relink managed npm plugin packages.",
+      };
+  }
+}
+
+export function pluginRegistryIssueToRepairEffect(
+  issue: PluginRegistryHealthIssue,
+): HealthRepairEffect {
+  switch (issue.kind) {
+    case "registry-missing-or-stale":
+      return {
+        kind: "state",
+        action: "would-rebuild-plugin-registry",
+        target: issue.path,
+        dryRunSafe: false,
+      };
+    case "stale-managed-npm-bundled-plugin":
+      return {
+        kind: "package",
+        action: "would-remove-stale-managed-npm-bundled-plugin",
+        target: issue.packageDir,
+        dryRunSafe: false,
+      };
+    case "stale-local-bundled-plugin-install-record":
+      return {
+        kind: "state",
+        action: "would-remove-stale-local-bundled-plugin-install-record",
+        target: issue.pluginId,
+        dryRunSafe: false,
+      };
+    case "managed-npm-openclaw-peer-link":
+      return {
+        kind: "package",
+        action: "would-relink-managed-npm-openclaw-peer",
+        target: issue.packageDir,
+        dryRunSafe: false,
+      };
+  }
+}
+
 /**
  * Runs plugin registry doctor repairs and refreshes the persisted plugin index when needed.
  *
diff --git a/src/flows/doctor-health-contributions.test.ts b/src/flows/doctor-health-contributions.test.ts
@@ -1051,6 +1051,7 @@ describe("doctor health contributions", () => {
     expect(contributionIds).toContain("core/doctor/config-audit-scrub");
     expect(contributionIds).toContain("core/doctor/session-transcripts");
     expect(contributionIds).toContain("core/doctor/session-snapshots");
+    expect(contributionIds).toContain("core/doctor/plugin-registry");
     expect(contributionChecks.map((check) => check.id)).toEqual(contributionIds);
   });
 
diff --git a/src/flows/doctor-health-contributions.ts b/src/flows/doctor-health-contributions.ts
