caraer-cli 0.1.2__py3-none-any.whl

caraer_cli/commands/auth.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import getpass
+import time
+import webbrowser
+
+import typer
+
+from caraer_cli.api import auth as auth_api
+from caraer_cli.context import AppContext
+from caraer_cli.errors import ApiError, AuthError
+from caraer_cli.formatters.output import print_data, print_success, print_warning
+from caraer_cli.state import session as session_store
+
+app = typer.Typer(help="Authentication commands.", no_args_is_help=True)
+
+
+def _store_tokens(profile: str, data: dict) -> str:
+    """Extract and persist access (+ optional refresh) token from an auth payload."""
+    token = None
+    refresh_token = data.get("refreshToken")
+    token_obj = data.get("token")
+    if isinstance(token_obj, dict):
+        token = token_obj.get("token")
+    if not token:
+        token = data.get("accessToken")
+    if not token:
+        raise typer.BadParameter("Login succeeded but no token was returned.")
+    session_store.set_session_token(
+        profile,
+        str(token),
+        refresh_token=str(refresh_token) if refresh_token else None,
+    )
+    return str(token)
+
+
+@app.command("login")
+def login(
+    ctx: typer.Context,
+    email: str | None = typer.Option(
+        None,
+        "--email",
+        help="Account email (password login). Omit for device-code browser login.",
+    ),
+    password: str = typer.Option(
+        None,
+        "--password",
+        prompt=False,
+        hide_input=True,
+        help="Password (prompted securely if --email is set and password omitted).",
+    ),
+    device: bool = typer.Option(
+        False,
+        "--device",
+        help="Force device-code login (default when --email is omitted).",
+    ),
+) -> None:
+    """Log in and store a session token for the active profile.
+
+    Defaults to device-code / browser login. Pass --email for password login (CI).
+    """
+    app_ctx: AppContext = ctx.obj
+    client = app_ctx.api_client()
+
+    use_device = device or not email
+    if use_device and email:
+        print_warning("Ignoring --email/--password; using device-code login.")
+
+    if use_device:
+        try:
+            start = auth_api.device_start(client).get("data") or {}
+        except ApiError as exc:
+            if email:
+                print_warning(
+                    f"Device login unavailable ({exc}). Falling back to password login."
+                )
+                use_device = False
+            else:
+                raise typer.BadParameter(
+                    "Device login is unavailable on this backend. "
+                    "Use 'caraer auth login --email you@example.com'."
+                ) from exc
+        else:
+            device_code = str(start.get("deviceCode") or "")
+            user_code = str(start.get("userCode") or "")
+            verification_uri = str(
+                start.get("verificationUriComplete")
+                or start.get("verificationUri")
+                or ""
+            )
+            interval = float(start.get("interval") or 5)
+            expires_in = float(start.get("expiresIn") or 600)
+            if not device_code or not user_code:
+                raise typer.BadParameter("Device start response missing codes.")
+            print_success(f"Device code: {user_code}")
+            if verification_uri:
+                print_success(f"Open: {verification_uri}")
+                try:
+                    webbrowser.open(verification_uri)
+                except Exception:  # noqa: BLE001
+                    pass
+            print_success("Waiting for approval in the browser…")
+            deadline = time.monotonic() + expires_in
+            while time.monotonic() < deadline:
+                time.sleep(max(1.0, interval))
+                poll = auth_api.device_poll(client, device_code).get("data") or {}
+                status = str(poll.get("status") or "").lower()
+                if status == "approved":
+                    _store_tokens(app_ctx.profile_name, poll)
+                    print_success(f"Logged in for profile '{app_ctx.profile_name}'.")
+                    _print_next_steps(app_ctx)
+                    return
+                if status in {"expired", "denied"}:
+                    raise typer.BadParameter(f"Device login {status}.")
+            raise typer.BadParameter("Device login timed out.")
+
+    from caraer_cli.wizard.prompts import require_text
+
+    email = require_text(email, "Email", flag="--email")
+    resolved_password = password or getpass.getpass("Password: ")
+    response = auth_api.login(client, email, resolved_password)
+    data = response.get("data", {})
+    _store_tokens(app_ctx.profile_name, data if isinstance(data, dict) else {})
+    print_success(f"Logged in for profile '{app_ctx.profile_name}'.")
+    _print_next_steps(app_ctx)
+
+
+def _print_next_steps(app_ctx: AppContext) -> None:
+    if app_ctx.profile.company_uuid:
+        print_success(
+            f"Profile company is '{app_ctx.profile.company_uuid}'. "
+            "If API calls fail with Company not found, run 'caraer company clear' "
+            "then 'caraer company list'."
+        )
+    else:
+        print_success("Next: run 'caraer company list' and 'caraer company select <uuid>'.")
+
+
+@app.command("logout")
+def logout(ctx: typer.Context) -> None:
+    """Log out and clear the stored session token for the active profile."""
+    app_ctx: AppContext = ctx.obj
+    client = app_ctx.api_client()
+    try:
+        auth_api.logout(client)
+    except AuthError:
+        pass
+    session_store.clear_session_token(app_ctx.profile_name)
+    print_success(f"Logged out profile '{app_ctx.profile_name}'.")
+
+
+@app.command("me")
+def me(ctx: typer.Context) -> None:
+    """Show the currently authenticated user."""
+    app_ctx: AppContext = ctx.obj
+    client = app_ctx.api_client()
+    response = auth_api.me(client)
+    print_data(response.get("data"), app_ctx.output)
+
+
+@app.command("refresh")
+def refresh_token(ctx: typer.Context) -> None:
+    """Refresh the access token using the stored refresh token."""
+    app_ctx: AppContext = ctx.obj
+    refresh = session_store.get_refresh_token(app_ctx.profile_name)
+    if not refresh:
+        raise typer.BadParameter(
+            "No refresh token stored. Run 'caraer auth login' (device flow) first."
+        )
+    client = app_ctx.api_client()
+    data = auth_api.refresh(client, refresh).get("data") or {}
+    _store_tokens(app_ctx.profile_name, data if isinstance(data, dict) else {})
+    print_success(f"Refreshed session for profile '{app_ctx.profile_name}'.")

caraer_cli/commands/company.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import typer
+
+from caraer_cli.api import auth as auth_api
+from caraer_cli.completion_callbacks import complete_company
+from caraer_cli.context import AppContext
+from caraer_cli.formatters.output import print_data, print_success
+from caraer_cli.state.config import save_config
+
+app = typer.Typer(help="Company context commands.", no_args_is_help=True)
+
+
+@app.command("list")
+def list_companies(ctx: typer.Context) -> None:
+    """List companies available to the authenticated user."""
+    app_ctx: AppContext = ctx.obj
+    client = app_ctx.api_client()
+    response = auth_api.companies(client)
+    companies = response.get("data")
+    if isinstance(companies, list):
+        minimal = []
+        for company in companies:
+            if not isinstance(company, dict):
+                continue
+            minimal.append(
+                {
+                    "name": company.get("name"),
+                    "uuid": company.get("uuid"),
+                }
+            )
+        print_data(minimal, app_ctx.output)
+        return
+    print_data([], app_ctx.output)
+
+
+@app.command("select")
+def select_company(
+    ctx: typer.Context,
+    company_uuid: str | None = typer.Argument(
+        None,
+        help="Company UUID to use for API calls. Prompted if omitted.",
+        autocompletion=complete_company,
+    ),
+) -> None:
+    """Select a company for the active profile."""
+    from caraer_cli.wizard.prompts import require_text
+
+    app_ctx: AppContext = ctx.obj
+    company_uuid = require_text(company_uuid, "Company UUID", flag="company-uuid")
+    cfg = app_ctx.config
+    profile = cfg.profiles[app_ctx.profile_name]
+    profile.company_uuid = company_uuid
+    profile.sandbox_uuid = None  # sandbox is always scoped to its owner company
+    save_config(cfg)
+    print_success(f"Selected company '{company_uuid}' for profile '{app_ctx.profile_name}'.")
+
+
+@app.command("clear")
+def clear_company(ctx: typer.Context) -> None:
+    """Remove the selected company from the active profile."""
+    app_ctx: AppContext = ctx.obj
+    cfg = app_ctx.config
+    profile = cfg.profiles[app_ctx.profile_name]
+    profile.company_uuid = None
+    profile.sandbox_uuid = None
+    save_config(cfg)
+    print_success(f"Cleared company for profile '{app_ctx.profile_name}'.")

caraer_cli/commands/installation.py

@@ -0,0 +1,182 @@
+"""Installation runtime commands: state, secrets, jobs, connections."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from caraer_cli.context import AppContext
+from caraer_cli.formatters.output import print_data, print_success
+
+state_app = typer.Typer(help="Installation state (key/value store).", no_args_is_help=True)
+secrets_app = typer.Typer(help="Installation secrets.", no_args_is_help=True)
+jobs_app = typer.Typer(help="Installation background jobs.", no_args_is_help=True)
+connections_app = typer.Typer(help="External OAuth connections.", no_args_is_help=True)
+
+
+def _require_app_uuid(ctx: typer.Context) -> tuple[AppContext, str]:
+    from caraer_cli.app_sync import resolve_app_root
+    from caraer_cli.project.schema import load_workspace
+
+    app_ctx: AppContext = ctx.obj
+    root = resolve_app_root(app_file=app_ctx.profile.app_file)
+    config = load_workspace(root)
+    if not config.appUuid:
+        raise ValueError("App has no remote UUID. Run 'caraer apps select' or 'caraer apps push'.")
+    return app_ctx, config.appUuid
+
+
+@state_app.command("get")
+def state_get(
+    ctx: typer.Context,
+    key: str | None = typer.Argument(None, help="Optional state key (omit for full map)."),
+) -> None:
+    """Get installation state (all keys, or one key)."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    client = app_ctx.api_client()
+    if key:
+        response = installation_api.get_state_key(client, app_uuid, key)
+    else:
+        response = installation_api.get_state(client, app_uuid)
+    print_data(response.get("data"), app_ctx.output)
+
+
+@state_app.command("set")
+def state_set(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help="State key."),
+    value: str = typer.Argument(..., help="JSON or plain string value."),
+) -> None:
+    """Set an installation state key."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    try:
+        parsed: Any = json.loads(value)
+    except json.JSONDecodeError:
+        parsed = value
+    response = installation_api.put_state_key(app_ctx.api_client(), app_uuid, key, parsed)
+    print_success(f"Set state key '{key}'")
+    print_data(response.get("data"), app_ctx.output)
+
+
+@state_app.command("delete")
+def state_delete(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help="State key to delete."),
+) -> None:
+    """Delete an installation state key."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    response = installation_api.delete_state_key(app_ctx.api_client(), app_uuid, key)
+    print_success(f"Deleted state key '{key}'")
+    print_data(response.get("data"), app_ctx.output)
+
+
+@secrets_app.command("list")
+def secrets_list(ctx: typer.Context) -> None:
+    """List installation secret names (values are never returned)."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    response = installation_api.list_secrets(app_ctx.api_client(), app_uuid)
+    print_data(response.get("data"), app_ctx.output)
+
+
+@secrets_app.command("set")
+def secrets_set(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Secret name."),
+    value: str = typer.Argument(..., help="Secret value."),
+) -> None:
+    """Create or update an installation secret."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    response = installation_api.put_secret(app_ctx.api_client(), app_uuid, name, value)
+    print_success(f"Set secret '{name}'")
+    print_data(response.get("data"), app_ctx.output)
+
+
+@secrets_app.command("delete")
+def secrets_delete(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Secret name to delete."),
+) -> None:
+    """Delete an installation secret."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    response = installation_api.delete_secret(app_ctx.api_client(), app_uuid, name)
+    print_success(f"Deleted secret '{name}'")
+    print_data(response.get("data"), app_ctx.output)
+
+
+@jobs_app.command("enqueue")
+def jobs_enqueue(
+    ctx: typer.Context,
+    function_name: str = typer.Argument(..., help="Function name to invoke."),
+    payload: str = typer.Option("{}", "--payload", help="JSON payload object."),
+    delay_seconds: float = typer.Option(0, "--delay", help="Delay before invoke (seconds)."),
+) -> None:
+    """Enqueue a background job for a function."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    try:
+        body = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid --payload JSON: {exc}") from exc
+    if not isinstance(body, dict):
+        raise ValueError("--payload must be a JSON object")
+    response = installation_api.enqueue_job(
+        app_ctx.api_client(),
+        app_uuid,
+        function_name=function_name,
+        payload=body,
+        delay_seconds=delay_seconds,
+    )
+    print_success("Job enqueued")
+    print_data(response.get("data"), app_ctx.output)
+
+
+@jobs_app.command("status")
+def jobs_status(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Job id from enqueue."),
+) -> None:
+    """Get status for an installation job."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    response = installation_api.get_job(app_ctx.api_client(), app_uuid, job_id)
+    print_data(response.get("data"), app_ctx.output)
+
+
+@connections_app.command("list")
+def connections_list(ctx: typer.Context) -> None:
+    """List external OAuth connection status for this app installation."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    response = installation_api.list_connections(app_ctx.api_client(), app_uuid)
+    print_data(response.get("data"), app_ctx.output)
+
+
+@connections_app.command("revoke")
+def connections_revoke(
+    ctx: typer.Context,
+    provider: str = typer.Argument(..., help="Provider name to revoke."),
+) -> None:
+    """Revoke an external OAuth connection."""
+    from caraer_cli.api import installation as installation_api
+
+    app_ctx, app_uuid = _require_app_uuid(ctx)
+    response = installation_api.delete_connection(app_ctx.api_client(), app_uuid, provider)
+    print_success(f"Revoked connection '{provider}'")
+    print_data(response.get("data"), app_ctx.output)

caraer_cli/commands/profile.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+import typer
+
+from caraer_cli.completion_callbacks import complete_output_format, complete_profile
+from caraer_cli.context import AppContext
+from caraer_cli.formatters.output import print_data, print_success
+from caraer_cli.state.config import ProfileConfig, profile_as_dict, save_config
+
+app = typer.Typer(help="Manage CLI config profiles.", no_args_is_help=True)
+
+
+def _require_profile(app_ctx: AppContext, name: str) -> ProfileConfig:
+    if name not in app_ctx.config.profiles:
+        raise typer.BadParameter(f"Unknown profile '{name}'.")
+    return app_ctx.config.profiles[name]
+
+
+def _resolve_target(app_ctx: AppContext, name: str | None) -> tuple[str, ProfileConfig]:
+    target = (name or app_ctx.profile_name).strip()
+    return target, _require_profile(app_ctx, target)
+
+
+@app.command("list")
+def list_profiles(ctx: typer.Context) -> None:
+    """List all profiles (marks the active one)."""
+    app_ctx: AppContext = ctx.obj
+    rows = []
+    for name, profile in app_ctx.config.profiles.items():
+        row = profile_as_dict(profile)
+        row["name"] = name
+        row["active"] = name == app_ctx.config.active_profile
+        rows.append(row)
+    print_data(rows, app_ctx.output)
+
+
+@app.command("show")
+def show_profile(
+    ctx: typer.Context,
+    name: str | None = typer.Argument(
+        None,
+        help="Profile name (defaults to the active profile).",
+        autocompletion=complete_profile,
+    ),
+) -> None:
+    """Show one profile's settings."""
+    app_ctx: AppContext = ctx.obj
+    target, profile = _resolve_target(app_ctx, name)
+    output = profile_as_dict(profile)
+    output["name"] = target
+    output["active"] = target == app_ctx.config.active_profile
+    print_data(output, app_ctx.output)
+
+
+@app.command("current")
+def current_profile(ctx: typer.Context) -> None:
+    """Show the active profile name and settings."""
+    app_ctx: AppContext = ctx.obj
+    output = profile_as_dict(app_ctx.profile)
+    output["name"] = app_ctx.profile_name
+    output["active"] = True
+    print_data(output, app_ctx.output)
+
+
+@app.command("use")
+def use_profile(
+    ctx: typer.Context,
+    name: str | None = typer.Argument(
+        None,
+        help="Profile name to activate. Prompted if omitted.",
+        autocompletion=complete_profile,
+    ),
+) -> None:
+    """Switch the active profile."""
+    from caraer_cli.wizard.prompts import require_text
+
+    app_ctx: AppContext = ctx.obj
+    name = require_text(name, "Profile name", flag="name")
+    _require_profile(app_ctx, name)
+    app_ctx.config.active_profile = name
+    save_config(app_ctx.config)
+    print_success(f"Set active profile to '{name}'.")
+
+
+@app.command("create")
+def create_profile(
+    ctx: typer.Context,
+    name: str | None = typer.Argument(None, help="New profile name. Prompted if omitted."),
+    base_url: str | None = typer.Option(
+        None,
+        "--base-url",
+        help="API base URL (required unless --from is set; prompted if omitted).",
+    ),
+    from_profile: str | None = typer.Option(
+        None,
+        "--from",
+        help="Copy settings from an existing profile.",
+        autocompletion=complete_profile,
+    ),
+    use: bool = typer.Option(False, "--use", help="Make this the active profile."),
+) -> None:
+    """Create a new profile, optionally copied from an existing one."""
+    from caraer_cli.wizard.prompts import require_text
+
+    app_ctx: AppContext = ctx.obj
+    name = require_text(name, "Profile name", flag="name")
+    if name in app_ctx.config.profiles:
+        raise typer.BadParameter(f"Profile '{name}' already exists.")
+
+    if from_profile:
+        source = _require_profile(app_ctx, from_profile)
+        profile = deepcopy(source)
+        if base_url:
+            profile.base_url = base_url
+    else:
+        base_url = require_text(base_url, "API base URL", flag="--base-url")
+        profile = ProfileConfig(base_url=base_url)
+
+    app_ctx.config.profiles[name] = profile
+    if use:
+        app_ctx.config.active_profile = name
+    save_config(app_ctx.config)
+    message = f"Created profile '{name}'."
+    if use:
+        message += " Set as active."
+    print_success(message)
+
+
+@app.command("delete")
+def delete_profile(
+    ctx: typer.Context,
+    name: str | None = typer.Argument(
+        None,
+        help="Profile name to delete. Prompted if omitted.",
+        autocompletion=complete_profile,
+    ),
+    force: bool = typer.Option(False, "--force", help="Allow deleting the active profile."),
+) -> None:
+    """Delete a profile."""
+    from caraer_cli.wizard.prompts import require_text
+
+    app_ctx: AppContext = ctx.obj
+    name = require_text(name, "Profile name", flag="name")
+    _require_profile(app_ctx, name)
+    if len(app_ctx.config.profiles) <= 1:
+        raise typer.BadParameter("Cannot delete the last remaining profile.")
+    if name == app_ctx.config.active_profile and not force:
+        raise typer.BadParameter(
+            f"'{name}' is the active profile. Switch first, or pass --force."
+        )
+
+    del app_ctx.config.profiles[name]
+    if app_ctx.config.active_profile == name:
+        app_ctx.config.active_profile = next(iter(app_ctx.config.profiles.keys()))
+    save_config(app_ctx.config)
+    print_success(f"Deleted profile '{name}'.")
+
+
+@app.command("set")
+def set_profile(
+    ctx: typer.Context,
+    name: str | None = typer.Argument(
+        None,
+        help="Profile to update (defaults to the active profile).",
+        autocompletion=complete_profile,
+    ),
+    base_url: str | None = typer.Option(None, "--base-url", help="API base URL."),
+    company_uuid: str | None = typer.Option(None, "--company-uuid", help="Selected company UUID."),
+    app_uuid: str | None = typer.Option(None, "--app-uuid", help="Selected remote app UUID."),
+    app_file: str | None = typer.Option(None, "--app-file", help="Selected local app file path."),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        help="Default output format: table|json|yaml.",
+        autocompletion=complete_output_format,
+    ),
+    timeout_seconds: float | None = typer.Option(
+        None,
+        "--timeout-seconds",
+        help="HTTP timeout in seconds.",
+    ),
+    verify_ssl: bool | None = typer.Option(
+        None,
+        "--verify-ssl/--no-verify-ssl",
+        help="Verify TLS certificates.",
+    ),
+    clear_company: bool = typer.Option(False, "--clear-company", help="Clear company_uuid."),
+    clear_app: bool = typer.Option(False, "--clear-app", help="Clear app_uuid."),
+    clear_app_file: bool = typer.Option(False, "--clear-app-file", help="Clear app_file."),
+) -> None:
+    """Update fields on a profile."""
+    app_ctx: AppContext = ctx.obj
+    target, profile = _resolve_target(app_ctx, name)
+
+    updates: list[str] = []
+    if base_url is not None:
+        profile.base_url = base_url
+        updates.append("base_url")
+    if company_uuid is not None:
+        profile.company_uuid = company_uuid.strip() or None
+        updates.append("company_uuid")
+    if app_uuid is not None:
+        profile.app_uuid = app_uuid.strip() or None
+        updates.append("app_uuid")
+    if app_file is not None:
+        profile.app_file = app_file.strip() or None
+        updates.append("app_file")
+    if output is not None:
+        normalized = output.strip().lower()
+        if normalized not in {"table", "json", "yaml"}:
+            raise typer.BadParameter("output must be one of: table, json, yaml.")
+        profile.output = normalized
+        updates.append("output")
+    if timeout_seconds is not None:
+        if timeout_seconds <= 0:
+            raise typer.BadParameter("timeout-seconds must be greater than 0.")
+        profile.timeout_seconds = timeout_seconds
+        updates.append("timeout_seconds")
+    if verify_ssl is not None:
+        profile.verify_ssl = verify_ssl
+        updates.append("verify_ssl")
+    if clear_company:
+        profile.company_uuid = None
+        updates.append("company_uuid")
+    if clear_app:
+        profile.app_uuid = None
+        updates.append("app_uuid")
+    if clear_app_file:
+        profile.app_file = None
+        updates.append("app_file")
+
+    if not updates:
+        raise typer.BadParameter("No fields to update. Pass at least one option.")
+
+    save_config(app_ctx.config)
+    unique = ", ".join(dict.fromkeys(updates))
+    print_success(f"Updated {unique} on profile '{target}'.")