stackgen-sdk 0.4.0rc13__tar.gz → 0.4.0rc15__tar.gz

{stackgen_sdk-0.4.0rc13 → stackgen_sdk-0.4.0rc15}/.gitignore

@@ -42,6 +42,9 @@ session-artifacts/
 .env
 .env.*
 
+# Generated before Jekyll by docs/prepare-doc-samples.py (CI and Docker).
+docs/_data/doc_samples.yml
+
 # Jekyll (only if native Ruby was used by mistake)
 docs/_site/
 docs/.jekyll-cache/

{stackgen_sdk-0.4.0rc13 → stackgen_sdk-0.4.0rc15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.4.0rc13
+Version: 0.4.0rc15
 Summary: StackGen SDK — Aiden, SRE, and Vault from one client
 Project-URL: Homepage, https://appcd-dev.github.io/stackgen-sdk/
 Project-URL: Documentation, https://appcd-dev.github.io/stackgen-sdk/

{stackgen_sdk-0.4.0rc13 → stackgen_sdk-0.4.0rc15}/src/stackgen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.0rc13'
-__version_tuple__ = version_tuple = (0, 4, 0, 'rc13')
+__version__ = version = '0.4.0rc15'
+__version_tuple__ = version_tuple = (0, 4, 0, 'rc15')
 
 __commit_id__ = commit_id = None

{stackgen_sdk-0.4.0rc13 → stackgen_sdk-0.4.0rc15}/src/stackgen/aiden/ask.py

@@ -6,7 +6,7 @@ import json
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from stackgen import _http
 from stackgen.aiden import sessions as session_helpers
@@ -14,6 +14,8 @@ from stackgen.aiden.run_status import ExecutionStatus
 from stackgen.config import StackgenConfig
 from stackgen.errors import HttpError, StackgenError, TimeoutError
 
+AskMode = Literal["plan", "simple"]
+
 
 @dataclass(frozen=True)
 class AskArtifactResult:
@@ -48,6 +50,7 @@ class AskArtifactJourney:
         session_id: str | None = None,
         source_app: str | None = None,
         source_metadata: dict[str, str] | None = None,
+        mode: AskMode | None = None,
     ) -> AskArtifactResult:
         cfg = self._config
         artifact = artifact_name or cfg.artifact_name
@@ -60,6 +63,7 @@ class AskArtifactJourney:
             session_id=session_id,
             source_app=source_app,
             source_metadata=source_metadata,
+            mode=mode,
         )
         trace_id = _http.text(start.get("trace_id"))
         if not trace_id:
@@ -106,6 +110,7 @@ class AskArtifactJourney:
         session_id: str | None = None,
         source_app: str | None = None,
         source_metadata: dict[str, str] | None = None,
+        mode: AskMode | None = None,
     ) -> dict[str, Any]:
         """POST /guild/api/v1/guild/ask/start."""
         body: dict[str, Any] = {"message": message}
@@ -119,6 +124,8 @@ class AskArtifactJourney:
             body["source_app"] = source_app
         if source_metadata:
             body["source_metadata"] = source_metadata
