execpad 0.1.0__py3-none-any.whl

execpad/__init__.py

@@ -0,0 +1,13 @@
+from execpad.run_log import export_run_log_json, export_run_log_markdown
+from execpad.runtime import Runtime
+from execpad.types import FileChange, RunLogEntry, RunResult, SerializedRuntime
+
+__all__ = [
+    "Runtime",
+    "RunResult",
+    "RunLogEntry",
+    "FileChange",
+    "SerializedRuntime",
+    "export_run_log_json",
+    "export_run_log_markdown",
+]

execpad/engines.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from execpad.types import RunResult
+
+
+def _truncate(stdout: str, stderr: str, max_bytes: int | None) -> tuple[str, str, bool]:
+    if max_bytes is None or max_bytes <= 0:
+        return stdout, stderr, False
+    if len(stdout) + len(stderr) <= max_bytes:
+        return stdout, stderr, False
+    budget = max_bytes
+    if len(stdout) > budget:
+        return stdout[:budget] + "\n...[truncated]", "", True
+    budget -= len(stdout)
+    err = stderr[:budget] + "\n...[truncated]" if len(stderr) > budget else stderr
+    return stdout, err, True
+
+
+def run_subprocess(
+    argv: list[str],
+    cwd: str,
+    env: dict[str, str] | None,
+    timeout_s: float,
+    max_output_bytes: int | None,
+) -> RunResult:
+    start = time.perf_counter()
+    try:
+        p = subprocess.run(
+            argv,
+            cwd=cwd,
+            env={**__import__("os").environ, **(env or {})},
+            capture_output=True,
+            text=True,
+            timeout=timeout_s,
+        )
+        out, err, trunc = _truncate(p.stdout or "", p.stderr or "", max_output_bytes)
+        return RunResult(
+            stdout=out,
+            stderr=err,
+            exit_code=p.returncode,
+            duration_ms=(time.perf_counter() - start) * 1000,
+            files=[],
+            truncated=trunc,
+        )
+    except subprocess.TimeoutExpired as e:
+        out, err, trunc = _truncate(
+            (e.stdout or "") if isinstance(e.stdout, str) else "",
+            (e.stderr or "") if isinstance(e.stderr, str) else "",
+            max_output_bytes,
+        )
+        return RunResult(
+            stdout=out,
+            stderr=err or "timeout",
+            exit_code=124,
+            duration_ms=(time.perf_counter() - start) * 1000,
+            files=[],
+            truncated=trunc,
+        )
+    except FileNotFoundError as e:
+        return RunResult(
+            stdout="",
+            stderr=str(e),
+            exit_code=127,
+            duration_ms=(time.perf_counter() - start) * 1000,
+            files=[],
+            truncated=False,
+        )
+
+
+def run_bash(code: str, cwd: str, env: dict[str, str] | None, timeout_s: float, max_out: int | None) -> RunResult:
+    bash = shutil.which("bash") or "bash"
+    return run_subprocess([bash, "-c", code], cwd, env, timeout_s, max_out)
+
+
+def run_python(code: str, cwd: str, env: dict[str, str] | None, timeout_s: float, max_out: int | None) -> RunResult:
+    py = shutil.which("python3") or shutil.which("python") or "python3"
+    return run_subprocess([py, "-c", code], cwd, env, timeout_s, max_out)
+
+
+def run_javascript(code: str, cwd: str, env: dict[str, str] | None, timeout_s: float, max_out: int | None) -> RunResult:
+    node = shutil.which("node") or "node"
+    return run_subprocess([node, "-e", code], cwd, env, timeout_s, max_out)
+
+
+def run_sql(code: str, cwd: str, env: dict[str, str] | None, timeout_s: float, max_out: int | None) -> RunResult:
+    import sqlite3
+
+    _ = cwd, env, timeout_s  # SQL runs in-memory; cwd reserved for attach extensions
+    start = time.perf_counter()
+    try:
+        con = sqlite3.connect(":memory:")
+        cur = con.cursor()
+        parts = [s.strip() for s in code.split(";") if s.strip()]
+        out_lines: list[str] = []
+        for stmt in parts:
+            cur.execute(stmt)
+            if cur.description:
+                rows = cur.fetchall()
+                out_lines.extend(str(r) for r in rows)
+            else:
+                con.commit()
+        con.close()
+        out = "\n".join(out_lines) + ("\n" if out_lines else "")
+        out, err, trunc = _truncate(out, "", max_out)
+        return RunResult(
+            stdout=out,
+            stderr=err,
+            exit_code=0,
+            duration_ms=(time.perf_counter() - start) * 1000,
+            files=[],
+            truncated=trunc,
+        )
+    except Exception as e:  # noqa: BLE001
+        return RunResult(
+            stdout="",
+            stderr=str(e),
+            exit_code=1,
+            duration_ms=(time.perf_counter() - start) * 1000,
+            files=[],
+            truncated=False,
+        )

