Charon/.github/instructions/copilot-instructions.md

Charon Copilot Instructions

Code Quality Guidelines

Every session should improve the codebase, not just add to it. Actively refactor code you encounter, even outside of your immediate task scope. Think about long-term maintainability and consistency. Make a detailed plan before writing code. Always create unit tests for new code coverage.

• MANDATORY: Read all relevant instructions in .github/instructions/ for the specific task before starting.
• ARCHITECTURE AWARENESS: Always consult ARCHITECTURE.md at the repository root before making significant changes to:
  • Core components (Backend API, Frontend, Caddy Manager, Security layers)
  • System architecture or data flow
  • Technology stack or dependencies
  • Deployment configuration
  • Directory structure or file organization
• DRY: Consolidate duplicate patterns into reusable functions, types, or components after the second occurrence.
• CLEAN: Delete dead code immediately. Remove unused imports, variables, functions, types, commented code, and console logs.
• LEVERAGE: Use battle-tested packages over custom implementations.
• READABLE: Maintain comments and clear naming for complex logic. Favor clarity over cleverness.
• CONVENTIONAL COMMITS: Write commit messages using feat:, fix:, chore:, refactor:, or docs: prefixes.

Governance & Precedence

When policy statements conflict across documentation sources, resolve using this precedence hierarchy:

