claude-dev-env 7.0.0 → 7.1.0

package/scripts/pr_verification/github_transport.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from http.client import HTTPResponse as OpenedHttpReply
+
+import jwt
+
+from .config.constants import (
+    UTF8_ENCODING,
+)
+from .config.timing import HTTP_TIMEOUT_SECONDS
+from .github_parsing import GitHubError
+
+
+@dataclass(frozen=True)
+class HttpReply:
+    status_code: int
+    headers: dict[str, str]
+    body: bytes
+
+
+HttpRequester = Callable[[str, str, dict[str, str], bytes | None], HttpReply]
+JwtEncoder = Callable[[dict[str, int | str], str, str], str]
+
+
+def _read_http_error(error: urllib.error.HTTPError) -> HttpReply:
+    return HttpReply(
+        status_code=error.code,
+        headers=dict(error.headers.items()),
+        body=error.read(),
+    )
+
+
+def request_http(
+    method: str,
+    url: str,
+    all_headers: dict[str, str],
+    body: bytes | None,
+) -> HttpReply:
+    """Send one GitHub HTTP request.
+
+    Args:
+        method: HTTP method.
+        url: Absolute request URL.
+        all_headers: Request headers.
+        body: Encoded request body, or None.
+
+    Returns:
+        The HTTP reply, including error replies with a status code.
+
+    Raises:
+        GitHubError: If the request fails before a status code exists.
+    """
+    request = urllib.request.Request(
+        url=url, data=body, headers=all_headers, method=method
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=HTTP_TIMEOUT_SECONDS) as reply:
+            return _read_http_reply(reply)
+    except urllib.error.HTTPError as error:
+        return _read_http_error(error)
+    except (urllib.error.URLError, OSError) as error:
+        raise GitHubError(str(error)) from error
+
+
+def _read_http_reply(reply: OpenedHttpReply) -> HttpReply:
+    return HttpReply(
+        status_code=reply.status,
+        headers=dict(reply.headers.items()),
+        body=reply.read(),
+    )
+
+
+def encode_app_jwt(
+    all_claims: dict[str, int | str], private_key: str, algorithm: str
+) -> str:
+    """Encode an app JWT.
+
+    Args:
+        all_claims: JWT claims.
+
+    Returns:
+        Encoded token.
+    """
+    encoded_token = jwt.encode(all_claims, private_key, algorithm=algorithm)
+    if isinstance(encoded_token, bytes):
+        return encoded_token.decode(UTF8_ENCODING)
+    return encoded_token