execpad/extensions/globs.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+
+def _excluded(rel: str, exclude_globs: list[str]) -> bool:
+    parts = rel.replace("\\", "/").split("/")
+    if "node_modules" in parts or ".git" in parts:
+        return True
+    posix = rel.replace("\\", "/")
+    return any(fnmatch.fnmatch(posix, g) for g in exclude_globs)
+
+
+def list_matching_rel_paths(
+    root: str | Path,
+    include_globs: list[str],
+    exclude_globs: list[str] | None = None,
+) -> list[str]:
+    exclude_globs = exclude_globs or []
+    rootp = Path(root).resolve()
+    rels: list[str] = []
+    for p in rootp.rglob("*"):
+        if not p.is_file():
+            continue
+        rel = str(p.relative_to(rootp)).replace("\\", "/")
+        if _excluded(rel, exclude_globs):
+            continue
+        posix = rel
+        if not include_globs:
+            rels.append(rel)
+            continue
+        if any(fnmatch.fnmatch(posix, g) for g in include_globs):
+            rels.append(rel)
+    return rels

execpad/run_log.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+from execpad.types import RunLogEntry
+
+
+def export_run_log_json(entries: list[RunLogEntry], *, pretty: bool = True) -> str:
+    payload = [
+        {
+            "id": e.id,
+            "at": e.at,
+            "language": e.language,
+            "code": e.code,
+            "cwd": e.cwd,
+            "exitCode": e.exit_code,
+            "durationMs": e.duration_ms,
+            "stdout": e.stdout,
+            "stderr": e.stderr,
+            "truncated": e.truncated,
+            "files": [{"path": f.path, "type": f.type, "size": f.size} for f in e.files],
+        }
+        for e in entries
+    ]
+    return json.dumps(payload, indent=2 if pretty else None)
+
+
+def export_run_log_markdown(entries: list[RunLogEntry]) -> str:
+    lines: list[str] = ["# execpad session log", ""]
+    for e in entries:
+        ts = datetime.fromtimestamp(e.at / 1000, tz=timezone.utc).isoformat()
+        lines.append(f"## {e.id} — {e.language} @ {ts}")
+        lines.append("")
+        lines.append(
+            f"- **exit:** {e.exit_code} · **duration:** {e.duration_ms}ms · **truncated:** {e.truncated}"
+        )
+        lines.append(f"- **cwd:** `{e.cwd}`")
+        if e.files:
+            parts = [f"{f.type}:{f.path}" for f in e.files]
+            lines.append(f"- **files:** {', '.join(parts)}")
+        lines.extend(["", "### code", "", "```", e.code, "```", "", "### stdout", "", "```", e.stdout or "(empty)", "```"])
+        lines.extend(["", "### stderr", "", "```", e.stderr or "(empty)", "```", ""])
+    return "\n".join(lines)

