claude-dev-env 8.6.1 → 8.8.0

package/scripts/ci/install-playtest.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/**
+ * Install playtest: run the shipped package the way a session loads it.
+ *
+ * The driver installs this package into a scratch home, reads the hook roster
+ * the install wrote into `settings.json`, starts one SessionStart hook and one
+ * PreToolUse hook from that installed tree against fixture payloads, and reads
+ * the output envelope each one returns.
+ *
+ * Every stage writes the envelope it read to the evidence directory and prints
+ * one line carrying the stage name, the artifact path and the artifact's
+ * SHA-256 digest::
+ *
+ *     every stage read the envelope it expected -> exit 0
+ *     one stage read something else             -> exit 1
+ *
+ * Usage::
+ *
+ *     node scripts/ci/install-playtest.mjs
+ *     node scripts/ci/install-playtest.mjs --home <dir> --evidence <dir>
+ *     node scripts/ci/install-playtest.mjs --home <dir> --skip-install
+ *
+ * `--home` names the scratch home to install into and keeps it after the run.
+ * `--skip-install` grades the tree already installed in that home, which is how
+ * a broken install is read back.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+    createScratchHome,
+    removeScratchHome,
+    runInstaller,
+    scratchHomeEnvironment,
+    SANDBOX_GIT_CONFIG_BODY,
+    SANDBOX_GIT_CONFIG_NAME,
+} from './scratch-home-install.mjs';
+
+export const EVIDENCE_PREFIX = 'cde-playtest-';
+export const SETTINGS_RELATIVE_PATH = join('.claude', 'settings.json');
+export const HOOK_TIMEOUT_MILLISECONDS = 60_000;
+export const PASS_MARK = 'PASS';
+export const FAIL_MARK = 'FAIL';
+export const DIGEST_ALGORITHM = 'sha256';
+export const INSTALL_STAGE_NAME = 'install';
+export const SESSION_START_STAGE_NAME = 'session_start_hook';
+export const BLOCKING_STAGE_NAME = 'blocking_hook';
+export const SESSION_START_EVENT_NAME = 'SessionStart';
+export const PRE_TOOL_USE_EVENT_NAME = 'PreToolUse';
+export const SESSION_START_HOOK_SCRIPT_NAME = 'working_style_prompt.py';
+export const BASH_HOOK_SCRIPT_NAME = 'bash_pre_tool_use_dispatcher.py';
+export const BASH_MATCHER = 'Bash';
+export const ALLOW_DECISION = 'allow';
+
+export const SESSION_START_PAYLOAD = {
+    hook_event_name: SESSION_START_EVENT_NAME,
+    source: 'startup',
+};
+
+export const BASH_HOOK_PAYLOAD = {
+    tool_name: BASH_MATCHER,
+    tool_input: { command: 'git show origin/main:.claude/settings.json' },
+};
+
+export const REWRITE_MARKER = 'MSYS2_ARG_CONV_EXCL';
+
+/**
+ * Parse the driver's arguments.
+ *
+ * @param {string[]} argv Arguments after the script name.
+ * @returns {{homePath: string | null, evidencePath: string | null, shouldSkipInstall: boolean}} The parsed options.
+ */
+export function parseArguments(argv) {
+    let homePath = null;
+    let evidencePath = null;
+    let shouldSkipInstall = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--home') {
+            homePath = argv[index + 1] ?? null;
+            index += 1;
+        } else if (token === '--evidence') {
+            evidencePath = argv[index + 1] ?? null;
+            index += 1;
+        } else if (token === '--skip-install') {
+            shouldSkipInstall = true;
+        }
+    }
+    return { homePath, evidencePath, shouldSkipInstall };
+}
+
+/**
+ * Read the SHA-256 digest of a file.
+ *
+ * @param {string} filePath Path of the file to digest.
+ * @returns {string} The hexadecimal digest.
+ */
+export function fileDigest(filePath) {
+    return createHash(DIGEST_ALGORITHM).update(readFileSync(filePath)).digest('hex');
+}
+
+/**
+ * Read every hook command the installed settings file declares for one event.
+ *
+ * @param {string} settingsPath Path of the installed settings file.
+ * @param {string} eventName Hook event name, such as `SessionStart`.
+ * @returns {{matcher: string, command: string}[]} Each declared hook command.
+ */
+export function hookCommandsForEvent(settingsPath, eventName) {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const allMatcherGroups = settings.hooks?.[eventName] ?? [];
+    const allCommands = [];
+    for (const eachGroup of allMatcherGroups) {
+        for (const eachHook of eachGroup.hooks ?? []) {
+            allCommands.push({ matcher: eachGroup.matcher ?? '', command: eachHook.command });
+        }
+    }
+    return allCommands;
+}
+
+/**
+ * Select the one installed hook command a stage drives.
+ *
+ * @param {{matcher: string, command: string}[]} allCommands Declared hook commands.
+ * @param {string} scriptName Basename of the hook script the stage drives.
+ * @returns {string} The command line the install wrote.
+ * @throws {Error} The installed roster declares no such hook.
+ */
+export function selectHookCommand(allCommands, scriptName) {
+    const selected = allCommands.find((each) => each.command.includes(scriptName));
+    if (!selected) {
+        throw new Error(`The installed hook roster declares no ${scriptName}`);
+    }
+    return selected.command;
+}
+
+/**
+ * Run one installed hook command against a payload and return its output.
+ *
+ * @param {string} command The command line the install wrote.
+ * @param {string} scratchHome Scratch home the install wrote into.
+ * @param {object} payload The hook payload written to standard input.
+ * @returns {{status: number | null, stdout: string, stderr: string}} The hook's result.
+ */
+export function runInstalledHook(command, scratchHome, payload) {
+    const hookProcess = spawnSync(command, {
+        shell: true,
+        input: JSON.stringify(payload),
+        encoding: 'utf8',
+        cwd: scratchHome,
+        timeout: HOOK_TIMEOUT_MILLISECONDS,
+        env: scratchHomeEnvironment(scratchHome),
+    });
+    return {
+        status: hookProcess.status,
+        stdout: hookProcess.stdout ?? '',
+        stderr: hookProcess.stderr ?? '',
+    };
+}
+
+/**
+ * Read a hook's standard output as an envelope for one event.
+ *
+ * @param {string} stdout The hook's standard output.
+ * @param {string} eventName The event name the envelope must name.
+ * @returns {object} The `hookSpecificOutput` object.
+ * @throws {Error} The output is not an envelope for that event.
+ */
+export function readEnvelope(stdout, eventName) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        throw new Error(`The hook wrote no ${eventName} envelope`);
+    }
+    const parsed = JSON.parse(trimmed);
+    const hookSpecificOutput = parsed.hookSpecificOutput;
+    if (!hookSpecificOutput || hookSpecificOutput.hookEventName !== eventName) {
+        throw new Error(`The hook envelope names ${hookSpecificOutput?.hookEventName} rather than ${eventName}`);
+    }
+    return hookSpecificOutput;
+}
+
+function writeEvidence(evidenceDirectory, stageName, body) {
+    const evidencePath = join(evidenceDirectory, `${stageName}.json`);
+    writeFileSync(evidencePath, `${body}\n`);
+    return evidencePath;
+}
+
+function reportStage(stageName, evidencePath) {
+    process.stdout.write(`[${PASS_MARK}] playtest ${stageName} ${evidencePath} ${DIGEST_ALGORITHM}=${fileDigest(evidencePath)}\n`);
+}
+
+function reportFailure(stageName, detail) {
+    process.stdout.write(`[${FAIL_MARK}] playtest ${stageName} ${detail}\n`);
+}
+
+function runInstallStage(scratchHome, evidenceDirectory, shouldSkipInstall) {
+    if (!shouldSkipInstall) {
+        const install = runInstaller(scratchHome, []);
+        if (install.status !== 0) {
+            throw new Error(`The installer exited ${install.status}: ${install.stderr.trim()}`);
+        }
+    }
+    const settingsPath = join(scratchHome, SETTINGS_RELATIVE_PATH);
+    if (!existsSync(settingsPath)) {
+        throw new Error(`The install wrote no ${settingsPath}`);
+    }
+    const evidencePath = writeEvidence(
+        evidenceDirectory,
+        INSTALL_STAGE_NAME,
+        JSON.stringify({ settingsPath, digest: fileDigest(settingsPath) }),
+    );
+    reportStage(INSTALL_STAGE_NAME, evidencePath);
+    return settingsPath;
+}
+
+function runSessionStartStage(settingsPath, scratchHome, evidenceDirectory) {
+    const command = selectHookCommand(
+        hookCommandsForEvent(settingsPath, SESSION_START_EVENT_NAME),
+        SESSION_START_HOOK_SCRIPT_NAME,
+    );
+    const hookResult = runInstalledHook(command, scratchHome, SESSION_START_PAYLOAD);
+    const envelope = readEnvelope(hookResult.stdout, SESSION_START_EVENT_NAME);
+    if (typeof envelope.additionalContext !== 'string' || envelope.additionalContext.length === 0) {
+        throw new Error('The SessionStart envelope carries no additionalContext');
+    }
+    const evidencePath = writeEvidence(evidenceDirectory, SESSION_START_STAGE_NAME, JSON.stringify(envelope));
+    reportStage(SESSION_START_STAGE_NAME, evidencePath);
+}
+
+function runBlockingStage(settingsPath, scratchHome, evidenceDirectory) {
+    const command = selectHookCommand(
+        hookCommandsForEvent(settingsPath, PRE_TOOL_USE_EVENT_NAME),
+        BASH_HOOK_SCRIPT_NAME,
+    );
+    const hookResult = runInstalledHook(command, scratchHome, BASH_HOOK_PAYLOAD);
+    const envelope = readEnvelope(hookResult.stdout, PRE_TOOL_USE_EVENT_NAME);
+    if (envelope.permissionDecision !== ALLOW_DECISION) {
+        throw new Error(`The PreToolUse envelope decided ${envelope.permissionDecision}`);
+    }
+    const rewrittenCommand = envelope.updatedInput?.command ?? '';
+    if (!rewrittenCommand.includes(REWRITE_MARKER)) {
+        throw new Error(`The PreToolUse envelope left the command unrewritten: ${rewrittenCommand}`);
+    }
+    const evidencePath = writeEvidence(evidenceDirectory, BLOCKING_STAGE_NAME, JSON.stringify(envelope));
+    reportStage(BLOCKING_STAGE_NAME, evidencePath);
+}
+
+/**
+ * Run every playtest stage and return the driver's exit code.
+ *
+ * @param {string[]} argv Arguments after the script name.
+ * @returns {number} Zero when every stage read the envelope it expected.
+ */
+export function runPlaytest(argv) {
+    const options = parseArguments(argv);
+    const scratchHome = options.homePath ?? createScratchHome();
+    if (options.homePath) {
+        mkdirSync(scratchHome, { recursive: true });
+        const gitConfigPath = join(scratchHome, SANDBOX_GIT_CONFIG_NAME);
+        if (!existsSync(gitConfigPath)) {
+            writeFileSync(gitConfigPath, SANDBOX_GIT_CONFIG_BODY);
+        }
+    }
+    const evidenceDirectory = options.evidencePath ?? mkdtempSync(join(tmpdir(), EVIDENCE_PREFIX));
+    mkdirSync(evidenceDirectory, { recursive: true });
+    let stageName = INSTALL_STAGE_NAME;
+    try {
+        const settingsPath = runInstallStage(scratchHome, evidenceDirectory, options.shouldSkipInstall);
+        stageName = SESSION_START_STAGE_NAME;
+        runSessionStartStage(settingsPath, scratchHome, evidenceDirectory);
+        stageName = BLOCKING_STAGE_NAME;
+        runBlockingStage(settingsPath, scratchHome, evidenceDirectory);
+    } catch (error) {
+        reportFailure(stageName, error instanceof Error ? error.message : String(error));
+        return 1;
+    } finally {
+        if (!options.homePath) {
+            removeScratchHome(scratchHome);
+        }
+    }
+    process.stdout.write('install playtest: every stage read its envelope\n');
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(runPlaytest(process.argv.slice(2)));
+}

package/scripts/ci/install-playtest.test.mjs

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { parseArguments, readEnvelope, selectHookCommand } from './install-playtest.mjs';
+import { SANDBOX_GIT_CONFIG_BODY, SANDBOX_GIT_CONFIG_NAME } from './scratch-home-install.mjs';
+
+const CI_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const DRIVER_PATH = join(CI_DIRECTORY, 'install-playtest.mjs');
+const DRIVER_TIMEOUT_MILLISECONDS = 300_000;
+const SILENT_HOOK_SOURCE = '#!/usr/bin/env python3\nprint("")\n';
+
+function runDriver(driverArguments) {
+    return spawnSync(process.execPath, [DRIVER_PATH, ...driverArguments], {
+        encoding: 'utf8',
+        timeout: DRIVER_TIMEOUT_MILLISECONDS,
+    });
+}
+
+test('the driver reads an envelope from every stage of a fresh install, and reports red when one stage writes none', () => {
+    const scratchHome = mkdtempSync(join(tmpdir(), 'cde-playtest-home-'));
+    const evidenceDirectory = mkdtempSync(join(tmpdir(), 'cde-playtest-evidence-'));
+    try {
+        const greenRun = runDriver(['--home', scratchHome, '--evidence', evidenceDirectory]);
+        assert.equal(greenRun.status, 0, `${greenRun.stdout}\n${greenRun.stderr}`);
+        assert.match(greenRun.stdout, /\[PASS\] playtest install .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest session_start_hook .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest blocking_hook .* sha256=[0-9a-f]{64}/);
+        assert.ok(
+            readFileSync(join(scratchHome, SANDBOX_GIT_CONFIG_NAME), 'utf8').startsWith(SANDBOX_GIT_CONFIG_BODY),
+        );
+
+        writeFileSync(
+            join(scratchHome, '.claude', 'hooks', 'session', 'working_style_prompt.py'),
+            SILENT_HOOK_SOURCE,
+        );
+        const redRun = runDriver(['--home', scratchHome, '--evidence', evidenceDirectory, '--skip-install']);
+        assert.equal(redRun.status, 1, `${redRun.stdout}\n${redRun.stderr}`);
+        assert.match(redRun.stdout, /\[FAIL\] playtest session_start_hook The hook wrote no SessionStart envelope/);
+        assert.doesNotMatch(redRun.stdout, /\[PASS\] playtest session_start_hook/);
+    } finally {
+        rmSync(scratchHome, { recursive: true, force: true });
+        rmSync(evidenceDirectory, { recursive: true, force: true });
+    }
+});
+
+test('parseArguments reads the home, evidence and skip-install options', () => {
+    assert.deepEqual(parseArguments([]), { homePath: null, evidencePath: null, shouldSkipInstall: false });
+    assert.deepEqual(
+        parseArguments(['--home', '/scratch/home', '--evidence', '/scratch/evidence', '--skip-install']),
+        { homePath: '/scratch/home', evidencePath: '/scratch/evidence', shouldSkipInstall: true },
+    );
+});
+
+test('selectHookCommand names the hook the installed roster declares', () => {
+    const allCommands = [
+        { matcher: '', command: 'python3 /home/.claude/hooks/session/task_tool_prompt.py' },
+        { matcher: '', command: 'python3 /home/.claude/hooks/session/working_style_prompt.py' },
+    ];
+    assert.equal(
+        selectHookCommand(allCommands, 'working_style_prompt.py'),
+        'python3 /home/.claude/hooks/session/working_style_prompt.py',
+    );
+    assert.throws(
+        () => selectHookCommand(allCommands, 'absent_hook.py'),
+        /declares no absent_hook\.py/,
+    );
+});
+
+test('readEnvelope refuses output that names another event or no envelope at all', () => {
+    const sessionStartOutput = JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: 'guidance' },
+    });
+    assert.equal(readEnvelope(sessionStartOutput, 'SessionStart').additionalContext, 'guidance');
+    assert.throws(() => readEnvelope('   ', 'SessionStart'), /wrote no SessionStart envelope/);
+    assert.throws(
+        () => readEnvelope(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse' } }), 'SessionStart'),
+        /names PreToolUse rather than SessionStart/,
+    );
+});

package/scripts/ci/installer-lifecycle.mjs

@@ -1,23 +1,20 @@
 #!/usr/bin/env node
 
-import { spawnSync } from 'node:child_process';
 import {
-    mkdtempSync,
     existsSync,
     lstatSync,
     readFileSync,
     realpathSync,
-    writeFileSync,
     readdirSync,
-    rmSync,
 } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
-import { tmpdir } from 'node:os';
-import { fileURLToPath } from 'node:url';
-
-const DRIVER_DIRECTORY = dirname(fileURLToPath(import.meta.url));
-const PACKAGE_ROOT = resolve(DRIVER_DIRECTORY, '..', '..');
-const INSTALL_ENTRY = join(PACKAGE_ROOT, 'bin', 'install.mjs');
+import { join } from 'node:path';
+import {
+    INSTALL_ENTRY,
+    SANDBOX_GIT_CONFIG_NAME,
+    createScratchHome,
+    removeScratchHome,
+    runInstaller,
+} from './scratch-home-install.mjs';
 
 const checks = [];
 
@@ -41,25 +38,9 @@ function collectFilesRecursive(directory) {
     return collected;
 }
 
-function runInstaller(sandboxHome, installerArguments) {
-    const gitConfigGlobal = join(sandboxHome, '.gitconfig-sandbox');
-    const installerProcess = spawnSync(process.execPath, [INSTALL_ENTRY, ...installerArguments], {
-        cwd: PACKAGE_ROOT,
-        encoding: 'utf8',
-        env: {
-            ...process.env,
-            HOME: sandboxHome,
-            USERPROFILE: sandboxHome,
-            GIT_CONFIG_GLOBAL: gitConfigGlobal,
-        },
-    });
-    return installerProcess;
-}
-
 function main() {
-    const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-driver-'));
+    const sandboxHome = createScratchHome();
     const claudeHome = join(sandboxHome, '.claude');
-    writeFileSync(join(sandboxHome, '.gitconfig-sandbox'), '[safe]\n\tdirectory = *\n');
     console.log(`Sandbox HOME: ${sandboxHome}`);
     console.log(`Install entry: ${INSTALL_ENTRY}\n`);
 
@@ -169,7 +150,7 @@ function main() {
         }
         record('settings.json carries managed hooks', managedHookCount > 0, `${managedHookCount} hook commands`);
 
-        const gitConfigGlobalPath = join(sandboxHome, '.gitconfig-sandbox');
+        const gitConfigGlobalPath = join(sandboxHome, SANDBOX_GIT_CONFIG_NAME);
         const gitHooksPathRedirectedIntoSandbox =
             existsSync(gitConfigGlobalPath) &&
             readFileSync(gitConfigGlobalPath, 'utf8').replace(/\\/g, '/').includes('/.claude/hooks/git-hooks');
@@ -195,7 +176,7 @@ function main() {
             sampleInstalledFile ? sampleInstalledFile : 'no sample file captured',
         );
     } finally {
-        rmSync(sandboxHome, { recursive: true, force: true });
+        removeScratchHome(sandboxHome);
         console.log(`\nSandbox removed: ${sandboxHome}`);
     }
 

package/scripts/ci/installer-lifecycle.test.mjs

@@ -24,3 +24,17 @@ test('the Windows adapter invokes the CI-owned lifecycle driver', () => {
     assert.match(adapterSource, /\$driverPath = Join-Path \$PSScriptRoot 'installer-lifecycle\.mjs'/);
     assert.doesNotMatch(adapterSource, /skills\\run-claude-dev-env/);
 });
+
+test('the lifecycle driver builds its sandbox through the shared scratch-home helper', () => {
+    const driverSource = readFileSync(DRIVER_PATH, 'utf8');
+    assert.match(driverSource, /from '\.\/scratch-home-install\.mjs'/);
+    assert.match(driverSource, /createScratchHome\(\)/);
+    assert.match(driverSource, /removeScratchHome\(sandboxHome\)/);
+    assert.doesNotMatch(driverSource, /spawnSync/);
+});
+
+test('the lifecycle driver reads the sandbox git-config name from the shared constant', () => {
+    const driverSource = readFileSync(DRIVER_PATH, 'utf8');
+    assert.match(driverSource, /SANDBOX_GIT_CONFIG_NAME/);
+    assert.doesNotMatch(driverSource, /'\.gitconfig-sandbox'/);
+});

package/scripts/ci/pstack-command-shim.test.mjs

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const CI_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const SHIM_PATH = join(CI_DIRECTORY, '..', 'windows', 'pstack', 'pstack-command-shim.ps1');
+const shimSource = readFileSync(SHIM_PATH, 'utf8');
+
+test('the shim hands every argument after the command to the entrypoint', () => {
+    assert.match(shimSource, /\$commandArguments = @\(\$args \| Select-Object -Skip 1\)/);
+    assert.match(shimSource, /& bun \$entrypoint @commandArguments/);
+});
+
+test('the shim validates the command without a parameter binder', () => {
+    assert.match(shimSource, /-notcontains \$command/);
+    assert.doesNotMatch(shimSource, /ValidateSet/);
+    assert.doesNotMatch(shimSource, /ValueFromRemainingArguments/);
+});
+
+test('the shim bootstraps dependencies before it launches the entrypoint', () => {
+    const bootstrapIndex = shimSource.indexOf('ensureDependenciesInstalled');
+    const launchIndex = shimSource.indexOf('& bun $entrypoint');
+    assert.ok(bootstrapIndex > -1, 'the bootstrap call is absent');
+    assert.ok(launchIndex > -1, 'the entrypoint launch is absent');
+    assert.ok(bootstrapIndex < launchIndex, 'the bootstrap call runs after the launch');
+});
+
+test('the shim exits with the code the entrypoint returned', () => {
+    assert.match(shimSource, /\$exitCode = \$LASTEXITCODE/);
+    assert.match(shimSource, /exit \$exitCode/);
+});

