pyddock 0.3.5__tar.gz → 0.3.6__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.5 → pyddock-0.3.6}/PKG-INFO +3 -3
  2. {pyddock-0.3.5 → pyddock-0.3.6}/README.md +2 -2
  3. {pyddock-0.3.5 → pyddock-0.3.6}/pyproject.toml +1 -1
  4. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/server.py +26 -12
  5. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/fs_find.py +60 -67
  6. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/fs_grep.py +140 -78
  7. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_file_tools.py +217 -0
  8. {pyddock-0.3.5 → pyddock-0.3.6}/uv.lock +1 -1
  9. {pyddock-0.3.5 → pyddock-0.3.6}/.gitignore +0 -0
  10. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/.gitignore +0 -0
  11. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/106d94c8123c0256 +0 -0
  12. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/1685e03b3aa38c02 +0 -0
  13. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/1deca112ec6f2f3c +0 -0
  14. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/2488a3a95c48acfb +0 -0
  15. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/2a94d83a13979745 +0 -0
  16. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/499f1d5a639a382a +0 -0
  17. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/4ee6f24fa151b65d +0 -0
  18. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/5b1b2189b70f5ef2 +0 -0
  19. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/5d6f8b26b2137fe1 +0 -0
  20. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/61f9b905d7da14e0 +0 -0
  21. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/67a7f4ab2d372f23 +0 -0
  22. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/6c6f5083ece3f86b +0 -0
  23. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/827e18b40f235443 +0 -0
  24. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/8401e4039d635fbc +0 -0
  25. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/8490e7baefc8c8c3 +0 -0
  26. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/a7c132b836381d0d +0 -0
  27. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/b395547bc71e5c52 +0 -0
  28. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/constants/ca50661510a40488 +0 -0
  29. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/tmp/tmpl8oe65gb +0 -0
  30. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/tmp/tmpqwper0dp +0 -0
  31. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/unicode_data/15.1.0/charmap.json.gz +0 -0
  32. {pyddock-0.3.5 → pyddock-0.3.6}/.hypothesis/unicode_data/15.1.0/codec-utf-8.json.gz +0 -0
  33. {pyddock-0.3.5 → pyddock-0.3.6}/LICENSE +0 -0
  34. {pyddock-0.3.5 → pyddock-0.3.6}/publish-to-pypi.ps1 +0 -0
  35. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/__init__.py +0 -0
  36. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_audit_enforcement.py +0 -0
  37. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_base.py +0 -0
  38. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_enforcement.py +0 -0
  39. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_fs_enforcement.py +0 -0
  40. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_import_hook.py +0 -0
  41. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_prewarm.py +0 -0
  42. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_process_utils.py +0 -0
  43. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_proxies.py +0 -0
  44. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_runtime.py +0 -0
  45. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/_subprocess_patch.py +0 -0
  46. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/ast_validator.py +0 -0
  47. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/cli.py +0 -0
  48. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/config.py +0 -0
  49. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/default_config.toml +0 -0
  50. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/executor.py +0 -0
  51. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/script_registry.py +0 -0
  52. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/shell_executor.py +0 -0
  53. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/__init__.py +0 -0
  54. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/fs_append.py +0 -0
  55. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/fs_delete.py +0 -0
  56. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/read_file.py +0 -0
  57. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/stat_file.py +0 -0
  58. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/tools/str_replace.py +0 -0
  59. {pyddock-0.3.5 → pyddock-0.3.6}/src/pyddock/venv_manager.py +0 -0
  60. {pyddock-0.3.5 → pyddock-0.3.6}/tests/__init__.py +0 -0
  61. {pyddock-0.3.5 → pyddock-0.3.6}/tests/_config_helpers.py +0 -0
  62. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_ast_properties.py +0 -0
  63. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_attr_reflection_hardening.py +0 -0
  64. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_audit_hook_backstop.py +0 -0
  65. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_chmod_integration.py +0 -0
  66. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_config.py +0 -0
  67. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_deny_always_wins.py +0 -0
  68. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_deny_messages.py +0 -0
  69. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_env_policy.py +0 -0
  70. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_executor.py +0 -0
  71. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_filesystem_guards.py +0 -0
  72. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_jailbreak_regression.py +0 -0
  73. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_proxy_properties.py +0 -0
  74. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_realistic.py +0 -0
  75. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_runtime.py +0 -0
  76. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_sandbox_escape_hardening.py +0 -0
  77. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_security_guards.py +0 -0
  78. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_server.py +0 -0
  79. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_shell_arg_paths.py +0 -0
  80. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_shell_executor.py +0 -0
  81. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_shell_properties.py +0 -0
  82. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_subprocess_enforcement.py +0 -0
  83. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_subprocess_properties.py +0 -0
  84. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_subst_trusted_path.py +0 -0
  85. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_trusted_prefixes_uv_cache.py +0 -0
  86. {pyddock-0.3.5 → pyddock-0.3.6}/tests/test_venv_stamp.py +0 -0
  87. {pyddock-0.3.5 → pyddock-0.3.6}/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.5
3
+ Version: 0.3.6
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
@@ -109,8 +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, with an optional `max_results_per_file` cap. Skips binary files when scanning a directory; always searches a directly named file.
112
+ - **`fs_find`** — Find files by name (`file_glob` or `file_regex`, mutually exclusive). 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, `exclude_regex`, and `file_glob`/`file_regex` file filtering as `fs_find`. Returns `path:line: content` per match with surrounding context lines (default: 1 for directory scans, 4 for single-file), capped at `max_results` and 300 chars per line, with an optional `max_results_per_file` cap. Skips binary files when scanning a directory; always searches a directly named file.
114
114
  - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
115
115
  - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
116
116
  - **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
@@ -85,8 +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, with an optional `max_results_per_file` cap. Skips binary files when scanning a directory; always searches a directly named file.
88
+ - **`fs_find`** — Find files by name (`file_glob` or `file_regex`, mutually exclusive). 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, `exclude_regex`, and `file_glob`/`file_regex` file filtering as `fs_find`. Returns `path:line: content` per match with surrounding context lines (default: 1 for directory scans, 4 for single-file), capped at `max_results` and 300 chars per line, with an optional `max_results_per_file` cap. Skips binary files when scanning a directory; always searches a directly named file.
90
90
  - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
91
91
  - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
92
92
  - **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pyddock"
3
- version = "0.3.5"
3
+ version = "0.3.6"
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"
@@ -353,25 +353,30 @@ def create_server(workspace: Path | None = None, debug: bool = False) -> FastMCP
353
353
  _fs_find_desc = (
354
354
  "Find files by name. Approximately: [p for p in os.walk(path) if file_glob matches]\n"
355
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)."
356
+ "Filenames under path (default: workspace root, must be a directory) are\n"
357
+ "matched against file_glob (e.g. '**/test_*.py') or file_regex\n"
358
+ "('test_.+\\.py'; mutually exclusive with file_glob). Hidden\n"
359
+ "dot-directories are pruned before descending (an explicit leading '.'\n"
360
+ "in file_glob, e.g. '.env', still matches hidden files); exclude_regex\n"
361
+ "(optional) prunes more by relative path. Returns matching relative\n"
362
+ "paths, one per line, capped at max_results (default: 100)."
362
363
  )
363
364
 
364
365
  @mcp.tool(name="fs_find", description=_fs_find_desc)
365
366
  async def fs_find(
366
- file_glob: str,
367
+ file_glob: str | None = None,
368
+ file_regex: str | None = None,
367
369
  path: str | None = None,
368
370
  exclude_regex: str | None = None,
369
371
  max_results: int | None = None,
370
372
  ) -> str:
