@kernelius/forge-cli 0.3.4 → 0.4.1

package/README.md

@@ -193,7 +193,7 @@ Config is stored at `~/.config/forge/config.json`:
 
 ```json
 {
-  "apiUrl": "https://forge.example.com",
+  "apiUrl": "https://forge-api.kernelius.com",
   "apiKey": "forge_agent_xxx...",
   "agentId": "user-id",
   "agentName": "username"

package/SKILL.md

@@ -221,6 +221,95 @@ forge templates view patient-record
 forge repos create --name my-patient-repo --template patient-record --visibility private
 ```
 
+## Webhooks
+
+Webhooks allow external systems (like OpenClaw) to receive notifications when events occur in Forge repositories.
+
+**List webhooks:**
+
+```bash
+forge webhooks list --repo @owner/repo
+```
+
+**Create a webhook:**
+
+```bash
+forge webhooks create --repo @owner/repo \
+  --url "https://your-server.com/hooks/forge" \
+  --events "issue.created,issue.commented,pr.created,pr.merged" \
+  --name "My Integration"
+```
+
+**Test a webhook:**
+
+```bash
+forge webhooks test --repo @owner/repo --id <webhook-id>
+```
+
+**View recent deliveries:**
+
+```bash
+forge webhooks deliveries --repo @owner/repo --id <webhook-id>
+```
+
+**List available events:**
+
+```bash
+forge webhooks events
+```
+
+**Update a webhook:**
+
+```bash
+forge webhooks update --repo @owner/repo --id <webhook-id> --events "issue.created,pr.created" --active
+```
+
+**Delete a webhook:**
+
+```bash
+forge webhooks delete --repo @owner/repo --id <webhook-id>
+```
+
+**Regenerate secret:**
+
+```bash
+forge webhooks regenerate-secret --repo @owner/repo --id <webhook-id>
+```
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `issue.created` | New issue opened |
+| `issue.updated` | Issue title/body changed |
+| `issue.closed` | Issue closed |
+| `issue.reopened` | Issue reopened |
+| `issue.commented` | Comment added to issue |
+| `pr.created` | Pull request opened |
+| `pr.updated` | PR title/body changed |
+| `pr.merged` | Pull request merged |
+| `pr.closed` | PR closed without merging |
+| `pr.review_requested` | Review requested on PR |
+| `pr.reviewed` | Review submitted |
+| `pr.commented` | Comment on PR |
+| `push` | Commits pushed |
+
+### Verifying Webhook Signatures
+
+Forge signs webhook payloads with HMAC-SHA256. Verify using the `X-Forge-Signature` header:
+
+```javascript
+const crypto = require('crypto');
+
+function verifySignature(payload, signature, secret) {
+  const expected = 'sha256=' + crypto
+    .createHmac('sha256', secret)
+    .update(JSON.stringify(payload))
+    .digest('hex');
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+```
+
 ## Important Notes
 
 - **Always specify `--repo @owner/repo`** when working with issues or PRs

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join as join2 } from "path";
@@ -1800,13 +1800,264 @@ function createUserCommand() {
   return user;
 }
 
