@shadowob/connector 1.1.3-dev.251

package/README.md

@@ -0,0 +1,157 @@
+# Shadow Connector
+
+Connection helpers for attaching a Shadow Buddy token to OpenClaw, Hermes Agent, or cc-connect.
+
+The package exports pure plan builders for app UIs and a `shadowob-connector` CLI for terminal setup.
+
+## CLI
+
+Print a plan:
+
+```bash
+npx @shadowob/connector@latest plan \
+  --target openclaw \
+  --server-url https://shadowob.com \
+  --token buddy-token
+```
+
+Apply a connector setup:
+
+```bash
+npx @shadowob/connector@latest connect \
+  --target hermes \
+  --server-url https://shadowob.com \
+  --token buddy-token
+```
+
+Use `--dry-run` to preview writes and commands. Use `--json` with `plan` when embedding the plan in another tool.
+
+## OpenClaw
+
+```bash
+npx @shadowob/connector@latest connect \
+  --target openclaw \
+  --server-url https://shadowob.com \
+  --token buddy-token
+```
+
+Equivalent manual steps:
+
+```bash
+openclaw plugins install @shadowob/openclaw-shadowob
+openclaw config set channels.shadowob.token 'buddy-token'
+openclaw config set channels.shadowob.serverUrl 'https://shadowob.com'
+openclaw gateway restart
+```
+
+OpenClaw resolves the Buddy identity from the token and pulls channel policy dynamically from Shadow.
+
+## Hermes Agent
+
+```bash
+npx @shadowob/connector@latest connect \
+  --target hermes \
+  --server-url https://shadowob.com \
+  --token buddy-token
+```
+
+The Hermes plugin is bundled in `hermes-shadowob-plugin/`. The connector copies it to `~/.hermes/plugins/shadowob`, writes the Shadow token/base URL, and enables the plugin.
+
+Hermes does not need `agentId` or `channelId` in the setup command. The plugin calls `/api/auth/me` to resolve the Buddy agent id, then `/api/agents/:id/config` to receive channel access policy dynamically, matching the OpenClaw plugin behavior.
+
+Manual config shape:
+
+```yaml
+plugins:
+  enabled:
+    - shadowob
+
+platforms:
+  shadowob:
+    enabled: true
+    token: "buddy-token"
+    extra:
+      base_url: "https://shadowob.com"
+      mention_only: false
+      rest_only: false
+      catchup_minutes: 0
+      download_media: true
+      slash_commands: []
+```
+
+Optional environment variables:
+
+```bash
+export SHADOW_BASE_URL="https://shadowob.com"
+export SHADOW_TOKEN="buddy-token"
+export SHADOW_HEARTBEAT_INTERVAL_SECONDS=30
+export SHADOW_SLASH_COMMANDS_JSON='[]'
+```
+
+## cc-connect
+
+```bash
+npx @shadowob/connector@latest connect \
+  --target cc-connect \
+  --server-url https://shadowob.com \
+  --token buddy-token \
+  --work-dir . \
+  --project-name shadow-buddy \
+  --agent-type codex
+```
+
+Equivalent TOML:
+
+```toml
+language = "zh"
+
+[[projects]]
+name = "shadow-buddy"
+work_dir = "."
+agent_type = "codex"
+
+[[projects.platforms]]
+type = "shadowob"
+
+[projects.platforms.options]
+token = "buddy-token"
+server_url = "https://shadowob.com"
+allow_from = "*"
+listen_dms = true
+share_session_in_channel = false
+progress_style = "compact"
+```
+
+## TypeScript API
+
+```ts
+import { createConnectorPlan, createConnectorPlans } from '@shadowob/connector'
+
+const hermes = createConnectorPlan({
+  target: 'hermes',
+  serverUrl: 'https://shadowob.com',
+  token: 'buddy-token',
+})
+
+const allPlans = createConnectorPlans({
+  serverUrl: 'https://shadowob.com',
+  token: 'buddy-token',
+})
+```
+
+## Tests
+
+```bash
+pnpm --filter @shadowob/connector test
+pnpm -C packages/connector typecheck
+pnpm -C packages/connector build
+uv run --project .tmp/hermes-agent --with pytest python -m pytest packages/connector/hermes-shadowob-plugin/tests
+```
+
+The tests cover plan generation for OpenClaw, Hermes, and cc-connect, and assert that Hermes setup no longer emits static `agentId` or `channelId` arguments.
+
+## Capability Coverage
+
+- OpenClaw: channel messages, DMs, threads, mentions, attachments/images, interactive components, slash commands, online status, typing/activity, reactions, edits/deletes.
+- Hermes Agent: channel messages, DMs, threads, attachments/images, interactive components, slash commands, online status, typing/activity, cron delivery.
+- cc-connect: channel messages, DMs, attachments/images, interactive components, slash commands, typing, streaming previews, forms.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawnSync } from "child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/index.ts
+var DEFAULT_SERVER_URL = "https://shadowob.com";
+var DEFAULT_WORK_DIR = ".";
+var DEFAULT_PROJECT_NAME = "shadow-buddy";
+var DEFAULT_CC_AGENT = "codex";
+var shellQuote = (value) => {
+  if (!value) return "''";
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+};
+var normalizeServerUrl = (value) => {
+  const trimmed = value.trim() || DEFAULT_SERVER_URL;
+  return trimmed.endsWith("/api") ? trimmed.slice(0, -4) : trimmed.replace(/\/$/, "");
+};
+var tokenOrPlaceholder = (token) => token.trim() || "<BUDDY_TOKEN>";
+function buildOpenClawPlan(input) {
+  const token = tokenOrPlaceholder(input.token);
+  const serverUrl = normalizeServerUrl(input.serverUrl);
+  const jsonConfig = JSON.stringify(
+    {
+      channels: {
+        shadowob: {
+          token,
+          serverUrl
+        }
+      }
+    },
+    null,
+    2
+  );
+  const commands = [
+    {
+      label: "Install plugin",
+      command: "openclaw plugins install @shadowob/openclaw-shadowob"
+    },
+    {
+      label: "Set Buddy token",
+      command: `openclaw config set channels.shadowob.token ${shellQuote(token)}`
+    },
+    {
+      label: "Set Shadow server URL",
+      command: `openclaw config set channels.shadowob.serverUrl ${shellQuote(serverUrl)}`
+    },
+    {
+      label: "Restart gateway",
+      command: "openclaw gateway restart"
+    }
+  ];
+  const quickCommand = commands.map((item) => item.command).join(" && ");
+  const connectCommand = [
+    "npx @shadowob/connector@latest connect",
+    "--target openclaw",
+    `--server-url ${shellQuote(serverUrl)}`,
+    `--token ${shellQuote(token)}`
+  ].join(" ");
+  return {
+    target: "openclaw",
+    title: "OpenClaw",
+    summary: "Install the Shadow channel plugin and bind this Buddy token to OpenClaw.",
+    connectCommand,
+    quickCommand,
+    commands,
+    configBlocks: [{ label: "openclaw.json", language: "json", content: jsonConfig }],
+    aiPrompt: [
+      "Configure this Shadow Buddy in OpenClaw.",
+      "",
+      `Shadow server URL: ${serverUrl}`,
+      `Buddy token: ${token}`,
+      "",
+      "Run these steps in order:",
+      ...commands.map((item, index) => `${index + 1}. ${item.command}`),
+      "",
+      "Confirm each step and then verify the gateway is running."
+    ].join("\n"),
+    docsUrl: "/product/index.html",
+    capabilities: [
+      "channelMessages",
+      "dms",
+      "threads",
+      "mentions",
+      "attachments",
+      "images",
+      "interactive",
+      "slashCommands",
+      "onlineStatus",
+      "typing",
+      "activityStatus",
+      "reactions",
+      "editDelete"
+    ]
+  };
+}
+function buildHermesPlan(input) {
+  const token = tokenOrPlaceholder(input.token);
+  const serverUrl = normalizeServerUrl(input.serverUrl);
+  const envBlock = [
+    `SHADOW_BASE_URL=${shellQuote(serverUrl)}`,
+    `SHADOW_TOKEN=${shellQuote(token)}`,
+    "SHADOW_ALLOW_ALL_USERS=true",
+    "SHADOW_HEARTBEAT_INTERVAL_SECONDS=30",
+    `SHADOW_SLASH_COMMANDS_JSON=${shellQuote("[]")}`
+  ].join("\n");
+  const yamlConfig = [
+    "plugins:",
+    "  enabled:",
+    "    - shadowob",
+    "",
+    "platforms:",
+    "  shadowob:",
+    "    enabled: true",
+    `    token: "${token}"`,
+    "    extra:",
+    `      base_url: "${serverUrl}"`,
+    "      mention_only: false",
+    "      rest_only: false",
+    "      catchup_minutes: 0",
+    "      download_media: true",
+    "      slash_commands: []"
+  ].join("\n");
+  const commands = [
+    {
+      label: "Copy plugin directory",
+      command: "mkdir -p ~/.hermes/plugins && cp -R ./packages/connector/hermes-shadowob-plugin ~/.hermes/plugins/shadowob"
+    },
+    {
+      label: "Install plugin dependencies",
+      command: "python -m pip install -r ~/.hermes/plugins/shadowob/requirements.txt"
+    },
+    {
+      label: "Enable plugin",
+      command: "hermes plugins enable shadowob"
+    },
+    {
+      label: "Start gateway",
+      command: "hermes gateway"
+    }
+  ];
+  const connectCommand = [
+    "npx @shadowob/connector@latest connect",
+    "--target hermes",
+    `--server-url ${shellQuote(serverUrl)}`,
+    `--token ${shellQuote(token)}`
+  ].join(" ");
+  return {
+    target: "hermes",
+    title: "Hermes Agent",
+    summary: "Install the ShadowOB Hermes platform plugin and run Hermes gateway for this Buddy.",
+    connectCommand,
+    quickCommand: commands.map((item) => item.command).join(" && "),
+    commands,
+    configBlocks: [
+      { label: "~/.hermes/.env", language: "bash", content: envBlock },
+      { label: "~/.hermes/config.yaml", language: "yaml", content: yamlConfig }
+    ],
+    aiPrompt: [
+      "Configure this Shadow Buddy in Hermes Agent.",
+      "",
+      `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."
+    ].join("\n"),
+    docsUrl: "https://hermes-agent.nousresearch.com/docs/user-guide/messaging",
+    capabilities: [
+      "channelMessages",
+      "dms",
+      "threads",
+      "attachments",
+      "images",
+      "interactive",
+      "slashCommands",
+      "onlineStatus",
+      "typing",
+      "activityStatus",
+      "cronDelivery"
+    ]
+  };
+}
+function buildCcConnectPlan(input) {
+  const token = tokenOrPlaceholder(input.token);
+  const serverUrl = normalizeServerUrl(input.serverUrl);
+  const projectName = input.projectName?.trim() || DEFAULT_PROJECT_NAME;
+  const workDir = input.workDir?.trim() || DEFAULT_WORK_DIR;
+  const agentType = input.agentType?.trim() || DEFAULT_CC_AGENT;
+  const tomlConfig = [
+    'language = "zh"',
+    "",
+    "[[projects]]",
+    `name = "${projectName}"`,
+    `work_dir = "${workDir}"`,
+    `agent_type = "${agentType}"`,
+    "",
+    "[[projects.platforms]]",
+    'type = "shadowob"',
+    "",
+    "[projects.platforms.options]",
+    `token = "${token}"`,
+    `server_url = "${serverUrl}"`,
+    'allow_from = "*"',
+    "listen_dms = true",
+    "share_session_in_channel = false",
+    'progress_style = "compact"'
+  ].join("\n");
+  const commands = [
+    { label: "Install cc-connect", command: "npm install -g cc-connect" },
+    { label: "Create config directory", command: "mkdir -p ~/.cc-connect" },
+    {
+      label: "Edit config",
+      command: "$EDITOR ~/.cc-connect/config.toml"
+    },
+    { label: "Start cc-connect", command: "cc-connect" }
+  ];
+  const connectCommand = [
+    "npx @shadowob/connector@latest connect",
+    "--target cc-connect",
+    `--server-url ${shellQuote(serverUrl)}`,
+    `--token ${shellQuote(token)}`,
+    `--work-dir ${shellQuote(workDir)}`,
+    `--project-name ${shellQuote(projectName)}`,
+    `--agent-type ${shellQuote(agentType)}`
+  ].join(" ");
+  return {
+    target: "cc-connect",
+    title: "cc-connect",
+    summary: "Use cc-connect ShadowOB Socket.IO platform support with this Buddy token.",
+    connectCommand,
+    quickCommand: commands.map((item) => item.command).join(" && "),
+    commands,
+    configBlocks: [{ label: "~/.cc-connect/config.toml", language: "toml", content: tomlConfig }],
+    aiPrompt: [
+      "Configure this Shadow Buddy in cc-connect.",
+      "",
+      `Shadow server URL: ${serverUrl}`,
+      `Buddy token: ${token}`,
+      `Project work_dir: ${workDir}`,
+      `Agent type: ${agentType}`,
+      "",
+      "Install cc-connect, add the TOML platform block, and start cc-connect."
+    ].join("\n"),
+    docsUrl: "https://github.com/buggyblues/cc-connect/blob/main/docs/shadowob.md",
+    capabilities: [
+      "channelMessages",
+      "dms",
+      "attachments",
+      "images",
+      "interactive",
+      "slashCommands",
+      "typing",
+      "streamingPreviews",
+      "forms"
+    ]
+  };
+}
+function createConnectorPlan(input) {
+  if (input.target === "openclaw") return buildOpenClawPlan(input);
+  if (input.target === "hermes") return buildHermesPlan(input);
+  if (input.target === "cc-connect") return buildCcConnectPlan(input);
+  throw new Error(`Unsupported connector target: ${String(input.target)}`);
+}
+
+// src/cli.ts
+var TARGETS = /* @__PURE__ */ new Set(["openclaw", "hermes", "cc-connect"]);
+function readOption(args, name) {
+  const prefix = `${name}=`;
+  const inline = args.find((arg) => arg.startsWith(prefix));
+  if (inline) return inline.slice(prefix.length);
+  const index = args.indexOf(name);
+  if (index >= 0) return args[index + 1];
+  return void 0;
+}
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+function usage() {
+  return [
+    "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>",
+    "",
+    "Options:",
+    "  --hermes-home <path>    Hermes config directory, default $HERMES_HOME or ~/.hermes",
+    "  --work-dir <path>       cc-connect project work directory",
+    "  --project-name <name>   cc-connect project name",
+    "  --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 cc-connect when target is cc-connect",
+    "  --no-install            Skip Hermes dependency install and plugin enablement",
+    "  --start                 Start Hermes gateway or cc-connect after setup",
+    "  --dry-run               Show what would be applied without changing files"
+  ].join("\n");
+}
+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 target = readOption(optionArgs, "--target");
+  if (!target || !TARGETS.has(target)) {
+    throw new Error("Missing or invalid --target");
+  }
+  const install = target === "cc-connect" ? hasFlag(optionArgs, "--install") : !hasFlag(optionArgs, "--no-install");
+  return {
+    command,
+    target,
+    serverUrl: readOption(optionArgs, "--server-url") ?? "https://shadowob.com",
+    token: readOption(optionArgs, "--token") ?? "",
+    hermesHome: readOption(optionArgs, "--hermes-home"),
+    workDir: readOption(optionArgs, "--work-dir"),
+    projectName: readOption(optionArgs, "--project-name"),
+    agentType: readOption(optionArgs, "--agent-type"),
+    json: hasFlag(optionArgs, "--json"),
+    force: hasFlag(optionArgs, "--force"),
+    install,
+    start: hasFlag(optionArgs, "--start"),
+    dryRun: hasFlag(optionArgs, "--dry-run")
+  };
+}
+function printPlan(options) {
+  const plan = createConnectorPlan(options);
+  if (options.json) {
+    console.log(JSON.stringify(plan, null, 2));
+    return;
+  }
+  console.log(`# ${plan.title}`);
+  console.log(plan.summary);
+  console.log("");
+  console.log("## Quick command");
+  console.log(plan.quickCommand);
+  for (const block of plan.configBlocks) {
+    console.log("");
+    console.log(`## ${block.label}`);
+    console.log(block.content);
+  }
+}
+function runShell(command, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] ${command}`);
+    return;
+  }
+  const result = spawnSync(command, { shell: true, stdio: "inherit" });
+  if (result.status !== 0) {
+    throw new Error(`Command failed with exit code ${result.status ?? "unknown"}: ${command}`);
+  }
+}
+function writeFile(path, content, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] write ${path}`);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content.endsWith("\n") ? content : `${content}
+`);
+}
+function upsertManagedBlock(path, name, content, dryRun) {
+  const begin = `# BEGIN ShadowOB ${name}`;
+  const end = `# END ShadowOB ${name}`;
+  const block = `${begin}
+${content}
+${end}`;
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const pattern = new RegExp(
+    `${begin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`
+  );
+  const next = existing.match(pattern) ? existing.replace(pattern, block) : [existing.trimEnd(), block].filter(Boolean).join("\n\n");
+  writeFile(path, next, dryRun);
+}
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function expandHome(value) {
+  return value.startsWith("~/") ? resolve(homedir(), value.slice(2)) : resolve(value);
+}
+function hermesPluginSource() {
+  const candidates = [
+    resolve(packageRoot(), "hermes-shadowob-plugin"),
+    resolve(process.cwd(), "packages/connector/hermes-shadowob-plugin")
+  ];
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (!found) throw new Error("Cannot find bundled hermes-shadowob-plugin directory");
+  return found;
+}
+function applyOpenClaw(options) {
+  const plan = createConnectorPlan(options);
+  for (const step of plan.commands) {
+    console.log(`Applying: ${step.label}`);
+    runShell(step.command, options.dryRun);
+  }
+}
+function applyHermes(options) {
+  const plan = createConnectorPlan(options);
+  const hermesDir = expandHome(options.hermesHome ?? process.env.HERMES_HOME ?? "~/.hermes");
+  const pluginTarget = resolve(hermesDir, "plugins/shadowob");
+  const envPath = resolve(hermesDir, ".env");
+  const configPath = resolve(hermesDir, "config.yaml");
+  const generatedConfigPath = resolve(hermesDir, "config.shadowob.yaml");
+  const envBlock = plan.configBlocks.find((block) => block.label === "~/.hermes/.env");
+  const yamlBlock = plan.configBlocks.find((block) => block.label === "~/.hermes/config.yaml");
+  if (!envBlock || !yamlBlock) throw new Error("Hermes plan is missing config blocks");
+  if (options.dryRun) {
+    console.log(`[dry-run] copy ${hermesPluginSource()} -> ${pluginTarget}`);
+  } else {
+    mkdirSync(resolve(hermesDir, "plugins"), { recursive: true });
+    cpSync(hermesPluginSource(), pluginTarget, { recursive: true, force: true });
+  }
+  upsertManagedBlock(envPath, "Hermes ShadowOB", envBlock.content, options.dryRun);
+  if (!existsSync(configPath) || options.force) {
+    writeFile(configPath, yamlBlock.content, options.dryRun);
+  } else {
+    writeFile(generatedConfigPath, yamlBlock.content, options.dryRun);
+    console.log(`Existing Hermes config kept. Generated ShadowOB config: ${generatedConfigPath}`);
+  }
+  if (options.install) {
+    runShell(
+      `python -m pip install -r "${resolve(pluginTarget, "requirements.txt")}"`,
+      options.dryRun
+    );
+    runShell("hermes plugins enable shadowob", options.dryRun);
+  }
+  if (options.start) {
+    runShell("hermes gateway", options.dryRun);
+  }
+}
+function applyCcConnect(options) {
+  const plan = createConnectorPlan(options);
+  const configBlock = plan.configBlocks.find((block) => block.label === "~/.cc-connect/config.toml");
+  if (!configBlock) throw new Error("cc-connect plan is missing config block");
+  const configPath = resolve(homedir(), ".cc-connect/config.toml");
+  const generatedPath = resolve(homedir(), ".cc-connect/config.shadowob.toml");
+  if (!existsSync(configPath) || options.force) {
+    writeFile(configPath, configBlock.content, options.dryRun);
+  } else {
+    writeFile(generatedPath, configBlock.content, options.dryRun);
+    console.log(`Existing cc-connect config kept. Generated ShadowOB config: ${generatedPath}`);
+  }
+  if (options.install) {
+    runShell("npm install -g cc-connect", options.dryRun);
+  }
+  if (options.start) {
+    runShell("cc-connect", options.dryRun);
+  }
+}
+function connect(options) {
+  if (options.target === "openclaw") {
+    applyOpenClaw(options);
+    return;
+  }
+  if (options.target === "hermes") {
+    applyHermes(options);
+    return;
+  }
+  applyCcConnect(options);
+}
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.command === "connect") {
+    connect(options);
+  } else {
+    printPlan(options);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  console.error("");
+  console.error(usage());
+  process.exit(1);
+}