# @mosaic/cli-tools

CLI tools for Mosaic Stack orchestration - git operations and CI monitoring.

## Overview

These scripts provide unified interfaces for:

- **Git Operations**: Abstract differences between `tea` (Gitea CLI) and `gh` (GitHub CLI)
  - Issue management (create, list, assign, close, comment)
  - Pull request management (create, list, merge, review)
  - Milestone management (create, list, close)
- **CI Monitoring**: Woodpecker CI pipeline integration
  - Pipeline status checking
  - Log retrieval
  - Automated waiting for completion

## Installation

The package is part of the Mosaic Stack monorepo. After `pnpm install`, the commands are available in the monorepo context.

```bash
# From monorepo root
pnpm install

# Commands available via pnpm exec or npx
pnpm exec mosaic-issue-create -t "Title" -b "Body"
```

## Commands

### Issues

| Command                | Description                                 |
| ---------------------- | ------------------------------------------- |
| `mosaic-issue-create`  | Create a new issue                          |
| `mosaic-issue-list`    | List issues (with filters)                  |
| `mosaic-issue-view`    | View issue details                          |
| `mosaic-issue-assign`  | Assign issue to user                        |
| `mosaic-issue-edit`    | Edit issue (title, body, labels, milestone) |
| `mosaic-issue-close`   | Close an issue                              |
| `mosaic-issue-reopen`  | Reopen a closed issue                       |
| `mosaic-issue-comment` | Add comment to issue                        |

### Pull Requests

| Command            | Description           |
| ------------------ | --------------------- |
| `mosaic-pr-create` | Create a pull request |
| `mosaic-pr-list`   | List pull requests    |
| `mosaic-pr-view`   | View PR details       |
| `mosaic-pr-merge`  | Merge a pull request  |
| `mosaic-pr-review` | Review a pull request |
| `mosaic-pr-close`  | Close a pull request  |

### Milestones

| Command                   | Description        |
| ------------------------- | ------------------ |
| `mosaic-milestone-create` | Create a milestone |
| `mosaic-milestone-list`   | List milestones    |
| `mosaic-milestone-close`  | Close a milestone  |

### CI/CD (Woodpecker)

| Command                     | Description                          |
| --------------------------- | ------------------------------------ |
| `mosaic-ci-pipeline-status` | Check pipeline status (latest or #N) |
| `mosaic-ci-pipeline-logs`   | Fetch pipeline logs                  |
| `mosaic-ci-pipeline-wait`   | Wait for pipeline completion         |

## Usage Examples

### Create an issue with milestone

```bash
mosaic-issue-create \
  -t "Fix authentication bug" \
  -b "Users cannot log in when..." \
  -l "bug,security" \
  -m "M6-AgentOrchestration"
```

### List open issues in milestone

```bash
mosaic-issue-list -s open -m "M6-AgentOrchestration"
```

### Create a pull request

```bash
mosaic-pr-create \
  -t "Fix authentication bug" \
  -b "Resolves #123" \
  -B develop \
  -H fix/auth-bug
```

### Merge with squash

```bash
mosaic-pr-merge -n 42 -m squash -d
```

### Monitor CI pipeline

```bash
# Check latest pipeline status
mosaic-ci-pipeline-status --latest

# Wait for specific pipeline to complete
mosaic-ci-pipeline-wait -n 42

# Fetch logs on failure
mosaic-ci-pipeline-logs -n 42
```

## Platform Detection

The scripts automatically detect whether you're working with Gitea or GitHub by examining the git remote URL. No configuration needed.

- `git.mosaicstack.dev` → Gitea (uses `tea`)
- `github.com` → GitHub (uses `gh`)

## Requirements

### Git Operations

- **Gitea**: `tea` CLI installed and authenticated
- **GitHub**: `gh` CLI installed and authenticated
- **Both**: `git` available in PATH

### CI Monitoring (Woodpecker)

- `woodpecker` CLI installed ([installation guide](https://woodpecker-ci.org/docs/usage/cli))
- Environment variables set:
  - `WOODPECKER_SERVER` - Woodpecker server URL (e.g., `https://ci.mosaicstack.dev`)
  - `WOODPECKER_TOKEN` - API token from Woodpecker UI (User → Access tokens)

## For Orchestrators

When using these tools in orchestrator/worker contexts:

```bash
# In worker prompt, reference via pnpm exec
pnpm exec mosaic-issue-create -t "Title" -m "Milestone"

# Or add to PATH in orchestrator setup
export PATH="$PATH:./node_modules/.bin"
mosaic-issue-create -t "Title" -m "Milestone"
```

## Development

Scripts are plain bash - edit directly in `bin/`.

```bash
# Lint with shellcheck (if installed)
pnpm lint
```