napkinstack 0.9.4__tar.gz → 0.9.6__tar.gz

{napkinstack-0.9.4 → napkinstack-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.9.4
+Version: 0.9.6
 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.9.4, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.9.6, 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.9.4" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.9.4"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.9.6" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.9.6"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -117,6 +117,7 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
 | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
 | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared |
+| `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
 | `nstack pr-check` | The test sheet and the cycle, read from the pull request description |
 | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
 | `nstack skills` | Exposes the playbooks as skills for the agent |

{napkinstack-0.9.4 → napkinstack-0.9.6}/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.9.4, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.9.6, 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.9.4" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.9.4"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.9.6" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.9.6"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -102,6 +102,7 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
 | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
 | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared |
+| `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
 | `nstack pr-check` | The test sheet and the cycle, read from the pull request description |
 | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
 | `nstack skills` | Exposes the playbooks as skills for the agent |

{napkinstack-0.9.4 → napkinstack-0.9.6}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.9.4"
+version = "0.9.6"
 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.9.4 → napkinstack-0.9.6}/src/napkinstack/cli.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from pathlib import Path
 
@@ -73,9 +74,9 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="nstack", description="NapkinStack engine.")
     parser.add_argument("--version", action=_Version, nargs=0, help="the engine's version, and where it came from")
     sub = parser.add_subparsers(dest="command", required=True, metavar="command")
-    _add(sub, "manifests", "manifests, lifecycles, deprecations (M1-M10)",
+    _add(sub, "manifests", "manifests, lifecycles, deprecations, what a release assembles (M1-M11)",
          lambda a: manifests.run(a.root))
-    _add(sub, "boundaries", "declared graph against real graph (B1-B8)",
+    _add(sub, "boundaries", "declared graph against real graph, release artefacts included (B1-B9)",
          lambda a: boundaries.run(a.root))
     _add(sub, "plan", "the discovery, the charter and the cycles (C1-C8)", lambda a: plan.run(a.root))
     sk = _add(sub, "skills", "generates or checks the skills (S1-S4)",
@@ -115,6 +116,11 @@ def build_parser() -> argparse.ArgumentParser:
               lambda a: compat.run(a.root, a.module, a.base))
     cp.add_argument("module", nargs="?", help="module holding the contracts (default: all)")
     cp.add_argument("--base", default="origin/main")
+    rl = _add(sub, "release", "makes one module's artefacts, or all of them, each into dist/<module> "
+                              "(commands.release), with what follows a named module passed to it",
+              lambda a: _release(a))
+    rl.add_argument("module", nargs="?", help="module name (default: all, each after what it assembles)")
+    rl.add_argument("arguments", nargs=argparse.REMAINDER, help="passed to the named module's command")
     rn = _add(sub, "run", "starts a module locally (commands.run), with what follows passed to it",
               lambda a: _run(a))
     rn.add_argument("module")
@@ -173,6 +179,15 @@ def _named_root(argv: list[str]) -> Path:
     return Path(".")
 
 
+def _release(a) -> int:
+    """`release` passes what follows a named module to its command, as `run` does."""
+    root, arguments = a.root, list(a.arguments)
+    if "--root" in arguments[:-1]:
+        at = arguments.index("--root")
+        root, arguments = _root(arguments[at + 1]), arguments[:at] + arguments[at + 2:]
+    return modules.run_verb(root, "release", a.module, arguments)
+
+
 def _run(a) -> int:
     """`run` passes what follows the module to its command; `--root`, written there as the
     other verbs take it, is still the root."""
@@ -183,8 +198,16 @@ def _run(a) -> int:
     return modules.run_verb(root, "run", a.module, arguments)
 
 
+# What git hands a hook to name its repository (D126): a hook of a linked worktree gets GIT_DIR,
+# and every git the engine runs, in a module or a checkout of its own, would read that one.
+# The engine names its project with --root; git finds the rest from where it runs.
+GIT_LOCATION = ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR")
+
+
 def main(argv: list[str] | None = None) -> int:
     argv = sys.argv[1:] if argv is None else argv
+    for name in GIT_LOCATION:
+        os.environ.pop(name, None)
     if late := provenance.behind(_named_root(argv)):
         print(late, file=sys.stderr, flush=True)
     args = build_parser().parse_args(argv)

{napkinstack-0.9.4 → napkinstack-0.9.6}/src/napkinstack/fitness/boundaries.py

@@ -18,6 +18,8 @@ Rules:
   B7  a provided contract exists: its path holds its document, inside a module's folder
   B8  a contract consumed from a deprecated module (warning): a deprecated module takes no
       new consumer, and the existing ones migrate before its removal date
+  B9  another module's release artefacts — its folder of the project's dist/ — read only by a
+      module that declares it in `assembles` (D127)
 
 DETECTION — textual and deliberately simple, with no stack assumed.
   - A contract is read where a module's file names its path (contracts/billing-api/v1),
@@ -99,6 +101,10 @@ def load_modules(root: Path) -> dict[str, dict]:
                 "provides": contract_entries(data, "provides"),
                 "consumes": contract_entries(data, "consumes"),
                 "owns_data": {table for table in owns if isinstance(table, str)},
+                "assembles": {other for other in (data.get("assembles") or []) if isinstance(other, str)}
+                if isinstance(data.get("assembles"), list) else set(),
+                "commands": {verb: command for verb, command in (data.get("commands") or {}).items()
+                             if isinstance(command, str)} if isinstance(data.get("commands"), dict) else {},
             }
     return modules
 
@@ -256,17 +262,65 @@ def check_contracts(root: Path, modules: dict[str, dict]) -> dict[str, dict[str,
     return reads
 
 
+# Another module's artefacts, as a release reads them: from its own artefacts folder, whatever
+# the shell writes the variable ("$NSTACK_DIST", ${NSTACK_DIST}, %NSTACK_DIST%, $(NSTACK_DIST)…),
+# or by a relative path that lands in the project's dist/ — never a dist/ of the module's own.
+FROM_OWN = re.compile(r"NSTACK_DIST[\"'%)}\]]?/\.\./([A-Za-z0-9._-]+)")
+RELATIVE = re.compile(r"(?<![\w.-])((?:\.\./)+)dist/([A-Za-z0-9._-]+)")
+
+
+def artefact_reads(root: Path, mod: dict, relative: str, text: str) -> tuple[set[str], str]:
+    """The module folders whose artefacts a line reads, and the line without those reads."""
+    read: set[str] = set()
+
+    def taken(match: re.Match) -> str:
+        read.add(match.group(match.lastindex))
+        return " "
+
+    text = FROM_OWN.sub(taken, text)
+
+    def landed(match: re.Match) -> str:
+        # From the file, or from the module's folder, where its commands run.
+        for start in ((mod["path"] / relative).parent, mod["path"]):
+            where = start / match.group(1) / "dist" / match.group(2)
+            if Path(posixpath.normpath(where.as_posix())) == root / "dist" / match.group(2):
+                read.add(match.group(2))
+                return " "
+        return match.group(0)
+
+    return read, RELATIVE.sub(landed, text)
+
+
+def unassembled(root: Path, name: str, mod: dict, read: set[str], by_folder: dict[str, str], where: str) -> None:
+    """B9: the artefacts read of a module this one does not assemble."""
+    for folder in sorted(read):
+        other_name = by_folder.get(folder)
+        if other_name and other_name != name and folder not in mod["assembles"]:
+            fail("B9", where, f"'{name}' reads the release artefacts of '{folder}' without assembling it.\n"
+                              f"      Action: add {folder} to assembles in its MANIFEST "
+                              "(.nstack/handbook/09-platform.md §2), or stop reading them.")
+
+
 def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
-    """B2 and B5. Returns module -> modules whose code it references."""
+    """B2, B5 and B9. Returns module -> modules whose code it references."""
     code: dict[str, set[str]] = {name: set() for name in modules}
     others = {name: code_patterns(mod) for name, mod in modules.items()}
+    by_folder = {mod["dirname"]: name for name, mod in modules.items()}
     contracts = [str(p.get("path")).strip("/") for mod in modules.values() for p in mod["provides"] if p.get("path")]
     for name, mod in modules.items():
+        # The commands its manifest declares, a release's among them, run from its folder.
+        for verb, command in mod["commands"].items():
+            read, _ = artefact_reads(root, mod, "MANIFEST.yaml", command.replace("\\", "/"))
+            unassembled(root, name, mod, read, by_folder, f"{mod['path'].relative_to(root)}/MANIFEST.yaml (commands.{verb})")
         for relative, lines in read_files(mod):
             source = Path(relative).suffix in SOURCE_SUFFIXES
             for lineno, line in enumerate(lines, 1):
                 imports = source and IMPORT_HINTS.search(line)
                 text = line.replace("\\", "/")
+                # B9 - another module's artefacts: read here, they are its artefacts, not its code;
+                # what is left of the line is still B2's.
+                read, text = artefact_reads(root, mod, relative, text)
+                unassembled(root, name, mod, read, by_folder, f"{mod['path'].relative_to(root) / relative}:{lineno}")
                 for other_name, (code_import, reach, block) in others.items():
                     if other_name == name:
                         continue

{napkinstack-0.9.4 → napkinstack-0.9.6}/src/napkinstack/fitness/manifests.py

@@ -17,6 +17,8 @@ Rules:
   M8  runbook required when criticality >= high
   M9  complete file envelope (AGENTS.md, README.md, tests/)
   M10 user_facing declared: true when a user sees the module (.nstack/handbook/05-workflow.md §7)
+  M11 assembles names other modules, as a list, and no module waits for itself through it
+      (.nstack/handbook/09-platform.md §2, D127)
 
 Usage :  nstack manifests [--root ROOT]
 Output:  0 if everything passes, 1 otherwise. Every failure explains the rule broken.
@@ -357,6 +359,53 @@ def comparator_owed(root: Path, manifests: list[Path]) -> None:
                                 "(.nstack/handbook/03-contracts.md §3).")
 
 
+def assembled(manifests: list[Path], root: Path) -> None:
+    """M11: what a module's release assembles — other modules' artefacts — names them, and never
+    leads back to the module itself: `nstack release` runs each after what it assembles."""
+    wants: dict[str, list[str]] = {}
+    places: dict[str, str] = {}
+    for manifest in manifests:
+        text = manifest.read_text(encoding="utf-8")
+        places[manifest.parent.name] = f"{manifest.relative_to(root).as_posix()}:{line_of(text, 'assembles')}"
+        try:
+            data = yaml.safe_load(text) or {}
+        except yaml.YAMLError:
+            continue  # M2 says it
+        listed = data.get("assembles") if isinstance(data, dict) else None
+        if listed is None:
+            continue
+        name = manifest.parent.name
+        if not isinstance(listed, list) or not all(isinstance(other, str) for other in listed):
+            fail(name, "M11", "assembles must be a list of module names.\n"
+                              "      Action: assembles: [<module>, …] — the modules whose release artefacts this one's release reads.",
+                 places[name])
+            continue
+        wants[name] = listed
+    known = {manifest.parent.name for manifest in manifests}
+    for name, listed in wants.items():
+        for other in listed:
+            if other == name or other not in known:
+                fail(name, "M11", f"assembles '{other}', " + ("itself" if other == name else "a module that does not exist") + ".\n"
+                                  "      Action: name another module of this project, or remove the entry (.nstack/handbook/09-platform.md §2).",
+                     places[name])
+
+    def back(name: str, path: list[str]) -> list[str] | None:
+        for other in wants.get(name, []):
+            if other == path[0]:
+                return path + [other]
+            if other not in path and (found := back(other, path + [other])):
+                return found
+        return None
+
+    seen: set[frozenset[str]] = set()
+    for name in sorted(wants):
+        loop = back(name, [name])
+        if loop and frozenset(loop) not in seen:
+            seen.add(frozenset(loop))
+            fail(name, "M11", f"releases that wait for each other: {' → '.join(loop)}.\n"
+                              "      Action: one of them stops assembling the other.", places[name])
+
+
 def run(root: Path) -> int:
     failures.clear()
     warnings.clear()
@@ -372,6 +421,7 @@ def run(root: Path) -> int:
 
     for manifest in manifests:
         check_manifest(manifest, today, root)
+    assembled(manifests, root)
     comparator_owed(root, manifests)
 
     print(f"Manifests checked: {len(manifests)}")

{napkinstack-0.9.4 → napkinstack-0.9.6}/src/napkinstack/modules.py

@@ -1,6 +1,6 @@
 """
 A project's modules: creation (nstack new-module) and standard verbs (nstack bootstrap,
-check, test, run, e2e, clean), with no imposed stack (PRODUCT.md P1, PDR-0001 R5).
+check, test, run, e2e, clean, release), with no imposed stack (PRODUCT.md P1, PDR-0001 R5).
 
 Each verb runs the command declared in the `commands` section of the module's
 MANIFEST.yaml, from its folder, through the system shell. NapkinStack never assumes a
@@ -10,6 +10,7 @@ borrowed from Nx (`nx test <project>`) and moon (`moon run project:task`).
 
 from __future__ import annotations
 
+import os
 import re
 import shutil
 import shlex
@@ -31,6 +32,8 @@ LOGIN = r"[A-Za-z0-9](?:-?[A-Za-z0-9]){0,38}"  # the same rule, unanchored: a ha
 OWNER = re.compile(  # same rule as copier.yml: organisation/team, or a GitHub user
     rf"[A-Za-z0-9-]+/[A-Za-z0-9._-]+|{HANDLE}")
 OPTIONAL = {"bootstrap": "nothing to prepare", "e2e": "no end-to-end scenario", "clean": "nothing to clean"}  # undeclared: skipped
+# Undeclared, skipped when every module is released; asked of one module by name, it is owed.
+ALL_ONLY = {"release": "nothing to release"}
 # What a criticality requires is the matrix of .nstack/handbook/05-workflow.md §7, read once (assurance).
 
 RUNBOOK = """# Runbook - {name}
@@ -301,13 +304,36 @@ def _modules(root: Path) -> dict[str, Path]:
     return {manifest.parent.name: manifest.parent for manifest in find_manifests(root)}
 
 
+def release_order(known: dict[str, Path]) -> list[str]:
+    """Every module after those its release assembles (D127); otherwise in their order."""
+    wants = {}
+    for target, folder in known.items():
+        try:
+            listed = (yaml.safe_load((folder / "MANIFEST.yaml").read_text(encoding="utf-8")) or {}).get("assembles")
+        except (yaml.YAMLError, AttributeError):
+            listed = None
+        wants[target] = [other for other in listed if other in known] if isinstance(listed, list) else []
+    order: list[str] = []
+
+    def place(target: str, path: tuple[str, ...]) -> None:
+        if target in order or target in path:  # a loop is M11's to refuse
+            return
+        for other in wants[target]:
+            place(other, path + (target,))
+        order.append(target)
+
+    for target in known:
+        place(target, ())
+    return order
+
+
 def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | None = None) -> int:
     known = _modules(root)
     if name is not None and name not in known:
         print(f"FAIL [{verb}] module '{name}' not found in {root}: no MANIFEST.yaml under that name.\n"
               f"      Known modules: {', '.join(known) or 'none'}.")
         return 1
-    targets = [name] if name is not None else list(known)
+    targets = [name] if name is not None else (release_order(known) if verb == "release" else list(known))
     if not targets:
         print(f"No module in {root}: nothing to run.")
         return 0
@@ -323,16 +349,28 @@ def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | Non
             return 1
         command = commands.get(verb)
         if not command:
-            if verb in OPTIONAL:
-                print(f"-> {target}: {verb} not declared, {OPTIONAL[verb]}.")
+            if verb in OPTIONAL or (verb in ALL_ONLY and name is None):
+                print(f"-> {target}: {verb} not declared, {OPTIONAL.get(verb) or ALL_ONLY[verb]}.")
                 continue
             print(f"FAIL [{verb}] module '{target}': commands.{verb} not declared in {manifest}.\n"
                   "      Action: declare the module stack's command there (.nstack/handbook/09-platform.md §2).")
             return 1
         if arguments:
             command = " ".join([command, *map(shlex.quote, arguments)])
+        environment = None
+        if verb == "release":
+            # Its artefacts, and nothing left from an earlier release: dist/<module>, emptied first.
+            dist = root / "dist" / target
+            odd = next((path for path in (dist.parent, dist) if path.is_symlink() or (path.exists() and not path.is_dir())), None)
+            if odd is not None:
+                print(f"FAIL [release] {odd.relative_to(root)} is a link or a file, not a folder of the project's own: "
+                      "nothing is emptied through it.\n      Action: remove it, then release again.")
+                return 1
+            shutil.rmtree(dist, ignore_errors=True)
+            dist.mkdir(parents=True)
+            environment = {**os.environ, "NSTACK_DIST": str(dist.resolve())}
         print(f"-> {target}: {command}", flush=True)
-        code = subprocess.run(command, shell=True, cwd=known[target]).returncode
+        code = subprocess.run(command, shell=True, cwd=known[target], env=environment).returncode
         if code:
             print(f"FAIL [{verb}] module '{target}': `{command}` exited with {code}.")
             return code

{napkinstack-0.9.4 → napkinstack-0.9.6}/src/napkinstack/templates/module/MANIFEST.yaml

@@ -50,6 +50,11 @@ consumes: []
 #    version: v1
 #    module: identity
 
+# Modules whose release artefacts this module's release assembles — what a user installs,
+# made of theirs (.nstack/handbook/09-platform.md §2). Read in dist/<module>/, never in their
+# folders; `nstack release` runs them first (M11, B9).
+# assembles: []
+
 # Data owned. Nobody else accesses it directly.
 data:
   owns: []
@@ -75,6 +80,9 @@ commands:
 #  e2e:                          # optional: end-to-end scenarios; evidence written to .evidence/
 #  clean:                        # optional: remove what the commands above leave in this folder
 #                                # (build outputs); CI runs it after every job on a self-hosted runner
+#  release:                      # optional: the module's shippable artefacts, written into
+#                                # $NSTACK_DIST (dist/<module>/); `nstack release <module> …`
+#                                # passes the platform or target to it
 
 docs:
   readme: README.md