docs/development-commands.md

# Development Commands

## Build & Development

- **`docker compose up`**: Start development server (main app on 7860, HMR on 7861)
- **`docker compose up --build`**: Compile for production
- **`docker compose exec development-server npm run start`**: Preview production build
- **`docker compose exec development-server npm run lint`**: Check code quality (Biome, TypeScript, knip, jscpd, architectural linter, documentation validator)
- **`docker compose exec development-server npm run format`**: Auto-format code with Biome

## Docker

- **`docker compose up`**: Development environment with SearXNG and Node.js
- **`docker compose -f docker-compose.production.yml up --build`**: Production deployment

## Testing

- **`docker compose exec development-server npm run test`**: Run Vitest tests
- **`docker compose exec development-server npm run test:watch`**: Run tests in watch mode
- **`docker compose exec development-server npm run test:coverage`**: Run tests with coverage report

Failure-injection cases (dependency down, empty results, aborted stream) are catalogued in `docs/failure-injection.md`.

## Offline eval

`eval/` is an offline eval that gives a regression signal for changes to the
reranker, the system prompt, the search-results formatting, or the model. See
`eval/README.md` for details and the LLM-judge environment variables.

- **`npm run eval`**: Run the full eval (retrieval + answer)
- **`npm run eval:retrieval`**: Retrieval eval (real ONNX reranker; local only, needs the model in `server/models/`)
- **`npm run eval:answer`**: Answer eval (LLM judge; gated on `EVAL_LLM_API_KEY`, skips without one)

### Coverage Reports for AI Analysis

After running `test:coverage`, AI agents can analyze these JSON files:

- **`coverage/coverage-summary.json`**: Quick metrics view - overall percentages per file
  ```json
  {
    "total": {
      "lines": { "total": 100, "covered": 85, "pct": 85 },
      "statements": { "total": 120, "covered": 100, "pct": 83.33 },
      "functions": { "total": 30, "covered": 25, "pct": 83.33 },
      "branches": { "total": 50, "covered": 40, "pct": 80 }
    },
    "/path/to/file.ts": { ... }
  }
  ```

- **`coverage/coverage-final.json`**: Detailed per-file coverage with line-by-line mapping
  - Use this to identify specific uncovered lines, branches, and functions
  - Maps statement/branch/function IDs to source locations

AI agents can parse these to identify:
- Files with coverage below thresholds
- Uncovered lines and branches
- Functions without tests
- Coverage gaps across the codebase

## CI/CD Pipeline

The repository uses nine GitHub Actions workflows for continuous integration, deployment, release management, security scanning, and issue triage:

### Workflow Files

| Workflow | Trigger | Purpose |
|---|---|---|
| `ci.yml` | Push/PR to `main` or `master` | Full lint (`npm run lint`), format check (`npm run format`), and Vitest test suite |
| `security.yml` | Push/PR to `main` or `master` | Secret scanning (Gitleaks) and license compliance check (`npm run license-check`) with artifact upload |
| `on-push-to-main.yml` | Push to `main` | Delegates to `reusable-check-docker.yml` |
| `on-pull-request-to-main.yml` | PR opened/synced/reopened to `main` | Delegates to `reusable-check-docker.yml`; skippable via `skip-check-docker` label |
| `publish-docker-image.yml` | Manual (`workflow_dispatch`), `main` only | Cuts a CalVer release: validates the optional `version` input (empty auto-computes today's date in UTC plus the next free same-day sequence), builds the multi-platform Docker image (linux/amd64, linux/arm64) and pushes it to `ghcr.io` as that version plus `latest` (build job, `contents: read` + `packages: write`), then a second job holding `contents: write` pushes the git tag and publishes the GitHub Release. The release job is idempotent: when a run pushed the tag but failed before publishing the Release, re-running that job alone finishes it without rebuilding |
| `scan-docker-image.yml` | Weekly (Monday 06:00 UTC) or manual | Trivy scan of the published image, reporting fixable HIGH/CRITICAL findings to code scanning |
| `deploy-to-hugging-face.yml` | Manual (`workflow_dispatch`) | Syncs the repository to a Hugging Face Space with the `hf` CLI over OIDC Trusted Publishers |
| `stale.yml` | Daily (01:30 UTC) or manual | Marks and closes inactive issues and labels stale pull requests |
| `reusable-check-docker.yml` | Called by other workflows | Docker compose production build + health check via `curl localhost:7860` (lint/format/test are covered by `ci.yml`) |

### Reusable Workflow (`reusable-check-docker.yml`)

Used by both `on-push-to-main` and `on-pull-request-to-main` to run the production container smoke test:

1. **check-docker-container** - Builds and starts the production container with `docker compose -f docker-compose.production.yml up -d`, then verifies the main page returns HTTP 200 within 60 seconds

### Docker Image Builds

The Docker image uses a single runtime stage:
The image installs Python/SearXNG, builds the Vite frontend, and runs SearXNG and Node.js in a single container via shell process composition. No compilation step is required: the reranker's ONNX Runtime binaries ship prebuilt with the npm dependency.

The production image is published to `ghcr.io` with multi-platform support (linux/amd64, linux/arm64). Labels are auto-generated from Git metadata via `docker/metadata-action`, and each release is published as `latest` and as its CalVer version tag; to pin a build, users reference the version tag or the image digest. Weekly, `scan-docker-image.yml` runs Trivy against the published `latest` and reports fixable HIGH/CRITICAL findings to code scanning.

### Manual Deployments

- **Publish Docker Image**: Triggered via GitHub UI from `main`, with an optional CalVer `version` input (leave it empty to auto-compute today's date in UTC and the next free same-day sequence) — builds and pushes the image to GitHub Container Registry, then pushes the git tag and publishes the GitHub Release
- **Deploy to Hugging Face**: Triggered via GitHub UI — syncs the repository to a Hugging Face Space using configuration from `.github/hf-space-config.yml`

## Quality Assurance

- **`docker compose exec development-server npm run lint`**: Biome linting, TypeScript checking, dependency validation, copy-paste detection, architectural validation, and documentation checks
- **`docker compose exec development-server npm run format`**: Format code with Biome (enforced via pre-commit hooks)

## Related Topics

- **Quick Start**: `docs/quick-start.md` - Installation and first run
- **Configuration**: `docs/configuration.md` - Environment variables
- **Pull Requests**: `docs/pull-requests.md` - Contribution workflow