workforge 2.4.1__py3-none-any.whl

workforge-2.4.1.dist-info/METADATA

@@ -0,0 +1,515 @@
+Metadata-Version: 2.5
+Name: workforge
+Version: 2.4.1
+Summary: Turn work inputs into provider-neutral requirements and planning items.
+Project-URL: Homepage, https://github.com/Nanielito/workforge
+Project-URL: Repository, https://github.com/Nanielito/workforge.git
+Project-URL: Issues, https://github.com/Nanielito/workforge/issues
+Project-URL: Changelog, https://github.com/Nanielito/workforge/blob/main/CHANGELOG.md
+Author: Daniel Ramirez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,github-projects,jira,planning,trello
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: typer>=0.12.3
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# WorkForge
+
+WorkForge turns raw work inputs into structured planning items, then sends them
+to planning providers such as Trello, GitHub Projects, and Jira Cloud.
+
+The core model is provider-neutral so the same requirements can become Trello
+cards, GitHub Issues attached to a Project v2, or Jira issues.
+
+## Goals
+
+- Keep planning automation outside product repositories.
+- Support multiple workspaces with their own configuration and environment.
+- Preview generated requirements before creating external items.
+- Add providers through a small adapter interface.
+
+## Versioning
+
+WorkForge uses semantic versioning.
+
+- Patch releases fix bugs without changing commands or output contracts.
+- Minor releases add backward-compatible commands, providers, or output files.
+- Major releases may change CLI behavior, provider contracts, or saved output
+  formats.
+
+`v1.0.0` is the stable Trello workflow release. The provider-neutral item
+terminology and GitHub Projects provider require a major release because they
+change saved output and CLI command names.
+
+Releases are created manually from the `Release` GitHub Actions workflow on
+`main`. The workflow updates the version and changelog, runs the test suite,
+builds and validates the wheel and source distribution, creates the Git tag,
+and attaches both distributions to a GitHub Release.
+
+See the [distribution and release guide](https://github.com/Nanielito/workforge/blob/main/docs/distribution.md)
+for the release process, public PyPI workflow, and required one-time setup.
+
+### Migrating from v1 to v2
+
+Version 2 uses provider-neutral item terminology. Existing generated output is
+not migrated automatically; rename `cards.json` to `items.json` and the
+`cards/` context directory to `items/`, or run `workforge discover --save` to
+rebuild them from the provider.
+
+The corresponding CLI names changed:
+
+| v1 | v2 |
+| --- | --- |
+| `card-context --card/-c` | `item-context --item/-i` |
+| `comment-card --card/-c` | `comment-item --item/-i` |
+| `move-card --card/-c --list/-l` | `move-item --item/-i --status/-s` |
+
+Scripts using the v1 names must be updated before upgrading; v2 does not keep
+deprecated aliases.
+
+## CI
+
+GitHub Actions runs on pull requests and pushes to `main`.
+
+- Tests run on Python 3.11, 3.12, and 3.13.
+- The package build is validated with `python -m build`.
+
+## Provider design documentation
+
+- [Trello provider design](https://github.com/Nanielito/workforge/blob/main/docs/trello-provider-design.md)
+- [GitHub Projects provider design](https://github.com/Nanielito/workforge/blob/main/docs/github-provider-design.md)
+- [Jira Cloud provider design](https://github.com/Nanielito/workforge/blob/main/docs/jira-provider-design.md)
+
+## Quick Start
+
+Install WorkForge as an isolated command-line tool:
+
+```bash
+uv tool install workforge
+```
+
+Contributors should continue to use `pip install -e ".[dev]"`.
+
+Create a project-local workspace:
+
+```bash
+workforge init .workforge --name linkealo --provider trello --namespace linkealo/shopify
+```
+
+Then add the printed entries to the host project's `.gitignore`:
+
+```gitignore
+.workforge/.env
+.workforge/output/
+```
+
+Preview requirements from a workspace inbox file:
+
+```bash
+workforge preview workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example
+```
+
+Save preview output next to the workspace:
+
+```bash
+workforge preview workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example --save
+```
+
+Create provider items:
+
+```bash
+workforge create workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example --provider trello --execute
+```
+
+Save created provider items:
+
+```bash
+workforge create workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example --provider trello --execute --save
+```
+
+Preview task-list updates for items matched by requirement title, then apply them:
+
+```bash
+workforge update workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example
+workforge update workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example --execute
+```
+
+Tasks that keep the same title retain their completion state. Other provider fields are left unchanged.
+
+Discover existing provider items by label and rebuild `items.json`:
+
+```bash
+workforge discover workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example --provider trello --label shopify --save
+```
+
+GitHub discovery can also filter by assignee and configured Project status:
+
+```bash
+workforge discover --workspace workspaces/github-projects-example --provider github --assignee @me --status todo --save
+```
+
+Trello uses the same options for board members and configured logical lists:
+
+```bash
+workforge discover --workspace workspaces/trello-example --provider trello --assignee @me --status doing --save
+```
+
+Jira uses JQL and accepts logical labels, account IDs or `@me`, and configured
+workflow statuses:
+
+```bash
+workforge discover --workspace workspaces/jira-example --provider jira --assignee @me --status doing --save
+```
+
+After choosing an existing item, assign it to the authenticated provider user:
+
+```bash
+workforge claim-item requirements.md --workspace workspaces/my-project --item "Fix login"
+```
+
+Use `--assignee <provider-user>` to assign it to someone else. Assignment remains optional when items are created.
+
+Check provider item status from saved `items.json`:
+
+```bash
+workforge status workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example --save
+```
+
+Generate implementation context for an agent:
+
+```bash
+workforge agent-context workspaces/trello-example/inbox/sample-requirements.md --workspace workspaces/trello-example --save
+```
+
+Generate implementation context for one item:
+
+```bash
+workforge item-context workspaces/trello-example/inbox/sample-requirements.md \
+  --workspace workspaces/trello-example \
+  --item "Fix UI" \
+  --save
+```
+
+Mark a provider checklist task as complete:
+
+```bash
+workforge complete-task workspaces/trello-example/inbox/sample-requirements.md \
+  --workspace workspaces/trello-example \
+  --item "Fix UI" \
+  --task "Add explicit customer data disclosure"
+```
+
+`--item` accepts an item ID, exact title, or unique title substring. `--task`
+accepts a checklist item ID, exact title, or unique title substring. By default,
+WorkForge refreshes `status.json` and `agent-context.md` after completing the
+task.
+
+Add an implementation comment to a provider item:
+
+```bash
+workforge comment-item workspaces/trello-example/inbox/sample-requirements.md \
+  --workspace workspaces/trello-example \
+  --item "Fix UI" \
+  --text "Started implementation from WorkForge agent context."
+```
+
+Move a provider item to another list or workflow column:
+
+```bash
+workforge move-item workspaces/trello-example/inbox/sample-requirements.md \
+  --workspace workspaces/trello-example \
+  --item "Fix UI" \
+  --status doing
+```
+
+For Trello, `--status` accepts a Trello list ID or a configured logical list name.
+By default, WorkForge refreshes `status.json` and `agent-context.md` after
+commenting or moving an item.
+
+Check provider credentials and workspace configuration:
+
+```bash
+workforge providers test --workspace workspaces/trello-example --provider trello
+```
+
+## Workspace Layout
+
+```txt
+<workspace>/
+  workforge.yaml
+  .env.example
+  inbox/
+  output/
+```
+
+Workspace `.env` files are intentionally local-only. Commit `.env.example`, not
+`.env`.
+
+Environment variables are scoped to the selected workspace at runtime. WorkForge
+reads `workspaces/<name>/.env` into an in-memory runtime object and passes those
+values to the selected provider. It does not load workspace credentials into the
+global process environment, which keeps simultaneous workspace runs isolated.
+
+## Workspace Modes
+
+WorkForge supports two workspace styles.
+
+Shared example workspaces live inside this repository:
+
+```txt
+workspaces/trello-example/
+workspaces/github-projects-example/
+workspaces/jira-example/
+```
+
+Project-local workspaces live inside the repository that the agent will modify:
+
+```txt
+some-project/
+  .workforge/
+    workforge.yaml
+    .env.example
+    inbox/
+    output/
+```
+
+Project-local workspaces are recommended when generating agent context for an
+implementation task because `agent-context.md`, `status.json`, and `items.json`
+stay close to the code being changed.
+
+## Jira Cloud
+
+Create an Atlassian API token and keep the credentials in the selected
+workspace's `.env`:
+
+```dotenv
+JIRA_EMAIL=you@example.com
+JIRA_API_TOKEN=
+```
+
+Configure one Jira Cloud project:
+
+```yaml
+providers:
+  jira:
+    site_url: https://example.atlassian.net
+    project_key: WF
+    issue_type: Task
+    labels:
+      feature: enhancement
+    versions:
+      v1: "10000"
+    status:
+      values:
+        todo: To Do
+        doing: In Progress
+        review: In Review
+        done: Done
+```
+
+`labels`, `versions`, and status names reference resources that already exist
+in Jira. WorkForge does not create or administer Jira projects, boards,
+workflows, versions, or labels.
+
+Validate access before creating issues:
+
+```bash
+workforge providers test --workspace workspaces/jira-example --provider jira
+workforge preview workspaces/jira-example/inbox/sample-requirements.md --workspace workspaces/jira-example
+```
+
+Use the same provider-neutral `create`, `status`, `complete-task`,
+`comment-item`, `move-item`, and `discover` commands shown above. Jira stores
+descriptions, comments, and managed tasks as Atlassian Document Format and
+changes statuses through transitions available from the issue's current state.
+
+## Input Format
+
+The initial parser accepts Markdown sections with optional tasks:
+
+```md
+## Clarify customer data collection
+
+Source: shopify_review
+Priority: high
+Milestone: release-2
+Labels: compliance, required
+
+Shopify asked us to explain what customer data is collected and why.
+
+- Review current privacy copy
+- Add explicit customer data disclosure
+- Validate wording against Shopify review requirements
+```
+
+Each `##` section becomes one provider-neutral requirement.
+
+## Output Files
+
+Saved output is grouped by input filename under the selected workspace:
+
+```txt
+workspaces/<name>/
+  inbox/
+    shopify-feedback-app-review.md
+  output/
+    shopify-feedback-app-review/
+      preview.json
+      items.json
+      status.json
+      agent-context.md
+      items/
+        fix-ui-operativa-post-instalacion.md
+```
+
+`preview.json` contains the provider-neutral requirements parsed from the input.
+`items.json` contains the items created by the selected provider, including IDs
+and URLs when the provider returns them.
+`status.json` contains the live provider status for saved items and tasks.
+`agent-context.md` turns that status into implementation-ready context with
+pending and completed tasks.
+`items/*.md` contains focused implementation context for a single provider item.
+
+## Discovering Existing Items
+
+Project-local workspaces can stay ignored by Git. To rebuild local tracking
+files after cloning a project, discover items from the planning provider:
+
+```bash
+workforge discover .workforge/inbox/shopify-feedback-app-review.md \
+  --workspace .workforge \
+  --provider trello \
+  --label shopify \
+  --save
+```
+
+This writes:
+
+```txt
+.workforge/output/shopify-feedback-app-review/items.json
+```
+
+Then refresh status and agent context:
+
+```bash
+workforge status .workforge/inbox/shopify-feedback-app-review.md --workspace .workforge --save
+workforge agent-context .workforge/inbox/shopify-feedback-app-review.md --workspace .workforge --save
+workforge item-context .workforge/inbox/shopify-feedback-app-review.md --workspace .workforge --item "Fix UI" --save
+```
+
+For Trello, `--label` accepts a configured logical label name, a Trello label
+ID, or a Trello label name. Logical labels are read from `workforge.yaml`:
+
+```yaml
+providers:
+  trello:
+    list_id: "trello-list-id"
+    lists:
+      todo: "trello-todo-list-id"
+      doing: "trello-doing-list-id"
+      done: "trello-done-list-id"
+    labels:
+      shopify: "trello-label-id"
+```
+
+## GitHub Projects
+
+The GitHub provider supports Projects v2 owned by a personal account. It creates
+repository Issues, renders requirement tasks as GitHub checkboxes, and adds each
+Issue to the configured Project.
+
+```yaml
+providers:
+  github:
+    owner: github-user
+    repository: repository-name
+    project_number: 1
+    labels:
+      feature: enhancement
+    milestones:
+      v2: 1
+    status:
+      field: Status
+      values:
+        todo: Todo
+        doing: In Progress
+        done: Done
+```
+
+Store a token with Issues and Projects read/write access in the workspace `.env`:
+
+```dotenv
+GITHUB_TOKEN=
+```
+
+Verify access without modifying GitHub:
+
+```bash
+workforge providers test --workspace .workforge --provider github
+```
+
+GitHub labels, milestones, and Status options must already exist. Logical labels,
+milestones, and status aliases map through `workforge.yaml`; unmapped requirement
+labels are ignored, while an unmapped milestone is rejected. Project workflows
+may independently close an Issue when its Status moves to `Done`.
+
+## Trello Labels
+
+Labels in Markdown are logical names. To attach real Trello labels to cards,
+map those logical names to Trello label IDs in the workspace config:
+
+```yaml
+providers:
+  trello:
+    list_id: "trello-list-id"
+    labels:
+      shopify-review: "trello-label-id"
+      compliance: "trello-label-id"
+```
+
+WorkForge sends mapped labels as `idLabels` when creating Trello cards. Unmapped
+labels are ignored by the Trello provider.
+
+WorkForge does not create Trello labels yet. Create or rename labels in Trello
+first, then paste their IDs into `workforge.yaml`.
+
+To create a label through the Trello API:
+
+```bash
+curl --request POST \
+  --url "https://api.trello.com/1/labels?name=shopify-review&color=blue&idBoard=TRELLO_BOARD_ID&key=$TRELLO_API_KEY&token=$TRELLO_API_TOKEN"
+```
+
+To rename an existing label:
+
+```bash
+curl --request PUT \
+  --url "https://api.trello.com/1/labels/TRELLO_LABEL_ID?name=shopify-review&key=$TRELLO_API_KEY&token=$TRELLO_API_TOKEN"
+```
+
+To list labels for a board:
+
+```bash
+curl "https://api.trello.com/1/boards/TRELLO_BOARD_ID/labels?fields=id,name,color&key=$TRELLO_API_KEY&token=$TRELLO_API_TOKEN"
+```
+
+## License
+
+WorkForge is available under the [MIT License](https://github.com/Nanielito/workforge/blob/main/LICENSE).

workforge-2.4.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+workforge/__init__.py,sha256=tGGaO9hyqtgHuzeTJjq8SaEXbfK7osEDvkTLm8Y80Ho,75
+workforge/cli.py,sha256=Gww4v20B8G44j2aeOgkPfWz0J6dkbDBMr65WnCK9ngM,27337
+workforge/config.py,sha256=NFTx38MFd4GsVI63byJnLDYBgQwIM9CeFzT_zQWEjIE,1363
+workforge/models.py,sha256=x4CtwbvIncS_ziX1HYLadN-OhIR3t1PrgnBYaBPSIro,1073
+workforge/core/__init__.py,sha256=z9gVNSsNJGLvqUErQDmDXLVPjMVMAMdod-NyEXPJtBc,31
+workforge/core/parser.py,sha256=yJtGq_KXQw5eHnrvClyzGM-SPz5BNctUzE0PjTDUxcc,2856
+workforge/providers/__init__.py,sha256=cxzR7JnFNBur4fYukhNRFRbIx7HnJLypk8I7ZGfkEMs,34
+workforge/providers/base.py,sha256=ek-VLDlWsnPQIA11kroLk_VpQOlZp-pZ5jWgZqsSn4w,1482
+workforge/providers/github.py,sha256=uG5QRkldKsuQKViUDm1R6UbepP7zka9dOz8bBHr5HIk,24252
+workforge/providers/jira.py,sha256=Z-AtvNN1U16orn0nNnYxhHT_gHSLjRB8bWqCdKVkf6I,21580
+workforge/providers/registry.py,sha256=E8cEcUNSKGvDNKV_VrR-GrfLSM2sUOxIQTGqL9lPXyQ,617
+workforge/providers/trello.py,sha256=T8Jy3eukdB3IsQkGI4v9CnA2OITQKS-XDR91sw7ncrM,18047
+workforge-2.4.1.dist-info/METADATA,sha256=ma4PsGZfJI-1-xWjxvqLzA7rvyZh7IcnxRCVWD8clFs,15752
+workforge-2.4.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+workforge-2.4.1.dist-info/entry_points.txt,sha256=ZvVNYSG4Ho2jsYzxouUxsI5R_T-f-ZosxmnlwET1WXs,48
+workforge-2.4.1.dist-info/licenses/LICENSE,sha256=0eBeIBG2hWATtWifYvMsg8JmmG9h5yLaDZkEtfXYnOk,1071
+workforge-2.4.1.dist-info/RECORD,,

workforge-2.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

workforge-2.4.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+workforge = workforge.cli:app

workforge-2.4.1.dist-info/licenses/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.