xcorecli 2.2.0__tar.gz → 2.3.0__tar.gz

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

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

{xcorecli-2.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.0 → xcorecli-2.3.0}/pyproject.toml

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

{xcorecli-2.2.0 → xcorecli-2.3.0}/xcli/migrations/cli.py

@@ -17,6 +17,7 @@ from xcli.migrations.runtime import (
     discover_models,
     get_backup_dir,
     get_database_url,
+    get_migration_dir,
     get_scan_paths,
     list_backups,
     parse_db_url,
@@ -24,6 +25,7 @@ from xcli.migrations.runtime import (
     render_discovery_summary,
     restore_database,
     run_alembic_command,
+    set_migration_dir,
 )
 
 _CTX = {"help_option_names": ["-h", "--help"]}
@@ -41,7 +43,7 @@ from pathlib import Path
 import sys
 
 from alembic import context
-from sqlalchemy import engine_from_config, pool
+from sqlalchemy import MetaData, engine_from_config, pool
 
 config = context.config
 ROOT = Path(config.config_file_name).resolve().parent if config.config_file_name else Path.cwd()
@@ -55,12 +57,47 @@ if config.config_file_name is not None:
 
 config.set_main_option("sqlalchemy.url", get_database_url())
 discovery = discover_models()
-target_metadata = discovery.target_metadata
+
+
+def _merge_metadata(entries: list[MetaData]) -> MetaData | None:
+    merged = MetaData()
+    seen: set[str] = set()
+    for entry in entries:
+        # `sorted_tables` respecte l'ordre des dépendances (une table est copiée après celles qu'elle référence).
+        for table in entry.sorted_tables:
+            key = table.key
+            if key in seen:
+                continue
+            seen.add(key)
+            table.to_metadata(merged)
+    # `MetaData` n'a pas de `__bool__` : un objet vide reste « vrai », c'est `tables` qu'il faut interroger.
+    return merged if merged.tables else None
+
+
+# Pilotes async de l'application → pilote synchrone équivalent DÉJÀ présent dans l'environnement. `aiosqlite` n'a
+# pas de « pilote » : le dialecte `sqlite` est déjà synchrone, d'où la chaîne vide.
+_ASYNC_TO_SYNC = {
+    "aiosqlite": "",
+    "asyncpg": "psycopg2",
+    "aiomysql": "pymysql",
+    "asyncmy": "pymysql",
+}
+
+
+def _sync_url(url: str) -> str:
+    for async_driver, sync_driver in _ASYNC_TO_SYNC.items():
+        if f"+{async_driver}:" in url:
+            # `sqlite` n'a pas de pilote : on retire le `+` plutôt que de laisser `sqlite+:` (plugin inexistant).
+            return url.replace(f"+{async_driver}:", f"+{sync_driver}:" if sync_driver else ":", 1)
+    return url
+
+
+target_metadata = _merge_metadata(discovery.target_metadata)
 
 
 def run_migrations_offline() -> None:
     context.configure(
-        url=get_database_url(),
+        url=_sync_url(get_database_url()),
         target_metadata=target_metadata,
         literal_binds=True,
         dialect_opts={"paramstyle": "named"},
@@ -73,7 +110,7 @@ def run_migrations_offline() -> None:
 
 def run_migrations_online() -> None:
     configuration = config.get_section(config.config_ini_section, {})
-    configuration["sqlalchemy.url"] = get_database_url()
+    configuration["sqlalchemy.url"] = _sync_url(get_database_url())
     connectable = engine_from_config(
         configuration,
         prefix="sqlalchemy.",
@@ -94,6 +131,7 @@ if context.is_offline_mode():
     run_migrations_offline()
 else:
     run_migrations_online()
+
 """
 
 _SCRIPT_TEMPLATE = '''\
@@ -165,6 +203,9 @@ datefmt = %H:%M:%S
 
 # ── Helpers ────────────────────────────────────────────────────
 
+_DIR_HELP = "Alembic directory (default: migration.directory in integration.yaml, else 'alembic')."
+
+
 def _alembic_dir(directory: str) -> Path:
     return (project_root() / directory).resolve()
 
@@ -199,10 +240,11 @@ def _do_backup(label: str = "") -> None:
 
 @app.command("init")
 def init(
-    directory: str = typer.Option("alembic", "--dir", help="Alembic directory to create."),
+    directory: Optional[str] = typer.Option(None, "--dir", help="Alembic directory to create. " + _DIR_HELP),
     force: bool = typer.Option(False, "--force", help="Overwrite generated files if they already exist."),
 ) -> None:
     """Create an Alembic workspace wired to integration.yaml and all discovered models."""
+    directory = directory or get_migration_dir()
     root = project_root()
     alembic_dir = _alembic_dir(directory)
     versions_dir = alembic_dir / "versions"
@@ -234,6 +276,9 @@ def init(
         encoding="utf-8",
     )
 
+    if get_migration_dir() != directory:
+        set_migration_dir(directory)
+
     db_info = parse_db_url(db_url)
 
     console.print(f"[green]✓[/green] Alembic initialized → [cyan]{alembic_dir}[/cyan]")
@@ -297,9 +342,10 @@ def revision(
         True, "--autogenerate/--empty",
         help="Generate operations from discovered models.",
     ),
-    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+    directory: Optional[str] = typer.Option(None, "--dir", help=_DIR_HELP),
 ) -> None:
     """Create a new Alembic revision from discovered models."""
+    directory = directory or get_migration_dir()
     _ensure_initialized(directory)
     with console.status("Scanning models..."):
         discovery = discover_models()
@@ -310,10 +356,11 @@ def revision(
 @app.command("upgrade")
 def upgrade(
     revision: str = typer.Argument("head", help="Target revision (head, +1, <id>)."),
-    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+    directory: Optional[str] = typer.Option(None, "--dir", help=_DIR_HELP),
     backup: bool = typer.Option(False, "--backup", "-b", help="Backup database before upgrading."),
 ) -> None:
     """Apply migrations up to the target revision."""
+    directory = directory or get_migration_dir()
     _ensure_initialized(directory)
     if backup:
         _do_backup("pre-upgrade")
@@ -323,10 +370,11 @@ def upgrade(
 @app.command("downgrade")
 def downgrade(
     revision: str = typer.Argument(..., help="Target revision (-1, base, <id>)."),
-    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+    directory: Optional[str] = typer.Option(None, "--dir", help=_DIR_HELP),
     backup: bool = typer.Option(True, "--backup/--no-backup", "-b", help="Backup database before downgrading."),
 ) -> None:
     """Rollback migrations to the target revision."""
+    directory = directory or get_migration_dir()
     _ensure_initialized(directory)
     if backup:
         _do_backup("pre-downgrade")
@@ -336,9 +384,10 @@ def downgrade(
 @app.command("current")
 def current(
     verbose: bool = typer.Option(False, "--verbose", "-v"),
-    directory: str = typer.Option("alembic", "--dir"),
+    directory: Optional[str] = typer.Option(None, "--dir", help=_DIR_HELP),
 ) -> None:
     """Show the current database revision."""
+    directory = directory or get_migration_dir()
     _ensure_initialized(directory)
     run_alembic_command(directory, lambda cfg: command.current(cfg, verbose=verbose))
 
@@ -346,9 +395,10 @@ def current(
 @app.command("history")
 def history(
     verbose: bool = typer.Option(False, "--verbose", "-v"),
-    directory: str = typer.Option("alembic", "--dir"),
+    directory: Optional[str] = typer.Option(None, "--dir", help=_DIR_HELP),
 ) -> None:
     """Show migration history."""
+    directory = directory or get_migration_dir()
     _ensure_initialized(directory)
     command.history(create_alembic_config(directory), verbose=verbose)
 
@@ -356,9 +406,10 @@ def history(
 @app.command("heads")
 def heads(
     verbose: bool = typer.Option(False, "--verbose", "-v"),
-    directory: str = typer.Option("alembic", "--dir"),
+    directory: Optional[str] = typer.Option(None, "--dir", help=_DIR_HELP),
 ) -> None:
     """Show migration heads."""
+    directory = directory or get_migration_dir()
     _ensure_initialized(directory)
     command.heads(create_alembic_config(directory), verbose=verbose)
 
@@ -366,13 +417,55 @@ def heads(
 @app.command("stamp")
 def stamp(
     revision: str = typer.Argument(..., help="Revision to stamp without running migrations."),
-    directory: str = typer.Option("alembic", "--dir"),
+    directory: Optional[str] = typer.Option(None, "--dir", help=_DIR_HELP),
 ) -> None:
     """Stamp the database at a revision without running migrations."""
+    directory = directory or get_migration_dir()
     _ensure_initialized(directory)
     run_alembic_command(directory, lambda cfg: command.stamp(cfg, revision))
 
 
+@app.command("rename")
+def rename_dir(
+    new_name: str = typer.Argument(..., help="New name for the Alembic directory."),
+    directory: Optional[str] = typer.Option(None, "--dir", help="Current directory name. " + _DIR_HELP),
+) -> None:
+    """Rename the Alembic directory and keep alembic.ini / integration.yaml in sync."""
+    directory = directory or get_migration_dir()
+    _ensure_initialized(directory)
+
+    root = project_root()
+    old_dir = _alembic_dir(directory)
+    new_dir = (root / new_name).resolve()
+
+    if new_dir.exists():
+        console.print(f"[red]Already exists:[/red] [cyan]{new_dir}[/cyan]")
+        raise typer.Exit(1)
+
+    old_dir.rename(new_dir)
+
+    ini_path = root / "alembic.ini"
+    ini_updated = False
+    if ini_path.exists():
+        text = ini_path.read_text(encoding="utf-8")
+        new_text = text.replace(f"script_location = {directory}", f"script_location = {new_name}", 1)
+        if new_text != text:
+            ini_path.write_text(new_text, encoding="utf-8")
+            ini_updated = True
+
+    set_migration_dir(new_name)
+
+    console.print(f"[green]✓[/green] Renamed [cyan]{directory}[/cyan] → [cyan]{new_name}[/cyan]")
+    if ini_updated:
+        console.print(f"[green]✓[/green] Updated [cyan]{ini_path}[/cyan]")
+    elif ini_path.exists():
+        console.print(
+            f"[yellow]⚠[/yellow] Could not find [dim]script_location = {directory}[/dim] in "
+            f"[cyan]{ini_path}[/cyan] — update it by hand."
+        )
+    console.print(f"[green]✓[/green] integration.yaml → [cyan]migration.directory: {new_name}[/cyan]")
+
+
 # ── Backup / Restore ───────────────────────────────────────────
 
 @app.command("backup")

{xcorecli-2.2.0 → xcorecli-2.3.0}/xcli/migrations/runtime.py

@@ -202,9 +202,38 @@ def get_backup_dir() -> Path:
     return p.resolve()
 
 
-def create_alembic_config(directory: str = "alembic") -> Config:
+def get_migration_dir() -> str:
+    """Name of the Alembic directory, persisted once by `xcli migration init`
+    (or `rename`) so every other command agrees on it without `--dir` having
+    to be repeated on each invocation."""
+    cfg = load_config()
+    return cfg.get("migration", {}).get("directory", "alembic")
+
+
+def set_migration_dir(name: str) -> None:
+    """Persist `migration.directory` in integration.yaml/json, backing up the
+    previous file first — mirrors the backup-then-rewrite convention used by
+    `xcli init upgrade` (xcli/init/upgrade.py)."""
+    path = require_config_path()
+    cfg = load_config()
+    cfg.setdefault("migration", {})["directory"] = name
+
+    bak = path.with_name(path.name + ".bak")
+    bak.write_text(path.read_text(encoding="utf-8"), encoding="utf-8")
+
+    if path.suffix.lower() == ".json":
+        import json
+        path.write_text(json.dumps(cfg, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    else:
+        path.write_text(
+            yaml.dump(cfg, default_flow_style=False, allow_unicode=True, sort_keys=False),
+            encoding="utf-8",
+        )
+
+
+def create_alembic_config(directory: str | None = None) -> Config:
     root = project_root()
-    alembic_dir = root / directory
+    alembic_dir = root / (directory or get_migration_dir())
     cfg = Config()
     cfg.set_main_option("script_location", str(alembic_dir))
     cfg.set_main_option("sqlalchemy.url", get_database_url())
@@ -533,8 +562,13 @@ def list_backups(backup_dir: Path | None = None) -> list[Path]:
 
 
 def _iter_python_files(scan_root: Path) -> Iterator[Path]:
+    # `_IGNORED_PARTS` only covers the literal defaults ("alembic", "migrations") —
+    # a project that renamed its migration directory (migration.directory /
+    # `xcli migration rename`) needs that name excluded too, or model discovery
+    # starts importing migration scripts as if they were app modules.
+    ignored = _IGNORED_PARTS | {get_migration_dir()}
     for path in scan_root.rglob("*.py"):
-        if any(part in _IGNORED_PARTS for part in path.parts):
+        if any(part in ignored for part in path.parts):
             continue
         yield path
 

xcorecli-2.2.0/docs/config/index.md

@@ -1,49 +0,0 @@
-# CLI Configuration
-
-The `config` command group allows you to manage the behavior of `xcorecli` itself and its interaction with the `xcore` project.
-
-## Commands Overview
-
-| Command | Description |
-|---------|-------------|
-| `show`  | Display the current merged configuration. |
-| `get`   | Retrieve a specific configuration value. |
-| `set`   | Update a configuration value. |
-| `validate` | Check `integration.yaml` for schema compliance. |
-
-## Managing Settings
-
-### Viewing Configuration
-
-To see your current setup, including defaults and overrides from `integration.yaml`:
-
-```bash
-xcli config show
-```
-
-### Updating Values
-
-You can modify settings directly from the CLI. These changes are typically applied to your local configuration or the project's `integration.yaml`.
-
-```bash title="Set Value"
-xcli config set app.debug true
-```
-
-!!! note "Layered Configuration"
-    `xcorecli` uses a layered approach:
-    1. Internal Defaults
-    2. `integration.yaml` (Project level)
-    3. Local CLI Config (User level)
-    4. Environment Variables
-
-## Runtime Configuration
-
-Some settings in the `runtime` section of `integration.yaml` can be adjusted without restarting the entire system, such as plugin reload intervals.
-
-```yaml
-plugins:
-  interval: 5 # Check for changes every 5 seconds
-```
-
-!!! info "Dynamic Updates"
-    Use `xcli manager services reload` to apply certain configuration changes on the fly.

xcorecli-2.2.0/docs/sandbox/index.md

@@ -1,43 +0,0 @@
-# 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 inspect the status of the isolation layer.
-
-```bash
-# View sandbox statistics
-xcli sandbox stats
-
-# Inspect a specific plugin's sandbox
-xcli sandbox inspect 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.