@lifeaitools/clauth 1.30.26 → 2.0.0

package/cli/commands/uninstall.js

@@ -1,164 +1,164 @@
-// cli/commands/uninstall.js
-// clauth uninstall — full teardown: DB objects, Edge Function, secrets, skill, local config
-//
-// Reverses everything `clauth install` does:
-//   1. Drops clauth tables, policies, triggers, functions from Supabase
-//   2. Deletes auth-vault Edge Function
-//   3. Removes CLAUTH_* secrets
-//   4. Removes Claude skill directory
-//   5. Clears local config (Conf store)
-
-import { existsSync, rmSync } from 'fs';
-import { join } from 'path';
-import Conf from 'conf';
-import chalk from 'chalk';
-import ora from 'ora';
-
-const MGMT = 'https://api.supabase.com/v1';
-const SKILLS_DIR = process.env.CLAUTH_SKILLS_DIR ||
-  (process.platform === 'win32'
-    ? join(process.env.USERPROFILE || '', '.claude', 'skills')
-    : join(process.env.HOME || '', '.claude', 'skills'));
-
-// ─────────────────────────────────────────────
-// Supabase Management API helper
-// ─────────────────────────────────────────────
-async function mgmt(pat, method, path, body) {
-  const res = await fetch(`${MGMT}${path}`, {
-    method,
-    headers: { 'Authorization': `Bearer ${pat}`, 'Content-Type': 'application/json' },
-    body: body ? JSON.stringify(body) : undefined,
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => res.statusText);
-    throw new Error(`${method} ${path} → HTTP ${res.status}: ${text}`);
-  }
-  if (res.status === 204) return {};
-  const text = await res.text();
-  if (!text) return {};
-  return JSON.parse(text);
-}
-
-// ─────────────────────────────────────────────
-// Main uninstall command
-// ─────────────────────────────────────────────
-export async function runUninstall(opts = {}) {
-  console.log(chalk.red('\n🗑️  clauth uninstall\n'));
-
-  const config = new Conf({ projectName: 'clauth' });
-
-  // ── Collect credentials ────────────────────
-  const ref = opts.ref || config.get('supabase_url')?.match(/https:\/\/(.+)\.supabase\.co/)?.[1];
-  const pat = opts.pat;
-
-  if (!ref) {
-    console.log(chalk.red('  Cannot determine Supabase project ref.'));
-    console.log(chalk.gray('  Use: clauth uninstall --ref <project-ref> --pat <personal-access-token>'));
-    process.exit(1);
-  }
-  if (!pat) {
-    console.log(chalk.red('  Supabase PAT required for teardown.'));
-    console.log(chalk.gray('  Use: clauth uninstall --ref <project-ref> --pat <personal-access-token>'));
-    process.exit(1);
-  }
-
-  console.log(chalk.gray(`  Project: ${ref}\n`));
-
-  // ── Step 1: Drop database objects ──────────
-  const s1 = ora('Dropping clauth database objects...').start();
-  const teardownSQL = `
-    -- Drop triggers
-    DROP TRIGGER IF EXISTS clauth_services_updated ON public.clauth_services;
-
-    -- Drop tables (CASCADE drops policies automatically)
-    DROP TABLE IF EXISTS public.clauth_audit CASCADE;
-    DROP TABLE IF EXISTS public.clauth_machines CASCADE;
-    DROP TABLE IF EXISTS public.clauth_services CASCADE;
-
-    -- Drop functions
-    DROP FUNCTION IF EXISTS public.clauth_touch_updated() CASCADE;
-    DROP FUNCTION IF EXISTS public.clauth_upsert_vault_secret(text, text) CASCADE;
-    DROP FUNCTION IF EXISTS public.clauth_get_vault_secret(text) CASCADE;
-    DROP FUNCTION IF EXISTS public.clauth_delete_vault_secret(text) CASCADE;
-  `;
-
-  try {
-    await mgmt(pat, 'POST', `/projects/${ref}/database/query`, { query: teardownSQL });
-    s1.succeed('Database objects dropped (tables, triggers, functions, policies)');
-  } catch (e) {
-    s1.fail(`Database teardown failed: ${e.message}`);
-    console.log(chalk.yellow('  You may need to drop objects manually via SQL editor.'));
-  }
-
-  // ── Step 2: Delete Edge Function ───────────
-  const s2 = ora('Deleting auth-vault Edge Function...').start();
-  try {
-    const res = await fetch(`${MGMT}/projects/${ref}/functions/auth-vault`, {
-      method: 'DELETE',
-      headers: { 'Authorization': `Bearer ${pat}` },
-    });
-    if (res.ok || res.status === 404) {
-      s2.succeed(res.status === 404
-        ? 'Edge Function not found (already deleted)'
-        : 'Edge Function deleted');
-    } else {
-      const text = await res.text().catch(() => res.statusText);
-      throw new Error(`HTTP ${res.status}: ${text}`);
-    }
-  } catch (e) {
-    s2.fail(`Edge Function delete failed: ${e.message}`);
-    console.log(chalk.yellow('  Delete manually: Supabase Dashboard → Edge Functions → auth-vault → Delete'));
-  }
-
-  // ── Step 3: Remove secrets ─────────────────
-  const s3 = ora('Removing clauth secrets...').start();
-  try {
-    // Supabase Management API: DELETE /projects/{ref}/secrets with body listing secret names
-    const res = await fetch(`${MGMT}/projects/${ref}/secrets`, {
-      method: 'DELETE',
-      headers: { 'Authorization': `Bearer ${pat}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify(['CLAUTH_HMAC_SALT', 'CLAUTH_ADMIN_BOOTSTRAP_TOKEN']),
-    });
-    if (res.ok) {
-      s3.succeed('Secrets removed (CLAUTH_HMAC_SALT, CLAUTH_ADMIN_BOOTSTRAP_TOKEN)');
-    } else {
-      const text = await res.text().catch(() => res.statusText);
-      throw new Error(`HTTP ${res.status}: ${text}`);
-    }
-  } catch (e) {
-    s3.warn(`Secret removal failed: ${e.message}`);
-    console.log(chalk.yellow('  Remove manually: Supabase → Settings → Edge Functions → Secrets'));
-  }
-
-  // ── Step 4: Remove Claude skill ────────────
-  const s4 = ora('Removing Claude skill...').start();
-  const skillDir = join(SKILLS_DIR, 'clauth');
-  if (existsSync(skillDir)) {
-    try {
-      rmSync(skillDir, { recursive: true, force: true });
-      s4.succeed(`Skill removed: ${skillDir}`);
-    } catch (e) {
-      s4.warn(`Could not remove skill: ${e.message}`);
-    }
-  } else {
-    s4.succeed('Skill directory not found (already removed)');
-  }
-
-  // ── Step 5: Clear local config ─────────────
-  const s5 = ora('Clearing local config...').start();
-  try {
-    config.clear();
-    s5.succeed('Local config cleared');
-  } catch (e) {
-    s5.warn(`Could not clear config: ${e.message}`);
-  }
-
-  // ── Done ───────────────────────────────────
-  console.log('');
-  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-  console.log(chalk.yellow('  ✓ clauth fully uninstalled'));
-  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-  console.log('');
-  console.log(chalk.gray('  To reinstall: npx @lifeaitools/clauth install'));
-  console.log('');
-}
+// cli/commands/uninstall.js
+// clauth uninstall — full teardown: DB objects, Edge Function, secrets, skill, local config
+//
+// Reverses everything `clauth install` does:
+//   1. Drops clauth tables, policies, triggers, functions from Supabase
+//   2. Deletes auth-vault Edge Function
+//   3. Removes CLAUTH_* secrets
+//   4. Removes Claude skill directory
+//   5. Clears local config (Conf store)
+
+import { existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import Conf from 'conf';
+import chalk from 'chalk';
+import ora from 'ora';
+
+const MGMT = 'https://api.supabase.com/v1';
+const SKILLS_DIR = process.env.CLAUTH_SKILLS_DIR ||
+  (process.platform === 'win32'
+    ? join(process.env.USERPROFILE || '', '.claude', 'skills')
+    : join(process.env.HOME || '', '.claude', 'skills'));
+
+// ─────────────────────────────────────────────
+// Supabase Management API helper
+// ─────────────────────────────────────────────
+async function mgmt(pat, method, path, body) {
+  const res = await fetch(`${MGMT}${path}`, {
+    method,
+    headers: { 'Authorization': `Bearer ${pat}`, 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(`${method} ${path} → HTTP ${res.status}: ${text}`);
+  }
+  if (res.status === 204) return {};
+  const text = await res.text();
+  if (!text) return {};
+  return JSON.parse(text);
+}
+
+// ─────────────────────────────────────────────
+// Main uninstall command
+// ─────────────────────────────────────────────
+export async function runUninstall(opts = {}) {
+  console.log(chalk.red('\n🗑️  clauth uninstall\n'));
+
+  const config = new Conf({ projectName: 'clauth' });
+
+  // ── Collect credentials ────────────────────
+  const ref = opts.ref || config.get('supabase_url')?.match(/https:\/\/(.+)\.supabase\.co/)?.[1];
+  const pat = opts.pat;
+
+  if (!ref) {
+    console.log(chalk.red('  Cannot determine Supabase project ref.'));
+    console.log(chalk.gray('  Use: clauth uninstall --ref <project-ref> --pat <personal-access-token>'));
+    process.exit(1);
+  }
+  if (!pat) {
+    console.log(chalk.red('  Supabase PAT required for teardown.'));
+    console.log(chalk.gray('  Use: clauth uninstall --ref <project-ref> --pat <personal-access-token>'));
+    process.exit(1);
+  }
+
+  console.log(chalk.gray(`  Project: ${ref}\n`));
+
+  // ── Step 1: Drop database objects ──────────
+  const s1 = ora('Dropping clauth database objects...').start();
+  const teardownSQL = `
+    -- Drop triggers
+    DROP TRIGGER IF EXISTS clauth_services_updated ON public.clauth_services;
+
+    -- Drop tables (CASCADE drops policies automatically)
+    DROP TABLE IF EXISTS public.clauth_audit CASCADE;
+    DROP TABLE IF EXISTS public.clauth_machines CASCADE;
+    DROP TABLE IF EXISTS public.clauth_services CASCADE;
+
+    -- Drop functions
+    DROP FUNCTION IF EXISTS public.clauth_touch_updated() CASCADE;
+    DROP FUNCTION IF EXISTS public.clauth_upsert_vault_secret(text, text) CASCADE;
+    DROP FUNCTION IF EXISTS public.clauth_get_vault_secret(text) CASCADE;
+    DROP FUNCTION IF EXISTS public.clauth_delete_vault_secret(text) CASCADE;
+  `;
+
+  try {
+    await mgmt(pat, 'POST', `/projects/${ref}/database/query`, { query: teardownSQL });
+    s1.succeed('Database objects dropped (tables, triggers, functions, policies)');
+  } catch (e) {
+    s1.fail(`Database teardown failed: ${e.message}`);
+    console.log(chalk.yellow('  You may need to drop objects manually via SQL editor.'));
+  }
+
+  // ── Step 2: Delete Edge Function ───────────
+  const s2 = ora('Deleting auth-vault Edge Function...').start();
+  try {
+    const res = await fetch(`${MGMT}/projects/${ref}/functions/auth-vault`, {
+      method: 'DELETE',
+      headers: { 'Authorization': `Bearer ${pat}` },
+    });
+    if (res.ok || res.status === 404) {
+      s2.succeed(res.status === 404
+        ? 'Edge Function not found (already deleted)'
+        : 'Edge Function deleted');
+    } else {
+      const text = await res.text().catch(() => res.statusText);
+      throw new Error(`HTTP ${res.status}: ${text}`);
+    }
+  } catch (e) {
+    s2.fail(`Edge Function delete failed: ${e.message}`);
+    console.log(chalk.yellow('  Delete manually: Supabase Dashboard → Edge Functions → auth-vault → Delete'));
+  }
+
+  // ── Step 3: Remove secrets ─────────────────
+  const s3 = ora('Removing clauth secrets...').start();
+  try {
+    // Supabase Management API: DELETE /projects/{ref}/secrets with body listing secret names
+    const res = await fetch(`${MGMT}/projects/${ref}/secrets`, {
+      method: 'DELETE',
+      headers: { 'Authorization': `Bearer ${pat}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(['CLAUTH_HMAC_SALT', 'CLAUTH_ADMIN_BOOTSTRAP_TOKEN']),
+    });
+    if (res.ok) {
+      s3.succeed('Secrets removed (CLAUTH_HMAC_SALT, CLAUTH_ADMIN_BOOTSTRAP_TOKEN)');
+    } else {
+      const text = await res.text().catch(() => res.statusText);
+      throw new Error(`HTTP ${res.status}: ${text}`);
+    }
+  } catch (e) {
+    s3.warn(`Secret removal failed: ${e.message}`);
+    console.log(chalk.yellow('  Remove manually: Supabase → Settings → Edge Functions → Secrets'));
+  }
+
+  // ── Step 4: Remove Claude skill ────────────
+  const s4 = ora('Removing Claude skill...').start();
+  const skillDir = join(SKILLS_DIR, 'clauth');
+  if (existsSync(skillDir)) {
+    try {
+      rmSync(skillDir, { recursive: true, force: true });
+      s4.succeed(`Skill removed: ${skillDir}`);
+    } catch (e) {
+      s4.warn(`Could not remove skill: ${e.message}`);
+    }
+  } else {
+    s4.succeed('Skill directory not found (already removed)');
+  }
+
+  // ── Step 5: Clear local config ─────────────
+  const s5 = ora('Clearing local config...').start();
+  try {
+    config.clear();
+    s5.succeed('Local config cleared');
+  } catch (e) {
+    s5.warn(`Could not clear config: ${e.message}`);
+  }
+
+  // ── Done ───────────────────────────────────
+  console.log('');
+  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+  console.log(chalk.yellow('  ✓ clauth fully uninstalled'));
+  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+  console.log('');
+  console.log(chalk.gray('  To reinstall: npx @lifeaitools/clauth install'));
+  console.log('');
+}

package/cli/index.js

@@ -149,11 +149,41 @@ program
 import { runInstall } from './commands/install.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runScrub } from './commands/scrub.js';
-import { runServe } from './commands/serve.js';
+import { runServe, MCP_TOOLS } from './commands/serve.js';
+import { listPlugins, registerPlugin } from './supervisor-registry.js';
 import { runOps } from './commands/ops.js';
 import { runOpsInstall } from './commands/ops-install.js';
 import { runCodevelop } from './commands/codevelop.js';
 import { runNpm, runPublish } from './commands/npm.js';
+import { runLogin } from './commands/login.js';
+
+// ──────────────────────────────────────────────
+// clauth login <target>
+// THE global login directive — the one sanctioned way to SSH into any
+// clauth-managed box. Never hand-fetch a private key (clauth get <ssh-service>)
+// and hand-roll ssh-agent/ssh yourself; add the box to LOGIN_TARGETS in
+// cli/commands/login.js instead and use this command.
+// ──────────────────────────────────────────────
+program
+  .command('login [target]')
+  .description('SSH into a clauth-managed box by name (e.g. vultr) — run with no target to list them')
+  .option('-c, --command <cmd>', 'Run one command instead of opening an interactive shell')
+  .option('--host <user@host>', 'Override the target\'s default host')
+  .option('--native-windows', 'Human-only: use native Windows OpenSSH instead of Git Bash (blocked for agent sessions)')
+  .addHelpText('after', `
+Examples:
+  clauth login                          List known login targets
+  clauth login vultr                    Interactive shell on the Vultr dev box
+  clauth login vultr -c "pm2 list"      Run one command, non-interactive
+  clauth login vultr --host root@1.2.3.4   Override the default host for this target
+`)
+  .action(async (target, opts) => {
+    await runLogin(target, {
+      command: opts.command,
+      host: opts.host,
+      nativeWindows: opts.nativeWindows,
+    });
+  });
 
 program
   .command('install')
@@ -933,6 +963,77 @@ tunnelCmd
     }
   });
 
