napkinstack 0.7.3__tar.gz → 0.7.4__tar.gz

{napkinstack-0.7.3 → napkinstack-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.7.3
+Version: 0.7.4
 Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
 License-Expression: MIT
 License-File: LICENSE
@@ -20,7 +20,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.7.3, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.7.4, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -84,8 +84,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.7.3" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.3"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.7.4" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.4"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -105,7 +105,7 @@ Each project then pins its version and changes it through `nstack update`.
 | Command | Role |
 |---|---|
 | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, GitHub checklist |
-| `nstack doctor` | Checks the workstation and the GitHub settings, read-only |
+| `nstack doctor` | Checks the workstation and the GitHub settings, read-only; names a newer published version |
 | `nstack settings` | Prints the calls that would bring the GitHub settings to the checklist; changes nothing |
 | `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
 | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |

{napkinstack-0.7.3 → napkinstack-0.7.4}/README.md

@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.7.3, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.7.4, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.7.3" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.3"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.7.4" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.4"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -90,7 +90,7 @@ Each project then pins its version and changes it through `nstack update`.
 | Command | Role |
 |---|---|
 | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, GitHub checklist |
-| `nstack doctor` | Checks the workstation and the GitHub settings, read-only |
+| `nstack doctor` | Checks the workstation and the GitHub settings, read-only; names a newer published version |
 | `nstack settings` | Prints the calls that would bring the GitHub settings to the checklist; changes nothing |
 | `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
 | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |

{napkinstack-0.7.3 → napkinstack-0.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.7.3"
+version = "0.7.4"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.7.3 → napkinstack-0.7.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.7.3"
+version = "0.7.4"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.7.3 → napkinstack-0.7.4}/src/napkinstack/doctor.py

@@ -5,6 +5,9 @@ Workflows inform; it is the GitHub settings that block, and they are not copied
 project. CHECKLIST is printed by nstack init, checked here, and repeated word for word in
 the foundation manual, skeleton/.nstack/handbook/INSTALL.md.jinja (a test verifies it).
 
+The registry is asked one question, without a token: which version is the latest published
+(NSTACK_REGISTRY_URL, otherwise https://pypi.org). An answer changes no exit code.
+
 GitHub is read with a token supplied by a human (GH_TOKEN, otherwise GITHUB_TOKEN):
 fine-grained, limited to the repository, Administration: read permission. Without a token,
 or when the API refuses a read, the setting is "not verified", never compliant. No write.
@@ -20,6 +23,8 @@ Rules:
       first minute. The plan check asks for it at the discovery's go (C8). Not reused.
   L6  CODEOWNERS starts with a default owner: the code owner review covers every path
   L7  the template source reachable by anyone: a repository, not a path on one machine
+  N1  information, never a gap (D91): a published version newer than the project's, read from
+      the registry — the one place a project learns of it. No other command opens a connection
   G1-G18  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
           repository, and on a private one G1-G5, G12, G13, G17 and G18 name the GitHub plan
           or option required
@@ -318,6 +323,45 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
     return results
 
 
+def _latest() -> str | None:
+    """The latest version the registry publishes, or None when it did not answer."""
+    registry = (os.environ.get("NSTACK_REGISTRY_URL") or "https://pypi.org").rstrip("/")
+    request = urllib.request.Request(f"{registry}/pypi/napkinstack/json",
+                                     headers={"Accept": "application/json", "User-Agent": f"nstack/{__version__}"})
+    try:
+        with urllib.request.urlopen(request, timeout=5) as response:
+            version = str(json.load(response)["info"]["version"])
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+    return version if PUBLISHED.fullmatch(f"v{version}") else None
+
+
+def _number(version: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in version.split("."))
+
+
+def _newer(answers: dict) -> None:
+    """Says whether a version newer than the project's is published (N1). Information: taking
+    a version is the team's decision, at a cycle's boundary, and nothing here counts it as a gap."""
+    commit = str(answers.get("_commit") or "")
+    if not PUBLISHED.fullmatch(commit):
+        return  # L1 already says the project is on no published version
+    print("\nNapkinStack")
+    latest = _latest()
+    if latest is None:
+        print("  NOT READ       the registry did not answer: whether a newer version is published is not known")
+        return
+    if _number(latest) <= _number(commit.removeprefix("v")):
+        print(f"  LATEST         the project is on {commit}, the latest published version")
+        return
+    from napkinstack.project import release_notes
+
+    print(f"  NEWER VERSION  v{latest} is published; the project is on {commit} — information, not a gap\n"
+          f"                 What it changes: {release_notes(str(answers.get('_src_path') or ''), commit, f'v{latest}')}\n"
+          f"                 To take it, at a cycle's boundary: uv tool install \"napkinstack=={latest}\" "
+          "--with-executables-from pre-commit, then nstack update")
+
+
 def _private(client: GitHub) -> bool:
     """Repository not public (private or internal); visibility unreadable: treated as public."""
     try:
@@ -374,6 +418,8 @@ def run(root: Path) -> int:
     for result in results:
         _display(*result)
 
+    _newer(answers)
+
     if plan.stage(root) == plan.UNFRAMED:
         # Said here and nowhere else, once: every other run names the stage in one line and
         # leaves it there. A stage is not a gap, and nothing below counts it as one.

{napkinstack-0.7.3 → napkinstack-0.7.4}/src/napkinstack/pull_request.py

@@ -185,6 +185,33 @@ def authors(root: Path, base: str, head: str, opener: str) -> tuple[set[str], se
     return logins, sessions, unnamed
 
 
+# A later commit does not name the earlier ones: the trailer is read on every commit an agent
+# made (D93). Said as two ways out, because rewriting a reviewed branch is not always allowed.
+UNNAMED_ACTION = (f"every commit an agent made carries \"{SESSION_TRAILER}: <id>\" (AGENTS.md §0) — "
+                  "a commit added now does not name the earlier ones: recommit them, on a new branch "
+                  "where the history is not rewritten; or have a person run the sheet.")
+
+
+def summary(body: str, authorship: tuple[set[str], set[str], list[str]]) -> list[str]:
+    """What the check read of a sheet, in a line, and what stands in a session's way before one
+    has done the work (D93): a verdict of one word told a verifier nothing of either."""
+    verifier, _, rows = read_sheet(body)
+    if not rows:
+        return []
+    counts: dict[str, int] = {}
+    for row in rows:
+        result = _result(row.get("result", ""))
+        result = result if result in RESULTS else "unreadable"
+        counts[result] = counts.get(result, 0) + 1
+    said = ", ".join(f"{number} {result}" for result, number in counts.items())
+    lines = [f"  Read: {len(rows)} scenario(s) — {said}; verifier: {verifier or 'not named'}, "
+             f"compared with {len(authorship[0])} account(s) and {len(authorship[1])} session(s) of the change"]
+    if authorship[2] and not SESSION.match(verifier):
+        lines.append(f"  NOTE: an agent's commits name no session ({', '.join(authorship[2])}): as it stands, "
+                     f"only a person can verify this change.\n        To let a session verify it: {UNNAMED_ACTION}")
+    return lines
+
+
 def check_verifier(verifier: str, authorship: tuple[set[str], set[str], list[str]], fail: Fail) -> None:
     """T2: the verifier is named — people as @handle anywhere on the line, an agent session as
     `session <id>` opening it — and none of the names is an author of the change."""
@@ -206,8 +233,7 @@ def check_verifier(verifier: str, authorship: tuple[set[str], set[str], list[str
                    "with a fresh context (.nstack/playbooks/verification.md).")
     elif session and unnamed:
         fail("T2", f"Test sheet: an agent's commits name no session ({', '.join(unnamed)}): the verifier "
-                   f"cannot be told from their author.\n      Action: the authoring session commits with "
-                   f"the trailer \"{SESSION_TRAILER}: <id>\" (AGENTS.md §0), then the sheet is run again.")
+                   f"cannot be told from their author.\n      Action: {UNNAMED_ACTION}")
 
 
 def _result(cell: str) -> str:
@@ -216,7 +242,7 @@ def _result(cell: str) -> str:
 
 def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
                 authorship: tuple[set[str], set[str], list[str]] = (set(), set(), []),
-                strict: bool = False) -> list[str]:
+                strict: bool = False, unchanged: Callable[[str], bool] = lambda commit: False) -> list[str]:
     """T1 to T5; returns the human-only scenarios, listed apart for the approver."""
     verifier, header, rows = read_sheet(body)
     if reasons and not rows:
@@ -257,7 +283,8 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
         if result == "passed" and (row["evidence"] in EMPTY or not SHA.fullmatch(commit)):
             fail("T3", f"scenario {ident}: passed without evidence and the commit verified.\n"
                        "      Action: link the screenshot, video, trace or log, and give the commit.")
-        elif result in {"passed", "failed"} and SHA.fullmatch(commit) and not head.startswith(commit):
+        elif (result in {"passed", "failed"} and SHA.fullmatch(commit) and not head.startswith(commit)
+              and not unchanged(commit)):
             # T4 split by kind (D71). An automated scenario is cheap and CI replays it when e2e is
             # declared, so it is re-run. One that was explored by hand costs a round: its evidence keeps the commit
             # it was produced on, and the verifier confirms at the head, naming what moved since.
@@ -362,12 +389,20 @@ def run(root: Path, base: str, body_file: Path | None = None) -> int:
 
     reasons = [reason for folder, found in modules.items() if (reason := sheet_reason(folder, found))]
     authorship = authors(root, base, head, os.environ.get("PR_AUTHOR", ""))
-    human_only = check_sheet(body, head, reasons, fail, authorship, rerun_at_head(modules))
+    # A commit whose tree is the head's is the head, for a sheet (D93): merging the default
+    # branch into a pull request that already carried it changes a hash and no file.
+    def tree_of(commit: str) -> str:
+        return _git(root, "rev-parse", "--verify", "--quiet", f"{commit}^{{tree}}").stdout.strip()
+
+    human_only = check_sheet(body, head, reasons, fail, authorship, rerun_at_head(modules),
+                             lambda commit: bool(tree_of(commit)) and tree_of(commit) == tree_of(head))
     if modules:
         check_cycle(root, body, labels, datetime.date.today(), fail)
 
     print(f"Modules touched : {len(modules)}" + "".join(f"\n  - {folder}" for folder in modules))
     print(f"Test sheet      : {'required' if reasons else 'not required'}")
+    for line in summary(body, authorship) if reasons else []:
+        print(line)
     for scenario in human_only:
         print(f"  For the approver, human only: {scenario}")
     for failure in failures: