# @mosaic/cli-tools

CLI tools for Mosaic Stack orchestration - git operations that work with both Gitea and GitHub.

## Overview

These scripts abstract the differences between `tea` (Gitea CLI) and `gh` (GitHub CLI), providing a unified interface for:

- Issue management (create, list, assign, close, comment)
- Pull request management (create, list, merge, review)
- Milestone management (create, list, close)

## 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  |

## 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
```

## 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

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

## 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
```