claude-dev-env 1.89.0 → 1.90.0

package/hooks/lifecycle/test_enter_worktree_origin_prefetch.py

@@ -0,0 +1,178 @@
+"""Unit tests for the enter_worktree_origin_prefetch PreToolUse hook.
+
+Uses real git repositories (a "remote" repo cloned into a "local" one) so the
+fetch behavior is exercised against actual git plumbing, not mocked calls.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "enter_worktree_origin_prefetch",
+    _HOOK_DIR / "enter_worktree_origin_prefetch.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+
+def _run_git(repo_directory: pathlib.Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=repo_directory,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+
+def _init_repo_with_commit(repo_directory: pathlib.Path) -> None:
+    repo_directory.mkdir(parents=True, exist_ok=True)
+    _run_git(repo_directory, "init", "--quiet", "--initial-branch=main")
+    _run_git(repo_directory, "config", "user.email", "test@example.com")
+    _run_git(repo_directory, "config", "user.name", "Test")
+    _run_git(repo_directory, "commit", "--allow-empty", "--quiet", "-m", "init")
+
+
+def _clone_as_local(remote_directory: pathlib.Path, local_directory: pathlib.Path) -> None:
+    subprocess.run(
+        ["git", "clone", "--quiet", str(remote_directory), str(local_directory)],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    _run_git(local_directory, "config", "user.email", "test@example.com")
+    _run_git(local_directory, "config", "user.name", "Test")
+
+
+def test_is_enter_worktree_creation_true_when_no_path_given() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {}}
+    assert hook_module.is_enter_worktree_creation(payload) is True
+
+
+def test_is_enter_worktree_creation_true_with_name_only() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {"name": "my-branch"}}
+    assert hook_module.is_enter_worktree_creation(payload) is True
+
+
+def test_is_enter_worktree_creation_false_when_path_given() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {"path": "/some/worktree"}}
+    assert hook_module.is_enter_worktree_creation(payload) is False
+
+
+def test_is_enter_worktree_creation_false_for_other_tool() -> None:
+    payload = {"tool_name": "Bash", "tool_input": {}}
+    assert hook_module.is_enter_worktree_creation(payload) is False
+
+
+def test_resolve_origin_default_branch_reads_cloned_head(tmp_path: pathlib.Path) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+
+    resolved_branch = hook_module.resolve_origin_default_branch(str(local_directory))
+
+    assert resolved_branch == "main"
+
+
+def test_resolve_origin_default_branch_returns_none_without_origin(
+    tmp_path: pathlib.Path,
+) -> None:
+    solo_directory = tmp_path / "solo"
+    _init_repo_with_commit(solo_directory)
+
+    resolved_branch = hook_module.resolve_origin_default_branch(str(solo_directory))
+
+    assert resolved_branch is None
+
+
+def test_fetch_origin_branch_updates_stale_local_ref(tmp_path: pathlib.Path) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+
+    _run_git(remote_directory, "commit", "--allow-empty", "--quiet", "-m", "second")
+    remote_head_sha = _run_git(remote_directory, "rev-parse", "HEAD").stdout.strip()
+    local_cached_sha_before = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_before != remote_head_sha
+
+    hook_module.fetch_origin_branch(str(local_directory), "main")
+
+    local_cached_sha_after = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_after == remote_head_sha
+
+
+def test_fetch_origin_branch_never_raises_when_remote_missing(tmp_path: pathlib.Path) -> None:
+    solo_directory = tmp_path / "solo"
+    _init_repo_with_commit(solo_directory)
+
+    hook_module.fetch_origin_branch(str(solo_directory), "main")
+
+
+def test_main_fetches_stale_ref_and_exits_zero(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+    _run_git(remote_directory, "commit", "--allow-empty", "--quiet", "-m", "second")
+    remote_head_sha = _run_git(remote_directory, "rev-parse", "HEAD").stdout.strip()
+
+    payload = {
+        "tool_name": "EnterWorktree",
+        "tool_input": {},
+        "cwd": str(local_directory),
+    }
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0
+    local_cached_sha_after = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_after == remote_head_sha
+
+
+def test_main_exits_zero_for_non_enter_worktree_tool(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    payload = {"tool_name": "Bash", "tool_input": {"command": "ls"}, "cwd": "/tmp"}
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0
+
+
+def test_main_exits_zero_on_malformed_json(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(sys, "stdin", io.StringIO("not json"))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.89.0",
+    "version": "1.90.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -17,6 +17,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
 | `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
 | `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
+| `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
 | `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
 | `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
 | `gh-body-file.md` | Use `--body-file` with a temp file for all `gh` commands carrying markdown body content |

package/rules/durable-post-artifacts.md

@@ -0,0 +1,35 @@
+# Durable Post Artifacts
+
+**When this applies:** Any GitHub post that lives on the server — an issue, a pull request, a comment, or a review — created through `gh` (`gh pr create/comment/edit/review`, `gh issue create/comment/edit`) or a GitHub MCP post tool.
+
+## Rule
+
+A post lives forever. Job scratch directories, worktrees, and system temp folders do not — they are cleaned soon after the run that made them. So a post must never point at a path in that scratch. The moment the directory is cleaned, the reference breaks and the reader is left with a dead path.
+
+Handle the two kinds of content differently:
+
+- **Text data** (logs, tables, diffs, stack traces): paste the actual text inline in the post body. Do not link a scratch file that holds it.
+- **Binary artifacts** (images, screenshots, archives): upload the file to the repository's durable `artifacts` release and link the permanent URL. Use the helper:
+
+  ```
+  python3 ~/.claude/scripts/gh_artifact_upload.py <file-path> <owner/repo>
+  ```
+
+  It ensures the repository has a prerelease tagged `artifacts`, uploads the file under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints the permanent download URL. Put that URL in the post.
+
+## Volatile paths that must not appear in a post body
+
+- A job scratch directory (`.claude-editor/jobs/`)
+- A worktree (`.claude/worktrees/`)
+- A system temp location (`AppData\Local\Temp`, `%TEMP%`, `$env:TEMP`, `/tmp/`)
+- The job scratch environment variable (`$CLAUDE_JOB_DIR`)
+
+Both slash directions count.
+
+## Enforcement
+
+The `volatile_path_in_post_blocker` PreToolUse hook reads the body of each `gh` post command and each GitHub MCP post call, scans it for these markers, and blocks the post when it finds one. For a `--body-file`, the hook reads the file and scans its contents, so writing the body to a temp file and passing it with `--body-file` stays allowed — what the hook rejects is a volatile path inside the text that gets posted.
+
+## Why
+
+A comment that cites an artifact under a job's tmp directory reads fine the moment it is posted and breaks a few minutes later, once the job is cleaned. Embedding text inline and linking binary artifacts to a durable release keeps every post readable for as long as it exists.

package/scripts/CLAUDE.md

@@ -6,6 +6,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 
 | File | Purpose |
 |---|---|
+| `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
 | `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -7,6 +7,7 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 | File | Constants for |
 |---|---|
 | `timing.py` | `sweep_empty_dirs.py` — `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode) |
+| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` — the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
 | `__init__.py` | Empty package marker |
 
 ## Convention

package/scripts/dev_env_scripts_constants/gh_artifact_upload_constants.py

@@ -0,0 +1,43 @@
+"""Constants for the gh_artifact_upload script.
+
+Per the project's configuration conventions, script-level scalar constants
+live in dev_env_scripts_constants alongside timing.py.
+"""
+
+ARTIFACTS_RELEASE_TAG: str = "artifacts"
+"""Release tag that holds durable post artifacts."""
+
+ARTIFACTS_RELEASE_TITLE: str = "Durable post artifacts"
+"""Human-readable title for the artifacts release."""
+
+ARTIFACTS_RELEASE_NOTES: str = (
+    "Permanent storage for binary artifacts linked from GitHub issue and pull "
+    "request posts. Job scratch directories are ephemeral and get cleaned soon "
+    "after a run; assets uploaded to this prerelease persist so a durable post "
+    "can link a stable URL."
+)
+"""Release body written when the artifacts release is first created."""
+
+GH_BINARY_NAME: str = "gh"
+"""The GitHub CLI executable name."""
+
+ASSET_NAME_TIMESTAMP_FORMAT: str = "%Y%m%d_%H%M%S"
+"""strftime format for the timestamp prefix on an uploaded asset name."""
+
+ASSET_NAME_TEMPLATE: str = "{timestamp}_{basename}"
+"""Template joining the timestamp prefix and the source file basename."""
+
+RELEASE_ASSETS_JSON_KEY: str = "assets"
+"""``gh release view --json`` field holding the release's asset list."""
+
+ASSET_URL_JSON_KEY: str = "url"
+"""Asset field carrying the browser download URL GitHub serves."""
+
+ASSET_CREATED_AT_JSON_KEY: str = "createdAt"
+"""Asset field carrying the ISO 8601 creation timestamp."""
+
+NOTES_FILE_SUFFIX: str = ".md"
+"""Suffix for the temporary release-notes file."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for subprocess output and temp files."""

