caraer-cli 0.1.2__py3-none-any.whl

caraer_cli/local_app.py

@@ -0,0 +1,135 @@
+"""Helpers for local app YAML/JSON selection and discovery."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from caraer_cli.project.app_manifest_template import APP_MANIFEST_NAMES
+from caraer_cli.project.paths import (
+    LEGACY_PROJECT_FILE,
+    WORKSPACE_FILE,
+    app_manifest_path,
+)
+from caraer_cli.utils import load_structured_file
+
+UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+APP_FILE_NAMES = APP_MANIFEST_NAMES
+
+
+def looks_like_uuid(value: str) -> bool:
+    return bool(UUID_RE.match(value.strip()))
+
+
+def looks_like_local_app_ref(value: str) -> bool:
+    """Heuristic: path-like refs should be treated as local app files/dirs."""
+    text = value.strip()
+    if not text:
+        return False
+    if looks_like_uuid(text):
+        return False
+    path = Path(text)
+    if path.exists() or (Path.cwd() / text).exists():
+        return True
+    suffix = path.suffix.lower()
+    if suffix in {".json", ".yaml", ".yml"}:
+        return True
+    if "/" in text or "\\" in text:
+        return True
+    return False
+
+
+def _candidate_app_files_in_dir(directory: Path) -> list[Path]:
+    candidates: list[Path] = []
+    if (directory / WORKSPACE_FILE).is_file() or (directory / LEGACY_PROJECT_FILE).is_file():
+        candidates.append(app_manifest_path(directory))
+    for name in APP_FILE_NAMES:
+        candidates.append(directory / name)
+        candidates.append(directory / "src" / "app" / name)
+    return candidates
+
+
+def resolve_app_file_path(path: str | Path) -> Path:
+    """Resolve a local app file, accepting an app directory or direct file path."""
+    raw = Path(path).expanduser()
+    resolved = raw.resolve() if raw.exists() else raw
+
+    if resolved.is_file():
+        return resolved.resolve()
+
+    if resolved.is_dir() or not resolved.suffix:
+        directory = resolved if resolved.is_dir() else raw
+        # Prefer resolving relative to cwd when the directory does not exist yet.
+        search_root = directory if directory.is_dir() else Path.cwd() / directory
+        if search_root.is_dir():
+            for candidate in _candidate_app_files_in_dir(search_root.resolve()):
+                if candidate.is_file():
+                    return candidate.resolve()
+        raise FileNotFoundError(
+            f"No app.caraer.yaml found under app directory: {search_root}"
+        )
+
+    if not resolved.exists():
+        raise FileNotFoundError(f"Local app file not found: {resolved}")
+    raise ValueError(f"Local app path is not a file: {resolved}")
+
+
+def load_local_app(path: str | Path) -> dict[str, Any]:
+    payload = load_structured_file(str(resolve_app_file_path(path)))
+    if not isinstance(payload, dict):
+        raise ValueError("Local app file must contain a YAML/JSON object.")
+    return payload
+
+
+def local_app_summary(path: Path, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+    data = payload if payload is not None else load_local_app(path)
+    return {
+        "source": "local",
+        "path": str(path),
+        "name": data.get("name"),
+        "label": data.get("label"),
+        "uuid": data.get("uuid"),
+        "privateApp": data.get("privateApp"),
+    }
+
+
+def discover_local_app_files(start: Path | None = None) -> list[Path]:
+    """Find candidate local app definition files near the current directory."""
+    root = (start or Path.cwd()).resolve()
+    found: list[Path] = []
+    seen: set[Path] = set()
+
+    def _add(path: Path) -> None:
+        if not path.is_file():
+            return
+        # Ignore function manifests.
+        if path.name == "function.caraer.json":
+            return
+        resolved = path.resolve()
+        if resolved in seen:
+            return
+        seen.add(resolved)
+        found.append(resolved)
+
+    for name in APP_FILE_NAMES:
+        _add(root / name)
+
+    for name in APP_FILE_NAMES:
+        _add(root / "src" / "app" / name)
+
+    # Child app folders: <dir>/caraer.json → src/app/app.caraer.yaml
+    for marker in (WORKSPACE_FILE, LEGACY_PROJECT_FILE):
+        for workspace in sorted(root.glob(f"*/{marker}")):
+            _add(app_manifest_path(workspace.parent))
+
+    # Also allow immediate child app manifests.
+    for name in APP_FILE_NAMES:
+        for path in sorted(root.glob(f"*/{name}")):
+            _add(path)
+        for path in sorted(root.glob(f"*/src/app/{name}")):
+            _add(path)
+
+    return found

caraer_cli/main.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import typer
+
+from caraer_cli import __version__
+from caraer_cli.commands import (
+    apps,
+    auth,
+    company,
+    profile,
+    publish,
+    sandbox,
+    skill,
+    webhooks,
+)
+from caraer_cli.completion_callbacks import complete_output_format, complete_profile
+from caraer_cli.context import AppContext
+from caraer_cli.errors import ApiError
+from caraer_cli.formatters.output import print_error
+from caraer_cli.state.config import active_profile, load_config
+from caraer_cli.state.session import get_session_token
+
+app = typer.Typer(
+    help="Caraer external developer CLI.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+app.add_typer(auth.app, name="auth")
+app.add_typer(company.app, name="company")
+app.add_typer(apps.app, name="apps")
+app.add_typer(webhooks.app, name="webhooks")
+app.add_typer(publish.app, name="publish")
+app.add_typer(sandbox.app, name="sandbox")
+app.add_typer(profile.app, name="profile")
+app.add_typer(skill.app, name="skill")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"caraer-cli {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    profile: str = typer.Option(
+        None,
+        "--profile",
+        help="Override config profile for this command.",
+        autocompletion=complete_profile,
+    ),
+    output: str = typer.Option(
+        None,
+        "--output",
+        help="table|json|yaml",
+        autocompletion=complete_output_format,
+    ),
+    debug: bool = typer.Option(False, "--debug", help="Show debug details on API errors."),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show the CLI version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Caraer external developer CLI."""
+    # During shell completion Click/Typer sets resilient_parsing; keep side effects light.
+    if ctx.resilient_parsing:
+        ctx.obj = None
+        return
+
+    cfg = load_config()
+    profile_name, profile_cfg = active_profile(cfg, profile)
+    selected_output = output or profile_cfg.output
+    token = get_session_token(profile_name)
+    ctx.obj = AppContext(
+        config=cfg,
+        profile_name=profile_name,
+        profile=profile_cfg,
+        token=token,
+        output=selected_output,
+        debug=debug,
+    )
+
+
+def run() -> None:
+    try:
+        app()
+    except ApiError as exc:
+        print_error(str(exc))
+        raise SystemExit(2) from None
+    except ValueError as exc:
+        print_error(str(exc))
+        raise SystemExit(2) from None
+    except typer.Exit:
+        raise
+    except SystemExit:
+        raise
+
+
+if __name__ == "__main__":
+    run()

caraer_cli/models/__init__.py

@@ -0,0 +1 @@
+"""Pydantic models for API envelopes."""

caraer_cli/models/api.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CaraerValidationError(BaseModel):
+    field: str | None = None
+    message: str | None = None
+    correctionSuggestion: str | None = None
+
+
+class ErrorEnvelope(BaseModel):
+    message: str = "Request failed."
+    status: int = 500
+    errors: list[CaraerValidationError] | None = None
+    roles: list[str] | None = None
+    scopes: list[str] | None = None
+    stackTrace: str | None = None
+    requestId: str | None = None
+    correlationId: str | None = None
+
+
+class SuccessEnvelope(BaseModel):
+    message: str = "Success"
+    data: Any = None
+
+
+class PaginationEnvelope(SuccessEnvelope):
+    total: int = 0
+    page: int = 1
+    perPage: int = 25
+    lastPage: int = 1
+
+
+class AuthTokenModel(BaseModel):
+    token: str | None = None
+    expiresAt: int | None = None
+
+
+class CompanyModel(BaseModel):
+    uuid: str
+    name: str | None = None
+
+
+class UserModel(BaseModel):
+    uuid: str
+    email: str | None = None
+    globalRole: str | None = None
+    token: AuthTokenModel | None = None
+    companies: list[CompanyModel] = Field(default_factory=list)

