pyddock 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. {pyddock-0.1.0 → pyddock-0.2.0}/.gitignore +1 -4
  2. {pyddock-0.1.0 → pyddock-0.2.0}/PKG-INFO +3 -3
  3. {pyddock-0.1.0 → pyddock-0.2.0}/README.md +2 -2
  4. pyddock-0.2.0/publish-to-pypi.ps1 +27 -0
  5. {pyddock-0.1.0 → pyddock-0.2.0}/pyproject.toml +1 -1
  6. pyddock-0.2.0/src/pyddock/__init__.py +10 -0
  7. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/_runtime.py +47 -13
  8. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/executor.py +1 -1
  9. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/server.py +2 -2
  10. pyddock-0.2.0/src/pyddock/venv_manager.py +389 -0
  11. pyddock-0.2.0/tests/test_chmod_integration.py +325 -0
  12. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_executor.py +1 -1
  13. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_file_tools.py +2 -2
  14. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_subst_trusted_path.py +1 -1
  15. pyddock-0.2.0/tests/test_venv_stamp.py +245 -0
  16. {pyddock-0.1.0 → pyddock-0.2.0}/uv.lock +1 -1
  17. pyddock-0.1.0/src/pyddock/__init__.py +0 -8
  18. pyddock-0.1.0/src/pyddock/venv_manager.py +0 -196
  19. {pyddock-0.1.0 → pyddock-0.2.0}/LICENSE +0 -0
  20. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/_process_utils.py +0 -0
  21. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/ast_validator.py +0 -0
  22. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/cli.py +0 -0
  23. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/config.py +0 -0
  24. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/default_config.toml +0 -0
  25. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/script_registry.py +0 -0
  26. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/shell_executor.py +0 -0
  27. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/tools/__init__.py +0 -0
  28. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/tools/fs_append.py +0 -0
  29. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/tools/fs_delete.py +0 -0
  30. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/tools/read_file.py +0 -0
  31. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/tools/stat_file.py +0 -0
  32. {pyddock-0.1.0 → pyddock-0.2.0}/src/pyddock/tools/str_replace.py +0 -0
  33. {pyddock-0.1.0 → pyddock-0.2.0}/tests/__init__.py +0 -0
  34. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_ast_properties.py +0 -0
  35. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_config.py +0 -0
  36. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_filesystem_guards.py +0 -0
  37. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_proxy_properties.py +0 -0
  38. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_realistic.py +0 -0
  39. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_runtime.py +0 -0
  40. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_security_guards.py +0 -0
  41. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_server.py +0 -0
  42. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_shell_arg_paths.py +0 -0
  43. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_shell_executor.py +0 -0
  44. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_shell_properties.py +0 -0
  45. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_subprocess_enforcement.py +0 -0
  46. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_subprocess_properties.py +0 -0
  47. {pyddock-0.1.0 → pyddock-0.2.0}/tests/test_workspace_imports.py +0 -0
@@ -10,7 +10,7 @@ build/
10
10
 
11
11
  # Virtual environments
12
12
  .venv/
13
- .pyddock/venv/
13
+ .pyddock/
14
14
 
15
15
  # IDE
16
16
  .idea/
@@ -27,6 +27,3 @@ Thumbs.db
27
27
  .pytest_cache/
28
28
  .coverage
29
29
  htmlcov/
30
-
31
- # Temp
32
- .pyddock/tmp/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pyddock
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls
5
5
  Project-URL: Homepage, https://github.com/portablestew/pyddock
6
6
  Project-URL: Repository, https://github.com/portablestew/pyddock
@@ -55,7 +55,7 @@ pyddock provides Python execution and shell command access with declarative poli
55
55
  "pyddock": {
56
56
  "command": "uvx",
57
57
  "args": ["pyddock", "serve", "--workspace", "<path-to-workspace>"],
58
- "autoApprove": ["run_python","run_shell","fs_read","fs_stat","fs_append","fs_delete","fs_str_replace"]
58
+ "autoApprove": ["run_python","run_shell","fs_readfile","fs_stat","fs_append","fs_delete","fs_str_replace"]
59
59
  }
60
60
  }
61
61
  }
@@ -107,7 +107,7 @@ Warning: deprecated API
107
107
 
