sernixa-cli 0.1.1__tar.gz → 0.2.0__tar.gz

sernixa_cli-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: sernixa-cli
+Version: 0.2.0
+Summary: Official Sernixa CLI for policy-governed local AI agent actions
+Author: Sernixa Team
+License-Expression: MIT
+Project-URL: Homepage, https://sernixa.com
+Project-URL: Repository, https://github.com/abhishekdhull63/Sernixa.ai-Web
+Project-URL: Documentation, https://github.com/abhishekdhull63/Sernixa.ai-Web/tree/main/docs/cli.md
+Keywords: sernixa,cli,governance,agents,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: sernixa>=0.4.0
+Requires-Dist: sernixa-agent>=1.6.0
+Requires-Dist: typer>=0.12.0
+
+# Sernixa CLI
+
+The official terminal and local-agent integration for Sernixa governance. The CLI evaluates actions against the real Sernixa control plane, installs supported agent hooks and MCP configuration, launches safe local discovery, and exposes operational evidence without a dashboard-only workflow.
+
+## Install and set up
+
+```bash
+pip install --upgrade sernixa-cli
+sernixa auth login
+sernixa setup
+sernixa doctor
+```
+
+`sernixa setup` configures Claude Code, Claude Desktop, Codex, and Cursor, preserves unrelated entries, backs up changed files, registers the bounded `sernixa://` dashboard launcher, and reports host restart or hook-trust steps. Preview without changing files:
+
+```bash
+sernixa setup --dry-run
+sernixa setup --target codex --target cursor --json
+```
+
+For local repository development:
+
+```bash
+python3 -m venv .venv-cli
+source .venv-cli/bin/activate
+pip install -e packages/sernixa -e packages/sernixa-agent -e apps/cli
+```
+
+The CLI defaults to `https://api.sernixa.com`. Stored credentials use the platform user-config directory and mode `0600` on Unix. `SERNIXA_API_KEY` and `SERNIXA_BASE_URL` override the stored configuration for non-interactive use.
+
+## One-command Auto Discover
+
+```bash
+sernixa discover
+sernixa discover --json
+sernixa discover --job discjob_0123456789abcdef0123456789abcdef
+```
+
+The command validates auth, initializes the supported local agent when needed, passes the stored credential only through the one-shot child-process environment, enrolls the stable machine ID, creates or accepts a policy-scoped job for that machine, runs one sync/task cycle, and waits for the terminal job result. The credential is not printed or duplicated into a second token file.
+
+The Command Center opens the same flow through `sernixa://discover` after a direct user click and an OS/browser confirmation. The native URL accepts only the fixed discovery action and an optional validated job ID; it cannot carry commands, credentials, paths, or environment values. If the launcher is unavailable, the dashboard shows the exact fallback command.
+
+Discovery candidates are observations for review. Enrollment is inventory. An accepted agent sync is proof. No discovery result silently becomes a managed MCP server.
+
+## Codex, Claude, and Cursor
+
+Supported global targets:
+
+- `claude`: Claude Code `PreToolUse` exec-form hook in `~/.claude/settings.json`.
+- `claude-desktop`: real stdio MCP server in the OS-specific Claude Desktop configuration.
+- `codex`: current `PreToolUse` JSON or array-of-tables TOML hook in `~/.codex`. Hooks are effective by default unless `[features].hooks = false`; users still review/trust new non-managed hooks in Codex.
+- `cursor`: global MCP entry in `~/.cursor/mcp.json`, shared by Cursor IDE and CLI.
+
+Install or repair an individual integration:
+
+```bash
+sernixa hook install claude
+sernixa hook install claude-desktop
+sernixa hook install codex
+sernixa hook install cursor
+
+sernixa hook repair codex
+sernixa hook status --json
+```
+
+Claude Code and Codex hooks call `sernixa hook run <provider>` before tool execution. `allow` continues through normal host permissions and `deny` blocks. Claude Code maps `review` to its supported human prompt. Current Codex `PreToolUse` does not support an `ask` result, so Sernixa maps `review` to a fail-closed deny with an explicit human-review reason instead of returning a hook shape that Codex would ignore. An API/configuration failure exits with code `2`, which both hosts treat as blocking; there is no local allow fallback.
+
+Claude Desktop and Cursor run `sernixa mcp serve`. The stdio MCP server exposes three non-mutating tools:
+
+- `sernixa_policy_check`: evaluate one proposed action.
+- `sernixa_plan_check`: evaluate a declared multi-step plan.
+- `sernixa_identity`: validate auth and return non-secret principal metadata.
+
+MCP tools provide explicit model capabilities; the installed hooks are the local tool-call enforcement points.
+
+## Governance and execution
+
+```bash
+sernixa validate payload.json
+cat payload.json | sernixa validate --json
+sernixa validate --from-claude < claude-hook.json
+sernixa validate --from-codex < codex-hook.jsonl
+sernixa validate-plan --agent-type codex plan.json
+sernixa validate-many --output json policies/*.json
+sernixa exec --plan plan.json -- npm test
+sernixa codex-exec --plan codex-plan.json -- codex exec "fix lint"
+```
+
+Exit codes are stable:
+
+- `0`: success or policy allow
+- `1`: deny, review required, invalid evidence, or non-success terminal result
+- `2`: configuration, parsing, auth, network, or API failure
+
+`validate-plan` calls the canonical plan endpoint. `exec` and `codex-exec` run the child command only after every planned step is allowed and bound to its proof.
+
+## Audit, approvals, and Flight Recorder
+
+```bash
+sernixa events --limit 25
+sernixa events --type governance_agent_plan_evaluated --json
+
+sernixa approvals list
+sernixa approvals decide approval_123 approved --reason "Reviewed bounded deployment."
+sernixa approvals decide approval_456 rejected --reason "Production scope is too broad."
+
+sernixa flight verify
+sernixa flight verify --stream stream_123 --json
+sernixa flight collectors
+```
+
+These commands call the authenticated organization endpoints and inherit backend permissions and feature entitlements. `sernixa decisions` remains a backward-compatible alias for the pending approval queue. Replay is not claimed because the backend does not expose an authorized decision-replay endpoint.
+
+## Stable configuration overrides
+
+- `SERNIXA_CONFIG_FILE`
+- `SERNIXA_PLAN_SESSION_FILE`
+- `SERNIXA_CLAUDE_CONFIG_FILE`
+- `SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE`
+- `SERNIXA_CODEX_HOOKS_FILE`
+- `SERNIXA_CODEX_CONFIG_FILE`
+- `SERNIXA_CURSOR_CONFIG_FILE`
+
+Project-scoped Codex files are intentionally not modified by global setup. Invalid JSON or TOML fails closed with the exact path and a repair command. Existing files are backed up before material changes.

