corvee 0.1.0__tar.gz

corvee-0.1.0/.claude/CLAUDE.md

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

corvee-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

corvee-0.1.0/.github/workflows/cicd.yaml

@@ -0,0 +1,190 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [master]
+  release:
+    types: [created]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0  # hatch-vcs needs full history (and any tags) to derive a version
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Install project (generates src/corvee/_version.py via the hatch-vcs build hook)
+        run: uv pip install --system -e .
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Install project and test dependencies
+        run: uv pip install --system -e '.[mcp]' pytest pytest-xdist
+      - name: Run tests
+        run: pytest -n auto
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [pre-commit, test]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Install hatch
+        run: uv tool install hatch
+      - name: Build
+        run: hatch build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  docs:
+    runs-on: ubuntu-latest
+    needs: [pre-commit, test]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Install hatch
+        run: uv tool install hatch
+      - name: Build documentation
+        run: hatch run docs-build
+      - if: github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: [docs]
+    if: github.ref == 'refs/heads/master'
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+
+  # Uploads the package to test.pypi.org on every push to master.
+  upload-test-pypi:
+    if: |
+      success()
+      && github.ref == 'refs/heads/master'
+      && github.actor == 'btschwertfeger'
+      && github.event_name == 'push'
+    needs: [build]
+    name: Upload development version to Test PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # mandatory for OIDC Trusted Publishing
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/corvee
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            api.github.com:443
+            github.com:443
+            test.pypi.org
+            uploads.github.com:443
+
+      - name: Download the distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package distributions to Test PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # Uploads the package to PyPI when a release is created.
+  upload-pypi:
+    if: |
+      success()
+      && github.actor == 'btschwertfeger'
+      && github.event_name == 'release'
+    needs: [build]
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # mandatory for OIDC Trusted Publishing
+      attestations: write # write build-provenance attestations
+    environment:
+      name: pypi
+      url: https://pypi.org/p/corvee
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            api.github.com:443
+            fulcio.sigstore.dev
+            github.com:443
+            pypi.org
+            rekor.sigstore.dev
+            timestamp.sigstore.dev
+            tuf-repo-cdn.sigstore.dev
+            upload.pypi.org
+
+      - name: Download the distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      # SLSA build provenance for the wheel and sdist, written to GitHub's
+      # attestation store and verifiable with `gh attestation verify`.
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: "dist/*"
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://upload.pypi.org/legacy/

corvee-0.1.0/.github/workflows/dependabot_auto_merge.yaml

@@ -0,0 +1,32 @@
+name: Dependabot auto-merge
+
+on: pull_request_target
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: ${{ github.actor == 'dependabot[bot]' }}
+    steps:
+      - name: Dependabot metadata
+        id: dependabot-metadata
+        uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Approve the PR
+        if: ${{ steps.dependabot-metadata.outputs.update-type != 'version-update:semver-major' }}
+        run: gh pr review --approve "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Enable auto-merge for patch/minor updates
+        if: ${{ steps.dependabot-metadata.outputs.update-type != 'version-update:semver-major' }}
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

corvee-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+*.whl
+
+# Environments
+.venv/
+venv/
+env/
+.hatch/
+
+# Testing / coverage / typing / linting caches
+.cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.nox/
+mutants/
+
+# Docs
+site/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# corvee project data (never committed)
+.corvee/

corvee-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,61 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.1
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+  - repo: https://github.com/psf/black
+    rev: 26.3.1
+    hooks:
+      - id: black
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty
+        entry: ty check
+        language: python
+        pass_filenames: false
+        additional_dependencies: ["ty==0.0.80", "click>=8.1", "pytest", "mcp>=2.2"]
+        args: [src, tests]
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        additional_dependencies: [tomli]
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+        exclude: ^mkdocs\.yml$
+      - id: check-yaml
+        name: check-yaml (mkdocs.yml, unsafe for the mermaid !!python/name tag)
+        files: ^mkdocs\.yml$
+        args: [--unsafe]
+      - id: check-toml
+      - id: check-json
+      - id: check-ast
+      - id: check-docstring-first
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: check-executables-have-shebangs
+      - id: trailing-whitespace
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: end-of-file-fixer
+      - id: detect-private-key
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: python-use-type-annotations
+      - id: python-check-blanket-noqa
+      - id: python-check-blanket-type-ignore
+      - id: python-check-mock-methods
+      - id: python-no-eval
+      - id: python-no-log-warn
+      - id: text-unicode-replacement-char

corvee-0.1.0/AGENTS.md

@@ -0,0 +1,146 @@
+# AGENTS.md
+
+Guidance for coding agents working on the corvee codebase itself, not the
+pointer block `corvee init` prints for other projects to paste into their
+own AGENTS.md.
+
+## Source of truth
+
+- `docs/spec.md` is the technical specification: schema, CLI contract, exit
+  codes, concurrency model. Implementation must match it. If the two
+  disagree, update `docs/spec.md` rather than letting it drift. Any new
+  feature bumps the spec's own version and extends `docs/spec.md` first,
+  independent of when it gets implemented. The spec documents intended
+  design, not just shipped behavior.
+- `pyproject.toml`'s `[tool.hatch.envs.default.scripts]` is the source of
+  truth for available dev commands. The list below covers the ones used
+  constantly. Run `hatch env show` for the full, current set.
+
+## Stack
+
+Python 3.11+, managed with Hatch (`uv` as the installer underneath). `src`
+layout: the package lives at `src/corvee/`, tests at `tests/`. click for the
+CLI, stdlib `sqlite3` for storage, no ORM. Every tool (pytest, ty, ruff,
+black, coverage) is configured in `pyproject.toml`, not in separate config
+files.
+
+```bash
+hatch run test                  # pytest, parallel via pytest-xdist
+hatch run check                 # every prek hook + test.
+                                 # Run this before considering a change done
+hatch run lint                  # ruff check, via prek
+hatch run format                # black, via prek
+hatch run typecheck             # ty, via prek
+hatch run +py=3.12 test:test    # run the suite against one Python version
+                                 # from the test matrix (3.11-3.14)
+```
+
+`lint`/`format`/`typecheck` all delegate to `prek run <hook-id>` rather than
+invoking ruff/black/ty directly, so hatch and CI can never drift apart on
+what each one actually runs. `hatch run check` (or `prek run --all-files`
+directly) is the mandatory quality gate before a change is considered
+finished.
+
+## Principles
+
+KISS, YAGNI, DRY. A change should be minimal and focused on what was asked.
+Do not use a bug fix or small feature as an excuse for a wider rework, a new
+abstraction, or unrelated cleanup. Three similar lines beat a premature
+abstraction.
+
+## Architecture
+
+Every CLI invocation flows through the same layers, in this order:
+
+1. **`cli/main.py`**: the click group. `CorveeGroup.main()` is overridden so
+   every failure, including click's own usage errors, is caught and
+   re-emitted through one path: a `{"error": {...}}` JSON object on stderr
+   plus the documented exit code (`errors.py`). This is what makes
+   `CliRunner`-based tests exercise the exact same error path a real
+   subprocess would.
+2. **`cli/commands/{task,fact}/*.py`**: one thin click command per verb. The
+   pattern is always: parse id(s) with `models.parse_task_refs`/
+   `parse_fact_refs` (which also determines local vs global scope from the
+   `TASK-GLOBAL-<n>`/`FACT-GLOBAL-<n>` prefix), open `corvee_context(...)`,
+   call exactly one `db/*.py` function to do the actual mutation/query, then
+   `output.emit_tasks`/`emit_facts` to print. Command files contain no SQL
+   and no business logic themselves.
+3. **`cli/context.py`** (`corvee_context`): resolves which SQLite file to
+   open (local project via `config.resolve_project()`, or the global
+   `~/.corvee/corvee.db` for `scope="global"`), opens it via
+   `db/connection.open_connection` (which also bootstraps/migrates the
+   schema), and wraps the command body in one transaction: `BEGIN IMMEDIATE`
+   for writes, plain `BEGIN` for reads, commit on success, rollback on any
+   exception. This is what gives multi-id commands like `task update 4 7 9`
+   their all-or-nothing property for free.
+4. **`db/*.py`**: raw `sqlite3` against the schema in `db/schema.py` (no
+   ORM). Each module owns one area: `tasks.py`, `facts.py`, `labels.py`,
+   `links.py`, `events.py`, `export_import.py`, `stats.py`. Mutating
+   functions here call into `guards/*.py` before writing (transition table,
+   parent/child cycle checks, claim conflicts, label patterns) and write the
+   corresponding `task_events`/`fact_events` row in the same call, so the
+   audit trail is not a separate step a caller can forget.
+5. **`guards/*.py`**: pure validation functions that raise
+   `errors.GuardViolationError`/`ClaimConflictError`/etc. Consult
+   `constants.py` for the data-driven rules (e.g. `TRANSITIONS`, a
+   `dict[State, frozenset[State]]`) rather than branching in code, so policy
+   changes are edits to one table.
+6. **`output.py`**: JSON array (or single object for `doctor`/`export`) vs.
+   fixed-width table rendering, `--fields` projection (`filter_fields`),
+   shared by every command group.
+
+Cross-cutting modules: `actor.py` resolves `$CORVEE_ACTOR`/
+`$CORVEE_SESSION_ID`. `config.py` walks up from cwd to find
+`.corvee/config.toml` (git-style) and resolves `db_path`. `timeutil.py` is
+the one place that formats the fixed-width UTC-with-milliseconds timestamps
+used everywhere on disk.
+
+**Scope.** Every task/fact lives in exactly one of two independent SQLite
+databases: the local project one (`.corvee/corvee.db`, pointed to by
+`.corvee/config.toml`) or one global database shared across the machine
+(`~/.corvee/corvee.db`, created lazily on first `--global` write). Scope is
+fixed at creation and encoded in the id itself (`TASK-14` vs
+`TASK-GLOBAL-14`), never passed as a separate flag on mutating commands. A
+merged read (`--scope all`, the default for listing) opens and closes one
+ordinary connection per database in turn, never a cross-database
+transaction.
+
+**Concurrency.** No daemon. Every invocation opens, does its transaction, and
+closes. WAL mode + `busy_timeout=5000` handle contention. Claims are a single
+conditional `UPDATE` checked by rows-affected. Full reasoning in
+`docs/concurrency.md` and spec §3.2/§3.3. Read that before touching
+`cli/context.py` or `db/connection.py`.
+
+**Exit codes.** `errors.py` defines one exception subclass per documented
+exit code (0 success, 1 internal, 2 usage, 3 not found, 4 claim conflict, 5
+guard violation, 6 project/config problem). Raise the matching subclass
+rather than a bare exception. `CorveeGroup.main()` is what turns it into the
+JSON-on-stderr shape and the process exit code.
+
+## Working here
+
+- TDD: write the failing test before the code that makes it pass.
+- No mocking SQLite. Tests run against a real database in `tmp_path`.
+- Every CLI command needs a `--help` epilog with at least three runnable
+  examples (enforced by a test).
+- Full type hints throughout. `ty` has zero tolerance for untyped public
+  signatures or unjustified `Any`.
+- Tests are classified by directory, not per-test decorators: `tests/unit`
+  (pure functions, no filesystem/db), `tests/acceptance` (through the CLI or
+  db layer against a real `tmp_path` SQLite database), `tests/e2e` (a real
+  `python -m corvee` subprocess). `conftest.py` applies the
+  `unit`/`acceptance`/`e2e` pytest marker automatically from
+  `item.path.parts`. Key shared fixtures: `project` (initialized project, cwd
+  inside it, `CORVEE_ACTOR` set), `runner` (`CliRunner`), `conn` (direct
+  connection to the project db), `add_task`/`add_fact` (create via CLI,
+  return the id).
+- Never run `corvee ... --global` directly in a shell against this
+  machine's real `~/.corvee/corvee.db` while manually poking at --global
+  behavior. Set `CORVEE_GLOBAL_DB=/some/scratch/path` first. The pytest
+  suite already isolates `$HOME` for you. This is only for ad hoc shell
+  commands outside it.
+- Commit one completed corvee task per commit, not a batch of several
+  tasks squashed into one. Finish the task (code, tests, docs, `hatch run
+  check` green, `corvee task comment`/`update --state done`), then commit
+  before starting the next one, so each commit maps onto one reviewable
+  unit of work and one task's audit trail.

