diff --git a/build.py b/build.py index 02c2414..35c81ee 100644 --- a/build.py +++ b/build.py @@ -362,14 +362,125 @@ def build_templates(folder: Path, dry_run: bool = False) -> None: f"({len(manifest['components'])} components)") +# ── Client template bundle ──────────────────────────────────────────────────── + +# Component kinds shipped in the vendored React client template +# (``templates/client``): the Vite + MUI shell that pairs with ``templates/app`` +# and renders the admin UI from the app's openapi.yaml via +# ``@aetoskia/react-openapi`` / ``@aetoskia/react-auth``. No seed tokens — +# ship as-is (see standards "40_ui_admin"). +_CLIENT_COMPONENTS: list[dict[str, str]] = [ + {"kind": "client-package", "path": "package.json", "placeholder": "", + "description": "npm manifest: @aetoskia deps, scripts (dev/build/preview)."}, + {"kind": "client-npmrc", "path": ".npmrc", "placeholder": "", + "description": "Private registry auth pointing at npm.aetoskia.com."}, + {"kind": "client-env", "path": ".env.example", "placeholder": "", + "description": "VITE_API_BASE_URL / VITE_AUTH_BASE_URL seed."}, + {"kind": "client-vite-config", "path": "vite.config.ts", "placeholder": "", + "description": "Vite config (dev server, build)."}, + {"kind": "client-tsconfig", "path": "tsconfig.json", "placeholder": "", + "description": "TypeScript config for the client."}, + {"kind": "client-index-html", "path": "index.html", "placeholder": "", + "description": "HTML entry point."}, + {"kind": "client-entry", "path": "src/main.jsx", "placeholder": "", + "description": "React entry: router + providers + theme."}, + {"kind": "client-openapi-config", "path": "src/openapi-config.ts", "placeholder": "", + "description": "Points the admin renderer at the app spec + auth-server spec."}, + {"kind": "client-home", "path": "src/Home.tsx", "placeholder": "", + "description": "Auto-listing home page (ResourceCard + LiveTable per resource)."}, + {"kind": "client-header", "path": "src/Header.tsx", "placeholder": "", + "description": "App header bar (brand + nav)."}, + {"kind": "client-footer", "path": "src/Footer.tsx", "placeholder": "", + "description": "App footer."}, + {"kind": "client-vite-env", "path": "src/vite-env.d.ts", "placeholder": "", + "description": "Vite client type declarations."}, + {"kind": "client-theme", "path": "src/shared-theme/AppTheme.tsx", "placeholder": "", + "description": "Theme provider wrapper (light/dark)."}, + {"kind": "client-theme-config", "path": "src/shared-theme/themeConfig.ts", "placeholder": "", + "description": "Palette / typography tokens."}, + {"kind": "client-theme-primitives", "path": "src/shared-theme/themePrimitives.ts", "placeholder": "", + "description": "MUI theme primitives (shadows, accents)."}, + {"kind": "client-theme-shim", "path": "src/shared-theme/mui.d.ts", "placeholder": "", + "description": "MUI v5 type shims (Theme.vars, SelectClasses.focused)."}, +] + + +def build_client_manifest(template_root: Path) -> dict[str, object]: + """Describe every component in the vendored client template. + + Args: + template_root (Path): The vendored ``templates/client`` directory. + + Returns: + dict[str, object]: Manifest with the component entries. + """ + components: list[dict[str, str]] = [] + for entry in _CLIENT_COMPONENTS: + rel = entry["path"] + if not (template_root / rel).exists(): + raise SystemExit(f"[ERR] client component path missing from template: {rel}") + components.append({ + "kind": entry["kind"], + "path": rel, + "placeholder": entry["placeholder"], + "description": entry["description"], + }) + return { + "project": "standards", + "template": "templates/client", + "components": components, + } + + +def build_client_templates(folder: Path, dry_run: bool = False) -> None: + """Vendor ``folder/src/templates/client`` into ``/mcp/templates/client``. + + Ships the React client skeleton (the auto-rendered admin shell) in the MCP + bundle so an agent can pull exact, current component code, and emits + ``client.json`` describing the kinds. Excludes caches and lock files. + + Args: + folder (Path): The hub folder owning ``src/templates/client``. + dry_run (bool): Print the plan without executing. + """ + name = folder.name + src = folder / "src" / "templates" / "client" + if not src.is_dir(): + return + out_dir = folder / "mcp" / "templates" / "client" + if dry_run: + print(f"[CLT] {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( + "node_modules", "dist", ".ruff_cache", ".pytest_cache", + ".mypy_cache", ".venv", "venv", ".git", "*.egg-info", + ), + ) + manifest = build_client_manifest(out_dir) + (folder / "mcp" / "client.json").write_text( + json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8" + ) + print(f"[CLT] {name} client template vendored to {out_dir.relative_to(ROOT)}/ " + f"({len(manifest['components'])} components)") + + # ── Drone standard bundle ───────────────────────────────────────────────────── -# The two CI shapes shipped in ``src/templates/drone``. There are exactly two -# types of ``.drone.yml`` in the org: a Python package (private PyPI) and a -# Docker deployment (build / push / run). See standards "10_drone_pipelines". +# The CI shapes shipped in ``src/templates/drone``. There are exactly three +# types of ``.drone.yml`` in the org: a Python package (private PyPI), an npm +# package (private npm registry), and a Docker deployment (build / push / run). +# See standards "90_drone_pipelines". _DRONE_COMPONENTS: list[dict[str, str]] = [ {"kind": "drone-pypi", "path": "python-lib.yaml", "placeholder": "", "description": "Drone pipeline: build + publish a Python package to the private PyPI index."}, + {"kind": "drone-npm", "path": "npm-lib.yaml", "placeholder": "", + "description": "Drone pipeline: build + publish an npm package to the private npm registry."}, {"kind": "drone-service", "path": "service-docker.yaml", "placeholder": "", "description": "Drone pipeline: build, push, and deploy a Docker service."}, ] @@ -398,7 +509,7 @@ def build_drone_manifest(template_root: Path) -> dict[str, object]: return { "project": "standards", "template": "templates/drone", - "types": ["pypi", "docker"], + "types": ["pypi", "npm", "docker"], "components": components, } @@ -406,9 +517,9 @@ def build_drone_manifest(template_root: Path) -> dict[str, object]: def build_drone_templates(folder: Path, dry_run: bool = False) -> None: """Vendor ``folder/src/templates/drone`` into ``/mcp/templates/drone``. - Ships the two ``.drone.yml`` shapes (PyPI package, Docker deployment) in the - MCP bundle so an agent can pull the exact CI file, and emits ``drone.json`` - describing them. + Ships the three ``.drone.yml`` shapes (PyPI package, npm package, Docker + deployment) in the MCP bundle so an agent can pull the exact CI file, and + emits ``drone.json`` describing them. Args: folder (Path): The hub folder owning ``src/templates/drone``. @@ -442,7 +553,7 @@ def build_drone_templates(folder: Path, dry_run: bool = False) -> None: # The release artefacts shipped in ``src/templates/release``. One canonical # changelog (Keep a Changelog + SemVer) and the service version file. See -# standards "11_versioning_and_changelog". +# standards "91_versioning_and_changelog". _RELEASE_COMPONENTS: list[dict[str, str]] = [ {"kind": "changelog", "path": "CHANGELOG.md", "placeholder": "", "description": "Keep a Changelog skeleton: one [Unreleased] section + compare links."}, @@ -523,7 +634,7 @@ def build_repos(folder: Path, dry_run: bool = False) -> None: The repository inventory (name, type, version source, Drone shape) is a single hand-authored JSON file, surfaced to agents through the ``registry://repos`` resource and the ``list_repos`` tool. See standards - "15_repository_inventory". + "94_repository_inventory". Args: folder (Path): The hub folder owning ``src/repos.json``. @@ -566,6 +677,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_client_templates(folder, dry_run=args.dry_run) build_drone_templates(folder, dry_run=args.dry_run) build_release_templates(folder, dry_run=args.dry_run) build_repos(folder, dry_run=args.dry_run) diff --git a/registry.py b/registry.py index 528c4cd..f7179e0 100644 --- a/registry.py +++ b/registry.py @@ -9,7 +9,8 @@ Resources: docs://index, docs://nav, docs://modules/{module} (from the base server) docs://spec (the pinned auth-server OpenAPI contract) registry://libraries (the structured catalog) - registry://components (the template component index) + registry://components (the app template component index) + registry://client (the client template component index) registry://drone (the CI template index) registry://release (the release template index) registry://repos (the repository inventory) @@ -20,7 +21,10 @@ Tools: list_app_components (the template component kinds) get_app_component (kind -> exact template file, seed tokens renamed) get_app_template (the whole app skeleton as a path -> content map) - list_drone_templates (the two CI shapes: PyPI package / Docker deployment) + list_client_components (the client template component kinds) + get_client_component (kind -> exact client template file) + get_client_template (the whole client skeleton as a path -> content map) + list_drone_templates (the three CI shapes: PyPI package / npm package / Docker deployment) get_drone_template (kind -> exact .drone.yml template) list_release_templates (the changelog + version-file artefacts) get_release_template (kind -> exact release template file) @@ -91,10 +95,14 @@ def _build_text(app_name: str, resources: str, pipelines: str, auth: str) -> str "4. Scaffold with `get_app_template()` (whole tree) or pull single " "files with `list_app_components()` and " "`get_app_component(kind, resource=..., family=...)`.\n" - "5. If auth is needed, read `docs://spec` (the auth-server contract) and " + "5. If a UI is needed, scaffold the client with `get_client_template()` " + "(or pull files via `list_client_components()` / " + "`get_client_component(kind)`) — the admin renders from your spec's x- " + "extensions; see `docs://modules/ui_admin`.\n" + "6. If auth is needed, read `docs://spec` (the auth-server contract) and " "`docs://modules/auth_integration`; declare `securitySchemes.bearerAuth` " "and `security` in your spec — do not write auth code.\n" - "6. Author only Tier C; keep Tier B as shipped.\n" + "7. Author only Tier C; keep Tier B as shipped.\n" ) @@ -103,8 +111,12 @@ _COMPLIANCE_TEXT = ( "Read `docs://modules/drone_pipelines` and `docs://modules/versioning_and_changelog`,\n" "then enumerate the working set with `registry://repos` (or `list_repos()`).\n\n" "For each repository, bring it to the standard for its `type`:\n\n" - "- **package** — `version` in `pyproject.toml`; root `CHANGELOG.md`; Drone file\n" - " from `get_drone_template(\"drone-pypi\")` (`python-lib.yaml`, tag-triggered).\n" + "- **package** (Python) — `version` in `pyproject.toml`; root `CHANGELOG.md`;\n" + " Drone file from `get_drone_template(\"drone-pypi\")` (`python-lib.yaml`,\n" + " tag-triggered).\n" + "- **package** (npm) — `version` in `package.json`; root `CHANGELOG.md`;\n" + " Drone file from `get_drone_template(\"drone-npm\")` (`npm-lib.yaml`,\n" + " tag-triggered, publishes to the private npm registry).\n" "- **service** — root `VERSION`; root `CHANGELOG.md`; Drone file from\n" " `get_drone_template(\"drone-service\")` (`service-docker.yaml`, tag-triggered\n" " with a `tag == VERSION` guard). The service must read its version from\n" @@ -291,6 +303,58 @@ class StandardsMCPServer(MCPServer): "content": text, } + def _client(self) -> dict[str, Any]: + """Load the client template component manifest.""" + path = Path(self.mcp_root) / "client.json" + if not path.exists(): + return {"error": "not_found", "path": str(path), "components": []} + return json.loads(path.read_bytes()) + + def _find_client_component(self, kind: str) -> dict[str, Any] | None: + for entry in self._client().get("components", []): + if entry.get("kind") == kind: + return entry + return None + + def _read_client_component(self, entry: dict[str, Any]) -> dict[str, Any]: + """Read a vendored client template file.""" + rel = entry["path"] + path = Path(self.mcp_root) / "templates" / "client" / rel + if not path.exists(): + return {"error": "not_found", "path": str(path)} + return { + "kind": entry["kind"], + "path": rel, + "placeholder": entry.get("placeholder"), + "content": path.read_text(encoding="utf-8"), + } + + def _client_files(self, prefix: str | None = None) -> dict[str, str]: + """Read the vendored client template tree as a path -> content map. + + Args: + prefix (str | None): Optional path prefix filter with POSIX + separators, for example ``"src/shared-theme/"``. + + Returns: + dict[str, str]: Relative POSIX path -> UTF-8 file content, + excluding caches and build output. + """ + root = Path(self.mcp_root) / "templates" / "client" + files: dict[str, str] = {} + if not root.is_dir(): + return files + for path in sorted(root.rglob("*")): + if not path.is_file(): + continue + if "__pycache__" in path.parts or path.suffix == ".pyc": + continue + rel = path.relative_to(root).as_posix() + if prefix and not rel.startswith(prefix): + continue + files[rel] = path.read_text(encoding="utf-8") + return files + # ------------------------------------------------------------------ # Standards surface # ------------------------------------------------------------------ @@ -304,6 +368,16 @@ class StandardsMCPServer(MCPServer): def components() -> dict[str, Any]: return self._components() + @self.app.resource("registry://client") + def client() -> dict[str, Any]: + """Return the client template component manifest. + + The React client skeleton (Vite + MUI) that pairs with the app + template; the admin UI renders from the app's openapi.yaml x- + extensions via @aetoskia/react-openapi. + """ + return self._client() + @self.app.resource("registry://drone") def drone() -> dict[str, Any]: return self._drone() @@ -434,13 +508,77 @@ class StandardsMCPServer(MCPServer): "files": files, } + @self.app.tool() + def list_client_components() -> list[dict[str, Any]]: + """List the reusable component kinds shipped in the client template. + + The React client (Vite + MUI) that pairs with the app template: + the admin shell rendering the app's resources from its + ``openapi.yaml``. See :func:`get_client_template` for the whole + tree and :func:`list_drone_templates` ("drone-npm") for its CI. + + Returns: + list[dict[str, Any]]: + Entries with ``kind``, ``path``, ``placeholder`` and + ``description``. Fetch one with :func:`get_client_component`. + """ + return self._client().get("components", []) + + @self.app.tool() + def get_client_component(kind: str) -> dict[str, Any]: + """Return the exact client template file for a component kind. + + Use this to copy current, app-neutral client code instead of + inventing it. See :func:`list_client_components` for valid kinds + (e.g. "client-home", "client-header", "client-openapi-config"). + + Args: + kind (str): Component kind, e.g. "client-openapi-config". + + Returns: + dict[str, Any]: ``{kind, path, placeholder, content}`` or an + error entry when the kind is unknown. + """ + entry = self._find_client_component(kind) + if entry is None: + return { + "error": "unknown_kind", + "kind": kind, + "available": [c["kind"] for c in self._client().get("components", [])], + } + return self._read_client_component(entry) + + @self.app.tool() + def get_client_template(prefix: str = "") -> dict[str, Any]: + """Return the whole client skeleton as a path -> content map. + + Use this to scaffold the UI in one shot instead of pulling + components one by one; combine with :func:`list_client_components` + for the kind and description metadata. + + Args: + prefix (str): Optional path prefix filter with POSIX + separators, for example ``"src/shared-theme/"``. Empty + returns every file. + + Returns: + dict[str, Any]: ``{root, file_count, files: {relpath: content}}``. + """ + files = self._client_files(prefix or None) + return { + "root": "templates/client", + "file_count": len(files), + "files": files, + } + @self.app.tool() def list_drone_templates() -> list[dict[str, Any]]: """List the CI (Drone) template shapes. - There are exactly two types of ``.drone.yml`` in the org: a Python - package published to the private PyPI index, and a Docker - deployment that builds, pushes, and runs a container. + There are exactly three types of ``.drone.yml`` in the org: a + Python package published to the private PyPI index, an npm package + published to the private npm registry, and a Docker deployment + that builds, pushes, and runs a container. Returns: list[dict[str, Any]]: @@ -455,10 +593,10 @@ class StandardsMCPServer(MCPServer): Use this to copy the current ``.drone.yml`` shape instead of inventing one. See :func:`list_drone_templates` for valid kinds - ("drone-pypi", "drone-service"). + ("drone-pypi", "drone-npm", "drone-service"). Args: - kind (str): Component kind, e.g. "drone-pypi" or + kind (str): Component kind, e.g. "drone-pypi", "drone-npm" or "drone-service". Returns: @@ -480,7 +618,7 @@ class StandardsMCPServer(MCPServer): These are the files every repo carries for releases: a Keep a Changelog ``CHANGELOG.md`` and, for services, a root ``VERSION`` - file. See standards "11_versioning_and_changelog". + file. See standards "91_versioning_and_changelog". Returns: list[dict[str, Any]]: @@ -517,13 +655,14 @@ class StandardsMCPServer(MCPServer): def list_repos(type: str | None = None) -> list[dict[str, Any]]: """List the repositories covered by the CI and versioning standards. - Each entry has: ``name``, ``type`` ("package" | "service"), + Each entry has: ``name``, ``type`` ("package" | "service" | "app"), ``path`` (relative to the aetos/ workspace root), ``version_source`` - ("pyproject.toml" | "VERSION"), ``drone`` (the template file), - ``trigger`` ("tag"), ``docs`` kinds, and ``mcp``. + ("pyproject.toml" | "package.json" | "VERSION"), ``drone`` (the + template file), ``trigger`` ("tag"), ``docs`` kinds, and ``mcp``. Args: - type (str | None): Optional filter, e.g. "package" or "service". + type (str | None): Optional filter, e.g. "package", "service" + or "app". Returns: list[dict[str, Any]]: Matching repository entries. diff --git a/standards/lib/90_drone_pipelines/index.html b/standards/lib/90_drone_pipelines/index.html index aa05cb1..7ee4d21 100644 --- a/standards/lib/90_drone_pipelines/index.html +++ b/standards/lib/90_drone_pipelines/index.html @@ -611,9 +611,18 @@
  • - + - Type B — Docker deployment (service-docker.yaml) + Type B — npm package (npm-lib.yaml) + + + +
    • + +
  • + + + Type C — Docker deployment (service-docker.yaml) @@ -656,7 +665,7 @@

    Drone Pipelines

    Summary

    Every Aetos repository ships a Drone CI definition at .drone.yml. There is -exactly one standard per repository, and there are two types of file, +exactly one standard per repository, and there are three types of file, chosen by what the repository produces:

    @@ -675,23 +684,30 @@ chosen by what the repository produces:

    - + + + + + + + - +
    dagpipe, doc-forge, hexa, mail-intake, mongo-ops, omniread, openapi-first, py-jwt
    B — Docker deploymentB — npm packagetemplates/drone/npm-lib.yamlA package published to the private npm registrydoc-weaver, react-auth, react-openapi
    C — Docker deployment templates/drone/service-docker.yaml An image pushed to the registry and run as a containerauth-serverauth-server, vet
    -

    Both templates run on platform: linux / arm64 with the workspace at -/drone/src. Copy the matching template to <repo>/.drone.yml; the Type A file -needs no edits, the Type B file needs its placeholders filled in (below).

    +

    All templates run on platform: linux / arm64 with the workspace at +/drone/src. Copy the matching template to <repo>/.drone.yml; the Type A and +Type B files need no edits, the Type C file needs its placeholders filled in +(below).

    Conventions: .drone.yml (not .yaml), one file per repo, secrets injected with from_secret — never commit credentials.

    Type A — PyPI package (python-lib.yaml)

    -

    For internal libraries. The file contains two pipelines:

    +

    For internal Python libraries. The file contains two pipelines:

    1. build-and-publish-pypi — triggered on tag:
    2. check-version — guard: fail unless $DRONE_TAG equals the version in @@ -716,7 +732,28 @@ with from_secret — never commit credentials.

      same file is reused verbatim across every library.
      3. -

      Type B — Docker deployment (service-docker.yaml)

      +

      Type B — npm package (npm-lib.yaml)

      +

      For internal npm libraries (the React packages). One pipeline, +build-and-publish-npm, triggered on tag:

      +
        +
      • check-version — guard: fail unless $DRONE_TAG equals the version in + package.json; query $NPM_REPO_URL for name@version; if it already + exists, exit 78 and skip the whole build.
        • +
      • quality-gate — write .npmrc from the secrets, npm install, then + npm run quality-gate.
        • +
      • build-package — npm install && npm run build into dist/.
        • +
      • publish-to-private-npm — npm publish --access restricted to + $NPM_REPO_URL.
        • +
      +

      Secrets: NPM_REPO_URL, NPM_USERNAME, NPM_PASSWORD. Auth is a generated +.npmrc (registry= + _auth= base64 of user:pass) written from secrets at +runtime — the committed .npmrc in a repo only points at the registry URL.

      +
        +
      • Ship as-is. Name and version come from package.json, so the same file + is reused verbatim across every npm package.
        • +
      +
      +

      Type C — Docker deployment (service-docker.yaml)

      For a service that ships a container image — a long-running API/worker, e.g. auth-server. The file contains one pipeline, build-and-deploy-service, triggered on tag:

      @@ -774,15 +811,18 @@ triggered on tag:

      What not to do

        -
      • Do not hand-roll a third shape. A repo is either Type A or Type B, never both.
        • +
      • Do not hand-roll a fourth shape. A repo is exactly one of Type A, B, or C, + never combinations.
      • Do not inline secrets; always use from_secret.
      • Do not drop the check-version / check-remote-image skip — it guards the index and the running container against duplicate publishes.
        • -
      • Do not drop the tag↔version guard. A package needs its pyproject.toml - version to equal the tag; a service needs a root VERSION file that equals - the tag. See 91 – Versioning & Changelog.
        • +
      • Do not drop the tag↔version guard. A Python package needs its + pyproject.toml version to equal the tag; an npm package needs its + package.json version; a service needs a root VERSION file. See + 91 – Versioning & Changelog.
      • Do not rename the pipelines; tooling and runbooks key off - build-and-publish-pypi and build-and-deploy-service.
        • + build-and-publish-pypi, build-and-publish-npm, and + build-and-deploy-service.
      diff --git a/standards/lib/91_versioning_and_changelog/index.html b/standards/lib/91_versioning_and_changelog/index.html index bf56263..bd58398 100644 --- a/standards/lib/91_versioning_and_changelog/index.html +++ b/standards/lib/91_versioning_and_changelog/index.html @@ -725,7 +725,7 @@ The version file is the source of truth, the git tag mu a Drone guard enforces that equality before anything is published. Releases are cut manually; a tag is what triggers the pipeline.

      This page pairs with 90 – Drone Pipelines: the version -and tag contract is exactly what those two CI shapes consume.

      +and tag contract is exactly what those three CI shapes consume.

      The version contract

      @@ -743,6 +743,11 @@ and tag contract is exactly what those two CI shapes consume.

      + + + + + @@ -838,7 +843,8 @@ bump travels with the change and only the tag is added afterwards:

    3. In the MR — reconcile [Unreleased] against the change (see Reconcile before releasing) and get the user's approval for any additions. Then set the intended release version: version - in pyproject.toml (or the VERSION file) to x.y.z, and promote the + in pyproject.toml or package.json (or the VERSION file) to x.y.z, + and promote the changelog (below). Changelog entries and link references name the version/tag, never a commit id.
    4. Merge or squash the MR into main.
      5. @@ -853,8 +859,10 @@ After the user confirms the MR is merged/squashed and says to proceed:

      1. Wait for that explicit go-ahead.
      2. Find the commit that introduced the version bump:
        3. -
      3. packages: +
      4. Python packages: git log -S 'version = "x.y.z"' -n 1 --format='%H %s' -- pyproject.toml
        5. +
      5. npm packages: + git log -S '"version": "x.y.z"' -n 1 --format='%H %s' -- package.json
      6. services: git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION
      7. Confirm that commit's version file equals x.y.z, then tag only that @@ -873,13 +881,14 @@ After the user confirms the MR is merged/squashed and says to proceed:

        on top.
      8. In the MR: add the two compare-link references at the bottom of the changelog, naming the version/tag (never a commit id).
        9. -
      9. In the MR: set the version file — pyproject.toml (version = "x.y.z") or - VERSION — to the intended release version.
        10. +
      10. In the MR: set the version file — pyproject.toml (version = "x.y.z"), + package.json ("version": "x.y.z"), or VERSION — to the intended + release version.
      11. Merge or squash the MR into main.
      12. Create the tag on the resulting commit: lightweight git tag x.y.z.
      13. Push the tag (git push origin x.y.z). Watch Drone: Type A publishes the - wheel/sdist, Type B builds and deploys the image; both first assert - tag == version.
        14. + wheel/sdist, Type B publishes the npm package, Type C builds and deploys + the image; all three first assert tag == version.
      14. Do not reuse the tag if the run fails — fix and cut x.y.(z+1).
      diff --git a/standards/lib/94_repository_inventory/index.html b/standards/lib/94_repository_inventory/index.html index 94eed65..a90acfd 100644 --- a/standards/lib/94_repository_inventory/index.html +++ b/standards/lib/94_repository_inventory/index.html @@ -602,18 +602,27 @@
    5. - + - Packages (Type A) + Packages (Type A — PyPI)
    6. - + - Services (Type B) + Packages (Type B — npm) + + + +
      7. + +
    7. + + + Services & Apps (Type C) @@ -667,13 +676,13 @@

      The canonical list of Aetos repositories covered by the CI and versioning standards, with the artifact each one produces, its version source, and its Drone shape. Every entry maps to the contract in -91 – Versioning & Changelog and the two CI +91 – Versioning & Changelog and the three CI files in 90 – Drone Pipelines.

      The same data is published machine-readably as the registry://repos MCP resource (and the list_repos tool), sourced from standards/src/repos.json. Paths are relative to the aetos/ workspace root.

      -

      Packages (Type A)

      +

      Packages (Type A — PyPI)

      A wheel + sdist published to the private index. Version source is pyproject.toml; Drone file is python-lib.yaml (tag-triggered).

      8. check-version also reads it to skip duplicates
      Library (npm package)version in package.jsoncheck-version also queries the registry to skip duplicates
      Service (Docker) VERSION file at the repo root one line, x.y.z; the service reads it (build-arg) — never hardcode the version
      @@ -737,7 +746,41 @@ Paths are relative to the aetos/ workspace root.

      -

      Services (Type B)

      +

      Packages (Type B — npm)

      +

      A package published to the private npm registry (npm.aetoskia.com). Version +source is package.json; Drone file is npm-lib.yaml (tag-triggered).

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RepoPathDocsMCP server
      doc-weaverdoc-weaverlib, wikidoc-weaver:8010
      react-authreact/react-authlib, wikireact-auth:8011
      react-openapireact/react-openapilib, wikireact-openapi:8012
      +
      +

      Services & Apps (Type C)

      A container image pushed to the registry and run on the Docker host. Version source is the VERSION file; Drone file is service-docker.yaml.

      @@ -745,6 +788,7 @@ source is the VERSION file; Drone file is service-docker.yaml + @@ -753,9 +797,17 @@ source is the VERSION file; Drone file is service-docker.yaml + + + + + + + +
      Repo PathType Trigger Docs
      auth-server auth-serverservice tag api, lib, wiki
      vetreact/vetapptaglib, wiki

      Tag-triggered and enforces tag == VERSION.

      @@ -772,13 +824,19 @@ source is the VERSION file; Drone file is service-docker.yaml -package +package (PyPI) pyproject.toml CHANGELOG.md python-lib.yaml -service +package (npm) +package.json +CHANGELOG.md +npm-lib.yaml + + +service / app VERSION CHANGELOG.md service-docker.yaml diff --git a/standards/lib/index.html b/standards/lib/index.html index a3240b5..46131db 100644 --- a/standards/lib/index.html +++ b/standards/lib/index.html @@ -821,8 +821,8 @@ and an optional pipelines layer.

      Delivery & Meta

        -
      • Drone Pipelines — the two CI shapes: a PyPI/npm package or a Docker - deployment.
        • +
      • Drone Pipelines — the three CI shapes: a PyPI package, an npm package, + or a Docker deployment.
      • Versioning & Changelog — SemVer, the tag↔version contract, and the release changelog.
      • Repository Inventory — every covered repo, its type, version source, and diff --git a/standards/lib/search/search_index.json b/standards/lib/search/search_index.json index d5d2d7a..70f8289 100644 --- a/standards/lib/search/search_index.json +++ b/standards/lib/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Standards Reference","text":"

        The reference half of the Standards description: the enforceable rules, patterns, and the internal library catalog that agents consult while coding.

        The reference is organized as an anatomy \u2014 one entry checklist and four pillars describing what an application is made of, plus delivery/meta pages and an optional pipelines layer.

        "},{"location":"#anatomy","title":"Anatomy","text":"
        • Build Recipe \u2014 the ordered, agentic checklist for a new app; the entry point that walks the whole anatomy.
        "},{"location":"#pillar-1-domains","title":"Pillar 1 \u2014 Domains","text":"
        • Layering Rules \u2014 the strict request \u2192 domain \u2192 repository layering and the rules that enforce it.
        "},{"location":"#pillar-2-openapi-spec-the-contract","title":"Pillar 2 \u2014 OpenAPI Spec (the contract)","text":"
        • Composition Root \u2014 a single composition point wiring the whole app.
        • Spec-First Routing \u2014 the OpenAPI contract as the routing source of truth.
        • CRUD Template \u2014 the standardized generic resource endpoint scaffold.
        • Auth Integration \u2014 consuming the shared auth-server service (spec-driven, no auth code).
        "},{"location":"#pillar-3-interfaces-infra","title":"Pillar 3 \u2014 Interfaces & Infra","text":"
        • Infra Adapters \u2014 how infrastructure connects without leaking into domain.
        "},{"location":"#pillar-4-ui","title":"Pillar 4 \u2014 UI","text":"
        • UI: Auto-Rendered Admin & Custom Pages \u2014 the @aetoskia/react-openapi admin rendered from the spec's x- extensions, and @aetoskia/react-auth for auth pages; the client template scaffold.
        "},{"location":"#pipelines-optional-layer","title":"Pipelines (optional layer)","text":"
        • Pipeline Scaffold \u2014 the deterministic pipeline skeleton for multi-stage jobs.
        • Worker & Progress \u2014 queued work, progress reporting, and visibility.
        • Human-in-the-Loop \u2014 guardrails and approvals inside automations.
        "},{"location":"#delivery-meta","title":"Delivery & Meta","text":"
        • Drone Pipelines \u2014 the two CI shapes: a PyPI/npm package or a Docker deployment.
        • Versioning & Changelog \u2014 SemVer, the tag\u2194version contract, and the release changelog.
        • Repository Inventory \u2014 every covered repo, its type, version source, and Drone shape.
        • Genericity Matrix \u2014 what is library-backed, template-provided, or authored.
        • Library Registry \u2014 the catalog of internal libraries behind all of it.

        Read the Wiki for the philosophy and rationale; these pages are the reference that mirrors the standards MCP bundle.

        "},{"location":"01_build_recipe/","title":"Build Recipe","text":""},{"location":"01_build_recipe/#summary","title":"Summary","text":"

        The ordered, deterministic checklist for generating a new application of the standard shape. Every step is fixed; only the resource model (step 2), the codegen pass (step 3), and the pipeline family (step 8) need app-specific work.

        The reference pages behind this recipe are organized as an anatomy: the domains layer, the OpenAPI contract that drives routing and the admin UI, the interfaces/infra seam, the auto-rendered UI client, and an optional pipelines layer \u2014 see the Standards Reference index.

        This page is served by the standards MCP as docs://modules/build_recipe. The start_app prompt on that server collects the two axes and hands off here; pull exact files with get_app_component.

        "},{"location":"01_build_recipe/#bootstrap","title":"\ud83d\ude80 Bootstrap","text":"

        From the standards docs checkout:

        cp -r <docs>/standards/src/templates/app apps/<your-app>\ncd apps/<your-app>\n

        Pair it with the React client template when a UI is needed (auto-rendered admin from the spec \u2014 see 40 \u2013 UI):

        cp -r <docs>/standards/src/templates/client apps/<your-app>-client\ncd apps/<your-app>-client && npm install\n

        Install the internal libraries \u2014 editable local checkouts (preferred in development) or the private index (CI / fresh machines). Credentials are environment-only; never commit them.

        # local checkouts\npip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa \\\n            -e ../aetos/dagpipe -e ../aetos/doc-forge\n# private index\npip install --extra-index-url \\\n  \"https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple\" .\n
        "},{"location":"01_build_recipe/#agent-prompt-copyable","title":"\ud83d\udccb Agent prompt (copyable)","text":"
        # Build a new application from the Aetos Standards blueprint\n\nYou are coding a complete new backend application conforming to the Aetos\nstandard app blueprint. Execute every step in order. Only steps 2\u20134 use the\napp-specific details provided by the user; everything else is deterministic.\n\n## Before writing any code\n\nConnect to the `standards` MCP server and read:\n- `docs://nav` (the module list)\n- `docs://modules/genericity_matrix` (Tier A library / Tier B template / Tier C authored)\n- `docs://modules/layering_rules` (the dependency rules)\n\nThen:\n- call `find_library` with `db`, `di`, `routing`, `ingestion`, `pipeline`, `docs`\n  and note the Tier A libraries that already exist \u2014 never reimplement one;\n- call `list_app_components()` and pull each file you need with\n  `get_app_component(kind, resource=..., family=...)` instead of writing it from\n  scratch.\n\n## Steps\n\n1. **Scaffold** \u2014 copy `standards/src/templates/app/` into `apps/<your-app>/`\n   (or pull the same tree via `get_app_template`). Keep the tree: `domain/`,\n   `infra/`, `interfaces/`, `pipelines/`, `tests/`, `scripts/`, plus\n   `pyproject.toml`, `openapi.yaml`, `config.py`, `init.py`, `main.py`,\n   `worker.py`, `Dockerfile`, `docker-compose.yaml`, `.env.example`.\n\n2. **Author the spec (app-specific)** \u2014 write `openapi.yaml`: resources,\n   schemas, `operationId`s, security, and extension metadata. This is the\n   contract and drives all routing. Every operation MUST have an `operationId`.\n\n3. **Generate the scaffold (codegen)** \u2014 from the spec, generate the wire\n   models and the exact handler signatures:\n   ```bash\n   openapi-first models openapi.yaml -o _gen/models.py\n   openapi-first routes openapi.yaml -o _gen/routes \\\n     --use-models --models-module _gen.models --inject-request --package --template-style\n   ```\n   `_gen/models.py` is the **wire contract** (Pydantic, one class per\n   `components.schemas` entry). `_gen/routes/<resource>/routes.py` lists every\n   `operationId` with its exact parameter signature. `--template-style` makes\n   those stubs `async def` with a `body` parameter, matching the handlers you\n   keep in `interfaces/` (without it they are sync `def` stubs taking\n   `payload`; both bind the same way). Treat `_gen/` as generated\n   (never hand-edit it) \u2014 the canonical handlers live in `interfaces/`.\n\n4. **Write each CRUD slice (app-specific)** \u2014 per resource create the four-file\n   slice: `models.py` (domain model, **no `id`**), `ports/db.py`\n   (`class XDocument(BaseDocument, X)` \u2014 id comes from `BaseDocument`),\n   `ports/service.py`, and optional `converters.py`. Follow the CRUD template.\n\n5. **Wire the composition root** \u2014 in `init.py`, build leaf repositories, then\n   dependent repositories, then services; add infra adapters (db, cache, stores,\n   progress bus, fetchers). Expose `get_svc` overloads.\n\n6. **Add routes** \u2014 create `interfaces/<resource>/routes.py` thin handlers whose\n   names match the `operationId`s (use the signatures from step 3 as your\n   checklist) and re-export them in `interfaces/openapi.py`. Add the cache\n   decorator to read endpoints.\n\n7. **Bootstrap app and worker** \u2014 confirm `main.py` runs the OpenAPI-first app\n   with its lifespan. If the app has long-running jobs, adapt `worker.py` to poll\n   the job collection, run the pipeline, and publish progress.\n\n8. **Add pipeline families (only if data-driven)** \u2014 copy `pipelines/example/`\n   to `pipelines/<family>/` with `abc.py`, `impl.py`, `pipeline.yaml`,\n   `resources/`, and reuse `pipelines/shared/` (loader + registry). Register the\n   root. Add fixtures and a parity test.\n\n9. **Add infrastructure only where needed** \u2014 Tier A capability: use the\n   library. Tier B capability: copy the template. Never hand-write a Tier A\n   library.\n\n10. **Tests** \u2014 integration tests with fakes at the HTTP edge; unit tests for\n    domain and pipeline logic; a config-consistency test for rule-driven\n    pipelines. Include `tests/integration/test_openapi_app_builds.py` (imports\n    the app, asserts `import main` binds every operation).\n\n11. **Scripts and seeds** \u2014 operator scripts under `scripts/` using\n    `init()` / `get_svc()` / `shutdown()`; run as `python -m scripts.<name>`.\n\n12. **Docs** \u2014 author GSDFC docstrings, generate `.pyi` stubs, mark the package\n    `py.typed`, and build the docs.\n\n**Definition of done:**\n- `python -c \"import main\"` succeeds.\n- `pytest` passes.\n- The app serves every operation in the spec; the worker drains its queue.\n- No domain module imports a web framework.\n- No Tier A library was reimplemented.\n
        "},{"location":"01_build_recipe/#where-the-steps-land","title":"\ud83e\udded Where the steps land","text":"

        The steps map onto the layers as follows:

        Step Package / file Depends on 1 \u00b7 Scaffold whole templates/app/ \u2014 2 \u00b7 Spec openapi.yaml \u2014 3 \u00b7 Codegen _gen/ (generated) spec, openapi-first 4 \u00b7 CRUD slices domain/<resource>/ spec, CRUD template 5 \u00b7 Wiring init.py every slice 6 \u00b7 Routes interfaces/<resource>/ services, openapi route registry 7 \u00b7 Bootstrap main.py, worker.py composition root 8 \u00b7 Pipelines pipelines/<family>/, shared/ library pipeline engine 9 \u00b7 Infra infra/ domain ports 10 \u00b7 Tests tests/ app + fixtures 11 \u00b7 Scripts scripts/ composition root 12 \u00b7 Docs docstrings + docs build code, Doc Forge"},{"location":"01_build_recipe/#the-codegen-fast-path-in-detail","title":"\ud83d\udd27 The codegen fast path, in detail","text":"

        openapi-first is spec \u2192 code only (it never generates a spec). Use it to erase the two mechanical parts of the build:

        Generated artifact Replaces Notes _gen/models.py hand-writing Pydantic wire models one class per components.schemas entry _gen/routes/<resource>/routes.py hand-typing handler signatures names == operationIds; request: Request injected

        Rules of the road:

        • Wire models are not domain models. _gen/models.py is the HTTP contract; domain/<resource>/models.py is your business shape. If the spec's schema has a required id: str, keep it off the domain model and let the document get its id from BaseDocument.
        • Use --template-style. Stubs are then async def ...(request, body: ...) matching interfaces/; without it they are sync def ...(payload: ...). Either binds (the router introspects the signature), but --template-style keeps the scaffold consistent with the code you keep.
        • Resource names are sanitized. /fetch-requests \u2192 fetch_requests.py.
        • Multipart bodies expand to UploadFile = File(...) / Form(...) params.
        • _gen/ is disposable. Regenerate on every spec change; git diff shows exactly what moved.
        "},{"location":"01_build_recipe/#definition-of-done","title":"\u26a0\ufe0f Definition of done","text":"
        • python -c \"import main\" succeeds.
        • pytest passes.
        • The app serves the spec's operations; the worker drains its queue.
        • No domain module imports a web framework.
        • No Tier A library was reimplemented.
        "},{"location":"01_build_recipe/#related","title":"Related","text":"
        • 10 \u2013 Layering Rules \u00b7 21 \u2013 CRUD Template \u00b7 22 \u2013 Auth Integration \u00b7 40 \u2013 UI \u00b7 50 \u2013 Pipeline Scaffold \u00b7 92 \u2013 Genericity Matrix
        "},{"location":"02_composition_root/","title":"Composition Root","text":""},{"location":"02_composition_root/#summary","title":"Summary","text":"

        All wiring happens in exactly one module. It builds a flat resource registry and exposes it to the HTTP layer and to scripts.

        "},{"location":"02_composition_root/#the-resource-registry","title":"The resource registry","text":"

        init.py returns a plain dict[str, Any]. Keys follow two conventions:

        • <resource>_repo \u2014 a repository adapter for a resource.
        • <resource>_svc \u2014 a service for a resource.

        Plus named infrastructure adaptors:

        • http_cache_store \u2014 response cache backend.
        • progress_bus \u2014 progress/event bus.
        • <vendor>_<kind> \u2014 fetchers, clients, stores.

        The API stores the dict on app.state.db_resources during lifespan startup. Handlers read from it; nothing imports concrete adapters.

        "},{"location":"02_composition_root/#shape","title":"Shape","text":"
        _resources: dict = {}\n_initialized = False\n\nasync def init(settings=None) -> dict:\n    global _initialized\n    if _initialized:\n        return _resources\n\n    await setup_database(uri=settings.mongo_uri, db_name=settings.mongo_db)\n\n    # 1. leaf repositories\n    user_repo = create_user_repo()\n\n    # 2. dependent repositories (dependencies passed by keyword)\n    wallet_repo = create_wallet_repo(user_repo=user_repo)\n\n    # 3. services (build via the DI library, injecting the repo)\n    _resources[\"user_repo\"]   = user_repo\n    _resources[\"wallet_repo\"] = wallet_repo\n    _resources[\"user_svc\"]    = get_user_service(user_repo)\n    _resources[\"wallet_svc\"]  = get_wallet_service(wallet_repo)\n\n    # 4. infrastructure adaptors (optional)\n    _resources[\"http_cache_store\"] = HttpCacheStore(...)\n    _resources[\"progress_bus\"]     = ProgressEventBus()\n\n    _initialized = True\n    return _resources\n\nasync def shutdown() -> None:\n    global _initialized\n    await close_stores(_resources)\n    await shutdown_database()\n    _resources.clear()\n    _initialized = False\n
        "},{"location":"02_composition_root/#typed-accessors","title":"Typed accessors","text":"

        Expose a get_svc(name) helper with one @overload per key so scripts get typing without importing concrete classes:

        @overload\ndef get_svc(name: Literal[\"user_svc\"]) -> UserService: ...\n@overload\ndef get_svc(name: Literal[\"wallet_svc\"]) -> WalletService: ...\n\ndef get_svc(name: str):\n    return _resources[name]\n

        Also expose get_db() (raw database handle) and pure helpers such as compute_fingerprint(payload) (canonical hash used for deduplication).

        "},{"location":"02_composition_root/#rules","title":"Rules","text":"
        • init() is idempotent.
        • The composition root is the only place that imports concrete adapters.
        • Handlers never call init(); they read request.app.state.db_resources.
        • Scripts call init() / shutdown() around their work.
        "},{"location":"10_layering_rules/","title":"Layering Rules","text":""},{"location":"10_layering_rules/#summary","title":"Summary","text":"

        The dependency direction is fixed. Violating it is a design defect.

        "},{"location":"10_layering_rules/#allowed-imports","title":"Allowed imports","text":"
        interfaces/*      ->  domain/*            (services, ports, models)\ninterfaces/*      ->  infra/adapters/*    (only read-only value objects)\ndomain/*          ->  domain/*            (same layer)\ndomain/*          ->  pipelines/*         (call a pipeline via a port)\ndomain/*/ports/*  ->  infra/*             (bind adapters + libraries at the seam)\ninfra/adapters/*  ->  domain/ports/*      (implement the interface)\nmain.py/init.py   ->  everything          (composition root only)\n
        "},{"location":"10_layering_rules/#forbidden-imports","title":"Forbidden imports","text":"
        domain/*          ->  interfaces/*        (never)\ndomain/*          ->  fastapi/starlette   (never)\ninfra/adapters/*  ->  interfaces/*        (never)\ninterfaces/*      ->  infra/db/*          (state lives in resources, not imports)\n
        "},{"location":"10_layering_rules/#why","title":"Why","text":"
        • The business logic is testable without a server or an event loop.
        • Adapters can be swapped (in-memory fake, real database) without touching business logic.
        • The HTTP edge stays thin and replaceable.
        "},{"location":"10_layering_rules/#the-portadapter-contract","title":"The port/adapter contract","text":"

        The ports/ package is the seam where the domain meets infrastructure. Each domain/<resource>/ports/ module declares the resource's models/document shape and exposes factory functions that bind a concrete adapter \u2014 so a port module is allowed to import from infra/ and from the persistence libraries. Everything outside ports/ in domain/ stays framework- and driver-free.

        domain/<resource>/ports/db.py       -> document model + create_<resource>_repo()\ndomain/<resource>/ports/service.py  -> service + get_<resource>_service()\ninfra/db/repos/<vendor>.py          -> repository adapter factory\ninfra/adapters/service.py           -> generic CRUD service base\n

        The composition root calls the port factories; nothing else constructs an adapter.

        "},{"location":"10_layering_rules/#enforcement","title":"Enforcement","text":"
        • domain/ must never import the web framework (fastapi / starlette) or interfaces/. Only the ports/ seam, infra/, and the composition root touch drivers.
        • Reviewers (and CI) reject import fastapi inside domain/ or infra/.
        "},{"location":"20_spec_first_routing/","title":"Spec-First Routing","text":""},{"location":"20_spec_first_routing/#summary","title":"Summary","text":"

        The OpenAPI document is the single source of truth for the HTTP contract. Handlers are bound to it by name; there is no decorator router.

        "},{"location":"20_spec_first_routing/#the-contract","title":"The contract","text":"
        • openapi.yaml (or .json) declares paths, schemas, parameters, responses, and security.
        • A custom operationId names the handler function.
        • The framework (openapi_first) validates requests/responses against the spec and dispatches to the handler whose name equals operationId.
        "},{"location":"20_spec_first_routing/#app-bootstrap","title":"App bootstrap","text":"
        # main.py\nfrom openapi_first.app import OpenAPIFirstApp\n\napp = OpenAPIFirstApp(\n    openapi_path=\"openapi.yaml\",\n    routes_module=interfaces.openapi,   # module whose namespace holds handlers\n    title=\"<App> API\",\n    version=\"0.1.0\",\n    lifespan=lifespan,\n)\n

        lifespan calls the composition root:

        @asynccontextmanager\nasync def lifespan(app):\n    app.state.db_resources = await init()\n    yield\n    await shutdown()\n
        "},{"location":"20_spec_first_routing/#handler-registry","title":"Handler registry","text":"

        interfaces/openapi.py is a flat re-export of every handler, so the framework can resolve operationId across the whole app:

        from interfaces.item.routes import *\nfrom interfaces.wallet.routes import *\nfrom interfaces.progress.sse import *\n
        "},{"location":"20_spec_first_routing/#handler-shape","title":"Handler shape","text":"

        Handlers are thin and synchronous with respect to business logic:

        async def create_item(request: Request, body: dict):\n    svc = request.app.state.db_resources[\"item_svc\"]\n    return await svc.create(Item.model_validate(body))\n

        Generated stubs. openapi-first routes emits this exact shape (async def handlers taking body) when given --template-style; without that flag the stub is def create_item(payload: ItemInput) \u2014 sync, with a payload parameter. Both shapes bind identically: the router resolves handlers by operationId and introspects the FastAPI signature, and it never inspects the request body. Pass --template-style so the generated signatures match the handlers you keep in interfaces/.

        "},{"location":"20_spec_first_routing/#conventions","title":"Conventions","text":"
        • operationId naming: list_<resource>, create_<resource>, get_<resource>, update_<resource>, delete_<resource>.
        • Read-only endpoints may use a cache decorator keyed on path + query + user.
        • Validation errors -> 400; not found -> 404; delete -> 204.
        • Security is declared once in the spec and enforced by the framework; handlers contain no auth code.
        "},{"location":"20_spec_first_routing/#authless-apps","title":"Authless apps","text":"

        Auth is deferred in the standard: the same spec-first app runs with or without it, because security lives entirely in the spec, never in handlers. For an app that needs no auth yet, do not invent per-handler auth checks \u2014 just omit the security keys:

        • Remove the top-level security: block.
        • Remove components.securitySchemes.
        • Do not add security: [] to operations. An explicit empty array is a per-operation override that means \"public\", and it only matters when a global security block exists. Leaving every operation without a security key is the cleanest authless spec.

        Profile endpoints (/users/me) and profile headers (x-profile) still exist in an authless app. Define a stand-in identity in the composition root \u2014 for example get_current_user returns or lazily creates a fixed \"Demo User\" \u2014 so handlers stay auth-agnostic and only the wiring changes when real auth arrives.

        The handlers, services, and composition root are unchanged. When auth is needed later, add the global security block and an introspecting dependency; only handlers that must opt out get security: [].

        "},{"location":"20_spec_first_routing/#codegen","title":"Codegen","text":"

        openapi_first scaffolds models and route stubs from the spec (see the Build Recipe, step 3):

        openapi-first models openapi.yaml -o _gen/models.py\nopenapi-first routes openapi.yaml -o _gen/routes \\\n  --use-models --models-module _gen.models --inject-request --package --template-style\n

        Prefer codegen over hand-writing boilerplate. The result is the wire contract and a set of operationId-named signatures \u2014 not the canonical handlers.

        "},{"location":"21_crud_template/","title":"CRUD Template","text":""},{"location":"21_crud_template/#summary","title":"Summary","text":"

        Every resource follows the same four-file slice. Repetition is intentional: it makes the codebase predictable and generatable.

        "},{"location":"21_crud_template/#the-slice","title":"The slice","text":"
        domain/<resource>/\n    models.py               # pure Pydantic model (no DB fields)\n    ports/\n        db.py               # document model + repository factory\n        service.py          # service class + factory\n        converters.py       # (optional) transforms\n
        "},{"location":"21_crud_template/#the-id-rule-model-vs-document","title":"The id rule (model vs. document)","text":"

        Two different objects, two different jobs:

        Object Lives in Has id? Purpose Domain model domain/<resource>/models.py No business shape, framework-free Document domain/<resource>/ports/db.py Yes (from BaseDocument) Mongo persistence shape

        BaseDocument (mongo-ops) supplies id: Optional[PyObjectId] (aliased to _id) plus created_at / updated_at. The domain model must not declare id; Mongo owns it.

        Trap \u2014 generated wire models. openapi-first models produces the HTTP contract (see the Build Recipe, step 3). Response schemas frequently declare a required id: str, so a generated class is not a domain model. If you write class ItemDocument(Item, BaseDocument) and Item re-exports a required id: str, that field shadows BaseDocument.id and no Mongo _id can ever be set. Fix it one of three ways:

        1. Preferred: keep the domain model id-free (hand-author it from the CRUD template), and keep the required id only on the wire model.
        2. Order the bases so the document wins: class ItemDocument(BaseDocument, Item).
        3. Keep a separate document type and translate with ports/converters.py.
        "},{"location":"21_crud_template/#modelspy","title":"models.py","text":"

        A framework-free Pydantic model describing the business shape (no id).

        class Item(BaseModel):\n    name: str\n    quantity: int = 0\n
        "},{"location":"21_crud_template/#portsdbpy","title":"ports/db.py","text":"

        The persistence model extends the business model and adds database concerns. The repository factory selects the right repository flavour.

        # Item is id-free; BaseDocument adds id/created_at/updated_at.\nclass ItemDocument(Item, BaseDocument):\n    pass\n\ndef create_item_repo(*, owner_repo=None) -> ItemRepository:\n    return repo_factory(\n        collection=\"items\",\n        document=ItemDocument,\n        populate_rules=[PopulateRule(field_name=\"owner\", collection_name=\"users\")],\n        cache=None,               # or a CachedBaseRepository config\n    )\n
        "},{"location":"21_crud_template/#nested-references","title":"Nested references","text":"

        The wire contract often declares a reference as an expanded object (expense.entity: Entity), while the domain model stays id-free. Pick one convention and apply it consistently:

        • Embed (default for small, stable refs) \u2014 store the object as a dict / list[dict] on the document; the API returns it verbatim. No populate wiring.
        • Populate \u2014 store an id and declare a PopulateRule; mongo-ops expands it on read. The referenced repo must be registered with the PopulationEngine.
        • Id only \u2014 store the id and let the client resolve it.

        For populate-backed repositories change a reference with update, not patch: patch rejects changes to populated FK fields by design.

        "},{"location":"21_crud_template/#portsservicepy","title":"ports/service.py","text":"

        The service is built through the DI library, injecting the repository. The generic CRUD base provides create/read/update/patch/delete/search/....

        class ItemService(CrudsServiceAdaptor[Item, ItemDocument]):\n    model = Item\n    schema = ItemDocument\n\ndef get_item_service(repo) -> ItemService:\n    return build(ItemService, instances={\"repo\": repo})\n
        "},{"location":"21_crud_template/#naming-conventions","title":"Naming conventions","text":"Concept Convention collection plural snake case (items) document <Resource>Document repository factory create_<resource>_repo service <Resource>Service service factory get_<resource>_service resource key <resource>_svc operationId list_items, create_item, ..."},{"location":"21_crud_template/#optional-files","title":"Optional files","text":"
        • converters.py \u2014 pure functions mapping between domain types.
        • ports/enrichment.py \u2014 adapts a pipeline into an async callable the service can invoke (used when a resource is populated by a pipeline).
        "},{"location":"22_auth_integration/","title":"Auth Integration","text":""},{"location":"22_auth_integration/#summary","title":"Summary","text":"

        Authentication is a service, not a library. Every Aetos application shares a single identity service \u2014 the auth-server \u2014 and consumes it through its HTTP contract. An app never implements registration, login, password hashing, or token issuance itself.

        The agent does not need an MCP bundle for the auth-server. It reads the pinned OpenAPI contract (below) and declares a bearer security scheme in its own spec; openapi_first then generates the verifying dependency. No auth code is written.

        "},{"location":"22_auth_integration/#read-the-contract","title":"Read the contract","text":"

        The auth-server OpenAPI document is pinned in the standards bundle and served as an MCP resource:

        docs://spec\n

        It is the authoritative client contract (OpenAPI 3.1). Read it to learn the endpoints and the request/response schemas:

        Endpoint Purpose POST /register Create a user (201, returns PublicUser) POST /login Authenticate and issue a JWT (LoginResponse) GET /me Current user's PublicUser (bearer required) POST /logout Stateless logout (LogoutResponse) POST /introspect Internal token introspection (active, user)

        The pinned snapshot is versioned (currently 0.0.5). If the caller has a live auth-server and needs the current contract, they can pass the full endpoint ({AUTH_SERVER}/openapi.json) and read it directly instead of the pin.

        "},{"location":"22_auth_integration/#wire-it-up-declare-dont-code","title":"Wire it up: declare, don't code","text":"

        Authentication is added by editing the app's own openapi.yaml \u2014 nothing else. Declare a global bearer requirement and point the scheme at the auth server (values come from the environment):

        security:\n  - bearerAuth: []\npaths:\n  # ...\ncomponents:\n  securitySchemes:\n    bearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n      x-server-url: \"{AUTH_SERVER}\"\n      x-introspect-path: \"/introspect\"\n      x-login-path: \"/login\"\n      x-register-path: \"/register\"\n      x-logout-path: \"/logout\"\n      x-me-path: \"/me\"\n

        openapi_first reads securitySchemes + security and generates a FastAPI dependency that extracts the bearer token, POSTs {\"token\": <jwt>} to {AUTH_SERVER}/introspect, and returns the user when active == true. It raises 401 on an invalid or inactive token and 503 when the auth server is unreachable. The generated handlers receive the authenticated user \u2014 you author no authentication code.

        "},{"location":"22_auth_integration/#public-operations","title":"Public operations","text":"

        A route that must stay open opts out by overriding security with an empty list:

        paths:\n  /health:\n    get:\n      operationId: health\n      security: []        # overrides the global requirement\n      responses:\n        \"200\":\n          description: OK\n
        "},{"location":"22_auth_integration/#environment","title":"Environment","text":"
        AUTH_SERVER=http://localhost:8000     # auth-server base URL\nJWT_SERVER=http://localhost:8000      # jwtlib client base URL (seeding/CLI)\n
        "},{"location":"22_auth_integration/#path-1-jwtlib-client-no-generator","title":"Path 1: jwtlib client (no generator)","text":"

        Apps that do not use a generated dependency verify requests with the py-jwt client:

        from jwtlib.introspection import authenticate_request\n\nauthorized = await authenticate_request(\n    should_skip_authentication,  # allow public paths\n    method,\n    path,\n    authorization_token,         # \"Bearer <jwt>\" or None\n)\n

        authenticate_request POSTs to {JWT_SERVER}/introspect (3 second timeout) and treats {\"active\": true, \"user\": {...}} as valid. Use this for seeding scripts and tests (jwtlib.register_user, jwtlib.login_user).

        "},{"location":"22_auth_integration/#golden-rules","title":"Golden rules","text":"
        1. Never trust an unverified token. Decode through the generated dependency or jwtlib before handling the request.
        2. Treat active: false as unauthenticated, even if the JWT decodes.
        3. Do not implement your own JWT parsing. Revocation and issuer changes must stay centralized in the auth-server.
        4. Do not add auth until the app's outcome is validated. Ship the app authless first; layer the security scheme once the core behaviour works.
        "},{"location":"22_auth_integration/#notes","title":"Notes","text":"
        • The default template is authless on purpose. Add the securitySchemes block above only when auth is required. Pull the shared slice with get_app_component(\"auth\").
        • The auth-server is deployed as a service (no importable package); the client surface is the spec, plus jwtlib for the low-level path.
        "},{"location":"30_infra_adaptors/","title":"Infra Adapters","text":""},{"location":"30_infra_adaptors/#summary","title":"Summary","text":"

        All external systems are reached through adapters in infra/. Prefer an existing internal library over writing a new adapter; where no library exists, copy the Tier B scaffold from templates/app. See the Genericity Matrix for the Tier A / B / C split.

        "},{"location":"30_infra_adaptors/#database-mongodb","title":"Database (MongoDB)","text":"
        • A single connection manager owns the client lifecycle. setup_database(uri, db_name) / shutdown_database().
        • A repository factory selects the repository flavour:
        repo_factory(collection, document, engine=None,\n             populate_rules=None, cache=None)\n
        • base repository \u2014 plain CRUD;
        • populating repository \u2014 resolves referenced documents (foreign keys);

        • cached repository \u2014 an LRU/TTL cache in front of reads.

        • Referenced documents are described declaratively:

        PopulateRule(field_name=\"owner\", collection_name=\"users\",\n             nested_rules=[], max_depth=2, projection=None)\n
        • Transactions use a session context manager provided by the library.

        Tier A \u2014 Library (Mongo Ops). Do not write raw Motor calls in the domain; consult the registry and the library's MCP before touching the driver.

        "},{"location":"30_infra_adaptors/#http-response-cache","title":"HTTP response cache","text":"

        Tier B \u2014 template. Copy from templates/app; not a standalone library.

        A generic GET cache sits behind a decorator.

        @cache_response(ttl=60)\nasync def list_items(request): ...\n
        • Keyed on path + query + user.
        • No-op when no store is wired.
        • invalidate(*resources) bumps a generation counter for write-triggered invalidation.
        "},{"location":"30_infra_adaptors/#event-progress-bus","title":"Event / progress bus","text":"

        Tier B \u2014 template. Copy from templates/app.

        A port with an in-memory default adapter (publish, get_events). Swap for a durable broker in production (see Worker & Progress).

        "},{"location":"30_infra_adaptors/#external-clients-ingestion","title":"External clients (ingestion)","text":"

        External fetchers (files, mail, HTTP) are adapters that wrap ingestion libraries. Construct them in the composition root and inject into orchestrators.

        Tier A \u2014 Libraries: Omniread (formats) and Mail Intake (email).

        "},{"location":"30_infra_adaptors/#llm-clients","title":"LLM clients","text":"

        Tier B \u2014 template. Copy the pool scaffold from templates/app.

        When a pipeline calls a model provider, route through a pool adaptor that handles provider selection, retries, and client lifecycle:

        pool = setup_async_pool(provider=settings.llm_provider)\nresult = await pool.complete(model=\"...\", messages=[...])\n

        Providers are selected by LLM_PROVIDER and configured by environment.

        "},{"location":"30_infra_adaptors/#key-value-store","title":"Key-value store","text":"

        Tier B \u2014 template. Copy from templates/app.

        For report/snapshot storage, provide a pluggable store port with a Redis adapter and an in-memory fallback.

        "},{"location":"30_infra_adaptors/#rule","title":"Rule","text":"
        • Tier A (libraries: DB, DI, ingestion, mail, auth, docs, pipelines) \u2014 use the library; writing a private copy is a defect. Query find_library first.
        • Tier B (cache, progress bus, LLM pool, KV store, composition shape, worker, tests) \u2014 these are template code, not libraries: copy them from templates/app rather than searching the registry.
        • Tier C (models, business logic, pipeline families, rules) \u2014 author them yourself.
        "},{"location":"40_ui_admin/","title":"UI: Auto-Rendered Admin & Custom Pages","text":""},{"location":"40_ui_admin/#summary","title":"Summary","text":"

        The UI axis of an Aetos app is a published React client, not code written per application. Two npm packages carry the whole surface:

        Package Role @aetoskia/react-openapi Renders a complete admin panel (CRUD tables, forms, filters, sorting, pagination, uploads) from the app's openapi.yaml \u2014 zero UI code. @aetoskia/react-auth Auth contexts and pages (login/register/me) wired to the auth-server, plus the axios client with token handling.

        Both publish to the private registry https://npm.aetoskia.com. The server spec is the single source of truth: the same openapi.yaml that drives openapi-first routing drives the admin UI, through x- extension fields (see below).

        "},{"location":"40_ui_admin/#scaffold","title":"Scaffold","text":"
        cp -r <docs>/standards/src/templates/client apps/<your-app>-client\ncd apps/<your-app>-client\nnpm install          # deps come from npm.aetoskia.com via .npmrc\nnpm run dev\n

        The client template is a Vite + MUI app with:

        • src/openapi-config.ts \u2014 points the renderer at the app's spec and the auth-server's spec;
        • .env.example \u2014 VITE_API_BASE_URL (app API) and VITE_AUTH_BASE_URL (auth-server);
        • a Home page that auto-lists every resource the spec declares, and a Header/Footer/theme scaffold.

        Custom pages are ordinary React routes layered on top; the auto-rendered admin is available per resource at #/resource/<name>.

        "},{"location":"40_ui_admin/#x-extensions-how-the-spec-steers-the-ui","title":"x- extensions: how the spec steers the UI","text":"

        The admin renderer reads a catalog of OpenAPI extension fields (x-resource, x-list-columns, x-display-format, x-label, x-order, x-hidden, x-sortable, x-filterable, x-autocomplete, x-fk, x-ui-type, x-upload, x-sse, x-profile, and the auth wiring x-server-url / x-login-path / x-me-path / \u2026) declared on schemas and properties.

        The catalog is canonical in the react-openapi source, not in this doc. Read it from the MCP bundle:

        docs://modules/react-openapi        # module: specExtensions \u2014 the full catalog\n

        The app's own spec carries the per-resource values; the catalog explains what each field does. The template's openapi.yaml shows the convention on the example Item and Job schemas.

        "},{"location":"40_ui_admin/#golden-rules","title":"Golden rules","text":"
        1. The spec owns the UI. Add a resource or rename a column in openapi.yaml; the admin follows. Never fork the renderer per app.
        2. Custom pages for workflows, auto-render for CRUD. Anything that is \"list / create / edit / delete an entity\" is a spec concern; anything that is a bespoke workflow is a React page.
        3. Auth is consumed, never re-implemented. @aetoskia/react-auth holds tokens and calls the auth-server endpoints declared by the x- wiring; pages read the context.
        4. Publish, don't vendor. UI shared across apps belongs in @aetoskia/react-openapi or @aetoskia/react-auth (SemVer, tag-triggered npm release), not copy-pasted into app trees.
        "},{"location":"40_ui_admin/#notes","title":"Notes","text":"
        • The server template ships authless by default (see 22 \u2013 Auth Integration); the client template pairs with it and degrades to \"no login\" until a security scheme is declared.
        • react/vet is the full-stack reference implementation: spec with x- extensions, server, and the consuming client in one tree.
        "},{"location":"50_pipeline_scaffold/","title":"Pipeline Scaffold","text":""},{"location":"50_pipeline_scaffold/#summary","title":"Summary","text":"

        Data-driven processing is expressed as a composition graph. The graph is built by a DI library; execution is driven by a DAG engine. Stages are pure and individually testable.

        "},{"location":"50_pipeline_scaffold/#when-to-use-a-pipeline","title":"When to use a pipeline","text":"

        Use a pipeline when a resource is produced by a multi-step transformation of an input (a document, a file, a message) rather than by a simple CRUD write.

        "},{"location":"50_pipeline_scaffold/#structure-of-a-family","title":"Structure of a family","text":"

        A family is one input shape (e.g. a file format or a message kind). Each family has the same skeleton:

        pipelines/<family>/\n    abc.py            # port contracts (stage interfaces + root interface)\n    impl.py           # concrete stages + root implementation\n    pipeline.yaml     # graph spec: nodes, edges, roots, schema\n    resources/\n        pipeline.yaml # runtime spec consumed by the loader\n        patterns/*.yaml  # rule fragments (pattern registry)\n    banks/<variant>.py   # optional variants that re-pin a few slots\n
        "},{"location":"50_pipeline_scaffold/#shared-scaffolding","title":"Shared scaffolding","text":"
        pipelines/shared/\n    ports.py     # RegistryPort, FinalizePort, etc.\n    loader.py    # build(root_cls) -> wires the graph + engine\n    registry.py  # resolve_root(...) -> root class for a (kind, variant)\n
        "},{"location":"50_pipeline_scaffold/#the-loader","title":"The loader","text":"
        def build(root_cls, *, instances=None, config=None):\n    # merge resources/patterns/*.yaml into a pattern registry\n    # bind registry/config into each graph node by id\n    # build the schema (state) class and the engine\n    root = root_cls()\n    root._engine = Engine(graph, state_cls, payload_cls)\n    return root\n
        "},{"location":"50_pipeline_scaffold/#the-registry","title":"The registry","text":"

        A single lookup replaces hand-rolled if/else selection:

        _FAMILIES = {\n    \"csv\":  {\"acme\": {\"heuristic\": AcmeCsvPipeline}},\n    \"json\": {\"globex\": {\"heuristic\": GlobexJsonPipeline}},\n}\n\ndef resolve_root(kind, variant, mode=\"heuristic\"):\n    return _FAMILIES[kind][variant][mode]\n

        Adding a new variant means adding one class and one registry entry.

        "},{"location":"50_pipeline_scaffold/#driving-a-pipeline","title":"Driving a pipeline","text":"

        Stages are driven explicitly so intermediate state can be persisted:

        pipeline = build(resolve_root(kind, variant))\ncontent = pipeline.ingest.materialize(raw_bytes)\nrecords = pipeline.reader.read(content)\nitems   = pipeline.normalize.build(records)\n
        "},{"location":"50_pipeline_scaffold/#testing","title":"Testing","text":"

        Because stages are pure, test each stage in isolation and test the assembled root against fixture inputs whose expected outputs are stored as golden files. A parity test replays fixtures headlessly.

        "},{"location":"51_worker_and_progress/","title":"Worker & Progress","text":""},{"location":"51_worker_and_progress/#summary","title":"Summary","text":"

        Long-running work runs in a background worker. Jobs are durable documents that move through an explicit status machine. Progress is streamed to clients.

        "},{"location":"51_worker_and_progress/#the-status-machine","title":"The status machine","text":"
        pending -> processing -> completed\n                     \\-> failed    (retried up to N times)\n                     \\-> paused    (waiting for human input)\n
        • pending \u2014 queued, eligible for pickup.
        • processing \u2014 claimed by a worker.
        • paused \u2014 blocked on a human-in-the-loop question.
        • failed \u2014 error; retry_count increments until a max, then skipped.
        • completed \u2014 terminal success.
        "},{"location":"51_worker_and_progress/#the-poll-loop","title":"The poll loop","text":"
        async def poll(resources):\n    backoff = MIN_POLL\n    while True:\n        jobs = await job_svc.search(filter={\"status\": \"pending\"}, limit=100)\n        backoff = MIN_POLL if jobs else min(backoff * 2, MAX_POLL)\n        for job in jobs:\n            if (job.retry_count or 0) >= MAX_RETRIES:\n                continue\n            await job_svc.update_status(job.id, \"processing\")\n            try:\n                await process(job, resources)\n            except PauseForResolution:\n                await job_svc.update_status(job.id, \"paused\")\n            except Exception as e:\n                await job_svc.update_status(\n                    job.id, \"failed\", error=str(e),\n                    retry_count=(job.retry_count or 0) + 1,\n                )\n        await asyncio.sleep(backoff)\n

        Tunables live in environment variables: WORKER_POLL_MIN, WORKER_POLL_MAX, WORKER_MAX_RETRIES.

        "},{"location":"51_worker_and_progress/#progress-events","title":"Progress events","text":"

        A worker publishes structured progress events to a bus (a port). The HTTP edge exposes a streaming endpoint that replays events for a given job id.

        class ProgressEvent(BaseModel):\n    job_id: str\n    step: str\n    status: str            # started | progress | completed | skipped | paused\n    message: dict | None = None\n

        The bus is an in-memory adapter by default; because it is a port, it can be swapped for a durable broker. Emit from the orchestrator at each stage:

        await self.bus.publish(ProgressEvent(job_id=jid, step=\"normalize\",\n                                     status=\"completed\", message={\"count\": n}))\n
        "},{"location":"51_worker_and_progress/#streaming-endpoint","title":"Streaming endpoint","text":"
        async def stream_job_events(request, id):\n    bus = request.app.state.db_resources.get(\"progress_bus\")\n    if bus is None:\n        return {\"events\": []}\n\n    async def gen():\n        sent = 0\n        while True:\n            events = bus.get_events(id)\n            for e in events[sent:]:\n                yield f\"data: {e.model_dump_json(exclude_none=True)}\\n\\n\"\n                sent += 1\n            await asyncio.sleep(0.5)\n\n    return StreamingResponse(gen(), media_type=\"text/event-stream\")\n

        Known limitation. The default in-memory bus is per-process. If the worker and the API run as separate processes, events published by the worker are not visible to the API. For production, back the bus with a shared broker. The port boundary makes this a one-adapter change.

        "},{"location":"52_human_in_loop/","title":"Human-in-the-Loop","text":""},{"location":"52_human_in_loop/#summary","title":"Summary","text":"

        Some inputs are ambiguous and must be resolved by a human before processing can continue. The blueprint models this as a durable pause: an exception is raised, a question is recorded, the job pauses, and later resumes.

        "},{"location":"52_human_in_loop/#the-mechanism","title":"The mechanism","text":"
        1. During processing, a stage raises a domain exception carrying the context needed to ask the question:
        raise PauseForResolution(\n    job_id=jid,\n    reference=\"<stable key for this decision>\",\n    options=[...],\n    context={...},\n)\n
        1. The orchestrator catches it, records a question document, and re-raises so the worker marks the job paused.
        2. A client lists pending questions and answers one:
        GET  /jobs/{id}/questions            -> list pending questions\nPOST /questions/{qid}/resolve  {choice}  -> record the choice\n
        1. When the last pending question is resolved, the resolve endpoint flips the parent job back to pending.
        2. The worker picks it up again, rebuilds a resolution map from previously answered questions, and seeds it into the pipeline so the same decision is not asked twice.
        "},{"location":"52_human_in_loop/#the-question-document","title":"The question document","text":"
        class Question(BaseDocument):\n    job_id: str\n    reference: str            # stable key: stage|field|value\n    status: str               # pending | resolved\n    options: list[dict]\n    context: dict\n    chosen: dict | None = None\n    resolved_at: str | None = None\n
        "},{"location":"52_human_in_loop/#resume-map","title":"Resume map","text":"

        The worker turns answered questions into a lookup keyed by reference, then injects it into the pipeline so that stage can skip re-raising:

        resolved = {q.reference: q.chosen for q in await svc.search(\n    filter={\"job_id\": jid, \"status\": \"resolved\"})}\n\npipeline = build(root, instances={\"pause\": handler}, config={\"resolved\": resolved})\n
        "},{"location":"52_human_in_loop/#resolve-endpoint","title":"Resolve endpoint","text":"
        async def resolve_question(request, id, body):\n    svc = request.app.state.db_resources[\"question_svc\"]\n    q = await svc.read(id)\n    await svc.update(id, {\"chosen\": body[\"chosen\"], \"status\": \"resolved\",\n                          \"resolved_at\": now()})\n\n    pending = await svc.search(filter={\"job_id\": q.job_id, \"status\": \"pending\"},\n                               limit=1)\n    if not pending:\n        jobs = request.app.state.db_resources[\"job_svc\"]\n        job = await jobs.read(q.job_id)\n        if job and job.status == \"paused\":\n            await jobs.update_status(q.job_id, \"pending\")\n    return q\n
        "},{"location":"52_human_in_loop/#cli-parity","title":"CLI parity","text":"

        The same flow is available through scripts/CLI: list, get, create, questions, resolve, retry.

        "},{"location":"90_drone_pipelines/","title":"Drone Pipelines","text":""},{"location":"90_drone_pipelines/#summary","title":"Summary","text":"

        Every Aetos repository ships a Drone CI definition at .drone.yml. There is exactly one standard per repository, and there are two types of file, chosen by what the repository produces:

        Type File Produces Repos A \u2014 PyPI package templates/drone/python-lib.yaml A wheel + sdist on the private index dagpipe, doc-forge, hexa, mail-intake, mongo-ops, omniread, openapi-first, py-jwt B \u2014 Docker deployment templates/drone/service-docker.yaml An image pushed to the registry and run as a container auth-server

        Both templates run on platform: linux / arm64 with the workspace at /drone/src. Copy the matching template to <repo>/.drone.yml; the Type A file needs no edits, the Type B file needs its placeholders filled in (below).

        Conventions: .drone.yml (not .yaml), one file per repo, secrets injected with from_secret \u2014 never commit credentials.

        "},{"location":"90_drone_pipelines/#type-a-pypi-package-python-libyaml","title":"Type A \u2014 PyPI package (python-lib.yaml)","text":"

        For internal libraries. The file contains two pipelines:

        1. build-and-publish-pypi \u2014 triggered on tag:
        2. check-version \u2014 guard: fail unless $DRONE_TAG equals the version in pyproject.toml; then read name / version and query $PIP_REPO_URL/simple/<package>/; if that version already exists, exit 78 and skip the whole build (see 91 \u2013 Versioning & Changelog).
        3. quality-gate \u2014 install the package with its [dev] extras from the private index, then black --check, ruff check, mypy, pydoclint, pytest.
        4. build-package \u2014 python -m build into dist/.
        5. upload-to-private-pypi \u2014 twine upload to $PIP_REPO_URL.
        6. backfill-pypi-from-tags \u2014 triggered on custom:
        7. fetch-tags \u2014 git fetch --tags --force.
        8. build-and-upload-missing \u2014 walk every tag in version order, skip the ones already on the index, git checkout the rest, verify tag == pyproject version at that commit, build, and upload. This is the disaster-recovery / replay path.

        Secrets: PIP_REPO_URL, PIP_USERNAME, PIP_PASSWORD.

        • Ship as-is. Package name and version come from pyproject.toml, so the same file is reused verbatim across every library.
        "},{"location":"90_drone_pipelines/#type-b-docker-deployment-service-dockeryaml","title":"Type B \u2014 Docker deployment (service-docker.yaml)","text":"

        For a service that ships a container image \u2014 a long-running API/worker, e.g. auth-server. The file contains one pipeline, build-and-deploy-service, triggered on tag:

        • fetch-tags \u2014 resolve the latest tag into LATEST_TAG.txt; fail if there are no tags.
        • check-version \u2014 guard: fail unless $DRONE_TAG equals the repo-root VERSION file (see 91 \u2013 Versioning & Changelog).
        • check-remote-image \u2014 if aetos/<app>:<tag> already exists locally, exit 78 and skip the build.
        • quality-gate \u2014 install from requirements.txt and run black / ruff / mypy / pytest.
        • build-image \u2014 docker build with the private-index build args, tagged aetos/<app>:<tag> and :latest.
        • push-image \u2014 login, re-tag with $REGISTRY_HOST, push both tags.
        • stop-old \u2014 docker rm -f <app>.
        • run-container \u2014 docker run -d --name <app> -p <host>:<container> --restart always with the service's -e environment.

        Secrets: PIP_REPO_URL, PIP_USERNAME, PIP_PASSWORD (service build args), REGISTRY_HOST, REGISTRY_USER, REGISTRY_PASS, plus the service runtime env (for example MONGO_*, JWT_SECRET).

        Placeholders to fill in per repo:

        Placeholder Meaning Example <app> service image / container name auth-server aetos/<app> image repository on the registry aetos/auth-server <host-port> / <container-port> published : in-image port 9003:8000 <ENV_VAR> runtime environment variable MONGO_HOST"},{"location":"90_drone_pipelines/#what-not-to-do","title":"What not to do","text":"
        • Do not hand-roll a third shape. A repo is either Type A or Type B, never both.
        • Do not inline secrets; always use from_secret.
        • Do not drop the check-version / check-remote-image skip \u2014 it guards the index and the running container against duplicate publishes.
        • Do not drop the tag\u2194version guard. A package needs its pyproject.toml version to equal the tag; a service needs a root VERSION file that equals the tag. See 91 \u2013 Versioning & Changelog.
        • Do not rename the pipelines; tooling and runbooks key off build-and-publish-pypi and build-and-deploy-service.
        "},{"location":"90_drone_pipelines/#related","title":"Related","text":"
        • 01 \u2013 Build Recipe \u00b7 30 \u2013 Infra Adapters \u00b7 91 \u2013 Versioning & Changelog \u00b7 93 \u2013 Library Registry
        "},{"location":"91_versioning_and_changelog/","title":"Versioning & Changelog","text":""},{"location":"91_versioning_and_changelog/#summary","title":"Summary","text":"

        Every Aetos artifact \u2014 library or service \u2014 is versioned with Semantic Versioning and documents its releases in a Keep a Changelog file. The version file is the source of truth, the git tag must equal it, and a Drone guard enforces that equality before anything is published. Releases are cut manually; a tag is what triggers the pipeline.

        This page pairs with 90 \u2013 Drone Pipelines: the version and tag contract is exactly what those two CI shapes consume.

        "},{"location":"91_versioning_and_changelog/#the-version-contract","title":"The version contract","text":"Artifact Source of truth Notes Library (PyPI package) version in pyproject.toml check-version also reads it to skip duplicates Service (Docker) VERSION file at the repo root one line, x.y.z; the service reads it (build-arg) \u2014 never hardcode the version

        Rules:

        1. One version per repository. No per-module versions.
        2. Tag = version. The git tag is bare SemVer (0.0.6), no v prefix, and it MUST match the version file byte-for-byte. The Drone guard fails the build otherwise \u2014 this is what stops a tag from silently publishing nothing.
        3. A release is a tag, created after the change is merged. The version bump and the changelog promotion travel inside the merge request (MR); the tag is added on the merged commit and pushed. See Tagging strategy.
        4. Never reuse a tag. If a release is wrong, cut a new patch version.
        "},{"location":"91_versioning_and_changelog/#pre-10-0yz","title":"Pre-1.0 (0.y.z)","text":"

        While a package is 0.y.z, 0.y is treated as the major line:

        • breaking change \u2192 0.(y+1).0
        • new feature \u2192 0.y.(z+1)
        • bug fix \u2192 0.y.(z+1)

        Once a package reaches 1.0.0, normal SemVer applies. Do not ship 1.0.0 until the public API is considered stable.

        "},{"location":"91_versioning_and_changelog/#the-changelog","title":"The changelog","text":"

        CHANGELOG.md at the repo root, in Keep a Changelog form. It always has exactly one open [Unreleased] section with the change categories that apply:

        ## [Unreleased]\n\n### Added\n### Changed\n### Deprecated\n### Removed\n### Fixed\n### Security\n

        On release you promote it \u2014 never delete history:

        ## [0.0.6] - 2026-03-07\n\n### Added\n- ...\n

        and add a link reference at the bottom:

        [Unreleased]: https://git.aetoskia.com/aetos/<repo>/compare/0.0.6...HEAD\n[0.0.6]: https://git.aetoskia.com/aetos/<repo>/compare/0.0.5...0.0.6\n

        Conventions:

        • Write entries for humans: one line each, imperative, referencing the user impact, not the commit hash.
        • Categories: Added, Changed, Deprecated, Removed, Fixed, Security. Omit empty categories.
        • Security fixes get their own entry even if the change is otherwise a bug fix.
        • Keep [Unreleased] current: add an entry in the same change that introduces the behaviour, not later.
        • The [Unreleased] heading is never renamed; copy its content into the new version heading and clear it.
        "},{"location":"91_versioning_and_changelog/#reconcile-before-releasing","title":"Reconcile before releasing","text":"

        [Unreleased] is a draft, not the source of truth. It is only trustworthy when it was maintained alongside each change; a long-running branch or a change that skipped the changelog leaves it stale, so it can silently under-report a release. Verify it against the change before you promote:

        1. List what actually changed since the last release: git log <last-tag>..HEAD and git diff --stat <last-tag>..HEAD.
        2. Compare that against [Unreleased]; add an entry for every user-facing change that is missing.
        3. Always show the proposed additions to the user and wait for approval before promoting. If an entry is ambiguous, ask rather than guess.

        Only then promote. Never cut a release with a known gap between the diff and the changelog.

        "},{"location":"91_versioning_and_changelog/#tagging-strategy-mr-based","title":"Tagging strategy (MR-based)","text":"

        The release version is known while the change is still a merge request, so the bump travels with the change and only the tag is added afterwards:

        1. In the MR \u2014 reconcile [Unreleased] against the change (see Reconcile before releasing) and get the user's approval for any additions. Then set the intended release version: version in pyproject.toml (or the VERSION file) to x.y.z, and promote the changelog (below). Changelog entries and link references name the version/tag, never a commit id.
        2. Merge or squash the MR into main.
        3. Create the tag x.y.z on the resulting commit (the merge/squash commit).
        4. Push the tag (git push origin x.y.z) \u2014 Drone builds the release.

        Because the version bump is inside the tagged commit, the guard's tag == version check can only fail if the wrong commit was tagged.

        "},{"location":"91_versioning_and_changelog/#agent-assisted-tagging","title":"Agent-assisted tagging","text":"

        The agent neither authors nor merges the MR, and never tags before the merge. After the user confirms the MR is merged/squashed and says to proceed:

        1. Wait for that explicit go-ahead.
        2. Find the commit that introduced the version bump:
        3. packages: git log -S 'version = \"x.y.z\"' -n 1 --format='%H %s' -- pyproject.toml
        4. services: git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION
        5. Confirm that commit's version file equals x.y.z, then tag only that commit, lightweight and bare: git tag x.y.z <sha>.
        6. Do not push. Ask the user to push the tag: git push origin x.y.z.
        "},{"location":"91_versioning_and_changelog/#release-checklist","title":"Release checklist","text":"
        1. Confirm the quality gate is green and main is up to date.
        2. In the MR: reconcile [Unreleased] against the change being released \u2014 git log <last-tag>..HEAD and git diff --stat <last-tag>..HEAD \u2014 add any missing user-facing entries, and get the user's approval for the additions. Then move every [Unreleased] entry under the new version heading with the target date (## [x.y.z] - YYYY-MM-DD) and restore an empty [Unreleased] on top.
        3. In the MR: add the two compare-link references at the bottom of the changelog, naming the version/tag (never a commit id).
        4. In the MR: set the version file \u2014 pyproject.toml (version = \"x.y.z\") or VERSION \u2014 to the intended release version.
        5. Merge or squash the MR into main.
        6. Create the tag on the resulting commit: lightweight git tag x.y.z.
        7. Push the tag (git push origin x.y.z). Watch Drone: Type A publishes the wheel/sdist, Type B builds and deploys the image; both first assert tag == version.
        8. Do not reuse the tag if the run fails \u2014 fix and cut x.y.(z+1).
        "},{"location":"91_versioning_and_changelog/#why-the-guard-matters","title":"Why the guard matters","text":"

        The version file and the tag are two facts that must agree; nothing in git enforces that by itself. A mismatch is not a theoretical risk \u2014 a package can be tagged 0.0.2 while its pyproject.toml still says 0.0.1, and the publish step (which compares the file against the index) then skips the build entirely, so 0.0.2 never reaches the index while looking like a release. The Drone guard turns that silent no-op into a hard failure.

        "},{"location":"91_versioning_and_changelog/#related","title":"Related","text":"
        • 90 \u2013 Drone Pipelines \u00b7 94 \u2013 Repository Inventory \u00b7 01 \u2013 Build Recipe \u00b7 93 \u2013 Library Registry
        "},{"location":"92_genericity_matrix/","title":"Genericity Matrix","text":""},{"location":"92_genericity_matrix/#summary","title":"Summary","text":"

        This page states precisely what is library-backed, what is template-provided, and what is app-specific and must be authored. Use it to scope a new build and to know, for any given capability, whether to call a library, copy template code, or write it yourself.

        "},{"location":"92_genericity_matrix/#tier-a-library-backed-use-never-reimplement","title":"Tier A \u2014 Library-backed (use; never reimplement)","text":"

        These capabilities already exist as internal libraries. Reach them through the library registry MCP (find_library(capability)) and read the library's own MCP for its API. Writing a private copy of any of these is a defect.

        Capability Library MCP Persistence: repositories, cache, populate, transactions Mongo Ops (mongo_ops) :8007 Dependency injection / composition Hexa (hexa) :8008 Deterministic multi-step transformation engine DAG Pipe (dagpipe) :8006 Spec-first HTTP edge, client, codegen OpenAPI First (openapi_first) :8004 Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) Omniread (omniread) :8003 Read-only email ingestion Mail Intake (mail_intake) :8002 JWT auth primitives (register, login, introspect) Py JWT (jwtlib) :8005 Documentation build (MkDocs + MCP) Doc Forge (docforge) :8001"},{"location":"92_genericity_matrix/#tier-b-template-provided-copy-from-templatesapp-then-adapt","title":"Tier B \u2014 Template-provided (copy from templates/app, then adapt)","text":"

        These are reusable internal components shipped inside the template \u2014 they are not independent libraries. Copy them as-is, then rename/populate only what is app-specific. They give every app the same wiring shape as the reference app. Fetch them by kind with get_app_component, or the whole tree with get_app_template.

        Component Template location Action Shipped Layering & dependency rule the package layout + import rules keep \u2705 Composition root shape init.py (get_svc/get_db, idempotency) keep \u2705 Spec-first web edge interfaces/openapi.py, thin handlers bound to operationId keep \u2705 CRUD slice pattern domain/<resource>/{models.py, ports/db.py, ports/service.py, converters.py} rename + fill \u2705 Generic CRUD service infra/adapters/service.py (CrudsServiceAdaptor) keep \u2705 Repository factory infra/db/repos/mongo.py (_repo_factory) keep \u2705 Worker poll + status loop worker.py keep \u2705 Progress bus infra/adapters/sse.py (keyed in-memory bus) + an app SSE endpoint keep \u2705 HTTP response cache infra/http_cache.py (cache_response + generation invalidation) keep \u2705 Key-value store infra/adapters/kv.py (port + in-memory + Redis adaptor) keep \u2705 Pipeline scaffold pipelines/shared/{ports,loader,registry}.py + pipelines/<family>/ rename + fill \u2705 Operator scripts scripts/ (init() / get_svc() / shutdown()) rename \u2705 Testing harness integration fakes + fixture-parity pattern keep \u2705 Project scaffolding pyproject.toml, Dockerfile, docker-compose.yaml, .env.example, openapi.yaml rename + fill \u2705"},{"location":"92_genericity_matrix/#tier-b-patterns-port-from-the-reference-app","title":"Tier B (patterns) \u2014 port from the reference app","text":"

        A few Tier B capabilities are real and reusable, but are shaped by the app or the provider, so the template does not ship them verbatim \u2014 copying them blindly would carry app-specific names. Treat them as patterns: lift the shape from the reference app and rename per app.

        Component Reference location Action Shipped Human-in-the-loop durable pause + question document + resolve endpoint + resume map port + reshape \u2717 LLM client pool provider-select + retry/rotation pool scaffold port + reshape \u2717"},{"location":"92_genericity_matrix/#tier-c-app-specific-must-be-authored","title":"Tier C \u2014 App-specific (must be authored)","text":"Artifact Why Resource models the business shape Repository populate/cache rules the relationships Service business logic domain behaviour Pipeline families the transformation graph Pattern/rule resources data-driven policy Fixtures & golden outputs test data"},{"location":"92_genericity_matrix/#the-two-axes","title":"The two axes","text":"

        Everything app-specific reduces to two axes:

        1. Resource model \u2014 the set of resources, their fields, relationships, and the OpenAPI contract.
        2. Pipeline family \u2014 only if inputs require multi-step transformation.

        If you can specify those two axes, the rest of the app follows mechanically: Tier A is imported, Tier B is copied, and Tier C is the only thing you author.

        "},{"location":"93_library_registry/","title":"Library Registry","text":""},{"location":"93_library_registry/#summary","title":"Summary","text":"

        The Aetos ecosystem provides internal libraries for the shared concerns of every application. Use them. Writing a private copy of any capability below is a defect.

        Each library also exposes its own documentation as an MCP server. An AI agent can read a library's full API by connecting to its MCP and reading docs://index, docs://nav, and docs://modules/{module}.

        "},{"location":"93_library_registry/#catalog","title":"Catalog","text":"Library Import Purpose Use instead of MCP DAG Pipe dagpipe Deterministic state-transformation DAG engine hand-rolled orchestration/topological ordering :8006 Hexa hexa Declarative DI / composition-root tooling manual wiring, hand-written factories :8008 Mongo Ops mongo_ops Async MongoDB repositories, cache, populate, transactions raw Motor CRUD and connection lifecycle :8007 Omniread omniread Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) custom scrapers/parsers :8003 OpenAPI First openapi_first Spec-first FastAPI bootstrap, client, codegen decorator routers and hand-written clients :8004 Mail Intake mail_intake Provider-agnostic read-only email ingestion Gmail OAuth + MIME parsing :8002 Py JWT jwtlib JWT auth primitives (register/login/introspect) password hashing + token code :8005 Doc Forge docforge Docstring compiler \u2192 MkDocs + MCP docs custom doc generators :8001 Doc Weaver doc-weaver JSDoc compiler \u2192 TypeDoc + MCP docs (React/TS) custom TypeScript doc generators :8010 React Auth react-auth JWT-backed React auth UI: provider, login page, profile screens, bearer axios client hand-rolled auth contexts and token handling in React apps :8011 React OpenAPI react-openapi Spec-driven React admin UI (CRUD, tables, forms, SSE) derived from an OpenAPI document per-resource hand-written admin screens :8012 Auth Server (service) Central identity service (register/login/me/logout/introspect) building auth endpoints yourself spec: docs://spec"},{"location":"93_library_registry/#how-to-choose","title":"How to choose","text":"You need to\u2026 Use persist and query documents Mongo Ops compose dependencies Hexa run a multi-step transformation DAG Pipe read/parse an arbitrary input format Omniread expose a contract-first HTTP API OpenAPI First ingest email Mail Intake authenticate users / verify tokens Py JWT (+ Auth Server) generate documentation Doc Forge generate React/TypeScript documentation Doc Weaver authenticate a React front-end React Auth (+ Auth Server) build a React admin UI from an OpenAPI spec React OpenAPI"},{"location":"93_library_registry/#discovery","title":"Discovery","text":"

        A single standards MCP exposes find_library(capability), which returns the matching library, its import name, its \"use instead of\" guidance, and its MCP endpoint (or, for the auth-server service, a spec pointer). It also serves the pinned auth-server OpenAPI contract at docs://spec. Query it before writing any infrastructure.

        "},{"location":"93_library_registry/#notes","title":"Notes","text":"
        • Hexa is a full library with its own MCP server on :8008: read docs://index, docs://nav, and docs://modules/{module} (e.g. docs://modules/hexa.container) to discover the DI surface \u2014 build(cls, *, instances, config) and the PortNode model.
        • Auth Server is a service, not an importable library: it has no MCP bundle by design. Read its client contract from the pinned OpenAPI document via docs://spec and wire it by declaring a bearerAuth security scheme in the app's own spec (see Auth Integration); py-jwt covers the low-level token path.
        • Doc Weaver is the TypeScript counterpart to Doc Forge: it reads JSDoc comments and emits a TypeDoc site plus the same doc-forge-shaped MCP bundle for React packages. Its convention is RDFC (the React Doc-forge Convention), the JSDoc parallel to GSDFC.
        • React Auth and React OpenAPI are front-end libraries (TypeScript, React 18 + MUI + React Router peers), not Python services \u2014 they consume the Auth Server and an OpenAPI document rather than serving one. Each ships a wiki, a TypeDoc site and an MCP bundle like every other library above.
        • Library MCP servers expose documentation resources (not executable tools): they tell an agent the available API surface so it does not invent code.
        "},{"location":"94_repository_inventory/","title":"Repository Inventory","text":""},{"location":"94_repository_inventory/#summary","title":"Summary","text":"

        The canonical list of Aetos repositories covered by the CI and versioning standards, with the artifact each one produces, its version source, and its Drone shape. Every entry maps to the contract in 91 \u2013 Versioning & Changelog and the two CI files in 90 \u2013 Drone Pipelines.

        The same data is published machine-readably as the registry://repos MCP resource (and the list_repos tool), sourced from standards/src/repos.json. Paths are relative to the aetos/ workspace root.

        "},{"location":"94_repository_inventory/#packages-type-a","title":"Packages (Type A)","text":"

        A wheel + sdist published to the private index. Version source is pyproject.toml; Drone file is python-lib.yaml (tag-triggered).

        Repo Path Docs MCP server dagpipe dagpipe lib, wiki dagpipe:8006 doc-forge doc-forge lib, wiki docforge:8001 hexa hexa lib, wiki hexa:8008 mail-intake mail-intake lib, wiki mail_intake:8002 mongo-ops mongo-ops lib, wiki mongo_ops:8007 omniread omniread lib, wiki omniread:8003 openapi-first openapi-first lib, wiki openapi_first:8004 py-jwt py-jwt lib, wiki jwtlib:8005"},{"location":"94_repository_inventory/#services-type-b","title":"Services (Type B)","text":"

        A container image pushed to the registry and run on the Docker host. Version source is the VERSION file; Drone file is service-docker.yaml.

        Repo Path Trigger Docs auth-server auth-server tag api, lib, wiki

        Tag-triggered and enforces tag == VERSION.

        "},{"location":"94_repository_inventory/#required-files-per-repo","title":"Required files per repo","text":"Type Version source Changelog Drone package pyproject.toml CHANGELOG.md python-lib.yaml service VERSION CHANGELOG.md service-docker.yaml

        Every covered repository must be able to satisfy tag == version: the version file (never a commit id) is bumped in the release MR, the MR is merged, and the tag is created on the merged commit.

        "},{"location":"94_repository_inventory/#reading-this-at-runtime","title":"Reading this at runtime","text":"
        • Resource: registry://repos
        • Tool: list_repos()
        • Humans: this page (mirror of standards/src/repos.json).
        "},{"location":"94_repository_inventory/#related","title":"Related","text":"
        • 90 \u2013 Drone Pipelines \u00b7 91 \u2013 Versioning & Changelog \u00b7 93 \u2013 Library Registry
        "}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Standards Reference","text":"

        The reference half of the Standards description: the enforceable rules, patterns, and the internal library catalog that agents consult while coding.

        The reference is organized as an anatomy \u2014 one entry checklist and four pillars describing what an application is made of, plus delivery/meta pages and an optional pipelines layer.

        "},{"location":"#anatomy","title":"Anatomy","text":"
        • Build Recipe \u2014 the ordered, agentic checklist for a new app; the entry point that walks the whole anatomy.
        "},{"location":"#pillar-1-domains","title":"Pillar 1 \u2014 Domains","text":"
        • Layering Rules \u2014 the strict request \u2192 domain \u2192 repository layering and the rules that enforce it.
        "},{"location":"#pillar-2-openapi-spec-the-contract","title":"Pillar 2 \u2014 OpenAPI Spec (the contract)","text":"
        • Composition Root \u2014 a single composition point wiring the whole app.
        • Spec-First Routing \u2014 the OpenAPI contract as the routing source of truth.
        • CRUD Template \u2014 the standardized generic resource endpoint scaffold.
        • Auth Integration \u2014 consuming the shared auth-server service (spec-driven, no auth code).
        "},{"location":"#pillar-3-interfaces-infra","title":"Pillar 3 \u2014 Interfaces & Infra","text":"
        • Infra Adapters \u2014 how infrastructure connects without leaking into domain.
        "},{"location":"#pillar-4-ui","title":"Pillar 4 \u2014 UI","text":"
        • UI: Auto-Rendered Admin & Custom Pages \u2014 the @aetoskia/react-openapi admin rendered from the spec's x- extensions, and @aetoskia/react-auth for auth pages; the client template scaffold.
        "},{"location":"#pipelines-optional-layer","title":"Pipelines (optional layer)","text":"
        • Pipeline Scaffold \u2014 the deterministic pipeline skeleton for multi-stage jobs.
        • Worker & Progress \u2014 queued work, progress reporting, and visibility.
        • Human-in-the-Loop \u2014 guardrails and approvals inside automations.
        "},{"location":"#delivery-meta","title":"Delivery & Meta","text":"
        • Drone Pipelines \u2014 the three CI shapes: a PyPI package, an npm package, or a Docker deployment.
        • Versioning & Changelog \u2014 SemVer, the tag\u2194version contract, and the release changelog.
        • Repository Inventory \u2014 every covered repo, its type, version source, and Drone shape.
        • Genericity Matrix \u2014 what is library-backed, template-provided, or authored.
        • Library Registry \u2014 the catalog of internal libraries behind all of it.

        Read the Wiki for the philosophy and rationale; these pages are the reference that mirrors the standards MCP bundle.

        "},{"location":"01_build_recipe/","title":"Build Recipe","text":""},{"location":"01_build_recipe/#summary","title":"Summary","text":"

        The ordered, deterministic checklist for generating a new application of the standard shape. Every step is fixed; only the resource model (step 2), the codegen pass (step 3), and the pipeline family (step 8) need app-specific work.

        The reference pages behind this recipe are organized as an anatomy: the domains layer, the OpenAPI contract that drives routing and the admin UI, the interfaces/infra seam, the auto-rendered UI client, and an optional pipelines layer \u2014 see the Standards Reference index.

        This page is served by the standards MCP as docs://modules/build_recipe. The start_app prompt on that server collects the two axes and hands off here; pull exact files with get_app_component.

        "},{"location":"01_build_recipe/#bootstrap","title":"\ud83d\ude80 Bootstrap","text":"

        From the standards docs checkout:

        cp -r <docs>/standards/src/templates/app apps/<your-app>\ncd apps/<your-app>\n

        Pair it with the React client template when a UI is needed (auto-rendered admin from the spec \u2014 see 40 \u2013 UI):

        cp -r <docs>/standards/src/templates/client apps/<your-app>-client\ncd apps/<your-app>-client && npm install\n

        Install the internal libraries \u2014 editable local checkouts (preferred in development) or the private index (CI / fresh machines). Credentials are environment-only; never commit them.

        # local checkouts\npip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa \\\n            -e ../aetos/dagpipe -e ../aetos/doc-forge\n# private index\npip install --extra-index-url \\\n  \"https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple\" .\n
        "},{"location":"01_build_recipe/#agent-prompt-copyable","title":"\ud83d\udccb Agent prompt (copyable)","text":"
        # Build a new application from the Aetos Standards blueprint\n\nYou are coding a complete new backend application conforming to the Aetos\nstandard app blueprint. Execute every step in order. Only steps 2\u20134 use the\napp-specific details provided by the user; everything else is deterministic.\n\n## Before writing any code\n\nConnect to the `standards` MCP server and read:\n- `docs://nav` (the module list)\n- `docs://modules/genericity_matrix` (Tier A library / Tier B template / Tier C authored)\n- `docs://modules/layering_rules` (the dependency rules)\n\nThen:\n- call `find_library` with `db`, `di`, `routing`, `ingestion`, `pipeline`, `docs`\n  and note the Tier A libraries that already exist \u2014 never reimplement one;\n- call `list_app_components()` and pull each file you need with\n  `get_app_component(kind, resource=..., family=...)` instead of writing it from\n  scratch.\n\n## Steps\n\n1. **Scaffold** \u2014 copy `standards/src/templates/app/` into `apps/<your-app>/`\n   (or pull the same tree via `get_app_template`). Keep the tree: `domain/`,\n   `infra/`, `interfaces/`, `pipelines/`, `tests/`, `scripts/`, plus\n   `pyproject.toml`, `openapi.yaml`, `config.py`, `init.py`, `main.py`,\n   `worker.py`, `Dockerfile`, `docker-compose.yaml`, `.env.example`.\n\n2. **Author the spec (app-specific)** \u2014 write `openapi.yaml`: resources,\n   schemas, `operationId`s, security, and extension metadata. This is the\n   contract and drives all routing. Every operation MUST have an `operationId`.\n\n3. **Generate the scaffold (codegen)** \u2014 from the spec, generate the wire\n   models and the exact handler signatures:\n   ```bash\n   openapi-first models openapi.yaml -o _gen/models.py\n   openapi-first routes openapi.yaml -o _gen/routes \\\n     --use-models --models-module _gen.models --inject-request --package --template-style\n   ```\n   `_gen/models.py` is the **wire contract** (Pydantic, one class per\n   `components.schemas` entry). `_gen/routes/<resource>/routes.py` lists every\n   `operationId` with its exact parameter signature. `--template-style` makes\n   those stubs `async def` with a `body` parameter, matching the handlers you\n   keep in `interfaces/` (without it they are sync `def` stubs taking\n   `payload`; both bind the same way). Treat `_gen/` as generated\n   (never hand-edit it) \u2014 the canonical handlers live in `interfaces/`.\n\n4. **Write each CRUD slice (app-specific)** \u2014 per resource create the four-file\n   slice: `models.py` (domain model, **no `id`**), `ports/db.py`\n   (`class XDocument(BaseDocument, X)` \u2014 id comes from `BaseDocument`),\n   `ports/service.py`, and optional `converters.py`. Follow the CRUD template.\n\n5. **Wire the composition root** \u2014 in `init.py`, build leaf repositories, then\n   dependent repositories, then services; add infra adapters (db, cache, stores,\n   progress bus, fetchers). Expose `get_svc` overloads.\n\n6. **Add routes** \u2014 create `interfaces/<resource>/routes.py` thin handlers whose\n   names match the `operationId`s (use the signatures from step 3 as your\n   checklist) and re-export them in `interfaces/openapi.py`. Add the cache\n   decorator to read endpoints.\n\n7. **Bootstrap app and worker** \u2014 confirm `main.py` runs the OpenAPI-first app\n   with its lifespan. If the app has long-running jobs, adapt `worker.py` to poll\n   the job collection, run the pipeline, and publish progress.\n\n8. **Add pipeline families (only if data-driven)** \u2014 copy `pipelines/example/`\n   to `pipelines/<family>/` with `abc.py`, `impl.py`, `pipeline.yaml`,\n   `resources/`, and reuse `pipelines/shared/` (loader + registry). Register the\n   root. Add fixtures and a parity test.\n\n9. **Add infrastructure only where needed** \u2014 Tier A capability: use the\n   library. Tier B capability: copy the template. Never hand-write a Tier A\n   library.\n\n10. **Tests** \u2014 integration tests with fakes at the HTTP edge; unit tests for\n    domain and pipeline logic; a config-consistency test for rule-driven\n    pipelines. Include `tests/integration/test_openapi_app_builds.py` (imports\n    the app, asserts `import main` binds every operation).\n\n11. **Scripts and seeds** \u2014 operator scripts under `scripts/` using\n    `init()` / `get_svc()` / `shutdown()`; run as `python -m scripts.<name>`.\n\n12. **Docs** \u2014 author GSDFC docstrings, generate `.pyi` stubs, mark the package\n    `py.typed`, and build the docs.\n\n**Definition of done:**\n- `python -c \"import main\"` succeeds.\n- `pytest` passes.\n- The app serves every operation in the spec; the worker drains its queue.\n- No domain module imports a web framework.\n- No Tier A library was reimplemented.\n
        "},{"location":"01_build_recipe/#where-the-steps-land","title":"\ud83e\udded Where the steps land","text":"

        The steps map onto the layers as follows:

        Step Package / file Depends on 1 \u00b7 Scaffold whole templates/app/ \u2014 2 \u00b7 Spec openapi.yaml \u2014 3 \u00b7 Codegen _gen/ (generated) spec, openapi-first 4 \u00b7 CRUD slices domain/<resource>/ spec, CRUD template 5 \u00b7 Wiring init.py every slice 6 \u00b7 Routes interfaces/<resource>/ services, openapi route registry 7 \u00b7 Bootstrap main.py, worker.py composition root 8 \u00b7 Pipelines pipelines/<family>/, shared/ library pipeline engine 9 \u00b7 Infra infra/ domain ports 10 \u00b7 Tests tests/ app + fixtures 11 \u00b7 Scripts scripts/ composition root 12 \u00b7 Docs docstrings + docs build code, Doc Forge"},{"location":"01_build_recipe/#the-codegen-fast-path-in-detail","title":"\ud83d\udd27 The codegen fast path, in detail","text":"

        openapi-first is spec \u2192 code only (it never generates a spec). Use it to erase the two mechanical parts of the build:

        Generated artifact Replaces Notes _gen/models.py hand-writing Pydantic wire models one class per components.schemas entry _gen/routes/<resource>/routes.py hand-typing handler signatures names == operationIds; request: Request injected

        Rules of the road:

        • Wire models are not domain models. _gen/models.py is the HTTP contract; domain/<resource>/models.py is your business shape. If the spec's schema has a required id: str, keep it off the domain model and let the document get its id from BaseDocument.
        • Use --template-style. Stubs are then async def ...(request, body: ...) matching interfaces/; without it they are sync def ...(payload: ...). Either binds (the router introspects the signature), but --template-style keeps the scaffold consistent with the code you keep.
        • Resource names are sanitized. /fetch-requests \u2192 fetch_requests.py.
        • Multipart bodies expand to UploadFile = File(...) / Form(...) params.
        • _gen/ is disposable. Regenerate on every spec change; git diff shows exactly what moved.
        "},{"location":"01_build_recipe/#definition-of-done","title":"\u26a0\ufe0f Definition of done","text":"
        • python -c \"import main\" succeeds.
        • pytest passes.
        • The app serves the spec's operations; the worker drains its queue.
        • No domain module imports a web framework.
        • No Tier A library was reimplemented.
        "},{"location":"01_build_recipe/#related","title":"Related","text":"
        • 10 \u2013 Layering Rules \u00b7 21 \u2013 CRUD Template \u00b7 22 \u2013 Auth Integration \u00b7 40 \u2013 UI \u00b7 50 \u2013 Pipeline Scaffold \u00b7 92 \u2013 Genericity Matrix
        "},{"location":"02_composition_root/","title":"Composition Root","text":""},{"location":"02_composition_root/#summary","title":"Summary","text":"

        All wiring happens in exactly one module. It builds a flat resource registry and exposes it to the HTTP layer and to scripts.

        "},{"location":"02_composition_root/#the-resource-registry","title":"The resource registry","text":"

        init.py returns a plain dict[str, Any]. Keys follow two conventions:

        • <resource>_repo \u2014 a repository adapter for a resource.
        • <resource>_svc \u2014 a service for a resource.

        Plus named infrastructure adaptors:

        • http_cache_store \u2014 response cache backend.
        • progress_bus \u2014 progress/event bus.
        • <vendor>_<kind> \u2014 fetchers, clients, stores.

        The API stores the dict on app.state.db_resources during lifespan startup. Handlers read from it; nothing imports concrete adapters.

        "},{"location":"02_composition_root/#shape","title":"Shape","text":"
        _resources: dict = {}\n_initialized = False\n\nasync def init(settings=None) -> dict:\n    global _initialized\n    if _initialized:\n        return _resources\n\n    await setup_database(uri=settings.mongo_uri, db_name=settings.mongo_db)\n\n    # 1. leaf repositories\n    user_repo = create_user_repo()\n\n    # 2. dependent repositories (dependencies passed by keyword)\n    wallet_repo = create_wallet_repo(user_repo=user_repo)\n\n    # 3. services (build via the DI library, injecting the repo)\n    _resources[\"user_repo\"]   = user_repo\n    _resources[\"wallet_repo\"] = wallet_repo\n    _resources[\"user_svc\"]    = get_user_service(user_repo)\n    _resources[\"wallet_svc\"]  = get_wallet_service(wallet_repo)\n\n    # 4. infrastructure adaptors (optional)\n    _resources[\"http_cache_store\"] = HttpCacheStore(...)\n    _resources[\"progress_bus\"]     = ProgressEventBus()\n\n    _initialized = True\n    return _resources\n\nasync def shutdown() -> None:\n    global _initialized\n    await close_stores(_resources)\n    await shutdown_database()\n    _resources.clear()\n    _initialized = False\n
        "},{"location":"02_composition_root/#typed-accessors","title":"Typed accessors","text":"

        Expose a get_svc(name) helper with one @overload per key so scripts get typing without importing concrete classes:

        @overload\ndef get_svc(name: Literal[\"user_svc\"]) -> UserService: ...\n@overload\ndef get_svc(name: Literal[\"wallet_svc\"]) -> WalletService: ...\n\ndef get_svc(name: str):\n    return _resources[name]\n

        Also expose get_db() (raw database handle) and pure helpers such as compute_fingerprint(payload) (canonical hash used for deduplication).

        "},{"location":"02_composition_root/#rules","title":"Rules","text":"
        • init() is idempotent.
        • The composition root is the only place that imports concrete adapters.
        • Handlers never call init(); they read request.app.state.db_resources.
        • Scripts call init() / shutdown() around their work.
        "},{"location":"10_layering_rules/","title":"Layering Rules","text":""},{"location":"10_layering_rules/#summary","title":"Summary","text":"

        The dependency direction is fixed. Violating it is a design defect.

        "},{"location":"10_layering_rules/#allowed-imports","title":"Allowed imports","text":"
        interfaces/*      ->  domain/*            (services, ports, models)\ninterfaces/*      ->  infra/adapters/*    (only read-only value objects)\ndomain/*          ->  domain/*            (same layer)\ndomain/*          ->  pipelines/*         (call a pipeline via a port)\ndomain/*/ports/*  ->  infra/*             (bind adapters + libraries at the seam)\ninfra/adapters/*  ->  domain/ports/*      (implement the interface)\nmain.py/init.py   ->  everything          (composition root only)\n
        "},{"location":"10_layering_rules/#forbidden-imports","title":"Forbidden imports","text":"
        domain/*          ->  interfaces/*        (never)\ndomain/*          ->  fastapi/starlette   (never)\ninfra/adapters/*  ->  interfaces/*        (never)\ninterfaces/*      ->  infra/db/*          (state lives in resources, not imports)\n
        "},{"location":"10_layering_rules/#why","title":"Why","text":"
        • The business logic is testable without a server or an event loop.
        • Adapters can be swapped (in-memory fake, real database) without touching business logic.
        • The HTTP edge stays thin and replaceable.
        "},{"location":"10_layering_rules/#the-portadapter-contract","title":"The port/adapter contract","text":"

        The ports/ package is the seam where the domain meets infrastructure. Each domain/<resource>/ports/ module declares the resource's models/document shape and exposes factory functions that bind a concrete adapter \u2014 so a port module is allowed to import from infra/ and from the persistence libraries. Everything outside ports/ in domain/ stays framework- and driver-free.

        domain/<resource>/ports/db.py       -> document model + create_<resource>_repo()\ndomain/<resource>/ports/service.py  -> service + get_<resource>_service()\ninfra/db/repos/<vendor>.py          -> repository adapter factory\ninfra/adapters/service.py           -> generic CRUD service base\n

        The composition root calls the port factories; nothing else constructs an adapter.

        "},{"location":"10_layering_rules/#enforcement","title":"Enforcement","text":"
        • domain/ must never import the web framework (fastapi / starlette) or interfaces/. Only the ports/ seam, infra/, and the composition root touch drivers.
        • Reviewers (and CI) reject import fastapi inside domain/ or infra/.
        "},{"location":"20_spec_first_routing/","title":"Spec-First Routing","text":""},{"location":"20_spec_first_routing/#summary","title":"Summary","text":"

        The OpenAPI document is the single source of truth for the HTTP contract. Handlers are bound to it by name; there is no decorator router.

        "},{"location":"20_spec_first_routing/#the-contract","title":"The contract","text":"
        • openapi.yaml (or .json) declares paths, schemas, parameters, responses, and security.
        • A custom operationId names the handler function.
        • The framework (openapi_first) validates requests/responses against the spec and dispatches to the handler whose name equals operationId.
        "},{"location":"20_spec_first_routing/#app-bootstrap","title":"App bootstrap","text":"
        # main.py\nfrom openapi_first.app import OpenAPIFirstApp\n\napp = OpenAPIFirstApp(\n    openapi_path=\"openapi.yaml\",\n    routes_module=interfaces.openapi,   # module whose namespace holds handlers\n    title=\"<App> API\",\n    version=\"0.1.0\",\n    lifespan=lifespan,\n)\n

        lifespan calls the composition root:

        @asynccontextmanager\nasync def lifespan(app):\n    app.state.db_resources = await init()\n    yield\n    await shutdown()\n
        "},{"location":"20_spec_first_routing/#handler-registry","title":"Handler registry","text":"

        interfaces/openapi.py is a flat re-export of every handler, so the framework can resolve operationId across the whole app:

        from interfaces.item.routes import *\nfrom interfaces.wallet.routes import *\nfrom interfaces.progress.sse import *\n
        "},{"location":"20_spec_first_routing/#handler-shape","title":"Handler shape","text":"

        Handlers are thin and synchronous with respect to business logic:

        async def create_item(request: Request, body: dict):\n    svc = request.app.state.db_resources[\"item_svc\"]\n    return await svc.create(Item.model_validate(body))\n

        Generated stubs. openapi-first routes emits this exact shape (async def handlers taking body) when given --template-style; without that flag the stub is def create_item(payload: ItemInput) \u2014 sync, with a payload parameter. Both shapes bind identically: the router resolves handlers by operationId and introspects the FastAPI signature, and it never inspects the request body. Pass --template-style so the generated signatures match the handlers you keep in interfaces/.

        "},{"location":"20_spec_first_routing/#conventions","title":"Conventions","text":"
        • operationId naming: list_<resource>, create_<resource>, get_<resource>, update_<resource>, delete_<resource>.
        • Read-only endpoints may use a cache decorator keyed on path + query + user.
        • Validation errors -> 400; not found -> 404; delete -> 204.
        • Security is declared once in the spec and enforced by the framework; handlers contain no auth code.
        "},{"location":"20_spec_first_routing/#authless-apps","title":"Authless apps","text":"

        Auth is deferred in the standard: the same spec-first app runs with or without it, because security lives entirely in the spec, never in handlers. For an app that needs no auth yet, do not invent per-handler auth checks \u2014 just omit the security keys:

        • Remove the top-level security: block.
        • Remove components.securitySchemes.
        • Do not add security: [] to operations. An explicit empty array is a per-operation override that means \"public\", and it only matters when a global security block exists. Leaving every operation without a security key is the cleanest authless spec.

        Profile endpoints (/users/me) and profile headers (x-profile) still exist in an authless app. Define a stand-in identity in the composition root \u2014 for example get_current_user returns or lazily creates a fixed \"Demo User\" \u2014 so handlers stay auth-agnostic and only the wiring changes when real auth arrives.

        The handlers, services, and composition root are unchanged. When auth is needed later, add the global security block and an introspecting dependency; only handlers that must opt out get security: [].

        "},{"location":"20_spec_first_routing/#codegen","title":"Codegen","text":"

        openapi_first scaffolds models and route stubs from the spec (see the Build Recipe, step 3):

        openapi-first models openapi.yaml -o _gen/models.py\nopenapi-first routes openapi.yaml -o _gen/routes \\\n  --use-models --models-module _gen.models --inject-request --package --template-style\n

        Prefer codegen over hand-writing boilerplate. The result is the wire contract and a set of operationId-named signatures \u2014 not the canonical handlers.

        "},{"location":"21_crud_template/","title":"CRUD Template","text":""},{"location":"21_crud_template/#summary","title":"Summary","text":"

        Every resource follows the same four-file slice. Repetition is intentional: it makes the codebase predictable and generatable.

        "},{"location":"21_crud_template/#the-slice","title":"The slice","text":"
        domain/<resource>/\n    models.py               # pure Pydantic model (no DB fields)\n    ports/\n        db.py               # document model + repository factory\n        service.py          # service class + factory\n        converters.py       # (optional) transforms\n
        "},{"location":"21_crud_template/#the-id-rule-model-vs-document","title":"The id rule (model vs. document)","text":"

        Two different objects, two different jobs:

        Object Lives in Has id? Purpose Domain model domain/<resource>/models.py No business shape, framework-free Document domain/<resource>/ports/db.py Yes (from BaseDocument) Mongo persistence shape

        BaseDocument (mongo-ops) supplies id: Optional[PyObjectId] (aliased to _id) plus created_at / updated_at. The domain model must not declare id; Mongo owns it.

        Trap \u2014 generated wire models. openapi-first models produces the HTTP contract (see the Build Recipe, step 3). Response schemas frequently declare a required id: str, so a generated class is not a domain model. If you write class ItemDocument(Item, BaseDocument) and Item re-exports a required id: str, that field shadows BaseDocument.id and no Mongo _id can ever be set. Fix it one of three ways:

        1. Preferred: keep the domain model id-free (hand-author it from the CRUD template), and keep the required id only on the wire model.
        2. Order the bases so the document wins: class ItemDocument(BaseDocument, Item).
        3. Keep a separate document type and translate with ports/converters.py.
        "},{"location":"21_crud_template/#modelspy","title":"models.py","text":"

        A framework-free Pydantic model describing the business shape (no id).

        class Item(BaseModel):\n    name: str\n    quantity: int = 0\n
        "},{"location":"21_crud_template/#portsdbpy","title":"ports/db.py","text":"

        The persistence model extends the business model and adds database concerns. The repository factory selects the right repository flavour.

        # Item is id-free; BaseDocument adds id/created_at/updated_at.\nclass ItemDocument(Item, BaseDocument):\n    pass\n\ndef create_item_repo(*, owner_repo=None) -> ItemRepository:\n    return repo_factory(\n        collection=\"items\",\n        document=ItemDocument,\n        populate_rules=[PopulateRule(field_name=\"owner\", collection_name=\"users\")],\n        cache=None,               # or a CachedBaseRepository config\n    )\n
        "},{"location":"21_crud_template/#nested-references","title":"Nested references","text":"

        The wire contract often declares a reference as an expanded object (expense.entity: Entity), while the domain model stays id-free. Pick one convention and apply it consistently:

        • Embed (default for small, stable refs) \u2014 store the object as a dict / list[dict] on the document; the API returns it verbatim. No populate wiring.
        • Populate \u2014 store an id and declare a PopulateRule; mongo-ops expands it on read. The referenced repo must be registered with the PopulationEngine.
        • Id only \u2014 store the id and let the client resolve it.

        For populate-backed repositories change a reference with update, not patch: patch rejects changes to populated FK fields by design.

        "},{"location":"21_crud_template/#portsservicepy","title":"ports/service.py","text":"

        The service is built through the DI library, injecting the repository. The generic CRUD base provides create/read/update/patch/delete/search/....

        class ItemService(CrudsServiceAdaptor[Item, ItemDocument]):\n    model = Item\n    schema = ItemDocument\n\ndef get_item_service(repo) -> ItemService:\n    return build(ItemService, instances={\"repo\": repo})\n
        "},{"location":"21_crud_template/#naming-conventions","title":"Naming conventions","text":"Concept Convention collection plural snake case (items) document <Resource>Document repository factory create_<resource>_repo service <Resource>Service service factory get_<resource>_service resource key <resource>_svc operationId list_items, create_item, ..."},{"location":"21_crud_template/#optional-files","title":"Optional files","text":"
        • converters.py \u2014 pure functions mapping between domain types.
        • ports/enrichment.py \u2014 adapts a pipeline into an async callable the service can invoke (used when a resource is populated by a pipeline).
        "},{"location":"22_auth_integration/","title":"Auth Integration","text":""},{"location":"22_auth_integration/#summary","title":"Summary","text":"

        Authentication is a service, not a library. Every Aetos application shares a single identity service \u2014 the auth-server \u2014 and consumes it through its HTTP contract. An app never implements registration, login, password hashing, or token issuance itself.

        The agent does not need an MCP bundle for the auth-server. It reads the pinned OpenAPI contract (below) and declares a bearer security scheme in its own spec; openapi_first then generates the verifying dependency. No auth code is written.

        "},{"location":"22_auth_integration/#read-the-contract","title":"Read the contract","text":"

        The auth-server OpenAPI document is pinned in the standards bundle and served as an MCP resource:

        docs://spec\n

        It is the authoritative client contract (OpenAPI 3.1). Read it to learn the endpoints and the request/response schemas:

        Endpoint Purpose POST /register Create a user (201, returns PublicUser) POST /login Authenticate and issue a JWT (LoginResponse) GET /me Current user's PublicUser (bearer required) POST /logout Stateless logout (LogoutResponse) POST /introspect Internal token introspection (active, user)

        The pinned snapshot is versioned (currently 0.0.5). If the caller has a live auth-server and needs the current contract, they can pass the full endpoint ({AUTH_SERVER}/openapi.json) and read it directly instead of the pin.

        "},{"location":"22_auth_integration/#wire-it-up-declare-dont-code","title":"Wire it up: declare, don't code","text":"

        Authentication is added by editing the app's own openapi.yaml \u2014 nothing else. Declare a global bearer requirement and point the scheme at the auth server (values come from the environment):

        security:\n  - bearerAuth: []\npaths:\n  # ...\ncomponents:\n  securitySchemes:\n    bearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n      x-server-url: \"{AUTH_SERVER}\"\n      x-introspect-path: \"/introspect\"\n      x-login-path: \"/login\"\n      x-register-path: \"/register\"\n      x-logout-path: \"/logout\"\n      x-me-path: \"/me\"\n

        openapi_first reads securitySchemes + security and generates a FastAPI dependency that extracts the bearer token, POSTs {\"token\": <jwt>} to {AUTH_SERVER}/introspect, and returns the user when active == true. It raises 401 on an invalid or inactive token and 503 when the auth server is unreachable. The generated handlers receive the authenticated user \u2014 you author no authentication code.

        "},{"location":"22_auth_integration/#public-operations","title":"Public operations","text":"

        A route that must stay open opts out by overriding security with an empty list:

        paths:\n  /health:\n    get:\n      operationId: health\n      security: []        # overrides the global requirement\n      responses:\n        \"200\":\n          description: OK\n
        "},{"location":"22_auth_integration/#environment","title":"Environment","text":"
        AUTH_SERVER=http://localhost:8000     # auth-server base URL\nJWT_SERVER=http://localhost:8000      # jwtlib client base URL (seeding/CLI)\n
        "},{"location":"22_auth_integration/#path-1-jwtlib-client-no-generator","title":"Path 1: jwtlib client (no generator)","text":"

        Apps that do not use a generated dependency verify requests with the py-jwt client:

        from jwtlib.introspection import authenticate_request\n\nauthorized = await authenticate_request(\n    should_skip_authentication,  # allow public paths\n    method,\n    path,\n    authorization_token,         # \"Bearer <jwt>\" or None\n)\n

        authenticate_request POSTs to {JWT_SERVER}/introspect (3 second timeout) and treats {\"active\": true, \"user\": {...}} as valid. Use this for seeding scripts and tests (jwtlib.register_user, jwtlib.login_user).

        "},{"location":"22_auth_integration/#golden-rules","title":"Golden rules","text":"
        1. Never trust an unverified token. Decode through the generated dependency or jwtlib before handling the request.
        2. Treat active: false as unauthenticated, even if the JWT decodes.
        3. Do not implement your own JWT parsing. Revocation and issuer changes must stay centralized in the auth-server.
        4. Do not add auth until the app's outcome is validated. Ship the app authless first; layer the security scheme once the core behaviour works.
        "},{"location":"22_auth_integration/#notes","title":"Notes","text":"
        • The default template is authless on purpose. Add the securitySchemes block above only when auth is required. Pull the shared slice with get_app_component(\"auth\").
        • The auth-server is deployed as a service (no importable package); the client surface is the spec, plus jwtlib for the low-level path.
        "},{"location":"30_infra_adaptors/","title":"Infra Adapters","text":""},{"location":"30_infra_adaptors/#summary","title":"Summary","text":"

        All external systems are reached through adapters in infra/. Prefer an existing internal library over writing a new adapter; where no library exists, copy the Tier B scaffold from templates/app. See the Genericity Matrix for the Tier A / B / C split.

        "},{"location":"30_infra_adaptors/#database-mongodb","title":"Database (MongoDB)","text":"
        • A single connection manager owns the client lifecycle. setup_database(uri, db_name) / shutdown_database().
        • A repository factory selects the repository flavour:
        repo_factory(collection, document, engine=None,\n             populate_rules=None, cache=None)\n
        • base repository \u2014 plain CRUD;
        • populating repository \u2014 resolves referenced documents (foreign keys);

        • cached repository \u2014 an LRU/TTL cache in front of reads.

        • Referenced documents are described declaratively:

        PopulateRule(field_name=\"owner\", collection_name=\"users\",\n             nested_rules=[], max_depth=2, projection=None)\n
        • Transactions use a session context manager provided by the library.

        Tier A \u2014 Library (Mongo Ops). Do not write raw Motor calls in the domain; consult the registry and the library's MCP before touching the driver.

        "},{"location":"30_infra_adaptors/#http-response-cache","title":"HTTP response cache","text":"

        Tier B \u2014 template. Copy from templates/app; not a standalone library.

        A generic GET cache sits behind a decorator.

        @cache_response(ttl=60)\nasync def list_items(request): ...\n
        • Keyed on path + query + user.
        • No-op when no store is wired.
        • invalidate(*resources) bumps a generation counter for write-triggered invalidation.
        "},{"location":"30_infra_adaptors/#event-progress-bus","title":"Event / progress bus","text":"

        Tier B \u2014 template. Copy from templates/app.

        A port with an in-memory default adapter (publish, get_events). Swap for a durable broker in production (see Worker & Progress).

        "},{"location":"30_infra_adaptors/#external-clients-ingestion","title":"External clients (ingestion)","text":"

        External fetchers (files, mail, HTTP) are adapters that wrap ingestion libraries. Construct them in the composition root and inject into orchestrators.

        Tier A \u2014 Libraries: Omniread (formats) and Mail Intake (email).

        "},{"location":"30_infra_adaptors/#llm-clients","title":"LLM clients","text":"

        Tier B \u2014 template. Copy the pool scaffold from templates/app.

        When a pipeline calls a model provider, route through a pool adaptor that handles provider selection, retries, and client lifecycle:

        pool = setup_async_pool(provider=settings.llm_provider)\nresult = await pool.complete(model=\"...\", messages=[...])\n

        Providers are selected by LLM_PROVIDER and configured by environment.

        "},{"location":"30_infra_adaptors/#key-value-store","title":"Key-value store","text":"

        Tier B \u2014 template. Copy from templates/app.

        For report/snapshot storage, provide a pluggable store port with a Redis adapter and an in-memory fallback.

        "},{"location":"30_infra_adaptors/#rule","title":"Rule","text":"
        • Tier A (libraries: DB, DI, ingestion, mail, auth, docs, pipelines) \u2014 use the library; writing a private copy is a defect. Query find_library first.
        • Tier B (cache, progress bus, LLM pool, KV store, composition shape, worker, tests) \u2014 these are template code, not libraries: copy them from templates/app rather than searching the registry.
        • Tier C (models, business logic, pipeline families, rules) \u2014 author them yourself.
        "},{"location":"40_ui_admin/","title":"UI: Auto-Rendered Admin & Custom Pages","text":""},{"location":"40_ui_admin/#summary","title":"Summary","text":"

        The UI axis of an Aetos app is a published React client, not code written per application. Two npm packages carry the whole surface:

        Package Role @aetoskia/react-openapi Renders a complete admin panel (CRUD tables, forms, filters, sorting, pagination, uploads) from the app's openapi.yaml \u2014 zero UI code. @aetoskia/react-auth Auth contexts and pages (login/register/me) wired to the auth-server, plus the axios client with token handling.

        Both publish to the private registry https://npm.aetoskia.com. The server spec is the single source of truth: the same openapi.yaml that drives openapi-first routing drives the admin UI, through x- extension fields (see below).

        "},{"location":"40_ui_admin/#scaffold","title":"Scaffold","text":"
        cp -r <docs>/standards/src/templates/client apps/<your-app>-client\ncd apps/<your-app>-client\nnpm install          # deps come from npm.aetoskia.com via .npmrc\nnpm run dev\n

        The client template is a Vite + MUI app with:

        • src/openapi-config.ts \u2014 points the renderer at the app's spec and the auth-server's spec;
        • .env.example \u2014 VITE_API_BASE_URL (app API) and VITE_AUTH_BASE_URL (auth-server);
        • a Home page that auto-lists every resource the spec declares, and a Header/Footer/theme scaffold.

        Custom pages are ordinary React routes layered on top; the auto-rendered admin is available per resource at #/resource/<name>.

        "},{"location":"40_ui_admin/#x-extensions-how-the-spec-steers-the-ui","title":"x- extensions: how the spec steers the UI","text":"

        The admin renderer reads a catalog of OpenAPI extension fields (x-resource, x-list-columns, x-display-format, x-label, x-order, x-hidden, x-sortable, x-filterable, x-autocomplete, x-fk, x-ui-type, x-upload, x-sse, x-profile, and the auth wiring x-server-url / x-login-path / x-me-path / \u2026) declared on schemas and properties.

        The catalog is canonical in the react-openapi source, not in this doc. Read it from the MCP bundle:

        docs://modules/react-openapi        # module: specExtensions \u2014 the full catalog\n

        The app's own spec carries the per-resource values; the catalog explains what each field does. The template's openapi.yaml shows the convention on the example Item and Job schemas.

        "},{"location":"40_ui_admin/#golden-rules","title":"Golden rules","text":"
        1. The spec owns the UI. Add a resource or rename a column in openapi.yaml; the admin follows. Never fork the renderer per app.
        2. Custom pages for workflows, auto-render for CRUD. Anything that is \"list / create / edit / delete an entity\" is a spec concern; anything that is a bespoke workflow is a React page.
        3. Auth is consumed, never re-implemented. @aetoskia/react-auth holds tokens and calls the auth-server endpoints declared by the x- wiring; pages read the context.
        4. Publish, don't vendor. UI shared across apps belongs in @aetoskia/react-openapi or @aetoskia/react-auth (SemVer, tag-triggered npm release), not copy-pasted into app trees.
        "},{"location":"40_ui_admin/#notes","title":"Notes","text":"
        • The server template ships authless by default (see 22 \u2013 Auth Integration); the client template pairs with it and degrades to \"no login\" until a security scheme is declared.
        • react/vet is the full-stack reference implementation: spec with x- extensions, server, and the consuming client in one tree.
        "},{"location":"50_pipeline_scaffold/","title":"Pipeline Scaffold","text":""},{"location":"50_pipeline_scaffold/#summary","title":"Summary","text":"

        Data-driven processing is expressed as a composition graph. The graph is built by a DI library; execution is driven by a DAG engine. Stages are pure and individually testable.

        "},{"location":"50_pipeline_scaffold/#when-to-use-a-pipeline","title":"When to use a pipeline","text":"

        Use a pipeline when a resource is produced by a multi-step transformation of an input (a document, a file, a message) rather than by a simple CRUD write.

        "},{"location":"50_pipeline_scaffold/#structure-of-a-family","title":"Structure of a family","text":"

        A family is one input shape (e.g. a file format or a message kind). Each family has the same skeleton:

        pipelines/<family>/\n    abc.py            # port contracts (stage interfaces + root interface)\n    impl.py           # concrete stages + root implementation\n    pipeline.yaml     # graph spec: nodes, edges, roots, schema\n    resources/\n        pipeline.yaml # runtime spec consumed by the loader\n        patterns/*.yaml  # rule fragments (pattern registry)\n    banks/<variant>.py   # optional variants that re-pin a few slots\n
        "},{"location":"50_pipeline_scaffold/#shared-scaffolding","title":"Shared scaffolding","text":"
        pipelines/shared/\n    ports.py     # RegistryPort, FinalizePort, etc.\n    loader.py    # build(root_cls) -> wires the graph + engine\n    registry.py  # resolve_root(...) -> root class for a (kind, variant)\n
        "},{"location":"50_pipeline_scaffold/#the-loader","title":"The loader","text":"
        def build(root_cls, *, instances=None, config=None):\n    # merge resources/patterns/*.yaml into a pattern registry\n    # bind registry/config into each graph node by id\n    # build the schema (state) class and the engine\n    root = root_cls()\n    root._engine = Engine(graph, state_cls, payload_cls)\n    return root\n
        "},{"location":"50_pipeline_scaffold/#the-registry","title":"The registry","text":"

        A single lookup replaces hand-rolled if/else selection:

        _FAMILIES = {\n    \"csv\":  {\"acme\": {\"heuristic\": AcmeCsvPipeline}},\n    \"json\": {\"globex\": {\"heuristic\": GlobexJsonPipeline}},\n}\n\ndef resolve_root(kind, variant, mode=\"heuristic\"):\n    return _FAMILIES[kind][variant][mode]\n

        Adding a new variant means adding one class and one registry entry.

        "},{"location":"50_pipeline_scaffold/#driving-a-pipeline","title":"Driving a pipeline","text":"

        Stages are driven explicitly so intermediate state can be persisted:

        pipeline = build(resolve_root(kind, variant))\ncontent = pipeline.ingest.materialize(raw_bytes)\nrecords = pipeline.reader.read(content)\nitems   = pipeline.normalize.build(records)\n
        "},{"location":"50_pipeline_scaffold/#testing","title":"Testing","text":"

        Because stages are pure, test each stage in isolation and test the assembled root against fixture inputs whose expected outputs are stored as golden files. A parity test replays fixtures headlessly.

        "},{"location":"51_worker_and_progress/","title":"Worker & Progress","text":""},{"location":"51_worker_and_progress/#summary","title":"Summary","text":"

        Long-running work runs in a background worker. Jobs are durable documents that move through an explicit status machine. Progress is streamed to clients.

        "},{"location":"51_worker_and_progress/#the-status-machine","title":"The status machine","text":"
        pending -> processing -> completed\n                     \\-> failed    (retried up to N times)\n                     \\-> paused    (waiting for human input)\n
        • pending \u2014 queued, eligible for pickup.
        • processing \u2014 claimed by a worker.
        • paused \u2014 blocked on a human-in-the-loop question.
        • failed \u2014 error; retry_count increments until a max, then skipped.
        • completed \u2014 terminal success.
        "},{"location":"51_worker_and_progress/#the-poll-loop","title":"The poll loop","text":"
        async def poll(resources):\n    backoff = MIN_POLL\n    while True:\n        jobs = await job_svc.search(filter={\"status\": \"pending\"}, limit=100)\n        backoff = MIN_POLL if jobs else min(backoff * 2, MAX_POLL)\n        for job in jobs:\n            if (job.retry_count or 0) >= MAX_RETRIES:\n                continue\n            await job_svc.update_status(job.id, \"processing\")\n            try:\n                await process(job, resources)\n            except PauseForResolution:\n                await job_svc.update_status(job.id, \"paused\")\n            except Exception as e:\n                await job_svc.update_status(\n                    job.id, \"failed\", error=str(e),\n                    retry_count=(job.retry_count or 0) + 1,\n                )\n        await asyncio.sleep(backoff)\n

        Tunables live in environment variables: WORKER_POLL_MIN, WORKER_POLL_MAX, WORKER_MAX_RETRIES.

        "},{"location":"51_worker_and_progress/#progress-events","title":"Progress events","text":"

        A worker publishes structured progress events to a bus (a port). The HTTP edge exposes a streaming endpoint that replays events for a given job id.

        class ProgressEvent(BaseModel):\n    job_id: str\n    step: str\n    status: str            # started | progress | completed | skipped | paused\n    message: dict | None = None\n

        The bus is an in-memory adapter by default; because it is a port, it can be swapped for a durable broker. Emit from the orchestrator at each stage:

        await self.bus.publish(ProgressEvent(job_id=jid, step=\"normalize\",\n                                     status=\"completed\", message={\"count\": n}))\n
        "},{"location":"51_worker_and_progress/#streaming-endpoint","title":"Streaming endpoint","text":"
        async def stream_job_events(request, id):\n    bus = request.app.state.db_resources.get(\"progress_bus\")\n    if bus is None:\n        return {\"events\": []}\n\n    async def gen():\n        sent = 0\n        while True:\n            events = bus.get_events(id)\n            for e in events[sent:]:\n                yield f\"data: {e.model_dump_json(exclude_none=True)}\\n\\n\"\n                sent += 1\n            await asyncio.sleep(0.5)\n\n    return StreamingResponse(gen(), media_type=\"text/event-stream\")\n

        Known limitation. The default in-memory bus is per-process. If the worker and the API run as separate processes, events published by the worker are not visible to the API. For production, back the bus with a shared broker. The port boundary makes this a one-adapter change.

        "},{"location":"52_human_in_loop/","title":"Human-in-the-Loop","text":""},{"location":"52_human_in_loop/#summary","title":"Summary","text":"

        Some inputs are ambiguous and must be resolved by a human before processing can continue. The blueprint models this as a durable pause: an exception is raised, a question is recorded, the job pauses, and later resumes.

        "},{"location":"52_human_in_loop/#the-mechanism","title":"The mechanism","text":"
        1. During processing, a stage raises a domain exception carrying the context needed to ask the question:
        raise PauseForResolution(\n    job_id=jid,\n    reference=\"<stable key for this decision>\",\n    options=[...],\n    context={...},\n)\n
        1. The orchestrator catches it, records a question document, and re-raises so the worker marks the job paused.
        2. A client lists pending questions and answers one:
        GET  /jobs/{id}/questions            -> list pending questions\nPOST /questions/{qid}/resolve  {choice}  -> record the choice\n
        1. When the last pending question is resolved, the resolve endpoint flips the parent job back to pending.
        2. The worker picks it up again, rebuilds a resolution map from previously answered questions, and seeds it into the pipeline so the same decision is not asked twice.
        "},{"location":"52_human_in_loop/#the-question-document","title":"The question document","text":"
        class Question(BaseDocument):\n    job_id: str\n    reference: str            # stable key: stage|field|value\n    status: str               # pending | resolved\n    options: list[dict]\n    context: dict\n    chosen: dict | None = None\n    resolved_at: str | None = None\n
        "},{"location":"52_human_in_loop/#resume-map","title":"Resume map","text":"

        The worker turns answered questions into a lookup keyed by reference, then injects it into the pipeline so that stage can skip re-raising:

        resolved = {q.reference: q.chosen for q in await svc.search(\n    filter={\"job_id\": jid, \"status\": \"resolved\"})}\n\npipeline = build(root, instances={\"pause\": handler}, config={\"resolved\": resolved})\n
        "},{"location":"52_human_in_loop/#resolve-endpoint","title":"Resolve endpoint","text":"
        async def resolve_question(request, id, body):\n    svc = request.app.state.db_resources[\"question_svc\"]\n    q = await svc.read(id)\n    await svc.update(id, {\"chosen\": body[\"chosen\"], \"status\": \"resolved\",\n                          \"resolved_at\": now()})\n\n    pending = await svc.search(filter={\"job_id\": q.job_id, \"status\": \"pending\"},\n                               limit=1)\n    if not pending:\n        jobs = request.app.state.db_resources[\"job_svc\"]\n        job = await jobs.read(q.job_id)\n        if job and job.status == \"paused\":\n            await jobs.update_status(q.job_id, \"pending\")\n    return q\n
        "},{"location":"52_human_in_loop/#cli-parity","title":"CLI parity","text":"

        The same flow is available through scripts/CLI: list, get, create, questions, resolve, retry.

        "},{"location":"90_drone_pipelines/","title":"Drone Pipelines","text":""},{"location":"90_drone_pipelines/#summary","title":"Summary","text":"

        Every Aetos repository ships a Drone CI definition at .drone.yml. There is exactly one standard per repository, and there are three types of file, chosen by what the repository produces:

        Type File Produces Repos A \u2014 PyPI package templates/drone/python-lib.yaml A wheel + sdist on the private index dagpipe, doc-forge, hexa, mail-intake, mongo-ops, omniread, openapi-first, py-jwt B \u2014 npm package templates/drone/npm-lib.yaml A package published to the private npm registry doc-weaver, react-auth, react-openapi C \u2014 Docker deployment templates/drone/service-docker.yaml An image pushed to the registry and run as a container auth-server, vet

        All templates run on platform: linux / arm64 with the workspace at /drone/src. Copy the matching template to <repo>/.drone.yml; the Type A and Type B files need no edits, the Type C file needs its placeholders filled in (below).

        Conventions: .drone.yml (not .yaml), one file per repo, secrets injected with from_secret \u2014 never commit credentials.

        "},{"location":"90_drone_pipelines/#type-a-pypi-package-python-libyaml","title":"Type A \u2014 PyPI package (python-lib.yaml)","text":"

        For internal Python libraries. The file contains two pipelines:

        1. build-and-publish-pypi \u2014 triggered on tag:
        2. check-version \u2014 guard: fail unless $DRONE_TAG equals the version in pyproject.toml; then read name / version and query $PIP_REPO_URL/simple/<package>/; if that version already exists, exit 78 and skip the whole build (see 91 \u2013 Versioning & Changelog).
        3. quality-gate \u2014 install the package with its [dev] extras from the private index, then black --check, ruff check, mypy, pydoclint, pytest.
        4. build-package \u2014 python -m build into dist/.
        5. upload-to-private-pypi \u2014 twine upload to $PIP_REPO_URL.
        6. backfill-pypi-from-tags \u2014 triggered on custom:
        7. fetch-tags \u2014 git fetch --tags --force.
        8. build-and-upload-missing \u2014 walk every tag in version order, skip the ones already on the index, git checkout the rest, verify tag == pyproject version at that commit, build, and upload. This is the disaster-recovery / replay path.

        Secrets: PIP_REPO_URL, PIP_USERNAME, PIP_PASSWORD.

        • Ship as-is. Package name and version come from pyproject.toml, so the same file is reused verbatim across every library.
        "},{"location":"90_drone_pipelines/#type-b-npm-package-npm-libyaml","title":"Type B \u2014 npm package (npm-lib.yaml)","text":"

        For internal npm libraries (the React packages). One pipeline, build-and-publish-npm, triggered on tag:

        • check-version \u2014 guard: fail unless $DRONE_TAG equals the version in package.json; query $NPM_REPO_URL for name@version; if it already exists, exit 78 and skip the whole build.
        • quality-gate \u2014 write .npmrc from the secrets, npm install, then npm run quality-gate.
        • build-package \u2014 npm install && npm run build into dist/.
        • publish-to-private-npm \u2014 npm publish --access restricted to $NPM_REPO_URL.

        Secrets: NPM_REPO_URL, NPM_USERNAME, NPM_PASSWORD. Auth is a generated .npmrc (registry= + _auth= base64 of user:pass) written from secrets at runtime \u2014 the committed .npmrc in a repo only points at the registry URL.

        • Ship as-is. Name and version come from package.json, so the same file is reused verbatim across every npm package.
        "},{"location":"90_drone_pipelines/#type-c-docker-deployment-service-dockeryaml","title":"Type C \u2014 Docker deployment (service-docker.yaml)","text":"

        For a service that ships a container image \u2014 a long-running API/worker, e.g. auth-server. The file contains one pipeline, build-and-deploy-service, triggered on tag:

        • fetch-tags \u2014 resolve the latest tag into LATEST_TAG.txt; fail if there are no tags.
        • check-version \u2014 guard: fail unless $DRONE_TAG equals the repo-root VERSION file (see 91 \u2013 Versioning & Changelog).
        • check-remote-image \u2014 if aetos/<app>:<tag> already exists locally, exit 78 and skip the build.
        • quality-gate \u2014 install from requirements.txt and run black / ruff / mypy / pytest.
        • build-image \u2014 docker build with the private-index build args, tagged aetos/<app>:<tag> and :latest.
        • push-image \u2014 login, re-tag with $REGISTRY_HOST, push both tags.
        • stop-old \u2014 docker rm -f <app>.
        • run-container \u2014 docker run -d --name <app> -p <host>:<container> --restart always with the service's -e environment.

        Secrets: PIP_REPO_URL, PIP_USERNAME, PIP_PASSWORD (service build args), REGISTRY_HOST, REGISTRY_USER, REGISTRY_PASS, plus the service runtime env (for example MONGO_*, JWT_SECRET).

        Placeholders to fill in per repo:

        Placeholder Meaning Example <app> service image / container name auth-server aetos/<app> image repository on the registry aetos/auth-server <host-port> / <container-port> published : in-image port 9003:8000 <ENV_VAR> runtime environment variable MONGO_HOST"},{"location":"90_drone_pipelines/#what-not-to-do","title":"What not to do","text":"
        • Do not hand-roll a fourth shape. A repo is exactly one of Type A, B, or C, never combinations.
        • Do not inline secrets; always use from_secret.
        • Do not drop the check-version / check-remote-image skip \u2014 it guards the index and the running container against duplicate publishes.
        • Do not drop the tag\u2194version guard. A Python package needs its pyproject.toml version to equal the tag; an npm package needs its package.json version; a service needs a root VERSION file. See 91 \u2013 Versioning & Changelog.
        • Do not rename the pipelines; tooling and runbooks key off build-and-publish-pypi, build-and-publish-npm, and build-and-deploy-service.
        "},{"location":"90_drone_pipelines/#related","title":"Related","text":"
        • 01 \u2013 Build Recipe \u00b7 30 \u2013 Infra Adapters \u00b7 91 \u2013 Versioning & Changelog \u00b7 93 \u2013 Library Registry
        "},{"location":"91_versioning_and_changelog/","title":"Versioning & Changelog","text":""},{"location":"91_versioning_and_changelog/#summary","title":"Summary","text":"

        Every Aetos artifact \u2014 library or service \u2014 is versioned with Semantic Versioning and documents its releases in a Keep a Changelog file. The version file is the source of truth, the git tag must equal it, and a Drone guard enforces that equality before anything is published. Releases are cut manually; a tag is what triggers the pipeline.

        This page pairs with 90 \u2013 Drone Pipelines: the version and tag contract is exactly what those three CI shapes consume.

        "},{"location":"91_versioning_and_changelog/#the-version-contract","title":"The version contract","text":"Artifact Source of truth Notes Library (PyPI package) version in pyproject.toml check-version also reads it to skip duplicates Library (npm package) version in package.json check-version also queries the registry to skip duplicates Service (Docker) VERSION file at the repo root one line, x.y.z; the service reads it (build-arg) \u2014 never hardcode the version

        Rules:

        1. One version per repository. No per-module versions.
        2. Tag = version. The git tag is bare SemVer (0.0.6), no v prefix, and it MUST match the version file byte-for-byte. The Drone guard fails the build otherwise \u2014 this is what stops a tag from silently publishing nothing.
        3. A release is a tag, created after the change is merged. The version bump and the changelog promotion travel inside the merge request (MR); the tag is added on the merged commit and pushed. See Tagging strategy.
        4. Never reuse a tag. If a release is wrong, cut a new patch version.
        "},{"location":"91_versioning_and_changelog/#pre-10-0yz","title":"Pre-1.0 (0.y.z)","text":"

        While a package is 0.y.z, 0.y is treated as the major line:

        • breaking change \u2192 0.(y+1).0
        • new feature \u2192 0.y.(z+1)
        • bug fix \u2192 0.y.(z+1)

        Once a package reaches 1.0.0, normal SemVer applies. Do not ship 1.0.0 until the public API is considered stable.

        "},{"location":"91_versioning_and_changelog/#the-changelog","title":"The changelog","text":"

        CHANGELOG.md at the repo root, in Keep a Changelog form. It always has exactly one open [Unreleased] section with the change categories that apply:

        ## [Unreleased]\n\n### Added\n### Changed\n### Deprecated\n### Removed\n### Fixed\n### Security\n

        On release you promote it \u2014 never delete history:

        ## [0.0.6] - 2026-03-07\n\n### Added\n- ...\n

        and add a link reference at the bottom:

        [Unreleased]: https://git.aetoskia.com/aetos/<repo>/compare/0.0.6...HEAD\n[0.0.6]: https://git.aetoskia.com/aetos/<repo>/compare/0.0.5...0.0.6\n

        Conventions:

        • Write entries for humans: one line each, imperative, referencing the user impact, not the commit hash.
        • Categories: Added, Changed, Deprecated, Removed, Fixed, Security. Omit empty categories.
        • Security fixes get their own entry even if the change is otherwise a bug fix.
        • Keep [Unreleased] current: add an entry in the same change that introduces the behaviour, not later.
        • The [Unreleased] heading is never renamed; copy its content into the new version heading and clear it.
        "},{"location":"91_versioning_and_changelog/#reconcile-before-releasing","title":"Reconcile before releasing","text":"

        [Unreleased] is a draft, not the source of truth. It is only trustworthy when it was maintained alongside each change; a long-running branch or a change that skipped the changelog leaves it stale, so it can silently under-report a release. Verify it against the change before you promote:

        1. List what actually changed since the last release: git log <last-tag>..HEAD and git diff --stat <last-tag>..HEAD.
        2. Compare that against [Unreleased]; add an entry for every user-facing change that is missing.
        3. Always show the proposed additions to the user and wait for approval before promoting. If an entry is ambiguous, ask rather than guess.

        Only then promote. Never cut a release with a known gap between the diff and the changelog.

        "},{"location":"91_versioning_and_changelog/#tagging-strategy-mr-based","title":"Tagging strategy (MR-based)","text":"

        The release version is known while the change is still a merge request, so the bump travels with the change and only the tag is added afterwards:

        1. In the MR \u2014 reconcile [Unreleased] against the change (see Reconcile before releasing) and get the user's approval for any additions. Then set the intended release version: version in pyproject.toml or package.json (or the VERSION file) to x.y.z, and promote the changelog (below). Changelog entries and link references name the version/tag, never a commit id.
        2. Merge or squash the MR into main.
        3. Create the tag x.y.z on the resulting commit (the merge/squash commit).
        4. Push the tag (git push origin x.y.z) \u2014 Drone builds the release.

        Because the version bump is inside the tagged commit, the guard's tag == version check can only fail if the wrong commit was tagged.

        "},{"location":"91_versioning_and_changelog/#agent-assisted-tagging","title":"Agent-assisted tagging","text":"

        The agent neither authors nor merges the MR, and never tags before the merge. After the user confirms the MR is merged/squashed and says to proceed:

        1. Wait for that explicit go-ahead.
        2. Find the commit that introduced the version bump:
        3. Python packages: git log -S 'version = \"x.y.z\"' -n 1 --format='%H %s' -- pyproject.toml
        4. npm packages: git log -S '\"version\": \"x.y.z\"' -n 1 --format='%H %s' -- package.json
        5. services: git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION
        6. Confirm that commit's version file equals x.y.z, then tag only that commit, lightweight and bare: git tag x.y.z <sha>.
        7. Do not push. Ask the user to push the tag: git push origin x.y.z.
        "},{"location":"91_versioning_and_changelog/#release-checklist","title":"Release checklist","text":"
        1. Confirm the quality gate is green and main is up to date.
        2. In the MR: reconcile [Unreleased] against the change being released \u2014 git log <last-tag>..HEAD and git diff --stat <last-tag>..HEAD \u2014 add any missing user-facing entries, and get the user's approval for the additions. Then move every [Unreleased] entry under the new version heading with the target date (## [x.y.z] - YYYY-MM-DD) and restore an empty [Unreleased] on top.
        3. In the MR: add the two compare-link references at the bottom of the changelog, naming the version/tag (never a commit id).
        4. In the MR: set the version file \u2014 pyproject.toml (version = \"x.y.z\"), package.json (\"version\": \"x.y.z\"), or VERSION \u2014 to the intended release version.
        5. Merge or squash the MR into main.
        6. Create the tag on the resulting commit: lightweight git tag x.y.z.
        7. Push the tag (git push origin x.y.z). Watch Drone: Type A publishes the wheel/sdist, Type B publishes the npm package, Type C builds and deploys the image; all three first assert tag == version.
        8. Do not reuse the tag if the run fails \u2014 fix and cut x.y.(z+1).
        "},{"location":"91_versioning_and_changelog/#why-the-guard-matters","title":"Why the guard matters","text":"

        The version file and the tag are two facts that must agree; nothing in git enforces that by itself. A mismatch is not a theoretical risk \u2014 a package can be tagged 0.0.2 while its pyproject.toml still says 0.0.1, and the publish step (which compares the file against the index) then skips the build entirely, so 0.0.2 never reaches the index while looking like a release. The Drone guard turns that silent no-op into a hard failure.

        "},{"location":"91_versioning_and_changelog/#related","title":"Related","text":"
        • 90 \u2013 Drone Pipelines \u00b7 94 \u2013 Repository Inventory \u00b7 01 \u2013 Build Recipe \u00b7 93 \u2013 Library Registry
        "},{"location":"92_genericity_matrix/","title":"Genericity Matrix","text":""},{"location":"92_genericity_matrix/#summary","title":"Summary","text":"

        This page states precisely what is library-backed, what is template-provided, and what is app-specific and must be authored. Use it to scope a new build and to know, for any given capability, whether to call a library, copy template code, or write it yourself.

        "},{"location":"92_genericity_matrix/#tier-a-library-backed-use-never-reimplement","title":"Tier A \u2014 Library-backed (use; never reimplement)","text":"

        These capabilities already exist as internal libraries. Reach them through the library registry MCP (find_library(capability)) and read the library's own MCP for its API. Writing a private copy of any of these is a defect.

        Capability Library MCP Persistence: repositories, cache, populate, transactions Mongo Ops (mongo_ops) :8007 Dependency injection / composition Hexa (hexa) :8008 Deterministic multi-step transformation engine DAG Pipe (dagpipe) :8006 Spec-first HTTP edge, client, codegen OpenAPI First (openapi_first) :8004 Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) Omniread (omniread) :8003 Read-only email ingestion Mail Intake (mail_intake) :8002 JWT auth primitives (register, login, introspect) Py JWT (jwtlib) :8005 Documentation build (MkDocs + MCP) Doc Forge (docforge) :8001"},{"location":"92_genericity_matrix/#tier-b-template-provided-copy-from-templatesapp-then-adapt","title":"Tier B \u2014 Template-provided (copy from templates/app, then adapt)","text":"

        These are reusable internal components shipped inside the template \u2014 they are not independent libraries. Copy them as-is, then rename/populate only what is app-specific. They give every app the same wiring shape as the reference app. Fetch them by kind with get_app_component, or the whole tree with get_app_template.

        Component Template location Action Shipped Layering & dependency rule the package layout + import rules keep \u2705 Composition root shape init.py (get_svc/get_db, idempotency) keep \u2705 Spec-first web edge interfaces/openapi.py, thin handlers bound to operationId keep \u2705 CRUD slice pattern domain/<resource>/{models.py, ports/db.py, ports/service.py, converters.py} rename + fill \u2705 Generic CRUD service infra/adapters/service.py (CrudsServiceAdaptor) keep \u2705 Repository factory infra/db/repos/mongo.py (_repo_factory) keep \u2705 Worker poll + status loop worker.py keep \u2705 Progress bus infra/adapters/sse.py (keyed in-memory bus) + an app SSE endpoint keep \u2705 HTTP response cache infra/http_cache.py (cache_response + generation invalidation) keep \u2705 Key-value store infra/adapters/kv.py (port + in-memory + Redis adaptor) keep \u2705 Pipeline scaffold pipelines/shared/{ports,loader,registry}.py + pipelines/<family>/ rename + fill \u2705 Operator scripts scripts/ (init() / get_svc() / shutdown()) rename \u2705 Testing harness integration fakes + fixture-parity pattern keep \u2705 Project scaffolding pyproject.toml, Dockerfile, docker-compose.yaml, .env.example, openapi.yaml rename + fill \u2705"},{"location":"92_genericity_matrix/#tier-b-patterns-port-from-the-reference-app","title":"Tier B (patterns) \u2014 port from the reference app","text":"

        A few Tier B capabilities are real and reusable, but are shaped by the app or the provider, so the template does not ship them verbatim \u2014 copying them blindly would carry app-specific names. Treat them as patterns: lift the shape from the reference app and rename per app.

        Component Reference location Action Shipped Human-in-the-loop durable pause + question document + resolve endpoint + resume map port + reshape \u2717 LLM client pool provider-select + retry/rotation pool scaffold port + reshape \u2717"},{"location":"92_genericity_matrix/#tier-c-app-specific-must-be-authored","title":"Tier C \u2014 App-specific (must be authored)","text":"Artifact Why Resource models the business shape Repository populate/cache rules the relationships Service business logic domain behaviour Pipeline families the transformation graph Pattern/rule resources data-driven policy Fixtures & golden outputs test data"},{"location":"92_genericity_matrix/#the-two-axes","title":"The two axes","text":"

        Everything app-specific reduces to two axes:

        1. Resource model \u2014 the set of resources, their fields, relationships, and the OpenAPI contract.
        2. Pipeline family \u2014 only if inputs require multi-step transformation.

        If you can specify those two axes, the rest of the app follows mechanically: Tier A is imported, Tier B is copied, and Tier C is the only thing you author.

        "},{"location":"93_library_registry/","title":"Library Registry","text":""},{"location":"93_library_registry/#summary","title":"Summary","text":"

        The Aetos ecosystem provides internal libraries for the shared concerns of every application. Use them. Writing a private copy of any capability below is a defect.

        Each library also exposes its own documentation as an MCP server. An AI agent can read a library's full API by connecting to its MCP and reading docs://index, docs://nav, and docs://modules/{module}.

        "},{"location":"93_library_registry/#catalog","title":"Catalog","text":"Library Import Purpose Use instead of MCP DAG Pipe dagpipe Deterministic state-transformation DAG engine hand-rolled orchestration/topological ordering :8006 Hexa hexa Declarative DI / composition-root tooling manual wiring, hand-written factories :8008 Mongo Ops mongo_ops Async MongoDB repositories, cache, populate, transactions raw Motor CRUD and connection lifecycle :8007 Omniread omniread Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) custom scrapers/parsers :8003 OpenAPI First openapi_first Spec-first FastAPI bootstrap, client, codegen decorator routers and hand-written clients :8004 Mail Intake mail_intake Provider-agnostic read-only email ingestion Gmail OAuth + MIME parsing :8002 Py JWT jwtlib JWT auth primitives (register/login/introspect) password hashing + token code :8005 Doc Forge docforge Docstring compiler \u2192 MkDocs + MCP docs custom doc generators :8001 Doc Weaver doc-weaver JSDoc compiler \u2192 TypeDoc + MCP docs (React/TS) custom TypeScript doc generators :8010 React Auth react-auth JWT-backed React auth UI: provider, login page, profile screens, bearer axios client hand-rolled auth contexts and token handling in React apps :8011 React OpenAPI react-openapi Spec-driven React admin UI (CRUD, tables, forms, SSE) derived from an OpenAPI document per-resource hand-written admin screens :8012 Auth Server (service) Central identity service (register/login/me/logout/introspect) building auth endpoints yourself spec: docs://spec"},{"location":"93_library_registry/#how-to-choose","title":"How to choose","text":"You need to\u2026 Use persist and query documents Mongo Ops compose dependencies Hexa run a multi-step transformation DAG Pipe read/parse an arbitrary input format Omniread expose a contract-first HTTP API OpenAPI First ingest email Mail Intake authenticate users / verify tokens Py JWT (+ Auth Server) generate documentation Doc Forge generate React/TypeScript documentation Doc Weaver authenticate a React front-end React Auth (+ Auth Server) build a React admin UI from an OpenAPI spec React OpenAPI"},{"location":"93_library_registry/#discovery","title":"Discovery","text":"

        A single standards MCP exposes find_library(capability), which returns the matching library, its import name, its \"use instead of\" guidance, and its MCP endpoint (or, for the auth-server service, a spec pointer). It also serves the pinned auth-server OpenAPI contract at docs://spec. Query it before writing any infrastructure.

        "},{"location":"93_library_registry/#notes","title":"Notes","text":"
        • Hexa is a full library with its own MCP server on :8008: read docs://index, docs://nav, and docs://modules/{module} (e.g. docs://modules/hexa.container) to discover the DI surface \u2014 build(cls, *, instances, config) and the PortNode model.
        • Auth Server is a service, not an importable library: it has no MCP bundle by design. Read its client contract from the pinned OpenAPI document via docs://spec and wire it by declaring a bearerAuth security scheme in the app's own spec (see Auth Integration); py-jwt covers the low-level token path.
        • Doc Weaver is the TypeScript counterpart to Doc Forge: it reads JSDoc comments and emits a TypeDoc site plus the same doc-forge-shaped MCP bundle for React packages. Its convention is RDFC (the React Doc-forge Convention), the JSDoc parallel to GSDFC.
        • React Auth and React OpenAPI are front-end libraries (TypeScript, React 18 + MUI + React Router peers), not Python services \u2014 they consume the Auth Server and an OpenAPI document rather than serving one. Each ships a wiki, a TypeDoc site and an MCP bundle like every other library above.
        • Library MCP servers expose documentation resources (not executable tools): they tell an agent the available API surface so it does not invent code.
        "},{"location":"94_repository_inventory/","title":"Repository Inventory","text":""},{"location":"94_repository_inventory/#summary","title":"Summary","text":"

        The canonical list of Aetos repositories covered by the CI and versioning standards, with the artifact each one produces, its version source, and its Drone shape. Every entry maps to the contract in 91 \u2013 Versioning & Changelog and the three CI files in 90 \u2013 Drone Pipelines.

        The same data is published machine-readably as the registry://repos MCP resource (and the list_repos tool), sourced from standards/src/repos.json. Paths are relative to the aetos/ workspace root.

        "},{"location":"94_repository_inventory/#packages-type-a-pypi","title":"Packages (Type A \u2014 PyPI)","text":"

        A wheel + sdist published to the private index. Version source is pyproject.toml; Drone file is python-lib.yaml (tag-triggered).

        Repo Path Docs MCP server dagpipe dagpipe lib, wiki dagpipe:8006 doc-forge doc-forge lib, wiki docforge:8001 hexa hexa lib, wiki hexa:8008 mail-intake mail-intake lib, wiki mail_intake:8002 mongo-ops mongo-ops lib, wiki mongo_ops:8007 omniread omniread lib, wiki omniread:8003 openapi-first openapi-first lib, wiki openapi_first:8004 py-jwt py-jwt lib, wiki jwtlib:8005"},{"location":"94_repository_inventory/#packages-type-b-npm","title":"Packages (Type B \u2014 npm)","text":"

        A package published to the private npm registry (npm.aetoskia.com). Version source is package.json; Drone file is npm-lib.yaml (tag-triggered).

        Repo Path Docs MCP server doc-weaver doc-weaver lib, wiki doc-weaver:8010 react-auth react/react-auth lib, wiki react-auth:8011 react-openapi react/react-openapi lib, wiki react-openapi:8012"},{"location":"94_repository_inventory/#services-apps-type-c","title":"Services & Apps (Type C)","text":"

        A container image pushed to the registry and run on the Docker host. Version source is the VERSION file; Drone file is service-docker.yaml.

        Repo Path Type Trigger Docs auth-server auth-server service tag api, lib, wiki vet react/vet app tag lib, wiki

        Tag-triggered and enforces tag == VERSION.

        "},{"location":"94_repository_inventory/#required-files-per-repo","title":"Required files per repo","text":"Type Version source Changelog Drone package (PyPI) pyproject.toml CHANGELOG.md python-lib.yaml package (npm) package.json CHANGELOG.md npm-lib.yaml service / app VERSION CHANGELOG.md service-docker.yaml

        Every covered repository must be able to satisfy tag == version: the version file (never a commit id) is bumped in the release MR, the MR is merged, and the tag is created on the merged commit.

        "},{"location":"94_repository_inventory/#reading-this-at-runtime","title":"Reading this at runtime","text":"
        • Resource: registry://repos
        • Tool: list_repos()
        • Humans: this page (mirror of standards/src/repos.json).
        "},{"location":"94_repository_inventory/#related","title":"Related","text":"
        • 90 \u2013 Drone Pipelines \u00b7 91 \u2013 Versioning & Changelog \u00b7 93 \u2013 Library Registry
        "}]} \ No newline at end of file diff --git a/standards/lib/sitemap.xml.gz b/standards/lib/sitemap.xml.gz index 7140084..4a88da2 100644 Binary files a/standards/lib/sitemap.xml.gz and b/standards/lib/sitemap.xml.gz differ diff --git a/standards/mcp/client.json b/standards/mcp/client.json new file mode 100644 index 0000000..dcf6cf7 --- /dev/null +++ b/standards/mcp/client.json @@ -0,0 +1,102 @@ +{ + "project": "standards", + "template": "templates/client", + "components": [ + { + "kind": "client-package", + "path": "package.json", + "placeholder": "", + "description": "npm manifest: @aetoskia deps, scripts (dev/build/preview)." + }, + { + "kind": "client-npmrc", + "path": ".npmrc", + "placeholder": "", + "description": "Private registry auth pointing at npm.aetoskia.com." + }, + { + "kind": "client-env", + "path": ".env.example", + "placeholder": "", + "description": "VITE_API_BASE_URL / VITE_AUTH_BASE_URL seed." + }, + { + "kind": "client-vite-config", + "path": "vite.config.ts", + "placeholder": "", + "description": "Vite config (dev server, build)." + }, + { + "kind": "client-tsconfig", + "path": "tsconfig.json", + "placeholder": "", + "description": "TypeScript config for the client." + }, + { + "kind": "client-index-html", + "path": "index.html", + "placeholder": "", + "description": "HTML entry point." + }, + { + "kind": "client-entry", + "path": "src/main.jsx", + "placeholder": "", + "description": "React entry: router + providers + theme." + }, + { + "kind": "client-openapi-config", + "path": "src/openapi-config.ts", + "placeholder": "", + "description": "Points the admin renderer at the app spec + auth-server spec." + }, + { + "kind": "client-home", + "path": "src/Home.tsx", + "placeholder": "", + "description": "Auto-listing home page (ResourceCard + LiveTable per resource)." + }, + { + "kind": "client-header", + "path": "src/Header.tsx", + "placeholder": "", + "description": "App header bar (brand + nav)." + }, + { + "kind": "client-footer", + "path": "src/Footer.tsx", + "placeholder": "", + "description": "App footer." + }, + { + "kind": "client-vite-env", + "path": "src/vite-env.d.ts", + "placeholder": "", + "description": "Vite client type declarations." + }, + { + "kind": "client-theme", + "path": "src/shared-theme/AppTheme.tsx", + "placeholder": "", + "description": "Theme provider wrapper (light/dark)." + }, + { + "kind": "client-theme-config", + "path": "src/shared-theme/themeConfig.ts", + "placeholder": "", + "description": "Palette / typography tokens." + }, + { + "kind": "client-theme-primitives", + "path": "src/shared-theme/themePrimitives.ts", + "placeholder": "", + "description": "MUI theme primitives (shadows, accents)." + }, + { + "kind": "client-theme-shim", + "path": "src/shared-theme/mui.d.ts", + "placeholder": "", + "description": "MUI v5 type shims (Theme.vars, SelectClasses.focused)." + } + ] +} \ No newline at end of file diff --git a/standards/mcp/drone.json b/standards/mcp/drone.json index 88e1bea..630934a 100644 --- a/standards/mcp/drone.json +++ b/standards/mcp/drone.json @@ -3,6 +3,7 @@ "template": "templates/drone", "types": [ "pypi", + "npm", "docker" ], "components": [ @@ -12,6 +13,12 @@ "placeholder": "", "description": "Drone pipeline: build + publish a Python package to the private PyPI index." }, + { + "kind": "drone-npm", + "path": "npm-lib.yaml", + "placeholder": "", + "description": "Drone pipeline: build + publish an npm package to the private npm registry." + }, { "kind": "drone-service", "path": "service-docker.yaml", diff --git a/standards/mcp/modules/drone_pipelines.json b/standards/mcp/modules/drone_pipelines.json index 9cba6e0..0e5bf50 100644 --- a/standards/mcp/modules/drone_pipelines.json +++ b/standards/mcp/modules/drone_pipelines.json @@ -2,7 +2,7 @@ "module": "drone_pipelines", "content": { "path": "drone_pipelines", - "docstring": "# Drone Pipelines\n\n## Summary\n\nEvery Aetos repository ships a Drone CI definition at `.drone.yml`. There is\nexactly **one standard per repository**, and there are **two types of file**,\nchosen by what the repository produces:\n\n| Type | File | Produces | Repos |\n|------|------|----------|-------|\n| **A — PyPI package** | `templates/drone/python-lib.yaml` | A wheel + sdist on the private index | `dagpipe`, `doc-forge`, `hexa`, `mail-intake`, `mongo-ops`, `omniread`, `openapi-first`, `py-jwt` |\n| **B — Docker deployment** | `templates/drone/service-docker.yaml` | An image pushed to the registry and run as a container | `auth-server` |\n\nBoth templates run on `platform: linux / arm64` with the workspace at\n`/drone/src`. Copy the matching template to `/.drone.yml`; the Type A file\nneeds no edits, the Type B file needs its placeholders filled in (below).\n\n> Conventions: `.drone.yml` (not `.yaml`), one file per repo, secrets injected\n> with `from_secret` — never commit credentials.\n\n---\n\n## Type A — PyPI package (`python-lib.yaml`)\n\nFor internal libraries. The file contains **two pipelines**:\n\n1. **`build-and-publish-pypi`** — triggered on `tag`:\n - `check-version` — **guard**: fail unless `$DRONE_TAG` equals the version in\n `pyproject.toml`; then read `name` / `version` and query\n `$PIP_REPO_URL/simple//`; if that version already exists, exit\n `78` and skip the whole build (see [91 – Versioning & Changelog](91_versioning_and_changelog.md)).\n - `quality-gate` — install the package with its `[dev]` extras from the\n private index, then `black --check`, `ruff check`, `mypy`, `pydoclint`,\n `pytest`.\n - `build-package` — `python -m build` into `dist/`.\n - `upload-to-private-pypi` — `twine upload` to `$PIP_REPO_URL`.\n2. **`backfill-pypi-from-tags`** — triggered on `custom`:\n - `fetch-tags` — `git fetch --tags --force`.\n - `build-and-upload-missing` — walk every tag in version order, skip the ones\n already on the index, `git checkout` the rest, verify `tag == pyproject\n version` at that commit, build, and upload. This is the disaster-recovery /\n replay path.\n\nSecrets: `PIP_REPO_URL`, `PIP_USERNAME`, `PIP_PASSWORD`.\n\n- **Ship as-is.** Package name and version come from `pyproject.toml`, so the\n same file is reused verbatim across every library.\n\n---\n\n## Type B — Docker deployment (`service-docker.yaml`)\n\nFor a service that ships a container image — a long-running API/worker, e.g.\n`auth-server`. The file contains **one pipeline**, `build-and-deploy-service`,\ntriggered on `tag`:\n\n- `fetch-tags` — resolve the latest tag into `LATEST_TAG.txt`; fail if there\n are no tags.\n- `check-version` — **guard**: fail unless `$DRONE_TAG` equals the repo-root\n `VERSION` file (see [91 – Versioning & Changelog](91_versioning_and_changelog.md)).\n- `check-remote-image` — if `aetos/:` already exists locally, exit\n `78` and skip the build.\n- `quality-gate` — install from `requirements.txt` and run\n `black` / `ruff` / `mypy` / `pytest`.\n- `build-image` — `docker build` with the private-index build args, tagged\n `aetos/:` and `:latest`.\n- `push-image` — login, re-tag with `$REGISTRY_HOST`, push both tags.\n- `stop-old` — `docker rm -f `.\n- `run-container` — `docker run -d --name -p :\n --restart always` with the service's `-e` environment.\n\nSecrets: `PIP_REPO_URL`, `PIP_USERNAME`, `PIP_PASSWORD` (service build args),\n`REGISTRY_HOST`, `REGISTRY_USER`, `REGISTRY_PASS`, plus the service runtime env\n(for example `MONGO_*`, `JWT_SECRET`).\n\nPlaceholders to fill in per repo:\n\n| Placeholder | Meaning | Example |\n|-------------|---------|---------|\n| `` | service image / container name | `auth-server` |\n| `aetos/` | image repository on the registry | `aetos/auth-server` |\n| `` / `` | published : in-image port | `9003:8000` |\n| `` | runtime environment variable | `MONGO_HOST` |\n\n---\n\n## What not to do\n\n- Do not hand-roll a third shape. A repo is either Type A or Type B, never both.\n- Do not inline secrets; always use `from_secret`.\n- Do not drop the `check-version` / `check-remote-image` skip — it guards the\n index and the running container against duplicate publishes.\n- Do not drop the tag↔version guard. A package needs its `pyproject.toml`\n version to equal the tag; a service needs a root `VERSION` file that equals\n the tag. See [91 – Versioning & Changelog](91_versioning_and_changelog.md).\n- Do not rename the pipelines; tooling and runbooks key off\n `build-and-publish-pypi` and `build-and-deploy-service`.\n\n---\n\n## Related\n\n- [01 – Build Recipe](01_build_recipe.md) · [30 – Infra Adapters](30_infra_adaptors.md) · [91 – Versioning & Changelog](91_versioning_and_changelog.md) · [93 – Library Registry](93_library_registry.md)\n", + "docstring": "# Drone Pipelines\n\n## Summary\n\nEvery Aetos repository ships a Drone CI definition at `.drone.yml`. There is\nexactly **one standard per repository**, and there are **three types of file**,\nchosen by what the repository produces:\n\n| Type | File | Produces | Repos |\n|------|------|----------|-------|\n| **A — PyPI package** | `templates/drone/python-lib.yaml` | A wheel + sdist on the private index | `dagpipe`, `doc-forge`, `hexa`, `mail-intake`, `mongo-ops`, `omniread`, `openapi-first`, `py-jwt` |\n| **B — npm package** | `templates/drone/npm-lib.yaml` | A package published to the private npm registry | `doc-weaver`, `react-auth`, `react-openapi` |\n| **C — Docker deployment** | `templates/drone/service-docker.yaml` | An image pushed to the registry and run as a container | `auth-server`, `vet` |\n\nAll templates run on `platform: linux / arm64` with the workspace at\n`/drone/src`. Copy the matching template to `/.drone.yml`; the Type A and\nType B files need no edits, the Type C file needs its placeholders filled in\n(below).\n\n> Conventions: `.drone.yml` (not `.yaml`), one file per repo, secrets injected\n> with `from_secret` — never commit credentials.\n\n---\n\n## Type A — PyPI package (`python-lib.yaml`)\n\nFor internal Python libraries. The file contains **two pipelines**:\n\n1. **`build-and-publish-pypi`** — triggered on `tag`:\n - `check-version` — **guard**: fail unless `$DRONE_TAG` equals the version in\n `pyproject.toml`; then read `name` / `version` and query\n `$PIP_REPO_URL/simple//`; if that version already exists, exit\n `78` and skip the whole build (see [91 – Versioning & Changelog](91_versioning_and_changelog.md)).\n - `quality-gate` — install the package with its `[dev]` extras from the\n private index, then `black --check`, `ruff check`, `mypy`, `pydoclint`,\n `pytest`.\n - `build-package` — `python -m build` into `dist/`.\n - `upload-to-private-pypi` — `twine upload` to `$PIP_REPO_URL`.\n2. **`backfill-pypi-from-tags`** — triggered on `custom`:\n - `fetch-tags` — `git fetch --tags --force`.\n - `build-and-upload-missing` — walk every tag in version order, skip the ones\n already on the index, `git checkout` the rest, verify `tag == pyproject\n version` at that commit, build, and upload. This is the disaster-recovery /\n replay path.\n\nSecrets: `PIP_REPO_URL`, `PIP_USERNAME`, `PIP_PASSWORD`.\n\n- **Ship as-is.** Package name and version come from `pyproject.toml`, so the\n same file is reused verbatim across every library.\n\n---\n\n## Type B — npm package (`npm-lib.yaml`)\n\nFor internal npm libraries (the React packages). One pipeline,\n**`build-and-publish-npm`**, triggered on `tag`:\n\n- `check-version` — **guard**: fail unless `$DRONE_TAG` equals the version in\n `package.json`; query `$NPM_REPO_URL` for `name@version`; if it already\n exists, exit `78` and skip the whole build.\n- `quality-gate` — write `.npmrc` from the secrets, `npm install`, then\n `npm run quality-gate`.\n- `build-package` — `npm install && npm run build` into `dist/`.\n- `publish-to-private-npm` — `npm publish --access restricted` to\n `$NPM_REPO_URL`.\n\nSecrets: `NPM_REPO_URL`, `NPM_USERNAME`, `NPM_PASSWORD`. Auth is a generated\n`.npmrc` (`registry=` + `_auth=` base64 of `user:pass`) written from secrets at\nruntime — the committed `.npmrc` in a repo only points at the registry URL.\n\n- **Ship as-is.** Name and version come from `package.json`, so the same file\n is reused verbatim across every npm package.\n\n---\n\n## Type C — Docker deployment (`service-docker.yaml`)\n\nFor a service that ships a container image — a long-running API/worker, e.g.\n`auth-server`. The file contains **one pipeline**, `build-and-deploy-service`,\ntriggered on `tag`:\n\n- `fetch-tags` — resolve the latest tag into `LATEST_TAG.txt`; fail if there\n are no tags.\n- `check-version` — **guard**: fail unless `$DRONE_TAG` equals the repo-root\n `VERSION` file (see [91 – Versioning & Changelog](91_versioning_and_changelog.md)).\n- `check-remote-image` — if `aetos/:` already exists locally, exit\n `78` and skip the build.\n- `quality-gate` — install from `requirements.txt` and run\n `black` / `ruff` / `mypy` / `pytest`.\n- `build-image` — `docker build` with the private-index build args, tagged\n `aetos/:` and `:latest`.\n- `push-image` — login, re-tag with `$REGISTRY_HOST`, push both tags.\n- `stop-old` — `docker rm -f `.\n- `run-container` — `docker run -d --name -p :\n --restart always` with the service's `-e` environment.\n\nSecrets: `PIP_REPO_URL`, `PIP_USERNAME`, `PIP_PASSWORD` (service build args),\n`REGISTRY_HOST`, `REGISTRY_USER`, `REGISTRY_PASS`, plus the service runtime env\n(for example `MONGO_*`, `JWT_SECRET`).\n\nPlaceholders to fill in per repo:\n\n| Placeholder | Meaning | Example |\n|-------------|---------|---------|\n| `` | service image / container name | `auth-server` |\n| `aetos/` | image repository on the registry | `aetos/auth-server` |\n| `` / `` | published : in-image port | `9003:8000` |\n| `` | runtime environment variable | `MONGO_HOST` |\n\n---\n\n## What not to do\n\n- Do not hand-roll a fourth shape. A repo is exactly one of Type A, B, or C,\n never combinations.\n- Do not inline secrets; always use `from_secret`.\n- Do not drop the `check-version` / `check-remote-image` skip — it guards the\n index and the running container against duplicate publishes.\n- Do not drop the tag↔version guard. A Python package needs its\n `pyproject.toml` version to equal the tag; an npm package needs its\n `package.json` version; a service needs a root `VERSION` file. See\n [91 – Versioning & Changelog](91_versioning_and_changelog.md).\n- Do not rename the pipelines; tooling and runbooks key off\n `build-and-publish-pypi`, `build-and-publish-npm`, and\n `build-and-deploy-service`.\n\n---\n\n## Related\n\n- [01 – Build Recipe](01_build_recipe.md) · [30 – Infra Adapters](30_infra_adaptors.md) · [91 – Versioning & Changelog](91_versioning_and_changelog.md) · [93 – Library Registry](93_library_registry.md)\n", "objects": {} } } \ No newline at end of file diff --git a/standards/mcp/modules/index.json b/standards/mcp/modules/index.json index 92cb6ff..4bd5073 100644 --- a/standards/mcp/modules/index.json +++ b/standards/mcp/modules/index.json @@ -2,7 +2,7 @@ "module": "index", "content": { "path": "index", - "docstring": "# Standards Reference\n\nThe reference half of the Standards description: the enforceable rules,\npatterns, and the internal library catalog that agents consult while coding.\n\nThe reference is organized as an **anatomy** — one entry checklist and four\npillars describing what an application is made of, plus delivery/meta pages\nand an optional pipelines layer.\n\n## Anatomy\n\n- **Build Recipe** — the ordered, agentic checklist for a new app; the entry\n point that walks the whole anatomy.\n\n## Pillar 1 — Domains\n\n- **Layering Rules** — the strict request → domain → repository layering and\n the rules that enforce it.\n\n## Pillar 2 — OpenAPI Spec (the contract)\n\n- **Composition Root** — a single composition point wiring the whole app.\n- **Spec-First Routing** — the OpenAPI contract as the routing source of truth.\n- **CRUD Template** — the standardized generic resource endpoint scaffold.\n- **Auth Integration** — consuming the shared auth-server service (spec-driven,\n no auth code).\n\n## Pillar 3 — Interfaces & Infra\n\n- **Infra Adapters** — how infrastructure connects without leaking into domain.\n\n## Pillar 4 — UI\n\n- **UI: Auto-Rendered Admin & Custom Pages** — the `@aetoskia/react-openapi`\n admin rendered from the spec's x- extensions, and `@aetoskia/react-auth`\n for auth pages; the client template scaffold.\n\n## Pipelines (optional layer)\n\n- **Pipeline Scaffold** — the deterministic pipeline skeleton for multi-stage\n jobs.\n- **Worker & Progress** — queued work, progress reporting, and visibility.\n- **Human-in-the-Loop** — guardrails and approvals inside automations.\n\n## Delivery & Meta\n\n- **Drone Pipelines** — the two CI shapes: a PyPI/npm package or a Docker\n deployment.\n- **Versioning & Changelog** — SemVer, the tag↔version contract, and the\n release changelog.\n- **Repository Inventory** — every covered repo, its type, version source, and\n Drone shape.\n- **Genericity Matrix** — what is library-backed, template-provided, or\n authored.\n- **Library Registry** — the catalog of internal libraries behind all of it.\n\nRead the **Wiki** for the philosophy and rationale; these pages are the\nreference that mirrors the `standards` MCP bundle.\n", + "docstring": "# Standards Reference\n\nThe reference half of the Standards description: the enforceable rules,\npatterns, and the internal library catalog that agents consult while coding.\n\nThe reference is organized as an **anatomy** — one entry checklist and four\npillars describing what an application is made of, plus delivery/meta pages\nand an optional pipelines layer.\n\n## Anatomy\n\n- **Build Recipe** — the ordered, agentic checklist for a new app; the entry\n point that walks the whole anatomy.\n\n## Pillar 1 — Domains\n\n- **Layering Rules** — the strict request → domain → repository layering and\n the rules that enforce it.\n\n## Pillar 2 — OpenAPI Spec (the contract)\n\n- **Composition Root** — a single composition point wiring the whole app.\n- **Spec-First Routing** — the OpenAPI contract as the routing source of truth.\n- **CRUD Template** — the standardized generic resource endpoint scaffold.\n- **Auth Integration** — consuming the shared auth-server service (spec-driven,\n no auth code).\n\n## Pillar 3 — Interfaces & Infra\n\n- **Infra Adapters** — how infrastructure connects without leaking into domain.\n\n## Pillar 4 — UI\n\n- **UI: Auto-Rendered Admin & Custom Pages** — the `@aetoskia/react-openapi`\n admin rendered from the spec's x- extensions, and `@aetoskia/react-auth`\n for auth pages; the client template scaffold.\n\n## Pipelines (optional layer)\n\n- **Pipeline Scaffold** — the deterministic pipeline skeleton for multi-stage\n jobs.\n- **Worker & Progress** — queued work, progress reporting, and visibility.\n- **Human-in-the-Loop** — guardrails and approvals inside automations.\n\n## Delivery & Meta\n\n- **Drone Pipelines** — the three CI shapes: a PyPI package, an npm package,\n or a Docker deployment.\n- **Versioning & Changelog** — SemVer, the tag↔version contract, and the\n release changelog.\n- **Repository Inventory** — every covered repo, its type, version source, and\n Drone shape.\n- **Genericity Matrix** — what is library-backed, template-provided, or\n authored.\n- **Library Registry** — the catalog of internal libraries behind all of it.\n\nRead the **Wiki** for the philosophy and rationale; these pages are the\nreference that mirrors the `standards` MCP bundle.\n", "objects": {} } } \ No newline at end of file diff --git a/standards/mcp/modules/repository_inventory.json b/standards/mcp/modules/repository_inventory.json index fbd3b0e..2131e3b 100644 --- a/standards/mcp/modules/repository_inventory.json +++ b/standards/mcp/modules/repository_inventory.json @@ -2,7 +2,7 @@ "module": "repository_inventory", "content": { "path": "repository_inventory", - "docstring": "# Repository Inventory\n\n## Summary\n\nThe canonical list of Aetos repositories covered by the CI and versioning\nstandards, with the artifact each one produces, its version source, and its\nDrone shape. Every entry maps to the contract in\n[91 – Versioning & Changelog](91_versioning_and_changelog.md) and the two CI\nfiles in [90 – Drone Pipelines](90_drone_pipelines.md).\n\nThe same data is published machine-readably as the `registry://repos` MCP\nresource (and the `list_repos` tool), sourced from `standards/src/repos.json`.\nPaths are relative to the `aetos/` workspace root.\n\n---\n\n## Packages (Type A)\n\nA wheel + sdist published to the private index. Version source is\n`pyproject.toml`; Drone file is `python-lib.yaml` (tag-triggered).\n\n| Repo | Path | Docs | MCP server |\n|------|------|------|------------|\n| `dagpipe` | `dagpipe` | lib, wiki | `dagpipe:8006` |\n| `doc-forge` | `doc-forge` | lib, wiki | `docforge:8001` |\n| `hexa` | `hexa` | lib, wiki | `hexa:8008` |\n| `mail-intake` | `mail-intake` | lib, wiki | `mail_intake:8002` |\n| `mongo-ops` | `mongo-ops` | lib, wiki | `mongo_ops:8007` |\n| `omniread` | `omniread` | lib, wiki | `omniread:8003` |\n| `openapi-first` | `openapi-first` | lib, wiki | `openapi_first:8004` |\n| `py-jwt` | `py-jwt` | lib, wiki | `jwtlib:8005` |\n\n---\n\n## Services (Type B)\n\nA container image pushed to the registry and run on the Docker host. Version\nsource is the `VERSION` file; Drone file is `service-docker.yaml`.\n\n| Repo | Path | Trigger | Docs |\n|------|------|---------|------|\n| `auth-server` | `auth-server` | tag | api, lib, wiki |\n\nTag-triggered and enforces `tag == VERSION`.\n\n---\n\n## Required files per repo\n\n| Type | Version source | Changelog | Drone |\n|------|----------------|-----------|-------|\n| package | `pyproject.toml` | `CHANGELOG.md` | `python-lib.yaml` |\n| service | `VERSION` | `CHANGELOG.md` | `service-docker.yaml` |\n\nEvery covered repository must be able to satisfy `tag == version`:\nthe version file (never a commit id) is bumped in the release MR, the MR is\nmerged, and the tag is created on the merged commit.\n\n---\n\n## Reading this at runtime\n\n- Resource: `registry://repos`\n- Tool: `list_repos()`\n- Humans: this page (mirror of `standards/src/repos.json`).\n\n---\n\n## Related\n\n- [90 – Drone Pipelines](90_drone_pipelines.md) · [91 – Versioning & Changelog](91_versioning_and_changelog.md) · [93 – Library Registry](93_library_registry.md)\n", + "docstring": "# Repository Inventory\n\n## Summary\n\nThe canonical list of Aetos repositories covered by the CI and versioning\nstandards, with the artifact each one produces, its version source, and its\nDrone shape. Every entry maps to the contract in\n[91 – Versioning & Changelog](91_versioning_and_changelog.md) and the three CI\nfiles in [90 – Drone Pipelines](90_drone_pipelines.md).\n\nThe same data is published machine-readably as the `registry://repos` MCP\nresource (and the `list_repos` tool), sourced from `standards/src/repos.json`.\nPaths are relative to the `aetos/` workspace root.\n\n---\n\n## Packages (Type A — PyPI)\n\nA wheel + sdist published to the private index. Version source is\n`pyproject.toml`; Drone file is `python-lib.yaml` (tag-triggered).\n\n| Repo | Path | Docs | MCP server |\n|------|------|------|------------|\n| `dagpipe` | `dagpipe` | lib, wiki | `dagpipe:8006` |\n| `doc-forge` | `doc-forge` | lib, wiki | `docforge:8001` |\n| `hexa` | `hexa` | lib, wiki | `hexa:8008` |\n| `mail-intake` | `mail-intake` | lib, wiki | `mail_intake:8002` |\n| `mongo-ops` | `mongo-ops` | lib, wiki | `mongo_ops:8007` |\n| `omniread` | `omniread` | lib, wiki | `omniread:8003` |\n| `openapi-first` | `openapi-first` | lib, wiki | `openapi_first:8004` |\n| `py-jwt` | `py-jwt` | lib, wiki | `jwtlib:8005` |\n\n---\n\n## Packages (Type B — npm)\n\nA package published to the private npm registry (`npm.aetoskia.com`). Version\nsource is `package.json`; Drone file is `npm-lib.yaml` (tag-triggered).\n\n| Repo | Path | Docs | MCP server |\n|------|------|------|------------|\n| `doc-weaver` | `doc-weaver` | lib, wiki | `doc-weaver:8010` |\n| `react-auth` | `react/react-auth` | lib, wiki | `react-auth:8011` |\n| `react-openapi` | `react/react-openapi` | lib, wiki | `react-openapi:8012` |\n\n---\n\n## Services & Apps (Type C)\n\nA container image pushed to the registry and run on the Docker host. Version\nsource is the `VERSION` file; Drone file is `service-docker.yaml`.\n\n| Repo | Path | Type | Trigger | Docs |\n|------|------|------|---------|------|\n| `auth-server` | `auth-server` | service | tag | api, lib, wiki |\n| `vet` | `react/vet` | app | tag | lib, wiki |\n\nTag-triggered and enforces `tag == VERSION`.\n\n---\n\n## Required files per repo\n\n| Type | Version source | Changelog | Drone |\n|------|----------------|-----------|-------|\n| package (PyPI) | `pyproject.toml` | `CHANGELOG.md` | `python-lib.yaml` |\n| package (npm) | `package.json` | `CHANGELOG.md` | `npm-lib.yaml` |\n| service / app | `VERSION` | `CHANGELOG.md` | `service-docker.yaml` |\n\nEvery covered repository must be able to satisfy `tag == version`:\nthe version file (never a commit id) is bumped in the release MR, the MR is\nmerged, and the tag is created on the merged commit.\n\n---\n\n## Reading this at runtime\n\n- Resource: `registry://repos`\n- Tool: `list_repos()`\n- Humans: this page (mirror of `standards/src/repos.json`).\n\n---\n\n## Related\n\n- [90 – Drone Pipelines](90_drone_pipelines.md) · [91 – Versioning & Changelog](91_versioning_and_changelog.md) · [93 – Library Registry](93_library_registry.md)\n", "objects": {} } } \ No newline at end of file diff --git a/standards/mcp/modules/versioning_and_changelog.json b/standards/mcp/modules/versioning_and_changelog.json index 1739932..7df1be0 100644 --- a/standards/mcp/modules/versioning_and_changelog.json +++ b/standards/mcp/modules/versioning_and_changelog.json @@ -2,7 +2,7 @@ "module": "versioning_and_changelog", "content": { "path": "versioning_and_changelog", - "docstring": "# Versioning & Changelog\n\n## Summary\n\nEvery Aetos artifact — library or service — is versioned with\n[Semantic Versioning](https://semver.org/spec/v2.0.0.html) and documents its\nreleases in a [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) file.\nThe **version file is the source of truth**, the **git tag must equal it**, and\na Drone guard enforces that equality before anything is published. Releases are\ncut manually; a tag is what triggers the pipeline.\n\nThis page pairs with [90 – Drone Pipelines](90_drone_pipelines.md): the version\nand tag contract is exactly what those two CI shapes consume.\n\n---\n\n## The version contract\n\n| Artifact | Source of truth | Notes |\n|----------|-----------------|-------|\n| Library (PyPI package) | `version` in `pyproject.toml` | `check-version` also reads it to skip duplicates |\n| Service (Docker) | `VERSION` file at the repo root | one line, `x.y.z`; the service **reads** it (build-arg) — never hardcode the version |\n\nRules:\n\n1. **One version per repository.** No per-module versions.\n2. **Tag = version.** The git tag is bare SemVer (`0.0.6`), no `v` prefix, and\n it MUST match the version file byte-for-byte. The Drone guard fails the\n build otherwise — this is what stops a tag from silently publishing nothing.\n3. **A release is a tag, created after the change is merged.** The version bump\n and the changelog promotion travel inside the merge request (MR); the tag is\n added on the merged commit and pushed. See [Tagging strategy](#tagging-strategy-mr-based).\n4. **Never reuse a tag.** If a release is wrong, cut a new patch version.\n\n### Pre-1.0 (0.y.z)\n\nWhile a package is `0.y.z`, **`0.y` is treated as the major line**:\n\n- breaking change → `0.(y+1).0`\n- new feature → `0.y.(z+1)`\n- bug fix → `0.y.(z+1)`\n\nOnce a package reaches `1.0.0`, normal SemVer applies. Do not ship `1.0.0`\nuntil the public API is considered stable.\n\n---\n\n## The changelog\n\n`CHANGELOG.md` at the repo root, in Keep a Changelog form. It always has exactly\none open `[Unreleased]` section with the change categories that apply:\n\n```markdown\n## [Unreleased]\n\n### Added\n### Changed\n### Deprecated\n### Removed\n### Fixed\n### Security\n```\n\nOn release you **promote** it — never delete history:\n\n```markdown\n## [0.0.6] - 2026-03-07\n\n### Added\n- ...\n```\n\nand add a link reference at the bottom:\n\n```markdown\n[Unreleased]: https://git.aetoskia.com/aetos//compare/0.0.6...HEAD\n[0.0.6]: https://git.aetoskia.com/aetos//compare/0.0.5...0.0.6\n```\n\nConventions:\n\n- Write entries for humans: one line each, imperative, referencing the user\n impact, not the commit hash.\n- Categories: **Added**, **Changed**, **Deprecated**, **Removed**, **Fixed**,\n **Security**. Omit empty categories.\n- Security fixes get their own entry even if the change is otherwise a bug fix.\n- Keep `[Unreleased]` current: add an entry in the same change that introduces\n the behaviour, not later.\n- The `[Unreleased]` heading is never renamed; copy its content into the new\n version heading and clear it.\n\n### Reconcile before releasing\n\n`[Unreleased]` is a **draft, not the source of truth**. It is only trustworthy\nwhen it was maintained alongside each change; a long-running branch or a change\nthat skipped the changelog leaves it stale, so it can silently under-report a\nrelease. Verify it against the change before you promote:\n\n1. List what actually changed since the last release:\n `git log ..HEAD` and `git diff --stat ..HEAD`.\n2. Compare that against `[Unreleased]`; add an entry for every user-facing change\n that is missing.\n3. **Always show the proposed additions to the user and wait for approval**\n before promoting. If an entry is ambiguous, ask rather than guess.\n\nOnly then promote. Never cut a release with a known gap between the diff and the\nchangelog.\n\n---\n\n## Tagging strategy (MR-based)\n\nThe release version is known while the change is still a merge request, so the\nbump travels with the change and only the tag is added afterwards:\n\n1. **In the MR** — reconcile `[Unreleased]` against the change (see\n [Reconcile before releasing](#reconcile-before-releasing)) and get the user's\n approval for any additions. Then set the intended release version: `version`\n in `pyproject.toml` (or the `VERSION` file) to `x.y.z`, and promote the\n changelog (below). Changelog entries and link references name the\n **version/tag**, never a commit id.\n2. **Merge or squash** the MR into `main`.\n3. **Create the tag** `x.y.z` on the resulting commit (the merge/squash commit).\n4. **Push the tag** (`git push origin x.y.z`) — Drone builds the release.\n\nBecause the version bump is inside the tagged commit, the guard's\n`tag == version` check can only fail if the wrong commit was tagged.\n\n### Agent-assisted tagging\n\nThe agent neither authors nor merges the MR, and never tags before the merge.\nAfter the user confirms the MR is merged/squashed and says to proceed:\n\n1. **Wait** for that explicit go-ahead.\n2. Find the commit that introduced the version bump:\n - packages:\n `git log -S 'version = \"x.y.z\"' -n 1 --format='%H %s' -- pyproject.toml`\n - services:\n `git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION`\n3. Confirm that commit's version file equals `x.y.z`, then tag **only** that\n commit, lightweight and bare: `git tag x.y.z `.\n4. **Do not push.** Ask the user to push the tag: `git push origin x.y.z`.\n\n---\n\n## Release checklist\n\n1. Confirm the quality gate is green and `main` is up to date.\n2. In the MR: reconcile `[Unreleased]` against the change being released —\n `git log ..HEAD` and `git diff --stat ..HEAD` — add any\n missing user-facing entries, and get the user's approval for the additions.\n Then move every `[Unreleased]` entry under the new version heading with the\n target date (`## [x.y.z] - YYYY-MM-DD`) and restore an empty `[Unreleased]`\n on top.\n3. In the MR: add the two compare-link references at the bottom of the\n changelog, naming the version/tag (never a commit id).\n4. In the MR: set the version file — `pyproject.toml` (`version = \"x.y.z\"`) or\n `VERSION` — to the intended release version.\n5. Merge or squash the MR into `main`.\n6. Create the tag on the resulting commit: lightweight `git tag x.y.z`.\n7. Push the tag (`git push origin x.y.z`). Watch Drone: Type A publishes the\n wheel/sdist, Type B builds and deploys the image; both first assert\n `tag == version`.\n8. Do not reuse the tag if the run fails — fix and cut `x.y.(z+1)`.\n\n---\n\n## Why the guard matters\n\nThe version file and the tag are two facts that must agree; nothing in git\nenforces that by itself. A mismatch is not a theoretical risk — a package can be\ntagged `0.0.2` while its `pyproject.toml` still says `0.0.1`, and the publish\nstep (which compares the **file** against the index) then skips the build\nentirely, so `0.0.2` never reaches the index while looking like a release. The\nDrone guard turns that silent no-op into a hard failure.\n\n---\n\n## Related\n\n- [90 – Drone Pipelines](90_drone_pipelines.md) · [94 – Repository Inventory](94_repository_inventory.md) · [01 – Build Recipe](01_build_recipe.md) · [93 – Library Registry](93_library_registry.md)\n", + "docstring": "# Versioning & Changelog\n\n## Summary\n\nEvery Aetos artifact — library or service — is versioned with\n[Semantic Versioning](https://semver.org/spec/v2.0.0.html) and documents its\nreleases in a [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) file.\nThe **version file is the source of truth**, the **git tag must equal it**, and\na Drone guard enforces that equality before anything is published. Releases are\ncut manually; a tag is what triggers the pipeline.\n\nThis page pairs with [90 – Drone Pipelines](90_drone_pipelines.md): the version\nand tag contract is exactly what those three CI shapes consume.\n\n---\n\n## The version contract\n\n| Artifact | Source of truth | Notes |\n|----------|-----------------|-------|\n| Library (PyPI package) | `version` in `pyproject.toml` | `check-version` also reads it to skip duplicates |\n| Library (npm package) | `version` in `package.json` | `check-version` also queries the registry to skip duplicates |\n| Service (Docker) | `VERSION` file at the repo root | one line, `x.y.z`; the service **reads** it (build-arg) — never hardcode the version |\n\nRules:\n\n1. **One version per repository.** No per-module versions.\n2. **Tag = version.** The git tag is bare SemVer (`0.0.6`), no `v` prefix, and\n it MUST match the version file byte-for-byte. The Drone guard fails the\n build otherwise — this is what stops a tag from silently publishing nothing.\n3. **A release is a tag, created after the change is merged.** The version bump\n and the changelog promotion travel inside the merge request (MR); the tag is\n added on the merged commit and pushed. See [Tagging strategy](#tagging-strategy-mr-based).\n4. **Never reuse a tag.** If a release is wrong, cut a new patch version.\n\n### Pre-1.0 (0.y.z)\n\nWhile a package is `0.y.z`, **`0.y` is treated as the major line**:\n\n- breaking change → `0.(y+1).0`\n- new feature → `0.y.(z+1)`\n- bug fix → `0.y.(z+1)`\n\nOnce a package reaches `1.0.0`, normal SemVer applies. Do not ship `1.0.0`\nuntil the public API is considered stable.\n\n---\n\n## The changelog\n\n`CHANGELOG.md` at the repo root, in Keep a Changelog form. It always has exactly\none open `[Unreleased]` section with the change categories that apply:\n\n```markdown\n## [Unreleased]\n\n### Added\n### Changed\n### Deprecated\n### Removed\n### Fixed\n### Security\n```\n\nOn release you **promote** it — never delete history:\n\n```markdown\n## [0.0.6] - 2026-03-07\n\n### Added\n- ...\n```\n\nand add a link reference at the bottom:\n\n```markdown\n[Unreleased]: https://git.aetoskia.com/aetos//compare/0.0.6...HEAD\n[0.0.6]: https://git.aetoskia.com/aetos//compare/0.0.5...0.0.6\n```\n\nConventions:\n\n- Write entries for humans: one line each, imperative, referencing the user\n impact, not the commit hash.\n- Categories: **Added**, **Changed**, **Deprecated**, **Removed**, **Fixed**,\n **Security**. Omit empty categories.\n- Security fixes get their own entry even if the change is otherwise a bug fix.\n- Keep `[Unreleased]` current: add an entry in the same change that introduces\n the behaviour, not later.\n- The `[Unreleased]` heading is never renamed; copy its content into the new\n version heading and clear it.\n\n### Reconcile before releasing\n\n`[Unreleased]` is a **draft, not the source of truth**. It is only trustworthy\nwhen it was maintained alongside each change; a long-running branch or a change\nthat skipped the changelog leaves it stale, so it can silently under-report a\nrelease. Verify it against the change before you promote:\n\n1. List what actually changed since the last release:\n `git log ..HEAD` and `git diff --stat ..HEAD`.\n2. Compare that against `[Unreleased]`; add an entry for every user-facing change\n that is missing.\n3. **Always show the proposed additions to the user and wait for approval**\n before promoting. If an entry is ambiguous, ask rather than guess.\n\nOnly then promote. Never cut a release with a known gap between the diff and the\nchangelog.\n\n---\n\n## Tagging strategy (MR-based)\n\nThe release version is known while the change is still a merge request, so the\nbump travels with the change and only the tag is added afterwards:\n\n1. **In the MR** — reconcile `[Unreleased]` against the change (see\n [Reconcile before releasing](#reconcile-before-releasing)) and get the user's\n approval for any additions. Then set the intended release version: `version`\n in `pyproject.toml` or `package.json` (or the `VERSION` file) to `x.y.z`,\n and promote the\n changelog (below). Changelog entries and link references name the\n **version/tag**, never a commit id.\n2. **Merge or squash** the MR into `main`.\n3. **Create the tag** `x.y.z` on the resulting commit (the merge/squash commit).\n4. **Push the tag** (`git push origin x.y.z`) — Drone builds the release.\n\nBecause the version bump is inside the tagged commit, the guard's\n`tag == version` check can only fail if the wrong commit was tagged.\n\n### Agent-assisted tagging\n\nThe agent neither authors nor merges the MR, and never tags before the merge.\nAfter the user confirms the MR is merged/squashed and says to proceed:\n\n1. **Wait** for that explicit go-ahead.\n2. Find the commit that introduced the version bump:\n - Python packages:\n `git log -S 'version = \"x.y.z\"' -n 1 --format='%H %s' -- pyproject.toml`\n - npm packages:\n `git log -S '\"version\": \"x.y.z\"' -n 1 --format='%H %s' -- package.json`\n - services:\n `git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION`\n3. Confirm that commit's version file equals `x.y.z`, then tag **only** that\n commit, lightweight and bare: `git tag x.y.z `.\n4. **Do not push.** Ask the user to push the tag: `git push origin x.y.z`.\n\n---\n\n## Release checklist\n\n1. Confirm the quality gate is green and `main` is up to date.\n2. In the MR: reconcile `[Unreleased]` against the change being released —\n `git log ..HEAD` and `git diff --stat ..HEAD` — add any\n missing user-facing entries, and get the user's approval for the additions.\n Then move every `[Unreleased]` entry under the new version heading with the\n target date (`## [x.y.z] - YYYY-MM-DD`) and restore an empty `[Unreleased]`\n on top.\n3. In the MR: add the two compare-link references at the bottom of the\n changelog, naming the version/tag (never a commit id).\n4. In the MR: set the version file — `pyproject.toml` (`version = \"x.y.z\"`),\n `package.json` (`\"version\": \"x.y.z\"`), or `VERSION` — to the intended\n release version.\n5. Merge or squash the MR into `main`.\n6. Create the tag on the resulting commit: lightweight `git tag x.y.z`.\n7. Push the tag (`git push origin x.y.z`). Watch Drone: Type A publishes the\n wheel/sdist, Type B publishes the npm package, Type C builds and deploys\n the image; all three first assert `tag == version`.\n8. Do not reuse the tag if the run fails — fix and cut `x.y.(z+1)`.\n\n---\n\n## Why the guard matters\n\nThe version file and the tag are two facts that must agree; nothing in git\nenforces that by itself. A mismatch is not a theoretical risk — a package can be\ntagged `0.0.2` while its `pyproject.toml` still says `0.0.1`, and the publish\nstep (which compares the **file** against the index) then skips the build\nentirely, so `0.0.2` never reaches the index while looking like a release. The\nDrone guard turns that silent no-op into a hard failure.\n\n---\n\n## Related\n\n- [90 – Drone Pipelines](90_drone_pipelines.md) · [94 – Repository Inventory](94_repository_inventory.md) · [01 – Build Recipe](01_build_recipe.md) · [93 – Library Registry](93_library_registry.md)\n", "objects": {} } } \ No newline at end of file diff --git a/standards/mcp/repos.json b/standards/mcp/repos.json index 9456f1c..8f0361d 100644 --- a/standards/mcp/repos.json +++ b/standards/mcp/repos.json @@ -1,6 +1,6 @@ { "project": "standards", - "note": "Machine-readable repository inventory. Mirrors standards/src/lib/15_repository_inventory.md. Read it with the registry://repos resource or the list_repos tool.", + "note": "Machine-readable repository inventory. Mirrors standards/src/lib/94_repository_inventory.md. Read it with the registry://repos resource or the list_repos tool.", "path_convention": "relative to the aetos/ workspace root", "repos": [ { @@ -35,6 +35,22 @@ "port": 8001 } }, + { + "name": "doc-weaver", + "type": "package", + "path": "doc-weaver", + "version_source": "package.json", + "drone": "npm-lib.yaml", + "trigger": "tag", + "docs": [ + "lib", + "wiki" + ], + "mcp": { + "server": "doc-weaver", + "port": 8010 + } + }, { "name": "hexa", "type": "package", @@ -131,6 +147,38 @@ "port": 8005 } }, + { + "name": "react-auth", + "type": "package", + "path": "react/react-auth", + "version_source": "package.json", + "drone": "npm-lib.yaml", + "trigger": "tag", + "docs": [ + "lib", + "wiki" + ], + "mcp": { + "server": "react-auth", + "port": 8011 + } + }, + { + "name": "react-openapi", + "type": "package", + "path": "react/react-openapi", + "version_source": "package.json", + "drone": "npm-lib.yaml", + "trigger": "tag", + "docs": [ + "lib", + "wiki" + ], + "mcp": { + "server": "react-openapi", + "port": 8012 + } + }, { "name": "auth-server", "type": "service", @@ -144,6 +192,19 @@ "wiki" ], "mcp": null + }, + { + "name": "vet", + "type": "app", + "path": "react/vet", + "version_source": "VERSION", + "drone": "service-docker.yaml", + "trigger": "tag", + "docs": [ + "lib", + "wiki" + ], + "mcp": null } ] } \ No newline at end of file diff --git a/standards/mcp/templates/client/.env.example b/standards/mcp/templates/client/.env.example new file mode 100644 index 0000000..996e6f8 --- /dev/null +++ b/standards/mcp/templates/client/.env.example @@ -0,0 +1,2 @@ +VITE_API_BASE_URL=http://localhost:8000 +VITE_AUTH_BASE_URL=http://localhost:8000 diff --git a/standards/mcp/templates/client/.gitignore b/standards/mcp/templates/client/.gitignore new file mode 100644 index 0000000..434c113 --- /dev/null +++ b/standards/mcp/templates/client/.gitignore @@ -0,0 +1,21 @@ +# See https://help.github.com/articles/ignoring-files/ for more about ignoring files. + +.env +# dependencies +node_modules + +# React Router +.react-router +build + +# misc +.DS_Store +dist +dist-ssr +*.local +.idea +tsconfig.tsbuildinfo + +# generated documentation +docs/mcp +site/ diff --git a/standards/mcp/templates/client/.npmrc b/standards/mcp/templates/client/.npmrc new file mode 100644 index 0000000..a412fd6 --- /dev/null +++ b/standards/mcp/templates/client/.npmrc @@ -0,0 +1 @@ +registry=https://npm.aetoskia.com diff --git a/standards/mcp/templates/client/CHANGELOG.md b/standards/mcp/templates/client/CHANGELOG.md new file mode 100644 index 0000000..3973a5a --- /dev/null +++ b/standards/mcp/templates/client/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +All notable changes to this project are documented here. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + + + +## [Unreleased] diff --git a/standards/mcp/templates/client/index.html b/standards/mcp/templates/client/index.html new file mode 100644 index 0000000..51be3f3 --- /dev/null +++ b/standards/mcp/templates/client/index.html @@ -0,0 +1,13 @@ + + + + + + + App Title + + +
        + + + diff --git a/standards/mcp/templates/client/package.json b/standards/mcp/templates/client/package.json new file mode 100644 index 0000000..02fee5a --- /dev/null +++ b/standards/mcp/templates/client/package.json @@ -0,0 +1,34 @@ +{ + "name": "client-template", + "private": true, + "version": "0.1.0", + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc -b && vite build", + "preview": "vite preview", + "quality-gate": "tsc --noEmit" + }, + "dependencies": { + "@aetoskia/react-auth": "^0.1.0", + "@aetoskia/react-openapi": "^0.1.0", + "@emotion/react": "^11.13.3", + "@emotion/styled": "^11.13.0", + "@mui/icons-material": "^5.16.7", + "@mui/material": "^5.16.7", + "axios": "^1.7.7", + "js-yaml": "^4.1.0", + "react": "^18.3.1", + "react-dom": "^18.3.1", + "react-router-dom": "^6.28.0" + }, + "devDependencies": { + "@types/js-yaml": "^4.0.9", + "@types/node": "^25.9.3", + "@types/react": "^18.3.12", + "@types/react-dom": "^18.3.1", + "@vitejs/plugin-react": "^4.3.4", + "typescript": "~5.6.2", + "vite": "^6.0.1" + } +} diff --git a/standards/mcp/templates/client/src/Footer.tsx b/standards/mcp/templates/client/src/Footer.tsx new file mode 100644 index 0000000..564c0b5 --- /dev/null +++ b/standards/mcp/templates/client/src/Footer.tsx @@ -0,0 +1,66 @@ +/** + * Site footer. + * + * A fixed bottom `AppBar` (pinned above the drawer via + * `zIndex.drawer + 1`) with a blurred translucent background and a top + * divider, rendering the `Copyright` line. Rendered once by `main.jsx` below + * the routed content. + * + * @packageDocumentation + */ + +import * as React from 'react'; +import Container from '@mui/material/Container'; +import Link from '@mui/material/Link'; +import Typography from '@mui/material/Typography'; +import { AppBar, Toolbar } from "@mui/material"; + +/** Copyright line linking to aetoskia.com with the current year. */ +function Copyright() { + return ( + + + {'Copyright © Aetoskia Internal Infrastructure — All rights reserved.'} + +   + {new Date().getFullYear()} + + ); +} + +/** + * Fixed bottom app bar showing the site copyright. + * + * @returns The footer `AppBar` element. + */ +export default function Footer() { + return ( + theme.zIndex.drawer + 1, + backdropFilter: 'blur(8px)', + boxShadow: 'none', + borderTop: '1px solid', + borderColor: 'divider', + }} + > + + + + + + + ); +} diff --git a/standards/mcp/templates/client/src/Header.tsx b/standards/mcp/templates/client/src/Header.tsx new file mode 100644 index 0000000..81e9e79 --- /dev/null +++ b/standards/mcp/templates/client/src/Header.tsx @@ -0,0 +1,83 @@ +/** + * Top navigation bar. + * + * A fixed `AppBar` with blurred translucent background and bottom divider, + * showing the app title/logo, the signed-in user (or a login button), and + * an Admin button. Rendered once by `main.jsx` above the routed content; + * the title navigates to `/` and the Admin button to `/admin`. + * + * @packageDocumentation + */ + +import * as React from "react"; +import { AppBar, Toolbar, Typography, Button, Chip, IconButton, Tooltip } from "@mui/material"; +import { useNavigate } from "react-router-dom"; +import DashboardIcon from "@mui/icons-material/Dashboard"; +import LogoutIcon from "@mui/icons-material/Logout"; +import { useAuth } from "@aetoskia/react-auth"; + +/** + * Fixed top app bar with the title/logo, current user, and an Admin button. + * + * Uses `useNavigate` and `useAuth`, so it must be rendered inside both a + * router and an `AuthProvider`. Clicking the title navigates to `/`; the + * Admin button navigates to `/admin`; the logout icon clears the session. + * + * @returns The header `AppBar` element. + */ +export default function Header() { + const navigate = useNavigate(); + const { currentUser, logout } = useAuth(); + + return ( + theme.zIndex.drawer + 1, + backdropFilter: "blur(8px)", + boxShadow: "none", + borderBottom: "1px solid", + borderColor: "divider", + }} + > + + + navigate("/")} + > + App Title + + + + + {currentUser && ( + + )} + + + + {currentUser && ( + + logout()} aria-label="Log out"> + + + + )} + + + ); +} diff --git a/standards/mcp/templates/client/src/Home.tsx b/standards/mcp/templates/client/src/Home.tsx new file mode 100644 index 0000000..09430b6 --- /dev/null +++ b/standards/mcp/templates/client/src/Home.tsx @@ -0,0 +1,214 @@ +/** + * Landing page: a grid of resource cards and a live preview table. + * + * Exercises the `@aetoskia/react-openapi` building blocks end-to-end: + * - `ResourceCard` - a grid of every top-level resource with a live record + * count (or SSE connection status for streaming resources). + * - `LiveTable` - preview of the first 5 records of the first non-streaming + * resource. + * + * Add custom pages as sibling routes in `main.jsx`; the auto-generated + * admin lives at `/admin/*` regardless. + * + * @packageDocumentation + */ + +import React, { useEffect, useMemo, useState } from "react"; +import { + Box, Container, Typography, Paper, Grid, Chip, + Table, TableBody, TableCell, TableContainer, TableHead, + TableRow, CircularProgress, +} from "@mui/material"; + +import { useNavigate } from "react-router-dom"; +import { useAppContext, useResource, ListCellRenderer, SseConnectionStatus, applyDisplayFormat } from "@aetoskia/react-openapi"; +import type { ResourceConfig, FieldConfig } from "@aetoskia/react-openapi"; + +/** + * Clickable card summarizing one resource. + * + * Shows the display name, field count and either a record-count chip (loaded + * via `useResource().list({ limit: 0 })`) or the SSE connection status for + * streaming resources; clicking navigates to `/admin/`. + * + * Props: + * - `resource` - the `ResourceConfig` to summarize. + */ +function ResourceCard({ resource }: { resource: ResourceConfig }) { + const navigate = useNavigate(); + const { list } = useResource(resource.name); + const [count, setCount] = useState(null); + + useEffect(() => { + if (resource.streaming) return; + list({ limit: 0 }).then((res) => setCount(res.total ?? res.items?.length ?? 0)); + }, [resource.name]); + + return ( + navigate(`/admin/${resource.name}`)} + sx={{ + p: 3, + borderRadius: 2, + border: "1px solid", + borderColor: "divider", + cursor: "pointer", + transition: "all 0.2s", + "&:hover": { borderColor: "primary.main", boxShadow: 1 }, + }} + > + + {resource.displayName} + + + {resource.fields.length} fields + + + {resource.streaming ? ( + + ) : ( + 0 ? "primary" : "default"} + variant="outlined" + /> + )} + + + + ); +} + +/** + * Preview table of the first 5 records of a resource. + * + * Columns come from `resource.listColumns`; each cell renders through + * `ListCellRenderer` using the resource display format (or the FK target's + * format for foreign-key columns). Shows a spinner while loading and a + * "No records found." message when empty. + * + * Props: + * - `resource` - the `ResourceConfig` to preview. + */ +function LiveTable({ resource }: { resource: ResourceConfig }) { + const { list } = useResource(resource.name); + const { resources: allResources } = useAppContext(); + const [rows, setRows] = useState(null); + const columns = resource.listColumns + .map((n) => resource.fields.find((f) => f.name === n)) + .filter(Boolean) as FieldConfig[]; + + useEffect(() => { + list({ limit: 5 }).then((res) => setRows(res.items ?? [])); + }, [resource.name]); + + if (!rows) { + return ( + + + + ); + } + + if (rows.length === 0) { + return No records found.; + } + + return ( + + + + + {columns.map((col) => ( + + {col.label} + + ))} + + + + {rows.map((row, i) => ( + + {columns.map((col) => { + const displayFormat = col.fk + ? (allResources.find((r) => r.name === col.fk!.resource)?.displayFormat ?? resource.displayFormat) + : resource.displayFormat; + return ( + + + + ); + })} + + ))} + +
        +         + ); +} + +/** + * Render the landing page: resource grid and live preview. + * + * @returns The page container, or a "no resources" notice when the spec + * exposes none. + */ +export default function Home() { + const { resources } = useAppContext(); + const topLevel = useMemo(() => resources.filter((r) => !r.parent), [resources]); + const previewResource = useMemo(() => topLevel.find((r) => !r.streaming) ?? topLevel[0], [topLevel]); + + if (resources.length === 0) { + return ( + + + No resources found in the OpenAPI spec. + + + ); + } + + return ( + + + + App Title + + + Auto-generated CRUD from an OpenAPI 3.1 spec using{" "} + + @aetoskia/react-openapi + + . + + + + + Resources + + + {topLevel.map((r) => ( + + + + ))} + + + + Live Preview + {previewResource && ( + + — first 5 records from {previewResource.displayName} + + )} + + {previewResource && } + + ); +} diff --git a/standards/mcp/templates/client/src/main.jsx b/standards/mcp/templates/client/src/main.jsx new file mode 100644 index 0000000..d0a3229 --- /dev/null +++ b/standards/mcp/templates/client/src/main.jsx @@ -0,0 +1,94 @@ +/** + * Application entry point. + * + * Creates the React root from `#root` and mounts the app: `AuthProvider` + * (JWT session against `VITE_AUTH_BASE_URL`) wraps a `LoginGate` (renders + * `AuthPage` until authenticated) which wraps `AppProvider` (fed by + * `specConfiguration`) → `BrowserRouter` → `AppTheme` → `Header` → routed + * content (`Home` at `/`, `Admin` at `/admin/*`) → `Footer`. + * + * @packageDocumentation + */ + +import * as React from 'react'; +import { createRoot } from 'react-dom/client'; +import { BrowserRouter, Routes, Route } from "react-router-dom"; +import { Box, CssBaseline, Toolbar } from "@mui/material"; +import { AuthProvider, AuthPage, useAuth } from "@aetoskia/react-auth"; +import Home from './Home'; +import { Admin, AppProvider } from '@aetoskia/react-openapi'; +import { specConfiguration } from './openapi-config'; +import Header from './Header'; +import Footer from './Footer'; +import AppTheme from './shared-theme/AppTheme'; + +const authServer = import.meta.env.VITE_AUTH_BASE_URL; + +const authConfig = { + serverUrl: authServer, + loginPath: "/login", + registerPath: "/register", + logoutPath: "/logout", + mePath: "/me", + introspectPath: "/introspect", +}; + +/** + * Route guard: renders the split-screen `AuthPage` until a user is + * authenticated, then renders the full application shell. + * + * @returns The login gate or the authenticated app. + */ +function LoginGate() { + const auth = useAuth(); + const [mode, setMode] = React.useState("login"); + + if (!auth.currentUser) { + return ( + + + {}} + onSwitchMode={() => setMode((m) => (m === "login" ? "register" : "login"))} + login={auth.login} + register={auth.register} + loading={auth.loading} + error={auth.error} + currentUser={auth.currentUser} + /> + + ); + } + + return ( + + + + +
        + + + + + + } /> + } /> + + + +