caraer_cli/project/__init__.py

@@ -0,0 +1,17 @@
+"""Local Caraer developer project helpers."""
+
+from caraer_cli.project.schema import (
+    PLATFORM_VERSION,
+    FunctionManifest,
+    ProjectConfig,
+    load_project_config,
+    save_project_config,
+)
+
+__all__ = [
+    "PLATFORM_VERSION",
+    "FunctionManifest",
+    "ProjectConfig",
+    "load_project_config",
+    "save_project_config",
+]

caraer_cli/project/app_bars_sync.py

@@ -0,0 +1,154 @@
+"""Discover / write modular appBars files under src/app/app-bars/."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from caraer_cli.project.paths import app_bars_dir
+from caraer_cli.project.schema import ProjectConfig
+
+LOCAL_APP_BAR_KEYS = (
+    "uuid",
+    "location",
+    "label",
+    "tooltipLabel",
+    "description",
+    "actionLabel",
+    "iframeUrl",
+    "icon",
+    "settingsSchema",
+    "webhook",
+)
+
+ACTION_BASED_LOCATIONS = frozenset({"RECORD_PREVIEW", "RECORD_OVERVIEW"})
+
+
+def _slug(value: str) -> str:
+    text = value.strip().lower()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    return text.strip("-") or "app-bar"
+
+
+def app_bar_filename(item: dict[str, Any]) -> str:
+    location = _slug(str(item.get("location") or "bar"))
+    label = _slug(str(item.get("label") or "app-bar"))
+    return f"{location}-{label}.json"
+
+
+def app_bar_identity(item: dict[str, Any]) -> str:
+    location = str(item.get("location") or "").strip().upper()
+    label = str(item.get("label") or "").strip().lower()
+    return f"{location}|{label}"
+
+
+def _sanitize_webhook(webhook: Any) -> dict[str, Any] | None:
+    if not isinstance(webhook, dict):
+        return None
+    cleaned: dict[str, Any] = {}
+    for key in (
+        "uuid",
+        "topic",
+        "deliveryMode",
+        "url",
+        "description",
+        "enabled",
+        "webhookFormat",
+        "serverlessFunction",
+    ):
+        if key in webhook and webhook[key] is not None:
+            cleaned[key] = webhook[key]
+    sf = cleaned.get("serverlessFunction")
+    if isinstance(sf, dict):
+        sf_out: dict[str, Any] = {}
+        if sf.get("name"):
+            sf_out["name"] = sf["name"]
+        elif sf.get("uuid"):
+            sf_out["uuid"] = sf["uuid"]
+        if sf_out:
+            cleaned["serverlessFunction"] = sf_out
+        else:
+            cleaned.pop("serverlessFunction", None)
+    return cleaned or None
+
+
+def sanitize_app_bar(item: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    for key in LOCAL_APP_BAR_KEYS:
+        if key not in item or item[key] is None:
+            continue
+        if key == "webhook":
+            webhook = _sanitize_webhook(item[key])
+            if webhook:
+                payload["webhook"] = webhook
+        else:
+            payload[key] = item[key]
+    return payload
+
+
+def discover_local_app_bars(
+    root: Path, config: ProjectConfig
+) -> list[tuple[Path, dict[str, Any]]]:
+    base = app_bars_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) and data.get("label") and data.get("location"):
+            found.append((path, sanitize_app_bar(data)))
+    return found
+
+
+def write_app_bars_files(
+    root: Path, config: ProjectConfig, items: list[dict[str, Any]]
+) -> int:
+    base = app_bars_dir(root, config.srcDir)
+    base.mkdir(parents=True, exist_ok=True)
+    for existing in base.glob("*.json"):
+        existing.unlink()
+    count = 0
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        sanitized = sanitize_app_bar(item)
+        if not app_bar_identity(sanitized).strip("|"):
+            continue
+        path = base / app_bar_filename(sanitized)
+        path.write_text(json.dumps(sanitized, indent=2) + "\n", encoding="utf-8")
+        count += 1
+    return count
+
+
+def resolve_app_bar_functions(
+    item: dict[str, Any],
+    *,
+    fn_by_name: dict[str, str],
+    strict: bool = True,
+) -> dict[str, Any] | None:
+    out = dict(item)
+    out.pop("uuid", None)
+    webhook = out.get("webhook")
+    if not isinstance(webhook, dict):
+        return out
+    webhook = dict(webhook)
+    webhook.pop("uuid", None)
+    sf = webhook.get("serverlessFunction")
+    if isinstance(sf, dict):
+        if sf.get("uuid"):
+            webhook["serverlessFunction"] = {"uuid": sf["uuid"]}
+        else:
+            name = sf.get("name")
+            if name and name in fn_by_name:
+                webhook["serverlessFunction"] = {"uuid": fn_by_name[name]}
+            elif name:
+                if strict:
+                    raise ValueError(
+                        f"App bar references function '{name}' but no UUID is known. "
+                        "Push functions first."
+                    )
+                return None
+    out["webhook"] = webhook
+    return out

caraer_cli/project/app_manifest_template.py

@@ -0,0 +1,68 @@
+"""Render and locate local app manifests (YAML preferred)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+APP_MANIFEST_YAML = "app.caraer.yaml"
+APP_MANIFEST_JSON = "app.caraer.json"  # legacy; still loaded if present
+APP_MANIFEST_NAMES = (APP_MANIFEST_YAML, APP_MANIFEST_JSON, "app.yaml", "app.yml", "app.json")
+
+_EXAMPLE_REQUIRED_SCOPES = """\
+# Example scopes (uncomment and edit):
+# requiredScopes:
+#   - tools.forms.all
+#   - records.candidate.properties_all
+"""
+
+_EXAMPLE_SETTINGS_SCHEMA = """\
+# Edit settingsSchema above, or: caraer apps add-setting
+# Optional modular files also work: src/app/settings/<name>.json (--modular)
+"""
+
+_EXAMPLE_PRICING_PLANS = """\
+# Edit pricingPlans above, or: caraer apps add-pricing-plan
+# Optional modular files: src/app/pricing/<slug>.json (--modular)
+"""
+
+_EXAMPLE_APP_BARS = """\
+# Edit appBars above, or: caraer apps add-app-bar
+# Optional modular files: src/app/app-bars/<slug>.json (--modular)
+# Lifecycle hooks: src/app/lifecycle/ + functions/on-* (caraer apps add-lifecycle-hook)
+"""
+
+
+def render_app_manifest(payload: dict[str, Any], *, include_examples: bool = True) -> str:
+    """Serialize an app manifest as YAML, optionally with commented-out examples."""
+    from caraer_cli.project.json_schemas import YAML_LANGUAGE_SERVER_COMMENT
+
+    data = dict(payload)
+    for key in ("requiredScopes", "settingsSchema", "pricingPlans", "appBars"):
+        data.setdefault(key, [])
+
+    body = yaml.safe_dump(
+        data,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+    ).rstrip() + "\n"
+    header = YAML_LANGUAGE_SERVER_COMMENT + "\n"
+    if not include_examples:
+        return header + body
+
+    lines = body.splitlines()
+    out: list[str] = [YAML_LANGUAGE_SERVER_COMMENT]
+    for line in lines:
+        out.append(line)
+        stripped = line.strip()
+        if stripped == "requiredScopes: []":
+            out.append(_EXAMPLE_REQUIRED_SCOPES.rstrip("\n"))
+        elif stripped == "settingsSchema: []":
+            out.append(_EXAMPLE_SETTINGS_SCHEMA.rstrip("\n"))
+        elif stripped == "pricingPlans: []":
+            out.append(_EXAMPLE_PRICING_PLANS.rstrip("\n"))
+        elif stripped == "appBars: []":
+            out.append(_EXAMPLE_APP_BARS.rstrip("\n"))
+    return "\n".join(out) + "\n"