# Development Tools and Workflow

## Tools

### run.sh

`run.sh` is a convenience wrapper that builds (if needed) and runs a namespace.

Examples:
```bash
Omni/Ide/run.sh Omni/Task.hs     # Build and run task manager
Omni/Ide/run.sh Biz/PodcastItLater/Web.py  # Build and run web server
```

This script will:
1. Check if the binary exists in `_/bin/`
2. Build it if it doesn't exist (exits on build failure)
3. Execute the binary with any additional arguments

### lint

Universal lint and formatting tool. Errors if lints fail or code is not formatted properly.

Examples:
```bash
lint Omni/Cli.hs                 # Lint a namespace
lint --fix **/*.py               # Lint and fix all Python files
```

### repl.sh

Like `nix-shell` but specific to this repo. Analyzes the namespace, pulls dependencies, and starts a shell or repl.

Examples:
```bash
repl.sh Omni/Bild.hs            # Start Haskell repl with namespace loaded
repl.sh --bash Omni/Log.py      # Start bash shell for namespace
```

### typecheck.sh

Like `lint` but only runs type checkers. Currently just supports Python with `mypy`, but eventually will support everything that `bild` supports.

Examples:
```bash
typecheck.sh Omni/Bild/Example.py  # Run the typechecker and report any errors
```

### Test Commands

Run tests:
```bash
bild --test Omni/Task.hs         # Build and test a namespace
```

The convention for all programs in the omnirepo is to run their tests if the first argument is `test`. So for example:

```bash
# this will build a the latest executable and then run tests
bild --test Omni/Task.hs

# this will just run the tests from the existing executable
_/bin/task test
```

## Git Workflow

### Use git-branchless

This repository uses **git-branchless** for a patch-based workflow instead of traditional branch-based git.

Key concepts:
- Work with **patches** (commits) directly rather than branches
- Use **stacking** to organize related changes
- Leverage **smartlog** to visualize commit history

### Common git-branchless Commands

**View commit graph:**
```bash
git smartlog
```

**Create a new commit:**
```bash
# Make your changes
git add .
git commit -m "Your commit message"
```

**Amend the current commit:**
```bash
# Make additional changes
git add .
git amend
```

**Move/restack commits:**
```bash
git move -s <source> -d <destination>
git restack
```

### When to Record Changes in Git

**DO record in git:**
- Completed features or bug fixes
- Working code that passes tests and linting
- Significant milestones in task completion

**DO NOT record in git:**
- Work in progress (unless specifically requested)
- Broken or untested code
- Temporary debugging changes

**NEVER do these git operations without explicit user request:**
- ❌ `git push` - NEVER push to remote unless explicitly asked
- ❌ `git pull` - NEVER pull from remote unless explicitly asked
- ❌ Force pushes or destructive operations
- ❌ Branch deletion or remote branch operations

**Why:** The user maintains control over when code is shared with collaborators. Always ask before syncing with remote repositories.

### Workflow Best Practices

1. **Make small, focused commits** - Each commit should represent one logical change
2. **Write descriptive commit messages** - Explain what and why, not just what
3. **Rebase and clean up history** - Use `git commit --amend` and `git restack` to keep history clean
4. **Test before committing** - Run `bild --test` and `lint` on affected namespaces

### Required Checks Before Completing Tasks

After completing a task, **always** run these commands for the namespace(s) you modified:

```bash
# Run tests
bild --test Omni/YourNamespace.hs

# Run linter
lint Omni/YourNamespace.hs
```

**Fix all reported errors** related to your changes before marking the task as complete. This ensures code quality and prevents breaking the build for other contributors.