package/scripts/pr_verification/lock.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from types import TracebackType
+from typing import Self
+
+if sys.platform == "win32":
+    import msvcrt
+else:
+    import fcntl
+
+from .config.constants import (
+    SUPERVISOR_LOCK_ERROR,
+    SUPERVISOR_LOCK_FILE_MODE,
+    SUPERVISOR_LOCK_FILENAME,
+    SUPERVISOR_LOCK_IO_ERROR,
+)
+
+if sys.platform == "win32":
+
+    def _acquire_file_lock(file_descriptor: int) -> None:
+        """Acquire one nonblocking Windows lock."""
+        os.lseek(file_descriptor, 0, os.SEEK_SET)
+        msvcrt.locking(file_descriptor, msvcrt.LK_NBLCK, 1)
+
+    def _release_file_lock(file_descriptor: int) -> None:
+        """Release one Windows lock."""
+        os.lseek(file_descriptor, 0, os.SEEK_SET)
+        msvcrt.locking(file_descriptor, msvcrt.LK_UNLCK, 1)
+
+else:
+
+    def _acquire_file_lock(file_descriptor: int) -> None:
+        """Acquire one nonblocking POSIX lock."""
+        fcntl.flock(file_descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+    def _release_file_lock(file_descriptor: int) -> None:
+        """Release one POSIX lock."""
+        fcntl.flock(file_descriptor, fcntl.LOCK_UN)
+
+
+class SupervisorLockError(RuntimeError):
+    """Raised when the supervisor lock cannot be acquired or released."""
+
+
+class SupervisorLock:
+    def __init__(self, cache_root: Path) -> None:
+        self.cache_root = cache_root.resolve()
+        self.lock_path = self.cache_root / SUPERVISOR_LOCK_FILENAME
+        self.file_descriptor: int | None = None
+
+    def __enter__(self) -> Self:
+        self.acquire()
+        return self
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.release()
+
+    def acquire(self) -> None:
+        """Acquire the operating-system lock for this cache root.
+
+        Raises:
+            SupervisorLockError: If another owner holds the lock or I/O fails.
+        """
+        try:
+            self.cache_root.mkdir(parents=True, exist_ok=True)
+            file_descriptor = os.open(
+                self.lock_path,
+                os.O_CREAT | os.O_RDWR,
+                SUPERVISOR_LOCK_FILE_MODE,
+            )
+        except OSError as error:
+            raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+        try:
+            _acquire_file_lock(file_descriptor)
+        except (BlockingIOError, PermissionError) as error:
+            _close_file_descriptor_without_raising(file_descriptor)
+            raise SupervisorLockError(SUPERVISOR_LOCK_ERROR) from error
+        except OSError as error:
+            _close_file_descriptor_without_raising(file_descriptor)
+            raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+        self.file_descriptor = file_descriptor
+
+    def release(self) -> None:
+        """Release the operating-system lock and close its file descriptor.
+
+        Raises:
+            SupervisorLockError: If unlocking or closing the file fails.
+        """
+        file_descriptor = self.file_descriptor
+        if file_descriptor is None:
+            return
+        self.file_descriptor = None
+        try:
+            _release_file_lock(file_descriptor)
+        except OSError as error:
+            raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+        finally:
+            _close_file_descriptor(file_descriptor)
+
+
+def _close_file_descriptor(file_descriptor: int) -> None:
+    """Close one lock file descriptor."""
+    try:
+        os.close(file_descriptor)
+    except OSError as error:
+        raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+
+
+def _close_file_descriptor_without_raising(file_descriptor: int) -> None:
+    """Close one lock file descriptor while a lock failure is already being raised."""
+    try:
+        os.close(file_descriptor)
+    except OSError:
+        return

package/scripts/pr_verification/model.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from .config.constants import (
+    STATUS_ERROR,
+    STATUS_FAILURE,
+    STATUS_PENDING,
+    STATUS_SUCCESS,
+)
+
+
+class StatusState(str, Enum):
+    PENDING = STATUS_PENDING
+    ERROR = STATUS_ERROR
+    FAILURE = STATUS_FAILURE
+    SUCCESS = STATUS_SUCCESS
+
+
+@dataclass(frozen=True)
+class RepositorySettings:
+    slug: str
+    clone_url: str
+
+    @property
+    def name(self) -> str:
+        return self.slug.split("/", maxsplit=1)[1]
+
+
+@dataclass(frozen=True)
+class PullRequestCandidate:
+    repository_slug: str
+    pull_request_number: int
+    base_ref: str
+    base_sha: str
+    head_sha: str
+    merge_sha: str
+    is_draft: bool
+
+    @property
+    def key(self) -> tuple[str, int]:
+        return self.repository_slug, self.pull_request_number

package/scripts/pr_verification/requirements.txt

@@ -0,0 +1 @@
+PyJWT[crypto]>=2.10,<3

package/scripts/test_durable_post_lint.py

@@ -330,3 +330,100 @@ def test_cli_has_no_inline_body_flag() -> None:
     )
     assert completed_process.returncode == 2
     assert "unrecognized arguments" in completed_process.stderr
