# HarborForge.Cli

`HarborForge.Cli` is the Go-based `hf` binary for HarborForge.

## Build

```bash
go build -o ./bin/hf ./cmd/hf
```

To set the version at build time:

```bash
go build -ldflags "-X git.hangman-lab.top/zhi/HarborForge.Cli/internal/commands.Version=1.0.0" -o ./bin/hf ./cmd/hf
```

## Run

```bash
# Show help
./bin/hf --help

# Show only permitted commands
./bin/hf --help-brief

# Show version
./bin/hf version

# Check API health
./bin/hf health

# Configure API URL
./bin/hf config --url http://your-harborforge:8000

# View current config
./bin/hf config

# JSON output
./bin/hf version --json
```

## Package Layout

```text
cmd/hf/          CLI entrypoint
internal/
  client/        HTTP client wrapper for HarborForge API
  commands/      Command implementations
  config/        Config file resolution and management (.hf-config.json)
  help/          Help and help-brief renderer with detailed leaf help
  mode/          Runtime mode detection (padded-cell vs manual)
  output/        Output formatting (human-readable, JSON, tables)
  passmgr/       pass_mgr integration for secret resolution
```

## Runtime Modes

- **Padded-cell mode**: When `pass_mgr` is available, auth tokens are resolved automatically. Manual `--token` flags are rejected.
- **Manual mode**: When `pass_mgr` is not available, `--token` must be provided explicitly to authenticated commands.

## Current Status

### Implemented

**Foundation:**
- Go module and binary entrypoint
- Config file resolution relative to binary directory
- Runtime mode detection (`pass_mgr` present/absent)
- HTTP client wrapper (GET/POST/PUT/PATCH/DELETE)
- Output formatting (human-readable + `--json`)
- Auth token resolution (padded-cell + manual)

**Help system:**
- Top-level and group/leaf help rendering (`--help` / `--help-brief`)
- Permission-aware command visibility via `/auth/me/permissions`
- Detailed leaf help text for all commands, with padded-cell/manual auth flag differences
- `(not permitted)` rendering for unauthorized commands

**Core commands:**
- `hf version`, `hf health`, `hf config` (show / `--url` / `--acc-mgr-token`)

**Resource commands (all implemented with list/get/create/update/delete + special actions):**
- `hf user` — create, list, get, update, activate, deactivate, delete
- `hf role` — list, get, create, update, delete, set-permissions, add-permissions, remove-permissions
- `hf permission` — list
- `hf project` — list, get, create, update, delete, members, add-member, remove-member
- `hf milestone` — list, get, create, update, delete, progress
- `hf task` — list, get, create, update, transition, take, delete, search
- `hf meeting` — list, get, create, update, attend, delete
- `hf support` — list, get, create, update, take, transition, delete
- `hf propose` — list, get, create, update, accept, reject, reopen
- `hf monitor` — overview, server (list/get/create/delete), api-key (generate/revoke)

### Pending

- Backend code-based endpoint support (some commands still use id-based API routes)
- Comment and worklog commands
- Cross-platform binary packaging / release pipeline
- Integration tests