108
108
  Pyddock also exposes file I/O tools that execute through the same sandbox as `run_python` — same filesystem scoping, same protected directories, same policy enforcement. These are convenience shortcuts for common file operations; agents can't do anything they couldn't already do via `run_python` with `pathlib`. On failure, error messages include diagnostic context to guide the agent's next attempt.
109
109
 
110
- - **`fs_read`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
110
+ - **`fs_readfile`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
111
111
  - **`fs_stat`** — File metadata (exists, type, size, line count, modified). Returns `exists: false` for missing paths.
112
112
  - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
113
113
  - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
@@ -31,7 +31,7 @@ pyddock provides Python execution and shell command access with declarative poli
31
31
  "pyddock": {
32
32
  "command": "uvx",
33
33
  "args": ["pyddock", "serve", "--workspace", "<path-to-workspace>"],
34
- "autoApprove": ["run_python","run_shell","fs_read","fs_stat","fs_append","fs_delete","fs_str_replace"]
34
+ "autoApprove": ["run_python","run_shell","fs_readfile","fs_stat","fs_append","fs_delete","fs_str_replace"]
35
35
  }
36
36
  }
37
37
  }
@@ -83,7 +83,7 @@ Warning: deprecated API
83
83
 
84
84
  Pyddock also exposes file I/O tools that execute through the same sandbox as `run_python` — same filesystem scoping, same protected directories, same policy enforcement. These are convenience shortcuts for common file operations; agents can't do anything they couldn't already do via `run_python` with `pathlib`. On failure, error messages include diagnostic context to guide the agent's next attempt.
85
85
 
86
- - **`fs_read`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
86
+ - **`fs_readfile`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
87
87
  - **`fs_stat`** — File metadata (exists, type, size, line count, modified). Returns `exists: false` for missing paths.
88
88
  - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
89
89
  - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
