stackgen-sdk 0.1.1__py3-none-any.whl

stackgen/__init__.py

@@ -0,0 +1,52 @@
+"""StackGen Python SDK.
+
+Public entrypoint::
+
+    from stackgen import StackgenClient, StackgenConfig
+
+    client = StackgenClient.from_env()
+    result = client.aiden.run_webhook_and_download_report(payload)
+"""
+
+from __future__ import annotations
+
+from stackgen.client import StackgenClient
+from stackgen.config import StackgenConfig
+from stackgen.errors import HttpError, NotAllowlistedError, StackgenError, TimeoutError
+
+__all__ = [
+    "HttpError",
+    "NotAllowlistedError",
+    "StackgenClient",
+    "StackgenConfig",
+    "StackgenError",
+    "TimeoutError",
+]
+
+
+def _resolve_version() -> str:
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+    except ImportError:  # pragma: no cover
+        from importlib_metadata import PackageNotFoundError, version  # type: ignore
+
+    try:
+        return version("stackgen-sdk")
+    except PackageNotFoundError:
+        try:
+            return version("stackgen")
+        except PackageNotFoundError:
+            try:
+                from stackgen._version import __version__ as vcs_version
+
+                return vcs_version
+            except ImportError:
+                try:
+                    from stackgen._version import version as vcs_version
+
+                    return vcs_version
+                except ImportError:
+                    return "0.0.0"
+
+
+__version__ = _resolve_version()

stackgen/_http.py

@@ -0,0 +1,96 @@
+"""Shared HTTP helpers (stdlib)."""
+
+from __future__ import annotations
+
+import json
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+from stackgen.errors import HttpError, TimeoutError
+
+_RETRYABLE = {429, 502, 503, 504}
+
+
+def query(org_id: str) -> str:
+    if not org_id:
+        return ""
+    return "?" + urllib.parse.urlencode({"orgId": org_id})
+
+
+def request(
+    url: str,
+    token: str,
+    *,
+    method: str = "GET",
+    body: bytes | None = None,
+    content_type: str | None = None,
+    expect_json: bool = True,
+    retries: int = 3,
+) -> Any:
+    """Bearer HTTP call with bounded retries on transient GET failures."""
+    headers = {"Authorization": f"Bearer {token}"}
+    if content_type:
+        headers["Content-Type"] = content_type
+
+    attempt = 0
+    while True:
+        attempt += 1
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, context=ssl.create_default_context()) as resp:
+                raw = resp.read()
+                if not expect_json:
+                    return raw
+                if not raw:
+                    return {}
+                return json.loads(raw.decode("utf-8"))
+        except urllib.error.HTTPError as err:
+            detail = err.read().decode("utf-8", errors="replace")
+            if method == "GET" and err.code in _RETRYABLE and attempt < retries:
+                time.sleep(min(2**attempt, 8))
+                continue
+            raise HttpError(
+                f"{method} {url} -> HTTP {err.code}: {detail}",
+                status_code=err.code,
+            ) from err
+        except urllib.error.URLError as err:
+            if method == "GET" and attempt < retries:
+                time.sleep(min(2**attempt, 8))
+                continue
+            raise HttpError(f"{method} {url} -> {err}") from err
+
+
+def as_list(payload: Any) -> list[dict[str, Any]]:
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if isinstance(payload, dict):
+        items = payload.get("items")
+        if isinstance(items, list):
+            return [item for item in items if isinstance(item, dict)]
+    return []
+
+
+def text(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def poll_until(
+    deadline: float,
+    interval: float,
+    tick: Callable[[], Any | None],
+    *,
+    label: str,
+    timeout_seconds: int,
+) -> Any:
+    while time.monotonic() < deadline:
+        result = tick()
+        if result is not None:
+            return result
+        time.sleep(interval)
+    raise TimeoutError(label, timeout_seconds)

stackgen/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = None

stackgen/aiden/__init__.py

@@ -0,0 +1,9 @@
+"""Aiden (platform) namespace — webhooks, sessions, artifacts."""
+
+from stackgen.aiden.namespace import AidenNamespace
+from stackgen.aiden.webhook import WebhookReportResult
+
+__all__ = [
+    "AidenNamespace",
+    "WebhookReportResult",
+]

stackgen/aiden/namespace.py

@@ -0,0 +1,26 @@
+"""Aiden namespace — public methods for platform APIs."""
+
+from __future__ import annotations
+
+from stackgen.aiden.webhook import WebhookReportJourney, WebhookReportResult
+from stackgen.config import StackgenConfig
+
+
+class AidenNamespace:
+    """Aiden platform APIs (sessions, webhooks, artifacts)."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+        self._webhook = WebhookReportJourney(config)
+
+    def run_webhook_and_download_report(
+        self,
+        payload: str,
+        *,
+        artifact_name: str | None = None,
+        output_path: str | None = None,
+    ) -> WebhookReportResult:
+        """Trigger a webhook, wait for the session artifact, download it."""
+        return self._webhook.run(
+            payload, artifact_name=artifact_name, output_path=output_path
+        )

stackgen/aiden/runs.py

@@ -0,0 +1,36 @@
+"""Pure helpers for webhook run selection (unit-testable without HTTP)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from stackgen import _http
+
+
+def pick_run(
+    runs: list[dict[str, Any]],
+    dispatch_run_id: str,
+    known_run_ids: frozenset[str],
+) -> dict[str, Any] | None:
+    """Choose the webhook run that corresponds to a new trigger.
+
+    Preference order:
+      1. Exact match on ``id`` / ``run_id`` to ``dispatch_run_id``
+      2. First run whose id is not in ``known_run_ids`` (new since pre-trigger snapshot)
+      3. If no known ids and runs exist, the first run (best-effort on older motherships)
+    """
+    if dispatch_run_id:
+        for item in runs:
+            if dispatch_run_id in {
+                _http.text(item.get("id")),
+                _http.text(item.get("run_id")),
+            }:
+                return item
+    for item in runs:
+        if _http.text(item.get("id")) not in known_run_ids:
+            return item
+    if not runs:
+        return None
+    if not known_run_ids:
+        return runs[0]
+    return None

stackgen/aiden/webhook.py

@@ -0,0 +1,185 @@
+"""Aiden webhook → session-report journey."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.parse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from stackgen import _http
+from stackgen.aiden.runs import pick_run
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError, TimeoutError
+
+
+@dataclass(frozen=True)
+class WebhookReportResult:
+    """Result of trigger → wait → download session-report."""
+
+    webhook_id: str
+    invocation_id: str
+    session_id: str
+    artifacts: tuple[dict[str, Any], ...]
+    output_path: Path
+
+
+class WebhookReportJourney:
+    """Trigger a webhook, wait for the session artifact, and download it.
+
+    Uses ``webhook_token`` for POST trigger and ``api_token`` for poll/download.
+    """
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+
+    def run(
+        self,
+        payload: str,
+        *,
+        artifact_name: str | None = None,
+        output_path: str | None = None,
+    ) -> WebhookReportResult:
+        cfg = self._config
+        if not cfg.webhook_token:
+            raise ValueError("webhook_token is required for run_webhook_and_download_report")
+
+        artifact = artifact_name or cfg.artifact_name
+        dest = output_path or cfg.output_path
+
+        known_run_ids: frozenset[str] = frozenset()
+        if cfg.webhook_id:
+            known_run_ids = frozenset(
+                _http.text(item.get("id"))
+                for item in self._list_runs(cfg.webhook_id)
+                if _http.text(item.get("id"))
+            )
+
+        trigger = self._trigger(payload)
+        webhook_id = _http.text(trigger.get("webhook_id")) or _http.text(cfg.webhook_id)
+        invocation_id = _http.text(trigger.get("invocation_id"))
+        session_id = _http.text(trigger.get("session_id"))
+
+        if not session_id and not webhook_id:
+            raise StackgenError(
+                "trigger 202 did not include session_id or webhook_id; "
+                "set webhook_id for older motherships. "
+                f"body={json.dumps(trigger)}"
+            )
+
+        if not session_id:
+            session_id = self._wait_for_session(
+                webhook_id,
+                invocation_id,
+                _http.text(trigger.get("run_id")),
+                known_run_ids,
+            )
+
+        artifacts = self._wait_for_artifact(session_id, artifact)
+        path = self._download_artifact(session_id, artifact, dest)
+        return WebhookReportResult(
+            webhook_id=webhook_id,
+            invocation_id=invocation_id,
+            session_id=session_id,
+            artifacts=tuple(artifacts),
+            output_path=path,
+        )
+
+    def _trigger(self, payload: str) -> dict[str, Any]:
+        url = f"{self._config.aiden_url()}/api/v1/webhooks/trigger{_http.query(self._config.org_id)}"
+        data = _http.request(
+            url,
+            self._config.webhook_token,
+            method="POST",
+            body=payload.encode("utf-8"),
+            content_type="text/plain",
+        )
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected trigger payload: {data!r}")
+        return data
+
+    def _list_runs(self, webhook_id: str) -> list[dict[str, Any]]:
+        url = (
+            f"{self._config.aiden_url()}/api/v1/webhooks/{webhook_id}/runs"
+            f"{_http.query(self._config.org_id)}"
+        )
+        return _http.as_list(_http.request(url, self._config.api_token))
+
+    def _get_run(self, webhook_id: str, run_id: str) -> dict[str, Any]:
+        url = (
+            f"{self._config.aiden_url()}/api/v1/webhooks/{webhook_id}/runs/{run_id}"
+            f"{_http.query(self._config.org_id)}"
+        )
+        data = _http.request(url, self._config.api_token)
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected run payload: {data!r}")
+        return data
+
+    def _wait_for_session(
+        self,
+        webhook_id: str,
+        invocation_id: str,
+        dispatch_run_id: str,
+        known_run_ids: frozenset[str],
+    ) -> str:
+        cfg = self._config
+        deadline = time.monotonic() + cfg.timeout_seconds
+        run_id_hint = invocation_id or dispatch_run_id
+        while time.monotonic() < deadline:
+            run: dict[str, Any] | None = None
+            if run_id_hint:
+                try:
+                    run = self._get_run(webhook_id, run_id_hint)
+                except StackgenError:
+                    run = None
+            if run is None:
+                run = pick_run(self._list_runs(webhook_id), dispatch_run_id, known_run_ids)
+            if run is None:
+                time.sleep(cfg.poll_interval_seconds)
+                continue
+            if not run_id_hint:
+                run_id_hint = _http.text(run.get("id")) or _http.text(run.get("run_id"))
+            status = _http.text(run.get("status")).casefold()
+            session_id = _http.text(run.get("session_id"))
+            if status in {"failed", "skipped"}:
+                raise StackgenError(
+                    f"webhook invocation ended with status {status}: "
+                    f"{run.get('error') or 'no error detail'}"
+                )
+            if session_id:
+                return session_id
+            time.sleep(cfg.poll_interval_seconds)
+        raise TimeoutError("webhook session", cfg.timeout_seconds)
+
+    def _wait_for_artifact(
+        self, session_id: str, artifact_name: str
+    ) -> list[dict[str, Any]]:
+        cfg = self._config
+        deadline = time.monotonic() + cfg.timeout_seconds
+        url = (
+            f"{cfg.aiden_url()}/api/v1/sessions/{session_id}/artifacts"
+            f"{_http.query(cfg.org_id)}"
+        )
+        want = artifact_name.casefold()
+        artifacts: list[dict[str, Any]] = []
+        while time.monotonic() < deadline:
+            artifacts = _http.as_list(_http.request(url, cfg.api_token))
+            if any(_http.text(item.get("name")).casefold() == want for item in artifacts):
+                return artifacts
+            time.sleep(cfg.poll_interval_seconds)
+        raise TimeoutError(artifact_name, cfg.timeout_seconds)
+
+    def _download_artifact(
+        self, session_id: str, artifact_name: str, output_path: str
+    ) -> Path:
+        encoded = urllib.parse.quote(artifact_name, safe="")
+        url = (
+            f"{self._config.aiden_url()}/api/v1/sessions/{session_id}/artifacts/"
+            f"{encoded}/download{_http.query(self._config.org_id)}"
+        )
+        raw = _http.request(url, self._config.api_token, expect_json=False)
+        dest = Path(output_path)
+        dest.write_bytes(raw)
+        return dest

stackgen/cli.py

@@ -0,0 +1,33 @@
+"""CLI: trigger webhook and download session-report.md."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from stackgen.client import StackgenClient
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    payload = "{}"
+    if args:
+        path = Path(args[0])
+        if not path.is_file():
+            print(f"error: payload file does not exist: {path}", file=sys.stderr)
+            sys.exit(1)
+        payload = path.read_text(encoding="utf-8")
+    try:
+        client = StackgenClient(StackgenConfig.from_env())
+        result = client.aiden.run_webhook_and_download_report(payload)
+    except (StackgenError, ValueError) as err:
+        print(f"error: {err}", file=sys.stderr)
+        sys.exit(1)
+    print(f"session_id={result.session_id}")
+    print(f"output_path={result.output_path}")
+
+
+if __name__ == "__main__":
+    main()

stackgen/client.py

@@ -0,0 +1,31 @@
+"""StackgenClient — one entrypoint for Aiden, SRE, and Vault."""
+
+from __future__ import annotations
+
+from stackgen.aiden import AidenNamespace
+from stackgen.config import StackgenConfig
+from stackgen.sre import SRENamespace
+from stackgen.vault import VaultNamespace
+
+
+class StackgenClient:
+    """Product SDK client.
+
+    Namespaces:
+      - ``aiden`` — platform automations, sessions, session-report download
+      - ``sre`` — alerts and investigations
+      - ``vault`` — secrets (allowlisted separately)
+    """
+
+    def __init__(self, config: StackgenConfig):
+        if not config.api_token:
+            raise ValueError("api_token is required")
+        self.config = config
+        self.aiden = AidenNamespace(config)
+        self.sre = SRENamespace(config)
+        self.vault = VaultNamespace(config)
+
+    @classmethod
+    def from_env(cls) -> StackgenClient:
+        """Construct from environment variables (see StackgenConfig.from_env)."""
+        return cls(StackgenConfig.from_env())

stackgen/config.py

@@ -0,0 +1,88 @@
+"""Configuration for StackgenClient."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class StackgenConfig:
+    """Connection and auth settings for the StackGen mothership.
+
+    ``base_url`` is the mothership host without a product suffix
+    (for example ``https://azure-eu.cloud.stackgen.com``). Aiden routes live
+    under ``/guild``; SRE under ``/app/sre``.
+    """
+
+    base_url: str
+    api_token: str
+    webhook_token: str = ""
+    org_id: str = ""
+    webhook_id: str = ""
+    artifact_name: str = "session-report.md"
+    output_path: str = "session-report.md"
+    poll_interval_seconds: int = 5
+    timeout_seconds: int = 1800
+
+    def mothership(self) -> str:
+        """Normalized mothership URL without trailing slash or ``/guild``."""
+        base = self.base_url.rstrip("/")
+        if base.endswith("/guild"):
+            return base[: -len("/guild")]
+        return base
+
+    def aiden_url(self) -> str:
+        """HTTP prefix for Aiden APIs."""
+        return self.mothership() + "/guild"
+
+    def sre_url(self) -> str:
+        """HTTP prefix for the SRE app."""
+        return self.mothership() + "/app/sre"
+
+    def vault_url(self) -> str:
+        """HTTP prefix for Vault on the mothership edge."""
+        return self.mothership() + "/vault/v1"
+
+    @classmethod
+    def from_env(cls) -> StackgenConfig:
+        """Build config from environment variables.
+
+        Recognized variables:
+          STACKGEN_URL / STACKGEN_BASE_URL
+          STACKGEN_TOKEN / STACKGEN_API_TOKEN
+          WEBHOOK_TOKEN
+          ORG_ID / STACKGEN_ORG_ID / STACKGEN_PROJECT
+          WEBHOOK_ID
+          ARTIFACT_NAME, OUTPUT_PATH, POLL_INTERVAL_SECONDS, TIMEOUT_SECONDS
+        """
+        base = (
+            os.environ.get("STACKGEN_URL")
+            or os.environ.get("STACKGEN_BASE_URL")
+            or ""
+        ).strip()
+        token = (
+            os.environ.get("STACKGEN_TOKEN")
+            or os.environ.get("STACKGEN_API_TOKEN")
+            or ""
+        ).strip()
+        if not base:
+            raise ValueError("STACKGEN_URL (or STACKGEN_BASE_URL) is required")
+        if not token:
+            raise ValueError("STACKGEN_TOKEN (or STACKGEN_API_TOKEN) is required")
+        return cls(
+            base_url=base,
+            api_token=token,
+            webhook_token=os.environ.get("WEBHOOK_TOKEN", "").strip(),
+            org_id=(
+                os.environ.get("ORG_ID")
+                or os.environ.get("STACKGEN_ORG_ID")
+                or os.environ.get("STACKGEN_PROJECT")
+                or ""
+            ).strip(),
+            webhook_id=os.environ.get("WEBHOOK_ID", "").strip(),
+            artifact_name=os.environ.get("ARTIFACT_NAME", "session-report.md"),
+            output_path=os.environ.get("OUTPUT_PATH", "session-report.md"),
+            poll_interval_seconds=int(os.environ.get("POLL_INTERVAL_SECONDS", "5")),
+            timeout_seconds=int(os.environ.get("TIMEOUT_SECONDS", "1800")),
+        )

stackgen/errors.py

@@ -0,0 +1,41 @@
+"""SDK errors — typed hierarchy (fail closed, catch at boundaries)."""
+
+from __future__ import annotations
+
+
+class StackgenError(RuntimeError):
+    """Base class for all StackGen SDK errors."""
+
+
+class HttpError(StackgenError):
+    """An HTTP call to StackGen failed.
+
+    ``status_code`` is set when the server returned an HTTP status; it is
+    ``None`` for transport failures (DNS, connection reset, TLS).
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class TimeoutError(StackgenError):
+    """A poll/wait loop exceeded the configured timeout."""
+
+    def __init__(self, label: str, timeout_seconds: int) -> None:
+        self.label = label
+        self.timeout_seconds = timeout_seconds
+        super().__init__(f"timed out waiting for {label} after {timeout_seconds}s")
+
+
+class NotAllowlistedError(StackgenError):
+    """Caller requested an operation that is not in the public SDK surface."""
+
+    def __init__(self, namespace: str, operation: str) -> None:
+        self.namespace = namespace
+        self.operation = operation
+        super().__init__(
+            f"{namespace}.{operation} is not allowlisted in this SDK release. "
+            "Upstream teams publish APIs via allowlists/external.yaml "
+            "(see docs/UPSTREAM.md)."
+        )