agnix setup

Author: davidabram

README.md

@@ -12,3 +12,45 @@ This repository contains system prompts, agent configuration patterns, and evals
 
 Built by [CroCoder](https://www.crocoder.dev/)
 
+## Dev shell agnix tooling
+
+This repository exposes `agnix` and `agnix-lsp` through `nix develop` using a Nix-first shell with Rust toolchain support.
+
+### Quick start
+
+```bash
+nix develop
+agnix --help
+agnix-lsp --help
+```
+
+### Shell behavior
+
+- On shell entry, `shellHook` adds `~/.cargo/bin` to `PATH`.
+- If `agnix` is missing, `shellHook` automatically runs `cargo install --locked agnix-cli`.
+- `agnix-lsp` is provided by a shim that resolves in this order:
+  1. `AGNIX_LSP_BIN` (when set to an executable path)
+  2. `~/.cargo/bin/agnix-lsp`
+  3. A manual-install guidance message (non-zero exit)
+
+### Manual fallback for agnix-lsp
+
+```bash
+cargo install --locked agnix-lsp
+```
+
+Optional explicit override:
+
+```bash
+export AGNIX_LSP_BIN="$HOME/.cargo/bin/agnix-lsp"
+```
+
+### Verification
+
+```bash
+nix flake check
+nix develop -c which agnix
+nix develop -c which agnix-lsp
+nix develop -c agnix --help
+nix develop -c agnix-lsp --help
+```

context/patterns.md

@@ -5,6 +5,13 @@
 - Use the Nix dev shell as the canonical toolchain entrypoint for generation work.
 - `flake.nix` includes `pkl` so contributors can run validation commands with `nix develop -c ...` without host-level installs.
 
+## Dev-shell fallback shims for unavailable nixpkgs tools
+
+- When required CLI tools are not available as direct nixpkgs attrs, use the least-friction dev-shell fallback that keeps commands usable in `nix develop`.
+- Current repo behavior: include `cargo` and `rustc` in `devShells.default`, export `~/.cargo/bin` on `PATH`, and auto-run `cargo install --locked agnix-cli` in `shellHook` when `agnix` is missing.
+- `agnix-lsp` currently remains shim-based: use `AGNIX_LSP_BIN` when set and executable, otherwise use `~/.cargo/bin/agnix-lsp` when present, otherwise print manual install guidance and exit non-zero.
+- `shellHook` prints a version banner for `bun`, `pkl`, `tsc`, `typescript-language-server`, `rustc`, and `agnix` so shell state is visible on entry.
+
 ## Pkl renderer layering
 
 - Keep target-agnostic canonical content in `config/pkl/base/shared-content.pkl`.

context/plans/agnix-dev-shell.md

@@ -1,23 +1,23 @@
 # Plan: agnix-dev-shell
 
 ## 1) Change summary
-Add `agnix` and `agnix-lsp` to the repository Nix dev environment in `flake.nix` using a reproducible Nix-first approach, without automatic networked Cargo installs during `nix develop`.
+Add `agnix` and `agnix-lsp` to the repository Nix dev environment in `flake.nix` using a reproducible Nix-first approach, with automatic `cargo install` for `agnix-cli` during `nix develop` when `agnix` is missing.
 
 ## 2) Success criteria
 - `nix develop` exposes `agnix` and `agnix-lsp` on `PATH` for contributors.
-- The solution is Nix-first and does not auto-run `cargo install` from shell startup.
-- If direct Nix packages are unavailable, the fallback behavior is explicitly documented and non-automatic.
+- The solution is Nix-first and auto-runs `cargo install --locked agnix-cli` from shell startup when `agnix` is missing.
+- If direct Nix packages are unavailable, fallback behavior is explicitly documented for remaining tools.
 - Verification steps for command availability and basic execution are documented and pass.
 
 ## 3) Constraints and non-goals
 - In scope: dev-shell changes in `flake.nix` and related developer docs/context updates.
 - In scope: package resolution for both `agnix` and `agnix-lsp` in nixpkgs (or explicit non-auto fallback guidance).
 - Out of scope: Home Manager activation logic and system-level package installation.
 - Out of scope: changing application/runtime code outside environment and docs/context artifacts.
-- Non-goal: adding networked auto-install behavior in `shellHook`.
+- Non-goal: adding networked auto-install behavior in `shellHook` for tools other than `agnix`.
 
 ## 4) Task stack (T01..T05)
-- [ ] T01: Confirm package sourcing strategy and exact package attrs (status:todo)
+- [x] T01: Confirm package sourcing strategy and exact package attrs (status:done)
   - Task ID: T01
   - Goal: Resolve the concrete Nix package names/attrs for `agnix` and `agnix-lsp` (or define explicit documented fallback if one is missing).
   - Boundaries (in/out of scope):
@@ -28,8 +28,12 @@ Add `agnix` and `agnix-lsp` to the repository Nix dev environment in `flake.nix`
     - Strategy remains Nix-first and non-networked at shell startup.
   - Verification notes (commands or checks):
     - Evaluate package availability via flake/package checks used in this repo workflow.
+  - Evidence:
+    - Verified nixpkgs attribute availability in this repo flake context with `nix eval --json --impure --expr 'let flake = builtins.getFlake (toString ./.); pkgs = import flake.inputs.nixpkgs { system = builtins.currentSystem; }; in { agnix = builtins.hasAttr "agnix" pkgs; agnix_lsp = builtins.hasAttr "agnix-lsp" pkgs; }'`, which returned `{ "agnix": false, "agnix_lsp": false }`.
+    - Confirmed strategy for follow-up tasks: no direct nixpkgs attrs currently exist for `agnix` or `agnix-lsp`, so maintain Nix-first behavior where possible and document any fallback as explicit manual/non-automatic guidance (no networked install in `shellHook`).
+    - Ran repository light check `nix flake check` after resolution; dev shell derivation evaluates successfully on the current system.
 
-- [ ] T02: Update `flake.nix` dev shell to include agnix tooling (status:todo)
+- [x] T02: Update `flake.nix` dev shell to include agnix tooling (status:done)
   - Task ID: T02
   - Goal: Modify `devShells.default` package set so both commands are available in `nix develop`.
   - Boundaries (in/out of scope):
@@ -42,8 +46,12 @@ Add `agnix` and `agnix-lsp` to the repository Nix dev environment in `flake.nix`
     - `nix flake check`
     - `nix develop -c which agnix`
     - `nix develop -c which agnix-lsp`
+  - Evidence:
+    - Updated `flake.nix` to add `agnix` and `agnix-lsp` fallback-safe PATH shims via `pkgs.writeShellScriptBin`, keeping behavior non-automatic and avoiding networked installs in `shellHook`.
+    - Ran `nix flake check`; dev shell derivation evaluates successfully on the current system.
+    - Ran `nix develop -c which agnix` and `nix develop -c which agnix-lsp`; both commands resolve to Nix store shim binaries in the dev shell.
 
-- [ ] T03: Add developer-facing usage and fallback notes (status:todo)
+- [x] T03: Add developer-facing usage and fallback notes (status:done)
   - Task ID: T03
   - Goal: Document how contributors get `agnix` tooling in dev shell and what to do if a package is unavailable.
   - Boundaries (in/out of scope):
@@ -54,8 +62,11 @@ Add `agnix` and `agnix-lsp` to the repository Nix dev environment in `flake.nix`
     - Manual fallback instructions (if required) are clear and isolated.
   - Verification notes (commands or checks):
     - Docs dry-run review: follow written steps from clean shell entry to command verification.
+  - Evidence:
+    - Added `README.md` section "Dev shell agnix tooling" with Nix-first usage, explicit non-automatic fallback policy, manual Cargo fallback commands, optional `AGNIX_BIN`/`AGNIX_LSP_BIN` overrides, and `which`-based verification steps.
+    - Performed docs dry-run command checks: `nix develop -c which agnix` and `nix develop -c which agnix-lsp`.
 
-- [ ] T04: Sync context records for current-state environment behavior (status:todo)
+- [x] T04: Sync context records for current-state environment behavior (status:done)
   - Task ID: T04
   - Goal: Update relevant `context/` files so future sessions reflect the new dev-shell tooling state.
   - Boundaries (in/out of scope):
@@ -65,8 +76,13 @@ Add `agnix` and `agnix-lsp` to the repository Nix dev environment in `flake.nix`
     - Context files accurately describe how `agnix` and `agnix-lsp` are provided in this repo.
   - Verification notes (commands or checks):
     - Context/code consistency spot-check between `flake.nix` and updated context entries.
+  - Evidence:
+    - Updated `context/patterns.md` to reflect current state: dev shell now includes `cargo` and `rustc`, exports `~/.cargo/bin` on `PATH`, and auto-installs `agnix-cli` when `agnix` is missing.
+    - Updated `README.md` to match shell behavior and clarify that `agnix-lsp` remains shim/manual fallback based.
+    - Applied user-approved scope change to include automatic networked install of `agnix-cli` during shell startup.
+    - Spot-checked behavior with `nix flake check`, `nix develop -c which agnix`, `nix develop -c agnix --help`, and `nix develop -c which agnix-lsp`.
 
-- [ ] T05: Validation and cleanup (status:todo)
+- [x] T05: Validation and cleanup (status:done)
   - Task ID: T05
   - Goal: Run full verification, confirm success criteria evidence, and remove temporary artifacts.
   - Boundaries (in/out of scope):
@@ -82,6 +98,14 @@ Add `agnix` and `agnix-lsp` to the repository Nix dev environment in `flake.nix`
     - `nix develop -c agnix-lsp --help`
     - `nix develop -c which agnix`
     - `nix develop -c which agnix-lsp`
+  - Evidence:
+    - Ran `nix flake check` (exit 0): `devShells.x86_64-linux.default` evaluated successfully; incompatible-system warning reported for non-host platforms only.
+    - Ran `nix develop -c which agnix` (exit 0): resolved to `/home/davidabram/.cargo/bin/agnix`.
+    - Ran `nix develop -c which agnix-lsp` (exit 0): resolved to `/home/davidabram/.cargo/bin/agnix-lsp`.
+    - Ran `nix develop -c agnix --help` (exit 0): help text printed with command set (`validate`, `init`, `eval`, `telemetry`, `schema`).
+    - Ran `nix develop -c agnix-lsp --help` (exit 0): command returned successfully in the dev shell.
+    - Cleanup: removed temporary verification artifact directory `context/tmp/pkl-generated`; `context/tmp/` now only contains `.gitignore`.
+    - Success-criteria check: all plan success criteria now have explicit command evidence and passing verification on the current host.
 
 ## 5) Open questions
-- None. Scope and install-policy choices were confirmed: Nix packages first, and no auto network installs during shell startup.
+- None. Scope and install-policy choices are currently: Nix-first shell, automatic `cargo install --locked agnix-cli` when `agnix` is absent, and manual fallback behavior retained for `agnix-lsp`.

flake.nix

@@ -19,6 +19,30 @@
           inherit system;
         };
 
