claude-dev-env 2.15.1 → 2.17.0

package/bin/install.prune.test.mjs

@@ -1,4 +1,4 @@
-import { test, after } from 'node:test';
+import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { execFileSync, spawnSync } from 'node:child_process';
 import {
@@ -9,7 +9,6 @@ import {
     readFileSync,
     readdirSync,
     rmSync,
-    cpSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, basename } from 'node:path';
@@ -28,21 +27,15 @@ const RETIRED_SKILL_DIRECTORIES = [
     'pr-consistency-audit',
     'bdd-protocol',
 ];
-const PERSONAL_SKILL_DIRECTORIES = ['balatro', 'midjourney-sref', 'credit-card-picker'];
+const PERSONAL_SKILL_DIRECTORIES = ['credit-card-picker', 'midjourney-sref'];
 const SHIPPED_SKILL_DIRECTORY = 'autoconverge';
 const PRUNED_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
 const SKIP_PRUNE_NOTICE_MARKER = 'Skipping retired-skill and stale-file prune';
 const STALE_SKILL_FILE_RELATIVE_SEGMENTS = ['scripts', 'retired_module.py'];
 const RUNTIME_ARTIFACT_RELATIVE_SEGMENTS = ['scripts', '__pycache__', 'helper.cpython-312.pyc'];
-const DEPENDENCY_STUB_PACKAGE_SEGMENTS = ['@jl-cmd', 'prompt-generator'];
-const DEPENDENCY_SUPPLIED_SKILL_DIRECTORY = 'dependency-supplied-skill';
 const SCOPED_GROUP_SKILL_DIRECTORY = 'orchestrator';
 const CORE_REVIEW_GUIDE_SKILL_DIRECTORIES = [
     'small-cl',
-    'comments',
-    'reviews',
-    'descriptions',
-    'emergencies',
 ];
 const PRIOR_RUN_BACKUP_DIRECTORY_NAMES = [
     '2020-01-01T00-00-00-000Z',
@@ -70,70 +63,6 @@ const NESTED_SKILL_FILE_SEGMENTS = [NESTED_SKILL_DIRECTORY, 'scripts', 'a.py'];
 const MYPY_INI_FILE_NAME = '.mypy.ini';
 const SKIPPED_RECORD_SUMMARY_MARKER = 'manifest record(s) skipped';
 
-/**
- * Create a stub node_modules tree the installer can resolve the declared
- * dependency package from, and return its root for the child's NODE_PATH.
- *
- * The installer resolves `@jl-cmd/prompt-generator/package.json`; a lone
- * package.json at that path is enough for `createRequire.resolve` to succeed.
- * The stub makes the dependency resolvable inside the sandbox so a full install
- * exercises the real prune path. It does not prove the real private package
- * resolves in a real install — CI cannot host that package — only that the
- * resolved-dependency branch prunes as designed.
- *
- * @param {string} homeDirectory The sandbox home the stub is nested under.
- * @returns {string} The stub modules root to place on the child's NODE_PATH.
- */
-let isolatedInstallerPath = null;
-let isolatedPackageCopyRoot = null;
-
-/**
- * Copy the package into a temp directory without node_modules and return the
- * copy's installer path.
- *
- * The installer resolves its declared dependencies with Node's regular
- * node_modules walk starting at its own file, so the real installer under the
- * repo always finds `@jl-cmd/prompt-generator` once `npm install` has run —
- * removing NODE_PATH from the child cannot make the dependency unresolvable
- * there. Running the copy makes resolution genuinely fail through the
- * installer's own catch path: no node_modules sits in the copy's ancestry and
- * the child gets no NODE_PATH. The copy is created once and shared by every
- * unresolved-dependency install; installs write only into their sandbox HOME.
- *
- * @returns {string} The path to `bin/install.mjs` inside the package copy.
- */
-function ensureIsolatedInstallerPath() {
-    if (isolatedInstallerPath !== null) return isolatedInstallerPath;
-    isolatedPackageCopyRoot = mkdtempSync(join(tmpdir(), 'cdev-prune-package-'));
-    cpSync(PACKAGE_DIRECTORY, isolatedPackageCopyRoot, {
-        recursive: true,
-        filter: sourcePath => basename(sourcePath) !== EXCLUDED_PACKAGE_COPY_DIRECTORY,
-    });
-    isolatedInstallerPath = join(isolatedPackageCopyRoot, 'bin', 'install.mjs');
-    return isolatedInstallerPath;
-}
-
-after(() => {
-    if (isolatedPackageCopyRoot !== null) {
-        rmSync(isolatedPackageCopyRoot, { recursive: true, force: true });
-    }
-});
-
-function ensureDependencyStub(homeDirectory) {
-    const stubModulesRoot = join(homeDirectory, 'dependency-stub-modules');
-    const stubPackageDirectory = join(stubModulesRoot, ...DEPENDENCY_STUB_PACKAGE_SEGMENTS);
-    mkdirSync(stubPackageDirectory, { recursive: true });
-    writeFileSync(
-        join(stubPackageDirectory, 'package.json'),
-        JSON.stringify({
-            name: DEPENDENCY_STUB_PACKAGE_SEGMENTS.join('/'),
-            version: '1.0.0',
-            description: 'sandbox dependency stub',
-        }) + '\n',
-    );
-    return stubModulesRoot;
-}
-
 /**
  * Report whether a path under one managed root landed in a run backup.
  *
@@ -203,20 +132,12 @@ function plantSkillDirectory(skillsDirectory, skillName, withSkillManifest) {
 /**
  * Run the real installer against the sandbox home and return its stdout.
  *
- * The declared dependency package is resolvable by default: the child's
- * NODE_PATH points at a sandbox stub so `createRequire.resolve` finds it and the
- * full-install prune runs. Passing ``{ dependencyResolvable: false }`` runs the
- * installer from an isolated package copy with no node_modules in its ancestry
- * and no NODE_PATH, so the dependency fails to resolve and the installer skips
- * the prune.
- *
  * @param {string} homeDirectory The sandbox home the installer writes into.
  * @param {string[]} extraArguments Installer arguments (for example ``['--only', 'core']``).
- * @param {{dependencyResolvable?: boolean}} options Whether the dependency resolves.
  * @returns {string} The installer's stdout.
  */
-function runInstaller(homeDirectory, extraArguments, options = {}) {
-    const { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory, options);
+function runInstaller(homeDirectory, extraArguments) {
+    const { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory);
     return execFileSync('node', [installerPath, ...extraArguments], {
         cwd: dirname(installerPath),
         encoding: 'utf8',
@@ -228,11 +149,9 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
  * Build the installer path and child environment one sandbox run uses.
  *
  * @param {string} homeDirectory The sandbox home the installer writes into.
- * @param {{dependencyResolvable?: boolean}} options Whether the dependency resolves.
  * @returns {{installerPath: string, childEnvironment: object}} The invocation inputs.
  */
-function resolveInstallerInvocation(homeDirectory, options) {
-    const dependencyResolvable = options.dependencyResolvable !== false;
+function resolveInstallerInvocation(homeDirectory) {
     const childEnvironment = {
         ...process.env,
         HOME: homeDirectory,
@@ -240,12 +159,7 @@ function resolveInstallerInvocation(homeDirectory, options) {
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
         CODEX_HOME: join(homeDirectory, '.codex'),
     };
-    if (dependencyResolvable) {
-        childEnvironment.NODE_PATH = ensureDependencyStub(homeDirectory);
-        return { installerPath: INSTALLER_PATH, childEnvironment };
-    }
-    delete childEnvironment.NODE_PATH;
-    return { installerPath: ensureIsolatedInstallerPath(), childEnvironment };
+    return { installerPath: INSTALLER_PATH, childEnvironment };
 }
 
 /**
@@ -259,7 +173,7 @@ function resolveInstallerInvocation(homeDirectory, options) {
  * @returns {string} The child's stdout and stderr, joined.
  */
 function runInstallerReadingBothStreams(homeDirectory, extraArguments) {
-    const { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory, {});
+    const { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory);
     const completedRun = spawnSync('node', [installerPath, ...extraArguments], {
         cwd: dirname(installerPath),
         encoding: 'utf8',
@@ -634,7 +548,7 @@ test('a full reinstall prunes a manifest-recorded skill absent from the package
     const sandbox = createSandbox();
     try {
         const retiredManifestSkill = 'ghost-skill';
-        const personalSkill = 'balatro';
+        const personalSkill = 'credit-card-picker';
         plantSkillDirectory(sandbox.skillsDirectory, retiredManifestSkill, true);
         plantSkillDirectory(sandbox.skillsDirectory, personalSkill, false);
         writeFileSync(
@@ -701,115 +615,25 @@ test('a scoped --only install leaves retired skills in place because prune runs
     }
 });
 
-test('a full reinstall keeps pr-fix-protocol because the package ships it again', () => {
+test('a full reinstall keeps autoconverge because the package ships it again', () => {
     const sandbox = createSandbox();
     try {
-        plantSkillDirectory(sandbox.skillsDirectory, 'pr-fix-protocol', true);
-        writeFileSync(join(sandbox.skillsDirectory, 'pr-fix-protocol', 'SKILL.md'), 'stale seeded copy\n');
+        plantSkillDirectory(sandbox.skillsDirectory, 'autoconverge', true);
+        writeFileSync(join(sandbox.skillsDirectory, 'autoconverge', 'SKILL.md'), 'stale seeded copy\n');
 
         const installerOutput = runInstaller(sandbox.homeDirectory, []);
 
         assert.equal(
             installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
             false,
-            'the resolvable-dependency install runs the prune rather than skipping it',
+            'the full install runs the prune rather than skipping it',
         );
-        const restoredSkillPath = join(sandbox.skillsDirectory, 'pr-fix-protocol', 'SKILL.md');
-        assert.equal(existsSync(restoredSkillPath), true, 'pr-fix-protocol survives and is reinstalled');
+        const restoredSkillPath = join(sandbox.skillsDirectory, 'autoconverge', 'SKILL.md');
+        assert.equal(existsSync(restoredSkillPath), true, 'autoconverge survives and is reinstalled');
         assert.notEqual(
             readFileSync(restoredSkillPath, 'utf8'),
             'stale seeded copy\n',
-            'the shipped pr-fix-protocol overwrites the stale seeded copy',
-        );
-    } finally {
-        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
-    }
-});
-
-test('a full reinstall with an unresolved dependency skips the prune and leaves retired skills untouched', () => {
-    const sandbox = createSandbox();
-    try {
-        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
-            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
-        }
-
-        const installerOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
-
-        assert.equal(
-            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            true,
-            'the installer logs a notice that it is skipping the prune',
-        );
-        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
-            assert.equal(
-                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
-                true,
-                `retired skill ${retiredSkill} should survive when a dependency is unresolved`,
-            );
-            assert.equal(
-                prunedSkillBackupContains(sandbox.claudeDirectory, retiredSkill),
-                false,
-                `retired skill ${retiredSkill} should not be moved to backup when the prune is skipped`,
-            );
-        }
-    } finally {
-        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
-    }
-});
-
-test('a full install that holds the prune keeps prior manifest file entries it did not itself write', () => {
-    const sandbox = createSandbox();
-    try {
-        runInstaller(sandbox.homeDirectory, []);
-        const { staleFilePath } = seedStaleSkillFile(sandbox);
-        const filesBeforeHeldPrune = readManifest(sandbox.manifestPath).files;
-
-        const installerOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
-
-        assert.equal(
-            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            true,
-            'the unresolved-dependency install holds both prunes',
-        );
-        const recordedFiles = new Set(readManifest(sandbox.manifestPath).files);
-        assert.equal(
-            recordedFiles.has(staleFilePath),
-            true,
-            'the entry a later pruning install needs to spot the stale file stays on the record',
-        );
-        const droppedEntries = filesBeforeHeldPrune.filter(priorPath => !recordedFiles.has(priorPath));
-        assert.deepEqual(droppedEntries, [], 'a held prune drops no prior file entry');
-    } finally {
-        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
-    }
-});
-
-test('a full install that holds the prune keeps prior manifest skill names it did not itself install', () => {
-    const sandbox = createSandbox();
-    try {
-        runInstaller(sandbox.homeDirectory, []);
-        plantSkillDirectory(sandbox.skillsDirectory, DEPENDENCY_SUPPLIED_SKILL_DIRECTORY, true);
-        const manifest = readManifest(sandbox.manifestPath);
-        manifest.skills.push(DEPENDENCY_SUPPLIED_SKILL_DIRECTORY);
-        writeFileSync(sandbox.manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-
-        const installerOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
-
-        assert.equal(
-            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            true,
-            'the unresolved-dependency install holds both prunes',
-        );
-        const recordedSkills = new Set(readManifest(sandbox.manifestPath).skills);
-        assert.equal(
-            recordedSkills.has(DEPENDENCY_SUPPLIED_SKILL_DIRECTORY),
-            true,
-            'the name a later pruning install needs to spot the retired skill stays on the record',
-        );
-        assert.equal(
-            recordedSkills.has(SHIPPED_SKILL_DIRECTORY),
-            true,
-            'the held run still records the skills it installed itself',
+            'the shipped autoconverge overwrites the stale seeded copy',
         );
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
@@ -856,43 +680,38 @@ test('a scoped core install ships the canonical review guide skills', () => {
     }
 });
 
-test('the prune skip is scoped: once the dependency resolves a later full install prunes normally', () => {
+test('a scoped core install leaves retired skills in place; a later full install prunes them', () => {
     const sandbox = createSandbox();
     try {
         for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
             plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
         }
 
-        const skippedOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
-        assert.equal(
-            skippedOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            true,
-            'the unresolved-dependency install skips the prune',
-        );
+        runInstaller(sandbox.homeDirectory, ['--only', 'core']);
         for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
             assert.equal(
                 existsSync(join(sandbox.skillsDirectory, retiredSkill)),
                 true,
-                `retired skill ${retiredSkill} should still be present after the skipped prune`,
+                `retired skill ${retiredSkill} should survive a scoped install`,
             );
         }
 
-        const resolvedOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: true });
+        const fullOutput = runInstaller(sandbox.homeDirectory, []);
         assert.equal(
-            resolvedOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            fullOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
             false,
-            'the resolved-dependency install runs the prune, proving the skip is not a permanent disable',
+            'the full install runs the prune',
         );
         for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
             assert.equal(
                 existsSync(join(sandbox.skillsDirectory, retiredSkill)),
                 false,
-                `retired skill ${retiredSkill} should be pruned once the dependency resolves`,
+                `retired skill ${retiredSkill} should be pruned on the full install`,
             );
             assert.equal(
                 prunedSkillBackupContains(sandbox.claudeDirectory, retiredSkill),
                 true,
-                `retired skill ${retiredSkill} should be moved to the prune backup on the resolved install`,
+                `retired skill ${retiredSkill} should be moved to the prune backup`,
             );
         }
     } finally {

package/bin/install.test.mjs

@@ -176,6 +176,15 @@ test('CONTENT_DIRECTORIES includes _shared so installer copies _shared/pr-loop/
 });
 
 
+test('CONTENT_DIRECTORIES omits agents because that tree installs to the agents home', () => {
+    assert.equal(
+        CONTENT_DIRECTORIES.includes('agents'),
+        false,
+        'agents copies into ~/.agents/agents; ~/.claude/agents is the lookup pointer',
+    );
+});
+
+
 test('core includeDirectories ships _shared and scripts for advisor protocol and CLI fallback', () => {
     assert.ok(
         CORE_INCLUDE_DIRECTORIES.includes('_shared'),
@@ -205,6 +214,12 @@ test('CORE_SKILLS ships issue-tracker so the core group installs the skill the S
 });
 
 
+test('CORE_SKILLS ships ELI5 as the leaf presentation skill', () => {
+    assert.ok(CORE_SKILLS.includes('eli5'), 'eli5 must be in CORE_SKILLS');
+    assert.equal(INSTALL_GROUPS.core.skills.includes('eli5'), true);
+});
+
+
 test('EVER_SHIPPED_SKILL_NAMES retains imagegen so reinstall prunes the retired skill', () => {
     assert.ok(
         EVER_SHIPPED_SKILL_NAMES.has('imagegen'),
@@ -971,7 +986,6 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/claude_md_orphan_file_blocker.py', timeout: 10 },
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/pytest_testpaths_orphan_blocker.py', timeout: 10 },
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/open_questions_in_plans_blocker.py', timeout: 10 },
-                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/plain_language_blocker.py', timeout: 10 },
                 ],
             },
         ],
@@ -979,10 +993,9 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('FOLDED_HOOK_RELATIVE_PATHS contains all 15 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
-    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 16);
+test('FOLDED_HOOK_RELATIVE_PATHS contains all 14 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 15);
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/write_existing_file_blocker.py'));
-    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/plain_language_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/code_rules_enforcer.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/pytest_testpaths_orphan_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/md_to_html_blocker.py'));
@@ -1005,7 +1018,6 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
         'blocking/env_var_table_code_drift_blocker.py',
         'blocking/pytest_testpaths_orphan_blocker.py',
         'blocking/open_questions_in_plans_blocker.py',
-        'blocking/plain_language_blocker.py',
     ];
     const retiredHooks = [
         'blocking/md_to_html_blocker.py',

package/bin/publish-directory-pointer.mjs

@@ -0,0 +1,175 @@
+/**
+ * Publish a Claude Code lookup path as a directory pointer to the agents home.
+ *
+ * Skills and agents live under the agents home. Claude Code still discovers
+ * them at `managedRoot/skills` and `managedRoot/agents`, so the installer
+ * writes those two paths as directory pointers (a POSIX symlink, or a Windows
+ * junction). One helper owns the create, refresh, and relocate steps.
+ */
+
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    readlinkSync,
+    readdirSync,
+    renameSync,
+    rmSync,
+    symlinkSync,
+    unlinkSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { normalizePathForComparison } from './resolve-install-root.mjs';
+
+export const DIRECTORY_POINTER_TYPE_JUNCTION = 'junction';
+export const DIRECTORY_POINTER_TYPE_DIR = 'dir';
+export const POINTER_ACTION_ALREADY_POINTING = 'already-pointing';
+export const POINTER_ACTION_CREATED = 'created';
+
+/**
+ * Directory-pointer type this host uses.
+ *
+ * Windows receives a junction so the pointer works without Developer Mode.
+ * POSIX receives a directory symlink.
+ *
+ * @param {string} [platform]
+ * @returns {typeof DIRECTORY_POINTER_TYPE_JUNCTION | typeof DIRECTORY_POINTER_TYPE_DIR}
+ */
+export function directoryPointerTypeForPlatform(platform = process.platform) {
+    return platform === 'win32'
+        ? DIRECTORY_POINTER_TYPE_JUNCTION
+        : DIRECTORY_POINTER_TYPE_DIR;
+}
+
+/**
+ * Report whether pointerPath is a directory pointer whose target is targetPath.
+ *
+ * @param {string} pointerPath
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function isDirectoryPointerTo(pointerPath, targetPath) {
+    const pathKind = readPathKind(pointerPath);
+    if (pathKind !== 'symlink') {
+        return false;
+    }
+    const linkTarget = readlinkSync(pointerPath);
+    const resolvedLinkTarget = resolve(dirname(pointerPath), linkTarget);
+    return normalizePathForComparison(resolvedLinkTarget)
+        === normalizePathForComparison(resolve(targetPath));
+}
+
+/**
+ * Make pointerPath a directory pointer to targetPath.
+ *
+ * A real directory already sitting at the lookup path is merged into the
+ * target, then the pointer is written. A pointer that already aims at the
+ * target is left in place.
+ *
+ * @param {string} pointerPath Claude Code lookup path (for example `~/.claude/skills`).
+ * @param {string} targetPath Canonical directory (for example `~/.agents/skills`).
+ * @param {{ pointerType?: string }} [options]
+ * @returns {{ action: string, pointerPath: string, targetPath: string }}
+ */
+export function ensureDirectoryPointer(pointerPath, targetPath, options = {}) {
+    const pointerType = options.pointerType ?? directoryPointerTypeForPlatform();
+    const resolvedTarget = resolve(targetPath);
+    const resolvedPointer = resolve(pointerPath);
+    mkdirSync(resolvedTarget, { recursive: true });
+
+    if (isDirectoryPointerTo(resolvedPointer, resolvedTarget)) {
+        return {
+            action: POINTER_ACTION_ALREADY_POINTING,
+            pointerPath: resolvedPointer,
+            targetPath: resolvedTarget,
+        };
+    }
+
+    const pathKind = readPathKind(resolvedPointer);
+    if (pathKind === 'symlink') {
+        unlinkSync(resolvedPointer);
+    } else if (pathKind === 'directory') {
+        mergeDirectoryContents(resolvedPointer, resolvedTarget);
+        rmSync(resolvedPointer, { recursive: true, force: true });
+    } else if (pathKind === 'file') {
+        throw new Error(
+            `Cannot publish a directory pointer: ${resolvedPointer} is a file`,
+        );
+    }
+
+    mkdirSync(dirname(resolvedPointer), { recursive: true });
+    symlinkSync(resolvedTarget, resolvedPointer, pointerType);
+    return {
+        action: POINTER_ACTION_CREATED,
+        pointerPath: resolvedPointer,
+        targetPath: resolvedTarget,
+    };
+}
+
+/**
+ * Remove a directory pointer when it aims at the expected target.
+ *
+ * @param {string} pointerPath
+ * @param {string} targetPath
+ * @returns {boolean} True when this call unlinked the pointer.
+ */
+export function unlinkDirectoryPointerIfMatch(pointerPath, targetPath) {
+    if (!isDirectoryPointerTo(pointerPath, targetPath)) {
+        return false;
+    }
+    unlinkSync(pointerPath);
+    return true;
+}
+
+/**
+ * @param {string} absolutePath
+ * @returns {'missing' | 'symlink' | 'directory' | 'file' | 'other'}
+ */
+function readPathKind(absolutePath) {
+    let stats;
+    try {
+        stats = lstatSync(absolutePath);
+    } catch (readError) {
+        if (readError && readError.code === 'ENOENT') {
+            return 'missing';
+        }
+        throw readError;
+    }
+    if (stats.isSymbolicLink()) {
+        return 'symlink';
+    }
+    if (stats.isDirectory()) {
+        return 'directory';
+    }
+    if (stats.isFile()) {
+        return 'file';
+    }
+    return 'other';
+}
+
+/**
+ * Move unique entries from sourceDirectory into destinationDirectory.
+ *
+ * An entry that already exists at the destination stays there. Nested
+ * directories merge the same way. Leftover source entries are removed by the
+ * caller with the source directory.
+ *
+ * @param {string} sourceDirectory
+ * @param {string} destinationDirectory
+ * @returns {void}
+ */
+function mergeDirectoryContents(sourceDirectory, destinationDirectory) {
+    mkdirSync(destinationDirectory, { recursive: true });
+    const allEntries = readdirSync(sourceDirectory, { withFileTypes: true });
+    for (const eachEntry of allEntries) {
+        const sourceChild = join(sourceDirectory, eachEntry.name);
+        const destinationChild = join(destinationDirectory, eachEntry.name);
+        if (!existsSync(destinationChild)) {
+            renameSync(sourceChild, destinationChild);
+            continue;
+        }
+        if (eachEntry.isDirectory() && readPathKind(destinationChild) === 'directory') {
+            mergeDirectoryContents(sourceChild, destinationChild);
+        }
+    }
+}