codexkit 1.0.0

package/.codex/skills/cloudflare/references/zaraz/README.md

@@ -0,0 +1,360 @@
+# Cloudflare Zaraz Skill
+
+Expert guidance for Cloudflare Zaraz - server-side tag manager for loading third-party tools at the edge.
+
+## What is Zaraz?
+
+Zaraz offloads third-party scripts (analytics, ads, chat, marketing) to Cloudflare's edge, improving site speed, privacy, and security. Zero client-side performance impact.
+
+## Core Concepts
+
+- **Server-side execution** - Scripts run on Cloudflare, not user's browser
+- **Single HTTP request** - All tools loaded via one endpoint
+- **Privacy-first** - Control data sent to third parties
+- **No client-side JS** - Minimal browser overhead
+
+## Zaraz Dashboard Setup
+
+1. Navigate to domain > Zaraz
+2. Click "Start setup"
+3. Add tools (Google Analytics, Facebook Pixel, etc.)
+4. Configure triggers and actions
+
+## Web API
+
+Zaraz provides `zaraz` object in browser:
+
+### Track Events
+
+```javascript
+// Basic event
+zaraz.track('button_click');
+
+// Event with properties
+zaraz.track('purchase', {
+  value: 99.99,
+  currency: 'USD',
+  item_id: '12345'
+});
+
+// E-commerce events
+zaraz.track('add_to_cart', {
+  product_name: 'Widget',
+  price: 29.99,
+  quantity: 1
+});
+```
+
+### Set User Properties
+
+```javascript
+zaraz.set('userId', 'user_12345');
+zaraz.set('plan', 'premium');
+zaraz.set({
+  email: '[email protected]',
+  country: 'US',
+  age: 30
+});
+```
+
+### E-commerce Tracking
+
+```javascript
+// Product view
+zaraz.ecommerce('Product Viewed', {
+  product_id: 'SKU123',
+  name: 'Blue Widget',
+  price: 49.99,
+  currency: 'USD'
+});
+
+// Add to cart
+zaraz.ecommerce('Product Added', {
+  product_id: 'SKU123',
+  quantity: 2,
+  price: 49.99
+});
+
+// Purchase
+zaraz.ecommerce('Order Completed', {
+  order_id: 'ORD-789',
+  total: 149.98,
+  revenue: 149.98,
+  shipping: 10.00,
+  tax: 12.50,
+  currency: 'USD',
+  products: [
+    { product_id: 'SKU123', quantity: 2, price: 49.99 }
+  ]
+});
+```
+
+## Consent Management
+
+```javascript
+// Check consent status
+if (zaraz.consent.getAll().analytics) {
+  zaraz.track('page_view');
+}
+
+// Request consent
+zaraz.consent.modal = true; // Show consent modal
+
+// Set consent programmatically
+zaraz.consent.setAll({
+  analytics: true,
+  marketing: false,
+  preferences: true
+});
+
+// Listen for consent changes
+zaraz.consent.addEventListener('consentChanged', () => {
+  console.log('Consent updated:', zaraz.consent.getAll());
+});
+```
+
+## Workers Integration
+
+Access Zaraz data in Workers:
+
+```typescript
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    
+    // Inject Zaraz tracking
+    if (url.pathname === '/checkout') {
+      const response = await fetch(req);
+      const html = await response.text();
+      
+      const tracking = `
+        <script>
+          zaraz.track('checkout_started', {
+            cart_value: 99.99
+          });
+        </script>
+      `;
+      
+      const modified = html.replace('</body>', tracking + '</body>');
+      return new Response(modified, response);
+    }
+    
+    return fetch(req);
+  }
+};
+```
+
+## Triggers
+
+Configure when tools fire:
+
+### Page Rules
+
+- **Pageview** - On every page load
+- **DOM Ready** - When DOM is ready
+- **Click** - Element clicks (CSS selector)
+- **Form submission** - Form submits
+- **Scroll depth** - User scrolls percentage
+- **Timer** - After time elapsed
+- **Variable match** - Custom conditions
+
+### Example Trigger
+
+```
+Trigger: Button Click
+Match rule: CSS Selector = .buy-button
+Action: Track event "purchase_intent"
+```
+
+## Common Tools
+
+### Google Analytics 4
+
+```javascript
+// Track page view (automatic)
+zaraz.track('pageview');
+
+// Custom event
+zaraz.track('sign_up', {
+  method: 'email'
+});
+```
+
+### Facebook Pixel
+
+```javascript
+zaraz.track('PageView');
+zaraz.track('Purchase', {
+  value: 99.99,
+  currency: 'USD'
+});
+```
+
+### Google Ads Conversion
+
+```javascript
+zaraz.track('conversion', {
+  send_to: 'AW-XXXXXXXXX/YYYYYY',
+  value: 1.00,
+  currency: 'USD'
+});
+```
+
+## Custom Managed Components
+
+Build custom tools:
+
+```javascript
+// Example: Custom analytics tool
+export default class CustomAnalytics {
+  async handleEvent(event) {
+    const { type, payload } = event;
+    
+    await fetch('https://analytics.example.com/track', {
+      method: 'POST',
+      body: JSON.stringify({
+        event: type,
+        properties: payload,
+        timestamp: Date.now()
+      })
+    });
+  }
+}
+```
+
+## Data Layer
+
+Use `zaraz.dataLayer` for structured data:
+
+```javascript
+// Set data layer
+window.zaraz.dataLayer = {
+  user_id: '12345',
+  page_type: 'product',
+  category: 'electronics'
+};
+
+// Access in triggers
+// Variable: {{client.__zarazTrack.page_type}}
+```
+
+## Server-Side Configuration
+
+### zaraz.toml
+
+```toml
+[settings]
+auto_inject = true
+debug_mode = false
+
+[[tools]]
+type = "google-analytics"
+id = "G-XXXXXXXXXX"
+
+[[tools.triggers]]
+match_rule = "Pageview"
+```
+
+## Privacy Features
+
+1. **IP anonymization** - Automatic
+2. **Cookie control** - Consent-based
+3. **Data minimization** - Send only necessary data
+4. **Regional compliance** - GDPR, CCPA support
+
+## Performance
+
+```javascript
+// Zaraz automatically:
+// - Batches requests
+// - Defers non-critical scripts
+// - Proxies third-party requests
+// - Caches tool configurations
+
+// Result: ~0ms client-side overhead
+```
+
+## Debugging
+
+```javascript
+// Enable debug mode in dashboard, then:
+zaraz.debug = true;
+
+// View events in console
+zaraz.track('test_event', { debug: true });
+
+// Check loaded tools
+console.log(zaraz.tools);
+```
+
+## Best Practices
+
+1. **Use triggers** instead of inline `zaraz.track()` when possible
+2. **Batch events** for related actions
+3. **Test with debug mode** before production
+4. **Implement consent** for GDPR compliance
+5. **Monitor performance** in dashboard analytics
+6. **Use data layer** for structured data
+
+## Common Patterns
+
+### SPA Tracking
+
+```javascript
+// On route change
+router.afterEach((to, from) => {
+  zaraz.track('pageview', {
+    page_path: to.path,
+    page_title: to.meta.title
+  });
+});
+```
+
+### User Identification
+
+```javascript
+// On login
+zaraz.set('user_id', user.id);
+zaraz.set('user_email', user.email);
+zaraz.track('login', { method: 'password' });
+```
+
+### A/B Testing
+
+```javascript
+const variant = Math.random() < 0.5 ? 'A' : 'B';
+zaraz.set('ab_test_variant', variant);
+zaraz.track('ab_test_view', { variant });
+```
+
+## Limits
+
+- **Tools**: Unlimited
+- **Events**: Unlimited
+- **Data retention**: Per tool's policy
+- **Request size**: 100KB per request
+
+## Troubleshooting
+
+### Events not firing
+
+- Check trigger conditions in dashboard
+- Verify tool is enabled
+- Enable debug mode
+- Check browser console for errors
+
+### Consent issues
+
+- Verify consent modal configuration
+- Check `zaraz.consent.getAll()` status
+- Ensure tools respect consent settings
+
+## Reference
+
+- [Zaraz Docs](https://developers.cloudflare.com/zaraz/)
+- [Web API](https://developers.cloudflare.com/zaraz/web-api/)
+- [Managed Components](https://developers.cloudflare.com/zaraz/advanced/load-custom-managed-component/)
+
+---
+
+This skill focuses exclusively on Zaraz. For Workers development, see `cloudflare-workers` skill.

package/.codex/skills/code-navigation/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: code-navigation
+description: Use when navigating unfamiliar code, tracing cross-file dependencies, or before editing — efficient code reading patterns that minimize tool calls and token waste
+version: 1.0.0
+tags: [workflow, code-quality, context]
+dependencies: []
+---
+
+# Code Navigation Skill
+
+## When to Use
+
+- Exploring an unfamiliar codebase or module
+- Tracing a function call across multiple files
+- Understanding blast radius before a breaking change
+- Planning edits that touch multiple files
+
+## When NOT to Use
+
+- Simple single-file edits where you already know the location
+- Reading config or documentation files
+
+## Core Principle
+
+> Collapse multiple tool calls into fewer, smarter ones. Every unnecessary read or search wastes tokens and turns.
+
+## Navigation Patterns
+
+### Pattern 1: Search First, Read Second
+
+**Wrong** (3-6 tool calls):
+```
+glob("*.ts") → read(file1) → "too big" → grep("functionName") → read(file2) → read(file3, section)
+```
+
+**Right** (1-2 tool calls):
+```
+grep("functionName", path: "src/") → read(exact_file, offset: line-10, limit: 30)
+```
+
+Start with search (grep, LSP findReferences) to locate, then read only what you need.
+
+### Pattern 2: Multi-Symbol Search
+
+When tracing a call chain (A calls B calls C), search for all symbols together:
+```
+grep({ pattern: "functionA|functionB|functionC", path: "src/" })
+```
+
+Or use LSP outgoingCalls to get the full call tree from a single point.
+
+### Pattern 3: Don't Re-Read What You've Already Seen
+
+**Anti-pattern**: Search returns full function body, then agent reads the same file again.
+
+If search results already show the code you need, work from that output. Only re-read when:
+- You need surrounding context (lines above/below the match)
+- You need the exact content for editing (verify before edit)
+- The search result was truncated
+
+### Pattern 4: Blast Radius Check (Before Breaking Changes)
+
+**WHEN**: Before renaming, removing, or changing the signature of an export.
+**SKIP**: When adding new code, fixing internal bugs, or reading.
+
+Steps:
+1. `lsp({ operation: "findReferences" })` — find all callers
+2. `lsp({ operation: "incomingCalls" })` — get the call hierarchy
+3. Review each caller to assess impact
+4. Plan edits from leaf callers inward (furthest dependencies first)
+
+### Pattern 5: Context Locality
+
+When editing a file, search results from the same directory/package are more likely relevant. Pass context when available:
+- In grep: use `path: "src/same-module/"` to scope
+- In LSP: operations are already file-scoped
+- In tilth: pass `context` param to boost nearby results
+
+### Pattern 6: Outline Before Deep Read
+
+For large files (>200 lines), get the structure first:
+```
+lsp({ operation: "documentSymbol", filePath: "src/large-file.ts", line: 1, character: 1 })
+```
+
+This gives you function names + line ranges. Then read only the section you need with `offset` and `limit`.
+
+### Pattern 7: Follow the Call Chain (Not the File Tree)
+
+**Wrong**: Read files top-to-bottom hoping to understand the flow.
+**Right**: Start from the entry point, follow function calls:
+
+```
+1. lsp({ operation: "goToDefinition" })   → find where it's defined
+2. lsp({ operation: "outgoingCalls" })     → what does it call?
+3. lsp({ operation: "goToDefinition" })    → follow the interesting callee
+```
+
+## With tilth MCP
+
+When tilth is available, it provides superior navigation:
+
+| Built-in Tool | tilth Equivalent | Advantage |
+|---|---|---|
+| `grep` + `read` | `tilth_search` (expand: 2) | Returns definitions with inline source — no second read needed |
+| `glob` | `tilth_files` | Adds token estimates per file |
+| `read` (large file) | `tilth_read` | Auto-outlines large files, shows structure |
+| `lsp(incomingCalls)` | `tilth_search(kind: "callers")` | Cross-language structural caller detection |
+| Manual tracing | `tilth_deps` | Shows imports + downstream callers before breaking changes |
+
+**IMPORTANT**: If tilth is available, prefer it over built-in grep/glob/read for code navigation. Tilth's expanded search results include full source — do NOT re-read files already shown in search output.
+
+## Cost Awareness
+
+Every tool call has a token cost. Efficient navigation means:
+- Fewer tool calls per task
+- Less context consumed by redundant reads
+- More budget available for actual implementation
+
+**Target**: Find and understand any symbol in ≤3 tool calls, not 6+.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Read entire large file | Use outline first, then section read |
+| Search → read same code again | Work from search results directly |
+| Trace calls one-by-one | Multi-symbol search or outgoingCalls |
+| Explore randomly | Start from entry point, follow calls |
+| Forget to check blast radius | Always check before signature changes |

package/.codex/skills/code-review/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: code-review
+description: Formal review framework with severity levels, categories, and actionable finding format.
+---
+
+# code-review
+
+## Purpose
+Produce high-signal, actionable review feedback that improves code quality without blocking on style-only noise.
+
+## Use This Skill When
+- Reviewing pull requests before merge
+- Auditing risky changes (auth, billing, data deletion, concurrency)
+- Validating hotfixes with limited test coverage
+- Mentoring via review comments that teach and unblock
+
+## Workflow Phases
+1. Context gather
+2. Diff analysis
+3. Risk classification
+4. Findings report
+
+## Expected Outputs
+- Structured findings with `file:line`
+- Correct severity assignment (P0-P3)
+- Concrete fix direction and verification hint
+- Merge recommendation (approve / request changes)
+
+## Success Indicators
+- Findings map to real user or system impact
+- No speculative claims without evidence from diff/tests
+- Security and performance risks called out explicitly
+- Reviewer comments are short, precise, and patchable
+
+## Fast Start
+Run these commands first:
+
+```bash
+git diff --name-only origin/main...HEAD
+git diff -U5 origin/main...HEAD
+npm run typecheck
+npm test -- --runInBand
+```
+
+## Severity Scale
+
+| Severity | Meaning | Merge Impact |
+|---|---|---|
+| P0 | Blocker; unsafe to merge | Block merge |
+| P1 | Must fix; high risk or correctness issue | Block merge |
+| P2 | Should fix; medium risk or maintainability gap | Can merge with follow-up |
+| P3 | Nit; style or optional improvement | Optional |
+
+## Review Categories
+- Correctness
+- Security
+- Performance
+- Maintainability
+- Test adequacy
+
+## Finding Format
+```text
+- file:line — [P1][Correctness]
+  Issue: <specific behavior defect>
+  Why: <user/system impact>
+  Suggestion: <minimal patch direction>
+  Verify: <test or command that proves fix>
+```
+
+## Review Order (high-signal first)
+1. Entry points and trust boundaries (HTTP handlers, CLI args, webhooks)
+2. State mutation paths (writes, deletes, side effects)
+3. Error handling and rollback paths
+4. Concurrency/async behavior (race conditions, stale reads)
+5. Tests and assertions around changed behavior
+6. Naming/readability nits only after major risks are cleared
+
+## Language-Specific Checklist
+
+### TypeScript / JavaScript
+- Validate untrusted input with schema/runtime checks, not just types.
+- Avoid `any` and unsafe casts in new code paths.
+- Ensure async calls are awaited or intentionally fire-and-forget with comment.
+- Check promise rejection handling (`try/catch`, `Promise.allSettled` where needed).
+- Verify narrow types after guards; avoid non-null assertions unless proven.
+- Prefer pure helpers for business logic; keep handlers thin.
+
+### Python
+- Check mutable default arguments and shared-state hazards.
+- Verify exception specificity (`except Exception` only with clear re-raise strategy).
+- Confirm context managers for files/connections/locks.
+- Validate serialization boundaries (datetime/timezone, Decimal/float conversion).
+- Watch for N+1 ORM queries and missing prefetch/select_related.
+
+### Go
+- Ensure errors are wrapped with context and not dropped.
+- Confirm `context.Context` propagation to I/O and DB calls.
+- Verify goroutine lifecycle and channel close ownership.
+- Look for data races on shared maps/slices.
+- Check nil interface pitfalls (`var err error = (*MyErr)(nil)`).
+
+### Rust
+- Confirm ownership/borrowing changes preserve invariants.
+- Avoid `unwrap()`/`expect()` in production paths unless truly impossible.
+- Review `unsafe` blocks for documented invariants.
+- Check `Send/Sync` assumptions when introducing threads/tasks.
+- Prefer explicit error types over broad boxed errors at boundaries.
+
+### SQL / Data Layer
+- Parameterize all dynamic values (no string-built SQL).
+- Verify indexes cover new filter/order predicates.
+- Ensure pagination is stable (deterministic ORDER BY).
+- Check transaction boundaries and isolation assumptions.
+- Review migration safety: backfill strategy, lock duration, rollback plan.
+
+## Security Review Patterns
+
+### Input and trust boundary
+- Is every external input validated and normalized once?
+- Are dangerous fields allowlisted rather than blocklisted?
+- Are file paths/URLs/commands sanitized before use?
+
+### AuthN / AuthZ
+- Is identity established before reading protected resources?
+- Is authorization checked on object-level operations (IDOR prevention)?
+- Are role checks centralized and test-covered?
+
+### Secrets and data exposure
+- No secrets in logs, errors, snapshots, fixtures.
+- Errors should avoid leaking internals (SQL, stack traces, tokens).
+- Sensitive payloads should be redacted in telemetry.
+
+### Injection and SSRF
+- SQL/NoSQL/query injections blocked via parameterization.
+- Template rendering escapes untrusted values.
+- Outbound fetches restrict protocols/hosts where applicable.
+
+### State-changing operations
+- CSRF protections for cookie-authenticated state changes.
+- Idempotency keys for payment/order/retry-prone endpoints.
+- Replay protections for signed webhooks.
+
+## Performance Review Patterns
+- Replace O(n²) loops with maps/sets when cardinality can grow.
+- Collapse repeated DB/API calls into batch fetches.
+- Push filtering/sorting to DB when indexes exist.
+- Avoid full object serialization when partial fields suffice.
+- Check cache correctness (TTL, key cardinality, invalidation path).
+- Validate that background work is bounded (queue size, retries, backoff).
+
+## Test Adequacy Heuristics
+- New branch added → at least one test that fails without the branch.
+- Bug fix → regression test reproduces old failure first.
+- Security-sensitive change → negative tests for unauthorized inputs.
+- Data mutation change → tests assert persisted state, not only response body.
+- Concurrency change → tests with deterministic synchronization when possible.
+
+## Concrete Finding Examples
+
+### P0 example
+- `src/auth/token.ts:88` — [P0][Security]
+  Issue: JWT verification skips signature check when `alg` header missing.
+  Why: Forged tokens can authenticate as arbitrary users.
+  Suggestion: Reject tokens without explicit allowed algorithm and enforce signature verification.
+  Verify: Add test with forged unsigned token; auth must fail.
+
+### P1 example
+- `src/orders/create.ts:142` — [P1][Correctness]
+  Issue: Inventory decrement occurs before payment confirmation and is never rolled back on payment failure.
+  Why: Stock drift and oversell under transient payment errors.
+  Suggestion: Wrap inventory+payment finalization in transaction or reserve-then-confirm workflow.
+  Verify: Simulate payment error; inventory remains unchanged.
+
+### P2 example
+- `src/reports/monthly.ts:54` — [P2][Performance]
+  Issue: Per-customer DB query inside loop (`N+1` pattern).
+  Why: Latency grows linearly with customer count.
+  Suggestion: Fetch aggregates in one grouped query and map results in memory.
+  Verify: Benchmark 1k customers before/after.
+
+### P3 example
+- `src/cli/flags.ts:19` — [P3][Maintainability]
+  Issue: Option name `x` is non-descriptive.
+  Why: Increases onboarding and misuse risk.
+  Suggestion: Rename to `--dry-run` and keep alias for compatibility.
+  Verify: CLI help output includes new flag and alias works.
+
+## Merge Recommendation Rules
+- **Approve**: no P0/P1 findings; tests and type checks pass.
+- **Request changes**: any P0/P1, or missing verification for risky areas.
+- **Approve with follow-ups**: only P2/P3 findings with clear tickets.
+
+## Comment Writing Rules
+- Lead with impact, not preference.
+- One issue per comment.
+- Include minimal fix direction, not full rewrite requests.
+- Avoid “consider maybe”; be explicit about severity and reason.
+
+## Anti-Patterns to Avoid in Review
+- Nit-picking style while missing security/correctness flaws.
+- Requiring large refactors unrelated to the diff.
+- Commenting on generated or vendored files unless security-critical.
+- Asking for tests without naming the behavior gap.
+
+## Exit Criteria
+- Every major risk area reviewed (correctness, security, performance, tests).
+- Findings include severity, impact, and actionable fix path.
+- Merge recommendation is explicit and justified.