sovaria-cli 0.2.0__py3-none-any.whl

apps/cli/src/commands/deploy.py

@@ -0,0 +1,1099 @@
+"""CLI commands for Forge deploy/versioning/invoke/simulate/history workflows."""
+
+from __future__ import annotations
+
+import io
+import json
+import time
+import zipfile
+from pathlib import Path
+from typing import Any
+
+import httpx
+import typer
+
+from apps.cli.src.utils.auth_store import load_tokens
+from apps.cli.src.utils.config import get_api_url
+
+app = typer.Typer()
+
+_POLL_INTERVAL = 2  # seconds
+_POLL_TIMEOUT = 120  # seconds
+_ASYNC_POLL_INTERVAL = 2  # seconds
+_ASYNC_POLL_TIMEOUT = 600  # seconds
+
+
+@app.command("deploy")
+def deploy(
+    directory: Path = typer.Argument(
+        Path("."),
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+        help="Path to the function directory to deploy",
+    ),
+    name: str | None = typer.Option(None, "--name", "-n", help="Function name"),
+    project_id: str | None = typer.Option(None, "--project", "-p", help="Target project node ID"),
+    note: str = typer.Option("", "--note", help="Version change note for deployment history"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """
+    Deploy a cloud function to the Forge engine.
+
+    Example:
+        sov deploy ./my-function --name greet --project proj-abc123
+    """
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    fn_name = name or directory.resolve().name
+
+    typer.echo(f"Packaging {directory.resolve()} …")
+    zip_bytes = _zip_directory(directory)
+    typer.echo(f"  Compressed size: {len(zip_bytes):,} bytes")
+
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+
+    # Upload
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/fn/deploy",
+            headers=headers,
+            files={"bundle": (f"{fn_name}.zip", zip_bytes, "application/zip")},
+            data={"name": fn_name, "project_id": project_id or "", "change_note": note},
+            timeout=60,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Upload failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    deploy_data = resp.json()
+    deploy_id = deploy_data.get("deploy_id")
+    deploy_version = deploy_data.get("version")
+    resolved_project_id = project_id or deploy_data.get("project_id")
+    if not deploy_id:
+        typer.echo(f"Unexpected response: {resp.text}", err=True)
+        raise typer.Exit(1)
+
+    if deploy_version:
+        typer.echo(f"Version: v{deploy_version}")
+
+    typer.echo(f"Deploy started (id={deploy_id}). Waiting for build…")
+
+    # Poll for status
+    deadline = time.time() + _POLL_TIMEOUT
+    while time.time() < deadline:
+        try:
+            poll = httpx.get(
+                f"{api_url}/api/v1/fn/{deploy_id}/status",
+                headers=headers,
+                params={"project_id": resolved_project_id} if resolved_project_id else None,
+                timeout=10,
+            )
+            poll.raise_for_status()
+            status_data = poll.json()
+            status = status_data.get("status", "UNKNOWN")
+
+            if status == "READY":
+                invoke_url = status_data.get("invoke_url", "<unknown>")
+                typer.echo(
+                    typer.style(f"✓ Deployed! Invoke URL: {invoke_url}", fg=typer.colors.GREEN)
+                )
+                return
+            elif status == "FAILED":
+                typer.echo(f"Deploy failed: {status_data.get('error', 'unknown error')}", err=True)
+                raise typer.Exit(1)
+            else:
+                typer.echo(f"  Status: {status} …", nl=False)
+                typer.echo("\r", nl=False)
+        except httpx.HTTPStatusError as exc:
+            typer.echo(f"Poll error: {exc.response.text}", err=True)
+            raise typer.Exit(1) from exc
+
+        time.sleep(_POLL_INTERVAL)
+
+    typer.echo("Deploy timed out", err=True)
+    raise typer.Exit(1)
+
+
+@app.command("status")
+def status(
+    deploy_id: str = typer.Argument(..., help="Deployment id returned by `sov fn deploy`"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Optional project scope (recommended for strict sandbox isolation)",
+    ),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Check status of a Forge deployment."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/v1/fn/{deploy_id}/status",
+            headers=headers,
+            params={"project_id": project_id} if project_id else None,
+            timeout=15,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Status request failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    data = resp.json()
+    typer.echo(json.dumps(data, indent=2, sort_keys=True))
+
+
+@app.command("invoke")
+def invoke(
+    function_name: str = typer.Argument(..., help="Function name/path (e.g. my-fn)"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for invocation sandbox",
+    ),
+    deploy_id: str | None = typer.Option(
+        None,
+        "--deploy-id",
+        help="Invoke a specific deployment id instead of latest",
+    ),
+    execution_profile: str = typer.Option(
+        "standard",
+        "--execution-profile",
+        help="Execution profile: standard or heavy",
+    ),
+    async_mode: bool = typer.Option(
+        False,
+        "--async",
+        help="Queue async invocation (recommended for heavy functions)",
+    ),
+    wait: bool = typer.Option(
+        True,
+        "--wait/--no-wait",
+        help="When --async is used, poll until completion",
+    ),
+    simulate: bool = typer.Option(
+        False,
+        "--simulate",
+        help="Run simulation mode and store simulation history",
+    ),
+    data: str | None = typer.Option(
+        None,
+        "--data",
+        help="Inline JSON payload passed to the function",
+    ),
+    data_file: Path | None = typer.Option(
+        None,
+        "--data-file",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        help="Path to JSON payload file",
+    ),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Invoke a deployed function via Forge sandbox runtime."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    payload = _load_json_payload(data=data, data_file=data_file)
+
+    query: dict[str, str] = {}
+    if project_id:
+        query["project_id"] = project_id
+    if deploy_id:
+        query["deploy_id"] = deploy_id
+
+    query["execution_profile"] = execution_profile
+
+    if async_mode:
+        query["simulation"] = "true" if simulate else "false"
+        try:
+            resp = httpx.post(
+                f"{api_url}/api/v1/fn/{function_name}/invoke/async",
+                headers=headers,
+                params=query,
+                json=payload,
+                timeout=30,
+            )
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            typer.echo(f"Async invocation failed: {exc.response.text}", err=True)
+            raise typer.Exit(1) from exc
+
+        accepted = resp.json()
+        typer.echo(json.dumps(accepted, indent=2, sort_keys=True))
+
+        invocation_id = accepted.get("invocation_id")
+        if wait and invocation_id:
+            final_status = _poll_async_invocation(
+                api_url=api_url,
+                headers=headers,
+                invocation_id=str(invocation_id),
+                project_id=project_id,
+            )
+            typer.echo(json.dumps(final_status, indent=2, sort_keys=True))
+            if final_status.get("status") not in {"SUCCEEDED"}:
+                raise typer.Exit(1)
+        return
+
+    endpoint = "simulate" if simulate else "invoke"
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/fn/{function_name}/{endpoint}",
+            headers=headers,
+            params=query if query else None,
+            json=payload,
+            timeout=60,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Invocation failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("versions")
+def versions(
+    function_name: str = typer.Argument(..., help="Function name/path (e.g. my-fn)"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for version history",
+    ),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+    offset: int = typer.Option(0, "--offset", min=0),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List deployment versions for one function."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    params: dict[str, str | int] = {"limit": limit, "offset": offset}
+    if project_id:
+        params["project_id"] = project_id
+
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/v1/fn/{function_name}/versions",
+            headers=headers,
+            params=params,
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Version history request failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("history")
+def history(
+    function_name: str = typer.Argument(..., help="Function name/path (e.g. my-fn)"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for invocation history",
+    ),
+    mode: str | None = typer.Option(
+        None,
+        "--mode",
+        help="Optional mode filter: invoke or simulate",
+    ),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+    offset: int = typer.Option(0, "--offset", min=0),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List invocation history for one function."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    params: dict[str, str | int] = {"limit": limit, "offset": offset}
+    if project_id:
+        params["project_id"] = project_id
+    if mode:
+        params["mode"] = mode
+
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/v1/fn/{function_name}/history/invocations",
+            headers=headers,
+            params=params,
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Invocation history request failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("functions")
+def functions(
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for function listing",
+    ),
+    limit: int = typer.Option(100, "--limit", min=1, max=500),
+    offset: int = typer.Option(0, "--offset", min=0),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List Forge functions with active versions and queue summary."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    params: dict[str, str | int] = {"limit": limit, "offset": offset}
+    if project_id:
+        params["project_id"] = project_id
+
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/v1/fn/functions",
+            headers=headers,
+            params=params,
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Function listing failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("jobs")
+def jobs(
+    function_name: str = typer.Argument(..., help="Function name/path (e.g. my-fn)"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for durable async jobs",
+    ),
+    status: str | None = typer.Option(None, "--status", help="Optional status filter"),
+    limit: int = typer.Option(100, "--limit", min=1, max=500),
+    offset: int = typer.Option(0, "--offset", min=0),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List durable async jobs for a function."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    params: dict[str, str | int] = {"limit": limit, "offset": offset}
+    if project_id:
+        params["project_id"] = project_id
+    if status:
+        params["status"] = status
+
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/v1/fn/{function_name}/jobs",
+            headers=headers,
+            params=params,
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Job listing failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("sim-diff")
+def sim_diff(
+    function_name: str = typer.Argument(..., help="Function name/path (e.g. my-fn)"),
+    left_invocation_id: str = typer.Argument(..., help="Left simulation invocation id"),
+    right_invocation_id: str = typer.Argument(..., help="Right simulation invocation id"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for simulation diff",
+    ),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Show unified diff between two simulation invocations."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    params: dict[str, str] = {
+        "left_invocation_id": left_invocation_id,
+        "right_invocation_id": right_invocation_id,
+    }
+    if project_id:
+        params["project_id"] = project_id
+
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/v1/fn/{function_name}/history/simulation-diff",
+            headers=headers,
+            params=params,
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Simulation diff request failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("promote")
+def promote(
+    function_name: str = typer.Argument(..., help="Function name/path (e.g. my-fn)"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for version promotion",
+    ),
+    version: int | None = typer.Option(None, "--version", min=1, help="Target version to promote"),
+    deploy_id: str | None = typer.Option(None, "--deploy-id", help="Target deploy id to promote"),
+    reason: str = typer.Option("", "--reason", help="Promotion reason"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Promote a deployment/version to become active."""
+    if version is None and not deploy_id:
+        typer.echo("Provide either --version or --deploy-id", err=True)
+        raise typer.Exit(1)
+
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    params: dict[str, str] = {}
+    if project_id:
+        params["project_id"] = project_id
+
+    body: dict[str, object] = {"reason": reason}
+    if version is not None:
+        body["version"] = version
+    if deploy_id:
+        body["deploy_id"] = deploy_id
+
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/fn/{function_name}/promote",
+            headers=headers,
+            params=params if params else None,
+            json=body,
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Promote request failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("rollback")
+def rollback(
+    function_name: str = typer.Argument(..., help="Function name/path (e.g. my-fn)"),
+    project_id: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Project scope for rollback",
+    ),
+    version: int | None = typer.Option(
+        None,
+        "--version",
+        min=1,
+        help="Optional explicit target version (defaults to previous active)",
+    ),
+    reason: str = typer.Option("", "--reason", help="Rollback reason"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Rollback active function deployment to a previous version."""
+    tokens = load_tokens(profile=profile)
+    if not tokens:
+        typer.echo("Not logged in. Run: sov login", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile)
+    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+    params: dict[str, str] = {}
+    if project_id:
+        params["project_id"] = project_id
+
+    body: dict[str, object] = {"reason": reason}
+    if version is not None:
+        body["version"] = version
+
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/fn/{function_name}/rollback",
+            headers=headers,
+            params=params if params else None,
+            json=body,
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Rollback request failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(json.dumps(resp.json(), indent=2, sort_keys=True))
+
+
+@app.command("logs")
+def logs(
+    function_name: str = typer.Argument(..., help="Function name"),
+    limit: int = typer.Option(50, "--limit", min=1, max=200),
+    offset: int = typer.Option(0, "--offset", min=0),
+    status: str | None = typer.Option(None, "--status", help="Filter: SUCCEEDED, FAILED, TIMEOUT"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Fetch recent invocation logs for a function."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    params: dict[str, str] = {"limit": str(limit), "offset": str(offset)}
+    if status:
+        params["status"] = status
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/fn/functions/{safe_name}/logs",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            params=params,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("get")
+def get_function(
+    function_name: str = typer.Argument(..., help="Function name"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Get function metadata."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/fn/functions/{safe_name}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("delete")
+def delete_function(
+    function_name: str = typer.Argument(..., help="Function name"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Delete a deployed function."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    if not yes and not typer.confirm(f"Delete function '{function_name}'?"):
+        raise typer.Exit(0)
+
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="DELETE",
+            path=f"/api/v1/fn/functions/{safe_name}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+    typer.echo(typer.style(f"Deleted function '{function_name}'", fg=typer.colors.GREEN))
+
+
+@app.command("source")
+def function_source(
+    function_name: str = typer.Argument(..., help="Function name"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Fetch function source code."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/fn/functions/{safe_name}/source",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("update")
+def update_function(
+    function_name: str = typer.Argument(..., help="Function name"),
+    source: str | None = typer.Option(None, "--source", help="Inline source code"),
+    source_file: Path | None = typer.Option(None, "--source-file", exists=True, readable=True),
+    runtime: str | None = typer.Option(None, "--runtime"),
+    entrypoint: str | None = typer.Option(None, "--entrypoint"),
+    region: str | None = typer.Option(None, "--region"),
+    description: str | None = typer.Option(None, "--description"),
+    verify_jwt: bool | None = typer.Option(None, "--verify-jwt/--no-verify-jwt"),
+    env_vars_json: str | None = typer.Option(None, "--env-vars", help="JSON object"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Patch function metadata and/or source."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, parse_json_arg, print_json
+
+    if source and source_file:
+        raise typer.BadParameter("Use either --source or --source-file, not both")
+    body: dict[str, object] = {}
+    if source_file:
+        body["source"] = source_file.read_text(encoding="utf-8")
+    elif source is not None:
+        body["source"] = source
+    if runtime is not None:
+        body["runtime"] = runtime
+    if entrypoint is not None:
+        body["entrypoint"] = entrypoint
+    if region is not None:
+        body["region"] = region
+    if description is not None:
+        body["description"] = description
+    if verify_jwt is not None:
+        body["verify_jwt"] = verify_jwt
+    if env_vars_json is not None:
+        env_vars = parse_json_arg(env_vars_json, label="env-vars")
+        if env_vars is None or not isinstance(env_vars, dict):
+            raise typer.BadParameter("--env-vars must be a JSON object")
+        body["env_vars"] = env_vars
+    if not body:
+        raise typer.BadParameter("Provide at least one field to update")
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="PATCH",
+            path=f"/api/v1/fn/functions/{safe_name}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("policy-get")
+def policy_get(
+    function_name: str = typer.Argument(..., help="Function name"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Fetch function invoke policy."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/fn/functions/{safe_name}/policy",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("policy-set")
+def policy_set(
+    function_name: str = typer.Argument(..., help="Function name"),
+    policy_json: str = typer.Argument(..., help="JSON policy object"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Replace function invoke policy."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, parse_json_arg, print_json
+
+    policy = parse_json_arg(policy_json, label="policy")
+    if policy is None or not isinstance(policy, dict):
+        raise typer.BadParameter("policy must be a JSON object")
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="PUT",
+            path=f"/api/v1/fn/functions/{safe_name}/policy",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body=policy,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("bindings-get")
+def bindings_get(
+    function_name: str = typer.Argument(..., help="Function name"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Fetch function secret bindings."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/fn/functions/{safe_name}/bindings",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("bindings-set")
+def bindings_set(
+    function_name: str = typer.Argument(..., help="Function name"),
+    bindings_json: str = typer.Argument(..., help='JSON array, e.g. [{"name":"API_KEY","value":"..."}]'),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Replace function secret bindings."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, parse_json_arg, print_json
+
+    bindings = parse_json_arg(bindings_json, label="bindings")
+    if bindings is None or not isinstance(bindings, list):
+        raise typer.BadParameter("bindings must be a JSON array")
+    safe_name = quote(function_name, safe="")
+    try:
+        result = call_api(
+            method="PUT",
+            path=f"/api/v1/fn/functions/{safe_name}/bindings",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"bindings": bindings},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("github-repos")
+def github_repos(
+    token: str | None = typer.Option(None, "--token", help="Optional GitHub PAT override"),
+    limit: int = typer.Option(30, "--limit", min=1, max=100),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """List GitHub repositories available for import."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    body: dict[str, object] = {"limit": limit}
+    if token:
+        body["token"] = token
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/fn/github/repositories",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("github-import")
+def github_import(
+    function_name: str = typer.Option(..., "--name", help="Function name to create/update"),
+    repository: str = typer.Option(..., "--repo", help="owner/repo"),
+    path: str = typer.Option(..., "--path", help="Path within the repository"),
+    ref: str = typer.Option("main", "--ref"),
+    token: str | None = typer.Option(None, "--token"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Import a function from a GitHub repository path."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    body: dict[str, object] = {
+        "function_name": function_name,
+        "repository": repository,
+        "path": path,
+        "ref": ref,
+    }
+    if token:
+        body["token"] = token
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/fn/github/import",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("github-commit")
+def github_commit(
+    function_name: str = typer.Option(..., "--name", help="Local function name"),
+    repository: str = typer.Option(..., "--repo", help="owner/repo"),
+    path: str = typer.Option(..., "--path", help="Target path in the repository"),
+    message: str = typer.Option(..., "--message", help="Commit message"),
+    ref: str = typer.Option("main", "--ref"),
+    token: str | None = typer.Option(None, "--token"),
+    committer_name: str | None = typer.Option(None, "--committer-name"),
+    committer_email: str | None = typer.Option(None, "--committer-email"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Commit local function source back to GitHub."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    body: dict[str, object] = {
+        "function_name": function_name,
+        "repository": repository,
+        "path": path,
+        "message": message,
+        "ref": ref,
+    }
+    if token:
+        body["token"] = token
+    if committer_name:
+        body["committer_name"] = committer_name
+    if committer_email:
+        body["committer_email"] = committer_email
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/fn/github/commit",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+def _zip_directory(directory: Path) -> bytes:
+    """Recursively zip all files in *directory* and return raw zip bytes."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for path in sorted(directory.rglob("*")):
+            if path.is_file() and not _should_exclude(path):
+                zf.write(path, path.relative_to(directory))
+    return buf.getvalue()
+
+
+def _load_json_payload(*, data: str | None, data_file: Path | None) -> Any:
+    if data and data_file:
+        raise typer.BadParameter("Use either --data or --data-file, not both")
+    if data_file:
+        return json.loads(data_file.read_text(encoding="utf-8"))
+    if data:
+        return json.loads(data)
+    return {}
+
+
+def _poll_async_invocation(
+    *,
+    api_url: str,
+    headers: dict[str, str],
+    invocation_id: str,
+    project_id: str | None,
+) -> dict[str, Any]:
+    """Poll async invocation status until terminal state or timeout."""
+    deadline = time.time() + _ASYNC_POLL_TIMEOUT
+
+    while time.time() < deadline:
+        params = {"project_id": project_id} if project_id else None
+        resp = httpx.get(
+            f"{api_url}/api/v1/fn/invocations/{invocation_id}",
+            headers=headers,
+            params=params,
+            timeout=15,
+        )
+        if resp.status_code >= 400:
+            typer.echo(f"Async status request failed: {resp.text}", err=True)
+            raise typer.Exit(1)
+
+        body = resp.json()
+        if not isinstance(body, dict):
+            typer.echo("Async status response was not a JSON object", err=True)
+            raise typer.Exit(1)
+        status = str(body.get("status", "UNKNOWN")).upper()
+        if status in {"SUCCEEDED", "FAILED", "TIMEOUT"}:
+            return body
+
+        time.sleep(_ASYNC_POLL_INTERVAL)
+
+    typer.echo("Async invocation polling timed out", err=True)
+    raise typer.Exit(1)
+
+
+_EXCLUDE_NAMES = {".git", "__pycache__", ".venv", "node_modules", ".DS_Store"}
+_EXCLUDE_SUFFIXES = {".pyc", ".pyo", ".egg-info"}
+
+
+def _should_exclude(path: Path) -> bool:
+    for part in path.parts:
+        if part in _EXCLUDE_NAMES:
+            return True
+    return path.suffix in _EXCLUDE_SUFFIXES