+
+
+RELEASE_BRANCH = "release-please--branches--main--components--claude-dev-env"
+RELEASE_BODY = """:robot: I have created a release *beep* *boop*
+---
+
+
+## [7.0.0](https://example.invalid/compare/v6.0.0...v7.0.0) (2026-01-01)
+
+
+### Features
+
+* a shipped change
+
+---
+This PR was generated with [Release Please](https://example.invalid/release-please).
+"""
+
+
+def should_accept_a_release_body_without_the_house_headings() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-edit",
+        title=None,
+        body_text=RELEASE_BODY,
+        head_branch=RELEASE_BRANCH,
+    )
+    assert all_findings == ()
+
+
+@pytest.mark.parametrize(
+    "damaged_body",
+    [
+        RELEASE_BODY.replace(":robot: I have created a release *beep* *boop*", ""),
+        RELEASE_BODY.replace("This PR was generated with [Release Please]", ""),
+    ],
+)
+def should_report_a_release_body_that_lost_a_marker(damaged_body: str) -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-edit",
+        title=None,
+        body_text=damaged_body,
+        head_branch=RELEASE_BRANCH,
+    )
+    assert [each_finding.code for each_finding in all_findings] == [
+        "rewritten-release-body"
+    ]
+
+
+def should_report_a_release_body_rewritten_into_house_prose() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-edit",
+        title=None,
+        body_text="This pull request publishes claude-dev-env 2.37.0.",
+        head_branch=RELEASE_BRANCH,
+    )
+    assert [each_finding.code for each_finding in all_findings] == [
+        "rewritten-release-body"
+    ]
+
+
+def should_keep_the_house_headings_for_an_ordinary_branch() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-create",
+        title="fix(cli): tighten input handling",
+        body_text="Body without the required headings.",
+        head_branch="fix/ordinary-branch",
+    )
+    assert MISSING_HEADING_CODE_NAME in {
+        each_finding.code for each_finding in all_findings
+    }
+
+
+MISSING_HEADING_CODE_NAME = "missing-pr-description-heading"
+
+
+def should_report_a_rewritten_release_body_through_the_command_line(
+    tmp_path: Path,
+) -> None:
+    body_path = tmp_path / "body.md"
+    body_path.write_text("This pull request publishes the package.", encoding="utf-8")
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--action",
+            "pr-edit",
+            "--body-file",
+            str(body_path),
+            "--head-branch",
+            RELEASE_BRANCH,
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed_process.returncode == 1
+    assert "keep the generated text whole" in completed_process.stderr

