wade-cli 0.0.1__tar.gz → 0.0.2__tar.gz

wade_cli-0.0.2/.claude/settings.local.json

@@ -0,0 +1,37 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run:*)",
+      "Bash(git:*)",
+      "Bash(chmod +x:*)",
+      "Bash(bash:*)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(python3:*)",
+      "Bash(find:*)",
+      "WebSearch",
+      "WebFetch(domain:opencode.ai)",
+      "WebFetch(domain:github.com)",
+      "Bash(python:*)",
+      "Bash(uv pip:*)",
+      "Bash(codex:*)",
+      "Bash(copilot:*)",
+      "Bash(gh api:*)",
+      "Bash(gh issue:*)",
+      "Bash(gh pr:*)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(.venv/bin/mypy:*)",
+      "Bash(.venv/bin/ruff:*)",
+      "Bash(./scripts/check.sh:*)",
+      "Bash(./scripts/test.sh:*)",
+      "Bash(./scripts/fmt.sh:*)",
+      "Bash(./scripts/check-all.sh:*)",
+      "Bash(xargs cat:*)",
+      "Bash(uv build:*)",
+      "Bash(wade implement-task:*)",
+      "Bash(wade work:*)",
+      "Bash(wade plan-task:*)",
+      "Bash(gh run:*)"
+    ]
+  }
+}

wade_cli-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Lint with ruff
+        run: uv run ruff check src/ tests/
+      - name: Format check with ruff
+        run: uv run ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Type check with mypy
+        run: uv run mypy src/ --strict
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Configure git
+        run: |
+          git config --global user.email "test@wade.dev"
+          git config --global user.name "wade test"
+          git config --global init.defaultBranch main
+      - name: Run unit tests
+        run: uv run pytest tests/unit/ -v --tb=short
+      - name: Run integration tests
+        run: uv run pytest tests/integration/ -v --tb=short
+
+  test-live:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: [test]
+    env:
+      RUN_LIVE_GH_TESTS: "1"
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Install gh CLI
+        run: |
+          type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
+          curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+          sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+          sudo apt update && sudo apt install gh -y
+      - name: Run live tests
+        if: env.GH_TOKEN != ''
+        run: uv run pytest tests/live/ -v --tb=short

wade_cli-0.0.2/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

wade_cli-0.0.2/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Create Draft Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  draft-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract changelog section
+        id: changelog
+        run: |
+          VERSION="${GITHUB_REF_NAME}"
+          NOTES=$(awk "/^## \[${VERSION}\]/{found=1; next} found && /^## \[/{exit} found{print}" CHANGELOG.md)
+          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          echo "$NOTES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --draft \
+            --title "$GITHUB_REF_NAME" \
+            --notes "${{ steps.changelog.outputs.notes }}"

wade_cli-0.0.2/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# wade runtime (per-project, gitignored)
+.wade/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+uv.lock
+
+# Temporary commit message file (agents use this to avoid rewriting on hook retries)
+.commit-msg
+
+# Local archive (pre-reset export)
+archive/

wade_cli-0.0.2/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        args: [--strict]
+        additional_dependencies:
+          - typer>=0.12
+          - pydantic>=2.0
+          - pydantic-settings>=2.0
+          - sqlmodel>=0.0.16
+          - pyyaml>=6.0
+          - rich>=13.0
+          - structlog>=24.0
+          - types-PyYAML>=6.0
+        pass_filenames: false
+        entry: mypy src/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: check-merge-conflict

wade_cli-0.0.2/AGENTS.md

