@denial-web/clawguard 0.1.11 → 0.1.12

package/README.md

@@ -68,6 +68,14 @@ npx @denial-web/clawguard hermes install ./candidate-skill --to ~/.hermes/skills
 
 The approval JSONL payload is designed for a bot or daemon to forward to WhatsApp, Telegram, Slack, Discord, or another owner channel before any files are copied into a trusted skill folder.
 
+Check the approval setup and print the exact command flow:
+
+```bash
+npx @denial-web/clawguard approvals doctor --chat-id 123456789
+```
+
+Use `--framework hermes` to print Hermes install commands, or `--check-telegram` when you want ClawGuard to call Telegram `getMe` and verify the bot token.
+
 If OpenClaw already has messaging configured, ClawGuard can hand the approval message to OpenClaw:
 
 ```bash

package/docs/INTEGRATION_SPEC.md

@@ -78,6 +78,17 @@ TELEGRAM_BOT_TOKEN=123456:token clawguard approvals watch ./.clawguard/approvals
 
 The watcher keeps search and discovery unrestricted. It only reacts after a guarded install writes a pending approval request. By default it records sent ids in `./.clawguard/approvals.jsonl.sent.json`, so restarting the bridge does not resend the same request. Use `--once --dry-run` for setup checks and CI smoke tests.
 
+### Approval Doctor
+
+Before wiring a real agent into the approval loop, users can run:
+
+```bash
+clawguard approvals doctor \
+  --chat-id 123456789
+```
+
+The doctor checks local runtime readiness, writable approval and decision paths, install destination writability, Telegram token presence, and Telegram chat id presence. It does not call Telegram by default. With `--check-telegram`, it calls Telegram `getMe` to verify the configured bot token. The command prints suggested guarded install, watcher, poller, and apply commands for OpenClaw by default; `--framework hermes` switches the guarded install example to Hermes.
+
 ### Approval Decisions
 
 Owner decisions are stored separately from approval requests. This keeps the original scan evidence immutable and gives messaging bridges a simple append-only target:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denial-web/clawguard",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Explainable security scanner for OpenClaw-style skills and MCP tool configs.",
   "type": "module",
   "repository": {

package/src/cli.js

@@ -41,7 +41,8 @@ if (![
   "approvals-watch",
   "approvals-decide",
   "approvals-poll-telegram",
-  "approvals-apply"
+  "approvals-apply",
+  "approvals-doctor"
 ].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
@@ -106,6 +107,17 @@ try {
     process.exit(approvalApplyExitCode(result));
   }
 
+  if (command === "approvals-doctor") {
+    const doctorOptions = parseApprovalDoctorOptions(optionValues);
+    const result = await runApprovalDoctor(doctorOptions);
+    if (doctorOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printApprovalDoctorResult(result);
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+
   const cliOptions = parseOptions(optionValues);
   cliOptions.framework = framework;
   const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
@@ -171,6 +183,7 @@ Usage:
   clawguard approvals decide <approval.json|approvals.jsonl> --id <id> --decision approve|deny
   clawguard approvals poll-telegram <approvals.jsonl> --decisions <decisions.jsonl>
   clawguard approvals apply <approvals.jsonl> --id <id> --decisions <decisions.jsonl>
+  clawguard approvals doctor [--chat-id <id>]
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -214,6 +227,8 @@ Options:
   --offset-state <path>   Telegram update offset state file.
   --telegram-updates-file <path>
                           Read Telegram updates from a JSON file for tests or offline replay.
+  --check-telegram        In approvals doctor, call Telegram getMe to verify the bot token.
+  --framework <name>      In approvals doctor, show openclaw or hermes commands. Default: openclaw.
 
 Gate exit codes:
   0 = allow
@@ -232,6 +247,7 @@ Examples:
   npx @denial-web/clawguard approvals decide ./.clawguard/approvals.jsonl --id <id> --decision approve
   npx @denial-web/clawguard approvals poll-telegram ./.clawguard/approvals.jsonl --decisions ./.clawguard/decisions.jsonl
   npx @denial-web/clawguard approvals apply ./.clawguard/approvals.jsonl --id <id> --decisions ./.clawguard/decisions.jsonl
+  npx @denial-web/clawguard approvals doctor --chat-id 123456789
   npm run scan -- examples/risky-skill
   npm run scan -- examples/metadata-mismatch-skill --policy governed --fail-on-policy
   npm run scan -- examples/metadata-mismatch-skill --html clawguard.html
@@ -355,6 +371,14 @@ function parseCommand(values) {
     };
   }
 
+  if (rawCommand === "approvals" && values[1] === "doctor") {
+    return {
+      command: "approvals-doctor",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
   if (["openclaw", "hermes"].includes(rawCommand)) {
     const nestedCommand = values[1];
 
@@ -662,6 +686,209 @@ async function applyApprovalDecision(options) {
   return result;
 }
 
+async function runApprovalDoctor(options) {
+  const approvalPath = path.resolve(options.approvalPath);
+  const decisionsPath = path.resolve(options.decisionsPath);
+  const installDir = path.resolve(options.installDir);
+  const target = options.target;
+  const token = options.botToken ?? process.env.TELEGRAM_BOT_TOKEN;
+  const checks = [
+    checkNodeVersion(),
+    {
+      id: "approval-path-format",
+      status: approvalPath.endsWith(".jsonl") ? "pass" : "warn",
+      message: approvalPath.endsWith(".jsonl")
+        ? "Approval queue uses JSONL."
+        : "Approval queue is not .jsonl; JSONL is recommended for watcher integrations.",
+      detail: approvalPath
+    },
+    {
+      id: "telegram-token",
+      status: token ? "pass" : "warn",
+      message: token
+        ? "Telegram bot token is configured."
+        : "Telegram bot token is not configured. Set TELEGRAM_BOT_TOKEN or pass --bot-token.",
+      detail: token ? "present" : "missing"
+    },
+    {
+      id: "telegram-chat",
+      status: options.chatId ? "pass" : "warn",
+      message: options.chatId
+        ? "Telegram chat id is configured."
+        : "Telegram chat id is missing. Pass --chat-id before running the watcher.",
+      detail: options.chatId ?? "missing"
+    }
+  ];
+
+  checks.push(await checkWritablePath("approval-directory-writable", path.dirname(approvalPath)));
+  checks.push(await checkWritablePath("decision-directory-writable", path.dirname(decisionsPath)));
+  checks.push(await checkWritablePath("install-directory-writable", installDir));
+
+  if (options.checkTelegram) {
+    checks.push(await checkTelegramBot(token, options));
+  }
+
+  const commands = createApprovalDoctorCommands({
+    framework: options.framework,
+    target,
+    installDir,
+    approvalPath,
+    decisionsPath,
+    chatId: options.chatId ?? "<telegram-chat-id>"
+  });
+  const ok = checks.every((check) => check.status !== "fail");
+
+  return {
+    ok,
+    framework: options.framework,
+    paths: {
+      target,
+      installDir,
+      approvalPath,
+      decisionsPath
+    },
+    checks,
+    commands
+  };
+}
+
+function checkNodeVersion() {
+  const major = Number.parseInt(process.versions.node.split(".")[0], 10);
+  return {
+    id: "node-version",
+    status: major >= 20 ? "pass" : "fail",
+    message: major >= 20
+      ? `Node.js ${process.versions.node} satisfies ClawGuard's runtime requirement.`
+      : `Node.js ${process.versions.node} is too old. ClawGuard requires Node.js 20 or newer.`,
+    detail: process.versions.node
+  };
+}
+
+async function checkWritablePath(id, directory) {
+  const resolved = path.resolve(directory);
+  const probePath = path.join(resolved, `.clawguard-doctor-${process.pid}.tmp`);
+
+  try {
+    await fs.mkdir(resolved, { recursive: true });
+    await fs.writeFile(probePath, "ok\n", { flag: "wx" });
+    await fs.unlink(probePath);
+    return {
+      id,
+      status: "pass",
+      message: "Directory is writable.",
+      detail: resolved
+    };
+  } catch (error) {
+    return {
+      id,
+      status: "fail",
+      message: `Directory is not writable: ${error.message}`,
+      detail: resolved
+    };
+  }
+}
+
+async function checkTelegramBot(botToken, options) {
+  if (!botToken) {
+    return {
+      id: "telegram-api",
+      status: "warn",
+      message: "Skipped Telegram API check because no bot token is configured.",
+      detail: "missing token"
+    };
+  }
+
+  const apiBase = options.telegramApiBase ?? "https://api.telegram.org";
+  const endpoint = `${apiBase.replace(/\/$/, "")}/bot${botToken}/getMe`;
+
+  try {
+    const response = await fetch(endpoint);
+    const text = await response.text();
+    let payload;
+
+    try {
+      payload = text ? JSON.parse(text) : null;
+    } catch {
+      payload = undefined;
+    }
+
+    if (!response.ok || payload?.ok === false) {
+      return {
+        id: "telegram-api",
+        status: "fail",
+        message: `Telegram getMe failed with HTTP ${response.status}.`,
+        detail: redactTelegramToken(endpoint)
+      };
+    }
+
+    return {
+      id: "telegram-api",
+      status: "pass",
+      message: "Telegram bot API responded successfully.",
+      detail: payload?.result?.username ? `@${payload.result.username}` : redactTelegramToken(endpoint)
+    };
+  } catch (error) {
+    return {
+      id: "telegram-api",
+      status: "fail",
+      message: `Telegram getMe failed: ${error.message}`,
+      detail: redactTelegramToken(endpoint)
+    };
+  }
+}
+
+function createApprovalDoctorCommands(details) {
+  const installArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    details.framework,
+    "install",
+    details.target,
+    "--to",
+    details.installDir,
+    "--approval-out",
+    details.approvalPath
+  ];
+  const watchArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    "approvals",
+    "watch",
+    details.approvalPath,
+    "--via",
+    "telegram",
+    "--chat-id",
+    details.chatId
+  ];
+  const pollArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    "approvals",
+    "poll-telegram",
+    details.approvalPath,
+    "--decisions",
+    details.decisionsPath
+  ];
+  const applyArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    "approvals",
+    "apply",
+    details.approvalPath,
+    "--id",
+    "<approval-id>",
+    "--decisions",
+    details.decisionsPath
+  ];
+
+  return {
+    guardedInstall: installArgs.map(shellQuote).join(" "),
+    watchTelegram: `TELEGRAM_BOT_TOKEN=<token> ${watchArgs.map(shellQuote).join(" ")}`,
+    pollTelegram: `TELEGRAM_BOT_TOKEN=<token> ${pollArgs.map(shellQuote).join(" ")}`,
+    applyDecision: applyArgs.map(shellQuote).join(" ")
+  };
+}
+
 async function readLatestApprovalDecision(decisionsPath, approvalId) {
   let decisions;
 
@@ -941,6 +1168,24 @@ function printApprovalApplyResult(result) {
   console.log(`Reason: ${result.reason}`);
 }
 
+function printApprovalDoctorResult(result) {
+  console.log("ClawGuard approvals doctor");
+  console.log(`Framework: ${displayFramework(result.framework)}`);
+  console.log(`Ready: ${result.ok ? "yes" : "no"}`);
+  console.log("\nChecks:");
+  for (const check of result.checks) {
+    console.log(`- [${check.status.toUpperCase()}] ${check.message}`);
+    if (check.detail) {
+      console.log(`  ${check.detail}`);
+    }
+  }
+  console.log("\nSuggested commands:");
+  console.log(`1. ${result.commands.guardedInstall}`);
+  console.log(`2. ${result.commands.watchTelegram}`);
+  console.log(`3. ${result.commands.pollTelegram}`);
+  console.log(`4. ${result.commands.applyDecision}`);
+}
+
 async function readApprovalRequest(approvalPath, id) {
   const resolvedPath = path.resolve(approvalPath);
   const approvals = await readApprovalRequests(resolvedPath);
@@ -1374,6 +1619,10 @@ function commandLabel(commandName) {
     return "Approval apply";
   }
 
+  if (commandName === "approvals-doctor") {
+    return "Approvals doctor";
+  }
+
   if (commandName === "gate") {
     return "Gate";
   }
@@ -2094,6 +2343,95 @@ function parseApprovalApplyOptions(values) {
   return options;
 }
 
+function parseApprovalDoctorOptions(values) {
+  const options = {
+    approvalPath: ".clawguard/approvals.jsonl",
+    decisionsPath: ".clawguard/decisions.jsonl",
+    installDir: ".agents/skills",
+    target: "./candidate-skill",
+    framework: "openclaw",
+    chatId: undefined,
+    botToken: undefined,
+    telegramApiBase: undefined,
+    checkTelegram: false,
+    json: false
+  };
+
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+
+    if (value === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    if (value === "--approval-out") {
+      options.approvalPath = requireNextValue(values, index, "--approval-out");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--decisions") {
+      options.decisionsPath = requireNextValue(values, index, "--decisions");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--to") {
+      options.installDir = requireNextValue(values, index, "--to");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--target") {
+      options.target = requireNextValue(values, index, "--target");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--framework") {
+      options.framework = requireNextValue(values, index, "--framework");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--chat-id") {
+      options.chatId = requireNextValue(values, index, "--chat-id");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--bot-token") {
+      options.botToken = requireNextValue(values, index, "--bot-token");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--telegram-api-base") {
+      options.telegramApiBase = requireNextValue(values, index, "--telegram-api-base");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--check-telegram") {
+      options.checkTelegram = true;
+      continue;
+    }
+
+    if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+
+    throw new Error(`Unexpected argument for approvals doctor: ${value}`);
+  }
+
+  if (!["openclaw", "hermes"].includes(options.framework)) {
+    throw new Error("Invalid --framework value. Use one of: openclaw, hermes");
+  }
+
+  return options;
+}
+
 async function writeReportFile(outputPath, content) {
   const resolvedPath = path.resolve(outputPath);
   await fs.mkdir(path.dirname(resolvedPath), { recursive: true });