Merge development into main

.cspell.json

@@ -4,7 +4,7 @@
   "ignorePaths": ["**/*.json", "**/*.css", "node_modules", "**/*.log"],
   "useGitignore": true,
   "language": "en",
-  "words": ["dataurl", "devpool", "fkey", "outdir", "servedir", "supabase", "typebox", "ubiquibot", "smee", "tomlify"],
+  "words": ["dataurl", "devpool", "fkey", "mswjs", "outdir", "servedir", "supabase", "typebox", "ubiquibot", "smee", "tomlify"],
   "dictionaries": ["typescript", "node", "software-terms"],
   "import": ["@cspell/dict-typescript/cspell-ext.json", "@cspell/dict-node/cspell-ext.json", "@cspell/dict-software-terms"],
   "ignoreRegExpList": ["[0-9a-fA-F]{6}"]

.github/knip.ts

@@ -3,9 +3,9 @@ import type { KnipConfig } from "knip";
 const config: KnipConfig = {
   entry: ["src/worker.ts"],
   project: ["src/**/*.ts"],
-  ignoreBinaries: ["build", "i", "format:cspell", "awk", "lsof"],
+  ignoreBinaries: ["i"],
   ignoreExportsUsedInFile: true,
-  ignoreDependencies: ["@mswjs/data", "esbuild", "eslint-config-prettier", "eslint-plugin-prettier"],
+  ignoreDependencies: ["@mswjs/data", "esbuild", "eslint-config-prettier", "eslint-plugin-prettier", "msw"],
 };
 
 export default config;

.github/workflows/build.yml

@@ -30,11 +30,13 @@ jobs:
           bun setup-kv
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 
       - uses: cloudflare/wrangler-action@v3
         with:
-          wranglerVersion: '3.57.0'
+          wranglerVersion: "3.57.0"
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           secrets: |
             WEBHOOK_PROXY_URL
             WEBHOOK_SECRET

.github/workflows/bun-testing.yml

@@ -2,7 +2,7 @@ name: Run Bun testing suite
 on:
   workflow_dispatch:
   pull_request:
-    types: [ opened, synchronize ]
+    types: [opened, synchronize]
 
 env:
   NODE_ENV: "test"
@@ -18,7 +18,7 @@ jobs:
       - uses: oven-sh/setup-bun@v1
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.10.0'
+          node-version: "20.10.0"
       - uses: actions/checkout@master
         with:
           fetch-depth: 0

.github/workflows/cspell.yml → .github/workflows/format.yml

@@ -1,11 +1,11 @@
-name: Spell Check
+name: Format Checks
 
 on:
   push:
 
 jobs:
-  spellcheck:
-    name: Check for spelling errors
+  formatCheck:
+    name: Check for formatting issues
     runs-on: ubuntu-latest
 
     steps:
@@ -17,8 +17,10 @@ jobs:
         with:
           node-version: "20.10.0"
 
-      - name: Install bun & CSpell
-        run: npm i -g bun cspell
+      - uses: oven-sh/setup-bun@v1
 
-      - name: Run cspell
-        run: bun format:cspell
+      - name: Install deps
+        run: bun i
+
+      - name: Run checks
+        run: bun format

.github/workflows/knip-reporter.yml

@@ -0,0 +1,38 @@
+name: Knip-reporter
+
+on:
+  workflow_run:
+    workflows: ["Knip"]
+    types:
+      - completed
+
+jobs:
+  knip-reporter:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion != 'success' }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: knip-results
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Read pr number
+        id: pr-number
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./pr-number.txt
+          trim: true
+
+      - name: Report knip results to pull request
+        uses: gitcoindev/knip-reporter@main
+        with:
+          verbose: true
+          comment_id: ${{ github.workflow }}-reporter
+          command_script_name: knip-ci
+          annotations: true
+          ignore_results: false
+          json_input: true
+          json_input_file_name: knip-results.json
+          pull_request_number: ${{ steps.pr-number.outputs.content }}
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/knip.yml

@@ -1,10 +1,7 @@
 name: Knip
 
 on:
-  pull_request_target:
-  workflow_dispatch:
-
-permissions: write-all
+  pull_request:
 
 jobs:
   run-knip:
@@ -23,11 +20,17 @@ jobs:
           npm i -g bun
           bun install
 
-      - name: Report knip results to pull request
-        uses: Codex-/knip-reporter@v2
+      - name: Store PR number
+        run: echo ${{ github.event.number }} > pr-number.txt
+
+      - name: Run Knip
+        run: bun knip || bun knip --reporter json > knip-results.json
+
+      - name: Upload knip result
+        if: failure()
+        uses: actions/upload-artifact@v4
         with:
-          verbose: true
-          comment_id: ${{ github.workflow }}-reporter
-          command_script_name: knip-ci
-          annotations: true
-          ignore_results: false
+          name: knip-results
+          path: |
+            knip-results.json
+            pr-number.txt

README.md

@@ -1,4 +1,3 @@
-
 # @ubiquity/ubiquibot-kernel
 
 The kernel is designed to:
@@ -11,11 +10,11 @@ The kernel is designed to:
 - **`PRIVATE_KEY`**
   Obtain a private key from your GitHub App settings and convert it to the Public-Key Cryptography Standards #8 (PKCS#8) format. Use the following command to perform this conversion and append the result to your `.dev.vars` file:
 