+        if mode:
+            body["mode"] = mode
 
         url = (
             f"{self._config.aiden_url()}/api/v1/guild/ask/start"

stackgen_sdk-0.4.0rc15/src/stackgen/aiden/integration_secrets.py

@@ -0,0 +1,316 @@
+"""Compose Vault secret store + integration upsert for operators.
+
+Resolves Vault category / subcategory / required keys from Aiden's
+integration catalog and Vault ``GET /support/metadata``, so callers pass a
+plain ``secrets`` map instead of hand-building ``[{key, value}]`` metadata.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from stackgen.aiden.resources import AidenResources
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError
+from stackgen.vault.metadata import VaultMetadataKey, find_supported_format
+from stackgen.vault.namespace import VaultNamespace
+
+# Deprecated: metadata discovery replaces kind. Kept for call-site / type compat.
+IntegrationSecretKind = Literal["github", "grafana", "kafka", "generic"]
+
+
+def _as_str(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _norm(value: str) -> str:
+    return value.strip().lower()
+
+
+def _snake_to_camel(key: str) -> str:
+    parts = key.split("_")
+    if len(parts) < 2:
+        return key
+    return parts[0] + "".join(p[:1].upper() + p[1:] for p in parts[1:] if p)
+
+
+def _camel_to_snake(key: str) -> str:
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", key).lower()
+
+
+def _pick(secrets: dict[str, str], *keys: str) -> str:
+    for key in keys:
+        found = _as_str(secrets.get(key))
+        if found:
+            return found
+        camel = _snake_to_camel(key)
+        if camel != key:
+            found = _as_str(secrets.get(camel))
+            if found:
+                return found
+        snake = _camel_to_snake(key)
+        if snake != key:
+            found = _as_str(secrets.get(snake))
+            if found:
+                return found
+    return ""
+
+
+def _find_integration_type(
+    catalog: list[dict[str, Any]], type_name: str
+) -> dict[str, Any] | None:
+    want = _norm(type_name)
+    for row in catalog:
+        if _norm(_as_str(row.get("type"))) == want:
+            return row
+    return None
+
+
+def _build_value_entries(
+    secrets: dict[str, str],
+    key_defs: tuple[VaultMetadataKey, ...] | list[VaultMetadataKey],
+) -> list[dict[str, str]]:
+    """Map a plain secrets dict onto Vault metadata keys (with defaults)."""
+    entries: list[dict[str, str]] = []
+    missing: list[str] = []
+    seen: set[str] = set()
+
+    for key_def in key_defs:
+        key = key_def.key
+        if not key:
+            continue
+        seen.add(key)
+        value = _pick(secrets, key)
+        if not value and key_def.default:
+            value = key_def.default
+        if not value:
+            if key_def.required:
+                missing.append(key)
+            continue
+        entries.append({"key": key, "value": value})
+
+    if missing:
+        raise StackgenError(
+            "upsert_integration_with_secrets missing required Vault keys: "
+            + ", ".join(missing)
+        )
+
+    # Preserve extra caller keys not listed in metadata (optional extras).
+    for raw_key, raw_val in secrets.items():
+        key = _as_str(raw_key)
+        val = _as_str(raw_val)
+        if not key or not val:
+            continue
+        snake = _camel_to_snake(key)
+        if key in seen or snake in seen:
+            continue
+        entries.append({"key": snake if snake != key else key, "value": val})
+
+    if not entries:
+        raise StackgenError("upsert_integration_with_secrets requires secrets")
+    return entries
+
+
+class IntegrationSecretsJourney:
+    """Store Vault credentials, bind ``secret_ref_ids``, upsert an integration."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+        self._vault = VaultNamespace(config)
+        self._resources = AidenResources(config)
+
+    def upsert(
+        self,
+        name: str,
+        *,
+        type: str,
+        secrets: dict[str, str],
+        description: str | None = None,
+        secret_name: str | None = None,
+        scope: str = "TENANT",
+        enabled: bool = True,
+        env: dict[str, str] | None = None,
+        runner_id: str | None = None,
+        skip_connectivity_check: bool | None = None,
+        vault_category: str | None = None,
+        vault_subcategory: str | None = None,
+        integration: dict[str, Any] | None = None,
+        # Deprecated: ignored when metadata resolves; kept for call-site compat.
+        kind: str | None = None,
+    ) -> dict[str, Any]:
+        """Happy path: Vault store → bind ``secret_ref_ids`` → PUT integration.
+
+        ``secrets`` is a plain key/value map. The SDK resolves Vault
+        category/subcategory and required keys from Aiden's integration catalog
+        and Vault ``GET /support/metadata``. Pass ``vault_category`` /
+        ``vault_subcategory`` to override discovery.
+
+        Returns ``{"integration", "secret_ids", "secrets"}``.
+        """
+        del kind  # metadata-driven; kept only for backward-compatible kwargs
+        clean_name = _as_str(name)
+        clean_type = _as_str(type)
+        if not clean_name:
+            raise StackgenError("upsert_integration_with_secrets requires name")
+        if not clean_type:
+            raise StackgenError("upsert_integration_with_secrets requires type")
+        if not isinstance(secrets, dict) or not secrets:
+            raise StackgenError("upsert_integration_with_secrets requires secrets")
+
+        vault_name = _as_str(secret_name) or f"{clean_name}-creds"
+        vault_desc = _as_str(description) or f"{clean_type} integration credentials"
+
+        category, subcategory, value = self._resolve_secret_payload(
+            clean_type,
+            secrets,
+            vault_category=_as_str(vault_category) or None,
+            vault_subcategory=_as_str(vault_subcategory) or None,
+        )
+
+        skip = skip_connectivity_check
+        if skip is None:
+            # Connectivity checks often fail for runner-bound / synthetic secrets.
+            skip = True
+
+        shared_with = [self._config.org_id] if self._config.org_id else []
+        stored = self._vault.store_secret(
+            {
+                "name": vault_name,
+                "description": vault_desc,
+                "category": category,
+                "subcategory": subcategory,
+                "value": value,
+                "sharedWith": shared_with,
+                "skip_connectivity_check": skip,
+            }
+        )
+
+        secret_id = _as_str(stored.get("id"))
+        if not secret_id:
+            raise StackgenError(
+                "upsert_integration_with_secrets: Vault store did not return id"
+            )
+
+        body: dict[str, Any] = {
+            "type": clean_type,
+            "description": _as_str(description) or f"{clean_type} integration",
+            "scope": scope,
+            "enabled": enabled,
+            "secret_ref_ids": [secret_id],
+        }
+        if env is not None:
+            body["env"] = env
+        if runner_id is not None:
+            body["runner_id"] = runner_id
+        if integration:
+            body.update(integration)
+        # Owned credential binding wins over accidental overrides in integration{}
+        body["secret_ref_ids"] = [secret_id]
+        body["type"] = clean_type
+
+        integration_row = self._resources.upsert_integration(clean_name, body)
+        return {
+            "integration": integration_row,
+            "secret_ids": [secret_id],
+            "secrets": [stored],
+        }
+
+    def _resolve_secret_payload(
+        self,
+        type_name: str,
+        secrets: dict[str, str],
+        *,
+        vault_category: str | None,
+        vault_subcategory: str | None,
+    ) -> tuple[str, str, list[dict[str, str]]]:
+        subcategory = vault_subcategory
+        if not subcategory:
+            types = self._resources.list_integration_types()
+            type_row = _find_integration_type(types, type_name)
+            if type_row:
+                linked = _as_str(type_row.get("linked_vault_subcategory"))
+                subcategory = linked or _as_str(type_row.get("type")) or type_name
+            else:
+                subcategory = type_name
+
+        metadata = self._vault.get_supported_metadata()
+        row = find_supported_format(metadata, subcategory)
+
+        if row:
+            category = vault_category or row.category
+            if not category:
+                raise StackgenError(
+                    f"Vault metadata for subcategory={subcategory!r} has no category"
+                )
+            subcategory = row.subcategory or subcategory
+            value = _build_value_entries(secrets, row.keys)
+            return category, subcategory, value
+
+        if vault_category and vault_subcategory:
+            # Explicit overrides without a catalog row: trust the caller.
+            value = [
+                {"key": _camel_to_snake(k) if k else k, "value": v}
+                for k, v in secrets.items()
+                if _as_str(k) and _as_str(v)
+            ]
+            if not value:
+                raise StackgenError("upsert_integration_with_secrets requires secrets")
+            return vault_category, vault_subcategory, value
+
+        # Fallback for common types when metadata is unavailable (preserves
+        # github / grafana / kafka behavior from earlier SDK releases).
+        fallback = self._legacy_fallback(type_name, secrets)
+        if fallback:
+            return fallback
+
+        raise StackgenError(
+            "upsert_integration_with_secrets could not resolve Vault metadata "
+            f"for type={type_name!r} subcategory={subcategory!r}. "
+            "Pass vault_category and vault_subcategory, or ensure Vault "
+            "GET /support/metadata lists that subcategory."
+        )
+
+    def _legacy_fallback(
+        self, type_name: str, secrets: dict[str, str]
+    ) -> tuple[str, str, list[dict[str, str]]] | None:
+        kind = _norm(type_name)
+        if kind == "github":
+            token = _pick(secrets, "token")
+            if not token:
+                raise StackgenError("github secrets require token")
+            return "scm", "github", [{"key": "token", "value": token}]
+        if kind == "grafana":
+            base_url = _pick(secrets, "base_url", "baseUrl")
+            api_token = _pick(secrets, "api_token", "apiToken")
+            if not base_url or not api_token:
+                raise StackgenError(
+                    "grafana secrets require base_url (or baseUrl) and "
+                    "api_token (or apiToken)"
+                )
+            return (
+                "Observability",
+                "grafana",
+                [
+                    {"key": "base_url", "value": base_url},
+                    {"key": "api_token", "value": api_token},
+                ],
+            )
+        if kind == "kafka":
+            bootstrap = _pick(secrets, "bootstrap_servers", "bootstrapServers")
+            if not bootstrap:
+                raise StackgenError(
+                    "kafka secrets require bootstrap_servers (or bootstrapServers)"
+                )
+            value = [{"key": "bootstrap_servers", "value": bootstrap}]
+            for wire, *aliases in (
+                ("security_protocol", "securityProtocol"),
+                ("sasl_mechanism", "saslMechanism"),
+                ("sasl_username", "saslUsername"),
+                ("sasl_password", "saslPassword"),
+            ):
+                found = _pick(secrets, wire, *aliases)
+                if found:
+                    value.append({"key": wire, "value": found})
+            return "Messaging", "kafka", value
+        return None

{stackgen_sdk-0.4.0rc13 → stackgen_sdk-0.4.0rc15}/src/stackgen/aiden/namespace.py

@@ -3,10 +3,14 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Iterator
+from typing import Any, Iterator, Literal
 
 from stackgen.aiden.ask import AskArtifactJourney, AskArtifactResult
 from stackgen.aiden.audit import AuditExportJourney, AuditExportResult
+from stackgen.aiden.integration_secrets import (
+    IntegrationSecretKind,
+    IntegrationSecretsJourney,
+)
 from stackgen.aiden.models import ModelRegistry
 from stackgen.aiden.resources import AidenResources, PolicyConflictRule
 from stackgen.aiden.run_status import RunStatus, build_run_status, require_run_ids
@@ -29,6 +33,7 @@ class AidenNamespace:
         self._workflows = WorkflowPublishJourney(config)
         self._webhook_ops = WebhookOps(config)
         self._resources = AidenResources(config)
+        self._integration_secrets = IntegrationSecretsJourney(config)
         self._subscribe = ExecutionSubscribe(config)
         self._audit = AuditExportJourney(config)
         self.models = ModelRegistry(config)
@@ -160,6 +165,7 @@ class AidenNamespace:
         session_id: str | None = None,
         source_app: str | None = None,
         source_metadata: dict[str, str] | None = None,
+        mode: Literal["plan", "simple"] | None = None,
     ) -> AskArtifactResult:
         """Start Ask Guild, poll execution, wait for artifact, download it."""
         return self._ask.run(
@@ -171,6 +177,7 @@ class AidenNamespace:
             session_id=session_id,
             source_app=source_app,
             source_metadata=source_metadata,
+            mode=mode,
         )
 
     def start_ask(
@@ -182,12 +189,14 @@ class AidenNamespace:
         session_id: str | None = None,
         source_app: str | None = None,
         source_metadata: dict[str, str] | None = None,
+        mode: Literal["plan", "simple"] | None = None,
     ) -> dict[str, Any]:
         """POST /guild/api/v1/guild/ask/start (fire-and-forget).
 
         Returns ``session_id`` / ``trace_id`` immediately. Persist those ids and
         call :meth:`get_run_status` from a separate scheduler — this method does
-        not wait for completion.
+        not wait for completion. Pass ``mode="plan"`` or ``"simple"`` to pin
+        Genie execution for the session.
         """
         return self._ask.start_ask(
             message,
@@ -196,6 +205,7 @@ class AidenNamespace:
             session_id=session_id,
             source_app=source_app,
             source_metadata=source_metadata,
+            mode=mode,
         )
 
     def start_workflow_run(
@@ -286,6 +296,14 @@ class AidenNamespace:
         return self._workflows.publish(workflow, agents=agents, approve=approve)
 
     # Expanded allowlisted surface (thin REST) — delegated to AidenResources.
+    def register_agent(self, body: dict[str, Any]) -> dict[str, Any]:
+        """POST /agents — register with integrations, HITL, runners, and related fields."""
+        return self._resources.register_agent(body)
+
+    def update_agent(self, name: str, body: dict[str, Any]) -> dict[str, Any]:
+        """PUT /agents/{name} — update mutable fields (full-list semantics when provided)."""
+        return self._resources.update_agent(name, body)
+
     def get_agent(self, name: str) -> dict[str, Any]:
         return self._resources.get_agent(name)
 
@@ -326,12 +344,65 @@ class AidenNamespace:
     def list_integration_types(self) -> list[dict[str, Any]]:
         return self._resources.list_integration_types()
 
-    def get_integration(self, name: str) -> dict[str, Any]:
-        return self._resources.get_integration(name)
+    def get_integration(
+        self,
+        name: str,
+        *,
+        include_tools: bool = True,
+    ) -> dict[str, Any]:
+        """GET integration; defaults to include_tools so discovered_tools populate."""
+        return self._resources.get_integration(name, include_tools=include_tools)
 
     def upsert_integration(self, name: str, body: dict[str, Any]) -> dict[str, Any]:
         return self._resources.upsert_integration(name, body)
 
+    def upsert_integration_with_secrets(
+        self,
+        name: str,
+        *,
+        type: str,
+        secrets: dict[str, str],
+        kind: IntegrationSecretKind | None = None,
+        description: str | None = None,
+        secret_name: str | None = None,
+        scope: str = "TENANT",
+        enabled: bool = True,
+        env: dict[str, str] | None = None,
+        runner_id: str | None = None,
+        skip_connectivity_check: bool | None = None,
+        vault_category: str | None = None,
+        vault_subcategory: str | None = None,
+        integration: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Store Vault credentials, bind ``secret_ref_ids``, and upsert an integration.
+
+        Pass a plain ``secrets`` map; the SDK resolves Vault category,
+        subcategory, and required keys from Aiden's catalog and Vault
+        ``GET /support/metadata``. Override with ``vault_category`` /
+        ``vault_subcategory`` when discovery is wrong or unavailable.
+
+        Advanced callers can still ``vault.store_*_secret`` then
+        ``upsert_integration(..., secret_ref_ids=[...])`` themselves.
+
+        Returns ``{"integration", "secret_ids", "secrets"}``.
+        """
+        return self._integration_secrets.upsert(
+            name,
+            type=type,
+            secrets=secrets,
+            kind=kind,
+            description=description,
+            secret_name=secret_name,
+            scope=scope,
+            enabled=enabled,
+            env=env,
+            runner_id=runner_id,
+            skip_connectivity_check=skip_connectivity_check,
+            vault_category=vault_category,
+            vault_subcategory=vault_subcategory,
+            integration=integration,
+        )
+
     def delete_integration(self, name: str) -> dict[str, Any]:
         return self._resources.delete_integration(name)
 
@@ -344,6 +415,10 @@ class AidenNamespace:
     def list_approvals(self, **params: Any) -> list[dict[str, Any]]:
         return self._resources.list_approvals(**params)
 
+    def get_approval(self, approval_id: str) -> dict[str, Any]:
+        """GET /approvals/{id}."""
+        return self._resources.get_approval(approval_id)
+
     def resolve_approval(self, approval_id: str, body: dict[str, Any]) -> dict[str, Any]:
         return self._resources.resolve_approval(approval_id, body)
 

{stackgen_sdk-0.4.0rc13 → stackgen_sdk-0.4.0rc15}/src/stackgen/aiden/resources.py

@@ -31,7 +31,11 @@ def _with_org(config: StackgenConfig, params: dict[str, Any] | None = None) -> d
 
 
 def _query_string(params: dict[str, Any]) -> str:
-    cleaned = {k: v for k, v in params.items() if v is not None and v != ""}
+    cleaned: dict[str, Any] = {}
+    for k, v in params.items():
+        if v is None or v == "":
+            continue
+        cleaned[k] = "true" if v is True else "false" if v is False else v
     if not cleaned:
         return ""
     return "?" + urllib.parse.urlencode(cleaned)
@@ -69,6 +73,14 @@ class AidenResources:
             kwargs["content_type"] = "application/json"
         return _http.request(self._url(path, params), self._config.api_token, **kwargs)
 
+    def register_agent(self, body: dict[str, Any]) -> dict[str, Any]:
+        """POST /agents — register with full config (integrations, HITL, runners, …)."""
+        return _as_object(self._send("/agents", "POST", body), "registerAgent")
+
+    def update_agent(self, name: str, body: dict[str, Any]) -> dict[str, Any]:
+        """PUT /agents/{name} — update mutable fields (full-list when provided)."""
+        return _as_object(self._send(f"/agents/{name}", "PUT", body), "updateAgent")
+
     def get_agent(self, name: str) -> dict[str, Any]:
         return _as_object(self._get(f"/agents/{name}"), "getAgent")
 
@@ -116,8 +128,17 @@ class AidenResources:
     def list_integration_types(self) -> list[dict[str, Any]]:
         return _http.as_list(self._get("/integrations/types"))
 
-    def get_integration(self, name: str) -> dict[str, Any]:
-        return _as_object(self._get(f"/integrations/{name}"), "getIntegration")
+    def get_integration(
+        self,
+        name: str,
+        *,
+        include_tools: bool = True,
+    ) -> dict[str, Any]:
+        """GET /integrations/{name}. Defaults to include_tools so discovered_tools populate."""
+        return _as_object(
+            self._get(f"/integrations/{name}", {"include_tools": include_tools}),
+            "getIntegration",
+        )
 
     def upsert_integration(self, name: str, body: dict[str, Any]) -> dict[str, Any]:
         return _as_object(
@@ -144,6 +165,10 @@ class AidenResources:
     def list_approvals(self, **params: Any) -> list[dict[str, Any]]:
         return _http.as_list(self._get("/approvals", params))
 
+    def get_approval(self, approval_id: str) -> dict[str, Any]:
+        """GET /approvals/{id} — one pending or historical HITL approval."""
+        return _as_object(self._get(f"/approvals/{approval_id}"), "getApproval")
+
     def resolve_approval(self, approval_id: str, body: dict[str, Any]) -> dict[str, Any]:
         return _as_object(
             self._send(f"/approvals/{approval_id}", "POST", body), "resolveApproval"

{stackgen_sdk-0.4.0rc13 → stackgen_sdk-0.4.0rc15}/src/stackgen/config.py

@@ -52,8 +52,8 @@ class StackgenConfig:
         return self.mothership() + "/app/sre"
 
     def vault_url(self) -> str:
-        """HTTP prefix for Vault on the mothership edge."""
-        return self.mothership() + "/vault/v1"
+        """HTTP prefix for Vault on the mothership edge (``/api/vault/v1``)."""
+        return self.mothership() + "/api/vault/v1"
 
     def appcd_url(self) -> str:
         """HTTP prefix for organization (project) management."""