@lifeaitools/clauth 1.30.16 → 1.30.18

package/cli/supervisor-registry.js

@@ -13,6 +13,7 @@ const ACTIONS = new Set(["start", "stop", "restart", "reconcile", "test", "promo
 const DEFAULT_HEALTH_RECONCILE_INTERVAL_MS = 10000;
 const DEFAULT_HEALTH_TIMEOUT_MS = 2500;
 const HEALTH_RECONCILE_COOLDOWN_MS = 15000;
+const DOCUMENTATION_FIELDS = ["architecture", "operator_guide", "install", "runbook", "tool_reference", "release", "agent_context"];
 
 export function getSupervisorPort() {
   return Number(process.env.CLAUTH_SUPERVISOR_PORT || DEFAULT_SUPERVISOR_PORT);
@@ -188,6 +189,25 @@ function normalizeDestination(destination) {
   return value;
 }
 
+function normalizeDocumentation(value) {
+  if (value == null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("documentation must be an object");
+  const documentation = {};
+  for (const field of DOCUMENTATION_FIELDS) {
+    if (value[field] == null) continue;
+    if (typeof value[field] !== "string" || !value[field].trim()) {
+      throw new Error(`documentation.${field} must be a non-empty path`);
+    }
+    const ref = value[field].trim().replaceAll("\\", "/");
+    if (ref.startsWith("/") || ref.includes("..") || /^[a-z]+:/i.test(ref)) {
+      throw new Error(`documentation.${field} must be a repository-relative path`);
+    }
+    documentation[field] = ref;
+  }
+  if (!documentation.architecture) throw new Error("documentation.architecture is required");
+  return documentation;
+}
+
 function localhostHealth(pathOrUrl, port) {
   if (!pathOrUrl) return null;
   if (/^https?:\/\//i.test(pathOrUrl)) {
@@ -237,6 +257,7 @@ export function validatePluginManifest(manifest, sourcePath = "") {
     id,
     version,
     publisher: String(manifest.publisher || "unknown"),
+    documentation: normalizeDocumentation(manifest.documentation),
     // Only trusted managed manifests may opt into automatic startup. User
     // plugins remain awaiting_enable until an operator explicitly enables them.
     core: manifest.core === true,
@@ -494,20 +515,33 @@ export function runSurfaceAction(id, action, actor = "localhost") {
   if (!command || command.length === 0) {
     return operation(action, { surface_id: id }, surface, { ok: false, state: "command_missing" }, actor);
   }
-  const [cmd, ...args] = command;
-  const result = spawnSync(cmd, args, {
-    cwd: surface.cwd || undefined,
-    env: { ...process.env, CLAUTH_PM2_HOME: getClauthPm2Home(), PM2_HOME: getClauthPm2Home() },
-    windowsHide: true,
-    encoding: "utf8",
-    timeout: Number(surface.timeoutMs || 30000),
-  });
+  const execute = (selectedCommand) => {
+    const [cmd, ...args] = selectedCommand;
+    return spawnSync(cmd, args, {
+      cwd: surface.cwd || undefined,
+      env: { ...process.env, CLAUTH_PM2_HOME: getClauthPm2Home(), PM2_HOME: getClauthPm2Home() },
+      windowsHide: true,
+      encoding: "utf8",
+      timeout: Number(surface.timeoutMs || 30000),
+    });
+  };
+  let result = execute(command);
+  let fallbackUsed = false;
+  // PM2 restart returns non-zero when the process was deleted. Reconcile is
+  // allowed to fall back to the declared start command; explicit restart keeps
+  // its strict failure semantics for operator-requested actions.
+  if (action === "reconcile" && result.status !== 0 && Array.isArray(surface.start) && surface.start.length > 0 && command !== surface.start) {
+    const restartStatus = result.status;
+    result = execute(surface.start);
+    fallbackUsed = true;
+    result.stderr = `restart exited ${restartStatus}; start fallback attempted\n${result.stderr || ""}`;
+  }
   return operation(action, { surface_id: id }, surface, {
     ok: result.status === 0,
     state: result.status === 0 ? "operation_completed" : "operation_failed",
     status: result.status,
     stderr: result.stderr?.slice(0, 2000),
-    evidence: [`CLAUTH_PM2_HOME=${getClauthPm2Home()}`],
+    evidence: [`CLAUTH_PM2_HOME=${getClauthPm2Home()}`, ...(fallbackUsed ? ["reconcile_start_fallback=true"] : [])],
   }, actor);
 }
 

package/cli/supervisor-registry.test.js

@@ -66,6 +66,11 @@ function baseManifest(id, overrides = {}) {
       restart: ["node", "--version"],
     }],
     test: { command: ["node", "--version"], port: "auto", health: "/health", selfTest: [["node", "--version"]] },
+    documentation: {
+      architecture: "docs/systems/example/ARCHITECTURE.md",
+      operator_guide: "docs/systems/example/OPERATE.md",
+      tool_reference: ".claude/context/mcp-endpoint-design.md",
+    },
     ...overrides,
   };
 }
@@ -77,6 +82,8 @@ test("validatePluginManifest accepts LIFEAI plugin contract with isolated test c
   assert.equal(plugin.surfaces[0].destination, "local/clauth/pm2");
   assert.equal(plugin.surfaces[0].lifecycle_owner, "clauth");
   assert.equal(plugin.surfaces[0].health, "http://127.0.0.1:39111/health");
+  assert.equal(plugin.documentation.architecture, "docs/systems/example/ARCHITECTURE.md");
+  assert.equal(plugin.documentation.operator_guide, "docs/systems/example/OPERATE.md");
 });
 
 test("validatePluginManifest accepts empty test command arrays from the v1 template", () => {
@@ -92,6 +99,15 @@ test("validatePluginManifest rejects invalid manifests and non-local health URLs
   assert.throws(() => validatePluginManifest(baseManifest("bad", {
     surfaces: [{ id: "bad", health: "https://example.com/health" }],
   })), /localhost-only/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { architecture: "../outside.md" },
+  })), /repository-relative/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { operator_guide: "docs/guide.md" },
+  })), /documentation.architecture is required/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { architecture: "https://example.com/architecture.md" },
+  })), /repository-relative/);
 });
 
 test("discovery merges managed and user roots without silent managed-id shadowing", () => withTempSupervisor((root) => {
@@ -174,6 +190,29 @@ test("surface actions use dedicated clauth PM2 home and keep CodeFlow observe-on
   assert.equal(supervisorHealth().surfaces, 2);
 }));
 
+test("reconcile falls back to the declared start command when restart reports a missing process", () => withTempSupervisor((root) => {
+  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", "fallback-demo", baseManifest("fallback-demo", {
+    core: true,
+    enable_default: true,
+    surfaces: [{
+      id: "primary",
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "clauth",
+      port: 39114,
+      health: "/health",
+      start: [process.execPath, "--version"],
+      restart: [process.execPath, "-e", "process.exit(1)"],
+    }],
+  }));
+  discoverPlugins();
+  const receipt = runSurfaceAction("fallback-demo:primary", "reconcile");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(receipt.resulting_state.evidence.includes("reconcile_start_fallback=true"), true);
+}));
+
 test("surface promote and rollback never fall through to restart commands", () => withTempSupervisor((root) => {
   const managed = path.join(root, "managed");
   process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/clauth",
-  "version": "1.30.16",
+  "version": "1.30.18",
   "description": "Hardware-bound credential vault for the LIFEAI infrastructure stack",
   "type": "module",
   "bin": {