corvee-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Requires Python 3.11+ and [Hatch](https://hatch.pypa.io/) (`uv` is used
+underneath as the installer).
+
+```bash
+hatch run test                  # run the test suite (parallel via pytest-xdist)
+hatch run cov                   # run the test suite with coverage
+hatch run lint                  # ruff check, via prek
+hatch run format                # black, via prek
+hatch run typecheck             # ty, via prek
+hatch run check                 # every prek hook + test
+hatch run mutate                # mutation testing against db/ and guards/,
+                                 # opt-in, not part of check/CI
+hatch run +py=3.12 test:test    # run the suite against one Python version
+                                 # from the test matrix (3.11-3.14)
+hatch run docs-serve            # serve the documentation locally
+hatch build                     # build sdist + wheel
+```
+
+`hatch run check` (or `prek run --all-files` directly) is the quality gate
+for any change. Run it before considering a change done.
+
+See [AGENTS.md](AGENTS.md) for the architecture, testing conventions, and
+the `corvee` task-tracking workflow this project uses on itself.
+
+## Before you open a PR
+
+Open an issue first and wait for a maintainer to approve it before starting
+a pull request. This applies to features and non-trivial fixes. A typo or
+other trivial fix can go straight to a PR. Approval keeps effort from being
+spent on work that doesn't fit the project's direction. PRs opened without an
+approved issue may be closed and asked to go through this process first.