Merge branch 'main' into feature/edit-comments

Author: nedtwigg

.claude/agents/corpus-fixer.md

@@ -0,0 +1,39 @@
+---
+name: corpus-fixer
+description: Use this agent when you need to fix or improve the detection logic for a specific Gitcasso corpus by testing changes in the corpus:view development environment. Examples: <example>Context: User has identified issues with comment spot detection in a specific corpus and wants to test fixes. user: 'The comment detection is missing some spots in corpus ABC123, can you help fix the enhancer logic?' assistant: 'I'll use the corpus-fixer agent to investigate and fix the detection issues in that corpus.' <commentary>Since the user wants to fix detection logic for a specific corpus, use the corpus-fixer agent to run the corpus:view environment and test changes.</commentary></example> <example>Context: User wants to validate that recent changes to an enhancer are working correctly. user: 'I made some changes to the GitHub enhancer, can you test it against corpus XYZ789?' assistant: 'Let me use the corpus-fixer agent to test your enhancer changes against that specific corpus.' <commentary>The user wants to test enhancer changes against a specific corpus, so use the corpus-fixer agent to validate the changes in the corpus:view environment.</commentary></example>
+model: inherit
+---
+
+You are an expert Gitcasso corpus debugging specialist with deep knowledge of browser extension development. You operate exclusively within the `browser-extension` directory and specialize in using the corpus:view development environment to diagnose and fix detection logic issues.
+
+Your primary workflow:
+
+1. **Environment Setup**: Always start by reading the documentation at the top of the `corpus-view.ts` file to understand the dev environment.
+
+2. **Launch Development Environment**: Execute `pnpm corpus:view` to bring up the corpus:view development environment. Ensure the environment starts successfully before proceeding.
+
+3. **Browser Navigation**: Use the Playwright MCP to interact with the development environment. Navigate to the specific Gitcasso corpus that needs investigation or fixing.
+
+4. **Code Synchronization**: Always click the button with id `gitcasso-rebuild-btn` to ensure you're testing against the latest code changes. Wait for the rebuild to complete before analyzing results.
+
+5. **Detection Analysis**: Examine the detected spots in the `gitcasso-comment-spots` element. Analyze what spots are being detected, what might be missing, and identify patterns in the detection logic that need improvement.
+
+6. **Enhancer Modification**: Based on your analysis, make targeted changes to the specific enhancer's detection logic. Focus on:
+   - Improving selector accuracy
+   - Handling edge cases in the DOM structure
+   - Optimizing detection algorithms for the specific site pattern
+   - Ensuring compatibility with dynamic content loading
+
+7. **Iterative Testing**: After making changes, rebuild and test again to validate improvements. Continue this cycle until the detection logic works correctly for the target corpus.
+
+8. **Documentation**: Clearly explain what issues you found, what changes you made, and why those changes improve the detection logic.
+
+Key principles:
+- Always work incrementally - make small, targeted changes and test frequently
+- Focus on the specific corpus mentioned by the user unless told otherwise
+- Pay attention to browser console errors and network issues that might affect detection
+- Consider how your changes might impact other sites or corpus entries
+- Be methodical in your debugging approach - document what you try and what results you observe
+- Understand that corpus can be either HAR files (for initial page loads) or HTML snapshots (for post-interaction states)
+
+You have expertise in CSS selectors, DOM manipulation, JavaScript debugging, and understanding how different websites structure their comment systems. Use this knowledge to create robust, reliable detection logic that works across various edge cases.

.claude/commands/finish-wc.md

@@ -0,0 +1,5 @@
+- run `git status` to see the changes in the working copy
+- **figure out the intent of the change**
+- complete whatever tasks are necessary to complete this change
+- make sure that `pnpm precommit` succeeds when you are done
+- don't fix `precommit` by reverting the changes, it is more important to complete the initial change

browser-extension/README.md

@@ -69,17 +69,42 @@ When the `textarea` gets removed from the page, the `TextareaRegistry` is notifi
 ## Testing
 
 - `npm run playground` gives you a test environment where you can tinker with the popup with various test data, supports hot reload
-- `npm run har:view` gives you recordings of various web pages which you can see with and without enhancement by the browser extension
-
-### Recording new HAR files
-
-- the har recordings live in `tests/har`, they are complete recordings of the network requests of a single page load
-- you can add or change URLs in `tests/har-index.ts`
-- `npx playwright codegen https://github.com/login --save-storage=playwright/.auth/gh.json` will store new auth tokens
-  - login manually, then close the browser
-  - ***these cookies are very sensitive! we only run this script using a test account that has no permissions or memberships to anything, recommend you do the same!***
-- `pnpm run har:record` this records new snapshots using those auth tokens (it needs args, run it with no args for docs)
-  - DO NOT COMMIT AND PUSH NEW OR CHANGED `har` files!
-  - we try to sanitize these (see `har-record.ts` for details) but there may be important PII in them
-  - if you need new HAR files for something, let us know and we will generate them ourselves using a dummy account
-  - IF YOUR PR CHANGES OR ADDS HAR FILES WE WILL CLOSE IT. Ask for HAR files and we'll be happy to generate clean ones you can test against.
+- `npm run corpus:view` gives you recordings of various web pages which you can see with and without enhancement by the browser extension
+
+### Test Corpus
+
+We maintain a corpus of test pages in two formats for testing the browser extension:
+
+#### HAR Corpus (Automated)
+
+- For testing initial page loads and network requests
+- HAR recordings live in `tests/corpus/har/`, complete recordings of the network requests of a single page load
+- You can add or change URLs in `tests/corpus/_corpus-index.ts`
+- **Recording new HAR files:**
+  - `npx playwright codegen https://github.com/login --save-storage=playwright/.auth/gh.json` will store new auth tokens
+    - login manually, then close the browser
+    - ***these cookies are very sensitive! we only run this script using a test account that has no permissions or memberships to anything, recommend you do the same!***
+  - `pnpm run corpus:record:har` records new HAR files using those auth tokens (it needs args, run it with no args for docs)
+    - DO NOT COMMIT AND PUSH NEW OR CHANGED HAR files!
+    - we try to sanitize these (see `har-record.ts` for details) but there may be important PII in them
+    - if you need new HAR files for something, let us know and we will generate them ourselves using a dummy account
+    - IF YOUR PR CHANGES OR ADDS HAR FILES WE WILL CLOSE IT. Ask for HAR files and we'll be happy to generate clean ones you can test against.
+
+#### HTML Corpus (Manual)
+
+- For testing post-interaction states (e.g., expanded textareas, modal dialogs, dynamic content)
+- HTML snapshots live in `tests/corpus/html/`, manually captured using SingleFile browser extension
+- All assets are inlined in a single HTML file by SingleFile
+- **Creating new HTML corpus files:**
+  1. Navigate to the desired page state (click buttons, expand textareas, etc.)
+  2. Use SingleFile browser extension to save the complete page
+  3. Save the `.html` file to `tests/corpus/html/` with a descriptive name
+  4. Add an entry to `tests/corpus/_corpus-index.ts` with `type: 'html'` and a description of the captured state
+
+#### Viewing Corpus Files
+
+- Run `pnpm run corpus:view` to start the test server at http://localhost:3001
+- Select any corpus file to view in two modes:
+  - **Clean**: Original page without extension
+  - **Gitcasso**: Page with extension injected for testing
+- Both HAR and HTML corpus types are supported

browser-extension/package.json

@@ -62,8 +62,8 @@
     "test": "vitest run",
     "playground": "vite --config vite.playground.config.ts",
     "playground:build": "vite build --config vite.playground.config.ts",
-    "har:record": "tsx tests/har-record.ts",
-    "har:view": "tsx tests/har-view.ts"
+    "corpus:record:har": "tsx tests/har-record.ts",
+    "corpus:view": "tsx tests/corpus-view.ts"
   },
   "type": "module",
   "version": "0.0.1"

browser-extension/src/entrypoints/content.ts

@@ -1,11 +1,26 @@
 import { CONFIG } from '../lib/config'
-import type { CommentEvent, CommentSpot } from '../lib/enhancer'
+import type { CommentEvent, CommentSpot, StrippedLocation } from '../lib/enhancer'
 import { logger } from '../lib/logger'
 import { EnhancerRegistry, TextareaRegistry } from '../lib/registries'
 
 const enhancers = new EnhancerRegistry()
 const enhancedTextareas = new TextareaRegistry()
 