@@ -0,0 +1,183 @@
+# AGENTS.md
+
+This file provides guidance to AI agents working on the WADE codebase.
+For detailed reference on specific topics, see `docs/dev/`.
+
+## Project Overview
+
+**WADE** (Workflow for AI-Driven Engineering) is a Python CLI toolkit for AI-agent-driven git workflow management. It wraps `gh` CLI and native git to manage GitHub Issues as tasks, git worktrees for isolated development, branch safety checks, and installable Agent Skill files. CLI entry point: **`wade`**.
+
+## Terminology
+
+Two distinct worlds interact in this codebase. Always be clear which one you are working in:
+
+| Term | Meaning |
+|------|---------|
+| **the WADE repo** / **this project** | This source repository — `src/wade/`, `templates/`, `tests/`, `scripts/` |
+| **inited project** / **target project** | Any third-party repo that has run `wade init` to adopt the workflow |
+| **skill templates** | Markdown files in `templates/skills/` — the source of truth, part of the WADE repo |
+| **installed skills** | Copies (or symlinks) of skill templates placed in a project's `.claude/skills/` by `wade init` |
+| **AGENTS.md pointer** | A short `## Git Workflow` block that `wade init` injects into an inited project's `AGENTS.md` |
+
+**This `AGENTS.md` governs development of WADE itself.** Skills, the pointer, and the progressive disclosure architecture are all *outputs* of WADE — artifacts installed into inited projects, not rules for developing WADE.
+
+**WADE uses its own workflow.** This repo is itself an inited project. Follow the `## Git Workflow` pointer at the bottom and the phase-specific skill referenced in your clipboard prompt.
+
+## Commands
+
+> **AI agents: always run the scripts below — never improvise raw `uv run pytest` / `mypy` / `ruff` calls.**
+
+| Script | Purpose |
+|--------|---------|
+| `./scripts/test.sh` | Run all tests (excludes live) |
+| `./scripts/test.sh tests/unit/` | Unit tests only |
+| `./scripts/check.sh` | Lint + type-check (both) |
+| `./scripts/check.sh --lint` | Lint + format check only |
+| `./scripts/check.sh --types` | Type check (strict mypy) only |
+| `./scripts/fmt.sh` | Auto-format source in-place |
+| `./scripts/check-all.sh` | Full checklist (test + check) |
+
+```bash
+uv pip install -e ".[dev]"           # Install for development
+python scripts/auto_version.py patch # Version bump (patch/minor/major)
+
+# Version bumps MUST be done with the script above. NEVER bump pyproject.toml
+# manually, as the script generates CHANGELOG.md and git tags automatically.
+```
+
+> Full commands reference: see `docs/dev/architecture.md`
+
+## Architecture
+
+```
+CLI Layer      ->  can import: services, models, config, logging, ui
+Service Layer  ->  can import: providers, ai_tools, git, db, models, config, logging
+Provider Layer ->  can import: models, config, logging  (NO service imports)
+AI Tool Layer  ->  can import: models, config, logging  (NO service imports)
+Git Layer      ->  can import: models, config, logging  (NO service imports)
+DB Layer       ->  can import: models, logging           (NO config imports)
+Models Layer   ->  can import: nothing (leaf dependency)
+```
+
+No circular dependencies. Models are pure data. Services orchestrate. **Never import a higher layer from a lower layer.**
+
+CLI modules are thin dispatch — they parse flags via Typer, then call service methods. Business logic lives in `services/`, not in `cli/`.
+
+> Full package structure, command dispatch, config system, and subsystem details: see `docs/dev/architecture.md`
+
+### Key Design Patterns
+
+- **AI Tool Self-Registration**: `AbstractAITool.__init_subclass__` auto-registers adapters. Adding a new AI tool = one file, one class.
+- **Provider Abstraction**: `AbstractTaskProvider` ABC with pluggable backends (currently GitHub via `gh` CLI).
+- **Prompts as .md Templates**: All AI prompts live in `templates/prompts/`, not inline strings.
+- **Synchronous Only**: No asyncio. Process-level parallelism via multiple terminals.
+- **Pydantic Everywhere**: All data structures are Pydantic `BaseModel` subclasses, not dicts.
+
+## Design Principles
+
+### Determinism via Services
+
+All deterministic operations — git commands, state transitions, file manipulation, API calls — **must live in service/utility code**, never in AI agent reasoning.
+
+- **Code decides and executes** — fetch, merge, branch creation, worktree lifecycle, issue state changes. Codified in `services/`, `git/`, `providers/`.
+- **Agents interpret and decide** — reading conflict diffs, choosing resolution strategies, composing commit messages. Guided by skills.
+
+**Test**: "Can an AI agent get this wrong by reasoning about it?" If yes, put it in code.
+
+### Two Worlds
+
+Everything in this repo exists in one of two worlds:
+
+| WADE repo (source) | Inited project (output) |
+|---------------------|------------------------|
+| `src/wade/` | installed `wade` binary |
+| `templates/skills/<name>/SKILL.md` | `.claude/skills/<name>/SKILL.md` |
+| `templates/agents-pointer.md` | `## Git Workflow` block in target `AGENTS.md` |
+| `AGENTS.md` (this file) | target project's own `AGENTS.md` |
+
+When developing WADE, **only touch the left column**. Always edit `templates/skills/<name>/SKILL.md` directly — never edit files inside `.claude/skills/` (those are symlinks in this repo, copies in inited projects).
+
+> Skills system deep dive (symlinks, pointer markers, installation lifecycle): see `docs/dev/skills-system.md`
+
+## Conventions
+
+### Naming
+
+- **Modules**: `snake_case.py` — one module per concern
+- **Classes**: `PascalCase` — Pydantic models, ABCs, adapters
+- **Functions**: `snake_case` — `_` prefix for private helpers
+- **Constants**: `UPPER_SNAKE_CASE`
+- **Enums**: `StrEnum` for string-valued enums
+- **CLI commands**: top-level commands (`wade plan-task`, `wade implement-task`)
+
+### Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+`feat:` (minor), `fix:` (patch), `docs:` (patch), `refactor:` (patch),
+`test:` (patch), `chore:` (patch). Breaking changes (`feat!:`) -> major.
+
+**Before every commit — mandatory sequence (Python changes only):**
+
+> Skip this if your commit touches only non-Python files (e.g. `.md`, `.gitignore`, `templates/`).
+
+```bash
+./scripts/fmt.sh           # auto-fix formatting in-place
+./scripts/check.sh --lint  # verify lint passes — fix any remaining errors before proceeding
+```
+
+**Commit using a message file** (handles pre-commit hook retries without rewriting the message):
+
+```bash
+# Write message once
+cat > .commit-msg << 'EOF'
+feat: your message here
+EOF
+
+git add <files>
+git commit -F .commit-msg
+
+# If hooks auto-modified files, just re-add and retry — same file:
+git add <auto-modified-files>
+git commit -F .commit-msg
+```
+
+`.commit-msg` is gitignored — never committed.
+
+## Change Checklist
+
+Before considering any work complete:
+
+- [ ] **Code** — `./scripts/test.sh` passes
+- [ ] **Types + Lint** — `./scripts/check.sh` passes (or run both at once: `./scripts/check-all.sh`)
+- [ ] **`AGENTS.md`** — updated if architecture, conventions, or workflow changed
+- [ ] **`README.md`** — updated if user-facing behavior changed
+- [ ] **`templates/skills/`** — updated if agent-facing rules changed (plan-session for planning, work-session for implementation)
+- [ ] **Commit** — uses conventional-commit prefix
+
+> Full 10-item checklist, documentation rules, feedback loop, and correction-driven docs: see `docs/dev/documentation-policies.md`
+
+## Detailed Reference
+
+Read these on-demand when working in a specific area:
+
+| When you are... | Read |
+|-----------------|------|
+| Modifying architecture, config, or commands | `docs/dev/architecture.md` |
+| Adding an AI tool, provider, or subcommand | `docs/dev/extending.md` |
+| Writing or running tests | `docs/dev/testing.md` |
+| Working on skills, pointer system, or `wade init` | `docs/dev/skills-system.md` |
+| Updating documentation policies | `docs/dev/documentation-policies.md` |
+
+<!-- wade:pointer:start -->
+## Git Workflow
+
+**First action every session** — read the skill referenced in your clipboard
+prompt for full session rules.
+
+Critical rules you must always follow:
+
+1. Never create GitHub Issues via `gh issue create` — use `wade new-task`
+   or read @.claude/skills/task/SKILL.md
+2. Never create PRs manually (`gh pr create`) or push branches directly — use
+   `wade work done`
+<!-- wade:pointer:end -->