package/scripts/gh_artifact_upload.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""Upload a file to a repo's durable 'artifacts' release and print its URL.
+
+A durable GitHub post (issue, PR, comment, review) must not link a file under a
+job scratch directory or worktree, because that scratch is cleaned soon after
+the run while the post lives forever. Binary artifacts belong in a permanent
+place instead. This tool ensures the repo has a prerelease tagged ``artifacts``,
+uploads the given file under a timestamped asset name, and prints the permanent
+download URL a post can safely link. The timestamped name keeps each upload a
+distinct asset. An upload never overwrites an earlier one. A same-name collision
+fails loudly instead of replacing the bytes an existing URL already serves.
+
+Usage::
+
+    python3 gh_artifact_upload.py <file-path> <owner/repo>
+    -> https://github.com/<owner>/<repo>/releases/download/artifacts/20260707_140233_contact_sheet.png
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from dev_env_scripts_constants.gh_artifact_upload_constants import (
+    ARTIFACTS_RELEASE_NOTES,
+    ARTIFACTS_RELEASE_TAG,
+    ARTIFACTS_RELEASE_TITLE,
+    ASSET_CREATED_AT_JSON_KEY,
+    ASSET_NAME_TEMPLATE,
+    ASSET_NAME_TIMESTAMP_FORMAT,
+    ASSET_URL_JSON_KEY,
+    GH_BINARY_NAME,
+    NOTES_FILE_SUFFIX,
+    RELEASE_ASSETS_JSON_KEY,
+    UTF8_ENCODING,
+)
+
+
+class ArtifactUploadError(Exception):
+    """Raised when creating the release or uploading the asset fails."""
+
+
+def _run_gh(all_arguments: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [GH_BINARY_NAME, *all_arguments],
+        capture_output=True,
+        text=True,
+        encoding=UTF8_ENCODING,
+        check=False,
+    )
+
+
+def artifacts_release_exists(repository: str) -> bool:
+    """Return whether the durable artifacts release already exists in the repo.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        True when ``gh release view`` finds the ``artifacts`` release.
+    """
+    completion = _run_gh(
+        [
+            "release",
+            "view",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--json",
+            "tagName",
+        ]
+    )
+    return completion.returncode == 0
+
+
+def ensure_artifacts_release(repository: str) -> None:
+    """Create the artifacts prerelease when the repo does not already have it.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Raises:
+        ArtifactUploadError: When the release cannot be created.
+    """
+    if artifacts_release_exists(repository):
+        return
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=NOTES_FILE_SUFFIX, delete=False, encoding=UTF8_ENCODING
+    ) as notes_file:
+        notes_file.write(ARTIFACTS_RELEASE_NOTES)
+        notes_path = notes_file.name
+    completion = _run_gh(
+        [
+            "release",
+            "create",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--prerelease",
+            "--title",
+            ARTIFACTS_RELEASE_TITLE,
+            "--notes-file",
+            notes_path,
+        ]
+    )
+    Path(notes_path).unlink(missing_ok=True)
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+
+
+def timestamped_asset_name(file_path: str) -> str:
+    """Return ``YYYYMMDD_HHMMSS_<basename>`` for the given file path.
+
+    Args:
+        file_path: The source file to be uploaded.
+
+    Returns:
+        The asset name that prefixes the basename with the current timestamp.
+    """
+    current_timestamp = datetime.datetime.now().strftime(ASSET_NAME_TIMESTAMP_FORMAT)
+    return ASSET_NAME_TEMPLATE.format(
+        timestamp=current_timestamp, basename=Path(file_path).name
+    )
+
+
+def _uploaded_asset_download_url(repository: str) -> str:
+    """Read the just-uploaded asset's real download URL back from GitHub.
+
+    ::
+
+        upload "My Report.png" -> GitHub stores "..._My.Report.png"
+        read-back -> the URL GitHub serves for that sanitized name
+
+    GitHub sanitizes an asset filename on upload: spaces and other characters
+    become periods. The stored name, and so the download URL, can differ from
+    the local name. Reading the release back returns the URL GitHub actually
+    serves for the most recently created asset, which is the one just uploaded.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        The browser download URL of the newest artifacts-release asset.
+
+    Raises:
+        ArtifactUploadError: When the read-back fails, the response cannot be
+            parsed, or no asset carries a download URL.
+    """
+    completion = _run_gh(
+        [
+            "release",
+            "view",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--json",
+            RELEASE_ASSETS_JSON_KEY,
+        ]
+    )
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+    try:
+        parsed_release = json.loads(completion.stdout)
+    except json.JSONDecodeError as decode_error:
+        raise ArtifactUploadError(f"could not read release assets: {decode_error}")
+    all_assets = (
+        parsed_release.get(RELEASE_ASSETS_JSON_KEY, [])
+        if isinstance(parsed_release, dict)
+        else []
+    )
+    all_dated_assets = [
+        each_asset
+        for each_asset in all_assets
+        if isinstance(each_asset, dict) and each_asset.get(ASSET_CREATED_AT_JSON_KEY)
+    ]
+    if not all_dated_assets:
+        raise ArtifactUploadError("uploaded asset not found on read-back")
+    newest_asset = max(
+        all_dated_assets,
+        key=lambda each_asset: each_asset[ASSET_CREATED_AT_JSON_KEY],
+    )
+    asset_url = newest_asset.get(ASSET_URL_JSON_KEY)
+    if not isinstance(asset_url, str) or not asset_url:
+        raise ArtifactUploadError("uploaded asset carries no download URL on read-back")
+    return asset_url
+
+
+def upload_artifact(file_path: str, repository: str) -> str:
+    """Upload a file to the artifacts release and return its permanent URL.
+
+    Args:
+        file_path: The source file to upload.
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        The permanent download URL for the uploaded asset.
+
+    Raises:
+        ArtifactUploadError: When the file is missing or the upload fails.
+    """
+    source_path = Path(file_path)
+    if not source_path.is_file():
+        raise ArtifactUploadError(f"file not found: {file_path}")
+    ensure_artifacts_release(repository)
+    asset_name = timestamped_asset_name(file_path)
+    with tempfile.TemporaryDirectory() as staging_directory:
+        staged_asset_path = Path(staging_directory) / asset_name
+        shutil.copyfile(source_path, staged_asset_path)
+        completion = _run_gh(
+            [
+                "release",
+                "upload",
+                ARTIFACTS_RELEASE_TAG,
+                str(staged_asset_path),
+                "--repo",
+                repository,
+            ]
+        )
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+    return _uploaded_asset_download_url(repository)
+
+
+def main() -> int:
+    """Parse arguments, upload the file, and print the permanent asset URL.
+
+    Returns:
+        ``0`` when the upload succeeds, ``1`` when it fails.
+    """
+    parser = argparse.ArgumentParser(
+        description="Upload a file to a repo's durable 'artifacts' release."
+    )
+    parser.add_argument("file_path", help="Path to the file to upload.")
+    parser.add_argument(
+        "repository", metavar="owner/repo", help="Target GitHub repository slug."
+    )
+    parsed_arguments = parser.parse_args()
+    try:
+        asset_url = upload_artifact(
+            parsed_arguments.file_path, parsed_arguments.repository
+        )
+    except ArtifactUploadError as upload_error:
+        print(f"gh-artifact-upload failed: {upload_error}", file=sys.stderr)
+        return 1
+    print(asset_url)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())