alexion
6a9d4d4770
`nix develop` now yields the toolchain the repository actually needs — Node, `git`, `tea`, and `curl` — giving a declarative answer to "what do I need to work on this", which the repository previously specified nowhere. The shell takes its Node from the package's `passthru` rather than naming `pkgs.nodejs` a second time, so development and the shipped artifact cannot drift onto different majors and cannot be set independently. `package.nix` declares that `passthru` as an interface rather than leaving the shell to read an incidental build attribute; it does not enter the derivation, so the store path is unchanged. The checks output aliases the package, so `nix flake check` builds it and thereby runs both its verification phases instead of being a silent no-op. No per-stage checks: the only stage adding coverage is the full typecheck, which spans `test/` and `bench/` and would drag the benchmark harness into the derivation's inputs, undoing the source filtering. It stays in CI. The shell deliberately omits `gitea-axi` itself. The benchmark's arm resolves that binary by name off PATH and must get the locally built `dist/main.js`, so supplying the packaged one would silently substitute the wrong artifact.
6.9 KiB
gitea-axi — Agent Instructions
Commits
Any commit message you write must follow the Conventional Commits specification as documented in CONVENTIONAL-COMMITS.md.
Gotchas
The origin remote is a self-hosted Gitea instance (git.alexion.dev), not GitHub.
The gh CLI does not work here.
The benchmark arms invoke the built dist/main.js (the gitea-axi binary on PATH), not the TypeScript source.
Run npm run build before any live bench:run if you want src/ changes reflected; the bench does not run from source.
Prefer this project's own CLI for pull requests — it is the tool being built, so opening its PRs with it is the dogfood path:
npm run build && node dist/main.js pr create --login alexion --base main --head <branch> --title <text> --body-file <path>.
It reuses the tea login store, which here holds exactly alexion — there is no axi profile, and the csv-reviewer profile that used to exist is gone for good.
selectLogin matches the --login value against those names exactly, so --login alexion works and an unknown name like --login axi fails with VALIDATION_ERROR ("Login profile "axi" not found").
Fall back to tea pr create --login alexion --base main --head <branch> only for what gitea-axi cannot do yet; tea pr still lists PRs until pr list lands (task 0008).
The same login store backs the benchmark: npm run bench:run -- --arm <arm> --login alexion --task <id> (or set GITEA_AXI_BENCH_LOGIN=alexion).
The bench/ unit tests only run under their own Vitest project config: npx vitest run --config vitest.bench.config.ts bench/<file>.test.ts.
Plain npx vitest run bench/<file>.test.ts reports "no tests" because the default vitest.config.ts includes only test/**.
Task branches are merged into main on the remote, so the local main goes stale.
Always git fetch origin and cut a task branch from origin/main, not from whatever local main happens to point at.
Gitea's issue/PR search endpoint (GET /repos/issues/search, behind search issues/search prs) is backed by an asynchronous, eventually-consistent issue indexer (bleve by default).
Content created moments earlier may not be searchable yet, so end-to-end assertions that create an issue/PR and then search for it must poll (e.g. expect.poll) until it is indexed rather than searching once.
The fixture tier is unaffected — it stubs the endpoint — so this bites only the live test/e2e tier.
tea is still a runtime dependency, despite ADR 0002 being titled "use direct Gitea API instead of wrapping the tea subprocess".
That ADR moved command dispatch to gitea-js; it explicitly kept tea for credential discovery, and its own Consequences section says so.
Per ADR 0001 as amended, src/context.ts resolves auth by shelling out to tea login list --output json (discovery) and tea login helper get --login <name> (token, with in-place OAuth refresh).
The only bypass is the test hook requiring GITEA_AXI_API_URL + GITEA_AXI_TOKEN + GITEA_AXI_REPO together; there is no user-facing path that avoids tea, and TEA_NOT_INSTALLED exists for its absence.
Neither node/npm nor tea is on the PATH in a non-interactive shell on this machine, and there is no ~/.gitconfig.
This is a NixOS host with no global Node install, so run work through the flake's dev shell: nix develop --command <cmd>, which carries Node, git, tea, and curl — enough for the build, the fast tier, the live end-to-end tier, and the benchmark harness's own runner.
That covers anything resolving credentials, including gitea-axi pr create.
The shell deliberately does not put gitea-axi on the PATH, so a live bench:run of the gitea-axi arm still needs the built binary exposed under that name itself — see the benchmark gotcha above.
nix shell nixpkgs#nodejs -c ... still works for a one-off outside the repository, but inside it the dev shell is the declarative answer and pins the same Node the package is built against.
node_modules/ may be absent too, so npm ci first.
Commits need an explicit identity: git -c user.name=alexion -c user.email=contact@alexion.dev commit ..., matching the existing history.
The Nix derivation's source is an explicit allowlist in package.nix, not the whole repository and not a gitignore filter.
A new build-relevant top-level file — a TypeScript configuration, a runner configuration the fast tier loads, a directory the build reads — must be added to that lib.fileset.unions list or nix build fails on a missing file.
The failure is loud but disconnected from its cause: the error names the missing file, not the allowlist that omitted it.
The flip side is the point of the design — touching an ADR, a spec, a task, a bench/ file, or prose documentation must not change the derivation's output path.
buildNpmPackage provides no check hook, so doCheck = true on its own is silently inert — the build logs no Makefile or custom checkPhase, doing nothing and ships a package whose tests never ran.
Running the fast tier inside the derivation requires an explicit checkPhase; it also needs git and which in nativeCheckInputs and a writable HOME, since some of those tests shell out to git.
nodejsInstallExecutables (inside npmInstallHook) installs each manifest bin entry as a generated wrapper that invokes node <path> explicitly, not as a symlink to the entrypoint.
So under Nix the executable bit on dist/main.js is not load-bearing — chmod -x on it changes nothing — while the bit on $out/bin/gitea-axi is, and makeWrapper always sets it.
The npm path differs: there the bin entry is symlinked and npm sets the bit at install time.
npmInstallHook runs npm prune --omit=dev against the build tree's node_modules during installPhase, so dev dependencies (vitest included) are gone by the time postInstall or installCheckPhase runs.
Anything that needs them after install must snapshot the tree in preInstall first; cp -al is the cheap way, since the prune's deletions do not follow hardlinks.
Running vitest inside the derivation leaves a run cache at node_modules/.vite/…/results.json that records durations and timestamps, and npmInstallHook copies node_modules into $out wholesale.
Left alone it ships a stray cache in the closure and makes the output non-reproducible — visible only under nix build --rebuild, which reports "may not be deterministic"; an ordinary build stays green.
checkPhase deletes it before the install phase runs.
nixpkgs 26.11 (the nixos-unstable the flake tracks) has dropped x86_64-darwin.
legacyPackages.x86_64-darwin now throws rather than merely failing to build, so listing that system in the flake's systems breaks nix flake show and nix flake check for every system at once, not just that one.
Intel macOS would need the 26.05 branch.