package/scripts/ci/scratch-home-install.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Install this package into a scratch home directory.
+ *
+ * The installer writes into `$HOME/.claude` and rewrites the global git
+ * configuration. Both are redirected here so a run leaves the caller's own home
+ * untouched.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+
+export const PACKAGE_ROOT = resolve(SCRIPT_DIRECTORY, '..', '..');
+export const INSTALL_ENTRY = join(PACKAGE_ROOT, 'bin', 'install.mjs');
+export const SCRATCH_HOME_PREFIX = 'cde-driver-';
+export const SANDBOX_GIT_CONFIG_NAME = '.gitconfig-sandbox';
+export const SANDBOX_GIT_CONFIG_BODY = '[safe]\n\tdirectory = *\n';
+
+/**
+ * Create a scratch home with an isolated global git configuration.
+ *
+ * @returns {string} The scratch home directory path.
+ */
+export function createScratchHome() {
+    const scratchHome = mkdtempSync(join(tmpdir(), SCRATCH_HOME_PREFIX));
+    writeFileSync(join(scratchHome, SANDBOX_GIT_CONFIG_NAME), SANDBOX_GIT_CONFIG_BODY);
+    return scratchHome;
+}
+
+/**
+ * Build the environment an installer run and an installed hook both read.
+ *
+ * @param {string} scratchHome Scratch home directory path.
+ * @returns {NodeJS.ProcessEnv} The environment for a child process.
+ */
+export function scratchHomeEnvironment(scratchHome) {
+    return {
+        ...process.env,
+        HOME: scratchHome,
+        USERPROFILE: scratchHome,
+        GIT_CONFIG_GLOBAL: join(scratchHome, SANDBOX_GIT_CONFIG_NAME),
+    };
+}
+
+/**
+ * Run `bin/install.mjs` against a scratch home.
+ *
+ * @param {string} scratchHome Scratch home directory path.
+ * @param {string[]} installerArguments Arguments passed to the installer.
+ * @returns {import('node:child_process').SpawnSyncReturns<string>} The installer result.
+ */
+export function runInstaller(scratchHome, installerArguments) {
+    return spawnSync(process.execPath, [INSTALL_ENTRY, ...installerArguments], {
+        cwd: PACKAGE_ROOT,
+        encoding: 'utf8',
+        env: scratchHomeEnvironment(scratchHome),
+    });
+}
+
+/**
+ * Remove a scratch home and everything the install wrote into it.
+ *
+ * @param {string} scratchHome Scratch home directory path.
+ * @returns {void}
+ */
+export function removeScratchHome(scratchHome) {
+    rmSync(scratchHome, { recursive: true, force: true });
+}

