@shadowob/connector 1.1.6 → 1.1.7

package/dist/cli.js

@@ -2,10 +2,12 @@
 
 // src/cli.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { chmodSync as chmodSync2, cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname2, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
+import { parse as parseToml2 } from "smol-toml";
+import { parse as parseYaml2 } from "yaml";
 
 // src/cc-connect-installer.ts
 import { execFileSync, spawnSync } from "child_process";
@@ -249,6 +251,15 @@ function binaryLooksUsable(path) {
     return false;
   }
 }
+function getCcConnectBinaryStatus() {
+  const override = process.env.SHADOW_CC_CONNECT_BIN?.trim();
+  if (override) {
+    const binaryPath2 = expandHome(override);
+    return { binaryPath: binaryPath2, usable: binaryLooksUsable(binaryPath2), source: "env" };
+  }
+  const binaryPath = cachedBinaryPath();
+  return { binaryPath, usable: binaryLooksUsable(binaryPath), source: "cache" };
+}
 async function ensureCcConnectFork(options) {
   const override = process.env.SHADOW_CC_CONNECT_BIN?.trim();
   if (override) {
@@ -522,7 +533,7 @@ function buildOpenClawPlan(input) {
   return {
     target: "openclaw",
     title: "OpenClaw",
-    summary: "Install the Shadow channel plugin and bind this Buddy token to OpenClaw.",
+    summary: "Install the Shadow channel plugin, Shadow CLI bin/skills, and a Buddy CLI profile for OpenClaw.",
     connectCommand,
     quickCommand,
     commands,
@@ -533,6 +544,9 @@ function buildOpenClawPlan(input) {
       `Shadow server URL: ${serverUrl}`,
       `Buddy token: ${token}`,
       "",
+      `Preferred one-line setup: ${connectCommand}`,
+      "The connector installs/configures the Shadow CLI, official Shadow skill files, and the Buddy profile before applying the OpenClaw channel config.",
+      "",
       "Run these steps in order:",
       ...commands.map((item, index) => `${index + 1}. ${item.command}`),
       "",
@@ -617,7 +631,7 @@ function buildHermesPlan(input) {
   return {
     target: "hermes",
     title: "Hermes Agent",
-    summary: "Install the ShadowOB Hermes platform plugin and run Hermes gateway for this Buddy.",
+    summary: "Install the ShadowOB Hermes platform plugin, Shadow CLI bin/skills, and a Buddy CLI profile.",
     connectCommand,
     quickCommand: commands.map((item) => item.command).join(" && "),
     commands,
@@ -631,7 +645,8 @@ function buildHermesPlan(input) {
       `Shadow server URL: ${serverUrl}`,
       `Buddy token: ${token}`,
       "",
-      "Install the bundled ShadowOB platform plugin, write the environment values above, enable the plugin, then run hermes gateway. The plugin resolves the Buddy agent id and channel policy from Shadow at runtime."
+      `Preferred one-line setup: ${connectCommand}`,
+      "The connector installs/configures the Shadow CLI, official Shadow skill files, and the Buddy profile before writing Hermes config. The plugin resolves the Buddy agent id and channel policy from Shadow at runtime."
     ].join("\n"),
     docsUrl: "https://hermes-agent.nousresearch.com/docs/user-guide/messaging",
     capabilities: [
@@ -709,7 +724,7 @@ function buildCcConnectPlan(input) {
   return {
     target: "cc-connect",
     title: "cc-connect",
-    summary: `Use ${CC_CONNECT_FORK_REPO}@${CC_CONNECT_FORK_SHORT_REF} with ShadowOB Socket.IO platform support for this Buddy token.`,
+    summary: `Use ${CC_CONNECT_FORK_REPO}@${CC_CONNECT_FORK_SHORT_REF} with ShadowOB Socket.IO support, Shadow CLI bin/skills, and a Buddy CLI profile.`,
     connectCommand: startCommand,
     quickCommand: startCommand,
     commands,
@@ -722,7 +737,8 @@ function buildCcConnectPlan(input) {
       `Project work_dir: ${workDir}`,
       `Agent type: ${agentType}`,
       "",
-      `Install ${CC_CONNECT_FORK_REPO}@${CC_CONNECT_FORK_SHORT_REF}, add the TOML platform block, and start cc-connect.`
+      `Preferred one-line setup: ${startCommand}`,
+      `Install ${CC_CONNECT_FORK_REPO}@${CC_CONNECT_FORK_SHORT_REF}, install/configure the Shadow CLI and official Shadow skill files, add the TOML platform block, and start cc-connect.`
     ].join("\n"),
     docsUrl: CC_CONNECT_FORK_DOCS_URL,
     capabilities: [
@@ -752,6 +768,10 @@ function createConnectorPlan(input) {
 
 // src/cli.ts
 var TARGETS = /* @__PURE__ */ new Set(["openclaw", "hermes", "cc-connect"]);
+var COMMANDS = /* @__PURE__ */ new Set(["plan", "connect", "update", "doctor", "fix", "status", "scan"]);
+var ALL_TARGETS = ["openclaw", "hermes", "cc-connect"];
+var SHADOW_CLI_PACKAGE = "@shadowob/cli@latest";
+var SHADOW_CONNECTOR_PACKAGE = "@shadowob/connector@latest";
 function readOption(args, name) {
   const prefix = `${name}=`;
   const inline = args.find((arg) => arg.startsWith(prefix));
@@ -768,8 +788,14 @@ function usage() {
     "Usage:",
     "  shadowob-connector plan --target <openclaw|hermes|cc-connect> --server-url <url> --token <token>",
     "  shadowob-connector connect --target <openclaw|hermes|cc-connect> --server-url <url> --token <token>",
+    "  shadowob-connector update --target <openclaw|hermes|cc-connect> --server-url <url> --token <token>",
+    "  shadowob-connector fix --target <openclaw|hermes|cc-connect> --server-url <url> --token <token>",
+    "  shadowob-connector scan [--target <openclaw|hermes|cc-connect>] [--server-url <url>] [--token <token>]",
+    "  shadowob-connector doctor [--target <openclaw|hermes|cc-connect>]",
+    "  shadowob-connector status [--target <openclaw|hermes|cc-connect>]",
     "",
     "Options:",
+    "  --server-url <url>      Shadow server URL, default https://shadowob.com",
     "  --openclaw-config <path> OpenClaw JSON config, default $OPENCLAW_CONFIG or ~/.shadowob/openclaw.json",
     "  --hermes-home <path>    Hermes config directory, default $HERMES_HOME or ~/.hermes",
     "  --work-dir <path>       cc-connect project work directory",
@@ -777,25 +803,33 @@ function usage() {
     "  --agent-type <type>     cc-connect agent type, default codex",
     "  --json                  Print the full plan as JSON",
     "  --force                 Overwrite target config files when needed",
-    "  --install               Install the ShadowOB cc-connect fork when target is cc-connect",
-    "  --no-install            Skip Hermes dependency install and plugin enablement",
+    "  --install               Install connector runtime dependencies",
+    "  --no-install            Skip connector runtime dependency installation",
     "  --start                 Start Hermes gateway or cc-connect after setup",
     "  --dry-run               Show what would be applied without changing files"
   ].join("\n");
 }
+function requireTarget(options) {
+  if (!options.target) throw new Error("Missing or invalid --target");
+  return options.target;
+}
 function parseArgs(args) {
   if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
     console.log(usage());
     process.exit(0);
   }
   const commandArg = args[0];
-  const command = commandArg === "connect" || commandArg === "plan" ? commandArg : "plan";
-  const optionArgs = command === "plan" ? args.filter((arg) => arg !== "plan") : args.slice(1);
+  const hasCommand = commandArg ? COMMANDS.has(commandArg) : false;
+  const command = hasCommand ? commandArg : "plan";
+  const optionArgs = hasCommand ? args.slice(1) : args;
   const target = readOption(optionArgs, "--target");
-  if (!target || !TARGETS.has(target)) {
+  if (target && !TARGETS.has(target)) {
+    throw new Error("Missing or invalid --target");
+  }
+  if (!target && command !== "doctor" && command !== "status" && command !== "scan") {
     throw new Error("Missing or invalid --target");
   }
-  const install = target === "cc-connect" ? hasFlag(optionArgs, "--install") : !hasFlag(optionArgs, "--no-install");
+  const install = command === "fix" || command === "update" ? !hasFlag(optionArgs, "--no-install") : target === "cc-connect" ? hasFlag(optionArgs, "--install") : !hasFlag(optionArgs, "--no-install");
   return {
     command,
     target,
@@ -814,7 +848,8 @@ function parseArgs(args) {
   };
 }
 function printPlan(options) {
-  const plan = createConnectorPlan(options);
+  const target = requireTarget(options);
+  const plan = createConnectorPlan({ ...options, target });
   if (options.json) {
     console.log(JSON.stringify(plan, null, 2));
     return;
@@ -873,6 +908,570 @@ function normalizeServerUrl2(value) {
   const trimmed = value.trim() || "https://shadowob.com";
   return trimmed.endsWith("/api") ? trimmed.slice(0, -4) : trimmed.replace(/\/$/, "");
 }
+function shellQuote2(value) {
+  if (!value) return "''";
+  if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function tokenForCommand(options) {
+  return options.token.trim() || "<BUDDY_TOKEN>";
+}
+function connectorCommand(command, target, options, extras = []) {
+  const parts = ["shadowob-connector", command, "--target", target];
+  if (command !== "doctor" && command !== "status") {
+    parts.push(
+      "--server-url",
+      normalizeServerUrl2(options.serverUrl),
+      "--token",
+      tokenForCommand(options)
+    );
+  }
+  parts.push(...extras);
+  return parts.map(shellQuote2).join(" ");
+}
+function commandExists(command) {
+  const result = spawnSync2(command, ["--version"], { stdio: "ignore" });
+  return result.status === 0;
+}
+function writeExecutable(path, content, dryRun) {
+  writeFile(path, content, dryRun);
+  if (dryRun) return;
+  chmodSync2(path, 493);
+}
+function ensureNpxShim(options) {
+  if (commandExists(options.command)) return;
+  const localBin = resolve2(homedir2(), ".local/bin");
+  const target = resolve2(localBin, options.command);
+  const content = [
+    "#!/usr/bin/env sh",
+    `exec npx -y ${options.packageSpec} ${options.binaryName === options.command ? "" : options.binaryName} "$@"`,
+    ""
+  ].join("\n").replace('  "$@"', ' "$@"');
+  console.log(`Applying: Install ${options.command} shim ${target}`);
+  writeExecutable(target, content, options.dryRun);
+  const pathEntries = (process.env.PATH ?? "").split(":");
+  if (!pathEntries.includes(localBin)) {
+    console.log(`Note: add ${localBin} to PATH so agents can run ${options.command}`);
+  }
+}
+function shadowCliProfileName(options) {
+  return options.projectName?.trim() || "shadow-buddy";
+}
+function writeShadowCliProfile(options) {
+  const configPath = resolve2(homedir2(), ".shadowob/shadowob.config.json");
+  const current = (() => {
+    try {
+      return JSON.parse(readExisting(configPath));
+    } catch {
+      return {};
+    }
+  })();
+  const profileName = shadowCliProfileName(options);
+  const next = {
+    ...current,
+    profiles: {
+      ...current.profiles ?? {},
+      [profileName]: {
+        serverUrl: normalizeServerUrl2(options.serverUrl),
+        token: options.token
+      }
+    },
+    currentProfile: profileName
+  };
+  console.log(`Applying: Configure Shadow CLI profile ${profileName}`);
+  writeFile(configPath, JSON.stringify(next, null, 2), options.dryRun);
+}
+function shadowobSkillMarkdown() {
+  const candidates = [
+    resolve2(packageRoot(), "skills/shadowob/SKILL.md"),
+    resolve2(process.cwd(), "skills/shadowob-cli/SKILL.md"),
+    resolve2(process.cwd(), "packages/openclaw-shadowob/skills/shadowob/SKILL.md")
+  ];
+  let currentDir = packageRoot();
+  while (true) {
+    candidates.push(resolve2(currentDir, "skills/shadowob-cli/SKILL.md"));
+    const parentDir = dirname2(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+  const found = candidates.find((candidate) => existsSync2(candidate));
+  if (!found) throw new Error("Cannot find bundled Shadow CLI skill");
+  return readFileSync(found, "utf8");
+}
+function shadowobSkillTargets(options) {
+  const hermesDir = expandHome2(options.hermesHome ?? process.env.HERMES_HOME ?? "~/.hermes");
+  return Array.from(
+    /* @__PURE__ */ new Set([
+      resolve2(homedir2(), ".shadowob/skills/shadowob/SKILL.md"),
+      resolve2(homedir2(), ".agents/skills/shadowob/SKILL.md"),
+      resolve2(homedir2(), ".codex/skills/shadowob/SKILL.md"),
+      resolve2(homedir2(), ".claude/skills/shadowob/SKILL.md"),
+      resolve2(homedir2(), ".gemini/skills/shadowob/SKILL.md"),
+      resolve2(homedir2(), ".opencode/skills/shadowob/SKILL.md"),
+      resolve2(homedir2(), ".openclaw/skills/shadowob/SKILL.md"),
+      resolve2(hermesDir, "skills/shadowob/SKILL.md")
+    ])
+  );
+}
+function installShadowCliAndSkills(options) {
+  ensureNpxShim({
+    command: "shadowob",
+    packageSpec: SHADOW_CLI_PACKAGE,
+    binaryName: "shadowob",
+    dryRun: options.dryRun
+  });
+  ensureNpxShim({
+    command: "shadowob-connector",
+    packageSpec: SHADOW_CONNECTOR_PACKAGE,
+    binaryName: "shadowob-connector",
+    dryRun: options.dryRun
+  });
+  const skill = shadowobSkillMarkdown();
+  for (const target of shadowobSkillTargets(options)) {
+    console.log(`Applying: Install Shadow skill ${target}`);
+    writeFile(target, skill, options.dryRun);
+  }
+  writeShadowCliProfile(options);
+}
+function check(target, status, label, detail, fix) {
+  return { target, status, label, detail, fix };
+}
+function selectedTargets(options) {
+  return options.target ? [options.target] : [...ALL_TARGETS];
+}
+function parseJsonFile(path, label) {
+  try {
+    const content = readExisting(path);
+    if (!content.trim()) return { error: `${label} config is empty` };
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { error: `${label} config must be an object` };
+    }
+    return { value: parsed };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function diagnoseCommon(options) {
+  const checks = [
+    check(
+      "common",
+      commandExists("shadowob") ? "ok" : "warn",
+      "Shadow CLI command",
+      commandExists("shadowob") ? "shadowob is on PATH" : "shadowob is not on PATH",
+      "Run fix/update to install the ~/.local/bin/shadowob shim."
+    ),
+    check(
+      "common",
+      commandExists("shadowob-connector") ? "ok" : "warn",
+      "Connector command",
+      commandExists("shadowob-connector") ? "shadowob-connector is on PATH" : "shadowob-connector is not on PATH",
+      "Run fix/update to install the ~/.local/bin/shadowob-connector shim."
+    )
+  ];
+  const profilePath = resolve2(homedir2(), ".shadowob/shadowob.config.json");
+  if (!existsSync2(profilePath)) {
+    checks.push(
+      check(
+        "common",
+        "warn",
+        "Shadow CLI profile",
+        `${profilePath} does not exist`,
+        "Run fix/update with --token to write the Buddy profile."
+      )
+    );
+  } else {
+    const parsed = parseJsonFile(profilePath, "Shadow CLI");
+    const profiles = asObject(parsed.value?.profiles);
+    const profileName = shadowCliProfileName(options);
+    checks.push(
+      check(
+        "common",
+        parsed.error ? "fail" : profiles[profileName] ? "ok" : "warn",
+        "Shadow CLI profile",
+        parsed.error ?? (profiles[profileName] ? `profile ${profileName} exists` : `profile ${profileName} is missing`),
+        "Run fix/update with --token to write the Buddy profile."
+      )
+    );
+  }
+  const skillTargets = shadowobSkillTargets(options);
+  const installed = skillTargets.filter((target) => existsSync2(target)).length;
+  checks.push(
+    check(
+      "common",
+      installed > 0 ? "ok" : "warn",
+      "Shadow skill files",
+      `${installed}/${skillTargets.length} common skill locations contain shadowob/SKILL.md`,
+      "Run fix/update to install the official Shadow skill files."
+    )
+  );
+  return checks;
+}
+function diagnoseOpenClaw(options) {
+  const configPath = expandHome2(
+    options.openclawConfig ?? process.env.OPENCLAW_CONFIG ?? "~/.shadowob/openclaw.json"
+  );
+  const checks = [
+    check(
+      "openclaw",
+      commandExists("openclaw") ? "ok" : "warn",
+      "OpenClaw command",
+      commandExists("openclaw") ? "openclaw is on PATH" : "openclaw is not on PATH",
+      "Install OpenClaw before starting the gateway."
+    )
+  ];
+  if (!existsSync2(configPath)) {
+    checks.push(
+      check(
+        "openclaw",
+        "fail",
+        "OpenClaw config",
+        `${configPath} does not exist`,
+        "Run fix/update."
+      )
+    );
+    return checks;
+  }
+  const parsed = parseJsonFile(configPath, "OpenClaw");
+  if (parsed.error) {
+    checks.push(
+      check(
+        "openclaw",
+        "fail",
+        "OpenClaw config",
+        parsed.error,
+        "Fix the JSON or run fix/update with --force."
+      )
+    );
+    return checks;
+  }
+  const root = parsed.value ?? {};
+  const channels = asObject(root.channels);
+  const shadow = asObject(channels.shadowob);
+  const plugins = asObject(root.plugins);
+  const pluginEntries = asObject(plugins.entries);
+  checks.push(
+    check(
+      "openclaw",
+      typeof shadow.token === "string" && shadow.token.length > 0 ? "ok" : "fail",
+      "OpenClaw Shadow token",
+      typeof shadow.token === "string" && shadow.token.length > 0 ? "channels.shadowob.token is set" : "channels.shadowob.token is missing",
+      "Run fix/update with --token."
+    ),
+    check(
+      "openclaw",
+      typeof shadow.serverUrl === "string" && shadow.serverUrl.length > 0 ? "ok" : "fail",
+      "OpenClaw Shadow server URL",
+      typeof shadow.serverUrl === "string" && shadow.serverUrl.length > 0 ? `channels.shadowob.serverUrl=${shadow.serverUrl}` : "channels.shadowob.serverUrl is missing",
+      "Run fix/update with --server-url."
+    ),
+    check(
+      "openclaw",
+      asObject(pluginEntries["openclaw-shadowob"]).enabled === true ? "ok" : "warn",
+      "OpenClaw Shadow plugin entry",
+      asObject(pluginEntries["openclaw-shadowob"]).enabled === true ? "openclaw-shadowob plugin entry is enabled" : "openclaw-shadowob plugin entry is missing or disabled",
+      "Run fix/update."
+    )
+  );
+  return checks;
+}
+function diagnoseHermes(options) {
+  const hermesDir = expandHome2(options.hermesHome ?? process.env.HERMES_HOME ?? "~/.hermes");
+  const pluginTarget = resolve2(hermesDir, "plugins/shadowob");
+  const envPath = resolve2(hermesDir, ".env");
+  const configPath = resolve2(hermesDir, "config.yaml");
+  const checks = [
+    check(
+      "hermes",
+      commandExists("hermes") ? "ok" : "warn",
+      "Hermes command",
+      commandExists("hermes") ? "hermes is on PATH" : "hermes is not on PATH",
+      "Install Hermes before starting the gateway."
+    ),
+    check(
+      "hermes",
+      existsSync2(pluginTarget) ? "ok" : "fail",
+      "Hermes Shadow plugin",
+      existsSync2(pluginTarget) ? `${pluginTarget} exists` : `${pluginTarget} is missing`,
+      "Run fix/update."
+    )
+  ];
+  const env = readExisting(envPath);
+  checks.push(
+    check(
+      "hermes",
+      env.includes("SHADOW_TOKEN=") && env.includes("SHADOW_BASE_URL=") ? "ok" : "fail",
+      "Hermes environment",
+      existsSync2(envPath) ? "SHADOW_TOKEN and SHADOW_BASE_URL are present" : `${envPath} does not exist`,
+      "Run fix/update with --token and --server-url."
+    )
+  );
+  if (!existsSync2(configPath)) {
+    checks.push(
+      check("hermes", "fail", "Hermes config", `${configPath} does not exist`, "Run fix/update.")
+    );
+    return checks;
+  }
+  try {
+    const parsed = parseYaml2(readExisting(configPath));
+    const root = asObject(parsed);
+    const shadow = asObject(asObject(root.platforms).shadowob);
+    checks.push(
+      check(
+        "hermes",
+        shadow.enabled === true && typeof shadow.token === "string" ? "ok" : "fail",
+        "Hermes Shadow platform",
+        shadow.enabled === true && typeof shadow.token === "string" ? "platforms.shadowob is enabled" : "platforms.shadowob is missing token or enabled=true",
+        "Run fix/update."
+      )
+    );
+  } catch (error) {
+    checks.push(
+      check(
+        "hermes",
+        "fail",
+        "Hermes config",
+        error instanceof Error ? error.message : String(error),
+        "Fix the YAML or run fix/update with --force."
+      )
+    );
+  }
+  return checks;
+}
+function diagnoseCcConnect(options) {
+  const configPath = resolve2(homedir2(), ".cc-connect/config.toml");
+  const binary = getCcConnectBinaryStatus();
+  const checks = [
+    check(
+      "cc-connect",
+      binary.usable ? "ok" : "warn",
+      "cc-connect Shadow fork",
+      binary.usable ? `${binary.binaryPath} passes version check` : `${binary.binaryPath} is missing or does not match the pinned Shadow fork`,
+      "Run fix/update with --install."
+    )
+  ];
+  if (!existsSync2(configPath)) {
+    checks.push(
+      check(
+        "cc-connect",
+        "fail",
+        "cc-connect config",
+        `${configPath} does not exist`,
+        "Run fix/update."
+      )
+    );
+    return checks;
+  }
+  try {
+    const root = parseToml2(readExisting(configPath));
+    const projects = Array.isArray(root.projects) ? root.projects : [];
+    const projectName = options.projectName?.trim() || "shadow-buddy";
+    const workDir = options.workDir?.trim() || ".";
+    const project = projects.find((item) => asObject(item).name === projectName) ?? projects.find((item) => asObject(asObject(asObject(item).agent).options).work_dir === workDir);
+    const projectPlatforms = asObject(project).platforms;
+    const platforms = Array.isArray(projectPlatforms) ? projectPlatforms : [];
+    const shadow = platforms.find((item) => asObject(item).type === "shadowob");
+    const shadowOptions = asObject(asObject(shadow).options);
+    checks.push(
+      check(
+        "cc-connect",
+        project ? "ok" : "fail",
+        "cc-connect project",
+        project ? `project ${projectName} is configured` : `project ${projectName} is missing`,
+        "Run fix/update with --project-name and --work-dir."
+      ),
+      check(
+        "cc-connect",
+        typeof shadowOptions.token === "string" && typeof shadowOptions.server_url === "string" ? "ok" : "fail",
+        "cc-connect Shadow platform",
+        typeof shadowOptions.token === "string" && typeof shadowOptions.server_url === "string" ? "shadowob platform has token and server_url" : "shadowob platform is missing token or server_url",
+        "Run fix/update with --token and --server-url."
+      )
+    );
+  } catch (error) {
+    checks.push(
+      check(
+        "cc-connect",
+        "fail",
+        "cc-connect config",
+        error instanceof Error ? error.message : String(error),
+        "Fix the TOML or run fix/update with --force."
+      )
+    );
+  }
+  return checks;
+}
+function diagnostics(options) {
+  const checks = diagnoseCommon(options);
+  for (const target of selectedTargets(options)) {
+    if (target === "openclaw") checks.push(...diagnoseOpenClaw(options));
+    if (target === "hermes") checks.push(...diagnoseHermes(options));
+    if (target === "cc-connect") checks.push(...diagnoseCcConnect(options));
+  }
+  return checks;
+}
+function printDiagnostics(options, mode) {
+  const checks = diagnostics(options);
+  if (options.json) {
+    console.log(
+      JSON.stringify({ ok: !checks.some((item) => item.status === "fail"), checks }, null, 2)
+    );
+    return !checks.some((item) => item.status === "fail");
+  }
+  console.log(`# Connector ${mode}`);
+  for (const item of checks) {
+    const marker = item.status === "ok" ? "OK" : item.status === "warn" ? "WARN" : "FAIL";
+    console.log(
+      `[${marker}] ${item.target}: ${item.label}${item.detail ? ` - ${item.detail}` : ""}`
+    );
+    if (mode === "doctor" && item.status !== "ok" && item.fix) {
+      console.log(`       fix: ${item.fix}`);
+    }
+  }
+  return !checks.some((item) => item.status === "fail");
+}
+function firstExistingPath(paths) {
+  return paths.find((path) => existsSync2(path));
+}
+function openClawConfigCandidates(options) {
+  return Array.from(
+    new Set(
+      [
+        options.openclawConfig,
+        process.env.OPENCLAW_CONFIG,
+        process.env.OPENCLAW_CONFIG_PATH,
+        "~/.shadowob/openclaw.json",
+        "~/.openclaw/openclaw.json"
+      ].filter((value) => !!value?.trim()).map(expandHome2)
+    )
+  );
+}
+function ccConnectScanExtras(options) {
+  const configPath = resolve2(homedir2(), ".cc-connect/config.toml");
+  const fallback = [
+    "--work-dir",
+    options.workDir?.trim() || ".",
+    "--project-name",
+    options.projectName?.trim() || "shadow-buddy",
+    "--agent-type",
+    options.agentType?.trim() || "codex"
+  ];
+  if (!existsSync2(configPath)) return fallback;
+  try {
+    const root = parseToml2(readExisting(configPath));
+    const projects = Array.isArray(root.projects) ? root.projects : [];
+    const configuredProject = projects.find((project2) => {
+      const platformsValue = asObject(project2).platforms;
+      const platforms = Array.isArray(platformsValue) ? platformsValue : [];
+      return platforms.some((platform) => asObject(platform).type === "shadowob");
+    }) ?? projects[0];
+    const project = asObject(configuredProject);
+    const agent = asObject(project.agent);
+    const agentOptions = asObject(agent.options);
+    return [
+      "--work-dir",
+      options.workDir?.trim() || (typeof agentOptions.work_dir === "string" ? agentOptions.work_dir : "."),
+      "--project-name",
+      options.projectName?.trim() || (typeof project.name === "string" ? project.name : "shadow-buddy"),
+      "--agent-type",
+      options.agentType?.trim() || (typeof agent.type === "string" ? agent.type : "codex")
+    ];
+  } catch {
+    return fallback;
+  }
+}
+function scanOpenClaw(options) {
+  const configPath = firstExistingPath(openClawConfigCandidates(options));
+  const evidence = [];
+  if (commandExists("openclaw")) evidence.push("openclaw command is on PATH");
+  if (configPath) evidence.push(`config found at ${configPath}`);
+  const detected = evidence.length > 0;
+  return {
+    target: "openclaw",
+    detected,
+    evidence,
+    configPath,
+    connectCommand: connectorCommand("connect", "openclaw", options),
+    updateCommand: connectorCommand("update", "openclaw", options),
+    doctorCommand: connectorCommand("doctor", "openclaw", options),
+    statusCommand: connectorCommand("status", "openclaw", options)
+  };
+}
+function scanHermes(options) {
+  const hermesDir = expandHome2(options.hermesHome ?? process.env.HERMES_HOME ?? "~/.hermes");
+  const configPath = resolve2(hermesDir, "config.yaml");
+  const evidence = [];
+  if (commandExists("hermes")) evidence.push("hermes command is on PATH");
+  if (existsSync2(configPath)) evidence.push(`config found at ${configPath}`);
+  if (existsSync2(resolve2(hermesDir, "plugins/shadowob"))) {
+    evidence.push(`shadowob plugin found under ${resolve2(hermesDir, "plugins/shadowob")}`);
+  }
+  return {
+    target: "hermes",
+    detected: evidence.length > 0,
+    evidence,
+    configPath: existsSync2(configPath) ? configPath : void 0,
+    connectCommand: connectorCommand("connect", "hermes", options),
+    updateCommand: connectorCommand("update", "hermes", options),
+    doctorCommand: connectorCommand("doctor", "hermes", options),
+    statusCommand: connectorCommand("status", "hermes", options)
+  };
+}
+function scanCcConnect(options) {
+  const configPath = resolve2(homedir2(), ".cc-connect/config.toml");
+  const binary = getCcConnectBinaryStatus();
+  const evidence = [];
+  if (commandExists("cc-connect")) evidence.push("cc-connect command is on PATH");
+  if (binary.usable) evidence.push(`Shadow fork binary found at ${binary.binaryPath}`);
+  if (existsSync2(configPath)) evidence.push(`config found at ${configPath}`);
+  const extras = ccConnectScanExtras(options);
+  return {
+    target: "cc-connect",
+    detected: evidence.length > 0,
+    evidence,
+    configPath: existsSync2(configPath) ? configPath : void 0,
+    connectCommand: connectorCommand("connect", "cc-connect", options, extras),
+    updateCommand: connectorCommand("update", "cc-connect", options, extras),
+    doctorCommand: connectorCommand("doctor", "cc-connect", options),
+    statusCommand: connectorCommand("status", "cc-connect", options)
+  };
+}
+function scanConnectors(options) {
+  return selectedTargets(options).map((target) => {
+    if (target === "openclaw") return scanOpenClaw(options);
+    if (target === "hermes") return scanHermes(options);
+    return scanCcConnect(options);
+  });
+}
+function printScan(options) {
+  const results = scanConnectors(options);
+  if (options.json) {
+    console.log(
+      JSON.stringify({ serverUrl: normalizeServerUrl2(options.serverUrl), results }, null, 2)
+    );
+    return;
+  }
+  console.log("# Connector scan");
+  console.log(`Shadow server URL: ${normalizeServerUrl2(options.serverUrl)}`);
+  console.log(`Buddy token: ${options.token.trim() ? "provided" : "<BUDDY_TOKEN>"}`);
+  for (const result of results) {
+    console.log("");
+    console.log(`## ${result.target}`);
+    console.log(`Detected: ${result.detected ? "yes" : "no"}`);
+    if (result.evidence.length > 0) {
+      console.log("Evidence:");
+      for (const item of result.evidence) console.log(`- ${item}`);
+    }
+    console.log("Connection instructions:");
+    console.log(`- connect: ${result.connectCommand}`);
+    console.log(`- update: ${result.updateCommand}`);
+    console.log(`- doctor: ${result.doctorCommand}`);
+    console.log(`- status: ${result.statusCommand}`);
+  }
+}
 function hermesPluginSource() {
   const candidates = [
     resolve2(packageRoot(), "hermes-shadowob-plugin"),
@@ -882,33 +1481,39 @@ function hermesPluginSource() {
   if (!found) throw new Error("Cannot find bundled hermes-shadowob-plugin directory");
   return found;
 }
-function applyOpenClaw(options) {
-  const plan = createConnectorPlan(options);
+function applyOpenClaw(options, behavior = { restart: true }) {
+  const target = requireTarget(options);
+  const plan = createConnectorPlan({ ...options, target });
   const configPath = expandHome2(
     options.openclawConfig ?? process.env.OPENCLAW_CONFIG ?? "~/.shadowob/openclaw.json"
   );
-  console.log("Applying: Install plugin");
-  runShell("openclaw plugins install @shadowob/openclaw-shadowob", options.dryRun);
+  installShadowCliAndSkills(options);
   console.log(`Applying: Merge OpenClaw config ${configPath}`);
   const next = mergeOpenClawConfigContent(readExisting(configPath), {
     token: options.token,
     serverUrl: normalizeServerUrl2(options.serverUrl)
   });
   writeFile(configPath, next, options.dryRun);
+  if (options.install) {
+    console.log("Applying: Install plugin");
+    runShell("openclaw plugins install @shadowob/openclaw-shadowob", options.dryRun);
+  }
   const restart = plan.commands.find((step) => step.label === "Restart gateway");
-  if (restart) {
+  if (restart && behavior.restart) {
     console.log(`Applying: ${restart.label}`);
     runShell(restart.command, options.dryRun);
   }
 }
 function applyHermes(options) {
-  const plan = createConnectorPlan(options);
+  const target = requireTarget(options);
+  const plan = createConnectorPlan({ ...options, target });
   const hermesDir = expandHome2(options.hermesHome ?? process.env.HERMES_HOME ?? "~/.hermes");
   const pluginTarget = resolve2(hermesDir, "plugins/shadowob");
   const envPath = resolve2(hermesDir, ".env");
   const configPath = resolve2(hermesDir, "config.yaml");
   const envBlock = plan.configBlocks.find((block) => block.label === "~/.hermes/.env");
   if (!envBlock) throw new Error("Hermes plan is missing config blocks");
+  installShadowCliAndSkills(options);
   if (options.dryRun) {
     console.log(`[dry-run] copy ${hermesPluginSource()} -> ${pluginTarget}`);
   } else {
@@ -937,9 +1542,11 @@ function applyHermes(options) {
   }
 }
 async function applyCcConnect(options) {
-  const plan = createConnectorPlan(options);
+  const target = requireTarget(options);
+  const plan = createConnectorPlan({ ...options, target });
   const configBlock = plan.configBlocks.find((block) => block.label === "~/.cc-connect/config.toml");
   if (!configBlock) throw new Error("cc-connect plan is missing config block");
+  installShadowCliAndSkills(options);
   const configPath = resolve2(homedir2(), ".cc-connect/config.toml");
   const nextConfig = options.force ? configBlock.content : mergeCcConnectConfigContent(readExisting(configPath), {
     token: options.token,
@@ -963,20 +1570,41 @@ async function applyCcConnect(options) {
   }
 }
 async function connect(options) {
-  if (options.target === "openclaw") {
+  const target = requireTarget(options);
+  if (target === "openclaw") {
     applyOpenClaw(options);
     return;
   }
-  if (options.target === "hermes") {
+  if (target === "hermes") {
     applyHermes(options);
     return;
   }
   await applyCcConnect(options);
 }
+async function repair(options, mode) {
+  const target = requireTarget(options);
+  console.log(`Applying: ${mode} ${target} connector`);
+  if (target === "openclaw") {
+    applyOpenClaw(options, { restart: options.start });
+    return;
+  }
+  if (target === "hermes") {
+    applyHermes({ ...options, start: options.start });
+    return;
+  }
+  await applyCcConnect({ ...options, start: options.start });
+}
 async function main() {
   const options = parseArgs(process.argv.slice(2));
   if (options.command === "connect") {
     await connect(options);
+  } else if (options.command === "fix" || options.command === "update") {
+    await repair(options, options.command);
+  } else if (options.command === "doctor" || options.command === "status") {
+    const ok = printDiagnostics(options, options.command);
+    if (options.command === "doctor" && !ok) process.exitCode = 1;
+  } else if (options.command === "scan") {
+    printScan(options);
   } else {
     printPlan(options);
   }