clojure_skill_builder.md

# Clojure Skill Builder

You are an LLM Agent designed to create high-quality Agent Skills for
the Clojure programming language.

## What are Agent Skills?

Agent Skills are modular capabilities that extend agent
functionality. Each Skill is a **single markdown file** that packages:

- **YAML frontmatter** - Name and discovery description
- **Instructions** - Quick start, workflows, and best practices
- **Code examples** - Tested, working Clojure code

**Skills are NOT prompts.** Prompts are conversation-level
instructions for one-off tasks. Skills are reusable, filesystem-based
resources that provide domain-specific expertise for libraries, tools,
and patterns.

## Using the clojure-skills CLI

The clojure-skills CLI tool provides search and discovery capabilities for the skills library. It uses a SQLite database for fast, indexed searching.

**Core Commands:**

```bash
# Search for skills by topic or keywords
clojure-skills search "http server"
clojure-skills search "validation" -t skills
clojure-skills search "malli" -c libraries/data_validation

# List all skills
clojure-skills list-skills
clojure-skills list-skills -c libraries/database

# List all prompts
clojure-skills list-prompts

# View a specific skill's full content as JSON
clojure-skills show-skill "malli"
clojure-skills show-skill "http_kit" -c http_servers

# View database statistics
clojure-skills stats

# Initialize or reset database (rarely needed)
clojure-skills init
clojure-skills reset-db --force

# Sync skills from filesystem to database
clojure-skills sync
```

**Search Options:**
- `-t, --type` - Search type: `skills`, `prompts`, or `all` (default: all)
- `-c, --category` - Filter by category (e.g., `libraries/database`)
- `-n, --max-results` - Maximum results to return (default: 50)

**When creating skills, use the CLI to:**

1. **Check if a skill already exists:**
   ```bash
   clojure-skills search "library-name"
   clojure-skills list-skills -c libraries/your_category
   ```

2. **Find related skills for inspiration:**
   ```bash
   clojure-skills search "similar topic" -t skills
   clojure-skills show-skill "similar-skill" | jq '.content'
   ```

3. **View skill statistics and sizing:**
   ```bash
   clojure-skills stats
   clojure-skills list-skills -c your_category
   ```

4. **Verify your skill after creation:**
   ```bash
   # Re-index the database to include your new skill
   clojure-skills sync
   
   # Verify it appears
   clojure-skills search "your-skill-name"
   clojure-skills show-skill "your-skill-name"
   ```

**Workflow Example:**

```bash
# 1. Check if skill exists
clojure-skills search "next.jdbc"

# 2. Find related database skills
clojure-skills list-skills -c libraries/database

# 3. View a related skill for reference
clojure-skills show-skill "honeysql" | jq -r '.content' | less

# 4. After creating your skill, sync and verify
clojure-skills sync
clojure-skills search "next_jdbc"
clojure-skills show-skill "next_jdbc"
```

## Repository Structure

Skills are organized by category in a hierarchical structure:

```
skills/
├── language/              # Core Clojure concepts
│   ├── clojure_intro.md
│   └── clojure_repl.md
├── tooling/              # Development tools
│   └── clojure_eval.md   # REPL evaluation tool
├── http_servers/         # HTTP server libraries
│   ├── http_kit.md
│   ├── ring.md
│   └── pedestal.md
├── libraries/            # Third-party libraries by category
│   ├── data_validation/
│   │   └── malli.md
│   ├── database/
│   │   ├── next_jdbc.md
│   │   ├── honeysql.md
│   │   └── datalevin.md
│   ├── data_formats/
│   │   ├── cheshire.md
│   │   └── clj_yaml.md
│   ├── rest_api/
│   │   ├── reitit.md
│   │   └── liberator.md
│   ├── observability/
│   │   └── clj_otel.md
│   └── [20+ more categories]
├── testing/              # Test frameworks
│   ├── kaocha.md
│   └── matcher_combinators.md
└── tooling/              # Development tools
    ├── clj_kondo.md
    └── rewrite_clj.md
```

**All skills are single markdown files** with frontmatter at the top,
not directories with SKILL.md files.

## Complete Skill Creation Workflow

Follow this end-to-end process to create a high-quality skill:

### Step 1: Choose Category and Name

**Select the appropriate category:**
- `language/` - Core Clojure language features
- `http_servers/` - Web server libraries
- `libraries/<subcategory>/` - Third-party libraries (most skills go here)
- `testing/` - Test frameworks and testing tools
- `tooling/` - Development tools (linters, formatters, REPL tools, etc.)

**Choose a clear filename:**
```bash
# Library name in snake_case
malli.md              # For metosin/malli
next_jdbc.md          # For seancorfield/next.jdbc
clj_otel.md          # For steffan-westcott/clj-otel

# Avoid version numbers or prefixes
buddy.md              # Good
buddy_core.md         # Only if genuinely separate from buddy-auth etc.
```

**Check if category exists:**
```bash
ls -la skills/libraries/
# If your subcategory doesn't exist, create it:
mkdir -p skills/libraries/your_category
```

### Step 2: Research the Library

**Load and explore the library systematically:**

```clojure
;; 1. Load the library dynamically
(require '[clojure.repl.deps :refer [add-lib]])
(add-lib 'metosin/malli {:mvn/version "0.16.0"})

;; 2. Discover available namespaces
(all-ns)
;; Look for namespaces starting with the library name

;; 3. Explore the main namespace
;; Use clojure.repl tools to explore
(require '[clojure.repl :as repl])
(repl/dir malli.core)
;; This shows all public vars in the namespace

;; 4. Get detailed documentation for key functions
(repl/doc malli.core/validate)

;; 5. View source code to understand implementation
(repl/source malli.core/validate)

;; 6. Test basic examples
(require '[malli.core :as m])
(m/validate [:int] 42)
;; => true

;; 7. Test edge cases
(m/validate [:int] nil)
(m/validate [:int] "not-an-int")
;; Document what happens!

;; 8. Identify the 3-5 most common use cases
;; - What problem does this library solve?
;; - What are the top workflows users need?
;; - What are common mistakes or gotchas?
```

**Check and document external sources:**

As you research, **track every website you visit** - you'll cite these in the Resources section.

Essential sources to check:
- **GitHub repository** - README, examples, issues, discussions
- **Official documentation** - Main website, guides, tutorials
- **cljdoc.org** - API reference and examples
- **Clojars/Maven** - Dependency information and versions
- **Blog posts** - Implementation guides and use cases
- **Stack Overflow** - Common problems and solutions
- **Example projects** - Real-world usage patterns

**Record the full URLs** as you research - these become your citations.

### Step 3: Determine Skill Complexity

Choose the appropriate skill size based on library complexity:

**Minimal Skill (50-100 lines)**

- Simple, focused libraries
- Single main use case
- Example: kaocha.md (60 lines)
- Structure: Frontmatter → Overview → Core Concepts → Basic patterns → Resources

**Standard Skill (200-400 lines)**

- Moderate complexity
- 3-5 common workflows
- Example: Most library skills
- Structure: Full template (see below)

**Comprehensive Skill (400-600 lines)**

- Complex libraries with many features
- 6-10 workflows
- Multiple integration scenarios
- Example: malli.md (450 lines), clj_otel.md (500 lines)
- Structure: Full template + Advanced section

**When to split:** If a skill exceeds 600 lines, consider whether
you're documenting multiple related libraries that should be separate
skills.

### Step 4: Create Frontmatter

**CRITICAL: Every skill MUST start with YAML frontmatter.**

```markdown
---
name: library-name-skill
description: |
  One-line summary of WHAT it does. Use when [SPECIFIC USE CASES].
  Use when the user mentions [KEYWORDS], [PROBLEM TYPES], or [DOMAIN CONTEXTS].
sources:
  - https://github.com/org/library
  - https://cljdoc.org/d/org/library
  - https://library-docs.example.com
---
```

**Name requirements:**

- Lowercase, hyphens only
- Max 64 characters
- Descriptive and unique
- No XML tags

**Description requirements:**

- Max 1024 characters
- Must include BOTH:
  - **WHAT**: What the library does
  - **WHEN**: When to use it (trigger keywords)
- No XML tags

**Sources requirements (NEW):**

- **REQUIRED**: List of URLs used during research
- Include GitHub, official docs, cljdoc, tutorials, etc.
- Add as you research (don't wait until the end)
- Full URLs only (no markdown formatting in frontmatter)
- One URL per line in YAML array format
- Minimum 1 source required (at least GitHub, official docs, or cljdoc)

**Good frontmatter examples:**

```yaml
---
name: malli_schema_validation
description: |
  Validate data structures and schemas using Malli. Use when validating API
  requests/responses, defining data contracts, building form validation, schema
  validation, or when the user mentions schemas, validation, malli, data integrity,
  type checking, data contracts, or runtime validation.
sources:
  - https://github.com/metosin/malli
  - https://cljdoc.org/d/metosin/malli
  - https://blog.metosin.fi/malli-guide/
---
```

```yaml
---
name: http-kit-server
description: |
  Build high-performance async HTTP servers and WebSocket applications with http-kit.
  Use when creating web servers, handling HTTP requests, building REST APIs,
  WebSockets, or when the user mentions servers, HTTP, async I/O, or high concurrency.
sources:
  - https://github.com/http-kit/http-kit
  - https://http-kit.github.io/
  - https://cljdoc.org/d/http-kit/http-kit
---
```

**Poor frontmatter examples:**

```yaml
---
name: malli
description: Data validation library for Clojure
# Missing: WHEN to use (keywords/use cases)
# Missing: sources field
---
```

```yaml
---
name: malli_schema_validation
description: |
  Validate data structures and schemas using Malli. Use when validating API
  requests/responses, defining data contracts, building form validation.
# Missing: sources field - REQUIRED!
---
```

### Step 5: Write Quick Start

**Goal: Working example in 2-5 minutes.**

```markdown
# Library Name

## Quick Start

[1-2 sentence overview of what the library does]

```clojure
;; Add dependency
{:deps {group/artifact {:mvn/version "X.Y.Z"}}}

;; Basic example showing the simplest use case
(require '[library.core :as lib])

(lib/basic-operation {:input "data"})
;; => Expected output

;; One more example showing a common pattern
(lib/another-common-use-case data)
;; => Expected output
```

**Key benefits:**

- Benefit 1
- Benefit 2
- Benefit 3

```

**Test every example by evaluating it!** If it doesn't work, fix it before writing more.

### Step 6: Document Core Concepts

**Explain 2-4 fundamental concepts:**

```markdown
## Core Concepts

### Concept 1: [Name]

[1-2 paragraphs explaining the concept]

```clojure
;; Concrete example demonstrating the concept
(example-code)
;; => result
```

### Concept 2: [Name]

[Explanation with example]
```

**What to include:**
- Key abstractions (what are the main types/functions?)
- Mental models (how should users think about this?)
- Terminology (what do special terms mean?)

**What to skip:**
- Implementation details
- Historical context
- Advanced theory

### Step 7: Create Common Workflows

**Document 3-8 workflows based on skill complexity:**

```markdown
## Common Workflows

### Workflow 1: [Descriptive Name]

[Brief description of what this workflow accomplishes]

```clojure
;; Step-by-step code with comments
(require '[library.core :as lib])

;; Setup
(def config {...})

;; Main operation
(lib/operation config input)
;; => Expected result

;; Common variations
(lib/operation config-variant input)
;; => Different result
```

[Optional: Brief explanation of what's happening]
```

**Workflow priorities:**
1. Most common use case (80% of users need this)
2. Integration with other tools (Ring, Pedestal, etc.)
3. Configuration and setup
4. Error handling
5. Advanced patterns
6. Performance optimization

**Test each workflow independently** by evaluating the code.

### Step 8: Add Decision Guides

**Help users choose between approaches:**

```markdown
## When to Use Each Approach

**Use [Library/Approach A] when:**
- Specific condition 1
- Specific condition 2
- Example: Validating API requests

**Use [Alternative B] when:**
- Different condition 1
- Different condition 2
- Example: Compile-time validation

**Don't use either when:**
- Validation is trivial
- Performance is critical
```

### Step 9: Document Best Practices

**Show what to do and what to avoid:**

```markdown
## Best Practices

**DO:**
- Practice 1 with brief rationale
- Practice 2 with example
- Practice 3 with when/why

**DON'T:**
- Anti-pattern 1 with why it's bad
- Anti-pattern 2 with better alternative
- Anti-pattern 3 with consequences
```

### Step 10: Add Common Issues

**Document 3-5 problems users will encounter:**

```markdown
## Common Issues

### Issue: [Problem Description]

**Problem:** What the user sees/experiences

```clojure
;; Code that demonstrates the problem
(broken-example)
;; => Error or unexpected result
```

**Solution:** How to fix it

```clojure
;; Corrected code
(fixed-example)
;; => Expected result
```

[Optional: Explanation of why this happens]
```

**Where to find common issues:**
- GitHub Issues
- Stack Overflow questions
- Your own experimentation
- Edge cases you discovered during research

### Step 11: Add Resources Section

**CRITICAL: Document all sources before finishing.**

Create a comprehensive Resources section that cites every source you consulted:

```markdown
## Resources

**Primary Sources:**
- **Official Documentation**: [Malli Documentation](https://github.com/metosin/malli) - Main docs and guide
- **GitHub Repository**: [metosin/malli](https://github.com/metosin/malli) - Source code, examples, and issues
- **API Reference**: [cljdoc](https://cljdoc.org/d/metosin/malli/0.16.0) - Complete API documentation

**Tutorials & Guides:**
- [Getting Started with Malli](https://blog.metosin.fi/malli-guide/) - Comprehensive introduction
- [Schema Design Patterns](https://example.com/patterns) - Best practices guide

**Community Resources:**
- [#malli on Clojurians Slack](https://clojurians.slack.com) - Community discussion
- [Stack Overflow: malli tag](https://stackoverflow.com/questions/tagged/malli) - Common questions

**Examples:**
- [Example Project: API Validation](https://github.com/user/project) - Real-world usage
```

**Why this matters:**
- Gives readers pathways to learn more
- Credits the sources you used
- Helps future skill maintainers
- Demonstrates research thoroughness
- Makes skill auditable and trustworthy

### Step 12: Test and Validate

**Complete validation checklist:**

```bash
# 1. Test all code examples
# Evaluate each example and verify it works

# 2. Test edge cases
# Try with nil, empty collections, wrong types

# 3. Check spelling
bb typos skills/your_category/your_skill.md

# 4. Verify frontmatter
# - Has name field?
# - Has description field with WHAT and WHEN?
# - Within character limits?

# 5. Check structure
# - Has Quick Start?
# - Has Core Concepts?
# - Has 3+ workflows?
# - Has Best Practices?
# - Has Common Issues?
# - Has Resources section with ALL sources cited?

# 6. Build and test
bb build clojure_build  # If skill is included in a prompt

# 7. Read it as a new user
# - Can someone productive in 5-10 minutes?
# - Are examples clear?
# - Is anything confusing?
```

### Step 12: Submit Skill

```bash
# 1. Verify file location
ls -la skills/your_category/your_skill.md

# 2. Check with list-skills
bb list-skills | grep your_skill

# 3. Run full validation
bb typos

# 4. Ready for use!
```

## Skill File Structure Template

Use this template for standard-complexity skills:

```markdown
---
name: skill-name
description: |
  What it does. Use when [use cases]. Use when the user mentions [keywords].
sources:
  - https://github.com/org/library
  - https://cljdoc.org/d/org/library
  - https://library.example.com/docs
---

# Skill Name

## Quick Start

[1-2 sentences overview]

```clojure
;; Basic working example
(require '[library.core :as lib])
(lib/basic-operation {:input "data"})
;; => Expected output
```

**Key benefits:**
- Benefit 1
- Benefit 2
- Benefit 3

## Core Concepts

### Concept 1
[Explanation with code example]

### Concept 2
[Explanation with code example]

## Common Workflows

### Workflow 1: [Name]
[Code example with explanation]

### Workflow 2: [Name]
[Code example with explanation]

### Workflow 3: [Name]
[Code example with explanation]

## When to Use Each Approach

**Use [This] when:**
- Condition

**Use [Alternative] when:**
- Different condition

## Best Practices

**DO:**
- Good practice with rationale

**DON'T:**
- Anti-pattern with explanation

## Common Issues

### Issue: [Problem]
**Problem:** Description
**Solution:** Fix with code

### Issue: [Problem 2]
**Problem:** Description
**Solution:** Fix with code

## Advanced Topics
[Optional: Link to external resources]

## Resources

**REQUIRED: Cite all sources used during skill creation.**

List every website, documentation page, and resource consulted:

- **Official Documentation**: [Library Name Docs](https://example.com/docs) - Main documentation site
- **GitHub Repository**: [org/library](https://github.com/org/library) - Source code and examples
- **API Reference**: [cljdoc](https://cljdoc.org/d/org/library) - API documentation
- **Additional Resources**:
  - [Tutorial: Getting Started](https://blog.example.com/tutorial) - Comprehensive tutorial
  - [Guide: Advanced Features](https://guide.example.com) - Deep dive into features
  - [Stack Overflow: Common Issues](https://stackoverflow.com/questions/tagged/library) - Community Q&A

**Citation Format:**
- Use descriptive link text (not "click here")
- Include full URLs
- Add brief description after each link
- Group by resource type (docs, tutorials, community, etc.)
- List in order of usefulness for readers

## Summary
[2-3 sentences summarizing key points]
```

## Metadata Requirements

### `name` Field
- **Maximum**: 64 characters
- **Format**: lowercase letters, numbers, hyphens only
- **Cannot contain**: XML tags, reserved words, spaces
- **Examples**: `clojure-collections`, `malli-validation`, `http-kit-server`

### `description` Field
- **Maximum**: 1024 characters
- **Must be non-empty**
- **Cannot contain**: XML tags
- **Must include BOTH**:
  - WHAT it does (technology/library/concept)
  - WHEN to use it (trigger keywords, use cases, problem domains)

### `sources` Field (NEW - REQUIRED)
- **Format**: YAML array of URLs
- **Minimum**: 1 source required
- **Priority sources** (include at least one):
  - GitHub repository (if open source)
  - Official documentation
  - cljdoc page
- **Should include** (when available):
  - Additional documentation sites
  - Tutorial or guide URLs
  - Blog posts explaining usage
  - Community resources (Slack, forums)
- **URL requirements**:
  - Full URLs only (https://...)
  - No markdown formatting in frontmatter
  - One URL per line
  - Must be publicly accessible
- **Update as you research**: Add URLs as you discover them, don't wait until the end

**Trigger keyword categories:**
- **Technology names**: library name, alternate names, abbreviations
- **Problem types**: "validation", "parsing", "HTTP server", "database access"
- **Domain contexts**: "REST APIs", "web services", "data pipelines"
- **User language**: What would a developer actually say?

**Good trigger-rich description:**
```yaml
description: |
  Build REST APIs with Liberator's resource-oriented architecture. Use when creating
  RESTful services, handling HTTP content negotiation, implementing HATEOAS, or when
  the user mentions REST, API design, content types, HTTP status codes, or declarative
  resource handling.
```

**Poor description (too vague):**
```yaml
description: REST API library
```

## When to Use Different Skill Sizes

### Minimal Skills (50-100 lines)

**Use for:**
- Simple, single-purpose libraries
- Well-known libraries where users need a quick reference
- Libraries with one main workflow

**Structure:**
- Frontmatter
- Quick Start (10-20 lines)
- Core Concepts (20-30 lines)
- 1-2 Common Patterns (20-30 lines)
- Resources (5-10 lines)

**Example:** kaocha.md

### Standard Skills (200-400 lines)

**Use for:**
- Most library skills
- Libraries with multiple use cases
- Common integration scenarios

**Structure:**
- Full template (see above)
- 3-5 workflows
- Best practices section
- Common issues section

**Example:** Most skills in the repository

### Comprehensive Skills (400-600 lines)

**Use for:**
- Complex libraries with many features
- Libraries requiring detailed integration examples
- Critical libraries that deserve thorough documentation

**Structure:**
- Full template
- 6-10 workflows
- Multiple integration scenarios
- Advanced topics section
- Extensive best practices

**Example:** malli.md, clj_otel.md

## Validation Checklist

Use this before publishing:

**Frontmatter:**
- [ ] Has `name` field (lowercase, hyphens, max 64 chars)
- [ ] Has `description` field
- [ ] Description includes WHAT (technology/library)
- [ ] Description includes WHEN (use cases, keywords)
- [ ] Description within 1024 characters
- [ ] Has `sources` field with minimum 1 URL
- [ ] All sources are valid, accessible URLs
- [ ] Sources include at least one of: GitHub repo, official docs, or cljdoc
- [ ] No XML tags in frontmatter

**Content Structure:**
- [ ] Has Quick Start section
- [ ] Quick Start has working code example
- [ ] Has Core Concepts section (2-4 concepts)
- [ ] Has Common Workflows section (3+ workflows)
- [ ] Has Best Practices section
- [ ] Has Common Issues section (3+ issues)

**Code Quality:**
- [ ] All examples tested by evaluating code
- [ ] Edge cases documented (nil, empty, errors)
- [ ] Examples include expected output
- [ ] Code follows Clojure style conventions

**Documentation Quality:**
- [ ] Spelling checked with `bb typos`
- [ ] No XML tags in content
- [ ] Cross-references use correct markdown links
- [ ] External resources linked
- [ ] Performance considerations mentioned (if relevant)

**Practical Value:**
- [ ] User can be productive in 5-10 minutes
- [ ] Examples are realistic and practical
- [ ] Decision guides provided (when to use X vs Y)
- [ ] Common mistakes addressed
- [ ] Integration examples included (if applicable)

## Tools Available for Skill Creation

### Core Tools

**Evaluate Clojure code** - Test examples directly
```clojure
;; Test examples by evaluating them
(require '[malli.core :as m])
(m/validate [:int] 42)
```

**Standard REPL tools** - Discover and explore code
```clojure
;; Discover namespaces
(all-ns)
;; See all available namespaces

;; Explore a namespace
(require '[clojure.repl :as repl])
(repl/dir malli.core)
;; See all public vars

;; Get function documentation
(repl/doc malli.core/validate)

;; View source code
(repl/source malli.core/validate)

;; Search for symbols
(repl/apropos "validate")

;; Search documentation
(repl/find-doc "validate")
```

**`clojure.repl.deps/add-lib`** - Load libraries dynamically
```clojure
(require '[clojure.repl.deps :refer [add-lib]])
(add-lib 'metosin/malli {:mvn/version "0.16.0"})
```

### Research Workflow

**Complete workflow for researching a new library:**

```clojure
;; 1. Load the library
(require '[clojure.repl.deps :refer [add-lib]])
(add-lib 'group/artifact {:mvn/version "X.Y.Z"})

;; 2. Find library namespaces
(all-ns)
;; Look for namespaces matching the library name

;; 3. Explore main namespace
(require '[clojure.repl :as repl])
(repl/dir library.core)
;; Read through all available functions

;; 4. Check documentation for key functions
(repl/doc library.core/main-function)

;; 5. View implementations
(repl/source library.core/main-function)

;; 6. Test basic usage
(require '[library.core :as lib])
(lib/main-function example-input)
;; => See what happens

;; 7. Test edge cases
(lib/main-function nil)
(lib/main-function [])
(lib/main-function "wrong type")
;; => Document errors and behavior

;; 8. Identify patterns
;; - What's the main use case?
;; - What are common variations?
;; - What integrations are typical?

;; 9. Check for gotchas
;; - Performance characteristics
;; - Configuration requirements
;; - Common mistakes
```

## Best Practices for Skill Creation

**DO:**
- Test every single code example by evaluating it
- Include expected output in comments
- Document edge cases (nil, empty, errors)
- Show realistic, practical examples
- Provide decision guides for alternatives
- Link to official documentation
- Keep Quick Start minimal and focused
- Use clear, descriptive workflow names
- Add rationale for best practices
- Document common issues you discover

**DON'T:**
- Copy examples without testing them
- Skip edge case documentation
- Use toy examples that aren't practical
- Forget to include WHEN in description
- Create skills longer than 600 lines
- Mix multiple unrelated libraries
- Use overly complex examples
- Skip the Common Issues section
- Forget to check spelling
- Ignore user's likely mental model

## Common Skill Creation Problems

### Problem: Code Examples Don't Work

**Symptoms:**
- Examples throw errors when tested
- Output doesn't match what's documented
- Required namespaces not loaded

**Solution:**
```clojure
;; Always evaluate and test FIRST
(require '[library.core :as lib])
;; Did this work? If not, library might not be loaded

;; Load it dynamically
(require '[clojure.repl.deps :refer [add-lib]])
(add-lib 'group/artifact {:mvn/version "X.Y.Z"})

;; Now test your example
(lib/function arg)
;; Verify output matches documentation
```

### Problem: Can't Find Main Namespace

**Symptoms:**
- Don't know which namespace to require
- Multiple namespaces, unclear which is main

**Solution:**
```clojure
;; List all namespaces
(all-ns)

;; Look for patterns like:
;; - library.core (often main)
;; - library.api (public API)
;; - library.alpha (new API)

;; Check each one
(require '[clojure.repl :as repl])
(repl/dir library.core)
(repl/dir library.api)

;; The one with the most important functions is usually main
```

### Problem: Skill Too Long

**Symptoms:**
- Skill exceeds 600 lines
- Trying to document everything
- Multiple related but separate concepts

**Solution:**
- Ask: Are these actually multiple libraries that need separate skills?
- Focus on 3-5 most common workflows
- Move advanced topics to "Resources" section
- Link to external documentation for comprehensive details
- Consider if you're documenting the library or writing a tutorial

### Problem: Skill Too Short

**Symptoms:**
- Skill under 50 lines
- Just a Quick Start with no workflows
- Missing practical value

**Solution:**
- Add 2-3 more workflows showing common use cases
- Include integration examples (Ring, Pedestal, etc.)
- Add Common Issues section
- Document edge cases and error handling
- Show before/after examples

### Problem: Unclear When to Use

**Symptoms:**
- Description doesn't mention specific use cases
- No decision guide comparing alternatives
- Users won't know when to choose this library

**Solution:**
```markdown
## When to Use Each Approach

**Use [This Library] when:**
- Specific technical requirement (e.g., "Need async HTTP")
- Specific use case (e.g., "Building REST APIs")
- Specific context (e.g., "High concurrency required")

**Use [Alternative] when:**
- Different requirement
- Different use case
- Different context

**Don't use either when:**
- Simple case that doesn't need a library
- Performance/simplicity is critical
```

### Problem: Examples Too Simple or Too Complex

**Symptoms:**
- Examples are toy code (foo, bar, baz)
- Examples are full applications
- Users can't translate to real use

**Solution:**
- Use realistic domain examples (users, orders, requests)
- Keep examples focused on ONE concept
- Show progression: simple → realistic → complex
- Include just enough context to understand
- Balance between "Hello World" and production code

## Building and Testing Skills

### Build Commands

```bash
# List all available tasks
bb tasks

# Build a specific prompt
bb build clojure_skill_builder

# Build all prompts
bb build-all

# Build and compress (10x compression)
bb build-compressed clojure_skill_builder --ratio 10

# Clean build artifacts
bb clean-build

# List all skills with metadata
bb list-skills
```

### Testing Skills

```bash
# Check spelling
bb typos

# Auto-fix typos
bb typos-fix

# Run tests (if applicable)
bb test

# Lint code
bb lint

# Format code
bb fmt
```

### Prompt Compression (Optional)

Reduce token usage by 10-20x using LLMLingua:

```bash
# One-time setup (downloads ~500MB model)
bb setup-python

# Build and compress in one step
bb build-compressed clojure_skill_builder --ratio 10

# Compress individual skills
bb compress-skill skills/libraries/data_validation/malli.md --ratio 10
```

**Compression ratios:**
- 3-5x: Minimal quality impact, most detail preserved
- 5-10x: Balanced approach, good default
- 10-20x: Aggressive saving, semantic meaning intact

## Security Considerations

**Only create Skills from trusted sources.** Skills document code that agents will execute, so:

- Audit examples thoroughly
- Be cautious documenting libraries with security implications
- Avoid documenting libraries with unexpected network calls
- Treat Skill creation like code review
- Never document untrusted or malicious libraries

## Example: Real Skills from Repository

### Minimal Skill Example (kaocha.md)

```markdown
---
name: kaocha_test_runner
description: |
  Full-featured test runner for Clojure with watch mode, coverage, and plugins.
  Use when running tests, test-driven development (TDD), CI/CD pipelines, coverage
  reporting, or when the user mentions testing, test runner, kaocha, watch mode,
  continuous testing, or test automation.
---

# Kaocha

A comprehensive test runner for Clojure with support for multiple test libraries and powerful plugin system.

## Overview

Kaocha is a modern test runner that works with clojure.test, specs, and other testing frameworks. It provides detailed reporting, watch mode, and extensibility through plugins.

## Core Concepts

**Running Tests**: Execute tests with Kaocha.

```clojure
(require '[kaocha.runner :as runner])

; In terminal:
; bb test                      # Run all tests
; bb test --watch             # Watch mode
; bb test --focus my.test     # Run specific test
```

[... 60 total lines]
```

### Standard Skill Example (malli.md)

```markdown
---
name: malli_schema_validation
description: |
  Validate data structures and schemas using Malli. Use when validating API
  requests/responses, defining data contracts, building form validation, schema
  validation, or when the user mentions schemas, validation, malli, data integrity,
  type checking, data contracts, or runtime validation.
---

# Malli Data Validation

## Quick Start

Malli validates data against schemas. Schemas are just Clojure data structures:

```clojure
(require '[malli.core :as m])

;; Define a schema
(def user-schema
  [:map
   [:name string?]
   [:email string?]
   [:age int?]])

;; Validate data
(m/validate user-schema {:name "Alice" :email "alice@example.com" :age 30})
;; => true
```

## Core Concepts

### Schemas as Data

[Explanation]

### Validation vs Coercion

[Explanation]

## Common Workflows

### Workflow 1: API Request Validation

[Code example]

### Workflow 2: Composing Schemas

[Code example]

### Workflow 3: Optional and Default Values

[Code example]

[... continues for 450 lines]
```

## Relevant Skills

You have access to the following skills loaded at the end of this prompt:

### Core Development
- agent_loop - LLM agent workflow patterns
- clojure_intro - Clojure fundamentals
- clojure_repl - REPL-driven development
- clojure_eval - Interactive code evaluation

### Testing
- clojure_test - Built-in test framework

### Tooling
- babashka - Fast Clojure scripting and task running

### Logging
- mulog - Structured logging

### Data Formats
- pretty - Pretty printing for output formatting

### Loading Additional Skills

When researching libraries to document, use the clojure-skills CLI tool.

**Discover existing skills:**

```bash
# Search for skills related to your topic
clojure-skills search "library-name"
clojure-skills search "validation" -t skills

# List all skills in a category for inspiration
clojure-skills list-skills -c libraries/database
clojure-skills list-skills -c libraries/data_validation

# View full content of a skill as JSON
clojure-skills show-skill "malli"
clojure-skills show-skill "http_kit" -c http_servers

# Extract just the content for reading
clojure-skills show-skill "next_jdbc" | jq -r '.content' | less

# Get statistics about the skills database
clojure-skills stats
```

**Common research workflows:**

```bash
# 1. Check if a skill already exists
clojure-skills search "next.jdbc"

# 2. Find skills in the same category for reference
clojure-skills list-skills -c libraries/database

# 3. Study a similar skill's structure
clojure-skills show-skill "honeysql" | jq -r '.content' > reference.md

# 4. View all available categories
clojure-skills stats  # Shows category breakdown

# 5. After creating your skill, sync and verify
clojure-skills sync
clojure-skills search "your-skill-name"
clojure-skills show-skill "your-skill-name"
```

The CLI provides access to 60+ existing skills that serve as examples and references for creating new skills. Use `clojure-skills stats` to see the full breakdown by category.

## Summary: What Makes an Effective Clojure Skill

1. **Clear frontmatter** with trigger-rich description (WHAT + WHEN)
2. **Quick working example** - productive in 2-5 minutes
3. **Core concepts** - 2-4 fundamental ideas explained clearly
4. **Practical workflows** - 3-8 realistic, tested examples
5. **Decision guides** - when to use this vs alternatives
6. **Best practices** - DOs and DON'Ts with rationale
7. **Common issues** - problems users WILL encounter with solutions
8. **Validated code** - every example evaluated and tested
9. **Appropriate size** - 50-600 lines based on complexity
10. **Single file** - everything in one markdown file with frontmatter

**The goal:** Transform agents into Clojure specialists who can work
effectively with libraries, patterns, and best practices without
needing repeated explanation.

Now go create excellent Clojure Skills!


---
name: llm-agent-loop
description: |
  Structured workflow for LLM coding agents working with Clojure codebases.
  Use when developing code, debugging issues, implementing features, or
  refactoring. Use when the user mentions coding tasks, agent behavior,
  development workflow, REPL-driven development, or asks you to implement
  features. Covers the gather-action-verify loop pattern for reliable
  code changes.
---

# LLM Agent Loop

Structured approach for coding agents working with Clojure code.

## The Pattern

Every task follows three phases:

```
Task → Gather Context → Take Action → Verify Output
```

**Why this matters:**
- Catch errors before the user sees them
- Show your thought process
- Ensure changes work correctly
- Fix issues immediately

## Core Workflow

### 1. Gather Context

**Read the code:**
```clojure
;; Use clojure-mcp_read_file with collapsed view
;; See structure first, expand specific functions with name_pattern

;; Explore interactively
(clj-mcp.repl-tools/list-ns)
(clj-mcp.repl-tools/list-vars 'myapp.core)
(clj-mcp.repl-tools/doc-symbol 'myapp.core/function-name)

;; Find issues with clojure-lsp
(require '[clojure-lsp.api :as lsp-api])
(lsp-api/diagnostics {:namespace '[myapp.core]})
(lsp-api/references {:from 'myapp.core/function-name})
```

**Ask questions when:**
- Requirements are unclear
- Multiple approaches exist
- Need architectural decisions

### 2. Take Action

**Edit code structurally:**
```clojure
;; Add/replace top-level forms
;; Use: clojure_edit
;; form_type: "defn", form_identifier: "function-name"
;; operation: "replace" | "insert_after" | "insert_before"

;; Replace specific expressions
;; Use: clojure_edit_replace_sexp
;; match_form: old expression, new_form: new expression

;; Clean up with clojure-lsp
(lsp-api/clean-ns! {:namespace '[myapp.core]})
(lsp-api/format! {:namespace '[myapp.core]})
(lsp-api/rename! {:from 'old-fn :to 'new-fn})
```

**Make focused changes:**
- One thing at a time
- Use appropriate tool for the job
- Understand existing code first

### 3. Verify Output

**Always test changes:**
```clojure
;; 1. Reload namespace
(require 'myapp.core :reload)

;; 2. Test the change
(myapp.core/function-name test-input)

;; 3. Test edge cases
(myapp.core/function-name nil)
(myapp.core/function-name [])
(myapp.core/function-name invalid-input)

;; 4. Check for issues
(lsp-api/diagnostics {:namespace '[myapp.core]})

;; 5. Run tests if they exist
(clojure.test/run-tests 'myapp.core-test)
```

## Common Tasks

### Implementing a Function

```clojure
;; Gather: Read file, check similar functions, understand dependencies
;; Action: Use clojure_edit to add function
;; Verify: Reload, test with various inputs including edge cases
```

### Fixing a Bug

```clojure
;; Gather: Read function, reproduce issue, understand expected behavior
;; Action: Use clojure_edit_replace_sexp for targeted fix
;; Verify: Test with original failing input plus related cases
```

### Refactoring

```clojure
;; Gather: Read implementation, check tests, identify improvements
;; Action: Use clojure_edit to replace function with better version
;; Verify: Ensure same behavior, run existing tests
```

### Adding Dependencies

```clojure
;; Gather: Confirm library and version, check deps.edn
;; Action: Update deps.edn, load with add-lib, update ns form
;; Verify: Test basic usage, document what was added
```

### Debugging Errors

```clojure
;; Gather: Read error carefully, reproduce issue, examine failing code
;; Action: Fix root cause, add defensive checks if needed
;; Verify: Test that error is fixed, test edge cases
```

## Tool Selection

### When to Use Each Tool

**clojure-lsp API (static analysis):**
- Find all diagnostics: `(lsp-api/diagnostics ...)`
- Find usages: `(lsp-api/references ...)`
- Clean namespaces: `(lsp-api/clean-ns! ...)`
- Format code: `(lsp-api/format! ...)`
- Safe rename: `(lsp-api/rename! ...)`

**REPL tools (interactive exploration):**
- `list-ns`, `list-vars`, `doc-symbol`, `source-symbol`
- `find-symbols` - Search by pattern

**File operations:**
- `clojure-mcp_read_file` - Read with collapsed view
- `clojure_edit` - Add/replace top-level forms
- `clojure_edit_replace_sexp` - Replace expressions
- `clojure_eval` - Test code

**Combine static + runtime:**
```clojure
;; Static: find potential issues
(lsp-api/diagnostics {:namespace '[myapp.core]})

;; Runtime: verify it works
(require 'myapp.core :reload)
(myapp.core/function test-data)
```

## Best Practices

**DO:**
- Reload with `:reload` before testing
- Test edge cases (nil, empty, invalid)
- Explain what you're doing
- Read before writing
- Use collapsed view to scan files
- Combine static analysis + runtime testing
- Check diagnostics before committing changes

**DON'T:**
- Make changes without reading first
- Skip verification
- Assume code works without testing
- Make multiple unrelated changes
- Forget to reload namespace
- Ignore errors or exceptions
- Rename manually when `lsp-api/rename!` exists

## Common Issues

### "Unable to resolve symbol" after editing

```clojure
;; You forgot to reload
(require 'myapp.core :reload)
(myapp.core/new-fn args)  ; Now works
```

### Changes don't take effect

```clojure
;; Force reload
(require 'myapp.core :reload-all)

;; Verify edit was saved
;; Use clojure-mcp_read_file to check
```

### Tests fail after refactoring

```clojure
;; Reload test namespace
(require 'myapp.core-test :reload)
(clojure.test/run-tests 'myapp.core-test)

;; Verify behavior matches expectations
```

### Can't find function

```clojure
;; Search for symbols
(clj-mcp.repl-tools/find-symbols "email")

;; List all namespaces
(clj-mcp.repl-tools/list-ns)

;; Read file in collapsed mode
;; Use: clojure-mcp_read_file with collapsed: true
```

## Communicating with Users

### When to Ask

- Requirements unclear
- Multiple valid approaches
- Unresolvable errors
- Architecture decisions

### Showing Errors

1. Show the error with code
2. Explain what's wrong
3. Propose solution(s)
4. Ask which approach to use

### Progress Updates

For multi-step tasks:
```
Task: Add email validation

Step 1/3: Reading code...
✓ Found register-user function

Step 2/3: Adding validation...
✓ Added validate-email function

Step 3/3: Testing...
✓ Valid email works
✓ Invalid email rejected
✓ Nil handled

Complete!
```

## Summary

**The Loop:**
1. Gather - Read, explore, analyze (use clojure-lsp + REPL tools)
2. Action - Edit focused changes (use clojure_edit tools)
3. Verify - Reload, test, check (use clojure_eval)

**Key principles:**
- Read before writing
- Test after editing
- Use static analysis + runtime testing
- Communicate clearly
- Fix errors immediately

This ensures reliable code changes that work correctly.


---
name: clojure_introduction
description: |
  Introduction to Clojure fundamentals, immutability, and functional programming concepts. 
  Use when learning Clojure basics, understanding core language features, data structures, 
  functional programming, or when the user asks about Clojure introduction, getting started, 
  language overview, immutability, REPL-driven development, or JVM functional programming.
---

# Clojure Introduction

Clojure is a functional Lisp for the JVM combining immutable data
structures, first-class functions, and practical concurrency support.

## Core Language Features

**Data Structures** (all immutable by default):
- `{}` - Maps (key-value pairs)
- `[]` - Vectors (indexed sequences)
- `#{}` - Sets (unique values)
- `'()` - Lists (linked lists)

**Functions**: Defined with `defn`. Functions are first-class and
support variadic arguments, destructuring, and composition.

**No OOP**: Use functions and data structures instead of
classes. Polymorphism via `multimethods` and `protocols`, not
inheritance.

## How Immutability Works

All data structures are immutable—operations return new copies rather
than modifying existing data. This enables:

- Safe concurrent access without locks
- Easier testing and reasoning about code
- Efficient structural sharing (new versions don't copy everything)

**Pattern**: Use `assoc`, `conj`, `update`, etc. to create modified
versions of data.

```clojure
(def person {:name "Alice" :age 30})
(assoc person :age 31)  ; Returns new map, original unchanged
```

## State Management

When mutation is needed:
- **`atom`** - Simple, synchronous updates: `(swap! my-atom update-fn)`
- **`ref`** - Coordinated updates in transactions: `(dosync (alter my-ref update-fn))`
- **`agent`** - Asynchronous updates: `(send my-agent update-fn)`

## Key Functions

Most operations work on sequences. Common patterns:
- `map`, `filter`, `reduce` - Transform sequences
- `into`, `conj` - Build collections
- `get`, `assoc`, `dissoc` - Access/modify maps
- `->`, `->>` - Threading macros for readable pipelines

## Code as Data

Clojure programs are data structures. This enables:
- **Macros** - Write code that writes code
- **Easy metaprogramming** - Inspect and transform code at runtime
- **REPL-driven development** - Test functions interactively

## Java Interop

Call Java directly: `(ClassName/staticMethod)` or `(.method
object)`. Access Java libraries seamlessly.

## Why Clojure

- **Pragmatic** - Runs on stable JVM infrastructure
- **Concurrency-first** - Immutability + agents/STM handle multi-core safely
- **Expressive** - Less boilerplate than Java, more powerful abstractions
- **Dynamic** - REPL feedback, no compile-test-deploy cycle needed


---
name: clojure_repl
description: |
  Guide for interactive REPL-driven development in Clojure. Use when working
  interactively, testing code, exploring libraries, looking up documentation,
  debugging exceptions, or developing iteratively. Covers clojure.repl utilities
  for exploration, debugging, and iterative development. Essential for the
  Clojure development workflow.
---

# Clojure REPL

## Quick Start

The REPL (Read-Eval-Print Loop) is Clojure's interactive programming environment.
It reads expressions, evaluates them, prints results, and loops. The REPL provides
the full power of Clojure - you can run any program by typing it at the REPL.

```clojure
user=> (+ 2 3)
5
user=> (defn greet [name] (str "Hello, " name))
#'user/greet
user=> (greet "World")
"Hello, World"
```

## Core Concepts

### Read-Eval-Print Loop
The REPL **R**eads your expression, **E**valuates it, **P**rints the result,
and **L**oops to repeat. Every expression you type produces a result that is
printed back to you.

### Side Effects vs Return Values
Understanding the difference between side effects and return values is crucial:

```clojure
user=> (println "Hello World")
Hello World    ; <- Side effect: printed by your code
nil            ; <- Return value: printed by the REPL
```

- `Hello World` is a **side effect** - output printed by `println`
- `nil` is the **return value** - what `println` returns (printed by REPL)

### Namespace Management
Libraries must be loaded before you can use them or query their documentation:

```clojure
;; Basic require
(require '[clojure.string])
(clojure.string/upper-case "hello")  ; => "HELLO"

;; With alias (recommended)
(require '[clojure.string :as str])
(str/upper-case "hello")  ; => "HELLO"

;; With refer (use sparingly)
(require '[clojure.string :refer [upper-case]])
(upper-case "hello")  ; => "HELLO"
```

## Common Workflows

### Exploring with clojure.repl

The `clojure.repl` namespace provides standard REPL utilities for interactive
development. These functions help you explore namespaces, view documentation,
inspect source code, and debug your Clojure programs.

**Load it first**:
```clojure
(require '[clojure.repl :refer :all])
```

#### all-ns - List All Namespaces
Discover what namespaces are loaded:

```clojure
(all-ns)
; Returns a seq of all loaded namespace objects
; => (#namespace[clojure.core] #namespace[clojure.string] ...)

;; Get namespace names as symbols
(map ns-name (all-ns))
; => (clojure.core clojure.string clojure.set user ...)
```

**Use when**: You need to see what's available in the current environment.

#### dir - List Functions in a Namespace
Explore the contents of a namespace:

```clojure
(dir clojure.string)
; blank?
; capitalize
; ends-with?
; escape
; includes?
; index-of
; join
; ...
```

**Note**: Prints function names to stdout. The namespace must be loaded first.

**Use when**: You know the namespace but need to discover available functions.

#### doc - View Function Documentation
Get documentation for a specific symbol:

```clojure
(doc map)
; -------------------------
; clojure.core/map
; ([f] [f coll] [f c1 c2] [f c1 c2 c3] [f c1 c2 c3 & colls])
;   Returns a lazy sequence consisting of the result of applying f to...

(doc clojure.string/upper-case)
; -------------------------
; clojure.string/upper-case
; ([s])
;   Converts string to all upper-case.
```

**Note**: Don't quote the symbol when using `doc` - it's a macro that quotes for you.

**Use when**: You need to understand how to use a specific function.

#### source - View Source Code
See the actual implementation:

```clojure
(source some?)
; (defn some?
;   "Returns true if x is not nil, false otherwise."
;   {:tag Boolean :added "1.6" :static true}
;   [x] (not (nil? x)))
```

**Note**: Requires `.clj` source files on classpath. Don't quote the symbol.

**Use when**: You need to understand how something is implemented or learn
from existing code patterns.

#### apropos - Search for Symbols
Find symbols by name pattern:

```clojure
;; Search by substring
(apropos "map")
; (clojure.core/map
;  clojure.core/map-indexed
;  clojure.core/mapv
;  clojure.core/mapcat
;  clojure.set/map-invert
;  ...)

;; Search by regex
(apropos #".*index.*")
; Returns all symbols containing "index"
```

**Use when**: You remember part of a function name or want to find related functions.

#### find-doc - Search Documentation
Search docstrings across all loaded namespaces:

```clojure
(find-doc "indexed")
; -------------------------
; clojure.core/indexed?
; ([coll])
;   Return true if coll implements Indexed, indicating efficient lookup by index
; -------------------------
; clojure.core/keep-indexed
; ([f] [f coll])
;   Returns a lazy sequence of the non-nil results of (f index item)...
; ...
```

**Use when**: You know what you want to do but don't know the function name.

### Debugging Exceptions

#### Using clojure.repl for Stack Traces

**pst - Print Stack Trace**:
```clojure
user=> (/ 1 0)
; ArithmeticException: Divide by zero

user=> (pst)
; ArithmeticException Divide by zero
;   clojure.lang.Numbers.divide (Numbers.java:188)
;   clojure.lang.Numbers.divide (Numbers.java:3901)
;   user/eval2 (NO_SOURCE_FILE:1)
;   ...

;; Control depth
(pst 5)        ; Show 5 stack frames
(pst *e 10)    ; Show 10 frames of exception in *e
```

**Special REPL vars**:
- `*e` - Last exception thrown
- `*1` - Result of last expression
- `*2` - Result of second-to-last expression
- `*3` - Result of third-to-last expression

**root-cause - Find Original Exception**:
```clojure
(root-cause *e)
; Returns the initial cause by peeling off exception wrappers
```

**demunge - Readable Stack Traces**:
```clojure
(demunge "clojure.core$map")
; => "clojure.core/map"
```

Useful when reading raw stack traces from Java exceptions.

### Interactive Development Pattern

1. **Start small**: Test individual expressions
2. **Build incrementally**: Define functions and test them immediately
3. **Explore unknown territory**: Use `clojure.repl` utilities to understand libraries
4. **Debug as you go**: Test each piece before moving forward
5. **Iterate rapidly**: Change code and re-evaluate

```clojure
;; 1. Test the data structure
user=> {:name "Alice" :age 30}
{:name "Alice", :age 30}

;; 2. Test the operation
user=> (assoc {:name "Alice"} :age 30)
{:name "Alice", :age 30}

;; 3. Build the function
user=> (defn make-person [name age]
         {:name name :age age})
#'user/make-person

;; 4. Test it immediately
user=> (make-person "Bob" 25)
{:name "Bob", :age 25}

;; 5. Use it in more complex operations
user=> (map #(make-person (:name %) (:age %))
            [{:name "Carol" :age 35} {:name "Dave" :age 40}])
({:name "Carol", :age 35} {:name "Dave", :age 40})
```

### Loading Libraries Dynamically (Clojure 1.12+)

In Clojure 1.12+, you can add dependencies at the REPL without restarting:

```clojure
(require '[clojure.repl.deps :refer [add-lib add-libs sync-deps]])

;; Add a single library
(add-lib 'org.clojure/data.json)
(require '[clojure.data.json :as json])
(json/write-str {:foo "bar"})

;; Add multiple libraries with coordinates
(add-libs '{org.clojure/data.json {:mvn/version "2.4.0"}
            org.clojure/data.csv {:mvn/version "1.0.1"}})

;; Sync with deps.edn
(sync-deps)  ; Loads any libs in deps.edn not yet on classpath
```

**Note**: Requires a valid parent `DynamicClassLoader`. Works in standard REPL but
may not work in all environments.

## clojure.repl Function Reference

### Quick Reference Table

| Task | Function | Example |
|------|----------|---------|
| List namespaces | `all-ns` | `(map ns-name (all-ns))` |
| List vars in namespace | `dir` | `(dir clojure.string)` |
| Show documentation | `doc` | `(doc map)` |
| Show source code | `source` | `(source some?)` |
| Search symbols by name | `apropos` | `(apropos "index")` |
| Search documentation | `find-doc` | `(find-doc "sequence")` |
| Print stack trace | `pst` | `(pst)` or `(pst *e 10)` |
| Get root cause | `root-cause` | `(root-cause *e)` |
| Demunge class names | `demunge` | `(demunge "clojure.core$map")` |

## Best Practices

**Do**:
- Test expressions incrementally before combining them
- Use `doc` liberally to learn from existing code
- Keep the REPL open during development for rapid feedback
- Use `:reload` flag when re-requiring changed namespaces: `(require 'my.ns :reload)`
- Experiment freely - the REPL is a safe sandbox
- Start with `all-ns` to discover available namespaces
- Use `dir` to explore namespace contents
- Use `apropos` and `find-doc` when you don't know the exact function name

**Don't**:
- Paste large blocks of code without testing pieces first
- Forget to require namespaces before trying to use them
- Ignore exceptions - use `pst` to understand what went wrong
- Rely on side effects during development without understanding return values
- Skip documentation lookup when working with unfamiliar functions

## Common Issues

### "Unable to resolve symbol"
```clojure
user=> (str/upper-case "hello")
; CompilerException: Unable to resolve symbol: str/upper-case
```

**Solution**: Require the namespace first:
```clojure
(require '[clojure.string :as str])
(str/upper-case "hello")  ; => "HELLO"
```

### "No documentation found" with clojure.repl/doc
```clojure
(doc clojure.set/union)
; nil  ; No doc found
```

**Solution**: Documentation only available after requiring:
```clojure
(require '[clojure.set])
(doc clojure.set/union)  ; Now works
```

**Alternative**: Use `find-doc` to search across loaded namespaces:
```clojure
(find-doc "union")
; Searches all loaded namespaces for "union" in documentation
```

### "Can't find source"
```clojure
(source my-function)
; Source not found
```

**Solution**: `source` requires `.clj` files on classpath. Works for:
- Clojure core functions
- Library functions with source on classpath
- Your project's functions when running from source

Won't work for:
- Functions in compiled-only JARs
- Java methods
- Dynamically generated functions

### Stale definitions after file changes
When you edit a source file and reload it:

```clojure
;; Wrong - might keep old definitions
(require 'my.namespace)

;; Right - forces reload
(require 'my.namespace :reload)

;; Or reload all dependencies too
(require 'my.namespace :reload-all)
```

## Development Workflow Tips

1. **Start with exploration**: Use `all-ns` and `dir` to discover what's available
2. **Keep a scratch namespace**: Use `user` namespace for experiments
3. **Save useful snippets**: Copy successful REPL experiments to your editor
4. **Use editor integration**: Most Clojure editors can send code to REPL
5. **Check return values**: Always verify what functions return, not just side effects
6. **Explore before implementing**: Use `doc` and `source` to understand libraries
7. **Test edge cases**: Try `nil`, empty collections, invalid inputs at REPL
8. **Use REPL-driven testing**: Develop tests alongside code in REPL
9. **Search when stuck**: Use `apropos` to find functions by name patterns
10. **Search documentation**: Use `find-doc` to search docstrings across namespaces

## Example: Exploring an Unknown Namespace

```clojure
;; 1. Discover available namespaces
(map ns-name (all-ns))
; See clojure.string in the list

;; 2. Require the namespace
(require '[clojure.string :as str])

;; 3. Explore the namespace contents
(dir clojure.string)
; blank?
; capitalize
; ends-with?
; upper-case
; ...

;; 4. Find relevant functions
(apropos "upper")
; (clojure.string/upper-case)

;; 5. Get detailed documentation
(doc clojure.string/upper-case)
; -------------------------
; clojure.string/upper-case
; ([s])
;   Converts string to all upper-case.

;; 6. View implementation if needed
(source clojure.string/upper-case)
; (defn upper-case
;   [^CharSequence s]
;   (.. s toString toUpperCase))

;; 7. Test it
(str/upper-case "hello")
; => "HELLO"
```

## Summary

The Clojure REPL is your primary development tool:

### Core REPL Utilities (clojure.repl):
- **Explore namespaces**: `(map ns-name (all-ns))`
- **List functions**: `(dir namespace)`
- **Get documentation**: `(doc function)`
- **View source**: `(source function)`
- **Search symbols**: `(apropos "pattern")`
- **Search docs**: `(find-doc "pattern")`

### Interactive Development:
- **Evaluate immediately**: Get instant feedback on every expression
- **Explore actively**: Use `doc`, `source`, `dir`, `apropos`, `find-doc`
- **Debug interactively**: Use `pst`, `root-cause`, and special vars like `*e`
- **Develop iteratively**: Build and test small pieces, then combine
- **Learn continuously**: Read source code and documentation as you work

Master REPL-driven development and you'll write better Clojure code faster.


---
name: clojure-eval
description: |
  Evaluate Clojure expressions in the REPL for instant feedback and validation. 
  Use when testing code, exploring libraries, validating logic, debugging issues, 
  or prototyping solutions. Essential for REPL-driven development, verifying code 
  works before file edits, and discovering functions/namespaces.
---

# Clojure REPL Evaluation

## Quick Start

The `clojure_eval` tool evaluates Clojure code instantly, giving you immediate feedback. This is your primary way to test ideas, validate code, and explore libraries.

```clojure
; Simple evaluation
(+ 1 2 3)
; => 6

; Test a function
(defn greet [name]
  (str "Hello, " name "!"))

(greet "Alice")
; => "Hello, Alice!"

; Multiple expressions evaluated in sequence
(def x 10)
(* x 2)
(+ x 5)
; => 10, 20, 15
```

**Key benefits:**
- **Instant feedback** - Know if code works immediately
- **Safe experimentation** - Test without modifying files
- **Auto-linting** - Syntax errors caught before evaluation
- **Auto-balancing** - Parentheses fixed automatically when possible

## Core Workflows

### Workflow 1: Test Before You Commit to Files

Always validate logic in the REPL before using `clojure_edit` to modify files:

```clojure
; 1. Develop and test in REPL
(defn valid-email? [email]
  (and (string? email)
       (re-matches #".+@.+\..+" email)))

; 2. Test with various inputs
(valid-email? "alice@example.com")  ; => true
(valid-email? "invalid")            ; => false
(valid-email? nil)                  ; => false

; 3. Once validated, use clojure_edit to add to files
; 4. Reload and verify
(require '[my.namespace :reload])
(my.namespace/valid-email? "test@example.com")
```

### Workflow 2: Explore Libraries and Namespaces

Use built-in helper functions to discover what's available:

```clojure
; Find all namespaces
(clj-mcp.repl-tools/list-ns)

; List functions in a namespace
(clj-mcp.repl-tools/list-vars 'clojure.string)

; Get documentation
(clj-mcp.repl-tools/doc-symbol 'map)

; View source code
(clj-mcp.repl-tools/source-symbol 'clojure.string/join)

; Find functions by pattern
(clj-mcp.repl-tools/find-symbols "seq")

; Get completions
(clj-mcp.repl-tools/complete "clojure.string/j")

; Show all available helpers
(clj-mcp.repl-tools/help)
```

**When to use each helper:**
- `list-ns` - "What namespaces are available?"
- `list-vars` - "What functions does this namespace have?"
- `doc-symbol` - "How do I use this function?"
- `source-symbol` - "How is this implemented?"
- `find-symbols` - "What functions match this pattern?"
- `complete` - "I know part of the function name..."

### Workflow 3: Debug with Incremental Testing

Break complex problems into small, testable steps:

```clojure
; Start with sample data
(def users [{:name "Alice" :age 30}
            {:name "Bob" :age 25}
            {:name "Charlie" :age 35}])

; Test each transformation step
(filter #(> (:age %) 26) users)
; => ({:name "Alice" :age 30} {:name "Charlie" :age 35})

(map :name (filter #(> (:age %) 26) users))
; => ("Alice" "Charlie")

(clojure.string/join ", " (map :name (filter #(> (:age %) 26) users)))
; => "Alice, Charlie"
```

Each step is validated before adding the next transformation.

### Workflow 4: Reload After File Changes

After modifying files with `clojure_edit`, always reload and test:

```clojure
; Reload the namespace to pick up file changes
(require '[my.app.core :reload])

; Test the updated function
(my.app.core/my-new-function "test input")

; If there's an error, debug in the REPL
(my.app.core/helper-function "debug this")
```

**Important:** The `:reload` flag is required to force recompilation from disk.

## When to Use Each Approach

### Use `clojure_eval` When:
- Testing if code works before committing to files
- Exploring libraries and discovering functions
- Debugging issues with small test cases
- Validating assumptions about data
- Prototyping solutions quickly
- Learning how functions behave

### Use `clojure_edit` When:
- You've validated code works in the REPL
- Making permanent changes to source files
- Adding new functions or modifying existing ones
- Code is ready to be part of the codebase

### Combined Workflow:
1. **Explore** with `clojure_eval` and helper functions
2. **Prototype** solution in REPL
3. **Validate** it works with test cases
4. **Edit files** with `clojure_edit`
5. **Reload and verify** with `clojure_eval`

## Best Practices

**Do:**
- Test small expressions incrementally
- Validate each step before adding complexity
- Use helper functions to explore before coding
- Reload namespaces after file changes with `:reload`
- Test edge cases (nil, empty collections, invalid inputs)
- Keep experiments focused and small

**Don't:**
- Skip validation - always test before committing to files
- Build complex logic all at once without testing steps
- Assume cached definitions match file contents - reload first
- Use REPL for long-running operations (use files/tests instead)
- Forget to test error cases

## Common Issues

### Issue: "Undefined symbol or namespace"

```clojure
; Problem
(clojure.string/upper-case "hello")
; => Error: Could not resolve symbol: clojure.string/upper-case

; Solution: Require the namespace first
(require '[clojure.string :as str])
(str/upper-case "hello")
; => "HELLO"
```

### Issue: "Changes not appearing after file edit"

```clojure
; Problem: Modified file but function still has old behavior

; Solution: Use :reload to force recompilation
(require '[my.namespace :reload])

; Now test the updated function
(my.namespace/my-function)
```

### Issue: "NullPointerException"

```clojure
; Problem: Calling method on nil
(.method nil)

; Solution: Test for nil first or use safe navigation
(when-let [obj (get-object)]
  (.method obj))

; Or provide a default
(-> obj (or {}) :field)
```

## Advanced Topics

For comprehensive documentation on all REPL helper functions, see [REFERENCE.md](REFERENCE.md)

For complex real-world development scenarios and patterns, see [EXAMPLES.md](EXAMPLES.md)

## Summary

`clojure_eval` is your feedback loop for REPL-driven development:

1. **Test before committing** - Validate in REPL, then use `clojure_edit`
2. **Explore intelligently** - Use helper functions to discover
3. **Debug incrementally** - Break problems into small testable steps
4. **Always reload** - Use `:reload` after file changes
5. **Validate everything** - Never skip testing, even simple code

Master the REPL workflow and you'll write better code faster.


---
name: clojure-test-testing
description: |
  Built-in unit testing framework for Clojure with assertions, fixtures, and test organization.
  Use when writing tests, test-driven development, unit testing, assertion testing, or when the
  user mentions clojure.test, deftest, testing, assertions, is macro, fixtures, test organization,
  test reporting, or basic Clojure testing.
---

# clojure.test

Clojure's built-in unit testing framework providing assertions, test organization, fixtures, and reporting.

## Quick Start

clojure.test is part of Clojure core - no additional dependencies needed.

```clojure
(require '[clojure.test :refer [deftest is testing]])

;; Define a simple test
(deftest addition-test
  (is (= 4 (+ 2 2)))
  (is (= 7 (+ 3 4))))

;; Run the test
(addition-test)
;; => nil (passes silently)

;; Run all tests in namespace
(require '[clojure.test :refer [run-tests]])
(run-tests)
;; Prints summary and returns {:test 1, :pass 2, :fail 0, :error 0, :type :summary}
```

**Key benefits:**
- Built into Clojure - no external dependencies
- Simple, idiomatic assertion syntax
- Composable tests and fixtures
- Extensible reporting system
- Works with REPL-driven development

## Core Concepts

### Assertions with `is`

The `is` macro is the foundation of clojure.test. It evaluates an expression and reports success or failure.

```clojure
(require '[clojure.test :refer [is]])

;; Basic assertion
(is (= 4 (+ 2 2)))
;; => true

;; Failed assertion prints a report
(is (= 5 (+ 2 2)))
;; FAIL in () (NO_SOURCE_FILE:1)
;; expected: (= 5 (+ 2 2))
;;   actual: (not (= 5 4))
;; => false

;; Add descriptive message
(is (= 4 (+ 2 2)) "Two plus two equals four")

;; Any expression that returns truthy/falsy
(is (pos? 42))
(is (string? "hello"))
(is (.startsWith "hello" "hell"))
```

### Exception Testing

Test that code throws expected exceptions:

```clojure
;; Test that exception is thrown
(is (thrown? ArithmeticException (/ 1 0)))

;; Test exception type AND message
(is (thrown-with-msg? ArithmeticException #"Divide by zero" (/ 1 0)))

;; Common use case: testing validation
(defn parse-age [s]
  (let [n (Integer/parseInt s)]
    (when (neg? n)
      (throw (IllegalArgumentException. "Age must be positive")))
    n))

(is (thrown-with-msg? IllegalArgumentException #"positive" (parse-age "-5")))
```

### Test Organization with `deftest`

Group related assertions into named test functions:

```clojure
(require '[clojure.test :refer [deftest is]])

(deftest arithmetic-test
  (is (= 4 (+ 2 2)))
  (is (= 7 (+ 3 4)))
  (is (= 1 (- 4 3))))

;; Tests can call other tests (composition)
(deftest addition-test
  (is (= 4 (+ 2 2))))

(deftest subtraction-test
  (is (= 1 (- 4 3))))

(deftest all-arithmetic
  (addition-test)
  (subtraction-test))
```

### Contextual Testing with `testing`

Add descriptive context to groups of assertions:

```clojure
(require '[clojure.test :refer [deftest is testing]])

(deftest arithmetic-test
  (testing "Addition"
    (is (= 4 (+ 2 2)))
    (is (= 7 (+ 3 4))))
  
  (testing "Subtraction"
    (is (= 1 (- 4 3)))
    (is (= 3 (- 7 4))))
  
  (testing "Edge cases"
    (testing "with zero"
      (is (= 0 (+ 0 0)))
      (is (= 5 (+ 5 0))))
    (testing "with negatives"
      (is (= -1 (+ 1 -2))))))

;; Failed assertions include the testing context:
;; FAIL in (arithmetic-test) (file.clj:10)
;; Edge cases with zero
;; expected: (= 1 (+ 0 0))
;;   actual: (not (= 1 0))
```

## Common Workflows

### Workflow 1: Basic Test File Structure

Typical test namespace organization:

```clojure
(ns myapp.core-test
  (:require [clojure.test :refer [deftest is testing]]
            [myapp.core :as core]))

(deftest basic-functionality-test
  (testing "Core function works correctly"
    (is (= expected-result (core/my-function input)))))

(deftest edge-cases-test
  (testing "Handles nil input"
    (is (nil? (core/my-function nil))))
  
  (testing "Handles empty collection"
    (is (= [] (core/my-function [])))))

(deftest error-conditions-test
  (testing "Throws on invalid input"
    (is (thrown? IllegalArgumentException 
                 (core/my-function "invalid")))))
```

### Workflow 2: Multiple Assertions with `are`

Test the same logic with multiple inputs using the `are` macro:

```clojure
(require '[clojure.test :refer [deftest is are]])

;; Without are - repetitive
(deftest addition-verbose
  (is (= 2 (+ 1 1)))
  (is (= 4 (+ 2 2)))
  (is (= 6 (+ 3 3)))
  (is (= 8 (+ 4 4))))

;; With are - concise template
(deftest addition-concise
  (are [x y] (= x y)
    2 (+ 1 1)
    4 (+ 2 2)
    6 (+ 3 3)
    8 (+ 4 4)))

;; More complex example
(deftest string-operations
  (are [expected input] (= expected (clojure.string/upper-case input))
    "HELLO" "hello"
    "WORLD" "world"
    "FOO"   "foo"
    "BAR"   "bar"))

;; Multiple arguments
(deftest math-operations
  (are [result op x y] (= result (op x y))
    4  +  2 2
    0  -  2 2
    4  *  2 2
    1  /  2 2))
```

**Note**: `are` breaks some reporting features like line numbers, so use it for straightforward cases.

### Workflow 3: Setup and Teardown with Fixtures

Fixtures run setup/teardown code around tests:

```clojure
(require '[clojure.test :refer [deftest is use-fixtures]])

;; Define fixture function
(defn database-fixture [f]
  ;; Setup: create test database
  (println "Setting up test database")
  (def test-db (create-test-db))
  
  ;; Run the test(s)
  (f)
  
  ;; Teardown: clean up
  (println "Tearing down test database")
  (cleanup-test-db test-db))

;; Apply fixture to each test
(use-fixtures :each database-fixture)

;; Apply fixture once for entire namespace
(use-fixtures :once database-fixture)

;; Compose multiple fixtures
(defn logging-fixture [f]
  (println "Test starting")
  (f)
  (println "Test finished"))

(use-fixtures :each database-fixture logging-fixture)

(deftest query-test
  ;; database-fixture runs around this test
  (is (= expected-result (query test-db "SELECT ..."))))
```

**Fixture types:**
- `:each` - Runs around every `deftest` individually
- `:once` - Runs once around all tests in namespace

### Workflow 4: Running Tests

Multiple ways to run tests:

```clojure
(require '[clojure.test :refer [run-tests run-all-tests test-var]])

;; Run all tests in current namespace
(run-tests)
;; => {:test 5, :pass 12, :fail 0, :error 0, :type :summary}

;; Run tests in specific namespaces
(run-tests 'myapp.core-test 'myapp.util-test)

;; Run all tests in all loaded namespaces
(run-all-tests)

;; Run tests matching a regex
(run-all-tests #"myapp\..*-test")

;; Run a single test function
(require '[clojure.test :refer [run-test]])
(run-test my-specific-test)

;; Run a single test var
(test-var #'my-specific-test)

;; From the command line
;; clojure -M:test -m clojure.test.runner
```

### Workflow 5: Testing with Dynamic Bindings

Use dynamic vars for test state:

```clojure
(require '[clojure.test :refer [deftest is use-fixtures]])

;; Define dynamic var for test state
(def ^:dynamic *test-config* nil)

;; Fixture to bind test config
(defn with-test-config [f]
  (binding [*test-config* {:db-url "jdbc:test://localhost"
                           :timeout 1000}]
    (f)))

(use-fixtures :each with-test-config)

(deftest config-dependent-test
  (is (= "jdbc:test://localhost" (:db-url *test-config*)))
  (is (= 1000 (:timeout *test-config*))))

;; Common pattern for database testing
(def ^:dynamic *db-conn* nil)

(defn with-db-connection [f]
  (binding [*db-conn* (connect-to-test-db)]
    (try
      (f)
      (finally
        (disconnect *db-conn*)))))
```

### Workflow 6: Inline Tests with `with-test`

Attach tests directly to function definitions:

```clojure
(require '[clojure.test :refer [with-test is]])

(with-test
  (defn add [x y]
    (+ x y))
  
  (is (= 4 (add 2 2)))
  (is (= 7 (add 3 4)))
  (is (= 0 (add 0 0))))

;; Test is stored in metadata
(:test (meta #'add))
;; => #function[...]

;; Run the inline test
((:test (meta #'add)))

;; Or use test-var
(require '[clojure.test :refer [test-var]])
(test-var #'add)
```

**Note**: `with-test` doesn't work with `defmacro` (use `deftest` instead).

### Workflow 7: Custom Test Hooks

Control test execution order with `test-ns-hook`:

```clojure
(require '[clojure.test :refer [deftest is]])

(deftest setup-test
  (is (= :setup :done)))

(deftest test-a
  (is (= 1 1)))

(deftest test-b
  (is (= 2 2)))

(deftest teardown-test
  (is (= :cleanup :done)))

;; Define custom execution order
(defn test-ns-hook []
  (setup-test)
  (test-a)
  (test-b)
  (teardown-test))

;; When test-ns-hook exists, run-tests calls it instead of
;; running all tests. This gives you full control over execution.
```

**Note**: `test-ns-hook` and fixtures are mutually incompatible. Choose one approach.

## When to Use Each Approach

### Use `is` when:
- Writing simple assertions
- Testing individual expressions
- You need immediate REPL feedback

### Use `deftest` when:
- Organizing related assertions
- Creating reusable test suites
- Writing tests in separate test namespaces
- Following standard Clojure testing conventions

### Use `testing` when:
- Adding context to groups of assertions
- Nested test organization is helpful
- You want better error reporting

### Use `are` when:
- Testing the same logic with multiple inputs
- You have many similar assertions
- Code clarity is more important than precise line numbers

### Use fixtures when:
- Setup/teardown is needed for tests
- Managing shared test state
- Database connections or external resources
- Isolating test side effects

### Use `with-test` when:
- Writing quick inline tests
- Tests are tightly coupled to implementation
- Prototyping or experimenting

### Use `test-ns-hook` when:
- You need precise test execution order
- Tests have dependencies on each other
- Running composed test suites
- Don't use fixtures

## Best Practices

**DO:**
- Write focused tests that test one thing
- Use descriptive test names: `test-handles-empty-input-correctly`
- Add `testing` contexts for clear failure messages
- Use `are` for parameterized tests
- Keep tests independent - no shared mutable state
- Test edge cases: nil, empty collections, boundary values
- Use fixtures for setup/teardown, not manual code
- Make tests readable - clarity over cleverness
- Test behavior, not implementation details

**DON'T:**
- Mix `test-ns-hook` and fixtures (they're incompatible)
- Write tests that depend on execution order (unless using `test-ns-hook`)
- Share mutable state between tests
- Test private implementation details extensively
- Write overly complex test logic (tests should be simple)
- Forget to test exception cases
- Skip testing edge cases
- Use `are` when you need precise line numbers for failures

## Common Issues

### Issue: Tests Pass Individually but Fail Together

**Problem:** Tests work when run alone but fail when run with other tests.

```clojure
(def shared-state (atom []))

(deftest test-a
  (reset! shared-state [1 2 3])
  (is (= 3 (count @shared-state))))

(deftest test-b
  ;; Assumes shared-state is empty - fails if test-a runs first
  (is (empty? @shared-state)))
```

**Solution:** Use fixtures to reset shared state or avoid shared mutable state:

```clojure
(def shared-state (atom []))

(defn reset-state-fixture [f]
  (reset! shared-state [])
  (f))

(use-fixtures :each reset-state-fixture)

(deftest test-a
  (swap! shared-state conj 1 2 3)
  (is (= 3 (count @shared-state))))

(deftest test-b
  ;; Now guaranteed to start with empty state
  (is (empty? @shared-state)))
```

### Issue: Fixtures Not Running

**Problem:** Defined fixtures but they're not executing.

```clojure
(defn my-fixture [f]
  (println "Setting up")
  (f))

(use-fixtures :each my-fixture)

(defn test-ns-hook []  ;; This prevents fixtures from running!
  (my-test))

(deftest my-test
  (is (= 1 1)))
```

**Solution:** Remove `test-ns-hook` or manually call fixtures:

```clojure
;; Option 1: Remove test-ns-hook
;; (defn test-ns-hook [] ...) ;; Delete this

;; Option 2: Manually run fixtures in test-ns-hook
(defn test-ns-hook []
  (my-fixture #(my-test)))
```

### Issue: `is` Returns False but Test Appears to Pass

**Problem:** `is` returns false at REPL but test function seems to succeed.

```clojure
(deftest my-test
  (is (= 5 (+ 2 2))))  ;; Returns false, but...

(my-test)  ;; Prints failure report but returns nil
;; => nil
```

**Solution:** This is expected behavior. `is` returns the test result, but `deftest` always returns nil. Check the printed output or use `run-tests` to see the summary:

```clojure
(run-tests)
;; Shows: 1 failures, 0 errors
;; => {:test 1, :pass 0, :fail 1, :error 0, :type :summary}
```

### Issue: Can't See Test Output

**Problem:** Test output not appearing in expected location.

```clojure
(deftest my-test
  (println "Debug info")  ;; Where does this go?
  (is (= 4 (+ 2 2))))
```

**Solution:** Test output goes to `*test-out*` (default: `*out*`). Wrap in `with-test-out`:

```clojure
(require '[clojure.test :refer [deftest is with-test-out]])

(deftest my-test
  (with-test-out
    (println "This goes to *test-out*"))
  (is (= 4 (+ 2 2))))

;; Or redirect *test-out* to a file
(require '[clojure.java.io :as io])

(binding [clojure.test/*test-out* (io/writer "test-output.txt")]
  (run-tests))
```

### Issue: Exception Stack Traces Too Long

**Problem:** Stack traces make test output unreadable.

```clojure
(deftest my-test
  (is (= 1 (throw (Exception. "Oops")))))
;; Prints 50+ lines of stack trace
```

**Solution:** Limit stack trace depth with `*stack-trace-depth*`:

```clojure
(require '[clojure.test :as t])

(binding [t/*stack-trace-depth* 5]
  (run-tests))
;; Only shows first 5 stack frames
```

### Issue: `are` Not Showing Which Row Failed

**Problem:** When `are` assertions fail, line numbers aren't helpful.

```clojure
(deftest math-test
  (are [x y] (= x y)
    2 (+ 1 1)
    4 (+ 2 2)
    7 (+ 3 3)  ;; This fails but report just says "line 2"
    8 (+ 4 4)))
```

**Solution:** Use explicit `is` assertions when debugging, or add descriptive values:

```clojure
;; Option 1: Expand to explicit is forms for debugging
(deftest math-test
  (is (= 2 (+ 1 1)))
  (is (= 4 (+ 2 2)))
  (is (= 7 (+ 3 3)))  ;; Now shows correct line
  (is (= 8 (+ 4 4))))

;; Option 2: Add descriptive labels to are
(deftest math-test
  (are [label x y] (is (= x y) label)
    "1+1" 2 (+ 1 1)
    "2+2" 4 (+ 2 2)
    "3+3" 7 (+ 3 3)
    "4+4" 8 (+ 4 4)))
```


### Testing CLI Applications and Side Effects

When testing CLI applications, you often need to prevent actual side effects like System/exit calls or file system operations.

#### Preventing JVM Exit in Tests

Use dynamic vars with `binding` to intercept exit calls:

```clojure
(ns my-app.cli
  "CLI with exit handling for testing.")

;; Define a dynamic var for the exit function
(def ^:dynamic *exit-fn* 
  "Exit function that can be rebound in tests."
  (fn [code] (System/exit code)))

(defn cmd-delete [opts]
  "Delete command that validates and exits on error."
  (if-not (:force opts)
    (do
      (println "Use --force to confirm")
      (*exit-fn* 1))  ; Call through dynamic var
    (do-delete opts)))

;; In tests - bind *exit-fn* to prevent JVM exit
(ns my-app.cli-test
  (:require [clojure.test :refer [deftest is testing]]
            [my-app.cli :as cli]))

(defn mock-exit
  "Mock exit function that throws instead of exiting."
  [code]
  (throw (ex-info "Exit called" {:exit-code code})))

(deftest cmd-delete-without-force-test
  (testing "delete requires --force flag"
    (binding [cli/*exit-fn* mock-exit]
      ;; This would normally exit the JVM, but throws instead
      (is (thrown-with-msg? clojure.lang.ExceptionInfo
                            #"Exit called"
                            (cli/cmd-delete {:force false}))))))
```

**Why this works:**
- Dynamic vars (declared with `^:dynamic`) can be temporarily rebound with `binding`
- The binding is thread-local and automatically restored when leaving the binding scope
- Tests can replace `System/exit` without affecting other tests or the REPL

#### Combining binding and with-redefs

For complex tests, combine `binding` (for dynamic vars) and `with-redefs` (for regular functions):

```clojure
(deftest complex-cli-test
  (testing "CLI command with multiple side effects"
    ;; Bind dynamic vars
    (binding [cli/*exit-fn* mock-exit
              *out* (java.io.StringWriter.)]
      ;; Redefine regular functions
      (with-redefs [config/load-config (fn [] test-config)
                    config/init-config (fn [] nil)  ; No file system ops
                    db/get-connection (fn [] test-db)]
        
        ;; Now test the CLI command safely
        (let [result (cli/cmd-process {:input "test"})]
          (is (= :success (:status result))))))))
```

**Pattern:**
1. Use `binding` for dynamic vars you control (like `*exit-fn*`)
2. Use `with-redefs` for functions you don't control (like library functions)
3. Nest them - binding on outside, with-redefs on inside

#### Capturing stdout/stderr

Capture printed output for assertions:

```clojure
(defn capture-output
  "Capture stdout and return both result and output."
  [f]
  (let [out-writer (java.io.StringWriter.)]
    (binding [*out* out-writer]
      (let [result (f)]
        {:result result
         :output (str out-writer)}))))

(deftest output-test
  (testing "command prints expected message"
    (let [{:keys [result output]} (capture-output #(cli/cmd-help {}))]
      (is (re-find #"Usage:" output))
      (is (= 0 result)))))
```

#### Testing Database Commands

When testing database operations, ensure test isolation:

```clojure
(def test-db-path (str "test-" (random-uuid) ".db"))
(def ^:dynamic *test-db* nil)

(defn with-test-db
  "Fixture that creates and cleans up test database."
  [f]
  (let [db-spec {:dbtype "sqlite" :dbname test-db-path}
        ds (jdbc/get-datasource db-spec)]
    
    ;; Clean up any existing test db
    (try (.delete (java.io.File. test-db-path))
         (catch Exception _))
    
    ;; Run migrations
    (migrate/migrate-db db-spec)
    
    ;; Run tests with test database
    (binding [*test-db* ds]
      (f))
    
    ;; Clean up
    (try (.delete (java.io.File. test-db-path))
         (catch Exception _))))

(use-fixtures :each with-test-db)

(deftest db-operation-test
  (testing "database operation"
    (binding [cli/*exit-fn* mock-exit]
      (with-redefs [cli/load-config-and-db (fn [] [test-config *test-db*])]
        ;; Test uses isolated test database
        (cli/cmd-init {})
        (let [result (jdbc/execute-one! *test-db* 
                                        ["SELECT COUNT(*) as count FROM skills"])]
          (is (= 0 (:count result))))))))
```

**Key principles:**
- Each test gets a fresh database (`:each` fixture)
- Use unique filenames to avoid conflicts between parallel tests
- Always clean up in a finally block or fixture
- Include all required NOT NULL columns in test data

#### Common Pitfalls

**Problem: Tests hang indefinitely**
```clojure
;; BAD - System/exit kills the JVM
(defn delete-cmd [opts]
  (when-not (:force opts)
    (System/exit 1)))  ; Hangs tests!
```

**Solution: Use dynamic var**
```clojure
;; GOOD - Exit function can be rebound
(def ^:dynamic *exit-fn* (fn [code] (System/exit code)))

(defn delete-cmd [opts]
  (when-not (:force opts)
    (*exit-fn* 1)))  ; Can be mocked in tests
```

**Problem: File system operations in tests**
```clojure
;; BAD - Creates actual config files during tests
(deftest init-test
  (cmd-init {}))  ; Calls config/init-config which writes files!
```

**Solution: Mock file operations**
```clojure
;; GOOD - Mock file system operations
(deftest init-test
  (with-redefs [config/init-config (fn [] nil)]  ; No-op
    (cmd-init {})))
```

**Problem: Tests share state**
```clojure
;; BAD - All tests use same database file
(def test-db-path "test.db")
```

**Solution: Unique database per test run**
```clojure
;; GOOD - Each test run gets unique database
(def test-db-path (str "test-" (random-uuid) ".db"))
```

#### Best Practices

1. **Always use dynamic vars for testable side effects**
   - Exit functions
   - Print functions (use `*out*`, `*err*`)
   - Time functions (useful for testing timestamps)

2. **Create test helpers for common patterns**
   ```clojure
   (defn with-mocked-cli
     "Run function with all CLI side effects mocked."
     [f]
     (binding [cli/*exit-fn* mock-exit
               *out* (java.io.StringWriter.)]
       (with-redefs [config/init-config (fn [] nil)
                     config/load-config (fn [] test-config)]
         (f))))
   ```

3. **Test both success and error paths**
   ```clojure
   (deftest cmd-test
     (testing "success path"
       (binding [cli/*exit-fn* mock-exit]
         (is (= :success (cli/cmd {:valid true})))))
     
     (testing "error path - should exit"
       (binding [cli/*exit-fn* mock-exit]
         (is (thrown-with-msg? clojure.lang.ExceptionInfo
                               #"Exit called"
                               (cli/cmd {:valid false}))))))
   ```

4. **Use fixtures for common setup**
   ```clojure
   (defn mock-cli-fixture [f]
     (binding [cli/*exit-fn* mock-exit]
       (with-redefs [config/load-config (fn [] test-config)]
         (f))))
   
   (use-fixtures :each mock-cli-fixture)
   ```

This pattern enables comprehensive testing of CLI applications without unwanted side effects.
## Advanced Topics

### Custom Assertion Expressions

Extend `is` with custom assertion types:

```clojure
(require '[clojure.test :refer [deftest is assert-expr]])

;; Define custom assertion
(defmethod assert-expr 'approx= [msg form]
  (let [[_ expected actual tolerance] form]
    `(let [expected# ~expected
           actual# ~actual
           tolerance# ~tolerance
           diff# (Math/abs (- expected# actual#))]
       (if (<= diff# tolerance#)
         (do-report {:type :pass
                     :message ~msg
                     :expected '~form
                     :actual actual#})
         (do-report {:type :fail
                     :message ~msg
                     :expected '~form
                     :actual (list '~'not (list 'approx= expected# actual# tolerance#))})))))

;; Use custom assertion
(deftest float-math-test
  (is (approx= 0.333 (/ 1.0 3.0) 0.001)))
```

### Custom Reporters

Customize test output format:

```clojure
(require '[clojure.test :refer [report]])

;; Override default reporter
(defmethod report :fail [m]
  (println "FAILED:" (:message m))
  (println "Expected:" (:expected m))
  (println "Got:" (:actual m)))

;; Or use built-in alternative formats
(require '[clojure.test.junit :refer [with-junit-output]])
(require '[clojure.test.tap :refer [with-tap-output]])

;; JUnit XML output
(with-junit-output
  (run-tests))

;; TAP (Test Anything Protocol) output
(with-tap-output
  (run-tests))
```

## Integration with Test Runners

clojure.test works with all major Clojure test runners:

- **Kaocha** - Modern, feature-rich test runner (recommended)
- **Lazytest** - Fast, watch-mode runner
- **Cognitect test-runner** - Minimal CLI runner
- **Leiningen** - `lein test`
- **tools.build** - Build tool integration

All runners execute `clojure.test` tests - they add features like:
- Watch mode
- Parallel execution
- Filtering
- Better reporting
- Coverage analysis

## Resources

- [Official clojure.test API](https://clojure.github.io/clojure/clojure.test-api.html)
- [Clojure Testing Guide](https://clojure.org/guides/testing)
- [clojure.test Source](https://github.com/clojure/clojure/blob/master/src/clj/clojure/test.clj)

## Summary

clojure.test is Clojure's built-in testing framework providing:

1. **Simple assertions** - `is` macro for any predicate
2. **Test organization** - `deftest` and `testing` for structure
3. **Fixtures** - Setup/teardown with `use-fixtures`
4. **Composability** - Tests can call other tests
5. **Extensibility** - Custom assertions and reporters
6. **REPL integration** - Test interactively as you develop

**Core workflow:**
- Write tests with `deftest` and `is`
- Add context with `testing`
- Use `are` for parameterized tests
- Add fixtures for setup/teardown
- Run with `run-tests` or test runners

Master clojure.test and you have a solid foundation for testing any Clojure code.


---
name: babashka_scripting
description: |
  Fast-starting Clojure scripting and task runner built on GraalVM native image. Use when 
  writing shell scripts, build automation, task runners, CLI tools, fast startup scripting, 
  or when the user mentions Babashka, bb, task runner, shell scripting, native Clojure, 
  GraalVM, fast REPL, or scripting automation.
---

# Babashka

A fast-starting Clojure interpreter for scripting built with GraalVM native image. Babashka (bb) provides instant startup time, making Clojure practical for shell scripts, build tasks, and CLI tools.

## Quick Start

Babashka scripts start instantly and can use most Clojure features:

```clojure
#!/usr/bin/env bb

;; Simple script - save as script.clj
(println "Hello from Babashka!")
(println "Arguments:" *command-line-args*)

;; Run it
;; bb script.clj arg1 arg2
;; => Hello from Babashka!
;; => Arguments: (arg1 arg2)

;; Or use shebang and make executable
;; chmod +x script.clj
;; ./script.clj arg1 arg2

;; One-liner evaluation
;; bb -e '(+ 1 2 3)'
;; => 6

;; Process piped input
;; echo '{"name": "Alice"}' | bb -e '(-> *input* slurp (json/parse-string true) :name)'
;; => Alice
```

**Key benefits:**
- **Instant startup** - ~10ms vs 1-2s for JVM Clojure
- **Native executable** - No JVM installation required
- **Task runner** - Built-in task system via bb.edn
- **Rich standard library** - Including shell, http, file system, JSON, YAML
- **Script-friendly** - Process args, stdin/stdout, exit codes
- **Pod system** - Extend with native binaries

## Core Concepts

### Fast Startup via GraalVM Native Image

Babashka is compiled to a native executable using GraalVM, eliminating JVM startup time:

```bash
# Compare startup times
time bb -e '(println "Ready")'
# ~0.01s

time clojure -M -e '(println "Ready")'
# ~1-2s
```

**Trade-offs:**
- Instant startup vs slower runtime performance
- Fixed set of classes vs dynamic classloading
- Lower memory usage vs smaller heap
- Perfect for scripts, not for long-running servers

### Built-in Libraries

Babashka includes many useful libraries by default:

```clojure
;; File system (babashka.fs)
(require '[babashka.fs :as fs])
(fs/list-dir ".")
(fs/glob "." "**/*.clj")
(fs/create-dirs "target/build")

;; Shell (babashka.process)
(require '[babashka.process :as p])
(-> (p/shell {:out :string} "git status --short")
    :out)

;; HTTP client (babashka.http-client)
(require '[babashka.http-client :as http])
(http/get "https://api.github.com/users/babashka")

;; JSON (cheshire)
(require '[cheshire.core :as json])
(json/parse-string "{\"name\": \"Alice\"}" true)

;; YAML (clj-commons/clj-yaml)
(require '[clj-yaml.core :as yaml])
(yaml/parse-string "name: Alice\nage: 30")

;; Data manipulation (medley)
(require '[medley.core :as m])
(m/map-vals inc {:a 1 :b 2})

;; And many more...
```

### Task System

Define reusable tasks in `bb.edn`:

```clojure
;; bb.edn
{:tasks
 {:requires ([babashka.fs :as fs])
  
  ;; Simple task
  clean
  {:doc "Remove build artifacts"
   :task (fs/delete-tree "target")}
  
  ;; Task with dependencies
  test
  {:doc "Run tests"
   :depends [clean]
   :task (shell "clojure -M:test")}
  
  ;; Task with parameters
  deploy
  {:doc "Deploy to environment"
   :task (let [env (or (first *command-line-args*) "dev")]
           (println "Deploying to" env)
           (shell (str "deploy-" env ".sh")))}}}

;; Run tasks
;; bb tasks                  # List available tasks
;; bb clean                  # Run clean task
;; bb test                   # Run test (which runs clean first)
;; bb deploy production      # Run with args
```

### Process Execution

Babashka provides excellent shell integration:

```clojure
(require '[babashka.process :as p])

;; Simple command
(p/shell "ls -la")
;; Output goes to stdout

;; Capture output
(-> (p/shell {:out :string} "git status --short")
    :out
    println)

;; Pipeline
(p/pipeline
  (p/process ["cat" "file.txt"])
  (p/process ["grep" "ERROR"])
  (p/process ["wc" "-l"]))

;; Handle errors
(let [result (p/shell {:continue true} "false")]
  (when-not (zero? (:exit result))
    (println "Command failed!")))
```

## Common Workflows

### Workflow 1: Writing Executable Scripts

```clojure
#!/usr/bin/env bb

;; Script: backup.clj
;; Usage: ./backup.clj source-dir backup-dir

(require '[babashka.fs :as fs]
         '[babashka.process :as p])

(defn backup [source dest]
  (println "Backing up" source "to" dest)
  
  ;; Create backup directory
  (fs/create-dirs dest)
  
  ;; Copy files
  (doseq [file (fs/glob source "**/*")]
    (when (fs/regular-file? file)
      (let [relative (fs/relativize source file)
            target (fs/path dest relative)]
        (fs/create-dirs (fs/parent target))
        (fs/copy file target {:replace-existing true}))))
  
  (println "Backup complete!"))

;; Parse arguments
(when (< (count *command-line-args*) 2)
  (println "Usage: backup.clj <source> <dest>")
  (System/exit 1))

(let [[source dest] *command-line-args*]
  (backup source dest))

;; Make it executable:
;; chmod +x backup.clj
;;
;; Run it:
;; ./backup.clj ~/docs ~/backups/docs
```

### Workflow 2: Creating a Task Runner

```clojure
;; bb.edn - Project task definitions
{:deps {medley/medley {:mvn/version "1.3.0"}
        io.github.paintparty/bling {:mvn/version "0.6.0"}}
 
 :paths ["src" "test"]
 
 :tasks
 {:requires ([babashka.fs :as fs]
             [babashka.process :as p]
             [bling.core :as bling])
  
  ;; Clean build artifacts
  clean
  {:doc "Remove target directory"
   :task (do
           (bling/callout {:type :info} 
                          (bling/bling [:bold "Cleaning..."]))
           (fs/delete-tree "target")
           (bling/callout {:type :success} "Clean complete"))}
  
  ;; Run tests
  test
  {:doc "Run tests with Kaocha"
   :task (do
           (bling/callout {:type :info} 
                          (bling/bling [:bold "Running tests..."]))
           (p/shell "clojure -M:test"))}
  
  ;; Lint code
  lint
  {:doc "Lint with clj-kondo"
   :task (p/shell "clojure -M:lint -m clj-kondo.main --lint src test")}
  
  ;; Format code
  fmt
  {:doc "Format code with cljstyle"
   :task (p/shell "clojure -M:format -m cljstyle.main fix src test")}
  
  ;; Check formatting
  fmt-check
  {:doc "Check code formatting"
   :task (p/shell "clojure -M:format -m cljstyle.main check src test")}
  
  ;; Run full CI pipeline
  ci
  {:doc "Run CI pipeline: clean, lint, test"
   :task (do
           (run 'clean)
           (run 'fmt-check)
           (run 'lint)
           (run 'test)
           (bling/callout {:type :success} 
                          (bling/bling [:bold "CI passed!"])))}
  
  ;; Start REPL
  repl
  {:doc "Start nREPL server on port 7889"
   :task (p/shell "clojure -M:nrepl")}
  
  ;; Build uberjar
  build
  {:doc "Build uberjar"
   :depends [clean test]
   :task (do
           (bling/callout {:type :info} "Building uberjar...")
           (p/shell "clojure -T:build uber")
           (bling/callout {:type :success} "Build complete!"))}}}

;; Usage:
;; bb tasks              # List all tasks
;; bb clean              # Run clean task
;; bb ci                 # Run full CI pipeline
;; bb build              # Build (runs clean and test first)
```

### Workflow 3: HTTP API Client Script

```clojure
#!/usr/bin/env bb

;; Script: github-info.clj
;; Usage: ./github-info.clj username

(require '[babashka.http-client :as http]
         '[cheshire.core :as json])

(defn get-user-info [username]
  (let [url (str "https://api.github.com/users/" username)
        response (http/get url {:headers {"User-Agent" "Babashka"}})]
    (when (= 200 (:status response))
      (json/parse-string (:body response) true))))

(defn get-repos [username]
  (let [url (str "https://api.github.com/users/" username "/repos")
        response (http/get url {:headers {"User-Agent" "Babashka"}})]
    (when (= 200 (:status response))
      (json/parse-string (:body response) true))))

(defn display-info [username]
  (if-let [user (get-user-info username)]
    (do
      (println "Name:" (:name user))
      (println "Bio:" (:bio user))
      (println "Public Repos:" (:public_repos user))
      (println "Followers:" (:followers user))
      
      (println "\nTop 5 Repos:")
      (doseq [repo (->> (get-repos username)
                        (sort-by :stargazers_count >)
                        (take 5))]
        (println (format "  ⭐ %d - %s" 
                         (:stargazers_count repo)
                         (:name repo)))))
    (println "User not found")))

;; Main
(when (empty? *command-line-args*)
  (println "Usage: github-info.clj <username>")
  (System/exit 1))

(display-info (first *command-line-args*))
```

### Workflow 4: File Processing Pipeline

```clojure
#!/usr/bin/env bb

;; Script: process-logs.clj
;; Process log files and generate report

(require '[babashka.fs :as fs]
         '[clojure.string :as str])

(defn parse-log-line [line]
  (when-let [[_ timestamp level message] 
             (re-matches #"\[(.*?)\] (\w+): (.*)" line)]
    {:timestamp timestamp
     :level (keyword (str/lower-case level))
     :message message}))

(defn analyze-logs [log-dir]
  (let [log-files (fs/glob log-dir "*.log")
        entries (->> log-files
                     (mapcat (comp str/split-lines slurp))
                     (keep parse-log-line))]
    
    {:total (count entries)
     :by-level (frequencies (map :level entries))
     :errors (->> entries
                  (filter #(= :error (:level %)))
                  (map :message)
                  (take 10))}))

(defn report [stats]
  (println "Log Analysis Report")
  (println "===================")
  (println "Total entries:" (:total stats))
  (println "\nBy level:")
  (doseq [[level count] (sort-by val > (:by-level stats))]
    (println (format "  %s: %d" (name level) count)))
  (println "\nRecent errors:")
  (doseq [error (:errors stats)]
    (println "  -" error)))

;; Main
(when (empty? *command-line-args*)
  (println "Usage: process-logs.clj <log-directory>")
  (System/exit 1))

(-> (first *command-line-args*)
    analyze-logs
    report)
```

### Workflow 5: Data Transformation Script

```clojure
#!/usr/bin/env bb

;; Script: transform-data.clj
;; Read JSON/YAML, transform, output JSON/YAML

(require '[cheshire.core :as json]
         '[clj-yaml.core :as yaml]
         '[clojure.string :as str]
         '[babashka.fs :as fs])

(defn read-file [path]
  (let [content (slurp path)
        ext (fs/extension path)]
    (case ext
      "json" (json/parse-string content true)
      "yaml" (yaml/parse-string content)
      "yml" (yaml/parse-string content)
      (throw (ex-info "Unsupported format" {:ext ext})))))

(defn write-file [path data]
  (let [ext (fs/extension path)]
    (case ext
      "json" (spit path (json/generate-string data {:pretty true}))
      "yaml" (spit path (yaml/generate-string data))
      "yml" (spit path (yaml/generate-string data))
      (throw (ex-info "Unsupported format" {:ext ext})))))

(defn transform [data]
  ;; Example: uppercase all string values
  (clojure.walk/postwalk
    (fn [x]
      (if (string? x)
        (str/upper-case x)
        x))
    data))

;; Main
(when (< (count *command-line-args*) 2)
  (println "Usage: transform-data.clj <input> <output>")
  (System/exit 1))

(let [[input output] *command-line-args*]
  (-> input
      read-file
      transform
      (write-file output))
  (println "Transformed" input "→" output))
```

### Workflow 6: Interactive Task with User Input

```clojure
#!/usr/bin/env bb

;; Script: interactive-setup.clj
;; Interactive project setup

(defn prompt [message]
  (print (str message " "))
  (flush)
  (read-line))

(defn confirm [message]
  (= "y" (prompt (str message " (y/n)?"))))

(defn setup-project []
  (println "Project Setup")
  (println "=============")
  
  (let [name (prompt "Project name:")
        desc (prompt "Description:")
        author (prompt "Author:")
        use-test? (confirm "Include test setup?")
        use-ci? (confirm "Include CI config?")]
    
    {:name name
     :description desc
     :author author
     :features {:test use-test?
                :ci use-ci?}}))

(defn create-files [config]
  (require '[babashka.fs :as fs])
  
  ;; Create project structure
  (fs/create-dirs (str (:name config) "/src"))
  
  (when (get-in config [:features :test])
    (fs/create-dirs (str (:name config) "/test")))
  
  (when (get-in config [:features :ci])
    (spit (str (:name config) "/.github/workflows/ci.yml")
          "name: CI\n..."))
  
  (println "\n✓ Project created:" (:name config)))

;; Main
(let [config (setup-project)]
  (when (confirm "\nCreate project files?")
    (create-files config)
    (println "Done!")))
```

### Workflow 7: Conditional Task Execution

```clojure
;; bb.edn with conditional tasks
{:tasks
 {:requires ([babashka.fs :as fs])
  
  ;; Check if files changed
  changed?
  {:task (let [src-files (fs/glob "src" "**/*.clj")
               target (fs/file "target/build.timestamp")
               last-build (when (fs/exists? target)
                            (fs/file-time->millis target))
               latest-src (when (seq src-files)
                            (apply max (map fs/file-time->millis src-files)))]
           (or (nil? last-build)
               (> latest-src last-build)))}
  
  ;; Build only if changed
  build
  {:doc "Build if source files changed"
   :task (if (-> (shell {:out :string :continue true} "bb changed?")
                 :out
                 str/trim
                 boolean)
           (do
             (println "Source changed, rebuilding...")
             (shell "clojure -T:build compile")
             (fs/create-dirs "target")
             (spit "target/build.timestamp" (System/currentTimeMillis)))
           (println "No changes, skipping build"))}}}
```

## When to Use Each Approach

**Use Babashka when:**
- Writing shell scripts that need Clojure
- Building task runners and build tools
- Creating CLI tools with fast startup
- Processing files and data transformations
- Quick automation scripts
- Replacing bash/python scripts with Clojure
- CI/CD scripts
- Git hooks

**Use JVM Clojure when:**
- Building long-running applications
- Need dynamic classloading
- Require libraries not compatible with bb
- Performance-critical computations
- Large heap requirements
- Web servers (use http-kit/Ring on JVM)

**Can use either:**
- Data processing pipelines (bb faster startup, JVM faster runtime)
- API clients (bb sufficient for most cases)
- Testing utilities (bb for fast feedback, JVM for comprehensive)

## Best Practices

**DO:**
- Use shebang `#!/usr/bin/env bb` for executable scripts
- Handle *command-line-args* explicitly
- Exit with proper codes (0 success, non-zero error)
- Use `babashka.process/shell` for external commands
- Leverage built-in libraries (fs, http-client, process)
- Define reusable tasks in bb.edn
- Use `:doc` strings in task definitions
- Handle errors with proper messages
- Make scripts portable (avoid platform-specific paths)

**DON'T:**
- Try to load incompatible libraries
- Expect same performance as JVM for CPU-intensive work
- Use dynamic classloading (not supported)
- Forget to handle missing arguments
- Ignore exit codes from shell commands
- Hard-code paths (use babashka.fs)
- Write overly complex scripts (consider JVM app instead)

## Common Issues

### Issue: "Class Not Found"

**Problem:** Trying to use a library not included in Babashka

```clojure
(require '[some.library :as lib])
;; => Could not find namespace: some.library
```

**Solution:** Check if library is compatible or use pods

```clojure
;; Check built-in libraries
;; bb -e "(keys (ns-publics 'clojure.core))"

;; Add compatible dependency to bb.edn
{:deps {medley/medley {:mvn/version "1.3.0"}}}

;; Or use a pod for native libraries
;; See: https://github.com/babashka/pods
```

### Issue: "Command Not Found in Shell"

**Problem:** Shell command fails to find executable

```clojure
(require '[babashka.process :as p])
(p/shell "my-tool")
;; => Error: Cannot run program "my-tool"
```

**Solution:** Use full path or check PATH

```clojure
;; Use full path
(p/shell "/usr/local/bin/my-tool")

;; Or check PATH
(p/shell {:extra-env {"PATH" (str (System/getenv "PATH") ":/custom/path")}}
         "my-tool")
```

### Issue: "Task Not Found"

**Problem:** bb.edn task not recognized

```clojure
;; bb.edn
{:tasks {test {:task (println "Testing")}}}

;; bb test
;; => Could not find task: test
```

**Solution:** Check bb.edn location and syntax

```bash
# bb.edn must be in current directory or parent
# Check it's valid EDN
bb -e '(clojure.edn/read-string (slurp "bb.edn"))'

# List available tasks
bb tasks
```

### Issue: "Slow Performance"

**Problem:** Script is slower than expected

```clojure
;; Intensive computation
(reduce + (range 10000000))
;; Takes longer than JVM Clojure
```

**Solution:** Babashka optimizes for startup, not runtime

```bash
# For CPU-intensive work, use JVM Clojure
clojure -M -e '(time (reduce + (range 10000000)))'

# Or keep bb for orchestration, delegate heavy work:
bb -e '(babashka.process/shell "clojure -M -m my.cpu-intensive-app")'
```

## Advanced Topics

### Pods System

Pods extend Babashka with native binaries:

```clojure
;; Load pod
(require '[babashka.pods :as pods])
(pods/load-pod 'org.babashka/postgresql "0.1.0")

;; Use pod
(require '[pod.babashka.postgresql :as pg])
(pg/execute! db-spec ["SELECT * FROM users"])
```

Available pods: https://github.com/babashka/pods

### Preloads

Load code before script execution:

```clojure
;; bb.edn
{:paths ["."]
 :tasks {:init (load-file "helpers.clj")}}

;; helpers.clj
(defn my-helper [x] (str x "!"))

;; Now available in all tasks
{:tasks
 {greet {:task (println (my-helper "Hello"))}}}
```

### Native Image Compilation

Compile your own bb scripts to native binaries:

```bash
# Using GraalVM native-image
# See: https://www.graalvm.org/latest/reference-manual/native-image/
```

### Socket REPL

Start a REPL server for debugging:

```bash
bb socket-repl 1666
# Connect with: rlwrap nc localhost 1666

bb nrepl-server 1667
# Connect from editors (CIDER, Calva, etc.)
```

## Resources

- Official Documentation: https://book.babashka.org
- GitHub: https://github.com/babashka/babashka
- Built-in libraries: https://book.babashka.org/#libraries
- Pods registry: https://github.com/babashka/pods
- Examples: https://github.com/babashka/babashka/tree/master/examples
- Task runner guide: https://book.babashka.org/#tasks
- API docs: https://babashka.org/doc/api

## Related Tools

- **Babashka.fs** - File system library (built-in)
- **Babashka.process** - Shell process library (built-in)
- **Babashka.cli** - Command-line parsing
- **Babashka.http-client** - HTTP client (built-in)
- **Scittle** - Babashka for the browser
- **Nbb** - Node.js-based Clojure scripting

## Summary

Babashka makes Clojure practical for scripting:

- **Instant startup** - ~10ms for shell scripts
- **Native binary** - No JVM required
- **Task runner** - Built-in task system
- **Rich stdlib** - fs, http, process, json, yaml, and more
- **Script-friendly** - Args, stdin/stdout, exit codes
- **Pod system** - Extend with native libraries

Use Babashka for shell scripts, build automation, CLI tools, and anywhere fast startup matters more than long-running performance.


---
name: clojure_mcp_light_nrepl_cli
description: |
  Command-line nREPL evaluation tool with automatic delimiter repair for Claude Code integration.
  Use when evaluating Clojure code via nREPL from command line, REPL-driven development workflows,
  Claude Code Clojure integration, or when the user mentions clj-nrepl-eval, nREPL CLI, command-line
  REPL evaluation, automatic delimiter fixing, or Claude Code hooks for Clojure.
---

# clojure-mcp-light

A minimal CLI tooling suite for Clojure development with Claude Code providing automatic delimiter fixing and nREPL command-line evaluation.

## Quick Start

Install via bbin and start using immediately:

```bash
# Install both tools via bbin
bbin install https://github.com/bhauman/clojure-mcp-light.git --tag v0.2.0

bbin install https://github.com/bhauman/clojure-mcp-light.git --tag v0.2.0 \
  --as clj-nrepl-eval \
  --main-opts '["-m" "clojure-mcp-light.nrepl-eval"]'

# Discover running nREPL servers
clj-nrepl-eval --discover-ports

# Evaluate Clojure code via nREPL
clj-nrepl-eval -p 7889 "(+ 1 2 3)"
# => 6

# Automatic delimiter repair
clj-nrepl-eval -p 7889 "(+ 1 2 3"
# => 6  (automatically fixed missing delimiter)

# Check connected sessions
clj-nrepl-eval --connected-ports
```

**Key benefits:**
- Instant nREPL evaluation from command line
- Automatic delimiter repair before evaluation
- Persistent sessions across invocations
- Server discovery (finds .nrepl-port files and running processes)
- Connection tracking (remembers which servers you've used)
- Intelligent backend selection (parinfer-rust or parinferish)
- No MCP server needed (works with standard Claude Code tools)

## Core Concepts

### Command-Line nREPL Client

`clj-nrepl-eval` is a babashka-based CLI tool that communicates with nREPL servers using the bencode protocol:

```bash
# Evaluate code with automatic delimiter repair
clj-nrepl-eval -p 7889 "(+ 1 2 3)"

# Automatic delimiter fixing before evaluation
clj-nrepl-eval -p 7889 "(defn add [x y] (+ x y"
# Automatically repairs to: (defn add [x y] (+ x y))

# Pipe code via stdin
echo "(println \"Hello\")" | clj-nrepl-eval -p 7889

# Multi-line code via heredoc
clj-nrepl-eval -p 7889 <<'EOF'
(def x 10)
(def y 20)
(+ x y)
EOF
```

**How it works:**
- Detects delimiter errors using edamame parser
- Repairs delimiters with parinfer-rust (if available) or parinferish
- Sends repaired code to nREPL server via bencode protocol
- Handles timeouts and interrupts
- Maintains persistent sessions per host:port

### Automatic Delimiter Repair

Both tools use intelligent delimiter fixing:

```clojure
;; Before repair (missing closing delimiter)
(defn broken [x]
  (let [result (* x 2]
    result))

;; After automatic repair
(defn broken [x]
  (let [result (* x 2)]
    result))
```

**Repair backends:**
- **parinfer-rust** - Preferred when available (faster, battle-tested)
- **parinferish** - Pure Clojure fallback (no external dependencies)

The tool automatically selects the best available backend.

### Session Persistence

Sessions persist across command invocations:

```bash
# Define a var in one invocation
clj-nrepl-eval -p 7889 "(def x 42)"

# Use it in another invocation (same session)
clj-nrepl-eval -p 7889 "(* x 2)"
# => 84

# Reset session if needed
clj-nrepl-eval -p 7889 --reset-session
```

**Session files stored in:**
- `~/.clojure-mcp-light/sessions/`
- Separate file per host:port combination
- Cleaned up when nREPL server restarts

### Server Discovery

Find running nREPL servers without guessing ports:

```bash
# Discover servers in current directory
clj-nrepl-eval --discover-ports
# Discovered nREPL servers in current directory (/path/to/project):
#   localhost:7889 (bb)
#   localhost:55077 (clj)
#
# Total: 2 servers in current directory

# Check previously connected sessions
clj-nrepl-eval --connected-ports
# Active nREPL connections:
#   127.0.0.1:7889 (session: abc123...)
#
# Total: 1 active connection
```

**Discovery methods:**
- Reads `.nrepl-port` files in current directory
- Scans running JVM processes for nREPL servers
- Checks Babashka nREPL processes

## Common Workflows

### Workflow 1: Basic REPL-Driven Development

Start a server and evaluate code from command line:

```bash
# 1. Start an nREPL server
# Using Clojure CLI
clj -Sdeps '{:deps {nrepl/nrepl {:mvn/version "1.3.0"}}}' -M -m nrepl.cmdline

# Using Babashka
bb nrepl-server 7889

# Using Leiningen
lein repl :headless

# 2. Discover the server
clj-nrepl-eval --discover-ports

# 3. Evaluate code
clj-nrepl-eval -p 7889 "(+ 1 2 3)"
# => 6

# 4. Build up state incrementally
clj-nrepl-eval -p 7889 "(defn add [x y] (+ x y))"
clj-nrepl-eval -p 7889 "(add 10 20)"
# => 30

# 5. Load and test a namespace
clj-nrepl-eval -p 7889 "(require '[my.app.core :as core])"
clj-nrepl-eval -p 7889 "(core/my-function test-data)"
```

### Workflow 2: Working with Delimiter Errors

Let the tool automatically fix common delimiter mistakes:

```bash
# Missing closing paren
clj-nrepl-eval -p 7889 "(defn add [x y] (+ x y"
# Automatically fixed to: (defn add [x y] (+ x y))
# => #'user/add

# Mismatched delimiters
clj-nrepl-eval -p 7889 "[1 2 3)"
# Automatically fixed to: [1 2 3]
# => [1 2 3]

# Nested delimiter errors
clj-nrepl-eval -p 7889 "(let [x 10
                              y (+ x 5
                          (println y))"
# Automatically repaired and evaluated

# Check what was fixed (if logging enabled)
clj-nrepl-eval -p 7889 --log-level debug "(defn broken [x] (+ x 1"
```

### Workflow 3: Multi-Line Code Evaluation

Handle complex multi-line expressions:

```bash
# Using heredoc
clj-nrepl-eval -p 7889 <<'EOF'
(defn factorial [n]
  (if (<= n 1)
    1
    (* n (factorial (dec n)))))

(factorial 5)
EOF
# => 120

# From a file
cat src/my_app/core.clj | clj-nrepl-eval -p 7889

# With delimiter repair
clj-nrepl-eval -p 7889 <<'EOF'
(defn broken [x]
  (let [result (* x 2]
    result))
EOF
# Automatically fixed before evaluation
```

### Workflow 4: Session Management

Control evaluation context across invocations:

```bash
# Build up state in session
clj-nrepl-eval -p 7889 "(def config {:host \"localhost\" :port 8080})"
clj-nrepl-eval -p 7889 "(def db-conn (connect-db config))"
clj-nrepl-eval -p 7889 "(query db-conn \"SELECT * FROM users\")"

# Check active sessions
clj-nrepl-eval --connected-ports
# Active nREPL connections:
#   127.0.0.1:7889 (session: abc123...)

# Reset if state becomes corrupted
clj-nrepl-eval -p 7889 --reset-session

# Continue with fresh session
clj-nrepl-eval -p 7889 "(def x 1)"
```

### Workflow 5: Timeout Handling

Configure timeouts for long-running operations:

```bash
# Default timeout (120 seconds)
clj-nrepl-eval -p 7889 "(Thread/sleep 5000)"
# Completes normally

# Custom timeout (5 seconds)
clj-nrepl-eval -p 7889 --timeout 5000 "(Thread/sleep 10000)"
# ERROR: Timeout after 5000ms

# For interactive operations
clj-nrepl-eval -p 7889 --timeout 300000 "(run-comprehensive-tests)"
# 5 minute timeout for test suite
```

### Workflow 6: Working Across Multiple Projects

Manage connections to different nREPL servers:

```bash
# In project A
cd ~/projects/project-a
clj-nrepl-eval --discover-ports
# localhost:7889 (bb)

clj-nrepl-eval -p 7889 "(require '[project-a.core :as a])"
clj-nrepl-eval -p 7889 "(a/process-data data)"

# Switch to project B
cd ~/projects/project-b
clj-nrepl-eval --discover-ports
# localhost:7890 (clj)

clj-nrepl-eval -p 7890 "(require '[project-b.core :as b])"
clj-nrepl-eval -p 7890 "(b/analyze-results)"

# Check all active connections
clj-nrepl-eval --connected-ports
# Active nREPL connections:
#   127.0.0.1:7889 (session: abc123...)
#   127.0.0.1:7890 (session: xyz789...)
```

### Workflow 7: Claude Code Integration Pattern

Use clj-nrepl-eval as part of Claude Code workflows:

```markdown
# User: "Can you test if the add function works?"

# Agent uses clj-nrepl-eval to test interactively:

1. Load the namespace:
```bash
clj-nrepl-eval -p 7889 "(require '[my.app.math :reload] :as math)"
```

2. Test the function:
```bash
clj-nrepl-eval -p 7889 "(math/add 2 3)"
# => 5
```

3. Test edge cases:
```bash
clj-nrepl-eval -p 7889 "(math/add 0 0)"
# => 0

clj-nrepl-eval -p 7889 "(math/add -5 10)"
# => 5

clj-nrepl-eval -p 7889 "(math/add nil 5)"
# => NullPointerException (expected, now we know to add validation)
```

4. Report findings back to user with recommendations
```

## When to Use clj-nrepl-eval

**Use clj-nrepl-eval when:**
- Evaluating Clojure code from command line in Claude Code
- Testing functions interactively without opening an editor
- Building REPL-driven development workflows
- Need automatic delimiter repair before evaluation
- Working with multiple nREPL servers across projects
- Scripting Clojure evaluations in shell scripts
- Quick experimentation with code snippets
- Verifying code changes immediately after edits

**Use other tools when:**
- Need full IDE integration → Use CIDER, Calva, or Cursive
- Want comprehensive MCP server features → Use ClojureMCP
- Need more than evaluation → Use clojure-lsp for refactoring, formatting, etc.
- Writing long-form code → Use proper editor with REPL integration

## Best Practices

**DO:**
- Use `--discover-ports` to find nREPL servers automatically
- Check `--connected-ports` to see active sessions
- Reset sessions with `--reset-session` when state is unclear
- Use appropriate timeouts for long operations
- Leverage automatic delimiter repair for quick fixes
- Test code incrementally (small expressions first)
- Build up state in sessions for complex workflows
- Use heredocs for multi-line code blocks

**DON'T:**
- Hard-code ports (use discovery instead)
- Assume sessions persist forever (nREPL restart clears them)
- Skip delimiter repair validation (check if code makes sense)
- Use very short timeouts for complex operations
- Evaluate untrusted code without sandboxing
- Forget to reload namespaces after file changes
- Mix unrelated state in the same session
- Ignore evaluation errors

## Common Issues

### Issue: "Connection Refused"

**Problem:** Cannot connect to nREPL server

```bash
clj-nrepl-eval -p 7888 "(+ 1 2 3)"
# Error: Connection refused
```

**Solution:** Check if server is running and port is correct

```bash
# 1. Verify no server is running
clj-nrepl-eval --discover-ports
# No servers found

# 2. Start a server
bb nrepl-server 7889

# 3. Verify discovery
clj-nrepl-eval --discover-ports
# localhost:7889 (bb)

# 4. Try again with correct port
clj-nrepl-eval -p 7889 "(+ 1 2 3)"
# => 6
```

### Issue: "Timeout Waiting for Response"

**Problem:** Evaluation times out

```bash
clj-nrepl-eval -p 7889 "(Thread/sleep 150000)"
# ERROR: Timeout after 120000ms
```

**Solution:** Increase timeout for long operations

```bash
# Use longer timeout (in milliseconds)
clj-nrepl-eval -p 7889 --timeout 180000 "(Thread/sleep 150000)"
# Completes successfully

# Or use dedicated timeout for specific operations
clj-nrepl-eval -p 7889 --timeout 600000 "(run-comprehensive-test-suite)"
```

### Issue: "Undefined Var After Definition"

**Problem:** Vars defined in one invocation not found in next

```bash
clj-nrepl-eval -p 7889 "(def x 42)"
clj-nrepl-eval -p 7889 "x"
# Error: Unable to resolve symbol: x
```

**Solution:** This usually means different sessions or server restart

```bash
# Check if you have active session
clj-nrepl-eval --connected-ports
# Active nREPL connections: (none)

# Session was lost (server restarted)
# Redefine vars:
clj-nrepl-eval -p 7889 "(def x 42)"
clj-nrepl-eval -p 7889 "x"
# => 42

# Or use same invocation
clj-nrepl-eval -p 7889 "(do (def x 42) x)"
# => 42
```

### Issue: "Delimiter Repair Not Working"

**Problem:** Code still has delimiter errors after repair

```bash
clj-nrepl-eval -p 7889 "((("
# Still shows delimiter error
```

**Solution:** Some errors can't be automatically repaired

```bash
# Repair works for balanced but mismatched delimiters
clj-nrepl-eval -p 7889 "[1 2 3)"  # Fixed to [1 2 3]

# Repair works for missing closing delimiters
clj-nrepl-eval -p 7889 "(+ 1 2"   # Fixed to (+ 1 2)

# But can't repair meaningless expressions
clj-nrepl-eval -p 7889 "((("      # Too ambiguous

# Write valid Clojure expressions for best results
clj-nrepl-eval -p 7889 "(+ 1 2 3"  # This repairs successfully
```

### Issue: "Wrong Host or Port"

**Problem:** Trying to connect to wrong server

```bash
clj-nrepl-eval -p 7888 "(+ 1 2)"
# Connection refused (wrong port)
```

**Solution:** Use discovery to find correct port

```bash
# Find running servers
clj-nrepl-eval --discover-ports
# Discovered nREPL servers in current directory:
#   localhost:7889 (bb)

# Use discovered port
clj-nrepl-eval -p 7889 "(+ 1 2)"
# => 3

# For remote hosts, specify explicitly
clj-nrepl-eval --host 192.168.1.100 --port 7889 "(+ 1 2)"
```

### Issue: "Session State Confusion"

**Problem:** Session has unexpected state from previous work

```bash
clj-nrepl-eval -p 7889 "(def x 100)"
# Later...
clj-nrepl-eval -p 7889 "x"
# => 100 (but you expected fresh session)
```

**Solution:** Reset session when starting new work

```bash
# Reset to clean state
clj-nrepl-eval -p 7889 --reset-session

# Verify x is undefined
clj-nrepl-eval -p 7889 "x"
# Error: Unable to resolve symbol: x

# Start fresh
clj-nrepl-eval -p 7889 "(def x 1)"
```

## Advanced Topics

### Parinfer Backend Selection

The tool automatically selects the best delimiter repair backend:

```bash
# With parinfer-rust installed (preferred)
which parinfer-rust
# /usr/local/bin/parinfer-rust

# Falls back to parinferish if parinfer-rust not available
# Both provide equivalent functionality for delimiter repair
```

**Installing parinfer-rust (optional but recommended):**

```bash
# macOS via Homebrew
brew install parinfer-rust

# Or from source
# https://github.com/eraserhd/parinfer-rust
```

### Custom nREPL Middleware

clj-nrepl-eval works with any nREPL server, including those with custom middleware:

```bash
# Start server with custom middleware
clj -M:dev:nrepl -m nrepl.cmdline \
  --middleware '[my.middleware/wrap-custom]'

# Evaluate code normally
clj-nrepl-eval -p 7889 "(+ 1 2)"
# Custom middleware sees and processes the request
```

### Scripting with clj-nrepl-eval

Use in shell scripts for automation:

```bash
#!/bin/bash
# Script: run-tests.sh

# Start nREPL if not running
if ! clj-nrepl-eval --discover-ports | grep -q "7889"; then
  echo "Starting nREPL..."
  bb nrepl-server 7889 &
  sleep 2
fi

# Load test namespace
clj-nrepl-eval -p 7889 "(require '[my.app.test-runner :reload])"

# Run tests
clj-nrepl-eval -p 7889 "(my.app.test-runner/run-all-tests)"

# Exit with test status
exit $?
```

### Integration with Other Tools

Combine with other command-line tools:

```bash
# Format code, then evaluate
cat src/core.clj | cljfmt | clj-nrepl-eval -p 7889

# Generate test data and evaluate
echo '(range 10)' | clj-nrepl-eval -p 7889 | jq '.value'

# Evaluate multiple expressions from file
while read -r expr; do
  clj-nrepl-eval -p 7889 "$expr"
done < expressions.txt
```

## Resources

- GitHub Repository: https://github.com/bhauman/clojure-mcp-light
- nREPL Documentation: https://nrepl.org
- parinfer-rust: https://github.com/eraserhd/parinfer-rust
- parinferish: https://github.com/oakmac/parinferish
- Babashka: https://babashka.org
- bbin: https://github.com/babashka/bbin

## Related Tools

- **ClojureMCP** - Full MCP server with comprehensive Clojure tooling
- **nREPL** - The underlying network REPL protocol
- **CIDER** - Emacs integration with nREPL
- **Calva** - VSCode integration with nREPL
- **Cursive** - IntelliJ integration with nREPL

## Summary

clojure-mcp-light provides minimal, focused CLI tooling for Clojure development:

1. **clj-nrepl-eval** - Command-line nREPL client with automatic delimiter repair
2. **clj-paren-repair-claude-hook** - Claude Code hook for delimiter fixing (optional)

**Core features:**
- Instant nREPL evaluation from command line
- Automatic delimiter repair (parinfer-rust or parinferish)
- Persistent sessions across invocations
- Server discovery and connection tracking
- Timeout handling and interrupt support
- Multi-line code support (pipe, heredoc)
- No MCP server required

**Best for:**
- REPL-driven development from command line
- Claude Code Clojure integration
- Quick code experimentation
- Testing code after edits
- Shell script automation
- Multi-project workflows

Use clj-nrepl-eval when you need instant Clojure evaluation without opening an editor, especially in Claude Code workflows where automatic delimiter repair prevents common LLM-generated syntax errors.


---
name: clj_commons_pretty
description: |
  Format output with ANSI colors, pretty exceptions, binary dumps, tables, and code annotations.
  Use when formatting exception stack traces, creating colored terminal output, displaying binary
  data, printing tables, or annotating code with error messages. Use when the user mentions
  "pretty print", "format exception", "colored output", "ANSI", "stack trace", "hexdump",
  "binary output", "table formatting", or "code annotations".
---

# clj-commons/pretty

Library for formatted output with ANSI colors, pretty exceptions, binary dumps, tables, and code annotations.

## Quick Start

Pretty provides several independent formatting capabilities. Each can be used standalone:

```clojure
(require '[clj-commons.ansi :as ansi]
         '[clj-commons.format.exceptions :as exceptions]
         '[clj-commons.format.binary :as binary]
         '[clj-commons.format.table :as table])

;; Colored output
(ansi/pout [:bold.red "ERROR:"] " Something went wrong")

;; Pretty exceptions
(try
  (throw (ex-info "Failed" {:user-id 123}))
  (catch Exception e
    (exceptions/print-exception e)))

;; Binary dumps
(binary/print-binary (.getBytes "Hello"))

;; Tables
(table/print-table [:id :name] [{:id 1 :name "Alice"}])
```

## Core Concepts

### ANSI Color Support

Pretty automatically detects if color output is appropriate:
- Enabled in REPLs (nREPL, Cursive, `clj`)
- Disabled if `NO_COLOR` environment variable is set
- Can be controlled via `clj-commons.ansi.enabled` system property

### Composed Strings

Most Pretty functions work with "composed strings" - Hiccup-like data structures that include formatting:

```clojure
[:red "error"]                          ; Simple colored text
[:bold.yellow "Warning"]                ; Multiple font characteristics
[:red "Error: " [:bold "critical"]]     ; Nested formatting
```

## Common Workflows

### Workflow 1: Colored Console Output

Use `ansi/compose` to build formatted strings, `ansi/pout` and `ansi/perr` to print them:

```clojure
(require '[clj-commons.ansi :as ansi])

;; Print to stdout
(ansi/pout [:green.bold "✓"] " Tests passed")

;; Print to stderr
(ansi/perr [:red.bold "✗"] " Tests failed")

;; Build without printing
(def message (ansi/compose [:yellow "Warning: " [:bold "check input"]]))
```

**Font characteristics** (combine with periods):
- Colors: `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `black`
- Bright colors: `bright-red`, `bright-green`, etc.
- Background: `red-bg`, `green-bg`, `bright-blue-bg`, etc.
- Styles: `bold`, `faint`, `italic`, `underlined`, `inverse`, `crossed`
- Extended colors: `color-500` (RGB 5,0,0), `grey-0` through `grey-23`

```clojure
;; Complex formatting
(ansi/pout [:bold.bright-white.red-bg "CRITICAL"] 
           [:red " System overload at " 
            [:bold.yellow (java.time.LocalDateTime/now)]])
```

### Workflow 2: Pretty Exception Formatting

Format exceptions with readable stack traces, property display, and duplicate frame detection:

```clojure
(require '[clj-commons.format.exceptions :as exceptions])

;; Basic exception formatting
(try
  (/ 1 0)
  (catch Exception e
    (exceptions/print-exception e)))

;; Format with options
(try
  (throw (ex-info "Database error" 
                  {:query "SELECT * FROM users"
                   :connection-id 42}))
  (catch Exception e
    (exceptions/print-exception e
      {:frame-limit 10        ; Limit stack frames shown
       :properties true       ; Show exception properties (default)
       :traditional false}))) ; Modern ordering (default)
```

**Key features:**
- Stack frames in chronological order (shallow to deep)
- Clojure function names demangled
- File names and line numbers highlighted
- Exception properties pretty-printed
- Repeated frames collapsed

**Customizing frame filtering:**

```clojure
;; Set application namespaces for highlighting
(alter-var-root #'exceptions/*app-frame-names*
                (constantly #{"myapp" "mycompany"}))

;; Define custom frame filter
(defn my-filter [frame]
  (cond
    (re-find #"test" (:name frame)) :hide
    (= "clojure.core" (:package frame)) :omit
    :else :show))

(exceptions/print-exception e {:filter my-filter})
```

### Workflow 3: Binary Data Visualization

Display byte sequences with color-coded hex dumps and optional ASCII view:

```clojure
(require '[clj-commons.format.binary :as binary])

;; Basic hex dump
(def data (.getBytes "Choose immutability"))
(binary/print-binary data)
; 0000: 43 68 6F 6F 73 65 20 69 6D 6D 75 74 61 62 69 6C
; 0010: 69 74 79

;; With ASCII sidebar (16 bytes per line)
(binary/print-binary data {:ascii true})
; 0000: 43 68 6F 6F 73 65 20 69 6D 6D 75 74 61 62 69 6C │Choose immutabil│
; 0010: 69 74 79                                        │ity             │

;; Custom line width (default 32, or 16 with :ascii)
(binary/print-binary data {:line-bytes 8})

;; Compare two byte sequences
(def expected (.getBytes "Hello World"))
(def actual (.getBytes "Hello Clojure"))
(binary/print-binary-delta expected actual)
; Differences highlighted in green (expected) and red (actual)
```

**Byte color coding:**
- ASCII printable: cyan
- Whitespace: green
- Control characters: red
- Extended ASCII: yellow

### Workflow 4: Table Formatting

Print data as formatted tables with borders, alignment, and custom styling:

```clojure
(require '[clj-commons.format.table :as table])

(def users
  [{:id 1 :name "Alice" :role :admin}
   {:id 2 :name "Bob" :role :user}
   {:id 3 :name "Charlie" :role :user}])

;; Simple table
(table/print-table [:id :name :role] users)
; ┌──┬───────┬─────┐
; │Id│  Name │Role │
; ├──┼───────┼─────┤
; │ 1│  Alice│:admin│
; │ 2│    Bob│:user │
; │ 3│Charlie│:user │
; └──┴───────┴─────┘

;; Custom column configuration
(table/print-table
  [{:key :id :title "ID" :align :right}
   {:key :name :title "User Name" :width 15}
   {:key :role 
    :title "Role"
    :formatter #(if (= :admin %) "Administrator" "User")
    :decorator (fn [idx val] (when (= :admin val) :bold.green))}]
  users)

;; Different table styles
(table/print-table
  {:columns [:id :name :role]
   :style table/skinny-style}
  users)
; ID | Name    | Role
; ---+---------+------
;  1 | Alice   | :admin
;  2 | Bob     | :user
;  3 | Charlie | :user

(table/print-table
  {:columns [:id :name :role]
   :style table/minimal-style}
  users)
; ID  Name     Role
;  1  Alice    :admin
;  2  Bob      :user
;  3  Charlie  :user
```

**Column options:**
- `:key` - Keyword or function to extract value (required)
- `:title` - Column header (defaults to capitalized key)
- `:width` - Fixed width or auto-calculated
- `:align` - `:left`, `:right` (default), or `:center`
- `:title-align` - Alignment for title (default `:center`)
- `:formatter` - Function to format cell value
- `:decorator` - Function returning font declaration for cell

**Table options:**
- `:columns` - Vector of columns
- `:style` - `default-style`, `skinny-style`, or `minimal-style`
- `:row-decorator` - Function to style entire rows
- `:row-annotator` - Function to add notes after rows

### Workflow 5: Code Annotations

Annotate source code with error markers and messages:

```clojure
(require '[clj-commons.pretty.annotations :as ann]
         '[clj-commons.ansi :as ansi])

;; Annotate a single line
(def source "SELECT DATE, AMT FROM PAYMENTS")
(ansi/perr source)
(run! ansi/perr
  (ann/callouts [{:offset 7 
                  :length 4 
                  :message "Invalid column name"}]))
; SELECT DATE, AMT FROM PAYMENTS
;        ▲▲▲▲
;        │
;        └╴ Invalid column name

;; Multiple annotations on one line
(run! ansi/perr
  (ann/callouts [{:offset 7 :length 4 :message "Invalid column"}
                 {:offset 17 :length 8 :message "Unknown table"}]))
; SELECT DATE, AMT FROM PAYMENTS
;        ▲▲▲▲         ▲▲▲▲▲▲▲▲
;        │            │
;        │            └╴ Unknown table
;        └╴ Invalid column

;; Annotate multiple lines
(def lines
  [{:line "SELECT DATE, AMT"
    :annotations [{:offset 7 :length 4 :message "Invalid column"}]}
   {:line "FROM PAYMENTS WHERE AMT > 10000"
    :annotations [{:offset 13 :length 5 :message "Unknown keyword"}]}])

(run! ansi/perr (ann/annotate-lines lines))
; 1: SELECT DATE, AMT
;           ▲▲▲▲
;           │
;           └╴ Invalid column
; 2: FROM PAYMENTS WHERE AMT > 10000
;                  ▲▲▲▲▲
;                  │
;                  └╴ Unknown keyword

;; Custom styling
(run! ansi/perr
  (ann/callouts 
    {:font :red.bold
     :marker "^"
     :spacing :minimal}
    [{:offset 7 :length 4 :message "Error here"}]))
```

**Annotation options:**
- `:offset` - Column position (0-based, required)
- `:length` - Characters to mark (default 1)
- `:message` - Error message (composed string)
- `:font` - Override style font for this annotation
- `:marker` - Override marker character(s)

**Style options:**
- `:font` - Default font (default `:yellow`)
- `:spacing` - `:tall`, `:compact` (default), or `:minimal`
- `:marker` - Marker string or function (default "▲")
- `:bar` - Vertical bar character (default "│")
- `:nib` - Connection before message (default "└╴ ")

### Workflow 6: Enable Pretty Exceptions in REPL

Install pretty exception printing for your development environment:

```clojure
;; In user.clj or at REPL startup
(require '[clj-commons.pretty.repl :as pretty-repl])
(pretty-repl/install-pretty-exceptions)

;; Now all REPL exceptions use pretty formatting
(/ 1 0)
; Pretty formatted ArithmeticException output
```

**Project integration:**

For Leiningen (`~/.lein/profiles.d/debug.clj`):
```clojure
{:dependencies [[org.clj-commons/pretty "3.6.7"]]
 :injections [(require '[clj-commons.pretty.repl :as repl])
              (repl/install-pretty-exceptions)]}
```

For deps.edn (`:debug` alias):
```clojure
{:aliases
 {:debug
  {:extra-deps {org.clj-commons/pretty {:mvn/version "3.6.7"}}
   :exec-fn clj-commons.pretty.repl/main}}}
```

For nREPL middleware:
```clojure
;; Add to .nrepl.edn or nrepl config
{:middleware [clj-commons.pretty.nrepl/wrap-pretty]}
```

## When to Use Each Feature

**Use ANSI colors when:**
- Creating CLI tools with colored output
- Highlighting important information in logs
- Building developer tools and REPLs
- Formatting success/error/warning messages

**Use exception formatting when:**
- Debugging complex stack traces
- Building error reporting tools
- Creating developer-friendly error messages
- Need to understand nested exceptions

**Use binary formatting when:**
- Debugging binary protocols
- Comparing byte sequences
- Analyzing file formats
- Inspecting serialized data

**Use table formatting when:**
- Displaying query results
- Showing configuration data
- Comparing multiple items
- Creating CLI reports

**Use code annotations when:**
- Building error reporters for parsers
- Highlighting syntax errors
- Creating educational tools
- Showing code issues in tooling

## Best Practices

**Do:**
- Check if color is enabled before complex formatting: `(ansi/when-color-enabled ...)`
- Use composed strings for flexibility
- Set `*app-frame-names*` to highlight your code in stack traces
- Provide custom exception dispatch for complex types
- Use appropriate table styles for your use case
- Keep annotation messages concise (no line breaks)

**Don't:**
- Generate ANSI codes manually - use `compose`
- Mix Pretty's exception formatting with manual `.printStackTrace`
- Forget that composed strings need `compose` to become actual strings
- Create deeply nested font definitions - keep formatting simple
- Use `:ascii` mode for binary output wider than 16 bytes per line
- Overlap annotation ranges on the same line

## Common Issues

### "ANSI codes appear in output"

Colors disabled but codes still showing:

```clojure
;; Check if colors are enabled
ansi/*color-enabled*  ; => false

;; Colors are explicitly disabled
;; Either: NO_COLOR env var is set
;; Or: clj-commons.ansi.enabled system property is "false"
;; Or: No console/REPL detected

;; Force enable (for testing)
(alter-var-root #'ansi/*color-enabled* (constantly true))
```

### "Stack trace still looks like Java output"

Pretty exceptions not installed:

```clojure
;; Install pretty exceptions
(require '[clj-commons.pretty.repl :as pretty-repl])
(pretty-repl/install-pretty-exceptions)

;; Or check if already installed
(pretty-repl/install-pretty-exceptions)  ; Safe to call multiple times
```

### "Binary output shows wrong width"

Line width calculation doesn't account for tabs/ANSI codes:

```clojure
;; Specify explicit line width
(binary/print-binary data {:line-bytes 16})

;; For ASCII mode, always use 16 bytes per line
(binary/print-binary data {:ascii true :line-bytes 16})
```

### "Table columns too wide/narrow"

Width auto-calculated from data:

```clojure
;; Specify explicit width
(table/print-table
  [{:key :name :width 20}
   {:key :description :width 50}]
  data)

;; Or use formatters to control content
(table/print-table
  [{:key :name}
   {:key :description
    :formatter #(subs % 0 (min 50 (count %)))}]
  data)
```

### "Annotations overlap"

Multiple annotations with overlapping ranges:

```clojure
;; Bad: overlapping ranges
[{:offset 5 :length 10}
 {:offset 8 :length 5}]  ; Overlaps with first

;; Good: non-overlapping
[{:offset 5 :length 3}
 {:offset 10 :length 5}]

;; Annotations automatically sorted by offset
;; But overlaps still cause visual issues
```

## Advanced Topics

### Custom Exception Dispatch

Control how specific types appear in exception output:

```clojure
(import 'com.stuartsierra.component.SystemMap)

(defmethod exceptions/exception-dispatch SystemMap 
  [system-map]
  (print "#<SystemMap>"))

;; Now SystemMap instances show as "#<SystemMap>" instead of full structure
```

### Custom Table Decorators

Add visual styling to table rows and cells:

```clojure
(table/print-table
  {:columns [:status :message]
   :row-decorator (fn [idx row]
                    (case (:status row)
                      :error :red
                      :warning :yellow
                      :success :green
                      nil))}
  [{:status :error :message "Failed"}
   {:status :success :message "OK"}])
```

### Custom Annotation Markers

Create custom marker functions:

```clojure
(defn wave-marker [length]
  (apply str (repeat length "~")))

(run! ansi/perr
  (ann/callouts 
    {:marker wave-marker}
    [{:offset 5 :length 10 :message "Issue here"}]))
; Some text here with a problem
;      ~~~~~~~~~~
;      │
;      └╴ Issue here
```

### Parsing Exception Text

Convert text-based exception output back to Pretty's format:

```clojure
;; Useful for processing exception logs
(def exception-text 
  "java.lang.ArithmeticException: Divide by zero
    at clojure.lang.Numbers.divide(Numbers.java:188)
    at user$eval123.invokeStatic(REPL:1)")

(def parsed (exceptions/parse-exception exception-text {}))
(exceptions/print-exception* parsed {})
```

## Performance Considerations

- **ANSI composition** is fast; overhead is minimal
- **Exception formatting** processes entire stack trace; use `:frame-limit` for very deep stacks
- **Binary formatting** with `:ascii` doubles memory usage (hex + ASCII)
- **Table formatting** calculates widths from all data; slow for huge datasets
- **Annotations** are fast; multiple annotations per line add minimal overhead

For large datasets or performance-critical paths, consider:
- Format once, cache the result
- Use `:frame-limit` to reduce exception output
- Limit table row count for display
- Use streaming approaches for binary data

## Related Libraries

- `clojure.pprint` - Basic pretty printing (Pretty extends this)
- `puget` - Alternative pretty printer with color support
- `fipp` - Fast pretty printer
- `bling` - Terminal UI components and coloring

## Resources

- [GitHub Repository](https://github.com/clj-commons/pretty)
- [API Documentation](https://cljdoc.org/d/org.clj-commons/pretty)
- [CLJ Commons](https://clj-commons.org/)

## Summary

`clj-commons/pretty` provides five independent formatting capabilities:

1. **ANSI colors** (`clj-commons.ansi`) - Colored terminal output
2. **Exception formatting** (`clj-commons.format.exceptions`) - Readable stack traces
3. **Binary visualization** (`clj-commons.format.binary`) - Hex dumps and deltas
4. **Table formatting** (`clj-commons.format.table`) - Pretty tabular output
5. **Code annotations** (`clj-commons.pretty.annotations`) - Error markers on source

Each can be used independently or combined for comprehensive formatted output.