execpad/runtime.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from execpad.engines import run_bash, run_javascript, run_python, run_sql
+from execpad.extensions.globs import list_matching_rel_paths
+from execpad.types import FileChange, Language, RunLogEntry, RunResult, SerializedRuntime
+
+
+def _cp_tree(src: Path, dest: Path) -> None:
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest, dirs_exist_ok=True)
+
+
+def _merge_overlay_to_root(work: Path, root: Path) -> None:
+    for p in work.rglob("*"):
+        if p.is_file():
+            rel = p.relative_to(work)
+            out = root / rel
+            out.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(p, out)
+
+
+def _snapshot_tree(root: Path, rels: list[str]) -> dict[str, tuple[float, int]]:
+    m: dict[str, tuple[float, int]] = {}
+    for rel in rels:
+        p = root / rel
+        if p.is_file():
+            st = p.stat()
+            m[rel] = (st.st_mtime, st.st_size)
+    return m
+
+
+def _diff_tree(root: Path, before: dict[str, tuple[float, int]], rels: list[str]) -> list[FileChange]:
+    changes: list[FileChange] = []
+    for rel in rels:
+        p = root / rel
+        if not p.is_file():
+            if rel in before:
+                changes.append(FileChange(path=rel, type="deleted", size=0))
+            continue
+        st = p.stat()
+        prev = before.get(rel)
+        if prev is None:
+            changes.append(FileChange(path=rel, type="created", size=st.st_size))
+        elif prev[0] != st.st_mtime or prev[1] != st.st_size:
+            changes.append(FileChange(path=rel, type="modified", size=st.st_size))
+    return changes
+
+
+class Runtime:
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        readonly: bool = False,
+        overlay: bool = False,
+        limits: dict[str, Any] | None = None,
+        files: dict[str, str] | None = None,
+        include_globs: list[str] | None = None,
+        exclude_globs: list[str] | None = None,
+        run_log: bool = True,
+        run_log_max_entries: int = 200,
+        on_run: Callable[[RunLogEntry], None] | None = None,
+    ) -> None:
+        self.root = Path(root).resolve()
+        self._readonly = readonly
+        self._overlay = overlay
+        self._limits = limits or {}
+        self._include = include_globs
+        self._exclude = exclude_globs or ["**/node_modules/**", "**/.git/**"]
+        self._owns_workdir = overlay
+        self._run_log_enabled = run_log
+        self._run_log_max = max(1, int(run_log_max_entries))
+        self._on_run = on_run
+        self._run_log: list[RunLogEntry] = []
+        self._log_seq = 0
+        if overlay:
+            self._workdir = Path(tempfile.mkdtemp(prefix="execpad-"))
+            _cp_tree(self.root, self._workdir)
+        else:
+            self._workdir = self.root
+        if files:
+            for rel, content in files.items():
+                p = self._workdir / rel
+                p.parent.mkdir(parents=True, exist_ok=True)
+                p.write_text(content, encoding="utf8")
+
+    @property
+    def effective_root(self) -> Path:
+        return self._workdir
+
+    def _timeout_s(self) -> float:
+        return float(self._limits.get("timeout_ms", 30_000)) / 1000.0
+
+    def _max_out(self) -> int | None:
+        return self._limits.get("max_output_bytes")
+
+    def _glob_scope(self) -> list[str]:
+        inc = self._include or ["**/*"]
+        return list_matching_rel_paths(self._workdir, inc, self._exclude)
+
+    def run(
+        self,
+        language: Language,
+        code: str,
+        *,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> RunResult:
+        wd = (self._workdir / (cwd or ".")).resolve()
+        if not str(wd).startswith(str(self._workdir.resolve())):
+            raise ValueError("cwd escapes workspace")
+        timeout_s = self._timeout_s()
+        max_out = self._max_out()
+        before = _snapshot_tree(self._workdir, self._glob_scope())
+        if language == "bash":
+            r = run_bash(code, str(wd), env, timeout_s, max_out)
+        elif language == "python":
+            r = run_python(code, str(wd), env, timeout_s, max_out)
+        elif language == "javascript":
+            r = run_javascript(code, str(wd), env, timeout_s, max_out)
+        elif language == "sql":
+            r = run_sql(code, str(wd), env, timeout_s, max_out)
+        else:
+            raise ValueError(f"Unknown language: {language}")
+        after_rels = list_matching_rel_paths(self._workdir, ["**/*"], self._exclude)
+        r.files = _diff_tree(self._workdir, before, after_rels)
+        if self._run_log_enabled:
+            self._log_seq += 1
+            entry = RunLogEntry(
+                id=f"run-{self._log_seq}",
+                at=time.time() * 1000,
+                language=language,
+                code=code,
+                cwd=str(wd),
+                exit_code=r.exit_code,
+                duration_ms=r.duration_ms,
+                stdout=r.stdout,
+                stderr=r.stderr,
+                truncated=r.truncated,
+                files=list(r.files),
+            )
+            self._run_log.append(entry)
+            while len(self._run_log) > self._run_log_max:
+                self._run_log.pop(0)
+            if self._on_run:
+                self._on_run(entry)
+        return r
+
+    def get_run_log(self) -> list[RunLogEntry]:
+        return list(self._run_log)
+
+    def clear_run_log(self) -> None:
+        self._run_log.clear()
+
+    def apply(self) -> None:
+        if not self._overlay:
+            raise RuntimeError("apply() only valid in overlay mode")
+        _merge_overlay_to_root(self._workdir, self.root)
+
+    def close(self) -> None:
+        if self._owns_workdir and self._workdir.exists():
+            shutil.rmtree(self._workdir, ignore_errors=True)
+
+    def serialize(self) -> SerializedRuntime:
+        writes: dict[str, str] = {}
+        if self._overlay:
+            for p in self._workdir.rglob("*"):
+                if p.is_file():
+                    rel = str(p.relative_to(self._workdir)).replace("\\", "/")
+                    writes[rel] = p.read_text(encoding="utf8", errors="replace")
+        return SerializedRuntime(
+            version=1,
+            root=str(self.root),
+            readonly=self._readonly,
+            overlay=self._overlay,
+            overlay_writes=writes,
+        )
+
+    @staticmethod
+    def deserialize(data: SerializedRuntime) -> Runtime:
+        if data.version != 1:
+            raise ValueError("Unsupported version")
+        return Runtime(
+            data.root,
+            overlay=data.overlay,
+            readonly=data.readonly,
+            files=data.overlay_writes if data.overlay and data.overlay_writes else None,
+        )
+
+    def fs_write(self, rel: str, content: str) -> None:
+        if self._readonly:
+            raise OSError("read-only")
+        p = self._workdir / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf8")
+
+    def fs_read(self, rel: str) -> str:
+        return (self._workdir / rel).read_text(encoding="utf8")
+
+    def as_openai_tool(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": "execute_code",
+                "description": "Execute code in workspace (bash, python, javascript, sql).",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "language": {
+                            "type": "string",
+                            "enum": ["bash", "python", "javascript", "sql"],
+                        },
+                        "code": {"type": "string"},
+                    },
+                    "required": ["language", "code"],
+                },
+            },
+        }
+
+    def execute_tool_call(self, args: dict[str, Any]) -> RunResult:
+        return self.run(args["language"], args["code"])

execpad/types.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+Language = Literal["bash", "python", "javascript", "sql"]
+
+
+@dataclass
+class FileChange:
+    path: str
+    type: Literal["created", "modified", "deleted"]
+    size: int
+
+
+@dataclass
+class RunResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_ms: float
+    files: list[FileChange] = field(default_factory=list)
+    truncated: bool = False
+
+
+@dataclass
+class RunLogEntry:
+    id: str
+    at: float
+    language: Language
+    code: str
+    cwd: str
+    exit_code: int
+    duration_ms: float
+    stdout: str
+    stderr: str
+    truncated: bool
+    files: list[FileChange]
+
+
+@dataclass
+class SerializedRuntime:
+    version: int
+    root: str
+    readonly: bool
+    overlay: bool
+    overlay_writes: dict[str, str]

execpad-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: execpad
+Version: 0.1.0
+Summary: Multi-language code execution against a real directory for AI agents
+Author: slaps.dev
+License-Expression: Apache-2.0
+Keywords: agents,ai,bash,ci,code-execution,nodejs,openai,python,sandbox,sqlite,subprocess,tool-calling
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# execpad
+
+Execute **bash**, **Python**, **JavaScript** (Node), and **SQL** against a **real project directory**—with optional overlay, read-only mode, file-change tracking, and a session run log. Built for **AI agents**, CI, and local tooling.
+
+Same design in **TypeScript** (npm) and **Python** (PyPI / local install).
+
+---
+
+## Install
+
+### JavaScript / TypeScript (npm)
+
+```bash
+npm install execpad
+```
+
+Requires **Node.js ≥ 18**. For SQL on Node, the **`sqlite3`** binary must be on your `PATH`.
+
+### Python
+
+```bash
+pip install execpad
+```
+
+From a clone (editable):
+
+```bash
+pip install -e ./python
+```
+
+Requires **Python ≥ 3.10**. For SQL in Python, the runtime uses **stdlib `sqlite3`** (no `sqlite3` CLI required).
+
+---
+
+## Quick start
+
+### TypeScript
+
+```ts
+import { Runtime } from "execpad";
+
+const rt = new Runtime("./my-project");
+const r = await rt.run("python", 'print(open("README.md").read()[:80])');
+console.log(r.stdout);
+console.log(r.files); // file changes under the workspace
+rt.close();
+```
+
+### Python
+
+```python
+from execpad import Runtime
+
+rt = Runtime("./my-project")
+r = rt.run("python", "print(1 + 1)")
+print(r.stdout)
+rt.close()
+```
+
+---
+
+## Features
+
+| Capability | Summary |
+|------------|---------|
+| **Languages** | `bash`, `python`, `javascript`, `sql` |
+| **Workspace modes** | Normal, **read-only** (`readonly: true`), or **overlay** (temp copy + `apply()` back to disk) |
+| **File tracking** | `includeGlobs` / `excludeGlobs` (minimatch) scope which paths appear in `RunResult.files` |
+| **Limits** | `timeoutMs`, `maxOutputBytes` per run or via `limits` on the runtime |
+| **Session log** | `getRunLog()`, `clearRunLog()`, `exportRunLogJSON` / `exportRunLogMarkdown`, optional `onRun` |
+| **OpenAI tools** | `asOpenAITool()` + `executeToolCall({ language, code })` (TS); `as_openai_tool` / `execute_tool_call` (Python) |
+| **Persistence** | `serialize()` / `Runtime.deserialize()` for overlay state |
+
+---
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [Getting started](docs/getting-started.md) | Install, first runs, overlay, read-only |
+| [Configuration](docs/configuration.md) | `RuntimeOptions`, `RunOptions`, globs, limits, run log |
+| [API reference](docs/api-reference.md) | `Runtime`, types, filesystem adapters, exports |
+| [Security](docs/security.md) | Threat model, workspace boundaries, subprocess behavior |
+| [Python notes](docs/python.md) | Node vs Python differences |
+
+---
+
+## License
+
+Apache-2.0

execpad-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+execpad/__init__.py,sha256=4R48vDjQr9kKnv4lhOlh5AxezQMnLfuzCfK3-4sL6pw,356
+execpad/engines.py,sha256=g-98GzN-cOMsygCVtRbCGvQso4AW9TiEkobQj7o57H4,4189
+execpad/run_log.py,sha256=FSEDM1D5vaedR49ipp-Y8693PgeD1NCFwkluWOIzNTU,1617
+execpad/runtime.py,sha256=6M64Si-hPx7jt5ng7ccKVQS1xCZpp2WYszsgxPQIjII,8061
+execpad/types.py,sha256=AkwwJgrs-hYOR3KccHE4aL-cL9bf-lrrk351sMOAYHw,845
+execpad/extensions/globs.py,sha256=llBOKing9Y6lSGG7Keo8bPQAeKepUUqhJI51nxZuHzo,1008
+execpad-0.1.0.dist-info/METADATA,sha256=0j83N3Jom48LS7W-tvksuSq5OV6J7hqzHYXzhtdXetY,2882
+execpad-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+execpad-0.1.0.dist-info/RECORD,,

execpad-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any