Refactor approval tests -> bats

.github/workflows/test.yml

@@ -10,14 +10,12 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
+    - name: Install test dependencies
+      run: sudo apt-get update && sudo apt-get install -y bats shellcheck
     - name: Run shellcheck tests
-      run: shellcheck alf setup
-    - name: Build container for approval tests
-      run: docker compose build
-    - name: Run approval tests
-      run: docker compose run ci
-    - name: Run sanity test in zsh
-      run: docker compose run test_zsh
+      run: shellcheck alf setup uninstall
+    - name: Run Bats tests
+      run: bats --recursive --print-output-on-failure test
 
   ubuntu_setup:
     name: Setup on Ubuntu
@@ -26,9 +24,13 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
     - name: Run setup
-      run: ./setup
+      run:
+        ./setup
+        command -v alf
     - name: Run uninstall
-      run: ./uninstall
+      run:
+        ./uninstall
+        ! command -v alf
 
   macos_setup:
     name: Setup on macOS
@@ -39,9 +41,13 @@ jobs:
     - name: Upgrade the outdated bash
       run: brew install bash
     - name: Run setup
-      run: ./setup
+      run:
+        ./setup
+        command -v alf
     - name: Run uninstall
-      run: ./uninstall
+      run:
+        ./uninstall
+        ! command -v alf
 
   static_analysis:
     name: Static analysis

AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md
+
+## Purpose
+
+This repository is a Bashly-based CLI. Prefer working from the source partials in `src/` and regenerate artifacts as needed.
+
+## Source Of Truth
+
+- Do not use the generated `./alf` executable as the primary code-reading target.
+- Treat `./alf` as a generated artifact for verification only.
+- Read and edit:
+  - `src/bashly.yml`
+  - `src/initialize.sh`
+  - `src/commands/*.sh`
+  - `src/lib/*.sh`
+  - `settings.yml`
+
+## Generated Artifact Policy
+
+- Only inspect `./alf` when you need to verify generated output, trace a generation issue, or confirm the final emitted behavior.
+- Do not base architectural conclusions or refactoring plans on `./alf` when the equivalent source exists under `src/`.
+
+## Test Strategy
+
+The repository uses Bats as the primary test framework.
+
+For Bats tests, prefer this split:
+
+- Use checked-in fixtures when the unit's job is to interpret files, parse config, or derive behavior from prepared filesystem state.
+- Use stubs when the unit's job is orchestration.
+- In stub-driven unit tests, it is acceptable to create the smallest transient prerequisite inline when it is only a mechanical precondition (for example, an empty file required to satisfy an existence check).
+- Keep command adapter tests tiny and structural.
+- Keep integration tests sparse and focused on top-level CLI wiring, not behavior that is already covered at the unit level.
+
+## Review Notes
+
+- This project is being prepared for a `1.0.0` release and semver commitment.
+- Prefer deterministic, local, hermetic tests over live network access.
+- Treat installer flows as release/integration verification, not unit coverage.

README.md

@@ -104,7 +104,6 @@ Commands:
   save       Generate aliases to ~/.bash_aliases
   edit       Open your alf.conf for editing
   which      Show the alias command
-  upgrade    Upgrade alf to the latest version
   info       Show all alf related system facts
 
 Options: