alexion/gitea-axi
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

test: split the packaging tier and parameterize its installed binary (task 0036) #45

Merged
alexion merged 1 commits from task-0036-parameterized-installed-binary-tier into main 2026-07-19 22:38:00 -04:00
Conversation 0 Commits 1 Files Changed 7 +298 -190
alexion commented 2026-07-19 22:37:00 -04:00
Owner
Copy Link

Task: .claude/tasks/0036-parameterized-installed-binary-tier.md

First of the seven tasks implementing .claude/spec/nix-flake-packaging.md.

What was built

test/packaging/packaging.test.ts split into two facets, with the shared npm pack / extract / global-install mechanics factored into test/packaging/npm-artifact.ts:

  • tarball.test.ts — the shape of the packed tarball and its manifest. Npm-specific by nature; no other distribution method produces a tarball.
  • installed-binary.test.ts — what any installed gitea-axi must do, whatever installed it: run, render the dashboard against a fixture Gitea, and install its bundled Agent Skill.

The second facet takes the binary it drives from GITEA_AXI_INSTALLED_BIN. When that names an existing binary it drives it and skips pack-and-install entirely; unset (or empty) it packs and installs exactly as before, so the default developer experience is unchanged. A path that does not exist fails in beforeAll with an explanatory message rather than an opaque spawn ENOENT.

That makes one seam with two callers — the npm distribution path today, the Nix installation path in task 0038 — so the two cannot drift apart in what they guarantee. Nothing in the facet asserts on how the binary came to exist.

The runner configuration is untouched apart from its comments: its include glob already matched the whole directory.

Verification

Full tier run three ways, all green (7 tests), plus the fast suite (410 tests) and tsc --noEmit:

  • variable unset — both facets pack as before
  • pointing at a separately installed binary — installed-binary facet skipped its setup, 2.2s → 0.3s, no prepack build
  • empty string — falls back to pack-and-install

Deviations

Both minor and deliberate, and recorded in the task file's Implementation Notes:

  • The single it driving the installed binary became three (usage, render, Skill installation). The assertions do not change in character; this splits one case into the three behaviours the spec itself names, so a failure says which broke.
  • PUBLISHING.md's "Verifying the packed artifact" section was rewritten to describe the two facets and document the variable. Not an acceptance criterion, but the section described the tier as one undifferentiated thing and this change would have left it stale.

Consequence worth flagging for task 0038: the two facets now each run npm pack, so npm run test:pack builds twice. Invisible to the Nix build, which will run only installed-binary.test.ts against its own output rather than the full tier.

Review

Overall: LOW

  • Blast radius: Low — confined to test/packaging/ plus its config and PUBLISHING.md; no src/ or shipped artifact touched.
  • Reversibility: Low — a file split with assertions carried over; git revert restores the prior file exactly.
  • Test coverage: Low — this is the test tier, and every assertion from the deleted file reappears with no loss.
  • Sensitive domain: Low — no auth, permissions, or migrations; the one env var is a test-only opt-in that fails loudly on a bad path.
  • Size & complexity: Low — ~150 net lines, mostly moved; the one new branch is a guarded early return.
  • Runtime criticality: Low — dev-only tier, excluded from npm test, run via test:pack.

Three review findings were fixed in the diff: a factually wrong comment claiming fixture-server port collisions (the server binds port 0, so the real reason for fileParallelism: false is the shared dist/ that prepack writes), the empty-string env var being treated as provided, and PUBLISHING.md's stale singular framing.

Findings left unaddressed:

  • Standards — Duplicated Code (judgement call): the two test files each carry their own temp-dir create/remove lifecycle. Left as is: the two lifecycles are genuinely independent, and a shared helper would couple the files for three lines of setup.
  • Standards — Mysterious Name (judgement call): projectRoot is exported from npm-artifact.ts but tarball.test.ts uses it to locate PUBLISHING.md, an unrelated concern. Left as is: pre-existing coupling carried over unchanged, and worth addressing with the point below rather than alone.
  • Standards — Divergent Change (judgement call): tarball.test.ts's last case asserts both packed-manifest fields and that PUBLISHING.md mentions npm publish. Pre-existing, carried over verbatim; out of scope for a task about the installed-binary split.
  • Spec — over-factoring (minor): extractTarball has one caller, so unlike packTarball it did not need extracting. Left as is: it keeps the three npm-artifact mechanics described in one place at negligible cost.
Task: [`.claude/tasks/0036-parameterized-installed-binary-tier.md`](.claude/tasks/0036-parameterized-installed-binary-tier.md) First of the seven tasks implementing [`.claude/spec/nix-flake-packaging.md`](.claude/spec/nix-flake-packaging.md). ## What was built `test/packaging/packaging.test.ts` split into two facets, with the shared `npm pack` / extract / global-install mechanics factored into `test/packaging/npm-artifact.ts`: - **`tarball.test.ts`** — the shape of the packed tarball and its manifest. Npm-specific by nature; no other distribution method produces a tarball. - **`installed-binary.test.ts`** — what any *installed* gitea-axi must do, whatever installed it: run, render the dashboard against a fixture Gitea, and install its bundled Agent Skill. The second facet takes the binary it drives from `GITEA_AXI_INSTALLED_BIN`. When that names an existing binary it drives it and skips pack-and-install entirely; unset (or empty) it packs and installs exactly as before, so the default developer experience is unchanged. A path that does not exist fails in `beforeAll` with an explanatory message rather than an opaque spawn `ENOENT`. That makes one seam with two callers — the npm distribution path today, the Nix installation path in task 0038 — so the two cannot drift apart in what they guarantee. Nothing in the facet asserts on how the binary came to exist. The runner configuration is untouched apart from its comments: its `include` glob already matched the whole directory. ## Verification Full tier run three ways, all green (7 tests), plus the fast suite (410 tests) and `tsc --noEmit`: - variable unset — both facets pack as before - pointing at a separately installed binary — installed-binary facet skipped its setup, 2.2s → 0.3s, no `prepack` build - empty string — falls back to pack-and-install ## Deviations Both minor and deliberate, and recorded in the task file's Implementation Notes: - The single `it` driving the installed binary became three (usage, render, Skill installation). The assertions do not change in character; this splits one case into the three behaviours the spec itself names, so a failure says which broke. - `PUBLISHING.md`'s "Verifying the packed artifact" section was rewritten to describe the two facets and document the variable. Not an acceptance criterion, but the section described the tier as one undifferentiated thing and this change would have left it stale. Consequence worth flagging for task 0038: the two facets now each run `npm pack`, so `npm run test:pack` builds twice. Invisible to the Nix build, which will run only `installed-binary.test.ts` against its own output rather than the full tier. ## Review **Overall: LOW** - Blast radius: Low — confined to `test/packaging/` plus its config and `PUBLISHING.md`; no `src/` or shipped artifact touched. - Reversibility: Low — a file split with assertions carried over; `git revert` restores the prior file exactly. - Test coverage: Low — this *is* the test tier, and every assertion from the deleted file reappears with no loss. - Sensitive domain: Low — no auth, permissions, or migrations; the one env var is a test-only opt-in that fails loudly on a bad path. - Size & complexity: Low — ~150 net lines, mostly moved; the one new branch is a guarded early return. - Runtime criticality: Low — dev-only tier, excluded from `npm test`, run via `test:pack`. Three review findings were fixed in the diff: a factually wrong comment claiming fixture-server port collisions (the server binds port 0, so the real reason for `fileParallelism: false` is the shared `dist/` that `prepack` writes), the empty-string env var being treated as provided, and `PUBLISHING.md`'s stale singular framing. Findings left unaddressed: - **Standards — Duplicated Code (judgement call):** the two test files each carry their own temp-dir create/remove lifecycle. Left as is: the two lifecycles are genuinely independent, and a shared helper would couple the files for three lines of setup. - **Standards — Mysterious Name (judgement call):** `projectRoot` is exported from `npm-artifact.ts` but `tarball.test.ts` uses it to locate `PUBLISHING.md`, an unrelated concern. Left as is: pre-existing coupling carried over unchanged, and worth addressing with the point below rather than alone. - **Standards — Divergent Change (judgement call):** `tarball.test.ts`'s last case asserts both packed-manifest fields and that `PUBLISHING.md` mentions `npm publish`. Pre-existing, carried over verbatim; out of scope for a task about the installed-binary split. - **Spec — over-factoring (minor):** `extractTarball` has one caller, so unlike `packTarball` it did not need extracting. Left as is: it keeps the three npm-artifact mechanics described in one place at negligible cost.
alexion added 1 commit 2026-07-19 22:37:00 -04:00
test: split the packaging tier and parameterize its installed binary (task 0036)
All checks were successful
CI / test (pull_request) Successful in 53s
Details
CI / test (push) Successful in 52s
Details
6c31eb9e62 
The packaging tier held two kinds of assertion joined only by an
expensive shared setup: the shape of the packed tarball and its
manifest, and the behaviour of the resulting installed binary. Split
them, and teach the second to take the binary it drives from
GITEA_AXI_INSTALLED_BIN.

When that variable names an existing binary the tier drives it and skips
pack-and-install entirely; unset, it packs and installs exactly as
before. The installed-binary facet becomes one seam with two callers —
the npm distribution path today, the Nix installation path in task 0038
— so the two cannot drift apart in what they guarantee about an
installed gitea-axi. Nothing in it may assert on how the binary came to
exist, since store paths, wrapper internals, and the arrangement of the
installed tree are implementation detail of the installation method.

The tarball assertions stay npm-only: no other distribution method
produces a tarball or a packed manifest.
alexion merged commit 6c31eb9e62 into main 2026-07-19 22:38:00 -04:00
alexion deleted branch task-0036-parameterized-installed-binary-tier 2026-07-19 22:38:00 -04:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
alexion
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: alexion/gitea-axi#45
Delete Branch "task-0036-parameterized-installed-binary-tier"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?