Skip to content

dev.md

Latest commit

 

History

History
236 lines (169 loc) · 7.98 KB

dev.md

File metadata and controls

236 lines (169 loc) · 7.98 KB
Raw

Development

Prerequisites

  • Babashka (bb)
  • Node.js (for npm dependencies)

Setup

npm install

Local Development Workflow

Start the development environment:

If you are using VS Code:

  1. Run the default build task (Cmd/Ctrl+Shift+B) - starts Squint watch, unit test watcher, and Scittle Dev REPL
  2. Start Squint nREPL: bb squint-nrepl (or run the "Squint nREPL" VS Code task)
  3. Connect your editor to the Squint nREPL (port 1337)
    • Calva: "Connect to a running REPL" -> select "squint"

VS Code tasks (defined in .vscode/tasks.json):

  • Start Dev Environment (default build) - runs Squint watch, test:watch, and Scittle Dev REPL in parallel
  • Squint nREPL - starts the Squint nREPL server on port 1337
  • Scittle Dev REPL - starts the browser-nrepl relay (ports 31337/31338)

Manual alternative (separate terminals):

bb watch        # Terminal 1: Auto-compile on save
bb test:watch   # Terminal 2: Unit test watcher
bb squint-nrepl # Terminal 3: Squint nREPL

The Squint REPL lets you evaluate code in a Node.js environment, useful for testing pure functions that do not need the browser execution environment. See the epupp-squint skill for details.

Scittle Dev REPL

For experimenting with Scittle code (the runtime used in browser pages), the project includes a Joyride-based setup for connecting a Scittle repl, named scittle-dev-repl:

  1. Automatic setup: The Joyride workspace activation script (.joyride/scripts/workspace_activate.cljs) automatically:

    • Starts the browser-nrepl relay if not already running
    • Opens a Calva Flare webview with Scittle + nREPL client
    • Prompts to connect Calva

  2. Manual setup: Run the Joyride script directly:

    • Joyride: Run Workspace Script -> scittle_repl.cljs
    • Or connect Calva using "Scittle Dev REPL" sequence (port 31337)

Ports:

  • nREPL: 31337
  • WebSocket: 31338

The Scittle REPL runs in a VS Code webview, providing a browser-like environment for testing Scittle code before deploying to actual web pages.

Documentation Maintenance

For architecture and behavior drift sweeps, use the Documentation Ground Truth Sweep Checklist.

Testing

Unit Tests

Run unit tests once:

bb test

Compile only (no tests), pass Squint args directly:

bb squint-compile src/log.cljs
bb squint-compile --paths src test --output-dir build/test

Start unit test watchers (Squint + Vitest in parallel):

bb test:watch

Unit tests use Vitest and live in test/*.cljs. Squint compiles them to build/test/*.mjs which Vitest watches and runs.

E2E Tests

Default (AI Agents and Automated Testing):

bb test:e2e  # All E2E tests in Docker (headless), includes REPL integration

For humans (headed tests with visible browser):

bb test:e2e:headed     # Run tests (builds extension first)
bb test:e2e:ui:headed  # Interactive Playwright UI

Filter tests: Pass Playwright options to any e2e task:

bb test:e2e --grep "popup"     # Run only popup tests
bb test:e2e:headed --debug     # Debug mode with inspector (headed)

See testing.md for: complete testing strategy, fixtures, utilities, and troubleshooting.

CI/CD Pipeline

GitHub Actions runs on every push and PR:

┌───────────────┐   ┌─────────────┐
│ build-release │   │ build-test  │  <- Parallel builds
└───────────────┘   └──────┬──────┘
                           │
                   ┌───────┴───────┐
                   ▼               ▼
            ┌────────────┐  ┌────────────┐
            │ unit-tests │  │ e2e-tests  │  <- Parallel tests
            └────────────┘  └────────────┘
                   │               │
                   └───────┬───────┘
                           ▼
                     ┌─────────┐
                     │ release │  <- On version tags only
                     └─────────┘

See .github/workflows/build.yml for details.

Build

Build for all browsers (production):

bb build

Build for development (bumps dev version for testing):

bb build:dev

Build for e2e tests (dev config without version bump):

bb build:test

The build:test task uses dev config (needed for test-only message handlers like e2e/find-tab-id) but doesn't bump the manifest version. This prevents version drift when running e2e tests repeatedly.

Build for specific browser:

bb build:chrome
bb build:firefox
bb build:safari

Dev versions use 4-part format (0.0.7.0, 0.0.7.1). The 4th number is the build number, bumped by bb build:dev.

Load Extension Locally

Chrome:

  1. Unpack epupp-chrome.zip (will unpack a chrome folder)
  2. Go to chrome://extensions
  3. Enable "Developer mode"
  4. Click "Load unpacked"
  5. Select the chrome folder

Firefox:

  1. Go to about:debugging#/runtime/this-firefox
  2. Click "Load Temporary Add-on"
  3. Select any file in epupp-firefox.zip file

Safari:

  1. Safari → Settings → Developer → Click "Add Temporary Extension"
  2. Select the epupp-safari.zip file
  3. Ensure the extension is enabled in Safari → Settings → Extensions

Distribution

Release Process

Use the automated publish workflow:

bb publish

This will:

  1. Verify git is clean and on master branch
  2. Check CHANGELOG.md has unreleased content
  3. Strip build number from version (e.g., 0.0.7.8 -> 0.0.7)
  4. Update CHANGELOG with release date
  5. Commit, tag vN.N.N, and push
  6. Bump to next dev version (e.g., 0.0.8.0)

GitHub Actions then handles the rest automatically:

  1. Builds all three browser versions (Chrome, Firefox, Safari)
  2. Runs unit and E2E tests
  3. Creates a GitHub Release with downloadable artifacts
  4. Publishes to Chrome Web Store (auto-publish)
  5. Submits to Firefox AMO (with source code for review)

Safari remains manual (submit via Xcode to App Store Connect).

Store Publishing Details

Chrome Web Store: The publish_chrome CI job uploads the zip and auto-publishes. Updates typically go live within minutes. Uses chrome-webstore-upload-cli with a GCP service account.

Firefox AMO: The publish_firefox CI job submits the xpi along with a git archive source bundle for reviewer reproducibility. AMO review is asynchronous - the CI job submits and exits without waiting. Uses web-ext sign with JWT API credentials.

Safari: Manual. Submit via Xcode to App Store Connect.

Credential Setup (One-time)

Store publishing requires credentials stored in GitHub environment secrets:

  • chrome-store environment: CWS_SERVICE_ACCOUNT_KEY (GCP service account JSON key), CHROME_EXTENSION_ID (variable)
  • firefox-store environment: AMO_API_KEY (JWT issuer), AMO_API_SECRET (JWT secret)

To validate credentials without publishing, run the "Check Store Credentials" workflow manually from the Actions tab.

Troubleshooting Publish Failures

If a publish job fails after a successful release:

  • The GitHub Release and artifacts are unaffected
  • Re-run only the failed job from the Actions UI (no rebuild needed)
  • Check the job logs for credential or API errors
  • For persistent issues, publish manually using the store dashboards as a fallback

Related Documentation