sourcepack 1.10.0a0__py3-none-any.whl

sourcepack-1.10.0a0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: sourcepack
+Version: 1.10.0a0
+Summary: Local-first guardrail for unsupported AI repository assumptions before commit.
+License-Expression: MIT
+Keywords: ai,git,developer-tools,guardrails,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<img width="1800" height="620" alt="sourcepack-hero" src="https://github.com/user-attachments/assets/9b4af0df-1cfc-4aa8-8eb1-f673e6eb2e52" />
+
+AI coding tools can edit files, add imports, invent commands, or assume project structure that is not actually present. SourcePack checks AI-generated repo changes against trusted local repo evidence before commit.
+
+## Badges
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Package: local editable](https://img.shields.io/badge/package-local%20editable-blue)
+
+## Quick demo
+
+A small RED case: an AI change imports `fastapi`, but the repository does not declare `fastapi` in its dependency files.
+
+```bash
+$ sourcepack init . --auto
+$ printf 'from fastapi import FastAPI\n' > app.py
+$ git add app.py
+$ git commit -m "add API"
+RED LIGHT: commit blocked
+unsupported_dependency: app.py imports fastapi, but fastapi is not declared.
+
+Fix:
+- add fastapi intentionally to pyproject.toml
+- or remove the import
+- run sourcepack report open for details
+```
+
+Then inspect the human report:
+
+```bash
+sourcepack report open
+```
+
+## Product screenshot section
+
+Screenshot assets are generated from deterministic golden demo outputs and should be committed at these paths when refreshed:
+
+- `docs/assets/sourcepack-terminal-red.png` — terminal output from `fail-unsupported-dependency`.
+- `docs/assets/sourcepack-red-report.png` — HTML report from `fail-unsupported-dependency`.
+- `docs/assets/sourcepack-warn-report.png` — HTML report from `warn-new-file`.
+- `docs/assets/sourcepack-pass-report.png` — HTML report from `pass-clean`.
+
+See [`docs/assets/README.md`](docs/assets/README.md) for exact capture instructions. If these image files are absent, the paths above are expected screenshot targets, not claimed live screenshots.
+
+## Install
+
+Current local editable install:
+
+```bash
+python -m pip install -e .
+```
+
+SourcePack is not documented here as a published PyPI package. Planned package install commands such as `pipx install sourcepack`, `uv tool install sourcepack`, or `pip install sourcepack` should only be advertised after publication is true from release metadata.
+
+## Quick start
+
+```bash
+sourcepack init . --auto
+# make or receive AI changes
+sourcepack diff .
+sourcepack report open
+# if accepted, continue with normal git commit
+git commit -m "your change"
+```
+
+Local policy:
+
+- PASS exits `0`.
+- WARN exits `0` locally.
+- WARN exits nonzero with `--strict` or `--ci`.
+- FAIL exits nonzero.
+
+## How SourcePack works
+
+SourcePack keeps trusted repo evidence separate from AI guidance:
+
+- Baseline = the last trusted repo state.
+- Prompt context = AI guidance only.
+- Prompt context never becomes trust.
+- `sourcepack diff` checks actual repo changes against the baseline.
+
+Without baseline/prompt separation:
+
+- AI prompt context says `deploy.sh` exists and uses port `8080`.
+- That claim gets treated as trusted evidence.
+- AI edits against a fake deploy script.
+- The guardrail launders an AI claim into repo truth.
+
+With SourcePack:
+
+- Prompt context is only guidance.
+- `.sourcepack/baseline/` is enforcement trust.
+- If `deploy.sh` is not in the trusted baseline, the edit fails.
+- AI-generated context cannot bless its own assumptions.
+
+
+## Baseline lifecycle
+
+SourcePack enforcement depends on a reviewed `.sourcepack/baseline/`, while `.sourcepack/prompt/` remains AI guidance only. CI should consume committed baseline state and must not create or update trusted baseline state automatically. See [`docs/baseline-lifecycle.md`](docs/baseline-lifecycle.md) for safe local and PR flows.
+
+## Public-alpha readiness
+
+Public-alpha readiness is tracked in [`docs/public-alpha-readiness.md`](docs/public-alpha-readiness.md). SourcePack is a local evidence guardrail; it does not prove code correctness, security, dependency safety, runtime success, semantic validity, external API truth, or user intent.
+
+## What SourcePack catches
+
+| Case | Local result | Reason code |
+| --- | --- | --- |
+| Missing/fake file edits | FAIL | `missing_file` |
+| New file review | WARN | `new_file` |
+| Deleted file review | WARN | `deleted_file` |
+| Undeclared imports/dependencies | FAIL | `unsupported_dependency` |
+| Same-patch dependency additions | WARN | `declared_dependency` |
+| Unsupported commands | FAIL | `unsupported_command` |
+| Unsupported ecosystems | WARN | `unsupported_ecosystem` |
+| Protected `.sourcepack/` edits | FAIL | `protected_artifact` |
+| `.git/` path edits | FAIL | `git_path_modification` |
+| Unsafe paths | FAIL | `unsafe_path` |
+| Binary diffs | WARN or FAIL for high-risk paths | `binary_diff` |
+| Malformed diffs | FAIL | `malformed_diff` |
+| Missing/stale/corrupt baseline | FAIL or WARN depending on state and mode | `baseline_missing`, `baseline_stale`, `baseline_corrupt` |
+
+See [`docs/reason-codes.md`](docs/reason-codes.md) for reason-code behavior and fixes.
+
+## What SourcePack does not claim
+
+- Does not prove code correctness.
+- Does not prove security.
+- Does not replace tests.
+- Does not understand full program semantics.
+- Does not require cloud access.
+- Does not upload repo contents.
+
+## Commands
+
+Documented user-facing commands that exist in the current CLI:
+
+```bash
+sourcepack init . --auto
+sourcepack diff .
+sourcepack diff . --json
+sourcepack diff . --strict
+sourcepack diff . --ci
+sourcepack prompt . "task" --copy
+sourcepack baseline .
+sourcepack baseline . --refresh
+sourcepack report path
+sourcepack report open
+sourcepack status .
+sourcepack exec -- pytest
+sourcepack evidence list
+sourcepack evidence show <entry-id>
+sourcepack evidence clear
+sourcepack doctor
+sourcepack doctor --strict
+sourcepack demo
+```
+
+Hook management commands also exist for explicit maintenance:
+
+```bash
+sourcepack install-hook .
+sourcepack uninstall-hook .
+```
+
+## Local execution evidence
+
+`sourcepack exec -- <command...>` runs a local command and records bounded evidence under `.sourcepack/evidence/ledger.jsonl`. Ledger entries store command metadata, exit code, stdout/stderr SHA-256 hashes, short excerpts, git head, dirty-worktree state before and after execution, duration, and a small environment summary. They do not store full logs by default and are local-only. Command output can still contain sensitive information, so review `.sourcepack/evidence/` before sharing it.
+
+Use:
+
+```bash
+sourcepack exec -- pytest
+sourcepack evidence list
+sourcepack evidence show <entry-id>
+sourcepack evidence clear
+sourcepack evidence export --json
+```
+
+Execution evidence only supports bounded claims that a command was run locally. It does not prove code correctness, security, or external API behavior. Prompt context in `.sourcepack/prompt/` remains advisory and cannot satisfy execution evidence.
+
+## Local reports
+
+`sourcepack diff .` writes local report artifacts under `.sourcepack/reports/`:
+
+- `.sourcepack/reports/latest.html`
+- `.sourcepack/reports/latest.json`
+- `.sourcepack/reports/latest.md`
+
+Use:
+
+```bash
+sourcepack report path
+sourcepack report open
+```
+
+HTML is for humans. JSON is for automation and remains JSON-only on stdout when `sourcepack diff . --json` is used.
+
+## Git hooks
+
+`sourcepack init . --auto` installs hooks when possible in a Git repository.
+
+- The pre-commit hook checks staged changes with `sourcepack diff . --staged`.
+- The post-commit hook refreshes the baseline only after clean commits.
+- If the working tree is dirty after a commit, SourcePack marks the baseline stale instead of silently trusting it.
+- To uninstall hooks, run `sourcepack uninstall-hook .`.
+
+## CI
+
+The included GitHub Actions workflow installs SourcePack in editable mode, runs unit and pytest gates, runs the behavior matrix, and checks `sourcepack doctor` plus `sourcepack demo`.
+
+Safe CI usage for projects that intentionally manage a trusted baseline:
+
+```yaml
+- uses: actions/checkout@v4
+- run: python -m pip install -e .
+- run: sourcepack diff . --ci
+```
+
+`sourcepack diff . --ci` implies strict JSON output and exits nonzero for WARN or FAIL. CI must not establish trust automatically: if no trusted baseline exists, CI fails until a baseline strategy is intentionally created outside CI.
+
+## Validation
+
+Current validation is local and deterministic. `sourcepack doctor --strict` performs a production-readiness health check and fails on missing runtime prerequisites or packaged assets:
+
+- Hosted GitHub Actions workflow is the source of truth for hosted checks.
+- The behavior matrix covers canonical repo-state transitions.
+- The simulation harness validates local workflow transitions.
+- Gauntlet and smoke tests cover CLI and report behavior.
+- The optional real-corpus harness is available in `tools/real_corpus_validation.py` for caller-provided repositories.
+
+The primary proof unit is a repo-state transition, not a random repository.
+
+## Status
+
+v1.10.0-alpha: local-first alpha. Core judgment behavior is validated. Packaging, reports, demos, and UX polish are active areas.
+
+## Public-alpha checklist
+
+Before public alpha, verify:
+
+- Install works from a clean environment.
+- `sourcepack --version` works.
+- `sourcepack doctor` works.
+- `sourcepack demo` works.
+- `sourcepack init . --auto` works.
+- `sourcepack diff .` works.
+- `sourcepack report open` or `sourcepack report path` works.
+- Behavior matrix passes.
+- Golden demos pass.
+- Known limitations are documented.
+- Do not claim PyPI publication unless SourcePack is actually published there.
+
+
+## CI and editor planning
+
+See `docs/ci.md` for CI usage and `docs/vscode-extension-plan.md` for the VS Code extension plan.
+
+## GitHub Action
+
+SourcePack includes a composite GitHub Action that runs the existing `sourcepack` CLI in CI. It packages the CLI behavior; it does not create a second implementation of SourcePack judgment logic.
+
+Minimal workflow:
+
+```yaml
+name: SourcePack
+
+on:
+  pull_request:
+
+jobs:
+  sourcepack:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        with:
+          mode: ci
+          # fail-on-warn: 'true'
+```
+
+Baseline trust rule: CI consumes `.sourcepack/baseline/`. CI does not create, refresh, bless, or update trusted baseline state automatically. If the baseline is missing, the Action fails closed with `SourcePack baseline not found` and explains that CI will not create or update trusted baseline state automatically. Maintainers should create or refresh baselines locally or in a separate trusted maintainer-controlled setup workflow before relying on PR checks.
+
+The Action writes report artifacts to `sourcepack-report` by default, including `sourcepack.json`, `sourcepack.md`, `sourcepack.stderr.txt`, `sourcepack.stdout.txt`, and `sourcepack-command.txt` when available. `RED`/`FAIL` exits nonzero. `WARN` follows the selected CLI mode: `ci` and `strict` fail on WARN, while `local` does not unless `fail-on-warn: 'true'` is set.
+
+Before pushing, run SourcePack locally with:
+
+```bash
+sourcepack --version
+sourcepack doctor
+sourcepack diff . --json
+```
+
+Current limitations: PR commenting is future work and is not implemented by this Action. Unsupported ecosystems remain YELLOW/WARN unless SourcePack core supports them.

sourcepack-1.10.0a0.dist-info/RECORD

@@ -0,0 +1,33 @@
+sourcepack/__init__.py,sha256=Jmc0IHAtjgUKTH5ShgokAK02cCnNXfFdF4IqQS0UBWM,649
+sourcepack/baseline.py,sha256=7QDQ7GJnuWnbVCk1EEJ06ZdOSjcl-Do94DUq_Tq3ATs,14995
+sourcepack/cli.py,sha256=zJKyuFlVJiimbK_BBXw8KBeWXwZAaZfnBx5wCjlfkxY,160404
+sourcepack/commands.py,sha256=NEgtYNiiz_DB2tlxXuBS0UrX9obou5tJygFQ72vtnNI,8103
+sourcepack/dependencies.py,sha256=zD9a9alXkLH036U_I9Y9vLAG2GY3fySZFWPyoLNDU-E,5856
+sourcepack/diff_parser.py,sha256=Vu4_VcSk9CBoLceij2T41Nuz4v7NQD2vatcdnOdt1VQ,4811
+sourcepack/errors.py,sha256=Z8DH3NzdiYg8OK1Nn5zIQCPeps2U6ppTd8m8shOzPiM,400
+sourcepack/evidence.py,sha256=ANF5wXr4PpMzMYamXMvAcCK-dKQp2cp2GCY_iytspMA,4444
+sourcepack/execution_ledger.py,sha256=mi3bGSB9G77peUXAkpO8r85aViGB6mTxJL3KM9m0pRQ,9214
+sourcepack/git.py,sha256=Jg59PZWOxjuXBaun7UfABnmrUMpvnSdtlTMjIOL0rNM,2048
+sourcepack/judgment.py,sha256=VB44Sa6kgNyvVUYE7X4sDRigLurVJTfadom8jmBJVPM,98003
+sourcepack/packet.py,sha256=wW5Z9LHsN5G8cWp-0gpDHhupa_A9wVX_UfoaLR-slrQ,39133
+sourcepack/paths.py,sha256=bCVD5fv48Zss8B7cJ2778XOm-5IFy1Olu5DG-wZ_6tI,2733
+sourcepack/policy.py,sha256=JFi2ibM2wbnLVzzOEkFlicjrCju_vbs2FcLdAY6BTPM,1020
+sourcepack/reason_codes.py,sha256=W__-HTbopfaV6qUIONFH1Yxb2JQ4-VJKaP0GY-AYGZQ,2713
+sourcepack/schemas.py,sha256=FLXup-kieIGNl8YBA9bprtH8oSo9_TlZjkE6X0PtbU0,1479
+sourcepack/assets/__init__.py,sha256=TIJmnRgSvjDUJVM38klGMggQqJGnzUOEwM_LB2NFRXA,43
+sourcepack/assets/audit_template.md,sha256=NjpLJMcZaG3c3m9N3RLhOyU3MBw8hfbDp-EmYRuDwRY,335
+sourcepack/assets/packet_instructions.md,sha256=_ntT3OFq_VRaZLdHlGOVV7tavVcOjidQaCpSdeq1ffw,288
+sourcepack/ecosystems/__init__.py,sha256=ZYn95RhNEsRk_b1xicULGCuC_0W3F8IipE-G-9unVCY,71
+sourcepack/ecosystems/generic.py,sha256=tfBpa2l3ximW2q8lE-O8xgSRdGhtcHGvafM9Kt23a70,344
+sourcepack/ecosystems/node.py,sha256=yjfCgQ77We38ljUhEX6grxJ2jEFDaiwKPfHjltrk9qM,90
+sourcepack/ecosystems/python.py,sha256=Q2fZtZOFHlDMGuoKGmVa6dND_LkWQTG2TzJO5siR2GA,293
+sourcepack/reports/__init__.py,sha256=X4hizw17oJyf2N7Dusq8XoShowF9GCrT99b1sBHLrkA,259
+sourcepack/reports/html.py,sha256=dCyrwynsHIkwSBWBZ6T8uZsre6YCqTzOAW6T1b7YZrk,6852
+sourcepack/reports/json.py,sha256=bxnxgQVr7J05S-bbRFRKu4NNDvI8VBl3yZFxl3rBBVI,9442
+sourcepack/reports/markdown.py,sha256=HRu45o0MwKCin3E3lbGxtST0LBf8agXzgcm-LSZn_sc,3627
+sourcepack-1.10.0a0.dist-info/licenses/LICENSE,sha256=onMK1r_z5gNQRZAsMfScIB8EVnAp11rQEUt5OdVsnbs,1080
+sourcepack-1.10.0a0.dist-info/METADATA,sha256=YoeE7DSxpv7WQhi26Y2RVUQOWzleo-6aLCoaNFYiQf4,11725
+sourcepack-1.10.0a0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sourcepack-1.10.0a0.dist-info/entry_points.txt,sha256=FOJmWOs2xu6JBJRQWyi09Dq92hwLw1HMVgLOmxEmXq4,51
+sourcepack-1.10.0a0.dist-info/top_level.txt,sha256=lGcDKMPyHycZWRx91uPWnAz5idNX8q3gU_tqhugWPg0,11
+sourcepack-1.10.0a0.dist-info/RECORD,,

sourcepack-1.10.0a0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sourcepack-1.10.0a0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sourcepack = sourcepack.cli:main

sourcepack-1.10.0a0.dist-info/licenses/LICENSE

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

sourcepack-1.10.0a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sourcepack