Skip to content

CLAUDE.md

Latest commit

 

History

History
180 lines (140 loc) · 6.58 KB

CLAUDE.md

File metadata and controls

180 lines (140 loc) · 6.58 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Start

Project: Firefox extension "Fancy Links" - copies formatted links with titles instead of plain URLs
Status: ✅ Production-ready with Jest test suite

Essential Commands

# Test extension in Firefox
web-ext run --source-dir=src

# Run tests (multiple options available)
npm test                 # Run all tests
npm run test:watch       # Watch mode for development
npm run test:coverage    # Generate coverage report
npm run test:ci          # CI optimized

# Build for distribution
web-ext build --source-dir=src --artifacts-dir=dist

# Check for lint/format issues (matches CI --warnings-as-errors)
web-ext lint --source-dir=src --warnings-as-errors

Critical Files

  • src/formats/format-registry.js - All format logic (html, markdown, etc.)
  • src/background/background.js - Main extension logic
  • src/manifest.json - Extension configuration and version

Claude Workflow Triggers

ALWAYS execute Post-Change Workflow after:

  • Modifying any .js files in src/
  • Changing src/manifest.json
  • Adding/removing formats in src/formats/format-registry.js
  • Updating package.json dependencies or build configuration
  • Making functional changes to extension behavior

Exception: Documentation-only changes to .md files (skip workflow)

Pre-existing test failures: If tests reveal failures unrelated to your current changes, fix them anyway. Broken tests erode trust in the suite and only get harder to fix later.

Post-Change Workflow

CRITICAL: After triggering changes above, Claude Code must execute this sequence:

1. Validate Changes

# Test functionality (REQUIRED for all functional changes)
npm test

# Check extension compliance (must match CI: --warnings-as-errors)
web-ext lint --source-dir=src --warnings-as-errors

2. Commit Changes (if validation passes)

  • Reference GitHub issues in commit message if resolving them
  • Follow existing commit message style (git log --oneline)
  • Include concise Claude attribution: Co-Authored-By: Claude <noreply@anthropic.com>

3. Version Management (for releases)

Pre-release Versions

For testing new features before public release:

Preferred: Use npm run version:bump to automate version bumps:

npm run version:bump rc minor    # Start RC for next minor (1.4.5 -> 1.5.0-rc1)
npm run version:bump rc          # Increment RC (1.5.0-rc1 -> 1.5.0-rc2)
npm run version:bump stable      # Promote to stable (1.5.0-rc1 -> 1.5.0)

  1. Version Naming Scheme:

    • manifest.json: Use two fields:
      • version: {previousStable}.{suffixNum} (e.g., 1.4.5.1 for 1.5.0-rc1)
      • version_name: Target version with suffix (e.g., 1.5.0-rc1)
    • Supported suffixes (automatically detected from version_name):
      • rc - Release candidate (final testing before stable)
      • beta - Beta version (feature complete, testing needed)
      • alpha - Alpha version (early development, may be unstable)
    • Examples (current stable 1.4.5 → target 1.5.0): 
      "version": "1.4.5.1",        // {previousStable}.{suffixNum}
"version_name": "1.5.0-rc1"  // Target version with RC suffix
    • Critical: Using previous version ensures 1.4.5.1 < 1.5.0 for proper auto-updates

  2. Create pre-release:

    # Automated (preferred):
npm run version:bump rc minor
# Then follow the suggested git commands

# Manual (if needed):
# Update manifest.json with BOTH fields
# Example for 1.5.0-rc1 (assuming previous stable is 1.4.5):
#   "version": "1.4.5.1"
#   "version_name": "1.5.0-rc1"
git commit -am "Prepare v1.5.0-rc1 pre-release"
git tag v1.5.0-rc1
git push origin v1.5.0-rc1

  3. Pre-release behavior:

    • Automatically signed via AMO unlisted channel
    • Creates GitHub pre-release (marked as pre-release)
    • NOT submitted to AMO public listing
    • Distributed via GitHub releases page
    • Includes warning notice in release notes
    • Auto-updates to stable when released

Stable Releases

Update src/manifest.json version:

  • PATCH: Bug fixes, documentation
  • MINOR: New features, format additions
  • MAJOR: Breaking changes

Publish release:

git tag v<version>    # Triggers automated GitHub Actions build
git push origin v<version>

Note: AMO submission is controlled by the AMO_SUBMISSION_ENABLED GitHub Variable. Set to true in repository settings to enable automatic submission to addons.mozilla.org.

Project Structure

Production Code (src/):

  • background/ - Main extension logic and clipboard operations
  • popup/ - Toolbar UI
  • options/ - Settings page
  • formats/ - Centralized format registry
  • utils/ - Shared utilities (browser API, clipboard, URL cleaning, diagnostics, keyboard shortcuts)
  • icons/ - Extension icons and assets

Development (root):

  • test/ - Automated test suites
  • tools/ - Development utilities (icon generation)
  • design/ - Design assets and mockups

CI/CD (shared via evanwon/browser-extension-workflows):

  • .github/workflows/ - Thin callers to shared reusable workflows
  • Version tooling (version:bump, version:check) provided by browser-extension-workflows package

Technical Details

Format Registry (src/formats/format-registry.js)

Consolidated registry with 4 formats:

  • html - <a href="URL">Title</a>
  • markdown - [Title](URL) (Discord, Reddit, GitHub, Notion)
  • plaintext - Title - URL
  • urlparams - URL?_title=Page_Title

Browser Requirements

  • Firefox 142+ with Manifest V2
  • Permissions: clipboardWrite, activeTab, storage, notifications
  • Support for other browsers like Chrome is expected in the future; ensure that feature development is designed with future cross-browser compatibility

Development & Testing

Testing Extension

  • Development: web-ext run --source-dir=src (loads temporarily in Firefox)
  • Manual Testing: Load test/manual.html in Firefox with extension active

Distribution

  • CI/CD workflows are shared via evanwon/browser-extension-workflows (reusable GitHub Actions)
  • GitHub Actions auto-signs releases when AMO secrets are configured, triggered by git tags
  • Unsigned builds require Firefox Developer Edition or temporary loading

GitHub Issues & Task Management

All tasks tracked at: https://github.com/evanwon/fancy-links/issues

Labels

  • enhancement / bug / documentation
  • priority: high|medium|low