🤝 Contributing to ZSHAND¶

📋 This guide covers dev setup, workflow, conventions, and quality requirements for contributing to the ZSHAND framework.

Every contribution should leave the codebase faster, better documented, and better tested than before. Headers are not optional — they're how we communicate intent to humans, AI, and tooling alike.

🚀 Getting Started¶

📋 Prerequisites¶

🛠️ Dev Setup¶

Option 1: Dev Container (Recommended for new contributors)

# 1. Open in VS Code/Cursor with Dev Containers extension
# 2. Click "Reopen in Container" when prompted
# 3. Everything is set up automatically!
#    - All tools installed via mise
#    - zsh and zshdb ready for debugging
#    - Consistent environment for all contributors

See the 🐳 Using Dev Containers section for details.

Option 2: Local Setup

# 1. Clone the repo
git clone https://github.com/presempathy/zshand.git ~/code/zshand
cd ~/code/zshand

# 2. Install tools via mise
mise install

# 3. Run first-time setup (installs deps, creates user config dir)
zsh setup.zsh

# 4. Enable dev mode (disables bundles, enables debug output)
export ZSHAND_DEV_MODE=1
exec zsh

# 5. Verify everything works
just test          # Run full test suite
just lint          # Run linters
zcheck             # Framework integrity audit

With ZSHAND_DEV_MODE=1, the framework loads individual files instead of compiled bundles, and enables debug output. Always develop in this mode so you see changes immediately without recompiling.

📋 Using Just (Task Runner)¶

Just is the project's task runner. It provides a consistent interface for common development tasks.

🚀 Quick Start¶

# List all available tasks
just --list

# Run a task
just test
just lint
just build

📝 Common Tasks¶

⚠️ Important Notes¶

• Always run just test before committing to ensure tests pass
• Run just lint to catch formatting and linting issues early
• Use just check before opening a PR to run the full quality gate
• If a task fails, fix the errors before proceeding — don't skip tests or linting

Never commit code that fails just test or just lint. These checks run in CI/CD and will block your PR. If tests are failing, fix them locally first.

🐳 Using Dev Containers¶

Dev Containers provide a consistent development environment across all contributors, ensuring everyone has the same tools and dependencies.

🚀 Quick Start¶

1. Open in VS Code/Cursor with the Dev Containers extension installed
2. Click "Reopen in Container" when prompted, or use Command Palette:
3. F1 → Dev Containers: Reopen in Container
4. Wait for setup — the container will build and install dependencies automatically

📦 What's Included¶

The dev container automatically installs:

• zsh and zshdb (for debugging)
• mise (tool version manager)
• All development tools via mise (node, go, rust, uv, shellspec, just)
• Git and GitHub CLI

🔧 Configuration¶

The dev container configuration is in .devcontainer/devcontainer.json:

• Base image: mcr.microsoft.com/devcontainers/base:ubuntu
• Features: Common utilities, Git, Python
• Post-create: Installs zsh and zshdb

🐛 Debugging in Dev Container¶

The dev container includes zshdb for debugging zsh scripts:

1. Set breakpoints in your .zsh files
2. Use VS Code's Debug panel (F5)
3. Select "Debug Zsh Script" configuration
4. Step through code with full debugging support

⚠️ Important Notes¶

• All development happens inside the container — your local files are mounted
• Changes persist — files are synced between container and host
• Run just test inside the container to ensure compatibility
• Don't install tools manually — use mise or the container's package manager

The first time you open the dev container, it may take a few minutes to build. Subsequent opens are much faster thanks to Docker layer caching.

🧪 Using ShellSpec¶

ShellSpec is the BDD-style testing framework used for all test suites. It provides descriptive test syntax and comprehensive assertion matchers.

🚀 Quick Start¶

# Run all tests
shellspec

# Run specific spec file
shellspec spec/functions/dcopy_spec.sh

# Run tests in a directory
shellspec spec/core/

# Run with verbose output
shellspec --format documentation

# Run with coverage (requires kcov)
shellspec --kcov

📝 Writing ShellSpec Tests¶

Basic Structure¶

#!/usr/bin/env shellspec
# ── function_name_spec — Tests for function_name ──────────────────────────

Describe "function_name"
  # Setup (runs before each test)
  BeforeAll 'source "${PROJECT_ROOT}/functions/function_name.zsh"'

  It "returns success on valid input"
    When call function_name "valid_arg"
    The status should be success
    The output should include "expected text"
  End

  It "exits with error when argument missing"
    When call function_name
    The status should be failure
    The stderr should include "ERROR:"
  End

  It "handles edge cases correctly"
    When call function_name ""
    The status should be failure
  End
End

Common Matchers¶

Test Organization¶

spec/
├── functions/
│   └── dcopy_spec.sh          # Tests for functions/dcopy.zsh
├── core/
│   └── 08_audit_spec.sh        # Tests for core/08_audit.zsh
└── shared_functions/
    └── 01_stderr_error_spec.sh # Tests for shared_functions/01_stderr_error.zsh

Rule: Spec files mirror the source tree structure.

⚠️ Important Notes¶

• Always write tests for new functions or behavior changes
• Run tests before committing — use just test or shellspec
• Keep tests fast — avoid slow operations (network, file I/O) unless testing them
• Test edge cases — empty strings, missing args, invalid input
• Use descriptive test names — It "does something specific" not It "works"

All tests must pass before committing. If a test fails: 1. Read the error message carefully 2. Fix the code (not the test, unless the test is wrong) 3. Re-run the test to verify the fix 4. Run the full suite with just test before committing

📊 Coverage Expectations¶

📐 Conventions¶

📝 Header Standard¶

Every file must have a documentation header following HEADER_STANDARD.md. This is non-negotiable.

Quick checklist for every new file:

• ✅ Title line or box at correct tier
• ✅ USAGE section with signature and arguments
• ✅ DEPENDENCIES section (even if "None")
• ✅ EXIT CODES section
• ✅ EXAMPLES section (copy-pasteable)
• ✅ TESTING section (spec path, status, must-cover list)
• ✅ SEE ALSO section (related files)
• ✅ Closing rule (# ──...──)
• ✅ All dividers exactly 78 chars after #

🔢 File Naming¶

🏷️ Function Naming¶

🔄 Workflow¶

🌿 Branch Strategy¶

main              ← stable, always passes tests
  └── feat/name   ← feature branches (short-lived)
  └── fix/name    ← bug fix branches
  └── docs/name   ← documentation-only changes

✅ Before Submitting¶

Run the full quality gate:

# 1. Lint (fixes formatting automatically)
just lint                    # or: trunk check

# 2. Test (all tests must pass)
just test                    # Full ShellSpec suite
shellspec spec/core/         # Specific directory

# 3. Verify headers
grep -c '# ──' <your-file>  # Count section dividers

# 4. Benchmark (if touching startup path)
hyperfine --warmup 3 'zsh -ic exit'

# 5. Compile and verify
zprime                       # Rebuild all bundles
zcheck                       # Framework integrity

# Or run everything at once:
just check                   # Runs lint + test + build

All tests (just test) and linters (just lint) must pass before submitting. These checks run automatically in CI/CD and will block your PR if they fail.

📝 Commit Messages¶

Follow conventional commit format:

type(scope): short description

Optional longer description explaining why.

Closes #123

🧪 Testing Requirements¶

Every contribution that adds or modifies behavior must include tests using ShellSpec.

For detailed information on writing and running ShellSpec tests, see the 🧪 Using ShellSpec section above.

📍 Where Tests Go¶

Spec files mirror the source tree:

functions/dcopy.zsh           →  spec/functions/dcopy_spec.sh
core/08_audit.zsh             →  spec/core/08_audit_spec.sh
shared_functions/01_stderr_error.zsh  →  spec/shared_functions/01_stderr_error_spec.sh

🚀 Running Tests¶

# Run all tests (recommended)
just test

# Run specific spec file
shellspec spec/functions/dcopy_spec.sh

# Run tests in a directory
shellspec spec/core/

# Run with verbose output
shellspec --format documentation

📊 Coverage Expectations¶

Do not delete or relax existing test assertions without explicit approval. If a test needs updating, explain why in the commit message.

Always run just test before committing. Failing tests will block your PR in CI/CD.

✨ Linting & Formatting¶

The framework uses Trunk to manage all linters:

🚀 Running Linters¶

trunk check                  # Check all changed files
trunk check --all            # Check everything
trunk check <file>           # Check specific file
trunk fmt                    # Auto-fix formatting issues

⚠️ ShellCheck Overrides¶

If you must disable a ShellCheck rule:

1. Always add a comment explaining why
2. Prefer per-line disables over per-file
3. If the same disable appears in 3+ files, add it to .shellcheckrc instead

# shellcheck disable=SC2034  — Variable exported for use by sourced modules
local MY_VAR="value"

⚡ Performance Guidelines¶

The framework has strict performance targets:

📏 Rules¶

• 🚫 No network calls in startup path (hooks can defer)
• 🚫 No subprocess spawning unless absolutely necessary
• ✅ Use zsh builtins over external commands where possible
• ✅ Lazy-load heavy integrations (Docker, cloud CLIs)
• ✅ Cache results that don't change per-session
• ✅ Profile before and after with ZSHAND_PROFILE_BUNDLE=1

📊 Benchmarking a Change¶

# Before your change
hyperfine --warmup 3 'zsh -ic exit' --export-json before.json

# Make your change, rebuild
zprime

# After your change
hyperfine --warmup 3 'zsh -ic exit' --export-json after.json

# Compare (manual or via script)

📁 Adding a New File¶

Step-by-step¶

1. Choose the right directory (see ARCHITECTURE.md)
2. Pick the correct number prefix (even = framework, odd = user slot)
3. Write the header per HEADER_STANDARD.md
4. Implement the functionality
5. Write tests in the mirrored spec location
6. Run the quality gate (lint, test, benchmark)
7. Rebuild bundles with zprime
8. Verify with zcheck

🗂️ Example: Adding a new function¶

# 1. Create the function
vi functions/my_function.zsh

# 2. Write header (Standard tier for functions/)
#    Include: USAGE, DEPENDENCIES, EXIT CODES, EXAMPLES, TESTING, SEE ALSO

# 3. Create the spec
vi spec/functions/my_function_spec.sh

# 4. Verify
just test spec/functions/my_function_spec.sh
trunk check functions/my_function.zsh
zprime

🔗 Related Documents¶