;
};
diff --git a/docs/ai-agents.md b/docs/ai-agents.md
index 324b195..8a42867 100644
--- a/docs/ai-agents.md
+++ b/docs/ai-agents.md
@@ -40,12 +40,12 @@ The [GitHub Action](github-action.md) checks out nothing by itself. After `actio
```yaml
steps:
- uses: actions/checkout@v7
- - uses: bk1202/proofcli@v0.4.2
+ - uses: bk1202/proofcli@v0.4.3
with:
spec: examples/export/good.json
```
-Change `spec` to the contract that should pass for the pull request. The Action exposes `report`, `status`, and `exit-code` outputs. Optional `report` and `artifacts` inputs choose where evidence is saved. Pin a full commit SHA instead of `@v0.4.2` when the workflow needs an immutable action.
+Change `spec` to the contract that should pass for the pull request. The Action exposes `report`, `status`, and `exit-code` outputs. Optional `report` and `artifacts` inputs choose where evidence is saved. Pin a full commit SHA instead of `@v0.4.3` when the workflow needs an immutable action.
## Limits
diff --git a/docs/github-action.md b/docs/github-action.md
index dd1d9d9..4a2f87c 100644
--- a/docs/github-action.md
+++ b/docs/github-action.md
@@ -12,7 +12,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- - uses: bk1202/proofcli@v0.4.2
+ - uses: bk1202/proofcli@v0.4.3
id: proof
with:
spec: tests/export-contract.json
diff --git a/docs/releasing.md b/docs/releasing.md
index c2b2d89..f8d6689 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -5,9 +5,11 @@
3. Only after local validation, publish the candidate branch and obtain green Windows/macOS tests, both distribution-install jobs, and the advisory job. Inspect skips/failures. Merge the same reviewed candidate into main; retain CI links as evidence.
4. Create and push an annotated `v` tag targeting the validated commit. A pre-1.0 release is not a production/security certification.
5. The tag triggers `release.yml`. The read-only validation matrix must pass, including Linux runtime and three-platform composite Action checks. The publish job checks tag/version agreement, builds with pinned tools, verifies fresh wheel/sdist installs, installs hash-locked Pillow from `tools/release-requirements.txt` only to draw one PNG from a real failing run and a real passing run, and creates the GitHub release with both distributions, that screenshot, and `SHA256SUMS`. Pillow is not a ProofCLI runtime dependency. The job does not render a demo video.
-6. Successful release completion triggers `pypi.yml` on the default branch. Its read-only job accepts only a successful tag-push release from this repository, checks that the tag points to the validated commit, and downloads/checksums the published distribution bytes. A separate `pypi` environment job uses PyPA Trusted Publishing with `id-token: write` to upload those exact bytes. It executes no repository code and stores no long-lived token.
+6. Successful release completion triggers `pypi.yml` on the default branch. Its read-only job accepts only a successful tag-push release from this repository, checks that the tag points to the validated commit, and downloads/checksums the published distribution bytes. A separate `pypi` environment job uses PyPA Trusted Publishing with `id-token: write` to upload those exact bytes. It executes no repository code and stores no long-lived token. The `pypi` environment requires approval from bk1202 before that upload.
7. Confirm both workflows, actual downloadable checksums, PyPI version metadata, and a fresh `pip install proofcli==` before announcing index availability. Release creation and PyPI publication do not overwrite published versions; inspect partial failures rather than silently replacing bytes.
+To yank a version that is already on PyPI and ship a fix, follow [Yanking a bad release](yanking.md).
+
Before the first PyPI publication, register a pending GitHub publisher at `https://pypi.org/manage/account/publishing/`: project `proofcli`, owner `bk1202`, repository `proofcli`, workflow `pypi.yml`, environment `pypi`. The workflow cannot create that account-level authorization. If registration is missing, complete it and rerun the failed publication job. Pending registration does not reserve a package name.
Actions are pinned to immutable official commits; checkout credentials are not persisted. There is no privileged PR execution or user text interpolated into shell source. Release tags enter shell commands through environment variables. Only GitHub release publication receives repository write permission; only the separate PyPI publication job receives OIDC write permission.
diff --git a/docs/yanking.md b/docs/yanking.md
new file mode 100644
index 0000000..4c219f7
--- /dev/null
+++ b/docs/yanking.md
@@ -0,0 +1,33 @@
+# Yanking a bad release and shipping a fix
+
+Use this when a version already on PyPI is broken or unsafe. PyPI never lets a version number be uploaded twice or replaced, so the fix is always a new version.
+
+Yanking keeps the files on PyPI but tells installers to skip that version unless it is the only release that matches an exact pin (`==` or `===`, for example `proofcli==X.Y.Z`). It does not delete the files, and it can be undone. PyPI yanks a whole release, not one file inside it.
+
+Yank sparingly. PyPI's own guidance is to yank when a release is broken or uninstallable, when it breaks its own compatibility promise, or when it contains a security problem. Deleting a release is not part of this procedure.
+
+## 1. Yank the bad version on PyPI
+
+1. Sign in to PyPI with an account that can manage `proofcli`, and open `https://pypi.org/manage/project/proofcli/releases/`.
+2. Next to the bad version, open Options and choose Yank.
+3. Confirm in the dialog. A reason is optional and is shown on the release page and to installers. Give one.
+4. From a clean environment, `pip install proofcli` should select the newest release that is not yanked. `pip install proofcli==X.Y.Z` still installs the yanked version.
+
+## 2. Cut a fixed release
+
+1. Fix the problem on a branch and add a regression test that fails without the fix.
+2. Bump both package version declarations from [the release procedure](releasing.md): `version` under `[project]` in `pyproject.toml`, and `__version__` in `proofcli/__init__.py`. Add a changelog entry that names the yanked version and what was wrong.
+3. Update version pins in `README.md` and `docs/` (`proofcli==`, `bk1202/proofcli@v`, and `/proofcli/releases/tag/v` links). `tools/check_versions.py` checks those. It also checks release tags in `.github/workflows/demo-video.yml` and `bk1202/proofcli@v` pins in the demo source. It does not check `CHANGELOG.md`.
+4. Follow [the release procedure](releasing.md) from step 2. The new version must be higher than the yanked one (for example `0.4.4` after yanking `0.4.3`).
+5. Pushing the annotated `v` tag runs `release.yml` (Release assets). When that run succeeds, `pypi.yml` starts from the default branch. It does not start after a failed release. The upload is the `publish` job. That job uses the `pypi` environment, which requires approval from bk1202 before the files go to PyPI. Open the waiting run and approve it.
+6. Do the post-publish checks in [the release procedure](releasing.md) step 7, including a fresh `pip install proofcli==`.
+
+## 3. Tidy the GitHub side
+
+- Leave the old tag in place. Do not move or reuse it.
+- Edit the old GitHub Release notes to say the version was yanked, why, and which version replaces it.
+- If the GitHub Action (`bk1202/proofcli@v...`) was affected, say which tag users should move to.
+
+## 4. If the upload itself failed halfway
+
+Do not retry blindly. Check whether the version now exists on PyPI. If it does and the files are fine, nothing more is needed. If it exists and is bad, yank it and release a new version as above. If it does not exist, rerun the failed `publish` job in `pypi.yml`. That job uploads the distributions the `distributions` job already checked. It does not build them again.
diff --git a/proofcli/__init__.py b/proofcli/__init__.py
index bb8428e..b997adf 100644
--- a/proofcli/__init__.py
+++ b/proofcli/__init__.py
@@ -1,3 +1,3 @@
"""ProofCLI: verify explicit command postconditions."""
-__version__ = "0.4.2"
+__version__ = "0.4.3"
diff --git a/proofcli/cli.py b/proofcli/cli.py
index e47a90b..85c1221 100644
--- a/proofcli/cli.py
+++ b/proofcli/cli.py
@@ -169,8 +169,12 @@ def _parser(command, explicit):
parser.add_argument("--version", action="version", version=f"ProofCLI {__version__}")
parser.add_argument("--json", action="store_true", help="emit a single JSON report")
if command == "init":
- parser.add_argument("path", help="where to create the starter JSON spec")
- parser.add_argument("--force", action="store_true", help="replace an existing spec")
+ parser.add_argument("path", help="starter spec file, or a directory with --example")
+ parser.add_argument("--force", action="store_true", help="replace an existing spec or example")
+ parser.add_argument(
+ "--example", action="store_true",
+ help="write a demo that fails on 999.00 instead of 8.25",
+ )
else:
parser.add_argument("spec", help="path to a version 1 JSON spec")
if command == "run":
@@ -215,7 +219,114 @@ def _save_report(path, report):
temporary.unlink(missing_ok=True)
-def _init(path, force):
+_EXAMPLE_CSV = "id,customer,amount\n1,Ada,12.50\n2,Grace,8.25\n3,Linus,13.00\n"
+
+# Joined lines so the generated script contains a real "\n" string, on every platform.
+_EXAMPLE_SCRIPT = "\n".join([
+ '"""Write report.json and report.csv from input.csv.',
+ "",
+ "The second amount is written as 999.00. The process still exits 0.",
+ '"""',
+ "",
+ "import csv",
+ "import json",
+ "from pathlib import Path",
+ "",
+ "",
+ "def main():",
+ ' with Path("input.csv").open(encoding="utf-8", newline="") as handle:',
+ " rows = list(csv.DictReader(handle))",
+ ' rows[1]["amount"] = "999.00"',
+ ' text = json.dumps({"rows": rows}, indent=2) + "\\n"',
+ ' Path("report.json").write_text(text, encoding="utf-8")',
+ ' with Path("report.csv").open("w", encoding="utf-8", newline="") as handle:',
+ ' writer = csv.DictWriter(handle, fieldnames=["id", "customer", "amount"])',
+ " writer.writeheader()",
+ " writer.writerows(rows)",
+ ' print("Export complete")',
+ "",
+ "",
+ 'if __name__ == "__main__":',
+ " main()",
+ "",
+])
+
+
+def _example_spec():
+ rows = [
+ {"id": "1", "customer": "Ada", "amount": "12.50"},
+ {"id": "2", "customer": "Grace", "amount": "8.25"},
+ {"id": "3", "customer": "Linus", "amount": "13.00"},
+ ]
+ return {
+ "version": 1,
+ "name": "False success: wrong-value",
+ "argv": ["{python}", "{spec_dir}/export.py"],
+ "inputs": [{"source": "fixtures/input.csv", "dest": "input.csv"}],
+ "timeout_seconds": 10,
+ "expect": {
+ "exit_code": 0,
+ "stdout_regex": "Export complete",
+ "files": [
+ {"path": "report.json", "min_size": 1, "json_equals": {"rows": rows}},
+ {
+ "path": "report.csv",
+ "min_size": 1,
+ "csv": {
+ "columns": ["id", "customer", "amount"],
+ "exact_columns": True,
+ "rows": rows,
+ },
+ },
+ ],
+ },
+ }
+
+
+def _path_occupied(path):
+ """True for a real file or directory and for a dangling link."""
+ return path.is_symlink() or path.exists()
+
+
+def _init_example(directory, force):
+ """Write a self-contained failing demo. Refuse to replace anything without --force."""
+ directory = Path(directory).absolute()
+ if directory.is_symlink():
+ raise SpecError("example path is a link; choose a directory")
+ if _path_occupied(directory) and not directory.is_dir():
+ raise SpecError("example path is a file; choose a directory")
+ spec_text = json.dumps(_example_spec(), ensure_ascii=True, indent=2) + "\n"
+ files = [
+ (directory / "wrong-value.json", spec_text),
+ (directory / "export.py", _EXAMPLE_SCRIPT),
+ (directory / "fixtures" / "input.csv", _EXAMPLE_CSV),
+ ]
+ for path, _text in files:
+ parent = path.parent
+ if parent.is_symlink() or (_path_occupied(parent) and not parent.is_dir()):
+ raise SpecError(f"cannot create example files; {parent} is not a directory")
+ if path.is_dir() and not path.is_symlink():
+ raise SpecError(f"{path} is a directory; choose a path that can hold a file")
+ blocked = [path for path, _text in files if _path_occupied(path)]
+ if blocked and not force:
+ raise SpecError("example file already exists; use --force to replace it")
+ directory.mkdir(parents=True, exist_ok=True)
+ try:
+ for path, text in files:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ if path.is_symlink():
+ # Replace the link itself. Do not follow it and edit another file.
+ path.unlink()
+ with path.open("w" if force else "x", encoding="utf-8", newline="\n") as handle:
+ handle.write(text)
+ except FileExistsError as exc:
+ raise SpecError("example file already exists; use --force to replace it") from exc
+ return {"schema_version": 1, "status": "created", "path": str(directory / "wrong-value.json")}
+
+
+def _init(path, force, example=False):
+ if example:
+ return _init_example(path, force)
# Preserve a final symlink for exclusive creation: even a dangling link exists.
path = Path(path).absolute()
spec = {
@@ -261,7 +372,7 @@ def _main(argv=None):
args = parser.parse_args(tokens)
json_output = args.json
if command == "init":
- report = _init(args.path, args.force)
+ report = _init(args.path, args.force, args.example)
else:
spec_path = Path(args.spec).resolve()
# Preserve an error report for malformed/missing specs without ever
diff --git a/pyproject.toml b/pyproject.toml
index 0c3853e..956cc2d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "proofcli"
-version = "0.4.2"
+version = "0.4.3"
description = "Verify command output contracts instead of trusting exit code zero."
readme = "README.md"
requires-python = ">=3.10"
diff --git a/requirements-build.txt b/requirements-build.txt
index 0e94cf4..3d0d0d1 100644
--- a/requirements-build.txt
+++ b/requirements-build.txt
@@ -3,5 +3,5 @@ build==1.6.1 --hash=sha256:ecd351a4be9d35a9eaaba244a7687143c9c7d4aea6ac964e7e7dd
colorama==0.4.6 --hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6
packaging==26.3 --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
pyproject_hooks==1.3.3 --hash=sha256:5fc53fdac9f7bd63fbcdc868fb5f90b4784d78a53a3d3388cd738b807441a20b
-setuptools==84.0.0 --hash=sha256:51a52592b3b99e102b609654876bd65f19f999935166d1352678931132b0c670
+setuptools==84.1.0 --hash=sha256:5231689c6ac8156cd155cfb98c3fd6fb252c3e7e9bd3d78b64d3c55f132624c9
tomli==2.5.0 --hash=sha256:32a7b79ac57a2e83670ce329ccf675798bc5a2094783a63676866b70503f2e2b
diff --git a/tests/test_help.py b/tests/test_help.py
index 2a4c291..e4a29f1 100644
--- a/tests/test_help.py
+++ b/tests/test_help.py
@@ -111,9 +111,13 @@ def usage_block(text):
)
self.assertEqual(
usage_block(seen["init"]),
- "usage: proofcli init [-h] [--version] [--json] [--force] path",
+ "usage: proofcli init [-h] [--version] [--json] [--force] [--example] path",
)
self.assertIn("replace an existing spec", seen["init"])
+ self.assertIn("--example", seen["init"])
+ self.assertIn("999.00", seen["init"])
+ self.assertNotIn("--example", seen["run"])
+ self.assertNotIn("--example", seen["validate"])
self.assertIn("save the complete JSON report to this path", seen["run"])
self.assertNotIn("save the complete JSON report", seen["validate"])
self.assertNotIn("replace an existing spec", seen["validate"])
@@ -173,6 +177,7 @@ def test_help_and_usage_exit_codes_are_unchanged(self):
(["run"], "the following arguments are required: spec"),
(["validate"], "the following arguments are required: spec"),
(["init"], "the following arguments are required: path"),
+ (["init", "--example"], "the following arguments are required: path"),
(["--bogus"], "the following arguments are required: spec"),
(["run", missing, "--art", "x"], "unrecognized arguments: --art"),
(["--report", "--help"], "argument --report: expected one argument"),
diff --git a/tests/test_qol.py b/tests/test_qol.py
index 1170f3f..6944b63 100644
--- a/tests/test_qol.py
+++ b/tests/test_qol.py
@@ -94,6 +94,86 @@ def test_init_human_output_explains_next_command(self):
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("proofcli run", result.stdout)
+ def _run_printed_command(self, stdout):
+ """Run the `Next: proofcli run "..."` line with the same CLI subprocess."""
+ line = next(item for item in stdout.splitlines() if "Next:" in item)
+ self.assertIn("proofcli run ", line)
+ quoted = line.split("proofcli run ", 1)[1].strip()
+ self.assertTrue(quoted.startswith('"') and quoted.endswith('"'), stdout)
+ spec = quoted[1:-1]
+ installed = os.environ.get("PROOFCLI_TEST_INSTALLED") == "1"
+ env = os.environ.copy()
+ if installed:
+ executable = shutil.which("proofcli")
+ self.assertIsNotNone(executable, "Installed mode requires proofcli on PATH")
+ argv = [executable, "run", spec]
+ env.pop("PYTHONPATH", None)
+ else:
+ argv = [sys.executable, "-m", "proofcli", "run", spec]
+ env["PYTHONPATH"] = os.pathsep.join([str(PROJECT), env.get("PYTHONPATH", "")])
+ return subprocess.run(
+ argv, cwd=self.root, env=env, capture_output=True, text=True,
+ encoding="utf-8", errors="replace", timeout=30,
+ ), spec
+
+ def test_init_example_writes_a_demo_that_fails_on_the_wrong_amount(self):
+ directory = self.root / "export-demo"
+ result = self.invoke(["init", "--example", directory], json_output=False)
+ self.assertEqual(result.returncode, 0, result.stderr)
+ spec_path = directory / "wrong-value.json"
+ script_path = directory / "export.py"
+ fixture_path = directory / "fixtures" / "input.csv"
+ self.assertTrue(spec_path.is_file(), result.stdout)
+ self.assertTrue(script_path.is_file())
+ self.assertTrue(fixture_path.is_file())
+ self.assertFalse((directory / "report.json").exists())
+ spec = json.loads(spec_path.read_text(encoding="utf-8"))
+ self.assertEqual(spec["argv"][0], "{python}")
+ self.assertNotIn("sh", spec["argv"])
+ self.assertNotIn("bash", spec["argv"])
+ self.assertNotIn("cmd", spec["argv"])
+ completed, printed_spec = self._run_printed_command(result.stdout)
+ self.assertEqual(Path(printed_spec), spec_path)
+ self.assertEqual(completed.returncode, 1, completed.stdout + completed.stderr)
+ self.assertIn('expected: "8.25"', completed.stdout)
+ self.assertIn('actual: "999.00"', completed.stdout)
+
+ def test_init_example_refuses_to_overwrite_existing_files(self):
+ directory = self.root / "export-demo"
+ (directory / "fixtures").mkdir(parents=True)
+ kept = directory / "fixtures" / "input.csv"
+ kept.write_text("original fixture", encoding="utf-8")
+ result = self.invoke(["init", "--example", directory], json_output=False)
+ self.assertEqual(result.returncode, 2, result.stdout)
+ self.assertEqual(result.stdout, "")
+ self.assertIn("already exists", result.stderr)
+ self.assertIn("--force", result.stderr)
+ self.assertEqual(kept.read_text(encoding="utf-8"), "original fixture")
+ self.assertFalse((directory / "wrong-value.json").exists())
+ self.assertFalse((directory / "export.py").exists())
+ replaced = self.invoke(["init", "--example", directory, "--force"], json_output=False)
+ self.assertEqual(replaced.returncode, 0, replaced.stderr)
+ self.assertNotEqual(kept.read_text(encoding="utf-8"), "original fixture")
+ completed, _spec = self._run_printed_command(replaced.stdout)
+ self.assertEqual(completed.returncode, 1, completed.stdout + completed.stderr)
+ self.assertIn('expected: "8.25"', completed.stdout)
+ self.assertIn('actual: "999.00"', completed.stdout)
+
+ def test_plain_init_still_writes_a_passing_starter(self):
+ path = self.root / "starter.json"
+ result = self.invoke(["init", path], json_output=False)
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual([item.name for item in self.root.iterdir()], ["starter.json"])
+ generated = json.loads(path.read_text(encoding="utf-8"))
+ self.assertEqual(generated["argv"][:2], ["{python}", "-c"])
+ self.assertIn("ProofCLI verified this output.", generated["argv"][2])
+ self.assertEqual(generated["expect"]["exit_code"], 0)
+ self.assertNotIn("999.00", path.read_text(encoding="utf-8"))
+ self.assertNotIn("--example", result.stdout)
+ run = self.invoke(["run", path], json_output=False)
+ self.assertEqual(run.returncode, 0, run.stderr)
+ self.assertIn("PASSED", run.stdout)
+
def test_validate_does_not_execute_the_command(self):
path = self.marker_spec()
report = self.assert_report(self.invoke(["validate", path]), 0, "valid")