napkinstack 0.34.1__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.1 → napkinstack-0.34.2}/PKG-INFO +4 -4
- {napkinstack-0.34.1 → napkinstack-0.34.2}/README.md +3 -3
- {napkinstack-0.34.1 → napkinstack-0.34.2}/pyproject.toml +1 -1
- {napkinstack-0.34.1 → napkinstack-0.34.2}/pyproject.toml.orig +1 -1
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/agent.py +55 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/boundaries.py +7 -3
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/skills.py +17 -5
- {napkinstack-0.34.1 → napkinstack-0.34.2}/LICENSE +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/__init__.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/__main__.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/assurance.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/attest.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/board.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/cli.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/compat.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/discovery.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/doctor.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/evidence.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/__init__.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/hygiene.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/manifests.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/plan.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/pr_scope.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/hold.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/landed.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/modules.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/owners.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/project.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/provenance.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/pull_request.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/settings.py +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/README.md +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/AGENTS.md +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/README.md +0 -0
- {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/src/.gitkeep +0 -0
- {napkinstack-0.34.1 → 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)
|
|
@@ -31,7 +31,8 @@ DETECTION — textual and deliberately simple, with no stack assumed.
|
|
|
31
31
|
the statement, or quoted as a module specifier, or alone on a Go import block's line — or
|
|
32
32
|
where any line reaches into its folder (../billing/, modules/billing/). In a Python
|
|
33
33
|
file, a package named like the standard library's (import platform) is Python's own
|
|
34
|
-
(D258)
|
|
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
|
|
35
36
|
folder's name, or `code_name` when the code names it otherwise (com.acme.billing). A
|
|
36
37
|
relative path is read from the file's folder and from the module's — where the verbs run —
|
|
37
38
|
and a path that names something of the module's own, or a contract it provides, is none.
|
|
@@ -57,6 +58,7 @@ SOURCE_SUFFIXES = {
|
|
|
57
58
|
".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java", ".kt",
|
|
58
59
|
".rb", ".php", ".cs", ".swift", ".scala", ".ex", ".exs",
|
|
59
60
|
}
|
|
61
|
+
QUOTED_SPECIFIER = {".ts", ".tsx", ".js", ".jsx", ".go"} # the word after `import` is a binding (D260)
|
|
60
62
|
SKIP_DIRS = {"node_modules", "dist", "build", "target", "vendor", ".git",
|
|
61
63
|
"__pycache__", ".venv", "venv", "coverage", "generated"}
|
|
62
64
|
IMPORT_HINTS = re.compile(
|
|
@@ -133,7 +135,8 @@ def code_patterns(other: dict) -> tuple[re.Pattern, re.Pattern, re.Pattern, re.P
|
|
|
133
135
|
or quoted as a module specifier (JavaScript, TypeScript, Ruby). On any line: a relative or rooted
|
|
134
136
|
path into its folder — ending where the folder's name does, so that ../billing.csv is not billing.
|
|
135
137
|
A package named like a module of Python's standard library is apart: in a Python file,
|
|
136
|
-
`import platform` is Python's own (D258).
|
|
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)."""
|
|
137
140
|
code, folder = re.escape(other["code_name"]), re.escape(other["dirname"])
|
|
138
141
|
rooted = "|".join(MODULE_DIRS)
|
|
139
142
|
imports = re.compile(rf"(?<![\w-])(?:{rooted})[./]{folder}(?![\w-])"
|
|
@@ -335,6 +338,7 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
|
|
|
335
338
|
for relative, lines in read_files(mod):
|
|
336
339
|
source = Path(relative).suffix in SOURCE_SUFFIXES
|
|
337
340
|
python = Path(relative).suffix == ".py"
|
|
341
|
+
quoted = Path(relative).suffix in QUOTED_SPECIFIER
|
|
338
342
|
for lineno, line in enumerate(lines, 1):
|
|
339
343
|
imports = source and IMPORT_HINTS.search(line)
|
|
340
344
|
text = line.replace("\\", "/")
|
|
@@ -346,7 +350,7 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
|
|
|
346
350
|
if other_name == name:
|
|
347
351
|
continue
|
|
348
352
|
via_import = ((imports and (code_import.search(line)
|
|
349
|
-
or (package.search(line)
|
|
353
|
+
or (package.search(line) and not quoted
|
|
350
354
|
and not (python and _standard(modules[other_name])))))
|
|
351
355
|
or (source and block.search(line)))
|
|
352
356
|
reaches = [m for m in reach.finditer(text)
|
|
@@ -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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/docs/runbook.md
RENAMED
|
File without changes
|
{napkinstack-0.34.1 → 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
|