job-engine-spring: Instructions file for Codex

Repository Guidelines

job-engine-spring is a local-only MCP (Model Context Protocol) server, not a hosted service, REST API, web UI, or job-board scraper. It stores normalized candidate profiles and jobs, produces explainable profile-to-job match reports, and generates resume/cover-letter PDFs. Normal runtime is a persistent Streamable HTTP MCP endpoint published only on host loopback (http://127.0.0.1:8080/mcp); STDIO exists only for CI/package verification and isolated diagnostics. The application is MCP-first: do not add REST controllers unless REST compatibility is explicitly required — the privileged, disabled-by-default adapter/in/http/operator boundary (see below) is the one approved exception.

Project Structure & Module Organization

This is a Maven Java 25 Spring Boot 4.1.0 project. The main build descriptor is pom.xml, with the Maven wrapper available as mvnw. Production code lives in src/main/java, tests in src/test/java, and Flyway database migrations in src/main/resources/db/migration.

The package layout follows application boundaries: domain contains core business concepts, application holds use cases and orchestration, and adapter packages contain integrations. The adapters are adapter/in/mcp, adapter/in/http/operator (privileged, disabled by default), adapter/out/postgres, adapter/out/http, adapter/out/extraction, adapter/out/filesystem, and adapter/out/transaction.

Build, Test, and Development Commands

• ./mvnw test runs the unit test suite through Surefire.
• ./mvnw -q -Dtest=ClassName test runs a single test class; comma-separate multiple classes, e.g. ./mvnw -q -Dtest=JobServiceTests,JobMcpAdapterTests,HttpJobLinkContentFetcherTests test.
• ./mvnw verify -Pintegration-tests runs integration tests through Failsafe (Testcontainers/PostgreSQL) plus the JaCoCo coverage gate. Requires Docker.
• ./mvnw spring-boot:run starts the application locally.
• docker compose build mcp builds the local container image for the persistent Streamable HTTP MCP server.
• ./scripts/run-local-mcp-http.sh is the build-from-source dev path: it bootstraps the ignored .env (operator boundary on, private token), then runs docker compose up -d --build --force-recreate --wait postgres mcp, starting PostgreSQL privately and publishing MCP plus the operator routes only on host loopback; python3 scripts/smoke-mcp-http.py verifies initialize, discovery, and health. Use the raw docker compose up -d --build --wait postgres mcp when the environment file must not be touched.
• ./scripts/bootstrap-local-env.sh creates/updates the git-ignored .env: it sets JOB_ENGINE_OPERATOR_ENABLED=true when the value is missing or false, and generates a 64-character JOB_ENGINE_OPERATOR_BEARER_TOKEN when the existing token is shorter than 32 characters. It is idempotent, never prints the token, and never overrides an explicitly chosen non-default value. JOB_ENGINE_SKIP_ENV_BOOTSTRAP=true disables the automatic call in the deployment scripts.
• ./scripts/rebuild-local-mcp-jar.sh runs ./mvnw test, packages the jar, then runs hermes mcp test job-engine-spring if the Hermes CLI is present (RUN_TESTS=false to skip tests when already green).
• ./scripts/run-release-mcp-http.sh ghcr.io/jonhhh09/job-engine-spring:vX.Y.Z is the guarded release-only deployment path; it bootstraps .env, refuses local/latest images, and recreates the service without building.
• ./scripts/run-local-mcp-container.sh is the explicit STDIO CI/package-verification launcher. It activates the stdio profile and must not be used for normal Hermes tool calls.
• ./scripts/run-mcp-stdio-diag.sh launches a unique-named diagnostic MCP STDIO container so engineering smoke/diagnosis cannot kill an active Hermes session.
• python3 scripts/smoke-mcp-stdio.py -- ./scripts/run-local-mcp-container.sh verifies the containerized MCP initialize + tools/list STDIO contract for the default instance. Prefer ./scripts/run-mcp-stdio-diag.sh when Hermes may already be connected.
• ./scripts/run-local-mcp-stdio.sh runs the packaged jar directly over STDIO on the host, without Docker; use it only for isolated jar-level diagnosis.
• ./scripts/restart-local-mcp-server.sh is the jar-based STDIO restart helper (--foreground, --run-tests, --smoke-test); it does not touch the persistent Compose service.
• python3 scripts/verify-mcp-restored-data.py performs sanitized JSON-RPC reads against an isolated restored MCP server after ./scripts/postgres-restore.sh, never against the primary instance.
• scripts/tests/test-mcp-container-cleanup.sh is a Docker-free regression for cleanup ownership (preserve custom instances; remove default/legacy only for default launches).
• scripts/tests/test-bootstrap-local-env.sh is the Docker-free regression for the .env bootstrap (default-on, token strength, idempotence, explicit opt-out, no token in output).
• scripts/tests/run-postgres-ops-tests.sh runs the Docker-free backup/restore shell regressions in scripts/tests/postgres-ops-test.sh; scripts/tests/postgres-ops-integration.sh is the Docker-backed counterpart.
• python3 scripts/test-smoke-mcp-stdio.py and python3 scripts/tests/test-verify-mcp-restored-data.py are the self-tests for the two Python helpers.
• For pipeline, Compose, shell, Python, or MCP transport changes, also run actionlint, shellcheck, docker compose config, the image build, and the real STDIO MCP smoke test. CONTRIBUTING.md points here for that list.
• After rebuilding/redeploying: recreate the persistent service, then run /reload-mcp in the connected agent; if tool names/schemas/prompts changed, also run /reset to refresh the agent's cached tool schema.
• Backup/recovery: ./scripts/postgres-backup.sh, ./scripts/postgres-verify-backup.sh, ./scripts/postgres-restore.sh, ./scripts/postgres-backup-prune.sh. Restore/verify always target a disposable Compose project/volume, never the primary one directly.