y/kotsukotsu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kotsukotsu/AGENTS.md
polwex d88355267a m
2026-04-19 04:33:19 +07:00

3.3 KiB
Raw Permalink Blame History

Repository Guidelines

Project Structure

src/ holds the React client: components in src/components/, hooks in src/hooks/, lesson data in src/data/, and CSS in src/styles/. server.ts is the Bun entrypoint; server-only code lives in server/ (auth.ts, db.ts, config.ts). Nix files are split between flake.nix, generated bun.nix, and reusable deployment pieces in nix/.

Local Development

  • bun install: install dependencies from bun.lock.
  • bun run dev: start the Bun server with HMR on port 5174.
  • bun run lint: run ESLint.
  • bun run typecheck: run tsc -b.
  • bun run build: bundle the Bun server into build/.
  • bun run update:bun-nix: regenerate bun.nix after dependency changes.

Run bun run lint && bun run typecheck && bun run build before opening a PR.

Coding Conventions

TypeScript is strict on both client and server. Follow the existing style: single quotes in frontend files, PascalCase component filenames, useX hook names, and lowercase data/config modules. Keep runtime configuration in server/config.ts rather than scattering process.env reads.

Bun2nix Setup

This repo uses Bun as the package manager and bun2nix for reproducible Nix builds. The flow is:

  • bun.lock is the source of truth for JS dependencies.
  • bun.nix is generated from bun.lock with bun run update:bun-nix.
  • flake.nix imports the bun2nix overlay and exposes packages.<system>.default plus nixosModules.default.
  • nix/package.nix uses bun2nix.fetchBunDeps with bun.nix, runs bun run build, and installs the bundled server.js plus frontend assets as the kotsukotsu executable.

Whenever dependencies change, update both bun.lock and bun.nix in the same commit. CI checks that bun.nix matches the lockfile by regenerating it and failing on diff.

Server and Deployment Model

This repo is the application source, not the full server configuration. Production is intended to be managed from a separate NixOS infra repo that imports this flake and sets services.kotsukotsu.package = inputs.kotsukotsu.packages.${pkgs.system}.default;. The included module in nix/module.nix defines the systemd service, runtime env (APP_ORIGIN, PORT, SQLITE_PATH, SESSION_COOKIE_SECURE), and persistent state directory.

server/config.ts exists so production behavior is explicit: WebAuthn origin/RP ID, SQLite path, bind host, and secure cookies should come from NixOS service configuration, not reverse-proxy accident.

Forgejo and Woodpecker

Forgejo should be the canonical remote and PR system. Woodpecker runs repo CI from .woodpecker.yml: install deps in the flake dev shell, lint, typecheck, build, regenerate bun.nix, and nix build .#default. That validates the app package only.

Production deployment belongs in the separate infra repo. The expected flow is:

  • merge app changes in Forgejo
  • update the infra repo input that pins this app revision
  • let Woodpecker in the infra repo run nixos-rebuild --target-host ...

Keep app CI and host deployment separate; this repo proves the package is buildable, while the infra repo owns the actual VPS switch.

PR Guidance

Use focused, imperative commit messages such as auth: honor configured app origin or nix: package app with bun2nix. PRs should list verification steps and mention any dependency updates, bun.nix regeneration, or NixOS module changes.