Skip to content

Latest commit

 

History

History
66 lines (53 loc) · 3.76 KB

AGENTS.md

File metadata and controls

66 lines (53 loc) · 3.76 KB

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.

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 " in commits