fix(doctor): preview broken managed peer links

steipete · steipete · commit 974f3df7eb0f · 2026-05-12T07:32:55.000+01:00
diff --git a/src/commands/doctor-plugin-registry.test.ts b/src/commands/doctor-plugin-registry.test.ts
@@ -542,4 +542,40 @@ describe("maybeRepairPluginRegistryState", () => {
     expect(fs.realpathSync(linkPath)).toBe(fs.realpathSync(process.cwd()));
     expect(vi.mocked(note).mock.calls.join("\n")).toContain("Repaired OpenClaw host peer link");
   });
+
+  it("warns about broken managed npm openclaw peer links without repairing them", async () => {
+    const stateDir = makeTempDir();
+    const managed = createManagedNpmPlugin({
+      stateDir,
+      id: "codex",
+      packageName: "codex-plugin",
+      version: "2026.5.3",
+      peerDependencies: {
+        openclaw: ">=2026.5.3",
+      },
+    });
+    await writePersistedInstalledPluginIndex(
+      createCurrentIndexWithNpmRecord({
+        pluginId: "codex",
+        packageName: "codex-plugin",
+        packageDir: managed.packageDir,
+        version: "2026.5.3",
+      }),
+      { stateDir },
+    );
+
+    await maybeRepairPluginRegistryState({
+      stateDir,
+      env: hermeticEnv(),
+      config: {},
+      prompter: { shouldRepair: false },
+    });
+
+    const linkPath = path.join(managed.packageDir, "node_modules", "openclaw");
+    const notes = vi.mocked(note).mock.calls.join("\n");
+    expect(notes).toContain("Managed npm OpenClaw host peer links need repair");
+    expect(notes).toContain("codex-plugin");
+    expect(notes).toContain("openclaw doctor --fix");
+    expect(fs.existsSync(linkPath)).toBe(false);
+  });
 });
diff --git a/src/commands/doctor-plugin-registry.ts b/src/commands/doctor-plugin-registry.ts
@@ -10,7 +10,10 @@ import {
   type InstalledPluginIndexRecordStoreOptions,
 } from "../plugins/installed-plugin-index-records.js";
 import { loadInstalledPluginIndex } from "../plugins/installed-plugin-index.js";
-import { relinkOpenClawPeerDependenciesInManagedNpmRoot } from "../plugins/plugin-peer-link.js";
+import {
+  auditOpenClawPeerDependenciesInManagedNpmRoot,
+  relinkOpenClawPeerDependenciesInManagedNpmRoot,
+} from "../plugins/plugin-peer-link.js";
 import { refreshPluginRegistry } from "../plugins/plugin-registry.js";
 import { note } from "../terminal/note.js";
 import { shortenHomePath } from "../utils.js";
@@ -241,7 +244,19 @@ export function maybeRepairStaleManagedNpmBundledPlugins(
 export async function maybeRepairManagedNpmOpenClawPeerLinks(
   params: PluginRegistryDoctorRepairParams,
 ): Promise<boolean> {
+  const npmRoot = resolveManagedPluginNpmRoot(params);
   if (!params.prompter.shouldRepair) {
+    const audit = await auditOpenClawPeerDependenciesInManagedNpmRoot({ npmRoot });
+    if (audit.broken > 0) {
+      note(
+        [
+          "Managed npm OpenClaw host peer links need repair:",
+          ...audit.issues.map((issue) => `- ${issue.packageName}: ${issue.reason}`),
+          `Repair with ${formatCliCommand("openclaw doctor --fix")} to relink managed npm plugin packages.`,
+        ].join("\n"),
+        "Plugin registry",
+      );
+    }
     return false;
   }
 
@@ -251,7 +266,7 @@ export async function maybeRepairManagedNpmOpenClawPeerLinks(
     warn: (message) => messages.push({ level: "warn", message }),
   };
   const result = await relinkOpenClawPeerDependenciesInManagedNpmRoot({
-    npmRoot: resolveManagedPluginNpmRoot(params),
+    npmRoot,
     logger,
   });
 
diff --git a/src/plugins/plugin-peer-link.test.ts b/src/plugins/plugin-peer-link.test.ts
@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import {
+  auditOpenClawPeerDependenciesInManagedNpmRoot,
   linkOpenClawPeerDependencies,
   relinkOpenClawPeerDependenciesInManagedNpmRoot,
 } from "./plugin-peer-link.js";
@@ -50,6 +51,32 @@ describe("plugin peer links", () => {
     expect(messages.join("\n")).toContain('Linked peerDependency "openclaw"');
   });
 
+  it("audits missing managed npm openclaw peer links without relinking", async () => {
+    const npmRoot = makeTempDir();
+    const packageDir = path.join(npmRoot, "node_modules", "peer-plugin");
+    fs.mkdirSync(packageDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(packageDir, "package.json"),
+      JSON.stringify({
+        name: "peer-plugin",
+        version: "1.0.0",
+        peerDependencies: {
+          openclaw: ">=2026.0.0",
+        },
+      }),
+      "utf8",
+    );
+
+    const result = await auditOpenClawPeerDependenciesInManagedNpmRoot({ npmRoot });
+
+    const linkPath = path.join(packageDir, "node_modules", "openclaw");
+    expect(result.checked).toBe(1);
+    expect(result.broken).toBe(1);
+    expect(result.issues[0]?.packageName).toBe("peer-plugin");
+    expect(result.issues[0]?.reason).toContain(linkPath);
+    expect(fs.existsSync(linkPath)).toBe(false);
+  });
+
   it.runIf(process.platform !== "win32")(
     "does not follow a package-local node_modules symlink while linking openclaw peers",
     async () => {
diff --git a/src/plugins/plugin-peer-link.ts b/src/plugins/plugin-peer-link.ts
@@ -14,6 +14,18 @@ type RelinkManagedNpmRootResult = {
   skipped: number;
 };
 
+type OpenClawPeerLinkAuditIssue = {
+  packageName: string;
+  packageDir: string;
+  reason: string;
+};
+
+type AuditManagedNpmRootResult = {
+  checked: number;
+  broken: number;
+  issues: OpenClawPeerLinkAuditIssue[];
+};
+
 type OpenClawPeerLinkResult = "linked" | "skipped" | "unchanged";
 
 function readStringRecord(value: unknown): Record<string, string> {
@@ -89,6 +101,63 @@ async function safeRealpath(filePath: string): Promise<string | null> {
   }
 }
 
+function managedPackageNameFromDir(params: { npmRoot: string; packageDir: string }): string {
+  return path
+    .relative(path.join(params.npmRoot, "node_modules"), params.packageDir)
+    .split(path.sep)
+    .join("/");
+}
+
+async function auditOpenClawPeerDependency(params: {
+  hostRoot: string;
+  npmRoot: string;
+  packageDir: string;
+}): Promise<OpenClawPeerLinkAuditIssue | null> {
+  const packageName = managedPackageNameFromDir({
+    npmRoot: params.npmRoot,
+    packageDir: params.packageDir,
+  });
+  const nodeModulesDir = path.join(params.packageDir, "node_modules");
+  try {
+    const existing = await fs.lstat(nodeModulesDir);
+    if (!existing.isDirectory() || existing.isSymbolicLink()) {
+      return {
+        packageName,
+        packageDir: params.packageDir,
+        reason: `${nodeModulesDir} is not a real directory`,
+      };
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {
+        packageName,
+        packageDir: params.packageDir,
+        reason: `missing ${path.join(nodeModulesDir, "openclaw")}`,
+      };
+    }
+    throw error;
+  }
+
+  const linkPath = path.join(nodeModulesDir, "openclaw");
+  const currentTarget = await safeRealpath(linkPath);
+  if (!currentTarget) {
+    return {
+      packageName,
+      packageDir: params.packageDir,
+      reason: `missing ${linkPath}`,
+    };
+  }
+  const expectedTarget = (await safeRealpath(params.hostRoot)) ?? params.hostRoot;
+  if (currentTarget !== expectedTarget) {
+    return {
+      packageName,
+      packageDir: params.packageDir,
+      reason: `${linkPath} points to ${currentTarget} instead of ${expectedTarget}`,
+    };
+  }
+  return null;
+}
+
 async function ensureRealNodeModulesDir(params: {
   installedDir: string;
   logger: PluginPeerLinkLogger;
@@ -222,3 +291,35 @@ export async function relinkOpenClawPeerDependenciesInManagedNpmRoot(params: {
   }
   return { checked, attempted, repaired, skipped };
 }
+
+export async function auditOpenClawPeerDependenciesInManagedNpmRoot(params: {
+  npmRoot: string;
+}): Promise<AuditManagedNpmRootResult> {
+  const hostRoot = resolveOpenClawPackageRootSync({
+    argv1: process.argv[1],
+    moduleUrl: import.meta.url,
+    cwd: process.cwd(),
+  });
+  if (!hostRoot) {
+    return { checked: 0, broken: 0, issues: [] };
+  }
+
+  let checked = 0;
+  const issues: OpenClawPeerLinkAuditIssue[] = [];
+  for (const packageDir of await listManagedNpmRootPackageDirs(params.npmRoot)) {
+    const peerDependencies = await readPackagePeerDependencies(packageDir);
+    if (!Object.hasOwn(peerDependencies, "openclaw")) {
+      continue;
+    }
+    checked += 1;
+    const issue = await auditOpenClawPeerDependency({
+      hostRoot,
+      npmRoot: params.npmRoot,
+      packageDir,
+    });
+    if (issue) {
+      issues.push(issue);
+    }
+  }
+  return { checked, broken: issues.length, issues };
+}
