docs: break the declarative install path into tasks (tasks 0043-0045)
All checks were successful
CI / test (22) (pull_request) Successful in 48s
CI / test (true, 24) (pull_request) Successful in 1m4s
CI / flake (pull_request) Successful in 3s
CI / test (22) (push) Successful in 55s
CI / test (true, 24) (push) Successful in 1m5s
CI / flake (push) Successful in 2s
All checks were successful
CI / test (22) (pull_request) Successful in 48s
CI / test (true, 24) (pull_request) Successful in 1m4s
CI / flake (pull_request) Successful in 3s
CI / test (22) (push) Successful in 55s
CI / test (true, 24) (push) Successful in 1m5s
CI / flake (push) Successful in 2s
Grilling task 0042's mitigation found its framing too narrow. Recording an absolute entrypoint path is one defect; the deeper one is that `setup` is write-only, and an operator whose agent configuration is generated declaratively cannot let it write at all. On such a machine both halves fail — `setup hooks` against a read-only settings file, and `setup` on an unhandled filesystem error — and the Agent Skill gets hand-copied into the operator's own configuration, where it silently drifts from the package that ships it. Three tasks follow: - 0043 records the bare binary name, resolved through PATH, so the hook survives an upgrade on any wrapper-based install. Fixes the marker-substring coupling with it and drops the derivation's build-tree rename. - 0044 reports an unwritable target as a structured error naming no cause, rather than crashing. - 0045 adds the declarative install path: a stable Skill location, the Skill and hook specification exposed as Nix-consumable attributes, one committed hook specification read by both the expression and the test suite, and a home-manager module wiring them. Blocked by 0043, whose bare name the specification declares. CONTEXT.md gains the four terms this settled and amends `setup` and `SessionStart hook`, which described the imperative path as the only one. Entries for unbuilt work name the task that lands them, so the glossary does not assert behaviour the code lacks. The re-run-after-upgrade help text this branch added stays as it is: accurate until 0043 removes it, which that task carries as a criterion.
This commit was merged in pull request #51.
This commit is contained in:
@@ -0,0 +1,29 @@
|
||||
---
|
||||
spec: nix-flake-packaging
|
||||
---
|
||||
|
||||
## What to build
|
||||
|
||||
Report an unwritable target as an error the user can act on, instead of crashing.
|
||||
|
||||
Both halves of `setup` assume the files they manage are writable.
|
||||
When they are not — because a configuration manager owns them, because a file is flagged immutable, because the path is root-owned — the skill install raises a raw filesystem error with no handling at all, and the hook install surfaces the underlying message through its error collector without saying what a reader should do about it.
|
||||
|
||||
Neither failure is exotic.
|
||||
Any tool that manages a user's agent configuration declaratively renders these paths read-only, and gitea-axi's own Nix install method encourages exactly that arrangement.
|
||||
|
||||
The error names the file and the condition, and points at the general remedy: the file appears to be managed elsewhere, so the skill or hook should be declared through that configuration rather than installed by this command.
|
||||
|
||||
It deliberately does not guess at the cause.
|
||||
Read-only is not diagnostic of any particular manager, and naming one would be wrong for most users who hit this.
|
||||
|
||||
The failure follows the CLI's existing error convention rather than inventing a shape, so it carries a code and help lines like every other error the tool reports.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] An unwritable skill target produces a structured CLI error rather than an unhandled filesystem exception.
|
||||
- [ ] An unwritable hook target produces the same class of error, with the same guidance.
|
||||
- [ ] Both errors name the file that could not be written and state that it appears to be managed by another tool.
|
||||
- [ ] Neither error names or infers a specific configuration manager.
|
||||
- [ ] A skill target that is unwritable but already byte-identical to the bundled copy succeeds rather than failing, since nothing needs to be written.
|
||||
- [ ] The errors carry a code and help lines consistent with the rest of the CLI's error surface.
|
||||
Reference in New Issue
Block a user