napkinstack 0.6.0__tar.gz → 0.6.2__tar.gz

{napkinstack-0.6.0 → napkinstack-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.6.0
+Version: 0.6.2
 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,21 +20,23 @@ 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.5.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): every barrier
-> the framework announces refuses what it claims to — the boundaries read the contracts a
-> module uses, a contract version someone relies on changes only with a proof, the module
-> checks and stale approvals are enforced, a verifier is not an author, and every verdict names
-> the framework that gave it. Proved on the project that exposed the defects: eight probes
-> replayed, each refused or accepted as announced. The contract proof now runs in the base's
-> tree, so a change cannot rewrite what judges it; the diagnosis says whether anything refuses
-> at all; and a record names what reached the default branch outside a pull request — it
-> records, it never refuses. A first pilot project, private, starts from here.
+> **Status: v0.6.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): what the
+> framework announces, it refuses — and what it cannot refuse, it says. The boundaries read the
+> contracts a module uses, a contract version someone relies on changes only with a proof that
+> runs in the base's tree, the module checks and stale approvals are enforced, a verifier is not
+> an author, and every verdict names the framework that gave it. Since v0.6.0, a document still
+> holding its template's words is refused, a deprecated module's consumers are named with their
+> removal date, and a contract change runs the checks of both sides — the producer and every
+> declared consumer. The diagnosis says whether anything refuses at all; a record names what
+> reached the default branch outside a pull request, and never refuses it. A first pilot
+> project, private, starts from here.
 > Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
 > [move to English](docs/governance/plans/2026-09-16-english-migration.md),
 > [frame, verify, approve](docs/governance/plans/2026-09-16-v0.3.0-frame-verify-approve.md),
 > [every barrier refuses](docs/governance/plans/2026-09-19-v0.4.0-every-barrier-refuses.md),
 > [a proof that cannot be rewritten](docs/governance/plans/2026-09-20-v0.5.0-a-proof-that-cannot-be-rewritten.md),
 > [the conformance suite](docs/governance/plans/2026-09-20-m12-conformance-suite.md),
+> [what is announced refuses](docs/governance/plans/2026-09-20-v0.6.0-what-is-announced-refuses.md),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey

{napkinstack-0.6.0 → napkinstack-0.6.2}/README.md

@@ -5,21 +5,23 @@ 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.5.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): every barrier
-> the framework announces refuses what it claims to — the boundaries read the contracts a
-> module uses, a contract version someone relies on changes only with a proof, the module
-> checks and stale approvals are enforced, a verifier is not an author, and every verdict names
-> the framework that gave it. Proved on the project that exposed the defects: eight probes
-> replayed, each refused or accepted as announced. The contract proof now runs in the base's
-> tree, so a change cannot rewrite what judges it; the diagnosis says whether anything refuses
-> at all; and a record names what reached the default branch outside a pull request — it
-> records, it never refuses. A first pilot project, private, starts from here.
+> **Status: v0.6.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): what the
+> framework announces, it refuses — and what it cannot refuse, it says. The boundaries read the
+> contracts a module uses, a contract version someone relies on changes only with a proof that
+> runs in the base's tree, the module checks and stale approvals are enforced, a verifier is not
+> an author, and every verdict names the framework that gave it. Since v0.6.0, a document still
+> holding its template's words is refused, a deprecated module's consumers are named with their
+> removal date, and a contract change runs the checks of both sides — the producer and every
+> declared consumer. The diagnosis says whether anything refuses at all; a record names what
+> reached the default branch outside a pull request, and never refuses it. A first pilot
+> project, private, starts from here.
 > Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
 > [move to English](docs/governance/plans/2026-09-16-english-migration.md),
 > [frame, verify, approve](docs/governance/plans/2026-09-16-v0.3.0-frame-verify-approve.md),
 > [every barrier refuses](docs/governance/plans/2026-09-19-v0.4.0-every-barrier-refuses.md),
 > [a proof that cannot be rewritten](docs/governance/plans/2026-09-20-v0.5.0-a-proof-that-cannot-be-rewritten.md),
 > [the conformance suite](docs/governance/plans/2026-09-20-m12-conformance-suite.md),
+> [what is announced refuses](docs/governance/plans/2026-09-20-v0.6.0-what-is-announced-refuses.md),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey

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

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.6.0"
+version = "0.6.2"
 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.6.0 → napkinstack-0.6.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.6.0"
+version = "0.6.2"
 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.6.0 → napkinstack-0.6.2}/src/napkinstack/project.py

@@ -23,6 +23,8 @@ from napkinstack import __version__
 SOURCE = "https://github.com/NapkinStack/engineering-os.git"
 ANSWERS = ".copier-answers.yml"
 DOWNGRADE = re.compile(r"You are downgrading from (\S+) to (\S+)\.")
+# The forms of a GitHub source Copier records, from which a release page can be named.
+GITHUB = re.compile(r"^(?:https://github\.com/|git@github\.com:|gh:)(?P<repo>[^/]+/[^/]+?)(?:\.git)?/?$")
 
 
 def default_ref() -> str:
