Cursor rule

1---
2description: Shell script development and unit testing guidelines
3---
4 
5# Shell Script Development
6 
7## Script Location
8 
9- Place scripts in the `scripts/` directory
10- Use descriptive names with `.sh` extension
11- Make scripts executable: `chmod +x scripts/script_name.sh`
12 
13## Unit Testing
14 
15### Test Framework
16 
17- Use **Bach** testing framework for shell script unit tests
18- Bach is located at `scripts/test/vendor/bach.sh`
19- Bach requires Bash 4.3+ (available in nix environment)
20 
21### Test File Structure
22 
23- Test files should be in `scripts/test/` directory
24- Use `.test` extension (e.g., `scripts/test/run.sh.test`)
25- Test files must be executable
26 
27### Writing Tests
28 
291. Source Bach framework:
30```bash
31   source "$(dirname "$0")/vendor/bach.sh"
32```
33 
342. Create test functions with `test-` prefix:
35```bash
36   test-my-feature() {
37       # Test implementation
38   }
39```
40 
413. Create assertion functions with `-assert` suffix:
42```bash
43   test-my-feature-assert() {
44       @out "expected output"
45   }
46```
47 
484. Bach uses dry-run testing - it compares commands executed in test functions with expected commands in assert functions
49 
50### Running Tests
51 
52- Run all tests: `bash scripts/test/run_all_script_tests.sh`
53- Run individual test: `bash scripts/test/script_name.test`
54- In nix environment: `./scripts/run.sh bash scripts/test/run_all_script_tests.sh`
55 
56### Test Requirements
57 
58- All scripts in `scripts/` should have corresponding tests in `scripts/test/`
59- Tests are automatically discovered and run in CI
60- Tests must pass before merging
61 
62## CURSOR_DEV Mode Behavior
63 
64When scripts are run with `CURSOR_DEV=true nix develop -c <command>`, the nix shell hook (`scripts/nix_shell_hook.sh`) should:
65 
66- **Output only a one-liner**: `<<running within nix env>>` at the beginning
67- **Suppress all other output**: No log messages, environment info, or setup messages should appear
68- **Preserve command output**: The actual command's stdout/stderr should be displayed normally
69- **Show errors only**: If something goes wrong during setup, errors should still be visible
70 
71This ensures that when running commands via `CURSOR_DEV=true nix develop -c`, users see only:
721. The one-liner `<<running within nix env>>`
732. The command's actual output
74 
75All hook setup output is suppressed to keep the output clean and focused on the command being executed.
76