1. Highest Precedence: .github/instructions/** files (canonical source of truth)
2. Agent Overrides: .github/agents/** files (agent-specific customizations)
3. Operator Documentation: SECURITY.md, docs/security.md, docs/features/notifications.md (user-facing guidance)

Reconciliation Rule: When conflicts arise, the stricter security requirement wins. Update downstream documentation to match canonical text in .github/instructions/**.

Example: If .github/instructions/security.instructions.md mandates token redaction but operator docs suggest logging is acceptable, token redaction requirement takes precedence and operator docs must be updated.

🚨 CRITICAL ARCHITECTURE RULES 🚨

• Single Frontend Source: All frontend code MUST reside in frontend/. NEVER create backend/frontend/ or any other nested frontend directory.
• Single Backend Source: All backend code MUST reside in backend/.
• No Python: This is a Go (Backend) + React/TypeScript (Frontend) project. Do not introduce Python scripts or requirements.

🛑 Root Cause Analysis Protocol (MANDATORY)

Constraint: You must NEVER patch a symptom without tracing the root cause. If a bug is reported, do NOT stop at the first error message found. Use Playwright MCP to trace the entire flow from frontend action to backend processing. Identify the true origin of the issue.

The "Context First" Rule: Before proposing ANY code change or fix, you must build a mental map of the feature:

1. Entry Point: Where does the data enter? (API Route / UI Event)
2. Transformation: How is the data modified? (Handlers / Middleware)
3. Persistence: Where is it stored? (DB Models / Files)
4. Exit Point: How is it returned to the user?

Anti-Pattern Warning: - Do not assume the error log is the cause; it is often just the victim of an upstream failure.

• If you find an error, search for "upstream callers" to see why that data was bad in the first place.

Big Picture

• Charon is a self-hosted web app for managing reverse proxy host configurations with the novice user in mind. Everything should prioritize simplicity, usability, reliability, and security, all rolled into one simple binary + static assets deployment. No external dependencies.
• Users should feel like they have enterprise-level security and features with zero effort.
• backend/cmd/api loads config, opens SQLite, then hands off to internal/server.
• internal/config respects CHARON_ENV, CHARON_HTTP_PORT, CHARON_DB_PATH and creates the data/ directory.
• internal/server mounts the built React app (via attachFrontend) whenever frontend/dist exists.
• Persistent types live in internal/models; GORM auto-migrates them.

Backend Workflow

• Run: cd backend && go run ./cmd/api.
• Test: go test ./....
• Static Analysis (BLOCKING): Fast linters run automatically on every commit via lefthook pre-commit-phase hooks.
  • Staticcheck errors MUST be fixed - commits are BLOCKED until resolved
  • Manual run: make lint-fast or VS Code task "Lint: Staticcheck (Fast)"
  • Staticcheck-only: make lint-staticcheck-only
  • Runtime: ~11s (measured: 10.9s) (acceptable for commit gate)
  • Full golangci-lint (all linters): Use make lint-backend before PR (manual stage)
• API Response: Handlers return structured errors using gin.H{"error": "message"}.
• JSON Tags: All struct fields exposed to the frontend MUST have explicit json:"snake_case" tags.
• IDs: UUIDs (github.com/google/uuid) are generated server-side; clients never send numeric IDs.
• Security: Sanitize all file paths using filepath.Clean. Use fmt.Errorf("context: %w", err) for error wrapping.
• Graceful Shutdown: Long-running work must respect server.Run(ctx).

Troubleshooting Lefthook Staticcheck Failures

Common Issues:

1. "golangci-lint not found"

   • Install: See README.md Development Setup section
   • Verify: golangci-lint --version
   • Ensure $GOPATH/bin is in PATH

2. Staticcheck reports deprecated API usage (SA1019)

   • Fix: Replace deprecated function with recommended alternative
   • Check Go docs for migration path
   • Example: filepath.HasPrefix → use strings.HasPrefix with cleaned paths

3. "This value is never used" (SA4006)

   • Fix: Remove unused assignment or use the value
   • Common in test setup code

4. "Should replace if statement with..." (S10xx)

   • Fix: Apply suggested simplification
   • These improve readability and performance

5. Emergency bypass (use sparingly):

   • git commit --no-verify -m "Emergency hotfix"
   • MUST create follow-up issue to fix staticcheck errors
   • Only for production incidents

Frontend Workflow

• Location: Always work within frontend/.
• Stack: React 18 + Vite + TypeScript + TanStack Query (React Query).
• State Management: Use src/hooks/use*.ts wrapping React Query.
• API Layer: Create typed API clients in src/api/*.ts that wrap client.ts.
• Forms: Use local useState for form fields, submit via useMutation, then invalidateQueries on success.

Cross-Cutting Notes

• VS Code Integration: If you introduce new repetitive CLI actions (e.g., scans, builds, scripts), register them in .vscode/tasks.json to allow for easy manual verification.
• Sync: React Query expects the exact JSON produced by GORM tags (snake_case). Keep API and UI field names aligned.
• Migrations: When adding models, update internal/models AND internal/api/routes/routes.go (AutoMigrate).
• Testing: All new code MUST include accompanying unit tests.
• Ignore Files: Always check .gitignore, .dockerignore, and .codecov.yml when adding new file or folders.

Documentation

• Architecture: Update ARCHITECTURE.md when making changes to:
  • System architecture or component interactions
  • Technology stack (major version upgrades, library replacements)
  • Directory structure or organizational conventions
  • Deployment model or infrastructure
  • Security architecture or data flow
  • Integration points or external dependencies
• Features: Update docs/features.md when adding capabilities. This is a short "marketing" style list. Keep details to their individual docs.
• Links: Use GitHub Pages URLs (https://wikid82.github.io/charon/) for docs and GitHub blob links for repo files.

CI/CD & Commit Conventions

• Triggers: Use feat:, fix:, or perf: to trigger Docker builds. chore: skips builds.
• Beta: feature/beta-release always builds.
• History-Rewrite PRs: If a PR touches files in scripts/history-rewrite/ or docs/plans/history_rewrite.md, the PR description MUST include the history-rewrite checklist from .github/PULL_REQUEST_TEMPLATE/history-rewrite.md. This is enforced by CI.

PR Sizing & Decomposition

• Default Rule: Prefer smaller, reviewable PRs over one large PR when work spans multiple domains.
• Split into Multiple PRs When:
  • The change touches backend + frontend + infrastructure/security in one effort
  • The estimated diff is large enough to reduce review quality or increase rollback risk
  • The work can be delivered in independently testable slices without breaking behavior
  • A foundational refactor is needed before feature delivery
• Suggested PR Sequence:
  1. Foundation PR (types/contracts/refactors, no behavior change)
  2. Backend PR (API/model/service changes + tests)
  3. Frontend PR (UI integration + tests)
  4. Hardening PR (security/CI/docs/follow-up fixes)
• Per-PR Requirement: Every PR must remain deployable, pass DoD checks, and include a clear dependency note on prior PRs.

✅ Task Completion Protocol (Definition of Done)

Before marking an implementation task as complete, perform the following in order:

1. Playwright E2E Tests (MANDATORY - Run First):
   • Run: cd /projects/Charon npx playwright test --project=firefox from project root
   • Why First: If the app is broken at E2E level, unit tests may need updates. Catch integration issues early.
   • Scope: Run tests relevant to modified features (e.g., tests/manual-dns-provider.spec.ts)
   • On Failure: Trace root cause through frontend → backend flow before proceeding
   • Base URL: Uses PLAYWRIGHT_BASE_URL or default from playwright.config.js
   • All E2E tests must pass before proceeding to unit tests

1.5. GORM Security Scan (CONDITIONAL, BLOCKING): - Trigger Condition: Execute this gate when changes include backend models or database interaction logic: - backend/internal/models/** - GORM query/service layers - Database migrations or seeding logic - Exclusions: Skip this gate for docs-only (**/*.md) or frontend-only (frontend/**) changes - Run One Of: - VS Code task: Lint: GORM Security Scan - Lefthook: lefthook run pre-commit (includes gorm-security-scan) - Direct: ./scripts/scan-gorm-security.sh --check - Gate Enforcement: DoD is process-blocking until scanner reports zero CRITICAL/HIGH findings, even while automation remains in manual stage - Check Mode Required: Gate decisions must use check mode semantics (--check flag or equivalent task wiring) for pass/fail determination

2. Local Patch Coverage Preflight (MANDATORY - Run Before Unit/Coverage Tests):

   • Run: VS Code task Test: Local Patch Report or bash scripts/local-patch-report.sh from repo root.
   • Purpose: Surface exact changed files and uncovered changed lines before adding/refining unit tests.
   • Required Artifacts: test-results/local-patch-report.md and test-results/local-patch-report.json.
   • Expected Behavior: Report may warn (non-blocking rollout), but artifact generation is mandatory.

3. Security Scans (MANDATORY - Zero Tolerance):

   • CodeQL Go Scan: Run VS Code task "Security: CodeQL Go Scan (CI-Aligned)" OR lefthook run pre-commit
     • Must use security-and-quality suite (CI-aligned)
     • Zero high/critical (error-level) findings allowed
     • Medium/low findings should be documented and triaged
   • CodeQL JS Scan: Run VS Code task "Security: CodeQL JS Scan (CI-Aligned)" OR lefthook run pre-commit
     • Must use security-and-quality suite (CI-aligned)
     • Zero high/critical (error-level) findings allowed
     • Medium/low findings should be documented and triaged
   • Validate Findings: Run lefthook run pre-commit to check for HIGH/CRITICAL issues
   • Trivy Container Scan: Run VS Code task "Security: Trivy Scan" for container/dependency vulnerabilities
   • Results Viewing:
     • Primary: VS Code SARIF Viewer extension (MS-SarifVSCode.sarif-viewer)
     • Alternative: jq command-line parsing: jq '.runs[].results' codeql-results-*.sarif
     • CI: GitHub Security tab for automated uploads
   • ⚠️ CRITICAL: CodeQL scans are NOT run by default pre-commit hooks (manual stage for performance). You MUST run them explicitly via VS Code tasks or pre-commit manual commands before completing any task.
   • Why: CI enforces security-and-quality suite and blocks HIGH/CRITICAL findings. Local verification prevents CI failures and ensures security compliance.
   • CI Alignment: Local scans now use identical parameters to CI:
     • Query suite: security-and-quality (61 Go queries, 204 JS queries)
     • Database creation: --threads=0 --overwrite
     • Analysis: --sarif-add-baseline-file-info

4. Lefthook Triage: Run lefthook run pre-commit.

   • If errors occur, fix them immediately.
   • If logic errors occur, analyze and propose a fix.
   • Do not output code that violates pre-commit standards.

5. Staticcheck BLOCKING Validation: Pre-commit hooks automatically run fast linters including staticcheck.

   • CRITICAL: Staticcheck errors are BLOCKING - you MUST fix them before commit succeeds.
   • Manual verification: Run VS Code task "Lint: Staticcheck (Fast)" or make lint-fast
   • To check only staticcheck: make lint-staticcheck-only
   • Test files (_test.go) are excluded from staticcheck (matches CI behavior)
   • If pre-commit fails: Fix the reported issues, then retry commit
   • Do NOT use --no-verify to bypass this check unless emergency hotfix

6. Coverage Testing (MANDATORY - Non-negotiable):

   • Overall Coverage: Minimum 85% coverage is MANDATORY and will fail the PR if not met.
   • Patch Coverage: Developers should aim for 100% coverage of modified lines (Codecov Patch view). If patch coverage is incomplete, add targeted tests. However, patch coverage is a suggestion and will not block PR approval.
   • Backend Changes: Run the VS Code task "Test: Backend with Coverage" or execute scripts/go-test-coverage.sh.
     • Minimum coverage: 85% (set via CHARON_MIN_COVERAGE or CPM_MIN_COVERAGE).
     • If coverage drops below threshold, write additional tests to restore coverage.
     • All tests must pass with zero failures.
   • Frontend Changes: Run the VS Code task "Test: Frontend with Coverage" or execute scripts/frontend-test-coverage.sh.
     • Minimum coverage: 85% (set via CHARON_MIN_COVERAGE or CPM_MIN_COVERAGE).
     • If coverage drops below threshold, write additional tests to restore coverage.
     • All tests must pass with zero failures.
   • Critical: Coverage tests are NOT run by default pre-commit hooks (they are in manual stage for performance). You MUST run them explicitly via VS Code tasks or scripts before completing any task.
   • Why: CI enforces coverage in GitHub Actions. Local verification prevents CI failures and maintains code quality.

7. Type Safety (Frontend only):

   • Run the VS Code task "Lint: TypeScript Check" or execute cd frontend && npm run type-check.
   • Fix all type errors immediately. This is non-negotiable.
   • This check is also in manual stage for performance but MUST be run before completion.

8. Verify Build: Ensure the backend compiles and the frontend builds without errors.

   • Backend: cd backend && go build ./...
   • Frontend: cd frontend && npm run build

9. Fixed and New Code Testing:

   • Ensure all existing and new unit tests pass with zero failures.
   • When failures and errors are found, deep-dive into root causes. Using the correct subAgent, update the working plan, review the implementation, and fix the issues.
   • No issue is out of scope for investigation and resolution. All issues must be addressed before task completion.

10. Clean Up: Ensure no debug print statements or commented-out blocks remain.

    • Remove console.log, fmt.Println, and similar debugging statements.
    • Delete commented-out code blocks.
    • Remove unused imports.