+// Expose for debugging in har:view
+;(window as any).gitcassoTextareaRegistry = enhancedTextareas
+
+function detectLocation(): StrippedLocation {
+  if ((window as any).gitcassoMockLocation) {
+    return (window as any).gitcassoMockLocation
+  }
+  const result = {
+    host: window.location.host,
+    pathname: window.location.pathname,
+  }
+  logger.debug('[gitcasso] detectLocation called, returning:', result)
+  return result
+}
+
 function sendEventToBackground(type: 'ENHANCED' | 'DESTROYED', spot: CommentSpot): void {
   const message: CommentEvent = {
     spot,
@@ -23,6 +38,7 @@ enhancedTextareas.setEventHandlers(
 
 export default defineContentScript({
   main() {
+    logger.debug('Main was called')
     const textAreasOnPageLoad = document.querySelectorAll<HTMLTextAreaElement>(`textarea`)
     for (const textarea of textAreasOnPageLoad) {
       enhanceMaybe(textarea)
@@ -32,7 +48,7 @@ export default defineContentScript({
       childList: true,
       subtree: true,
     })
-    logger.debug('Extension loaded with', enhancers.getEnhancerCount, 'handlers')
+    logger.debug('Extension loaded with', enhancers.getEnhancerCount(), 'handlers')
   },
   matches: ['<all_urls>'],
   runAt: 'document_end',
@@ -77,24 +93,29 @@ function handleMutations(mutations: MutationRecord[]): void {
 }
 
 function enhanceMaybe(textarea: HTMLTextAreaElement) {
+  logger.debug('[gitcasso] enhanceMaybe called for textarea:', textarea.id, textarea.className)
   if (enhancedTextareas.get(textarea)) {
     logger.debug('textarea already registered {}', textarea)
     return
   }
 
-  logger.debug('activating textarea {}', textarea)
   injectStyles()
-
-  const enhancedTextarea = enhancers.tryToEnhance(textarea)
-  if (enhancedTextarea) {
-    logger.debug(
-      'Identified textarea:',
-      enhancedTextarea.spot.type,
-      enhancedTextarea.spot.unique_key,
-    )
-    enhancedTextareas.register(enhancedTextarea)
-  } else {
-    logger.debug('No handler found for textarea')
+  try {
+    const location = detectLocation()
+    logger.debug('[gitcasso] Calling tryToEnhance with location:', location)
+    const enhancedTextarea = enhancers.tryToEnhance(textarea, location)
+    if (enhancedTextarea) {
+      logger.debug(
+        'Identified textarea:',
+        enhancedTextarea.spot.type,
+        enhancedTextarea.spot.unique_key,
+      )
+      enhancedTextareas.register(enhancedTextarea)
+    } else {
+      logger.debug('No handler found for textarea')
+    }
+  } catch (e) {
+    logger.error(e)
   }
 }
 

browser-extension/src/lib/config.ts

@@ -9,6 +9,6 @@ export type LogLevel = (typeof LOG_LEVELS)[number]
 export const CONFIG = {
   ADDED_OVERTYPE_CLASS: 'gitcasso-overtype',
   EXTENSION_NAME: 'gitcasso', // decorates logs
-  LOG_LEVEL: 'INFO' satisfies LogLevel,
+  LOG_LEVEL: 'DEBUG' satisfies LogLevel,
   MODE: 'PROD' satisfies ModeType,
 } as const

browser-extension/src/lib/enhancer.ts

@@ -19,6 +19,15 @@ export interface CommentEvent {
   draft?: string
 }
 
+/**
+ * Minimal location information that enhancers need for routing decisions.
+ * Avoids dependency on global window/location objects for better testability.
+ */
+export interface StrippedLocation {
+  host: string
+  pathname: string
+}
+
 /** Wraps the textareas of a given platform with Gitcasso's enhancements. */
 export interface CommentEnhancer<Spot extends CommentSpot = CommentSpot> {
   /** Guarantees to only return a type within this list. */
@@ -27,7 +36,7 @@ export interface CommentEnhancer<Spot extends CommentSpot = CommentSpot> {
    * Whenever a new `textarea` is added to any webpage, this method is called.
    * If we return non-null, then we become the handler for that text area.
    */
-  tryToEnhance(textarea: HTMLTextAreaElement): Spot | null
+  tryToEnhance(textarea: HTMLTextAreaElement, location: StrippedLocation): Spot | null
   /** This gets called the first time that `tryToEnhance` returns non-null. */
   prepareForFirstEnhancement(): void
   /**

browser-extension/src/lib/enhancers/CommentEnhancerMissing.tsx

@@ -1,6 +1,6 @@
 import type { OverTypeInstance } from 'overtype'
 import type { ReactNode } from 'react'
-import type { CommentEnhancer, CommentSpot } from '../enhancer'
+import type { CommentEnhancer, CommentSpot, StrippedLocation } from '../enhancer'
 
 /** Used when an entry is in the table which we don't recognize. */
 export class CommentEnhancerMissing implements CommentEnhancer {
@@ -40,7 +40,7 @@ export class CommentEnhancerMissing implements CommentEnhancer {
   forSpotTypes(): string[] {
     throw new Error('Method not implemented.')
   }
-  tryToEnhance(_textarea: HTMLTextAreaElement): CommentSpot | null {
+  tryToEnhance(_textarea: HTMLTextAreaElement, _location: StrippedLocation): CommentSpot | null {
     throw new Error('Method not implemented.')
   }
   prepareForFirstEnhancement(): void {

browser-extension/src/lib/enhancers/github/githubIssueAddComment.tsx

@@ -1,7 +1,7 @@
 import { IssueOpenedIcon } from '@primer/octicons-react'
 import OverType, { type OverTypeInstance } from 'overtype'
 import type React from 'react'
-import type { CommentEnhancer, CommentSpot } from '@/lib/enhancer'
+import type { CommentEnhancer, CommentSpot, StrippedLocation } from '@/lib/enhancer'
 import { logger } from '@/lib/logger'
 import { modifyDOM } from '../modifyDOM'
 import { commonGithubOptions } from './ghOptions'
@@ -20,24 +20,31 @@ export class GitHubIssueAddCommentEnhancer implements CommentEnhancer<GitHubIssu
     return ['GH_ISSUE_ADD_COMMENT']
   }
 
-  tryToEnhance(_textarea: HTMLTextAreaElement): GitHubIssueAddCommentSpot | null {
-    if (document.querySelector('meta[name="hostname"]')?.getAttribute('content') !== 'github.com') {
+  tryToEnhance(
+    textarea: HTMLTextAreaElement,
+    location: StrippedLocation,
+  ): GitHubIssueAddCommentSpot | null {
+    if (textarea.id === 'feedback') {
+      return null
+    }
+    if (location.host !== 'github.com') {
       return null
     }
 
     // Parse GitHub URL structure: /owner/repo/issues/123 or /owner/repo/pull/456
-    logger.debug(`${this.constructor.name} examing url`, window.location.pathname)
+    logger.debug(`${this.constructor.name} examing url`, location.pathname)
 
-    const match = window.location.pathname.match(/^\/([^/]+)\/([^/]+)(?:\/issues\/(\d+))/)
-    logger.debug(`${this.constructor.name} found match`, window.location.pathname)
+    const match = location.pathname.match(/^\/([^/]+)\/([^/]+)(?:\/issues\/(\d+))/)
+    logger.debug(`${this.constructor.name} found match`, location.pathname)
     if (!match) return null
+
     const [, owner, repo, numberStr] = match
     const slug = `${owner}/${repo}`
     const number = parseInt(numberStr!, 10)
     const unique_key = `github.com:${slug}:${number}`
     const title = 'TODO_TITLE'
     return {
-      domain: 'github.com',
+      domain: location.host,
       number,
       slug,
       title,

browser-extension/src/lib/enhancers/github/githubIssueNewComment.tsx

@@ -1,5 +1,5 @@
 import OverType, { type OverTypeInstance } from 'overtype'
-import type { CommentEnhancer, CommentSpot } from '../../enhancer'
+import type { CommentEnhancer, CommentSpot, StrippedLocation } from '../../enhancer'
 import { logger } from '../../logger'
 import { modifyDOM } from '../modifyDOM'
 import { commonGithubOptions } from './ghOptions'
@@ -16,23 +16,26 @@ export class GitHubIssueNewCommentEnhancer implements CommentEnhancer<GitHubIssu
     return ['GH_ISSUE_NEW_COMMENT']
   }
 
-  tryToEnhance(_textarea: HTMLTextAreaElement): GitHubIssueNewCommentSpot | null {
-    if (document.querySelector('meta[name="hostname"]')?.getAttribute('content') !== 'github.com') {
+  tryToEnhance(
+    _textarea: HTMLTextAreaElement,
+    location: StrippedLocation,
+  ): GitHubIssueNewCommentSpot | null {
+    if (location.host !== 'github.com') {
       return null
     }
 
     // Parse GitHub URL structure: /owner/repo/issues/123 or /owner/repo/pull/456
-    logger.debug(`${this.constructor.name} examing url`, window.location.pathname)
+    logger.debug(`${this.constructor.name} examing url`, location.pathname)
 
-    const match = window.location.pathname.match(/^\/([^/]+)\/([^/]+)(?:\/issues\/new)/)
-    logger.debug(`${this.constructor.name} found match`, window.location.pathname)
+    const match = location.pathname.match(/^\/([^/]+)\/([^/]+)(?:\/issues\/new)/)
+    logger.debug(`${this.constructor.name} found match`, location.pathname)
 
     if (!match) return null
     const [, owner, repo] = match
     const slug = `${owner}/${repo}`
     const unique_key = `github.com:${slug}:new`
     return {
-      domain: 'github.com',
+      domain: location.host,
       slug,
       type: 'GH_ISSUE_NEW_COMMENT',
       unique_key,