assurance-cli 0.6.0__tar.gz → 0.6.2__tar.gz

assurance_cli-0.6.2/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: assurance-cli
+Version: 0.6.2
+Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
+Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://i-ops.dev
+Project-URL: Source, https://github.com/i-ops-hq/assurance
+Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: assurance-core>=0.14.0
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.27.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-openpyxl; extra == "dev"
+Provides-Extra: deps
+Requires-Dist: assurance-deps>=0.2.4; extra == "deps"
+Dynamic: license-file
+
+# assurance-cli
+
+[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![Tests](https://github.com/i-ops-hq/assurance/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance/blob/main/packages/cli/LICENSE)
+
+Did the job cover everything it was supposed to cover? Arithmetic, not models.
+
+## Install
+
+```bash
+pip install assurance-cli
+# or: pip install assurance   # every tool
+```
+
+## Quick start
+
+`assurance --help` lists: `init`, `check`, `diff`, `pin`, `drift`, `deps`, `budget`, `authority`, `audit`.
+`audit`, `budget`, `authority`, and `deps` forward to their packages when installed.
+
+Point `check` at a folder of dated files (real output from a temp folder with Jan, Feb, Apr CSVs):
+
+```
+$ assurance check reports
+3 of 4 months from 2026-01 to 2026-04 in reports — not in this folder: March 2026 — Range inferred from filenames: earliest 2026-01, latest 2026-04 — uneven spacing, so monthly was read from the names rather than detected. Override with --expect / --from / --to.
+```
+
+With `--fail-on-gap` that same line exits `1`.
+
+`diff` compares any two sets of keys (no folder required). `pin` snapshots MCP tool definitions and detects drift. `drift` watches a binary outcome stream.
+
+## What it checks
+
+- Dated or numbered series in a folder (`check`) — months, weeks, days, numbered runs
+- Coverage over any two key sets (`diff`)
+- MCP tool-description drift since a pin (`pin`)
+- Shift in a binary outcome stream (`drift`)
+- Forwards: session audit, run budget, authority review, dependency install hooks
+
+## In CI
+
+| exit | means |
+|---|---|
+| `0` | checked; no gap (or not asked to fail on one) |
+| `1` | gap / unexpected key / stale pin / nothing it could check |
+| `2` | could not run (bad path, missing sibling package, bad JSON) |
+
+## Limits
+
+- **Does not invent the expected set.** `diff` takes your declaration; `check` derives one and prints how.
+- **No network, no telemetry, no keys.**
+- **A folder it cannot parse exits 1**, not 0 — silence is not a pass.
+- Skipped tool directories (`.git`, `node_modules`, …) are named, not folded into “files not opened” as if they were content.
+
+See the [root README](https://github.com/i-ops-hq/assurance#readme) and [CHANGELOG.md](CHANGELOG.md).

assurance_cli-0.6.2/README.md

@@ -0,0 +1,56 @@
+# assurance-cli
+
+[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![Tests](https://github.com/i-ops-hq/assurance/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance/blob/main/packages/cli/LICENSE)
+
+Did the job cover everything it was supposed to cover? Arithmetic, not models.
+
+## Install
+
+```bash
+pip install assurance-cli
+# or: pip install assurance   # every tool
+```
+
+## Quick start
+
+`assurance --help` lists: `init`, `check`, `diff`, `pin`, `drift`, `deps`, `budget`, `authority`, `audit`.
+`audit`, `budget`, `authority`, and `deps` forward to their packages when installed.
+
+Point `check` at a folder of dated files (real output from a temp folder with Jan, Feb, Apr CSVs):
+
+```
+$ assurance check reports
+3 of 4 months from 2026-01 to 2026-04 in reports — not in this folder: March 2026 — Range inferred from filenames: earliest 2026-01, latest 2026-04 — uneven spacing, so monthly was read from the names rather than detected. Override with --expect / --from / --to.
+```
+
+With `--fail-on-gap` that same line exits `1`.
+
+`diff` compares any two sets of keys (no folder required). `pin` snapshots MCP tool definitions and detects drift. `drift` watches a binary outcome stream.
+
+## What it checks
+
+- Dated or numbered series in a folder (`check`) — months, weeks, days, numbered runs
+- Coverage over any two key sets (`diff`)
+- MCP tool-description drift since a pin (`pin`)
+- Shift in a binary outcome stream (`drift`)
+- Forwards: session audit, run budget, authority review, dependency install hooks
+
+## In CI
+
+| exit | means |
+|---|---|
+| `0` | checked; no gap (or not asked to fail on one) |
+| `1` | gap / unexpected key / stale pin / nothing it could check |
+| `2` | could not run (bad path, missing sibling package, bad JSON) |
+
+## Limits
+
+- **Does not invent the expected set.** `diff` takes your declaration; `check` derives one and prints how.
+- **No network, no telemetry, no keys.**
+- **A folder it cannot parse exits 1**, not 0 — silence is not a pass.
+- Skipped tool directories (`.git`, `node_modules`, …) are named, not folded into “files not opened” as if they were content.
+
+See the [root README](https://github.com/i-ops-hq/assurance#readme) and [CHANGELOG.md](CHANGELOG.md).

{assurance_cli-0.6.0 → assurance_cli-0.6.2}/assurance_cli/cli.py

@@ -25,23 +25,65 @@ FORWARDED: dict[str, tuple[str, str]] = {
     "budget": ("assurance_budget.cli", "pip install assurance-budget"),
     "authority": ("assurance_authority.cli", "pip install assurance-authority"),
     "audit": ("assurance_budget.session_cli", "pip install assurance-budget"),
+    "hook": ("assurance_budget.hook_setup", "pip install assurance-budget"),
 }
 
 _START_HERE = """\
-assurance — what an agent run covered, spent, may do, and is about to install.
+assurance — your AI agent says it's done. This tells you what it didn't check.
+No model, no network, no account.
 
-  assurance diff --expected A --found B   what was required vs. what was actually read
-  assurance check [FOLDER]                a folder of dated or numbered files: what is absent
+  assurance audit                         what the Claude Code session in this folder did, and skipped
+  assurance audit --demo                  the same report on a bundled sample session
+  assurance hook install                  run the audit after every Claude Code turn (remove undoes it)
+  assurance diff --expected A --found B   was everything that should have been read, read?
   assurance pin --save | --check          did an MCP server change a tool after you approved it?
-  assurance deps requirements.txt         what an install will execute, read without running it
-  assurance budget runs.jsonl             where an agent run's budget went
+  assurance deps package.json             what an install will execute, read without running it
+  assurance budget runs.jsonl             where an agent run's budget went, and where it looped
   assurance authority --example           may a task proceed for the person who asked?
-  assurance audit [TRANSCRIPT]            what a Claude Code session did, and what it could not classify
+  assurance check [FOLDER]                a folder of dated or numbered files: what is absent
 
+Run it after every Claude Code session: https://github.com/i-ops-hq/assurance#run-it-after-every-session
 assurance <command> --help for more.
 """
 
 
+#: Every distribution the `assurance` command can reach, in the order `--version` names them.
+_DISTRIBUTIONS = (
+    ("assurance-cli", "cli"),
+    ("assurance-budget", "budget"),
+    ("assurance-deps", "deps"),
+    ("assurance-authority", "authority"),
+    ("assurance-mcp", "mcp"),
+    ("assurance-core", "core"),
+)
+
+
+def _version_line() -> str:
+    """`assurance 0.1.2 (cli 0.6.1, budget 0.2.2, …)` — every installed part, so a bug report
+    names what actually ran. `pip install assurance` is one version number over several packages;
+    printing only the cli's used to say 0.6.0 to someone who had installed 0.1.1."""
+    parts = []
+    for dist, short in _DISTRIBUTIONS:
+        try:
+            parts.append(f"{short} {importlib.metadata.version(dist)}")
+        except importlib.metadata.PackageNotFoundError:
+            continue
+    try:
+        front = f"assurance {importlib.metadata.version('assurance')}"
+    except importlib.metadata.PackageNotFoundError:
+        front = "assurance"
+    return f"{front} ({', '.join(parts)})" if parts else front
+
+
+class _PrintVersion(argparse.Action):
+    """argparse's own version action rewraps the text to the terminal width, splitting a version
+    number across lines. This prints the line as it is."""
+
+    def __call__(self, parser: argparse.ArgumentParser, namespace: object, values: object, option_string: str | None = None) -> None:
+        print(_version_line())
+        parser.exit()
+
+
 def main(argv: list[str] | None = None) -> int:
     """Command-line entry for assurance checks."""
     # `deps` is forwarded whole, before argparse sees any of it. argparse claims `--help` for the
@@ -58,17 +100,23 @@ def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="assurance",
         description=(
-            "Did the job cover everything it was supposed to cover? Arithmetic, not models. "
-            "`diff` is the general command — it compares any two sets of keys. `check` is the "
-            "special case for a folder of dated or numbered files."
+            "Your AI agent says it's done. Assurance tells you what it didn't check. Every answer "
+            "is arithmetic over what happened; no model decides anything."
         ),
     )
-    parser.add_argument(
-        "--version",
-        action="version",
-        version=f"%(prog)s {importlib.metadata.version('assurance-cli')}",
-    )
+    parser.add_argument("--version", action=_PrintVersion, nargs=0, help="Show every installed part's version")
     sub = parser.add_subparsers(dest="command", required=True)
+    # First, because it is the one most people install this for. `main` forwards it before
+    # argparse runs; it is listed here so `assurance --help` shows it.
+    sub.add_parser(
+        "audit", add_help=False,
+        help="What the Claude Code session in this folder did, and what it skipped (--demo for a sample)",
+    )
+
+    sub.add_parser(
+        "hook", add_help=False,
+        help="Run the audit after every Claude Code turn: install, remove, status",
+    )
 
     init_parser = sub.add_parser("init", help="Write .assurance.json baseline")
     init_parser.add_argument("folder", help="Folder to baseline")
@@ -192,10 +240,6 @@ def main(argv: list[str] | None = None) -> int:
         "authority", add_help=False,
         help="Whether a task may proceed for the person who asked (assurance-authority)",
     )
-    sub.add_parser(
-        "audit", add_help=False,
-        help="What a Claude Code session did, and what could not be classified (assurance-budget)",
-    )
 
     args = parser.parse_args(argv)
 

assurance_cli-0.6.2/assurance_cli.egg-info/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: assurance-cli
+Version: 0.6.2
+Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
+Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://i-ops.dev
+Project-URL: Source, https://github.com/i-ops-hq/assurance
+Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: assurance-core>=0.14.0
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.27.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-openpyxl; extra == "dev"
+Provides-Extra: deps
+Requires-Dist: assurance-deps>=0.2.4; extra == "deps"
+Dynamic: license-file
+
+# assurance-cli
+
+[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![Tests](https://github.com/i-ops-hq/assurance/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance/blob/main/packages/cli/LICENSE)
+
+Did the job cover everything it was supposed to cover? Arithmetic, not models.
+
+## Install
+
+```bash
+pip install assurance-cli
+# or: pip install assurance   # every tool
+```
+
+## Quick start
+
+`assurance --help` lists: `init`, `check`, `diff`, `pin`, `drift`, `deps`, `budget`, `authority`, `audit`.
+`audit`, `budget`, `authority`, and `deps` forward to their packages when installed.
+
+Point `check` at a folder of dated files (real output from a temp folder with Jan, Feb, Apr CSVs):
+
+```
+$ assurance check reports
+3 of 4 months from 2026-01 to 2026-04 in reports — not in this folder: March 2026 — Range inferred from filenames: earliest 2026-01, latest 2026-04 — uneven spacing, so monthly was read from the names rather than detected. Override with --expect / --from / --to.
+```
+
+With `--fail-on-gap` that same line exits `1`.
+
+`diff` compares any two sets of keys (no folder required). `pin` snapshots MCP tool definitions and detects drift. `drift` watches a binary outcome stream.
+
+## What it checks
+
+- Dated or numbered series in a folder (`check`) — months, weeks, days, numbered runs
+- Coverage over any two key sets (`diff`)
+- MCP tool-description drift since a pin (`pin`)
+- Shift in a binary outcome stream (`drift`)
+- Forwards: session audit, run budget, authority review, dependency install hooks
+
+## In CI
+
+| exit | means |
+|---|---|
+| `0` | checked; no gap (or not asked to fail on one) |
+| `1` | gap / unexpected key / stale pin / nothing it could check |
+| `2` | could not run (bad path, missing sibling package, bad JSON) |
+
+## Limits
+
+- **Does not invent the expected set.** `diff` takes your declaration; `check` derives one and prints how.
+- **No network, no telemetry, no keys.**
+- **A folder it cannot parse exits 1**, not 0 — silence is not a pass.
+- Skipped tool directories (`.git`, `node_modules`, …) are named, not folded into “files not opened” as if they were content.
+
+See the [root README](https://github.com/i-ops-hq/assurance#readme) and [CHANGELOG.md](CHANGELOG.md).

{assurance_cli-0.6.0 → assurance_cli-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "assurance-cli"
-version = "0.6.0"
+version = "0.6.2"
 description = "CLI for folder assurance checks — coverage, staleness, and baselines."
 readme = "README.md"
 license = { text = "Apache-2.0" }

{assurance_cli-0.6.0 → assurance_cli-0.6.2}/tests/test_cli.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import importlib.metadata
+
 import csv
 import json
 from pathlib import Path
@@ -838,15 +840,49 @@ def test_help_lists_every_forwarded_command(capsys) -> None:
     with pytest.raises(SystemExit):
         main(["--help"])
     out = capsys.readouterr().out
-    for name in ("deps", "budget", "authority"):
+    for name in ("deps", "budget", "authority", "audit", "hook"):
         assert name in out
 
 
+def test_the_hook_subcommand_reaches_the_installer(tmp_path: Path, capsys, monkeypatch) -> None:
+    """`assurance hook` is forwarded whole to assurance-budget, like `audit`."""
+    pytest.importorskip("assurance_budget.hook_setup")
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "claude"))
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "state"))
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "state"))  # where backups go on Windows
+    monkeypatch.chdir(tmp_path)
+    assert main(["hook", "install", "--yes", "--command", "uvx assurance@9.9.9 audit --hook --nudge"]) == 0
+    assert "uvx assurance@9.9.9 audit --hook --nudge" in (tmp_path / "claude" / "settings.json").read_text()
+    assert main(["hook", "status"]) in (0, 1)
+    assert "uvx assurance@9.9.9 audit --hook --nudge" in capsys.readouterr().out
+    assert main(["hook", "remove", "--yes"]) == 0
+    assert not (tmp_path / "claude" / "settings.json").exists()
+
+
 def test_version_flag(capsys) -> None:
     with pytest.raises(SystemExit) as exc:
         main(["--version"])
     assert exc.value.code == 0
-    assert capsys.readouterr().out.strip().startswith("assurance ")
+    out = capsys.readouterr().out
+    assert out.startswith("assurance ")
+    # Every installed part is named, on one unwrapped line: `pip install assurance` is one version
+    # over several packages, and printing only the cli's told a 0.1.1 user "0.6.0".
+    assert out.count("\n") == 1
+    assert f"cli {importlib.metadata.version('assurance-cli')}" in out
+    assert f"core {importlib.metadata.version('assurance-core')}" in out
+
+
+def test_help_lists_audit_first(capsys) -> None:
+    with pytest.raises(SystemExit):
+        main(["--help"])
+    usage = capsys.readouterr().out.splitlines()[1]
+    assert usage.strip().startswith("{audit,")
+
+
+def test_start_here_leads_with_audit_and_the_demo(capsys) -> None:
+    assert main([]) == 0
+    listed = [line.split()[1] for line in capsys.readouterr().out.splitlines() if line.startswith("  assurance ")]
+    assert listed[:2] == ["audit", "audit"]
 
 
 def test_budget_version_flag(capsys) -> None: