caraer-cli 0.1.2__tar.gz

caraer_cli-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Unit tests
+        run: pytest tests/unit -q
+      - name: Build wheel
+        run: |
+          pip install build
+          python -m build
+      - name: CLI help
+        run: caraer --help

caraer_cli-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - name: Require API_TOKEN secret
+        env:
+          API_TOKEN: ${{ secrets.API_TOKEN }}
+        run: |
+          if [ -z "$API_TOKEN" ]; then
+            echo "::error::Missing secrets.API_TOKEN. Add a PyPI API token (pypi-...) as repository or 'pypi' environment secret named API_TOKEN, then re-run."
+            exit 1
+          fi
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.API_TOKEN }}

caraer_cli-0.1.2/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+env/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+.cursor/
+*.swp
+
+# Local env / secrets (never commit)
+.env
+.env.*
+!.env.example
+
+# Local CLI state (never commit)
+.caraer/
+*.local.json
+*.local.yaml
+*.local.yml
+
+# Scratch apps created while developing the CLI itself (keep on disk, do not publish)
+/my_public_app/
+/my_public_app_*/
+/my_second_cli_public_app/
+/jan_heins_public_app/
+/caraer_ai/
+
+# Maintainer planning notes (not part of the public developer contract)
+/docs/internal/

caraer_cli-0.1.2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## 0.1.2
+
+- Cursor Agent Skill `caraer-apps` under `skills/caraer-apps`, installable via
+  `caraer skill install` / `caraer skill install --project`
+- JSON Schemas under `schemas/` for app / function / webhook / schedule /
+  inbound / lifecycle configs (IDE `$schema` + optional `caraer-cli[schemas]`)
+- `caraer apps typegen` writes `src/types/caraer.d.ts` (Node) or
+  `caraer_types.py` (Python) payload helpers
+- Example app `examples/webhook-inbox` (inbound catch → installation state)
+- Modular marketplace files: `src/app/settings/`, `pricing/`, `app-bars/`, `lifecycle/`
+  (merged into the manifest on push; split on pull). Scaffolds:
+  `apps add-setting|add-pricing-plan|add-app-bar|add-lifecycle-hook`
+- `apps validate` covers settings, pricing, app bars, and lifecycle hooks
+- `apps add-setting|pricing-plan|app-bar` use wizard prompts and append to
+  `app.caraer.yaml` by default (`--modular` for separate JSON files)
+- `apps init` always scaffolds all four lifecycle hooks + `on-*` functions
+- Function sync includes sidecar `sourceFiles` so multi-file handlers deploy correctly
+- Docs: [docs/app_lifecycle.md](docs/app_lifecycle.md); webhook-inbox includes all
+  lifecycle hooks (install/uninstall/rotate/update)
+- V2 local `apps dev` matches container contract: `POST /functions/{name}`,
+  `X-Caraer-Function` header, and `body.functionName` (legacy `POST /{name}` kept)
+- `apps dev` emulates installation state/secrets/jobs/connections + inbound routes;
+  `--invoke-schedule` fires a local schedule once
+- `apps deploy --wait/--no-wait` polls `runtimeStatus` (same as `push --deploy`)
+- `apps pull` aligns local `platformVersion`/`runtime` with remote and pulls
+  external OAuth providers
+- Installation commands: `apps state|secrets|jobs|connections`
+- `apps test` remote-invokes a function (or `--sample-only`); `apps rollback`
+  redeploys a prior READY build; `apps builds list|get`
+- `apps logs --all` fetches app-level V2 container logs
+- `apps validate` covers schedules, inbound routes, and OAuth providers
+- `apps push` / `pull` sync schedules, inbound routes, and OAuth providers
+  (in addition to manifest, functions, webhooks)
+- Local app definition is now **`src/app/app.caraer.yaml`** (legacy `app.caraer.json` still loads);
+  scaffolds include commented examples for scopes, settings, pricing, and app bars
+- App platform **V2** (`platformVersion: 2026.2`): one async container runtime per app;
+  `apps push --deploy` polls `runtimeStatus`; `apps status` shows runtime fields
+- Default scaffold is `2026.2`; use `--platform 2026.1` for legacy per-function Cloud Functions
+- `caraer apps migrate-v2` — opt-in in-place V1 → V2 migration with runtime polling
+- Collapsed local **project** into **app**: `caraer.json` replaces `caraer.project.json`;
+  opaque developer-project id lives in `.caraer/state.json`
+- Single sync pair: `caraer apps pull` / `caraer apps push` syncs manifest, functions,
+  webhooks, schedules, inbound, and OAuth providers
+- Removed top-level `webhooks`, `pricing`, `appbars`, and `functions` command groups
+  (edit files under `src/app/` instead)
+- Removed `caraer apps link` and `caraer apps watch` (use `select` / `push` instead)
+- Removed deprecated `caraer project` command group (use `caraer apps` instead)
+- Removed `caraer config` command group (use `caraer profile` instead)
+- Removed `caraer completion` command group; shell completion is installed by `scripts/install.sh`
+- Public packaging polish: LICENSE, SECURITY, CONTRIBUTING; example defaults to `2026.2`
+- Developer sandboxes clone the selected company Neo4j DB only (same company
+  identity; `X-Caraer-Sandbox-Uuid` overrides `databaseid`). Recreate sandboxes
+  after upgrading past the old clone-company model
+  (`caraer sandbox use` / `clear`)
+- `caraer apps add-function` / `add-webhook` / `add-schedule` / `add-inbound`
+  scaffold local function folders and integration-runtime JSON files
+- Missing required args/options prompt interactively (questionary) instead of
+  failing with Typer usage errors; non-TTY still fails clearly
+- `caraer apps logs` prints log lines below the summary table; `--follow`
+  streams only new entries; skips unreadable Cloud Audit protobuf dumps
+
+## 0.1.0
+
+- Standalone `caraer-cli` package extracted from backend `clients/python`
+- Existing app / webhook / function commands
+- `caraer project` local project workflow (`init`, `link`, `upload`, `pull`, `watch`, `status`)
+- Build/deploy/logs/dev commands wired to developer-project APIs
+- `caraer functions delete`
+- `caraer sandbox` commands
+- Example project under `examples/webhook-inbox`
+- CI workflow and `scripts/ci.sh`

