@lifeaitools/clauth 2.0.0 → 2.0.1

package/cli/supervisor-registry.test.js

@@ -6,6 +6,7 @@ import test from "node:test";
 
 import {
   addTunnelRoute,
+  deregisterPlugin,
   discoverPlugins,
   getClauthPm2Home,
   listPlugins,
@@ -18,6 +19,9 @@ import {
   setPluginEnabled,
   shellQuote,
   supervisorHealth,
+  syncPluginsFromRepos,
+  SYNC_REPO_NAMES,
+  SYNC_SKIP_STATES,
   validatePluginManifest,
 } from "./supervisor-registry.js";
 import { isLoopbackAddress, supervisorLogDto, supervisorRequiresWriteToken } from "./commands/serve.js";
@@ -29,6 +33,14 @@ function withTempSupervisor(fn) {
   const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
   const oldPm2 = process.env.CLAUTH_PM2_HOME;
   process.env.CLAUTH_SUPERVISOR_DIR = root;
+  // CLAUTH_MANAGED_PLUGIN_ROOTS / CLAUTH_USER_PLUGIN_ROOTS are set as PERSISTENT
+  // MACHINE-LEVEL env vars on developer boxes, pointing at the LIVE daemon's
+  // plugin directories. rootEntries() prefers them over CLAUTH_SUPERVISOR_DIR,
+  // so overriding the supervisor dir ALONE leaves registerPlugin/deregisterPlugin
+  // writing to (and deleting from) the live fleet. Pin all three to the temp
+  // root here so a test cannot reach the live daemon by forgetting to.
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed-plugins");
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user-plugins");
   delete process.env.CLAUTH_PM2_HOME;
   try {
     return fn(root);
@@ -398,17 +410,46 @@ test("health reconciliation never restarts external or plugin-owned surfaces", a
   process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
   process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
   try {
+    // Both fixtures are deliberately PROBE-ABLE — local destination + port, so
+    // healthUrlForSurface() yields a real URL for each. That is what gives this
+    // test teeth.
+    //
+    // An earlier revision made the external fixture `vultr/` with no port. It
+    // read as equivalent and was not: portless + relative health resolves to a
+    // null URL, so reconcileSurfaceHealth's `if (!url) continue` skipped it
+    // BEFORE the owner/destination guard was consulted. Delete the guard this
+    // test is named for and it still passed green — it proved the surface was
+    // unprobe-able, not that it was probe-able and correctly left alone.
+    //
+    // Now the ONLY thing that can exclude external-demo is lifecycle_owner, and
+    // clauth-owned-demo is the positive control proving the probe machinery
+    // actually runs against this fixture shape. If `inspected` ever comes back
+    // empty, the control failed and the negative result means nothing.
     writePlugin(root, "managed", "external-demo", baseManifest("external-demo", {
       core: true,
       enable_default: true,
-      destination: "vultr/clauth/pm2",
+      destination: "local/clauth/pm2",
       lifecycle_owner: "external",
-      surfaces: [{ id: "primary", destination: "vultr/clauth/pm2", lifecycle_owner: "external", port: 39112, health: "/health" }],
+      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "external", port: 39112, health: "/health" }],
+    }));
+    writePlugin(root, "managed", "clauth-owned-demo", baseManifest("clauth-owned-demo", {
+      core: true,
+      enable_default: true,
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "clauth",
+      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "clauth", port: 39113, health: "/health" }],
     }));
     discoverPlugins();
     const result = await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: false, status: 503 }) });
-    assert.deepEqual(result.inspected, []);
-    assert.equal(listSurfaces()[0].state, "current");
+    const inspectedIds = result.inspected.map((s) => (typeof s === "string" ? s : s.surface_id));
+    // Positive control: the probe machinery ran at all.
+    assert.ok(inspectedIds.some((id) => String(id).includes("clauth-owned-demo")),
+      `control failed — clauth-owned surface was not probed, so "external was skipped" proves nothing (inspected: ${JSON.stringify(result.inspected)})`);
+    // The actual assertion: an externally-owned surface is never touched.
+    assert.ok(!inspectedIds.some((id) => String(id).includes("external-demo")),
+      `external-demo was probed — the lifecycle_owner guard is not excluding it (inspected: ${JSON.stringify(result.inspected)})`);
+    const external = listSurfaces().find((s) => s.plugin_id === "external-demo");
+    assert.equal(external.state, "current");
   } finally {
     if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
     else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
@@ -529,6 +570,306 @@ test("registerPlugin rejects an invalid manifest without writing anything", () =
   fs.rmSync(sourceDir, { recursive: true, force: true });
 }));
 
+// Builds throwaway product repos laid out like the real ones, so a sync sweep
+// exercises the real relative manifest paths without reading a live checkout.
+function withTempProductRepos(fn) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-sync-repos-"));
+  const regenRoot = path.join(base, "regen-root");
+  const rdcSkills = path.join(base, "rdc-skills");
+  const writeManifest = (repoRoot, relPath, manifest) => {
+    const full = path.join(repoRoot, relPath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, typeof manifest === "string" ? manifest : `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return full;
+  };
+  writeManifest(regenRoot, "packages/codeflow/clauth-plugin.json", baseManifest("codeflow-mcp"));
+  writeManifest(regenRoot, "apps/dev-center/clauth-plugin.json", baseManifest("dev-center"));
+  writeManifest(regenRoot, "mcp-servers/regen-media/clauth-plugin.json", baseManifest("regen-media"));
+  writeManifest(regenRoot, "mcp-servers/web-research/clauth-plugin.json", baseManifest("web-research"));
+  writeManifest(rdcSkills, "clauth-plugin.json", baseManifest("rdc-skills"));
+  try {
+    return fn({ base, regenRoot, rdcSkills, writeManifest, roots: { "regen-root": regenRoot, "rdc-skills": rdcSkills } });
+  } finally {
+    fs.rmSync(base, { recursive: true, force: true });
+  }
+}
+
+test("plugin sync inherits registerPlugin idempotence — a second sweep reports every manifest unchanged", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  const first = syncPluginsFromRepos(roots, "test");
+  assert.equal(first.length, 5, "one receipt per attempted manifest");
+  assert.deepEqual(
+    first.filter((entry) => !entry.ok).map((entry) => `${entry.repo}:${entry.state}`),
+    [],
+    "every manifest in a complete checkout must register",
+  );
+  assert.equal(first.every((entry) => entry.state === "registered"), true);
+
+  // registerPlugin sha256-compares before writing; sync must not defeat that by
+  // re-writing or re-hashing on its own.
+  const second = syncPluginsFromRepos(roots, "test");
+  assert.equal(second.length, 5);
+  assert.equal(second.every((entry) => entry.ok && entry.state === "unchanged"), true, "re-sweeping identical content must be a no-op");
+})));
+
+test("plugin sync warns and continues over a missing repo root instead of throwing", () => withTempSupervisor(() => withTempProductRepos(({ base, rdcSkills }) => {
+  // A box that never checked out regen-root must still sync what it does have.
+  const absent = path.join(base, "no-such-checkout");
+  assert.equal(fs.existsSync(absent), false);
+  let receipts;
+  assert.doesNotThrow(() => {
+    receipts = syncPluginsFromRepos({ "regen-root": absent, "rdc-skills": rdcSkills }, "test");
+  });
+  assert.equal(receipts.length, 5, "a skipped repo still yields a receipt per attempted manifest");
+  const missing = receipts.filter((entry) => entry.state === "repo_root_missing");
+  assert.equal(missing.length, 4, "all four regen-root manifests report the missing root");
+  assert.equal(missing.every((entry) => entry.ok === false), true);
+  const skills = receipts.find((entry) => entry.repo === "rdc-skills");
+  assert.equal(skills.ok, true);
+  assert.equal(skills.state, "registered");
+  assert.ok(listPlugins().find((plugin) => plugin.id === "rdc-skills"), "the reachable repo still registered");
+})));
+
+test("plugin sync registers the remaining manifests when one is malformed", () => withTempSupervisor(() => withTempProductRepos(({ regenRoot, roots, writeManifest }) => {
+  writeManifest(regenRoot, "apps/dev-center/clauth-plugin.json", "{ this is not valid json");
+
+  const receipts = syncPluginsFromRepos(roots, "test");
+  assert.equal(receipts.length, 5);
+  const bad = receipts.find((entry) => entry.path.includes("dev-center"));
+  assert.equal(bad.ok, false);
+  assert.equal(bad.state, "manifest_invalid");
+  const good = receipts.filter((entry) => entry !== bad);
+  assert.equal(good.length, 4);
+  assert.equal(good.every((entry) => entry.ok && entry.state === "registered"), true, "one bad manifest must not abort the sweep");
+  const ids = new Set(listPlugins().map((plugin) => plugin.id));
+  for (const id of ["codeflow-mcp", "regen-media", "web-research", "rdc-skills"]) {
+    assert.ok(ids.has(id), `${id} must still be registered`);
+  }
+})));
+
+test("deregisterPlugin removes only the named plugin and leaves siblings intact", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), true);
+
+  const receipt = deregisterPlugin("web-research", "test");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(receipt.resulting_state.state, "deregistered");
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), false, "the named plugin directory is gone");
+
+  for (const sibling of ["codeflow-mcp", "dev-center", "regen-media", "rdc-skills"]) {
+    assert.equal(fs.existsSync(path.join(managed, sibling)), true, `${sibling} must survive`);
+  }
+  // discovery re-ran, so the removed managed plugin is reported missing, not current
+  const after = listPlugins().find((plugin) => plugin.id === "web-research");
+  assert.equal(after.state, "missing_default");
+  assert.equal(after.enabled, false);
+})));
+
+test("deregisterPlugin on an unregistered id is a safe no-op, not an error", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const before = fs.readdirSync(managed).sort();
+
+  const receipt = deregisterPlugin("never-registered-plugin", "test");
+  assert.equal(receipt.resulting_state.ok, true, "a no-op is success, not failure");
+  assert.equal(receipt.resulting_state.state, "not_registered");
+  assert.deepEqual(fs.readdirSync(managed).sort(), before, "nothing else may be touched");
+})));
+
+test("deregisterPlugin rejects an id that would escape the managed-plugins root", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  // Mirrors the registerPlugin traversal test. The id here is raw CLI/HTTP
+  // input with no manifest validation upstream, and the operation DELETES
+  // recursively — so an id resolving to the root itself must reject too, which
+  // is where this is strictly stricter than registerPlugin's assertion.
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const sentinel = path.join(managed, "..", "sentinel-outside-root.txt");
+  fs.writeFileSync(sentinel, "must survive", "utf8");
+  const before = fs.readdirSync(managed).sort();
+
+  const evilIds = [
+    "..", "../..", "../sentinel-outside-root.txt", "..\\..", "/etc", "", ".",
+    // These three are stopped by the CHARSET guard alone — the containment
+    // assert waves all of them through, because path.resolve() normalizes the
+    // `..` away and Windows re-anchors a drive-relative path, so each lands
+    // back INSIDE the root (measured during code review). They are pinned here
+    // so the two guards are independently tested and nobody "simplifies" the
+    // charset rule believing containment is a safety net for it.
+    "sub/../web-research",
+    "C:web-research",
+    "web-research::$DATA",
+  ];
+  for (const evil of evilIds) {
+    const receipt = deregisterPlugin(evil, "test");
+    assert.equal(receipt.resulting_state.ok, false, `id ${JSON.stringify(evil)} must be rejected`);
+    assert.equal(receipt.resulting_state.state, "invalid_plugin_id");
+  }
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), true, "a charset-rejected alias must not have deleted the real plugin");
+
+  assert.equal(fs.existsSync(sentinel), true, "must never delete outside the managed-plugins root");
+  assert.equal(fs.existsSync(managed), true, "must never delete the managed-plugins root itself");
+  assert.deepEqual(fs.readdirSync(managed).sort(), before, "no registered plugin may be removed by a rejected id");
+})));
+
+test("validatePluginManifest rejects a port on any non-local destination, and keeps local ports", () => {
+  // A remote surface is reached by URL; its port is the deployment registry's
+  // fact. Copying it into the manifest creates a second home for one fact that
+  // then drifts (regen-media 3121 vs 3120, dev-center 3012 vs 3003). Worse, a
+  // ported remote surface makes localhostHealth() synthesize
+  // http://127.0.0.1:<port>/health for a service on another box, pointing the
+  // health reconciler at the wrong machine.
+  //
+  // The rule is keyed on the validated DESTINATION enum, never on the surface's
+  // free-text id/role — keying on the label was tried in review and failed both
+  // ways: renaming the surface bypassed it, and a local surface named "remote"
+  // was falsely rejected. Both directions are asserted below.
+  for (const destination of ["vultr/clauth/pm2", "coolify/clauth/docker"]) {
+    for (const port of [3110, "auto", 0]) {
+      assert.throws(() => validatePluginManifest(baseManifest("remote-port", {
+        surfaces: [{ id: "remote", destination, lifecycle_owner: "external", port }],
+      })), /must not declare a port/, `${destination} + port ${JSON.stringify(port)} must be rejected`);
+    }
+  }
+  // Renaming the surface must NOT bypass the rule — this is the bypass that
+  // keying on the `remote` label allowed.
+  for (const id of ["vultr", "prod", "primary", "local"]) {
+    assert.throws(() => validatePluginManifest(baseManifest("renamed-remote", {
+      surfaces: [{ id, destination: "vultr/clauth/pm2", lifecycle_owner: "external", port: 3110 }],
+    })), /must not declare a port/, `a non-local surface named "${id}" must still be rejected`);
+  }
+
+  // A remote surface WITHOUT a port is accepted — the shape all four shipped
+  // remote surfaces already use.
+  const remote = validatePluginManifest(baseManifest("remote-ok", {
+    surfaces: [{ id: "remote", destination: "vultr/clauth/pm2", lifecycle_owner: "external" }],
+  }), "clauth-plugin.json");
+  assert.equal(remote.surfaces[0].port, null);
+
+  // A LOCAL surface keeps its port on purpose — that port describes how the
+  // service runs on a developer box. This is not drift; do not "fix" it. A
+  // local surface merely NAMED "remote" is local, and must not be rejected.
+  for (const [id, destination] of [["local", "local/clauth/pm2"], ["primary", "local/clauth/pm2"], ["remote", "local/clauth/daemon"]]) {
+    const localSurface = validatePluginManifest(baseManifest(`${id}-ok`, {
+      surfaces: [{ id, destination, lifecycle_owner: "clauth", port: 3109, health: "/health" }],
+    }), "clauth-plugin.json");
+    assert.equal(localSurface.surfaces[0].port, 3109, `${destination} surface must keep its port`);
+    assert.equal(localSurface.surfaces[0].health, "http://127.0.0.1:3109/health");
+  }
+});
+
+test("deregisterPlugin removes a scoped @scope/pkg plugin instead of falsely reporting it absent", () => withTempSupervisor((root) => {
+  // A removal verb that reports ✓ while the plugin stays installed AND enabled
+  // is the one receipt this must never get wrong. The flat <root>/<id> probe
+  // misses the scoped layout entirely, so the location is resolved from the
+  // discovery_root/sourcePath discovery already records.
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp", { core: true, enable_default: true }));
+  discoverPlugins();
+  assert.equal(listPlugins().find((plugin) => plugin.id === "fs-mcp").enabled, true, "precondition: scoped plugin is enabled");
+
+  const receipt = deregisterPlugin("fs-mcp", "test");
+  assert.equal(receipt.resulting_state.state, "deregistered", "must not report not_registered for a scoped plugin");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(fs.existsSync(path.join(managed, "@lifeaitools", "fs-mcp")), false, "the scoped package directory is actually gone");
+  const after = listPlugins().find((plugin) => plugin.id === "fs-mcp");
+  assert.equal(after.enabled, false, "a deregistered plugin must not remain enabled");
+  assert.equal(after.state, "missing_default");
+}));
+
+test("deregisterPlugin finds a plugin in a non-first managed root and refuses a user-root plugin", () => withTempSupervisor((root) => {
+  // CLAUTH_MANAGED_PLUGIN_ROOTS is a path-delimited LIST; honoring only the
+  // first entry silently reports a real plugin as absent.
+  const managedA = path.join(root, "managed-a");
+  const managedB = path.join(root, "managed-b");
+  const user = path.join(root, "user");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = [managedA, managedB].join(path.delimiter);
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = user;
+  writePlugin(root, "managed-b", "second-root-plugin", baseManifest("second-root-plugin"));
+  writePlugin(root, "user", "user-only-plugin", baseManifest("user-only-plugin"));
+  discoverPlugins();
+
+  const second = deregisterPlugin("second-root-plugin", "test");
+  assert.equal(second.resulting_state.state, "deregistered", "a plugin in the 2nd managed root must be found");
+  assert.equal(fs.existsSync(path.join(managedB, "second-root-plugin")), false);
+
+  // A user-root plugin is out of this verb's remit — refuse it explicitly
+  // rather than reporting a green "not_registered" that implies it is gone.
+  const userReceipt = deregisterPlugin("user-only-plugin", "test");
+  assert.equal(userReceipt.resulting_state.ok, false);
+  assert.equal(userReceipt.resulting_state.state, "not_managed");
+  assert.equal(fs.existsSync(path.join(user, "user-only-plugin")), true, "the user plugin must be left intact");
+}));
+
+test("deregisterPlugin --dry-run resolves the target without deleting it", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+
+  const receipt = deregisterPlugin("web-research", "test", { dryRun: true });
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(receipt.resulting_state.state, "would_deregister");
+  assert.equal(receipt.resulting_state.target_dir, path.resolve(managed, "web-research"));
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), true, "a dry run must not delete anything");
+  assert.equal(listPlugins().find((plugin) => plugin.id === "web-research").state !== "missing_default", true);
+})));
+
+test("plugin sync reports an unknown repo-root override instead of silently sweeping the default checkout", () => withTempSupervisor(() => withTempProductRepos(({ roots, base }) => {
+  // A typo'd override name dropped on the floor means the sweep reads the
+  // DEFAULT checkout while printing ✓ on every line — success from the wrong repo.
+  const receipts = syncPluginsFromRepos({ ...roots, regen_root: path.join(base, "typo-checkout") }, "test");
+  const rejected = receipts.filter((entry) => entry.state === "unknown_repo_name");
+  assert.equal(rejected.length, 1);
+  assert.equal(rejected[0].repo, "regen_root");
+  assert.equal(rejected[0].ok, false);
+  assert.match(rejected[0].error, /unknown repo name/);
+  assert.equal(SYNC_SKIP_STATES.includes("unknown_repo_name"), false, "a typo'd repo name must fail the sweep, not be skipped");
+  assert.deepEqual([...SYNC_REPO_NAMES].sort(), ["rdc-skills", "regen-root"]);
+})));
+
+test("plugin sync never throws on a malformed repo root — the contract absence must not break", () => withTempSupervisor(() => withTempProductRepos(({ rdcSkills }) => {
+  // path.resolve() throws on a non-string; doing that before the existence
+  // guard aborted the whole sweep and lost every later repo's receipt.
+  for (const badRoot of [123, "   ", {}, [], true]) {
+    let receipts;
+    assert.doesNotThrow(() => {
+      receipts = syncPluginsFromRepos({ "regen-root": badRoot, "rdc-skills": rdcSkills }, "test");
+    }, `root ${JSON.stringify(badRoot)} must not throw`);
+    assert.equal(receipts.length, 5, "every attempted manifest still yields a receipt");
+    assert.equal(
+      receipts.filter((entry) => entry.repo === "regen-root" && entry.state === "repo_root_unknown").length,
+      4,
+      `root ${JSON.stringify(badRoot)} must be reported, not thrown`,
+    );
+    const skills = receipts.find((entry) => entry.repo === "rdc-skills");
+    assert.equal(skills.ok, true, "a later repo must still be swept after a bad earlier root");
+  }
+})));
+
+test("regression: scoped @scope/pkg and unscoped discovery both still work alongside deregister", () => withTempSupervisor((root) => {
+  // Epic 63d4d778 WP-1 taught findManifestFiles to descend one extra level for
+  // an @scope directory (node_modules/@lifeaitools/fs-mcp). Neither the sync
+  // sweep nor deregisterPlugin may regress that.
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  writePlugin(root, "managed", "plain-plugin", baseManifest("plain-plugin"));
+  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp"));
+
+  const discovered = discoverPlugins();
+  assert.ok(discovered.plugins.find((plugin) => plugin.id === "plain-plugin"), "unscoped layout still discovered");
+  assert.ok(discovered.plugins.find((plugin) => plugin.id === "fs-mcp"), "scoped layout still discovered");
+
+  // Deregistering the unscoped plugin must not disturb the scoped tree.
+  const receipt = deregisterPlugin("plain-plugin", "test");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(fs.existsSync(path.join(managed, "plain-plugin")), false);
+  assert.equal(fs.existsSync(path.join(managed, "@lifeaitools", "fs-mcp", "clauth-plugin.json")), true, "scoped package must be untouched");
+
+  const after = discoverPlugins();
+  assert.ok(after.plugins.find((plugin) => plugin.id === "fs-mcp" && plugin.state !== "missing_default"), "scoped plugin still discoverable after a sibling deregister");
+}));
+
 test("tunnel route add and remove produce reversible operation receipts", () => withTempSupervisor((root) => {
   process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
   process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");