+        agnixLspShim = pkgs.writeShellScriptBin "agnix-lsp" ''
+                    set -euo pipefail
+
+                    if [ -n "''${AGNIX_LSP_BIN:-}" ] && [ -x "''${AGNIX_LSP_BIN}" ]; then
+                      exec "''${AGNIX_LSP_BIN}" "$@"
+                    fi
+
+                    if [ -x "$HOME/.cargo/bin/agnix-lsp" ]; then
+                      exec "$HOME/.cargo/bin/agnix-lsp" "$@"
+                    fi
+
+                    cat >&2 <<'EOF'
+          agnix-lsp is not bundled in nixpkgs for this dev shell yet.
+
+                    Manual fallback (non-automatic):
+                      cargo install --locked agnix-lsp
+
+                    Then either:
+                      - ensure ~/.cargo/bin is on PATH, or
+                      - set AGNIX_LSP_BIN to the agnix-lsp binary path.
+          EOF
+                    exit 1
+        '';
+
       in
       {
         devShells.default = pkgs.mkShell {
@@ -28,17 +52,29 @@
             pkl
             typescript
             nodePackages.typescript-language-server
+            agnixLspShim
+            cargo
+            rustc
           ];
 
           shellHook = ''
             version_of() {
               "$1" --version 2>/dev/null | awk 'match($0, /[0-9]+(\.[0-9]+)+/) { print substr($0, RSTART, RLENGTH); exit }'
             }
 
+            export PATH="$HOME/.cargo/bin:$PATH"
+
+            if [ ! -x "$HOME/.cargo/bin/agnix" ]; then
+              echo "- agnix: installing agnix-cli via cargo"
+              cargo install --locked agnix-cli
+            fi
+
             echo "- bun: $(version_of bun)"
             echo "- pkl: $(version_of pkl)"
             echo "- tsc: $(version_of tsc)"
             echo "- tsserver-lsp: $(version_of typescript-language-server)"
+            echo "- rust: $(version_of rustc)"
+            echo "- agnix: $(version_of agnix)"
           '';
         };
       }