pyddock 0.3.2__tar.gz → 0.3.4__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 (87) hide show
  1. {pyddock-0.3.2 → pyddock-0.3.4}/PKG-INFO +4 -2
  2. {pyddock-0.3.2 → pyddock-0.3.4}/README.md +3 -1
  3. {pyddock-0.3.2 → pyddock-0.3.4}/publish-to-pypi.ps1 +9 -3
  4. {pyddock-0.3.2 → pyddock-0.3.4}/pyproject.toml +1 -1
  5. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_base.py +36 -17
  6. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_fs_enforcement.py +28 -5
  7. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/default_config.toml +2 -0
  8. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/server.py +59 -0
  9. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/shell_executor.py +22 -11
  10. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/tools/fs_append.py +8 -3
  11. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/tools/fs_delete.py +8 -3
  12. pyddock-0.3.4/src/pyddock/tools/fs_find.py +203 -0
  13. pyddock-0.3.4/src/pyddock/tools/fs_grep.py +279 -0
  14. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/tools/read_file.py +8 -3
  15. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/tools/stat_file.py +8 -3
  16. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/tools/str_replace.py +8 -3
  17. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_file_tools.py +330 -0
  18. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_jailbreak_regression.py +38 -3
  19. {pyddock-0.3.2 → pyddock-0.3.4}/uv.lock +1 -1
  20. {pyddock-0.3.2 → pyddock-0.3.4}/.gitignore +0 -0
  21. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/.gitignore +0 -0
  22. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/106d94c8123c0256 +0 -0
  23. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/1685e03b3aa38c02 +0 -0
  24. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/1deca112ec6f2f3c +0 -0
  25. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/2488a3a95c48acfb +0 -0
  26. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/2a94d83a13979745 +0 -0
  27. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/499f1d5a639a382a +0 -0
  28. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/4ee6f24fa151b65d +0 -0
  29. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/5b1b2189b70f5ef2 +0 -0
  30. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/5d6f8b26b2137fe1 +0 -0
  31. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/61f9b905d7da14e0 +0 -0
  32. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/67a7f4ab2d372f23 +0 -0
  33. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/6c6f5083ece3f86b +0 -0
  34. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/827e18b40f235443 +0 -0
  35. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/8401e4039d635fbc +0 -0
  36. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/8490e7baefc8c8c3 +0 -0
  37. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/a7c132b836381d0d +0 -0
  38. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/b395547bc71e5c52 +0 -0
  39. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/constants/ca50661510a40488 +0 -0
  40. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/tmp/tmpl8oe65gb +0 -0
  41. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/tmp/tmpqwper0dp +0 -0
  42. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/unicode_data/15.1.0/charmap.json.gz +0 -0
  43. {pyddock-0.3.2 → pyddock-0.3.4}/.hypothesis/unicode_data/15.1.0/codec-utf-8.json.gz +0 -0
  44. {pyddock-0.3.2 → pyddock-0.3.4}/LICENSE +0 -0
  45. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/__init__.py +0 -0
  46. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_audit_enforcement.py +0 -0
  47. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_enforcement.py +0 -0
  48. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_import_hook.py +0 -0
  49. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_prewarm.py +0 -0
  50. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_process_utils.py +0 -0
  51. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_proxies.py +0 -0
  52. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_runtime.py +0 -0
  53. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/_subprocess_patch.py +0 -0
  54. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/ast_validator.py +0 -0
  55. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/cli.py +0 -0
  56. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/config.py +0 -0
  57. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/executor.py +0 -0
  58. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/script_registry.py +0 -0
  59. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/tools/__init__.py +0 -0
  60. {pyddock-0.3.2 → pyddock-0.3.4}/src/pyddock/venv_manager.py +0 -0
  61. {pyddock-0.3.2 → pyddock-0.3.4}/tests/__init__.py +0 -0
  62. {pyddock-0.3.2 → pyddock-0.3.4}/tests/_config_helpers.py +0 -0
  63. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_ast_properties.py +0 -0
  64. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_attr_reflection_hardening.py +0 -0
  65. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_audit_hook_backstop.py +0 -0
  66. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_chmod_integration.py +0 -0
  67. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_config.py +0 -0
  68. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_deny_always_wins.py +0 -0
  69. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_deny_messages.py +0 -0
  70. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_env_policy.py +0 -0
  71. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_executor.py +0 -0
  72. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_filesystem_guards.py +0 -0
  73. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_proxy_properties.py +0 -0
  74. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_realistic.py +0 -0
  75. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_runtime.py +0 -0
  76. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_sandbox_escape_hardening.py +0 -0
  77. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_security_guards.py +0 -0
  78. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_server.py +0 -0
  79. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_shell_arg_paths.py +0 -0
  80. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_shell_executor.py +0 -0
  81. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_shell_properties.py +0 -0
  82. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_subprocess_enforcement.py +0 -0
  83. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_subprocess_properties.py +0 -0
  84. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_subst_trusted_path.py +0 -0
  85. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_trusted_prefixes_uv_cache.py +0 -0
  86. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_venv_stamp.py +0 -0
  87. {pyddock-0.3.2 → pyddock-0.3.4}/tests/test_workspace_imports.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pyddock
3
- Version: 0.3.2
3
+ Version: 0.3.4
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_readfile","fs_stat","fs_append","fs_delete","fs_str_replace"]
58
+ "autoApprove": ["run_python","run_shell","fs_readfile","fs_stat","fs_find","fs_grep","fs_append","fs_delete","fs_str_replace"]
59
59
  }
60
60
  }
61
61
  }
@@ -109,6 +109,8 @@ Pyddock also exposes file I/O tools that execute through the same sandbox as `ru
109
109
 
110
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
+ - **`fs_find`** — Find files by name (`file_glob` match, recursive). Prunes hidden dot-directories and `exclude_regex` matches before descending (never walked, not just filtered), so large ignored trees (`.venv/`, `node_modules/`) stay fast. Returns matching relative paths, capped at `max_results`.
113
+ - **`fs_grep`** — Search file contents by `grep_regex` (always case-insensitive). Same hidden-directory pruning and `exclude_regex` as `fs_find`. Returns `path:line: content` per match, capped at `max_results` and 300 chars per line. Skips binary files when scanning a directory; always searches a directly named file.
112
114
  - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
113
115
  - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
114
116
  - **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
@@ -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_readfile","fs_stat","fs_append","fs_delete","fs_str_replace"]
34
+ "autoApprove": ["run_python","run_shell","fs_readfile","fs_stat","fs_find","fs_grep","fs_append","fs_delete","fs_str_replace"]
35
35
  }
36
36
  }
37
37
  }
@@ -85,6 +85,8 @@ Pyddock also exposes file I/O tools that execute through the same sandbox as `ru
85
85
 
86
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
+ - **`fs_find`** — Find files by name (`file_glob` match, recursive). Prunes hidden dot-directories and `exclude_regex` matches before descending (never walked, not just filtered), so large ignored trees (`.venv/`, `node_modules/`) stay fast. Returns matching relative paths, capped at `max_results`.
89
+ - **`fs_grep`** — Search file contents by `grep_regex` (always case-insensitive). Same hidden-directory pruning and `exclude_regex` as `fs_find`. Returns `path:line: content` per match, capped at `max_results` and 300 chars per line. Skips binary files when scanning a directory; always searches a directly named file.
88
90
  - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
89
91
  - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
90
92
  - **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
@@ -2,6 +2,12 @@
2
2
 
3
3
  $ErrorActionPreference = "Stop"
4
4
 
5
+ # Determine project name from the git repo root
6
+ $repoRoot = git rev-parse --show-toplevel 2>$null
7
+ if ($LASTEXITCODE -ne 0 -or -not $repoRoot) { throw "Not inside a git repository" }
8
+ $ProjectName = Split-Path -Leaf $repoRoot
9
+ Write-Host "Project name: $ProjectName"
10
+
5
11
  # Clean dist
6
12
  Write-Host "Cleaning dist/..."
7
13
  if (Test-Path dist) { Remove-Item -Recurse -Force dist }
@@ -18,15 +24,15 @@ if ($LASTEXITCODE -ne 0) { throw "testpypi upload failed" }
18
24
 
19
25
  # Hint for testing
20
26
  Write-Host "`nTo test from testpypi:"
21
- Write-Host " uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pyddock"
27
+ Write-Host " uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ $ProjectName"
22
28
 
23
29
  # Pause for confirmation
24
30
  $response = Read-Host "`nType 'y' to upload to pypi (anything else aborts)"
25
31
  if ($response -ne 'y') { Write-Host "Aborted."; exit 0 }
26
32
 
27
33
  # Upload to pypi
28
- Write-Host "> uvx twine upload --repository pyddock dist/*"
29
- uvx twine upload --repository pyddock dist/*
34
+ Write-Host "> uvx twine upload --repository $ProjectName dist/*"
35
+ uvx twine upload --repository $ProjectName dist/*
30
36
  if ($LASTEXITCODE -ne 0) { throw "pypi upload failed" }
31
37
 
32
38
  Write-Host "`nDone!"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pyddock"
3
- version = "0.3.2"
3
+ version = "0.3.4"
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"
@@ -36,33 +36,39 @@ del _os_for_path
36
36
  _ORIGINALS: dict[str, Any] = {}
37
37
 
38
38
 
39
- def has_ntfs_stream(path: Any) -> bool:
40
- """Detect an NTFS alternate-data-stream (ADS) reference in a path.
39
+ def ntfs_stream_base(path: Any) -> str | None:
40
+ """Return the base path of an NTFS alternate-data-stream (ADS) reference.
41
41
 
42
42
  On Windows, ``name:stream`` (and ``name::$DATA``, ``dir:stream``) addresses a
43
43
  *different* securable object than the path's lexical components imply: a write
44
44
  to ``.pyddock:pwned`` lands a data stream on the ``.pyddock`` directory, yet
45
45
  the lexical leaf ``.pyddock:pwned`` is not a child of ``.pyddock`` — so a
46
46
  ``relative_to('.pyddock')`` containment check decides "not protected" and the
47
- write slips through. ``realpath`` does not reliably normalize the stream away
48
- (a not-yet-existing stream resolves to the literal), so the only sound defense
49
- is to reject the syntax up front.
47
+ write slips through.
50
48
 
51
49
  A ``:`` is only legal as the drive designator at index 1 of the FIRST path
52
50
  component (``C:\\...`` or the drive-relative ``C:rest``). A ``:`` anywhere else
53
- is a stream reference. Returns False on non-Windows, where ``:`` is an
51
+ opens a named stream on the component to its left. When such a reference is
52
+ present this returns the lexical BASE — everything up to (but not including)
53
+ the stream ``:`` — i.e. the object the stream would attach to. Returns None
54
+ when no stream reference is present, and on non-Windows, where ``:`` is an
54
55
  ordinary, legal filename character.
55
56
 
56
- NOTE: this primitive is deliberately strict and makes NO exception for
57
- URL-looking strings (``https://...``). It guards real filesystem operations
58
- (``open``/``Path.write_*``), where the argument is always a local path and a
59
- ``scheme:`` prefix would still carry a stream-bearing ``:``. The one place a
60
- URL is a legitimate value — a shell CLI argument — filters URLs out *before*
61
- they reach this check (see ``_looks_like_path`` in shell_executor), so URLs
62
- never get here in the first place.
57
+ Callers existence-check the resolved base to decide whether the reference is
58
+ security-relevant: the ADS containment-evasion attack aliases a stream onto
59
+ an *existing* (and typically protected) object — ``.pyddock``, a workspace
60
+ module dir, the stdlib — all of which always exist on disk. A colon in a
61
+ string that merely looks path-like (e.g. a commit message) has a base that
62
+ does not exist, so it is not a real stream reference.
63
+
64
+ NOTE: this is purely lexical and makes NO exception for URL-looking strings
65
+ (``https://...``); a ``scheme:`` prefix still carries a stream-bearing ``:``.
66
+ The one place a URL is a legitimate value — a shell CLI argument — filters
67
+ URLs out *before* they reach this check (see ``_looks_like_path`` in
68
+ shell_executor), so URLs never get here in the first place.
63
69
  """
64
70
  if _os_name != "nt":
65
- return False
71
+ return None
66
72
  parts = str(path).replace("/", "\\").split("\\")
67
73
  for idx, comp in enumerate(parts):
68
74
  if not comp:
@@ -71,9 +77,22 @@ def has_ntfs_stream(path: Any) -> bool:
71
77
  # First component may carry a 'X:' drive designator (X: or X:rest).
72
78
  if idx == 0 and len(comp) >= 2 and comp[0].isalpha() and comp[1] == ":":
73
79
  start = 2
74
- if ":" in comp[start:]:
75
- return True
76
- return False
80
+ ci = comp.find(":", start)
81
+ if ci != -1:
82
+ base_parts = parts[:idx] + [comp[:ci]]
83
+ return "\\".join(base_parts)
84
+ return None
85
+
86
+
87
+ def has_ntfs_stream(path: Any) -> bool:
88
+ """Pure-syntactic NTFS ADS detector — True if *path* carries a stream ``:``.
89
+
90
+ See ``ntfs_stream_base`` for the parsing rules. This is the lexical primitive
91
+ (existence-agnostic). Enforcement layers DO NOT call this directly: they
92
+ existence-gate via ``ntfs_stream_base`` so a colon in a non-path string does
93
+ not raise a false positive. Returns False on non-Windows.
94
+ """
95
+ return ntfs_stream_base(path) is not None
77
96
 
78
97
 
79
98
  def canonical_path(path: Any) -> pathlib.Path:
@@ -14,7 +14,7 @@ import tempfile as _tempfile_module
14
14
  import _io as _cio_module
15
15
  from typing import Any
16
16
 
17
- from pyddock._base import _ORIGINALS, _PYDDOCK_DIR, _find_deny_hint, canonical_path, has_ntfs_stream
17
+ from pyddock._base import _ORIGINALS, _PYDDOCK_DIR, _find_deny_hint, canonical_path, ntfs_stream_base
18
18
  from pyddock._import_hook import _caller_is_trusted
19
19
  from pyddock._audit_enforcement import install_audit_enforcement
20
20
  from pyddock._process_utils import make_child_env
@@ -54,16 +54,30 @@ def apply_filesystem_scoping(
54
54
  """
55
55
  return canonical_path(p)
56
56
 
57
+ def _resolve_scope_path(p: str) -> pathlib.Path:
58
+ """Resolve a scope path entry to an absolute, canonicalized path.
59
+
60
+ Supports:
61
+ - "~" or "~/..." — expanded via os.path.expanduser
62
+ - Absolute paths (e.g. "C:\\Users\\...") — used as-is
63
+ - Relative paths (e.g. ".", "src") — joined with workspace_root
64
+ """
65
+ expanded = _real_os.path.expanduser(p)
66
+ path = pathlib.Path(expanded)
67
+ if path.is_absolute():
68
+ return _abspath(path)
69
+ return _abspath(workspace_root / expanded)
70
+
57
71
  # Canonicalize allowed paths (realpath: resolves symlinks/junctions/8.3
58
72
  # names) so they compare consistently with canonicalized candidate paths.
59
73
  resolved_writable = [
60
- _abspath(workspace_root / p) for p in writable_paths
74
+ _resolve_scope_path(p) for p in writable_paths
61
75
  ]
62
76
 
63
77
  # "*" means unrestricted reads
64
78
  unrestricted_reads = "*" in readable_paths
65
79
  resolved_readable = [
66
- _abspath(workspace_root / p) for p in readable_paths if p != "*"
80
+ _resolve_scope_path(p) for p in readable_paths if p != "*"
67
81
  ]
68
82
 
69
83
  # .pyddock/ is always excluded from writes (self-modification protection)
@@ -243,7 +257,12 @@ def apply_filesystem_scoping(
243
257
  path = _real_os.fsdecode(path)
244
258
  if _is_null_device(path):
245
259
  return
246
- if has_ntfs_stream(path):
260
+ # NTFS alternate data stream whose base object EXISTS — aliasing a
261
+ # stream onto an existing (often protected) object evades containment
262
+ # checks. Gated on existence to avoid false positives on colon-bearing
263
+ # strings whose base does not exist.
264
+ _stream_base = ntfs_stream_base(path)
265
+ if _stream_base is not None and _real_os.path.exists(_stream_base):
247
266
  raise PermissionError(
248
267
  f"PermissionError: Cannot read '{path}' — NTFS alternate data "
249
268
  f"streams (':' in a path component) are not permitted. Use a "
@@ -271,7 +290,11 @@ def apply_filesystem_scoping(
271
290
  path = _real_os.fsdecode(path)
272
291
  if _is_null_device(path):
273
292
  return
274
- if has_ntfs_stream(path):
293
+ # NTFS alternate data stream whose base object EXISTS (see _check_read).
294
+ # The base of '.pyddock:x' is '.pyddock' (always present) — caught; a
295
+ # colon in a non-existent-base string is not a real stream reference.
296
+ _stream_base = ntfs_stream_base(path)
297
+ if _stream_base is not None and _real_os.path.exists(_stream_base):
275
298
  raise PermissionError(
276
299
  f"PermissionError: Cannot write to '{path}' — NTFS alternate "
277
300
  f"data streams (':' in a path component) are not permitted. A "
@@ -69,7 +69,9 @@ P4 = "p4python" # Restricted to non-submit operations
69
69
  # Filesystem scoping for run_python.
70
70
  # Paths are relative to the workspace root (the --workspace directory or CWD).
71
71
  # "." = the workspace directory itself (and everything under it)
72
+ # "~" = user home directory (os.path.expanduser); "~/subdir" works too
72
73
  # "*" = unrestricted (entire host filesystem)
74
+ # Absolute paths (e.g. "C:\\Data") are also accepted and used as-is.
73
75
  # Writes are always denied to .pyddock/ (self-modification protection) and to
74
76
  # paths matching shell-executable script patterns (write-then-execute prevention).
75
77
  [filesystem]
@@ -350,6 +350,65 @@ def create_server(workspace: Path | None = None, debug: bool = False) -> FastMCP
350
350
  "end_line": end_line,
351
351
  })
352
352
 
353
+ _fs_find_desc = (
354
+ "Find files by name. Approximately: [p for p in os.walk(path) if file_glob matches]\n"
355
+ "\n"
356
+ "file_glob is a glob (e.g. '*.py', '**/test_*.py') matched against filenames\n"
357
+ "under path (default: workspace root, must be a directory). Hidden\n"
358
+ "dot-directories are pruned before descending (an explicit leading '.' in\n"
359
+ "file_glob, e.g. '.env', still matches hidden files); exclude_regex\n"
360
+ "(optional) prunes more by relative path. Returns matching relative paths,\n"
361
+ "one per line, capped at max_results (default: 100)."
362
+ )
363
+
364
+ @mcp.tool(name="fs_find", description=_fs_find_desc)
365
+ async def fs_find(
366
+ file_glob: str,
367
+ path: str | None = None,
368
+ exclude_regex: str | None = None,
369
+ max_results: int | None = None,
370
+ ) -> str:
371
+ if not file_glob or not file_glob.strip():
372
+ return "Error: 'file_glob' is required and must be non-empty."
373
+ return await registry.execute("fs_find", {
374
+ "file_glob": file_glob,
375
+ "path": path,
376
+ "exclude_regex": exclude_regex,
377
+ "max_results": max_results,
378
+ })
379
+
380
+ _fs_grep_desc = (
381
+ "Search file contents by regex (always case-insensitive). Approximately:\n"
382
+ "fs_find() then re.search(grep_regex, line, re.IGNORECASE) per line of\n"
383
+ "each matched file.\n"
384
+ "\n"
385
+ "grep_regex is searched within each file matched by file_glob (glob,\n"
386
+ "default '*') under path (default: workspace root). Returns\n"
387
+ "'path:line: content' per match, capped at max_results (default: 100)\n"
388
+ "and 300 chars per line.\n"
389
+ "\n"
390
+ "Binary files are skipped when scanning a directory path. A single named\n"
391
+ "file is always searched."
392
+ )
393
+
394
+ @mcp.tool(name="fs_grep", description=_fs_grep_desc)
395
+ async def fs_grep(
396
+ grep_regex: str,
397
+ file_glob: str | None = None,
398
+ path: str | None = None,
399
+ exclude_regex: str | None = None,
400
+ max_results: int | None = None,
401
+ ) -> str:
402
+ if not grep_regex:
403
+ return "Error: 'grep_regex' is required and must be non-empty."
404
+ return await registry.execute("fs_grep", {
405
+ "grep_regex": grep_regex,
406
+ "file_glob": file_glob,
407
+ "path": path,
408
+ "exclude_regex": exclude_regex,
409
+ "max_results": max_results,
410
+ })
411
+
353
412
  return mcp
354
413
 
355
414
 
@@ -15,7 +15,7 @@ from pathlib import Path
15
15
  from typing import Any
16
16
 
17
17
  from pyddock.config import PyddockConfig, ShellPolicyConfig, find_deny_hint
18
- from pyddock._base import canonical_path, has_ntfs_stream
18
+ from pyddock._base import canonical_path, ntfs_stream_base
19
19
  from pyddock._process_utils import get_startupinfo, kill_and_drain, make_child_env, truncate_output
20
20
 
21
21
  import shutil
@@ -501,11 +501,18 @@ def evaluate_arg_paths(
501
501
  # NTFS alternate data streams alias a different object than their
502
502
  # lexical path implies (e.g. "--output=.pyddock:x" writes onto the
503
503
  # protected .pyddock dir while evading the relative_to() check).
504
- if has_ntfs_stream(candidate):
505
- return (
506
- f"Argument '{arg}' uses an NTFS alternate data stream "
507
- f"(':' in a path component), which is not permitted."
508
- )
504
+ # Gated on existence of the base object: protected targets always
505
+ # exist, so the attack is still caught, while a colon in a value
506
+ # whose base does not exist is not treated as a stream.
507
+ _stream_base = ntfs_stream_base(candidate)
508
+ if _stream_base is not None:
509
+ _base_p = Path(_stream_base)
510
+ _base_abs = _base_p if _base_p.is_absolute() else workspace_root / _base_p
511
+ if _base_abs.exists():
512
+ return (
513
+ f"Argument '{arg}' uses an NTFS alternate data stream "
514
+ f"(':' in a path component), which is not permitted."
515
+ )
509
516
  # Resolve relative to workspace root (same as command cwd)
510
517
  resolved = _abspath(workspace_root / candidate)
511
518
 
@@ -584,11 +591,15 @@ def evaluate_cwd(
584
591
  return None
585
592
 
586
593
  cwd_str = cwd.decode("utf-8", "surrogateescape") if isinstance(cwd, bytes) else str(cwd)
587
- if has_ntfs_stream(cwd_str):
588
- return (
589
- f"cwd '{cwd_str}' uses an NTFS alternate data stream (':' in a path "
590
- f"component), which is not permitted."
591
- )
594
+ _cwd_stream_base = ntfs_stream_base(cwd_str)
595
+ if _cwd_stream_base is not None:
596
+ _cwd_base_p = Path(_cwd_stream_base)
597
+ _cwd_base_abs = _cwd_base_p if _cwd_base_p.is_absolute() else workspace_root / _cwd_base_p
598
+ if _cwd_base_abs.exists():
599
+ return (
600
+ f"cwd '{cwd_str}' uses an NTFS alternate data stream (':' in a path "
601
+ f"component), which is not permitted."
602
+ )
592
603
  ws_root_abs = _abspath(workspace_root)
593
604
  pyddock_dir = _abspath(workspace_root / ".pyddock")
594
605
  resolved = _abspath(workspace_root / Path(cwd_str))
@@ -19,11 +19,16 @@ workspace_root = _PARAMS["workspace_root"]
19
19
 
20
20
 
21
21
  def resolve_path(raw_path: str) -> Path:
22
- """Resolve a user-provided path to absolute, relative to workspace root."""
23
- p = Path(raw_path)
22
+ """Resolve a user-provided path to absolute, relative to workspace root.
23
+
24
+ Expands a leading '~' (home directory) before resolving, mirroring how
25
+ [filesystem] scope paths (writable_paths/readable_paths) are resolved.
26
+ """
27
+ expanded = os.path.expanduser(raw_path)
28
+ p = Path(expanded)
24
29
  if p.is_absolute():
25
30
  return Path(os.path.abspath(str(p)))
26
- return Path(os.path.abspath(str(Path(workspace_root) / raw_path)))
31
+ return Path(os.path.abspath(str(Path(workspace_root) / expanded)))
27
32
 
28
33
 
29
34
  def generate_diff(old_lines: list[str], new_lines: list[str], filename: str) -> str:
@@ -20,11 +20,16 @@ _MAX_DELETE_DIFF_BYTES = 16_384 # 16 KB truncation for delete diffs
20
20
 
21
21
 
22
22
  def resolve_path(raw_path: str) -> Path:
23
- """Resolve a user-provided path to absolute, relative to workspace root."""
24
- p = Path(raw_path)
23
+ """Resolve a user-provided path to absolute, relative to workspace root.
24
+
25
+ Expands a leading '~' (home directory) before resolving, mirroring how
26
+ [filesystem] scope paths (writable_paths/readable_paths) are resolved.
27
+ """
28
+ expanded = os.path.expanduser(raw_path)
29
+ p = Path(expanded)
25
30
  if p.is_absolute():
26
31
  return Path(os.path.abspath(str(p)))
27
- return Path(os.path.abspath(str(Path(workspace_root) / raw_path)))
32
+ return Path(os.path.abspath(str(Path(workspace_root) / expanded)))
28
33
 
29
34
 
30
35
  def generate_diff(old_lines: list[str], new_lines: list[str], filename: str) -> str:
@@ -0,0 +1,203 @@
1
+ """fs_find tool script.
2
+
3
+ Find files by name under a directory. Approximately:
4
+ [p for p in os.walk(path) if file_glob matches]
5
+
6
+ Hidden dot-directories (and their contents) are pruned before descending —
7
+ they are never walked, not just filtered from results — so this stays fast
8
+ on large ignored trees like .venv/ or node_modules/. An optional
9
+ exclude_regex prunes/excludes additional entries the same way. A file_glob
10
+ whose final segment starts with '.' (e.g. '.env') explicitly matches hidden
11
+ files despite the pruning, mirroring shell glob semantics where '*' does not
12
+ match a leading dot but an explicit pattern does. Returns matching paths
13
+ (relative to the workspace root when possible), one per line, capped at
14
+ max_results.
15
+ """
16
+ import os
17
+ import re
18
+ import sys
19
+ from pathlib import Path
20
+
21
+ # --- Parameters ---
22
+ file_glob = _PARAMS["file_glob"]
23
+ path_str = _PARAMS.get("path") or "."
24
+ exclude_regex = _PARAMS.get("exclude_regex")
25
+ max_results = _PARAMS.get("max_results") or 100
26
+ workspace_root = _PARAMS["workspace_root"]
27
+
28
+
29
+ def resolve_path(raw_path: str) -> Path:
30
+ """Resolve a user-provided path to absolute, relative to workspace root.
31
+
32
+ Expands a leading '~' (home directory) before resolving, mirroring how
33
+ [filesystem] scope paths (writable_paths/readable_paths) are resolved.
34
+ """
35
+ expanded = os.path.expanduser(raw_path)
36
+ p = Path(expanded)
37
+ if p.is_absolute():
38
+ return Path(os.path.abspath(str(p)))
39
+ return Path(os.path.abspath(str(Path(workspace_root) / expanded)))
40
+
41
+
42
+ def display_path(p: Path) -> str:
43
+ """Format a path for output: relative to workspace root when possible."""
44
+ try:
45
+ rel = p.relative_to(workspace_root)
46
+ return str(rel).replace("\\", "/")
47
+ except ValueError:
48
+ return str(p)
49
+
50
+
51
+ def translate_glob(pattern: str) -> str:
52
+ """Translate a glob pattern to an anchored regex.
53
+
54
+ Supports '*' (any run of non-separator chars), '?' (one non-separator
55
+ char), '[seq]'/'[!seq]' character classes, and '**' as a recursive
56
+ any-depth-of-segments wildcard. Matched against a forward-slash path.
57
+ """
58
+ i, n = 0, len(pattern)
59
+ out: list[str] = []
60
+ while i < n:
61
+ c = pattern[i]
62
+ i += 1
63
+ if c == "*":
64
+ if i < n and pattern[i] == "*":
65
+ i += 1
66
+ if i < n and pattern[i] == "/":
67
+ i += 1
68
+ out.append("(?:.*/)?")
69
+ else:
70
+ out.append(".*")
71
+ else:
72
+ out.append("[^/]*")
73
+ elif c == "?":
74
+ out.append("[^/]")
75
+ elif c == "[":
76
+ j = i
77
+ if j < n and pattern[j] == "!":
78
+ j += 1
79
+ if j < n and pattern[j] == "]":
80
+ j += 1
81
+ while j < n and pattern[j] != "]":
82
+ j += 1
83
+ if j >= n:
84
+ out.append(re.escape("["))
85
+ else:
86
+ stuff = pattern[i:j]
87
+ if stuff.startswith("!"):
88
+ stuff = "^" + stuff[1:]
89
+ out.append("[" + stuff + "]")
90
+ i = j + 1
91
+ else:
92
+ out.append(re.escape(c))
93
+ return "^" + "".join(out) + "$"
94
+
95
+
96
+ def is_hidden(name: str) -> bool:
97
+ """True if a single path component is dot-prefixed."""
98
+ return name.startswith(".")
99
+
100
+
101
+ def rel_posix(base: Path, dirpath: str) -> str:
102
+ """Relative path from base to dirpath, forward-slash, '' at base itself."""
103
+ rel = os.path.relpath(dirpath, str(base))
104
+ if rel == ".":
105
+ return ""
106
+ return rel.replace("\\", "/")
107
+
108
+
109
+ # --- Main ---
110
+ if not file_glob:
111
+ print("file_glob must be non-empty.", file=sys.stderr)
112
+ sys.exit(1)
113
+
114
+ exclude_re = None
115
+ if exclude_regex:
116
+ try:
117
+ exclude_re = re.compile(exclude_regex)
118
+ except re.error as e:
119
+ print(f"Invalid exclude_regex '{exclude_regex}': {e}", file=sys.stderr)
120
+ sys.exit(1)
121
+
122
+ # Matching strategy mirrors Path.rglob(): a pattern with no '/' matches the
123
+ # filename at any depth; a pattern containing '/' matches the full relative
124
+ # path from `path` (e.g. '**/test_*.py').
125
+ match_basename_only = "/" not in file_glob
126
+ file_regex = re.compile(translate_glob(file_glob))
127
+
128
+ # A glob whose final segment starts with '.' explicitly targets hidden files
129
+ # (e.g. '.env', '**/.env') — mirrors shell semantics where '*' does not match
130
+ # a leading dot but an explicit pattern does. Hidden DIRECTORIES are still
131
+ # pruned regardless (performance); point `path` directly at one to search
132
+ # inside it.
133
+ allow_hidden_files = file_glob.rsplit("/", 1)[-1].startswith(".")
134
+
135
+ path = resolve_path(path_str)
136
+
137
+ if not path.exists():
138
+ print(f"Path not found: '{path_str}'", file=sys.stderr)
139
+ sys.exit(1)
140
+
141
+ if not path.is_dir():
142
+ print(f"'{path_str}' is not a directory. fs_find searches directories.", file=sys.stderr)
143
+ sys.exit(1)
144
+
145
+ results: list[Path] = []
146
+ truncated = False
147
+ skipped_hidden = 0
148
+ skipped_excluded = 0
149
+
150
+ for dirpath, dirnames, filenames in os.walk(path):
151
+ if truncated:
152
+ break
153
+ rel_dir = rel_posix(path, dirpath)
154
+
155
+ # Prune hidden / excluded subdirectories BEFORE os.walk descends into
156
+ # them — this is what keeps large ignored trees (.venv/, node_modules/)
157
+ # from ever being scanned at all.
158
+ kept_dirnames = []
159
+ for d in dirnames:
160
+ if is_hidden(d):
161
+ skipped_hidden += 1
162
+ continue
163
+ rel_sub = f"{rel_dir}/{d}" if rel_dir else d
164
+ if exclude_re is not None and exclude_re.search(rel_sub):
165
+ skipped_excluded += 1
166
+ continue
167
+ kept_dirnames.append(d)
168
+ dirnames[:] = kept_dirnames
169
+
170
+ for f in filenames:
171
+ if is_hidden(f) and not allow_hidden_files:
172
+ skipped_hidden += 1
173
+ continue
174
+ rel_file = f"{rel_dir}/{f}" if rel_dir else f
175
+ if exclude_re is not None and exclude_re.search(rel_file):
176
+ skipped_excluded += 1
177
+ continue
178
+ target = f if match_basename_only else rel_file
179
+ if not file_regex.match(target):
180
+ continue
181
+ results.append(Path(dirpath) / f)
182
+ if len(results) >= max_results:
183
+ truncated = True
184
+ break
185
+
186
+ notes = []
187
+ if truncated:
188
+ notes.append(f"Showing first {max_results} results. Narrow file_glob or path to see more.")
189
+ if skipped_hidden:
190
+ notes.append(f"{skipped_hidden} hidden file(s)/dir(s) skipped.")
191
+ if skipped_excluded:
192
+ notes.append(f"{skipped_excluded} excluded file(s)/dir(s) skipped.")
193
+
194
+ if not results:
195
+ msg = f"No files matching '{file_glob}' found under '{path_str}'."
196
+ if notes:
197
+ msg += " (" + " ".join(notes) + ")"
198
+ print(msg)
199
+ else:
200
+ output = "\n".join(display_path(p) for p in results)
201
+ if notes:
202
+ output += "\n\n[" + " ".join(notes) + "]"
203
+ print(output)