-    ```sh
-    echo "PRIVATE_KEY=\"$(openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in YOUR_PRIVATE_KEY.PEM | awk 'BEGIN{ORS="\\n"} 1')\"" >> .dev.vars
-    ```
+  ```sh
+  echo "PRIVATE_KEY=\"$(openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in YOUR_PRIVATE_KEY.PEM | awk 'BEGIN{ORS="\\n"} 1')\"" >> .dev.vars
+  ```
 
-    **Note:** Replace `YOUR_PRIVATE_KEY.PEM` with the path to your actual PEM file when running the command.
+  **Note:** Replace `YOUR_PRIVATE_KEY.PEM` with the path to your actual PEM file when running the command.
 
 - **`WEBHOOK_SECRET`**
   Set this value in both your GitHub App settings and here.
@@ -26,7 +25,6 @@ The kernel is designed to:
 - **`WEBHOOK_PROXY_URL` (only for development)**
   Obtain a webhook URL at [smee.io](https://smee.io/) and set it in your GitHub App settings.
 
-
 ### Quick Start
 
 ```bash
@@ -39,31 +37,38 @@ bun dev
 ### Deploying to Cloudflare Workers
 
 1. **Install Dependencies:**
+
    - Execute `bun install` to install the required dependencies.
 
 2. **Create a Github App:**
+
    - Generate a Github App and configure its settings.
    - Navigate to app settings and click `Permissions & events`.
    - Ensure the app is subscribed to all events with the following permissions:
 
      Repository permissions:
+
      - Actions: Read & Write
      - Contents: Read & Write
      - Issues: Read & Write
      - Pull Requests: Read & Write
 
      Organization permissions:
+
      - Members: Read only
 
 3. **Cloudflare Account Setup:**
+
    - If not done already, create a Cloudflare account.
    - Run `npx wrangler login` to log in.
 
 4. **Create a KV Namespace:**
+
    - Generate a KV namespace using `npx wrangler kv:namespace create PLUGIN_CHAIN_STATE`.
    - Copy the generated ID and paste it under `[env.dev]` in `wrangler.toml`.
 
 5. **Manage Secrets:**
+
    - Add (env) secrets using `npx wrangler secret put <KEY> --env dev`.
    - For the private key, execute the following (replace `YOUR_PRIVATE_KEY.PEM` with the actual PEM file path):
 
@@ -97,7 +102,9 @@ Example usage:
 const input: PluginInput = {
   stateId: "abc123",
   eventName: "issue_comment.created",
-  eventPayload: { /* ... */ },
+  eventPayload: {
+    /* ... */
+  },
   settings: '{ "key": "value" }',
   authToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
   ref: "refs/heads/main",
@@ -126,6 +133,45 @@ const output: PluginOutput = {
 };
 ```
 
+## Plugin Quick Start
+
+The kernel supports 2 types of plugins:
+
+1. Github actions ([wiki](https://github.com/ubiquity/ubiquibot-kernel/wiki/How-it-works))
+2. Cloudflare Workers (which are simple backend servers with a single API route)
+
+How to run a "hello-world" plugin the Cloudflare way:
+
+1. Run `bun dev` to spin up the kernel
+2. Run `bun plugin:hello-world` to spin up a local server for the "hello-world" plugin
+3. Update the bot's config file in the repository where you use the bot (`OWNER/REPOSITORY/.github/.ubiquibot-config.yml`):
+
+```
+plugins:
+  'issue_comment.created':
+    - name: "hello-world-plugin name"
+      description: "hello-world-plugin description"
+      command: "/hello"
+      example: "/hello example"
+      skipBotEvents: true
+      uses:
+      # hello-world-plugin
+      - plugin: http://127.0.0.1:9090
+        type: github
+        with:
+          response: world
+```
+
+4. Post a `/hello` comment in any issue
+5. The bot should respond with the `world` message ([example](https://github.com/rndquu-org/test-repo/issues/54#issuecomment-2149313139))
+
+How it works:
+
+1. When you post the `/hello` command the kernel receives the `issue_comment.created` event
+2. The kernel matches the `/hello` command to the plugin that should be executed (i.e. the API method that should be called)
+3. The kernel passes github event payload, bot's access token and plugin settings (from `.ubiquibot-config.yml`) to the plugin endpoint
+4. The plugin performs all of the required actions and returns the result
+
 ## Testing
 
 ### Jest

deploy/setup_kv_namespace.ts → deploy/setup-kv-namespace.ts

@@ -77,13 +77,15 @@ async function main() {
   let namespaceId: string;
   try {
     const res = execSync(`wrangler kv:namespace create ${NAMESPACE_TITLE}`).toString();
+    console.log(res);
     const newId = res.match(/id = \s*"([^"]+)"/)?.[1];
     if (!newId) {
       throw new Error(`The new ID could not be found.`);
     }
     namespaceId = newId;
     console.log(`Namespace created with ID: ${namespaceId}`);
   } catch (error) {
+    console.error(error);
     const listOutput = JSON.parse(execSync(`wrangler kv:namespace list`).toString()) as Namespace[];
     const existingNamespace = listOutput.find((o) => o.title === NAMESPACE_TITLE_WITH_PREFIX);
     if (!existingNamespace) {
@@ -99,6 +101,6 @@ async function main() {
 main()
   .then(() => console.log("Successfully bound namespace."))
   .catch((e) => {
-    console.error("Error checking or creating namespace:", e);
+    console.error("Error checking or creating namespace:\n", e);
     process.exit(1);
   });