@@ -30,6 +32,23 @@ def default_ref() -> str:
     return f"v{__version__}"
 
 
+def release_notes(source: str, previous: str, current: str) -> str:
+    """Where to read what a version changes, before taking it. The published package carries
+    the engine and not the skeleton, so comparing two releases of it cannot show what an update
+    merges (D63): the notes are the only channel, and the command that brings the change names
+    them (D62).
+
+    It names the whole distance travelled, never the target alone (D66). One `nstack update`
+    can cross several versions, and the change that conflicts with the project's own files may
+    come from any of them: a release page holds one version and cannot answer for the others.
+    The CHANGELOG at the tag holds them all."""
+    found = GITHUB.match(source.strip())
+    if found:
+        return (f"https://github.com/{found['repo']}/blob/{current}/CHANGELOG.md"
+                f" — every section above {previous}")
+    return f"CHANGELOG.md, every section above {previous}, in {source}"
+
+
 def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
     return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
 
@@ -67,15 +86,27 @@ def _explain(exc: Exception, command: str, where: Path, source: str, ref: str) -
     if text.startswith("Cannot update: version from last update not detected"):
         return (f"FAIL [{command}] The project does not come from a published version (_commit in {ANSWERS}): "
                 f"no merge base.\n{action}create the project from a vX.Y.Z tag.")
+    # An OSError carrying an errno is the filesystem answering, not the template being out of
+    # reach: a full disk, a read-only path, a directory an interrupted run left behind. Calling
+    # it "unreachable" sends the reader to --source, --ref and the network, none of which can
+    # help (D65). The OSErrors Copier raises for a template it could not read carry no errno.
+    if isinstance(exc, OSError) and exc.errno:
+        return (f"FAIL [{command}] {command} stopped on a local filesystem error: {text}\n"
+                f"{action}read the error above and fix what it names \u2014 space, permissions, or "
+                "something left behind by an interrupted run. The template and the network are "
+                "not in question.")
     if isinstance(exc, OSError) or text == "Local template must be a directory.":
         lines = [line.split("|", 1)[-1].strip() for line in text.splitlines() if line.strip()]
         # git writes the cause on an `error:` line and the outcome on a `fatal:` one; keeping
         # the last line alone drops the only one that says what happened (D54).
         detail = " — ".join(line for line in lines if line.startswith(("error:", "fatal:"))) or lines[-1]
-        # A git `error:` line means git refused something local, so the action is local too:
-        # Copier copies the template's uncommitted state into its clone before reading it.
-        local = ("git refused a file of the template's working tree, which Copier copies as it "
-                 "is: commit or stash it, or remove the file git names above.")
+        # A git `error:` line means git refused something local, and git has already named it:
+        # a file of the template's uncommitted state, which Copier copies into its clone, or
+        # anything else it could not open. The action points at that line rather than guessing
+        # which of the two it was (D55).
+        local = ("git named what it could not handle above: fix that file, or, when the "
+                 "template's working tree is uncommitted, commit or stash it — Copier copies it "
+                 "as it is.")
         remote = "check --source and --ref (a vX.Y.Z tag), and network access."
         return (f"FAIL [{command}] Template {source} at version {ref} unreachable: {detail}\n"
                 + action + (local if detail.startswith("error:") else remote))
@@ -89,9 +120,18 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
     from napkinstack.doctor import CHECKLIST
 
     destination = destination.resolve()
-    if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
-        print(f"FAIL [init] {destination} is not empty: nstack init creates a new project.\n"
-              "      Action: pick a folder that is missing or empty.")
+    if destination.exists() and not destination.is_dir():
+        print(f"FAIL [init] {destination} is a file, not a folder: nstack init creates a new "
+              "project.\n      Action: pick a folder that is missing or empty.")
+        return 1
+    # Naming what fills the folder: it is usually hidden — an editor's, an agent's — and a
+    # reader told only "not empty" goes hunting for it (D56).
+    entries = sorted(entry.name for entry in destination.iterdir()) if destination.exists() else []
+    if entries:
+        listed = ", ".join(entries[:4]) + (f", and {len(entries) - 4} more" if len(entries) > 4 else "")
+        print(f"FAIL [init] {destination} is not empty: it holds {listed}.\n"
+              "      Action: pick a folder that is missing or empty, or create the project in a "
+              f"folder inside it — nstack init {destination}/<project>.")
         return 1
     data = {question: value for question, value in answers.items() if value is not None}
     try:
@@ -178,5 +218,7 @@ def update(root: Path, ref: str) -> int:
 
     print(f"Branch {branch}: NapkinStack {previous} -> {current}, merged with the project's "
           "adaptations.")
+    print(f"What {previous} -> {current} changes, engine and project apart: "
+          f"{release_notes(str(_answers(root).get('_src_path') or ''), previous, current)}")
     print(f"\nNext step: git push -u origin {branch}, then open the PR; CI validates it.")
     return 0