monarch-cloud 0.1.0__tar.gz

monarch_cloud-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: monarch-cloud
+Version: 0.1.0
+Summary: Public developer CLI for Monarch Cloud
+Author: Africa Compute Fund
+Project-URL: Homepage, https://app.africacomputefund.com
+Project-URL: Documentation, https://app.africacomputefund.com/docs
+Keywords: monarch,cloud,compute,developer-tools,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.24
+
+# Monarch Cloud CLI
+
+A lightweight public developer client for the existing Monarch REST Platform API.
+
+```bash
+python -m pip install monarch-cloud
+monarch login
+monarch whoami
+monarch catalog
+monarch gpus
+monarch models --scope catalog
+monarch jobs
+monarch wallet
+monarch init "My app" --blueprint backend
+monarch status
+monarch dev
+monarch deploy hello ./hello.js
+```
+
+**Authentication:** `monarch login` prompts for an existing Monarch REST API key
+without echoing it, validates it against `GET /v1/account/identity`, then saves
+it in a mode-0600 file under your user configuration directory. For ephemeral
+environments set `MONARCH_API_KEY` instead; this takes precedence. This is REST
+API-key login, **not** the OAuth browser flow used by the MCP connector. Key
+creation and account access are provided through Monarch Cloud.
+
+`monarch mcp` prints the public OAuth MCP endpoint for compatible AI clients;
+it does not bundle an MCP server or impersonate an OAuth token.
+
+## Command surfaces
+
+- Discovery: `catalog`, `gpus`, `models`, `datasets`, `jobs`, `job ID`,
+  `wallet`, `inference-models`, `whoami`.
+- Projects: `init`, `status`, `dev`, `deploy NAME SOURCE_JS`.
+- Migration: `migrate`, `migrate-storage`, `migrate-postgres`,
+  `migrate-gcs`, `import-documents`.
+- Account: `login`, `logout`, `mcp`.
+
+`deploy` deploys one JavaScript **Project Function**, not arbitrary whole-app
+infrastructure. Some public REST APIs and the MCP's purpose-built tools are
+not yet wrapped as CLI commands; Cloud, REST and MCP remain the source of truth.
+
+Project selection is stored in `.monarch/project.json`. The one-time Project
+server key is saved in `.monarch/server-key` and must never be committed.
+Source migration secrets are only read from environment variables or named
+credential files, not CLI arguments. The server enforces the same account,
+scope, billing, quotas, and approvals as its other public clients.
+
+## For maintainers
+
+The public release is built from the **canonical** implementation at
+`scripts/monarch_platform.py` using
+`python scripts/package_monarch_cloud.py --build`. The staging tool copies
+only this public module, the package metadata, and this README into an isolated
+temporary build directory. The private `./monarch` operator CLI, admin scripts,
+deployment infrastructure, and internal MCP server are not packaged.
+
+There is no CI publisher and no GitHub Actions workflow. The owner publishes
+the reviewed files to PyPI explicitly after checking the build. See
+`docs/operations/MONARCH_CLOUD_PYPI.md` for release instructions.

monarch_cloud-0.1.0/README.md

@@ -0,0 +1,60 @@
+# Monarch Cloud CLI
+
+A lightweight public developer client for the existing Monarch REST Platform API.
+
+```bash
+python -m pip install monarch-cloud
+monarch login
+monarch whoami
+monarch catalog
+monarch gpus
+monarch models --scope catalog
+monarch jobs
+monarch wallet
+monarch init "My app" --blueprint backend
+monarch status
+monarch dev
+monarch deploy hello ./hello.js
+```
+
+**Authentication:** `monarch login` prompts for an existing Monarch REST API key
+without echoing it, validates it against `GET /v1/account/identity`, then saves
+it in a mode-0600 file under your user configuration directory. For ephemeral
+environments set `MONARCH_API_KEY` instead; this takes precedence. This is REST
+API-key login, **not** the OAuth browser flow used by the MCP connector. Key
+creation and account access are provided through Monarch Cloud.
+
+`monarch mcp` prints the public OAuth MCP endpoint for compatible AI clients;
+it does not bundle an MCP server or impersonate an OAuth token.
+
+## Command surfaces
+
+- Discovery: `catalog`, `gpus`, `models`, `datasets`, `jobs`, `job ID`,
+  `wallet`, `inference-models`, `whoami`.
+- Projects: `init`, `status`, `dev`, `deploy NAME SOURCE_JS`.
+- Migration: `migrate`, `migrate-storage`, `migrate-postgres`,
+  `migrate-gcs`, `import-documents`.
+- Account: `login`, `logout`, `mcp`.
+
+`deploy` deploys one JavaScript **Project Function**, not arbitrary whole-app
+infrastructure. Some public REST APIs and the MCP's purpose-built tools are
+not yet wrapped as CLI commands; Cloud, REST and MCP remain the source of truth.
+
+Project selection is stored in `.monarch/project.json`. The one-time Project
+server key is saved in `.monarch/server-key` and must never be committed.
+Source migration secrets are only read from environment variables or named
+credential files, not CLI arguments. The server enforces the same account,
+scope, billing, quotas, and approvals as its other public clients.
+
+## For maintainers
+
+The public release is built from the **canonical** implementation at
+`scripts/monarch_platform.py` using
+`python scripts/package_monarch_cloud.py --build`. The staging tool copies
+only this public module, the package metadata, and this README into an isolated
+temporary build directory. The private `./monarch` operator CLI, admin scripts,
+deployment infrastructure, and internal MCP server are not packaged.
+
+There is no CI publisher and no GitHub Actions workflow. The owner publishes
+the reviewed files to PyPI explicitly after checking the build. See
+`docs/operations/MONARCH_CLOUD_PYPI.md` for release instructions.

monarch_cloud-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "monarch-cloud"
+version = "0.1.0"
+description = "Public developer CLI for Monarch Cloud"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.24,<1"]
+authors = [{name = "Africa Compute Fund"}]
+keywords = ["monarch", "cloud", "compute", "developer-tools", "cli"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://app.africacomputefund.com"
+Documentation = "https://app.africacomputefund.com/docs"
+
+[project.scripts]
+monarch = "monarch_cloud.cli:entrypoint"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["monarch_cloud*"]

monarch_cloud-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

monarch_cloud-0.1.0/src/monarch_cloud/__init__.py

@@ -0,0 +1 @@
+"""Monarch Cloud public developer client."""

monarch_cloud-0.1.0/src/monarch_cloud/cli.py

@@ -0,0 +1,843 @@
+#!/usr/bin/env python3
+"""Unified Monarch Platform CLI for developers and agents.
+
+The CLI is intentionally a thin client over Monarch's public Platform API. It
+never bypasses server-side policy, billing, readiness, or authority checks.
+
+Secrets:
+- MONARCH_API_KEY supplies the developer/account credential.
+- One-time Project server keys are written to .monarch/server-key with mode 0600.
+- Source migration credentials stay in environment variables, never argv.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import re
+import stat
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+DEFAULT_API_BASE = "https://app.africacomputefund.com"
+DEFAULT_STATE_DIR = Path(".monarch")
+PUBLIC_MCP_URL = "https://app.africacomputefund.com/mcp"
+PROJECT_FILE = "project.json"
+SERVER_KEY_FILE = "server-key"
+
+
+class MonarchCLIError(RuntimeError):
+    pass
+
+
+def _api_base(value: str | None) -> str:
+    base = str(value or os.getenv("MONARCH_API_BASE_URL") or DEFAULT_API_BASE).rstrip("/")
+    url = urlsplit(base)
+    allowed_local = url.scheme == "http" and url.hostname in {"localhost", "127.0.0.1", "::1"}
+    if not (url.scheme == "https" or allowed_local) or not url.hostname:
+        raise MonarchCLIError("Monarch API URL must use HTTPS (HTTP allowed only for localhost)")
+    if url.username or url.password or url.query or url.fragment:
+        raise MonarchCLIError("Invalid Monarch API URL: credentials, query and fragment are not accepted")
+    return base
+
+
+def _credentials_path() -> Path:
+    override = os.getenv("MONARCH_CONFIG_HOME")
+    if override:
+        return Path(override).expanduser() / "credentials.json"
+    return Path(os.getenv("XDG_CONFIG_HOME") or Path.home() / ".config").expanduser() / "monarch" / "credentials.json"
+
+
+def _token(required: bool = True) -> str:
+    value = str(os.getenv("MONARCH_API_KEY") or "").strip()
+    if not value:
+        path = _credentials_path()
+        if path.is_symlink():
+            raise MonarchCLIError("Refusing to read a symlinked credentials file")
+        if path.exists():
+            if os.name != "nt" and stat.S_IMODE(path.stat().st_mode) & 0o077:
+                raise MonarchCLIError("Credentials must have private permissions (0600)")
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+                value = str(payload.get("api_key") or "").strip() if isinstance(payload, dict) else ""
+            except (ValueError, OSError) as exc:
+                raise MonarchCLIError("Credentials file is unreadable") from exc
+    if required and not value:
+        raise MonarchCLIError("Run 'monarch login' or set MONARCH_API_KEY")
+    return value
+
+
+def _required_env(name: str) -> str:
+    value = str(os.getenv(name) or "").strip()
+    if not value:
+        raise MonarchCLIError(f"{name} is required")
+    return value
+
+
+def _json_print(value: Any) -> None:
+    print(json.dumps(value, indent=2, sort_keys=True, default=str))
+
+
+def _compact_print(value: Any) -> None:
+    print(json.dumps(value, separators=(",", ":"), default=str))
+
+
+def _request(
+    method: str,
+    path: str,
+    *,
+    api_base: str,
+    token: str | None = None,
+    body: dict[str, Any] | None = None,
+    timeout: float = 120.0,
+    idempotency_key: str | None = None,
+) -> dict[str, Any]:
+    headers = {"Accept": "application/json", "X-Request-ID": str(uuid.uuid4())}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+    try:
+        with httpx.Client(timeout=httpx.Timeout(timeout, connect=30.0), follow_redirects=False) as client:
+            response = client.request(method.upper(), api_base + path, headers=headers, json=body)
+    except httpx.HTTPError as exc:
+        raise MonarchCLIError("Monarch could not be reached") from exc
+
+    try:
+        payload: Any = response.json()
+    except Exception:
+        payload = {"message": response.text[:1000]}
+
+    if response.status_code >= 400:
+        message = "Monarch request failed"
+        code = None
+        if isinstance(payload, dict):
+            detail = payload.get("detail") or payload.get("error") or payload
+            if isinstance(detail, dict):
+                message = str(detail.get("error") or detail.get("message") or message)
+                code = detail.get("code")
+            elif isinstance(detail, str):
+                message = detail
+        suffix = f" [{code}]" if code else ""
+        raise MonarchCLIError(f"{message}{suffix} (HTTP {response.status_code})")
+    if not isinstance(payload, (dict, list)):
+        raise MonarchCLIError("Monarch returned an unexpected response")
+    return payload
+
+
+def _state_dir(value: str | None) -> Path:
+    return Path(value or DEFAULT_STATE_DIR).expanduser()
+
+
+def _project_path(state_dir: Path) -> Path:
+    return state_dir / PROJECT_FILE
+
+
+def _server_key_path(state_dir: Path) -> Path:
+    return state_dir / SERVER_KEY_FILE
+
+
+def _read_project(state_dir: Path) -> dict[str, Any]:
+    path = _project_path(state_dir)
+    if not path.exists():
+        return {}
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise MonarchCLIError(f"Project state is unreadable: {path}") from exc
+    if not isinstance(value, dict):
+        raise MonarchCLIError(f"Project state must be a JSON object: {path}")
+    return value
+
+
+def _project_id(args: argparse.Namespace, state_dir: Path) -> str:
+    explicit = str(getattr(args, "project_id", "") or "").strip()
+    if explicit:
+        return explicit
+    stored = str(_read_project(state_dir).get("project_id") or "").strip()
+    if stored:
+        return stored
+    raise MonarchCLIError("No Project selected. Run 'monarch init' or pass --project-id.")
+
+
+def _write_private(path: Path, value: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    if path.is_symlink():
+        raise MonarchCLIError("Refusing to write a symlinked private file")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(path, flags, 0o600)
+    if hasattr(os, "fchmod"):
+        os.fchmod(fd, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as stream:
+        stream.write(value.rstrip("\n") + "\n")
+    try:
+        path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+
+def _write_project_state(state_dir: Path, payload: dict[str, Any]) -> None:
+    state_dir.mkdir(parents=True, exist_ok=True)
+    _project_path(state_dir).write_text(
+        json.dumps(payload, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def cmd_login(args: argparse.Namespace) -> int:
+    key = getpass.getpass("Monarch REST API key (hidden): ").strip()
+    if not key:
+        raise MonarchCLIError("No API key entered")
+    identity = _request("GET", "/v1/account/identity", api_base=_api_base(args.api_base_url), token=key)
+    _write_private(_credentials_path(), json.dumps({"api_key": key}))
+    _json_print({"ok": True, "identity": identity})
+    return 0
+
+
+def cmd_logout(args: argparse.Namespace) -> int:
+    path = _credentials_path()
+    if path.is_symlink():
+        raise MonarchCLIError("Refusing to remove symlinked credentials")
+    path.unlink(missing_ok=True)
+    _json_print({"ok": True, "note": "MONARCH_API_KEY environment variables are unaffected"})
+    return 0
+
+
+def cmd_whoami(args: argparse.Namespace) -> int:
+    _json_print(_request("GET", "/v1/account/identity", api_base=_api_base(args.api_base_url), token=_token()))
+    return 0
+
+
+def cmd_discover(args: argparse.Namespace) -> int:
+    paths = {"gpus": "/v1/gpus", "models": "/v1/models", "datasets": "/v1/datasets",
+             "jobs": "/v1/jobs", "wallet": "/v1/account/balance",
+             "inference-models": "/v1/inference/catalog"}
+    path = paths[args.command]
+    if args.command == "models" and args.scope:
+        path += "?scope=" + args.scope
+    _json_print(_request("GET", path, api_base=_api_base(args.api_base_url), token=_token()))
+    return 0
+
+
+def cmd_job(args: argparse.Namespace) -> int:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", args.job_id):
+        raise MonarchCLIError("Invalid training job identifier")
+    _json_print(_request("GET", f"/v1/jobs/{args.job_id}", api_base=_api_base(args.api_base_url), token=_token()))
+    return 0
+
+
+def cmd_mcp(args: argparse.Namespace) -> int:
+    _json_print({"url": PUBLIC_MCP_URL, "authentication": "OAuth",
+                 "note": "Connect this URL in an MCP-compatible client; no operator tools are exposed."})
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    api_base = _api_base(args.api_base_url)
+    token = _token()
+    state_dir = _state_dir(args.state_dir)
+    existing = _read_project(state_dir)
+    if existing and not args.force:
+        raise MonarchCLIError(
+            f"{_project_path(state_dir)} already selects Project {existing.get('project_id')}; use --force to replace local selection"
+        )
+    body = {
+        "name": args.name,
+        "blueprint_id": args.blueprint,
+        "region": args.region,
+        "key_name": args.key_name,
+    }
+    if args.org_id:
+        body["org_id"] = args.org_id
+    result = _request("POST", "/v1/platform/launch", api_base=api_base, token=token, body=body)
+    project = result.get("project") if isinstance(result.get("project"), dict) else {}
+    key = result.get("server_key") if isinstance(result.get("server_key"), dict) else {}
+    project_id = str(project.get("project_id") or "").strip()
+    if not project_id:
+        raise MonarchCLIError("Monarch launch response did not include project_id")
+    secret = str(key.get("secret") or "").strip()
+    state = {
+        "api_base_url": api_base,
+        "project_id": project_id,
+        "name": project.get("name"),
+        "blueprint_id": project.get("blueprint_id"),
+        "region": project.get("region"),
+    }
+    _write_project_state(state_dir, state)
+    if secret:
+        _write_private(_server_key_path(state_dir), secret)
+    output = {
+        "ok": True,
+        "project": state,
+        "server_key_file": str(_server_key_path(state_dir)) if secret else None,
+        "bindings": result.get("bindings") or [],
+        "warnings": result.get("warnings") or [],
+        "next": [
+            "monarch status",
+            "monarch dev",
+            "monarch deploy-function <name> <source.js>",
+        ],
+    }
+    _json_print(output)
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    project_id = _project_id(args, state_dir)
+    runtime = _request("GET", f"/v1/projects/{project_id}/runtime", api_base=api_base, token=token)
+    usage = _request("GET", f"/v1/projects/{project_id}/usage", api_base=api_base, token=token)
+    bindings = _request("GET", f"/v1/projects/{project_id}/bindings", api_base=api_base, token=token)
+    _json_print({"project_id": project_id, "runtime": runtime, "usage": usage, "bindings": bindings})
+    return 0
+
+
+def cmd_dev(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    project_id = _project_id(args, state_dir)
+    config = _request("GET", f"/v1/projects/{project_id}/client-config", api_base=api_base, token=token)
+    runtime = _request("GET", f"/v1/projects/{project_id}/runtime", api_base=api_base, token=token)
+    _json_print({
+        "project_id": project_id,
+        "client_config": config,
+        "runtime": runtime,
+        "server_key_file": str(_server_key_path(state_dir)) if _server_key_path(state_dir).exists() else None,
+        "note": "Use the public client config in browser/mobile code. Keep the server key on trusted backend infrastructure only.",
+    })
+    return 0
+
+
+def cmd_deploy_function(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    project_id = _project_id(args, state_dir)
+    source_path = Path(args.source).expanduser()
+    source = source_path.read_text(encoding="utf-8")
+    body = {
+        "name": args.name,
+        "source": source,
+        "scopes": args.scope or [],
+    }
+    result = _request(
+        "POST",
+        f"/v1/projects/{project_id}/functions",
+        api_base=api_base,
+        token=token,
+        body=body,
+        timeout=180,
+        idempotency_key=args.idempotency_key or str(uuid.uuid4()),
+    )
+    _json_print(result)
+    return 0
+
+
+def _services(value: str) -> list[str]:
+    return [item.strip() for item in str(value or "").split(",") if item.strip()]
+
+
+def cmd_migrate(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    services = _services(args.services)
+    analyze = _request(
+        "POST",
+        "/v1/platform/migrations/analyze",
+        api_base=api_base,
+        token=token,
+        body={"provider": args.provider, "services": services},
+    )
+    manifest = _request(
+        "POST",
+        "/v1/platform/migrations/manifest",
+        api_base=api_base,
+        token=token,
+        body={"provider": args.provider, "services": services, "project_name": args.name},
+    )
+    output: dict[str, Any] = {"analysis": analyze, "manifest": manifest}
+    if args.prepare:
+        body: dict[str, Any] = {
+            "provider": args.provider,
+            "services": services,
+            "name": args.name,
+            "region": args.region,
+            "key_name": args.key_name,
+        }
+        if args.org_id:
+            body["org_id"] = args.org_id
+        prepared = _request(
+            "POST",
+            "/v1/platform/migrations/prepare",
+            api_base=api_base,
+            token=token,
+            body=body,
+            timeout=180,
+        )
+        output["prepared"] = prepared
+        project = prepared.get("project") if isinstance(prepared.get("project"), dict) else {}
+        key = prepared.get("server_key") if isinstance(prepared.get("server_key"), dict) else {}
+        project_id = str(project.get("project_id") or "").strip()
+        if project_id:
+            _write_project_state(state_dir, {
+                "api_base_url": api_base,
+                "project_id": project_id,
+                "name": project.get("name"),
+                "blueprint_id": project.get("blueprint_id"),
+                "region": project.get("region"),
+                "migration_source": args.provider,
+            })
+        secret = str(key.get("secret") or "").strip()
+        if secret:
+            _write_private(_server_key_path(state_dir), secret)
+        if isinstance(output.get("prepared"), dict) and secret:
+            output["prepared"] = dict(output["prepared"])
+            server_key = output["prepared"].get("server_key")
+            if isinstance(server_key, dict):
+                output["prepared"]["server_key"] = {k: v for k, v in server_key.items() if k != "secret"}
+                output["prepared"]["server_key_file"] = str(_server_key_path(state_dir))
+    _json_print(output)
+    return 0
+
+
+def cmd_migrate_storage(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    project_id = _project_id(args, state_dir)
+    source_access = _required_env("MONARCH_MIGRATION_SOURCE_ACCESS_KEY_ID")
+    source_secret = _required_env("MONARCH_MIGRATION_SOURCE_SECRET_ACCESS_KEY")
+    source_session = str(os.getenv("MONARCH_MIGRATION_SOURCE_SESSION_TOKEN") or "").strip() or None
+
+    cursor = str(args.start_after or "")
+    totals = {"copied": 0, "skipped": 0, "bytes_copied": 0}
+    batch_number = 0
+    while True:
+        batch_number += 1
+        body: dict[str, Any] = {
+            "source_bucket": args.bucket,
+            "source_access_key_id": source_access,
+            "source_secret_access_key": source_secret,
+            "source_prefix": args.prefix,
+            "start_after": cursor,
+            "max_objects": args.max_objects,
+            "max_batch_bytes": args.max_batch_bytes,
+            "dry_run": bool(args.dry_run),
+        }
+        if source_session:
+            body["source_session_token"] = source_session
+        if args.endpoint:
+            body["source_endpoint"] = args.endpoint
+        if args.source_region:
+            body["source_region"] = args.source_region
+        if args.target_region:
+            body["target_region"] = args.target_region
+
+        result = _request(
+            "POST",
+            f"/v1/projects/{project_id}/migrations/object-storage/s3",
+            api_base=api_base,
+            token=token,
+            body=body,
+            timeout=300,
+            idempotency_key=str(uuid.uuid4()),
+        )
+        totals["copied"] += int(result.get("copied") or 0)
+        totals["skipped"] += int(result.get("skipped") or 0)
+        totals["bytes_copied"] += int(result.get("bytes_copied") or 0)
+        _compact_print({
+            "batch": batch_number,
+            "copied": result.get("copied"),
+            "skipped": result.get("skipped"),
+            "bytes_copied": result.get("bytes_copied"),
+            "complete": result.get("complete"),
+            "next_start_after": result.get("next_start_after"),
+        })
+        if bool(result.get("complete")) or args.one_batch:
+            _json_print({
+                "ok": bool(result.get("complete")) or bool(args.one_batch),
+                "dry_run": bool(args.dry_run),
+                "batches": batch_number,
+                **totals,
+                "complete": bool(result.get("complete")),
+                "resume_after": result.get("next_start_after"),
+            })
+            return 0
+        next_cursor = str(result.get("next_start_after") or "")
+        if not next_cursor or next_cursor == cursor:
+            raise MonarchCLIError("Migration cursor did not advance; refusing an infinite retry loop")
+        cursor = next_cursor
+
+
+def cmd_migrate_postgres(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    project_id = _project_id(args, state_dir)
+    dsn = _required_env("MONARCH_MIGRATION_POSTGRES_DSN")
+    cursor = str(args.start_after or "")
+    totals = {"imported": 0, "skipped": 0, "rows_considered": 0}
+    batches = 0
+    while True:
+        batches += 1
+        body = {
+            "source_dsn": dsn,
+            "table": args.table,
+            "schema_name": args.schema,
+            "primary_key": args.primary_key,
+            "collection": args.collection,
+            "start_after": cursor or None,
+            "max_rows": args.max_rows,
+            "mode": args.mode,
+            "dry_run": bool(args.dry_run),
+        }
+        result = _request(
+            "POST",
+            f"/v1/projects/{project_id}/migrations/database/postgres",
+            api_base=api_base,
+            token=token,
+            body=body,
+            timeout=300,
+            idempotency_key=str(uuid.uuid4()),
+        )
+        totals["imported"] += int(result.get("imported") or 0)
+        totals["skipped"] += int(result.get("skipped") or 0)
+        totals["rows_considered"] += int(result.get("rows_considered") or 0)
+        _compact_print({
+            "batch": batches,
+            "imported": result.get("imported"),
+            "skipped": result.get("skipped"),
+            "rows_considered": result.get("rows_considered"),
+            "complete": result.get("complete"),
+            "next_start_after": result.get("next_start_after"),
+        })
+        if bool(result.get("complete")) or args.one_batch:
+            _json_print({
+                "ok": bool(result.get("complete")) or bool(args.one_batch),
+                "dry_run": bool(args.dry_run),
+                "batches": batches,
+                **totals,
+                "complete": bool(result.get("complete")),
+                "resume_after": result.get("next_start_after"),
+                "semantic_target": "project_documents",
+                "relational_semantics_preserved": False,
+            })
+            return 0
+        next_cursor = str(result.get("next_start_after") or "")
+        if not next_cursor or next_cursor == cursor:
+            raise MonarchCLIError("PostgreSQL migration cursor did not advance")
+        cursor = next_cursor
+
+
+def _gcs_credential(args: argparse.Namespace) -> str:
+    if args.credentials_file:
+        return Path(args.credentials_file).expanduser().read_text(encoding="utf-8")
+    return _required_env("MONARCH_MIGRATION_GCS_SERVICE_ACCOUNT_JSON")
+
+
+def cmd_migrate_gcs(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    project_id = _project_id(args, state_dir)
+    credential = _gcs_credential(args)
+    cursor = str(args.start_after or "")
+    totals = {"copied": 0, "skipped": 0, "bytes_copied": 0}
+    batches = 0
+    while True:
+        batches += 1
+        body = {
+            "source_bucket": args.bucket,
+            "source_service_account_json": credential,
+            "source_prefix": args.prefix,
+            "start_after": cursor,
+            "max_objects": args.max_objects,
+            "max_batch_bytes": args.max_batch_bytes,
+            "target_region": args.target_region,
+            "dry_run": bool(args.dry_run),
+        }
+        result = _request(
+            "POST",
+            f"/v1/projects/{project_id}/migrations/object-storage/gcs",
+            api_base=api_base,
+            token=token,
+            body=body,
+            timeout=300,
+            idempotency_key=str(uuid.uuid4()),
+        )
+        totals["copied"] += int(result.get("copied") or 0)
+        totals["skipped"] += int(result.get("skipped") or 0)
+        totals["bytes_copied"] += int(result.get("bytes_copied") or 0)
+        _compact_print({
+            "batch": batches,
+            "copied": result.get("copied"),
+            "skipped": result.get("skipped"),
+            "bytes_copied": result.get("bytes_copied"),
+            "complete": result.get("complete"),
+            "next_start_after": result.get("next_start_after"),
+        })
+        if bool(result.get("complete")) or args.one_batch:
+            _json_print({
+                "ok": bool(result.get("complete")) or bool(args.one_batch),
+                "dry_run": bool(args.dry_run),
+                "batches": batches,
+                **totals,
+                "complete": bool(result.get("complete")),
+                "resume_after": result.get("next_start_after"),
+            })
+            return 0
+        next_cursor = str(result.get("next_start_after") or "")
+        if not next_cursor or next_cursor == cursor:
+            raise MonarchCLIError("GCS migration cursor did not advance")
+        cursor = next_cursor
+
+
+def _load_document_items(path: Path, collection_override: str | None) -> list[dict[str, Any]]:
+    raw = path.read_text(encoding="utf-8")
+    if path.suffix.lower() in {".jsonl", ".ndjson"}:
+        values = [json.loads(line) for line in raw.splitlines() if line.strip()]
+    else:
+        parsed = json.loads(raw)
+        if isinstance(parsed, dict) and isinstance(parsed.get("items"), list):
+            values = parsed["items"]
+        elif isinstance(parsed, list):
+            values = parsed
+        else:
+            raise MonarchCLIError("Document import JSON must be an array or an object with an items array")
+    items: list[dict[str, Any]] = []
+    for index, value in enumerate(values):
+        if not isinstance(value, dict):
+            raise MonarchCLIError(f"Document item {index} must be an object")
+        collection = str(collection_override or value.get("collection") or "").strip()
+        document_id = str(value.get("document_id") or value.get("id") or "").strip()
+        if not collection or not document_id:
+            raise MonarchCLIError(f"Document item {index} needs collection and document_id/id")
+        if isinstance(value.get("data"), dict):
+            data = dict(value["data"])
+        elif collection_override:
+            data = {
+                str(key): item
+                for key, item in value.items()
+                if key not in {"collection", "document_id", "id"}
+            }
+        else:
+            raise MonarchCLIError(f"Document item {index} needs a data object")
+        items.append({"collection": collection, "document_id": document_id, "data": data})
+    return items
+
+
+def cmd_import_documents(args: argparse.Namespace) -> int:
+    state_dir = _state_dir(args.state_dir)
+    stored = _read_project(state_dir)
+    api_base = _api_base(args.api_base_url or stored.get("api_base_url"))
+    token = _token()
+    project_id = _project_id(args, state_dir)
+    source_path = Path(args.source).expanduser()
+    items = _load_document_items(source_path, args.collection)
+    imported = skipped = 0
+    batches = 0
+    for offset in range(0, len(items), args.batch_size):
+        batches += 1
+        batch = items[offset : offset + args.batch_size]
+        result = _request(
+            "POST",
+            f"/v1/projects/{project_id}/migrations/documents",
+            api_base=api_base,
+            token=token,
+            body={
+                "items": batch,
+                "mode": args.mode,
+                "dry_run": bool(args.dry_run),
+                "source": args.source_label,
+            },
+            timeout=180,
+            idempotency_key=str(uuid.uuid4()),
+        )
+        imported += int(result.get("imported") or 0)
+        skipped += int(result.get("skipped") or 0)
+        _compact_print({
+            "batch": batches,
+            "items": len(batch),
+            "imported": result.get("imported"),
+            "skipped": result.get("skipped"),
+            "dry_run": result.get("dry_run"),
+        })
+    _json_print({
+        "ok": True,
+        "source_file": str(source_path),
+        "dry_run": bool(args.dry_run),
+        "batches": batches,
+        "items": len(items),
+        "imported": imported,
+        "skipped": skipped,
+    })
+    return 0
+
+
+def cmd_catalog(args: argparse.Namespace) -> int:
+    api_base = _api_base(args.api_base_url)
+    payload = _request("GET", "/v1/platform/catalog", api_base=api_base, token=None)
+    _json_print(payload)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="monarch", description="Monarch Platform developer and agent CLI")
+    parser.add_argument("--api-base-url", default=None)
+    parser.add_argument("--state-dir", default=str(DEFAULT_STATE_DIR))
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    login = sub.add_parser("login", help="Validate and securely save your Monarch REST API key")
+    login.set_defaults(func=cmd_login)
+    logout = sub.add_parser("logout", help="Delete the local developer API key")
+    logout.set_defaults(func=cmd_logout)
+    whoami = sub.add_parser("whoami", help="Show your authenticated Monarch identity")
+    whoami.set_defaults(func=cmd_whoami)
+    for name, help_text in (
+        ("gpus", "List customer-visible GPU offerings"),
+        ("datasets", "List accessible datasets"),
+        ("jobs", "List your training jobs"),
+        ("wallet", "Read account wallet balance"),
+        ("inference-models", "List hosted inference models"),
+    ):
+        public = sub.add_parser(name, help=help_text)
+        public.set_defaults(func=cmd_discover)
+    models = sub.add_parser("models", help="List available or owned models")
+    models.add_argument("--scope", choices=["catalog", "mine"], default=None)
+    models.set_defaults(func=cmd_discover)
+    job = sub.add_parser("job", help="Inspect one training job")
+    job.add_argument("job_id")
+    job.set_defaults(func=cmd_job)
+    mcp = sub.add_parser("mcp", help="Show the public OAuth MCP endpoint")
+    mcp.set_defaults(func=cmd_mcp)
+
+    init = sub.add_parser("init", help="Launch a Project from a Blueprint")
+    init.add_argument("name")
+    init.add_argument("--blueprint", default="backend")
+    init.add_argument("--region", default="auto")
+    init.add_argument("--org-id", default=None)
+    init.add_argument("--key-name", default="local backend")
+    init.add_argument("--force", action="store_true")
+    init.set_defaults(func=cmd_init)
+
+    status = sub.add_parser("status", help="Inspect Project runtime, usage and bindings")
+    status.add_argument("--project-id", default=None)
+    status.set_defaults(func=cmd_status)
+
+    dev = sub.add_parser("dev", help="Show public client configuration and runtime readiness")
+    dev.add_argument("--project-id", default=None)
+    dev.set_defaults(func=cmd_dev)
+
+    deploy = sub.add_parser("deploy", aliases=["deploy-function"], help="Deploy or replace one Project Function")
+    deploy.add_argument("name")
+    deploy.add_argument("source")
+    deploy.add_argument("--project-id", default=None)
+    deploy.add_argument("--scope", action="append", default=[])
+    deploy.add_argument("--idempotency-key", default=None)
+    deploy.set_defaults(func=cmd_deploy_function)
+
+    migrate = sub.add_parser("migrate", help="Analyze and optionally prepare a migration target")
+    migrate.add_argument("provider")
+    migrate.add_argument("--services", default="")
+    migrate.add_argument("--name", default="Migrated app")
+    migrate.add_argument("--region", default="auto")
+    migrate.add_argument("--org-id", default=None)
+    migrate.add_argument("--key-name", default="migration backend")
+    migrate.add_argument("--prepare", action="store_true")
+    migrate.set_defaults(func=cmd_migrate)
+
+    migrate_storage = sub.add_parser("migrate-storage", help="Copy S3-compatible objects into the selected Project")
+    migrate_storage.add_argument("bucket")
+    migrate_storage.add_argument("--project-id", default=None)
+    migrate_storage.add_argument("--endpoint", default=None)
+    migrate_storage.add_argument("--source-region", default=None)
+    migrate_storage.add_argument("--target-region", default=None)
+    migrate_storage.add_argument("--prefix", default="")
+    migrate_storage.add_argument("--start-after", default="")
+    migrate_storage.add_argument("--max-objects", type=int, default=25)
+    migrate_storage.add_argument("--max-batch-bytes", type=int, default=128 * 1024 * 1024)
+    migrate_storage.add_argument("--dry-run", action="store_true")
+    migrate_storage.add_argument("--one-batch", action="store_true")
+    migrate_storage.set_defaults(func=cmd_migrate_storage)
+
+    migrate_postgres = sub.add_parser("migrate-postgres", help="Copy PostgreSQL table rows into Project documents")
+    migrate_postgres.add_argument("table")
+    migrate_postgres.add_argument("--project-id", default=None)
+    migrate_postgres.add_argument("--schema", default="public")
+    migrate_postgres.add_argument("--primary-key", default=None)
+    migrate_postgres.add_argument("--collection", default=None)
+    migrate_postgres.add_argument("--start-after", default="")
+    migrate_postgres.add_argument("--max-rows", type=int, default=100)
+    migrate_postgres.add_argument("--mode", choices=["upsert", "skip_existing"], default="upsert")
+    migrate_postgres.add_argument("--dry-run", action="store_true")
+    migrate_postgres.add_argument("--one-batch", action="store_true")
+    migrate_postgres.set_defaults(func=cmd_migrate_postgres)
+
+    migrate_gcs = sub.add_parser("migrate-gcs", help="Copy GCS/Firebase Storage objects into the selected Project")
+    migrate_gcs.add_argument("bucket")
+    migrate_gcs.add_argument("--project-id", default=None)
+    migrate_gcs.add_argument("--credentials-file", default=None)
+    migrate_gcs.add_argument("--target-region", default=None)
+    migrate_gcs.add_argument("--prefix", default="")
+    migrate_gcs.add_argument("--start-after", default="")
+    migrate_gcs.add_argument("--max-objects", type=int, default=25)
+    migrate_gcs.add_argument("--max-batch-bytes", type=int, default=128 * 1024 * 1024)
+    migrate_gcs.add_argument("--dry-run", action="store_true")
+    migrate_gcs.add_argument("--one-batch", action="store_true")
+    migrate_gcs.set_defaults(func=cmd_migrate_gcs)
+
+    import_documents = sub.add_parser("import-documents", help="Import exported JSON/JSONL documents into the selected Project")
+    import_documents.add_argument("source")
+    import_documents.add_argument("--project-id", default=None)
+    import_documents.add_argument("--collection", default=None)
+    import_documents.add_argument("--source-label", default="local_export")
+    import_documents.add_argument("--batch-size", type=int, default=100, choices=range(1, 501), metavar="1..500")
+    import_documents.add_argument("--mode", choices=["upsert", "skip_existing"], default="upsert")
+    import_documents.add_argument("--dry-run", action="store_true")
+    import_documents.set_defaults(func=cmd_import_documents)
+
+    catalog = sub.add_parser("catalog", help="Read public Platform services and pricing")
+    catalog.set_defaults(func=cmd_catalog)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+def entrypoint() -> int:
+    try:
+        return main()
+    except KeyboardInterrupt:
+        return 130
+    except (MonarchCLIError, OSError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(entrypoint())

monarch_cloud-0.1.0/src/monarch_cloud.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: monarch-cloud
+Version: 0.1.0
+Summary: Public developer CLI for Monarch Cloud
+Author: Africa Compute Fund
+Project-URL: Homepage, https://app.africacomputefund.com
+Project-URL: Documentation, https://app.africacomputefund.com/docs
+Keywords: monarch,cloud,compute,developer-tools,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.24
+
+# Monarch Cloud CLI
+
+A lightweight public developer client for the existing Monarch REST Platform API.
+
+```bash
+python -m pip install monarch-cloud
+monarch login
+monarch whoami
+monarch catalog
+monarch gpus
+monarch models --scope catalog
+monarch jobs
+monarch wallet
+monarch init "My app" --blueprint backend
+monarch status
+monarch dev
+monarch deploy hello ./hello.js
+```
+
+**Authentication:** `monarch login` prompts for an existing Monarch REST API key
+without echoing it, validates it against `GET /v1/account/identity`, then saves
+it in a mode-0600 file under your user configuration directory. For ephemeral
+environments set `MONARCH_API_KEY` instead; this takes precedence. This is REST
+API-key login, **not** the OAuth browser flow used by the MCP connector. Key
+creation and account access are provided through Monarch Cloud.
+
+`monarch mcp` prints the public OAuth MCP endpoint for compatible AI clients;
+it does not bundle an MCP server or impersonate an OAuth token.
+
+## Command surfaces
+
+- Discovery: `catalog`, `gpus`, `models`, `datasets`, `jobs`, `job ID`,
+  `wallet`, `inference-models`, `whoami`.
+- Projects: `init`, `status`, `dev`, `deploy NAME SOURCE_JS`.
+- Migration: `migrate`, `migrate-storage`, `migrate-postgres`,
+  `migrate-gcs`, `import-documents`.
+- Account: `login`, `logout`, `mcp`.
+
+`deploy` deploys one JavaScript **Project Function**, not arbitrary whole-app
+infrastructure. Some public REST APIs and the MCP's purpose-built tools are
+not yet wrapped as CLI commands; Cloud, REST and MCP remain the source of truth.
+
+Project selection is stored in `.monarch/project.json`. The one-time Project
+server key is saved in `.monarch/server-key` and must never be committed.
+Source migration secrets are only read from environment variables or named
+credential files, not CLI arguments. The server enforces the same account,
+scope, billing, quotas, and approvals as its other public clients.
+
+## For maintainers
+
+The public release is built from the **canonical** implementation at
+`scripts/monarch_platform.py` using
+`python scripts/package_monarch_cloud.py --build`. The staging tool copies
+only this public module, the package metadata, and this README into an isolated
+temporary build directory. The private `./monarch` operator CLI, admin scripts,
+deployment infrastructure, and internal MCP server are not packaged.
+
+There is no CI publisher and no GitHub Actions workflow. The owner publishes
+the reviewed files to PyPI explicitly after checking the build. See
+`docs/operations/MONARCH_CLOUD_PYPI.md` for release instructions.

monarch_cloud-0.1.0/src/monarch_cloud.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/monarch_cloud/__init__.py
+src/monarch_cloud/cli.py
+src/monarch_cloud.egg-info/PKG-INFO
+src/monarch_cloud.egg-info/SOURCES.txt
+src/monarch_cloud.egg-info/dependency_links.txt
+src/monarch_cloud.egg-info/entry_points.txt
+src/monarch_cloud.egg-info/requires.txt
+src/monarch_cloud.egg-info/top_level.txt

monarch_cloud-0.1.0/src/monarch_cloud.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

monarch_cloud-0.1.0/src/monarch_cloud.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+monarch = monarch_cloud.cli:entrypoint

monarch_cloud-0.1.0/src/monarch_cloud.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx<1,>=0.24

monarch_cloud-0.1.0/src/monarch_cloud.egg-info/top_level.txt

@@ -0,0 +1 @@
+monarch_cloud