# gh-auto-agent — Usage & Testing Guide

> How to install, configure, run, and test the agent — with every command documented.

---

## Table of Contents

1. [Prerequisites](#1-prerequisites)
2. [Installation](#2-installation)
3. [Configuration (optional AI)](#3-configuration-optional-ai)
4. [Quick Start](#4-quick-start)
5. [Command Reference](#5-command-reference)
6. [Testing the Program](#6-testing-the-program)
7. [Troubleshooting](#7-troubleshooting)

---

## 1. Prerequisites

| Tool | Version | Check | Install |
|---|---|---|---|
| Node.js | ≥ 18 | `node --version` | https://nodejs.org |
| Git | any recent | `git --version` | https://git-scm.com |
| GitHub CLI | ≥ 2.0 | `gh --version` | https://cli.github.com |

You must be authenticated with GitHub CLI:

```powershell
gh auth status      # should show "Logged in to github.com"
# if not:
gh auth login
```

---

## 2. Installation

```powershell
cd "path\to\gh-auto-agent"

# Option A — install globally so `agent` is on your PATH
npm link
agent help

# Option B — run directly without installing
node index.js help
```

> In the examples below, `agent <cmd>` and `node index.js <cmd>` are
> interchangeable.

---

## 3. Configuration (optional AI)

AI is **off by default**. The agent works fully in static mode without it.
To enable AI reasoning for unknown failures, smart commit messages, and PR
descriptions, configure one provider.

### Easiest — a `.env` file

```powershell
Copy-Item .env.example .env
notepad .env        # uncomment ONE provider line
```

Example `.env`:
```env
GITHUB_TOKEN=ghp_xxxxxxxxxxxx        # GitHub Models (free for GitHub users)
# or OPENAI_API_KEY=sk-...
# or AGENT_AI_PROVIDER=ollama        # local model, no key
```

### Or export in your shell (PowerShell)

```powershell
$env:OPENAI_API_KEY = "sk-..."
# or
$env:GITHUB_TOKEN = "ghp_..."
```

### Verify

```powershell
agent ai
# ✔ Active: github (gpt-4o-mini)     ← AI enabled
# ⚠ No AI provider configured...     ← static mode (still fully functional)
```

**Provider precedence:** real shell environment variables always override `.env`.
**Search order for `.env`:** `$AGENT_ENV_FILE` → `./.env` → install-dir `.env`.

---

## 4. Quick Start

```powershell
# See everything the agent can do
agent help

# Inspect the current repo (read-only, safe)
agent status

# Check AI provider status
agent ai

# Bootstrap a brand-new project
agent init my-app

# Ship your changes (branch → commit → push → PR → merge)
agent ship "feat: add feature"

# Fix anything broken in the repo
agent fix
```

---

## 5. Command Reference

### 🧠 Smart Commands

#### `agent init [name]`
Bootstrap a project. Uses native `gh` for repo + README + `.gitignore` + license,
then adds a language-aware CI workflow.

| Flag | Description |
|---|---|
| `--template <t>` | Force language: `node`, `python`, `dotnet`, `go`, `rust` |
| `--public` | Create a public repo (default: private) |

```powershell
agent init my-app
agent init api --template node --public
```

---

#### `agent ship [message]`
From a dirty working tree to a merged PR in one command.

Steps: create feature branch (if on main) → commit (AI message if enabled) →
push → create PR (AI description) → wait for CI → auto-merge → return to main.

| Flag | Description |
|---|---|
| `--draft` | Create the PR as a draft, skip merge |
| `--no-merge` | Create the PR but don't auto-merge |

```powershell
agent ship "feat: add authentication"
agent ship --draft
agent ship "fix: null check" --no-merge
```

---

#### `agent fix`
Scans the repo for issues (failing CI, PR conflicts, missing CI config, behind
upstream, working-tree conflicts) and fixes them autonomously.

```powershell
agent fix
```

---

#### `agent heal [--dry-run]`
Deep health scan + repair: failed runs (with AI root-cause), stale merged
branches, conflicted PRs, missing configs, and basic security checks.

| Flag | Description |
|---|---|
| `--dry-run` | Show what would be fixed without applying changes |

```powershell
agent heal --dry-run        # preview
agent heal                  # apply fixes
```

---

#### `agent watch`
Continuously monitors workflow runs and auto-fixes failures as they happen.

| Flag | Description |
|---|---|
| `--interval <sec>` | Poll interval in seconds (default: 30) |
| `--once` | Run a single check cycle and exit |

```powershell
agent watch
agent watch --interval 60
agent watch --once
```

---

#### `agent deploy [env]`
Full deployment pipeline with rollback safety: switch to main → run tests →
bump version → tag → GitHub release → monitor → auto-rollback on failure.

| Flag | Description |
|---|---|
| `--tag <version>` | Release tag (auto-bumps patch if omitted) |
| `--rollback` | Revert the last deployment |

```powershell
agent deploy production
agent deploy staging --tag v2.1.0
agent deploy --rollback
```

---

### 🔧 Pipeline Commands

Define multi-step workflows in YAML (`.agent/pipelines/*.yml`). Each step
auto-heals on failure.

```powershell
agent pipeline create release      # scaffold a template
agent pipeline run release.yml     # execute it
agent pipeline list                # list available pipelines
```

Example pipeline:
```yaml
name: release
steps:
  - name: Run tests
    run: npm test
  - name: Push
    action: push
    with:
      message: "chore: release"
  - name: Create PR
    action: pr-create
    with:
      title: "Release"
  - name: Merge
    action: pr-merge
```

---

### 👥 Team Commands

```powershell
agent team setup       # create labels, config rules, CODEOWNERS
agent team assign      # auto-assign reviewers to open PRs by changed paths
agent team label       # auto-label PRs (by file type + size S/M/L/XL)
```

Configuration is stored in `.agent/team.json`.

---

### 🔍 Info Commands

```powershell
agent status           # full project health dashboard (read-only)
agent ai               # AI provider status + setup help
agent state show       # current agent execution state (JSON)
agent state reset      # clear agent state
agent help             # full command reference
```

---

## 6. Testing the Program

There are three levels — from instant/safe to full end-to-end.

### Level 1 — Unit tests (offline, no side effects)

```powershell
npm test
```

Runs 91 tests covering the parser, state manager, YAML parser, AI config
detection, command safety filter, and `.env` loader. Touches nothing on GitHub.

Expected output ends with:
```
  Passed: 91
  Failed: 0
  Total:  91
```

### Level 2 — Read-only commands (safe)

These call `gh`/`git` to read state but never write:

```powershell
node index.js help
node index.js ai
node index.js status        # live dashboard of the current repo
node index.js state show
```

### Level 3 — End-to-end (creates a throwaway repo)

The real test. Create a disposable repo, exercise the agent, then delete it.

```powershell
# 1. Scratch folder OUTSIDE this project
cd $env:TEMP
mkdir agent-test-repo; cd agent-test-repo

# 2. Add a tiny project so language detection works
'{ "name": "agent-test", "version": "1.0.0", "scripts": { "test": "echo ok" } }' |
  Out-File package.json -Encoding utf8

# 3. Bootstrap (repo + README + .gitignore + license + CI)
$AGENT = "C:\Users\v-ttetali\MyWorkspace\projects\agent cli\gh-auto-agent\index.js"
node $AGENT init agent-test-repo

# 4. Make a change and ship it end-to-end
'console.log("hello")' | Out-File app.js -Encoding utf8
node $AGENT ship "feat: add entrypoint"

# 5. Inspect and self-heal
node $AGENT status
node $AGENT fix
```

**Cleanup:**
```powershell
gh repo delete TarunReddy/agent-test-repo --yes
cd ..; Remove-Item agent-test-repo -Recurse -Force
```

### Level 4 — Test AI features

With a provider configured (`agent ai` shows "Active"):

- `agent ship` → commit messages and PR bodies are AI-generated from the diff
- Break the CI on purpose (e.g. a failing test), then `agent fix` → AI diagnoses
  the root cause and applies a safe fix
- `agent heal` → shows AI root-cause analysis in the health report

---

## 7. Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `gh: command not found` | GitHub CLI not installed | Install from https://cli.github.com |
| Auth errors on every command | Not logged in | `gh auth login` |
| `agent ai` shows "No AI provider" | No key configured | Add a key to `.env` or export it |
| AI suggests nothing / "no safe command" | Low confidence or destructive command blocked | Expected — safety filter; fix manually |
| Workflow run ID not found | Run hasn't started yet | The agent waits/polls; retry the command |
| `.env` not picked up | Wrong location | Place it in the cwd, or set `$AGENT_ENV_FILE` |
| Force-push blocked | Safety design | The agent uses `--force-with-lease` only |

### Useful diagnostics

```powershell
node index.js state show     # see last task, retry count, history
gh auth status               # verify GitHub auth
gh run list --limit 5        # see recent workflow runs
Get-Content .gh-auto-agent-state.json   # raw agent state
```

Per-run logs are written to `logs/github/{runId}.log` with the command, output,
detected error, and fix applied.

---

*See [HOW-IT-WORKS.md](./HOW-IT-WORKS.md) for architecture and design philosophy.*