package/scripts/ci/scratch-home-install.test.mjs

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import {
+    INSTALL_ENTRY,
+    PACKAGE_ROOT,
+    SANDBOX_GIT_CONFIG_BODY,
+    SANDBOX_GIT_CONFIG_NAME,
+    createScratchHome,
+    removeScratchHome,
+    runInstaller,
+    scratchHomeEnvironment,
+} from './scratch-home-install.mjs';
+
+test('the package root and install entry resolve to files that exist', () => {
+    assert.equal(existsSync(INSTALL_ENTRY), true, INSTALL_ENTRY);
+    assert.equal(existsSync(join(PACKAGE_ROOT, 'package.json')), true, PACKAGE_ROOT);
+});
+
+test('a scratch home starts with an isolated global git configuration and is removable', () => {
+    const scratchHome = createScratchHome();
+    try {
+        const gitConfigPath = join(scratchHome, SANDBOX_GIT_CONFIG_NAME);
+        assert.equal(readFileSync(gitConfigPath, 'utf8'), SANDBOX_GIT_CONFIG_BODY);
+        assert.equal(existsSync(join(scratchHome, '.claude')), false);
+
+        const environment = scratchHomeEnvironment(scratchHome);
+        assert.equal(environment.HOME, scratchHome);
+        assert.equal(environment.USERPROFILE, scratchHome);
+        assert.equal(environment.GIT_CONFIG_GLOBAL, gitConfigPath);
+    } finally {
+        removeScratchHome(scratchHome);
+    }
+    assert.equal(existsSync(scratchHome), false);
+});
+
+test('the installer runs against a scratch home and leaves the caller home alone', () => {
+    const scratchHome = createScratchHome();
+    try {
+        const help = runInstaller(scratchHome, ['--help']);
+        assert.equal(help.status, 0, `${help.stdout}\n${help.stderr}`);
+        assert.match(help.stdout, /Usage:/);
+        assert.equal(existsSync(join(scratchHome, '.claude')), false);
+    } finally {
+        removeScratchHome(scratchHome);
+    }
+});