371
- if not file_glob or not file_glob.strip():
372
- return "Error: 'file_glob' is required and must be non-empty."
373
+ if not file_glob and not file_regex:
374
+ return "Error: provide either 'file_glob' or 'file_regex'."
375
+ if file_glob and file_regex:
376
+ return "Error: provide file_glob or file_regex, not both."
373
377
  return await registry.execute("fs_find", {
374
378
  "file_glob": file_glob,
379
+ "file_regex": file_regex,
375
380
  "path": path,
376
381
  "exclude_regex": exclude_regex,
377
382
  "max_results": max_results,
@@ -383,9 +388,12 @@ def create_server(workspace: Path | None = None, debug: bool = False) -> FastMCP
383
388
  "each matched file.\n"
384
389
  "\n"
385
390
  "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. Optional max_results_per_file caps matches per file.\n"
391
+ "default '*') or file_regex (mutually exclusive) under path\n"
392
+ "(default: workspace root). Returns 'path:line: content' per match,\n"
393
+ "capped at max_results (default: 100) and 300 chars per line. Optional\n"
394
+ "max_results_per_file caps matches per file. context_lines controls\n"
395
+ "how many surrounding lines are shown around each match; set to 0 for\n"
396
+ "compact output.\n"
389
397
  "\n"
390
398
  "Binary files are skipped when scanning a directory path. A single named\n"
391
399
  "file is always searched."
@@ -395,20 +403,26 @@ def create_server(workspace: Path | None = None, debug: bool = False) -> FastMCP
395
403
  async def fs_grep(
396
404
  grep_regex: str,
397
405
  file_glob: str | None = None,
406
+ file_regex: str | None = None,
398
407
  path: str | None = None,
399
408
  exclude_regex: str | None = None,
400
409
  max_results: int | None = None,
401
410
  max_results_per_file: int | None = None,
411
+ context_lines: int | None = None,
402
412
  ) -> str:
403
413
  if not grep_regex:
404
414
  return "Error: 'grep_regex' is required and must be non-empty."
415
+ if file_glob and file_regex:
416
+ return "Error: provide file_glob or file_regex, not both."
405
417
  return await registry.execute("fs_grep", {
406
418
  "grep_regex": grep_regex,
407
419
  "file_glob": file_glob,
420
+ "file_regex": file_regex,
408
421
  "path": path,
409
422
  "exclude_regex": exclude_regex,
410
423
  "max_results": max_results,
411
424
  "max_results_per_file": max_results_per_file,
425
+ "context_lines": context_lines,
412
426
  })
413
427
 
414
428
  return mcp
@@ -1,7 +1,15 @@
1
1
  """fs_find tool script.
2
2
 
3
- Find files by name under a directory. Approximately:
4
- [p for p in os.walk(path) if file_glob matches]
3
+ Find files by name. Approximately: [p for p in os.walk(path) if file_glob matches]
4
+
5
+ file_glob is a glob (e.g. '*.py', '**/test_*.py') matched against filenames
6
+ under path (default: workspace root, must be a directory). Alternatively,
7
+ file_regex provides a raw regex matched the same way (mutually exclusive
8
+ with file_glob): a pattern with no '/' matches basenames at any depth, a
9
+ pattern containing '/' matches the full relative path. Like grep_regex/
10
+ exclude_regex elsewhere in these tools, file_regex matches anywhere in the
11
+ name/path (re.search), not just the whole thing — anchor with ^/$ for an
12
+ exact match.
5
13
 
6
14
  Hidden dot-directories (and their contents) are pruned before descending —
7
15
  they are never walked, not just filtered from results — so this stays fast
@@ -13,13 +21,15 @@ match a leading dot but an explicit pattern does. Returns matching paths
13
21
  (relative to the workspace root when possible), one per line, capped at
14
22
  max_results.
15
23
  """
24
+ import glob as _glob
16
25
  import os
17
26
  import re
18
27
  import sys
19
28
  from pathlib import Path
20
29
 
21
30
  # --- Parameters ---
22
- file_glob = _PARAMS["file_glob"]
31
+ file_glob = _PARAMS.get("file_glob")
32
+ file_regex = _PARAMS.get("file_regex")
23
33
  path_str = _PARAMS.get("path") or "."
24
34
  exclude_regex = _PARAMS.get("exclude_regex")
25
35
  max_results = _PARAMS.get("max_results") or 100
@@ -48,51 +58,6 @@ def display_path(p: Path) -> str:
48
58
  return str(p)
49
59
 
50
60
 
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
61
  def is_hidden(name: str) -> bool:
97
62
  """True if a single path component is dot-prefixed."""
98
63
  return name.startswith(".")
@@ -106,11 +71,45 @@ def rel_posix(base: Path, dirpath: str) -> str:
106
71
  return rel.replace("\\", "/")
107
72
 
108
73
 
109
- # --- Main ---
110
- if not file_glob:
111
- print("file_glob must be non-empty.", file=sys.stderr)
74
+ # --- Input validation ---
75
+ if file_glob and file_regex:
76
+ print("Provide file_glob or file_regex, not both.", file=sys.stderr)
112
77
  sys.exit(1)
113
78
 
79
+ # Default to '*' glob when neither is specified
80
+ if not file_glob and not file_regex:
81
+ file_glob = "*"
82
+
83
+ # Build the compiled file-matching regex from whichever param was given.
84
+ if file_glob:
85
+ # glob.translate() is the stdlib's canonical glob-to-regex translator (Python 3.13+).
86
+ # include_hidden=True because pyddock handles hidden-file pruning separately in the
87
+ # walk loop (via is_hidden()/allow_hidden_files). seps="/" because rel_posix() always
88
+ # produces forward-slash paths regardless of OS.
89
+ file_pattern_rx = re.compile(
90
+ _glob.translate(file_glob, recursive=True, include_hidden=True, seps="/")
91
+ )
92
+ # A glob whose final segment starts with '.' explicitly targets hidden files.
93
+ allow_hidden_files = file_glob.rsplit("/", 1)[-1].startswith(".")
94
+ # A pattern with no '/' matches basenames only; otherwise match the full relative path.
95
+ match_basename_only = "/" not in file_glob
96
+ pattern_display = file_glob
97
+ else:
98
+ try:
99
+ file_pattern_rx = re.compile(file_regex)
100
+ except re.error as e:
101
+ print(f"Invalid file_regex '{file_regex}': {e}", file=sys.stderr)
102
+ sys.exit(1)
103
+ # Regex mode: no hidden-file allowance via pattern inspection — unlike a
104
+ # glob's leading '.', there's no reliable syntactic way to tell whether an
105
+ # arbitrary regex "means" to target a hidden file (use exclude_regex or
106
+ # point path at a hidden dir directly instead). Same basename-vs-full-path
107
+ # convention as file_glob: a pattern with no '/' matches basenames at any
108
+ # depth; a pattern containing '/' matches the full relative path.
109
+ allow_hidden_files = False
110
+ match_basename_only = "/" not in file_regex
111
+ pattern_display = file_regex
112
+
114
113
  exclude_re = None
115
114
  if exclude_regex:
116
115
  try:
@@ -119,19 +118,6 @@ if exclude_regex:
119
118
  print(f"Invalid exclude_regex '{exclude_regex}': {e}", file=sys.stderr)
120
119
  sys.exit(1)
121
120
 
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
121
  path = resolve_path(path_str)
136
122
 
137
123
  if not path.exists():
@@ -176,7 +162,13 @@ for dirpath, dirnames, filenames in os.walk(path):
176
162
  skipped_excluded += 1
177
163
  continue
178
164
  target = f if match_basename_only else rel_file
179
- if not file_regex.match(target):
165
+ # search, not match/fullmatch: glob-derived patterns are anchored on
166
+ # both ends by glob.translate() itself (its regex ends in \z), so
167
+ # search() behaves identically to fullmatch() for the file_glob case.
168
+ # For file_regex, search() keeps it consistent with grep_regex/
169
+ # exclude_regex elsewhere in these tools (substring match by default;
170
+ # the caller anchors with ^/$ if they want a whole-name match).
171
+ if not file_pattern_rx.search(target):
180
172
  continue
181
173
  results.append(Path(dirpath) / f)
182
174
  if len(results) >= max_results:
@@ -185,14 +177,15 @@ for dirpath, dirnames, filenames in os.walk(path):
185
177
 
186
178
  notes = []
187
179
  if truncated:
188
- notes.append(f"Showing first {max_results} results. Narrow file_glob or path to see more.")
180
+ pattern_param = "file_glob" if file_glob else "file_regex"
181
+ notes.append(f"Showing first {max_results} results. Narrow {pattern_param} or path to see more.")
189
182
  if skipped_hidden:
190
183
  notes.append(f"{skipped_hidden} hidden file(s)/dir(s) skipped.")
191
184
  if skipped_excluded:
192
185
  notes.append(f"{skipped_excluded} excluded file(s)/dir(s) skipped.")
193
186
 
194
187
  if not results:
195
- msg = f"No files matching '{file_glob}' found under '{path_str}'."
188
+ msg = f"No files matching '{pattern_display}' found under '{path_str}'."
196
189
  if notes:
197
190
  msg += " (" + " ".join(notes) + ")"
198
191
  print(msg)
@@ -4,6 +4,16 @@ Search file contents by regex (always case-insensitive). Approximately:
4
4
  fs_find() then re.search(grep_regex, line, re.IGNORECASE) per line of each
5
5
  matched file.
6
6
 
7
+ grep_regex is searched within each file matched by file_glob (glob,
8
+ default '*') or file_regex (mutually exclusive) under path (default:
9
+ workspace root). Returns 'path:line: content' per match, capped at
10
+ max_results (default: 100) and 300 chars per line. Optional
11
+ max_results_per_file caps matches per file. Like file_glob, file_regex
12
+ matches basenames at any depth unless it contains '/' (then it matches the
13
+ full relative path); like grep_regex/exclude_regex, file_regex matches
14
+ anywhere in the name/path (re.search), not just the whole thing — anchor
15
+ with ^/$ for an exact match.
16
+
7
17
  Hidden dot-directories are pruned before descending (see fs_find); an
8
18
  optional exclude_regex prunes/excludes additional entries the same way. A
9
19
  file_glob whose final segment starts with '.' (e.g. '.env') explicitly
@@ -14,8 +24,11 @@ Binary files are skipped when scanning a directory path (sniffed from the
14
24
  same read used for matching — no separate open). A single named file is
15
25
  always searched, binary or not.
16
26
 
17
- max_results_per_file (optional) caps matches per individual file.
27
+ context_lines controls how many surrounding lines are shown around each
28
+ match. Default: 1 for directory scans, 4 for single-file targets. Set to 0
29
+ for compact output with no context.
18
30
  """
31
+ import glob as _glob
19
32
  import os
20
33
  import re
21
34
  import sys
@@ -23,11 +36,13 @@ from pathlib import Path
23
36
 
24
37
  # --- Parameters ---
25
38
  grep_regex = _PARAMS["grep_regex"]
26
- file_glob = _PARAMS.get("file_glob") or "*"
39
+ file_glob = _PARAMS.get("file_glob")
40
+ file_regex = _PARAMS.get("file_regex")
27
41
  path_str = _PARAMS.get("path") or "."
28
42
  exclude_regex = _PARAMS.get("exclude_regex")
29
43
  max_results = _PARAMS.get("max_results") or 100
30
44
  max_results_per_file = _PARAMS.get("max_results_per_file")
45
+ context_lines = _PARAMS.get("context_lines") # None = adaptive default
31
46
  workspace_root = _PARAMS["workspace_root"]
32
47
 
33
48
  # --- Constants ---
@@ -57,51 +72,6 @@ def display_path(p: Path) -> str:
57
72
  return str(p)
58
73
 
59
74
 
60
- def translate_glob(pattern: str) -> str:
61
- """Translate a glob pattern to an anchored regex.
62
-
63
- Supports '*' (any run of non-separator chars), '?' (one non-separator
64
- char), '[seq]'/'[!seq]' character classes, and '**' as a recursive
65
- any-depth-of-segments wildcard. Matched against a forward-slash path.
66
- """
67
- i, n = 0, len(pattern)
68
- out: list[str] = []
69
- while i < n:
70
- c = pattern[i]
71
- i += 1
72
- if c == "*":
73
- if i < n and pattern[i] == "*":
74
- i += 1
75
- if i < n and pattern[i] == "/":
76
- i += 1
77
- out.append("(?:.*/)?")
78
- else:
79
- out.append(".*")
80
- else:
81
- out.append("[^/]*")
82
- elif c == "?":
83
- out.append("[^/]")
84
- elif c == "[":
85
- j = i
86
- if j < n and pattern[j] == "!":
87
- j += 1
88
- if j < n and pattern[j] == "]":
89
- j += 1
90
- while j < n and pattern[j] != "]":
91
- j += 1
92
- if j >= n:
93
- out.append(re.escape("["))
94
- else:
95
- stuff = pattern[i:j]
96
- if stuff.startswith("!"):
97
- stuff = "^" + stuff[1:]
98
- out.append("[" + stuff + "]")
99
- i = j + 1
100
- else:
101
- out.append(re.escape(c))
102
- return "^" + "".join(out) + "$"
103
-
104
-
105
75
  def is_hidden(name: str) -> bool:
106
76
  """True if a single path component is dot-prefixed."""
107
77
  return name.startswith(".")
@@ -144,6 +114,59 @@ def read_text_or_skip_reason(p: Path) -> tuple[str | None, str | None]:
144
114
  return (chunk + rest).decode("utf-8", errors="replace"), None
145
115
 
146
116
 
117
+ def format_matches_with_context(
118
+ lines: list[str], match_line_nums: list[int], label: str, ctx: int
119
+ ) -> list[str]:
120
+ """Format matched lines with surrounding context, merging overlapping groups.
121
+
122
+ Uses grep-style output:
123
+ path:linenum: matched line content
124
+ path-linenum- context line content
125
+ Groups of matches whose context windows overlap are merged and separated
126
+ from non-overlapping groups by a '--' line.
127
+
128
+ Args:
129
+ lines: All lines in the file (0-indexed list).
130
+ match_line_nums: 1-indexed line numbers that matched.
131
+ label: Display path prefix for each output line.
132
+ ctx: Number of context lines before and after each match.
133
+
134
+ Returns:
135
+ List of formatted output strings.
136
+ """
137
+ if not match_line_nums:
138
+ return []
139
+
140
+ total = len(lines)
141
+ output: list[str] = []
142
+
143
+ # Build merged groups of (start_0idx, end_0idx_exclusive, set_of_match_0idxs)
144
+ groups: list[tuple[int, int, set[int]]] = []
145
+ for ln in match_line_nums:
146
+ idx = ln - 1 # convert to 0-indexed
147
+ start = max(0, idx - ctx)
148
+ end = min(total, idx + ctx + 1)
149
+ if groups and start <= groups[-1][1]:
150
+ # Merge with previous group
151
+ prev_start, prev_end, prev_matches = groups[-1]
152
+ groups[-1] = (prev_start, max(prev_end, end), prev_matches | {idx})
153
+ else:
154
+ groups.append((start, end, {idx}))
155
+
156
+ for gi, (start, end, match_idxs) in enumerate(groups):
157
+ if gi > 0:
158
+ output.append("--")
159
+ for i in range(start, end):
160
+ line_content = truncate_line(lines[i])
161
+ line_num = i + 1 # 1-indexed for display
162
+ if i in match_idxs:
163
+ output.append(f"{label}:{line_num}: {line_content}")
164
+ else:
165
+ output.append(f"{label}-{line_num}- {line_content}")
166
+
167
+ return output
168
+
169
+
147
170
  # --- Main ---
148
171
  if not grep_regex:
149
172
  print("grep_regex must be non-empty.", file=sys.stderr)
@@ -155,6 +178,31 @@ except re.error as e:
155
178
  print(f"Invalid grep_regex '{grep_regex}': {e}", file=sys.stderr)
156
179
  sys.exit(1)
157
180
 
181
+ # --- File pattern validation (mutually exclusive) ---
182
+ if file_glob and file_regex:
183
+ print("Provide file_glob or file_regex, not both.", file=sys.stderr)
184
+ sys.exit(1)
185
+
186
+ if not file_glob and not file_regex:
187
+ file_glob = "*"
188
+
189
+ if file_glob:
190
+ file_pattern_rx = re.compile(
191
+ _glob.translate(file_glob, recursive=True, include_hidden=True, seps="/")
192
+ )
193
+ allow_hidden_files = file_glob.rsplit("/", 1)[-1].startswith(".")
194
+ match_basename_only = "/" not in file_glob
195
+ else:
196
+ try:
197
+ file_pattern_rx = re.compile(file_regex)
198
+ except re.error as e:
199
+ print(f"Invalid file_regex '{file_regex}': {e}", file=sys.stderr)
200
+ sys.exit(1)
201
+ # See fs_find.py for the rationale on allow_hidden_files and
202
+ # match_basename_only in regex mode.
203
+ allow_hidden_files = False
204
+ match_basename_only = "/" not in file_regex
205
+
158
206
  exclude_re = None
159
207
  if exclude_regex:
160
208
  try:
@@ -163,17 +211,6 @@ if exclude_regex:
163
211
  print(f"Invalid exclude_regex '{exclude_regex}': {e}", file=sys.stderr)
164
212
  sys.exit(1)
165
213
 
166
- # Matching strategy mirrors Path.rglob() (see fs_find.py's translate_glob).
167
- match_basename_only = "/" not in file_glob
168
- file_regex = re.compile(translate_glob(file_glob))
169
-
170
- # A glob whose final segment starts with '.' explicitly targets hidden files
171
- # (e.g. '.env', '**/.env') — mirrors shell semantics where '*' does not match
172
- # a leading dot but an explicit pattern does. Hidden DIRECTORIES are still
173
- # pruned regardless (performance); point `path` directly at one to search
174
- # inside it.
175
- allow_hidden_files = file_glob.rsplit("/", 1)[-1].startswith(".")
176
-
177
214
  path = resolve_path(path_str)
178
215
 
179
216
  if not path.exists():
@@ -181,16 +218,23 @@ if not path.exists():
181
218
  sys.exit(1)
182
219
 
183
220
  matches: list[str] = []
221
+ match_count = 0 # counts actual match lines (not context) for max_results
184
222
  skipped_hidden = 0
185
223
  skipped_excluded = 0
186
224
  skipped_binary = 0
187
225
  skipped_unreadable = 0
188
226
  truncated = False
189
227
 
190
- if path.is_file():
228
+ # Resolve adaptive context_lines default: 4 for single-file, 1 for dir scan.
229
+ is_single_file = path.is_file()
230
+ if context_lines is not None:
231
+ ctx = max(0, int(context_lines))
232
+ else:
233
+ ctx = 4 if is_single_file else 1
234
+
235
+ if is_single_file:
191
236
  # A directly named file is always searched — bypasses hidden/exclude/glob
192
- # filtering and the binary sniff. Covers grepping a partially corrupted
193
- # log file, or a dotfile named explicitly.
237
+ # filtering and the binary sniff.
194
238
  try:
195
239
  text = path.read_text(encoding="utf-8", errors="replace")
196
240
  except OSError:
@@ -199,26 +243,32 @@ if path.is_file():
199
243
 
200
244
  if text is not None:
201
245
  label = display_path(path)
202
- file_match_count = 0
203
- for line_num, line in enumerate(text.splitlines(), start=1):
246
+ all_lines = text.splitlines()
247
+ match_line_nums: list[int] = []
248
+ for line_num, line in enumerate(all_lines, start=1):
204
249
  if regex.search(line):
205
- matches.append(f"{label}:{line_num}: {truncate_line(line)}")
206
- file_match_count += 1
207
- if len(matches) >= max_results:
250
+ match_line_nums.append(line_num)
251
+ match_count += 1
252
+ if match_count >= max_results:
208
253
  truncated = True
209
254
  break
210
- if max_results_per_file and file_match_count >= max_results_per_file:
255
+ if max_results_per_file and match_count >= max_results_per_file:
211
256
  break
257
+
258
+ if ctx > 0:
259
+ matches = format_matches_with_context(all_lines, match_line_nums, label, ctx)
260
+ else:
261
+ for ln in match_line_nums:
262
+ matches.append(f"{label}:{ln}: {truncate_line(all_lines[ln - 1])}")
212
263
  else:
213
264
  # Single pass: walk, filter, and match together so max_results can stop
214
265
  # the walk early instead of enumerating the entire (pruned) tree first.
215
- for dirpath, dirnames, filenames in os.walk(path):
266
+ for dirpath_str, dirnames, filenames in os.walk(path):
216
267
  if truncated:
217
268
  break
218
- rel_dir = rel_posix(path, dirpath)
269
+ rel_dir = rel_posix(path, dirpath_str)
219
270
 
220
- # Prune hidden / excluded subdirectories BEFORE os.walk descends into
221
- # them — never walked, not just filtered from results.
271
+ # Prune hidden / excluded subdirectories BEFORE os.walk descends.
222
272
  kept_dirnames = []
223
273
  for d in dirnames:
224
274
  if is_hidden(d):
@@ -232,6 +282,8 @@ else:
232
282
  dirnames[:] = kept_dirnames
233
283
 
234
284
  for f in filenames:
285
+ if truncated:
286
+ break
235
287
  if is_hidden(f) and not allow_hidden_files:
236
288
  skipped_hidden += 1
237
289
  continue
@@ -240,10 +292,11 @@ else:
240
292
  skipped_excluded += 1
241
293
  continue
242
294
  target = f if match_basename_only else rel_file
243
- if not file_regex.match(target):
295
+ # search, not match/fullmatch — see fs_find.py for rationale.
296
+ if not file_pattern_rx.search(target):
244
297
  continue
245
298
 
246
- candidate = Path(dirpath) / f
299
+ candidate = Path(dirpath_str) / f
247
300
  text, reason = read_text_or_skip_reason(candidate)
248
301
  if reason == "binary":
249
302
  skipped_binary += 1
@@ -253,18 +306,27 @@ else:
253
306
  continue
254
307
 
255
308
  label = display_path(candidate)
309
+ all_lines = text.splitlines()
256
310
  file_match_count = 0
257
- for line_num, line in enumerate(text.splitlines(), start=1):
311
+ match_line_nums = []
312
+ for line_num, line in enumerate(all_lines, start=1):
258
313
  if regex.search(line):
259
- matches.append(f"{label}:{line_num}: {truncate_line(line)}")
314
+ match_line_nums.append(line_num)
260
315
  file_match_count += 1
261
- if len(matches) >= max_results:
316
+ match_count += 1
317
+ if match_count >= max_results:
262
318
  truncated = True
263
319
  break
264
320
  if max_results_per_file and file_match_count >= max_results_per_file:
265
321
  break
266
- if truncated:
267
- break
322
+
323
+ if ctx > 0:
324
+ matches.extend(
325
+ format_matches_with_context(all_lines, match_line_nums, label, ctx)
326
+ )
327
+ else:
328
+ for ln in match_line_nums:
329
+ matches.append(f"{label}:{ln}: {truncate_line(all_lines[ln - 1])}")
268
330
 
269
331
  notes = []
270
332
  if truncated:
@@ -37,6 +37,7 @@ pathlib = true
37
37
  re = true
38
38
  difflib = true
39
39
  datetime = true
40
+ glob = true
40
41
 
41
42
  [filesystem]
42
43
  writable_paths = ["."]
@@ -614,8 +615,10 @@ class TestFsGrep:
614
615
  (d / f"f{i}.txt").write_text("needle\n" * 5, encoding="utf-8")
615
616
  result = run(registry, "fs_grep", {
616
617
  "grep_regex": "needle", "path": str(d), "max_results": 3,
618
+ "context_lines": 0,
617
619
  })
618
620
  assert "Showing first 3 matches" in result
621
+ # With context_lines=0, only match lines appear (each contains "needle" once)
619
622
  assert result.count("needle") == 3
620
623
 
621
624
  def test_max_results_per_file_caps_matches_within_a_file(self, ws: Path, registry: ScriptToolRegistry):
@@ -628,7 +631,9 @@ class TestFsGrep:
628
631
 
629
632
  result = run(registry, "fs_grep", {
630
633
  "grep_regex": "needle", "path": str(ws), "max_results_per_file": 2,
634
+ "context_lines": 0,
631
635
  })
636
+ # Only match lines (context_lines=0), so count filename occurrences directly
632
637
  assert result.count("dense.txt") == 2
633
638
  assert "sparse.txt" in result
634
639
 
@@ -640,9 +645,219 @@ class TestFsGrep:
640
645
 
641
646
  result = run(registry, "fs_grep", {
642
647
  "grep_regex": "needle", "path": str(f), "max_results_per_file": 3,
648
+ "context_lines": 0,
643
649
  })
650
+ # With context_lines=0, each match line contains the filename once
644
651
  assert result.count("dense.txt") == 3
645
652
 
653
+ def test_file_regex_filters_files(self, ws: Path, registry: ScriptToolRegistry):
654
+ """file_regex as alternative to file_glob restricts which files are searched."""
655
+ (ws / "Server.log").write_text("needle\n", encoding="utf-8")
656
+ (ws / "Client.log").write_text("needle\n", encoding="utf-8")
657
+ (ws / "other.txt").write_text("needle\n", encoding="utf-8")
658
+ result = run(registry, "fs_grep", {
659
+ "grep_regex": "needle", "file_regex": r"(Server|Client)\.log",
660
+ "path": str(ws), "context_lines": 0,
661
+ })
662
+ assert "Server.log" in result
663
+ assert "Client.log" in result
664
+ assert "other.txt" not in result
665
+
666
+ def test_file_glob_and_file_regex_mutually_exclusive(self, ws: Path, registry: ScriptToolRegistry):
667
+ """Passing both file_glob and file_regex is an error."""
668
+ (ws / "a.py").write_text("needle\n", encoding="utf-8")
669
+ result = run(registry, "fs_grep", {
670
+ "grep_regex": "needle", "file_glob": "*.py",
671
+ "file_regex": "a", "path": str(ws),
672
+ })
673
+ assert "not both" in result.lower()
674
+
675
+ def test_grep_file_regex_with_slash_matches_full_relative_path(
676
+ self, ws: Path, registry: ScriptToolRegistry,
677
+ ):
678
+ """A file_regex containing '/' scopes to the full relative path,
679
+ mirroring file_glob's basename-vs-full-path convention."""
680
+ sub = ws / "sub"
681
+ sub.mkdir()
682
+ (sub / "target.py").write_text("needle\n", encoding="utf-8")
683
+ (ws / "target.py").write_text("needle\n", encoding="utf-8")
684
+
685
+ result = run(registry, "fs_grep", {
686
+ "grep_regex": "needle", "file_regex": r"sub/target\.py",
687
+ "path": str(ws), "context_lines": 0,
688
+ })
689
+ assert "sub/target.py" in result
690
+ assert result.count("target.py") == 1
691
+
692
+ def test_grep_file_regex_matches_as_substring(self, ws: Path, registry: ScriptToolRegistry):
693
+ """file_regex matches anywhere in the name (re.search), like
694
+ grep_regex/exclude_regex — a partial pattern missing the extension
695
+ still matches."""
696
+ (ws / "fs_find.py").write_text("needle\n", encoding="utf-8")
697
+ result = run(registry, "fs_grep", {
698
+ "grep_regex": "needle", "file_regex": r"fs_find", "path": str(ws),
699
+ })
700
+ assert "fs_find.py" in result
701
+
702
+ def test_grep_file_regex_can_be_anchored_for_exact_match(self, ws: Path, registry: ScriptToolRegistry):
703
+ """A caller wanting an exact-name match can anchor file_regex with ^/$."""
704
+ (ws / "fs_find.py").write_text("needle\n", encoding="utf-8")
705
+ (ws / "fs_find.pyc").write_text("needle\n", encoding="utf-8")
706
+ result = run(registry, "fs_grep", {
707
+ "grep_regex": "needle", "file_regex": r"^fs_find\.py$", "path": str(ws),
708
+ })
709
+ assert "fs_find.py:" in result
710
+ assert "fs_find.pyc" not in result
711
+
712
+ def test_context_lines_default_directory_scan(self, ws: Path, registry: ScriptToolRegistry):
713
+ """Directory scan defaults to 1 line of context around matches."""
714
+ f = ws / "ctx.txt"
715
+ f.write_text("line1\nline2\nneedle\nline4\nline5\n", encoding="utf-8")
716
+ result = run(registry, "fs_grep", {"grep_regex": "needle", "path": str(ws)})
717
+ # Match line uses ':'
718
+ assert "ctx.txt:3:" in result
719
+ # Context lines use '-' separator and show 1 before/after
720
+ assert "ctx.txt-2-" in result
721
+ assert "ctx.txt-4-" in result
722
+ # Lines outside the 1-line context window should NOT appear
723
+ assert "ctx.txt-1-" not in result
724
+ assert "ctx.txt-5-" not in result
725
+
726
+ def test_context_lines_default_single_file(self, ws: Path, registry: ScriptToolRegistry):
727
+ """Single-file target defaults to 4 lines of context around matches."""
728
+ f = ws / "ctx_single.txt"
729
+ lines = [f"line{i}" for i in range(1, 12)]
730
+ lines[5] = "needle" # line 6 (1-indexed)
731
+ f.write_text("\n".join(lines) + "\n", encoding="utf-8")
732
+ result = run(registry, "fs_grep", {"grep_regex": "needle", "path": str(f)})
733
+ # Match at line 6 with 4 context -> lines 2..10
734
+ assert "ctx_single.txt:6:" in result
735
+ assert "ctx_single.txt-2-" in result # 4 lines before
736
+ assert "ctx_single.txt-10-" in result # 4 lines after
737
+
738
+ def test_context_lines_zero_compact(self, ws: Path, registry: ScriptToolRegistry):
739
+ """context_lines=0 produces compact output with no context."""
740
+ f = ws / "compact.txt"
741
+ f.write_text("before\nneedle\nafter\n", encoding="utf-8")
742
+ result = run(registry, "fs_grep", {
743
+ "grep_regex": "needle", "path": str(ws), "context_lines": 0,
744
+ })
745
+ assert "compact.txt:2:" in result
746
+ # No context lines
747
+ assert "compact.txt-1-" not in result
748
+ assert "compact.txt-3-" not in result
749
+
750
+ def test_context_lines_overlap_merged(self, ws: Path, registry: ScriptToolRegistry):
751
+ """Adjacent matches have their context windows merged, separated by '--'
752
+ only between non-overlapping groups."""
753
+ f = ws / "overlap.txt"
754
+ # Matches on lines 2 and 4 (context_lines=1 -> windows [1..3] and [3..5] overlap -> merged)
755
+ # Match on line 9 (window [8..10]) is separated from the first group by a gap (lines 6-7)
756
+ content = "line1\nneedle_a\nline3\nneedle_b\nline5\nline6\nline7\nline8\nneedle_c\nline10\n"
757
+ f.write_text(content, encoding="utf-8")
758
+ result = run(registry, "fs_grep", {
759
+ "grep_regex": "needle", "path": str(ws), "context_lines": 1,
760
+ })
761
+ # needle_a (line2) and needle_b (line4) overlap -> merged, no '--' between them
762
+ # needle_c (line9) is separated -> '--' before it
763
+ assert "--" in result
764
+ lines = result.splitlines()
765
+ sep_indices = [i for i, l in enumerate(lines) if l == "--"]
766
+ assert len(sep_indices) == 1
767
+
768
+
769
+ # =============================================================================
770
+ # fs_find file_regex tests
771
+ # =============================================================================
772
+
773
+
774
+ class TestFsFindFileRegex:
775
+ def test_file_regex_matches(self, ws: Path, registry: ScriptToolRegistry):
776
+ """file_regex matches filenames by regex."""
777
+ (ws / "Server.log").write_text("x", encoding="utf-8")
778
+ (ws / "Client.log").write_text("x", encoding="utf-8")
779
+ (ws / "other.txt").write_text("x", encoding="utf-8")
780
+ result = run(registry, "fs_find", {
781
+ "file_regex": r"(Server|Client)\.log", "path": str(ws),
782
+ })
783
+ assert "Server.log" in result
784
+ assert "Client.log" in result
785
+ assert "other.txt" not in result
786
+
787
+ def test_file_glob_and_file_regex_mutually_exclusive(self, ws: Path, registry: ScriptToolRegistry):
788
+ """Passing both file_glob and file_regex is an error."""
789
+ (ws / "a.py").write_text("x", encoding="utf-8")
790
+ result = run(registry, "fs_find", {
791
+ "file_glob": "*.py", "file_regex": "a", "path": str(ws),
792
+ })
793
+ assert "not both" in result.lower()
794
+
795
+ def test_invalid_file_regex(self, ws: Path, registry: ScriptToolRegistry):
796
+ """Invalid file_regex -> error, not a crash."""
797
+ (ws / "a.py").write_text("x", encoding="utf-8")
798
+ result = run(registry, "fs_find", {
799
+ "file_regex": "(unclosed", "path": str(ws),
800
+ })
801
+ assert "Invalid file_regex" in result
802
+
803
+ def test_find_file_regex_with_slash_matches_full_relative_path(
804
+ self, ws: Path, registry: ScriptToolRegistry,
805
+ ):
806
+ """A file_regex containing '/' matches the full relative path from
807
+ path, mirroring file_glob's basename-vs-full-path convention."""
808
+ sub = ws / "sub"
809
+ sub.mkdir()
810
+ (sub / "target.py").write_text("x", encoding="utf-8")
811
+ (ws / "target.py").write_text("x", encoding="utf-8")
812
+
813
+ # Without a slash, matches basenames at any depth -> both files.
814
+ result_basename = run(registry, "fs_find", {
815
+ "file_regex": r"target\.py", "path": str(ws),
816
+ })
817
+ assert result_basename.count("target.py") == 2
818
+
819
+ # With a slash, scopes to the full relative path -> only the nested one.
820
+ result_scoped = run(registry, "fs_find", {
821
+ "file_regex": r"sub/target\.py", "path": str(ws),
822
+ })
823
+ assert "sub/target.py" in result_scoped
824
+ assert result_scoped.count("target.py") == 1
825
+
826
+ def test_find_file_regex_matches_as_substring(self, ws: Path, registry: ScriptToolRegistry):
827
+ """file_regex matches anywhere in the name (re.search), like
828
+ exclude_regex — a partial pattern missing the extension still matches."""
829
+ (ws / "fs_find.py").write_text("x", encoding="utf-8")
830
+ result = run(registry, "fs_find", {
831
+ "file_regex": r"fs_find", "path": str(ws),
832
+ })
833
+ assert "fs_find.py" in result
834
+
835
+ def test_find_file_regex_can_be_anchored_for_exact_match(self, ws: Path, registry: ScriptToolRegistry):
836
+ """A caller wanting an exact-name match can anchor file_regex with ^/$."""
837
+ (ws / "fs_find.py").write_text("x", encoding="utf-8")
838
+ (ws / "fs_find.pyc").write_text("x", encoding="utf-8")
839
+ result = run(registry, "fs_find", {
840
+ "file_regex": r"^fs_find\.py$", "path": str(ws),
841
+ })
842
+ assert "fs_find.py" in result
843
+ assert "fs_find.pyc" not in result
844
+
845
+ def test_find_file_regex_truncation_note_names_file_regex(
846
+ self, ws: Path, registry: ScriptToolRegistry,
847
+ ):
848
+ """The truncation hint names the parameter actually in use — it should
849
+ say 'file_regex', not 'file_glob', when file_regex was the active
850
+ pattern (regression: the note used to hardcode 'file_glob')."""
851
+ d = ws / "many"
852
+ d.mkdir()
853
+ for i in range(10):
854
+ (d / f"f{i}.py").write_text("x", encoding="utf-8")
855
+ result = run(registry, "fs_find", {
856
+ "file_regex": r"\.py$", "path": str(d), "max_results": 3,
857
+ })
858
+ assert "Narrow file_regex or path" in result
859
+ assert "file_glob" not in result
860
+
646
861
 
647
862
  # =============================================================================
648
863
  # Sandbox enforcement tests
@@ -691,6 +906,7 @@ pathlib = true
691
906
  re = true
692
907
  difflib = true
693
908
  datetime = true
909
+ glob = true
694
910
 
695
911
  [filesystem]
696
912
  writable_paths = ["."]
@@ -743,6 +959,7 @@ pathlib = true
743
959
  re = true
744
960
  difflib = true
745
961
  datetime = true
962
+ glob = true
746
963
  [filesystem]
747
964
  writable_paths = ["."]
748
965
  readable_paths = ["."]
@@ -480,7 +480,7 @@ wheels = [
480
480
 
481
481
  [[package]]
482
482
  name = "pyddock"
483
- version = "0.3.5"
483
+ version = "0.3.6"
484
484
  source = { editable = "." }
485
485
  dependencies = [
486
486
  { name = "mcp" },
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes