general-augment-cli 0.1.0__tar.gz

general_augment_cli-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+packages/cli/uv.lock
+
+# Environment
+.env
+.env.local
+.env.gcp
+hermes-tenants/
+
+# Secrets
+*.pem
+*.key
+*.p12
+*.pfx
+.jks
+service-account.json
+.clerk/
+
+# Docker
+*.log
+docker-data/
+
+# IDE
+.idea/
+.vscode/
+
+# Build
+build/
+dist/
+*.egg-info/
+node_modules/
+.next/
+dashboard/.vercel/
+coverage/
+playwright-report/
+test-results/
+*.tsbuildinfo
+artifacts/
+dashboard/artifacts/
+
+# Kubernetes secrets
+k8s/secrets/*
+!k8s/secrets/.gitkeep
+
+# OS
+.DS_Store
+.vercel

general_augment_cli-0.1.0/AGENTS.md

@@ -0,0 +1,15 @@
+# CLI Agent Instructions
+
+These instructions apply under `packages/cli/`.
+
+Inherit [`packages/AGENTS.md`](../AGENTS.md) and the repo root
+[`AGENTS.md`](../../AGENTS.md).
+
+## Scope
+
+- The public CLI command is `genaug`.
+- The primary manifest is `genaug-agent.yaml`.
+- Help text, scaffolds, examples, and generated output should prefer General Augment
+  branding and omit runtime-selection fields.
+- If CLI behavior changes, update `packages/cli/README.md`, docs under `docs/public/`,
+  docs-site CLI pages, and CLI tests in the same change.

general_augment_cli-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: general-augment-cli
+Version: 0.1.0
+Summary: Standalone CLI for General Augment.
+Author: General Augment
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# General Augment CLI
+
+Standalone developer CLI for General Augment.
+
+During private beta, use the repo-local command prefix unless the published package is
+available in your Python package index:
+
+```bash
+uv run --project packages/cli genaug --version
+uv run --project packages/cli genaug --help
+```
+
+When the package is available, the same commands work through the installed `genaug`
+entrypoint:
+
+```bash
+pip install general-augment-cli
+genaug --version
+genaug auth login --api-key gaadmlive...
+genaug doctor
+genaug projects list
+genaug init dayplan-agent --tool web_search
+genaug integrate https://petstore3.swagger.io/api/v3/openapi.json
+genaug validate ./petstore-agent/genaug-agent.yaml
+genaug deploy ./petstore-agent/genaug-agent.yaml
+genaug keys create --project petstore-agent --name "Production backend"
+genaug mock --host 127.0.0.1 --port 8787 --quiet
+genaug smoke --idempotency-key smoke-replay-1 --metadata feature=spark
+genaug smoke --project petstore-agent
+genaug verify --project petstore-agent
+genaug onboarding verify --project petstore-agent --json
+```
+
+If the package install fails during private beta, keep using
+`uv run --project packages/cli genaug ...` from the General Augment repository instead
+of assuming the package has shipped to your package index.
+
+`genaug auth login` verifies the key against `/api/v1/admin/me` before writing local
+config. The CLI stores auth at `~/.genaug/config.yaml` by default with owner-only file
+permissions. Set
+`GENAUG_CLI_CONFIG` to use a custom path.
+
+Preferred environment overrides:
+
+```bash
+export GENAUG_ADMIN_API_KEY=gaadmlive...
+export GENAUG_ADMIN_BASE_URL=https://api.generalaugment.com
+```
+
+`GENAUG_API_KEY` and `GENAUG_API_BASE_URL` are also accepted, which keeps local
+mock and SDK test scripts easy to share.
+
+The generated manifest is `genaug-agent.yaml`. Use `genaug init <name>` when you want
+a starter agent before an OpenAPI spec exists. Use
+`genaug integrate <openapi-spec> --auto-deploy` when you want the CLI to create or
+update the project and register the generated OpenAPI tools in one pass. Without
+`--auto-deploy`, review the scaffold first, then run
+`genaug validate ./<agent>/genaug-agent.yaml` and
+`genaug deploy ./<agent>/genaug-agent.yaml`. `deploy` runs the same local validation
+before calling the hosted API. Both scaffolds include
+`CODING_AGENT_PROMPT.md`, which is the paste-ready backend handoff for a coding agent.
+
+## Common workflows
+
+- Auth: `genaug auth login`, `genaug auth whoami`, `genaug auth logout`
+- Starter scaffold: `genaug init <name> --tool web_search`
+- Local config validation: `genaug validate ./genaug-agent.yaml --json`
+- Projects: `genaug projects list`, `genaug projects create`, `genaug projects usage`,
+  `genaug projects runtime-policy`, `genaug projects export`, `genaug projects archive`
+- API keys: `genaug keys create`, `genaug keys list`, `genaug keys update`,
+  `genaug keys revoke`
+- Skills, tools, and channels: `genaug skills list`, `genaug skills view`,
+  `genaug skills apply`, `genaug skills delete`, `genaug tools list`, `genaug tools toggle`,
+  `genaug tools discovery`, `genaug channels status`, `genaug channels connect`,
+  `genaug channels test`, `genaug channels disconnect`. Telegram supports connect,
+  test, and disconnect; WhatsApp/SMS support sender configuration and clearing.
+- MCP servers: `genaug mcp list`, `genaug mcp add`, `genaug mcp test`,
+  `genaug mcp delete`. Use exactly one transport per server: `--url` for HTTP
+  endpoints or `--command` for stdio servers.
+- Model providers: `genaug model-providers list`, `genaug model-providers set`,
+  `genaug model-providers health`, `genaug model-providers revoke`
+- Billing: `genaug billing checkout`, `genaug billing portal`,
+  `genaug billing events`
+- Memory: `genaug memory store`, `genaug memory search`, `genaug memory profile`,
+  `genaug memory delete`, `genaug memory purge-user`
+- Users and identity: `genaug users list`, `genaug users detail`,
+  `genaug users delete`, `genaug identity list`, `genaug identity create-test`,
+  `genaug identity link-user`, `genaug identity verification-code`,
+  `genaug identity magic-link`, `genaug identity verify`,
+  `genaug identity resolve`, `genaug identity unlink`
+- Observability: `genaug observability trace`, `genaug observability support-bundle`
+- Approvals: `genaug approvals list`, `genaug approvals approve`, `genaug approvals deny`
+- Operations: `genaug doctor`, `genaug status`, `genaug logs`
+- App smoke checks: `genaug smoke --message "Reply exactly with: ok"`,
+  `genaug smoke --structured`, `genaug smoke --json`
+- Project acceptance checks: `genaug verify --project <project-slug>`, which checks
+  project keys, hosted agent test, tools, logs, usage, usage limits, observability,
+  runtime policy model routing, memory lifecycle, and tool-call audit before printing
+  dashboard URLs for the same tenant.
+- One-command onboarding gate: `genaug onboarding verify --project <project-slug> --json`,
+  which wraps the same project checks with CLI/API version metadata and a coding-agent
+  friendly ready/blocked payload.
+- Local development: `genaug dev ./genaug-agent.yaml --message "Hello"`
+- Local mock testing: `genaug mock --host 127.0.0.1 --port 8787 --quiet`
+
+## Billing
+
+```bash
+genaug billing checkout --project dayplan-agent --tier pro
+genaug billing portal --project dayplan-agent
+genaug billing events --project dayplan-agent --json
+```
+
+Use these commands for hosted billing actions when Stripe is configured for the
+project. `checkout` returns a hosted Stripe Checkout URL for Pro or Team, `portal`
+returns a hosted Stripe Customer Portal URL for linked customers, and `events` lists
+stored Stripe webhook events such as checkout completion, invoice payment, and payment
+failure. These commands do not create Stripe products, prices, or webhooks directly;
+those stay in the server-side billing setup and readiness flow.
+
+For a full CLI-to-dashboard onboarding proof from this repository, run:
+
+```bash
+make app-developer-onboarding-smoke
+```
+
+That harness creates a fresh dummy tenant from a richer OpenAPI fixture, proves
+generated tool governance, deploys SOUL.md and skills, sends real `/v1/responses`
+smokes for multiple app users, runs `genaug verify --json`, starts an owned dashboard
+dev server, and writes JSON evidence plus screenshots for the project overview, skills,
+tools, integrate, and analytics pages. Add `GENAUG_DASHBOARD_SMOKE_ARCHIVE_PROJECT=1`
+when CI should archive the created smoke project after the artifact is captured.
+
+`genaug smoke` checks `/health/ready` and sends one project-keyed `/v1/responses`
+request using bearer auth. Use `--idempotency-key`, `--request-id`, `--traceparent`,
+and repeated `--metadata key=value` flags when you need replayable support/debug
+evidence from hosted API or the local mock. Use `--project <project-slug>` when the
+configured key is a management key and the app-facing request needs `X-Project-ID`.
+Use `--structured` to request the default `json_schema` smoke response, or
+`--schema-file ./schema.json` to verify an app-specific structured-output contract.
+With `--json`, smoke output includes the `/health/ready` payload, the full
+`/v1/responses` object, `response_id`, `request_id`, and `trace_id` so automation can
+prove health and tracing from one command.
+
+When the API returns a rate-limit `429`, the CLI prints the stable reason and
+`Retry-After` timing when the platform includes them.
+
+`genaug doctor` checks the resolved config path, base URL, API key presence,
+`/health/ready`, and `/api/v1/admin/me` without printing secret values. Run it before
+`integrate` when a new developer is unsure whether local auth or network setup is the
+problem.
+
+`genaug mock` runs the deterministic local HTTP mock. Use it for offline app contract tests against
+`/v1/responses`, memory routes, project setup, OpenAPI tool registration, key
+management, logs, usage, observability, health checks, idempotency replays, trace
+metadata, structured-output fixtures, and semantic SSE fixtures.
+
+The console commands are defined in `pyproject.toml`:
+
+```toml
+[project.scripts]
+genaug = "platform_cli.main:app"
+```

general_augment_cli-0.1.0/README.md

@@ -0,0 +1,163 @@
+# General Augment CLI
+
+Standalone developer CLI for General Augment.
+
+During private beta, use the repo-local command prefix unless the published package is
+available in your Python package index:
+
+```bash
+uv run --project packages/cli genaug --version
+uv run --project packages/cli genaug --help
+```
+
+When the package is available, the same commands work through the installed `genaug`
+entrypoint:
+
+```bash
+pip install general-augment-cli
+genaug --version
+genaug auth login --api-key gaadmlive...
+genaug doctor
+genaug projects list
+genaug init dayplan-agent --tool web_search
+genaug integrate https://petstore3.swagger.io/api/v3/openapi.json
+genaug validate ./petstore-agent/genaug-agent.yaml
+genaug deploy ./petstore-agent/genaug-agent.yaml
+genaug keys create --project petstore-agent --name "Production backend"
+genaug mock --host 127.0.0.1 --port 8787 --quiet
+genaug smoke --idempotency-key smoke-replay-1 --metadata feature=spark
+genaug smoke --project petstore-agent
+genaug verify --project petstore-agent
+genaug onboarding verify --project petstore-agent --json
+```
+
+If the package install fails during private beta, keep using
+`uv run --project packages/cli genaug ...` from the General Augment repository instead
+of assuming the package has shipped to your package index.
+
+`genaug auth login` verifies the key against `/api/v1/admin/me` before writing local
+config. The CLI stores auth at `~/.genaug/config.yaml` by default with owner-only file
+permissions. Set
+`GENAUG_CLI_CONFIG` to use a custom path.
+
+Preferred environment overrides:
+
+```bash
+export GENAUG_ADMIN_API_KEY=gaadmlive...
+export GENAUG_ADMIN_BASE_URL=https://api.generalaugment.com
+```
+
+`GENAUG_API_KEY` and `GENAUG_API_BASE_URL` are also accepted, which keeps local
+mock and SDK test scripts easy to share.
+
+The generated manifest is `genaug-agent.yaml`. Use `genaug init <name>` when you want
+a starter agent before an OpenAPI spec exists. Use
+`genaug integrate <openapi-spec> --auto-deploy` when you want the CLI to create or
+update the project and register the generated OpenAPI tools in one pass. Without
+`--auto-deploy`, review the scaffold first, then run
+`genaug validate ./<agent>/genaug-agent.yaml` and
+`genaug deploy ./<agent>/genaug-agent.yaml`. `deploy` runs the same local validation
+before calling the hosted API. Both scaffolds include
+`CODING_AGENT_PROMPT.md`, which is the paste-ready backend handoff for a coding agent.
+
+## Common workflows
+
+- Auth: `genaug auth login`, `genaug auth whoami`, `genaug auth logout`
+- Starter scaffold: `genaug init <name> --tool web_search`
+- Local config validation: `genaug validate ./genaug-agent.yaml --json`
+- Projects: `genaug projects list`, `genaug projects create`, `genaug projects usage`,
+  `genaug projects runtime-policy`, `genaug projects export`, `genaug projects archive`
+- API keys: `genaug keys create`, `genaug keys list`, `genaug keys update`,
+  `genaug keys revoke`
+- Skills, tools, and channels: `genaug skills list`, `genaug skills view`,
+  `genaug skills apply`, `genaug skills delete`, `genaug tools list`, `genaug tools toggle`,
+  `genaug tools discovery`, `genaug channels status`, `genaug channels connect`,
+  `genaug channels test`, `genaug channels disconnect`. Telegram supports connect,
+  test, and disconnect; WhatsApp/SMS support sender configuration and clearing.
+- MCP servers: `genaug mcp list`, `genaug mcp add`, `genaug mcp test`,
+  `genaug mcp delete`. Use exactly one transport per server: `--url` for HTTP
+  endpoints or `--command` for stdio servers.
+- Model providers: `genaug model-providers list`, `genaug model-providers set`,
+  `genaug model-providers health`, `genaug model-providers revoke`
+- Billing: `genaug billing checkout`, `genaug billing portal`,
+  `genaug billing events`
+- Memory: `genaug memory store`, `genaug memory search`, `genaug memory profile`,
+  `genaug memory delete`, `genaug memory purge-user`
+- Users and identity: `genaug users list`, `genaug users detail`,
+  `genaug users delete`, `genaug identity list`, `genaug identity create-test`,
+  `genaug identity link-user`, `genaug identity verification-code`,
+  `genaug identity magic-link`, `genaug identity verify`,
+  `genaug identity resolve`, `genaug identity unlink`
+- Observability: `genaug observability trace`, `genaug observability support-bundle`
+- Approvals: `genaug approvals list`, `genaug approvals approve`, `genaug approvals deny`
+- Operations: `genaug doctor`, `genaug status`, `genaug logs`
+- App smoke checks: `genaug smoke --message "Reply exactly with: ok"`,
+  `genaug smoke --structured`, `genaug smoke --json`
+- Project acceptance checks: `genaug verify --project <project-slug>`, which checks
+  project keys, hosted agent test, tools, logs, usage, usage limits, observability,
+  runtime policy model routing, memory lifecycle, and tool-call audit before printing
+  dashboard URLs for the same tenant.
+- One-command onboarding gate: `genaug onboarding verify --project <project-slug> --json`,
+  which wraps the same project checks with CLI/API version metadata and a coding-agent
+  friendly ready/blocked payload.
+- Local development: `genaug dev ./genaug-agent.yaml --message "Hello"`
+- Local mock testing: `genaug mock --host 127.0.0.1 --port 8787 --quiet`
+
+## Billing
+
+```bash
+genaug billing checkout --project dayplan-agent --tier pro
+genaug billing portal --project dayplan-agent
+genaug billing events --project dayplan-agent --json
+```
+
+Use these commands for hosted billing actions when Stripe is configured for the
+project. `checkout` returns a hosted Stripe Checkout URL for Pro or Team, `portal`
+returns a hosted Stripe Customer Portal URL for linked customers, and `events` lists
+stored Stripe webhook events such as checkout completion, invoice payment, and payment
+failure. These commands do not create Stripe products, prices, or webhooks directly;
+those stay in the server-side billing setup and readiness flow.
+
+For a full CLI-to-dashboard onboarding proof from this repository, run:
+
+```bash
+make app-developer-onboarding-smoke
+```
+
+That harness creates a fresh dummy tenant from a richer OpenAPI fixture, proves
+generated tool governance, deploys SOUL.md and skills, sends real `/v1/responses`
+smokes for multiple app users, runs `genaug verify --json`, starts an owned dashboard
+dev server, and writes JSON evidence plus screenshots for the project overview, skills,
+tools, integrate, and analytics pages. Add `GENAUG_DASHBOARD_SMOKE_ARCHIVE_PROJECT=1`
+when CI should archive the created smoke project after the artifact is captured.
+
+`genaug smoke` checks `/health/ready` and sends one project-keyed `/v1/responses`
+request using bearer auth. Use `--idempotency-key`, `--request-id`, `--traceparent`,
+and repeated `--metadata key=value` flags when you need replayable support/debug
+evidence from hosted API or the local mock. Use `--project <project-slug>` when the
+configured key is a management key and the app-facing request needs `X-Project-ID`.
+Use `--structured` to request the default `json_schema` smoke response, or
+`--schema-file ./schema.json` to verify an app-specific structured-output contract.
+With `--json`, smoke output includes the `/health/ready` payload, the full
+`/v1/responses` object, `response_id`, `request_id`, and `trace_id` so automation can
+prove health and tracing from one command.
+
+When the API returns a rate-limit `429`, the CLI prints the stable reason and
+`Retry-After` timing when the platform includes them.
+
+`genaug doctor` checks the resolved config path, base URL, API key presence,
+`/health/ready`, and `/api/v1/admin/me` without printing secret values. Run it before
+`integrate` when a new developer is unsure whether local auth or network setup is the
+problem.
+
+`genaug mock` runs the deterministic local HTTP mock. Use it for offline app contract tests against
+`/v1/responses`, memory routes, project setup, OpenAPI tool registration, key
+management, logs, usage, observability, health checks, idempotency replays, trace
+metadata, structured-output fixtures, and semantic SSE fixtures.
+
+The console commands are defined in `pyproject.toml`:
+
+```toml
+[project.scripts]
+genaug = "platform_cli.main:app"
+```

general_augment_cli-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "general-augment-cli"
+version = "0.1.0"
+description = "Standalone CLI for General Augment."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "General Augment" }]
+dependencies = [
+  "typer[all]>=0.12.0",
+  "httpx>=0.27.0",
+  "rich>=13.7.0",
+  "pyyaml>=6.0.0",
+  "pydantic>=2.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+genaug = "platform_cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/platform_cli"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "ASYNC", "B", "C4", "G", "RUF"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true

general_augment_cli-0.1.0/src/platform_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Standalone CLI package for the agent platform."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

general_augment_cli-0.1.0/src/platform_cli/branding.py

@@ -0,0 +1,27 @@
+"""Small branding model for standalone CLI copy."""
+
+from __future__ import annotations
+
+import os
+
+from pydantic import BaseModel, Field
+
+
+class Branding(BaseModel):
+    """User-facing CLI branding loaded from environment variables."""
+
+    product_name: str = Field(
+        default_factory=lambda: os.getenv("BRAND_PRODUCT_NAME", "General Augment"),
+    )
+    product_slug: str = Field(
+        default_factory=lambda: os.getenv("BRAND_PRODUCT_SLUG", "general-augment"),
+    )
+    docs_url: str = Field(
+        default_factory=lambda: os.getenv("BRAND_DOCS_URL", "https://docs.generalaugment.com"),
+    )
+    api_key_prefix: str = Field(default_factory=lambda: os.getenv("BRAND_API_KEY_PREFIX", "gaadm"))
+
+
+def get_branding() -> Branding:
+    """Return current process branding."""
+    return Branding()

general_augment_cli-0.1.0/src/platform_cli/client.py

@@ -0,0 +1,179 @@
+"""Thin HTTP client for the standalone CLI."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from platform_cli.config import CLIConfig
+from platform_cli.errors import APIError, CLIError
+
+ADMIN_PREFIX = "/api/v1/admin"
+INTEGRATIONS_PREFIX = "/api/v1/integrations"
+REQUEST_TIMEOUT_SECONDS = 30.0
+
+
+class PlatformClient:
+    """Synchronous HTTP client for platform admin and public endpoints."""
+
+    def __init__(self, config: CLIConfig, *, timeout: float = REQUEST_TIMEOUT_SECONDS) -> None:
+        """Initialize the client from CLI config."""
+        self.config = config
+        self.base_url = config.base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> PlatformClient:
+        """Return this client in context managers."""
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Close this client."""
+        self.close()
+
+    def admin(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Call an admin API endpoint."""
+        if not self.config.api_key:
+            raise CLIError("No API key configured. Run genaug auth login first.")
+        return self._request(
+            method,
+            f"{ADMIN_PREFIX}{path}",
+            json=json,
+            params=params,
+            authenticated=True,
+        )
+
+    def public(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Call a public API endpoint."""
+        return self._request(method, path, params=params, authenticated=False)
+
+    def integrations(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Call an app-integration endpoint with admin API-key auth."""
+        if not self.config.api_key:
+            raise CLIError("No API key configured. Run genaug auth login first.")
+        return self._request(
+            method,
+            f"{INTEGRATIONS_PREFIX}{path}",
+            json=json,
+            params=params,
+            authenticated=True,
+        )
+
+    def app(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Call an app-facing endpoint using bearer auth."""
+        if not self.config.api_key:
+            raise CLIError("No API key configured. Run genaug auth login first.")
+        return self._request(
+            method,
+            path,
+            json=json,
+            params=params,
+            extra_headers=headers,
+            authenticated=True,
+            auth_mode="bearer",
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+        authenticated: bool,
+        auth_mode: str = "admin",
+    ) -> Any:
+        """Send one request and decode the response."""
+        headers: dict[str, str] = {}
+        if authenticated and self.config.api_key:
+            if auth_mode == "bearer":
+                headers["Authorization"] = f"Bearer {self.config.api_key}"
+            else:
+                headers["X-Admin-Key"] = self.config.api_key
+        headers.update(dict(extra_headers or {}))
+        try:
+            response = self._client.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=headers,
+                json=dict(json) if json is not None else None,
+                params=dict(params) if params is not None else None,
+            )
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.RequestError) as exc:
+            raise CLIError(f"Could not reach the platform API at {self.base_url}: {exc}") from exc
+        if response.status_code >= 400:
+            raise APIError(response.status_code, _error_detail(response), response.headers)
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            if authenticated:
+                raise CLIError(
+                    "Platform API returned malformed JSON for an authenticated request."
+                ) from exc
+            return response.text
+
+
+def resolve_project(client: PlatformClient, project_ref: str) -> dict[str, Any]:
+    """Resolve a project by id, slug, or name."""
+    payload = client.admin("GET", "/projects")
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        if project_ref in {str(item.get("id")), str(item.get("slug")), str(item.get("name"))}:
+            return item
+    raise CLIError(f"Project not found: {project_ref}")
+
+
+def encode_path_segment(value: str) -> str:
+    """Encode one path segment for safe URL interpolation."""
+    return quote(value, safe="")
+
+
+def _error_detail(response: httpx.Response) -> Any:
+    """Extract one error detail from an HTTP response."""
+    try:
+        payload = response.json()
+    except ValueError:
+        return response.text
+    if isinstance(payload, dict):
+        return payload.get("detail") or payload
+    return payload

general_augment_cli-0.1.0/src/platform_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Typer command modules for the standalone CLI."""