wade_cli-0.0.2/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## v0.0.2 (2026-03-04)
+
+Initial public release of WADE — Workflow for AI-Driven Engineering.
+
+## v0.0.1 (2026-03-04)
+
+PyPI name reservation.

wade_cli-0.0.2/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

wade_cli-0.0.2/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to WADE
+
+## Development Setup
+
+**Prerequisites:** [gh CLI](https://cli.github.com/) must be installed and authenticated — WADE shells out to it for all GitHub operations.
+
+```bash
+gh auth login     # first-time setup
+gh auth status    # verify it worked
+```
+
+Then clone and install:
+
+```bash
+git clone https://github.com/ivanviragine/wade.git
+cd wade
+uv pip install -e ".[dev]"
+```
+
+## Running Checks
+
+> Always use the scripts — never invoke `pytest`, `mypy`, or `ruff` directly.
+
+| Command | What it does |
+|---------|-------------|
+| `./scripts/test.sh` | Run all tests (excludes live) |
+| `./scripts/test.sh tests/unit/` | Unit tests only |
+| `./scripts/check.sh` | Lint + type-check |
+| `./scripts/check.sh --lint` | Lint only |
+| `./scripts/check.sh --types` | mypy strict only |
+| `./scripts/fmt.sh` | Auto-format in-place |
+| `./scripts/check-all.sh` | Full suite (tests + lint + types) |
+
+## Architecture
+
+```
+CLI Layer      →  services, models, config, logging, ui
+Service Layer  →  providers, ai_tools, git, db, models, config, logging
+Provider Layer →  models, config, logging  (no service imports)
+Git Layer      →  models, config, logging  (no service imports)
+Models Layer   →  nothing (leaf)
+```
+
+CLI modules are thin dispatch — parse flags with Typer, call service methods. Business logic lives in `services/`, not `cli/`.
+
+See `docs/dev/architecture.md` for the full reference.
+
+## Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+| Prefix | Semver bump |
+|--------|------------|
+| `feat:` | minor |
+| `feat!:` | major (breaking) |
+| `fix:`, `docs:`, `refactor:`, `chore:`, `test:` | patch |
+
+## Releasing
+
+### First release (one-time setup)
+
+```bash
+./scripts/setup-release.sh
+```
+
+This creates the GitHub `pypi` environment, does the first PyPI upload, and walks you through trusted publishing setup.
+
+### Every release after that
+
+```bash
+python scripts/auto_version.py patch --push   # or minor / major
+```
+
+This bumps the version, generates `CHANGELOG.md`, commits, tags, and pushes. CI then:
+
+1. Creates a **draft GitHub Release** with the changelog notes
+2. You review it on GitHub and click **Publish Release**
+3. CI publishes the wheel to PyPI automatically
+
+### Version bump types
+
+```bash
+python scripts/auto_version.py patch   # bug fixes     0.1.0 → 0.1.1
+python scripts/auto_version.py minor   # new features  0.1.0 → 0.2.0
+python scripts/auto_version.py major   # breaking      0.1.0 → 1.0.0
+```
+
+Add `--dry-run` to preview without making changes.
+
+## Detailed Reference
+
+| Topic | File |
+|-------|------|
+| Architecture, config, commands | `docs/dev/architecture.md` |
+| Adding AI tools, providers, subcommands | `docs/dev/extending.md` |
+| Writing and running tests | `docs/dev/testing.md` |
+| Skills system and `wade init` | `docs/dev/skills-system.md` |
+| Documentation policies | `docs/dev/documentation-policies.md` |

wade_cli-0.0.2/Dockerfile

@@ -0,0 +1,37 @@
+ARG PYTHON_VERSION=3.11
+FROM python:${PYTHON_VERSION}-slim
+
+# Install git and gh CLI (needed for integration tests)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+       | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+       > /etc/apt/sources.list.d/github-cli.list \
+    && apt-get update && apt-get install -y gh \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml .
+COPY src/ src/
+COPY tests/ tests/
+COPY templates/ templates/
+
+# Install dependencies
+RUN uv venv /app/.venv && \
+    uv pip install --python /app/.venv/bin/python ".[dev]"
+
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Configure git for tests
+RUN git config --global user.email "test@wade.dev" && \
+    git config --global user.name "wade test" && \
+    git config --global init.defaultBranch main
+
+CMD ["pytest", "tests/", "-v", "--ignore=tests/live"]