euron-code 0.1.0__py3-none-any.whl

euron_code/tools/base.py

@@ -0,0 +1,167 @@
+"""Tool plumbing shared by every tool."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from euron_code.permissions import Request
+
+
+class ToolError(Exception):
+    """Raised by a tool to return an error message to the model."""
+
+
+@dataclass
+class ToolResult:
+    content: str
+    is_error: bool = False
+    preview: Optional[str] = None  # short text for the user; defaults to content
+
+
+@dataclass
+class FileRecord:
+    mtime: float
+    size: int
+    ranges: List[tuple] = field(default_factory=list)
+
+
+class ReadTracker:
+    """Remembers which files the model has read (for edit safety and read dedupe)."""
+
+    def __init__(self) -> None:
+        self.files: Dict[str, FileRecord] = {}
+
+    @staticmethod
+    def _key(path: Path) -> str:
+        k = str(path.resolve())
+        return k.lower() if os.name == "nt" else k
+
+    def mark_read(self, path: Path, rng: Optional[tuple] = None) -> None:
+        st = path.stat()
+        rec = self.files.get(self._key(path))
+        if rec is None or rec.mtime != st.st_mtime or rec.size != st.st_size:
+            rec = FileRecord(st.st_mtime, st.st_size)
+            self.files[self._key(path)] = rec
+        if rng is not None and rng not in rec.ranges:
+            rec.ranges.append(rng)
+
+    def mark_written(self, path: Path) -> None:
+        st = path.stat()
+        self.files[self._key(path)] = FileRecord(st.st_mtime, st.st_size, [])
+
+    def was_read(self, path: Path) -> bool:
+        return self._key(path) in self.files
+
+    def unchanged_since_read(self, path: Path) -> bool:
+        rec = self.files.get(self._key(path))
+        if rec is None:
+            return False
+        try:
+            st = path.stat()
+        except OSError:
+            return False
+        return rec.mtime == st.st_mtime and rec.size == st.st_size
+
+    def already_has(self, path: Path, rng: tuple) -> bool:
+        rec = self.files.get(self._key(path))
+        return bool(rec) and self.unchanged_since_read(path) and rng in rec.ranges
+
+    def clear(self) -> None:
+        """Called after compaction: file contents are no longer in context."""
+        for rec in self.files.values():
+            rec.ranges.clear()
+
+
+@dataclass
+class ToolContext:
+    root: Path
+    settings: Dict[str, Any]
+    ui: Any
+    tracker: ReadTracker = field(default_factory=ReadTracker)
+    shell: Any = None  # ShellSession
+    todos: List[Dict[str, Any]] = field(default_factory=list)
+    agent: Any = None  # the running Agent (for the task tool)
+
+    @property
+    def max_output_chars(self) -> int:
+        return int(self.settings.get("toolOutputMaxChars") or 12000)
+
+    def resolve(self, p: str) -> Path:
+        if not isinstance(p, str) or not p.strip():
+            raise ToolError("A non-empty path is required.")
+        raw = os.path.expanduser(p.strip())
+        path = Path(raw)
+        if not path.is_absolute():
+            path = self.root / path
+        return Path(os.path.normpath(str(path)))
+
+    def rel(self, path: Path) -> str:
+        try:
+            return path.resolve().relative_to(self.root.resolve()).as_posix()
+        except ValueError:
+            return str(path)
+
+
+def truncate(text: str, max_chars: int, note: str = "") -> str:
+    """Keep the head and tail of long output, with a note saying what was cut."""
+    if len(text) <= max_chars:
+        return text
+    head = int(max_chars * 0.6)
+    tail = max_chars - head
+    cut = text[head: len(text) - tail]
+    cut_lines = cut.count("\n")
+    msg = (f"\n\n[... output truncated: {len(cut)} characters / ~{cut_lines} lines omitted"
+           f"{'; ' + note if note else ''} ...]\n\n")
+    return text[:head] + msg + text[len(text) - tail:]
+
+
+class Tool:
+    name: str = ""
+    description: str = ""
+    parameters: Dict[str, Any] = {}
+    read_only: bool = False
+
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {"name": self.name, "description": self.description, "parameters": self.parameters},
+        }
+
+    def permission(self, args: Dict[str, Any], ctx: ToolContext) -> Request:
+        return Request(category=None, tool=self.name)
+
+    def describe(self, args: Dict[str, Any], ctx: ToolContext) -> str:
+        """One-line summary shown to the user."""
+        return ""
+
+    def preview(self, args: Dict[str, Any], ctx: ToolContext) -> Optional[str]:
+        """Extra detail shown in the permission prompt (e.g. a diff). May raise ToolError."""
+        return None
+
+    def run(self, args: Dict[str, Any], ctx: ToolContext) -> ToolResult:
+        raise NotImplementedError
+
+
+def require(args: Dict[str, Any], key: str, typ: type = str) -> Any:
+    if key not in args or args[key] is None:
+        raise ToolError(f"Missing required parameter `{key}`.")
+    v = args[key]
+    if typ is str and not isinstance(v, str):
+        raise ToolError(f"Parameter `{key}` must be a string.")
+    return v
+
+
+def opt_int(args: Dict[str, Any], key: str, default: Optional[int]) -> Optional[int]:
+    v = args.get(key)
+    if v is None or v == "":
+        return default
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        raise ToolError(f"Parameter `{key}` must be an integer.")
+
+
+DiffFn = Callable[[str, str, str], str]

euron_code/tools/db.py

@@ -0,0 +1,368 @@
+"""db_query: explore SQLite files and Postgres / MySQL databases the user configured.
+
+Read-only by default, enforced twice:
+  1. a SQL guard rejects anything that is not a plain read (SELECT / WITH / EXPLAIN / SHOW / ...);
+  2. the connection itself is opened read-only (SQLite `mode=ro`, Postgres read-only session,
+     MySQL `TRANSACTION READ ONLY`).
+Writes need `db.allowWrites: true` in settings AND a per-statement permission prompt.
+
+Connections live in settings, never in the conversation:
+  "db": {"connections": {"app": "postgresql://user:${PGPASSWORD}@localhost/app",
+                         "local": "sqlite:///data/app.db"}}
+`${VAR}` is expanded from the environment so passwords need not be stored in the file.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sqlite3
+from pathlib import Path
+from typing import Any, List, Optional, Sequence, Tuple
+from urllib.parse import unquote, urlparse
+
+from euron_code.permissions import Request
+from euron_code.tools.base import Tool, ToolContext, ToolError, ToolResult, opt_int, truncate
+
+READ_FIRST = {"select", "with", "explain", "show", "describe", "desc", "pragma", "values", "table"}
+DENY_TOKENS = {
+    "insert", "update", "delete", "drop", "create", "alter", "truncate", "grant", "revoke", "merge",
+    "upsert", "attach", "detach", "vacuum", "reindex", "copy", "call", "exec", "execute", "lock",
+    "into", "rename", "load_extension", "set_config", "pg_terminate_backend", "pg_cancel_backend",
+    "pg_reload_conf", "lo_import", "lo_export", "pg_read_file", "pg_read_binary_file", "pg_ls_dir",
+    "dblink", "dblink_exec", "nextval", "setval", "refresh", "analyze", "optimize", "handler",
+}
+
+
+def _strip_sql(sql: str) -> str:
+    """Remove comments, string literals and quoted identifiers so keyword checks see only code."""
+    out = []
+    i, n = 0, len(sql)
+    while i < n:
+        c = sql[i]
+        if sql.startswith("--", i) or c == "#":
+            j = sql.find("\n", i)
+            i = n if j == -1 else j
+            out.append(" ")
+        elif sql.startswith("/*", i):
+            j = sql.find("*/", i + 2)
+            i = n if j == -1 else j + 2
+            out.append(" ")
+        elif c in ("'", '"', "`"):
+            j = i + 1
+            while j < n:
+                if sql[j] == c:
+                    if j + 1 < n and sql[j + 1] == c:
+                        j += 2
+                        continue
+                    break
+                if sql[j] == "\\" and c == "'":
+                    j += 2
+                    continue
+                j += 1
+            i = j + 1
+            out.append(" 'x' " if c == "'" else " ident ")
+        elif c == "$":
+            m = re.match(r"\$([A-Za-z_]\w*)?\$", sql[i:])
+            if m:
+                tag = m.group(0)
+                j = sql.find(tag, i + len(tag))
+                i = n if j == -1 else j + len(tag)
+                out.append(" 'x' ")
+            else:
+                out.append(c)
+                i += 1
+        else:
+            out.append(c)
+            i += 1
+    return "".join(out)
+
+
+def check_read_only(sql: str) -> Tuple[bool, str]:
+    """Return (ok, reason). ok=True only for statements that cannot write."""
+    code = _strip_sql(sql)
+    stmts = [s.strip() for s in code.split(";") if s.strip()]
+    if not stmts:
+        return False, "empty statement"
+    for s in stmts:
+        toks = re.findall(r"[A-Za-z_][A-Za-z0-9_]*", s.lower())
+        if not toks:
+            return False, "no SQL keyword found"
+        first = toks[0]
+        if first not in READ_FIRST:
+            return False, f"`{first.upper()}` statements are not read-only"
+        bad = sorted(set(toks) & DENY_TOKENS)
+        if first == "explain":
+            # EXPLAIN ANALYZE runs the statement; allow only when the rest is a plain read
+            rest = [t for t in toks[1:] if t not in ("analyze", "verbose", "query", "plan", "format",
+                                                      "json", "text", "costs", "buffers", "true", "false")]
+            if rest and rest[0] not in ("select", "with", "values", "table"):
+                return False, "EXPLAIN of a non-SELECT statement"
+            bad = [b for b in bad if b != "analyze"]
+        if bad:
+            return False, f"contains {', '.join(b.upper() for b in bad)}"
+        if first == "pragma" and "=" in s:
+            return False, "PRAGMA assignments change the database"
+    return True, ""
+
+
+def expand_env(s: str) -> str:
+    return re.sub(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}", lambda m: os.environ.get(m.group(1), ""), s)
+
+
+def mask_dsn(dsn: str) -> str:
+    return re.sub(r"(://[^:/@]+:)[^@]*@", r"\1****@", dsn)
+
+
+def _fmt(v: Any) -> str:
+    if v is None:
+        return "NULL"
+    if isinstance(v, (bytes, bytearray, memoryview)):
+        return f"<{len(bytes(v))} bytes>"
+    s = str(v).replace("\n", "\\n")
+    return s if len(s) <= 200 else s[:200] + "..."
+
+
+def format_table(cols: Sequence[str], rows: Sequence[Sequence[Any]], total: Optional[int], limit: int) -> str:
+    if not cols:
+        return "(statement returned no columns)"
+    cells = [[_fmt(v) for v in r] for r in rows]
+    widths = [min(60, max([len(str(c))] + [len(r[i]) for r in cells])) for i, c in enumerate(cols)]
+    def line(vals):
+        return " | ".join(str(v)[:60].ljust(widths[i]) for i, v in enumerate(vals)).rstrip()
+    out = [line(cols), "-+-".join("-" * w for w in widths)]
+    out += [line(r) for r in cells]
+    n = len(rows)
+    more = total is not None and total > n
+    out.append(f"({n} row{'s' if n != 1 else ''}{'; more rows exist, showing the first ' + str(limit) if more else ''})")
+    return "\n".join(out)
+
+
+class Connection:
+    def __init__(self, kind: str, target: str, label: str):
+        self.kind = kind  # sqlite | postgres | mysql
+        self.target = target
+        self.label = label
+
+
+def resolve_connection(name: Optional[str], ctx: ToolContext) -> Connection:
+    conns = (ctx.settings.get("db") or {}).get("connections") or {}
+    if not name:
+        if len(conns) == 1:
+            name = next(iter(conns))
+        else:
+            raise ToolError("Give `database`: a configured connection name "
+                            f"({', '.join(conns) or 'none configured'}) or a path to a .db/.sqlite file.")
+    raw = conns.get(name)
+    if raw is None:
+        p = ctx.resolve(name)
+        if p.suffix.lower() in (".db", ".sqlite", ".sqlite3", ".db3") or p.is_file():
+            if not p.is_file():
+                raise ToolError(f"SQLite file not found: {ctx.rel(p)}")
+            return Connection("sqlite", str(p), ctx.rel(p))
+        raise ToolError(f"Unknown database {name!r}. Configured: {', '.join(conns) or 'none'}. "
+                        "The user can add one with `euron config set db.connections.<name> <dsn>`.")
+    dsn = expand_env(str(raw))
+    low = dsn.lower()
+    if low.startswith("sqlite:"):
+        # sqlite:///rel/path.db, sqlite:////abs/path.db, sqlite:///C:/abs/path.db, sqlite:path.db
+        if low.startswith("sqlite:///"):
+            path = dsn[len("sqlite:///"):]
+        elif low.startswith("sqlite://"):
+            path = dsn[len("sqlite://"):]
+        else:
+            path = dsn[len("sqlite:"):]
+        p = ctx.resolve(path)
+        return Connection("sqlite", str(p), name)
+    if low.startswith(("postgres://", "postgresql://")):
+        return Connection("postgres", dsn, name)
+    if low.startswith(("mysql://", "mariadb://")):
+        return Connection("mysql", dsn, name)
+    p = ctx.resolve(dsn)
+    return Connection("sqlite", str(p), name)
+
+
+def _run_sqlite(conn: Connection, sql: str, params: Sequence[Any], write: bool, limit: int):
+    p = Path(conn.target)
+    if not p.is_file():
+        raise ToolError(f"SQLite file not found: {conn.label}")
+    if write:
+        db = sqlite3.connect(str(p), timeout=10)
+    else:
+        db = sqlite3.connect(p.resolve().as_uri() + "?mode=ro", uri=True, timeout=10)
+    try:
+        cur = db.cursor()
+        if write:
+            cur.executescript(sql) if not params and sql.count(";") > 1 else cur.execute(sql, params)
+            db.commit()
+            return [], [], None, cur.rowcount
+        cur.execute(sql, params)
+        cols = [d[0] for d in cur.description] if cur.description else []
+        rows = cur.fetchmany(limit + 1)
+        return cols, rows[:limit], (limit + 1 if len(rows) > limit else len(rows)), None
+    except sqlite3.Error as e:
+        raise ToolError(f"SQLite error: {e}")
+    finally:
+        db.close()
+
+
+def _run_postgres(conn: Connection, sql: str, params: Sequence[Any], write: bool, limit: int):
+    try:
+        import psycopg  # type: ignore
+        v3 = True
+    except ImportError:
+        try:
+            import psycopg2 as psycopg  # type: ignore
+            v3 = False
+        except ImportError:
+            raise ToolError("Postgres support needs a driver: pip install \"euron-code[postgres]\"")
+    try:
+        db = psycopg.connect(conn.target, connect_timeout=10)
+    except Exception as e:
+        raise ToolError(f"Cannot connect to {conn.label}: {mask_dsn(str(e))}")
+    try:
+        if v3:
+            db.read_only = not write
+        else:
+            db.set_session(readonly=not write)
+        cur = db.cursor()
+        cur.execute("SET statement_timeout = 30000")
+        cur.execute(sql, params or None)
+        if write:
+            db.commit()
+            return [], [], None, cur.rowcount
+        cols = [d[0] for d in cur.description] if cur.description else []
+        rows = cur.fetchmany(limit + 1) if cur.description else []
+        db.rollback()
+        return cols, rows[:limit], (limit + 1 if len(rows) > limit else len(rows)), None
+    except Exception as e:
+        raise ToolError(f"Postgres error: {e}")
+    finally:
+        db.close()
+
+
+def _run_mysql(conn: Connection, sql: str, params: Sequence[Any], write: bool, limit: int):
+    try:
+        import pymysql  # type: ignore
+    except ImportError:
+        raise ToolError("MySQL support needs a driver: pip install \"euron-code[mysql]\"")
+    u = urlparse(conn.target)
+    try:
+        db = pymysql.connect(host=u.hostname or "localhost", port=u.port or 3306,
+                             user=unquote(u.username or ""), password=unquote(u.password or ""),
+                             database=(u.path or "/").lstrip("/") or None, connect_timeout=10,
+                             read_timeout=30)
+    except Exception as e:
+        raise ToolError(f"Cannot connect to {conn.label}: {mask_dsn(str(e))}")
+    try:
+        cur = db.cursor()
+        if not write:
+            cur.execute("SET SESSION TRANSACTION READ ONLY")
+            cur.execute("START TRANSACTION READ ONLY")
+        cur.execute(sql, params or None)
+        if write:
+            db.commit()
+            return [], [], None, cur.rowcount
+        cols = [d[0] for d in cur.description] if cur.description else []
+        rows = cur.fetchmany(limit + 1) if cur.description else []
+        db.rollback()
+        return cols, list(rows)[:limit], (limit + 1 if len(rows) > limit else len(rows)), None
+    except Exception as e:
+        raise ToolError(f"MySQL error: {e}")
+    finally:
+        db.close()
+
+
+RUNNERS = {"sqlite": _run_sqlite, "postgres": _run_postgres, "mysql": _run_mysql}
+
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$")
+
+
+def helper_sql(kind: str, action: str, table: Optional[str]) -> Tuple[str, List[Any]]:
+    if action == "list_tables":
+        if kind == "sqlite":
+            return ("SELECT name, type FROM sqlite_master WHERE type IN ('table','view') "
+                    "AND name NOT LIKE 'sqlite_%' ORDER BY name"), []
+        if kind == "postgres":
+            return ("SELECT table_schema, table_name, table_type FROM information_schema.tables "
+                    "WHERE table_schema NOT IN ('pg_catalog','information_schema') "
+                    "ORDER BY table_schema, table_name"), []
+        return ("SELECT table_name, table_type FROM information_schema.tables "
+                "WHERE table_schema = DATABASE() ORDER BY table_name"), []
+    if not table or not _IDENT.match(table):
+        raise ToolError("`table` must be a plain table name (optionally schema.table).")
+    schema, _, name = table.rpartition(".")
+    if kind == "sqlite":
+        return f"SELECT cid, name, type, \"notnull\", dflt_value, pk FROM pragma_table_info('{name}')", []
+    ph = "%s"
+    if kind == "postgres":
+        sql = ("SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns "
+               f"WHERE table_name = {ph}" + (f" AND table_schema = {ph}" if schema else "") + " ORDER BY ordinal_position")
+        return sql, [name] + ([schema] if schema else [])
+    sql = ("SELECT column_name, column_type, is_nullable, column_key, column_default FROM information_schema.columns "
+           f"WHERE table_name = {ph} AND table_schema = " + (ph if schema else "DATABASE()") + " ORDER BY ordinal_position")
+    return sql, [name] + ([schema] if schema else [])
+
+
+class DbQuery(Tool):
+    name = "db_query"
+    description = (
+        "Explore a database: a SQLite file in the project, or a Postgres/MySQL connection the user "
+        "configured by name. action `list_tables`, `describe` (needs `table`), or `query` (needs `sql`). "
+        "Read-only: only SELECT/WITH/EXPLAIN/SHOW/PRAGMA unless the user enabled writes. Results are "
+        "capped (default 200 rows); add LIMIT to large queries."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string", "enum": ["query", "list_tables", "describe"]},
+            "database": {"type": "string", "description": "Connection name from settings, or a path to a SQLite file."},
+            "sql": {"type": "string"},
+            "table": {"type": "string"},
+        },
+        "required": ["action"],
+    }
+
+    def _plan(self, args, ctx):
+        action = args.get("action") or ("query" if args.get("sql") else "list_tables")
+        conn = resolve_connection(args.get("database"), ctx)
+        if action == "query":
+            sql = args.get("sql")
+            if not isinstance(sql, str) or not sql.strip():
+                raise ToolError("action `query` needs `sql`.")
+            ok, reason = check_read_only(sql)
+            write = not ok
+            if write and not (ctx.settings.get("db") or {}).get("allowWrites"):
+                raise ToolError(
+                    f"Rejected: this database tool is read-only ({reason}). The user can allow writes with "
+                    "`euron config set db.allowWrites true`; each write still asks for permission."
+                )
+            return action, conn, sql, [], write
+        if action not in ("list_tables", "describe"):
+            raise ToolError("action must be query, list_tables or describe.")
+        sql, params = helper_sql(conn.kind, action, args.get("table"))
+        return action, conn, sql, params, False
+
+    def permission(self, args, ctx):
+        _, conn, sql, _, write = self._plan(args, ctx)
+        paths = [Path(conn.target)] if conn.kind == "sqlite" else []
+        return Request("DbWrite" if write else "Db", self.name, paths=paths, command=sql)
+
+    def describe(self, args, ctx):
+        a = args.get("action") or "query"
+        what = args.get("sql") or args.get("table") or ""
+        return f"{a} {args.get('database') or ''} {what}".strip()[:160]
+
+    def preview(self, args, ctx):
+        _, conn, sql, _, write = self._plan(args, ctx)
+        return f"{'WRITE to' if write else 'Read'} {conn.kind} database {conn.label}:\n{sql}"
+
+    def run(self, args, ctx):
+        action, conn, sql, params, write = self._plan(args, ctx)
+        limit = max(1, min(opt_int(args, "limit", None) or int((ctx.settings.get("db") or {}).get("maxRows") or 200), 1000))
+        cols, rows, total, affected = RUNNERS[conn.kind](conn, sql, params, write, limit)
+        if write:
+            return ToolResult(f"Statement executed on {conn.label}. Rows affected: {affected}.")
+        body = format_table(cols, rows, total, limit)
+        return ToolResult(truncate(body, ctx.max_output_chars, "add LIMIT or select fewer columns"),
+                          preview=f"{len(rows)} rows")