bensz-auto-contribution 1.1.2__tar.gz

bensz_auto_contribution-1.1.2/LICENSE

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

bensz_auto_contribution-1.1.2/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: bensz-auto-contribution
+Version: 1.1.2
+Summary: Tamper-evident BAC contribution attribution ledger
+Author: bensz auto contribution
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/huangwb8/bensz-auto-contribution
+Project-URL: Documentation, https://github.com/huangwb8/bensz-auto-contribution#readme
+Project-URL: Source, https://github.com/huangwb8/bensz-auto-contribution
+Project-URL: Issues, https://github.com/huangwb8/bensz-auto-contribution/issues
+Project-URL: Changelog, https://github.com/huangwb8/bensz-auto-contribution/blob/main/CHANGELOG.md
+Keywords: ai,audit,attribution,contribution,tamper-evident
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# 🧭 Bensz Auto Contribution
+
+**Tamper-evident contribution attribution for human-AI software collaboration**
+
+[![Release](https://img.shields.io/github/v/tag/huangwb8/bensz-auto-contribution?label=release&color=blue)](https://github.com/huangwb8/bensz-auto-contribution/tags)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
+[![BAC Format](https://img.shields.io/badge/BAC_format-v2-7C3AED.svg)](docs/bac-tutorial.md)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+</div>
+
+---
+
+## ✨ Introduction
+
+Bensz Auto Contribution, or **BAC**, is a contribution attribution and audit system designed for AI coding tools. Its core artifact is a `.bac` file: a project-bound, append-only, tamper-evident record of what came from humans, what came from AI, what came from tools, and what evidence was observed during development.
+
+BAC does not claim that a file can never be modified. Instead, it makes changes detectable through structured events, canonical JSON, hash chaining, local checkpoints, project context binding, and future-ready signature and timestamp fields.
+
+**🌟 Core Highlight**: BAC gives AI coding sessions a durable audit trail. It helps teams explain AI usage, review collaboration boundaries, verify generated work, and reconstruct development history without mixing human intent, AI generation, tool output, and file evidence into one vague blob.
+
+### Key Features
+
+- 🧑‍💻 **Human-AI Attribution**: Explicitly separates `human`, `ai`, `tool`, and `system` sources.
+- 🧾 **Append-Only Event Model**: Records contribution history as ordered events instead of overwriting prior state.
+- 🔗 **Hash-Chain Verification**: Detects modified, inserted, deleted, duplicated, or reordered events.
+- 📦 **Single-File `.bac` Container**: Stores a ZIP-based v2 ledger with `manifest.json` and canonical JSON event files.
+- 🛡️ **Tamper-Evident Security Boundary**: Describes integrity guarantees honestly without overstating immutability.
+- 🧠 **AI Tool Ready**: Designed for Codex CLI, Claude Code, and other agentic coding environments.
+- 🔍 **Evidence-Aware Records**: Captures file hashes, git diff summaries, command text, exit codes, test results, and checkpoints.
+- 🧼 **Sensitive Data Redaction**: Avoids storing secrets, private prompts, or unrelated user data by default.
+
+---
+
+<div align="center">
+
+### ⭐ If this project helps you, please give it a Star!
+
+Building reliable attribution for AI-assisted work takes careful design, testing, and threat modeling. Your Star helps more builders discover BAC.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=huangwb8/bensz-auto-contribution&type=Date)](https://star-history.com/#huangwb8/bensz-auto-contribution&Date)
+
+</div>
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- No runtime third-party dependencies
+
+### Installation
+
+```bash
+python -m pip install bensz-auto-contribution
+
+# source or development install
+python -m pip install -e .
+```
+
+### Basic Usage
+
+Create a single-file `.bac` container and write the genesis event:
+
+```bash
+bac init
+```
+
+Record a human requirement:
+
+```bash
+bac record \
+  --event-type human_instruction \
+  --source-type human \
+  --summary "Add BAC verification workflow"
+```
+
+Record AI generation or implementation intent:
+
+```bash
+bac record \
+  --event-type ai_generation \
+  --source-type ai \
+  --summary "Implemented hash-chain verifier"
+```
+
+Record a tool result:
+
+```bash
+bac record \
+  --event-type test_result \
+  --source-type tool \
+  --summary "Unit tests passed" \
+  --command-text "python -m unittest discover -s tests -v" \
+  --exit-code 0
+```
+
+Record a local checkpoint to reduce tail-truncation risk:
+
+```bash
+bac record \
+  --event-type checkpoint \
+  --source-type system \
+  --summary "Local checkpoint"
+```
+
+Verify integrity:
+
+```bash
+bac verify
+```
+
+Inspect the contribution timeline:
+
+```bash
+bac inspect
+```
+
+All commands support `--root` for the target project root and `--bac-file` for a custom `.bac` path. `init`, `record`, `verify`, and `inspect` also support `--json` for machine-readable output.
+
+## 🧩 Where BAC Fits
+
+BAC is a process record and audit aid, not a final judge of contribution ownership.
+
+In AI-assisted research, writing, and software projects, BAC can record human requirements, constraints, reviews, hand-written edits, final approvals, AI drafts, refactoring proposals, generated code, command outputs, tests, citation checks, build logs, file snapshots, and diff summaries.
+
+These records can support AI usage disclosure, internal review, compliance notes, and dispute reconstruction. They do not automatically determine academic authorship, legal ownership, or final responsibility. Those decisions still require project policy, institutional rules, journal guidelines, and human judgment.
+
+## 📦 `.bac` Format
+
+The default file is `project.bac`. Externally, it is one file. Internally, it is a ZIP container with at least:
+
+```text
+manifest.json
+events/000000000001.json
+events/000000000002.json
+```
+
+`manifest.json` records the container version, event format, project binding information, genesis event hash, and storage conventions. Each file under `events/` is one canonical JSON event. Event filenames are continuous and start at `000000000001.json`.
+
+A BAC event includes:
+
+- `format`: currently `bac.event.v2`
+- `event_type`: examples include `genesis`, `human_instruction`, `ai_generation`, `tool_command`, `file_change`, `test_result`, and `checkpoint`
+- `source_type`: one of `human`, `ai`, `tool`, or `system`
+- `trust_level`: one of `declared`, `observed`, `signed`, `verified`, or `anchored`
+- `project`: root path, project binding hash, git remote, commit, branch, and dirty state
+- `payload`: summary, command data, file snapshots, or event-specific content
+- `evidence`: diff summaries, file hashes, command results, or other verifiable evidence
+- `redactions`: fields removed or masked for safety
+- `prev_event_hash` and `event_hash`: the verifiable hash chain
+
+The verifier checks whether the file is a valid ZIP container, whether internal paths are duplicated, whether event numbering is continuous, whether the manifest matches the genesis event, and whether the hash chain can be recomputed.
+
+For a field-by-field walkthrough, see [BAC Tutorial](docs/bac-tutorial.md).
+
+## 🛡️ Security Model
+
+BAC is **tamper-evident**, not tamper-proof.
+
+It can detect common integrity problems such as edited event content, missing events, reordered events, duplicated internal ZIP paths, broken event numbering, mismatched genesis metadata, invalid hash links, and checkpoint inconsistencies.
+
+Without an external anchor, a purely local hash chain cannot fully prevent tail truncation. BAC therefore supports local checkpoints today and keeps room for future Ed25519 signatures, git notes, release artifacts, trusted timestamps, or external transparency logs.
+
+## 🧪 Development
+
+Run the test suite:
+
+```bash
+python -m pytest -q
+python -m unittest discover -s tests -v
+```
+
+Current coverage includes canonicalization, v2 container structure, hash-chain recomputation, tamper detection, duplicate internal path detection, checkpoint verification, sensitive data redaction, and CLI end-to-end flows.
+
+Build and check PyPI distributions locally:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Releases are published to PyPI through GitHub Actions and PyPI Trusted Publishing. See [PyPI Release](docs/pypi-release.md).
+
+## 🗂️ Project Structure
+
+```text
+bensz-auto-contribution/
+├── AGENTS.md
+├── CHANGELOG.md
+├── CLAUDE.md
+├── LICENSE
+├── README.md
+├── README.zh-CN.md
+├── docs
+│   ├── bac-tutorial.md
+│   ├── pypi-release.md
+│   └── plans
+├── pyproject.toml
+├── src
+│   └── bac
+│       ├── adapters
+│       ├── core
+│       ├── report
+│       ├── service
+│       └── storage
+└── tests
+```
+
+## 🤖 AI-Assisted Development
+
+This repository includes project instructions for AI coding tools:
+
+- `AGENTS.md` for OpenAI Codex CLI
+- `CLAUDE.md` for Claude Code
+
+When changing contribution attribution logic, keep the security boundary precise: BAC provides verifiable, tamper-evident records. It should not be described as impossible to modify.
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome around the `.bac` file format, threat model, AI tool integration, verification logic, signing and timestamping, and developer experience.
+
+## 📄 License
+
+MIT License

bensz_auto_contribution-1.1.2/README.md

@@ -0,0 +1,232 @@
+<div align="center">
+
+# 🧭 Bensz Auto Contribution
+
+**Tamper-evident contribution attribution for human-AI software collaboration**
+
+[![Release](https://img.shields.io/github/v/tag/huangwb8/bensz-auto-contribution?label=release&color=blue)](https://github.com/huangwb8/bensz-auto-contribution/tags)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
+[![BAC Format](https://img.shields.io/badge/BAC_format-v2-7C3AED.svg)](docs/bac-tutorial.md)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+</div>
+
+---
+
+## ✨ Introduction
+
+Bensz Auto Contribution, or **BAC**, is a contribution attribution and audit system designed for AI coding tools. Its core artifact is a `.bac` file: a project-bound, append-only, tamper-evident record of what came from humans, what came from AI, what came from tools, and what evidence was observed during development.
+
+BAC does not claim that a file can never be modified. Instead, it makes changes detectable through structured events, canonical JSON, hash chaining, local checkpoints, project context binding, and future-ready signature and timestamp fields.
+
+**🌟 Core Highlight**: BAC gives AI coding sessions a durable audit trail. It helps teams explain AI usage, review collaboration boundaries, verify generated work, and reconstruct development history without mixing human intent, AI generation, tool output, and file evidence into one vague blob.
+
+### Key Features
+
+- 🧑‍💻 **Human-AI Attribution**: Explicitly separates `human`, `ai`, `tool`, and `system` sources.
+- 🧾 **Append-Only Event Model**: Records contribution history as ordered events instead of overwriting prior state.
+- 🔗 **Hash-Chain Verification**: Detects modified, inserted, deleted, duplicated, or reordered events.
+- 📦 **Single-File `.bac` Container**: Stores a ZIP-based v2 ledger with `manifest.json` and canonical JSON event files.
+- 🛡️ **Tamper-Evident Security Boundary**: Describes integrity guarantees honestly without overstating immutability.
+- 🧠 **AI Tool Ready**: Designed for Codex CLI, Claude Code, and other agentic coding environments.
+- 🔍 **Evidence-Aware Records**: Captures file hashes, git diff summaries, command text, exit codes, test results, and checkpoints.
+- 🧼 **Sensitive Data Redaction**: Avoids storing secrets, private prompts, or unrelated user data by default.
+
+---
+
+<div align="center">
+
+### ⭐ If this project helps you, please give it a Star!
+
+Building reliable attribution for AI-assisted work takes careful design, testing, and threat modeling. Your Star helps more builders discover BAC.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=huangwb8/bensz-auto-contribution&type=Date)](https://star-history.com/#huangwb8/bensz-auto-contribution&Date)
+
+</div>
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- No runtime third-party dependencies
+
+### Installation
+
+```bash
+python -m pip install bensz-auto-contribution
+
+# source or development install
+python -m pip install -e .
+```
+
+### Basic Usage
+
+Create a single-file `.bac` container and write the genesis event:
+
+```bash
+bac init
+```
+
+Record a human requirement:
+
+```bash
+bac record \
+  --event-type human_instruction \
+  --source-type human \
+  --summary "Add BAC verification workflow"
+```
+
+Record AI generation or implementation intent:
+
+```bash
+bac record \
+  --event-type ai_generation \
+  --source-type ai \
+  --summary "Implemented hash-chain verifier"
+```
+
+Record a tool result:
+
+```bash
+bac record \
+  --event-type test_result \
+  --source-type tool \
+  --summary "Unit tests passed" \
+  --command-text "python -m unittest discover -s tests -v" \
+  --exit-code 0
+```
+
+Record a local checkpoint to reduce tail-truncation risk:
+
+```bash
+bac record \
+  --event-type checkpoint \
+  --source-type system \
+  --summary "Local checkpoint"
+```
+
+Verify integrity:
+
+```bash
+bac verify
+```
+
+Inspect the contribution timeline:
+
+```bash
+bac inspect
+```
+
+All commands support `--root` for the target project root and `--bac-file` for a custom `.bac` path. `init`, `record`, `verify`, and `inspect` also support `--json` for machine-readable output.
+
+## 🧩 Where BAC Fits
+
+BAC is a process record and audit aid, not a final judge of contribution ownership.
+
+In AI-assisted research, writing, and software projects, BAC can record human requirements, constraints, reviews, hand-written edits, final approvals, AI drafts, refactoring proposals, generated code, command outputs, tests, citation checks, build logs, file snapshots, and diff summaries.
+
+These records can support AI usage disclosure, internal review, compliance notes, and dispute reconstruction. They do not automatically determine academic authorship, legal ownership, or final responsibility. Those decisions still require project policy, institutional rules, journal guidelines, and human judgment.
+
+## 📦 `.bac` Format
+
+The default file is `project.bac`. Externally, it is one file. Internally, it is a ZIP container with at least:
+
+```text
+manifest.json
+events/000000000001.json
+events/000000000002.json
+```
+
+`manifest.json` records the container version, event format, project binding information, genesis event hash, and storage conventions. Each file under `events/` is one canonical JSON event. Event filenames are continuous and start at `000000000001.json`.
+
+A BAC event includes:
+
+- `format`: currently `bac.event.v2`
+- `event_type`: examples include `genesis`, `human_instruction`, `ai_generation`, `tool_command`, `file_change`, `test_result`, and `checkpoint`
+- `source_type`: one of `human`, `ai`, `tool`, or `system`
+- `trust_level`: one of `declared`, `observed`, `signed`, `verified`, or `anchored`
+- `project`: root path, project binding hash, git remote, commit, branch, and dirty state
+- `payload`: summary, command data, file snapshots, or event-specific content
+- `evidence`: diff summaries, file hashes, command results, or other verifiable evidence
+- `redactions`: fields removed or masked for safety
+- `prev_event_hash` and `event_hash`: the verifiable hash chain
+
+The verifier checks whether the file is a valid ZIP container, whether internal paths are duplicated, whether event numbering is continuous, whether the manifest matches the genesis event, and whether the hash chain can be recomputed.
+
+For a field-by-field walkthrough, see [BAC Tutorial](docs/bac-tutorial.md).
+
+## 🛡️ Security Model
+
+BAC is **tamper-evident**, not tamper-proof.
+
+It can detect common integrity problems such as edited event content, missing events, reordered events, duplicated internal ZIP paths, broken event numbering, mismatched genesis metadata, invalid hash links, and checkpoint inconsistencies.
+
+Without an external anchor, a purely local hash chain cannot fully prevent tail truncation. BAC therefore supports local checkpoints today and keeps room for future Ed25519 signatures, git notes, release artifacts, trusted timestamps, or external transparency logs.
+
+## 🧪 Development
+
+Run the test suite:
+
+```bash
+python -m pytest -q
+python -m unittest discover -s tests -v
+```
+
+Current coverage includes canonicalization, v2 container structure, hash-chain recomputation, tamper detection, duplicate internal path detection, checkpoint verification, sensitive data redaction, and CLI end-to-end flows.
+
+Build and check PyPI distributions locally:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Releases are published to PyPI through GitHub Actions and PyPI Trusted Publishing. See [PyPI Release](docs/pypi-release.md).
+
+## 🗂️ Project Structure
+
+```text
+bensz-auto-contribution/
+├── AGENTS.md
+├── CHANGELOG.md
+├── CLAUDE.md
+├── LICENSE
+├── README.md
+├── README.zh-CN.md
+├── docs
+│   ├── bac-tutorial.md
+│   ├── pypi-release.md
+│   └── plans
+├── pyproject.toml
+├── src
+│   └── bac
+│       ├── adapters
+│       ├── core
+│       ├── report
+│       ├── service
+│       └── storage
+└── tests
+```
+
+## 🤖 AI-Assisted Development
+
+This repository includes project instructions for AI coding tools:
+
+- `AGENTS.md` for OpenAI Codex CLI
+- `CLAUDE.md` for Claude Code
+
+When changing contribution attribution logic, keep the security boundary precise: BAC provides verifiable, tamper-evident records. It should not be described as impossible to modify.
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome around the `.bac` file format, threat model, AI tool integration, verification logic, signing and timestamping, and developer experience.
+
+## 📄 License
+
+MIT License

bensz_auto_contribution-1.1.2/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bensz-auto-contribution"
+version = "1.1.2"
+description = "Tamper-evident BAC contribution attribution ledger"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "bensz auto contribution"}
+]
+keywords = ["ai", "audit", "attribution", "contribution", "tamper-evident"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Version Control",
+  "Topic :: System :: Archiving"
+]
+dependencies = []
+
+[project.scripts]
+bac = "bac.adapters.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/huangwb8/bensz-auto-contribution"
+Documentation = "https://github.com/huangwb8/bensz-auto-contribution#readme"
+Source = "https://github.com/huangwb8/bensz-auto-contribution"
+Issues = "https://github.com/huangwb8/bensz-auto-contribution/issues"
+Changelog = "https://github.com/huangwb8/bensz-auto-contribution/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

bensz_auto_contribution-1.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bensz_auto_contribution-1.1.2/src/bac/__init__.py

@@ -0,0 +1,3 @@
+"""BAC contribution attribution ledger."""
+
+__version__ = "2.0.0"

bensz_auto_contribution-1.1.2/src/bac/__main__.py

@@ -0,0 +1,5 @@
+from bac.adapters.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())