Skip to content

AGENTS.md

Latest commit

 

History

History
43 lines (37 loc) · 3.04 KB

AGENTS.md

File metadata and controls

43 lines (37 loc) · 3.04 KB
Raw

AGENTS.md

Repo Reality

  • README.md is still Bun scaffold text; trust package.json scripts instead.
  • This is a single Bun + TypeScript service (not a monorepo).

Entrypoints and Runtime Flow

  • Main boot is src/index.ts: load config -> init DB -> init permission helper -> ensure log dir -> start task queue processing -> init Aptly -> sync additional live-repo files -> init API -> start Aptly -> start Hono API.
  • bun run start (and compiled binaries) use scripts/entrypoint.ts, which force-sets LRA_DB_AUTO_MIGRATE=true.
  • bun run dev runs src/index.ts directly and does not force migrations.
  • When the users table is empty, startup creates a default admin user and writes a reset URL to ${LRA_CONFIG_BASE_DIR}/initial_admin_password_reset_token.txt.

Required Env and Host Tools

  • Required env vars are enforced in src/utils/config.ts; missing required keys exit the process.
  • Required keys include LRA_PRIVATE_KEY_PATH, LRA_PUBLIC_KEY_PATH, and all LRA_S3_* settings.
  • Boolean env parsing is strict: only the string "true" becomes true; everything else becomes false.
  • First Aptly startup downloads a binary to ${LRA_APTLY_ROOT}/bin/aptly; host needs network access and unzip.
  • Package upload verification runs dpkg --info; keep dpkg available for release upload flows/tests.

Commands (Source of Truth)

  • Install deps: bun install
  • Dev server: bun run dev
  • Start server (auto-migrate): bun run start
  • Typecheck: bun run typecheck (checks src, tests, scripts)
  • Run all tests: bun test
  • Run one test file: bun test tests/permission-helper.test.ts
  • DB workflow after schema edits: bun run db:generate then bun run db:migrate
  • Regenerate Aptly API client: bun run aptly-api-client:generate
  • Compile binary: bun run compile <platform|auto|all> [version] [--no-version-tag]
  • Docker expects build/bin/leios-api-linux-x64-baseline; generate with bun run compile linux-x64-baseline --no-version-tag.

Testing Gotchas

  • bunfig.toml preloads tests/helpers/preload.ts for every test run.
  • Preload builds a self-contained test env with a temp DB, generated GPG keys, and a local s3rver, then starts the Hono API on port 12151 and Aptly on a random free dynamic port.
  • Tests are integration-heavy (DB + Aptly + S3-style publish config + generated local GPG keys), not pure unit tests.
  • The test preload does not start TaskScheduler.processQueue(), so routes that enqueue tasks only create DB task records unless a test starts the scheduler explicitly.
  • tests/aptly.test.ts needs .deb fixtures under testdata/.

Codegen and Edit Boundaries

  • src/aptly/api-client/** is generated by openapi-ts; do not hand-edit generated files.
  • After DB schema changes, commit both drizzle/*.sql and drizzle/meta/*.
  • Keep API responses aligned with APIResponse; success responses include data, error responses currently return success, code, and message.
  • Package/release delete/upload routes enqueue testing-repo:update; these tasks only execute when the task scheduler loop is running.