claude-dev-env 4.0.0 → 4.2.0

package/.agents/skills/everything-search/SKILL.md

@@ -13,13 +13,23 @@ Search files instantly on Windows using the Everything command-line interface (e
 
 ## Hard limits
 
-Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds — narrow the search to what you need.
+Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds. Narrow the search to what you need.
 
 When `es.exe` fails or returns nothing, self-heal first: fall back to the `Glob` tool (name and path patterns) or `Grep` (file contents), and report the outage so the reader knows the index was unavailable. When self-healing also fails, ask the user through `AskUserQuestion` with a short analysis and next-step options.
 
 ## Registry tokens
 
-The `es_exe_path_rewriter` hook resolves scope tokens before the command runs. A `{project-name}` placeholder or a bare registry key from `~/.claude/project-paths.json` becomes its quoted absolute path in the command. The hook allows and rewrites — it never blocks — so a search scoped to a registered project names the project token and lets the hook fill in the path.
+Run project-name searches through this command:
+
+```text
+python "${CLAUDE_SKILL_DIR}/scripts/everything_search.py" <project-name> <search arguments>
+```
+
+The command reads `~/.claude/project-paths.json`. An exact project name or `{project-name}` argument becomes one absolute path. Unknown names, absolute paths, flags, and spaces stay as they are. The command then starts `es.exe` without a shell.
+
+Put the search scope first. The first argument names a project, path, file, extension, date, or size. An options-only request exits before `es.exe` starts. Use `-version` alone to read the installed Everything version.
+
+Path and operator searches run when the registry file is missing. Malformed registry content, an empty search, a missing `es.exe`, or a process start failure returns a nonzero exit. After a successful start, the command returns the `es.exe` exit status.
 
 ## Instructions
 
@@ -131,7 +141,7 @@ Run separate searches for each extension type:
 
 - Everything must be running (system tray) for es.exe to work
 - Run one extension per search for cleaner results
-- Use `dm:` for recent file searches instead of manual date filtering
+- Use `dm:` to filter recent files by the index timestamp
 - Combine with path to narrow scope
 - Results return instantly regardless of drive size
 
@@ -152,3 +162,8 @@ Everything indexes REAL paths only, not junctions or mapped drives.
 **Common drive mappings:**
 - `Z:\Projects\` -> `Y:\Work\Projects\`
 - When in Z:\, translate to Y:\ equivalent for Everything searches
+
+## Files
+
+- `scripts/everything_search.py` runs one Everything search without a shell.
+- `scripts/test_everything_search.py` verifies registry expansion and command failures.

package/.agents/skills/everything-search/scripts/everything_search.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import TextIO
+
+from everything_search_command_constants.config.constants import (
+    CLAUDE_DIRECTORY_NAME,
+    EXECUTABLE_NAME,
+    EXECUTION_ERROR_EXIT_CODE,
+    INFORMATIONAL_ARGUMENT,
+    INVALID_INPUT_EXIT_CODE,
+    PROJECT_PATHS_FILE_NAME,
+    REGISTRY_META_KEY,
+    SEARCH_SCOPE_REQUIRED_MESSAGE,
+    UTF8_ENCODING,
+)
+
+
+class RegistryRunFatal(ValueError):
+    """Stop the run when the project-path registry is unreadable or invalid."""
+
+
+def load_registry(registry_path: Path) -> dict[str, str]:
+    """Read project names and absolute paths from a registry file.
+
+    Args:
+        registry_path: Registry file to read.
+
+    Returns:
+        The registered paths keyed by project name.
+
+    Raises:
+        RegistryRunFatal: The file is unreadable or its content is invalid.
+    """
+    if not registry_path.is_file():
+        return {}
+    try:
+        all_registry_entries = json.loads(
+            registry_path.read_text(encoding=UTF8_ENCODING)
+        )
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise RegistryRunFatal(f"Malformed registry: {error}") from error
+    return _validated_registry_entries(all_registry_entries)
+
+
+def _validated_registry_entries(all_registry_entries: object) -> dict[str, str]:
+    if not isinstance(all_registry_entries, dict):
+        raise RegistryRunFatal("Invalid registry: expected an object")
+    all_registered_paths_by_name: dict[str, str] = {}
+    for each_registry_name, each_registered_path in all_registry_entries.items():
+        if each_registry_name == REGISTRY_META_KEY:
+            continue
+        if not isinstance(each_registry_name, str) or not isinstance(
+            each_registered_path, str
+        ):
+            raise RegistryRunFatal("Invalid registry: names and paths must be strings")
+        if not _is_absolute_path(each_registered_path):
+            raise RegistryRunFatal("Invalid registry: paths must be absolute")
+        all_registered_paths_by_name[each_registry_name] = each_registered_path
+    return all_registered_paths_by_name
+
+
+def _is_absolute_path(search_argument: str) -> bool:
+    try:
+        return (
+            PureWindowsPath(search_argument).is_absolute()
+            or PurePosixPath(search_argument).is_absolute()
+        )
+    except ValueError:
+        return False
+
+
+def _registry_name(search_argument: str) -> str:
+    if search_argument.startswith("{") and search_argument.endswith("}"):
+        return search_argument[1:-1]
+    return search_argument
+
+
+def expand_search_arguments(
+    all_search_arguments: Sequence[str],
+    all_registered_paths_by_name: Mapping[str, str],
+) -> list[str]:
+    """Return the registered path for an exact project name or `{project-name}` token.
+
+    Unknown names, absolute paths, flags, and spaces stay as their own arguments.
+
+    Args:
+        all_search_arguments: Everything search arguments.
+        all_registered_paths_by_name: Absolute paths keyed by project name.
+
+    Returns:
+        Arguments with exact project names as their registered paths.
+    """
+    all_expanded_arguments: list[str] = []
+    for each_search_argument in all_search_arguments:
+        registry_name = _registry_name(each_search_argument)
+        if (
+            not _is_absolute_path(each_search_argument)
+            and registry_name in all_registered_paths_by_name
+        ):
+            all_expanded_arguments.append(all_registered_paths_by_name[registry_name])
+        else:
+            all_expanded_arguments.append(each_search_argument)
+    return all_expanded_arguments
+
+
+def _run_search(
+    executable_path: str,
+    all_search_arguments: Sequence[str],
+    search_stdout: TextIO,
+    search_stderr: TextIO,
+) -> int:
+    try:
+        search_run = subprocess.run(
+            [executable_path, *all_search_arguments],
+            capture_output=True,
+            check=False,
+            encoding=UTF8_ENCODING,
+            shell=False,
+            text=True,
+        )
+    except OSError as error:
+        search_stderr.write(f"{error}\n")
+        return EXECUTION_ERROR_EXIT_CODE
+    search_stdout.write(search_run.stdout)
+    search_stderr.write(search_run.stderr)
+    return search_run.returncode
+
+
+def _run_registered_search(
+    all_search_arguments: Sequence[str],
+    registry_path: Path,
+    executable_path: str | None,
+    search_stdout: TextIO,
+    search_stderr: TextIO,
+) -> int:
+    try:
+        all_registered_paths_by_name = load_registry(registry_path)
+    except RegistryRunFatal as error:
+        search_stderr.write(f"{error}\n")
+        return INVALID_INPUT_EXIT_CODE
+    selected_executable_path = executable_path or shutil.which(EXECUTABLE_NAME)
+    if selected_executable_path is None:
+        search_stderr.write(f"{EXECUTABLE_NAME} was not found.\n")
+        return EXECUTION_ERROR_EXIT_CODE
+    all_expanded_arguments = expand_search_arguments(
+        all_search_arguments, all_registered_paths_by_name
+    )
+    return _run_search(
+        selected_executable_path,
+        all_expanded_arguments,
+        search_stdout,
+        search_stderr,
+    )
+
+
+def _has_search_scope(all_search_arguments: Sequence[str]) -> bool:
+    first_argument = all_search_arguments[0]
+    return bool(first_argument.strip()) and not first_argument.startswith("-")
+
+
+def _is_informational_operation(all_search_arguments: Sequence[str]) -> bool:
+    return (
+        len(all_search_arguments) == 1
+        and all_search_arguments[0].casefold() == INFORMATIONAL_ARGUMENT
+    )
+
+
+def main(all_search_arguments: Sequence[str]) -> int:
+    """Expand project names and run one Everything search.
+
+    Args:
+        all_search_arguments: Arguments passed to Everything.
+
+    Returns:
+        The Everything process exit status or a command error status.
+    """
+    if not all_search_arguments:
+        sys.stderr.write("At least one search argument is required.\n")
+        return INVALID_INPUT_EXIT_CODE
+    if not _has_search_scope(all_search_arguments) and not _is_informational_operation(
+        all_search_arguments
+    ):
+        sys.stderr.write(SEARCH_SCOPE_REQUIRED_MESSAGE)
+        return INVALID_INPUT_EXIT_CODE
+    selected_registry_path = (
+        Path.home() / CLAUDE_DIRECTORY_NAME / PROJECT_PATHS_FILE_NAME
+    )
+    return _run_registered_search(
+        all_search_arguments,
+        selected_registry_path,
+        None,
+        sys.stdout,
+        sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/.agents/skills/everything-search/scripts/everything_search_command_constants/__init__.py

@@ -0,0 +1 @@
+"""Constants for the Everything search command."""

package/.agents/skills/everything-search/scripts/everything_search_command_constants/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration for the Everything search command."""

package/.agents/skills/everything-search/scripts/everything_search_command_constants/config/constants.py

@@ -0,0 +1,11 @@
+"""Configuration constants for the Everything search command."""
+
+CLAUDE_DIRECTORY_NAME = ".claude"
+EXECUTABLE_NAME = "es.exe"
+EXECUTION_ERROR_EXIT_CODE = 1
+INFORMATIONAL_ARGUMENT = "-version"
+INVALID_INPUT_EXIT_CODE = 2
+PROJECT_PATHS_FILE_NAME = "project-paths.json"
+REGISTRY_META_KEY = "_meta"
+SEARCH_SCOPE_REQUIRED_MESSAGE = "The first search argument must define a path, project, name, extension, date, or size scope.\n"
+UTF8_ENCODING = "utf-8"

package/.agents/skills/everything-search/scripts/test_everything_search.py

@@ -0,0 +1,172 @@
+import importlib
+import io
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+search = importlib.import_module("everything_search")
+
+KNOWN_PATH = "Y:\\Projects\\my-repo"
+REGISTRY = {"my-repo": KNOWN_PATH}
+
+
+def test_expand_search_arguments_rewrites_bare_registry_token() -> None:
+    assert search.expand_search_arguments(["my-repo", "config.py"], REGISTRY) == [
+        KNOWN_PATH,
+        "config.py",
+    ]
+
+
+def test_expand_search_arguments_rewrites_exact_placeholder_token() -> None:
+    assert search.expand_search_arguments(["{my-repo}", "config.py"], REGISTRY) == [
+        KNOWN_PATH,
+        "config.py",
+    ]
+
+
+def test_expand_search_arguments_preserves_unknown_tokens_and_spaces() -> None:
+    all_arguments = ["unknown-name", "foo bar", "config.py"]
+    assert search.expand_search_arguments(all_arguments, REGISTRY) == all_arguments
+
+
+@pytest.mark.parametrize(
+    "absolute_path",
+    [
+        "C:/Users/example/file.py",
+        "\\\\server\\share\\folder",
+        "/mnt/c/Projects/repo",
+    ],
+)
+def test_expand_search_arguments_preserves_absolute_paths(absolute_path: str) -> None:
+    assert search.expand_search_arguments([absolute_path], REGISTRY) == [absolute_path]
+
+
+def test_expand_search_arguments_preserves_embedded_flag_tokens() -> None:
+    all_arguments = ["--flag={my-repo}", "--regex=^{my-repo}$"]
+    assert search.expand_search_arguments(all_arguments, REGISTRY) == all_arguments
+
+
+def test_load_registry_returns_empty_mapping_for_missing_file(tmp_path: Path) -> None:
+    assert search.load_registry(tmp_path / "missing.json") == {}
+
+
+@pytest.mark.parametrize(
+    "registry_bytes",
+    [
+        b"\xff",
+        b"{not valid",
+        json.dumps({"my-repo": 42}).encode(),
+        json.dumps({"my-repo": ""}).encode(),
+        json.dumps({"my-repo": "relative/path"}).encode(),
+    ],
+)
+def test_load_registry_reports_invalid_input(
+    tmp_path: Path, registry_bytes: bytes
+) -> None:
+    registry_path = tmp_path / "project-paths.json"
+    registry_path.write_bytes(registry_bytes)
+    with pytest.raises(search.RegistryRunFatal, match="(Malformed|Invalid)"):
+        search.load_registry(registry_path)
+
+
+def test_main_runs_direct_search_without_registry_or_shell() -> None:
+    completed_process = search.subprocess.CompletedProcess(
+        args=["es.exe", "foo bar"],
+        returncode=0,
+        stdout="found path\n",
+        stderr="",
+    )
+    captured_stdout = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(
+            search.subprocess, "run", return_value=completed_process
+        ) as run_process,
+        patch.object(search.sys, "stdout", captured_stdout),
+    ):
+        exit_code = search.main(["foo bar"])
+    assert exit_code == 0
+    assert captured_stdout.getvalue() == "found path\n"
+    run_process.assert_called_once_with(
+        ["es.exe", "foo bar"],
+        capture_output=True,
+        check=False,
+        encoding="utf-8",
+        shell=False,
+        text=True,
+    )
+
+
+def test_main_passes_through_child_exit_status() -> None:
+    completed_process = search.subprocess.CompletedProcess(
+        args=["es.exe", "config.py"], returncode=7, stdout="", stderr="failed\n"
+    )
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(search.subprocess, "run", return_value=completed_process),
+        patch.object(search.sys, "stderr", captured_stderr),
+    ):
+        exit_code = search.main(["config.py"])
+    assert exit_code == 7
+    assert captured_stderr.getvalue() == "failed\n"
+
+
+def test_main_reports_missing_executable() -> None:
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value=None),
+        patch.object(search.sys, "stderr", captured_stderr),
+    ):
+        exit_code = search.main(["config.py"])
+    assert exit_code != 0
+    assert "es.exe" in captured_stderr.getvalue()
+
+
+def test_main_reports_empty_search_arguments() -> None:
+    captured_stderr = io.StringIO()
+    with patch.object(search.sys, "stderr", captured_stderr):
+        exit_code = search.main([])
+    assert exit_code == search.INVALID_INPUT_EXIT_CODE
+    assert "search argument" in captured_stderr.getvalue()
+
+
+@pytest.mark.parametrize("all_arguments", [["-n", "50"], [""], ["   "]])
+def test_main_rejects_unscoped_search_without_launching_child(
+    all_arguments: list[str],
+) -> None:
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search.subprocess, "run") as run_process,
+        patch.object(search.sys, "stderr", captured_stderr),
+    ):
+        exit_code = search.main(all_arguments)
+    assert exit_code == search.INVALID_INPUT_EXIT_CODE
+    assert "first search argument" in captured_stderr.getvalue().lower()
+    run_process.assert_not_called()
+
+
+def test_main_allows_version_information_operation() -> None:
+    completed_process = search.subprocess.CompletedProcess(
+        args=["es.exe", "-version"], returncode=0, stdout="1.1.0.30\n", stderr=""
+    )
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(
+            search.subprocess, "run", return_value=completed_process
+        ) as run_process,
+    ):
+        exit_code = search.main(["-version"])
+    assert exit_code == 0
+    run_process.assert_called_once()

package/.agents/skills/syncing-submodules/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: syncing-submodules
+description: >-
+  Records a submodule's current commit in its parent repository.
+  Triggers: submodule sync, /submodule-sync, sync parent submodule,
+  update parent pointer, record submodule commit, commit submodule pointer,
+  sync superproject, update superproject pointer, parent repo submodule update,
+  finish submodule commit. Does not handle clone, checkout, update main,
+  or ordinary commits.
+---
+
+# Syncing submodules
+
+## Principle
+
+A submodule commit changes the child repository first. Change the parent pointer only when this skill runs. Limit the parent commit to the submodule path so other staged work stays staged.
+
+## Gotchas
+
+- Inherited `GIT_*` variables can redirect child Git commands. The script removes them from its Git environment.
+- Submodule paths can contain brackets or wildcard characters. The script sends Git a literal pathspec.
+- `git diff --cached --quiet` uses exit 1 for a changed pointer. Any higher exit is a failure.
+- The parent repository may already contain staged work. The path-only commit must leave it staged.
+- A repository without a superproject is a successful `not_submodule` result.
+- The old hook returned success after a failed parent commit. This command returns a nonzero exit.
+
+## When this applies
+
+Use this skill after committing inside a checked-out submodule when its parent repository should record the new commit.
+
+Refusals use the first matching line:
+
+- Clone, initialize, or check out a submodule: `Use Git's submodule commands. This skill records an existing submodule commit in its parent.`
+- Fast-forward `main`: `Use /update. This skill changes one parent submodule pointer.`
+- Make an ordinary commit or push: `Use /source-command-commit. This skill commits only a parent submodule pointer.`
+
+## Process
+
+### Seed the run tasks
+
+Register every item in `reference/run-tasks.md` as a session task with the host task tool. Complete each task with an exit code, JSON field, or repository readback. If the host has no task tool, stop with `A task tool is required to track this repository-changing operation.`
+
+### Run the command
+
+Execute the bundled script. Do not reconstruct the Git sequence by hand.
+
+```text
+python "${CLAUDE_SKILL_DIR}/scripts/sync_parent_pointer.py" --repository "<submodule-path>"
+```
+
+Python 3 and Git are required. GitHub CLI is optional and only supplies an open pull request URL.
+
+The script writes one JSON object to standard output. Exit 0 permits `updated`, `unchanged`, and `not_submodule`. Exit 1 reports a Git or repository failure. Exit 2 reports invalid arguments. Treat every nonzero exit as incomplete work. Fix the reported condition, rerun the command, and keep the task open until the command exits 0.
+
+### Report the result
+
+- `updated`: report `parent_repository`, `submodule_path`, `commit`, and `parent_commit`.
+- `unchanged`: report that the parent already records `commit`.
+- `not_submodule`: report that no parent repository changed.
+- `pull_request_url`: invoke `/pr-title-description` with that URL after reporting the sync result.
+
+If `/pr-title-description` is not installed, report `pull_request_url` and finish the successful sync.
+
+## Constraints
+
+- Run the script from this skill package.
+- Commit only the literal submodule path in the parent repository.
+- Preserve every unrelated staged parent path.
+- Never push, switch branches, rewrite commits, or change Git configuration.
+- Never treat a failed Git command as success.
+
+## Examples
+
+- Updated pointer: `status` is `updated`, `submodule_path` is `modules/child`, and `parent_commit` names the new parent commit.
+- No superproject: `status` is `not_submodule`; every parent and commit field is null.
+- Failed stage: exit 1, `status` is `error`, and standard error starts with `syncing-submodules:`.
+
+## Sub-skills
+
+| Skill | When | Produces | Missing behavior |
+|---|---|---|---|
+| `/pr-title-description` | The result includes `pull_request_url` | A title and description based on the full pull request diff | Report the URL and keep the completed sync |
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Selection, operation boundary, result handling, and peer routing |
+| `reference/run-tasks.md` | Task seeds for each repository-changing run |
+| `scripts/sync_parent_pointer.py` | Execute the parent pointer sync and return one JSON result |
+| `scripts/submodule_sync.py` | Own the Git operation and typed sync report |
+| `scripts/test_sync_parent_pointer.py` | Prove command parsing, JSON output, and hook deletion |
+| `scripts/test_submodule_sync.py` | Prove exact commits, preserved staging, no-op states, and failures |
+| `scripts/submodule_sync_constants/__init__.py` | Mark the constants package |
+| `scripts/submodule_sync_constants/config/__init__.py` | Mark the configuration package |
+| `scripts/submodule_sync_constants/config/constants.py` | Named command, message, field, and exit-code constants |
+
+## Folder map
+
+- `reference/` contains the run task seeds.
+- `scripts/` contains the executable command, Git operation, tests, and constants package.

package/.agents/skills/syncing-submodules/reference/run-tasks.md

@@ -0,0 +1,9 @@
+# Run task seeds
+
+- Resolve the requested repository path.
+- Execute `scripts/sync_parent_pointer.py` for that path.
+- Record the exit code and parse the single JSON result.
+- Fix any reported failure and rerun until the command exits 0.
+- Read back the parent pointer and unrelated staged paths when the status is `updated`.
+- Report the result fields.
+- Route an open pull request URL to `/pr-title-description` or report the URL when that skill is missing.