docs: record that the session-start hook stores an absolute path (task 0042)
All checks were successful
CI / test (22) (pull_request) Successful in 46s
CI / test (true, 24) (pull_request) Successful in 1m6s
CI / flake (pull_request) Successful in 3s

Resolve the nix-flake-packaging spec's open verification item by observation
rather than inference, and act on the unfavourable answer.

`resolvePortableHookCommand` in axi-sdk-js returns the bare binary name only
when a PATH entry realpath-matches the entrypoint. npm symlinks its bin entry
straight at dist/main.js and satisfies that; Nix installs a generated wrapper
script whose realpath is the wrapper, so the absolute store path is recorded
instead. Verified by probing the SDK with both install shapes and by driving
the flake-built binary against a temporary HOME.

The path is content-addressed, so it moves on every rebuild and is eventually
collected, and a session-start hook that cannot execute fails silently. The
mitigation is documentation, per the decision recorded when the item was
opened: the setup help text now says to re-run `setup hooks` after an upgrade.

How the setup command constructs the hook is deliberately unchanged. Preferring
the bare name is the right answer for every wrapper-based install, not a Nix
special case, so it belongs in a successor task with its own ADR alongside the
related `isManagedHook` substring defect. package.nix's postUnpack rename
therefore stays; its comment no longer promises this task will remove it.
This commit is contained in:
2026-07-20 10:03:45 -04:00
parent 710bbfdeac
commit 397da5d7a6
5 changed files with 88 additions and 13 deletions

View File

@@ -68,9 +68,12 @@ buildNpmPackage {
# finding "gitea-axi" within it. Naming the tree makes the build representative
# rather than an environment no operator ever has.
#
# This coupling is a defect, not a property worth preserving — see task 0042,
# which removes the hook's dependence on the entrypoint path entirely. Once it
# lands this rename should go with it.
# This coupling is a defect, not a property worth preserving. Task 0042
# verified the resolution behaviour and documented the mitigation, but left
# the hook's dependence on the entrypoint path in place: removing it needs its
# own ADR, since a stable search-path name is the right answer for every
# installation method and not a Nix special case. This rename goes away with
# that task, not before.
postUnpack = ''
mv "$sourceRoot" gitea-axi
export sourceRoot=gitea-axi