caraer-cli 0.1.2__py3-none-any.whl

caraer_cli/commands/publish.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import typer
+
+from caraer_cli.api import apps as apps_api
+from caraer_cli.context import AppContext
+from caraer_cli.formatters.output import print_data, print_success
+from caraer_cli.resolve import resolve_app_uuid
+
+app = typer.Typer(help="Publishing commands for app creators.", no_args_is_help=True)
+
+
+@app.command("submit")
+def submit(
+    ctx: typer.Context,
+    app_uuid: str | None = typer.Option(None, "--app", "--app-uuid", help="App UUID (defaults to selected app)."),
+) -> None:
+    """Submit the selected app for marketplace review."""
+    app_ctx: AppContext = ctx.obj
+    resolved = resolve_app_uuid(app_ctx, app_uuid)
+    response = apps_api.submit_for_review(app_ctx.api_client(), resolved)
+    print_success("Submitted app for review.")
+    print_data(response.get("data"), app_ctx.output)
+
+
+@app.command("status")
+def status(
+    ctx: typer.Context,
+    app_uuid: str | None = typer.Option(None, "--app", "--app-uuid", help="App UUID (defaults to selected app)."),
+) -> None:
+    """Show publish state and creator-visible feedback for the selected app."""
+    app_ctx: AppContext = ctx.obj
+    resolved = resolve_app_uuid(app_ctx, app_uuid)
+    response = apps_api.get_public_app(app_ctx.api_client(), resolved)
+    data = response.get("data", {})
+    publish_data = data.get("appPublish", {})
+    if isinstance(publish_data, dict):
+        # reviewerNotes are SUPER_ADMIN-only; drop defensively if ever present.
+        publish_data = {k: v for k, v in publish_data.items() if k != "reviewerNotes"}
+    print_data(publish_data, app_ctx.output)

caraer_cli/commands/sandbox.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import typer
+
+from caraer_cli.api import sandboxes as sandboxes_api
+from caraer_cli.context import AppContext
+from caraer_cli.formatters.output import print_data, print_success
+from caraer_cli.state.config import load_config, save_config
+
+app = typer.Typer(help="Developer sandbox commands.", no_args_is_help=True)
+
+
+@app.command("create")
+def create_sandbox(
+    ctx: typer.Context,
+    name: str | None = typer.Option(None, "--name", help="Sandbox name (slug). Prompted if omitted."),
+    label: str = typer.Option("", "--label", help="Display label (defaults to --name)."),
+) -> None:
+    """Clone the selected company's Neo4j database into a developer sandbox."""
+    from caraer_cli.wizard.prompts import require_text
+
+    app_ctx: AppContext = ctx.obj
+    if not app_ctx.profile.company_uuid:
+        raise ValueError("Select a company first with 'caraer company select <uuid>'.")
+    name = require_text(name, "Sandbox name", flag="--name")
+    response = sandboxes_api.create_sandbox(
+        app_ctx.api_client(),
+        {"name": name, "label": label or name},
+    )
+    data = response.get("data") or {}
+    print_success(
+        "Created sandbox DB clone for the selected company. "
+        "Activate with 'caraer sandbox use <sandbox-uuid>' "
+        "(sends X-Caraer-Sandbox-Uuid; company identity stays the owner)."
+    )
+    print_data(data, app_ctx.output)
+
+
+@app.command("list")
+def list_sandboxes(ctx: typer.Context) -> None:
+    """List sandboxes for the owner company (ignores active sandbox override)."""
+    app_ctx: AppContext = ctx.obj
+    if not app_ctx.profile.company_uuid:
+        raise ValueError("Select a company first with 'caraer company select <uuid>'.")
+    response = sandboxes_api.list_sandboxes(app_ctx.api_client())
+    print_data(response.get("data"), app_ctx.output)
+
+
+@app.command("use")
+def use_sandbox(
+    ctx: typer.Context,
+    sandbox_uuid: str | None = typer.Argument(
+        None,
+        help="Sandbox UUID (DeveloperSandbox uuid). Prompted if omitted.",
+    ),
+) -> None:
+    """Activate a sandbox via X-Caraer-Sandbox-Uuid (overrides Neo4j databaseid only)."""
+    from caraer_cli.wizard.prompts import require_text
+
+    app_ctx: AppContext = ctx.obj
+    if not app_ctx.profile.company_uuid:
+        raise ValueError("Select the owner company first with 'caraer company select <uuid>'.")
+    sandbox_uuid = require_text(sandbox_uuid, "Sandbox UUID", flag="sandbox-uuid")
+    response = sandboxes_api.get_sandbox(app_ctx.api_client(), sandbox_uuid)
+    data = response.get("data") or {}
+    owner = data.get("ownerCompanyUuid")
+    if owner and str(owner) != str(app_ctx.profile.company_uuid):
+        raise ValueError(
+            f"Sandbox owner {owner} does not match selected company "
+            f"{app_ctx.profile.company_uuid}. Select the owner company first."
+        )
+    cfg = load_config()
+    profile = cfg.profiles[app_ctx.profile_name]
+    profile.sandbox_uuid = str(data.get("uuid") or sandbox_uuid)
+    save_config(cfg)
+    print_success(
+        f"Using sandbox {profile.sandbox_uuid} "
+        f"(company {profile.company_uuid}, db override). "
+        "API calls will send X-Caraer-Sandbox-Uuid."
+    )
+    print_data(data, app_ctx.output)
+
+
+@app.command("clear")
+def clear_sandbox(ctx: typer.Context) -> None:
+    """Stop sending X-Caraer-Sandbox-Uuid (return to the owner company database)."""
+    app_ctx: AppContext = ctx.obj
+    cfg = load_config()
+    profile = cfg.profiles[app_ctx.profile_name]
+    profile.sandbox_uuid = None
+    save_config(cfg)
+    print_success("Cleared sandbox override; requests use the selected company database.")

caraer_cli/commands/skill.py

@@ -0,0 +1,165 @@
+"""Install Cursor Agent skills shipped with caraer-cli."""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+import typer
+
+from caraer_cli.formatters.output import print_error, print_success, print_warning
+
+app = typer.Typer(help="Cursor / AI IDE skill helpers.", no_args_is_help=True)
+
+SKILL_ID = "caraer-apps"
+
+
+def _repo_skill_dir() -> Path | None:
+    """Dev checkout: <repo>/skills/caraer-apps next to the package."""
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "skills" / SKILL_ID
+        if candidate.is_dir() and (candidate / "SKILL.md").is_file():
+            return candidate
+    return None
+
+
+def _copy_packaged_skill(dest: Path) -> bool:
+    try:
+        root = resources.files("caraer_cli") / "skills" / SKILL_ID
+    except (TypeError, FileNotFoundError, ModuleNotFoundError):
+        return False
+    try:
+        if not root.is_dir():
+            return False
+        skill_md = root / "SKILL.md"
+        if not skill_md.is_file():
+            return False
+        with resources.as_file(root) as path:
+            shutil.copytree(path, dest)
+        return True
+    except (FileNotFoundError, OSError, NotADirectoryError):
+        return False
+
+
+def resolve_skill_source() -> Path:
+    """Return a real filesystem path for read-only inspection (path command)."""
+    repo = _repo_skill_dir()
+    if repo is not None:
+        return repo
+    try:
+        root = resources.files("caraer_cli") / "skills" / SKILL_ID
+        with resources.as_file(root) as path:
+            if path.is_dir() and (path / "SKILL.md").is_file():
+                # as_file may be temporary; prefer reporting packaged logical path
+                return Path(path)
+    except (TypeError, FileNotFoundError, ModuleNotFoundError, OSError):
+        pass
+    raise FileNotFoundError(
+        f"Skill '{SKILL_ID}' not found. Reinstall caraer-cli or clone "
+        "Caraer-HQ/caraer-cli."
+    )
+
+
+def default_user_skills_dir() -> Path:
+    return Path.home() / ".cursor" / "skills"
+
+
+def project_skills_dir(cwd: Path | None = None) -> Path:
+    return (cwd or Path.cwd()) / ".cursor" / "skills"
+
+
+def install_skill(
+    *,
+    project: bool = False,
+    target_root: Path | None = None,
+    force: bool = False,
+) -> Path:
+    root = target_root or (
+        project_skills_dir() if project else default_user_skills_dir()
+    )
+    dest = root / SKILL_ID
+    if dest.exists():
+        if not force:
+            raise FileExistsError(
+                f"{dest} already exists. Pass --force to replace it."
+            )
+        if dest.is_dir():
+            shutil.rmtree(dest)
+        else:
+            dest.unlink()
+    root.mkdir(parents=True, exist_ok=True)
+
+    if _copy_packaged_skill(dest):
+        return dest
+
+    repo = _repo_skill_dir()
+    if repo is not None:
+        shutil.copytree(repo, dest)
+        return dest
+
+    raise FileNotFoundError(
+        f"Skill '{SKILL_ID}' not found. Reinstall caraer-cli or clone "
+        "Caraer-HQ/caraer-cli."
+    )
+
+
+@app.command("install")
+def install_cmd(
+    project: bool = typer.Option(
+        False,
+        "--project",
+        help="Install into ./.cursor/skills (current directory) instead of ~/.cursor/skills.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Replace an existing caraer-apps skill directory.",
+    ),
+    path: Path | None = typer.Option(
+        None,
+        "--path",
+        help="Custom skills root directory (contains caraer-apps/).",
+    ),
+) -> None:
+    """Install the Caraer Apps Cursor skill for AI IDEs."""
+    try:
+        dest = install_skill(project=project, target_root=path, force=force)
+    except FileExistsError as exc:
+        print_error(str(exc))
+        raise typer.Exit(1) from exc
+    except FileNotFoundError as exc:
+        print_error(str(exc))
+        raise typer.Exit(1) from exc
+
+    print_success(f"Installed skill → {dest}")
+    print_warning(
+        "Restart Cursor or start a new agent chat so the skill is discovered."
+    )
+
+
+@app.command("path")
+def path_cmd() -> None:
+    """Print the on-disk source path for the shipped caraer-apps skill."""
+    try:
+        source = resolve_skill_source()
+    except FileNotFoundError as exc:
+        print_error(str(exc))
+        raise typer.Exit(1) from exc
+    typer.echo(str(source))
+
+
+@app.command("list")
+def list_cmd() -> None:
+    """Show install locations and whether caraer-apps is present."""
+    try:
+        source = resolve_skill_source()
+        typer.echo(f"source\t{source}")
+    except FileNotFoundError as exc:
+        typer.echo(f"source\tMISSING ({exc})")
+
+    user = default_user_skills_dir() / SKILL_ID
+    project = project_skills_dir() / SKILL_ID
+    typer.echo(f"user\t{user}\t{'yes' if user.is_dir() else 'no'}")
+    typer.echo(f"project\t{project}\t{'yes' if project.is_dir() else 'no'}")

caraer_cli/commands/webhooks.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import typer
+
+from caraer_cli.api import webhooks as webhook_api
+from caraer_cli.context import AppContext
+from caraer_cli.formatters.output import print_data
+from caraer_cli.resolve import resolve_app_uuid
+
+app = typer.Typer(help="Webhook discovery and test helpers.", no_args_is_help=True)
+
+
+@app.command("formats")
+def formats(
+    ctx: typer.Context,
+    app_uuid: str | None = typer.Option(
+        None, "--app", "--app-uuid", help="App UUID (defaults to selected app)."
+    ),
+) -> None:
+    """List available webhook payload formats."""
+    app_ctx: AppContext = ctx.obj
+    resolved = resolve_app_uuid(app_ctx, app_uuid)
+    response = webhook_api.get_formats(app_ctx.api_client(), resolved)
+    print_data(response.get("data", response), app_ctx.output)
+
+
+@app.command("events")
+def events(
+    ctx: typer.Context,
+    app_uuid: str | None = typer.Option(
+        None, "--app", "--app-uuid", help="App UUID (defaults to selected app)."
+    ),
+) -> None:
+    """List available webhook record events."""
+    app_ctx: AppContext = ctx.obj
+    resolved = resolve_app_uuid(app_ctx, app_uuid)
+    response = webhook_api.get_events(app_ctx.api_client(), resolved)
+    print_data(response.get("data", response), app_ctx.output)
+
+
+@app.command("test")
+def test(
+    ctx: typer.Context,
+    webhook_uuid: str | None = typer.Argument(
+        None,
+        help="Remote webhook UUID. Prompted if omitted.",
+    ),
+    record: str | None = typer.Option(
+        None,
+        "--record",
+        help="Record UUID to include in the test payload. Prompted if omitted.",
+    ),
+    event: str = typer.Option("created", "--event", help="Record event type, e.g. created|updated."),
+    app_uuid: str | None = typer.Option(
+        None, "--app", "--app-uuid", help="App UUID (defaults to selected app)."
+    ),
+) -> None:
+    """Fire a test webhook delivery for a record event."""
+    from caraer_cli.wizard.prompts import require_text
+
+    app_ctx: AppContext = ctx.obj
+    webhook_uuid = require_text(webhook_uuid, "Webhook UUID", flag="webhook-uuid")
+    record = require_text(record, "Record UUID", flag="--record")
+    resolved = resolve_app_uuid(app_ctx, app_uuid)
+    response = webhook_api.test_webhook(
+        app_ctx.api_client(), resolved, webhook_uuid, record, event
+    )
+    print_data(response.get("data", response), app_ctx.output)

