Merge pull request #163 from mean-weasel/fix/issue-162-local-self-hosting-config

fix: avoid tracked local self-hosting config edits

Author: neonwatty

.dev.vars.example

@@ -29,6 +29,7 @@ YOUR_PRIVATE_KEY_CONTENT_HERE
 
 # Your GitHub App's URL slug (the name in lowercase with hyphens)
 # Find it at: https://github.com/apps/YOUR_APP_NAME
+# Local development should override the committed wrangler.toml default here instead of editing wrangler.toml.
 # GITHUB_APP_NAME=my-bugdrop-app
 
 # Allowed origins for CORS (comma-separated, or "*" for all)
@@ -37,3 +38,6 @@ YOUR_PRIVATE_KEY_CONTENT_HERE
 
 # Maximum screenshot size in MB
 # MAX_SCREENSHOT_SIZE_MB=5
+
+# RATE_LIMIT is intentionally not configured here.
+# Local development runs with ENVIRONMENT=development and can work without a KV namespace.

.gitignore

@@ -13,6 +13,9 @@ public/versions.json
 # Local secrets (NEVER commit)
 .dev.vars
 
+# Local self-hosting test page override
+public/test/local-config.js
+
 # Private keys (NEVER commit)
 *.pem
 private-key*.pem
@@ -29,6 +32,7 @@ private-key*.pem
 .plans/
 .superpowers/
 .playwright-mcp/
+docs/superpowers/
 
 # OS files
 .DS_Store

SELF_HOSTING.md

@@ -43,24 +43,32 @@ GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
 -----END RSA PRIVATE KEY-----"
 ```
 
-Next, update `wrangler.toml` with your app name and remove the upstream KV namespace IDs:
+Next, keep local configuration in ignored files so your fork does not accumulate noisy diffs.
 
-```toml
-[vars]
-GITHUB_APP_NAME = "your-app-name"  # Must match your GitHub App's URL slug
+In `.dev.vars`, uncomment and set your GitHub App slug:
 
-# Remove or replace the [[kv_namespaces]] section (and the
-# [[env.preview.kv_namespaces]] section) — the existing IDs belong
-# to the upstream deployment. See Step 5 to create your own,
-# or delete both sections entirely to disable rate limiting.
+```bash
+GITHUB_APP_NAME=your-app-name
 ```
 
-> **Note:** The test pages under `public/test/` have `data-repo` set to `mean-weasel/bugdrop-widget-test`. Change this in all test HTML files to a repo where your GitHub App is installed:
->
-> ```bash
-> # macOS / BSD sed
-> find public/test -name '*.html' -exec sed -i '' 's/mean-weasel\/bugdrop-widget-test/your-org\/your-repo/g' {} +
-> ```
+The committed `wrangler.toml` contains the upstream development defaults used by this repository. For local development, prefer `.dev.vars` overrides instead of editing `wrangler.toml`.
+
+If you want the local test pages under `/test/` to submit to a repository where your GitHub App is installed, copy the local test config example:
+
+```bash
+cp public/test/local-config.example.js public/test/local-config.js
+```
+
+Then edit `public/test/local-config.js`:
+
+```js
+window.BugDropTestConfig = {
+  ...(window.BugDropTestConfig || {}),
+  repo: 'your-org/your-repo',
+};
+```
+
+`public/test/local-config.js` is ignored by git. Without it, test pages keep using the upstream test repository `mean-weasel/bugdrop-widget-test`, which is what CI expects.
 
 ## 3. Build the Widget
 
@@ -83,15 +91,19 @@ Visit http://localhost:8787/test/ to try the widget.
 
 Rate limiting prevents spam and protects GitHub API quotas. It uses Cloudflare KV for distributed storage.
 
-> **Important:** The `[[kv_namespaces]]` IDs in `wrangler.toml` belong to the upstream deployment and will not work for your account. You must create your own namespaces below, or remove the section to disable rate limiting.
+> **Important:** The `[[kv_namespaces]]` IDs in `wrangler.toml` belong to the upstream deployment and will not work for your account.
+
+For local development, you can leave rate limiting unconfigured. BugDrop disables rate limiting when no `RATE_LIMIT` binding is present.
+
+For production, create your own KV namespaces and update your deployment configuration with the IDs from Wrangler. Do not reuse the upstream IDs committed in this repository.
 
 ```bash
 # Create KV namespaces
 npx wrangler kv:namespace create RATE_LIMIT
 npx wrangler kv:namespace create RATE_LIMIT --preview
 ```
 
-Copy the IDs from the output and update `wrangler.toml`:
+Copy the IDs from the output and update your production deployment configuration:
 
 ```toml
 [[kv_namespaces]]

docs/website/self-hosting.mdx

@@ -35,7 +35,8 @@ You need to create your own GitHub App to replace the hosted BugDrop app. The ap
 | **Webhook** | Not required (optional) |
 | **Installation scope** | Your repositories |
 
-You will need the App ID, private key, and installation ID to configure the Worker.
+You will need the App ID and private key to configure the Worker. BugDrop discovers the
+installation for each repository at request time.
 
 ## Architecture Overview
 
@@ -60,15 +61,15 @@ The Cloudflare Worker acts as a secure proxy between the user's browser and the
 
 ## Setup Instructions
 
-Full self-hosting instructions, including environment variables, Wrangler configuration, and deployment steps, are available in the repository:
+Full self-hosting instructions, including environment variables, ignored local configuration, and deployment steps, are available in the repository:
 
 **[SELF_HOSTING.md on GitHub](https://github.com/mean-weasel/bugdrop/blob/main/SELF_HOSTING.md)**
 
 The guide covers:
 
 1. **Forking the repository** -- Get your own copy of the BugDrop codebase
 2. **Creating a GitHub App** -- Step-by-step instructions for creating and configuring the app
-3. **Configuring Wrangler** -- Setting up `wrangler.toml` with your account details
+3. **Configuring local overrides** -- Using ignored `.dev.vars` and `public/test/local-config.js` files so your fork stays clean
 4. **Setting secrets** -- Storing your GitHub App credentials as Worker secrets
 5. **Deploying** -- Publishing the Worker to your Cloudflare account
 6. **Testing** -- Verifying the deployment works end-to-end

e2e/widget.spec.ts

@@ -1,3 +1,5 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
 import { test, expect, type Page } from '@playwright/test';
 
 /**
@@ -39,6 +41,109 @@ test.describe('Widget Loading', () => {
     const button = page.locator('#bugdrop-host').locator('css=.bd-trigger');
     await expect(button).toBeVisible();
   });
+
+  test('missing local test config returns an empty script', async ({ page }) => {
+    const response = await page.request.get('/test/local-config.js');
+
+    expect(response.status()).toBe(200);
+    expect(response.headers()['content-type']).toContain('application/javascript');
+    expect(await response.text()).toBe('');
+  });
+
+  test('test pages use upstream repo when no local override is present', async ({ page }) => {
+    await page.route('**/test/local-config.js', route => {
+      return route.fulfill({ status: 404 });
+    });
+
+    await page.goto('/test/');
+
+    const widgetScript = page.locator('script[src="/widget.js"]');
+    await expect(widgetScript).toBeAttached();
+
+    const repo = await widgetScript.evaluate(script => {
+      return (script as HTMLScriptElement).dataset.repo;
+    });
+
+    expect(repo).toBe('mean-weasel/bugdrop-widget-test');
+  });
+
+  test('test pages use local repo override when configured', async ({ page }) => {
+    await page.route('**/test/local-config.js', route => {
+      return route.fulfill({
+        contentType: 'application/javascript',
+        body: `
+          window.BugDropTestConfig = {
+            ...(window.BugDropTestConfig || {}),
+            repo: 'local-owner/local-repo',
+          };
+        `,
+      });
+    });
+
+    await page.goto('/test/');
+
+    const widgetScript = page.locator('script[src="/widget.js"]');
+    await expect(widgetScript).toBeAttached();
+
+    const repo = await widgetScript.evaluate(script => {
+      return (script as HTMLScriptElement).dataset.repo;
+    });
+
+    expect(repo).toBe('local-owner/local-repo');
+  });
+
+  test('non-index test pages use local repo override when configured', async ({ page }) => {
+    await page.route('**/test/local-config.js', route => {
+      return route.fulfill({
+        contentType: 'application/javascript',
+        body: `
+          window.BugDropTestConfig = {
+            ...(window.BugDropTestConfig || {}),
+            repo: 'local-owner/local-repo',
+          };
+        `,
+      });
+    });
+
+    await page.goto('/test/color-default.html');
+
+    const widgetScript = page.locator('script[src="/widget.js"]');
+    await expect(widgetScript).toBeAttached();
+
+    const repo = await widgetScript.evaluate(script => {
+      return (script as HTMLScriptElement).dataset.repo;
+    });
+
+    expect(repo).toBe('local-owner/local-repo');
+  });
+
+  test('widget test fixtures use shared local config loader', async () => {
+    const fixtureDir = join(process.cwd(), 'public', 'test');
+    const fixtureNames = (await readdir(fixtureDir)).filter(name => name.endsWith('.html'));
+    const nonWidgetFixtures = new Set(['pull-tab-mock.html']);
+
+    for (const fixtureName of fixtureNames) {
+      const source = await readFile(join(fixtureDir, fixtureName), 'utf8');
+      const directWidgetScript = /<script\b(?=[^>]*\bsrc=["']\/widget\.js["'])/i.test(source);
+
+      expect(
+        directWidgetScript,
+        `${fixtureName} should load the widget through load-widget.js`
+      ).toBe(false);
+      expect(source, `${fixtureName} should not hard-code the upstream test repo`).not.toContain(
+        'data-repo="mean-weasel/bugdrop-widget-test"'
+      );
+
+      if (!nonWidgetFixtures.has(basename(fixtureName))) {
+        expect(source, `${fixtureName} should include the shared test loader`).toContain(
+          'src="/test/load-widget.js"'
+        );
+        expect(source, `${fixtureName} should call the shared test loader`).toContain(
+          'loadBugDropTestWidget'
+        );
+      }
+    }
+  });
 });
 
 test.describe('Widget Interaction', () => {

public/test/annotation-preview-size.html

@@ -61,6 +61,15 @@ <h1>Widget</h1>
     <div class="row">Object: example.company/feature/preview</div>
   </main>
 
-  <script id="bugdrop-script" defer src="/widget.js" data-repo="mean-weasel/bugdrop-widget-test" data-theme="dark" data-color="#ff9e64"></script>
+  <script src="/test/load-widget.js"></script>
+  <script>
+    window.loadBugDropTestWidget({
+      id: 'bugdrop-script',
+      dataset: {
+        theme: 'dark',
+        color: '#ff9e64',
+      },
+    });
+  </script>
 </body>
 </html>

public/test/annotation-small-wide-area.html

@@ -33,6 +33,15 @@
 <body>
   <div id="small-wide-target" class="field-label">Settlement Stage</div>
 
-  <script id="bugdrop-script" defer src="/widget.js" data-repo="mean-weasel/bugdrop-widget-test" data-theme="dark" data-color="#ff9e64"></script>
+  <script src="/test/load-widget.js"></script>
+  <script>
+    window.loadBugDropTestWidget({
+      id: 'bugdrop-script',
+      dataset: {
+        theme: 'dark',
+        color: '#ff9e64',
+      },
+    });
+  </script>
 </body>
 </html>

public/test/annotation-style.html

@@ -123,13 +123,15 @@ <h1>Shipmen Overview</h1>
       </section>
     </main>
 
-    <script
-      id="bugdrop-script"
-      defer
-      src="/widget.js"
-      data-repo="mean-weasel/bugdrop-widget-test"
-      data-theme="dark"
-      data-color="#ff9e64"
-    ></script>
+    <script src="/test/load-widget.js"></script>
+    <script>
+      window.loadBugDropTestWidget({
+        id: 'bugdrop-script',
+        dataset: {
+          theme: 'dark',
+          color: '#ff9e64',
+        },
+      });
+    </script>
   </body>
 </html>

public/test/api-only.html

@@ -197,7 +197,12 @@ <h2>Usage Example</h2>
   </script>
 
   <!-- BugDrop widget in API-only mode (no floating button) -->
-  <script src="/widget.js" data-repo="test/repo" data-button="false"></script>
+  <script src="/test/load-widget.js"></script>
+  <script>
+    window.loadBugDropTestWidget({
+      dataset: { button: 'false' },
+    });
+  </script>
 
   <script>
     // Check if BugDrop already initialized (in case the event fired before our listener)

public/test/color-custom.html

@@ -39,6 +39,14 @@ <h1>Custom Color Test</h1>
   </div>
 
   <!-- Load BugDrop WITH custom purple color -->
-  <script src="/widget.js" data-repo="mean-weasel/bugdrop-widget-test" data-theme="dark" data-color="#9333EA"></script>
+  <script src="/test/load-widget.js"></script>
+  <script>
+    window.loadBugDropTestWidget({
+      dataset: {
+        theme: 'dark',
+        color: '#9333EA',
+      },
+    });
+  </script>
 </body>
 </html>