# Echelon

Consolidated CLI for DodaTech's internal development platform. Replaces per-project Bash tooling with a single globally-installed binary.

## Installation

```bash
npm install -g @dodatech/echelon
```

## Quick Start

```bash
# Initialize in an existing git repo
echelon init

# Start work on a GitHub issue
echelon forge start https://github.com/org/repo/issues/42

# Create a PR when done
echelon forge finish --classification ship

# Check status of all epics
echelon forge status

# Create a release
echelon forge release patch

# Validate setup
echelon doctor
```

## Commands

### Forge Workflow

| Command | Description |
|---------|-------------|
| `forge start <issue-url>` | Create branch from GitHub issue, push to remote |
| `forge finish` | Create PR with merge classification label |
| `forge status` | Show active epics and PR status |
| `forge release <patch\|minor\|major>` | Semantic version bump, annotated tag, push |
| `forge handoff` | Clean client-ready repo sync |

### Project Management

| Command | Description |
|---------|-------------|
| `init` | Initialize `.echelon/` config in current project |
| `doctor` | Validate project setup and dependencies |
| `migrate` | Migrate config/state from older formats |

### Common Flags

- `--json` — Machine-readable JSON output
- `--dry-run` — Preview without making changes (where applicable)
- `--verbose` / `-v` — Show verbose output

## Configuration

Echelon uses `.echelon/echelon.yaml` for project configuration:

```yaml
project:
  name: "My Project"

git:
  default_branch: main

forge:
  runtime:
    package_manager: pnpm
    test_command: "pnpm test"

  pr:
    default_classification: ask  # ship | show | ask

  handoff:
    target_repo: "https://github.com/client/repo.git"
    exclude_patterns:
      - "internal-docs/"
```

See `templates/echelon.yaml` for a full template with all options.

## Authentication

GitHub access uses this cascade (first match wins):

1. `GH_TOKEN` environment variable
2. `GITHUB_TOKEN` environment variable
3. `gh auth token` (GitHub CLI)

## Merge Classifications

PRs are labeled with merge intent:

- **ship** — merge immediately after CI passes
- **show** — ready for review, merge after approval
- **ask** — needs discussion before merging

## Migration

Coming from `.forge/` scripts or an older Echelon setup:

```bash
echelon migrate
```

This converts old config formats and state files to the current schema.

## Development

```bash
pnpm install
pnpm build
pnpm test
./bin/dev.js <command>
```

## License

Private — DodaTech internal use only.