full ci-cd pipeline built on bun2nix

.gitignore

@@ -9,6 +9,7 @@ lerna-debug.log*
 
 node_modules
 dist
+build
 dist-ssr
 *.local
 

.woodpecker.yml

@@ -0,0 +1,14 @@
+when:
+  - event: [pull_request, push]
+
+steps:
+  checks:
+    image: nixos/nix:latest
+    commands:
+      - nix develop --accept-flake-config -c bun install --frozen-lockfile
+      - nix develop --accept-flake-config -c bun run lint
+      - nix develop --accept-flake-config -c bun run typecheck
+      - nix develop --accept-flake-config -c bun run build
+      - nix develop --accept-flake-config -c bun run update:bun-nix
+      - git diff --exit-code bun.nix
+      - nix build --accept-flake-config .#default

AGENTS.md

@@ -0,0 +1,46 @@
+# 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 `leo-ed` 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.leo-ed.package = inputs.leo-ed.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.

bun.lock

@@ -18,6 +18,7 @@
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react": "^6.0.1",
         "bun-types": "^1.3.11",
+        "bun2nix": "^2.0.8",
         "eslint": "^9.39.4",
         "eslint-plugin-react-hooks": "^7.0.1",
         "eslint-plugin-react-refresh": "^0.5.2",
@@ -253,6 +254,8 @@
 
     "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
 
+    "bun2nix": ["bun2nix@2.0.8", "", { "dependencies": { "sade": "^1.8.1" }, "bin": { "bun2nix": "index.ts" } }, "sha512-pwq35hA81X1Kjsi5Xo69Aii9aY3zZHhWXwqF1QRz/uB35KzKbwJZ16WrhadiG9/T6bjOsRrPZtzuAyqmlXopLw=="],
+
     "callsites": ["callsites@3.1.0", "", {}, "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ=="],
 
     "caniuse-lite": ["caniuse-lite@1.0.30001781", "", {}, "sha512-RdwNCyMsNBftLjW6w01z8bKEvT6e/5tpPVEgtn22TiLGlstHOVecsX2KHFkD5e/vRnIE4EGzpuIODb3mtswtkw=="],
@@ -429,6 +432,8 @@
 
     "minimatch": ["minimatch@3.1.5", "", { "dependencies": { "brace-expansion": "^1.1.7" } }, "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w=="],
 
+    "mri": ["mri@1.2.0", "", {}, "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA=="],
+
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
     "nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
@@ -485,6 +490,8 @@
 
     "rolldown": ["rolldown@1.0.0-rc.11", "", { "dependencies": { "@oxc-project/types": "=0.122.0", "@rolldown/pluginutils": "1.0.0-rc.11" }, "optionalDependencies": { "@rolldown/binding-android-arm64": "1.0.0-rc.11", "@rolldown/binding-darwin-arm64": "1.0.0-rc.11", "@rolldown/binding-darwin-x64": "1.0.0-rc.11", "@rolldown/binding-freebsd-x64": "1.0.0-rc.11", "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.11", "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.11", "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.11", "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.11", "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.11", "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.11", "@rolldown/binding-linux-x64-musl": "1.0.0-rc.11", "@rolldown/binding-openharmony-arm64": "1.0.0-rc.11", "@rolldown/binding-wasm32-wasi": "1.0.0-rc.11", "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.11", "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.11" }, "bin": { "rolldown": "bin/cli.mjs" } }, "sha512-NRjoKMusSjfRbSYiH3VSumlkgFe7kYAa3pzVOsVYVFY3zb5d7nS+a3KGQ7hJKXuYWbzJKPVQ9Wxq2UvyK+ENpw=="],
 
+    "sade": ["sade@1.8.1", "", { "dependencies": { "mri": "^1.1.0" } }, "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A=="],
+
     "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
 
     "semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],

flake.lock

@@ -0,0 +1,136 @@
+{
+  "nodes": {
+    "bun2nix": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "import-tree": "import-tree",
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "systems": "systems",
+        "treefmt-nix": "treefmt-nix"
+      },
+      "locked": {
+        "lastModified": 1770895533,
+        "narHash": "sha256-v3QaK9ugy9bN9RXDnjw0i2OifKmz2NnKM82agtqm/UY=",
+        "owner": "nix-community",
+        "repo": "bun2nix",
+        "rev": "c843f477b15f51151f8c6bcc886954699440a6e1",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "bun2nix",
+        "type": "github"
+      }
+    },
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1769996383,
+        "narHash": "sha256-AnYjnFWgS49RlqX7LrC4uA+sCCDBj0Ry/WOJ5XWAsa0=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "57928607ea566b5db3ad13af0e57e921e6b12381",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "import-tree": {
+      "locked": {
+        "lastModified": 1763762820,
+        "narHash": "sha256-ZvYKbFib3AEwiNMLsejb/CWs/OL/srFQ8AogkebEPF0=",
+        "owner": "vic",
+        "repo": "import-tree",
+        "rev": "3c23749d8013ec6daa1d7255057590e9ca726646",
+        "type": "github"
+      },
+      "original": {
+        "owner": "vic",
+        "repo": "import-tree",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1776169885,
+        "narHash": "sha256-l/iNYDZ4bGOAFQY2q8y5OAfBBtrDAaPuRQqWaFHVRXM=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "lastModified": 1769909678,
+        "narHash": "sha256-cBEymOf4/o3FD5AZnzC3J9hLbiZ+QDT/KDuyHXVJOpM=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "72716169fe93074c333e8d0173151350670b824c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "bun2nix": "bun2nix",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "treefmt-nix": {
+      "inputs": {
+        "nixpkgs": [
+          "bun2nix",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1770228511,
+        "narHash": "sha256-wQ6NJSuFqAEmIg2VMnLdCnUc0b7vslUohqqGGD+Fyxk=",
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "rev": "337a4fe074be1042a35086f15481d763b8ddc0e7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,58 @@
+{
+  description = "leo-ed typing app";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    bun2nix.url = "github:nix-community/bun2nix";
+    bun2nix.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  nixConfig = {
+    extra-substituters = [
+      "https://cache.nixos.org"
+      "https://nix-community.cachix.org"
+    ];
+    extra-trusted-public-keys = [
+      "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
+      "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
+    ];
+  };
+
+  outputs = { self, nixpkgs, bun2nix }:
+    let
+      systems = [ "x86_64-linux" "aarch64-linux" ];
+      forAllSystems = nixpkgs.lib.genAttrs systems;
+    in
+    {
+      packages = forAllSystems (system:
+        let
+          pkgs = import nixpkgs {
+            inherit system;
+            overlays = [ bun2nix.overlays.default ];
+          };
+        in
+        rec {
+          leo-ed = pkgs.callPackage ./nix/package.nix { };
+          default = leo-ed;
+        });
+
+      devShells = forAllSystems (system:
+        let
+          pkgs = import nixpkgs {
+            inherit system;
+            overlays = [ bun2nix.overlays.default ];
+          };
+        in
+        {
+          default = pkgs.mkShell {
+            packages = with pkgs; [
+              bun
+              bun2nix
+              nodejs
+            ];
+          };
+        });
+
+      nixosModules.default = import ./nix/module.nix;
+    };
+}

nix/module.nix

@@ -0,0 +1,115 @@
+{ config, lib, pkgs, ... }:
+
+let
+  cfg = config.services.leo-ed;
+in
+{
+  options.services.leo-ed = {
+    enable = lib.mkEnableOption "leo-ed typing app";
+
+    package = lib.mkOption {
+      type = lib.types.nullOr lib.types.package;
+      default = null;
+      description = "The leo-ed package to run, typically inputs.leo-ed.packages.${pkgs.system}.default.";
+    };
+
+    host = lib.mkOption {
+      type = lib.types.str;
+      default = "127.0.0.1";
+      description = "Listen address for the Bun server.";
+    };
+
+    port = lib.mkOption {
+      type = lib.types.port;
+      default = 5174;
+      description = "Listen port for the Bun server.";
+    };
+
+    domain = lib.mkOption {
+      type = lib.types.nullOr lib.types.str;
+      default = null;
+      example = "typing.example.com";
+      description = "Public domain used for WebAuthn RP ID and cookie origin.";
+    };
+
+    dataDir = lib.mkOption {
+      type = lib.types.str;
+      default = "/var/lib/leo-ed";
+      description = "Directory for the persistent SQLite database.";
+    };
+
+    user = lib.mkOption {
+      type = lib.types.str;
+      default = "leo-ed";
+      description = "User account for the service.";
+    };
+
+    group = lib.mkOption {
+      type = lib.types.str;
+      default = "leo-ed";
+      description = "Group for the service.";
+    };
+
+    secureCookies = lib.mkOption {
+      type = lib.types.bool;
+      default = true;
+      description = "Whether to mark auth cookies as Secure.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    assertions = [
+      {
+        assertion = cfg.package != null;
+        message = "services.leo-ed.package must be set, usually from this flake input.";
+      }
+      {
+        assertion = cfg.domain != null && cfg.domain != "";
+        message = "services.leo-ed.domain must be set.";
+      }
+      {
+        assertion = lib.hasPrefix "/" cfg.dataDir;
+        message = "services.leo-ed.dataDir must be an absolute path.";
+      }
+    ];
+
+    users.groups = lib.mkIf (cfg.group == "leo-ed") {
+      leo-ed = { };
+    };
+
+    users.users = lib.mkIf (cfg.user == "leo-ed") {
+      leo-ed = {
+        isSystemUser = true;
+        group = cfg.group;
+        home = toString cfg.dataDir;
+        createHome = false;
+      };
+    };
+
+    systemd.tmpfiles.rules = [
+      "d ${toString cfg.dataDir} 0750 ${cfg.user} ${cfg.group} -"
+    ];
+
+    systemd.services.leo-ed = {
+      description = "leo-ed typing app";
+      after = [ "network.target" ];
+      wantedBy = [ "multi-user.target" ];
+
+      environment = {
+        APP_ORIGIN = "https://${cfg.domain}";
+        HOST = cfg.host;
+        PORT = builtins.toString cfg.port;
+        SESSION_COOKIE_SECURE = lib.boolToString cfg.secureCookies;
+        SQLITE_PATH = "${cfg.dataDir}/leo-typing.db";
+      };
+
+      serviceConfig = {
+        ExecStart = lib.getExe cfg.package;
+        Group = cfg.group;
+        Restart = "on-failure";
+        User = cfg.user;
+        WorkingDirectory = cfg.dataDir;
+      };
+    };
+  };
+}

nix/package.nix

@@ -0,0 +1,54 @@
+{ lib
+, stdenvNoCC
+, bun
+, bun2nix
+, makeWrapper
+}:
+
+let
+  packageJson = lib.importJSON ../package.json;
+in
+stdenvNoCC.mkDerivation {
+  pname = "leo-ed";
+  version = packageJson.version;
+
+  src = lib.cleanSource ../.;
+  bunDeps = bun2nix.fetchBunDeps {
+    bunNix = ../bun.nix;
+  };
+
+  nativeBuildInputs = [
+    bun2nix.hook
+    bun
+    makeWrapper
+  ];
+
+  dontRunLifecycleScripts = true;
+  dontUseBunInstall = true;
+
+  buildPhase = ''
+    runHook preBuild
+    bun run build
+    runHook postBuild
+  '';
+
+  installPhase = ''
+    runHook preInstall
+
+    mkdir -p $out/share/leo-ed $out/bin
+    cp -r build/. $out/share/leo-ed/
+
+    makeWrapper ${lib.getExe bun} $out/bin/leo-ed \
+      --run "cd $out/share/leo-ed" \
+      --add-flags "$out/share/leo-ed/server.js"
+
+    runHook postInstall
+  '';
+
+  meta = {
+    description = "Typing practice app with passkey auth";
+    homepage = "https://example.invalid";
+    mainProgram = "leo-ed";
+    platforms = lib.platforms.linux;
+  };
+}

package.json

@@ -5,9 +5,11 @@
   "type": "module",
   "scripts": {
     "dev": "bun --hot server.ts",
-    "build": "tsc -b",
+    "build": "bun build --target bun server.ts --outdir build",
+    "build:prod": "bun run typecheck && bun run build",
     "lint": "eslint .",
-    "typecheck": "tsc -b"
+    "typecheck": "tsc -b",
+    "update:bun-nix": "bunx bun2nix -o bun.nix"
   },
   "dependencies": {
     "@simplewebauthn/browser": "^13.3.0",
@@ -23,6 +25,7 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "bun-types": "^1.3.11",
+    "bun2nix": "^2.0.8",
     "eslint": "^9.39.4",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",