caraer_cli/completion.py

@@ -0,0 +1,77 @@
+"""Shell completion helpers and installers for the Caraer CLI."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Iterable
+
+from typer._completion_shared import get_completion_script, install as typer_install
+
+SUPPORTED_SHELLS = ("zsh", "bash", "fish", "powershell", "pwsh")
+
+
+def detect_shell(explicit: str | None = None) -> str:
+    """Resolve a shell name, preferring an explicit value then common fallbacks."""
+    if explicit:
+        shell = explicit.strip().lower()
+        if shell not in SUPPORTED_SHELLS:
+            raise ValueError(
+                f"Unsupported shell '{explicit}'. Use one of: {', '.join(SUPPORTED_SHELLS)}"
+            )
+        return shell
+
+    try:
+        import shellingham
+
+        name, _cmd = shellingham.detect_shell()
+        if name:
+            return str(name).lower()
+    except Exception:
+        pass
+
+    env_shell = (os.environ.get("SHELL") or "").strip()
+    if env_shell:
+        return Path(env_shell).name.lower()
+
+    raise ValueError(
+        "Could not detect your shell. Pass --shell zsh|bash|fish to the installer."
+    )
+
+
+def completion_env_var(prog_name: str = "caraer") -> str:
+    return "_{}_COMPLETE".format(prog_name.replace("-", "_").upper())
+
+
+def show_completion_script(*, shell: str | None = None, prog_name: str = "caraer") -> str:
+    resolved = detect_shell(shell)
+    return get_completion_script(
+        prog_name=prog_name,
+        complete_var=completion_env_var(prog_name),
+        shell=resolved,
+    )
+
+
+def install_completion(*, shell: str | None = None, prog_name: str = "caraer") -> tuple[str, Path]:
+    resolved = detect_shell(shell)
+    installed_shell, path = typer_install(
+        shell=resolved,
+        prog_name=prog_name,
+        complete_var=completion_env_var(prog_name),
+    )
+    return installed_shell, Path(path)
+
+
+def _safe_startswith(value: str, incomplete: str) -> bool:
+    return value.lower().startswith((incomplete or "").lower())
+
+
+def complete_from_pairs(
+    pairs: Iterable[tuple[str, str]],
+    incomplete: str,
+) -> list[tuple[str, str]]:
+    return [
+        (value, help_text)
+        for value, help_text in pairs
+        if _safe_startswith(value, incomplete) or _safe_startswith(help_text, incomplete)
+    ]

caraer_cli/completion_callbacks.py

@@ -0,0 +1,162 @@
+"""Dynamic shell autocompletion callbacks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from caraer_cli.completion import complete_from_pairs
+from caraer_cli.local_app import discover_local_app_files, local_app_summary
+from caraer_cli.state.config import load_config
+
+
+def complete_profile(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    try:
+        cfg = load_config()
+    except Exception:
+        return []
+    pairs = [(name, profile.base_url) for name, profile in cfg.profiles.items()]
+    return complete_from_pairs(pairs, incomplete)
+
+
+def complete_output_format(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    return complete_from_pairs(
+        [("table", "Human-readable table"), ("json", "JSON"), ("yaml", "YAML")],
+        incomplete,
+    )
+
+
+def complete_local_app(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    try:
+        for path in discover_local_app_files():
+            try:
+                summary = local_app_summary(path)
+                label = summary.get("label") or summary.get("name") or path.name
+                pairs.append((str(path), str(label)))
+                # Also offer project/dir style selection when nested.
+                if path.parent.name == "app" and path.name.startswith("app.caraer."):
+                    project_root = path.parents[2] if len(path.parents) >= 3 else path.parent
+                    pairs.append((str(project_root), f"app: {label}"))
+            except Exception:
+                pairs.append((str(path), path.name))
+    except Exception:
+        return []
+    return complete_from_pairs(pairs, incomplete)
+
+
+def _completion_app_context() -> Any | None:
+    """Build a lightweight AppContext for completion-time API lookups."""
+    try:
+        from caraer_cli.context import AppContext
+        from caraer_cli.state.config import active_profile, load_config
+        from caraer_cli.state.session import get_session_token
+
+        cfg = load_config()
+        profile_name, profile_cfg = active_profile(cfg)
+        token = get_session_token(profile_name)
+        if not token:
+            return None
+        return AppContext(
+            config=cfg,
+            profile_name=profile_name,
+            profile=profile_cfg,
+            token=token,
+            output="json",
+            debug=False,
+        )
+    except Exception:
+        return None
+
+
+def complete_app_ref(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    """Complete remote app UUIDs and local app paths."""
+    results = complete_local_app(ctx, incomplete)
+    app_ctx = getattr(ctx, "obj", None) or _completion_app_context()
+    if app_ctx is None:
+        return results
+    try:
+        from caraer_cli.api import apps as apps_api
+
+        response = apps_api.list_apps(
+            app_ctx.api_client(),
+            app_type="my",
+            page=1,
+            limit=50,
+        )
+        rows = response.get("data") if isinstance(response.get("data"), list) else []
+        pairs: list[tuple[str, str]] = []
+        for row in rows:
+            if not isinstance(row, dict) or not row.get("uuid"):
+                continue
+            label = row.get("label") or row.get("name") or "app"
+            pairs.append((str(row["uuid"]), str(label)))
+        results.extend(complete_from_pairs(pairs, incomplete))
+    except Exception:
+        pass
+    return results
+
+
+def complete_company(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    app_ctx = getattr(ctx, "obj", None) or _completion_app_context()
+    if app_ctx is None:
+        return []
+    try:
+        from caraer_cli.api import auth as auth_api
+
+        response = auth_api.companies(app_ctx.api_client())
+        companies = response.get("data") if isinstance(response.get("data"), list) else []
+        pairs: list[tuple[str, str]] = []
+        for company in companies:
+            if not isinstance(company, dict) or not company.get("uuid"):
+                continue
+            pairs.append((str(company["uuid"]), str(company.get("name") or "company")))
+        return complete_from_pairs(pairs, incomplete)
+    except Exception:
+        return []
+
+
+def complete_runtime(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    return complete_from_pairs(
+        [("nodejs22", "Node.js 22"), ("python312", "Python 3.12")],
+        incomplete,
+    )
+
+
+def complete_auth_method(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    return complete_from_pairs(
+        [("OAUTH2", "OAuth 2.0"), ("API_KEY", "API key")],
+        incomplete,
+    )
+
+
+def complete_local_function(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    try:
+        from caraer_cli.app_sync import resolve_app_root
+        from caraer_cli.project.schema import load_workspace
+        from caraer_cli.project.sync import list_local_function_names
+        from caraer_cli.state.config import active_profile, load_config
+
+        cfg = load_config()
+        _, profile = active_profile(cfg)
+        root = resolve_app_root(app_file=profile.app_file)
+        config = load_workspace(root)
+        pairs = [(name, "local function") for name in list_local_function_names(root, config)]
+        return complete_from_pairs(pairs, incomplete)
+    except Exception:
+        return []
+
+
+def complete_app_list_type(ctx: typer.Context, incomplete: str) -> list[tuple[str, str]]:
+    return complete_from_pairs(
+        [
+            ("my", "Apps you created"),
+            ("private", "Private apps"),
+            ("public", "Public marketplace apps"),
+            ("native", "Native apps"),
+            ("local", "Local project files"),
+        ],
+        incomplete,
+    )
+

caraer_cli/context.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from caraer_cli.api.client import CaraerApiClient, RequestContext
+from caraer_cli.state import session as session_store
+from caraer_cli.state.config import CliConfig, ProfileConfig
+
+
+@dataclass
+class AppContext:
+    config: CliConfig
+    profile_name: str
+    profile: ProfileConfig
+    token: str | None
+    output: str
+    debug: bool
+
+    def api_client(self) -> CaraerApiClient:
+        profile_name = self.profile_name
+
+        def _persist(access: str, refresh: str | None) -> None:
+            session_store.set_session_token(
+                profile_name, access, refresh_token=refresh
+            )
+            self.token = access
+
+        return CaraerApiClient(
+            RequestContext(
+                base_url=self.profile.base_url,
+                token=self.token,
+                company_uuid=self.profile.company_uuid,
+                sandbox_uuid=self.profile.sandbox_uuid,
+                timeout_seconds=self.profile.timeout_seconds,
+                verify_ssl=self.profile.verify_ssl,
+                debug=self.debug,
+                profile_name=self.profile_name,
+                refresh_token=session_store.get_refresh_token(self.profile_name),
+                on_tokens_refreshed=_persist,
+            )
+        )