npm package: @r5n/sisyphus
Description: Sisyphus CLI - A tool for versioning and publishing packages
Author: @ice-chillios
Latest version: 0.4.8

<div align="center">
  <a href="https://github.com/r5n-labs">
    <img src="https://avatars.githubusercontent.com/u/99986752?s=400&v=4" alt="R5N Labs" width="100" height="100">
  </a>

  <p><strong>Version Control That Actually Makes Sense 🪨</strong></p>
  <p><em>🪨 Because versioning shouldn't feel like pushing a boulder uphill</em></p>

  <h1>Sisyphus</h1>

  <p>
    <a href="https://www.npmjs.com/package/@r5n/sisyphus">
      <img src="https://img.shields.io/npm/v/@r5n/sisyphus.svg" alt="npm version">
    </a>
    <a href="https://github.com/r5n-labs/clis/blob/main/packages/sisyphus/LICENSE">
      <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License">
    </a>
    <img src="https://img.shields.io/badge/bundle%20size-~80KB-green.svg" alt="Bundle Size">
  </p>
</div>

---

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

<details>
<summary><strong>The stone system in action</strong></summary>

```bash
$ 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
```
</details>

<details>
<summary><strong>Smart dependency tracking</strong></summary>

```bash
$ 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
```
</details>

<details>
<summary><strong>One command release</strong></summary>

```bash
$ 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!
```
</details>

## 📦 Installation

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

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

## 🚀 Quick Start

### 1. Initialize Sisyphus

```bash
# Interactive setup
sisyphus init

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

### 2. Create Version Stones

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

```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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.

```bash
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`:

```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": "bot@example.com"
  },
  "release": {
    "github": true,
    "npm": true,
    "tags": true
  },
  "changelog": {
    "generate": true,
    "includeCommits": true
  }
}
```

### Stone File Format

Stones are stored in `.sisyphus/stones/`:

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

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

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

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

```bash
# 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](https://github.com/r5n-labs/clis) for contribution guidelines.

## 📄 License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

---