coderio 0.4.3__tar.gz → 0.5.0__tar.gz

{coderio-0.4.3 → coderio-0.5.0}/.github/workflows/ci.yml

@@ -67,22 +67,40 @@ jobs:
 
       - name: Audit dependencies for known vulnerabilities
         # Scans installed packages against the PyPI advisory database.
-        # Non-blocking (continue-on-error) — reports issues without failing CI.
+        # BLOCKING since 2026-08-28 (audit finding: continue-on-error made the
+        # scan decorative — known CVEs could never turn CI red). If a flagged
+        # vuln is a false positive / unfixable, add an explicit --ignore-vuln
+        # with a comment rather than re-adding continue-on-error.
         shell: bash
-        continue-on-error: true
         run: |
           uv pip install pip-audit
           uv run pip-audit
 
       - name: Run tests with coverage
         # Enforces a coverage floor so coverage can't silently regress.
-        # The 70% floor is conservative (current baseline is ~75%) — it catches
-        # gross regressions (a module losing its tests) without failing on
-        # minor fluctuations. pyproject.toml's [tool.coverage.report]
-        # fail_under=60 is the local-dev default; CI enforces the stricter 70%.
+        # Measured baseline 2026-08-24: 82% total (weakest: sandbox_runner 43%
+        # — POSIX-only branches skip on Windows). The 75% floor keeps real
+        # headroom for platform variance while catching gross regressions
+        # (a module losing its tests). pyproject.toml's
+        # [tool.coverage.report] fail_under=60 is the local-dev default;
+        # CI enforces the stricter 75%.
         shell: bash
         run: |
-          uv run python -m pytest -q --cov=coderio --cov-report=term-missing --cov-fail-under=70
+          uv run python -m pytest -q --cov=coderio --cov-report=term-missing --cov-fail-under=75
+
+      - name: MCP extra smoke (install + loader import)
+        # The mcp extra was never installed in CI (audit 2026-09-04 P1-17):
+        # `load_mcp_tools_sync` — the code path behind README's "MCP support"
+        # — was never executed anywhere, in tests or CI. Install the extra
+        # from the frozen lock and at least run the loader test module
+        # against the real adapters package. One matrix leg is enough (the
+        # loader is pure Python; this step exists so the import path can't
+        # rot silently).
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          uv sync --frozen --extra dev --extra mcp
+          uv run python -c "from coderio.mcp_loader import load_mcp_tools_sync; print('mcp loader import OK')"
+          uv run python -m pytest tests/test_mcp_loader.py -q
 
       - name: Type check (mypy)
         # HARD GATE for clean modules. pyproject.toml's [[tool.mypy.overrides]]

{coderio-0.4.3 → coderio-0.5.0}/.github/workflows/release.yml

@@ -28,7 +28,18 @@ jobs:
   # workflow covers pushes/PRs, but a tag could be cut from a commit that
   # predates a fix; this gate makes the release itself fail loudly instead.
   test:
-    runs-on: ubuntu-latest
+    # Runs on ubuntu AND windows: windows-latest is the priority platform and
+    # a tag could otherwise ship a Windows-only regression (2026-08-28 audit).
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    env:
+      # Mirror ci.yml: Windows runners default to cp1252 and CJK output
+      # crashes with UnicodeEncodeError (audit finding #11).
+      PYTHONIOENCODING: utf-8
+      PYTHONUTF8: "1"
     steps:
       - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
@@ -94,10 +105,30 @@ jobs:
           /tmp/sdist-test-venv/bin/coderio --help
 
       - name: Create GitHub Release + attach artifacts
+        # Restored (2026-08-28 audit #3): the artifact refactor
+        # accidentally dropped Release creation while the header still
+        # promised it. dist/ is still in this job's workspace; the publish
+        # job downloads the same artifacts separately.
         uses: softprops/action-gh-release@v3
         with:
           generate_release_notes: true
-          files: dist/*.whl dist/*.tar.gz
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+
+      - name: Upload verified artifacts for publishing
+        # Pass the EXACT artifacts that were verified in the clean venvs to
+        # the publish job — the old flow REBUILT in publish-pypi, so PyPI
+        # could receive a different byte stream than the one verified above
+        # (2026-08-28 audit: non-deterministic build gap).
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 3
 
   publish-pypi:
     # PyPI via Trusted Publishing (OIDC) — no API token to manage or leak.
@@ -108,14 +139,13 @@ jobs:
     permissions:
       id-token: write  # OIDC token for Trusted Publishing
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-python@v7
+      - name: Download verified artifacts
+        # No rebuild: publish EXACTLY the wheel/sdist verified in the release
+        # job (2026-08-28 audit fix). No checkout needed either.
+        uses: actions/download-artifact@v4
         with:
-          python-version: "3.12"
-      - name: Build (same commit as the verified artifacts)
-        run: |
-          pip install build
-          python -m build
+          name: dist
+          path: dist
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:

coderio-0.5.0/.gitignore

@@ -0,0 +1,64 @@
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+
+# Testing / linting
+.pytest_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# coderio user data (project-local layer)
+.coderio/
+
+# Misc
+*.log
+.tmp/
+tmp/
+.zcode/
+
+# zcode workspace instructions — local only, not part of the project
+/AGENTS.md
+/AGENTS_EXAMPLE.md
+
+# Local audit/analysis artifacts — single-maintainer working notes (2026-09-02
+# review: 34 untracked items at repo root). Files stay on disk; git just
+# stops listing them. Delete manually when no longer wanted.
+/coderio-*analysis*.md
+/coderio-optimization-checklist-*.md
+/coderio-latest-test-report-*.md
+/coderio-detailed-analysis-*.md
+/coderio-project-analysis.md
+/coderio-vs-mainstream-agents-*.md
+/juejin-post-*.md
+/_test_subagent/
+/docs/blog/
+/hello.py
+/test.py
+
+# Local screenshots / assets at the repo root (not shipped docs images)
+/*.png
+!/docs/images/*.png

{coderio-0.4.3 → coderio-0.5.0}/CHANGELOG.md

@@ -6,6 +6,259 @@ All notable changes to coderio are documented here. The format follows
 `pyproject.toml`'s `[project].version` — `coderio.__version__` reads it via
 `importlib.metadata`.
 
+## [0.5.0] — 2026-09-04
+
+### Security — 2026-09-04 third-party audit batch (P0; each fix re-verified by an independent adversarial round, mutation-tested, and runtime-audited)
+
+An external third-party audit (report committed as `PROJECT_REVIEW_2026-09-04.md`)
+found five confirmed issues and three seam breaks where the implementation was
+weaker than the documentation's promise. All fixed and double-checked:
+
+- **P0-1 · command blacklist leaked plain (non-obfuscated) footguns.**
+  `${HOME}` brace expansion, any drive letter (`Remove-Item -Recurse D:\`,
+  `rd /s /q D:\data`) and UNC targets, PowerShell home spellings
+  (`$USERPROFILE` / `$env:USERPROFILE` / `%USERPROFILE%`), the documented
+  symbolic chmod modes (`a+rwx`, `ugo+rwx`) plus `7777`/`1777` supersets,
+  PowerShell `Stop-Computer`/`Restart-Computer`, `diskutil partitionDisk` /
+  `apfs delete*`, the `cp`/`shred`/`wipefs` raw-device family, named-function
+  fork bombs (`bomb(){ bomb|bomb & }; bomb`, newline-call variant), and the
+  `Remove-Item` pipeline form (`ls D:\ | ri -r`) — all blocked now. One false
+  positive fixed in the same pass: `git rm -r D:\proj` was caught by an alias
+  match at any token position; the PowerShell branch now matches only at the
+  segment head.
+- **P0-2 · web_fetch SSRF: shared-address ranges leaked.** `is_global`
+  depends on the CPython version (CVE-2024-4032 reclassified several ranges in
+  3.11.9/3.12.3), so on older 3.11 patch releases the Aliyun internal metadata
+  service (`100.100.200.200`, the classic SSRF payout) was fetchable. Explicit
+  CIDR blocks for 100.64/10, 192.0.0.0/24, 192.88.99.0/24, 198.18.0.0/15 —
+  version-independent — plus the `is_global` catch-all for everything else.
+- **P0-3 · VerifyGate counted `echo foo.py` as verification.** The
+  file-reference branch required only that the command MENTION a written file.
+  Now the segment must actually run it: an interpreter/runner head
+  (`python src/foo.py`, `uv run …`), the file itself as the command
+  (`./foo.py`), or a known verifier — with shell wrappers unwrapped first
+  (`bash -c 'echo foo.py'` is an echo), inline-code flags closing the segment
+  (`python -c "print('foo.py')"`, incl. `python -u -c`), and Windows
+  `.exe` spellings normalized. `cat`/`git diff`/`ls` mentions never verify.
+- **P0-4 · credentials: non-atomic write + corrupt file silently wiped keys.**
+  A crash mid-write truncated the TOML, `read_credentials` treated corrupt
+  files as empty, and the next save persisted that emptiness — every stored
+  key gone. Writes are now atomic (PID-unique temp file, permission-
+  restricted before key bytes land, `os.replace`); a corrupt file is backed up
+  to `.corrupt` before being rebuilt; `UnicodeDecodeError` (non-UTF-8
+  corruption) is caught explicitly — it previously crashed /setup outright.
+- **P0-5 · the Windows session lock was not mutually exclusive.**
+  `msvcrt.locking` locks at the current position and an append-mode handle
+  starts at open-time EOF — a holder appending under the lock grew the file,
+  so a later opener locked a different byte and both processes "held" the
+  lock (reproduced before the fix). The mutex is now byte [0,1) via
+  `seek(0)`; appends still land at the never-locked EOF; unlock targets the
+  range actually held.
+- **P0-6 · default-config execute could hang forever (Windows).** The plain
+  path used `subprocess.run(timeout=...)`, whose Windows timeout kills only
+  the direct child — grandchildren kept the pipes open and `communicate()`
+  waited for EOF indefinitely (the exact bug `tools/bash.py` had fixed; the
+  production path regressed it). Now Popen + `taskkill /T /F` tree kill (Job
+  fallback) + bounded reap, returning exit 124 at ~timeout; the old Job-at-
+  kill-time approach in `win_job` never contained pre-existing grandchildren.
+- **P0-7 · the documented `Z_API_KEY` path guaranteed an auth failure.**
+  Onboarding skip and the headless error both say "set Z_API_KEY", but
+  `_pick_api_key("anthropic")` read only `ANTHROPIC_API_KEY` — and every
+  coding-plan provider is anthropic-kind. `Z_API_KEY` now falls through
+  (Anthropic's own variable keeps precedence).
+
+### Fixed — P1 behavior defects + P2 hygiene (2026-09-04, same audit)
+
+- **P1-8** the bash probe cache was one class-level value: the first
+  instance's result shadowed every other instance's `[tools].bash_shell`
+  config for the whole process. Now keyed by the configured shell.
+- **P1-9** `activate_skill` returned only "Activated skill: X" — the playbook
+  body reached the system prompt one turn LATER (the docstring's
+  `on_activate_skill` callback never existed). The body now rides the tool
+  result (same-turn context), and re-activation re-supplies it (recovery
+  after context compaction).
+- **P1-10** PLAN mode wrote files: every successful `write_todos` mirrored
+  arbitrary todo content to `<project>/.coderio/plan.md` — bypassing the
+  read-only contract and `/undo`. Suppressed under a PLAN gate (todos still
+  work in memory); the PlanGate nudge no longer advertises the mirror there.
+- **P1-11** sandbox degradation is visible and honest: a degraded run
+  (Linux without bubblewrap) prefixes `[sandbox unavailable: …]` to the tool
+  output, and `auto_allow_if_sandboxed` now works only where the sandbox
+  actually provides a boundary — on macOS / Linux-without-bwrap / Linux job
+  mode it is disabled with a printed reason instead of yielding "zero
+  isolation + zero confirmation".
+- **P1-12** checkpoint `/undo` could silently restore an OLDER state: budget
+  eviction had no floor, so a newest snapshot over budget evicted itself.
+  The newest entry is now eviction-proof; files over the whole budget are
+  skipped with a warning; the multi-instance lost-update boundary is
+  documented.
+- **P1-13** TUI wedge: `worker.cancel()` landing between submit and thread
+  start finished the worker without running its `finally`, leaving
+  `_is_running` stuck True (every submit refused until restart). The stale
+  state is now detected and cleared (one resubmit); the in-flight guard is
+  not weakened, and `action_interrupt` no longer claims cancel() can unblock
+  a running thread.
+- **P1-14** the repo trust gate now covers `.coderio/commands/` and
+  `.coderio/agents/` — prompt templates injected into the model verbatim
+  deserve the same first-use confirmation as skills. NOTE for existing users:
+  repos that ship these directories will re-prompt once (trust is
+  content-keyed).
+- **P1-15** explicit sync-only middleware contract: all four production
+  middlewares inherit `SyncOnlyMiddleware`, and a contract test pins that no
+  async surface is defined (an overriding `aafter_model` was tested and
+  breaks even the sync path — langgraph wires the node differently).
+- **P1-18** multimodal prompts were `str(list)`'d in three places — hook
+  rejection persisted base64 garbage into the session (prompt text lost),
+  `/export` leaked image blobs into markdown, and the TUI encoded every
+  image twice per message. New `session.message.text_of_content` is the
+  single text view; `build_user_content` accepts pre-extracted images.
+- **P1-19** `win_sandbox` now checks `assign_to_job`'s return value (a
+  failure previously meant no resource caps and a dead timeout tree-kill,
+  silently); the `cmd /c` quoting/`$VAR` divergence between sandboxed and
+  plain runs is documented in the module docstring and README. Found during
+  the release gate itself: when the restricted-token launch dies during
+  initialization (NTSTATUS 0xC0000142 family with zero output — observed on
+  a windows-latest runner image roll), `run_sandboxed` now degrades to a
+  visibly-marked plain run instead of returning a mysterious crash code.
+- **P2 hygiene**: `neutralize_base_prompt` removed (deepagents 0.7.6
+  deprecated `BASE_AGENT_PROMPT` with zero internal consumption — the call
+  was a no-op that raised a LangChainDeprecationWarning every startup);
+  dead `render_markdown`/`render_error`/`render_tool_call` and the ghost
+  `on_truncated` protocol method removed; factory's duplicate custom-provider
+  branch collapsed; `HookSpec` caches its compiled matcher (was a fresh
+  re.compile per tool call per hook); hook `communicate` failures kill and
+  reap the child; model-facing `timeout` args bounded (web_fetch ≤ 600s,
+  bash ≤ 3600s).
+- **docs**: the architecture doc no longer describes the removed hand-written
+  loop (`run_step`/`_execute_turn` pseudocode), the deleted `[context]`
+  config section, or the `_invoke_tool` error-grading table; the data-flow
+  chapter follows the real deepagents middleware path; README/README_en
+  dropped the "auto-compaction (60% window trigger)" claim (no such knob);
+  the third-party report itself is committed as
+  `PROJECT_REVIEW_2026-09-04.md`.
+- **CI**: new `MCP extra smoke` leg (ubuntu/py3.12) installs the mcp extra
+  from the frozen lock and runs the loader tests against real adapters —
+  `load_mcp_tools_sync` had never been executed by any test or CI job.
+  Surfaced (and fixed) a pre-existing mypy error that only appears with the
+  py.typed adapters installed.
+
+### Added — 2026-09-03 review batch
+- **Confirm diff preview**: CONFIRM-mode prompts for write_file / edit_file /
+  multi_edit render a unified diff of the change (matching the real tool
+  semantics: replace_all, multi-match failure, multi_edit all-or-nothing).
+- **hooks environment whitelist**: hook subprocesses get CODERIO_* +
+  exec-resolution + temp/locale vars instead of the full os.environ.
+- **credentials hardening**: ACL-restricted before key bytes hit the disk;
+  icacls failures logged; corrupt credentials file no longer crashes /setup.
+- **AGENTS.md walk boundary**: falls back to the enclosing GIT root for
+  repos without coderio config (subdirectory launches keep nearest-wins).
+- **concurrent-submission guard** + interruptible permission wait + escaped
+  model-name retry in onboarding (`m` = change model) + `--version` flag.
+- ROADMAP.md / ROADMAP_en.md added (maintenance status, Now/Next/Later,
+  non-goals).
+
+### Fixed — audit-driven hardening (2026-08-28 + 2026-09-02 review batches)
+- **Command blacklist**: rebuilt segment/token parsing (multi-line, wrapper
+  shells incl. path-qualified and sudo-prefixed, PowerShell/cmd variants);
+  xargs-into-recursive-rm with flags in any position; `find -delete`/
+  `-exec rm` dangerous-root set widened to any absolute path, ~, $HOME, globs
+  (the `rm -rf /etc` blocked / `find /etc -delete` leaked double standard).
+- **Instruction injection**: the AGENTS.md walk is bounded at the launch dir
+  even when no workspace_root is configured (a parent directory's AGENTS.md
+  could previously leak into every project launched from below it).
+- **Hooks**: subprocess environment is now a whitelist (CODERIO_* + exec
+  resolution + temp/locale) instead of a full os.environ copy — repo hooks
+  can no longer read environment secrets; hooks stdout contract documented
+  (raw stdout injects for SessionStart/UserPromptSubmit, no JSON parsing).
+- **Credentials**: the file is created and ACL-restricted BEFORE any key
+  bytes hit the disk (write-then-restrict window closed); icacls failures
+  are logged; a missing Windows username skips inheritance-stripping
+  instead of producing a file nobody can read.
+- **TUI/engine**: a turn in flight no longer accepts a second submission
+  (concurrent engine threads interleaved session writes); Esc now breaks a
+  pending permission-prompt wait (previously blocked up to 120s); interrupt
+  drops the thread checkpoint (dangling tool_calls state) — now regression
+  tested.
+- **run**: timeout path logs why the daemon thread survives and how
+  `[tools].sandbox_mode = "job"` reaps the process tree; headless stdout
+  writes survive interpreter teardown.
+
+### Changed — structure (P2 decomposition, behavior-preserving)
+- `run_deep_agent` decomposed: `TurnSpec` dataclass (15 kwargs → 1 spec),
+  `build_middleware/build_backend/build_subagents` builders, module-level
+  `make_shell_backend` factory; body ≤80 lines, behavior pinned by the
+  existing suite + adversarial equivalence review.
+- `CoderioTUI` (1380 → 983 lines): StreamHandler protocol, agent-thread
+  state, render queue and confirmation wait extracted to
+  `cli/stream_controller.py`; every bare `except: pass` in tui.py now logs.
+- `build_turn_spec` in cli/repl.py is the single CommandPolicy/TurnSpec
+  construction path for headless and TUI runs (was two field-identical
+  copies).
+- Tool-name registry (`tools/taxonomy.py`) is now the literal single source:
+  web_search registered, permission/harness literals re-pointed, the two
+  bash→execute prose regexes merged, the shim removed.
+- tests/e2e filled (5 black-box CLI tests); app.py coverage 36%→95%,
+  tui_runtime.py 35%→96%.
+
+### Added
+- AGENTS.md / CLAUDE.md project instructions injected into the system
+  prompt (nearest-wins, bounded at the project root / git root).
+- Tool-name registry `tools/taxonomy.py` — one definition of engine/harness
+  names and categories (was 6+ drifting ad-hoc copies, the root cause of
+  several recorded P0s).
+- `--version` flag.
+- docs/CONFIG.md — full config.toml field reference, hooks syntax,
+  .mcp.json fields, custom agents/commands, trust mechanism.
+
+### Deprecated / Removed
+- Removed half-demolished relics: [context] config section, RichStream,
+  phase-timeline dead branches, to_langchain_tools passthrough (P2-8 batch).
+- README: removed the Claude Code / aider comparison table; honest
+  macOS-sandbox disclosure added to Known limitations.
+
+## [0.4.4] — 2026-08-24
+
+### Added — extensibility & safety-of-agency features (each adversarially reviewed, mutation-verified)
+- **Custom slash commands**: `.coderio/commands/*.md` (project layer overrides user layer)
+  turn prompt templates into `/commands` with `$ARGUMENTS` substitution and optional
+  frontmatter descriptions. Built-ins can never be shadowed — exact matches refused at
+  expansion, case variants dropped at discovery (Windows case-insensitive-FS spoof
+  surface). Bodies route straight to the engine, never re-enter built-in dispatch: a
+  repo file with body `/mode full` cannot flip the permission gate.
+- **Custom subagents**: `.coderio/agents/*.md` define personas invokable via
+  `task(subagent_type=...)`. Persona-only customization — every assembled spec rides
+  the same PLAN-gated read-only middleware stack as the built-in research agent;
+  reserved names dropped at discovery AND re-filtered at wiring time. Adversarially
+  verified end-to-end: write tools physically unbound, nested task() blocked on three
+  independent layers.
+- **File checkpoints + `/undo`**: every structured write (write_file/edit_file/
+  multi_edit) snapshots the target's pre-write state; `/undo` reverts step by step.
+  multi_edit is one undo step; error paths consume no depth; failed restores re-push
+  for retry; bounded at 50 entries / 64MB; deliberately survives /clear. Shell-side
+  writes (redirects) bypass it — OS sandboxing is the layer for that class.
+- **Plan artifact**: the todo list mirrors to `<project>/.coderio/plan.md` after every
+  successful write_todos; user edits between messages are adopted at next turn start
+  (human override wins) with an injected note so the model doesn't execute a stale plan.
+
+### Fixed
+- Three prompt surfaces (PlanGate nudge, CompletionGate force-continue, CODE-workflow)
+  directed the model to coderio's legacy `todo()` tool whose store is an orphan the
+  gates never check — completion instructions could loop forever. All now point at
+  `write_todos`, the canonical surface.
+- Custom-command discovery anchor joined at the caller after a runtime audit caught
+  production loading zero commands while globbing root-level *.md files as agents.
+- Subagent discovery anchors walk up to the project root like skills/config/trust
+  (launching from a repo subdirectory previously missed project-layer definitions).
+- Frontmatter descriptions are truncated to 1024 chars and control-char-stripped —
+  a 90KB description previously reached the main model verbatim every turn.
+
+### Changed
+- CI coverage floor raised 70% → 75% against a measured 82% baseline (gate verified
+  to trip); stale coverage comments corrected.
+- tui.py decomposed (1627 → 1332 lines): input dispatch + session lifecycle extracted
+  to testable TuiRuntime; behavior verified statement-equivalent by AST diff + real
+  Textual input-routing tests.
+
 ## [0.4.3] — 2026-08-21
 
 ### Security — P1/P2 hardening (audit-verified, adversarial + mutation tested)
@@ -563,7 +816,13 @@ All notable changes to coderio are documented here. The format follows
 - Rich stream UI + Textual TUI with foldable thinking.
 - jsonl session persistence with compression truncation.
 
-[Unreleased]: https://github.com/Lion-1209/coderio/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Lion-1209/coderio/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Lion-1209/coderio/compare/v0.4.4...v0.5.0
+[0.4.4]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.4
+[0.4.3]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.3
+[0.4.2]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.2
+[0.4.1]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.1
+[0.4.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.0
 [0.3.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.3.0
 [0.2.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.2.0
 [0.1.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.1.0

{coderio-0.4.3 → coderio-0.5.0}/CONTRIBUTING.md

@@ -6,16 +6,22 @@ Thanks for your interest in contributing! This guide covers the basics.
 
 ## Development setup
 
+The project uses [uv](https://docs.astral.sh/uv/) for dependency management
+(locked via `uv.lock`, same as CI). Python 3.11+ required.
+
 ```bash
 git clone <repo-url> coderio
 cd coderio
-python -m venv .venv
+uv sync --frozen                 # creates .venv from the lockfile
+uv run pytest -q                 # run anything inside the managed venv
+```
 
-# Windows (Git Bash)
-.venv/Scripts/python.exe -m pip install -e ".[dev]"
+With the venv activated (`.venv/Scripts/activate` on Windows,
+`.venv/bin/activate` elsewhere) the plain commands work too:
 
-# Linux / macOS
-.venv/bin/python -m pip install -e ".[dev]"
+```bash
+python -m pytest -q
+python -m ruff check src tests
 ```
 
 Set your API key: