xcorecli 2.1.0__tar.gz → 2.3.0__tar.gz

{xcorecli-2.1.0 → xcorecli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xcorecli
-Version: 2.1.0
+Version: 2.3.0
 Summary: CLI for xcore — configuration, plugins, monitoring
 Requires-Python: >=3.12
 Requires-Dist: alembic>=1.18.0

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/commands/health.md

@@ -39,5 +39,7 @@ xcli services
 
 If `health` reports errors:
 1. Check the logs: `make logs`
-2. Validate configuration: `xcli config validate`
+2. Check your marketplace credentials aren't the issue: `xcli config show`
+   (there's no dedicated `integration.yaml` validator — it's checked
+   automatically whenever `xcli manager start` reads it)
 3. Restart services: `make restart`

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/commands/init.md

@@ -12,11 +12,19 @@ xcli init my-project
 
 ### Database Options
 
-The initialization wizard supports several database backends with pre-configured URL templates:
-- **SQLite**: `sqlite:///./data/xcore.db` (Default)
-- **PostgreSQL**: `postgresql://user:pass@localhost:5432/db`
-- **MySQL**: `mysql+pymysql://user:pass@localhost:3306/db`
-- **MariaDB**: `mysql+pymysql://user:pass@localhost:3306/db`
+The initialization wizard supports several database backends with
+pre-configured URL templates — always the **async** driver variant, never
+a sync one, since `xcore` is async end-to-end:
+
+- **SQLite** (default): `sqlite+aiosqlite:///./xcore.db`
+- **PostgreSQL**: `postgresql+asyncpg://user:pass@localhost:5432/dbname`
+- **MySQL**: `mysql+aiomysql://user:pass@localhost:3306/dbname`
+- **MariaDB**: `mysql+aiomysql://user:pass@localhost:3306/dbname`
+
+`--db-url` overrides the template entirely if you need a different
+host/user/password — but keep the `+aiosqlite`/`+asyncpg`/`+aiomysql`
+driver suffix; a plain `postgresql://`/`mysql://` URL uses a sync driver
+that doesn't work with this framework's async SQLAlchemy engine.
 
 ### Generated Structure
 

xcorecli-2.3.0/docs/config/index.md

@@ -0,0 +1,48 @@
+# CLI Configuration
+
+The `config` command group stores the two credentials `xcorecli` needs to
+talk to the marketplace: an **API key** (`xdk_...`, authorizes downloads)
+and a **signing key** (verifies the HMAC signature of every ZIP before
+extraction). It does **not** manage `integration.yaml` or any other
+project-level setting — see [Getting started → Configuration](../getting-started/configuration.md)
+for that.
+
+!!! tip "Prefer `xcli login`"
+    `xcli login` (device-code flow, opens a browser) fetches and stores
+    **both** credentials in one step, without ever printing them to the
+    terminal. `config set` below is the manual fallback — useful in a
+    non-interactive environment (CI, a container) where opening a browser
+    isn't possible.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `xcli config set <key> <value>` | Store a credential — `key` must be `api-key` or `signing-key`. |
+| `xcli config show` | Print whether each credential is set (values are masked, never shown in full). |
+
+## Setting credentials manually
+
+```bash
+xcli config set api-key xdk_...
+xcli config set signing-key <your-signing-secret>
+```
+
+Both are written to `~/.xcli/config.json` — the same file `xcli login`
+writes to, so mixing the two approaches (login once, then manually rotate
+one key later) is safe.
+
+## Checking status
+
+```bash
+xcli config show
+```
+
+```
+api-key:     set
+signing-key: not set
+```
+
+Nothing else is configurable through this command group — there is no
+`get`/`validate` sub-command, and no arbitrary `key.path value` form; `key`
+is restricted to exactly `api-key` or `signing-key`.

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/getting-started/configuration.md

@@ -67,4 +67,4 @@ observability:
 
 ## Validation
 
-`xcorecli` validates this file upon startup to ensure all required fields are present and correctly typed. Use `xcli config validate` to check your configuration manually.
+`xcorecli` validates this file upon startup to ensure all required fields are present and correctly typed — there is no separate command to check it manually ahead of time; `xcli manager start` (or any command that touches the running project) is itself the validation step. This is unrelated to [`xcli config`](../config/index.md), which only stores your marketplace API/signing keys, not `integration.yaml` settings.

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/getting-started/install.md

@@ -13,7 +13,7 @@ Getting started with `xcorecli` is straightforward. The project uses [Poetry](ht
 ### 1. Clone the Repository
 
 ```bash
-git clone https://github.com/your-repo/xcorecli.git
+git clone https://github.com/xcore-team/xcoreCli.git
 cd xcorecli
 ```
 

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/index.md

@@ -17,7 +17,7 @@
 ## Quick Start Overview
 
 ```bash title="Quick Install"
-git clone https://github.com/your-repo/xcorecli.git
+git clone https://github.com/xcore-team/xcoreCli.git
 cd xcorecli
 make install
 ```

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/migration/index.md

@@ -23,6 +23,15 @@ xcli migration init
 
 This creates the `alembic/` directory, configuration files, and scans for initial models.
 
+!!! tip "Custom directory name"
+    Pass `--dir my_migrations` to use a different directory name. The chosen
+    name is persisted to `migration.directory` in `integration.yaml`, so every
+    other `migration` command (`revision`, `upgrade`, `downgrade`, `current`,
+    `history`, `heads`, `stamp`) picks it up automatically — no need to repeat
+    `--dir` on each call. To rename an already-initialized project, use
+    `xcli migration rename <new_name>` instead of moving the folder by hand —
+    it also updates `alembic.ini` and `integration.yaml` for you.
+
 ## Safety & Backups
 
 Before performing dangerous operations, `xcorecli` can automatically backup your database.
@@ -99,5 +108,13 @@ Check which migrations have been applied.
 xcli migration history
 ```
 
+See the database's current revision, or where the migration chain's
+unapplied heads are:
+
+```bash
+xcli migration current   # what revision the DB is actually stamped at
+xcli migration heads     # latest revision(s) defined in the migration scripts
+```
+
 !!! tip "Stamping"
     Use `xcli migration stamp <id>` to mark the database at a specific revision without running the actual migration scripts.

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/plugin/install.md

@@ -32,14 +32,38 @@ To see all available versions for a plugin:
 xcli plugin versions name-of-plugin
 ```
 
-## Installing from Git or URL
+## Installing from Git or a Local Zip
 
-You can install plugins directly from a Git repository or a hosted `.zip` file.
+You can install plugins directly from a Git repository or a `.zip` file
+instead of the marketplace — neither one goes through HMAC verification,
+that's marketplace-only, so run `xcli plugin health` afterward (see below).
 
 ```bash title="Git Install"
 xcli plugin install my-plugin --source git --url https://github.com/user/plugin.git
 ```
 
+```bash title="Zip Install"
+xcli plugin install my-plugin --source zip --url ./path/to/plugin.zip
+```
+
+`--url` is required for both `git` and `zip` — omitting it fails fast
+rather than falling back to the marketplace.
+
+## Reinstalling
+
+```bash
+xcli plugin install name-of-plugin --force     # overwrite an existing install
+```
+
+Without `--force`, installing over an already-installed plugin (same name)
+is refused with a one-line message telling you to add the flag.
+
+!!! bug "`--no-deps` currently has no effect"
+    The flag is accepted (`install --no-deps`) but the installer never
+    reads it — confirmed in `xcli/plugin/install_commands.py`: dependencies
+    install the same way whether or not you pass it. Not documented as
+    working here on purpose; treat it as reserved for now.
+
 ## Management Commands
 
 ### Detailed Info

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/plugin/marketplace.md

@@ -1,7 +1,8 @@
 # Plugin Marketplace
 
-Discover plugins available on the marketplace before installing them — all
-three commands here are read-only and public, no credentials required.
+Discover plugins available on the marketplace before installing them.
+`browse`/`search`/`info` below are read-only and public, no credentials
+required; `mine` is the one exception (see below).
 
 ## Browse All
 
@@ -30,6 +31,20 @@ published versions.
 xcli plugin marketplace info name-of-plugin
 ```
 
+## Your Plugins
+
+`browse`/`search` above only ever show **public** plugins — unauthenticated
+requests, by design. To also see your own **private** plugins, use `mine`
+instead, which sends your API key:
+
+```bash title="Your plugins"
+xcli plugin marketplace mine
+```
+
+Needs the same API key as installing does — see
+[Authentication](../getting-started/auth.md). `xcli login`'s personal key
+works here even without a project-scoped key for any specific plugin.
+
 ## What's not here
 
 Rating a plugin (`POST /plugins/{slug}/ratings`) requires a full user

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/plugin/security.md

@@ -29,6 +29,35 @@ For a comprehensive check of all plugins (including manifest validation and AST
 xcli plugin health
 ```
 
+## Validating Manifests
+
+Beyond signature checks, `validate` checks the plugin manifest itself
+(`plugin.yaml` structure, required fields) and can track its **IPC
+surface** — the actions and events a plugin exposes to others — across
+versions:
+
+```bash title="Validate a plugin"
+xcli plugin security validate my-plugin
+```
+
+Without a path, it scans every plugin found via `integration.yaml`
+instead of just one:
+
+```bash
+xcli plugin security validate
+```
+
+```bash title="Track breaking IPC changes"
+xcli plugin security validate my-plugin --save            # snapshot today's IPC surface
+xcli plugin security validate my-plugin --check-breaking   # diff against that snapshot
+```
+
+`--save` writes the current IPC action/event schemas to a snapshot file
+(default `.xcore/schemas.json`, override with `--schema-file`); a later
+`--check-breaking` run reports anything removed or changed since — useful
+in CI to catch an accidental breaking change to a plugin's public IPC
+contract before it ships.
+
 ## Strict Mode
 
 Enable `strict_trusted` in your configuration to refuse any plugin that is not properly signed.

{xcorecli-2.1.0 → xcorecli-2.3.0}/docs/reference.md

@@ -12,6 +12,15 @@ A comprehensive list of all commands available in `xcorecli`.
 - `xcli services`: Show status and details of all system services (local
   runtime — not the marketplace catalog, see `xcli service` below).
 
+## `config`  Credentials
+
+- `config set <api-key|signing-key> <value>`: Store one credential in
+  `~/.xcli/config.json` — the manual alternative to `xcli login` above.
+- `config show`: Print whether each credential is set (masked).
+
+Only these two keys exist — no arbitrary `integration.yaml` settings live
+here, see [Configuration](getting-started/configuration.md) for that file.
+
 ## `manager`  Administration
 
 - `manager start`: Start the FastAPI server (uvicorn).
@@ -50,10 +59,19 @@ A comprehensive list of all commands available in `xcorecli`.
 - `marketplace browse`: List published plugins (`--sort newest|downloads|rating`).
 - `marketplace search`: Search by name or description.
 - `marketplace info`: Pre-install details, including published versions.
+- `marketplace mine`: List *your* plugins — public and private alike (needs
+  an API key; `browse`/`search`/`info` above are public, no credentials).
 
 No `rate` command — rating requires a full user session (JWT), not an API
 key; rate plugins from the XCoreHub dashboard.
 
+### `plugin security`  Signing & validation
+- `security sign`: HMAC-sign a plugin (`plugin.sig`).
+- `security verify`: Verify a plugin's signature.
+- `security validate`: Validate plugin manifest(s); `--check-breaking`
+  diffs IPC actions/events against a saved schema snapshot, `--save`
+  updates that snapshot.
+
 ### `plugin update`  Maintenance
 - `update check`: Check for new versions.
 - `update apply`: Apply updates (--all, --dry-run).
@@ -62,7 +80,21 @@ key; rate plugins from the XCoreHub dashboard.
 - `runtime load`: Activate a plugin.
 - `runtime unload`: Deactivate a plugin.
 - `runtime reload`: Restart a plugin.
+- `runtime reload-all`: Restart every active plugin at once.
 - `runtime status`: Show active plugins.
+- `runtime call`: Invoke a plugin action directly (`--payload '{"k": "v"}'`).
+
+## `sandbox`  Isolated Execution
+
+Run a plugin in isolation and inspect its declared resource/network/
+filesystem policy — none of these require the plugin to already be loaded
+by a running instance.
+
+- `sandbox run`: Launch a plugin sandboxed, keep it running (Ctrl+C to stop).
+- `sandbox call`: Start sandboxed, call one action, print the result, stop.
+- `sandbox limits`: Show resource limits from the manifest.
+- `sandbox network`: Show the declared network policy.
+- `sandbox fs`: Show the declared filesystem policy.
 
 ## `service`  Marketplace Extensions
 
@@ -104,4 +136,7 @@ confused with `xcli services`/`xcli manager services` (local runtime).
 - `migration revision`: Create a new migration.
 - `migration upgrade`: Apply migrations (--backup).
 - `migration downgrade`: Rollback migrations.
+- `migration current`: Show the database's current revision.
+- `migration heads`: Show the migration chain's latest defined revision(s).
+- `migration stamp`: Mark the DB at a revision without running scripts.
 - `migration history`: Show migration list.

xcorecli-2.3.0/docs/sandbox/index.md

@@ -0,0 +1,86 @@
+# Plugin Sandboxing
+
+The Sandbox provides a secure execution environment for third-party or untrusted plugins, ensuring they cannot compromise the host system.
+
+## Resource Isolation
+
+Sandboxed plugins are restricted in their resource consumption to prevent "noisy neighbor" issues or intentional Denial of Service.
+
+### Limits Configuration
+
+You can define default limits in `integration.yaml`:
+
+```yaml
+security:
+  rate_limit_default:
+    calls: 200        # Max IPC calls
+    period_seconds: 60 # Per minute
+```
+
+## AST-Based Whitelisting
+
+The core of the sandbox is an AST (Abstract Syntax Tree) analyzer that scans the plugin's code before execution.
+
+- **Whitelisted**: Only modules listed in `security.allowed_imports` can be imported.
+- **Blacklisted**: Modules in `security.forbidden_imports` (like `os` or `subprocess`) are explicitly blocked.
+
+!!! danger "Sandbox Bypass"
+    Attempting to bypass the sandbox via reflection or other advanced Python techniques is monitored and will result in the plugin being immediately unloaded.
+
+## Managing the Sandbox
+
+Use the `sandbox` command group to run a plugin in isolation and inspect the
+policy declared in its manifest — none of these require the plugin to
+already be loaded by a running `xcore` instance, unlike `xcli plugin
+runtime`.
+
+### Run
+
+Launch a plugin in an isolated sandbox process and keep it running until
+you interrupt it (Ctrl+C):
+
+```bash
+xcli sandbox run my-sandboxed-plugin
+```
+
+### Call
+
+Start the sandbox, invoke a single action, print the result, then stop —
+useful for testing one IPC action without keeping the process alive:
+
+```bash
+xcli sandbox call my-sandboxed-plugin send_email --payload '{"to": "user@example.com"}'
+```
+
+!!! warning "Sandboxed plugins only"
+    `sandbox call` refuses a plugin whose `execution_mode` isn't
+    `sandboxed` — use `xcli plugin runtime call` for a `trusted` plugin
+    instead.
+
+### Limits
+
+Show the resource limits declared in the plugin's manifest (timeout, max
+memory/disk, rate limit) — read-only, no process started:
+
+```bash
+xcli sandbox limits my-sandboxed-plugin
+```
+
+### Network
+
+Show the plugin's declared network policy (`network:` in `plugin.yaml`):
+
+```bash
+xcli sandbox network my-sandboxed-plugin
+```
+
+### Filesystem
+
+Show the plugin's declared filesystem policy (`filesystem:` in `plugin.yaml`):
+
+```bash
+xcli sandbox fs my-sandboxed-plugin
+```
+
+!!! info "Trusted vs. Sandboxed"
+    By default, plugins are treated as **Sandboxed**. You must explicitly mark a plugin as **Trusted** in its `plugin.yaml` (and usually sign it) to run it with full permissions.

{xcorecli-2.1.0 → xcorecli-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xcorecli"
-version = "2.1.0"
+version = "2.3.0"
 description = "CLI for xcore — configuration, plugins, monitoring"
 readme = "README.md"
 requires-python = ">=3.12"

{xcorecli-2.1.0 → xcorecli-2.3.0}/uv.lock

@@ -782,7 +782,7 @@ wheels = [
 
 [[package]]
 name = "xcorecli"
-version = "2.0.0"
+version = "2.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },