Overview

Ever wished you could stack up version changes like a todo list and release them all at once? That's Sisyphus. It revolutionizes how you handle versioning in monorepos—no more juggling multiple PRs or manual version bumps.

✨ Why You'll Love It

• 🪨 Stack Your Changes - Create "stones" as you work, release when you're ready
• 🧞 Dependency Magic - Updates related packages automatically (it just knows!)
• 📝 Changelogs That Write Themselves - From commits to beautiful docs instantly
• 🚀 One Command to Rule Them All - Version, build, publish, tag - done!
• 🏷️ Alpha to Stable Pipeline - Smart prerelease promotion workflow
• 🎯 80KB of Excellence - Faster than your npm install
• 🔄 GitHub Native - Creates releases and tags automatically

🎬 See The Magic

$ sisyphus init
✔ Initialize Sisyphus in single or multi package mode? · multi
✔ Which packages should be ignored? · @internal/scripts
✔ Select a tag for releases · latest
✔ Enable commit configuration? · Yes
✔ Commit message template · chore(release): $\{message}
✔ Enable changelog generation? · Yes

✨ Sisyphus v0.3.42 is setup to roll stones.

$ sisyphus version
✔ Select packages for versioning:
  ◉ @myapp/auth
  ◉ @myapp/core
  ◯ @myapp/utils
✔ Select bump type · minor
✔ Provide a summary for these changes · Add OAuth2 authentication
✔ Are you sure you want to create this stone? · Yes

✓ Stone created: proud-mountain
   Location: .sisyphus/stones/proud-mountain.md

$ sisyphus check
🪨 Pending stones (2):

1. proud-mountain
   Created: 2 days ago
   Message: Add OAuth2 authentication

   Package changes:
   • @myapp/auth: 1.2.0 → 1.3.0 (minor)
   • @myapp/core: 2.1.0 → 2.1.1 (dependency)

2. gentle-river
   Created: today
   Message: Breaking API changes

   Package changes:
   • @myapp/api: 3.2.0 → 4.0.0 (major)
   • @myapp/cli: 1.0.0 → 2.0.0 (dependency)
   • @myapp/sdk: 2.5.0 → 3.0.0 (dependency)

Last release: v3.2.0 (1 week ago)
Ready to roll 5 packages with 2 stones

$ sisyphus roll --publish --github --changelog
🪨 Rolling stones...

Processing 2 stones:
  • proud-mountain
  • gentle-river

📦 Updating package versions:
  ✓ @myapp/auth: 1.2.0 → 1.3.0
  ✓ @myapp/core: 2.1.0 → 2.1.1
  ✓ @myapp/api: 3.2.0 → 4.0.0
  ✓ @myapp/cli: 1.0.0 → 2.0.0
  ✓ @myapp/sdk: 2.5.0 → 3.0.0

📝 Generating changelogs...
  ✓ Updated 5 CHANGELOG.md files
  ✓ Generated root CHANGELOG.md

🚀 Publishing to npm...
  ✓ Published 5 packages

🏷️ Creating git tags...
  ✓ Tagged 5 packages
  ✓ Created release tag: v4.0.0

🎆 GitHub release created: v4.0.0

✓ Cleaned up 2 stones
✅ Successfully rolled all stones!

📦 Installation

# Using Bun (recommended)
bun add -g @r5n/sisyphus
sisyphus --help

# Direct usage (no installation)
bunx @r5n/sisyphus --help

🚀 Quick Start

1. Initialize Sisyphus

# Interactive setup
sisyphus init

# Non-interactive with options
sisyphus init --nonInteractive --tag latest

2. Create Version Stones

# Interactive version creation
sisyphus version

# Quick version with commit message
sisyphus version "feat: add new feature" --packages @org/package-a:minor

# Specific version bump
sisyphus version --packages @org/core:major @org/utils:patch

3. Roll Stones (Release)

# Check pending releases
sisyphus check

# Release with all features
sisyphus roll --publish --github

# Dry run to preview
sisyphus roll --dry-run

📖 Commands

sisyphus init

Initialize Sisyphus in your project.

Options:

• -i, --ignore <packages> - Packages to ignore (multiple allowed)
• -n, --nonInteractive - Skip interactive prompts
• -o, --overwrite - Overwrite existing configuration
• -s, --single - Single package mode (non-monorepo)
• -t, --tag <tag> - Default release tag (default: "latest")

sisyphus version

Create a new version stone (changeset).

Options:

• -b, --bump <type> - Bump type (major/minor/patch)
• -d, --dryRun - Preview changes without creating stone
• -f, --filter <string> - Filter packages by name
• -s, --snapshot - Create snapshot versions
• -t, --tag <tag> - Release tag (e.g., "beta", "alpha")
• -y, --yes - Skip confirmation prompt

Examples:

# Create stone interactively
sisyphus version

# Create stone with specific bump
sisyphus version --bump minor --filter @org/core

# Snapshot release
sisyphus version --snapshot --tag dev

# Skip confirmation
sisyphus version --yes

sisyphus roll

Process stones and release packages.

Options:

• -c, --changelog - Generate changelog
• -d, --dryRun - Preview release without publishing
• -g, --github - Create GitHub releases
• -n, --npm - Publish to npm
• -r, --changelogRoot - Generate root changelog
• -t, --withTags - Create git tags
• --githubToken <token> - GitHub authentication token
• --npmToken <token> - NPM authentication token
• --rootTag <tag> - Root package tag

sisyphus check

Check current stones and package states.

Options:

• --debug - Show debug information
• --json - Output in JSON format

Output includes:

• Pending stones with version changes
• Affected packages
• Dependency updates
• Last release information

sisyphus preview

Preview what versions will be after rolling stones.

Options:

• -j, --json - Output in JSON format
• -v, --verbose - Show additional information

sisyphus prerelease

Manage prerelease versions (alpha, beta, rc).

Options:

• -t, --type <type> - Prerelease type (alpha/beta/rc/canary/dev/next)
• -b, --bump <type> - Bump type (major/minor/patch)
• -p, --promote - Promote existing prereleases (interactive UI)
• -f, --filter <string> - Filter packages
• -d, --dryRun - Preview changes
• -y, --yes - Skip confirmation

Promotion Flow:

• Alpha → Beta, RC, or Stable
• Beta → RC or Stable
• RC/Next → Stable only

Examples:

# Create beta prerelease
sisyphus prerelease --type beta --bump minor

# Promote prereleases (shows smart options)
sisyphus prerelease --promote

# Non-interactive prerelease
sisyphus prerelease --type alpha --bump patch --filter @org/core --yes

sisyphus stone

Manage pending stones.

Subcommands:

• list - View all pending stones
• show <id> - Display stone content
• delete <id> - Remove a stone
• edit <id> - Modify stone message
• merge - Combine multiple stones

sisyphus graph

Visualize monorepo package dependencies.

Options:

• -j, --json - Output in JSON format
• -f, --filter <string> - Filter to specific package
• -d, --depth <number> - Limit depth of dependency tree
• -v, --show-versions - Display package versions

Examples:

# Show full dependency graph
sisyphus graph

# Focus on specific package
sisyphus graph --filter @org/core

# Export as JSON
sisyphus graph --json > dependencies.json

sisyphus help

Show help information for commands.

sisyphus help
sisyphus help version
sisyphus version --help

🔧 Configuration

Why Stones? 🤔

Traditional versioning forces you to release immediately or lose track of changes. Stones change everything:

Monday:    "Fixed auth bug"        → 🪨 Create stone
Tuesday:   "Added user profiles"   → 🪨 Create stone
Wednesday: "Optimized database"    → 🪨 Create stone
Thursday:  "Ready to ship!"        → 🎯 Roll all stones!

Benefits:

• ✅ Stack changes throughout the week
• ✅ Review everything before release
• ✅ Coordinate multi-package updates
• ✅ Never lose track of what needs releasing
• ✅ Git-friendly (stones are just markdown files)

Configuration File

Sisyphus uses .sisyphus/config.json:

{
  "$schema": "https://raw.githubusercontent.com/r5n-labs/clis/main/packages/sisyphus/schema.json",
  "tag": "latest",
  "ignore": ["packages/*-internal"],
  "single": false,
  "commit": {
    "message": "chore(release): ${message}",
    "author": "Sisyphus Bot",
    "email": "[email protected]"
  },
  "release": {
    "github": true,
    "npm": true,
    "tags": true
  },
  "changelog": {
    "generate": true,
    "includeCommits": true
  }
}

Stone File Format

Stones are stored in .sisyphus/stones/:

### feat: add authentication system

This adds OAuth2 support and improves security.

---

|   minor   |        patch        |
| :-------: | :-----------------: |
| @org/auth | @org/core, @org/api |

📂 Project Structure

your-project/
├── .sisyphus/
│   ├── config.json         # Sisyphus configuration
│   └── stones/             # Pending version changes
│       ├── feat-auth.md
│       └── fix-memory.md
├── packages/
│   ├── core/
│   │   ├── package.json
│   │   └── CHANGELOG.md    # Auto-generated
│   └── auth/
│       ├── package.json
│       └── CHANGELOG.md
└── CHANGELOG.md            # Root changelog (optional)

🏗️ Architecture

Technology Stack

• Runtime: Bun (optimized for performance)
• Validation: Banditypes (lightweight schemas)
• CLI Framework: Custom with @clack/prompts
• Bundle: Fully self-contained with zero runtime dependencies

How It Works

1. Stone Creation: Captures version intent without modifying files
2. Dependency Resolution: Analyzes workspace dependencies
3. Version Calculation: Determines final versions from all stones
4. Release Pipeline: Updates files, builds, publishes, and tags
5. Cleanup: Removes processed stones after success

📊 Examples

Monorepo Release Flow

# Monday: Feature development
sisyphus version --bump minor --filter @app/core

# Tuesday: Bug fix
sisyphus version --bump patch --filter @app/auth

# Wednesday: Breaking change
sisyphus version --bump major --filter @app/api

# Friday: Release everything
sisyphus check  # Review pending changes
sisyphus roll --npm --github --changelog

Prerelease Workflow

# Create beta versions
sisyphus version --bump minor --filter @org/new-feature --tag beta

# Roll beta release
sisyphus roll --npm

# Later, promote to stable
sisyphus version --bump minor --filter @org/new-feature --tag latest
sisyphus roll --npm

CI/CD Integration

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.head_ref }}
      - uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install

      - name: Check for stones
        id: check
        run: |
          if [ -d ".sisyphus/stones" ] && [ "$(ls -A .sisyphus/stones)" ]; then
            echo "has_stones=true" >> $GITHUB_OUTPUT
          fi

      - name: Release
        if: steps.check.outputs.has_stones == 'true'
        run: bunx @r5n/sisyphus roll --npm --github --changelog
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

🔐 Security

Token Management

• NPM Publishing: Requires NPM_TOKEN or --npmToken
• GitHub Releases: Requires GITHUB_TOKEN or --githubToken
• Tokens are never stored in configuration
• Use environment variables in CI/CD

Best Practices

1. Review stones before rolling (sisyphus check)
2. Use dry-run mode for safety
3. Commit stones to version control
4. Set up branch protection for release branches

🐛 Troubleshooting

Common Issues

1. "No stones found"

   • Create stones with sisyphus version first
   • Check .sisyphus/stones/ directory

2. "Package not found"

   • Verify package name in version command
   • Check if package is ignored in config

3. "Publish failed"

   • Verify NPM token permissions
   • Check if version already exists
   • Ensure package.json has required fields

Debug Mode

# Verbose logging
DEBUG=* sisyphus roll --dry-run

# Check configuration
cat .sisyphus/config.json

# Inspect stones
ls -la .sisyphus/stones/

🤝 Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.