caraer_cli-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+This repository is the Caraer developer CLI. External contributions may be
+limited; if you have a fix or improvement, open an issue or pull request and we
+will review it.
+
+## Setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+./scripts/install.sh
+```
+
+## Checks
+
+```bash
+./scripts/ci.sh
+# or: pytest tests/unit -q
+```
+
+## Guidelines
+
+- Keep the CLI thin: talk to Caraer REST APIs; do not require GCP credentials.
+- Treat `caraer.json` + `src/app/` as a stable public contract.
+- Prefer clear error messages over silent failures.
+- Do not commit local scratch apps, `.caraer/` state, or `.env` files.
+- Add unit tests for command/API behavior changes under `tests/unit/`.
+
+## Security
+
+Report vulnerabilities privately — see [SECURITY.md](SECURITY.md).

caraer_cli-0.1.2/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) Caraer / Loyall. All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of the
+Software, in whole or in part, is strictly prohibited except as expressly permitted
+in a written agreement with Caraer.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

caraer_cli-0.1.2/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: caraer-cli
+Version: 0.1.2
+Summary: Developer CLI for Caraer apps, webhooks, and serverless functions.
+Project-URL: Homepage, https://caraer.com
+Project-URL: Documentation, https://developer.caraer.com
+Author: Caraer
+License: Proprietary
+License-File: LICENSE
+Keywords: apps,caraer,cli,marketplace,serverless
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.2.1
+Requires-Dist: platformdirs>=4.2.2
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: questionary>=2.0.1
+Requires-Dist: rich>=13.7.1
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12.3
+Provides-Extra: dev
+Requires-Dist: build>=1.2.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.2; extra == 'dev'
+Provides-Extra: schemas
+Requires-Dist: jsonschema>=4.22.0; extra == 'schemas'
+Description-Content-Type: text/markdown
+
+# Caraer CLI
+
+Standalone developer CLI for Caraer app lifecycle management.
+
+Install and use this package independently of the Caraer backend. It talks to
+the Caraer API as a thin client — no GCP credentials are required on your machine.
+
+## Requirements
+
+- **Python 3.10+**
+- A Caraer account with access to a company that can create public apps
+
+## Install
+
+### From PyPI
+
+```bash
+pipx install caraer-cli
+# or: uv tool install caraer-cli
+# or: pip install caraer-cli
+```
+
+Publishing (maintainers): tag `v*` runs [`.github/workflows/publish.yml`](.github/workflows/publish.yml).
+Add a PyPI API token as the `API_TOKEN` secret on the GitHub `pypi` environment
+(or as a repository secret with the same name).
+
+### From source (development)
+
+```bash
+git clone <this-repo> caraer-cli
+cd caraer-cli
+python3 -m venv .venv
+source .venv/bin/activate
+./scripts/install.sh                 # pip install + shell tab completion
+# or: ./scripts/install.sh --shell zsh
+caraer --help
+```
+
+If install fails with `requires a different Python`, create the venv with
+`python3.10` / `python3.11` / `python3.12` explicitly.
+
+Tab completion is installed by `scripts/install.sh`. Restart the terminal afterward.
+
+## AI IDEs (Cursor skill)
+
+Ship an Agent Skill so Cursor (and similar IDEs) can scaffold and validate Caraer
+apps correctly:
+
+```bash
+caraer skill install              # ~/.cursor/skills/caraer-apps
+caraer skill install --project    # ./.cursor/skills/caraer-apps
+caraer skill list
+```
+
+Source of truth: [`skills/caraer-apps`](skills/caraer-apps). After install, start a
+new agent chat and ask it to create or edit a Caraer app.
+
+## Quick start
+
+```bash
+caraer auth login
+# or password/CI: caraer auth login --email you@example.com
+caraer company list
+caraer company select <company-uuid>
+caraer apps list
+caraer apps select <app-uuid>   # pulls the full app folder locally
+```
+
+Create a new local app and push everything in one step:
+
+```bash
+caraer apps init --label "My App"
+cd my_app
+# edit src/app/app.caraer.yaml, src/app/functions/, src/app/webhooks/
+caraer apps push --deploy       # prompts for version (> previous) + release notes
+caraer apps version             # live semver + recent builds
+caraer apps status
+caraer apps logs                # uses the only local function (or prompts)
+caraer apps logs --all          # V2 app container logs
+caraer apps dev                 # local server: POST /functions/<name>
+caraer apps test --record <uuid>
+caraer apps state get
+caraer apps secrets list
+caraer apps rollback            # redeploy prior READY build
+```
+
+New apps default to workspace `platformVersion: 2026.2` (App platform V2: one async
+container runtime per app). Use `caraer apps init --platform 2026.1` only for the
+legacy per-function Cloud Functions model. See [docs/platform_versioning.md](docs/platform_versioning.md).
+
+`apps push` syncs the full app: marketplace manifest (including pricing + app bars),
+functions, webhooks, schedules, inbound routes, and external OAuth providers.
+There is no separate upload command.
+
+Add local scaffolds inside an app folder:
+
+```bash
+caraer apps add-function my-action
+caraer apps add-webhook --topic record.created --function my-action
+caraer apps add-schedule renew-watch --function my-action --cron "0 0 */6 * * *"
+caraer apps add-inbound gmail-push --function my-action --auth SHARED_SECRET
+caraer apps add-setting          # wizard → appends to app.caraer.yaml
+caraer apps add-pricing-plan     # wizard → appends to app.caraer.yaml
+caraer apps add-app-bar          # wizard → appends to app.caraer.yaml
+caraer apps add-lifecycle-hook   # wizard → lifecycle/*.json + function
+caraer apps add-webhook --topic app.bar.triggered --mode HTTP --url https://example.com/hook
+```
+
+`add-setting` / `add-pricing-plan` / `add-app-bar` write into `app.caraer.yaml` by
+default (use `--modular` for separate JSON files). Lifecycle hooks stay under
+`src/app/lifecycle/` because they pair with function folders.
+
+Lifecycle hooks (`install` / `uninstall` / `rotate` / `update`) and matching
+`functions/on-*` folders are created automatically by `caraer apps init`.
+
+
+Only the **app creator company** (or super-admin) can push builds for an app.
+
+## Platform versions
+
+| CLI `platformVersion` | App platform | Notes |
+|-----------------------|--------------|-------|
+| `2026.2` (default) | V2 | One container per app; async deploy; poll `runtimeStatus` |
+| `2026.1` | V1 | One Cloud Function per serverless function (legacy) |
+
+Migrate an existing V1 app in place with:
+
+```bash
+caraer apps migrate-v2 [--runtime nodejs22|python312]
+```
+
+This provisions the shared container, keeps webhook delivery on legacy function URLs
+until `runtimeStatus=READY`, then updates local `caraer.json` to `2026.2`.
+
+## Command groups
+
+- `auth` / `company` / `profile` — session and profiles
+- `apps` — local folder lifecycle + full sync (`pull` / `push`), builds, logs, local dev
+- `webhooks` — formats, events, and test helpers
+- `publish` — submit / status for marketplace review
+- `sandbox` — clone the company Neo4j DB (same company; `X-Caraer-Sandbox-Uuid` overrides `databaseid`)
+
+## Local app layout
+
+```text
+my_app/
+  caraer.json                 # workspace metadata (platformVersion, appUuid, …)
+  src/app/
+    app.caraer.yaml           # identity, auth, OAuth, settings, pricing, app bars
+    lifecycle/*.json          # install|uninstall|rotate|update hooks
+    functions/<name>/         # function.caraer.json + entry source
+    webhooks/*.json           # one webhook definition per file
+    schedules/*.json          # cron → function (integration runtime)
+    inbound/*.json            # public inbound routes → function
+```
+
+`add-setting` / `add-pricing-plan` / `add-app-bar` append to `app.caraer.yaml`.
+Optional modular JSON files (`settings/`, `pricing/`, `app-bars/`) still merge on
+push when present (`--modular`). `apps init` always creates all four lifecycle
+hooks + `on-*` functions. See [docs/app_lifecycle.md](docs/app_lifecycle.md).
+
+See [`examples/webhook-inbox`](examples/webhook-inbox) for a minimal sample
+(inbound route, settings, lifecycle, app bar).
+
+## Profiles
+
+Config lives in the user config dir (`config.toml`). Defaults include `dev`,
+`staging`, and `prod`.
+
+```bash
+caraer profile list
+caraer profile use staging
+caraer profile set --base-url https://api.caraer.com --output json
+```
+
+Override the active profile for a single command with `--profile <name>`.
+
+For local API development against a running backend:
+
+```bash
+caraer profile set --base-url http://localhost:8080
+```
+
+## Developer sandboxes
+
+Create a Neo4j DB clone of the selected company, then activate it per request.
+Company identity stays the same; only the Neo4j `databaseid` is overridden:
+
+```bash
+caraer company select <owner-company-uuid>
+caraer sandbox create --name my-test
+caraer sandbox list
+caraer sandbox use <sandbox-uuid>   # same company; sends X-Caraer-Sandbox-Uuid
+# … test against the clone DB …
+caraer sandbox clear                # back to the company production database
+```
+
+Each company may have at most **3** active sandboxes. After a backend deploy that
+changed the sandbox model, recreate sandboxes (old clone-company sandboxes are invalid).
+
+Sandboxes isolate **Neo4j data only** — function runtime code is still shared with
+production. Prefer `caraer apps push --dry-run` to preview changes, and treat
+`--target sandbox` as a data sandbox, not a separate code environment.
+
+## Documentation
+
+- [Platform versioning](docs/platform_versioning.md) — V1 vs V2 runtime model
+- [Backend contract](docs/backend_contract.md) — REST endpoints used by the CLI
+- [Changelog](CHANGELOG.md)
+- [Security](SECURITY.md)
+- Cursor skill: [`skills/caraer-apps`](skills/caraer-apps) (`caraer skill install`)
+
+## Related
+
+- API / platform: Caraer backend
+- Docs site: https://developer.caraer.com
+- Example app: [`examples/webhook-inbox`](examples/webhook-inbox)
+
+## Development / CI
+
+```bash
+./scripts/ci.sh
+```
+
+GitHub Actions workflow: `.github/workflows/ci.yml`
+
+## License
+
+Proprietary — see [LICENSE](LICENSE).