worktree-shield 0.1.0__tar.gz

worktree_shield-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BhuwanJoshi-01
+
+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.

worktree_shield-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: worktree-shield
+Version: 0.1.0
+Summary: Audit parallel Git worktrees for shared ports, databases and Docker resources before your agents collide.
+Keywords: git,worktree,ai-agents,docker-compose,ports,sarif,ci,linter
+Author: BhuwanJoshi-01
+Author-email: BhuwanJoshi-01 <bhuwanj779@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://bhuwanjoshi-01.github.io/worktree-shield/
+Project-URL: Documentation, https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/cli.md
+Project-URL: Source, https://github.com/BhuwanJoshi-01/worktree-shield
+Project-URL: Issues, https://github.com/BhuwanJoshi-01/worktree-shield/issues
+Project-URL: Changelog, https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Worktree Shield
+
+**Audit parallel Git worktrees for shared ports, databases and Docker resources before your agents collide.**
+
+[![CI](https://github.com/BhuwanJoshi-01/worktree-shield/actions/workflows/ci.yml/badge.svg)](https://github.com/BhuwanJoshi-01/worktree-shield/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/LICENSE)
+[![Website](https://img.shields.io/badge/website-worktree--shield-1e1e24.svg)](https://bhuwanjoshi-01.github.io/worktree-shield/)
+
+> **Status:** 0.1.0 is the first release. It is tested on Linux and Windows; reports from macOS and from your own
+> worktree setups are very welcome. See the [roadmap](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/roadmap.md).
+
+Git worktrees give every agent or task its own checkout, but not its own infrastructure. Three worktrees can still
+start a dev server on the same port, migrate the same `app_dev` database, reuse one Docker Compose project name or
+write to the same absolute folder:
+
+```text
+repo-main/              API -> :8000     DB -> postgres://localhost/app_dev
+repo-feature-login/     API -> :8000     DB -> postgres://localhost/app_dev
+repo-feature-billing/   API -> :8001     DB -> postgres://localhost/app_dev
+```
+
+Worktree Shield finds these shared resources in worktrees that **already exist**, however they were created
+(plain `git worktree`, a worktree manager or a coding agent), and reports each one with the file and line it came
+from and how certain the collision is.
+
+## Install
+
+Needs Python 3.11 or newer and Git.
+
+```bash
+uv tool install git+https://github.com/BhuwanJoshi-01/worktree-shield   # until the PyPI release
+pipx install git+https://github.com/BhuwanJoshi-01/worktree-shield      # or with pipx
+```
+
+## Use
+
+```bash
+worktree-shield scan                 # all worktrees of the current repository, read-only
+worktree-shield scan --strict        # exit 1 when a finding fails under the policy, for CI and agent preflight
+worktree-shield scan --scope static  # configuration only; leave running processes alone
+worktree-shield plan                 # one change per worktree that would resolve it; never applied
+worktree-shield explain WTS-PORT-001 # what a finding means and how to fix it
+worktree-shield policy               # the policy in .worktree-shield.toml, checked, or the defaults
+worktree-shield resources            # every port, database, Compose name and path each worktree declares
+worktree-shield report --format sarif --output conflicts.sarif   # also markdown, json
+worktree-shield scan --strict --format json                      # for agents and scripts
+```
+
+![worktree-shield scan on three worktrees that share a port, a database and a Compose project](https://raw.githubusercontent.com/BhuwanJoshi-01/worktree-shield/main/docs/images/scan.svg)
+
+Try it on a repository built to collide:
+
+```bash
+python examples/conflicting-worktrees/build.py /tmp/wts-demo
+worktree-shield scan --repo /tmp/wts-demo/app --scope static
+```
+
+## In CI
+
+A CI checkout is a single worktree, so the GitHub Action checks this branch out next to another ref, as a second
+worktree, and reports what the two would share:
+
+```yaml
+jobs:
+  worktree-shield:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write   # for upload-sarif
+    steps:
+      - uses: actions/checkout@v7
+      - uses: BhuwanJoshi-01/worktree-shield@v0.1.0
+        with:
+          compare-with: main     # refs to check out next to this branch
+          strict: "true"         # fail when a finding fails under .worktree-shield.toml
+      - uses: github/codeql-action/upload-sarif@v4
+        if: always()             # upload the report even when the scan failed the job
+        with:
+          sarif_file: worktree-shield.sarif
+```
+
+The scan in CI is static: running processes on a runner say nothing about your machine.
+
+## What it promises
+
+- **Read-only.** It never writes to your worktrees or `.git`, never prunes, kills, starts containers or touches
+  databases.
+- **Nothing from the repository runs.** Config files are parsed as data; package scripts, Git hooks, Vite configs
+  and Compose are never executed. Docker doesn't need to be running.
+- **No secrets in output.** Database URLs are reduced to host, port and database name as soon as they are read.
+  `.env` files are only read when you opt in.
+- **Honest certainty.** Two worktrees declaring the same port is a *probable* collision; it is *confirmed* only when
+  a running process proves it. Intentionally shared infrastructure (one Postgres for everyone) can be allowed by
+  policy.
+- No network access, no telemetry.
+
+## Alternatives
+
+Worktree managers can avoid collisions when they create the worktrees:
+[workz](https://github.com/rohansx/workz) allocates ports, database names and Compose project names, and
+[worktree-compose](https://github.com/mostafasudo/worktree-compose) checks port collisions between the worktrees it
+manages with `wtc doctor`. Worktree Shield doesn't create anything; it audits whatever is already there, with a
+policy file, CI exit codes and SARIF.
+
+## Documentation
+
+- [Command reference](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/cli.md) and exit codes
+- [Rules](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/rules.md): every finding ID, what decides its status, how to fix it
+- [Policy file](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/policy.md): `.worktree-shield.toml`
+- [What is read](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/what-is-read.md), and what never is
+- [JSON, SARIF and Markdown output](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/json-output.md), with [sample reports](https://github.com/BhuwanJoshi-01/worktree-shield/tree/main/docs/sample-reports)
+- [Architecture](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/architecture.md), [privacy](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/privacy.md), [troubleshooting](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/troubleshooting.md)
+
+## License
+
+[MIT](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/LICENSE)

worktree_shield-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Worktree Shield
+
+**Audit parallel Git worktrees for shared ports, databases and Docker resources before your agents collide.**
+
+[![CI](https://github.com/BhuwanJoshi-01/worktree-shield/actions/workflows/ci.yml/badge.svg)](https://github.com/BhuwanJoshi-01/worktree-shield/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/LICENSE)
+[![Website](https://img.shields.io/badge/website-worktree--shield-1e1e24.svg)](https://bhuwanjoshi-01.github.io/worktree-shield/)
+
+> **Status:** 0.1.0 is the first release. It is tested on Linux and Windows; reports from macOS and from your own
+> worktree setups are very welcome. See the [roadmap](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/roadmap.md).
+
+Git worktrees give every agent or task its own checkout, but not its own infrastructure. Three worktrees can still
+start a dev server on the same port, migrate the same `app_dev` database, reuse one Docker Compose project name or
+write to the same absolute folder:
+
+```text
+repo-main/              API -> :8000     DB -> postgres://localhost/app_dev
+repo-feature-login/     API -> :8000     DB -> postgres://localhost/app_dev
+repo-feature-billing/   API -> :8001     DB -> postgres://localhost/app_dev
+```
+
+Worktree Shield finds these shared resources in worktrees that **already exist**, however they were created
+(plain `git worktree`, a worktree manager or a coding agent), and reports each one with the file and line it came
+from and how certain the collision is.
+
+## Install
+
+Needs Python 3.11 or newer and Git.
+
+```bash
+uv tool install git+https://github.com/BhuwanJoshi-01/worktree-shield   # until the PyPI release
+pipx install git+https://github.com/BhuwanJoshi-01/worktree-shield      # or with pipx
+```
+
+## Use
+
+```bash
+worktree-shield scan                 # all worktrees of the current repository, read-only
+worktree-shield scan --strict        # exit 1 when a finding fails under the policy, for CI and agent preflight
+worktree-shield scan --scope static  # configuration only; leave running processes alone
+worktree-shield plan                 # one change per worktree that would resolve it; never applied
+worktree-shield explain WTS-PORT-001 # what a finding means and how to fix it
+worktree-shield policy               # the policy in .worktree-shield.toml, checked, or the defaults
+worktree-shield resources            # every port, database, Compose name and path each worktree declares
+worktree-shield report --format sarif --output conflicts.sarif   # also markdown, json
+worktree-shield scan --strict --format json                      # for agents and scripts
+```
+
+![worktree-shield scan on three worktrees that share a port, a database and a Compose project](https://raw.githubusercontent.com/BhuwanJoshi-01/worktree-shield/main/docs/images/scan.svg)
+
+Try it on a repository built to collide:
+
+```bash
+python examples/conflicting-worktrees/build.py /tmp/wts-demo
+worktree-shield scan --repo /tmp/wts-demo/app --scope static
+```
+
+## In CI
+
+A CI checkout is a single worktree, so the GitHub Action checks this branch out next to another ref, as a second
+worktree, and reports what the two would share:
+
+```yaml
+jobs:
+  worktree-shield:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write   # for upload-sarif
+    steps:
+      - uses: actions/checkout@v7
+      - uses: BhuwanJoshi-01/worktree-shield@v0.1.0
+        with:
+          compare-with: main     # refs to check out next to this branch
+          strict: "true"         # fail when a finding fails under .worktree-shield.toml
+      - uses: github/codeql-action/upload-sarif@v4
+        if: always()             # upload the report even when the scan failed the job
+        with:
+          sarif_file: worktree-shield.sarif
+```
+
+The scan in CI is static: running processes on a runner say nothing about your machine.
+
+## What it promises
+
+- **Read-only.** It never writes to your worktrees or `.git`, never prunes, kills, starts containers or touches
+  databases.
+- **Nothing from the repository runs.** Config files are parsed as data; package scripts, Git hooks, Vite configs
+  and Compose are never executed. Docker doesn't need to be running.
+- **No secrets in output.** Database URLs are reduced to host, port and database name as soon as they are read.
+  `.env` files are only read when you opt in.
+- **Honest certainty.** Two worktrees declaring the same port is a *probable* collision; it is *confirmed* only when
+  a running process proves it. Intentionally shared infrastructure (one Postgres for everyone) can be allowed by
+  policy.
+- No network access, no telemetry.
+
+## Alternatives
+
+Worktree managers can avoid collisions when they create the worktrees:
+[workz](https://github.com/rohansx/workz) allocates ports, database names and Compose project names, and
+[worktree-compose](https://github.com/mostafasudo/worktree-compose) checks port collisions between the worktrees it
+manages with `wtc doctor`. Worktree Shield doesn't create anything; it audits whatever is already there, with a
+policy file, CI exit codes and SARIF.
+
+## Documentation
+
+- [Command reference](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/cli.md) and exit codes
+- [Rules](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/rules.md): every finding ID, what decides its status, how to fix it
+- [Policy file](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/policy.md): `.worktree-shield.toml`
+- [What is read](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/what-is-read.md), and what never is
+- [JSON, SARIF and Markdown output](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/json-output.md), with [sample reports](https://github.com/BhuwanJoshi-01/worktree-shield/tree/main/docs/sample-reports)
+- [Architecture](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/architecture.md), [privacy](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/privacy.md), [troubleshooting](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/troubleshooting.md)
+
+## License
+
+[MIT](https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/LICENSE)

worktree_shield-0.1.0/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "worktree-shield"
+version = "0.1.0"
+description = "Audit parallel Git worktrees for shared ports, databases and Docker resources before your agents collide."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "git",
+    "worktree",
+    "ai-agents",
+    "docker-compose",
+    "ports",
+    "sarif",
+    "ci",
+    "linter",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "psutil>=7.2.2",
+    "pyyaml>=6.0.3",
+    "rich>=15.0.0",
+    "typer>=0.27.3",
+]
+
+[[project.authors]]
+name = "BhuwanJoshi-01"
+email = "bhuwanj779@gmail.com"
+
+[project.urls]
+Homepage = "https://bhuwanjoshi-01.github.io/worktree-shield/"
+Documentation = "https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/cli.md"
+Source = "https://github.com/BhuwanJoshi-01/worktree-shield"
+Issues = "https://github.com/BhuwanJoshi-01/worktree-shield/issues"
+Changelog = "https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/CHANGELOG.md"
+
+[project.scripts]
+worktree-shield = "worktree_shield.cli:main"
+wtshield = "worktree_shield.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.170.14",
+    "jsonschema>=4.26.0",
+    "mypy>=2.4.1",
+    "pytest>=9.2.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.3",
+    "types-psutil>=7.2.2.20260906",
+    "types-pyyaml>=6.0.12.20261103",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "C4",
+    "PTH",
+    "S",
+    "PT",
+    "RUF",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = [
+    "worktree_shield",
+    "tests",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "S104",
+    "S105",
+    "S106",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]
+xfail_strict = true
+
+[tool.coverage.run]
+source = ["worktree_shield"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true

worktree_shield-0.1.0/pyproject.toml.orig

@@ -0,0 +1,110 @@
+[project]
+name = "worktree-shield"
+version = "0.1.0"
+description = "Audit parallel Git worktrees for shared ports, databases and Docker resources before your agents collide."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "BhuwanJoshi-01", email = "bhuwanj779@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["git", "worktree", "ai-agents", "docker-compose", "ports", "sarif", "ci", "linter"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "psutil>=7.2.2",
+    "pyyaml>=6.0.3",
+    "rich>=15.0.0",
+    "typer>=0.27.3",
+]
+
+[project.urls]
+Homepage = "https://bhuwanjoshi-01.github.io/worktree-shield/"
+Documentation = "https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/docs/cli.md"
+Source = "https://github.com/BhuwanJoshi-01/worktree-shield"
+Issues = "https://github.com/BhuwanJoshi-01/worktree-shield/issues"
+Changelog = "https://github.com/BhuwanJoshi-01/worktree-shield/blob/main/CHANGELOG.md"
+
+[project.scripts]
+worktree-shield = "worktree_shield.cli:main"
+wtshield = "worktree_shield.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.170.14",
+    "jsonschema>=4.26.0",
+    "mypy>=2.4.1",
+    "pytest>=9.2.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.3",
+    "types-psutil>=7.2.2.20260906",
+    "types-pyyaml>=6.0.12.20261103",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F",  # pycodestyle, pyflakes
+    "I",            # import order
+    "B",            # bugbear
+    "UP",           # pyupgrade
+    "SIM",          # simplify
+    "C4",           # comprehensions
+    "PTH",          # pathlib
+    "S",            # bandit: subprocesses and secret handling must be deliberate
+    "PT",           # pytest style
+    "RUF",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["worktree_shield", "tests"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",  # assert is how pytest works
+    "S104",  # bind addresses such as 0.0.0.0 are test data, nothing binds them
+    "S105", "S106",  # fake secrets are the point of the redaction tests
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+xfail_strict = true
+
+[tool.coverage.run]
+source = ["worktree_shield"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true

worktree_shield-0.1.0/src/worktree_shield/__init__.py

@@ -0,0 +1,8 @@
+"""Worktree Shield: audit parallel Git worktrees for shared resources."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("worktree-shield")
+except PackageNotFoundError:  # imported from a source tree that was never installed
+    __version__ = "0+unknown"

worktree_shield-0.1.0/src/worktree_shield/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m worktree_shield``."""
+
+from worktree_shield.cli import main
+
+if __name__ == "__main__":
+    main()