caraer-cli 0.1.2__py3-none-any.whl

caraer_cli/project/inbound_sync.py

@@ -0,0 +1,192 @@
+"""Sync inbound routes between src/app/inbound/*.json and the remote API."""
+
+from __future__ import annotations
+
+import json
+import re
+import secrets
+from pathlib import Path
+from typing import Any
+
+from caraer_cli.api import integration_runtime as api
+from caraer_cli.api.client import CaraerApiClient
+from caraer_cli.project.paths import inbound_dir
+from caraer_cli.project.schema import ProjectConfig
+from caraer_cli.project.state import load_state, save_state
+
+LOCAL_INBOUND_KEYS = (
+    "uuid",
+    "name",
+    "label",
+    "authMode",
+    "enqueue",
+    "sharedSecret",
+    "serverlessFunction",
+)
+
+
+def _slug(value: str) -> str:
+    text = value.strip().lower()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    return text.strip("-") or "inbound"
+
+
+def inbound_filename(item: dict[str, Any]) -> str:
+    name = str(item.get("name") or "inbound")
+    uuid = str(item.get("uuid") or "")[:8]
+    parts = [_slug(name)]
+    if uuid:
+        parts.append(uuid)
+    return "-".join(parts) + ".json"
+
+
+def discover_local_inbound(root: Path, config: ProjectConfig) -> list[tuple[Path, dict[str, Any]]]:
+    base = inbound_dir(root, config.srcDir)
+    if not base.is_dir():
+        return []
+    found: list[tuple[Path, dict[str, Any]]] = []
+    for path in sorted(base.glob("*.json")):
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            found.append((path, data))
+    return found
+
+
+def _sanitize_local(item: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    for key in LOCAL_INBOUND_KEYS:
+        if key in item and item[key] is not None:
+            payload[key] = item[key]
+    # Never persist sharedSecret after push in pulled files — keep local-only until push.
+    sf = payload.get("serverlessFunction")
+    if isinstance(sf, dict):
+        cleaned: dict[str, Any] = {}
+        if sf.get("name"):
+            cleaned["name"] = sf["name"]
+        elif sf.get("uuid"):
+            cleaned["uuid"] = sf["uuid"]
+        if cleaned:
+            payload["serverlessFunction"] = cleaned
+        else:
+            payload.pop("serverlessFunction", None)
+    return payload
+
+
+def _sanitize_remote(item: dict[str, Any]) -> dict[str, Any]:
+    payload = _sanitize_local(item)
+    payload.pop("sharedSecret", None)
+    if item.get("hasSharedSecret"):
+        payload["hasSharedSecret"] = True
+    return payload
+
+
+def _resolve_sf(payload: dict[str, Any], *, fn_by_name: dict[str, str]) -> dict[str, Any]:
+    out = dict(payload)
+    out.pop("uuid", None)
+    out.pop("hasSharedSecret", None)
+    sf = out.get("serverlessFunction")
+    if not isinstance(sf, dict):
+        return out
+    if sf.get("uuid"):
+        out["serverlessFunction"] = {"uuid": sf["uuid"]}
+        return out
+    name = sf.get("name")
+    if name and name in fn_by_name:
+        out["serverlessFunction"] = {"uuid": fn_by_name[name]}
+        return out
+    if name:
+        raise ValueError(
+            f"Inbound route references function '{name}' but no UUID is known. Push functions first."
+        )
+    return out
+
+
+def pull_inbound(client: CaraerApiClient, root: Path, config: ProjectConfig) -> int:
+    if not config.appUuid:
+        raise ValueError("App is not linked.")
+    response = api.list_inbound_routes(client, config.appUuid)
+    items = response.get("data") or []
+    if not isinstance(items, list):
+        items = []
+    base = inbound_dir(root, config.srcDir)
+    base.mkdir(parents=True, exist_ok=True)
+    for existing in base.glob("*.json"):
+        existing.unlink()
+    state = load_state(root)
+    inbound_map: dict[str, str] = {}
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        sanitized = _sanitize_remote(item)
+        path = base / inbound_filename(sanitized)
+        path.write_text(json.dumps(sanitized, indent=2) + "\n", encoding="utf-8")
+        if sanitized.get("uuid") and sanitized.get("name"):
+            inbound_map[str(sanitized["name"])] = str(sanitized["uuid"])
+    state["inbound"] = inbound_map
+    save_state(root, state)
+    return len(inbound_map)
+
+
+def push_inbound(
+    client: CaraerApiClient,
+    root: Path,
+    config: ProjectConfig,
+    *,
+    delete_missing: bool = False,
+) -> dict[str, Any]:
+    if not config.appUuid:
+        raise ValueError("App is not linked.")
+    state = load_state(root)
+    fn_state = state.get("functions") or {}
+    fn_by_name = {
+        name: str(meta["uuid"])
+        for name, meta in fn_state.items()
+        if isinstance(meta, dict) and meta.get("uuid")
+    }
+    remote = api.list_inbound_routes(client, config.appUuid).get("data") or []
+    remote_by_uuid = {
+        str(i["uuid"]): i for i in remote if isinstance(i, dict) and i.get("uuid")
+    }
+    remote_by_name = {
+        str(i["name"]): i for i in remote if isinstance(i, dict) and i.get("name")
+    }
+    local = discover_local_inbound(root, config)
+    pushed: dict[str, str] = {}
+    kept_uuids: set[str] = set()
+    for path, raw in local:
+        sanitized = _sanitize_local(raw)
+        payload = _resolve_sf(sanitized, fn_by_name=fn_by_name)
+        name = str(sanitized.get("name") or "")
+        uuid = str(sanitized.get("uuid") or "")
+        existing = remote_by_uuid.get(uuid) or remote_by_name.get(name)
+        auth_mode = str(payload.get("authMode") or "SHARED_SECRET").upper()
+        if (
+            not existing
+            and auth_mode == "SHARED_SECRET"
+            and not str(payload.get("sharedSecret") or "").strip()
+        ):
+            generated = secrets.token_urlsafe(24)
+            payload["sharedSecret"] = generated
+            # Keep locally so Pub/Sub can be configured; not written back after create.
+            sanitized["sharedSecret"] = generated
+            path.write_text(json.dumps(sanitized, indent=2) + "\n", encoding="utf-8")
+        if existing and existing.get("uuid"):
+            resp = api.update_inbound_route(client, config.appUuid, str(existing["uuid"]), payload)
+            data = resp.get("data") or existing
+        else:
+            resp = api.create_inbound_route(client, config.appUuid, payload)
+            data = resp.get("data") or {}
+        if isinstance(data, dict) and data.get("uuid"):
+            kept_uuids.add(str(data["uuid"]))
+            if data.get("name"):
+                pushed[str(data["name"])] = str(data["uuid"])
+            write_back = _sanitize_remote({**sanitized, **data})
+            write_back.pop("sharedSecret", None)
+            path.write_text(json.dumps(write_back, indent=2) + "\n", encoding="utf-8")
+    if delete_missing:
+        for uuid in remote_by_uuid:
+            if uuid not in kept_uuids:
+                api.delete_inbound_route(client, config.appUuid, uuid)
+    state["inbound"] = pushed
+    save_state(root, state)
+    return {"pushed": len(pushed), "deletedMissing": delete_missing}

caraer_cli/project/json_schemas.py

@@ -0,0 +1,66 @@
+"""JSON Schema URLs and helpers for Caraer app config files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+SCHEMA_REPO_BASE = (
+    "https://raw.githubusercontent.com/caraer/caraer-cli/main/schemas"
+)
+
+APP_MANIFEST_SCHEMA_URL = f"{SCHEMA_REPO_BASE}/app.caraer.schema.json"
+FUNCTION_SCHEMA_URL = f"{SCHEMA_REPO_BASE}/function.caraer.schema.json"
+WEBHOOK_SCHEMA_URL = f"{SCHEMA_REPO_BASE}/webhook.caraer.schema.json"
+SCHEDULE_SCHEMA_URL = f"{SCHEMA_REPO_BASE}/schedule.caraer.schema.json"
+INBOUND_SCHEMA_URL = f"{SCHEMA_REPO_BASE}/inbound.caraer.schema.json"
+LIFECYCLE_SCHEMA_URL = f"{SCHEMA_REPO_BASE}/lifecycle.caraer.schema.json"
+
+YAML_LANGUAGE_SERVER_COMMENT = (
+    f"# yaml-language-server: $schema={APP_MANIFEST_SCHEMA_URL}"
+)
+
+SCHEMA_FILENAMES = {
+    "app": "app.caraer.schema.json",
+    "function": "function.caraer.schema.json",
+    "webhook": "webhook.caraer.schema.json",
+    "schedule": "schedule.caraer.schema.json",
+    "inbound": "inbound.caraer.schema.json",
+    "lifecycle": "lifecycle.caraer.schema.json",
+}
+
+
+def schemas_dir() -> Path | None:
+    """Locate the local ``schemas/`` directory when available."""
+    here = Path(__file__).resolve()
+    candidates = [
+        # Packaged: caraer_cli/schemas (via hatch force-include)
+        here.parents[1] / "schemas",
+        # Dev checkout: <repo>/schemas
+        here.parents[2] / "schemas",
+    ]
+    for path in candidates:
+        if path.is_dir() and (path / "function.caraer.schema.json").is_file():
+            return path
+    return None
+
+
+def with_json_schema(payload: dict[str, Any], schema_url: str) -> dict[str, Any]:
+    """Return a copy of payload with ``$schema`` first."""
+    out: dict[str, Any] = {"$schema": schema_url}
+    for key, value in payload.items():
+        if key == "$schema":
+            continue
+        out[key] = value
+    return out
+
+
+def dump_json_with_schema(
+    path: Path, payload: dict[str, Any], schema_url: str
+) -> None:
+    """Write JSON with a leading ``$schema`` field."""
+    path.write_text(
+        json.dumps(with_json_schema(payload, schema_url), indent=2) + "\n",
+        encoding="utf-8",
+    )

caraer_cli/project/lifecycle_sync.py

@@ -0,0 +1,119 @@
+"""Discover / write lifecycle webhook configs under src/app/lifecycle/."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from caraer_cli.project.paths import lifecycle_dir
+from caraer_cli.project.schema import ProjectConfig
+
+# filename stem → (manifest key, expected topic)
+LIFECYCLE_HOOKS: dict[str, tuple[str, str]] = {
+    "install": ("installWebhook", "app.installed"),
+    "uninstall": ("uninstallWebhook", "app.uninstalled"),
+    "rotate": ("rotateWebhook", "app.rotated"),
+    "update": ("updateWebhook", "app.updated"),
+}
+
+MANIFEST_KEY_TO_FILE = {
+    manifest_key: stem for stem, (manifest_key, _) in LIFECYCLE_HOOKS.items()
+}
+
+LOCAL_LIFECYCLE_KEYS = (
+    "topic",
+    "deliveryMode",
+    "url",
+    "description",
+    "enabled",
+    "webhookFormat",
+    "secret",
+    "serverlessFunction",
+)
+
+
+def sanitize_lifecycle(item: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    for key in LOCAL_LIFECYCLE_KEYS:
+        if key in item and item[key] is not None:
+            payload[key] = item[key]
+    sf = payload.get("serverlessFunction")
+    if isinstance(sf, dict):
+        cleaned: dict[str, Any] = {}
+        if sf.get("name"):
+            cleaned["name"] = sf["name"]
+        elif sf.get("uuid"):
+            cleaned["uuid"] = sf["uuid"]
+        if cleaned:
+            payload["serverlessFunction"] = cleaned
+        else:
+            payload.pop("serverlessFunction", None)
+    return payload
+
+
+def discover_local_lifecycle(
+    root: Path, config: ProjectConfig
+) -> dict[str, dict[str, Any]]:
+    """Return manifest_key → sanitized webhook dict for present lifecycle files."""
+    base = lifecycle_dir(root, config.srcDir)
+    if not base.is_dir():
+        return {}
+    found: dict[str, dict[str, Any]] = {}
+    for stem, (manifest_key, _topic) in LIFECYCLE_HOOKS.items():
+        path = base / f"{stem}.json"
+        if not path.is_file():
+            continue
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            found[manifest_key] = sanitize_lifecycle(data)
+    return found
+
+
+def write_lifecycle_files(
+    root: Path, config: ProjectConfig, hooks: dict[str, dict[str, Any] | None]
+) -> int:
+    """Write lifecycle/*.json from manifest hook objects. Clears missing files."""
+    base = lifecycle_dir(root, config.srcDir)
+    base.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for stem, (manifest_key, expected_topic) in LIFECYCLE_HOOKS.items():
+        path = base / f"{stem}.json"
+        raw = hooks.get(manifest_key)
+        if not isinstance(raw, dict) or not raw:
+            if path.exists():
+                path.unlink()
+            continue
+        sanitized = sanitize_lifecycle(raw)
+        if not sanitized.get("topic"):
+            sanitized["topic"] = expected_topic
+        path.write_text(json.dumps(sanitized, indent=2) + "\n", encoding="utf-8")
+        count += 1
+    return count
+
+
+def resolve_lifecycle_functions(
+    webhook: dict[str, Any],
+    *,
+    fn_by_name: dict[str, str],
+    strict: bool = True,
+) -> dict[str, Any] | None:
+    out = dict(webhook)
+    sf = out.get("serverlessFunction")
+    if not isinstance(sf, dict):
+        return out
+    if sf.get("uuid"):
+        out["serverlessFunction"] = {"uuid": sf["uuid"]}
+        return out
+    name = sf.get("name")
+    if name and name in fn_by_name:
+        out["serverlessFunction"] = {"uuid": fn_by_name[name]}
+        return out
+    if name:
+        if strict:
+            raise ValueError(
+                f"Lifecycle webhook references function '{name}' but no UUID is known. "
+                "Push functions first."
+            )
+        return None
+    return out