@kernelius/forge-cli 0.3.3 → 0.4.0

package/SKILL.md

@@ -40,7 +40,18 @@ Before using any forge commands, ensure the user is authenticated:
 forge auth whoami
 ```
 
-If not authenticated, the user needs to:
+If not authenticated, the user can either:
+
+**Option 1: Create a new account (signup)**
+```bash
+forge auth signup \
+  --username johndoe \
+  --email john@example.com \
+  --name "John Doe" \
+  --password secret
+```
+
+**Option 2: Login with existing API key**
 1. Get an agent API key from Forge at `/settings/agents`
 2. Login with: `forge auth login --token forge_agent_xxx...`
 
@@ -106,6 +117,24 @@ forge issues close --repo @owner/repo --number 42
 forge issues comment --repo @owner/repo --number 42 --body "This is fixed now"
 ```
 
+**List comments on an issue:**
+
+```bash
+forge issues comments --repo @owner/repo --number 42
+```
+
+**Reopen an issue:**
+
+```bash
+forge issues reopen --repo @owner/repo --number 42
+```
+
+**Edit an issue:**
+
+```bash
+forge issues edit --repo @owner/repo --number 42 --title "New title" --body "Updated description"
+```
+
 ## Pull Requests
 
 **List pull requests:**
@@ -148,6 +177,139 @@ forge prs close --repo @owner/repo --number 10
 forge prs comment --repo @owner/repo --number 10 --body "Looks good to me!"
 ```
 
+**Submit a review:**
+
+```bash
+# Approve a PR
+forge prs review --repo @owner/repo --number 10 --state approve --body "LGTM!"
+
+# Request changes
+forge prs review --repo @owner/repo --number 10 --state request_changes --body "Please fix X"
+```
+
+**View PR diff:**
+
+```bash
+forge prs diff --repo @owner/repo --number 10
+```
+
+**List commits in a PR:**
+
+```bash
+forge prs commits --repo @owner/repo --number 10
+```
+
+## Templates
+
+**List available templates:**
+
+```bash
+forge templates list
+# Filter by organization type:
+forge templates list --org-type healthcare
+```
+
+**View template details:**
+
+```bash
+forge templates view patient-record
+```
+
+**Create repository from template:**
+
+```bash
+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";
@@ -1049,9 +1049,10 @@ function createIssuesCommand() {
   issues.command("labels").description("List repository labels").requiredOption("--repo <repo>", "Repository (@owner/name)").action(async (options) => {
     try {
       const [ownerIdentifier, name] = parseRepoArg2(options.repo);
-      const labels = await apiGet(
+      const result = await apiGet(
         `/api/repositories/${ownerIdentifier}/${name}/labels`
       );
+      const labels = result.labels || [];
       if (labels.length === 0) {
         console.log(chalk4.yellow("No labels found"));
         return;
@@ -1369,7 +1370,8 @@ function createPrsCommand() {
       const pr = await apiGet(
         `/api/repositories/${ownerIdentifier}/${name}/pulls/${options.number}`
       );
-      const reviews = await apiGet(`/api/pulls/${pr.id}/reviews`);
+      const result = await apiGet(`/api/pulls/${pr.id}/reviews`);
+      const reviews = result.reviews || [];
       if (reviews.length === 0) {
         console.log(chalk5.yellow("No reviews found"));
         return;
@@ -1403,7 +1405,8 @@ function createPrsCommand() {
       const pr = await apiGet(
         `/api/repositories/${ownerIdentifier}/${name}/pulls/${options.number}`
       );
-      const commits = await apiGet(`/api/pulls/${pr.id}/commits`);
+      const result = await apiGet(`/api/pulls/${pr.id}/commits`);
+      const commits = result.commits || [];
       if (commits.length === 0) {
         console.log(chalk5.yellow("No commits found"));
         return;
@@ -1546,7 +1549,8 @@ function createOrgsCommand() {
   });
   orgs.command("members").description("List organization members").argument("<slug>", "Organization slug").action(async (slug) => {
     try {
-      const members = await apiGet(`/api/organizations/${slug}/members`);
+      const result = await apiGet(`/api/orgs/${slug}/members`);
+      const members = result.members || [];
       if (members.length === 0) {
         console.log(chalk6.yellow("No members found"));
         return;
@@ -1564,7 +1568,7 @@ function createOrgsCommand() {
   });
   orgs.command("member-add").description("Add a member to organization").argument("<slug>", "Organization slug").argument("<username>", "Username to add").option("--role <role>", "Member role (owner/admin/member)", "member").action(async (slug, username, options) => {
     try {
-      await apiPost(`/api/organizations/${slug}/members`, {
+      await apiPost(`/api/orgs/${slug}/members`, {
         username,
         role: options.role
       });
@@ -1576,7 +1580,7 @@ function createOrgsCommand() {
   });
   orgs.command("member-remove").description("Remove a member from organization").argument("<slug>", "Organization slug").argument("<username>", "Username to remove").action(async (slug, username) => {
     try {
-      await apiDelete(`/api/organizations/${slug}/members/${username}`);
+      await apiDelete(`/api/orgs/${slug}/members/${username}`);
       console.log(chalk6.green(`\u2713 Removed @${username} from @${slug}`));
     } catch (error) {
       console.error(chalk6.red(`Error: ${error.message}`));
@@ -1585,7 +1589,8 @@ function createOrgsCommand() {
   });
   orgs.command("teams").description("List organization teams").argument("<slug>", "Organization slug").action(async (slug) => {
     try {
-      const teams = await apiGet(`/api/organizations/${slug}/teams`);
+      const result = await apiGet(`/api/orgs/${slug}/teams`);
+      const teams = result.teams || [];
       if (teams.length === 0) {
         console.log(chalk6.yellow("No teams found"));
         return;
@@ -1605,7 +1610,7 @@ function createOrgsCommand() {
   });
   orgs.command("team-create").description("Create a team in organization").argument("<slug>", "Organization slug").requiredOption("--name <name>", "Team name").option("--description <desc>", "Team description").action(async (slug, options) => {
     try {
-      const team = await apiPost(`/api/organizations/${slug}/teams`, {
+      const team = await apiPost(`/api/orgs/${slug}/teams`, {
         name: options.name,
         description: options.description
       });
@@ -1617,9 +1622,10 @@ function createOrgsCommand() {
   });
   orgs.command("team-members").description("List team members").argument("<slug>", "Organization slug").argument("<team>", "Team name").action(async (slug, team) => {
     try {
-      const members = await apiGet(
-        `/api/organizations/${slug}/teams/${team}/members`
+      const result = await apiGet(
+        `/api/orgs/${slug}/teams/${team}/members`
       );
+      const members = result.members || [];
       if (members.length === 0) {
         console.log(chalk6.yellow("No team members found"));
         return;
@@ -1637,7 +1643,7 @@ function createOrgsCommand() {
   orgs.command("team-add-member").description("Add a member to team").argument("<slug>", "Organization slug").argument("<team>", "Team name").argument("<username>", "Username to add").action(async (slug, team, username) => {
     try {
       await apiPost(
-        `/api/organizations/${slug}/teams/${team}/members`,
+        `/api/orgs/${slug}/teams/${team}/members`,
         {
           username
         }
@@ -1651,7 +1657,7 @@ function createOrgsCommand() {
   orgs.command("team-remove-member").description("Remove a member from team").argument("<slug>", "Organization slug").argument("<team>", "Team name").argument("<username>", "Username to remove").action(async (slug, team, username) => {
     try {
       await apiDelete(
-        `/api/organizations/${slug}/teams/${team}/members/${username}`
+        `/api/orgs/${slug}/teams/${team}/members/${username}`
       );
       console.log(chalk6.green(`\u2713 Removed @${username} from team ${team}`));
     } catch (error) {
@@ -1794,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());
@@ -1809,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.3",
+  "version": "0.4.0",
   "description": "Command-line tool for Kernelius Forge - the agent-native Git platform",
   "type": "module",
   "bin": {