workforge 2.4.1__tar.gz

workforge-2.4.1/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install build dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Build distribution
+        run: python -m build

workforge-2.4.1/.github/workflows/release.yml

@@ -0,0 +1,145 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version bump type
+        required: true
+        default: patch
+        type: choice
+        options:
+          - major
+          - minor
+          - patch
+
+jobs:
+  release:
+    name: Build and release
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install package and release tools
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest
+
+      - name: Install git-cliff
+        uses: taiki-e/install-action@v2
+        with:
+          tool: git-cliff
+
+      - name: Read current version
+        id: version
+        run: |
+          VERSION=$(sed -n 's/^version = "\([0-9]*\.[0-9]*\.[0-9]*\)"/\1/p' pyproject.toml)
+          if [ -z "$VERSION" ]; then
+            echo "Could not read the project version from pyproject.toml."
+            exit 1
+          fi
+          echo "current=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Calculate next version
+        id: bump
+        env:
+          CURRENT_VERSION: ${{ steps.version.outputs.current }}
+          BUMP: ${{ inputs.bump }}
+        run: |
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+
+          case "$BUMP" in
+            major)
+              MAJOR=$((MAJOR + 1))
+              MINOR=0
+              PATCH=0
+              ;;
+            minor)
+              MINOR=$((MINOR + 1))
+              PATCH=0
+              ;;
+            patch)
+              PATCH=$((PATCH + 1))
+              ;;
+          esac
+
+          NEW_VERSION="$MAJOR.$MINOR.$PATCH"
+          if git rev-parse "v$NEW_VERSION" >/dev/null 2>&1; then
+            echo "Tag v$NEW_VERSION already exists."
+            exit 1
+          fi
+          echo "new_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Update version and changelog
+        env:
+          NEW_VERSION: ${{ steps.bump.outputs.new_version }}
+        run: |
+          sed -i "s/^version = \"[0-9]*\.[0-9]*\.[0-9]*\"/version = \"$NEW_VERSION\"/" pyproject.toml
+          git-cliff --tag "v$NEW_VERSION" > CHANGELOG.md
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Verify distribution metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Commit version and tag
+        env:
+          NEW_VERSION: ${{ steps.bump.outputs.new_version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml CHANGELOG.md
+          git commit -m "chore: release $NEW_VERSION"
+          git tag -a "v$NEW_VERSION" -m "v$NEW_VERSION"
+          git push origin HEAD:main --follow-tags
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.bump.outputs.new_version }}
+          name: v${{ steps.bump.outputs.new_version }}
+          body_path: CHANGELOG.md
+          files: dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/workforge
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

workforge-2.4.1/.gitignore

@@ -0,0 +1,32 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Local secrets and shell helpers
+.env
+.env.*
+!.env.example
+*.local
+set_env*.fish
+
+# Personal workspaces are local by default. Keep shared examples explicitly.
+workspaces/*
+!workspaces/trello-example/
+!workspaces/trello-example/**
+!workspaces/github-projects-example/
+!workspaces/github-projects-example/**
+workspaces/github-projects-example/.env
+!workspaces/jira-example/
+!workspaces/jira-example/**
+workspaces/jira-example/.env
+
+# Workspace generated artifacts
+workspaces/*/output/**
+!workspaces/*/output/
+!workspaces/*/output/.gitkeep

workforge-2.4.1/AGENTS.md

@@ -0,0 +1,135 @@
+# WorkForge Agent Guide
+
+## Project overview
+
+WorkForge is a Python CLI that parses Markdown requirements into provider-neutral planning items and synchronizes them with planning systems such as Trello, GitHub Projects, and Jira.
+
+The project prioritizes:
+
+- provider-neutral domain models;
+- isolated, project-specific workspace configuration and credentials;
+- safe previews before external writes;
+- small provider adapters with consistent behavior;
+- backward-compatible CLI and saved-output contracts within a major version.
+
+Python 3.11 is the minimum supported version. The package uses Typer for the CLI, Pydantic for models and configuration, HTTPX for provider requests, PyYAML for workspace files, and pytest for tests.
+
+## Repository map
+
+- `src/workforge/cli.py`: Typer commands and application orchestration.
+- `src/workforge/models.py`: provider-neutral domain and status models.
+- `src/workforge/config.py`: workspace configuration and isolated `.env` loading.
+- `src/workforge/core/parser.py`: Markdown-to-requirement parsing.
+- `src/workforge/providers/base.py`: provider contract.
+- `src/workforge/providers/registry.py`: provider construction.
+- `src/workforge/providers/{trello,github,jira}.py`: provider-specific API logic.
+- `tests/`: behavior-focused unit tests, including mocked HTTP provider tests.
+- `workspaces/*-example/`: committed examples only; generated output and real credentials remain local.
+- `docs/`: provider designs and other decisions that need more detail than the README.
+- `.github/workflows/`: CI and manual SemVer release automation.
+
+The main flow is:
+
+1. `load_workspace` reads `workforge.yaml` and a workspace-local `.env` without mutating the process environment.
+2. `parse_markdown_requirements` produces provider-neutral `Requirement` models.
+3. `build_provider` selects a `PlanningProvider` adapter.
+4. CLI orchestration calls the adapter and optionally saves provider-neutral JSON or Markdown context under the workspace output directory.
+
+## Working rules
+
+- Read the relevant implementation, callers, tests, and local diff before editing.
+- Preserve unrelated and pre-existing working-tree changes. Never discard, overwrite, stage, or commit them.
+- Make the smallest complete change. Reuse existing patterns and dependencies; do not add speculative abstractions or dependencies.
+- Keep provider-specific concepts inside provider modules. Shared models, parser output, CLI terminology, and saved formats must remain provider-neutral.
+- Extend `PlanningProvider` and `build_provider` together when adding a provider capability, then cover every concrete provider as required by the contract.
+- Keep CLI commands thin: parsing/configuration, provider selection, orchestration, output, and persistence belong there; provider API details do not.
+- Preserve async provider methods and inject `httpx.MockTransport` in tests. Tests must not call live external services.
+- Validate configuration before network requests and turn provider failures into useful, secret-safe errors.
+- Never expose tokens, credentials, authorization headers, or `.env` contents in output, exceptions, fixtures, logs, or commits.
+- Do not mutate external planning systems unless the user explicitly authorizes it. Prefer preview, provider checks, and mocked tests while developing.
+- WorkForge dogfoods its GitHub provider: create this repository's tracking issues through the `workspaces/workforge` workspace and WorkForge CLI, previewing first and using `--execute` only when the user explicitly authorizes the external write. Use `gh` or the GitHub UI only when that workflow cannot perform the requested operation.
+- When the user authorizes work on a tracked issue, claim it with `workforge claim-item ... --assignee @me` and move it to `doing` before implementation. This applies to existing issues and issues created for a new requirement.
+- Treat the issue's managed tasks as the implementation checklist. Complete each task through `workforge complete-task` as soon as its behavior is implemented and its relevant check passes; leave unfinished or unverified tasks open and report them at handoff.
+- If implementation changes the checklist scope, update the workspace requirement and synchronize it through WorkForge before continuing task tracking.
+- Do not close a tracked issue or move it to `done` when implementation finishes. Leave it in `doing` while the pull request is open; the pull request or project automation closes it and moves it to `done` on merge.
+- Keep workspace secrets in `.env`, commit only `.env.example`, and preserve workspace isolation by passing the runtime environment explicitly.
+- Treat CLI names, options, JSON fields, output paths, provider contracts, and workspace configuration as public interfaces. Breaking changes require explicit approval and a major release plan.
+- Update README examples or design docs when user-facing commands, configuration, provider behavior, or output contracts change.
+- Do not manually edit release versions or generated changelog entries as part of ordinary feature work; the release workflow owns them.
+
+## Tests and verification
+
+Install the development environment with:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+For a focused change, run the smallest relevant test first:
+
+```bash
+python -m pytest tests/test_<area>.py
+```
+
+Before handing off a completed code change, run the full local CI equivalent:
+
+```bash
+python -m pytest
+python -m build
+```
+
+Add or update tests for every behavior change and regression fix. Prefer observable behavior over implementation-detail assertions. Provider tests should assert request paths and payloads, success mapping, configuration validation, error handling, and secret redaction where relevant.
+
+If a required check cannot run, state exactly which check was skipped and why. Do not claim verification that was not performed.
+
+## Git and commits
+
+- Use Conventional Commits: `<type>(<optional-scope>): <imperative summary>`.
+- Allowed common types are `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`, and `perf`.
+- Keep the subject concise, lowercase after the colon, and free of a trailing period.
+- Use a scope when it adds useful precision, such as `github`, `trello`, `jira`, `cli`, `parser`, or `workspace`.
+- Mark breaking changes with `!` and explain them in a `BREAKING CHANGE:` footer.
+- Keep commits atomic: one coherent change plus its tests and documentation.
+- Do not create a commit, push, or open a PR unless the user asks. Before committing, inspect the staged diff and ensure it contains only intended files.
+
+Examples:
+
+```text
+feat(jira): create issues from requirements
+fix(cli): preserve workspace output on provider failure
+docs: document provider configuration
+feat(cli)!: rename card commands to item commands
+```
+
+## Pull request handoff
+
+Always provide a ready-to-paste PR title and summary when handing off a completed change, even if no PR is created.
+
+Use a Conventional Commit-style PR title and this body:
+
+```markdown
+## Summary
+
+- <what changed>
+- <why it changed>
+
+## Verification
+
+- `<command>`
+- <manual check, or `Not run (reason)`>
+
+## Risks
+
+- <compatibility, migration, external side-effect, or operational risk>
+- None identified
+
+Closes #<issue-number>
+```
+
+Include the `Closes` line only when the work is associated with a tracked issue. Mention user-visible CLI/configuration/output changes, deferred work, and breaking or migration implications. Keep the summary factual; never claim tests passed unless they were run successfully.
+
+## Definition of done
+
+A change is complete only when the requested behavior is implemented, relevant tests cover it, applicable tests pass, documentation is updated when needed, no secrets or unrelated changes are included, and the handoff contains the changed files, verification results, and PR-ready summary.

workforge-2.4.1/CHANGELOG.md

@@ -0,0 +1,125 @@
+## [2.4.1] - 2026-08-21
+
+### 💼 Other
+
+- Publish releases to PyPI
+
+### 📚 Documentation
+
+- Document public distribution workflow
+- License WorkForge under MIT
+
+### ⚙️ Miscellaneous Tasks
+
+- *(github pages)* Create theme configuration file
+- Updates documentation
+## [2.4.0] - 2026-08-21
+
+### 🚀 Features
+
+- *(cli)* Synchronize requirement task lists
+
+### 📚 Documentation
+
+- Complete provider design documentation
+- Define tracked issue workflow
+
+### ⚙️ Miscellaneous Tasks
+
+- Release 2.4.0
+## [2.3.0] - 2026-08-21
+
+### 🚀 Features
+
+- *(cli)* Claim existing provider items
+
+### ⚙️ Miscellaneous Tasks
+
+- Release 2.3.0
+## [2.2.0] - 2026-08-21
+
+### 🚀 Features
+
+- *(jira)* Add provider connectivity
+- *(jira)* Create issues from requirements
+- *(jira)* Track and complete issue tasks
+- *(jira)* Comment on and transition issues
+- *(jira)* Discover issues with JQL filters
+- *(jira)* Harden provider for release
+
+### 📚 Documentation
+
+- Add project agent guidelines
+
+### ⚙️ Miscellaneous Tasks
+
+- Release 2.2.0
+## [2.1.0] - 2026-08-21
+
+### 🚀 Features
+
+- Filter GitHub discovery by assignee and status
+- Filter Trello discovery by member and list
+
+### ⚙️ Miscellaneous Tasks
+
+- Release 2.1.0
+## [2.0.0] - 2026-08-20
+
+### 🚀 Features
+
+- Add GitHub provider connectivity check
+- Create GitHub issues from requirements
+- Add created issues to GitHub Projects
+- Read GitHub issue task status
+- Complete GitHub issue tasks
+- Update GitHub Project item status
+- Discover GitHub Project issues
+- Comment on GitHub issues
+- Assign GitHub milestones to requirements
+
+### 🐛 Bug Fixes
+
+- Harden GitHub provider failures
+
+### 🚜 Refactor
+
+- Store provider output as items
+- Use provider-neutral item terminology
+
+### 📚 Documentation
+
+- Document GitHub Projects provider
+- Add GitHub Projects example workspace
+- Add v2 migration guide
+
+### ⚙️ Miscellaneous Tasks
+
+- Release 2.0.0
+## [1.0.0] - 2026-08-05
+
+### 🚀 Features
+
+- Add trello workflow sync commands
+- Add workspace init command
+- Discover trello cards by label
+- Add focused card context command
+- Add Trello card action commands
+
+### 📚 Documentation
+
+- Include Trello lists and labels in example workspace
+
+### 🧪 Testing
+
+- Decouple shared tests from project fixtures
+
+### ⚙️ Miscellaneous Tasks
+
+- Scaffold workforge cli
+- Scope workspace runtime environment
+- Refine workspace gitignore rules
+- Add test and build workflow
+- Rename the Trello example workspace
+- Add Python release workflow
+- Release 1.0.0

workforge-2.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Ramirez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.