docs(standards): vendor template into MCP bundle; add component tools + start_app prompt

build.py

@@ -168,6 +168,151 @@ def build_bundle(folder: Path, dry_run: bool = False) -> None:
     print(f"[MCP]  {name}  bundle written to {out_dir.relative_to(ROOT)}/ ({len(nav)} modules)")
 
 
+# ── Template bundle ──────────────────────────────────────────────────────────
+
+# Component kinds shipped in the vendored template. ``placeholder`` names the
+# seed token an agent renames: "resource" -> item/Item, "family" -> example/
+# Example; "" means ship as-is.
+_TEMPLATE_COMPONENTS: list[dict[str, str]] = [
+    # Per-resource slice (seed: item/Item).
+    {"kind": "model", "path": "domain/item/models.py", "placeholder": "resource",
+     "description": "Business Pydantic model for a resource."},
+    {"kind": "ports-db", "path": "domain/item/ports/db.py", "placeholder": "resource",
+     "description": "Document model + repository factory for a resource."},
+    {"kind": "ports-service", "path": "domain/item/ports/service.py", "placeholder": "resource",
+     "description": "CRUD service wired through the DI library."},
+    {"kind": "converters", "path": "domain/item/ports/converters.py", "placeholder": "resource",
+     "description": "Optional pure converters between domain types."},
+    {"kind": "routes", "path": "interfaces/item/routes.py", "placeholder": "resource",
+     "description": "Thin HTTP handlers bound to operationIds."},
+    {"kind": "test-model", "path": "tests/unit/test_item_models.py", "placeholder": "resource",
+     "description": "Unit test for the resource model."},
+    {"kind": "test-routes", "path": "tests/integration/test_item_routes.py", "placeholder": "resource",
+     "description": "Integration test at the HTTP edge."},
+    # Per-family pipeline scaffold (seed: example/Example).
+    {"kind": "pipeline-abc", "path": "pipelines/example/abc.py", "placeholder": "family",
+     "description": "Port contracts for a pipeline family."},
+    {"kind": "pipeline-impl", "path": "pipelines/example/impl.py", "placeholder": "family",
+     "description": "Concrete stages, wired root, and family registration."},
+    {"kind": "pipeline-yaml", "path": "pipelines/example/pipeline.yaml", "placeholder": "family",
+     "description": "Graph spec (nodes, edges, roots, schema)."},
+    {"kind": "pipeline-resources", "path": "pipelines/example/resources/pipeline.yaml", "placeholder": "family",
+     "description": "Runtime spec consumed by the shared loader."},
+    {"kind": "pipeline-pattern", "path": "pipelines/example/resources/patterns/example.yaml", "placeholder": "family",
+     "description": "Pattern/rule fragment merged by the loader."},
+    # Shared pipeline scaffolding (ship as-is).
+    {"kind": "pipeline-ports", "path": "pipelines/shared/ports.py", "placeholder": "",
+     "description": "Shared pipeline ports (FinalizePort, RegistryPort)."},
+    {"kind": "pipeline-loader", "path": "pipelines/shared/loader.py", "placeholder": "",
+     "description": "Shared loader: DI wiring + pattern merge."},
+    {"kind": "pipeline-registry", "path": "pipelines/shared/registry.py", "placeholder": "",
+     "description": "Shared registry: (kind, variant, mode) -> root class."},
+    {"kind": "pipeline-simple", "path": "pipelines/item_sync.py", "placeholder": "",
+     "description": "Smallest pipeline form (plain async steps)."},
+    # Second resource slice (seed: job).
+    {"kind": "job-model", "path": "domain/job/models.py", "placeholder": "",
+     "description": "Seeded second resource model (job)."},
+    {"kind": "job-ports-db", "path": "domain/job/ports/db.py", "placeholder": "",
+     "description": "Seeded second resource repository (job)."},
+    {"kind": "job-ports-service", "path": "domain/job/ports/service.py", "placeholder": "",
+     "description": "Seeded second resource service (job)."},
+    {"kind": "job-routes", "path": "interfaces/job/routes.py", "placeholder": "",
+     "description": "Seeded second resource routes (job)."},
+    # Root / shared files (ship as-is).
+    {"kind": "config", "path": "config.py", "placeholder": "",
+     "description": "Settings dataclass + singleton."},
+    {"kind": "init", "path": "init.py", "placeholder": "",
+     "description": "Composition root (init/shutdown, get_svc)."},
+    {"kind": "main", "path": "main.py", "placeholder": "",
+     "description": "Spec-first app bootstrap + lifespan."},
+    {"kind": "worker", "path": "worker.py", "placeholder": "",
+     "description": "Poll loop + job status machine."},
+    {"kind": "openapi", "path": "openapi.yaml", "placeholder": "",
+     "description": "OpenAPI contract skeleton."},
+    {"kind": "pyproject", "path": "pyproject.toml", "placeholder": "",
+     "description": "Packaging + dependency pins."},
+    {"kind": "dockerfile", "path": "Dockerfile", "placeholder": "",
+     "description": "API + worker image with private-index wiring."},
+    {"kind": "compose", "path": "docker-compose.yaml", "placeholder": "",
+     "description": "api + worker + mongo compose file."},
+    {"kind": "env-example", "path": ".env.example", "placeholder": "",
+     "description": "Environment variable template."},
+    {"kind": "db-setup", "path": "infra/db/setup.py", "placeholder": "",
+     "description": "Mongo connection lifecycle."},
+    {"kind": "repo", "path": "infra/db/repos/mongo.py", "placeholder": "",
+     "description": "Repository factory (base/populating/cached)."},
+    {"kind": "service-adapter", "path": "infra/adapters/service.py", "placeholder": "",
+     "description": "Generic CRUD service adaptor."},
+    {"kind": "script-seed", "path": "scripts/seed.py", "placeholder": "",
+     "description": "Operator seed script."},
+    {"kind": "script-drop", "path": "scripts/drop.py", "placeholder": "",
+     "description": "Operator drop script."},
+]
+
+
+def build_components_manifest(template_root: Path) -> dict[str, object]:
+    """Describe every component in the vendored template.
+
+    Args:
+        template_root (Path): The vendored ``templates/app`` directory.
+
+    Returns:
+        dict[str, object]: Manifest with the seed tokens and component entries.
+    """
+    components: list[dict[str, str]] = []
+    for entry in _TEMPLATE_COMPONENTS:
+        rel = entry["path"]
+        if not (template_root / rel).exists():
+            raise SystemExit(f"[ERR]  component path missing from template: {rel}")
+        components.append({
+            "kind": entry["kind"],
+            "path": rel,
+            "placeholder": entry["placeholder"],
+            "description": entry["description"],
+        })
+    return {
+        "project": "standards",
+        "template": "templates/app",
+        "seed": {"resource": "item", "family": "example"},
+        "components": components,
+    }
+
+
+def build_templates(folder: Path, dry_run: bool = False) -> None:
+    """Vendor ``folder/src/templates/app`` into ``<name>/mcp/templates/app``.
+
+    Ships the runnable skeleton in the MCP bundle so an agent can pull exact,
+    current component code, and emits ``components.json`` describing the kinds.
+    Excludes ``__pycache__`` / ``*.pyc``.
+
+    Args:
+        folder (Path): The hub folder owning ``src/templates/app``.
+        dry_run (bool): Print the plan without executing.
+    """
+    name = folder.name
+    src = folder / "src" / "templates" / "app"
+    if not src.is_dir():
+        return
+    out_dir = folder / "mcp" / "templates" / "app"
+    if dry_run:
+        print(f"[TPL]  {name}  {src.relative_to(ROOT)}/** -> {out_dir.relative_to(ROOT)}/**")
+        return
+
+    if out_dir.exists():
+        shutil.rmtree(out_dir)
+    out_dir.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(
+        src, out_dir,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+    )
+    manifest = build_components_manifest(out_dir)
+    (folder / "mcp" / "components.json").write_text(
+        json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8"
+    )
+    print(f"[TPL]  {name}  template vendored to {out_dir.relative_to(ROOT)}/ "
+          f"({len(manifest['components'])} components)")
+
+
 # ── CLI ──────────────────────────────────────────────────────────────────────
 
 
@@ -186,6 +331,7 @@ def main() -> None:
 
     for folder in folders:
         build_bundle(folder, dry_run=args.dry_run)
+        build_templates(folder, dry_run=args.dry_run)
         build_html(folder, dry_run=args.dry_run)