package/scripts/tests/test-audit-hooks-cli.mjs

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const auditCliPath = path.join(packageRoot, "audit-hooks-cli.mjs");
+
+function writeJson(filePath, jsonDocument) {
+  writeFileSync(filePath, JSON.stringify(jsonDocument), "utf8");
+}
+
+function createAuditFixture({
+  canonicalHooks = {},
+  claudeHooks = { hooks: {} },
+  codexHooks = { hooks: {} },
+} = {}) {
+  const fixtureRoot = mkdtempSync(path.join(tmpdir(), "hook-audit-cli-"));
+  const canonicalHooksRoot = path.join(fixtureRoot, "packages", "claude-dev-env", "hooks");
+  const homeDirectory = path.join(fixtureRoot, "home");
+  mkdirSync(canonicalHooksRoot, { recursive: true });
+  mkdirSync(path.join(homeDirectory, ".claude", "hooks"), { recursive: true });
+  mkdirSync(path.join(homeDirectory, ".codex", "hooks"), { recursive: true });
+  writeJson(path.join(canonicalHooksRoot, "hooks.json"), { hooks: canonicalHooks });
+  writeJson(path.join(homeDirectory, ".claude", "settings.json"), claudeHooks);
+  writeJson(path.join(homeDirectory, ".codex", "hooks.json"), codexHooks);
+  return { fixtureRoot, homeDirectory };
+}
+
+function runAuditCli(allArguments) {
+  const childProcess = spawnSync(process.execPath, [auditCliPath, ...allArguments], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    env: { ...process.env, HOME: path.join(tmpdir(), "unused-audit-cli-home") },
+    shell: false,
+  });
+  assert.equal(childProcess.error, undefined);
+  return childProcess;
+}
+
+test("writes a JSON audit report to stdout through the CLI", () => {
+  const fixture = createAuditFixture({
+    canonicalHooks: {
+      PreToolUse: [{
+        matcher: "Write",
+        hooks: [{
+          type: "command",
+          command: "python3 " + "$" + "{CLAUDE_PLUGIN_ROOT}/hooks/blocking/write_existing_file_blocker.py",
+        }],
+      }],
+    },
+  });
+  try {
+    const childProcess = runAuditCli([
+      "--format",
+      "json",
+      "--repository-root",
+      fixture.fixtureRoot,
+    ]);
+
+    assert.equal(childProcess.status, 0);
+    assert.equal(childProcess.stderr, "");
+    const report = JSON.parse(childProcess.stdout);
+    assert.equal(report.summary.directCount, 1);
+    assert.equal(report.registrationEligibility.status, "not_checked");
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
+test("writes the JSON audit report to the requested file through the CLI", () => {
+  const fixture = createAuditFixture();
+  const reportPath = path.join(fixture.fixtureRoot, "audit-report.json");
+  try {
+    const childProcess = runAuditCli([
+      "--format",
+      "json",
+      "--output",
+      reportPath,
+      "--repository-root",
+      fixture.fixtureRoot,
+    ]);
+
+    assert.equal(childProcess.status, 0);
+    assert.equal(childProcess.stdout, "");
+    const report = JSON.parse(readFileSync(reportPath, "utf8"));
+    assert.equal(report.summary.directCount, 0);
+    assert.equal(report.summary.findingCount, 0);
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
+test("returns a strict nonblocking failure through the CLI", () => {
+  const fixture = createAuditFixture({
+    claudeHooks: {
+      hooks: {
+        SessionStart: [{
+          hooks: [{ command: "node cleanup.mjs", type: "command" }],
+        }],
+      },
+    },
+  });
+  const catalogPath = path.join(fixture.fixtureRoot, "lifecycle.json");
+  writeJson(catalogPath, {
+    hooks: {
+      "external:cleanup.mjs": {
+        lifecycle: "delete",
+        reason: "The installed entry is retired.",
+        replacement: null,
+      },
+    },
+  });
+  try {
+    const childProcess = runAuditCli([
+      "--format",
+      "json",
+      "--catalog",
+      catalogPath,
+      "--home",
+      fixture.homeDirectory,
+      "--installed",
+      "--require-nonblocking",
+      "--repository-root",
+      fixture.fixtureRoot,
+    ]);
+
+    assert.equal(childProcess.status, 1);
+    assert.equal(childProcess.stderr, "");
+    const report = JSON.parse(childProcess.stdout);
+    assert.equal(report.registrationEligibility.status, "ineligible");
+    assert.equal(
+      report.findings.some(({ code, target }) =>
+        code === "NONBLOCKING_LIFECYCLE_MISMATCH" && target === "external:cleanup.mjs",
+      ),
+      true,
+    );
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});

package/scripts/tests/test-audit-hooks.mjs

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -73,6 +73,37 @@ test("renders deterministic private JSON", () => {
   assert.equal(first.includes("python3 ${CLAUDE_PLUGIN_ROOT}"), false);
 });
 
+test("does not compare the live graph with retired baseline counts", () => {
+  const report = auditHooks({ repositoryRoot });
+  assert.equal(report.summary.directCount, report.directRegistrations.length);
+  assert.equal(report.summary.effectiveCount, report.hostedRegistrations.length);
+  assert.equal(report.summary.logicalAssociationCount, report.logicalRegistrations.length);
+  assert.ok(report.summary.directCount > 0);
+  assert.ok(report.summary.effectiveCount > 0);
+  assert.ok(report.summary.logicalAssociationCount > report.summary.directCount);
+  assert.equal(report.findings.some(({ code }) => code === "DIRECT_COUNT_DRIFT"), false);
+  assert.equal(report.findings.some(({ code }) => code === "HOSTED_COUNT_DRIFT"), false);
+});
+
+test("does not execute registered commands", () => {
+  const fixture = createAuditFixture({
+    canonicalHooks: {
+      PreToolUse: [{
+        hooks: [{
+          command: "node -e \"require('node:fs').writeFileSync('audit-executed', 'yes')\"",
+          type: "command",
+        }],
+      }],
+    },
+  });
+  try {
+    auditHooks({ repositoryRoot: fixture.fixtureRoot });
+    assert.equal(existsSync(path.join(fixture.fixtureRoot, "audit-executed")), false);
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
 test("reports every unclassified target", () => {
   const temporaryRoot = mkdtempSync(path.join(tmpdir(), "hook-audit-"));
   const catalogPath = path.join(temporaryRoot, "lifecycle.json");
@@ -86,6 +117,15 @@ test("reports every unclassified target", () => {
   }
 });
 
+test("reports canonical native Git hooks from the installer registry", () => {
+  const report = auditHooks({ repositoryRoot });
+  assert.deepEqual(
+    report.knownGitRegistrations.map(({ target }) => target),
+    ["git:pre-commit", "git:pre-push", "git:post-commit"],
+  );
+  assert.equal(report.summary.knownGitHookCount, 3);
+});
+
 test("keeps each hosted matcher as narrow as its roster", () => {
   const fixture = createAuditFixture({
     canonicalHooks: {
@@ -161,6 +201,7 @@ test("classifies installed-only targets", () => {
       catalogPath,
       homeDirectory: fixture.homeDirectory,
       includeInstalled: true,
+      requireNonblocking: true,
       repositoryRoot: temporaryRoot,
     });
     const missingTargets = new Set(
@@ -266,6 +307,46 @@ test("reports missing installed dispatcher targets", () => {
   }
 });
 
+test("rejects an installed-only registration without nonblocking lifecycle", () => {
+  const fixture = createAuditFixture({
+    claudeHooks: {
+      hooks: {
+        SessionStart: [{
+          hooks: [{ command: "node cleanup.mjs", type: "command" }],
+        }],
+      },
+    },
+  });
+  const catalogPath = path.join(fixture.fixtureRoot, "lifecycle.json");
+  writeJson(catalogPath, {
+    hooks: {
+      "external:cleanup.mjs": {
+        lifecycle: "delete",
+        reason: "The installed entry is retired.",
+        replacement: null,
+      },
+    },
+  });
+  try {
+    const report = auditHooks({
+      catalogPath,
+      homeDirectory: fixture.homeDirectory,
+      includeInstalled: true,
+      requireNonblocking: true,
+      repositoryRoot: fixture.fixtureRoot,
+    });
+    assert.equal(report.registrationEligibility.status, "ineligible");
+    assert.equal(
+      report.findings.some(({ code, target }) =>
+        code === "NONBLOCKING_LIFECYCLE_MISMATCH" && target === "external:cleanup.mjs",
+      ),
+      true,
+    );
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
 test("checks canonical managed parity for Codex registrations", () => {
   const fixture = createAuditFixture({
     canonicalHooks: {
@@ -355,6 +436,7 @@ test("finds default Git hooks from a worktree", () => {
     runGit(sourceRoot, ["commit", "--quiet", "--allow-empty", "-m", "fixture"], environment);
     runGit(sourceRoot, ["worktree", "add", "--quiet", worktreeRoot, "HEAD"], environment);
     writeHookFile(path.join(sourceRoot, ".git", "hooks"), "pre-commit");
+    writeHookFile(path.join(sourceRoot, ".git", "hooks"), "post-commit");
     const canonicalHooksRoot = path.join(worktreeRoot, "packages", "claude-dev-env", "hooks");
     const homeDirectory = path.join(sourceRoot, "home");
     mkdirSync(canonicalHooksRoot, { recursive: true });
@@ -366,9 +448,19 @@ test("finds default Git hooks from a worktree", () => {
     const report = auditHooks({
       homeDirectory,
       includeInstalled: true,
+      requireNonblocking: true,
       repositoryRoot: worktreeRoot,
     });
-    assert.deepEqual(report.gitRegistrations.map(({ target }) => target), ["git:pre-commit"]);
+    assert.deepEqual(report.gitRegistrations.map(({ target }) => target), [
+      "git:pre-commit",
+      "git:post-commit",
+    ]);
+    assert.equal(
+      report.findings.some(({ code, target }) =>
+        code === "NATIVE_GIT_BLOCKING_HOOK" && target === "git:pre-commit",
+      ),
+      true,
+    );
   } finally {
     if (previousGlobalConfig === undefined) delete process.env.GIT_CONFIG_GLOBAL;
     else process.env.GIT_CONFIG_GLOBAL = previousGlobalConfig;