Skip to content

CLAUDE.md

Latest commit

 

History

History
367 lines (256 loc) · 17.1 KB

CLAUDE.md

File metadata and controls

367 lines (256 loc) · 17.1 KB
Raw

CLAUDE.md

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

For tool-neutral operational guidance for automated agents (e.g., Codex, CI bots), see AGENTS.md.

Project Overview

This is a SvelteKit-based web presence for Network Pro Strategies, deployed via Vercel. The codebase emphasizes security, privacy, and maintainability, and is distributed as both a production website and an npm package (@networkpro/web). It includes Progressive Web App (PWA) functionality with a custom service worker, strict Content Security Policy (CSP) configuration, and comprehensive testing.

AI Guardrails

This repository may be worked on using AI-assisted tools (e.g., Claude Code). When doing so, the following guardrails apply:

  • Do not introduce new environment modes or alter environment-detection logic (src/lib/utils/env.js) without explicit human approval.
  • Do not weaken security posture: CSP rules, analytics gating, service worker exclusions, and audit-mode behavior must not be relaxed for convenience.
  • Do not invent or assume CI/CD workflows: Deployment behavior must match existing infrastructure (Vercel for production, Netlify for audit via branch-scoped workflow).
  • Do not add or modify analytics, telemetry, or external network calls without confirming consent and environment gating logic.
  • Do not refactor for style or abstraction alone if it obscures intent, security checks, or explicit control flow.
  • Do not commit secrets or sensitive data; environment files are strictly separated by purpose.
  • Prefer explicit, readable code over "clever" optimizations, especially in security- or environment-related paths.

If a change would materially affect security, deployment behavior, environment resolution, or privacy guarantees, pause and ask for confirmation before proceeding.

AI tools should treat this file (CLAUDE.md) as authoritative guidance and defer to existing documentation and code comments where conflicts arise.

Svelte MCP Server

Claude Code can use the Svelte MCP server, which provides comprehensive Svelte 5 and SvelteKit documentation. Use the available tools as follows:

Available Svelte MCP Tools

1. list-sections

Use this FIRST to discover all available documentation sections. It returns a structured list with titles, use cases, and paths.

When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.

2. get-documentation

Retrieves full documentation content for specific sections. It accepts single or multiple sections.

After calling list-sections, Claude Code MUST analyze the returned documentation sections, especially the use_cases field, and then use get-documentation to fetch ALL documentation sections that are relevant for the user's task.

3. svelte-autofixer

Analyzes Svelte code and returns issues and suggestions.

Claude Code MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.

4. playground-link

Generates a Svelte Playground link with the provided code.

After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.

Allowed AI Uses

AI-assisted tools may be used in this repository for the following purposes:

  • Code comprehension and explanation: Explaining existing logic, security controls, environment detection, or architectural decisions.
  • Incremental feature development: Implementing new features or routes that follow established patterns and respect existing constraints.
  • Bug fixing and debugging: Identifying defects, edge cases, or test failures and proposing targeted fixes.
  • Test creation and improvement: Writing or extending unit tests, integration tests, and E2E tests consistent with existing testing architecture.
  • Refactoring for clarity: Improving readability, structure, or maintainability without altering behavior, security posture, or environment semantics.
  • Documentation updates: Improving README files, comments, JSDoc, and other documentation to better reflect current behavior.
  • Dependency and configuration review: Highlighting outdated dependencies, misconfigurations, or potential risks (without making changes unilaterally).
  • Accessibility and standards compliance: Suggesting improvements related to a11y, web standards, or best practices, subject to review.
  • Clarifying questions: Asking for confirmation when intent, risk, or trade-offs are unclear.

AI output should be treated as assistance, not authority. All changes are subject to human review and approval.

Essential Commands

Development

npm run dev                # Start dev server
npm run dev:audit          # Dev server in audit mode (hardened CSP, no analytics)
npm run build              # Production build
npm run build:audit        # Audit build (for testing hardened CSP)
npm run preview            # Preview production build locally

Testing

npm run test:all           # Run all unit tests (client + server)
npm run test:client        # Run client-side unit tests (jsdom)
npm run test:server        # Run server-side unit tests (node)
npm run test:watch         # Watch mode for client tests
npm run test:coverage      # Generate coverage reports
npm run test:e2e           # Run Playwright E2E tests (with 1 retry)
npm run lhci:run           # Run Lighthouse CI audits

Linting & Formatting

npm run lint:all           # Run all linters (JS, CSS, Markdown, Prettier)
npm run lint:fix           # Auto-fix ESLint issues
npm run format:fix         # Auto-fix Prettier formatting
npm run lint:css           # Lint CSS and Svelte styles
npm run lint:md            # Lint Markdown files

Pre-commit Verification

npm run checkout           # Full verification (type-check, tests, linting)
npm run verify             # Alias for checkout

Single Test Execution

# Run a specific client test
npx vitest run tests/unit/client/path/to/test.test.js

# Run a specific server test
npx vitest run tests/unit/server/path/to/test.test.js

# Run a specific E2E test
npx playwright test tests/e2e/app.spec.js

Architecture & Key Patterns

Environment Management

The project uses a multi-environment setup with behavior controlled primarily by PUBLIC_ENV_MODE, with Vite mode and local command fallbacks used where needed:

  • development / dev: Local development with report-only CSP, no analytics
  • production / prod: Full CSP enforcement, consent-gated Matomo analytics, CSP reporting to production endpoint
  • audit: Hardened environment for security testing: no analytics, no external CSP reporting, strict CSP
  • test: CI/test mode with report-only CSP for automation
  • codex: Special mode for Claude Code development

Critical: Environment detection happens in two places:

  1. Build/config time: PUBLIC_ENV_MODE is the primary contract. svelte.config.js also falls back to Vite mode and NODE_ENV=development so normal vite dev uses report-only CSP.
  2. Runtime: src/lib/utils/env.js exposes environment flags to app code. The audit.netwk.pro hostname remains a belt-and-suspenders signal and diagnostic, but policy selection must come from the build mode.

The detectEnvironment() function in src/lib/utils/env.js unifies this logic and is used throughout the app.

Content Security Policy (CSP)

CSP is configured in svelte.config.js via SvelteKit kit.csp, based on build/config-time environment selection:

  • Production: Strict CSP with Content-Security-Policy header, real CSP reporting endpoint
  • Audit: Hardened CSP with no analytics domains, no CSP reporting
  • Dev/Test: Report-only mode (Content-Security-Policy-Report-Only) for debugging

src/hooks.server.js no longer constructs or emits CSP headers directly. It still sets request-time security headers, emits the production Report-To header, logs audit hostname mismatches, and records audit-mode Probely diagnostics.

Current Trade-off: SvelteKit manages hashes for framework-generated inline scripts. The production policy keeps scripts restricted to self plus the Matomo origin, and still allows unsafe-inline for styles because Svelte transitions can generate inline styles at runtime. The Keep Android Open banner is implemented first-party as a Svelte component to avoid third-party inline script injection.

Probely Scanner Diagnostics: hooks.server.js detects Probely DAST scanners using isProbelyScanner() from src/lib/security/probely.js, but this is diagnostic-only and does not bypass request handling.

Service Worker & PWA

The service worker is defined in src/service-worker.js and handles:

  • Precaching of build artifacts and static files
  • Runtime caching strategies (cache-first, network-first)
  • Cache versioning and cleanup

Registration: src/lib/registerServiceWorker.js handles:

  • SW registration and update lifecycle
  • Cache cleanup (removes non-prefixed caches)
  • Install prompt support (beforeinstallprompt event)
  • Firefox localhost compatibility skip
  • ?nosw query parameter bypass via static/disableSw.js

Route Structure

  • +page.svelte: Page component
  • +page.server.js: Server-side page load (metadata, redirects)
  • +layout.svelte: Root layout with analytics init, MetaTags, header/footer
  • +layout.js: Client-side layout load (pathname detection)
  • +server.js: API endpoints (e.g., /api/mock-csp, /pgp/[key])

Special Routes:

  • /pgp/[key]/+server.js: Dynamic PGP key serving with proper Content-Type headers
  • /api/mock-csp/+server.js: Mock CSP violation reporting endpoint for dev/test

Component Organization

src/lib/
├── components/         # Reusable Svelte components
│   ├── layout/        # Header, Footer
│   └── foss/          # FOSS-specific components
├── pages/             # Page-specific content components (e.g., AboutContent.svelte)
├── data/              # Static data (fossData.js, pgpKeys.js)
├── stores/            # Svelte stores (posthog.js, trackingPreferences.js)
├── utils/             # Helper utilities (env.js, utm.js, purify.js)
├── types/             # Type definitions and constants
├── styles/            # Global CSS
└── security/          # Security utilities (probely.js)

Import Pattern: Use $lib alias for all internal imports (configured in jsconfig.json via vite-tsconfig-paths).

Analytics & Tracking

Matomo analytics are loaded through the compatibility helper at src/lib/stores/posthog.js. The legacy path and app-facing API are preserved while the provider is consent-gated and environment-aware.

Key Functions:

  • initPostHog(): Initializes local tracking preference state and loads Matomo when allowed
  • capture(event): Sends pageviews and limited event captures to Matomo when allowed
  • showReminder: Svelte store for tracking consent banner state

Analytics initialization happens in src/lib/utils/initAnalytics.js, called from +layout.svelte.

Testing Architecture

Unit Tests: Split into client (jsdom) and server (node) contexts with separate Vitest configs:

  • tests/unit/client/: Browser-environment tests (components, client utils)
  • tests/unit/server/: Node-environment tests (server utils, API endpoints)
  • tests/unit/server/internal/auditCoverage.test.js: Warns about untested source files

E2E Tests: Playwright tests in tests/e2e/:

  • app.spec.js: Desktop and mobile route tests
  • mobile.spec.js: Mobile-specific assertions
  • shared/helpers.js: Shared test utilities (viewport helpers, element getters)

Coverage Audit: The project includes a coverage audit that warns (but doesn't fail) when source files lack corresponding unit tests.

Configuration Files

  • svelte.config.js: SvelteKit config with Vercel adapter, kit.csp, mode selection, and prerender error handling
  • vite.config.js: Vite config with SvelteKit, LightningCSS, devtools-json plugins
  • vitest.config.client.js: Client-side unit test config (jsdom environment)
  • vitest.config.server.js: Server-side unit test config (node environment)
  • playwright.config.js: E2E test config (Chromium, Firefox, WebKit)
  • .lighthouserc.cjs: Lighthouse CI audit configuration
  • postcss.config.cjs: PostCSS with autoprefixer
  • vercel.json: Vercel deployment config

Development Workflows

Adding a New Route

  1. Create src/routes/your-route/+page.svelte

  2. Create src/routes/your-route/+page.server.js for metadata:

    export function load() {
  return {
    meta: {
      title: 'Your Page Title',
      description: 'Your page description',
    },
  };
}

  3. Add corresponding E2E test in tests/e2e/app.spec.js

  4. Update sitemap at static/sitemap.xml if needed

Adding a New Component

  1. Create component in src/lib/components/YourComponent.svelte
  2. Export from src/lib/components/index.js if it's shared
  3. Add unit test in tests/unit/client/components/YourComponent.test.js
  4. Use $lib/components alias for imports

Modifying CSP

  1. Edit svelte.config.js and update the appropriate kit.csp directive set
  2. Test in audit mode: npm run dev:audit
  3. Check CSP violations in browser console or /api/mock-csp logs
  4. Update tests if needed

Adding Analytics Events

  1. Import capture from $lib/stores/posthog
  2. Call capture('event_name', { properties }) in client-side code
  3. Only pageviews and limited event fields are sent; user identification remains disabled

Important Constraints

Security Considerations

  • Never commit sensitive data: Use .env for local secrets, never .env.template
  • CSP compliance: Prefer SvelteKit-managed hashes/nonces, avoid broad unsafe-inline for scripts, and document any temporary production relaxations or third-party inline-script hash allowances
  • PGP keys: .asc files in static/pgp/ are served directly, not precached

Code Quality Standards

  • No emojis in commit messages or code comments unless explicitly requested
  • Copyright headers required on all source files
  • ESLint + Prettier enforced via pre-commit hooks
  • Stylelint for CSS/Svelte style validation
  • JSDoc required for exported functions

Build Requirements

  • Node.js: >= 22.0.0, < 25
  • npm: >= 10.0.0, < 12
  • Enforced via engines in package.json and scripts/checkNode.js

Testing Requirements

  • Unit tests should use appropriate environment (client vs. server)
  • E2E tests automatically retry once to reduce flakiness
  • Coverage audit warns about untested files but doesn't fail CI

Common Gotchas

  1. Service Worker Caching: Use ?nosw query param to bypass SW for testing
  2. Environment Detection: PUBLIC_ENV_MODE is the build-time source of truth; audit.netwk.pro hostname detection is diagnostic/defense-in-depth
  3. CSP Violations: Check browser console in dev mode; violations are logged to /api/mock-csp
  4. Analytics Initialization: The compatibility helper initializes preference state but does not send events
  5. Static Asset Imports: Use Vite's import syntax (e.g., import logo from '$lib/img/logo.png')
  6. Prerendering: Some routes are prerendered at build time; check svelte.config.js error handlers

Debugging Tips

  • Enable debug mode: Add ?debug=true to URL for verbose console logs
  • Disable service worker: Add ?nosw to URL to bypass SW caching
  • Check environment: Use detectEnvironment() in any file to see current env flags
  • View CSP violations: Check /api/mock-csp endpoint logs in dev mode
  • Playwright UI mode: Run npx playwright test --ui for interactive debugging

Deployment Environments

  • Production

    • URL: https://netwk.pro
    • Hosting: Vercel
    • Deployment model: Automatic builds and deployments triggered by merges to master
    • CI: Managed by Vercel (not GitHub Actions)

  • Audit

    • URL: https://audit.netwk.pro
    • Hosting: Netlify
    • Purpose: Hardened security environment (strict CSP, no analytics, no external CSP reporting)
    • Deployment model:
      • Built and deployed via a GitHub Actions workflow
      • Workflow file: .github/workflows/deploy-audit-netlify.yml
      • Workflow exists only on the audit-netlify branch
      • Deployments are intentionally decoupled from production

  • Preview

    • Hosting: Vercel
    • Trigger: Pull requests and non-master branches
    • Purpose: Ephemeral previews for review and testing

Note: There is no single CI/CD pipeline shared by all environments. Production relies on Vercel’s native build system, while the audit environment uses a dedicated, branch-scoped GitHub Actions workflow.