napkinstack 0.34.0__tar.gz → 0.34.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {napkinstack-0.34.0 → napkinstack-0.34.2}/PKG-INFO +4 -4
- {napkinstack-0.34.0 → napkinstack-0.34.2}/README.md +3 -3
- {napkinstack-0.34.0 → napkinstack-0.34.2}/pyproject.toml +1 -1
- {napkinstack-0.34.0 → napkinstack-0.34.2}/pyproject.toml.orig +1 -1
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/agent.py +55 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/attest.py +1 -1
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/cli.py +1 -1
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/boundaries.py +43 -16
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/hold.py +35 -4
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/pull_request.py +11 -9
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/skills.py +17 -5
- {napkinstack-0.34.0 → napkinstack-0.34.2}/LICENSE +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/__init__.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/__main__.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/assurance.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/board.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/compat.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/discovery.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/doctor.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/evidence.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/__init__.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/hygiene.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/manifests.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/plan.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/pr_scope.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/landed.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/modules.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/owners.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/project.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/provenance.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/settings.py +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/README.md +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/AGENTS.md +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/README.md +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/src/.gitkeep +0 -0
- {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/tests/.gitkeep +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: napkinstack
|
|
3
|
-
Version: 0.34.
|
|
3
|
+
Version: 0.34.2
|
|
4
4
|
Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
|
|
5
5
|
License-Expression: MIT
|
|
6
6
|
License-File: LICENSE
|
|
@@ -22,7 +22,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
|
|
|
22
22
|
the project, which then receives new versions on demand; no application stack is imposed.
|
|
23
23
|
Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
|
|
24
24
|
|
|
25
|
-
> **Status: v0.34.
|
|
25
|
+
> **Status: v0.34.2, published** on [PyPI](https://pypi.org/project/napkinstack/).
|
|
26
26
|
> What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
|
|
27
27
|
> What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
|
|
28
28
|
|
|
@@ -86,8 +86,8 @@ To try it without installing anything, or to install it from this repository ins
|
|
|
86
86
|
registry — always pinned to a release tag:
|
|
87
87
|
|
|
88
88
|
```bash
|
|
89
|
-
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.34.
|
|
90
|
-
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.
|
|
89
|
+
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.34.2" nstack init my-project
|
|
90
|
+
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.2"
|
|
91
91
|
```
|
|
92
92
|
|
|
93
93
|
**Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
|
|
@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
|
|
|
5
5
|
the project, which then receives new versions on demand; no application stack is imposed.
|
|
6
6
|
Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
|
|
7
7
|
|
|
8
|
-
> **Status: v0.34.
|
|
8
|
+
> **Status: v0.34.2, published** on [PyPI](https://pypi.org/project/napkinstack/).
|
|
9
9
|
> What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
|
|
10
10
|
> What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
|
|
11
11
|
|
|
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
|
|
|
69
69
|
registry — always pinned to a release tag:
|
|
70
70
|
|
|
71
71
|
```bash
|
|
72
|
-
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.34.
|
|
73
|
-
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.
|
|
72
|
+
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.34.2" nstack init my-project
|
|
73
|
+
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.2"
|
|
74
74
|
```
|
|
75
75
|
|
|
76
76
|
**Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
|
|
@@ -19,6 +19,7 @@ dedicated system user).
|
|
|
19
19
|
from __future__ import annotations
|
|
20
20
|
|
|
21
21
|
import html
|
|
22
|
+
import io
|
|
22
23
|
import http.server
|
|
23
24
|
import json
|
|
24
25
|
import os
|
|
@@ -27,6 +28,7 @@ import secrets
|
|
|
27
28
|
import shutil
|
|
28
29
|
import subprocess
|
|
29
30
|
import sys
|
|
31
|
+
import tarfile
|
|
30
32
|
import time
|
|
31
33
|
import urllib.error
|
|
32
34
|
import urllib.parse
|
|
@@ -521,6 +523,55 @@ def _sockets(clone: Path) -> bool:
|
|
|
521
523
|
return isinstance(answers, dict) and answers.get("agent_sockets") is True
|
|
522
524
|
|
|
523
525
|
|
|
526
|
+
CLAUDE_SKILLS = ".claude/skills"
|
|
527
|
+
|
|
528
|
+
|
|
529
|
+
def _skills_beside(name: str, clone: Path) -> tuple[list[str], str | None]:
|
|
530
|
+
"""D261: Claude Code's sandbox write-protects `.claude/skills/` — an agent may not rewrite its own
|
|
531
|
+
instructions —, so git cannot write the committed skills there either: a merge or a checkout
|
|
532
|
+
bringing new ones stops. Run outside the sandbox, this leaves that folder out of the clone's
|
|
533
|
+
working tree (a sparse checkout: still in every commit, never written) and lays the skills of
|
|
534
|
+
the default branch, as last fetched, in a folder of the agent's own, given to Claude Code by
|
|
535
|
+
--add-dir. Nothing where the project commits no Claude Code skill. Returns (arguments, what to say)."""
|
|
536
|
+
if _git("rev-parse", "--verify", "-q", "origin/HEAD", cwd=clone).returncode:
|
|
537
|
+
return [], (" - skills: the clone does not know its remote's default branch (origin/HEAD), so its committed "
|
|
538
|
+
"Claude Code skills are not read.\n Action: git remote set-head origin --auto, in the clone.")
|
|
539
|
+
if _git("rev-parse", "--verify", "-q", f"origin/HEAD:{CLAUDE_SKILLS}", cwd=clone).returncode:
|
|
540
|
+
return [], None
|
|
541
|
+
patterns = ["/*", f"!/{CLAUDE_SKILLS}/"]
|
|
542
|
+
sparse = _git("config", "--bool", "core.sparseCheckout", cwd=clone).stdout.strip() == "true"
|
|
543
|
+
if not sparse:
|
|
544
|
+
made = _git("sparse-checkout", "set", "--no-cone", *patterns, cwd=clone)
|
|
545
|
+
if made.returncode:
|
|
546
|
+
return [], (f" - skills: {CLAUDE_SKILLS}/ could not be left out of the clone: "
|
|
547
|
+
f"{(made.stderr or made.stdout).strip()}\n"
|
|
548
|
+
" In the sandbox, a merge or a checkout that changes the skills will stop.")
|
|
549
|
+
elif _git("sparse-checkout", "list", cwd=clone).stdout.split() != patterns:
|
|
550
|
+
return [], (f" - skills: the clone is already a sparse checkout of someone else's patterns: left as is. "
|
|
551
|
+
f"In the sandbox, a merge or a checkout that changes {CLAUDE_SKILLS}/ will stop.")
|
|
552
|
+
kept = [line[2:] for line in _git("ls-files", "-v", "--", CLAUDE_SKILLS, cwd=clone).stdout.splitlines()
|
|
553
|
+
if not line.startswith("S ")]
|
|
554
|
+
left = (f" - skills: {CLAUDE_SKILLS}/ left out of the clone's working tree, which the sandbox write-protects"
|
|
555
|
+
if not kept else
|
|
556
|
+
f" - skills: {CLAUDE_SKILLS}/ NOT left out of the clone: changed there, kept by git ({', '.join(kept[:3])}). "
|
|
557
|
+
f"In the sandbox, a merge that changes them will stop.\n"
|
|
558
|
+
f" Action: commit or restore them, then nstack agent run {name} again")
|
|
559
|
+
folder = home() / name / "skills"
|
|
560
|
+
shutil.rmtree(folder, ignore_errors=True)
|
|
561
|
+
folder.mkdir(parents=True)
|
|
562
|
+
archive = subprocess.run(["git", "archive", "origin/HEAD", CLAUDE_SKILLS], cwd=clone, capture_output=True)
|
|
563
|
+
try:
|
|
564
|
+
if archive.returncode:
|
|
565
|
+
raise OSError(archive.stderr.decode(errors="replace").strip())
|
|
566
|
+
with tarfile.open(fileobj=io.BytesIO(archive.stdout)) as tar:
|
|
567
|
+
tar.extractall(folder, filter="data")
|
|
568
|
+
except (tarfile.TarError, OSError) as exc:
|
|
569
|
+
return [], f"{left}.\n - skills: the default branch's could not be laid for the agent ({exc}): it starts without them."
|
|
570
|
+
return ["--add-dir", str(folder)], (
|
|
571
|
+
f"{left}; the default branch's, as last fetched, in {folder} (--add-dir), laid again at each run: "
|
|
572
|
+
"a change there lasts one session and reaches no one.")
|
|
573
|
+
|
|
574
|
+
|
|
524
575
|
def _claude_settings(name: str, sockets: bool = False) -> Path:
|
|
525
576
|
"""Claude Code's settings of the agent's own, added to the person's (D199): their sandbox, when
|
|
526
577
|
on, cuts the forge — the agent's git and gh go nowhere — and lets it write nowhere outside its
|
|
@@ -670,6 +721,10 @@ def run(name: str, command: list[str]) -> int:
|
|
|
670
721
|
"no write to .git/config.\n"
|
|
671
722
|
" - the agent checks who it is with: nstack agent status", sys.stderr)
|
|
672
723
|
if Path(command[0]).name.lower() in ("claude", "claude.exe", "claude.cmd"):
|
|
724
|
+
beside, said = _skills_beside(name, Path(app["clone"]))
|
|
725
|
+
command = [command[0], *beside, *command[1:]]
|
|
726
|
+
if said:
|
|
727
|
+
_say(said, sys.stderr)
|
|
673
728
|
if any(arg == "--settings" or arg.startswith("--settings=") for arg in command[1:]):
|
|
674
729
|
_say(f" - claude: your --settings is kept; if your sandbox is on, its sandbox.network.allowedDomains "
|
|
675
730
|
f"needs {', '.join(_hosts())}.", sys.stderr)
|
|
@@ -226,7 +226,7 @@ def _remote(root: Path) -> str | None:
|
|
|
226
226
|
branch = _git(root, "symbolic-ref", "--quiet", "--short", "HEAD", check=False).stdout.strip()
|
|
227
227
|
if branch:
|
|
228
228
|
named = _git(root, "config", f"branch.{branch}.remote", check=False).stdout.strip()
|
|
229
|
-
if named:
|
|
229
|
+
if named and named != ".": # "." tracks a local branch: no remote
|
|
230
230
|
return named
|
|
231
231
|
remotes = _git(root, "remote", check=False).stdout.split()
|
|
232
232
|
return "origin" if "origin" in remotes else None
|
|
@@ -204,7 +204,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
204
204
|
lambda a: hold.release(a.root, a.deliverable, a.session, a.person))
|
|
205
205
|
rs.add_argument("deliverable", help="the deliverable's identifier, D<n>, or '#<n>', an issue")
|
|
206
206
|
rs.add_argument("--session", help="the agent's session, written on the release")
|
|
207
|
-
rs.add_argument("--person", help="who releases it, such as @alice (default: git's user)")
|
|
207
|
+
rs.add_argument("--person", help="who releases it, such as @alice (default: the hold's person when --session is one of its sessions, else git's user)")
|
|
208
208
|
dl = _add(sub, "deliver", "records that a merged deliverable is delivered, criterion by criterion, with no pull request; "
|
|
209
209
|
"refused with no merge of it",
|
|
210
210
|
lambda a: hold.deliver_command(a.root, a.deliverable, a.held or [], a.session, a.person, a.write_states))
|
|
@@ -23,11 +23,16 @@ Rules:
|
|
|
23
23
|
|
|
24
24
|
DETECTION — textual and deliberately simple, with no stack assumed.
|
|
25
25
|
- A contract is read where a module's file names its path (contracts/billing-api/v1),
|
|
26
|
-
its name and version (billing-api/v1), or its name as a quoted string ("billing-api")
|
|
26
|
+
its name and version (billing-api/v1), or its name as a quoted string ("billing-api")
|
|
27
|
+
beside a quoted version or "contracts" — the path in pieces. Its quoted name alone is the
|
|
28
|
+
read of a contract the module consumes, and nothing for one it does not (D259).
|
|
27
29
|
- Another module's code is referenced where an import line names its folder from the root
|
|
28
30
|
(modules.billing, modules/billing, from modules import billing) or its package — opening
|
|
29
31
|
the statement, or quoted as a module specifier, or alone on a Go import block's line — or
|
|
30
|
-
where any line reaches into its folder (../billing/, modules/billing/).
|
|
32
|
+
where any line reaches into its folder (../billing/, modules/billing/). In a Python
|
|
33
|
+
file, a package named like the standard library's (import platform) is Python's own
|
|
34
|
+
(D258); in a JavaScript, TypeScript or Go file, only the quoted specifier names one — the
|
|
35
|
+
word after `import` is the file's own name for it (D260). Its package is its
|
|
31
36
|
folder's name, or `code_name` when the code names it otherwise (com.acme.billing). A
|
|
32
37
|
relative path is read from the file's folder and from the module's — where the verbs run —
|
|
33
38
|
and a path that names something of the module's own, or a contract it provides, is none.
|
|
@@ -53,6 +58,7 @@ SOURCE_SUFFIXES = {
|
|
|
53
58
|
".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java", ".kt",
|
|
54
59
|
".rb", ".php", ".cs", ".swift", ".scala", ".ex", ".exs",
|
|
55
60
|
}
|
|
61
|
+
QUOTED_SPECIFIER = {".ts", ".tsx", ".js", ".jsx", ".go"} # the word after `import` is a binding (D260)
|
|
56
62
|
SKIP_DIRS = {"node_modules", "dist", "build", "target", "vendor", ".git",
|
|
57
63
|
"__pycache__", ".venv", "venv", "coverage", "generated"}
|
|
58
64
|
IMPORT_HINTS = re.compile(
|
|
@@ -123,22 +129,30 @@ def read_files(module: dict):
|
|
|
123
129
|
yield relative, data.decode("utf-8", errors="ignore").splitlines()
|
|
124
130
|
|
|
125
131
|
|
|
126
|
-
def code_patterns(other: dict) -> tuple[re.Pattern, re.Pattern, re.Pattern]:
|
|
127
|
-
"""(import of its code, path into its folder
|
|
128
|
-
root, or its package opening the statement (Python, Rust, Java)
|
|
129
|
-
specifier (JavaScript, TypeScript, Ruby). On any line: a relative or rooted
|
|
130
|
-
folder — ending where the folder's name does, so that ../billing.csv is not billing.
|
|
132
|
+
def code_patterns(other: dict) -> tuple[re.Pattern, re.Pattern, re.Pattern, re.Pattern]:
|
|
133
|
+
"""(import of its code, path into its folder, Go import block, its bare package). On an import
|
|
134
|
+
line: its folder named from the root, or its package opening the statement (Python, Rust, Java)
|
|
135
|
+
or quoted as a module specifier (JavaScript, TypeScript, Ruby). On any line: a relative or rooted
|
|
136
|
+
path into its folder — ending where the folder's name does, so that ../billing.csv is not billing.
|
|
137
|
+
A package named like a module of Python's standard library is apart: in a Python file,
|
|
138
|
+
`import platform` is Python's own (D258). In JavaScript, TypeScript or Go the package opening the
|
|
139
|
+
statement is the binding, not the module: only the specifier counts (D260)."""
|
|
131
140
|
code, folder = re.escape(other["code_name"]), re.escape(other["dirname"])
|
|
132
141
|
rooted = "|".join(MODULE_DIRS)
|
|
133
142
|
imports = re.compile(rf"(?<![\w-])(?:{rooted})[./]{folder}(?![\w-])"
|
|
134
143
|
rf"|^\s*from\s+(?:{rooted})\s+import\s+(?:[\w\s]*,\s*)?{folder}(?![\w-])"
|
|
135
|
-
rf"|^\s*(?:from|import|(?:pub\s+)?use|extern\s+crate)\s+{code}(?![\w-])"
|
|
136
144
|
rf"|(?:\bfrom\s+|\b(?:require|import)\s*\(\s*|^\s*(?:import|require)\s+)"
|
|
137
145
|
rf"[\"'](?:@[\w.-]+/)?{code}(?:/[^\"']*)?[\"']")
|
|
138
146
|
reach = re.compile(rf"(?<![\w.-])\.\./(?:\.\./)*{folder}(?=/|[\"'\s)]|$)"
|
|
139
147
|
rf"|(?<![\w-])(?:{rooted})/{folder}/")
|
|
140
148
|
block = re.compile(rf"^\s*(?:\w+\s+)?\"[^\"]*(?<![\w-])(?:{rooted})/{folder}(?:/[^\"]*)?\"\s*$")
|
|
141
|
-
|
|
149
|
+
package = re.compile(rf"^\s*(?:from|import|(?:pub\s+)?use|extern\s+crate)\s+{code}(?![\w-])")
|
|
150
|
+
return imports, reach, block, package
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def _standard(other: dict) -> bool:
|
|
154
|
+
"""Its package bears the name of a module of Python's standard library (platform, json, logging)."""
|
|
155
|
+
return other["code_name"] in sys.stdlib_module_names
|
|
142
156
|
|
|
143
157
|
|
|
144
158
|
TOKEN = re.compile(r"[^\s'\"`)(,;]+")
|
|
@@ -169,8 +183,10 @@ def _lands_elsewhere(root: Path, mod: dict, relative: str, found: str, other: di
|
|
|
169
183
|
return any(place == target or place.startswith(f"{target}/") for place in (from_file, from_module))
|
|
170
184
|
|
|
171
185
|
|
|
172
|
-
def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, re.Pattern]]:
|
|
173
|
-
"""(contract, version or None, pattern) for every contract a module provides.
|
|
186
|
+
def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, re.Pattern, re.Pattern | None]]:
|
|
187
|
+
"""(contract, version or None, pattern, pieces) for every contract a module provides. Its name
|
|
188
|
+
alone, quoted, has `pieces`: the quoted `contracts` or version that makes it the path written in
|
|
189
|
+
pieces (ROOT / "contracts" / "billing-api"); without them, it is a word (D259)."""
|
|
174
190
|
patterns = []
|
|
175
191
|
for mod in modules.values():
|
|
176
192
|
for provided in mod["provides"]:
|
|
@@ -181,8 +197,9 @@ def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, r
|
|
|
181
197
|
paths = [rf"(?<![\w-]){n}/{v}(?![\w-])"]
|
|
182
198
|
if isinstance(provided.get("path"), str):
|
|
183
199
|
paths.append(re.escape(provided["path"].strip("/")))
|
|
184
|
-
patterns.append((name, version, re.compile("|".join(paths))))
|
|
185
|
-
patterns.append((name, None, re.compile(rf"[\"'`]{n}[\"'`]")
|
|
200
|
+
patterns.append((name, version, re.compile("|".join(paths)), None))
|
|
201
|
+
patterns.append((name, None, re.compile(rf"[\"'`]{n}[\"'`]"),
|
|
202
|
+
re.compile(rf"[\"'`](?:contracts|{v})[\"'`]")))
|
|
186
203
|
return patterns
|
|
187
204
|
|
|
188
205
|
|
|
@@ -231,12 +248,17 @@ def check_contracts(root: Path, modules: dict[str, dict]) -> dict[str, dict[str,
|
|
|
231
248
|
for name, mod in modules.items():
|
|
232
249
|
own = {p.get("contract") for p in mod["provides"]}
|
|
233
250
|
consumed = {(c.get("contract"), c.get("version")) for c in mod["consumes"]}
|
|
251
|
+
declared = {contract for contract, _ in consumed}
|
|
234
252
|
seen: set[tuple[str, str | None]] = set()
|
|
235
253
|
for relative, lines in read_files(mod):
|
|
236
254
|
for lineno, line in enumerate(lines, 1):
|
|
237
|
-
for contract, version, pattern in patterns:
|
|
255
|
+
for contract, version, pattern, pieces in patterns:
|
|
238
256
|
if contract in own or not pattern.search(line):
|
|
239
257
|
continue
|
|
258
|
+
# A word that happens to be its name (an event's, a label's) reads nothing,
|
|
259
|
+
# unless the module consumes that contract: then it is its read (D259).
|
|
260
|
+
if pieces and not pieces.search(line) and contract not in declared:
|
|
261
|
+
continue
|
|
240
262
|
producer = next((v for k, v in provided.items() if k[0] == contract), None)
|
|
241
263
|
if producer:
|
|
242
264
|
reads[name].setdefault(producer, set()).add(contract)
|
|
@@ -315,6 +337,8 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
|
|
|
315
337
|
unassembled(root, name, mod, read, by_folder, f"{mod['path'].relative_to(root)}/MANIFEST.yaml (commands.{verb})")
|
|
316
338
|
for relative, lines in read_files(mod):
|
|
317
339
|
source = Path(relative).suffix in SOURCE_SUFFIXES
|
|
340
|
+
python = Path(relative).suffix == ".py"
|
|
341
|
+
quoted = Path(relative).suffix in QUOTED_SPECIFIER
|
|
318
342
|
for lineno, line in enumerate(lines, 1):
|
|
319
343
|
imports = source and IMPORT_HINTS.search(line)
|
|
320
344
|
text = line.replace("\\", "/")
|
|
@@ -322,10 +346,13 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
|
|
|
322
346
|
# what is left of the line is still B2's.
|
|
323
347
|
read, text = artefact_reads(root, mod, relative, text)
|
|
324
348
|
unassembled(root, name, mod, read, by_folder, f"{mod['path'].relative_to(root) / relative}:{lineno}")
|
|
325
|
-
for other_name, (code_import, reach, block) in others.items():
|
|
349
|
+
for other_name, (code_import, reach, block, package) in others.items():
|
|
326
350
|
if other_name == name:
|
|
327
351
|
continue
|
|
328
|
-
via_import = (imports and code_import.search(line)
|
|
352
|
+
via_import = ((imports and (code_import.search(line)
|
|
353
|
+
or (package.search(line) and not quoted
|
|
354
|
+
and not (python and _standard(modules[other_name])))))
|
|
355
|
+
or (source and block.search(line)))
|
|
329
356
|
reaches = [m for m in reach.finditer(text)
|
|
330
357
|
if not _names_a_contract(root, mod, relative,
|
|
331
358
|
TOKEN.match(text, m.start()).group(), contracts)
|
|
@@ -94,6 +94,11 @@ class Unreachable(Exception):
|
|
|
94
94
|
"""The remote could not be read: nothing about its holds is known."""
|
|
95
95
|
|
|
96
96
|
|
|
97
|
+
def _then(error: Exception, action: str) -> str:
|
|
98
|
+
"""The Action line a caller adds, unless the error already says its own."""
|
|
99
|
+
return "" if "Action:" in str(error) else f"\n Action: {action}"
|
|
100
|
+
|
|
101
|
+
|
|
97
102
|
def fetch(root: Path, again: bool = False) -> str | None:
|
|
98
103
|
"""Brings the remote's holds, work branches and default branch in, as they are now; returns
|
|
99
104
|
the remote's name. `again`: the read after a refused push, which must see the hold that won."""
|
|
@@ -108,9 +113,29 @@ def fetch(root: Path, again: bool = False) -> str | None:
|
|
|
108
113
|
raise Unreachable(f"no answer from {name} within a minute") from None
|
|
109
114
|
if got.returncode != 0:
|
|
110
115
|
raise Unreachable(got.stderr.strip().splitlines()[0] if got.stderr.strip() else f"{name} refused the fetch")
|
|
116
|
+
_not_a_clone(root, name)
|
|
111
117
|
return name
|
|
112
118
|
|
|
113
119
|
|
|
120
|
+
def _not_a_clone(root: Path, name: str) -> None:
|
|
121
|
+
"""A remote that is a local clone of the forge — a verifier's `git clone --shared` of a working
|
|
122
|
+
clone — keeps the holds it fetched (refs/remotes, nstack's mirror), never as branches of its
|
|
123
|
+
own: a fetch of its branches brings none, and "nobody holds it" would be a guess. Said instead."""
|
|
124
|
+
if _git(root, "for-each-ref", "--count=1", f"{MIRROR}/hold").stdout.strip():
|
|
125
|
+
return # holds came in: the remote serves them
|
|
126
|
+
url = _git(root, "remote", "get-url", name).stdout.strip()
|
|
127
|
+
if not url.startswith("file://"):
|
|
128
|
+
if re.match(r"[A-Za-z][A-Za-z0-9+.-]*://", url):
|
|
129
|
+
return
|
|
130
|
+
if re.match(r"[^/\\]+:", url) and not re.match(r"[A-Za-z]:[/\\]", url):
|
|
131
|
+
return # user@host:path, never a local path; a Windows drive letter is one
|
|
132
|
+
served = _git(root, "ls-remote", name).stdout
|
|
133
|
+
if re.search(r"\trefs/(nstack-remote/hold|remotes/[^\n]*/nstack/hold)/", served):
|
|
134
|
+
raise Unreachable(f"{name} is a clone ({url}), not the forge: the holds it fetched are not its own "
|
|
135
|
+
f"branches.\n Action: point {name} at the forge (git remote set-url {name} <the "
|
|
136
|
+
"forge's address>), or run this where the remote is the forge")
|
|
137
|
+
|
|
138
|
+
|
|
114
139
|
def _ci_credential(root: Path, name: str) -> list[str]:
|
|
115
140
|
"""In GitHub Actions, the job's token for this one command: the checkout keeps no credential
|
|
116
141
|
(`persist-credentials: false`), and a private repository's holds are read with it (ADR-0008).
|
|
@@ -495,7 +520,7 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
|
|
|
495
520
|
name = fetch(root)
|
|
496
521
|
except Unreachable as error:
|
|
497
522
|
print(f"FAIL [hold] the remote cannot be read: nothing is known of {ident}'s hold.\n"
|
|
498
|
-
f" {error}
|
|
523
|
+
f" {error}{_then(error, 'check the network and the remote, then again.')}")
|
|
499
524
|
return 1
|
|
500
525
|
current = read(root, cycle, ident)
|
|
501
526
|
title = _issue_title(root, name, number) if number else title
|
|
@@ -600,6 +625,7 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
|
|
|
600
625
|
cycle = None if number else plan.accepted_cycle(root)
|
|
601
626
|
stem = ISSUES if number else (cycle[0].stem if cycle else None)
|
|
602
627
|
ident = f"issue-{number}" if number else ident
|
|
628
|
+
named = bool(person)
|
|
603
629
|
person, session = _person(root, person), (session or "").strip() or None
|
|
604
630
|
if any(not value.isprintable() for value in (person, session or "")):
|
|
605
631
|
print("FAIL [hold] a person or a session holds a line break or a control character.\n"
|
|
@@ -608,9 +634,11 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
|
|
|
608
634
|
try:
|
|
609
635
|
name = fetch(root)
|
|
610
636
|
except Unreachable as error:
|
|
611
|
-
print(f"FAIL [hold] the remote cannot be read.\n {error}
|
|
637
|
+
print(f"FAIL [hold] the remote cannot be read.\n {error}{_then(error, 'check it, then again.')}")
|
|
612
638
|
return 1
|
|
613
639
|
current = read(root, stem, ident) if stem else Hold()
|
|
640
|
+
if not named and session and session.casefold() in {one.casefold() for one in current.sessions}:
|
|
641
|
+
person = current.person # the holding session gives it back for its person, never git's user
|
|
614
642
|
if not current.held and not current.recorded:
|
|
615
643
|
ended = None if number else _ended(root, ident, stem)
|
|
616
644
|
if ended:
|
|
@@ -633,8 +661,11 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
|
|
|
633
661
|
f"--session {session}.")
|
|
634
662
|
return 1
|
|
635
663
|
if not (same(current.person, person) or is_decider or stale):
|
|
664
|
+
unnamed = ("" if named else f"\n No --person was given: git's user, {person}, was read. If you work for "
|
|
665
|
+
f"{current.person}, run again with --person {current.person}"
|
|
666
|
+
+ (", or with the session that holds it." if current.sessions else "."))
|
|
636
667
|
print(f"FAIL [hold] {ident} is {said(current)}: only its holder or the decider ({decider or 'none named'}) "
|
|
637
|
-
"releases a hold that is not stale
|
|
668
|
+
f"releases a hold that is not stale.{unnamed}\n Action: ask them.")
|
|
638
669
|
return 1
|
|
639
670
|
sha = _event(root, current.tip, ident, "release", person, session)
|
|
640
671
|
ok, where = _record(root, name, stem, ident, sha)
|
|
@@ -1004,7 +1035,7 @@ def deliver(root: Path, ident: str, given: list[str], session: str | None = None
|
|
|
1004
1035
|
try:
|
|
1005
1036
|
name = fetch(root)
|
|
1006
1037
|
except Unreachable as error:
|
|
1007
|
-
print(f"FAIL [deliver] the remote cannot be read.\n {error}
|
|
1038
|
+
print(f"FAIL [deliver] the remote cannot be read.\n {error}{_then(error, 'check it, then again.')}")
|
|
1008
1039
|
return 1
|
|
1009
1040
|
if _shallow(root):
|
|
1010
1041
|
print(f"FAIL [deliver] a shallow clone cannot read {ident}'s merges.\n Action: git fetch --unshallow, then again.")
|
|
@@ -605,12 +605,14 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
|
|
|
605
605
|
elif _on_record(root, path, data, match[1]):
|
|
606
606
|
warn(f"[K3] deliverable {match[1]} is on record as delivered, and this pull request delivers it again.\n"
|
|
607
607
|
f" Action: if its record is wrong, nstack unclaim {match[1]}; a defect found since is an issue of its own.")
|
|
608
|
-
elif states[match[1]] == "ready" and
|
|
608
|
+
elif states[match[1]] == "ready" and _nobody_holds(root, match[1]):
|
|
609
609
|
# Said, not refused. The hold says the work started; the cycle file stays the decider's
|
|
610
610
|
# record, never changed by a delivery — under `docs/`, a human would have to approve it.
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
611
|
+
from napkinstack import hold
|
|
612
|
+
|
|
613
|
+
warn(f"[K3] deliverable {match[1]} is still 'ready' and nobody holds it on {hold.remote(root) or 'this repository'} "
|
|
614
|
+
f"while this pull request delivers it.\n Action: nstack claim {match[1]} — the hold says it is in "
|
|
615
|
+
f"progress; {path.name} changes never in a delivery's pull request.")
|
|
614
616
|
|
|
615
617
|
|
|
616
618
|
def _on_record(root: Path, path: Path, data: dict, ident: str) -> bool:
|
|
@@ -624,12 +626,12 @@ def _on_record(root: Path, path: Path, data: dict, ident: str) -> bool:
|
|
|
624
626
|
return ident in plan.delivered_in(root, path, data)
|
|
625
627
|
|
|
626
628
|
|
|
627
|
-
def
|
|
628
|
-
"""Whether
|
|
629
|
+
def _nobody_holds(root: Path, ident: str) -> bool:
|
|
630
|
+
"""Whether the holds were read and none holds the deliverable. Holds that cannot be read are
|
|
631
|
+
no answer: K5 says why, and K3 never concludes "nobody"."""
|
|
629
632
|
from napkinstack import hold
|
|
630
633
|
|
|
631
|
-
|
|
632
|
-
return found is not None and not isinstance(found, str)
|
|
634
|
+
return hold.judge(root, ident) is None
|
|
633
635
|
|
|
634
636
|
|
|
635
637
|
def merge_sessions(root: Path, base: str, head: str) -> set[str]:
|
|
@@ -660,7 +662,7 @@ def check_hold(root: Path, body: str, labels: set[str], authorship: tuple[set[st
|
|
|
660
662
|
ident = match[1].upper()
|
|
661
663
|
found = hold.judge(root, ident)
|
|
662
664
|
if isinstance(found, str):
|
|
663
|
-
warn(f"[K5] the holds are not read
|
|
665
|
+
warn(f"[K5] the holds are not read: who holds {ident} is not judged here.\n {found}")
|
|
664
666
|
return
|
|
665
667
|
if found is None:
|
|
666
668
|
return
|
|
@@ -168,11 +168,18 @@ def run(root: Path, check_only: bool = False) -> int:
|
|
|
168
168
|
return 0
|
|
169
169
|
|
|
170
170
|
removed: set[str] = set()
|
|
171
|
+
refused: list[str] = []
|
|
171
172
|
for folder in FOLDERS:
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
173
|
+
try:
|
|
174
|
+
for name, entry in sorted(mapping.items()):
|
|
175
|
+
path, content = build(root, name, entry, folder)
|
|
176
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
177
|
+
path.write_text(content, encoding="utf-8")
|
|
178
|
+
except OSError as exc: # an agent's sandbox write-protects .claude/skills/ alone (D261)
|
|
179
|
+
if folder != FOLDERS[0]:
|
|
180
|
+
raise
|
|
181
|
+
refused.append(f"{folder.as_posix()}/ could not be written ({exc.strerror or exc})")
|
|
182
|
+
continue
|
|
176
183
|
# A playbook gone leaves its skill behind, still loaded by the agent: removed when generated
|
|
177
184
|
# here, never a skill a person wrote (no banner).
|
|
178
185
|
for made_dir in sorted((root / folder).glob("*/")):
|
|
@@ -182,10 +189,15 @@ def run(root: Path, check_only: bool = False) -> int:
|
|
|
182
189
|
if not any(made_dir.iterdir()):
|
|
183
190
|
made_dir.rmdir()
|
|
184
191
|
removed.add(made_dir.name)
|
|
185
|
-
|
|
192
|
+
written = [folder.as_posix() for folder in FOLDERS if not any(said.startswith(f"{folder.as_posix()}/") for said in refused)]
|
|
193
|
+
print(f"Skills generated in {' and '.join(f'{folder}/' for folder in written) or 'no folder'}: {len(mapping)}"
|
|
186
194
|
+ (f"; removed, their playbook gone: {', '.join(sorted(removed))}" if removed else ""))
|
|
187
195
|
for name in sorted(mapping):
|
|
188
196
|
print(f" - {name}")
|
|
197
|
+
for said in refused:
|
|
198
|
+
print(f"WARNING: {said}. Inside an agent's sandbox, that folder is protected: an agent never rewrites its "
|
|
199
|
+
"own instructions.\n"
|
|
200
|
+
" Action: a person runs nstack skills outside any sandbox and commits it — S3 says it until then.")
|
|
189
201
|
for folder in _ignored(root):
|
|
190
202
|
print(f"WARNING: {folder}/ is ignored by git: an agent starting from a fresh clone would not have the "
|
|
191
203
|
"skills.\n"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/docs/runbook.md
RENAMED
|
File without changes
|
{napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/tests/.gitkeep
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|