Add artifact vault contents
This commit is contained in:
109
projects/dotfiles/072-pi-ui-patched-pi-packaging-research.md
Normal file
109
projects/dotfiles/072-pi-ui-patched-pi-packaging-research.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
status: resolved
|
||||
parent: "[[070-pi-ui-flex-spacer-pi-patch-task]]"
|
||||
blocked-by: []
|
||||
resolved-at: "2026-08-01T08:35:00-04:00"
|
||||
tags:
|
||||
- ticket/research
|
||||
---
|
||||
|
||||
# Patched Pi packaging research
|
||||
|
||||
## Question
|
||||
|
||||
How should the flex-spacer Pi layout patch be packaged in this dotfiles flake so the ordinary `pi` command uses it after rebuild?
|
||||
|
||||
## Findings
|
||||
|
||||
The flex-spacer change is not an extension-only change.
|
||||
Pi's interactive mode source adds TUI children directly in `packages/coding-agent/src/modes/interactive/interactive-mode.ts`: header, loaded resources, chat, pending messages, status, widgets above editor, editor, widgets below editor, and footer.
|
||||
That is the layout stack the flex-spacer must change.
|
||||
Source: `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/modes/interactive/interactive-mode.ts`.
|
||||
|
||||
The installed Pi package is the nixpkgs `pi-coding-agent` package at version `0.82.1`.
|
||||
Its nixpkgs derivation builds from the upstream GitHub tag `v0.82.1`, restores the generated model catalog from the published npm package, builds TypeScript workspace packages, and wraps `$out/bin/pi` with Nix-provided `ripgrep` and `fd` on `PATH` plus default telemetry/version-check environment variables.
|
||||
Source: `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.
|
||||
|
||||
The active installed wrapper confirms the nixpkgs wrapper shape.
|
||||
`/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi` prepends Nix-store `fd` and `rg` paths, sets `PI_SKIP_VERSION_CHECK` and `PI_TELEMETRY`, then execs `.pi-wrapped` inside the same package output.
|
||||
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi`.
|
||||
|
||||
The current dotfiles Pi module uses Home Manager's `programs.pi-coding-agent` module.
|
||||
It currently sets `enable`, `settings`, managed extension files, and managed prompt files, but does not override the Pi package.
|
||||
Source: `modules/agents/pi/pi.nix`.
|
||||
|
||||
The Home Manager Pi configuration does expose a `package` option in this evaluated system.
|
||||
A targeted eval of `home-manager.users.alexion.programs.pi-coding-agent` returned keys including `package`, and an `extendModules` eval setting `home-manager.users.alexion.programs.pi-coding-agent.package = pkgs.pi-coding-agent.overrideAttrs (...)` changed the evaluated package name to `pi-coding-agent-test-0.82.1`.
|
||||
Source: `nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.programs.pi-coding-agent`; command verification in this research session.
|
||||
|
||||
The patch should therefore be applied by overriding `programs.pi-coding-agent.package`, not by installing a competing wrapper or copying a patched tree under home.
|
||||
A package override keeps the ordinary `pi` command managed by Home Manager and preserves the nixpkgs wrapper behavior unless deliberately changed.
|
||||
Sources: `modules/agents/pi/pi.nix`; `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.
|
||||
|
||||
The safest patch point is source-level patching before the TypeScript build, not post-install editing of generated JavaScript.
|
||||
The nixpkgs package builds from upstream TypeScript source and already runs the TypeScript build in `buildPhase`, so a `patches = [...]` or `postPatch` override can modify `packages/coding-agent/src/modes/interactive/interactive-mode.ts` and `packages/coding-agent/src/utils/tools-manager.ts` before compiled output is produced.
|
||||
Source: `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.
|
||||
|
||||
The tool lookup hardening belongs in the same package override if the layout patch already overrides Pi.
|
||||
Upstream `tools-manager.ts` currently treats a local tool path as available if the file exists and treats `spawnSync(cmd, ["--version"])` as success whenever there is no spawn error, without requiring exit status `0`.
|
||||
On NixOS this allowed an unusable generic Linux `~/.pi/agent/bin/fd` to mask the working Nix `fd` on `PATH`.
|
||||
Source: `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/utils/tools-manager.ts`.
|
||||
|
||||
A package override avoids the hardcoded-wrapper problem that a post-install copied package would create.
|
||||
If we copied the already-built installed package manually, its `bin/pi` script would still contain hardcoded store paths to the original `.pi-wrapped` and original Nix `fd`/`rg` inputs.
|
||||
Using `pkgs.pi-coding-agent.overrideAttrs` and the original derivation's `postFixup` lets Nix regenerate the wrapper for the patched output.
|
||||
Sources: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi`; `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.
|
||||
|
||||
The likely dotfiles shape is:
|
||||
|
||||
```nix
|
||||
let
|
||||
patchedPi = pkgs.pi-coding-agent.overrideAttrs (old: {
|
||||
patches = (old.patches or [ ]) ++ [ ./patches/pi-flex-spacer.patch ];
|
||||
});
|
||||
in {
|
||||
home-manager.users.${user}.programs.pi-coding-agent = {
|
||||
enable = true;
|
||||
package = patchedPi;
|
||||
# existing settings unchanged
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
If the patch is implemented with `postPatch` instead of a patch file, preserve any upstream `old.postPatch` first.
|
||||
A patch file is preferable for reviewability because it makes the layout and tool-lookup changes explicit.
|
||||
|
||||
## Answer
|
||||
|
||||
Package the flex-spacer as a source-level patch to `pkgs.pi-coding-agent` and set `home-manager.users.${user}.programs.pi-coding-agent.package` to that overridden package in `modules/agents/pi/pi.nix`.
|
||||
|
||||
Do not package it as a separate extension.
|
||||
Do not use the throwaway copied tree under `~/.local/share` for deployment.
|
||||
Do not copy the built package output and edit generated JavaScript unless no source-level override works, because the installed wrapper hardcodes store paths and Nix's original derivation already knows how to rebuild and rewrap Pi correctly.
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Create a reviewed patch file under the dotfiles Pi module, for example `modules/agents/pi/patches/pi-flex-spacer.patch`.
|
||||
Patch these upstream source files:
|
||||
|
||||
- `packages/coding-agent/src/modes/interactive/interactive-mode.ts`
|
||||
- `packages/coding-agent/src/utils/tools-manager.ts`
|
||||
|
||||
Then override the package in `modules/agents/pi/pi.nix` and assign it to `programs.pi-coding-agent.package`.
|
||||
|
||||
The implementation ticket `[[070-pi-ui-flex-spacer-pi-patch-task]]` should prefer this packaging plan.
|
||||
|
||||
## Limitations
|
||||
|
||||
This research verified the package option by evaluation and inspected the current nixpkgs package source.
|
||||
It did not build the final override or run the patched source-level derivation.
|
||||
|
||||
The upstream Pi source path was realized with `nix build --no-link` during research because the fetched source store path had not yet been materialized.
|
||||
|
||||
## Citations
|
||||
|
||||
- `modules/agents/pi/pi.nix`.
|
||||
- `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.
|
||||
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi`.
|
||||
- `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/modes/interactive/interactive-mode.ts`.
|
||||
- `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/utils/tools-manager.ts`.
|
||||
Reference in New Issue
Block a user