caraer-cli 0.1.2__py3-none-any.whl

caraer_cli/skills/.gitkeep

@@ -0,0 +1,2 @@
+# Packaged copy of repo skills/ (see hatch force-include). Placeholder so the
+# package path exists before build; wheel build overlays skills/caraer-apps.

caraer_cli/skills/caraer-apps/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: caraer-apps
+description: >-
+  Scaffolds, edits, validates, and deploys Caraer Apps V2 projects with the
+  caraer CLI (app.caraer.yaml, serverless functions, inbound routes, schedules,
+  lifecycle hooks, settings, app bars). Use when creating or changing a Caraer
+  public app, marketplace app, serverless function, webhook, inbound route, or
+  when the user mentions caraer apps, app.caraer.yaml, or caraer-cli.
+---
+
+# Caraer Apps (CLI)
+
+Build Caraer apps with the **caraer** CLI and the V2 layout (`platformVersion:
+2026.2`). Prefer CLI scaffolds over inventing folders by hand.
+
+## Install this skill
+
+From a machine with `caraer-cli` installed:
+
+```bash
+caraer skill install              # ~/.cursor/skills/caraer-apps
+caraer skill install --project    # ./.cursor/skills/caraer-apps (this repo)
+```
+
+Or copy `skills/caraer-apps/` from the [caraer-cli](https://github.com/Caraer-HQ/caraer-cli)
+repo into `~/.cursor/skills/caraer-apps/`.
+
+## Preconditions
+
+1. CLI available: `caraer --version` (Python 3.10+).
+2. Auth + company: `caraer auth login` then `caraer company select <uuid>`.
+3. Work inside an app folder (has `caraer.json`) or pass `--file`.
+
+## Golden path
+
+```bash
+caraer apps init --name my_app --label "My App"
+cd my_app
+# edit src/app/app.caraer.yaml + functions
+caraer apps validate
+caraer apps typegen
+caraer apps push --dry-run
+caraer apps push --deploy
+caraer apps install
+caraer apps status
+caraer apps logs --follow
+```
+
+Local loop without deploy:
+
+```bash
+caraer apps dev
+caraer apps test --function <name> --sample-only
+```
+
+## Project layout (V2)
+
+```text
+caraer.json
+src/app/
+  app.caraer.yaml           # identity, auth, settings, pricing, app bars, OAuth
+  functions/<name>/         # function.caraer.json + index.js|main.py (+ shared.js)
+  lifecycle/*.json          # install|uninstall|rotate|update → function
+  inbound/*.json            # public HTTP → function
+  schedules/*.json          # cron → function
+  webhooks/*.json           # platform events → function
+src/types/                  # from `caraer apps typegen`
+```
+
+JSON Schema for IDE hints:
+
+`https://raw.githubusercontent.com/Caraer-HQ/caraer-cli/main/schemas/app.caraer.schema.json`
+
+Point the YAML at it:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Caraer-HQ/caraer-cli/main/schemas/app.caraer.schema.json
+```
+
+Reference example: `examples/webhook-inbox` in the caraer-cli repo.
+
+## Agent workflow
+
+Copy and track:
+
+```text
+App progress:
+- [ ] Clarify job (inbound / schedule / record bar / OAuth / records)
+- [ ] `caraer apps init` or open existing app
+- [ ] Edit manifest settings (user-facing only)
+- [ ] Add/edit functions (shared helpers copied per folder)
+- [ ] Wire inbound / schedule / webhook / app bar / lifecycle
+- [ ] `caraer apps validate` → fix until 0 errors
+- [ ] `caraer apps push --dry-run` then `--deploy` when user asks
+```
+
+### Clarify before coding
+
+Ask only what blocks design:
+
+- Trigger: inbound HTTP, schedule, record event, app bar, or install lifecycle?
+- Runtime: `nodejs22` (default) or `python312`?
+- Need installation state/secrets? → `authMethod: API_KEY` (gets `installationToken`).
+- Need Caraer user OAuth app install? → `OAUTH2` + redirect URIs.
+- External provider (Google, etc.)? → `externalOAuthProviders` + `${ENV}` secrets.
+
+### Settings UX rules
+
+Installation settings are for **admins installing the app**, not developers.
+
+- Use clear labels + `helpText`. Prefer `SWITCH`, `OBJECT_SINGLE_SELECT`,
+  `SINGLE_SELECT` over free-text when possible.
+- Do **not** add `caraer_api_base` or other platform URLs — runtime injects
+  `body.caraerApiBase`.
+- Do **not** ask for object/property names as raw strings when a select type exists.
+- Keep required settings to the minimum that makes the app work.
+
+### Functions
+
+- Node: `exports.handler = async (req, res) => { ... }`.
+- Python: `def handler(request): ...` returning `{statusCode, body}`.
+- Each function folder deploys alone — **copy** `shared.js` / helpers into every
+  folder that needs them (see webhook-inbox).
+- Read settings via flattened `body.settingsSchema` (`name` → `value`).
+- Use `body.installationToken` + `body.appUuid` for
+  `/v2/apps/{appUuid}/installation/state|secrets|jobs`.
+- Prefer `body.caraerApiBase` when calling Caraer APIs.
+
+### Scaffolding commands
+
+| Need | Command |
+|------|---------|
+| New function | `caraer apps add-function` |
+| Inbound route | `caraer apps add-inbound` |
+| Schedule | `caraer apps add-schedule` |
+| Webhook | `caraer apps add-webhook` |
+| Setting | `caraer apps add-setting` |
+| App bar | `caraer apps add-app-bar` |
+| Lifecycle | `caraer apps add-lifecycle-hook` |
+| Pricing | `caraer apps add-pricing-plan` |
+
+### Validate loop
+
+After every structural edit:
+
+```bash
+caraer apps validate --file .
+```
+
+Fix errors before push. Warnings (e.g. missing inbound `sharedSecret`) are OK
+to leave for the installer when documented in README.
+
+### Deploy safety
+
+- Never push/deploy/install unless the user asks.
+- Use `caraer apps push --dry-run` first for non-trivial changes.
+- Do not commit secrets (`.env`, OAuth client secrets, inbound shared secrets).
+- Expand `${ENV_VAR}` OAuth client fields from the **process environment** on push.
+
+## Anti-patterns
+
+- Inventing V1 per-function GCP layouts when V2 is default.
+- Hand-writing remote UUIDs into YAML (let push fill them).
+- One giant shared package import across functions (runtime is per-folder).
+- Putting developer-only knobs in `settingsSchema`.
+- Skipping `validate` before `push`.
+
+## Dig deeper
+
+- Payload shapes, lifecycle events, settings flattening: [reference.md](reference.md)
+- CLI docs in the caraer-cli repo: `docs/app_lifecycle.md`, `docs/platform_versioning.md`
+- Schemas: `schemas/*.caraer.schema.json`

caraer_cli/skills/caraer-apps/reference.md

@@ -0,0 +1,163 @@
+# Caraer Apps — reference
+
+Companion to [SKILL.md](SKILL.md). Read when implementing handlers or wiring
+marketplace modules.
+
+## Auth methods
+
+| `authMethod` | Use when | Notes |
+|--------------|----------|-------|
+| `API_KEY` | App needs `installationToken` for state/secrets/jobs | Typical for integrations |
+| `OAUTH2` | Install uses Caraer OAuth app flow | Set `oauthRedirectUris` |
+
+External providers (`externalOAuthProviders`) are separate from `authMethod`.
+Connected tokens arrive as installation secrets (e.g. `gmail_access_token`).
+
+## Handler envelope (SERVERLESS)
+
+Approximate JSON body (also wrapped as `req.body` for Node):
+
+```json
+{
+  "event": "Installed",
+  "appUuid": "...",
+  "companyUuid": "...",
+  "installationToken": "...",
+  "caraerApiBase": "https://api.caraer.com/api",
+  "functionName": "catch",
+  "settingsSchema": [
+    { "name": "inbox_label", "type": "SINGLE_LINE", "value": "Main" }
+  ],
+  "secrets": {},
+  "payload": {}
+}
+```
+
+Lifecycle `event` values: `Installed`, `Updated`, `Uninstalled`, `Rotated`.
+
+Connect / Disconnect for external OAuth are **not** lifecycle webhooks — read
+secrets from the payload / secrets API after the user connects.
+
+## Installation APIs (Bearer installationToken)
+
+Base: `{caraerApiBase}` (no trailing slash).
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET/PUT | `/v2/apps/{appUuid}/installation/state` | JSON blob state |
+| GET/PUT | `/v2/apps/{appUuid}/installation/secrets` | Secret map |
+| POST | `/v2/apps/{appUuid}/installation/jobs` | `{ "functionName", "payload" }` |
+
+## Setting field types
+
+`SINGLE_LINE`, `MULTI_LINE`, `SINGLE_SELECT`, `MULTI_SELECT`,
+`RECORD_SINGLE_SELECT`, `RECORD_MULTI_SELECT`, `OBJECT_SINGLE_SELECT`,
+`OBJECT_MULTI_SELECT`, `PROPERTY_SINGLE_SELECT`, `PROPERTY_MULTI_SELECT`,
+`SWITCH`, `MAPPING`, `SECRET`.
+
+Flatten helper:
+
+```js
+function flattenSettings(schema) {
+  const out = {};
+  for (const field of schema || []) {
+    if (field && field.name) {
+      out[field.name] = field.value ?? field.defaultValue ?? null;
+    }
+  }
+  return out;
+}
+```
+
+`OBJECT_*_SELECT` values may be a string name or an object with `name` /
+`internalName` — normalize before API calls.
+
+## Inbound routes
+
+`src/app/inbound/<name>.json`:
+
+```json
+{
+  "name": "catch",
+  "authMode": "SHARED_SECRET",
+  "enqueue": true,
+  "serverlessFunction": { "name": "catch" }
+}
+```
+
+Public URL shape (after deploy):
+
+`POST /api/v2/public/apps/{appUuid}/inbound/{name}?companyUuid={companyUuid}`
+
+Header: `X-Caraer-Inbound-Secret: <sharedSecret>`.
+
+Set `sharedSecret` before production traffic; `validate` warns if missing.
+
+## Schedules
+
+Six-field cron (sec min hour dom mon dow), example every 12 hours:
+
+```json
+{
+  "name": "heartbeat",
+  "schedule": "0 0 */12 * * *",
+  "enabled": true,
+  "serverlessFunction": { "name": "heartbeat" }
+}
+```
+
+## App bars
+
+Action locations can use SERVERLESS without `iframeUrl`:
+
+- `RECORD_PREVIEW`, `RECORD_OVERVIEW`, `RECORD_DETAIL`, `TOOL_BAR`, `TRAIT_BAR`
+
+Wire `webhook.serverlessFunction.name` to a local function folder name.
+
+## Node handler skeleton
+
+```js
+exports.handler = async (req, res) => {
+  try {
+    const body =
+      typeof req.body === "string"
+        ? JSON.parse(req.body || "{}")
+        : req.body || {};
+    // ...
+    return res.status(200).json({ ok: true });
+  } catch (err) {
+    return res.status(500).json({
+      ok: false,
+      error: String(err && err.message ? err.message : err),
+    });
+  }
+};
+```
+
+## Python handler skeleton
+
+```python
+def handler(request):
+    body = request.get("body") if isinstance(request, dict) else {}
+    if isinstance(body, str):
+        import json
+        body = json.loads(body or "{}")
+    return {"statusCode": 200, "body": {"ok": True}}
+```
+
+## Useful CLI
+
+```bash
+caraer apps current
+caraer apps validate
+caraer apps push --dry-run
+caraer apps push --deploy
+caraer apps status
+caraer apps logs --follow
+caraer apps state get
+caraer apps jobs list
+caraer apps connections list
+caraer apps test --function <name> --record <uuid>
+caraer apps dev --invoke-schedule <schedule-name>
+caraer skill install --project
+```

caraer_cli/state/__init__.py

@@ -0,0 +1 @@
+"""Configuration and session helpers."""

caraer_cli/state/config.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+CONFIG_DIRNAME = "caraer-cli"
+CONFIG_FILENAME = "config.toml"
+
+
+@dataclass
+class ProfileConfig:
+    base_url: str
+    company_uuid: str | None = None
+    sandbox_uuid: str | None = None
+    app_uuid: str | None = None
+    app_file: str | None = None
+    output: str = "table"
+    timeout_seconds: float = 120.0
+    verify_ssl: bool = True
+
+
+@dataclass
+class CliConfig:
+    active_profile: str = "dev"
+    profiles: dict[str, ProfileConfig] = field(default_factory=dict)
+
+    @staticmethod
+    def default() -> "CliConfig":
+        return CliConfig(
+            active_profile="dev",
+            profiles={
+                "dev": ProfileConfig(base_url="http://localhost:8080"),
+                "staging": ProfileConfig(base_url="https://staging.caraer.com"),
+                "prod": ProfileConfig(base_url="https://caraer.com"),
+            },
+        )
+
+
+def config_dir() -> Path:
+    return Path(user_config_dir(CONFIG_DIRNAME))
+
+
+def config_path() -> Path:
+    return config_dir() / CONFIG_FILENAME
+
+
+def _toml_value(value: Any) -> str:
+    if isinstance(value, str):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None:
+        return '""'
+    return str(value)
+
+
+def _to_toml(cfg: CliConfig) -> str:
+    lines: list[str] = [f'active_profile = "{cfg.active_profile}"', ""]
+    for profile_name, profile in cfg.profiles.items():
+        lines.extend(
+            [
+                f"[profiles.{profile_name}]",
+                f"base_url = {_toml_value(profile.base_url)}",
+                f"company_uuid = {_toml_value(profile.company_uuid)}",
+                f"sandbox_uuid = {_toml_value(profile.sandbox_uuid)}",
+                f"app_uuid = {_toml_value(profile.app_uuid)}",
+                f"app_file = {_toml_value(profile.app_file)}",
+                f"output = {_toml_value(profile.output)}",
+                f"timeout_seconds = {_toml_value(profile.timeout_seconds)}",
+                f"verify_ssl = {_toml_value(profile.verify_ssl)}",
+                "",
+            ]
+        )
+    return "\n".join(lines).strip() + "\n"
+
+
+def load_config() -> CliConfig:
+    path = config_path()
+    if not path.exists():
+        cfg = CliConfig.default()
+        save_config(cfg)
+        return cfg
+
+    with path.open("rb") as handle:
+        raw = tomllib.load(handle)
+
+    cfg = CliConfig.default()
+    cfg.active_profile = raw.get("active_profile", cfg.active_profile)
+    profile_block = raw.get("profiles", {})
+    if isinstance(profile_block, dict):
+        cfg.profiles = {}
+        for name, value in profile_block.items():
+            if not isinstance(value, dict):
+                continue
+            cfg.profiles[name] = ProfileConfig(
+                base_url=str(value.get("base_url", "http://localhost:8080")),
+                company_uuid=value.get("company_uuid") or None,
+                sandbox_uuid=value.get("sandbox_uuid") or None,
+                app_uuid=value.get("app_uuid") or None,
+                app_file=value.get("app_file") or None,
+                output=str(value.get("output", "table")),
+                timeout_seconds=float(value.get("timeout_seconds", 120.0)),
+                verify_ssl=bool(value.get("verify_ssl", True)),
+            )
+
+    if cfg.active_profile not in cfg.profiles:
+        cfg.active_profile = next(iter(cfg.profiles.keys()), "dev")
+    return cfg
+
+
+def save_config(cfg: CliConfig) -> None:
+    dir_path = config_dir()
+    dir_path.mkdir(parents=True, exist_ok=True)
+    path = config_path()
+    path.write_text(_to_toml(cfg), encoding="utf-8")
+    os.chmod(path, 0o600)
+
+
+def active_profile(cfg: CliConfig, override: str | None = None) -> tuple[str, ProfileConfig]:
+    key = override or cfg.active_profile
+    if key not in cfg.profiles:
+        raise ValueError(f"Unknown profile '{key}'.")
+    return key, cfg.profiles[key]
+
+
+def profile_as_dict(profile: ProfileConfig) -> dict[str, Any]:
+    return {
+        "base_url": profile.base_url,
+        "company_uuid": profile.company_uuid,
+        "sandbox_uuid": profile.sandbox_uuid,
+        "app_uuid": profile.app_uuid,
+        "app_file": profile.app_file,
+        "output": profile.output,
+        "timeout_seconds": profile.timeout_seconds,
+        "verify_ssl": profile.verify_ssl,
+    }

caraer_cli/state/session.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import keyring
+from platformdirs import user_config_dir
+
+
+APP_NAME = "caraer-cli"
+SERVICE_NAME = "caraer-cli-session"
+
+
+def _fallback_session_path() -> Path:
+    path = Path(user_config_dir(APP_NAME)) / "sessions.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text("{}", encoding="utf-8")
+        os.chmod(path, 0o600)
+    return path
+
+
+def _load_fallback() -> dict[str, Any]:
+    path = _fallback_session_path()
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def _save_fallback(data: dict[str, Any]) -> None:
+    path = _fallback_session_path()
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    os.chmod(path, 0o600)
+
+
+def get_session_token(profile: str) -> str | None:
+    try:
+        token = keyring.get_password(SERVICE_NAME, profile)
+        if token:
+            return token
+    except Exception:
+        pass
+
+    data = _load_fallback()
+    value = data.get(profile, {})
+    token = value.get("token")
+    return str(token) if token else None
+
+
+def get_refresh_token(profile: str) -> str | None:
+    data = _load_fallback()
+    value = data.get(profile, {})
+    if not isinstance(value, dict):
+        return None
+    token = value.get("refreshToken")
+    return str(token) if token else None
+
+
+def set_session_token(
+    profile: str,
+    token: str,
+    *,
+    refresh_token: str | None = None,
+) -> None:
+    wrote_keyring = False
+    try:
+        keyring.set_password(SERVICE_NAME, profile, token)
+        wrote_keyring = True
+    except Exception:
+        wrote_keyring = False
+
+    # Always persist tokens in the fallback file so refreshToken survives
+    # even when the access token is stored in the OS keyring.
+    data = _load_fallback()
+    data.setdefault(profile, {})
+    if not isinstance(data[profile], dict):
+        data[profile] = {}
+    data[profile]["token"] = token
+    if refresh_token is not None:
+        data[profile]["refreshToken"] = refresh_token
+    if not wrote_keyring or refresh_token is not None:
+        _save_fallback(data)
+
+
+def clear_session_token(profile: str) -> None:
+    try:
+        keyring.delete_password(SERVICE_NAME, profile)
+    except Exception:
+        pass
+
+    data = _load_fallback()
+    if profile in data and isinstance(data[profile], dict):
+        data[profile].pop("token", None)
+        data[profile].pop("refreshToken", None)
+    _save_fallback(data)

caraer_cli/utils.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_structured_file(path: str) -> dict[str, Any]:
+    content = Path(path).read_text(encoding="utf-8")
+    suffix = Path(path).suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        payload = yaml.safe_load(content)
+    else:
+        payload = json.loads(content)
+    if not isinstance(payload, dict):
+        raise ValueError("Input file must contain a JSON/YAML object at the root.")
+    return payload
+
+
+def parse_patch(value: str) -> dict[str, Any]:
+    parsed = json.loads(value)
+    if not isinstance(parsed, dict):
+        raise ValueError("Patch must be a JSON object.")
+    return parsed
+
+
+def deep_merge(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in patch.items():
+        if (
+            key in merged
+            and isinstance(merged[key], dict)
+            and isinstance(value, dict)
+        ):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged

caraer_cli/wizard/__init__.py

@@ -0,0 +1,9 @@
+"""Interactive CLI wizards."""
+
+__all__ = ["run_public_app_wizard"]
+
+
+def run_public_app_wizard(*args, **kwargs):
+    from caraer_cli.wizard.public_app import run_public_app_wizard as _run
+
+    return _run(*args, **kwargs)