stack/packages/cli-tools

@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.

# 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

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

List open issues in milestone

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

Create a pull request

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

Merge with squash

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

Monitor CI pipeline

# 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)
• 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:

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

# Lint with shellcheck (if installed)
pnpm lint