@@ -0,0 +1,27 @@
1
+ # publish-to-pypi.ps1 - Publish to PyPI: clean, build, upload to testpypi, then pypi.
2
+
3
+ $ErrorActionPreference = "Stop"
4
+
5
+ # Clean dist
6
+ Write-Host "Cleaning dist/..."
7
+ if (Test-Path dist) { Remove-Item -Recurse -Force dist }
8
+
9
+ # Build
10
+ Write-Host "> uv build"
11
+ uv build
12
+ if ($LASTEXITCODE -ne 0) { throw "Build failed" }
13
+
14
+ # Upload to testpypi
15
+ Write-Host "> uvx twine upload --repository testpypi dist/*"
16
+ uvx twine upload --repository testpypi dist/*
17
+ if ($LASTEXITCODE -ne 0) { throw "testpypi upload failed" }
18
+
19
+ # Pause for confirmation
20
+ Read-Host "`nUploaded to testpypi. Press Enter to upload to pypi (Ctrl+C to abort)"
21
+
22
+ # Upload to pypi
23
+ Write-Host "> uvx twine upload --repository pyddock dist/*"
24
+ uvx twine upload --repository pyddock dist/*
25
+ if ($LASTEXITCODE -ne 0) { throw "pypi upload failed" }
26
+
27
+ Write-Host "`nDone!"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pyddock"
3
- version = "0.1.0"
3
+ version = "0.2.0"
4
4
  description = "MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls"
5
5
  requires-python = ">=3.11"
6
6
  license = "MIT"
@@ -0,0 +1,10 @@
1
+ """pyddock — policy-controlled Python execution via MCP."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("pyddock")
7
+ except PackageNotFoundError:
8
+ # Running inside the sandbox subprocess where pyddock is on sys.path
9
+ # but not installed as a package (no dist-info metadata).
10
+ __version__ = "0.0.0"
@@ -21,7 +21,11 @@ import tempfile as _tempfile_module
21
21
  import types
22
22
  from typing import Any
23
23
 
24
- from pyddock import SNIPPET_FILENAME
24
+ # Filename used for compile() when executing agent snippets.
25
+ # Defined here (not in __init__.py) so _runtime.py doesn't need to import
26
+ # the pyddock package — which would trigger importlib.metadata inside the
27
+ # sandbox subprocess where pyddock isn't installed as a package.
28
+ SNIPPET_FILENAME = "<snippet>"
25
29
 
26
30
  # Resolved at module load time (before the import hook activates).
27
31
  # Used by _caller_is_trusted to skip pyddock's own frames.
@@ -1345,25 +1349,46 @@ class RuntimeEnforcement:
1345
1349
  f"Hard link creation is disabled to prevent filesystem bypass."
1346
1350
  )
1347
1351
 
1348
- def _blocked_chmod(self_path: pathlib.Path, *args: Any, **kwargs: Any) -> None:
1349
- raise PermissionError(
1350
- f"PermissionError: Path.chmod() is not permitted. "
1351
- f"Permission changes are disabled."
1352
- )
1352
+ # chmod validation: block special bits (setuid/setgid/sticky) which
1353
+ # change how the OS treats the file. Standard permission bits (owner,
1354
+ # group, other rwx) are allowed — _check_write() already controls
1355
+ # which files can be modified at all.
1356
+ _CHMOD_SPECIAL_BITS = 0o7000
1353
1357
 
1354
- def _blocked_lchmod(self_path: pathlib.Path, *args: Any, **kwargs: Any) -> None:
1355
- raise PermissionError(
1356
- f"PermissionError: Path.lchmod() is not permitted. "
1357
- f"Permission changes are disabled."
1358
- )
1358
+ def _validate_chmod(mode: int, caller: str) -> None:
1359
+ """Reject non-integer or special-bit modes."""
1360
+ if not isinstance(mode, int):
1361
+ raise PermissionError(
1362
+ f"PermissionError: {caller} mode must be an integer."
1363
+ )
1364
+ if mode & _CHMOD_SPECIAL_BITS:
1365
+ raise PermissionError(
1366
+ f"PermissionError: {caller} mode {oct(mode)} requests "
1367
+ f"special bits ({oct(mode & _CHMOD_SPECIAL_BITS)}). "
1368
+ f"setuid/setgid/sticky are not permitted."
1369
+ )
1370
+
1371
+ _ORIGINALS["Path.chmod"] = pathlib.Path.chmod
1372
+ if hasattr(pathlib.Path, "lchmod"):
1373
+ _ORIGINALS["Path.lchmod"] = pathlib.Path.lchmod
1374
+
1375
+ def _guarded_chmod(self_path: pathlib.Path, mode: int, *args: Any, **kwargs: Any) -> None:
1376
+ _validate_chmod(mode, "Path.chmod()")
1377
+ _check_write(self_path)
1378
+ return _ORIGINALS["Path.chmod"](self_path, mode, *args, **kwargs)
1379
+
1380
+ def _guarded_lchmod(self_path: pathlib.Path, mode: int, *args: Any, **kwargs: Any) -> None:
1381
+ _validate_chmod(mode, "Path.lchmod()")
1382
+ _check_write(self_path)
1383
+ return _ORIGINALS["Path.lchmod"](self_path, mode, *args, **kwargs)
1359
1384
 
1360
1385
  pathlib.Path.symlink_to = _blocked_symlink_to
1361
1386
  pathlib.Path.hardlink_to = _blocked_hardlink_to
1362
1387
  if hasattr(pathlib.Path, "link_to"):
1363
1388
  pathlib.Path.link_to = _blocked_link_to
1364
- pathlib.Path.chmod = _blocked_chmod
1389
+ pathlib.Path.chmod = _guarded_chmod
1365
1390
  if hasattr(pathlib.Path, "lchmod"):
1366
- pathlib.Path.lchmod = _blocked_lchmod
1391
+ pathlib.Path.lchmod = _guarded_lchmod
1367
1392
 
1368
1393
  # Patch io.open — it's a separate function from builtins.open
1369
1394
  # and can bypass filesystem scoping if not patched.
@@ -1485,6 +1510,15 @@ class RuntimeEnforcement:
1485
1510
  safe_os.makedirs = _safe_makedirs
1486
1511
  safe_os.mkdir = _safe_mkdir
1487
1512
 
1513
+ # Expose os.chmod with the same validation as Path.chmod.
1514
+ def _safe_chmod(path: str, mode: int) -> None:
1515
+ _validate_chmod(mode, "os.chmod()")
1516
+ _check_write(pathlib.Path(path))
1517
+ _real_os.chmod(path, mode)
1518
+
1519
+ if "os" in sys.modules:
1520
+ sys.modules["os"].chmod = _safe_chmod
1521
+
1488
1522
  def apply_restrictions(self) -> None:
1489
1523
  """Apply module-level and class-level restrictions.
1490
1524
 
@@ -12,7 +12,7 @@ import tempfile
12
12
  from dataclasses import dataclass
13
13
  from pathlib import Path
14
14
 
15
- from pyddock import SNIPPET_FILENAME
15
+ from pyddock._runtime import SNIPPET_FILENAME
16
16
  from pyddock.config import PyddockConfig
17
17
  from pyddock._process_utils import get_startupinfo, kill_and_drain, make_child_env, truncate_output
18
18
  from pyddock.venv_manager import VenvManager
@@ -266,8 +266,8 @@ def create_server(workspace: Path | None = None) -> FastMCP:
266
266
  "Omit start/end for the whole file. Fails on binary/non-UTF-8 files."
267
267
  )
268
268
 
269
- @mcp.tool(name="fs_read", description=_read_file_desc)
270
- async def fs_read(
269
+ @mcp.tool(name="fs_readfile", description=_read_file_desc)
270
+ async def fs_readfile(
271
271
  path: str,
272
272
  start: int | None = None,
273
273
  end: int | None = None,
@@ -0,0 +1,389 @@
1
+ """Virtual environment manager for pyddock.
2
+
3
+ Creates and manages a venv at `.pyddock/venv/`, auto-installs allowed
4
+ third-party packages, and exposes the venv Python path for subprocess use.
5
+
6
+ Uses a stamp file (.pyddock/venv/installed.json) to skip redundant install
7
+ checks on subsequent boots. The stamp records:
8
+ - venv_created: creation timestamp of pyvenv.cfg (detects venv recreation)
9
+ - allowlist_hash: hash of sorted allowlist + pip_packages (detects config changes)
10
+ - workspace: {module_name: hash_of_pyproject_toml} (detects metadata changes)
11
+
12
+ If the stamp is missing, corrupt, or stale, a full install pass runs (same as
13
+ the previous always-install behavior) and a fresh stamp is written.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import hashlib
19
+ import json
20
+ import logging
21
+ import subprocess
22
+ import sys
23
+ import venv
24
+ from pathlib import Path
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+ # Name of the stamp file inside the venv directory.
29
+ _STAMP_FILENAME = "installed.json"
30
+
31
+
32
+ class VenvError(Exception):
33
+ """Raised when venv creation or package installation fails."""
34
+
35
+
36
+ def _hash_string(s: str) -> str:
37
+ """Return a short hex digest of a string (SHA-256, first 16 hex chars)."""
38
+ return hashlib.sha256(s.encode("utf-8")).hexdigest()[:16]
39
+
40
+
41
+ def _hash_file(path: Path) -> str:
42
+ """Return a short hex digest of a file's contents."""
43
+ return hashlib.sha256(path.read_bytes()).hexdigest()[:16]
44
+
45
+
46
+ def _get_venv_created(venv_path: Path) -> str | None:
47
+ """Return the creation/mtime timestamp of pyvenv.cfg as an ISO string.
48
+
49
+ Uses creation time on Windows (st_ctime_ns) and mtime on Unix.
50
+ Returns None if pyvenv.cfg doesn't exist.
51
+ """
52
+ cfg = venv_path / "pyvenv.cfg"
53
+ if not cfg.exists():
54
+ return None
55
+ stat = cfg.stat()
56
+ # On Windows, st_ctime is the file creation time.
57
+ # On Unix, st_ctime is the last metadata change (not creation), so use mtime.
58
+ if sys.platform == "win32":
59
+ ts = stat.st_ctime_ns
60
+ else:
61
+ ts = stat.st_mtime_ns
62
+ return str(ts)
63
+
64
+
65
+ class VenvManager:
66
+ """Manages the pyddock virtual environment and package installation.
67
+
68
+ Args:
69
+ venv_path: Path to the venv directory. Defaults to `.pyddock/venv/`.
70
+ allowed_imports: List of module names from the config allowlist.
71
+ """
72
+
73
+ def __init__(
74
+ self,
75
+ venv_path: Path | None = None,
76
+ allowed_imports: list[str] | None = None,
77
+ ) -> None:
78
+ if venv_path is None:
79
+ venv_path = Path(".pyddock") / "venv"
80
+ self._venv_path = venv_path
81
+ self._allowed_imports = set(allowed_imports or [])
82
+ self._stdlib_modules: set[str] = sys.stdlib_module_names # type: ignore[assignment]
83
+ self._installed_cache: set[str] = set() # packages confirmed installed
84
+ self._stamp: dict | None = None # loaded stamp data (None = not loaded yet)
85
+
86
+ # ------------------------------------------------------------------
87
+ # Stamp file management
88
+ # ------------------------------------------------------------------
89
+
90
+ def _stamp_path(self) -> Path:
91
+ """Path to the stamp file in the .pyddock directory (parent of venv)."""
92
+ return self._venv_path.parent / _STAMP_FILENAME
93
+
94
+ def _load_stamp(self) -> dict:
95
+ """Load and validate the stamp file.
96
+
97
+ Returns the parsed dict if valid and the venv_created timestamp
98
+ matches the current pyvenv.cfg. Returns an empty dict (triggering
99
+ full install) if the stamp is missing, corrupt, or stale.
100
+ """
101
+ if self._stamp is not None:
102
+ return self._stamp
103
+
104
+ stamp_path = self._stamp_path()
105
+ if not stamp_path.exists():
106
+ logger.debug("No stamp file found at %s", stamp_path)
107
+ self._stamp = {}
108
+ return self._stamp
109
+
110
+ try:
111
+ data = json.loads(stamp_path.read_text(encoding="utf-8"))
112
+ except (json.JSONDecodeError, OSError) as e:
113
+ logger.debug("Stamp file unreadable, will rebuild: %s", e)
114
+ self._stamp = {}
115
+ return self._stamp
116
+
117
+ if not isinstance(data, dict):
118
+ self._stamp = {}
119
+ return self._stamp
120
+
121
+ # Validate venv identity — if pyvenv.cfg was recreated, stamp is stale
122
+ expected_created = _get_venv_created(self._venv_path)
123
+ if expected_created is None or data.get("venv_created") != expected_created:
124
+ logger.debug(
125
+ "Venv timestamp mismatch (stamp=%s, actual=%s), will rebuild",
126
+ data.get("venv_created"),
127
+ expected_created,
128
+ )
129
+ self._stamp = {}
130
+ return self._stamp
131
+
132
+ self._stamp = data
133
+ return self._stamp
134
+
135
+ def _save_stamp(
136
+ self,
137
+ *,
138
+ allowlist_hash: str,
139
+ workspace_hashes: dict[str, str],
140
+ ) -> None:
141
+ """Write the stamp file with current state.
142
+
143
+ Overwrites any existing stamp. If writing fails (permissions, disk full),
144
+ logs a warning but does not raise — the next boot will just do a full
145
+ install again.
146
+ """
147
+ venv_created = _get_venv_created(self._venv_path)
148
+ data = {
149
+ "venv_created": venv_created,
150
+ "allowlist_hash": allowlist_hash,
151
+ "workspace": workspace_hashes,
152
+ }
153
+ try:
154
+ self._stamp_path().write_text(
155
+ json.dumps(data, indent=2), encoding="utf-8"
156
+ )
157
+ except OSError as e:
158
+ logger.warning("Failed to write stamp file: %s", e)
159
+ self._stamp = data
160
+
161
+ def _compute_allowlist_hash(self, pip_packages: dict[str, str] | None = None) -> str:
162
+ """Compute a hash representing the current allowlist + pip_packages mapping."""
163
+ if pip_packages is None:
164
+ pip_packages = {}
165
+ # Deterministic: sorted allowlist + sorted pip_packages items
166
+ parts = sorted(self._allowed_imports)
167
+ parts.append("||")
168
+ parts.extend(f"{k}={v}" for k, v in sorted(pip_packages.items()))
169
+ return _hash_string("\n".join(parts))
170
+
171
+ # ------------------------------------------------------------------
172
+ # Venv lifecycle
173
+ # ------------------------------------------------------------------
174
+
175
+ def ensure_venv(self) -> None:
176
+ """Create the virtual environment if it doesn't already exist."""
177
+ if self._venv_path.exists() and self.get_python_path().exists():
178
+ return
179
+
180
+ try:
181
+ venv.create(str(self._venv_path), with_pip=True)
182
+ except Exception as e:
183
+ raise VenvError(f"Failed to create venv at {self._venv_path}: {e}") from e
184
+
185
+ def get_python_path(self) -> Path:
186
+ """Return the path to the venv's Python interpreter.
187
+
188
+ On Windows this is `Scripts/python.exe`, on Unix it's `bin/python`.
189
+ """
190
+ if sys.platform == "win32":
191
+ return self._venv_path / "Scripts" / "python.exe"
192
+ return self._venv_path / "bin" / "python"
193
+
194
+ def is_stdlib(self, module_name: str) -> bool:
195
+ """Check if a module name is part of the Python standard library.
196
+
197
+ Uses `sys.stdlib_module_names` (Python 3.10+) for detection.
198
+ """
199
+ return module_name in self._stdlib_modules
200
+
201
+ def _is_installed(self, package_name: str) -> bool:
202
+ """Check if a package is already installed in the venv."""
203
+ if package_name in self._installed_cache:
204
+ return True
205
+ python = self.get_python_path()
206
+ try:
207
+ result = subprocess.run(
208
+ [str(python), "-c", f"import {package_name}"],
209
+ capture_output=True,
210
+ text=True,
211
+ timeout=10,
212
+ )
213
+ except subprocess.TimeoutExpired:
214
+ return False
215
+ if result.returncode == 0:
216
+ self._installed_cache.add(package_name)
217
+ return True
218
+ return False
219
+
220
+ def install_workspace(
221
+ self, packages: dict[str, str], workspace_root: Path
222
+ ) -> None:
223
+ """Install workspace packages in editable mode via pip install -e.
224
+
225
+ Skips packages whose pyproject.toml hash matches the stamp file,
226
+ meaning their project metadata hasn't changed since last install.
227
+
228
+ Args:
229
+ packages: Mapping of module name → relative path from workspace root.
230
+ workspace_root: The workspace root directory to resolve relative paths.
231
+
232
+ Raises:
233
+ VenvError: If pip install -e fails for any package.
234
+ """
235
+ if not packages:
236
+ return
237
+
238
+ stamp = self._load_stamp()
239
+ stamp_workspace = stamp.get("workspace", {})
240
+ python = self.get_python_path()
241
+ new_hashes: dict[str, str] = {}
242
+
243
+ for module_name, rel_path in packages.items():
244
+ abs_path = workspace_root / rel_path
245
+ # Hash pyproject.toml (or setup.py/setup.cfg) to detect metadata changes
246
+ toml_path = abs_path / "pyproject.toml"
247
+ if not toml_path.exists():
248
+ # Try setup.py as fallback
249
+ toml_path = abs_path / "setup.py"
250
+ if not toml_path.exists():
251
+ # Try setup.cfg as fallback
252
+ toml_path = abs_path / "setup.cfg"
253
+
254
+ if toml_path.exists():
255
+ current_hash = _hash_file(toml_path)
256
+ new_hashes[module_name] = current_hash
257
+ # Skip if hash matches stamp
258
+ if stamp_workspace.get(module_name) == current_hash:
259
+ logger.debug(
260
+ "Workspace module '%s' unchanged (hash=%s), skipping install",
261
+ module_name,
262
+ current_hash,
263
+ )
264
+ continue
265
+ else:
266
+ # No project metadata file — nothing to install or track.
267
+ # The module is on sys.path via trusted prefixes already.
268
+ logger.debug(
269
+ "Workspace module '%s' has no project metadata, skipping install",
270
+ module_name,
271
+ )
272
+ continue
273
+
274
+ logger.debug("Installing workspace module '%s' from %s", module_name, abs_path)
275
+ try:
276
+ result = subprocess.run(
277
+ [str(python), "-m", "pip", "install", "-e", str(abs_path)],
278
+ capture_output=True,
279
+ text=True,
280
+ timeout=300, # 5 minute timeout
281
+ )
282
+ except subprocess.TimeoutExpired:
283
+ raise VenvError(
284
+ f"Timed out installing workspace package '{module_name}' "
285
+ f"from {abs_path} (exceeded 5 minutes)."
286
+ )
287
+
288
+ if result.returncode != 0:
289
+ raise VenvError(
290
+ f"Failed to install workspace package '{module_name}' "
291
+ f"from {abs_path}.\n"
292
+ f"pip output:\n{result.stdout}\n{result.stderr}"
293
+ )
294
+
295
+ # Store computed workspace hashes for _save_stamp (called after install_missing)
296
+ self._workspace_hashes = new_hashes
297
+
298
+ def install_missing(
299
+ self,
300
+ imports: list[str],
301
+ workspace_skip: set[str] | None = None,
302
+ pip_packages: dict[str, str] | None = None,
303
+ ) -> None:
304
+ """Install any allowed non-stdlib packages not yet in the venv.
305
+
306
+ Uses the stamp file to skip the entire check when the allowlist hash
307
+ hasn't changed. If the hash matches, all packages are assumed installed.
308
+ If it doesn't match, falls back to per-package checks and installs.
309
+
310
+ After completing, writes a fresh stamp file recording the current state.
311
+
312
+ Args:
313
+ imports: List of module names extracted from the snippet's AST.
314
+ workspace_skip: Set of module names that are workspace packages
315
+ and should be skipped (already installed via install_workspace).
316
+ pip_packages: Mapping of import name → pip package name for packages
317
+ where the import name differs from the PyPI name (e.g.
318
+ {"dateutil": "python-dateutil"}).
319
+
320
+ Raises:
321
+ VenvError: If pip install fails for any package.
322
+ """
323
+ if workspace_skip is None:
324
+ workspace_skip = set()
325
+ if pip_packages is None:
326
+ pip_packages = {}
327
+
328
+ allowlist_hash = self._compute_allowlist_hash(pip_packages)
329
+ stamp = self._load_stamp()
330
+
331
+ # Fast path: if allowlist hash matches, all packages are installed
332
+ if stamp.get("allowlist_hash") == allowlist_hash:
333
+ logger.debug("Allowlist hash unchanged (%s), skipping install checks", allowlist_hash)
334
+ # Still save stamp to update workspace hashes if they changed
335
+ self._save_stamp(
336
+ allowlist_hash=allowlist_hash,
337
+ workspace_hashes=getattr(self, "_workspace_hashes", {}),
338
+ )
339
+ return
340
+
341
+ logger.debug("Allowlist hash changed (stamp=%s, current=%s), checking packages",
342
+ stamp.get("allowlist_hash"), allowlist_hash)
343
+
344
+ to_install: list[str] = []
345
+
346
+ for module_name in imports:
347
+ # Skip if not in the allowed list
348
+ if module_name not in self._allowed_imports:
349
+ continue
350
+ # Skip workspace packages (installed separately)
351
+ if module_name in workspace_skip:
352
+ continue
353
+ # Skip stdlib modules
354
+ if self.is_stdlib(module_name):
355
+ continue
356
+ # Skip already-installed packages
357
+ if self._is_installed(module_name):
358
+ continue
359
+ to_install.append(module_name)
360
+
361
+ if to_install:
362
+ # Translate import names to pip package names where they differ
363
+ pip_names = [pip_packages.get(name, name) for name in to_install]
364
+
365
+ python = self.get_python_path()
366
+ try:
367
+ result = subprocess.run(
368
+ [str(python), "-m", "pip", "install", *pip_names],
369
+ capture_output=True,
370
+ text=True,
371
+ timeout=300, # 5 minute timeout for pip install
372
+ )
373
+ except subprocess.TimeoutExpired:
374
+ raise VenvError(
375
+ f"Timed out installing packages {to_install} (exceeded 5 minutes). "
376
+ f"Try installing manually: pip install {' '.join(to_install)}"
377
+ )
378
+
379
+ if result.returncode != 0:
380
+ raise VenvError(
381
+ f"Failed to install packages {to_install}.\n"
382
+ f"pip output:\n{result.stdout}\n{result.stderr}"
383
+ )
384
+
385
+ # Write stamp with current state
386
+ self._save_stamp(
387
+ allowlist_hash=allowlist_hash,
388
+ workspace_hashes=getattr(self, "_workspace_hashes", {}),
389
+ )