Add cache handlers package

.changeset/README.md

@@ -1,8 +1,11 @@
 # Changesets
 
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+Hello and welcome! This folder has been automatically generated by
+`@changesets/cli`, a build tool that works with multi-package repos, or
+single-package repos to help you version and publish your code. You can find the
+full documentation for it
+[in our repository](https://github.com/changesets/changesets)
 
-We have a quick list of common questions to get you started engaging with this project in
+We have a quick list of common questions to get you started engaging with this
+project in
 [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -8,4 +8,4 @@
 	"baseBranch": "main",
 	"updateInternalDependencies": "patch",
 	"ignore": []
-}
+}

.github/workflows/claude.yml

@@ -0,0 +1,72 @@
+name: Claude PR Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude-code-action:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run Claude PR Action
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          timeout_minutes: "5"
+          # mcp_config: |
+          #   {
+          #     "mcpServers": {
+          #       "astro-docs": {
+          #         "type": "http",
+          #         "url": "https://mcp.docs.astro.build/mcp"
+          #       }
+          #     }
+          #   }
+          allowed_tools: |
+            Bash(pnpm install)
+            Bash(pnpm run:*)
+            Bash(npm run:*)
+            Bash(npx packages/am-i-vibing)
+          # mcp__astro-docs__search_astro_docs
+          # Optional: Restrict network access to specific domains only
+          # experimental_allowed_domains: |
+          #   .anthropic.com
+          #   .github.com
+          #   api.github.com
+          #   .githubusercontent.com
+          #   bun.sh
+          #   registry.npmjs.org
+          #   .blob.core.windows.net

.github/workflows/release.yaml → .github/workflows/release.yml

@@ -23,29 +23,36 @@ jobs:
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           app-id: ${{ secrets.APP_ID }}
       - name: Checkout Repo
-        uses: actions/checkout@v3
-
-      - name: Setup Node.js 22
-        uses: actions/setup-node@v3
+        uses: actions/checkout@v4
         with:
-          node-version: 22
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v3
 
-      - uses: pnpm/action-setup@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: latest
+          cache: "pnpm"
 
       - name: Install Dependencies
         run: pnpm install
 
       - name: Build Packages
-        run: pnpm build
+        run: pnpm run build
+      - run: pnpm run check
 
-      - name: publint
-        run: pnpm lint:package
+      # Update npm to latest version so that OIDC works correctly
+      - name: Update npm
+        run: npm install -g npm@latest
 
-      - name: Create Release PR or Publish to npm
+      - name: Create Release Pull Request or Publish to npm
         id: changesets
         uses: changesets/action@v1
         with:
-          version: pnpm run version
+          version: pnpm changeset version
           publish: pnpm changeset publish
           commit: "ci: release"
           title: "ci: release"

.github/workflows/semantic-prs.yml

@@ -0,0 +1,55 @@
+name: "Lint PR"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: write
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        with:
+          types: |
+            fix
+            feat
+            chore
+            docs
+            ci
+            test
+            revert
+        id: lint_pr_title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: marocchino/sticky-pull-request-comment@v2
+        # When the previous steps fails, the workflow would stop. By adding this
+        # condition you can continue the execution with the populated error message.
+        if: always() && (steps.lint_pr_title.outputs.error_message != null)
+        with:
+          header: pr-title-lint-error
+          message: |
+            Hey there and thank you for opening this pull request! 👋🏼
+
+            We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.
+            Without this title format, a release will not be triggered
+
+            Details:
+
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+
+      # Delete a previous comment when the issue has been resolved
+      - if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          delete: true

.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          cache: "pnpm"
+          check-latest: true
+          registry-url: "https://registry.npmjs.org"
+      - name: Install dependencies
+        run: |
+          corepack enable
+          pnpm install
+      - name: Build
+        run: pnpm build
+      - name: Test
+        run: pnpm test

.prettierignore

@@ -1,3 +1,4 @@
 package.json
 CHANGELOG.md
 pnpm-lock.yaml
+**/deno/**/*

.prettierrc

@@ -1 +1,3 @@
-{}
+{
+	"useTabs": true
+}

.vscode/settings.json

