ralph-cli 2.2.0__tar.gz

ralph_cli-2.2.0/.editorconfig

@@ -0,0 +1,22 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+[*.{json,yaml,yml,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

ralph_cli-2.2.0/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  # Python dependencies (uv/pip ecosystem)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "pytest*"
+          - "ruff"
+          - "pyright"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(ci)"

ralph_cli-2.2.0/.github/workflows/ci.yml

@@ -0,0 +1,141 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Extract version from pyproject.toml
+        id: pyproject
+        run: |
+          version=$(python3 -c "
+          import re, pathlib
+          text = pathlib.Path('pyproject.toml').read_text()
+          m = re.search(r'^version\s*=\s*\"([^\"]+)\"', text, re.MULTILINE)
+          print(m.group(1) if m else '')
+          ")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Extract version from __init__.py
+        id: init
+        run: |
+          version=$(python3 -c "
+          import re, pathlib
+          text = pathlib.Path('src/ralph/__init__.py').read_text()
+          m = re.search(r'^__version__\s*=\s*\"([^\"]+)\"', text, re.MULTILINE)
+          print(m.group(1) if m else '')
+          ")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Check CHANGELOG.md contains version entry
+        id: changelog
+        run: |
+          version="${{ steps.pyproject.outputs.version }}"
+          if grep -qF "## [$version]" CHANGELOG.md; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Verify version consistency
+        run: |
+          pyproject="${{ steps.pyproject.outputs.version }}"
+          init="${{ steps.init.outputs.version }}"
+          changelog="${{ steps.changelog.outputs.found }}"
+          errors=0
+
+          if [ -z "$pyproject" ]; then
+            echo "::error file=pyproject.toml::Could not extract version from pyproject.toml"
+            errors=1
+          fi
+
+          if [ "$pyproject" != "$init" ]; then
+            echo "::error file=src/ralph/__init__.py::Version mismatch: pyproject.toml has '$pyproject' but __init__.py has '$init'"
+            errors=1
+          fi
+
+          if [ "$changelog" != "true" ]; then
+            echo "::error file=CHANGELOG.md::CHANGELOG.md is missing an entry for version '$pyproject' (expected '## [$pyproject]')"
+            errors=1
+          fi
+
+          if [ "$errors" -ne 0 ]; then
+            echo ""
+            echo "Version consistency check failed. Ensure these files agree:"
+            echo "  - pyproject.toml  version = \"$pyproject\""
+            echo "  - src/ralph/__init__.py  __version__ = \"$init\""
+            echo "  - CHANGELOG.md   ## [$pyproject]  ($changelog)"
+            exit 1
+          fi
+
+          echo "Version consistency check passed: $pyproject"
+
+      - name: Verify tag matches pyproject.toml version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag="${GITHUB_REF#refs/tags/v}"
+          pyproject="${{ steps.pyproject.outputs.version }}"
+
+          if [ "$tag" != "$pyproject" ]; then
+            echo "::error::Git tag 'v$tag' does not match pyproject.toml version '$pyproject'"
+            exit 1
+          fi
+
+          echo "Tag validation passed: v$tag matches pyproject.toml version $pyproject"
+
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.26"
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run type checking
+        run: uv run pyright
+
+      - name: Run linting
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest --cov=ralph --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v5
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

ralph_cli-2.2.0/.github/workflows/publish.yml

@@ -0,0 +1,178 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  id-token: write
+  contents: write
+
+jobs:
+  ci-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Wait for CI workflow to succeed
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          commit_sha="${GITHUB_SHA}"
+          repo="${GITHUB_REPOSITORY}"
+          workflow_name="CI"
+          max_attempts=30
+          wait_seconds=30
+
+          echo "Checking CI workflow status for commit ${commit_sha}..."
+
+          for attempt in $(seq 1 "$max_attempts"); do
+            # Query CI workflow runs for this exact commit
+            run_data=$(gh api "repos/${repo}/actions/workflows/ci.yml/runs?head_sha=${commit_sha}&per_page=1" \
+              --jq '.workflow_runs[0] // empty')
+
+            if [ -z "$run_data" ]; then
+              if [ "$attempt" -eq "$max_attempts" ]; then
+                echo "::error::CI workflow has not run for commit ${commit_sha}. Ensure CI is triggered before publishing."
+                exit 1
+              fi
+              echo "Attempt ${attempt}/${max_attempts}: CI workflow not found yet. Waiting ${wait_seconds}s..."
+              sleep "$wait_seconds"
+              continue
+            fi
+
+            status=$(echo "$run_data" | jq -r '.status')
+            conclusion=$(echo "$run_data" | jq -r '.conclusion')
+            run_url=$(echo "$run_data" | jq -r '.html_url')
+
+            echo "CI run: status=${status}, conclusion=${conclusion}"
+            echo "  URL: ${run_url}"
+
+            if [ "$status" = "completed" ]; then
+              if [ "$conclusion" = "success" ]; then
+                echo "CI workflow passed for commit ${commit_sha}."
+                exit 0
+              else
+                echo "::error::CI workflow failed for commit ${commit_sha} (conclusion: ${conclusion}). See: ${run_url}"
+                exit 1
+              fi
+            fi
+
+            if [ "$attempt" -eq "$max_attempts" ]; then
+              echo "::error::CI workflow still running after $((max_attempts * wait_seconds))s. See: ${run_url}"
+              exit 1
+            fi
+
+            echo "Attempt ${attempt}/${max_attempts}: CI still running (status=${status}). Waiting ${wait_seconds}s..."
+            sleep "$wait_seconds"
+          done
+
+  build:
+    needs: ci-check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7
+        with:
+          version: "0.9.26"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/ralph-cli
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    needs: testpypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ralph-cli
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+
+  release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract release notes from CHANGELOG.md
+        id: notes
+        run: |
+          version="${{ steps.version.outputs.version }}"
+          # Extract content between this version header and the next version header
+          awk "/^## \\[${version}\\]/{found=1; next} /^## \\[/{if(found) exit} found{print}" CHANGELOG.md > release_notes.txt
+          # Remove leading/trailing blank lines
+          sed -i '/./,$!d' release_notes.txt
+          sed -i -e :a -e '/^\n*$/{$d;N;ba' -e '}' release_notes.txt
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Determine pre-release flag
+        id: prerelease
+        run: |
+          version="${{ steps.version.outputs.version }}"
+          if echo "$version" | grep -qE '(a|b|rc|dev|alpha|beta|pre)'; then
+            echo "flag=--prerelease" >> "$GITHUB_OUTPUT"
+          else
+            echo "flag=--latest" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --notes-file release_notes.txt \
+            ${{ steps.prerelease.outputs.flag }} \
+            dist/*

ralph_cli-2.2.0/.github/workflows/security.yml

@@ -0,0 +1,35 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Run weekly on Monday at 00:00 UTC
+    - cron: "0 0 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  codeql:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: security-and-quality
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:python"

ralph_cli-2.2.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Type checking
+.pyright/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Ruff
+.ruff_cache/

ralph_cli-2.2.0/AGENTS.md

@@ -0,0 +1,154 @@
+# Agent Instructions
+
+## Overview
+
+Ralph CLI - A Python CLI tool that implements the Ralph autonomous iteration pattern for Claude Code. This project wraps the entire autonomous coding workflow with proper project structure, intuitive commands, and a polished terminal experience.
+
+## Ralph Workflow
+
+**Key files:**
+- `plans/SPEC.md` - Feature specification
+- `plans/TASKS.json` - Task list with completion status
+- `plans/PROGRESS.txt` - Append-only iteration log
+
+**Iteration process:**
+1. Read `plans/TASKS.json` and pick highest-priority incomplete story
+2. Read `plans/PROGRESS.txt` for context and patterns
+3. Implement the story following acceptance criteria
+4. Run quality checks defined in `CLAUDE.md`
+5. Commit on success: `feat: [Story ID] - [Story Title]`
+6. Update TASKS.json (`passes: true`) and append to PROGRESS.txt
+7. Update CLAUDE.md and AGENTS.md with discovered patterns
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|------------|
+| Language | Python 3.11+ |
+| CLI Framework | Typer |
+| Terminal UI | Rich |
+| Data Validation | Pydantic |
+| Package Management | uv |
+| Linting/Formatting | ruff |
+| Type Checking | pyright |
+| Testing | pytest |
+
+## Project Structure
+
+```
+ralph_cli/
+├── pyproject.toml
+├── README.md
+├── CLAUDE.md
+├── AGENTS.md
+├── plans/
+│   ├── SPEC.md
+│   ├── TASKS.json
+│   └── PROGRESS.txt
+├── src/
+│   └── ralph/
+│       ├── __init__.py
+│       ├── cli.py              # Typer app, command definitions
+│       ├── commands/           # Command implementations
+│       ├── models/             # Pydantic models
+│       ├── services/           # Business logic (Claude, Git, etc.)
+│       ├── skills/             # Bundled skill definitions (packaged)
+│       │   ├── ralph/          # Core workflow skills
+│       │   │   ├── iteration/
+│       │   │   ├── prd/
+│       │   │   └── tasks/
+│       │   └── reviewers/      # Review pipeline skills
+│       │       ├── code_simplifier/
+│       │       ├── github_actions/
+│       │       ├── language/
+│       │       │   ├── bicep/
+│       │       │   └── python/
+│       │       ├── release/
+│       │       ├── repo_structure/
+│       │       └── test_quality/
+│       └── utils/              # Console and file utilities
+└── tests/
+```
+
+**Note:** Skills are bundled with the package for immediate use after `pip install ralph-cli`. Use `ralph sync` to copy them to `~/.claude/skills/` for native Claude Code integration.
+
+## Codebase Patterns
+
+(Keep in sync with CLAUDE.md)
+
+- Use Pydantic `BaseModel` for all classes, NOT stdlib `@dataclass` - this is a Pydantic project
+- Use `ConfigDict(arbitrary_types_allowed=True)` when fields use types like `Path` or `TextIO`
+- Use Pydantic `alias` with `populate_by_name=True` when JSON uses camelCase but Python should use snake_case
+- Use `by_alias=True` in `model_dump_json()` to serialize back to the original JSON format
+- Import `Iterator`, `Sequence`, etc. from `collections.abc` instead of `typing` (ruff UP035)
+- Use `X | None` instead of `Optional[X]` for type annotations (ruff UP045)
+- Use `ClassVar[T]` from `typing` for class-level constants in Pydantic `BaseModel` classes to avoid them being treated as fields
+- When calling Typer command functions directly (not through CLI), pass all Option parameters explicitly since Typer defaults are not applied programmatically
+- **Prompt construction**: Use `@filepath` notation with `build_skill_prompt()` to reference bundled skill files directly, reducing token usage. The function uses `SkillLoader.get_path()` to get the actual filesystem path to SKILL.md files. Example: `build_skill_prompt("ralph/prd", context)` produces `@/path/to/skills/ralph/prd/SKILL.md`
+
+## Project-Specific Instructions
+
+### Commands
+
+The CLI provides these commands:
+- `ralph init` - Scaffold a project for Ralph workflow
+- `ralph prd` - Interactive PRD creation with Claude
+- `ralph tasks <spec>` - Convert spec to TASKS.json
+- `ralph once` - Execute single iteration
+- `ralph loop [n]` - Run n iterations (default: 10)
+- `ralph review` - Run the review pipeline with automatic configuration
+- `ralph sync` - Sync skills to ~/.claude/skills/
+
+### Key Design Decisions
+
+1. **Subprocess for Claude Code**: Invoke `claude` CLI via subprocess, not as a library
+2. **Streaming output**: Default shows text output; `--verbose` shows full JSON
+3. **Branch management**: Auto-create/checkout branches from TASKS.json branchName
+4. **Memory system**: PROGRESS.txt is append-only; CLAUDE.md/AGENTS.md get pattern updates
+
+### Linear Integration
+
+This project tracks work in [Linear](https://linear.app/jmcptest) under the **Ralph CLI** team (identifier: `RAL`).
+
+**Hierarchy:** Project (release) > Parent Issue (feature/epic) > Sub-issue (user story)
+
+**GitHub integration is configured with:**
+- **Branch/PR linking** — PRs referencing `RAL-XX` identifiers auto-link to Linear issues
+- **Magic words** — Commits with `RAL-XX` get linked via webhook
+- **Public repo linkbacks** — Linear adds comments on linked GitHub PRs
+- **Bidirectional GitHub Issues sync** — Issues sync between `jackemcpherson/ralph-cli` and the Ralph CLI team (note: syncs new activity, does not back-import existing issues)
+
+**When creating PRs:**
+- Reference Linear identifiers in the PR body (e.g., `RAL-1`, `RAL-15`) for automatic linking
+- Use `Closes #XX` for GitHub issues to auto-close on merge
+- Linear issues should be updated to Done when their stories pass
+
+**When completing a feature branch:**
+1. Mark all completed stories as Done in Linear
+2. Mark parent issues as Done when all sub-issues complete
+3. Update the Linear project status to Completed after release
+
+### Release Process
+
+When merging a release PR:
+1. Update version in `pyproject.toml` and `src/ralph/__init__.py`
+2. Add changelog entry to `CHANGELOG.md`
+3. Merge the PR to main
+4. Create and push a git tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
+5. Create a GitHub Release from the tag with notes from CHANGELOG.md
+6. Update the Linear project description (link to release) and set status to Completed
+7. Clean up local and remote feature branches: `git branch -d <branch> && git fetch --prune`
+
+Tags must match the version in pyproject.toml (e.g., `v1.2.6` for version `1.2.6`).
+
+### File Formats
+
+**TASKS.json schema:**
+- `project`: string
+- `branchName`: string (e.g., "ralph/feature-name")
+- `description`: string
+- `userStories`: array of {id, title, description, acceptanceCriteria[], priority, passes, notes}
+
+**Quality checks in CLAUDE.md:**
+- Parsed from YAML between `<!-- RALPH:CHECKS:START -->` and `<!-- RALPH:CHECKS:END -->`
+- Each check has: name, command, required (boolean)