docs/development-commands.md

Development Commands

Build & Development

• docker compose up: Start development server with HMR on port 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, llama-server, 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:ui: Run tests with UI
• docker compose exec development-server npm run test:coverage: Run tests with coverage report

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

  {
    "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 six GitHub Actions workflows for continuous integration, deployment, and release management:

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
on-push-to-main.yml	Push to main	Delegates to reusable-test-lint-ping.yml
on-pull-request-to-main.yml	PR opened/synced/reopened to main	Delegates to reusable-test-lint-ping.yml; skippable via skip-test-lint-ping label
publish-docker-image.yml	Manual (workflow_dispatch)	Builds multi-platform Docker image (linux/amd64, linux/arm64) and pushes to ghcr.io
deploy-to-hugging-face.yml	Manual (workflow_dispatch)	Syncs repository to Hugging Face Spaces using JacobLinCool/huggingface-sync
reusable-test-lint-ping.yml	Called by other workflows	Two-job pipeline: (1) npm ci --ignore-scripts && npm run lint, (2) Docker compose production build + health check via curl localhost:7860

Reusable Workflow (reusable-test-lint-ping.yml)

Used by both on-push-to-main and on-pull-request-to-main to avoid duplication:

1. check-code-quality - Installs dependencies (skipping postinstall scripts) and runs npm run lint
2. check-docker-container (depends on check-code-quality) - 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 multi-stage build:

1. Builder stage (llama-builder): Compiles llama-server from llama.cpp source, extracts shared libraries (libllama.so, libmtmd.so, libggml.so, etc.)
2. Runtime stage: Installs Python/SearXNG, copies llama-server binaries, builds the Vite frontend, runs SearXNG and Node.js in a single container via shell process composition

The production image is published to ghcr.io with multi-platform support (linux/amd64, linux/arm64). Tags and labels are auto-generated from Git metadata via docker/metadata-action.

Manual Deployments

• Publish Docker Image: Triggered via GitHub UI — builds and pushes to GitHub Container Registry
• 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