napkinstack 0.1.0__tar.gz

napkinstack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NapkinStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

napkinstack-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: napkinstack
+Version: 0.1.0
+Summary: Framework de travail pour faire travailler plusieurs équipes et leurs agents sur un même dépôt : modules, contrats, garde-fous en CI.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: copier==9.18.2
+Requires-Dist: pre-commit==4.6.2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/NapkinStack/engineering-os
+Project-URL: Source, https://github.com/NapkinStack/engineering-os
+Project-URL: Issues, https://github.com/NapkinStack/engineering-os/issues
+Description-Content-Type: text/markdown
+
+# NapkinStack
+
+Framework de travail pour faire travailler plusieurs équipes et leurs agents sur un même
+dépôt : modules, contrats, garde-fous en CI. Sur le modèle de Django ou Rails, une commande
+crée le projet, qui reçoit ensuite les nouvelles versions à sa demande ; aucune stack
+applicative n'est imposée. Positionnement et vocabulaire : [`PRODUCT.md`](PRODUCT.md) §1.
+
+> **État : en construction (v0.1.0).** Toutes les commandes fonctionnent depuis ce dépôt ;
+> la première version publiée sur PyPI arrive au chantier M5, avant un premier projet
+> pilote. Suivi : [feuille de route](docs/governance/plans/2026-09-15-moteur-v0.1.0.md),
+> [`docs/governance/chantiers.md`](docs/governance/chantiers.md).
+
+## Le parcours d'un projet
+
+```mermaid
+flowchart LR
+    I["Installer<br/>uv tool install"]:::cmd --> N["nstack init"]:::cmd
+    N --> G["Publier sur GitHub<br/>appliquer la checklist"]:::humain
+    G --> D["nstack doctor<br/>lecture seule"]:::cmd
+    D --> M["nstack new-module"]:::cmd
+    M --> W["Travail en PR<br/>l'équipe et son agent"]:::humain
+    W --> U["nstack update<br/>branche fusionnée"]:::cmd
+    U --> P["PR relue<br/>validée par la CI"]:::humain
+    P -->|"version suivante"| U
+
+    classDef cmd fill:#1f2937,color:#fff
+    classDef humain fill:#065f46,color:#fff
+```
+
+**Légende** — gris : commande NapkinStack · vert : action de l'équipe. Décision :
+[PDR-0001](docs/pdr/0001-creer-un-projet-et-recevoir-les-evolutions.md).
+
+Le projet possède son squelette et l'adapte librement. Chaque nouvelle version lui arrive
+à sa demande, fusionnée avec ses adaptations ; les conflits restent à l'équipe.
+
+```mermaid
+flowchart LR
+    V1["Squelette v0.1<br/>base commune"]:::ref --> F{"Fusion<br/>à 3 voies"}
+    V2["Squelette v0.2<br/>correctifs NapkinStack"]:::ns --> F
+    PR["Projet<br/>adaptations de l'équipe"]:::equipe --> F
+    F -->|"lignes différentes"| B["Branche de mise à jour<br/>correctifs + adaptations"]:::ok
+    F -->|"même ligne modifiée"| X["Conflit marqué<br/>commit refusé"]:::ko
+
+    classDef ref fill:#374151,color:#fff
+    classDef ns fill:#1e3a8a,color:#fff
+    classDef equipe fill:#065f46,color:#fff
+    classDef ok fill:#065f46,color:#fff
+    classDef ko fill:#7c2d12,color:#fff
+```
+
+**Légende** — gris : version dont le projet est issu · bleu : nouvelle version · vert :
+travail de l'équipe et résultat accepté · rouge : conflit laissé à l'équipe.
+
+## Installer
+
+```bash
+uv tool install napkinstack --with-executables-from pre-commit   # prérequis : uv et git
+nstack init mon-projet
+```
+
+Disponible dès la publication de la v0.1.0 sur PyPI ; chaque projet épingle ensuite sa
+version et la change par `nstack update`.
+
+## Les commandes
+
+| Commande | Rôle |
+|---|---|
+| `nstack init <dossier>` | Crée le projet : squelette, dépôt git, commit initial, checklist GitHub |
+| `nstack doctor` | Vérifie le poste et les réglages GitHub, en lecture seule |
+| `nstack new-module <nom> <organisation>/<équipe> <criticité>` | Crée un module, sans stack imposée |
+| `nstack check`, `test`, `bootstrap` `[module]` ; `nstack run <module>` | Exécutent les commandes déclarées dans le manifest du module |
+| `nstack fitness` | Manifests, frontières entre modules, skills |
+| `nstack pr-scope` | Une PR = un module, budget de revue |
+| `nstack skills` | Expose les playbooks en skills pour l'agent |
+| `nstack update` | Pose la nouvelle version sur une branche à relire |
+
+**Prérequis** : uv et git. Les garde-fous bloquent vraiment sur un dépôt GitHub public, ou
+privé sous l'offre Team ou Pro ; sur un dépôt privé de l'offre Free, la CI informe sans
+bloquer ([précision de PDR-0001](docs/pdr/0001-creer-un-projet-et-recevoir-les-evolutions.md)).
+
+**IA** : NapkinStack n'en embarque aucune. L'agent de l'équipe (Claude Code, Codex,
+Copilot…) lit le kernel et les playbooks, lance les commandes, et la CI accepte ou refuse
+ses propositions comme celles de n'importe quel contributeur.
+
+## Ce dépôt
+
+```mermaid
+flowchart LR
+    S["skeleton/<br/>squelette de projet"]:::livre -->|"copier.yml"| P["Projet d'une équipe"]:::projet
+    E["src/napkinstack/<br/>moteur nstack"]:::livre -.->|"version épinglée"| P
+    A["PRODUCT.md · docs/governance/<br/>platform/ · CI du dépôt"]:::interne
+
+    classDef livre fill:#1e3a8a,color:#fff
+    classDef projet fill:#065f46,color:#fff
+    classDef interne fill:#374151,color:#fff
+```
+
+**Légende** — bleu : livré aux projets · vert : projet généré, qui possède son squelette ·
+gris : développement de NapkinStack, jamais copié (PDR-0001 R6). Trait plein : génération ;
+pointillé : dépendance versionnée.
+
+| Chemin | Rôle |
+|---|---|
+| `skeleton/` | Ce que reçoit chaque projet : kernel, playbooks, manuel, CI, hooks |
+| `copier.yml` | Questions posées à la création (gabarit Copier, ADR-0001) |
+| `src/napkinstack/` | Le moteur, commande `nstack` |
+| `platform/` | Enveloppe du module moteur : manifest, runbook, tests |
+| `PRODUCT.md`, `docs/governance/` | Contexte de travail sur NapkinStack |
+| `docs/adr/`, `docs/pdr/` | Décisions de NapkinStack |
+
+## Développer NapkinStack
+
+```bash
+uv sync                               # prérequis : uv
+uv run pre-commit install
+uv run nstack fitness                 # garde-fous du dépôt
+uv run bash platform/tests/run.sh     # oracle : chaque garde-fou prouve qu'il sait échouer
+uv run nstack init /tmp/essai --source . --ref HEAD   # projet d'essai depuis l'arbre de travail
+uv run nstack doctor --root /tmp/essai                # poste et réglages GitHub, en lecture seule
+```
+
+Contribuer : [`CONTRIBUTING.md`](CONTRIBUTING.md), après [`PRODUCT.md`](PRODUCT.md).
+
+Licence : [MIT](LICENSE).

napkinstack-0.1.0/README.md

@@ -0,0 +1,124 @@
+# NapkinStack
+
+Framework de travail pour faire travailler plusieurs équipes et leurs agents sur un même
+dépôt : modules, contrats, garde-fous en CI. Sur le modèle de Django ou Rails, une commande
+crée le projet, qui reçoit ensuite les nouvelles versions à sa demande ; aucune stack
+applicative n'est imposée. Positionnement et vocabulaire : [`PRODUCT.md`](PRODUCT.md) §1.
+
+> **État : en construction (v0.1.0).** Toutes les commandes fonctionnent depuis ce dépôt ;
+> la première version publiée sur PyPI arrive au chantier M5, avant un premier projet
+> pilote. Suivi : [feuille de route](docs/governance/plans/2026-09-15-moteur-v0.1.0.md),
+> [`docs/governance/chantiers.md`](docs/governance/chantiers.md).
+
+## Le parcours d'un projet
+
+```mermaid
+flowchart LR
+    I["Installer<br/>uv tool install"]:::cmd --> N["nstack init"]:::cmd
+    N --> G["Publier sur GitHub<br/>appliquer la checklist"]:::humain
+    G --> D["nstack doctor<br/>lecture seule"]:::cmd
+    D --> M["nstack new-module"]:::cmd
+    M --> W["Travail en PR<br/>l'équipe et son agent"]:::humain
+    W --> U["nstack update<br/>branche fusionnée"]:::cmd
+    U --> P["PR relue<br/>validée par la CI"]:::humain
+    P -->|"version suivante"| U
+
+    classDef cmd fill:#1f2937,color:#fff
+    classDef humain fill:#065f46,color:#fff
+```
+
+**Légende** — gris : commande NapkinStack · vert : action de l'équipe. Décision :
+[PDR-0001](docs/pdr/0001-creer-un-projet-et-recevoir-les-evolutions.md).
+
+Le projet possède son squelette et l'adapte librement. Chaque nouvelle version lui arrive
+à sa demande, fusionnée avec ses adaptations ; les conflits restent à l'équipe.
+
+```mermaid
+flowchart LR
+    V1["Squelette v0.1<br/>base commune"]:::ref --> F{"Fusion<br/>à 3 voies"}
+    V2["Squelette v0.2<br/>correctifs NapkinStack"]:::ns --> F
+    PR["Projet<br/>adaptations de l'équipe"]:::equipe --> F
+    F -->|"lignes différentes"| B["Branche de mise à jour<br/>correctifs + adaptations"]:::ok
+    F -->|"même ligne modifiée"| X["Conflit marqué<br/>commit refusé"]:::ko
+
+    classDef ref fill:#374151,color:#fff
+    classDef ns fill:#1e3a8a,color:#fff
+    classDef equipe fill:#065f46,color:#fff
+    classDef ok fill:#065f46,color:#fff
+    classDef ko fill:#7c2d12,color:#fff
+```
+
+**Légende** — gris : version dont le projet est issu · bleu : nouvelle version · vert :
+travail de l'équipe et résultat accepté · rouge : conflit laissé à l'équipe.
+
+## Installer
+
+```bash
+uv tool install napkinstack --with-executables-from pre-commit   # prérequis : uv et git
+nstack init mon-projet
+```
+
+Disponible dès la publication de la v0.1.0 sur PyPI ; chaque projet épingle ensuite sa
+version et la change par `nstack update`.
+
+## Les commandes
+
+| Commande | Rôle |
+|---|---|
+| `nstack init <dossier>` | Crée le projet : squelette, dépôt git, commit initial, checklist GitHub |
+| `nstack doctor` | Vérifie le poste et les réglages GitHub, en lecture seule |
+| `nstack new-module <nom> <organisation>/<équipe> <criticité>` | Crée un module, sans stack imposée |
+| `nstack check`, `test`, `bootstrap` `[module]` ; `nstack run <module>` | Exécutent les commandes déclarées dans le manifest du module |
+| `nstack fitness` | Manifests, frontières entre modules, skills |
+| `nstack pr-scope` | Une PR = un module, budget de revue |
+| `nstack skills` | Expose les playbooks en skills pour l'agent |
+| `nstack update` | Pose la nouvelle version sur une branche à relire |
+
+**Prérequis** : uv et git. Les garde-fous bloquent vraiment sur un dépôt GitHub public, ou
+privé sous l'offre Team ou Pro ; sur un dépôt privé de l'offre Free, la CI informe sans
+bloquer ([précision de PDR-0001](docs/pdr/0001-creer-un-projet-et-recevoir-les-evolutions.md)).
+
+**IA** : NapkinStack n'en embarque aucune. L'agent de l'équipe (Claude Code, Codex,
+Copilot…) lit le kernel et les playbooks, lance les commandes, et la CI accepte ou refuse
+ses propositions comme celles de n'importe quel contributeur.
+
+## Ce dépôt
+
+```mermaid
+flowchart LR
+    S["skeleton/<br/>squelette de projet"]:::livre -->|"copier.yml"| P["Projet d'une équipe"]:::projet
+    E["src/napkinstack/<br/>moteur nstack"]:::livre -.->|"version épinglée"| P
+    A["PRODUCT.md · docs/governance/<br/>platform/ · CI du dépôt"]:::interne
+
+    classDef livre fill:#1e3a8a,color:#fff
+    classDef projet fill:#065f46,color:#fff
+    classDef interne fill:#374151,color:#fff
+```
+
+**Légende** — bleu : livré aux projets · vert : projet généré, qui possède son squelette ·
+gris : développement de NapkinStack, jamais copié (PDR-0001 R6). Trait plein : génération ;
+pointillé : dépendance versionnée.
+
+| Chemin | Rôle |
+|---|---|
+| `skeleton/` | Ce que reçoit chaque projet : kernel, playbooks, manuel, CI, hooks |
+| `copier.yml` | Questions posées à la création (gabarit Copier, ADR-0001) |
+| `src/napkinstack/` | Le moteur, commande `nstack` |
+| `platform/` | Enveloppe du module moteur : manifest, runbook, tests |
+| `PRODUCT.md`, `docs/governance/` | Contexte de travail sur NapkinStack |
+| `docs/adr/`, `docs/pdr/` | Décisions de NapkinStack |
+
+## Développer NapkinStack
+
+```bash
+uv sync                               # prérequis : uv
+uv run pre-commit install
+uv run nstack fitness                 # garde-fous du dépôt
+uv run bash platform/tests/run.sh     # oracle : chaque garde-fou prouve qu'il sait échouer
+uv run nstack init /tmp/essai --source . --ref HEAD   # projet d'essai depuis l'arbre de travail
+uv run nstack doctor --root /tmp/essai                # poste et réglages GitHub, en lecture seule
+```
+
+Contribuer : [`CONTRIBUTING.md`](CONTRIBUTING.md), après [`PRODUCT.md`](PRODUCT.md).
+
+Licence : [MIT](LICENSE).

napkinstack-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "napkinstack"
+version = "0.1.0"
+description = "Framework de travail pour faire travailler plusieurs équipes et leurs agents sur un même dépôt : modules, contrats, garde-fous en CI."
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+dependencies = [
+    "PyYAML>=6.0",
+    "copier==9.18.2",
+    "pre-commit==4.6.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/NapkinStack/engineering-os"
+Source = "https://github.com/NapkinStack/engineering-os"
+Issues = "https://github.com/NapkinStack/engineering-os/issues"
+
+[project.scripts]
+nstack = "napkinstack.cli:main"
+
+[dependency-groups]
+dev = ["pytest==9.1.1"]
+
+[tool.uv]
+required-version = ">=0.12.14,<0.13"
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.13"]
+build-backend = "uv_build"

napkinstack-0.1.0/pyproject.toml.orig

@@ -0,0 +1,27 @@
+[project]
+name = "napkinstack"
+version = "0.1.0"
+description = "Framework de travail pour faire travailler plusieurs équipes et leurs agents sur un même dépôt : modules, contrats, garde-fous en CI."
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+dependencies = ["PyYAML>=6.0", "copier==9.18.2", "pre-commit==4.6.2"]
+
+[project.urls]
+Homepage = "https://github.com/NapkinStack/engineering-os"
+Source = "https://github.com/NapkinStack/engineering-os"
+Issues = "https://github.com/NapkinStack/engineering-os/issues"
+
+[project.scripts]
+nstack = "napkinstack.cli:main"
+
+[dependency-groups]
+dev = ["pytest==9.1.1"]
+
+[tool.uv]
+required-version = ">=0.12.14,<0.13"
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.13"]
+build-backend = "uv_build"

napkinstack-0.1.0/src/napkinstack/__init__.py

@@ -0,0 +1,5 @@
+"""NapkinStack — moteur : fitness functions, skills et scaffold de module."""
+
+from importlib.metadata import version
+
+__version__ = version("napkinstack")

napkinstack-0.1.0/src/napkinstack/cli.py

@@ -0,0 +1,103 @@
+"""Point d'entrée unique `nstack` (chantier C1, PDR-0001)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+from pathlib import Path
+
+from napkinstack import __version__, doctor, modules, skills
+from napkinstack.fitness import boundaries, manifests
+
+PACKAGE = Path(__file__).resolve().parent
+
+
+def _root(value: str) -> Path:
+    root = Path(value).resolve()
+    if not root.is_dir():
+        raise argparse.ArgumentTypeError(f"racine introuvable : {value}")
+    return root
+
+
+def _script(relative: str, *args: str, root: Path) -> int:
+    env = {**os.environ, "NSTACK_ROOT": str(root)}
+    return subprocess.run(["bash", str(PACKAGE / relative), *args], cwd=root, env=env).returncode
+
+
+def _fitness(root: Path) -> int:
+    results = [manifests.run(root), boundaries.run(root), skills.run(root, check_only=True)]
+    return 1 if any(results) else 0
+
+
+def _add(sub, name: str, help_: str, func) -> argparse.ArgumentParser:
+    parser = sub.add_parser(name, help=help_)
+    parser.add_argument("--root", type=_root, default=Path.cwd(),
+                        help="racine du projet (défaut : dossier courant)")
+    parser.set_defaults(func=func)
+    return parser
+
+
+def _init(args: argparse.Namespace) -> int:
+    from napkinstack import project  # Copier ne se charge que pour init et update
+
+    answers = {"project_name": args.project_name, "github_repo": args.github_repo,
+               "owner_team": args.owner_team}
+    return project.init(args.destination, answers, args.source or project.SOURCE,
+                        args.ref or project.default_ref())
+
+
+def _update(args: argparse.Namespace) -> int:
+    from napkinstack import project
+
+    return project.update(args.root, args.ref or project.default_ref())
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nstack", description="Moteur NapkinStack.")
+    parser.add_argument("--version", action="version", version=f"nstack {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="commande")
+    _add(sub, "manifests", "manifests, cycles de vie, dépréciations (M1–M9)",
+         lambda a: manifests.run(a.root))
+    _add(sub, "boundaries", "graphe déclaré contre graphe réel (B1–B5)",
+         lambda a: boundaries.run(a.root))
+    sk = _add(sub, "skills", "génère ou vérifie les skills (S1–S4)",
+              lambda a: skills.run(a.root, check_only=a.check))
+    sk.add_argument("--check", action="store_true", help="vérifier sans écrire")
+    _add(sub, "fitness", "manifests + frontières + skills",
+         lambda a: _fitness(a.root))
+    _add(sub, "doctor", "diagnostique le poste et les réglages GitHub, en lecture seule (PDR-0001)",
+         lambda a: doctor.run(a.root))
+    nm = _add(sub, "new-module", "crée un module et ses garde-fous, sans stack imposée",
+              lambda a: modules.nouveau(a.root, a.name, a.owner, a.criticality))
+    nm.add_argument("name", help="nom du module, kebab-case")
+    nm.add_argument("owner", help="équipe GitHub, organisation/équipe")
+    nm.add_argument("criticality", choices=["prototype", "standard", "eleve", "critique"])
+    for nom_verbe, aide in (("bootstrap", "prépare un module, ou tous (commands.bootstrap)"),
+                            ("check", "format, lint, types d'un module, ou de tous (commands.check)"),
+                            ("test", "tests d'un module, ou de tous (commands.test)")):
+        vb = _add(sub, nom_verbe, aide, lambda a, v=nom_verbe: modules.verbe(a.root, v, a.module))
+        vb.add_argument("module", nargs="?", help="nom du module (défaut : tous)")
+    rn = _add(sub, "run", "démarre un module en local (commands.run)",
+              lambda a: modules.verbe(a.root, "run", a.module))
+    rn.add_argument("module")
+    ps = _add(sub, "pr-scope", "une PR = un module, budget de revue (P1–P2)",
+              lambda a: _script("fitness/pr_scope.sh", a.base, root=a.root))
+    ps.add_argument("--base", default="origin/main")
+    ini = sub.add_parser("init", help="crée un projet à partir du squelette (PDR-0001)")
+    ini.add_argument("destination", type=Path, help="dossier du projet, absent ou vide")
+    ini.add_argument("--project-name", help="nom du projet (demandé si absent)")
+    ini.add_argument("--github-repo", help="dépôt GitHub, organisation/nom (demandé si absent)")
+    ini.add_argument("--owner-team", help="équipe GitHub du socle, organisation/équipe (demandé si absent)")
+    ini.add_argument("--source", help="gabarit : URL ou chemin (défaut : dépôt NapkinStack)")
+    ini.add_argument("--ref", help="version du squelette, tag vX.Y.Z (défaut : celle de nstack)")
+    ini.set_defaults(func=_init)
+    up = _add(sub, "update", "fusionne une version de NapkinStack sur une branche à relire (PDR-0001)",
+              _update)
+    up.add_argument("--ref", help="version cible, tag vX.Y.Z (défaut : celle de nstack)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)