sernixa_cli-0.2.0/README.md

@@ -0,0 +1,124 @@
+# Sernixa CLI
+
+The official terminal and local-agent integration for Sernixa governance. The CLI evaluates actions against the real Sernixa control plane, installs supported agent hooks and MCP configuration, launches safe local discovery, and exposes operational evidence without a dashboard-only workflow.
+
+## Install and set up
+
+```bash
+pip install --upgrade sernixa-cli
+sernixa auth login
+sernixa setup
+sernixa doctor
+```
+
+`sernixa setup` configures Claude Code, Claude Desktop, Codex, and Cursor, preserves unrelated entries, backs up changed files, registers the bounded `sernixa://` dashboard launcher, and reports host restart or hook-trust steps. Preview without changing files:
+
+```bash
+sernixa setup --dry-run
+sernixa setup --target codex --target cursor --json
+```
+
+For local repository development:
+
+```bash
+python3 -m venv .venv-cli
+source .venv-cli/bin/activate
+pip install -e packages/sernixa -e packages/sernixa-agent -e apps/cli
+```
+
+The CLI defaults to `https://api.sernixa.com`. Stored credentials use the platform user-config directory and mode `0600` on Unix. `SERNIXA_API_KEY` and `SERNIXA_BASE_URL` override the stored configuration for non-interactive use.
+
+## One-command Auto Discover
+
+```bash
+sernixa discover
+sernixa discover --json
+sernixa discover --job discjob_0123456789abcdef0123456789abcdef
+```
+
+The command validates auth, initializes the supported local agent when needed, passes the stored credential only through the one-shot child-process environment, enrolls the stable machine ID, creates or accepts a policy-scoped job for that machine, runs one sync/task cycle, and waits for the terminal job result. The credential is not printed or duplicated into a second token file.
+
+The Command Center opens the same flow through `sernixa://discover` after a direct user click and an OS/browser confirmation. The native URL accepts only the fixed discovery action and an optional validated job ID; it cannot carry commands, credentials, paths, or environment values. If the launcher is unavailable, the dashboard shows the exact fallback command.
+
+Discovery candidates are observations for review. Enrollment is inventory. An accepted agent sync is proof. No discovery result silently becomes a managed MCP server.
+
+## Codex, Claude, and Cursor
+
+Supported global targets:
+
+- `claude`: Claude Code `PreToolUse` exec-form hook in `~/.claude/settings.json`.
+- `claude-desktop`: real stdio MCP server in the OS-specific Claude Desktop configuration.
+- `codex`: current `PreToolUse` JSON or array-of-tables TOML hook in `~/.codex`. Hooks are effective by default unless `[features].hooks = false`; users still review/trust new non-managed hooks in Codex.
+- `cursor`: global MCP entry in `~/.cursor/mcp.json`, shared by Cursor IDE and CLI.
+
+Install or repair an individual integration:
+
+```bash
+sernixa hook install claude
+sernixa hook install claude-desktop
+sernixa hook install codex
+sernixa hook install cursor
+
+sernixa hook repair codex
+sernixa hook status --json
+```
+
+Claude Code and Codex hooks call `sernixa hook run <provider>` before tool execution. `allow` continues through normal host permissions and `deny` blocks. Claude Code maps `review` to its supported human prompt. Current Codex `PreToolUse` does not support an `ask` result, so Sernixa maps `review` to a fail-closed deny with an explicit human-review reason instead of returning a hook shape that Codex would ignore. An API/configuration failure exits with code `2`, which both hosts treat as blocking; there is no local allow fallback.
+
+Claude Desktop and Cursor run `sernixa mcp serve`. The stdio MCP server exposes three non-mutating tools:
+
+- `sernixa_policy_check`: evaluate one proposed action.
+- `sernixa_plan_check`: evaluate a declared multi-step plan.
+- `sernixa_identity`: validate auth and return non-secret principal metadata.
+
+MCP tools provide explicit model capabilities; the installed hooks are the local tool-call enforcement points.
+
+## Governance and execution
+
+```bash
+sernixa validate payload.json
+cat payload.json | sernixa validate --json
+sernixa validate --from-claude < claude-hook.json
+sernixa validate --from-codex < codex-hook.jsonl
+sernixa validate-plan --agent-type codex plan.json
+sernixa validate-many --output json policies/*.json
+sernixa exec --plan plan.json -- npm test
+sernixa codex-exec --plan codex-plan.json -- codex exec "fix lint"
+```
+
+Exit codes are stable:
+
+- `0`: success or policy allow
+- `1`: deny, review required, invalid evidence, or non-success terminal result
+- `2`: configuration, parsing, auth, network, or API failure
+
+`validate-plan` calls the canonical plan endpoint. `exec` and `codex-exec` run the child command only after every planned step is allowed and bound to its proof.
+
+## Audit, approvals, and Flight Recorder
+
+```bash
+sernixa events --limit 25
+sernixa events --type governance_agent_plan_evaluated --json
+
+sernixa approvals list
+sernixa approvals decide approval_123 approved --reason "Reviewed bounded deployment."
+sernixa approvals decide approval_456 rejected --reason "Production scope is too broad."
+
+sernixa flight verify
+sernixa flight verify --stream stream_123 --json
+sernixa flight collectors
+```
+
+These commands call the authenticated organization endpoints and inherit backend permissions and feature entitlements. `sernixa decisions` remains a backward-compatible alias for the pending approval queue. Replay is not claimed because the backend does not expose an authorized decision-replay endpoint.
+
+## Stable configuration overrides
+
+- `SERNIXA_CONFIG_FILE`
+- `SERNIXA_PLAN_SESSION_FILE`
+- `SERNIXA_CLAUDE_CONFIG_FILE`
+- `SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE`
+- `SERNIXA_CODEX_HOOKS_FILE`
+- `SERNIXA_CODEX_CONFIG_FILE`
+- `SERNIXA_CURSOR_CONFIG_FILE`
+
+Project-scoped Codex files are intentionally not modified by global setup. Invalid JSON or TOML fails closed with the exact path and a repair command. Existing files are backed up before material changes.

