Jason Woltje
ec87c5479b
- Add ci-pipeline-status.sh for checking pipeline status - Add ci-pipeline-logs.sh for fetching logs - Add ci-pipeline-wait.sh for waiting on completion - Update package.json bin section - Update README with CI commands and examples Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
162 lines
4.5 KiB
Markdown
162 lines
4.5 KiB
Markdown
# @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
|
|
```
|