Add AGENTS.md for codding agents

Author: kindermax

AGENTS.md

@@ -0,0 +1,66 @@
+# lets
+
+@README.md
+
+## Tools
+
+Use `lets` task runner for all build/test/lint operations instead of raw commands. Run `lets build` first if binary is missing.
+
+```bash
+lets build [bin]              # build CLI with version metadata
+lets build-and-install        # build and install lets-dev locally
+lets test                     # full suite: unit + bats + completions
+lets test-unit                # Go unit tests only
+lets test-bats [test]         # Docker-based Bats integration tests
+lets lint                     # golangci-lint via Docker
+lets fmt                      # go fmt ./...
+lets coverage [--html]        # coverage report
+lets run-docs                 # local docs dev server (docs/)
+lets publish-docs             # deploy docs site
+```
+
+`lets test-unit`, `lets test-bats`, and `lets lint` require Docker. Use `go test ./...` locally for quick iteration without Docker.
+
+## Agent Behavior
+
+- **Proactive execution** — Don't ask "Can I proceed?" for implementation. DO ask before changing success criteria, test thresholds, or what "working" means.
+- **Test early, test real** — Don't accumulate 10 changes then debug. After each logical step: does it work? With realistic input, not just edge case that triggered the work.
+- **Pushback** — Propose alternatives before implementing suboptimal approaches. Ask about design choices.
+- **Unify, don't duplicate** — Merge nearly-identical structs/functions rather than adding variants.
+- **No over-engineering** — Minimum complexity for current task. No speculative abstractions.
+- **Terseness** — Comments for surprising/hairy logic only. Be extremely concise in communication.
+
+## Package Structure
+
+- `main.go` — entry point, flag parsing, signal handling
+- `cmd/` — Cobra commands (root, subcommands, completion, LSP, self-update)
+- `config/` — config file discovery, loading, validation; `config/config/` defines Config/Command/Mixin structs and YAML unmarshaling
+- `executor/` — command execution, dependency resolution, env setup, checksum verification
+- `env/` — debug level state (`LETS_DEBUG`, levels 0-2)
+- `logging/` — logrus-based logging with command chain formatting
+- `lsp/` — Language Server Protocol: definition lookup, completion for depends, tree-sitter YAML parsing; `lets lsp` runs stdio-based server for IDE integration
+- `checksum/` — SHA1 file checksumming with glob patterns
+- `docopt/` — docopt argument parsing, produces `LETSOPT_*` and `LETSCLI_*` env vars
+- `upgrade/` — binary self-update from GitHub releases
+- `util/` — file/dir/version helpers
+- `workdir/` — `--init` scaffolding
+- `set/` — generic Set data structure
+- `test/` — test utilities (temp files, args helpers)
+
+## Key lets.yaml Fields
+
+- Top-level: `shell`, `env`, `eval_env`, `before`, `init`, `mixins`, `commands`
+- Command: `cmd`, `description`, `depends`, `env`, `options` (docopt), `work_dir`, `after`, `checksum`, `persist_checksum`, `ref`, `args`, `shell`
+
+## Project Rules
+
+- Follow `gofmt` exactly; tabs for indentation, ~120 char lines
+- Unit tests as `*_test.go` next to source; Bats tests in `tests/*.bats`
+- Fixtures in matching `tests/<scenario>/` folder, use `lets.yaml` unless variant needed
+- Bats tests use `run` + `assert_success`/`assert_line` pattern
+- Run at least `go test ./...` before considering work complete; `lets test-bats` for CLI-path changes
+- Commits: short imperative subjects (`Add ...`, `Fix ...`, `Use ...`), explain non-obvious context in body
+- **Changelog workflow**: add entries to the `Unreleased` section in `docs/docs/changelog.md` with each commit/PR. At release time, rename `Unreleased` to the new tag version
+- Do not commit `lets.my.yaml`, generated binaries, `.lets/`, `coverage.out`, or `node_modules`
+- CLI flags: kebab-case only (`--dry-run` not `--dry_run`)
+- No "Generated by <agent>" in commits

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

cmd/root_test.go

@@ -110,6 +110,32 @@ func TestRootCmdWithConfig(t *testing.T) {
 			t.Fatalf("expected foo suggestion, got %q", err.Error())
 		}
 	})
+
+	t.Run("should return exit code 2 for unknown command with no suggestions", func(t *testing.T) {
+		rootCmd, _ := newTestRootCmdWithConfig([]string{"zzzznotacommand"})
+
+		err := rootCmd.Execute()
+		if err == nil {
+			t.Fatal("expected unknown command error")
+		}
+
+		var exitCoder interface{ ExitCode() int }
+		if !errors.As(err, &exitCoder) {
+			t.Fatal("expected error with exit code")
+		}
+
+		if exitCode := exitCoder.ExitCode(); exitCode != 2 {
+			t.Fatalf("expected exit code 2, got %d", exitCode)
+		}
+
+		if !strings.Contains(err.Error(), `unknown command "zzzznotacommand"`) {
+			t.Fatalf("expected unknown command error, got %q", err.Error())
+		}
+
+		if strings.Contains(err.Error(), "Did you mean this?") {
+			t.Fatalf("expected no suggestions, got %q", err.Error())
+		}
+	})
 }
 
 func TestSelfCmd(t *testing.T) {
@@ -148,4 +174,36 @@ func TestSelfCmd(t *testing.T) {
 			t.Fatalf("expected lsp suggestion, got %q", err.Error())
 		}
 	})
+
+	t.Run("should return exit code 2 for unknown self subcommand with no suggestions", func(t *testing.T) {
+		bufOut := new(bytes.Buffer)
+
+		rootCmd := CreateRootCommand("v0.0.0-test")
+		rootCmd.SetArgs([]string{"self", "zzzznotacommand"})
+		rootCmd.SetOut(bufOut)
+		rootCmd.SetErr(bufOut)
+		InitSelfCmd(rootCmd, "v0.0.0-test")
+
+		err := rootCmd.Execute()
+		if err == nil {
+			t.Fatal("expected unknown command error")
+		}
+
+		var exitCoder interface{ ExitCode() int }
+		if !errors.As(err, &exitCoder) {
+			t.Fatal("expected error with exit code")
+		}
+
+		if exitCode := exitCoder.ExitCode(); exitCode != 2 {
+			t.Fatalf("expected exit code 2, got %d", exitCode)
+		}
+
+		if !strings.Contains(err.Error(), `unknown command "zzzznotacommand" for "lets self"`) {
+			t.Fatalf("expected unknown self subcommand error, got %q", err.Error())
+		}
+
+		if strings.Contains(err.Error(), "Did you mean this?") {
+			t.Fatalf("expected no suggestions, got %q", err.Error())
+		}
+	})
 }

tests/command_not_found.bats

@@ -29,3 +29,17 @@ setup() {
     assert_output --partial 'Did you mean this?'
     assert_output --partial 'lsp'
 }
+
+@test "command_not_found: no suggestions for completely unrelated command" {
+    run lets zzzznotacommand
+    assert_failure 2
+    assert_output --partial 'unknown command "zzzznotacommand" for "lets"'
+    refute_output --partial 'Did you mean this?'
+}
+
+@test "command_not_found: no suggestions for completely unrelated self subcommand" {
+    run lets self zzzznotacommand
+    assert_failure 2
+    assert_output --partial 'unknown command "zzzznotacommand" for "lets self"'
+    refute_output --partial 'Did you mean this?'
+}