Add Claude.md

Author: borkdude

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Neil is a CLI tool for managing `deps.edn`-based Clojure projects. It runs on Babashka and handles dependency management, project scaffolding, versioning, licensing, and alias management. Written in Clojure (`.clj`/`.cljc`), it is distributed as a single concatenated Babashka script.
+
+## Common Commands
+
+```bash
+bb run dev            # Start file watcher for auto-rebuilding the neil script
+bb run gen-script     # Build the standalone neil script from source modules
+bb run lint           # Run clj-kondo linter
+bb run test:bb        # Run Babashka integration tests (rebuilds script first)
+bb run test:clj       # Run Clojure unit tests
+bb run test:emacs     # Run Emacs integration tests
+bb run ci             # Run all: lint + test:bb + test:clj + test:emacs
+```
+
+Run specific Babashka test namespaces:
+```bash
+bb run test:bb :nses '[tests]'
+bb run test:bb :nses '[babashka.neil.version-test]'
+```
+
+Run specific Clojure tests:
+```bash
+clojure -M:test --namespace babashka.neil.dep-add-test
+```
+
+Set `BABASHKA_FAIL_FAST=true` to stop Babashka tests on first failure.
+
+## Architecture
+
+### Script Generation
+
+Neil is developed as modular source files but distributed as a single executable Babashka script (`./neil`). The build process (`dev/babashka/neil/gen_script.clj`) concatenates the `prelude` file (which injects dependencies via `babashka.deps/add-deps`) with all source modules in a specific order into the `neil` file. **After changing source files, run `bb run gen-script` (or use `bb run dev` for auto-rebuild) before running Babashka tests.**
+
+### Source Modules (src/babashka/neil/)
+
+- `neil.clj` — Main CLI entry point. Uses `babashka.cli/dispatch` for command routing. Contains most business logic for dep operations (add, search, upgrade, versions) and license management.
+- `curl.clj` — HTTP client wrapper with GitHub API auth (`NEIL_GITHUB_TOKEN`/`NEIL_GITHUB_USER`)
+- `git.clj` — Git operations (tags, SHAs, repo URL construction)
+- `new.clj` — Project scaffolding via deps-new
+- `version.clj` — Semantic versioning (set, bump major/minor/patch, tag)
+- `project.clj` — Project metadata from deps.edn
+- `rewrite.clj` — EDN formatting utilities
+- `test.cljc` — Test runner alias integration
+- `utils.clj` — Lazy-loading via `req-resolve` (workaround for Babashka pmap issues)
+- `meta.clj` — Generated version metadata (do not edit; regenerated by gen-script)
+
+### EDN Manipulation
+
+Neil uses `rewrite-edn` (built on `rewrite-clj`) to modify `deps.edn` files while preserving user formatting and whitespace. This is critical for version control friendliness.
+
+### Testing
+
+Two separate test suites:
+- **Babashka tests** (`tests.clj` + `test/babashka/neil/version_test.clj` + `test/babashka/neil/dep_upgrade_test.clj`): Integration tests that invoke the compiled `./neil` script. These require `bb run gen-script` first (handled automatically by `bb run test:bb`).
+- **Clojure tests** (`test/babashka/neil/`): Unit tests for individual modules, run via cognitect test-runner.
+
+### Version Management
+
+The project version lives in `deps.edn` at `:aliases :neil :project :version`. Use `bb run bump-version` to increment the patch version. The version is baked into the generated script via `meta.clj`.
+
+### Dependencies with `:neil/pinned`
+
+Dependencies in `deps.edn` can be marked with `:neil/pinned true` to skip them during `neil dep upgrade`.