temps CLAUDE.md

CLAUDE.md

Guidance for Claude Code when working with the Temps codebase. Core philosophy: code that works safely, and when it fails, explains why comprehensively.

Critical Rules

NEVER

• Put a real user's, customer's, or third party's identity into anything that leaves this machine. This repository is public. Company names, product names, internal hostnames, account names, contract/method names, real trace/span/request IDs, and any other detail that identifies whose system produced a payload must never appear in code, comments, test fixtures, commit messages, branch names, file names, PR titles, PR descriptions, PR comments, or issue text. This applies with full force to bug reports: a customer sends you a captured payload to get it fixed, not to have it published, and "it is just a fixture" is exactly how it gets published
  • Reproducing a reported bug: keep the shape that makes the payload valuable (timings, ordering, precision, nesting, sizes, edge cases) and replace everything that names anyone. Rename services, operations, and hosts to generic equivalents, and regenerate every identifier. A fixture that reproduces the bug and identifies nobody is strictly better -- it is also readable by someone who has never heard of the reporter
  • Describing the bug: say "a reported cross-project trace", never who reported it. The fix is reviewed on its merits; the reporter's identity adds nothing to a reviewer and cannot be taken back once pushed
  • Before pushing: grep the diff for the reporter's names and identifiers. Once it reaches GitHub it is effectively permanent -- force-pushing does not remove a pull request's recorded commits or its Files-changed diff, pull requests cannot be deleted, and forks may retain the objects. Removal at that point requires GitHub Support
• Commit .env files, credentials, or secrets -- this includes local dev-instance artifacts (encryption keys, auth secrets, generated tokens, temps_data-style data directories) created while running a local server for manual testing/verification. Before staging changes, run git status and scrutinize every path outside the files you intentionally edited -- a broad git add after spinning up a local test instance is the most common way this happens. If a secret is committed, treat it as compromised: remove it from tracking going forward at minimum, and flag to the user whether history needs rewriting (don't force-push without asking)
• Access database directly from HTTP handlers -- ALWAYS use services
• Return untyped JSON (serde_json::Value) -- ALWAYS use typed structs
• Use .context() from anyhow -- ALWAYS use .map_err() with typed errors
• Use .unwrap() or .expect() in production code -- ALWAYS use ? or explicit error handling
• Use anyhow::Result in service layer -- ALWAYS use typed error enums with thiserror
• Expose sensitive data (API keys, tokens) in responses -- ALWAYS mask them
• Create N+1 queries -- ALWAYS use JOINs for related data
• Leave the project in non-compilable state
• Use #[tokio::main] when integrating with pingora
• Use plain text logging -- ALWAYS use structured JSONL logging
• Overwrite apps/temps-cli/openapi.json with the raw server response (curl ... > openapi.json) -- the committed file is ~92,000 lines of sorted, indented JSON and the server serves it minified on one line, so a direct write reports -92,000 deletions and buries the real change. ALWAYS use cd apps/temps-cli && bun run spec:update (see Regenerating the OpenAPI clients)
• Create markdown documentation files unless explicitly requested
• Mark Docker tests with #[ignore] -- they MUST skip gracefully at runtime instead
• Create error types with generic messages -- ALWAYS include IDs, names, and operation context
• Expose internal dependencies via public accessors (e.g. service.db()) -- pass dependencies directly via constructor or AppState
• Use Option<T> for dependencies that are required -- use Arc<T> and fail at startup if missing
• Use get_service for required dependencies in plugins -- use require_service which fails fast with a clear error
• Add new runtime configuration as environment variables -- environment variables for configuration are forbidden. ALWAYS model it as a column on the relevant entity row (e.g. oidc_providers.trust_idp_email, not TEMPS_OIDC_SKIP_EMAIL_VERIFIED) so the admin can change it per-record at runtime via the API/UI, gets audit logging for free, and operators don't have to restart the binary to change a single tenant's behaviour. If the value is sensitive (credentials, tokens, private keys), the column MUST be encrypted at rest via EncryptionService, never stored as plaintext -- this applies even where env vars might otherwise seem tempting for secrets (e.g. a Vault CA bundle or auth token: store it encrypted on the provider row, not as TEMPS_VAULT_CA_BUNDLE). The only legitimate exception is bootstrap-time config needed before a database connection exists (e.g. DATABASE_URL, TEMPS_DATA_DIR, --license-path)