claude-dev-env 8.48.2 → 8.48.4

package/bin/install-plan.mjs

@@ -214,7 +214,6 @@ export function preflightSettingsIfNeeded(settingsPath, shouldInstallHooks, io =
  */
 export function buildInstallPlan(input) {
     const io = input.io || {};
-    const exists = io.existsSync || existsSync;
     const packageName = input.packageName || 'claude-dev-env';
 
     preflightManagedRoot(input.managedRoot, io);
@@ -250,9 +249,6 @@ export function buildInstallPlan(input) {
     preflightSettingsIfNeeded(settingsPath, shouldInstallHooks, io);
 
     const isUpdateRefresh = Boolean(input.isUpdateRefresh);
-    const shouldPurgeBeforeReinstall = isUpdateRefresh
-        && !input.selectedGroups
-        && exists(input.manifestFilePath);
 
     return Object.freeze({
         packageRoot: input.packageRoot,
@@ -261,7 +257,6 @@ export function buildInstallPlan(input) {
         targetIdentity: input.targetIdentity,
         selectedGroups: input.selectedGroups,
         isUpdateRefresh,
-        shouldPurgeBeforeReinstall,
         pythonCommand,
         shouldInstallHooks,
         priorManifest: Object.freeze({
@@ -277,7 +272,6 @@ export function buildInstallPlan(input) {
  * High-level mutation kinds the executor applies for this plan (E2 surface).
  *
  * @param {{
- *   shouldPurgeBeforeReinstall: boolean,
  *   shouldInstallHooks: boolean,
  *   selectedGroups: string[]|null,
  * }} plan
@@ -286,9 +280,6 @@ export function buildInstallPlan(input) {
 export function describeInstallMutations(plan) {
     /** @type {string[]} */
     const allMutations = [];
-    if (plan.shouldPurgeBeforeReinstall) {
-        allMutations.push('purge_managed_installation');
-    }
     allMutations.push(
         'ensure_managed_root',
         'publish_directory_pointers',

package/bin/install.mjs

@@ -2597,7 +2597,7 @@ function runFullInstallPrunes(
  * available to a later prune and to uninstall.
  *
  * @param {string[]|null} selectedGroups The `--only` group names, or null for a full install.
- * @param {{isUpdateRefresh?: boolean}} [options] Run options; `isUpdateRefresh` purges before reinstalling.
+ * @param {{isUpdateRefresh?: boolean}} [options] Run options; `isUpdateRefresh` labels the run as an update in the log.
  * @returns {void}
  */
 function install(selectedGroups, options = {}) {
@@ -2674,15 +2674,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     const isUpdateRefresh = plan.isUpdateRefresh;
     const pythonCommand = plan.pythonCommand;
 
-    if (plan.shouldPurgeBeforeReinstall) {
-        console.log(
-            `${PACKAGE_NAME}: --update — removing prior managed files under ${CLAUDE_HOME}, then reinstalling from the package.\n`,
-        );
-        purgeManagedInstallation({
-            isManifestRequired: false,
-            throwIfFault,
-        });
-    } else if (isUpdateRefresh) {
+    if (isUpdateRefresh) {
         const installScope = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'full';
         console.log(`${PACKAGE_NAME}: --update — re-running ${installScope} install into ${CLAUDE_HOME}\n`);
     }
@@ -3335,28 +3327,6 @@ function executeUninstallPlan(plan, helpers = {}) {
     return removed;
 }
 
-/**
- * Remove every file the ownership record lists for this managed root.
- *
- * Preflights the uninstall plan (settings JSON must be an object when present)
- * before any removal. When called from `--update` inside an install transaction,
- * pass that transaction's `throwIfFault` so a fault restores the outer snapshot
- * without nesting a second journal.
- *
- * @param {{
- *   isManifestRequired: boolean,
- *   throwIfFault?: (phase: string) => void,
- * }} options
- * @returns {number|void} 0 when no manifest exists and none is required.
- */
-function purgeManagedInstallation({ isManifestRequired, throwIfFault }) {
-    const plan = resolveUninstallPlan(isManifestRequired);
-    if (plan.isNoOp) {
-        return 0;
-    }
-    return executeUninstallPlan(plan, { throwIfFault });
-}
-
 /**
  * Uninstall the selected managed root inside a snapshot/restore transaction.
  *
@@ -3435,7 +3405,7 @@ ${PACKAGE_NAME} - Claude Code development standards installer
 
 Usage:
   npx ${PACKAGE_NAME}              Install everything into the main default root
-  npx ${PACKAGE_NAME} --update     Full install: remove prior manifest-tracked files first, then reinstall
+  npx ${PACKAGE_NAME} --update     Full install: copy the package over the prior install, then prune files it no longer ships
   npx ${PACKAGE_NAME} --only X     Install specific groups
   npx ${PACKAGE_NAME} --target DIR Install into DIR instead of ~/.claude (overrides CLAUDE_CONFIG_DIR)
   npx ${PACKAGE_NAME} --profile ID Install into one named profile root (under the profiles root)

package/bin/install.plan.test.mjs

@@ -91,7 +91,6 @@ test('buildInstallPlan is zero-write and freezes a success plan', () => {
         const plan = buildInstallPlan(planInput(packageRoot, managedRoot));
         assert.equal(plan.pythonCommand, 'python3');
         assert.equal(plan.shouldInstallHooks, true);
-        assert.equal(plan.shouldPurgeBeforeReinstall, false);
         assert.deepEqual(plan.priorManifest.skills, ['a']);
         assert.ok(Object.isFrozen(plan));
         assert.equal(treeStamp(managedRoot) + '//' + treeStamp(packageRoot), before);
@@ -166,7 +165,7 @@ test('settings preflight is hooks-gated; broken manifest stays tolerant', () =>
     }
 });
 
-test('update plan marks purge and lists E2 mutation kinds; journal omits hooks', () => {
+test('update plan copies before it prunes and never purges; journal omits hooks', () => {
     const { root, managedRoot, packageRoot } = sandbox();
     try {
         const manifestFilePath = join(managedRoot, '.claude-dev-env-manifest.json');
@@ -177,9 +176,11 @@ test('update plan marks purge and lists E2 mutation kinds; journal omits hooks',
             targetIdentity: 'profile-a',
             isUpdateRefresh: true,
         }));
-        assert.equal(plan.shouldPurgeBeforeReinstall, true);
         const allMutations = describeInstallMutations(plan);
-        assert.ok(allMutations.includes('purge_managed_installation'));
+        assert.ok(!allMutations.includes('purge_managed_installation'));
+        assert.ok(
+            allMutations.indexOf('copy_hook_files') < allMutations.indexOf('prune_retired_and_stale'),
+        );
         assert.ok(allMutations.includes('publish_directory_pointers'));
         assert.ok(allMutations.includes('merge_hooks_settings'));
         assert.ok(allMutations.includes('write_manifest'));

package/bin/install.update-keeps-hooks.test.mjs

@@ -0,0 +1,96 @@
+/**
+ * An `--update` reinstall keeps every registered hook script on disk for the
+ * whole run, so a live session's hook call never finds its script missing.
+ */
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn, spawnSync } from 'node:child_process';
+import { INSTALL_FAULT_ENV } from './install-transaction.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const REGISTERED_HOOK_RELATIVE_PATHS = [
+    join('blocking', 'bash_post_call_dispatcher.py'),
+    join('blocking', 'verify_before_acting.py'),
+];
+
+function installerEnvironment(homeDirectory) {
+    const childEnvironment = {
+        ...process.env,
+        CDE_INSTALL_PSTACK: '0',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
+        HOME: homeDirectory,
+        USERPROFILE: homeDirectory,
+        GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        CODEX_HOME: join(homeDirectory, '.codex'),
+    };
+    delete childEnvironment[INSTALL_FAULT_ENV];
+    return childEnvironment;
+}
+
+function runUpdateWhileWatching(homeDirectory, watchedPaths) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const missingCountByPath = new Map();
+        let outputText = '';
+        let hasExited = false;
+        const child = spawn(process.execPath, [INSTALLER_PATH, '--update'], {
+            cwd: THIS_DIRECTORY,
+            env: installerEnvironment(homeDirectory),
+        });
+        child.stdout.on('data', (chunk) => { outputText += chunk; });
+        child.stderr.on('data', (chunk) => { outputText += chunk; });
+        child.on('error', rejectPromise);
+        child.on('exit', (exitCode) => {
+            hasExited = true;
+            resolvePromise({ exitCode, outputText, missingCountByPath });
+        });
+        const pollOnce = () => {
+            if (hasExited) return;
+            for (const watchedPath of watchedPaths) {
+                if (!existsSync(watchedPath)) {
+                    missingCountByPath.set(watchedPath, (missingCountByPath.get(watchedPath) ?? 0) + 1);
+                }
+            }
+            setImmediate(pollOnce);
+        };
+        setImmediate(pollOnce);
+    });
+}
+
+test('--update never leaves a registered hook script missing mid-install', async () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-update-hooks-'));
+    try {
+        const firstInstall = spawnSync(process.execPath, [INSTALLER_PATH], {
+            cwd: THIS_DIRECTORY,
+            encoding: 'utf8',
+            env: installerEnvironment(homeDirectory),
+        });
+        assert.equal(firstInstall.status, 0, firstInstall.stdout + firstInstall.stderr);
+        const hooksDirectory = join(homeDirectory, '.agents', 'hooks');
+        const watchedPaths = REGISTERED_HOOK_RELATIVE_PATHS.map(
+            (relativePath) => join(hooksDirectory, relativePath),
+        );
+        for (const watchedPath of watchedPaths) {
+            assert.equal(existsSync(watchedPath), true, `first install wrote ${watchedPath}`);
+        }
+
+        const updateRun = await runUpdateWhileWatching(homeDirectory, watchedPaths);
+
+        assert.equal(updateRun.exitCode, 0, updateRun.outputText);
+        assert.deepEqual(
+            Object.fromEntries(updateRun.missingCountByPath),
+            {},
+            'a registered hook script was absent while --update ran',
+        );
+        for (const watchedPath of watchedPaths) {
+            assert.equal(existsSync(watchedPath), true, `--update left ${watchedPath} in place`);
+        }
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/package.json

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

package/scripts/agent_merge_check.py

@@ -607,6 +607,7 @@ def read_pull_request(slug: str, number: int, token: str) -> Mapping[str, object
 def read_blocked_evidence(
     slug: str,
     all_pull_request_fields: Mapping[str, object],
+    all_rules: list[object] | MergeCheckError,
     token: str,
 ) -> BlockedEvidence:
     """Read what stands behind a ``blocked`` merge state.
@@ -615,6 +616,8 @@ def read_blocked_evidence(
         slug: The repository as ``owner/name``.
         all_pull_request_fields: The pull request, carrying its base branch
             and its head commit.
+        all_rules: The base branch rules, or the failure that kept them
+            unread.
         token: The GitHub token the requests authenticate with.
 
     Returns:
@@ -628,7 +631,8 @@ def read_blocked_evidence(
         str(_nested_field(all_pull_request_fields, BASE_KEY, REF_KEY))
     )
     head_sha = str(_nested_field(all_pull_request_fields, HEAD_KEY, SHA_KEY))
-    all_rules = _read_branch_rules(slug, base_ref, token)
+    if isinstance(all_rules, MergeCheckError):
+        raise all_rules
     return BlockedEvidence(
         all_unmet_checks=_read_unmet_checks(slug, head_sha, all_rules, token),
         behind_by=_read_behind_by(slug, base_ref, head_sha, token),
@@ -636,13 +640,30 @@ def read_blocked_evidence(
     )
 
 
-def _read_branch_rules(slug: str, base_ref: str, token: str) -> list[object]:
-    return _request_list(
-        BRANCH_RULES_ENDPOINT_TEMPLATE.format(
-            api_root=GITHUB_API_ROOT, slug=slug, branch=base_ref
-        ),
-        token,
-    )
+def read_branch_rules(
+    slug: str, base_ref: str, token: str
+) -> list[object] | MergeCheckError:
+    """Read the rules GitHub reports as active on the base branch.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        base_ref: The branch the pull request merges into.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        The rules, or the failure that kept them unread.
+    """
+    try:
+        return _request_list(
+            BRANCH_RULES_ENDPOINT_TEMPLATE.format(
+                api_root=GITHUB_API_ROOT,
+                slug=slug,
+                branch=urllib.parse.quote(base_ref),
+            ),
+            token,
+        )
+    except MergeCheckError as failure:
+        return failure
 
 
 def read_unstable_checks(
@@ -879,7 +900,11 @@ def _field_at(document: object, all_fields: object, key: str) -> object:
 
 
 def read_merge_queue_ejection(
-    slug: str, number: int, base_ref: str, token: str
+    slug: str,
+    number: int,
+    base_ref: str,
+    all_rules: list[object] | MergeCheckError,
+    token: str,
 ) -> bool:
     """Read whether the merge queue ejected the pull request's current head.
 
@@ -891,6 +916,8 @@ def read_merge_queue_ejection(
         slug: The repository as ``owner/name``.
         number: The pull request number.
         base_ref: The branch the pull request merges into.
+        all_rules: The base branch rules, or the failure that kept them
+            unread.
         token: The GitHub token the request authenticates with.
 
     Returns:
@@ -901,7 +928,9 @@ def read_merge_queue_ejection(
         MergeCheckError: A read failed, or answered with another shape. A
             refused GraphQL query names the merge queue that needed it.
     """
-    if not _may_merge_through_a_queue(slug, base_ref, token):
+    if not isinstance(all_rules, MergeCheckError) and not has_merge_queue_rule(
+        all_rules
+    ):
         return False
     document = _merge_queue_removal_document(slug, number, base_ref, token)
     return _is_ejected_on_head(
@@ -924,14 +953,6 @@ def _merge_queue_removal_document(
         ) from failure
 
 
-def _may_merge_through_a_queue(slug: str, base_ref: str, token: str) -> bool:
-    try:
-        all_rules = _read_branch_rules(slug, urllib.parse.quote(base_ref), token)
-    except MergeCheckError:
-        return True
-    return has_merge_queue_rule(all_rules)
-
-
 def _list_along(document: object, all_keys: Sequence[str]) -> list[object]:
     all_records = functools.reduce(
         functools.partial(_field_at, document), all_keys, document
@@ -1009,11 +1030,10 @@ def main(all_arguments: Sequence[str]) -> int:
         unresolved_thread_count = read_unresolved_thread_count(
             parsed.slug, parsed.number, token
         )
+        base_ref = str(_nested_field(all_pull_request_fields, BASE_KEY, REF_KEY))
+        all_rules = read_branch_rules(parsed.slug, base_ref, token)
         is_ejected_from_merge_queue = read_merge_queue_ejection(
-            parsed.slug,
-            parsed.number,
-            str(_nested_field(all_pull_request_fields, BASE_KEY, REF_KEY)),
-            token,
+            parsed.slug, parsed.number, base_ref, all_rules, token
         )
     except MergeCheckError as failure:
         print(failure, file=sys.stderr)
@@ -1022,7 +1042,7 @@ def main(all_arguments: Sequence[str]) -> int:
     if all_pull_request_fields.get(MERGEABLE_STATE_KEY) == MERGEABLE_STATE_BLOCKED:
         try:
             blocked_evidence = read_blocked_evidence(
-                parsed.slug, all_pull_request_fields, token
+                parsed.slug, all_pull_request_fields, all_rules, token
             )
         except MergeCheckError as failure:
             print(failure, file=sys.stderr)

package/scripts/test_agent_merge_check.py

@@ -291,10 +291,15 @@ def test_a_ready_pull_request_exits_zero(monkeypatch: pytest.MonkeyPatch) -> Non
         "read_unresolved_thread_count",
         lambda slug, number, token: 0,
     )
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_branch_rules",
+        lambda slug, base_ref, token: [],
+    )
     monkeypatch.setattr(
         agent_merge_check,
         "read_merge_queue_ejection",
-        lambda slug, number, base_ref, token: False,
+        lambda slug, number, base_ref, all_rules, token: False,
     )
     assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 0
 
@@ -311,10 +316,15 @@ def test_a_held_pull_request_exits_one(monkeypatch: pytest.MonkeyPatch) -> None:
         "read_unresolved_thread_count",
         lambda slug, number, token: 0,
     )
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_branch_rules",
+        lambda slug, base_ref, token: [],
+    )
     monkeypatch.setattr(
         agent_merge_check,
         "read_merge_queue_ejection",
-        lambda slug, number, base_ref, token: False,
+        lambda slug, number, base_ref, all_rules, token: False,
     )
     assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 1
 
@@ -491,6 +501,65 @@ def test_an_unreadable_branch_rule_keeps_the_generic_blocked_reason(
     assert BLOCKED_HOLD_REASON in line
 
 
+def test_a_blocked_pull_request_reads_the_branch_rules_once(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    routed_answer = _github_answers(
+        MAIN_BRANCH_RULES,
+        [
+            _check_run("Ruff", "success", run_id=11),
+            _check_run("Tip Local green", "success", run_id=12),
+        ],
+        behind_by=225,
+    )
+    all_rules_urls: list[str] = []
+
+    def _answer(url: str, token: str, all_payload_fields: object) -> object:
+        if "/rules/branches/" in url:
+            all_rules_urls.append(url)
+        return routed_answer(url, token, all_payload_fields)
+
+    exit_code, line = _run_main(monkeypatch, capsys, _answer)
+    assert exit_code == 1
+    assert BEHIND_MERGE_QUEUE_HOLD_TEMPLATE.format(count=225) in line
+    assert len(all_rules_urls) == 1
+
+
+def test_read_branch_rules_quotes_the_base_branch_and_returns_its_rules(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_rules_urls: list[str] = []
+
+    def _answer(url: str, token: str, all_payload_fields: object) -> object:
+        all_rules_urls.append(url)
+        return MAIN_BRANCH_RULES
+
+    monkeypatch.setattr(agent_merge_check, "_request_json", _answer)
+    assert (
+        agent_merge_check.read_branch_rules(
+            "jl-cmd/claude-dev-env", "release/2026 q4", "token"
+        )
+        == MAIN_BRANCH_RULES
+    )
+    assert all_rules_urls[0].endswith("/rules/branches/release/2026%20q4")
+
+
+def test_read_branch_rules_returns_the_failure_of_a_refused_read(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    refusal = agent_merge_check.MergeCheckError("HTTP Error 403: Forbidden")
+
+    def _refuse(url: str, token: str, all_payload_fields: object) -> object:
+        raise refusal
+
+    monkeypatch.setattr(agent_merge_check, "_request_json", _refuse)
+    assert (
+        agent_merge_check.read_branch_rules("jl-cmd/claude-dev-env", "main", "token")
+        is refusal
+    )
+
+
 def _evidence(
     all_unmet_checks: tuple[str, ...] = (),
     behind_by: int = 0,
@@ -626,7 +695,7 @@ def test_read_blocked_evidence_reads_the_pull_request_4922_shape(
         ),
     )
     assert agent_merge_check.read_blocked_evidence(
-        "jl-cmd/claude-dev-env", PULL_REQUEST_4922, "token"
+        "jl-cmd/claude-dev-env", PULL_REQUEST_4922, MAIN_BRANCH_RULES, "token"
     ) == _evidence(behind_by=225)
 
 
@@ -821,7 +890,7 @@ def test_read_merge_queue_ejection_compares_failed_checks_removals_to_the_head(
     )
     assert (
         agent_merge_check.read_merge_queue_ejection(
-            "jl-cmd/claude-dev-env", 1442, "main", "token"
+            "jl-cmd/claude-dev-env", 1442, "main", MAIN_BRANCH_RULES, "token"
         )
         is expected_ejection
     )