claude-dev-env 2.9.0 → 2.10.0

package/bin/install.mjs

@@ -3,13 +3,18 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, copyFileSync, unlinkSync, rmSync, rmdirSync, renameSync, realpathSync, lstatSync } from 'node:fs';
 import { join, dirname, resolve, relative, basename, isAbsolute, extname } from 'node:path';
 import { homedir } from 'node:os';
-import { execSync, execFileSync } from 'node:child_process';
+import { execSync, execFileSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { installAllGitHooks } from './git_hooks_installer.mjs';
 import { installMypyIniForClaudeHooks } from './install_mypy_ini.mjs';
 import { expandHomeDirectoryTokensInSettings } from './expand_home_directory_tokens.mjs';
 import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
+import {
+    managedDenyEntriesFromPackageSettings,
+    mergeManagedPermissionsIntoSettings,
+    pruneManagedPermissionsFromSettings,
+} from './merge_managed_permissions.mjs';
 import {
     SKIPPED_SOURCE_ENTRY_NAMES,
     SKIPPED_SOURCE_FILE_EXTENSIONS,
@@ -17,17 +22,72 @@ import {
     MANAGED_SKILLS_DIRECTORY_NAME,
     MANAGED_HOOKS_DIRECTORY_NAME,
     SETTINGS_FILE_NAME,
-    MYPY_INI_FILE_NAME,
 } from './install-constants.mjs';
+import {
+    resolveInstallRoot,
+    parseExplicitTargetFromArgv,
+} from './resolve-install-root.mjs';
+import {
+    parseInstallTargetSelectionFromArgv,
+    resolveInstallTargets,
+    buildTargetManifestRecord,
+    stripTargetSelectionFlagsFromArgv,
+    resolveProfilesRootDirectory,
+    MAIN_DEFAULT_TARGET_IDENTITY,
+    TARGET_IDENTITY_FLAG,
+} from './select-install-targets.mjs';
+import {
+    buildInstallPlan,
+    buildUninstallPlan,
+    InstallPlanPreflightError,
+} from './install-plan.mjs';
+import {
+    FAULT_PHASES,
+    InstallTransactionFaultError,
+    TRANSACTION_JOURNAL_DIRECTORY_NAME,
+    capturePriorInstallSnapshot,
+    resolveFaultPhaseFromEnvironment,
+    runWithInstallTransaction,
+} from './install-transaction.mjs';
 
-const CLAUDE_HOME = join(homedir(), '.claude');
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const MANIFEST_FILE = join(CLAUDE_HOME, '.claude-dev-env-manifest.json');
-const MYPY_INI_INSTALL_PATH = join(homedir(), MYPY_INI_FILE_NAME);
+const INSTALL_ROOT_RESOLUTION = resolveInstallRoot({
+    environment: process.env,
+    homeDirectory: homedir(),
+    explicitTarget: (() => {
+        try {
+            return parseExplicitTargetFromArgv(process.argv.slice(2));
+        } catch {
+            return null;
+        }
+    })(),
+});
+const CLAUDE_HOME = INSTALL_ROOT_RESOLUTION.managedRoot;
+const MANIFEST_FILE = INSTALL_ROOT_RESOLUTION.manifestFilePath;
+const MYPY_INI_INSTALL_PATH = INSTALL_ROOT_RESOLUTION.mypyIniInstallPath;
 const PACKAGE_NAME = 'claude-dev-env';
 const PACKAGE_VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
 const packageRequire = createRequire(import.meta.url);
 
+/**
+ * Target identity for the current process hop. Multi-profile parent hops re-exec
+ * each child with --target-identity; a bare main install stays "main".
+ */
+const INSTALL_TARGET_IDENTITY = (() => {
+    try {
+        const selection = parseInstallTargetSelectionFromArgv(process.argv.slice(2));
+        if (selection.targetIdentity) {
+            return selection.targetIdentity;
+        }
+        if (selection.mode === 'profiles' && selection.allProfileIds.length === 1) {
+            return selection.allProfileIds[0];
+        }
+        return MAIN_DEFAULT_TARGET_IDENTITY;
+    } catch {
+        return MAIN_DEFAULT_TARGET_IDENTITY;
+    }
+})();
+
 export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts', '_shared', 'audit-rubrics'];
 
 /**
@@ -48,8 +108,7 @@ const NEVER_PRUNED_SKILL_DIRECTORIES = new Set(['_shared']);
 const PRUNED_SKILLS_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
 const RETIRED_SKILL_REASON_LABEL = 'retired';
 const STALE_FILE_REASON_LABEL = 'stale';
-const MANIFEST_FILES_KEY = 'files';
-const MANIFEST_SKILLS_KEY = 'skills';
+const MANIFEST_MANAGED_PERMISSIONS_KEY = 'managedPermissions';
 
 export const CORE_INCLUDE_DIRECTORIES = [
     'rules', 'docs', 'commands', 'agents', 'audit-rubrics', '_shared', 'scripts',
@@ -62,6 +121,7 @@ export const CORE_SKILLS = [
     'privacy-hygiene',
     'issue-tracker',
     'recall', 'remember', 'task-build',
+    'show',
 ];
 
 export function collectPackageSourceConflicts(packageDirectory) {
@@ -110,24 +170,6 @@ export function collectPackageSourceConflicts(packageDirectory) {
     return allConflicts;
 }
 
-function abortWhenPackageSourceHasConflicts(packageDirectory) {
-    const conflicts = collectPackageSourceConflicts(packageDirectory);
-    if (conflicts.length === 0) return;
-    console.error(
-        `\nERROR: ${PACKAGE_NAME} source has unmerged conflicts under ${packageDirectory}:\n`,
-    );
-    for (const conflict of conflicts) {
-        console.error(`  ${conflict.statusCode} ${conflict.path}`);
-    }
-    console.error(
-        '\nResolve the conflicts in the package source before running the installer.',
-    );
-    console.error(
-        'Installing from a conflicted source can copy stale or broken files into ~/.claude/.\n',
-    );
-    process.exit(1);
-}
-
 function resolveDependencyPackageRoot(dependencyPackageName) {
     const dependencyPackageJsonPath = packageRequire.resolve(
         `${dependencyPackageName}/package.json`
@@ -1357,6 +1399,37 @@ export function pruneRetiredHookEntriesFromSettings(settingsPath, retiredHookRel
     return removedCount;
 }
 
+/**
+ * Load ~/.claude/settings.json for an in-place merge, or `{}` when absent/empty.
+ *
+ * Malformed JSON or a non-object root ends the process so install never writes
+ * onto a shape the harness cannot read.
+ *
+ * @param {string} settingsPath Absolute path to settings.json.
+ * @returns {object}
+ */
+function loadClaudeSettingsObjectOrExit(settingsPath) {
+    if (!existsSync(settingsPath)) {
+        return {};
+    }
+    const raw = readFileSync(settingsPath, 'utf8').trim();
+    if (!raw) {
+        return {};
+    }
+    let settings;
+    try {
+        settings = JSON.parse(raw);
+    } catch {
+        console.error('  ERROR: settings.json is malformed JSON. Fix it and rerun.');
+        process.exit(1);
+    }
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+        console.error('  ERROR: settings.json holds a value other than a JSON object. Fix it and rerun.');
+        process.exit(1);
+    }
+    return settings;
+}
+
 /**
  * Merge one package source root's hook groups into ~/.claude/settings.json.
  *
@@ -1373,74 +1446,68 @@ function mergeHooks(hooksSourceRoot, pythonCommand) {
     if (!existsSync(hooksJsonPath)) return 0;
     const hooksConfig = JSON.parse(readFileSync(hooksJsonPath, 'utf8'));
     const settingsPath = join(CLAUDE_HOME, SETTINGS_FILE_NAME);
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        const raw = readFileSync(settingsPath, 'utf8').trim();
-        if (raw) {
-            try { settings = JSON.parse(raw); }
-            catch { console.error('  ERROR: settings.json is malformed JSON. Fix it and rerun.'); process.exit(1); }
-            if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
-                console.error('  ERROR: settings.json holds a value other than a JSON object. Fix it and rerun.');
-                process.exit(1);
-            }
-        }
-    }
+    const settings = loadClaudeSettingsObjectOrExit(settingsPath);
     const groupCount = mergeHooksIntoSettings(settings, hooksConfig, CLAUDE_HOME, pythonCommand);
     writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
     return groupCount;
 }
 
-function writeManifest(installedFiles, skillNames) {
-    const manifest = {
-        package: PACKAGE_NAME,
-        version: PACKAGE_VERSION,
-        installedAt: new Date().toISOString(),
-        [MANIFEST_FILES_KEY]: installedFiles,
-    };
-    if (skillNames) {
-        manifest[MANIFEST_SKILLS_KEY] = skillNames;
+function writeManifest(installedFiles, skillNames, managedPermissions = null) {
+    const manifest = buildTargetManifestRecord({
+        packageName: PACKAGE_NAME,
+        packageVersion: PACKAGE_VERSION,
+        targetIdentity: INSTALL_TARGET_IDENTITY,
+        managedRoot: CLAUDE_HOME,
+        files: installedFiles,
+        skills: skillNames,
+    });
+    if (managedPermissions && Array.isArray(managedPermissions.deny) && managedPermissions.deny.length > 0) {
+        manifest[MANIFEST_MANAGED_PERMISSIONS_KEY] = {
+            deny: [...managedPermissions.deny],
+        };
     }
     writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2) + '\n');
 }
 
 /**
- * Read the file list and the skill list the previous install recorded, in one
- * parse of the manifest.
+ * Load package-owned deny entries from the package settings.json source.
  *
- * A full install's manifest holds thousands of path strings, so the record is
- * read and parsed once and both lists are handed back together.
- *
- * Either list is null when the manifest is missing, unreadable, or holds no array
- * at that key, so a caller treats every such case as "no prior record": the skills
- * list leans on the ever-shipped set to find retired skills, and the files list
- * holds the stale-file prune for that run rather than guessing at what a prior
- * install wrote. A `--update` run purges the manifest before reinstalling, so this
- * read happens at the top of `install()` while the record is still on disk.
- *
- * @returns {{files: string[]|null, skills: string[]|null}} The recorded lists, each null when absent.
+ * @returns {string[]}
  */
-function readPriorManifestArrays() {
-    const missingRecord = { files: null, skills: null };
-    if (!existsSync(MANIFEST_FILE)) return missingRecord;
+function loadPackageManagedDenyEntries() {
+    const packageSettingsPath = join(PACKAGE_ROOT, SETTINGS_FILE_NAME);
+    if (!existsSync(packageSettingsPath)) {
+        return [];
+    }
     try {
-        const priorManifest = JSON.parse(readFileSync(MANIFEST_FILE, 'utf8'));
-        return {
-            files: arrayOrNull(priorManifest[MANIFEST_FILES_KEY]),
-            skills: arrayOrNull(priorManifest[MANIFEST_SKILLS_KEY]),
-        };
-    } catch {
-        return missingRecord;
+        const packageSettings = JSON.parse(readFileSync(packageSettingsPath, 'utf8'));
+        return managedDenyEntriesFromPackageSettings(packageSettings);
+    } catch (parseError) {
+        console.warn(
+            `  Warning: could not read package ${SETTINGS_FILE_NAME} for managed permissions (${parseError.message})`,
+        );
+        return [];
     }
 }
 
 /**
- * Return a recorded manifest value when it is an array, and null otherwise.
+ * Merge package-owned permission defaults into ~/.claude/settings.json.
  *
- * @param {unknown} recordedEntries The value read at a manifest key.
- * @returns {string[]|null} The array, or null when the key holds anything else.
+ * @returns {{addedCount: number, alreadyPresentCount: number, managedDenyEntries: string[]}}
  */
-function arrayOrNull(recordedEntries) {
-    return Array.isArray(recordedEntries) ? recordedEntries : null;
+function mergeManagedPermissions() {
+    const managedDenyEntries = loadPackageManagedDenyEntries();
+    if (managedDenyEntries.length === 0) {
+        return { addedCount: 0, alreadyPresentCount: 0, managedDenyEntries: [] };
+    }
+    const settingsPath = join(CLAUDE_HOME, SETTINGS_FILE_NAME);
+    const settingsExisted = existsSync(settingsPath);
+    const settings = loadClaudeSettingsObjectOrExit(settingsPath);
+    const mergeOutcome = mergeManagedPermissionsIntoSettings(settings, managedDenyEntries);
+    if (mergeOutcome.addedCount > 0 || !settingsExisted) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
+    }
+    return mergeOutcome;
 }
 
 /**
@@ -1660,25 +1727,104 @@ function runFullInstallPrunes(
  * @returns {void}
  */
 function install(selectedGroups, options = {}) {
-    const { files: priorManifestFiles, skills: priorManifestSkills } = readPriorManifestArrays();
-    const isUpdateRefresh = Boolean(options.isUpdateRefresh);
-    if (isUpdateRefresh && !selectedGroups && existsSync(MANIFEST_FILE)) {
+    let plan;
+    try {
+        plan = buildInstallPlan({
+            packageRoot: PACKAGE_ROOT,
+            managedRoot: CLAUDE_HOME,
+            manifestFilePath: MANIFEST_FILE,
+            targetIdentity: INSTALL_TARGET_IDENTITY,
+            selectedGroups,
+            isUpdateRefresh: Boolean(options.isUpdateRefresh),
+            installGroups: INSTALL_GROUPS,
+            collectSourceConflicts: collectPackageSourceConflicts,
+            detectPythonCommand: detectPython,
+            packageName: PACKAGE_NAME,
+        });
+    } catch (preflightError) {
+        if (preflightError instanceof InstallPlanPreflightError) {
+            console.error(preflightError.message);
+            process.exit(1);
+        }
+        throw preflightError;
+    }
+    executeInstallPlan(plan);
+}
+
+/**
+ * Apply one preflighted installation plan inside a snapshot/restore transaction.
+ *
+ * Captures the prior managed installation before any purge or write, then
+ * restores settings, manifest, managed files, and core.hooksPath on failure.
+ *
+ * @param {ReturnType<typeof buildInstallPlan>} plan
+ * @returns {void}
+ */
+function executeInstallPlan(plan) {
+    const faultPhase = resolveFaultPhaseFromEnvironment(process.env);
+    const snapshot = capturePriorInstallSnapshot({
+        managedRoot: CLAUDE_HOME,
+        manifestFilePath: MANIFEST_FILE,
+        settingsPath: plan.settingsPath,
+        priorManifestFiles: plan.priorManifest.files,
+        journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
+    });
+
+    try {
+        runWithInstallTransaction({
+            snapshot,
+            faultPhase,
+            runMutations: ({ throwIfFault, syncWrittenPaths }) => {
+                executeInstallPlanMutations(plan, { throwIfFault, syncWrittenPaths });
+            },
+        });
+    } catch (mutationError) {
+        if (mutationError instanceof InstallTransactionFaultError) {
+            console.error(
+                `ERROR: install aborted at ${mutationError.phase}; prior installation restored.`,
+            );
+            process.exit(1);
+        }
+        const message = mutationError instanceof Error
+            ? mutationError.message
+            : String(mutationError);
+        console.error(`ERROR: install failed (${message}); prior installation restored.`);
+        process.exit(1);
+    }
+}
+
+/**
+ * Mutation body for one preflighted plan. Invoked inside the transaction wrapper.
+ *
+ * @param {ReturnType<typeof buildInstallPlan>} plan
+ * @param {{
+ *   throwIfFault: (phase: string) => void,
+ *   syncWrittenPaths: (allPaths: string[]) => void,
+ * }} transactionHelpers
+ * @returns {void}
+ */
+function executeInstallPlanMutations(plan, transactionHelpers) {
+    const { throwIfFault, syncWrittenPaths } = transactionHelpers;
+    const selectedGroups = plan.selectedGroups;
+    const priorManifestFiles = plan.priorManifest.files;
+    const priorManifestSkills = plan.priorManifest.skills;
+    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({ requireManifest: false });
+        purgeManagedInstallation({
+            requireManifest: false,
+            throwIfFault,
+        });
     } else if (isUpdateRefresh) {
         const installScope = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'full';
         console.log(`${PACKAGE_NAME}: --update — re-running ${installScope} install into ${CLAUDE_HOME}\n`);
     }
     const groupLabel = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'all';
     console.log(`\nInstalling ${PACKAGE_NAME} (${groupLabel})...\n`);
-    abortWhenPackageSourceHasConflicts(PACKAGE_ROOT);
-    const pythonCommand = detectPython();
-    if (!pythonCommand) {
-        console.error('ERROR: No usable Python 3 found. Install Python 3.8+ from python.org and ensure py, python3, or python is on PATH. On Windows the Microsoft Store python.exe alias is rejected because it cannot run hooks.');
-        process.exit(1);
-    }
     console.log(`  Python: ${pythonCommand}`);
     mkdirSync(CLAUDE_HOME, { recursive: true });
 
@@ -1779,6 +1925,9 @@ function install(selectedGroups, options = {}) {
     }
     summary.skills = { created: skillsCreated, updated: skillsUpdated, pruned: 0, paths: skillPaths };
     allInstalledFiles.push(...skillPaths);
+    syncWrittenPaths(allInstalledFiles);
+    throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
+    throwIfFault(FAULT_PHASES.BEFORE_DURABLE_PROMOTION);
     const shouldInstallAnyHooks = shouldInstallAllHooks || (allowedHookFiles && allowedHookFiles.size > 0);
     if (shouldInstallAnyHooks) {
         let totalHooksCreated = 0;
@@ -1811,6 +1960,8 @@ function install(selectedGroups, options = {}) {
         console.log(`  Hook files: ${totalHooksCreated} new, ${totalHooksUpdated} updated`);
         summary.hookGroups = totalHookGroups;
         console.log(`  Hook groups: ${totalHookGroups} merged into settings.json`);
+        syncWrittenPaths(allInstalledFiles);
+        throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
 
         console.warn(
             '  Warning: git hook installation sets core.hooksPath globally — '
@@ -1831,6 +1982,9 @@ function install(selectedGroups, options = {}) {
             console.warn(`  Git hooks: ${gitHookInstallationResult.hooksPathConfigurationResult.reason}`);
         }
         console.log(`  Git hook shims: ${gitHookInstallationResult.createdShimPaths.length} files (pre-commit, pre-push, post-commit)`);
+        syncWrittenPaths(allInstalledFiles);
+        throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
+        throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
 
         const mypyIniInstallResult = installMypyIniForClaudeHooks({
             homeDirectory: homedir(),
@@ -1847,7 +2001,23 @@ function install(selectedGroups, options = {}) {
             console.warn(`    To enable mypy for Claude hooks, add this line under [mypy]:`);
             console.warn(`      ${mypyIniInstallResult.expectedLine}`);
         }
+    } else {
+        syncWrittenPaths(allInstalledFiles);
+        throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
+        throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
+        throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
+    }
+
+    const permissionMerge = mergeManagedPermissions();
+    summary.managedPermissions = permissionMerge;
+    if (permissionMerge.managedDenyEntries.length > 0) {
+        console.log(
+            `  Permissions: ${permissionMerge.addedCount} managed deny(s) added, `
+            + `${permissionMerge.alreadyPresentCount} already present `
+            + `(${permissionMerge.managedDenyEntries.length} package-owned)`,
+        );
     }
+
     const claudeHubSource = join(PACKAGE_ROOT, 'CLAUDE.md');
     if (existsSync(claudeHubSource)) {
         const claudeHubDest = join(CLAUDE_HOME, 'CLAUDE.md');
@@ -1893,7 +2063,16 @@ function install(selectedGroups, options = {}) {
     const manifestFiles = didPruneFinish
         ? manifestFilesWithFailedPrunes(allInstalledFiles, failedPrunePaths)
         : unionOnComparisonKey(priorManifestFiles || [], allInstalledFiles);
-    writeManifest(manifestFiles, manifestSkillNames);
+    const managedPermissionDenyEntries = summary.managedPermissions.managedDenyEntries;
+    writeManifest(
+        manifestFiles,
+        manifestSkillNames,
+        managedPermissionDenyEntries.length > 0
+            ? { deny: managedPermissionDenyEntries }
+            : null,
+    );
+    syncWrittenPaths([...allInstalledFiles, MANIFEST_FILE, plan.settingsPath]);
+    throwIfFault(FAULT_PHASES.AFTER_MANIFEST_WRITE);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
         if (summary[directory]) {
@@ -1985,66 +2164,92 @@ function removeRecordedFile(filePath) {
 }
 
 /**
- * Remove every file the manifest records, then drop the directories the removals
- * emptied.
- *
- * A record is removed when it names a path the installer writes: anything under
- * ~/.claude, plus the `~/.mypy.ini` the install writes in the home directory.
- * Every other record is skipped with a warning and counted, so one malformed
- * entry costs that entry alone: the purge removes every legitimate record, clears
- * the manifest, and leaves the user with a whole uninstall rather than a
- * half-removed install.
+ * Build the uninstall plan for this managed root.
  *
- * Directory cleanup runs after the file loop so a directory holding two recorded
- * files is judged once both are gone. Each walk stops at the managed root the
- * purged file sits under, which keeps ~/.claude itself and every unmanaged
- * sibling directory in place.
+ * @param {boolean} requireManifest
+ * @returns {ReturnType<typeof buildUninstallPlan>}
+ */
+function resolveUninstallPlan(requireManifest) {
+    return buildUninstallPlan({
+        managedRoot: CLAUDE_HOME,
+        manifestFilePath: MANIFEST_FILE,
+        requireManifest,
+        isRemovableRecord: isRemovableManifestRecord,
+    });
+}
+
+/**
+ * Apply one preflighted uninstall plan: remove removable files, prune managed
+ * hooks from settings, unset core.hooksPath when it points here, then drop the
+ * ownership manifest. Fault phases mirror the install transaction names.
  *
- * @param {{requireManifest: boolean}} options `requireManifest` exits when no manifest exists.
- * @returns {number|void} 0 when no manifest exists and none is required.
+ * @param {ReturnType<typeof buildUninstallPlan>} plan
+ * @param {{ throwIfFault?: (phase: string) => void }} [helpers]
+ * @returns {number} Count of files this call removed.
  */
-function purgeManagedInstallation({ requireManifest }) {
-    if (!existsSync(MANIFEST_FILE)) {
-        if (requireManifest) {
-            console.error('No installation manifest found. Nothing to uninstall.');
-            process.exit(1);
-        }
-        return 0;
-    }
-    const manifest = JSON.parse(readFileSync(MANIFEST_FILE, 'utf8'));
+function executeUninstallPlan(plan, helpers = {}) {
+    const throwIfFault = helpers.throwIfFault || (() => {});
     let removed = 0;
-    let skippedUnmanagedCount = 0;
     const managedRootByEmptiedDirectory = new Map();
-    for (const filePath of manifest.files) {
-        if (!isRemovableManifestRecord(filePath)) {
-            console.warn(`  Warning: skipping ${filePath} — the manifest record names no path this installer writes`);
-            skippedUnmanagedCount++;
-            continue;
+    for (const filePath of plan.removableFiles) {
+        if (removeRecordedFile(filePath)) {
+            removed += 1;
         }
-        if (removeRecordedFile(filePath)) removed++;
         const managedRoot = owningManagedRoot(filePath);
-        if (managedRoot) managedRootByEmptiedDirectory.set(dirname(resolve(filePath)), managedRoot);
+        if (managedRoot) {
+            managedRootByEmptiedDirectory.set(dirname(resolve(filePath)), managedRoot);
+        }
     }
     for (const [emptiedDirectory, managedRoot] of managedRootByEmptiedDirectory) {
         removeEmptiedParentDirectories(emptiedDirectory, managedRoot);
     }
-    if (skippedUnmanagedCount > 0) {
-        console.warn(`  ${skippedUnmanagedCount} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME} and outside ${MYPY_INI_INSTALL_PATH}`);
+    for (const eachSkippedPath of plan.skippedFiles) {
+        console.warn(
+            `  Warning: skipping ${eachSkippedPath} — the manifest record names no path this installer writes`,
+        );
     }
-    const settingsPath = join(CLAUDE_HOME, SETTINGS_FILE_NAME);
-    if (existsSync(settingsPath)) {
-        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    if (plan.skippedFiles.length > 0) {
+        console.warn(
+            `  ${plan.skippedFiles.length} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME} and outside ${MYPY_INI_INSTALL_PATH}`,
+        );
+    }
+    throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
+
+    if (existsSync(plan.settingsPath)) {
+        const settings = JSON.parse(readFileSync(plan.settingsPath, 'utf8'));
+        let settingsChanged = false;
         if (settings.hooks) {
             const managedHookRelativePaths = managedHookScriptRelativePathsFromSourceRoots(
-                managedPackageSourceRoots()
+                managedPackageSourceRoots(),
             );
             pruneManagedHooksFromSettings(settings, managedHookRelativePaths);
-            writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
+            settingsChanged = true;
             console.log('  Hook entries removed from settings.json');
         }
+        const managedDenyFromPlan = plan.managedPermissionDenyEntries.length > 0
+            ? plan.managedPermissionDenyEntries
+            : loadPackageManagedDenyEntries();
+        if (managedDenyFromPlan.length > 0) {
+            const pruneOutcome = pruneManagedPermissionsFromSettings(settings, managedDenyFromPlan);
+            if (pruneOutcome.removedCount > 0) {
+                settingsChanged = true;
+                console.log(
+                    `  Permission entries removed from settings.json: ${pruneOutcome.removedCount} managed deny(s)`,
+                );
+            }
+        }
+        if (settingsChanged) {
+            writeFileSync(plan.settingsPath, JSON.stringify(settings, null, 4) + '\n');
+        }
     }
+    throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
+
     unsetGlobalGitHooksPathIfOurs();
-    unlinkSync(MANIFEST_FILE);
+    throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
+
+    unlinkSync(plan.manifestFilePath);
+    throwIfFault(FAULT_PHASES.AFTER_MANIFEST_WRITE);
+
     for (const directory of MANAGED_TOP_LEVEL_DIRECTORY_NAMES) {
         const dirPath = join(CLAUDE_HOME, directory);
         try {
@@ -2054,11 +2259,85 @@ function purgeManagedInstallation({ requireManifest }) {
         } catch { /* leave non-empty dirs */ }
     }
     console.log(`\nRemoved ${removed} files.\n`);
+    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 {{
+ *   requireManifest: boolean,
+ *   throwIfFault?: (phase: string) => void,
+ * }} options
+ * @returns {number|void} 0 when no manifest exists and none is required.
+ */
+function purgeManagedInstallation({ requireManifest, throwIfFault }) {
+    const plan = resolveUninstallPlan(requireManifest);
+    if (plan.isNoOp) {
+        return 0;
+    }
+    return executeUninstallPlan(plan, { throwIfFault });
+}
+
+/**
+ * Uninstall the selected managed root inside a snapshot/restore transaction.
+ *
+ * Captures files, settings, manifest, and core.hooksPath before removal so any
+ * later fault restores a retryable installation from the ownership record.
+ *
+ * @returns {void}
+ */
 function uninstall() {
     console.log(`\nUninstalling ${PACKAGE_NAME}...\n`);
-    purgeManagedInstallation({ requireManifest: true });
+    let plan;
+    try {
+        plan = resolveUninstallPlan(true);
+    } catch (preflightError) {
+        if (preflightError instanceof InstallPlanPreflightError) {
+            console.error(preflightError.message);
+            process.exit(1);
+        }
+        throw preflightError;
+    }
+    if (plan.isNoOp) {
+        return;
+    }
+
+    const faultPhase = resolveFaultPhaseFromEnvironment(process.env);
+    const snapshot = capturePriorInstallSnapshot({
+        managedRoot: CLAUDE_HOME,
+        manifestFilePath: MANIFEST_FILE,
+        settingsPath: plan.settingsPath,
+        priorManifestFiles: plan.removableFiles,
+        journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
+    });
+
+    try {
+        runWithInstallTransaction({
+            snapshot,
+            faultPhase,
+            runMutations: ({ throwIfFault }) => {
+                executeUninstallPlan(plan, { throwIfFault });
+            },
+        });
+    } catch (mutationError) {
+        if (mutationError instanceof InstallTransactionFaultError) {
+            console.error(
+                `ERROR: uninstall aborted at ${mutationError.phase}; prior installation restored.`,
+            );
+            process.exit(1);
+        }
+        const message = mutationError instanceof Error
+            ? mutationError.message
+            : String(mutationError);
+        console.error(`ERROR: uninstall failed (${message}); prior installation restored.`);
+        process.exit(1);
+    }
 }
 
 /**
@@ -2078,10 +2357,13 @@ function printHelp() {
 ${PACKAGE_NAME} - Claude Code development standards installer
 
 Usage:
-  npx ${PACKAGE_NAME}              Install everything
+  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} --only X     Install specific groups
-  npx ${PACKAGE_NAME} --uninstall  Remove installed files
+  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)
+  npx ${PACKAGE_NAME} --profiles A,B  Install into each selected profile (one ownership manifest per target)
+  npx ${PACKAGE_NAME} --uninstall  Remove installed files from the selected root
   npx ${PACKAGE_NAME} --help       Show this help
 
 Groups:
@@ -2090,8 +2372,16 @@ ${groupLines}
 Examples:
   npx ${PACKAGE_NAME} --only core
   npx ${PACKAGE_NAME} --only core,journal
+  npx ${PACKAGE_NAME} --profile editor --only core
+  npx ${PACKAGE_NAME} --profiles editor,mel --only core
+
+Install location: ~/.claude/ by default; CLAUDE_CONFIG_DIR or --target selects another managed root.
+Named profiles resolve under LLM_SETTINGS_PROFILES_ROOT or ~/.claude-profiles/<directoryName>.
 
-Install location: ~/.claude/
+Root precedence: --target > CLAUDE_CONFIG_DIR > ~/.claude
+Profile selection (--profile/--profiles) is mutually exclusive with --target.
+Target selection finishes before any mutation. Each target writes its own manifest
+with package, version, targetIdentity, managedRoot, files, and skills.
 
 If ~/.claude/CLAUDE.md already exists and differs from the package copy, the installer
 writes the previous contents to ~/.claude/backups/CLAUDE.md.<timestamp>.bak first.
@@ -2130,30 +2420,186 @@ function realPathOrSelf(filesystemPath) {
     }
 }
 
+/**
+ * Load profile id → directoryName from the A1 launcher contract when present.
+ * Falls back to identity mapping when the file is missing, unreadable, or empty.
+ *
+ * @returns {Record<string, string>}
+ */
+function loadDirectoryNameByProfileId() {
+    const fallbackDirectoryNameByProfileId = {
+        main: 'main',
+        editor: 'editor',
+        mel: 'mel',
+        ev: 'ev',
+        master: 'master',
+        kimi: 'kimi',
+    };
+    const manifestPath = join(
+        PACKAGE_ROOT,
+        'scripts',
+        'profile-isolation-launchers',
+        'config',
+        'profiles.manifest.json',
+    );
+    if (!existsSync(manifestPath)) {
+        return fallbackDirectoryNameByProfileId;
+    }
+    try {
+        const document = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        /** @type {Record<string, string>} */
+        const directoryNameByProfileId = {};
+        const profiles = document && typeof document === 'object' ? document.profiles : null;
+        if (profiles && typeof profiles === 'object') {
+            for (const [eachProfileId, eachProfile] of Object.entries(profiles)) {
+                if (eachProfile && typeof eachProfile === 'object' && typeof eachProfile.directoryName === 'string') {
+                    directoryNameByProfileId[eachProfileId] = eachProfile.directoryName;
+                }
+            }
+        }
+        if (Object.keys(directoryNameByProfileId).length === 0) {
+            return fallbackDirectoryNameByProfileId;
+        }
+        return directoryNameByProfileId;
+    } catch {
+        return fallbackDirectoryNameByProfileId;
+    }
+}
+
+/**
+ * Run one install hop for a resolved target. Multi-target parents re-exec this
+ * module with --target and --target-identity so CLAUDE_HOME is correct at load.
+ *
+ * Abort-first: the first non-zero child status ends the loop.
+ *
+ * @param {import('./select-install-targets.mjs').ResolvedInstallTarget[]} allTargets
+ * @param {string[]} childArgv
+ * @returns {void}
+ */
+function runInstallForAllTargets(allTargets, childArgv) {
+    if (allTargets.length === 1) {
+        const onlyTarget = allTargets[0];
+        if (onlyTarget.managedRoot !== CLAUDE_HOME || onlyTarget.targetIdentity !== INSTALL_TARGET_IDENTITY) {
+            const childStatus = spawnInstallChild(onlyTarget, childArgv);
+            process.exit(childStatus);
+        }
+        return;
+    }
+    for (const eachTarget of allTargets) {
+        console.log(
+            `\n${PACKAGE_NAME}: target ${eachTarget.targetIdentity} → ${eachTarget.managedRoot}`,
+        );
+        const childStatus = spawnInstallChild(eachTarget, childArgv);
+        if (childStatus !== 0) {
+            console.error(
+                `ERROR: install failed for target ${eachTarget.targetIdentity} (exit ${childStatus})`,
+            );
+            process.exit(childStatus === null ? 1 : childStatus);
+        }
+    }
+    process.exit(0);
+}
+
+/**
+ * @param {import('./select-install-targets.mjs').ResolvedInstallTarget} target
+ * @param {string[]} childArgv
+ * @returns {number | null}
+ */
+function spawnInstallChild(target, childArgv) {
+    const result = spawnSync(
+        process.execPath,
+        [
+            fileURLToPath(import.meta.url),
+            '--target',
+            target.managedRoot,
+            TARGET_IDENTITY_FLAG,
+            target.targetIdentity,
+            ...childArgv,
+        ],
+        {
+            stdio: 'inherit',
+            env: process.env,
+        },
+    );
+    if (result.error) {
+        console.error(`ERROR: failed to spawn install child: ${result.error.message}`);
+        return 1;
+    }
+    return result.status === null ? 1 : result.status;
+}
+
 if (invokedAsEntryPoint(import.meta.url, process.argv[1])) {
     const rawArgs = process.argv.slice(2);
-    const args = rawArgs.filter((flag) => flag !== '--update');
-    const isUpdateRefresh = rawArgs.includes('--update');
-    if (args.includes('--help') || args.includes('-h')) {
+    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
         printHelp();
-    } else if (args.includes('--uninstall')) {
-        uninstall();
     } else {
-        const onlyIndex = args.indexOf('--only');
-        let selectedGroups = null;
-        if (onlyIndex !== -1) {
-            const onlyValue = args[onlyIndex + 1];
-            if (!onlyValue || onlyValue.startsWith('--')) {
-                console.error(`ERROR: --only requires a comma-separated list of groups.\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
-                process.exit(1);
+        let targetSelection;
+        try {
+            targetSelection = parseInstallTargetSelectionFromArgv(rawArgs);
+        } catch (selectionError) {
+            const message = selectionError instanceof Error
+                ? selectionError.message
+                : String(selectionError);
+            console.error(`ERROR: ${message}`);
+            process.exit(1);
+        }
+
+        const homeDirectory = homedir();
+        let allTargets;
+        try {
+            allTargets = resolveInstallTargets(targetSelection, {
+                homeDirectory,
+                environment: process.env,
+                profilesRoot: resolveProfilesRootDirectory({
+                    homeDirectory,
+                    environment: process.env,
+                }),
+                directoryNameByProfileId: loadDirectoryNameByProfileId(),
+            });
+        } catch (resolveError) {
+            const message = resolveError instanceof Error
+                ? resolveError.message
+                : String(resolveError);
+            console.error(`ERROR: ${message}`);
+            process.exit(1);
+        }
+
+        const childArgv = stripTargetSelectionFlagsFromArgv(rawArgs);
+        const args = childArgv.filter((flag) => flag !== '--update');
+        const isUpdateRefresh = childArgv.includes('--update');
+
+        const needsChildHop = allTargets.length > 1
+            || allTargets[0].managedRoot !== CLAUDE_HOME
+            || (
+                targetSelection.mode === 'profiles'
+                && allTargets[0].targetIdentity !== INSTALL_TARGET_IDENTITY
+            );
+
+        if (needsChildHop && !args.includes('--uninstall')) {
+            runInstallForAllTargets(allTargets, childArgv);
+        } else if (args.includes('--uninstall')) {
+            if (needsChildHop) {
+                runInstallForAllTargets(allTargets, childArgv);
+            } else {
+                uninstall();
             }
-            selectedGroups = onlyValue.split(',').map(name => name.trim());
-            const invalidGroups = selectedGroups.filter(name => !INSTALL_GROUPS[name]);
-            if (invalidGroups.length > 0) {
-                console.error(`ERROR: Unknown group(s): ${invalidGroups.join(', ')}\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
-                process.exit(1);
+        } else {
+            const onlyIndex = args.indexOf('--only');
+            let selectedGroups = null;
+            if (onlyIndex !== -1) {
+                const onlyValue = args[onlyIndex + 1];
+                if (!onlyValue || onlyValue.startsWith('--')) {
+                    console.error(`ERROR: --only requires a comma-separated list of groups.\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+                    process.exit(1);
+                }
+                selectedGroups = onlyValue.split(',').map(name => name.trim());
+                const invalidGroups = selectedGroups.filter(name => !INSTALL_GROUPS[name]);
+                if (invalidGroups.length > 0) {
+                    console.error(`ERROR: Unknown group(s): ${invalidGroups.join(', ')}\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+                    process.exit(1);
+                }
             }
+            install(selectedGroups, { isUpdateRefresh });
         }
-        install(selectedGroups, { isUpdateRefresh });
     }
 }