{sernixa_cli-0.1.1 → sernixa_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sernixa-cli"
-version = "0.1.1"
+version = "0.2.0"
 description = "Official Sernixa CLI for policy-governed local AI agent actions"
 readme = "README.md"
 license = "MIT"
@@ -19,7 +19,8 @@ classifiers = [
 ]
 dependencies = [
     "platformdirs>=4.0.0",
-    "sernixa>=0.3.1",
+    "sernixa>=0.4.0",
+    "sernixa-agent>=1.6.0",
     "typer>=0.12.0",
 ]
 

{sernixa_cli-0.1.1 → sernixa_cli-0.2.0}/sernixa_cli/__init__.py

@@ -1,3 +1,3 @@
 """Official Sernixa command-line client."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{sernixa_cli-0.1.1 → sernixa_cli-0.2.0}/sernixa_cli/adapters.py

@@ -85,13 +85,19 @@ def canonicalize_payload(raw: Any, *, mode: ProviderMode) -> CanonicalGovernance
             raise AdapterError("Governance payload must be a JSON object.")
         return CanonicalGovernanceRequest(input=raw, source="plain")
     if mode == "claude":
-        return CanonicalGovernanceRequest(input=_claude_to_governance(raw), source="claude")
+        return CanonicalGovernanceRequest(
+            input=_claude_to_governance(raw), source="claude"
+        )
     if mode == "codex":
-        return CanonicalGovernanceRequest(input=_codex_to_governance(raw), source="codex")
+        return CanonicalGovernanceRequest(
+            input=_codex_to_governance(raw), source="codex"
+        )
     raise AdapterError(f"Unsupported payload adapter: {mode}")
 
 
-def payload_from_content(content: str, *, mode: ProviderMode) -> CanonicalGovernanceRequest:
+def payload_from_content(
+    content: str, *, mode: ProviderMode
+) -> CanonicalGovernanceRequest:
     raw = load_json_payload(content)
     return canonicalize_payload(raw, mode=mode)
 
@@ -128,7 +134,9 @@ def _codex_to_governance(raw: Any) -> dict[str, Any]:
     event = _select_codex_event(raw)
     if not isinstance(event, dict):
         raise AdapterError("Codex payload must be a JSON object or JSON-lines stream.")
-    tool_name = _string(event.get("tool_name") or event.get("name") or event.get("tool"))
+    tool_name = _string(
+        event.get("tool_name") or event.get("name") or event.get("tool")
+    )
     tool_input = event.get("tool_input")
     if tool_input is None:
         if isinstance(event.get("input"), dict):
@@ -178,7 +186,9 @@ def _select_codex_event(raw: Any) -> Any:
         )
     ]
     if not candidates:
-        raise AdapterError("No recognizable Codex tool event found in JSON-lines stream.")
+        raise AdapterError(
+            "No recognizable Codex tool event found in JSON-lines stream."
+        )
     return candidates[-1]
 
 
@@ -243,7 +253,8 @@ def _action_for_tool(tool_name: str, tool_input: dict[str, Any]) -> dict[str, An
         return {
             "action": "network.request",
             "operation_class": "network",
-            "resource": _string(tool_input.get("url")) or _string(tool_input.get("query")),
+            "resource": _string(tool_input.get("url"))
+            or _string(tool_input.get("query")),
             "intent": _string(tool_input.get("prompt")),
         }
     if normalized.startswith("mcp__"):
@@ -258,7 +269,8 @@ def _action_for_tool(tool_name: str, tool_input: dict[str, Any]) -> dict[str, An
             "action": "agent.delegate",
             "operation_class": "delegate",
             "resource": _string(tool_input.get("subagent_type")),
-            "intent": _string(tool_input.get("prompt")) or _string(tool_input.get("description")),
+            "intent": _string(tool_input.get("prompt"))
+            or _string(tool_input.get("description")),
         }
     return {
         "action": f"tool.{normalized}",

sernixa_cli-0.2.0/sernixa_cli/discovery.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from sernixa import Client
+
+from .config import CliConfig
+
+
+class DiscoveryError(RuntimeError):
+    pass
+
+
+TERMINAL_JOB_STATES = {"completed", "failed", "expired", "cancelled"}
+
+
+def _run_agent(
+    command: list[str],
+    *,
+    input_text: str | None = None,
+    extra_env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(
+        command,
+        input=input_text,
+        text=True,
+        capture_output=True,
+        check=False,
+        env={**os.environ, **(extra_env or {})},
+    )
+    if completed.returncode != 0:
+        detail = completed.stderr.strip() or completed.stdout.strip()
+        raise DiscoveryError(detail or f"Command failed: {' '.join(command)}")
+    return completed
+
+
+def _agent_executable() -> str:
+    executable = shutil.which("sernixa-agent")
+    if not executable:
+        raise DiscoveryError(
+            "sernixa-agent is not installed. Upgrade sernixa-cli or install sernixa-agent>=1.6.0."
+        )
+    return executable
+
+
+def _ensure_agent_ready(
+    config: CliConfig,
+    *,
+    agent_config_path: Path,
+) -> tuple[str, dict[str, Any], bool, dict[str, str]]:
+    executable = _agent_executable()
+    agent_env = {"SERNIXA_DISCOVERY_TOKEN": config.api_key}
+    initialized = False
+    if not agent_config_path.exists():
+        _run_agent(
+            [
+                executable,
+                "init",
+                "--config",
+                str(agent_config_path),
+                "--api-base-url",
+                config.base_url,
+            ]
+        )
+        initialized = True
+    status = _run_agent(
+        [
+            executable,
+            "status",
+            "--config",
+            str(agent_config_path),
+            "--token-env",
+            "SERNIXA_DISCOVERY_TOKEN",
+            "--json",
+        ],
+        extra_env=agent_env,
+    )
+    try:
+        status_payload = json.loads(status.stdout)
+    except json.JSONDecodeError as exc:
+        raise DiscoveryError("sernixa-agent returned invalid status JSON.") from exc
+    auth = status_payload.get("auth") if isinstance(status_payload, dict) else None
+    if not isinstance(auth, dict) or not auth.get("ok"):
+        raise DiscoveryError(
+            "Unable to pass the stored CLI credential to the local discovery agent."
+        )
+    return executable, status_payload, initialized, agent_env
+
+
+def _discovery_job_payload(
+    policy: dict[str, Any], *, machine_id: str
+) -> dict[str, Any]:
+    process_enabled = bool(policy.get("process_inspection_enabled", False))
+    config_enabled = bool(policy.get("mcp_config_inspection_enabled", False))
+    return {
+        "scope": {"mode": "local_agent", "machine_ids": [machine_id]},
+        "requested_scan": {
+            "network_ports": "policy_default",
+            "stdio_detection": process_enabled or config_enabled,
+            "process_inspection": process_enabled,
+            "mcp_config_inspection": config_enabled,
+            "controlled_stdio_validation": False,
+            "max_candidates": min(int(policy.get("max_candidates") or 50), 100),
+        },
+    }
+
+
+def run_discovery(
+    client: Client,
+    config: CliConfig,
+    *,
+    job_id: str | None = None,
+    agent_config_path: Path | None = None,
+    timeout_seconds: float = 120.0,
+    poll_interval: float = 1.0,
+) -> dict[str, Any]:
+    """Enroll, dispatch, execute, and verify one bounded Auto Discover run."""
+    identity = client.whoami()
+    config_path = agent_config_path or Path.home() / ".sernixa" / "agent.json"
+    executable, agent_status, initialized, agent_env = _ensure_agent_ready(
+        config, agent_config_path=config_path
+    )
+    machine_id = str(agent_status.get("machine_id") or "")
+    if not machine_id:
+        raise DiscoveryError("sernixa-agent did not return a stable machine ID.")
+    _run_agent(
+        [
+            executable,
+            "enroll",
+            "--config",
+            str(config_path),
+            "--api-base-url",
+            config.base_url,
+            "--token-env",
+            "SERNIXA_DISCOVERY_TOKEN",
+        ],
+        extra_env=agent_env,
+    )
+    if job_id:
+        job = client.auto_discovery_job(job_id)
+    else:
+        policy = client.auto_discovery_policy()
+        job = client.create_auto_discovery_job(
+            _discovery_job_payload(policy, machine_id=machine_id)
+        )
+        job_id = str(job.get("job_id") or "")
+    if not job_id:
+        raise DiscoveryError("Sernixa did not return an Auto Discover job ID.")
+    agent_run = _run_agent(
+        [
+            executable,
+            "daemon",
+            "--config",
+            str(config_path),
+            "--api-base-url",
+            config.base_url,
+            "--token-env",
+            "SERNIXA_DISCOVERY_TOKEN",
+            "--once",
+        ],
+        extra_env=agent_env,
+    )
+    try:
+        agent_summary = json.loads(agent_run.stdout) if agent_run.stdout.strip() else {}
+    except json.JSONDecodeError:
+        agent_summary = {
+            "status": "completed",
+            "detail": agent_run.stdout.strip()[:500],
+        }
+    deadline = time.monotonic() + timeout_seconds
+    while str(job.get("status")) not in TERMINAL_JOB_STATES:
+        if time.monotonic() >= deadline:
+            raise DiscoveryError(
+                f"Timed out waiting for Auto Discover job {job_id}. The job may still complete in Sernixa."
+            )
+        time.sleep(max(0.05, poll_interval))
+        job = client.auto_discovery_job(job_id)
+    return {
+        "organization_id": identity.get("organization_id"),
+        "job": job,
+        "agent": {
+            "config_path": str(config_path.resolve(strict=False)),
+            "initialized": initialized,
+            "machine_id": agent_status.get("machine_id"),
+            "version": agent_status.get("agent_version"),
+            "cycle": agent_summary,
+        },
+        "trust_boundary": (
+            "Discovery candidates are observations for review. Enrollment is inventory; "
+            "the accepted agent sync is the proof recorded by Sernixa."
+        ),
+    }