@@ -1,3 +1,17 @@
 {
-    "typescript.tsdk": "node_modules/typescript/lib"
-}
+	"typescript.tsdk": "node_modules/typescript/lib",
+	"deno.enablePaths": [
+		"packages/cache-handlers/"
+	],
+	"deno.config": "./deno.json",
+	"deno.suggest.imports.hosts": {
+		"https://deno.land": true,
+		"https://jsr.io": true
+	},
+	"[typescript]": {
+		"editor.defaultFormatter": "denoland.vscode-deno"
+	},
+	"[javascript]": {
+		"editor.defaultFormatter": "denoland.vscode-deno"
+	}
+}

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## Repository Structure
+
+This is a monorepo for CDN cache control libraries using pnpm workspaces:
+
+- **Root**: Workspace configuration and shared tooling
+- **packages/**: Individual library packages
+  - `cdn-cache-control`: Easy, opinionated CDN cache header handling (TypeScript
+    class-based API)
+  - `cache-handlers`: Modern CDN cache primitives using web-standard middleware
+    (functional API)
+
+## Commands
+
+### Root-level commands (run from repository root):
+
+- `pnpm build` - Build all packages
+- `pnpm test` - Run tests for all packages (includes Deno, Node.js, and Workerd
+  tests)
+- `pnpm check` - Run type checking and linting for all packages
+- `pnpm lint` - Run linting for all packages
+- `pnpm format` - Format code using Prettier
+
+### Package-level commands (run within individual packages):
+
+- `pnpm build` - Build the package using tsdown (ESM + DTS output)
+- `pnpm dev` - Watch mode for development
+- `pnpm test` - Run tests (specific to each package's test setup)
+- `pnpm check` - Run publint and @arethetypeswrong/cli checks
+
+### Test-specific commands for cache-handlers package:
+
+- `pnpm test:deno` - Run Deno tests from repository root
+- `pnpm test:node` - Run Node.js tests via Vitest
+- `pnpm test:workerd` - Run Cloudflare Workers tests via Vitest
+
+## Development Workflow
+
+- Uses **pnpm** as package manager
+- **tsdown** for building TypeScript packages with ESM output and declaration
+  files
+- **deno** for testing
+- **publint** and **@arethetypeswrong/cli** for package validation
+- **Prettier** for code formatting (configured to use tabs in `.prettierrc`)
+
+## Package Architecture
+
+### cdn-cache-control
+
+- **API Style**: Class-based (`CacheHeaders` extends `Headers`)
+- **Target**: Simple cache header management with CDN-specific optimizations
+- **Testing**: Node.js only via `node --test`
+- **Build**: ESM + CommonJS outputs
+
+### cache-handlers
+
+- **API Style**: Functional middleware approach
+- **Target**: Web standard cache primitives for modern applications
+- **Key Features**:
+  - Factory functions (`createCacheHandlers`, `createReadHandler`, etc.)
+  - HTTP conditional requests (ETag, Last-Modified, 304 responses)
+  - Cache invalidation by tags and paths
+  - Multi-runtime support (Deno, Node.js, Cloudflare Workers)
+- **Testing**: Multi-runtime (Deno tests, Node.js via Vitest, Workerd via
+  Vitest)
+- **Build**: ESM-only output
+
+Each package follows this structure:
+
+- `src/index.ts` - Main entry point with comprehensive exports
+- `test/` - Test files (runtime-specific subdirectories for cache-handlers)
+- `dist/` - Built output (ESM + .d.ts files)
+- Package exports configured for proper TypeScript declarations
+
+## TypeScript Configuration
+
+Uses strict TypeScript configuration with:
+
+- Target: ES2022
+- Module: preserve (for bundler compatibility)
+- Strict mode with additional safety checks (`noUncheckedIndexedAccess`,
+  `noImplicitOverride`)
+- Library-focused settings (declaration files, declaration maps)
+
+## Use Specialized Agents for Complex Tasks
+
+ALWAYS use the appropriate specialized agents for complex work:
+
+- **technical-architect**: For designing system architecture, evaluating
+  technical approaches, planning major features
+- **code-reviewer**: For comprehensive code review after implementing
+  significant code changes
+- **test-engineer**: For analyzing test failures, creating new tests, and
+  enhancing test coverage. Should NOT fix application code - only
+  creates/updates test files
+- **docs-author**: For creating or updating documentation, READMEs, changesets,
+  or PR descriptions
+- **package-installer**: For installing npm packages with proper dependency
+  management