convert/CLAUDE.md

Approach

• Read existing files before writing. Don't re-read unless changed.
• Thorough in reasoning, concise in output.
• Skip files over 100KB unless required.
• No sycophantic openers or closing fluff.
• No emojis or em-dashes.
• Do not guess APIs, versions, flags, commit SHAs, or package names. Verify by reading code or docs before asserting.

MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

• Exploring code: semantic_search_nodes or query_graph instead of Grep
• Understanding impact: get_impact_radius instead of manually tracing imports
• Code review: detect_changes + get_review_context instead of reading entire files
• Finding relationships: query_graph with callers_of/callees_of/imports_of/tests_for
• Architecture questions: get_architecture_overview + list_communities

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Tool	Use when
detect_changes	Reviewing code changes — gives risk-scored analysis
get_review_context	Need source snippets for review — token-efficient
get_impact_radius	Understanding blast radius of a change
get_affected_flows	Finding which execution paths are impacted
query_graph	Tracing callers, callees, imports, tests, dependencies
semantic_search_nodes	Finding functions/classes by name or keyword
get_architecture_overview	Understanding high-level codebase structure
refactor_tool	Planning renames, finding dead code

Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use detect_changes for code review.
3. Use get_affected_flows to understand impact.
4. Use query_graph pattern="tests_for" to check coverage.

Local environment / running tests

• .env holds production credentials (o2switch host, real DB name/password). Never load it for local runs or tests.
• .env.local holds the local dev DB credentials (DB_HOST=127.0.0.1, DB_USER=convert_user, DB_NAME=file_converter, DB_PASSWORD=change_me). This is what local testing should use.
• src/config.js uses dotenv/config, which only loads .env and does not override variables already present in process.env. There's no vitest/dotenv wiring that picks up .env.local automatically.
• To run tests locally without touching prod config, pass the .env.local values as inline env vars so they take precedence before dotenv/config runs, e.g.:

  DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run
  

• A local MariaDB is expected to already be running on 127.0.0.1:3306 with the file_converter DB and convert_user credentials seeded.
• Known pre-existing failures unrelated to any fix: test/cleanup.test.js ("deletes an expired pending job...") and test/jobs/jobRepository.test.js ("finds expired jobs and allows deleting them") — both fail on main independent of other changes (looks like a clock/timezone mismatch around expiresAt comparisons, not yet root-caused). Don't assume a change caused these; verify against main first if they show up again.

Database schema & migrations

• prisma/schema.prisma is the source of truth for the conversion_jobs schema; prisma/migrations/ is its version history. db/schema.sql no longer exists.
• Prisma CLI commands (prisma migrate dev, prisma migrate deploy, prisma generate) need DATABASE_URL in their own process environment, separate from the app. Compute it from the same DB_HOST/DB_USER/DB_PASSWORD/DB_NAME values used for local tests, via node scripts/printDatabaseUrl.js — never write DATABASE_URL into .env or .env.local.
• To create a new migration locally after editing prisma/schema.prisma:

  DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage \
    DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate dev --name <description>
  

• To apply pending migrations in production: with the real DB_* values loaded from .env, run DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy before starting the app.