+// ──────────────────────────────────────────────
+// clauth mcp list
+// ──────────────────────────────────────────────
+// Known MCP-server plugin ids in the managed fleet. Positive allowlist
+// rather than a naming heuristic (credential-name conventions and health
+// route "kind" vary across these) — dev-center and any future non-MCP
+// pm2-managed surface stay excluded by construction. Deliberately distinct
+// from `clauth list` (vault credential services); this never touches those.
+const MCP_SERVER_PLUGIN_IDS = new Set([
+  "fs-mcp",
+  "web-research",
+  "regen-media",
+  "regen-media-local",
+  "codeflow-mcp",
+  "rdc-skills",
+]);
+
+const mcpCmd = program.command("mcp").description("Inspect clauth's own MCP tool catalog and managed MCP-server surfaces");
+
+mcpCmd
+  .command("list")
+  .description("List clauth's advertised MCP tools and MCP-server surfaces (never vault credential services)")
+  .action(() => {
+    console.log(chalk.cyan(`\n  clauth's own MCP tools (${MCP_TOOLS.length}):\n`));
+    for (const tool of MCP_TOOLS) {
+      console.log(`  ${chalk.white(tool.name)}  ${chalk.gray(tool.description || "")}`);
+    }
+    const mcpPlugins = listPlugins().filter((p) => MCP_SERVER_PLUGIN_IDS.has(p.id));
+    console.log(chalk.cyan(`\n  Managed MCP-server surfaces (${mcpPlugins.length}):\n`));
+    if (!mcpPlugins.length) {
+      console.log(chalk.gray("  none discovered — is the daemon running? clauth serve"));
+    }
+    for (const plugin of mcpPlugins) {
+      const state = plugin.enabled ? plugin.state : "disabled";
+      const icon = state === "current" ? "✓" : state === "disabled" ? "○" : "⚠";
+      console.log(`  ${icon} ${chalk.white(plugin.id)}  ${chalk.gray(state)}`);
+      for (const surface of plugin.surfaces || []) {
+        console.log(`      ${surface.id}  ${chalk.gray(surface.health || surface.routes?.[0]?.url || "no health route")}`);
+      }
+    }
+    console.log("");
+  });
+
+// ──────────────────────────────────────────────
+// clauth plugin register <manifest-path>
+// The self-registration entry point for PLUGIN-ARCHITECTURE-DECISION.md:
+// a product repo's own install/deploy step calls this after its
+// clauth-plugin.json is in place — same role as clauth's own
+// scripts/postinstall.js, for repos that have no npm-install lifecycle
+// hook of their own (monorepo workspace members, not standalone packages).
+// ──────────────────────────────────────────────
+const pluginCmd = program.command('plugin').description("Register and manage clauth-supervised plugin manifests");
+
+pluginCmd
+  .command('register <manifestPath>')
+  .description('Validate a clauth-plugin.json and register it with the local supervisor, then run discovery')
+  .action((manifestPath) => {
+    const resolved = path.resolve(process.cwd(), manifestPath);
+    const receipt = registerPlugin(resolved, 'cli');
+    const ok = receipt.resulting_state?.ok;
+    const state = receipt.resulting_state?.state;
+    if (!ok) {
+      const pluginState = receipt.resulting_state?.plugin_state;
+      const detail = receipt.resulting_state?.error || (pluginState ? `plugin_state=${pluginState}` : 'registration failed');
+      console.error(`  ✗ ${state}: ${detail}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`  ✓ ${chalk.white(receipt.target?.plugin_id || '?')} ${state} — surfaces: ${(receipt.resulting_state?.surfaces || []).join(', ') || 'none'}`);
+  });
+
 // ──────────────────────────────────────────────
 // clauth chitchat --session <id>
 // ──────────────────────────────────────────────

package/cli/supervisor-registry.js

@@ -167,7 +167,26 @@ function normalizeCommand(command, field) {
   const [cmd, ...args] = command;
   if (typeof cmd !== "string" || !cmd.trim()) throw new Error(`${field}[0] is required`);
   if (/[;&|<>]/.test(cmd)) throw new Error(`${field}[0] must be an executable path/name, not shell syntax`);
-  return [cmd, ...args.map(String)];
+  const normalizedArgs = args.map(String);
+  // shell:true (Windows-only, see execute() in runSurfaceAction) hands each
+  // arg to cmd.exe verbatim — a shell metacharacter in an arg is exactly as
+  // exploitable as one in cmd[0]. A legitimate CLI arg for the pm2/node
+  // invocations this schema targets never needs raw shell syntax.
+  for (const [i, arg] of normalizedArgs.entries()) {
+    if (/[;&|<>]/.test(arg)) throw new Error(`${field}[${i + 1}] must not contain shell syntax`);
+  }
+  return [cmd, ...normalizedArgs];
+}
+
+// Quotes a value for cmd.exe /c when shell:true is active and the value
+// contains whitespace — spawnSync does NOT auto-quote in that mode, so an
+// absolute path like "C:\Program Files\nodejs\node.exe" (or any arg with a
+// space) breaks at the first space unless the caller quotes it. Idempotent:
+// an already-quoted value is left as-is rather than double-quoted.
+export function shellQuote(value, useShell) {
+  if (!useShell || !/\s/.test(value)) return value;
+  if (value.startsWith('"') && value.endsWith('"')) return value;
+  return `"${value}"`;
 }
 
 function expandPathToken(value) {
@@ -229,7 +248,7 @@ function localhostHealth(pathOrUrl, port) {
 function normalizeSurface(surface, plugin) {
   if (!surface || typeof surface !== "object") throw new Error("surface must be an object");
   const id = String(surface.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash");
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
   const destination = normalizeDestination(surface.destination || plugin.destination);
   const lifecycle_owner = normalizeLifecycleOwner(surface.lifecycle_owner || plugin.lifecycle_owner);
   const port = surface.port === undefined || surface.port === null || surface.port === "auto" ? surface.port ?? null : Number(surface.port);
@@ -254,7 +273,7 @@ export function validatePluginManifest(manifest, sourcePath = "") {
   if (!manifest || typeof manifest !== "object") throw new Error("manifest must be an object");
   if (manifest.schema !== SCHEMA) throw new Error(`schema must be ${SCHEMA}`);
   const id = String(manifest.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash");
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
   const version = String(manifest.version || "").trim();
   if (!version) throw new Error("version is required");
   const plugin = {
@@ -306,6 +325,17 @@ function findManifestFiles(root) {
   for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     const full = path.join(root, entry.name);
     if (entry.isDirectory()) {
+      // A scoped npm package (@lifeaitools/fs-mcp) installs two levels deep
+      // under node_modules/@scope/pkg-name/ — descend one extra level only
+      // for @scope directories. Unscoped layout (one level) is unchanged.
+      if (entry.name.startsWith("@")) {
+        for (const scopedEntry of fs.readdirSync(full, { withFileTypes: true })) {
+          if (!scopedEntry.isDirectory()) continue;
+          const scopedCandidate = path.join(full, scopedEntry.name, "clauth-plugin.json");
+          if (fs.existsSync(scopedCandidate)) out.push(scopedCandidate);
+        }
+        continue;
+      }
       const candidate = path.join(full, "clauth-plugin.json");
       if (fs.existsSync(candidate)) out.push(candidate);
     } else if (entry.isFile() && entry.name === "clauth-plugin.json") {
@@ -394,6 +424,65 @@ export function discoverPlugins() {
   return { plugins, surfaces, events };
 }
 
+// Registers one plugin manifest into the managed-plugins root, then runs
+// discovery so it's picked up immediately. This is the entry point a product
+// repo's own install/deploy step calls to self-register — the mechanism the
+// PLUGIN-ARCHITECTURE-DECISION.md "each MCP ships its own clauth-plugin.json"
+// model needs for a monorepo workspace member (no npm install lifecycle hook
+// to piggyback on, unlike a standalone published package with postinstall.js).
+// Idempotent: re-registering unchanged content is a safe no-op re-affirm.
+export function registerPlugin(manifestPath, actor = "localhost") {
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, "utf8");
+  } catch (error) {
+    return operation("plugin.register", { manifest_path: manifestPath }, null, {
+      ok: false, state: "manifest_unreadable", error: error instanceof Error ? error.message : String(error),
+    }, actor);
+  }
+  let manifest;
+  try {
+    manifest = validatePluginManifest(JSON.parse(raw), manifestPath);
+  } catch (error) {
+    return operation("plugin.register", { manifest_path: manifestPath }, null, {
+      ok: false, state: "manifest_invalid", error: error instanceof Error ? error.message : String(error),
+    }, actor);
+  }
+  const [{ root: managedRoot }] = rootEntries();
+  const resolvedRoot = path.resolve(managedRoot);
+  const targetDir = path.resolve(managedRoot, manifest.id);
+  // Belt-and-braces: the id regex already rejects traversal-shaped ids, but
+  // this asserts containment at the actual write site so a future regex
+  // relaxation can't silently reopen a path escape out of the managed root —
+  // this is a credential vault writing files from parsed manifest content.
+  if (targetDir !== resolvedRoot && !targetDir.startsWith(resolvedRoot + path.sep)) {
+    return operation("plugin.register", { manifest_path: manifestPath, plugin_id: manifest.id }, null, {
+      ok: false, state: "manifest_invalid", error: "plugin id escapes the managed plugin root",
+    }, actor);
+  }
+  const targetPath = path.join(targetDir, "clauth-plugin.json");
+  const priorRaw = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null;
+  const unchanged = priorRaw !== null && sha256(priorRaw) === sha256(raw);
+  if (!unchanged) {
+    try {
+      fs.mkdirSync(targetDir, { recursive: true });
+      fs.writeFileSync(targetPath, raw, "utf8");
+    } catch (error) {
+      return operation("plugin.register", { manifest_path: manifestPath, plugin_id: manifest.id }, null, {
+        ok: false, state: "write_failed", error: error instanceof Error ? error.message : String(error),
+      }, actor);
+    }
+  }
+  const discovery = discoverPlugins();
+  const registered = discovery.plugins.find((plugin) => plugin.id === manifest.id);
+  return operation("plugin.register", { manifest_path: manifestPath, plugin_id: manifest.id }, null, {
+    ok: Boolean(registered) && registered.state !== "manifest_invalid",
+    state: unchanged ? "unchanged" : "registered",
+    plugin_state: registered?.state || "not_found",
+    surfaces: registered?.surfaces?.map((surface) => surface.id) || [],
+  }, actor);
+}
+
 export function listPlugins() {
   return loadSupervisorState().plugins || [];
 }
@@ -422,7 +511,7 @@ export function readSupervisorEvents(limit = 100) {
   });
 }
 
-function operation(action, target, prior, result, actor = "localhost") {
+export function operation(action, target, prior, result, actor = "localhost") {
   const receipt = {
     operationId: crypto.randomUUID(),
     actor,
@@ -522,10 +611,22 @@ export function runSurfaceAction(id, action, actor = "localhost") {
   }
   const execute = (selectedCommand) => {
     const [cmd, ...args] = selectedCommand;
-    return spawnSync(cmd, args, {
+    const useShell = process.platform === "win32";
+    // With shell:true on Windows, spawnSync hands cmd/args to cmd.exe /c
+    // verbatim and does NOT auto-quote — an absolute path or arg containing
+    // a space (e.g. "C:\Program Files\nodejs\node.exe") breaks at the first
+    // space unless quoted. Bare shim names (pm2, npm) never contain spaces,
+    // so this only ever affects absolute-path values, and only on Windows.
+    const resolvedCmd = shellQuote(cmd, useShell);
+    const resolvedArgs = args.map((arg) => shellQuote(arg, useShell));
+    return spawnSync(resolvedCmd, resolvedArgs, {
       cwd: surface.cwd || undefined,
       env: { ...process.env, CLAUTH_PM2_HOME: getClauthPm2Home(), PM2_HOME: getClauthPm2Home() },
       windowsHide: true,
+      // Windows resolves CLI shims (pm2, npm, etc.) to .cmd files that
+      // spawnSync cannot exec directly without a shell — ENOENT otherwise.
+      // POSIX targets (Vultr/Coolify) need no shell and keep prior behavior.
+      shell: useShell,
       encoding: "utf8",
       timeout: Number(surface.timeoutMs || 30000),
     });