command-gate 0.2.4__py3-none-any.whl

cgate/db/commands.py

@@ -0,0 +1,191 @@
+"""CommandsRepo: CRUD + status transitions for the `commands` table."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from cgate.db.connection import Database, connect
+from cgate.db.rows import col_int, iso, row_to_command
+from cgate.db.types import (
+    BatchId,
+    Command,
+    CommandId,
+    CommandStatus,
+    ServerType,
+)
+
+_TERMINAL_STATUSES: frozenset[CommandStatus] = frozenset(
+    {CommandStatus.EXECUTED, CommandStatus.REJECTED, CommandStatus.FAILED}
+)
+
+
+def all_terminal(commands_for_batch: list[Command]) -> bool:
+    """Return whether every command in the list has reached a terminal status.
+
+    Shared by the watch TUI's own approve/reject path and the MCP AUTO-mode
+    auto-execution path, both of which need to decide when a batch is done.
+    """
+    return all(command.status in _TERMINAL_STATUSES for command in commands_for_batch)
+
+
+class CommandsRepo:
+    """Command CRUD + per-batch listing + status transitions."""
+
+    _db: Database  # class-level annotation required by strict mode
+
+    def __init__(self, db: Database) -> None:
+        """Store the database handle for subsequent operations."""
+        self._db = db
+
+    def add(  # noqa: PLR0913 - one param per persisted command field, all but the first three optional
+        self,
+        *,
+        batch_id: BatchId,
+        server_alias: str,
+        server_type: ServerType,
+        command: str,
+        reason: str | None = None,
+        risk_label: str | None = None,
+    ) -> Command:
+        """Append a command to the end of a batch (position = max + 1, or 0 if empty).
+
+        Computes the position in the same statement as the INSERT (issue
+        #10) rather than a separate SELECT beforehand: two connections
+        racing the old SELECT-then-INSERT could both compute the same
+        ``next_pos`` before either committed, and the second INSERT would
+        die on the ``UNIQUE (batch_id, position)`` constraint. A single
+        ``INSERT ... SELECT`` is one write that SQLite serializes against
+        other writers, so the second racer recomputes against the first
+        racer's already-committed row instead of colliding with it.
+        """
+        command_id = CommandId(str(uuid4()))
+        now = datetime.now(UTC)
+        with connect(self._db) as conn:
+            _ = conn.execute(
+                """
+                INSERT INTO commands
+                    (id, batch_id, position, server_alias, server_type,
+                     command, status, created_at, reason, risk_label)
+                SELECT ?, ?, COALESCE(MAX(position), -1) + 1, ?, ?, ?, ?, ?, ?, ?
+                FROM commands WHERE batch_id = ?
+                """,
+                (
+                    command_id,
+                    batch_id,
+                    server_alias,
+                    server_type.value,
+                    command,
+                    CommandStatus.PENDING.value,
+                    iso(now),
+                    reason,
+                    risk_label,
+                    batch_id,
+                ),
+            )
+            pos_row = conn.execute(
+                "SELECT position FROM commands WHERE id = ?", (command_id,)
+            ).fetchone()
+            if pos_row is None:
+                msg = "inserted command disappeared before its position could be read"
+                raise RuntimeError(msg)
+            next_pos = col_int(pos_row, "position")
+        return Command(
+            id=command_id,
+            batch_id=batch_id,
+            position=next_pos,
+            server_alias=server_alias,
+            server_type=server_type,
+            command=command,
+            status=CommandStatus.PENDING,
+            result=None,
+            approved_by=None,
+            created_at=now,
+            resolved_at=None,
+            reason=reason,
+            risk_label=risk_label,
+        )
+
+    def get(self, command_id: CommandId) -> Command | None:
+        """Fetch a command by ID, or None if not found."""
+        with connect(self._db) as conn:
+            row = conn.execute(
+                """
+                SELECT id, batch_id, position, server_alias, server_type,
+                    command, status, result, approved_by, created_at, resolved_at,
+                    reason, risk_label
+                FROM commands WHERE id = ?
+                """,
+                (command_id,),
+            ).fetchone()
+        return row_to_command(row) if row is not None else None
+
+    def list_for_batch(self, batch_id: BatchId) -> list[Command]:
+        """All commands in a batch, ordered by position."""
+        with connect(self._db) as conn:
+            rows = conn.execute(
+                """
+                SELECT id, batch_id, position, server_alias, server_type,
+                    command, status, result, approved_by, created_at, resolved_at,
+                    reason, risk_label
+                FROM commands WHERE batch_id = ?
+                ORDER BY position ASC
+                """,
+                (batch_id,),
+            ).fetchall()
+        return [row_to_command(r) for r in rows]
+
+    def list_by_status(self, status: CommandStatus) -> list[Command]:
+        """All commands currently in the given status, across every batch."""
+        with connect(self._db) as conn:
+            rows = conn.execute(
+                """
+                SELECT id, batch_id, position, server_alias, server_type,
+                    command, status, result, approved_by, created_at, resolved_at,
+                    reason, risk_label
+                FROM commands WHERE status = ?
+                """,
+                (status.value,),
+            ).fetchall()
+        return [row_to_command(r) for r in rows]
+
+    def update_status(
+        self,
+        command_id: CommandId,
+        *,
+        status: CommandStatus,
+        approved_by: str | None = None,
+        result: str | None = None,
+        expected_status: CommandStatus | None = None,
+    ) -> bool:
+        """Transition a command's status; stamp resolved_at iff status is terminal.
+
+        When ``expected_status`` is given, the UPDATE only applies if the
+        row's current status still matches it -- a compare-and-swap guard
+        against a concurrent transition racing this one (issue #13; not
+        exploitable in today's single-process synchronous `watch`, but a
+        cheap guard against a future daemon/concurrent mode). Returns
+        whether the row was actually updated.
+        """
+        guard = " AND status = ?" if expected_status is not None else ""
+        guard_params = (expected_status.value,) if expected_status is not None else ()
+        with connect(self._db) as conn:
+            if status in _TERMINAL_STATUSES:
+                cursor = conn.execute(
+                    "UPDATE commands SET status = ?, approved_by = ?, result = ?, "  # noqa: S608 -- guard is one of two fixed literals, never user input
+                    f"resolved_at = ? WHERE id = ?{guard}",
+                    (
+                        status.value,
+                        approved_by,
+                        result,
+                        iso(datetime.now(UTC)),
+                        command_id,
+                        *guard_params,
+                    ),
+                )
+            else:
+                cursor = conn.execute(
+                    "UPDATE commands SET status = ?, approved_by = ?, result = ? "  # noqa: S608 -- guard is one of two fixed literals, never user input
+                    f"WHERE id = ?{guard}",
+                    (status.value, approved_by, result, command_id, *guard_params),
+                )
+        return cursor.rowcount > 0

cgate/db/connection.py

@@ -0,0 +1,104 @@
+"""SQLite connection wrapper and schema initialization."""
+from __future__ import annotations
+
+import sqlite3
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from cgate.db.schema import SCHEMA_SQL, SCHEMA_VERSION
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from pathlib import Path
+
+# Auto-approve mode tables (feature: modes + per-server opt-in). Kept out of
+# schema.py's Phase-1 SCHEMA_SQL so the original schema constant stays frozen;
+# both statements are IF NOT EXISTS, so init stays idempotent. No default
+# app_mode row is seeded: absence means "unset" and AppModeRepo.get() raises.
+_MODE_SETTINGS_SQL = """
+CREATE TABLE IF NOT EXISTS app_mode (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    mode TEXT NOT NULL CHECK (mode IN ('propose','auto')),
+    updated_at TEXT NOT NULL,
+    updated_by TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS server_settings (
+    server_alias TEXT PRIMARY KEY,
+    auto_allowed INTEGER NOT NULL DEFAULT 0 CHECK (auto_allowed IN (0,1)),
+    updated_at TEXT,
+    updated_by TEXT
+);
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class Database:
+    """A reference to a SQLite database file on disk."""
+
+    path: Path
+
+
+@contextmanager
+def connect(database: Database) -> Generator[sqlite3.Connection, None, None]:
+    """Open a SQLite connection. Commits on clean exit, rolls back on exception.
+
+    Sets row_factory=sqlite3.Row for column-name access, and PRAGMA foreign_keys=ON
+    so FK references in the schema are enforced.
+
+    ``timeout=30`` (sqlite3's default is 5s) because `cgate watch` and the
+    MCP server backing an AI agent's AUTO-mode auto-execution are two
+    separate processes that can now write to the same file at the same
+    time -- a short busy-timeout would surface as a spurious "database is
+    locked" error in the TUI under nothing worse than ordinary contention.
+    """
+    conn = sqlite3.connect(database.path, timeout=30)
+    conn.row_factory = sqlite3.Row
+    _ = conn.execute("PRAGMA foreign_keys = ON")
+    try:
+        yield conn
+        conn.commit()
+    except BaseException:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def _ensure_column(conn: sqlite3.Connection, *, table: str, column: str, sql_type: str) -> None:
+    """Add one column to an existing table if it isn't already there.
+
+    Unlike the ``CREATE TABLE IF NOT EXISTS`` statements everywhere else
+    in this file, SQLite's ``ALTER TABLE ... ADD COLUMN`` has no
+    ``IF NOT EXISTS`` form, so idempotency has to be a live
+    ``PRAGMA table_info`` check instead of a fixed SQL string.
+    """
+    # table/column/sql_type are always fixed literals from call sites below, never user input.
+    columns = {row["name"] for row in conn.execute(f"PRAGMA table_info({table})")}
+    if column not in columns:
+        _ = conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {sql_type}")
+
+
+def init_database(database: Database) -> None:
+    """Create parent dirs (if needed) and apply the schema; idempotent.
+
+    Uses ``INSERT OR IGNORE`` rather than a SELECT-then-INSERT (issue
+    #11): two ``cgate`` processes launched concurrently against a brand
+    new database file could otherwise both pass the SELECT before either
+    committed, then collide on the second's INSERT into the
+    ``version`` PRIMARY KEY. ``OR IGNORE`` makes the row idempotent in a
+    single statement instead.
+    """
+    database.path.parent.mkdir(parents=True, exist_ok=True)
+    with connect(database) as conn:
+        _ = conn.executescript(SCHEMA_SQL)
+        _ = conn.executescript(_MODE_SETTINGS_SQL)
+        _ensure_column(conn, table="commands", column="reason", sql_type="TEXT")
+        _ensure_column(conn, table="commands", column="risk_label", sql_type="TEXT")
+        applied_at = datetime.now(UTC).isoformat().replace("+00:00", "Z")
+        _ = conn.execute(
+            "INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)",
+            (SCHEMA_VERSION, applied_at),
+        )

cgate/db/mode.py

@@ -0,0 +1,74 @@
+"""AppModeRepo: read/upsert the single-row `app_mode` table (global behavior mode)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from cgate.db.connection import Database, connect
+from cgate.db.rows import col_str, iso, parse
+
+
+class Mode(StrEnum):
+    """Global behavior mode: queue every proposal, or allow per-server auto-execution."""
+
+    PROPOSE = "propose"
+    AUTO = "auto"
+
+
+class AppModeNotSetError(LookupError):
+    """The app_mode row is absent: the global mode has never been explicitly set."""
+
+    def __init__(self) -> None:
+        """Create the error with a fixed human-readable message."""
+        super().__init__("app mode is not set")
+
+
+@dataclass(frozen=True, slots=True)
+class AppMode:
+    """The singleton global mode row (id = 1) with its audit fields."""
+
+    mode: Mode
+    updated_at: datetime
+    updated_by: str
+
+
+class AppModeRepo:
+    """Read/upsert the single-row app_mode table; absence means "unset"."""
+
+    _db: Database  # class-level annotation required by strict mode
+
+    def __init__(self, db: Database) -> None:
+        """Store the database handle for subsequent operations."""
+        self._db = db
+
+    def get(self) -> AppMode:
+        """Fetch the global mode, raising AppModeNotSetError if never set."""
+        with connect(self._db) as conn:
+            row = conn.execute(
+                "SELECT mode, updated_at, updated_by FROM app_mode WHERE id = 1"
+            ).fetchone()
+        if row is None:
+            raise AppModeNotSetError
+        return AppMode(
+            mode=Mode(col_str(row, "mode")),
+            updated_at=parse(col_str(row, "updated_at")),
+            updated_by=col_str(row, "updated_by"),
+        )
+
+    def set(self, *, mode: Mode, updated_by: str) -> AppMode:
+        """Upsert the singleton row and return the value now in effect."""
+        now = datetime.now(UTC)
+        with connect(self._db) as conn:
+            _ = conn.execute(
+                """
+                INSERT INTO app_mode (id, mode, updated_at, updated_by)
+                VALUES (1, ?, ?, ?)
+                ON CONFLICT(id) DO UPDATE SET
+                    mode = excluded.mode,
+                    updated_at = excluded.updated_at,
+                    updated_by = excluded.updated_by
+                """,
+                (mode.value, iso(now), updated_by),
+            )
+        return AppMode(mode=mode, updated_at=now, updated_by=updated_by)

cgate/db/rows.py

@@ -0,0 +1,99 @@
+"""SQLite row parsing: read raw rows and convert them into typed domain values."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from cgate.db.types import (
+    Batch,
+    BatchId,
+    Command,
+    CommandId,
+    CommandStatus,
+    Connection,
+    ServerType,
+)
+
+if TYPE_CHECKING:
+    import sqlite3
+
+
+def iso(dt: datetime) -> str:
+    """Serialize a datetime to ISO-8601 UTC with a Z suffix."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+def parse(s: str) -> datetime:
+    """Parse an ISO-8601 timestamp (Z suffix supported) into a tz-aware datetime."""
+    return datetime.fromisoformat(s)
+
+
+def col_str(row: sqlite3.Row, col: str) -> str:
+    """Read a NOT NULL TEXT column from a row as str."""
+    return str(row[col])
+
+
+def col_opt_str(row: sqlite3.Row, col: str) -> str | None:
+    """Read a nullable TEXT column from a row; None for SQL NULL."""
+    value: object = row[col]
+    if value is None:
+        return None
+    return str(value)
+
+
+def col_int(row: sqlite3.Row, col: str) -> int:
+    """Read an INTEGER column from a row as int."""
+    return int(str(row[col]))
+
+
+def col_opt_dt(row: sqlite3.Row, col: str) -> datetime | None:
+    """Read a nullable TIMESTAMP column from a row as datetime."""
+    raw: object = row[col]
+    if raw is None:
+        return None
+    return parse(str(raw))
+
+
+def row_to_batch(row: sqlite3.Row) -> Batch:
+    """Convert a SQLite row into a typed Batch value object."""
+    return Batch(
+        id=BatchId(col_str(row, "id")),
+        title=col_str(row, "title"),
+        description=col_opt_str(row, "description"),
+        requested_by_agent=col_opt_str(row, "requested_by_agent"),
+        created_at=parse(col_str(row, "created_at")),
+        resolved_at=col_opt_dt(row, "resolved_at"),
+    )
+
+
+def row_to_command(row: sqlite3.Row) -> Command:
+    """Convert a SQLite row into a typed Command value object."""
+    return Command(
+        id=CommandId(col_str(row, "id")),
+        batch_id=BatchId(col_str(row, "batch_id")),
+        position=col_int(row, "position"),
+        server_alias=col_str(row, "server_alias"),
+        server_type=ServerType(col_str(row, "server_type")),
+        command=col_str(row, "command"),
+        status=CommandStatus(col_str(row, "status")),
+        result=col_opt_str(row, "result"),
+        approved_by=col_opt_str(row, "approved_by"),
+        created_at=parse(col_str(row, "created_at")),
+        resolved_at=col_opt_dt(row, "resolved_at"),
+        reason=col_opt_str(row, "reason"),
+        risk_label=col_opt_str(row, "risk_label"),
+    )
+
+
+def row_to_connection(row: sqlite3.Row) -> Connection:
+    """Convert a SQLite row into a typed Connection value object."""
+    return Connection(
+        alias=col_str(row, "alias"),
+        hostname=col_str(row, "hostname"),
+        server_type=ServerType(col_str(row, "server_type")),
+        detection_ssh=bool(col_int(row, "detection_ssh")),
+        detection_winrm=bool(col_int(row, "detection_winrm")),
+        created_at=parse(col_str(row, "created_at")),
+    )

cgate/db/schema.py

@@ -0,0 +1,54 @@
+"""SQL schema for command-gate (Phase 1, SQLite).
+
+Source of truth: spec-inicial.md, "Esquema de datos (SQLite)" section.
+Designed to migrate to SQL Server in Phase 2 with the same columns.
+"""
+from __future__ import annotations
+
+SCHEMA_VERSION = 2
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS batches (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    description TEXT,
+    requested_by_agent TEXT,
+    created_at TEXT NOT NULL,
+    resolved_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS commands (
+    id TEXT PRIMARY KEY,
+    batch_id TEXT NOT NULL REFERENCES batches(id),
+    position INTEGER NOT NULL,
+    server_alias TEXT NOT NULL,
+    server_type TEXT NOT NULL CHECK (server_type IN ('windows', 'linux')),
+    command TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (
+        status IN ('pending', 'approved', 'rejected', 'executed', 'failed')
+    ),
+    result TEXT,
+    approved_by TEXT,
+    created_at TEXT NOT NULL,
+    resolved_at TEXT,
+    UNIQUE (batch_id, position)
+);
+
+CREATE INDEX IF NOT EXISTS idx_commands_batch_id ON commands(batch_id);
+CREATE INDEX IF NOT EXISTS idx_commands_status ON commands(status);
+
+CREATE TABLE IF NOT EXISTS connections (
+    alias TEXT PRIMARY KEY,
+    hostname TEXT NOT NULL,
+    server_type TEXT NOT NULL CHECK (server_type IN ('windows', 'linux')),
+    detection_ssh INTEGER NOT NULL,
+    detection_winrm INTEGER NOT NULL,
+    created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_connections_server_type ON connections(server_type);
+"""

cgate/db/server_settings.py

@@ -0,0 +1,105 @@
+"""ServerSettingsRepo: per-server auto-approve opt-in rows (`server_settings` table)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from cgate.db.connection import Database, connect
+from cgate.db.rows import col_int, col_opt_dt, col_opt_str, col_str, iso
+
+if TYPE_CHECKING:
+    import sqlite3
+
+
+@dataclass(frozen=True, slots=True)
+class ServerSetting:
+    """Explicit auto-approve opt-in state for one server alias.
+
+    ``updated_at``/``updated_by`` are None only for the implicit default
+    returned by ``get_or_default`` when no row exists -- persisted rows
+    always carry both audit fields.
+    """
+
+    server_alias: str
+    auto_allowed: bool
+    updated_at: datetime | None
+    updated_by: str | None
+
+
+def _row_to_setting(row: sqlite3.Row) -> ServerSetting:
+    """Convert a SQLite row into a typed ServerSetting value object."""
+    return ServerSetting(
+        server_alias=col_str(row, "server_alias"),
+        auto_allowed=bool(col_int(row, "auto_allowed")),
+        updated_at=col_opt_dt(row, "updated_at"),
+        updated_by=col_opt_str(row, "updated_by"),
+    )
+
+
+class ServerSettingsRepo:
+    """Per-server opt-in CRUD; no row means auto-execute is NOT allowed."""
+
+    _db: Database  # class-level annotation required by strict mode
+
+    def __init__(self, db: Database) -> None:
+        """Store the database handle for subsequent operations."""
+        self._db = db
+
+    def get(self, alias: str) -> ServerSetting | None:
+        """Fetch the explicit setting for an alias, or None if never set."""
+        with connect(self._db) as conn:
+            row = conn.execute(
+                """
+                SELECT server_alias, auto_allowed, updated_at, updated_by
+                FROM server_settings WHERE server_alias = ?
+                """,
+                (alias,),
+            ).fetchone()
+        return _row_to_setting(row) if row is not None else None
+
+    def get_or_default(self, alias: str) -> ServerSetting:
+        """Fetch the setting, defaulting to auto_allowed=False when no row exists."""
+        setting = self.get(alias)
+        if setting is None:
+            return ServerSetting(
+                server_alias=alias,
+                auto_allowed=False,
+                updated_at=None,
+                updated_by=None,
+            )
+        return setting
+
+    def set(self, *, alias: str, auto_allowed: bool, updated_by: str) -> ServerSetting:
+        """Upsert the opt-in row for an alias and return the value now in effect."""
+        now = datetime.now(UTC)
+        with connect(self._db) as conn:
+            _ = conn.execute(
+                """
+                INSERT INTO server_settings
+                    (server_alias, auto_allowed, updated_at, updated_by)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(server_alias) DO UPDATE SET
+                    auto_allowed = excluded.auto_allowed,
+                    updated_at = excluded.updated_at,
+                    updated_by = excluded.updated_by
+                """,
+                (alias, int(auto_allowed), iso(now), updated_by),
+            )
+        return ServerSetting(
+            server_alias=alias,
+            auto_allowed=auto_allowed,
+            updated_at=now,
+            updated_by=updated_by,
+        )
+
+    def list_all(self) -> list[ServerSetting]:
+        """Return every alias with an explicit setting, ordered by alias."""
+        with connect(self._db) as conn:
+            rows = conn.execute(
+                """
+                SELECT server_alias, auto_allowed, updated_at, updated_by
+                FROM server_settings ORDER BY server_alias ASC
+                """
+            ).fetchall()
+        return [_row_to_setting(row) for row in rows]