atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a2_mo_composites/plan_store.py

@@ -0,0 +1,164 @@
+"""Tier a2 — append-only persistence for agent_plan/v1 documents.
+
+Codex's follow-up: 'forge auto step <card-id>' / 'forge auto apply
+<plan-id>' need plans to be addressable. This store gives every plan
+a stable id (SHA-256 prefix of the plan's structural content) and
+persists it under ``.atomadic-forge/plans/<id>.json``. Per-card
+state (applied / rejected / skipped) lives in a sibling
+``.atomadic-forge/plans/<id>.state.json`` so the plan doc itself
+stays append-only and re-emit-safe.
+
+Pure-ish: file I/O scoped under one project_root; no network. The
+pure id-derivation lives in a1 (``a1.lineage_chain.canonical_receipt_hash``-style)
+but for plans the canonical fields are different — declared inline
+here to keep the dependency surface tight.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+_DIRNAME = ".atomadic-forge"
+_PLANS_SUBDIR = "plans"
+
+
+# Fields that participate in the plan id hash. Mutable / volatile
+# fields are excluded so re-emitting the same plan yields the same id.
+_PLAN_HASH_INCLUDE: tuple[str, ...] = (
+    "schema_version",
+    "goal",
+    "mode",
+    "project_root",
+    "top_actions",
+)
+
+
+def compute_plan_id(plan: dict) -> str:
+    """SHA-256 hex prefix derived from the plan's structural content."""
+    canonical = {k: plan.get(k) for k in _PLAN_HASH_INCLUDE}
+    blob = json.dumps(canonical, sort_keys=True, default=str)
+    return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:12]
+
+
+def _now_utc_iso() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class PlanStore:
+    """Append-only plan + per-card-state persistence."""
+
+    def __init__(self, project_root: Path) -> None:
+        self.project_root = Path(project_root).resolve()
+        self.dir = self.project_root / _DIRNAME / _PLANS_SUBDIR
+
+    # ---- write paths ---------------------------------------------------
+
+    def save_plan(self, plan: dict) -> str:
+        """Persist a plan dict and return its id (idempotent)."""
+        plan_id = plan.get("id") or compute_plan_id(plan)
+        self.dir.mkdir(parents=True, exist_ok=True)
+        # Persist the plan with its id baked in so repeat saves are safe.
+        out = dict(plan)
+        out.setdefault("id", plan_id)
+        out.setdefault("saved_at_utc", _now_utc_iso())
+        target = self.dir / f"{plan_id}.json"
+        target.write_text(
+            json.dumps(out, indent=2, default=str), encoding="utf-8")
+        # Initialize state file if missing.
+        state_path = self._state_path(plan_id)
+        if not state_path.exists():
+            state_path.write_text(
+                json.dumps({
+                    "schema_version": "atomadic-forge.plan_state/v1",
+                    "plan_id": plan_id,
+                    "events": [],
+                }, indent=2),
+                encoding="utf-8",
+            )
+        return plan_id
+
+    def record_card_event(
+        self,
+        plan_id: str,
+        *,
+        card_id: str,
+        status: str,
+        detail: dict[str, Any] | None = None,
+    ) -> None:
+        """Append a per-card outcome (applied / rejected / skipped /
+        rolled_back). Pure append; never rewrites prior events."""
+        state = self.load_state(plan_id) or {
+            "schema_version": "atomadic-forge.plan_state/v1",
+            "plan_id": plan_id, "events": [],
+        }
+        state["events"].append({
+            "ts_utc": _now_utc_iso(),
+            "card_id": card_id,
+            "status": status,
+            "detail": detail or {},
+        })
+        self._state_path(plan_id).write_text(
+            json.dumps(state, indent=2, default=str), encoding="utf-8")
+
+    # ---- read paths ----------------------------------------------------
+
+    def load_plan(self, plan_id: str) -> dict | None:
+        target = self.dir / f"{plan_id}.json"
+        if not target.exists():
+            return None
+        try:
+            return json.loads(target.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+
+    def load_state(self, plan_id: str) -> dict | None:
+        target = self._state_path(plan_id)
+        if not target.exists():
+            return None
+        try:
+            return json.loads(target.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+
+    def list_plans(self) -> list[dict]:
+        """Return summaries newest-first by saved_at_utc."""
+        if not self.dir.exists():
+            return []
+        out: list[dict] = []
+        for f in self.dir.glob("*.json"):
+            if f.name.endswith(".state.json"):
+                continue
+            try:
+                doc = json.loads(f.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            out.append({
+                "plan_id": doc.get("id", f.stem),
+                "verdict": doc.get("verdict", "?"),
+                "goal": doc.get("goal", ""),
+                "mode": doc.get("mode", ""),
+                "action_count": doc.get("action_count", 0),
+                "applyable_count": doc.get("applyable_count", 0),
+                "saved_at_utc": doc.get("saved_at_utc", ""),
+            })
+        out.sort(key=lambda d: d["saved_at_utc"], reverse=True)
+        return out
+
+    def card_status(self, plan_id: str, card_id: str) -> str:
+        """Return the latest status for ``card_id`` in plan, or
+        'unapplied' when no event has been recorded."""
+        state = self.load_state(plan_id)
+        if not state:
+            return "unapplied"
+        for ev in reversed(state.get("events", [])):
+            if ev.get("card_id") == card_id:
+                return ev.get("status", "unapplied")
+        return "unapplied"
+
+    # ---- helpers -------------------------------------------------------
+
+    def _state_path(self, plan_id: str) -> Path:
+        return self.dir / f"{plan_id}.state.json"

atomadic_forge/a2_mo_composites/receipt_signer.py

@@ -0,0 +1,231 @@
+"""Tier a2 — Receipt signing client.
+
+Golden Path Lane A W2. Calls AAAA-Nexus ``/v1/verify/forge-receipt`` to
+obtain Sigstore Rekor metadata + AAAA-Nexus signature, mutates the
+Receipt in place, and returns it.
+
+Stateful by design: holds base URL + auth env name + last-known
+endpoint health (so a single CLI session probing once doesn't probe
+again on every Receipt). Fits a2 cleanly (composes a1 emitter output
++ a0 schema constants + std-lib I/O); never imports a3+.
+
+Graceful-degradation contract:
+  * If ``AAAA_NEXUS_API_KEY`` is unset → return the Receipt unchanged
+    with a ``notes`` entry explaining why. No exception.
+  * If the endpoint returns 4xx (trial-tier rate limit, key invalid,
+    feature not yet shipped) → same: return unsigned with a note.
+  * Network / DNS / timeout error → same: return unsigned with a note
+    that includes the underlying error class.
+  * 5xx → caller's choice: ``strict=True`` raises ``RuntimeError``;
+    ``strict=False`` (default) returns unsigned + note.
+
+Why the soft-fail default: per the Golden Path, "unsigned Receipts
+are valid. The signature fields default to None." A local-development
+``forge certify --sign`` invocation should never crash because the
+prod endpoint is having a bad day. CI gates that REQUIRE a signature
+should pass ``--sign --require-signed`` (Lane G future work).
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from copy import deepcopy
+from typing import Any
+
+from ..a0_qk_constants.receipt_schema import (
+    ForgeReceiptV1,
+    ReceiptAAAANexusSignature,
+    ReceiptSigstoreSignature,
+)
+
+
+class ReceiptSigner:
+    """Stateful signer that wraps the AAAA-Nexus verify endpoint."""
+
+    DEFAULT_BASE_URL = "https://aaaa-nexus.atomadictech.workers.dev"
+    DEFAULT_PATH = "/v1/verify/forge-receipt"
+    DEFAULT_TIMEOUT_SECONDS = 30
+    USER_AGENT = "atomadic-forge/0.2 (ReceiptSigner)"
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key_env: str = "AAAA_NEXUS_API_KEY",
+        path: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> None:
+        self.base_url = (
+            base_url
+            or os.environ.get("AAAA_NEXUS_URL")
+            or self.DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.api_key_env = api_key_env
+        self.path = path or self.DEFAULT_PATH
+        self.timeout_seconds = (
+            timeout_seconds
+            if timeout_seconds is not None
+            else self.DEFAULT_TIMEOUT_SECONDS
+        )
+        # Soft cache of last-known reachability so a session that
+        # probed once and got 404 doesn't re-probe on every receipt.
+        self._endpoint_known_unavailable = False
+
+    # ---- public surface ------------------------------------------------
+
+    def sign(
+        self,
+        receipt: ForgeReceiptV1,
+        *,
+        strict: bool = False,
+    ) -> ForgeReceiptV1:
+        """Return a new Receipt with the ``signatures`` block populated.
+
+        The input Receipt is not mutated. The output is a deep copy
+        with ``signatures.sigstore`` and ``signatures.aaaa_nexus``
+        either populated (success) or left at None with a ``notes``
+        entry (soft-fail).
+        """
+        out = deepcopy(receipt)
+        api_key = os.environ.get(self.api_key_env, "")
+        if not api_key:
+            self._note(out, f"{self.api_key_env} not set — receipt left unsigned")
+            return out
+        if self._endpoint_known_unavailable:
+            self._note(out, "AAAA-Nexus signing endpoint unavailable this session")
+            return out
+        try:
+            response = self._post_for_signature(receipt, api_key)
+        except (urllib.error.HTTPError, urllib.error.URLError, OSError,
+                ValueError) as exc:
+            return self._handle_request_failure(out, exc, strict=strict)
+        self._apply_signature(out, response)
+        return out
+
+    # ---- request helpers ----------------------------------------------
+
+    def _post_for_signature(
+        self,
+        receipt: ForgeReceiptV1,
+        api_key: str,
+    ) -> dict[str, Any]:
+        body = json.dumps({"receipt": receipt}, default=str).encode("utf-8")
+        endpoint = self.base_url + self.path
+        req = urllib.request.Request(
+            endpoint,
+            data=body,
+            headers={
+                "X-API-Key": api_key,
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": self.USER_AGENT,
+                "Accept": "application/json",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=self.timeout_seconds) as resp:
+            payload = resp.read()
+        decoded = json.loads(payload.decode("utf-8") or "{}")
+        if not isinstance(decoded, dict):
+            raise ValueError("AAAA-Nexus returned non-object body")
+        return decoded
+
+    def _apply_signature(
+        self,
+        receipt: ForgeReceiptV1,
+        response: dict[str, Any],
+    ) -> None:
+        sigstore = response.get("sigstore")
+        nexus = response.get("aaaa_nexus") or response.get("aaaa-nexus")
+        sigs = receipt.get("signatures") or {}
+        if isinstance(sigstore, dict):
+            sigs["sigstore"] = ReceiptSigstoreSignature(  # type: ignore[typeddict-item]
+                rekor_uuid=str(sigstore.get("rekor_uuid", "")),
+                log_index=int(sigstore.get("log_index", 0)),
+                bundle_path=str(sigstore.get("bundle_path", "")),
+            )
+        else:
+            sigs["sigstore"] = None  # type: ignore[typeddict-item]
+        if isinstance(nexus, dict):
+            sigs["aaaa_nexus"] = ReceiptAAAANexusSignature(  # type: ignore[typeddict-item]
+                signature=str(nexus.get("signature", "")),
+                key_id=str(nexus.get("key_id", "")),
+                issuer=str(nexus.get("issuer", "")),
+                issued_at_utc=str(nexus.get("issued_at_utc", "")),
+                verify_endpoint=str(nexus.get("verify_endpoint", self.path)),
+            )
+        else:
+            sigs["aaaa_nexus"] = None  # type: ignore[typeddict-item]
+        receipt["signatures"] = sigs  # type: ignore[typeddict-item]
+
+    # ---- failure handling ---------------------------------------------
+
+    def _handle_request_failure(
+        self,
+        receipt: ForgeReceiptV1,
+        exc: BaseException,
+        *,
+        strict: bool,
+    ) -> ForgeReceiptV1:
+        # 4xx: known bad request / auth / not-yet-shipped — never retry,
+        # mark endpoint unavailable for the session so subsequent calls
+        # in this run skip the round trip.
+        if isinstance(exc, urllib.error.HTTPError):
+            if 400 <= exc.code < 500:
+                self._endpoint_known_unavailable = True
+                self._note(
+                    receipt,
+                    f"AAAA-Nexus signing returned HTTP {exc.code}; "
+                    "receipt left unsigned",
+                )
+                return receipt
+            if strict:
+                raise RuntimeError(
+                    f"AAAA-Nexus signing failed with HTTP {exc.code}: {exc}"
+                ) from exc
+            self._note(
+                receipt,
+                f"AAAA-Nexus signing failed with HTTP {exc.code}; "
+                "soft-fail, receipt left unsigned",
+            )
+            return receipt
+        if strict:
+            raise RuntimeError(
+                f"AAAA-Nexus signing transport error: "
+                f"{type(exc).__name__}: {exc}"
+            ) from exc
+        self._note(
+            receipt,
+            f"AAAA-Nexus signing transport error "
+            f"({type(exc).__name__}); receipt left unsigned",
+        )
+        return receipt
+
+    # ---- helpers -------------------------------------------------------
+
+    @staticmethod
+    def _note(receipt: ForgeReceiptV1, message: str) -> None:
+        notes = list(receipt.get("notes") or [])
+        notes.append(message)
+        receipt["notes"] = notes  # type: ignore[typeddict-item]
+
+
+def sign_receipt(
+    receipt: ForgeReceiptV1,
+    *,
+    base_url: str | None = None,
+    api_key_env: str = "AAAA_NEXUS_API_KEY",
+    strict: bool = False,
+) -> ForgeReceiptV1:
+    """Module-level convenience: instantiate a signer and call ``sign``.
+
+    For one-shot CLI calls. Long-running processes should construct a
+    ``ReceiptSigner`` once and reuse it (the endpoint-availability
+    cache is per-instance).
+    """
+    return ReceiptSigner(
+        base_url=base_url,
+        api_key_env=api_key_env,
+    ).sign(receipt, strict=strict)

atomadic_forge/a3_og_features/__init__.py

@@ -0,0 +1 @@
+"""Tier a3 — features compose a2 composites + a1 helpers into capabilities."""

atomadic_forge/a3_og_features/commandsmith_feature.py

@@ -0,0 +1,267 @@
+"""Tier a3 — Commandsmith feature: discover, register, document, smoke-test.
+
+The Commandsmith feature glues together the a1 discoverer + a1 renderers and
+manages on-disk persistence for the registry.  It is the only module the a4
+CLI surface depends on.
+
+Pipelines exposed:
+
+* :meth:`sync` — full pipeline (discover → render registry → write docs).
+* :meth:`wrap_class` — generate a Typer wrapper around a single class
+  (used to lift a freshly assimilated symbol into a CLI command).
+* :meth:`smoke` — invoke ``--help`` on every registered command and record
+  exit codes.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import importlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from ..a0_qk_constants.commandsmith_types import (
+    CommandSignatureCard,
+    RegisteredCommandCard,
+    RegistryManifestCard,
+)
+from ..a1_at_functions.commandsmith_discover import discover_command_modules
+from ..a1_at_functions.commandsmith_render import (
+    render_command_doc,
+    render_command_index,
+    render_registry_module,
+    render_wrapper_module,
+)
+
+_REGISTRY_FILE = "_registry.py"
+_MANIFEST_FILE = "commandsmith_manifest.json"
+
+
+class Commandsmith:
+    """Manage the CLI registry for an ASS-ADE-style package.
+
+    ``package_root``: directory containing the ``commands/`` subfolder.
+    ``docs_root``:    where to write per-command Markdown.
+    ``manifest_dir``: where to persist ``commandsmith_manifest.json``.
+    """
+
+    def __init__(
+        self,
+        *,
+        package_root: Path,
+        package_name: str = "atomadic_forge",
+        docs_root: Path | None = None,
+        manifest_dir: Path | None = None,
+    ) -> None:
+        self.package_root = Path(package_root)
+        self.package_name = package_name
+        self.commands_dir = self.package_root / "commands"
+        self.docs_root = Path(docs_root) if docs_root else self.package_root.parent.parent / "docs" / "commands"
+        self.manifest_dir = Path(manifest_dir) if manifest_dir else self.package_root.parent.parent / ".atomadic-forge"
+
+    # ----- discovery --------------------------------------------------
+
+    def discover(self) -> list[RegisteredCommandCard]:
+        return discover_command_modules(
+            self.package_root,
+            package=self.package_name,
+            sub_dirs=("commands",),
+            source_root="atomadic_forge_seed",
+        )
+
+    # ----- registry / docs / manifest --------------------------------
+
+    def write_registry(self, cards: list[RegisteredCommandCard]) -> Path:
+        """Emit ``commands/_registry.py``."""
+        target = self.commands_dir / _REGISTRY_FILE
+        target.write_text(render_registry_module(cards), encoding="utf-8")
+        return target
+
+    def write_docs(self, cards: list[RegisteredCommandCard]) -> list[Path]:
+        """Write per-command Markdown plus an INDEX."""
+        self.docs_root.mkdir(parents=True, exist_ok=True)
+        out: list[Path] = []
+        for card in cards:
+            f = self.docs_root / f"{card['name']}.md"
+            f.write_text(render_command_doc(card), encoding="utf-8")
+            out.append(f)
+        idx = self.docs_root / "INDEX.md"
+        idx.write_text(render_command_index(cards), encoding="utf-8")
+        out.append(idx)
+        return out
+
+    def write_manifest(self, cards: list[RegisteredCommandCard],
+                       smoke_results: dict[str, bool] | None = None) -> Path:
+        manifest = RegistryManifestCard(
+            schema_version="atomadic-forge.commandsmith.registry/v1",
+            generated_at_utc=_dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            commands=cards,
+            smoke_results=smoke_results or {},
+        )
+        self.manifest_dir.mkdir(parents=True, exist_ok=True)
+        target = self.manifest_dir / _MANIFEST_FILE
+        target.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+        return target
+
+    # ----- generator wrapping a class --------------------------------
+
+    def wrap_class(
+        self,
+        *,
+        target_module: str,
+        target_class: str,
+        command_name: str,
+        out_dir: Path | None = None,
+        help_text: str = "",
+        auto_scan: str | None = None,
+    ) -> Path:
+        """Generate ``commands/<command_name>_cli.py`` wrapping a class.
+
+        ``auto_scan`` (optional): name of a method to call inside the Typer
+        callback (e.g. ``scan_repo`` for CherryPicker) so subcommands see a
+        populated instance state.  If omitted, a sensible default is picked:
+        any method whose name is exactly ``scan`` or starts with ``scan_``.
+        """
+        sub_cmds = self._inspect_class_methods(target_module, target_class)
+        init_params = self._inspect_init_params(target_module, target_class)
+        if auto_scan is None:
+            auto_scan = next(
+                (s["name"] for s in sub_cmds
+                 if s["name"] == "scan" or s["name"].startswith("scan_")),
+                None,
+            )
+        src = render_wrapper_module(
+            target_module=target_module,
+            target_class=target_class,
+            command_name=command_name,
+            sub_commands=sub_cmds,
+            help_text=help_text or f"Auto-wrapped {target_class}",
+            init_params=init_params,
+            auto_scan=auto_scan,
+        )
+        out = (out_dir or self.commands_dir) / f"{command_name.replace('-', '_')}_cli.py"
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(src, encoding="utf-8")
+        return out
+
+    def _inspect_init_params(self, target_module: str,
+                             target_class: str) -> list[str]:
+        """Extract __init__ parameter strings (``name: type``)."""
+        import inspect
+
+        try:
+            module = importlib.import_module(target_module)
+            cls = getattr(module, target_class)
+            sig = inspect.signature(cls.__init__)
+            params: list[str] = []
+            for pname, p in sig.parameters.items():
+                if pname == "self":
+                    continue
+                if p.kind in (inspect.Parameter.VAR_POSITIONAL,
+                              inspect.Parameter.VAR_KEYWORD):
+                    continue
+                ann = (
+                    p.annotation.__name__
+                    if p.annotation is not inspect.Parameter.empty
+                    and hasattr(p.annotation, "__name__")
+                    else str(p.annotation)
+                    if p.annotation is not inspect.Parameter.empty
+                    else "str"
+                )
+                params.append(f"{pname}: {ann}")
+            return params
+        except Exception:
+            return []
+
+    def _inspect_class_methods(
+        self, target_module: str, target_class: str,
+    ) -> list[CommandSignatureCard]:
+        """Live-inspect a class via importlib and return method signatures.
+
+        Falls back to AST scanning if import fails.
+        """
+        import inspect
+
+        try:
+            module = importlib.import_module(target_module)
+            cls = getattr(module, target_class)
+            cards: list[CommandSignatureCard] = []
+            for name, member in inspect.getmembers(cls, predicate=inspect.isfunction):
+                if name.startswith("_"):
+                    continue
+                sig = inspect.signature(member)
+                params: list[str] = []
+                for pname, p in sig.parameters.items():
+                    if pname == "self":
+                        continue
+                    ann = (
+                        p.annotation.__name__
+                        if p.annotation is not inspect.Parameter.empty
+                        and hasattr(p.annotation, "__name__")
+                        else str(p.annotation)
+                        if p.annotation is not inspect.Parameter.empty
+                        else "Any"
+                    )
+                    params.append(f"{pname}: {ann}")
+                ret = (
+                    sig.return_annotation.__name__
+                    if sig.return_annotation is not inspect.Signature.empty
+                    and hasattr(sig.return_annotation, "__name__")
+                    else "Any"
+                )
+                cards.append(CommandSignatureCard(
+                    name=name,
+                    parameters=params,
+                    return_type=ret,
+                    docstring=(inspect.getdoc(member) or "").split("\n")[0],
+                ))
+            return cards
+        except Exception:
+            return []
+
+    # ----- smoke test -------------------------------------------------
+
+    def smoke(self, cards: list[RegisteredCommandCard],
+              cli_invocation: list[str] | None = None) -> dict[str, bool]:
+        """Run ``<cli> <verb> --help`` for each card; record exit code == 0.
+
+        Subprocesses inherit ``PYTHONIOENCODING=utf-8`` so rich/Typer help
+        rendering doesn't blow up on Windows ``cp1252`` consoles.
+        """
+        import os
+        if cli_invocation is None:
+            # Use the forge CLI entry point.
+            cli_invocation = [sys.executable, "-m",
+                              "atomadic_forge.a4_sy_orchestration.cli"]
+        env = os.environ.copy()
+        env["PYTHONIOENCODING"] = "utf-8"
+        env["PYTHONUTF8"] = "1"
+        results: dict[str, bool] = {}
+        for card in cards:
+            try:
+                rc = subprocess.run(
+                    cli_invocation + [card["name"], "--help"],
+                    capture_output=True, text=True, timeout=20,
+                    env=env, encoding="utf-8", errors="replace",
+                ).returncode
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                rc = 1
+            results[card["name"]] = rc == 0
+        return results
+
+    # ----- one-shot pipeline -----------------------------------------
+
+    def sync(self, *, smoke: bool = False) -> RegistryManifestCard:
+        cards = self.discover()
+        self.write_registry(cards)
+        self.write_docs(cards)
+        smoke_results = self.smoke(cards) if smoke else {}
+        self.write_manifest(cards, smoke_results)
+        return RegistryManifestCard(
+            schema_version="atomadic-forge.commandsmith.registry/v1",
+            generated_at_utc=_dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            commands=cards,
+            smoke_results=smoke_results,
+        )

atomadic_forge/a3_og_features/demo_packages/mixed_py_js/src/mixed_pkg/__init__.py

@@ -0,0 +1,3 @@
+"""mixed_pkg — Python side of the polyglot Forge demo."""
+
+__version__ = "0.1.0"

atomadic_forge/a3_og_features/demo_packages/mixed_py_js/src/mixed_pkg/a0_qk_constants/__init__.py

@@ -0,0 +1,4 @@
+"""Tier a0 — constants for mixed_pkg."""
+
+GREETING_PREFIX: str = "hello"
+MAX_NAME_LEN: int = 64

atomadic_forge/a3_og_features/demo_packages/mixed_py_js/src/mixed_pkg/a1_at_functions/__init__.py

@@ -0,0 +1,14 @@
+"""Tier a1 — pure helpers for mixed_pkg. May import a0 only."""
+
+from mixed_pkg.a0_qk_constants import GREETING_PREFIX, MAX_NAME_LEN
+
+
+def greet(name: str) -> str:
+    """Return ``"hello, <name>"`` with a length cap. Pure."""
+    safe = name[:MAX_NAME_LEN].strip() or "world"
+    return f"{GREETING_PREFIX}, {safe}"
+
+
+def length_within(name: str) -> bool:
+    """Return True if the name is at most MAX_NAME_LEN characters. Pure."""
+    return len(name) <= MAX_NAME_LEN