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.
Files changed (41) hide show
  1. {napkinstack-0.34.1 → napkinstack-0.34.2}/PKG-INFO +4 -4
  2. {napkinstack-0.34.1 → napkinstack-0.34.2}/README.md +3 -3
  3. {napkinstack-0.34.1 → napkinstack-0.34.2}/pyproject.toml +1 -1
  4. {napkinstack-0.34.1 → napkinstack-0.34.2}/pyproject.toml.orig +1 -1
  5. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/agent.py +55 -0
  6. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/boundaries.py +7 -3
  7. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/skills.py +17 -5
  8. {napkinstack-0.34.1 → napkinstack-0.34.2}/LICENSE +0 -0
  9. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/__init__.py +0 -0
  10. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/__main__.py +0 -0
  11. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/assurance.py +0 -0
  12. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/attest.py +0 -0
  13. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/board.py +0 -0
  14. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/cli.py +0 -0
  15. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/compat.py +0 -0
  16. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/discovery.py +0 -0
  17. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/doctor.py +0 -0
  18. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/evidence.py +0 -0
  19. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/__init__.py +0 -0
  20. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/hygiene.py +0 -0
  21. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/manifests.py +0 -0
  22. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/plan.py +0 -0
  23. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/fitness/pr_scope.py +0 -0
  24. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/hold.py +0 -0
  25. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/landed.py +0 -0
  26. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/modules.py +0 -0
  27. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/owners.py +0 -0
  28. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/project.py +0 -0
  29. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/provenance.py +0 -0
  30. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/pull_request.py +0 -0
  31. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/settings.py +0 -0
  32. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.34.1 → napkinstack-0.34.2}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {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.1
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.1, published** on [PyPI](https://pypi.org/project/napkinstack/).
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.1" nstack init my-project
90
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.1"
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.1, published** on [PyPI](https://pypi.org/project/napkinstack/).
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.1" nstack init my-project
73
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.1"
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
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.34.1"
3
+ version = "0.34.2"
4
4
  description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.34.1"
3
+ version = "0.34.2"
4
4
  description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -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). Its package is its
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
- for name, entry in sorted(mapping.items()):
173
- path, content = build(root, name, entry, folder)
174
- path.parent.mkdir(parents=True, exist_ok=True)
175
- path.write_text(content, encoding="utf-8")
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
- print(f"Skills generated in {' and '.join(f'{folder.as_posix()}/' for folder in FOLDERS)}: {len(mapping)}"
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