backup-manager/AGENTS.md

Repository Guide

• Requires Node.js 22+. Use npm run check for the required lint -> typecheck -> test -> build verification order; npm test -- <file> runs one Vitest file.
• src/server.ts owns HTTP/authentication, src/service.ts owns the single-worker queue and cron polling, and src/executor.ts owns ordered step execution, SFTP collection, staging, and retention. The React UI is intentionally a single entrypoint at web/src/main.tsx.
• Runtime configuration is mandatory: ADMIN_PASSWORD and a base64-encoded 32-byte MASTER_KEY. Tests import modules without either; do not load environment configuration at module scope outside src/server.ts.
• SQLite state lives under DATA_DIR; artifacts live under BACKUP_DIR. Store artifact paths relative to BACKUP_DIR and download to .staging before atomically moving completed runs.
• SSH host-key pinning is independent of password/private-key user authentication. Never weaken hostVerifier, log decrypted values, or store credentials outside AES-256-GCM envelopes from src/crypto.ts.
• Jobs contain ordered mixed steps but use one SSH host/connection. continueOnError yields succeeded_with_warnings; required failures publish no artifacts. Keep legacy single-operation normalization in src/schemas.ts while persisted old jobs may exist.
• Remote commands must quote every configured value with shellQuote. Docker outputs are container paths copied with docker cp; remote command outputs are staged immediately; database and directory operations run tools on the SSH host.
• Scheduling is single-instance and non-overlapping per job. On startup, src/db.ts marks queued/running work failed; do not imply distributed-worker safety without replacing this design.
• npm run dev starts Fastify on 3000 and Vite on 5173; production serves dist/public from the Fastify process. docker compose up --build runs as UID/GID 10001, so mounted data/backup paths must be writable by it.