+// src/commands/webhooks.ts
+import { Command as Command8 } from "commander";
+import chalk8 from "chalk";
+function createWebhooksCommand() {
+  const webhooks = new Command8("webhooks").alias("webhook").description("Manage repository webhooks");
+  webhooks.command("list").description("List webhooks for a repository").requiredOption("--repo <repo>", "Repository (@owner/name)").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      const result = await apiGet(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks`
+      );
+      const webhookList = result.webhooks || [];
+      if (webhookList.length === 0) {
+        console.log(chalk8.yellow("No webhooks found"));
+        return;
+      }
+      console.log(chalk8.bold(`Webhooks (${webhookList.length})`));
+      console.log();
+      for (const webhook of webhookList) {
+        const statusIcon = webhook.active ? "\u{1F7E2}" : "\u26AA";
+        console.log(`${statusIcon} ${chalk8.cyan(webhook.name || webhook.id)}`);
+        console.log(chalk8.dim(`   URL: ${webhook.url}`));
+        console.log(chalk8.dim(`   Events: ${(webhook.events || []).join(", ")}`));
+        if (webhook.lastTriggeredAt) {
+          console.log(chalk8.dim(`   Last triggered: ${new Date(webhook.lastTriggeredAt).toLocaleString()}`));
+        }
+        if (webhook.failureCount > 0) {
+          console.log(chalk8.yellow(`   Failures: ${webhook.failureCount}`));
+        }
+        console.log();
+      }
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("view").description("View webhook details").requiredOption("--repo <repo>", "Repository (@owner/name)").requiredOption("--id <id>", "Webhook ID").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      const webhook = await apiGet(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks/${options.id}`
+      );
+      const statusIcon = webhook.active ? "\u{1F7E2} Active" : "\u26AA Inactive";
+      console.log(chalk8.bold(webhook.name || `Webhook ${webhook.id}`));
+      console.log(chalk8.dim(`Status: ${statusIcon}`));
+      console.log();
+      console.log(`URL: ${chalk8.cyan(webhook.url)}`);
+      console.log(`Secret: ${chalk8.dim(webhook.secret)}`);
+      console.log();
+      console.log(chalk8.bold("Events:"));
+      for (const event of webhook.events || []) {
+        console.log(`  \u2022 ${event}`);
+      }
+      console.log();
+      if (webhook.description) {
+        console.log(`Description: ${webhook.description}`);
+      }
+      console.log(chalk8.dim(`Created: ${new Date(webhook.createdAt).toLocaleString()}`));
+      if (webhook.lastTriggeredAt) {
+        console.log(chalk8.dim(`Last triggered: ${new Date(webhook.lastTriggeredAt).toLocaleString()}`));
+      }
+      if (webhook.lastSuccessAt) {
+        console.log(chalk8.green(`Last success: ${new Date(webhook.lastSuccessAt).toLocaleString()}`));
+      }
+      if (webhook.lastFailureAt) {
+        console.log(chalk8.yellow(`Last failure: ${new Date(webhook.lastFailureAt).toLocaleString()}`));
+      }
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("create").description("Create a new webhook").requiredOption("--repo <repo>", "Repository (@owner/name)").requiredOption("--url <url>", "Webhook URL to receive events").requiredOption("--events <events>", "Comma-separated list of events to listen for").option("--name <name>", "Friendly name for the webhook").option("--description <desc>", "Description of the webhook").option("--inactive", "Create webhook as inactive").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      const events = options.events.split(",").map((e) => e.trim());
+      const webhook = await apiPost(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks`,
+        {
+          url: options.url,
+          events,
+          webhookName: options.name,
+          description: options.description,
+          active: !options.inactive
+        }
+      );
+      console.log(chalk8.green("\u2713 Webhook created successfully"));
+      console.log();
+      console.log(`ID: ${chalk8.cyan(webhook.id)}`);
+      console.log(`URL: ${webhook.url}`);
+      console.log(`Events: ${events.join(", ")}`);
+      console.log();
+      console.log(chalk8.bold.yellow("\u26A0\uFE0F  Save this secret - it will only be shown once:"));
+      console.log(chalk8.cyan(webhook.secretFull));
+      console.log();
+      console.log(chalk8.dim("Use this secret to verify webhook signatures (X-Forge-Signature header)"));
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("update").description("Update a webhook").requiredOption("--repo <repo>", "Repository (@owner/name)").requiredOption("--id <id>", "Webhook ID").option("--url <url>", "New URL").option("--events <events>", "New comma-separated list of events").option("--name <name>", "New name").option("--description <desc>", "New description").option("--active", "Enable webhook").option("--inactive", "Disable webhook").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      const updates = {};
+      if (options.url) updates.url = options.url;
+      if (options.events) updates.events = options.events.split(",").map((e) => e.trim());
+      if (options.name !== void 0) updates.name = options.name;
+      if (options.description !== void 0) updates.description = options.description;
+      if (options.active) updates.active = true;
+      if (options.inactive) updates.active = false;
+      if (Object.keys(updates).length === 0) {
+        console.log(chalk8.yellow("No updates specified"));
+        return;
+      }
+      await apiPatch(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks/${options.id}`,
+        updates
+      );
+      console.log(chalk8.green("\u2713 Webhook updated successfully"));
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("delete").description("Delete a webhook").requiredOption("--repo <repo>", "Repository (@owner/name)").requiredOption("--id <id>", "Webhook ID").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      await apiDelete(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks/${options.id}`
+      );
+      console.log(chalk8.green("\u2713 Webhook deleted successfully"));
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("test").description("Send a test ping to a webhook").requiredOption("--repo <repo>", "Repository (@owner/name)").requiredOption("--id <id>", "Webhook ID").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      console.log(chalk8.dim("Sending test ping..."));
+      const result = await apiPost(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks/${options.id}/test`,
+        {}
+      );
+      if (result.success) {
+        console.log(chalk8.green("\u2713 Webhook test successful"));
+        console.log(chalk8.dim(`  Status: ${result.delivery.statusCode}`));
+        console.log(chalk8.dim(`  Duration: ${result.delivery.duration}ms`));
+      } else {
+        console.log(chalk8.red("\u2717 Webhook test failed"));
+        if (result.delivery.statusCode) {
+          console.log(chalk8.dim(`  Status: ${result.delivery.statusCode}`));
+        }
+        if (result.delivery.error) {
+          console.log(chalk8.dim(`  Error: ${result.delivery.error}`));
+        }
+      }
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("deliveries").description("List recent webhook deliveries").requiredOption("--repo <repo>", "Repository (@owner/name)").requiredOption("--id <id>", "Webhook ID").option("--limit <n>", "Number of deliveries to show", "20").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      const result = await apiGet(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks/${options.id}/deliveries?limit=${options.limit}`
+      );
+      const deliveries = result.deliveries || [];
+      if (deliveries.length === 0) {
+        console.log(chalk8.yellow("No deliveries found"));
+        return;
+      }
+      console.log(chalk8.bold(`Recent Deliveries (${deliveries.length})`));
+      console.log();
+      for (const delivery of deliveries) {
+        const statusIcon = delivery.success ? "\u2713" : "\u2717";
+        const statusColor = delivery.success ? chalk8.green : chalk8.red;
+        console.log(statusColor(`${statusIcon} ${delivery.event}`));
+        console.log(chalk8.dim(`   ${new Date(delivery.deliveredAt).toLocaleString()}`));
+        if (delivery.statusCode) {
+          console.log(chalk8.dim(`   Status: ${delivery.statusCode} \xB7 ${delivery.duration}ms`));
+        }
+        if (delivery.error) {
+          console.log(chalk8.yellow(`   Error: ${delivery.error}`));
+        }
+        console.log();
+      }
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("regenerate-secret").description("Regenerate webhook secret").requiredOption("--repo <repo>", "Repository (@owner/name)").requiredOption("--id <id>", "Webhook ID").action(async (options) => {
+    try {
+      const [ownerIdentifier, name] = parseRepoArg4(options.repo);
+      const result = await apiPost(
+        `/api/repositories/${ownerIdentifier}/${name}/webhooks/${options.id}/regenerate-secret`,
+        {}
+      );
+      console.log(chalk8.green("\u2713 Secret regenerated successfully"));
+      console.log();
+      console.log(chalk8.bold.yellow("\u26A0\uFE0F  Save this new secret - it will only be shown once:"));
+      console.log(chalk8.cyan(result.secretFull));
+      console.log();
+      console.log(chalk8.dim("Update your webhook receiver to use this new secret"));
+    } catch (error) {
+      console.error(chalk8.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+  webhooks.command("events").description("List available webhook event types").action(() => {
+    console.log(chalk8.bold("Available Webhook Events"));
+    console.log();
+    const events = [
+      { name: "issue.created", desc: "New issue opened" },
+      { name: "issue.updated", desc: "Issue title or body changed" },
+      { name: "issue.closed", desc: "Issue closed" },
+      { name: "issue.reopened", desc: "Issue reopened" },
+      { name: "issue.commented", desc: "New comment on issue" },
+      { name: "pr.created", desc: "Pull request opened" },
+      { name: "pr.updated", desc: "PR title/body changed" },
+      { name: "pr.merged", desc: "PR merged" },
+      { name: "pr.closed", desc: "PR closed without merging" },
+      { name: "pr.review_requested", desc: "Review requested on PR" },
+      { name: "pr.reviewed", desc: "PR review submitted" },
+      { name: "pr.commented", desc: "New comment on PR" },
+      { name: "push", desc: "Commits pushed to branch" },
+      { name: "repo.created", desc: "Repository created" },
+      { name: "repo.deleted", desc: "Repository deleted" }
+    ];
+    for (const event of events) {
+      console.log(`  ${chalk8.cyan(event.name.padEnd(22))} ${chalk8.dim(event.desc)}`);
+    }
+    console.log();
+    console.log(chalk8.dim("Use comma-separated list with --events flag:"));
+    console.log(chalk8.dim("  forge webhooks create --events issue.created,pr.created ..."));
+  });
+  return webhooks;
+}
+function parseRepoArg4(arg) {
+  const match = arg.match(/^@?([^/]+)\/(.+)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid repository format: ${arg}. Expected format: @owner/name or owner/name`
+    );
+  }
+  return [match[1], match[2]];
+}
+
 // src/index.ts
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname(__filename2);
 var packageJson = JSON.parse(
   readFileSync(join2(__dirname2, "../package.json"), "utf-8")
 );
-var program = new Command8();
+var program = new Command9();
 program.name("forge").description("CLI tool for Kernelius Forge - the agent-native Git platform").version(packageJson.version);
 program.addCommand(createAuthCommand());
 program.addCommand(createReposCommand());
@@ -1815,4 +2066,5 @@ program.addCommand(createPrsCommand());
 program.addCommand(createOrgsCommand());
 program.addCommand(createUserCommand());
 program.addCommand(createTemplatesCommand());
+program.addCommand(createWebhooksCommand());
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernelius/forge-cli",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "Command-line tool for Kernelius Forge - the agent-native Git platform",
   "type": "module",
   "bin": {