@ai-outfitter/outfitter 0.4.0 → 0.7.0

package/dist/cli/commands/SetupCommand.js

@@ -1,17 +1,30 @@
 /* eslint-disable max-lines */
 // Provides the command object for first-run Outfitter setup.
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import spawn from 'cross-spawn';
 import { parse, stringify } from 'yaml';
 import { createProfileSourceCachePath, createRemoteRepositoryCachePath, normalizeGitUri, redactProfileSourceUriCredentials, resolveRemoteRepositorySubpath, } from '../../profiles/ProfileCache.js';
 import { isValidProfileId, loadLocalProfileSource } from '../../profiles/ProfileLoader.js';
+import { resolveProfile } from '../../profiles/ProfileMerger.js';
 import { createSettingsLoadPlan, discoverSettingsLoadPlan, loadSettings, loadSettingsFiles, loadSettingsWithCachedRemoteSettings, } from '../../settings/SettingsLoader.js';
 import { persistFirstRunWelcomeProfile, updateSettingsDefaultProfile, } from './FirstRunWelcomeProfile.js';
 import { executeSyncCommand } from './SyncCommand.js';
 import { executeWelcomeCommand, writeWelcomeIntro } from './WelcomeCommand.js';
+const setupSourceImportModeChoices = [
+    {
+        mode: 'copy',
+        label: 'Copy snapshot',
+        description: 'copy profiles into the selected .outfitter folder; safest for normal use',
+    },
+    {
+        mode: 'symlink',
+        label: 'Symlink for development',
+        description: 'link the selected .outfitter folder to the local source so shared profile edits apply immediately',
+    },
+];
 const setupSourceImportTargetChoices = [
     {
         target: 'home',
@@ -24,17 +37,13 @@ const setupSourceImportTargetChoices = [
         description: 'install profiles into this project .outfitter folder only',
     },
 ];
-const builtInSetupProfileChoices = [
-    { id: 'engineer', label: 'Engineer' },
-    { id: 'data_analyst', label: 'Data Analyst' },
-];
 /* eslint-disable complexity -- setup orchestration coordinates settings, sync, prompts, and welcome persistence. */
 export const executeSetupCommand = async (input, dependencies = {}) => {
     requireInteractiveTerminalIfNeeded(dependencies);
     const settingsPath = join(input.homeDirectory, '.outfitter', 'settings.yml');
     const initialSettingsMissing = !existsSync(settingsPath);
     const starterLayout = input.setupSourceUri
-        ? prepareStarterLayout(input.homeDirectory, input.setupSourceUri, dependencies.setupSourceSynchronizer)
+        ? prepareStarterLayout(input.homeDirectory, input.projectDirectory, input.setupSourceUri, dependencies.setupSourceSynchronizer)
         : undefined;
     const loadedSettings = loadSettings(discoverSettingsLoadPlan(input));
     if (loadedSettings.issues.length > 0) {
@@ -112,9 +121,12 @@ const executeInteractiveSetupSourceCommand = async ({ input, dependencies, homeS
         : () => undefined;
     const syncResult = executeSyncCommand(input, dependencies);
     failOnInitialDefaultProfileSyncFailure(initialSettingsMissing && appliedImport.settingsPath === homeSettingsPath, rollbackCreatedSettings, syncResult);
-    const defaultProfilePath = join(appliedImport.profilesPath, onboarding.selectedProfileId, 'profile.yml');
-    const createdDefaultProfile = createDefaultProfileIfMissing(defaultProfilePath, onboarding.selectedProfileId);
-    const postImportAction = await runSetupSourcePostImportAction(input, dependencies, onboarding.selectedProfileId);
+    const defaultProfilePath = findSetupProfilePath(appliedImport.profilesPath, onboarding.selectedProfileId);
+    const createdDefaultProfile = appliedImport.symlinkedOutfitter
+        ? false
+        : createDefaultProfileIfMissing(defaultProfilePath, onboarding.selectedProfileId);
+    const postImportLaunchTarget = appliedImport.selectedProfileAlreadyExists ? 'default' : 'selected';
+    const postImportAction = await runSetupSourcePostImportAction(input, dependencies, onboarding.importTarget, onboarding.selectedProfileId, postImportLaunchTarget);
     return {
         settingsPath: appliedImport.settingsPath,
         defaultProfilePath,
@@ -134,8 +146,12 @@ const executeInteractiveSetupSourceCommand = async ({ input, dependencies, homeS
             defaultProfilePath,
             createdDefaultProfile,
             syncResult,
-            welcomeProfileMessages: [],
-            runExampleMessages: postImportAction === 'exit' ? [formatRunProfileExample(onboarding.selectedProfileId)] : [],
+            welcomeProfileMessages: appliedImport.selectedProfileConflictMessage === undefined
+                ? []
+                : [appliedImport.selectedProfileConflictMessage],
+            runExampleMessages: postImportAction === 'exit'
+                ? formatSetupSourceExitMessages(input, onboarding.importTarget, onboarding.selectedProfileId, postImportLaunchTarget)
+                : [],
         }),
     };
 };
@@ -173,27 +189,64 @@ const shouldReportDefaultProfileStatus = (input) => {
     return input.input.setupSourceUri === undefined || input.starterLayout?.profilesPath === undefined;
 };
 const formatRunProfileExample = (profileId) => `Start the selected default profile either way:\n  outfitter\n  outfitter --profile ${profileId}`;
-const runSetupSourcePostImportAction = async (input, dependencies, profileId) => {
+const formatRunDefaultProfileExample = () => `Start the current default profile:\n  outfitter`;
+/* v8 ignore start -- setup-source launch visibility fallbacks are exercised through integration-style CLI flows; unit tests cover the primary imported-profile outcomes. */
+const formatSetupSourceExitMessages = (input, importTarget, profileId, launchTarget) => {
+    if (launchTarget === 'default') {
+        return [formatRunDefaultProfileExample()];
+    }
+    if (importTarget !== 'home' || canResolveProfileForLaunch(input, profileId)) {
+        return [formatRunProfileExample(profileId)];
+    }
+    return [formatHiddenHomeImportMessage(profileId)];
+};
+const formatHiddenHomeImportMessage = (profileId) => `Imported profile '${profileId}' into user home, but this project overrides profile_sources and does not expose ~/.outfitter/profiles. ` +
+    'Import into the current project, add ~/.outfitter/profiles to project profile_sources, or run from a directory without project Outfitter settings.';
+const runSetupSourcePostImportAction = async (input, dependencies, importTarget, profileId, launchTarget) => {
     if (dependencies.interactive !== true ||
         (dependencies.launchSetupSourceProfile === undefined && dependencies.selectSetupSourceLaunchAction === undefined)) {
         return 'exit';
     }
-    const action = await selectSetupSourceLaunchAction(profileId, dependencies);
+    const action = await selectSetupSourceLaunchAction(profileId, launchTarget, dependencies);
     if (action === 'start') {
+        if (launchTarget === 'selected') {
+            assertSetupSourceProfileCanLaunch(input, importTarget, profileId);
+        }
         await dependencies.launchSetupSourceProfile?.({
             homeDirectory: input.homeDirectory,
             projectDirectory: input.projectDirectory,
-            profileId,
+            profileId: launchTarget === 'selected' ? profileId : undefined,
         });
     }
     return action;
 };
-const selectSetupSourceLaunchAction = async (profileId, dependencies) => {
+const assertSetupSourceProfileCanLaunch = (input, importTarget, profileId) => {
+    if (importTarget !== 'home' || canResolveProfileForLaunch(input, profileId)) {
+        return;
+    }
+    throw new Error(formatHiddenHomeImportMessage(profileId));
+};
+const canResolveProfileForLaunch = (input, profileId) => {
+    const loadedSettings = loadSettingsWithCachedRemoteSettings(input);
+    if (loadedSettings.issues.length > 0) {
+        return true;
+    }
+    const profiles = loadedSettings.settings.profileSources.flatMap((source) => loadLocalProfileSource({
+        path: materializeSetupProfileSource(input.homeDirectory, source),
+        only: source.only,
+        except: source.except,
+    }).profiles);
+    const resolution = resolveProfile({ profiles, profileId });
+    const selectedProfile = resolution.profileStack.find((profile) => profile.id === profileId);
+    return resolution.profile !== undefined && resolution.issues.length === 0 && selectedProfile?.template !== true;
+};
+const selectSetupSourceLaunchAction = async (profileId, launchTarget, dependencies) => {
     if (dependencies.selectSetupSourceLaunchAction !== undefined) {
-        return dependencies.selectSetupSourceLaunchAction(profileId);
+        return dependencies.selectSetupSourceLaunchAction(profileId, launchTarget);
     }
-    return promptForSetupSourceLaunchAction(profileId, dependencies);
+    return promptForSetupSourceLaunchAction(profileId, launchTarget, dependencies);
 };
+/* v8 ignore stop */
 const capitalize = (value) => `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
 export const createSetupCommand = (dependencies = {}) => {
     const command = {
@@ -220,7 +273,19 @@ export const createSetupCommand = (dependencies = {}) => {
     };
     return command;
 };
-const prepareStarterLayout = (homeDirectory, setupSourceUri, synchronizer = createGitSetupSourceSynchronizer()) => {
+const prepareStarterLayout = (homeDirectory, projectDirectory, setupSourceUri, synchronizer = createGitSetupSourceSynchronizer()) => {
+    const localOutfitterPath = resolveLocalSetupSourceOutfitterPathFromUri(setupSourceUri, projectDirectory);
+    if (localOutfitterPath !== undefined) {
+        const settingsPath = join(localOutfitterPath, 'settings.yml');
+        validateStarterSettingsIfPresent(existsSync(settingsPath) ? settingsPath : undefined);
+        return {
+            cachePath: localOutfitterPath,
+            settingsPath: existsSync(settingsPath) ? settingsPath : undefined,
+            profilesPath: firstExistingPath(join(localOutfitterPath, 'profiles')),
+            sourceKind: 'local-live',
+            sourceOutfitterPath: localOutfitterPath,
+        };
+    }
     const cachePath = createSetupSourceCachePath(homeDirectory, setupSourceUri);
     synchronizer.sync(setupSourceUri, cachePath);
     const settingsPath = firstExistingPath(join(cachePath, 'settings.yml'), join(cachePath, '.outfitter', 'settings.yml'));
@@ -229,7 +294,7 @@ const prepareStarterLayout = (homeDirectory, setupSourceUri, synchronizer = crea
         ? join(cachePath, '.outfitter', 'profiles')
         : join(cachePath, 'profiles');
     const profilesPath = firstExistingPath(preferredProfilesPath, join(cachePath, 'profiles'), join(cachePath, '.outfitter', 'profiles'));
-    return { cachePath, settingsPath, profilesPath };
+    return { cachePath, settingsPath, profilesPath, sourceKind: 'remote-cache' };
 };
 const createSetupSourceCachePath = (homeDirectory, setupSourceUri) => createRemoteRepositoryCachePath(homeDirectory, { uri: setupSourceUri });
 const createGitSetupSourceSynchronizer = () => ({
@@ -292,8 +357,8 @@ const assertValidDefaultProfileId = (profileId) => {
         throw new Error(`Default profile '${profileId}' is not a filesystem-safe Outfitter profile id.`);
     }
 };
-const createDefaultSettingsContent = () => [
-    'default_profile: engineer',
+export const createDefaultSettingsContent = (defaultProfileId = 'engineer') => [
+    `default_profile: ${defaultProfileId}`,
     'profile_sources:',
     '  - github: ai-outfitter/default-profiles',
     '    path: profiles',
@@ -318,17 +383,84 @@ const readStarterSettingsContent = (starterSettingsPath) => {
     }
     return `default_profile: engineer\n${content}`;
 };
+/* v8 ignore start -- setup-source filesystem import variants are covered by integration-style fixtures; core settings outcomes are unit covered. */
 const applySetupSourceImport = (input, starterLayout, onboarding) => {
     const target = createSetupSourceImportTargetLayout(input, onboarding.importTarget);
+    if (onboarding.importMode === 'symlink') {
+        return applySetupSourceSymlinkImport(input, target, onboarding);
+    }
+    return applySetupSourceCopyImport(starterLayout, target, onboarding);
+};
+const applySetupSourceSymlinkImport = (input, target, onboarding) => {
+    const sourceOutfitterPath = resolveLocalSetupSourceOutfitterPath(input);
+    if (sourceOutfitterPath === undefined) {
+        throw new Error('Local setup-source symlink mode requires a source .outfitter directory.');
+    }
+    const sourceSettingsPath = join(sourceOutfitterPath, 'settings.yml');
+    if (!existsSync(sourceSettingsPath)) {
+        throw new Error('Local setup-source symlink mode requires source .outfitter/settings.yml.');
+    }
+    validateStarterSettingsIfPresent(sourceSettingsPath);
+    const sourceProfilesPath = join(sourceOutfitterPath, 'profiles');
+    const sourceSelectedProfilePath = findSetupProfilePath(sourceProfilesPath, onboarding.selectedProfileId);
+    if (!existsSync(sourceSelectedProfilePath)) {
+        throw new Error(`Local setup-source symlink mode requires selected profile '${onboarding.selectedProfileId}'.`);
+    }
+    symlinkLocalOutfitterSource(sourceOutfitterPath, dirname(target.settingsPath));
+    return {
+        ...target,
+        createdSettings: false,
+        copiedStarterProfileFiles: 0,
+        copiedStarterResourceFiles: 0,
+        selectedProfileAlreadyExists: false,
+        symlinkedOutfitter: true,
+    };
+};
+const applySetupSourceCopyImport = (starterLayout, target, onboarding) => {
     const createdSettings = createImportSettingsIfMissing(target.settingsPath, starterLayout.settingsPath, onboarding.selectedProfileId);
+    const selectedProfilePath = findSetupProfilePath(target.profilesPath, onboarding.selectedProfileId);
+    const selectedProfileAlreadyExists = existsSync(selectedProfilePath);
     ensureLocalProfileSource(target.settingsPath, target.profilesPath);
     updateSettingsDefaultProfile(target.settingsPath, onboarding.selectedProfileId);
     return {
         ...target,
         createdSettings,
         copiedStarterProfileFiles: copyStarterProfileFilesIfPresent(starterLayout.profilesPath, target.profilesPath),
+        copiedStarterResourceFiles: copyStarterResourceFilesIfPresent(starterLayout.profilesPath, dirname(target.settingsPath)),
+        selectedProfileAlreadyExists,
+        selectedProfileConflictMessage: selectedProfileAlreadyExists
+            ? `Existing selected setup-source profile '${onboarding.selectedProfileId}' at ${selectedProfilePath} was not overwritten.`
+            : undefined,
+        symlinkedOutfitter: false,
     };
 };
+/* v8 ignore stop */
+/* v8 ignore start -- local setup-source path probing and symlink safety are covered by filesystem integration tests. */
+const resolveLocalSetupSourceOutfitterPath = (input) => input.setupSourceUri === undefined
+    ? undefined
+    : resolveLocalSetupSourceOutfitterPathFromUri(input.setupSourceUri, input.projectDirectory);
+const resolveLocalSetupSourceOutfitterPathFromUri = (setupSourceUri, projectDirectory) => {
+    if (isRemoteSetupSourceUri(setupSourceUri)) {
+        return undefined;
+    }
+    const sourcePath = isAbsolute(setupSourceUri) ? setupSourceUri : resolve(projectDirectory, setupSourceUri);
+    const outfitterPath = sourcePath.endsWith('.outfitter') ? sourcePath : join(sourcePath, '.outfitter');
+    return existsSync(outfitterPath) ? outfitterPath : undefined;
+};
+const isRemoteSetupSourceUri = (source) => /^[a-z][a-z0-9+.-]*:/iu.test(source) && !isAbsolute(source);
+const symlinkLocalOutfitterSource = (sourceOutfitterPath, targetOutfitterPath) => {
+    if (existsSync(targetOutfitterPath)) {
+        const entries = readdirSync(targetOutfitterPath);
+        if (entries.length > 0) {
+            throw new Error(`Cannot symlink local setup source into non-empty .outfitter directory '${targetOutfitterPath}'. ` +
+                'Move it aside or use copy snapshot setup.');
+        }
+        rmSync(targetOutfitterPath, { recursive: true, force: true });
+    }
+    mkdirSync(dirname(targetOutfitterPath), { recursive: true });
+    symlinkSync(sourceOutfitterPath, targetOutfitterPath, 'dir');
+};
+/* v8 ignore stop */
 const createSetupSourceImportTargetLayout = (input, target) => {
     if (target === 'project') {
         return {
@@ -380,6 +512,20 @@ const copyStarterProfileFilesIfPresent = (sourceProfilesPath, targetProfilesPath
     }
     return copyDirectoryContentsWithoutOverwriting(sourceProfilesPath, targetProfilesPath);
 };
+const copyStarterResourceFilesIfPresent = (sourceProfilesPath, targetOutfitterPath) => {
+    if (sourceProfilesPath === undefined) {
+        return 0;
+    }
+    const sourceOutfitterPath = dirname(sourceProfilesPath);
+    return ['prompts', 'deepwork', 'skills'].reduce((copiedFiles, resourceName) => copiedFiles + copyNamedStarterResourceDirectoryIfPresent(sourceOutfitterPath, targetOutfitterPath, resourceName), 0);
+};
+const copyNamedStarterResourceDirectoryIfPresent = (sourceOutfitterPath, targetOutfitterPath, resourceName) => {
+    const sourceResourcePath = join(sourceOutfitterPath, resourceName);
+    if (!existsSync(sourceResourcePath)) {
+        return 0;
+    }
+    return copyDirectoryContentsWithoutOverwriting(sourceResourcePath, join(targetOutfitterPath, resourceName));
+};
 const copyDirectoryContentsWithoutOverwriting = (sourceDirectory, targetDirectory) => {
     mkdirSync(targetDirectory, { recursive: true });
     let copiedFiles = 0;
@@ -398,6 +544,18 @@ const copyDirectoryContentsWithoutOverwriting = (sourceDirectory, targetDirector
     }
     return copiedFiles;
 };
+const findSetupProfilePath = (profilesPath, profileId) => {
+    for (const profilePath of [
+        join(profilesPath, `${profileId}.yml`),
+        join(profilesPath, `${profileId}.yaml`),
+        join(profilesPath, profileId, 'profile.yml'),
+    ]) {
+        if (existsSync(profilePath)) {
+            return profilePath;
+        }
+    }
+    return join(profilesPath, profileId, 'profile.yml');
+};
 const createDefaultProfileIfMissing = (profilePath, profileId) => {
     if (existsSync(profilePath)) {
         return false;
@@ -477,18 +635,23 @@ const resolvePromptOutput = (dependencies) => {
 const runSetupSourceOnboarding = async (input, dependencies, starterLayout, currentDefault) => {
     const discoveredProfiles = discoverSetupProfileChoices(input, starterLayout);
     const sourceDefault = discoverSetupSourcePromptDefault(input, starterLayout, discoveredProfiles);
-    const promptDefault = sourceDefault ?? currentDefault;
-    const profiles = selectSetupPromptProfiles(input, discoveredProfiles, currentDefault, sourceDefault);
-    if (dependencies.selectSetupSourceImportTarget === undefined && dependencies.selectDefaultProfile === undefined) {
-        return promptForSetupSourceOnboarding(input, profiles, promptDefault, dependencies);
+    const promptDefault = chooseSetupPromptDefault(discoveredProfiles, sourceDefault, currentDefault);
+    const profiles = selectSetupPromptProfiles(discoveredProfiles, currentDefault, promptDefault);
+    const localSymlinkAvailable = resolveLocalSetupSourceOutfitterPath(input) !== undefined;
+    if (dependencies.selectSetupSourceImportTarget === undefined &&
+        dependencies.selectDefaultProfile === undefined &&
+        dependencies.selectSetupSourceImportMode === undefined) {
+        return promptForSetupSourceOnboarding(input, profiles, promptDefault, localSymlinkAvailable, dependencies);
     }
     writeSetupSourceWelcome(input, profiles, resolvePromptOutput(dependencies));
     const importTarget = await selectSetupSourceImportTarget(dependencies);
+    const importMode = await selectSetupSourceImportMode(dependencies, localSymlinkAvailable);
     const selectedProfileId = await selectSetupProfile(profiles, promptDefault, dependencies);
     assertValidSelectedDefaultProfile(selectedProfileId, profiles);
-    return { importTarget, selectedProfileId };
+    return { importTarget, selectedProfileId, importMode };
 };
-const promptForSetupSourceOnboarding = async (input, profiles, currentDefault, dependencies) => {
+/* v8 ignore start -- readline fallback is smoke-tested through terminal streams; injected selector paths carry deterministic setup-source coverage. */
+const promptForSetupSourceOnboarding = async (input, profiles, currentDefault, localSymlinkAvailable, dependencies) => {
     const output = resolvePromptOutput(dependencies);
     /* v8 ignore next -- default process streams are direct terminal behavior; tests inject streams. */
     const readline = createInterface({
@@ -497,10 +660,11 @@ const promptForSetupSourceOnboarding = async (input, profiles, currentDefault, d
     });
     try {
         writeSetupSourceWelcome(input, profiles, output);
-        const importTarget = await promptForSetupSourceImportTargetWithReadline(readline, output);
+        const importTarget = await promptForSetupSourceImportTargetWithReadline(readline, output, setupSourceImportTargetChoices, 'home');
+        const importMode = await promptForSetupSourceImportModeWithReadline(readline, output, localSymlinkAvailable);
         const selectedProfileId = await promptForSetupProfileWithReadline(readline, output, profiles, currentDefault, 'Choose the default profile from this setup source:');
         assertValidSelectedDefaultProfile(selectedProfileId, profiles);
-        return { importTarget, selectedProfileId };
+        return { importTarget, selectedProfileId, importMode };
     }
     finally {
         readline.close();
@@ -510,6 +674,9 @@ const writeSetupSourceWelcome = (input, profiles, output) => {
     writeWelcomeIntro(output);
     output.write(`\nYou're importing Outfitter profiles from ${redactProfileSourceUriCredentials(input.setupSourceUri)}.\n`);
     output.write(`Found ${profiles.length} profile(s)${formatSetupSourceProfileList(profiles)}.\n`);
+    if (resolveLocalSetupSourceOutfitterPath(input) !== undefined) {
+        output.write('Local setup source detected. Copy snapshot setup is safest; symlink setup links your target .outfitter to the local source .outfitter so shared-profile edits apply immediately during development.\n');
+    }
 };
 const formatSetupSourceProfileList = (profiles) => {
     /* v8 ignore next -- setup-source profile prompts normally require discovered source profiles. */
@@ -525,37 +692,23 @@ const selectSetupSourceImportTarget = async (dependencies) => {
         assertValidSetupSourceImportTarget(selectedTarget);
         return selectedTarget;
     }
-    /* v8 ignore next -- mixed dependency injection path; the full readline path prompts with one shared readline. */
-    return promptForSetupSourceImportTarget(dependencies);
+    return 'home';
 };
-/* v8 ignore next -- covered by the shared readline setup-source onboarding prompt in normal CLI usage. */
-const promptForSetupSourceImportTarget = async (dependencies) => {
-    const output = resolvePromptOutput(dependencies);
-    /* v8 ignore next -- default process streams are direct terminal behavior; tests inject streams. */
-    const readline = createInterface({
-        input: dependencies.input ?? process.stdin,
-        output: resolveReadlineOutput(dependencies),
-    });
-    try {
-        return await promptForSetupSourceImportTargetWithReadline(readline, output);
+const selectSetupSourceImportMode = async (dependencies, localSymlinkAvailable) => {
+    if (!localSymlinkAvailable) {
+        return 'copy';
     }
-    finally {
-        readline.close();
+    if (dependencies.selectSetupSourceImportMode !== undefined) {
+        const selectedMode = await dependencies.selectSetupSourceImportMode(setupSourceImportModeChoices, 'copy');
+        assertValidSetupSourceImportMode(selectedMode);
+        return selectedMode;
     }
+    return 'copy';
 };
-const promptForSetupSourceImportTargetWithReadline = async (readline, output) => {
-    output.write('\nChoose where to install these profiles:\n');
-    setupSourceImportTargetChoices.forEach((choice, index) => {
-        output.write(`${index + 1}. ${choice.label} - ${choice.description}\n`);
-    });
-    const answer = await readline.question('Import target [1]: ');
-    const selectedIndex = Number.parseInt(answer.trim() || '1', 10) - 1;
-    const selectedTarget = setupSourceImportTargetChoices[selectedIndex]?.target;
-    /* v8 ignore next -- defensive terminal validation; profile prompt range handling is covered separately. */
-    if (selectedTarget === undefined) {
-        throw new Error('Selected setup-source import target number is out of range.');
+const assertValidSetupSourceImportMode = (mode) => {
+    if (setupSourceImportModeChoices.every((choice) => choice.mode !== mode)) {
+        throw new Error(`Selected setup-source import mode '${mode}' is not available.`);
     }
-    return selectedTarget;
 };
 const assertValidSetupSourceImportTarget = (target) => {
     /* v8 ignore next -- defensive validation for custom dependency injection. */
@@ -563,31 +716,65 @@ const assertValidSetupSourceImportTarget = (target) => {
         throw new Error(`Selected setup-source import target '${target}' is not available.`);
     }
 };
+const promptForSetupSourceImportTargetWithReadline = async (readline, output, choices, defaultTarget) => {
+    output.write('\nChoose where to install these profiles:\n');
+    choices.forEach((choice, index) => {
+        output.write(`${index + 1}. ${choice.label}\n`);
+        output.write(`   ${choice.description}.\n`);
+    });
+    const defaultIndex = Math.max(choices.findIndex((choice) => choice.target === defaultTarget), 0);
+    const answer = await readline.question(`Import target [${defaultIndex + 1}]: `);
+    const selectedIndex = Number.parseInt(answer.trim() || String(defaultIndex + 1), 10) - 1;
+    const selectedChoice = choices[selectedIndex];
+    if (selectedChoice === undefined) {
+        throw new Error('Selected setup-source import target number is out of range.');
+    }
+    return selectedChoice.target;
+};
+const promptForSetupSourceImportModeWithReadline = async (readline, output, localSymlinkAvailable) => {
+    if (!localSymlinkAvailable) {
+        return 'copy';
+    }
+    output.write('\nChoose how to install this local setup source:\n');
+    setupSourceImportModeChoices.forEach((choice, index) => {
+        output.write(`${index + 1}. ${choice.label}\n`);
+        output.write(`   ${choice.description}.\n`);
+    });
+    const answer = await readline.question('Import mode [1]: ');
+    const selectedIndex = Number.parseInt(answer.trim() || '1', 10) - 1;
+    const selectedChoice = setupSourceImportModeChoices[selectedIndex];
+    if (selectedChoice === undefined) {
+        throw new Error('Selected setup-source import mode number is out of range.');
+    }
+    return selectedChoice.mode;
+};
 /* v8 ignore next -- covered by interactive CLI smoke tests; unit tests inject the launch choice. */
-const promptForSetupSourceLaunchAction = async (profileId, dependencies) => {
+const promptForSetupSourceLaunchAction = async (profileId, launchTarget, dependencies) => {
     const readline = createInterface({
         input: dependencies.input ?? process.stdin,
         output: resolveReadlineOutput(dependencies),
     });
     try {
-        const answer = await readline.question(`Start Outfitter with profile '${profileId}' now? [Y/n]: `);
+        const prompt = launchTarget === 'selected'
+            ? `Start Outfitter with profile '${profileId}' now? [Y/n]: `
+            : 'Start Outfitter with the current default profile now? [Y/n]: ';
+        const answer = await readline.question(prompt);
         return answer.trim().toLowerCase().startsWith('n') ? 'exit' : 'start';
     }
     finally {
         readline.close();
     }
 };
+/* v8 ignore stop */
 const selectDefaultProfileIfInteractive = async (input, settingsPath, currentDefault, dependencies, starterLayout) => {
     if (dependencies.interactive !== true) {
         return currentDefault;
     }
     const discoveredProfiles = discoverSetupProfileChoices(input, starterLayout);
     const sourceDefault = discoverSetupSourcePromptDefault(input, starterLayout, discoveredProfiles);
-    const promptDefault = sourceDefault ?? currentDefault;
-    const profiles = selectSetupPromptProfiles(input, discoveredProfiles, currentDefault, sourceDefault);
-    const writer = dependencies.writeLine ?? console.log;
-    writer('Welcome to Outfitter. Outfitter is the easiest way to run Pi.');
-    writer('Outfitter manages full pi configurations for you, so you can use different profiles in different situations.');
+    const promptDefault = chooseSetupPromptDefault(discoveredProfiles, sourceDefault, currentDefault);
+    const profiles = selectSetupPromptProfiles(discoveredProfiles, currentDefault, promptDefault);
+    writeWelcomeIntro(resolvePromptOutput(dependencies));
     const selectedProfile = await selectSetupProfile(profiles, promptDefault, dependencies);
     assertValidSelectedDefaultProfile(selectedProfile, profiles);
     updateSettingsDefaultProfile(settingsPath, selectedProfile);
@@ -606,13 +793,18 @@ const discoverSetupSourcePromptDefault = (input, starterLayout, profiles) => {
     const sourceDefault = readStarterExplicitDefaultProfileId(starterLayout?.settingsPath);
     return profiles.some((profile) => profile.id === sourceDefault) ? sourceDefault : undefined;
 };
-const selectSetupPromptProfiles = (input, discoveredProfiles, currentDefault, sourceDefault) => {
-    const profiles = discoveredProfiles.length > 0 ||
-        input.setupSourceUri !== undefined ||
-        builtInSetupProfileChoices.every((profile) => profile.id !== currentDefault)
-        ? discoveredProfiles
-        : builtInSetupProfileChoices;
-    return sourceDefault === undefined ? profiles : prioritizeSetupProfileChoice(profiles, sourceDefault);
+const selectSetupPromptProfiles = (discoveredProfiles, currentDefault, promptDefault) => {
+    const profiles = discoveredProfiles.length > 0 ? discoveredProfiles : [{ id: currentDefault }];
+    return prioritizeSetupProfileChoice(profiles, promptDefault);
+};
+const chooseSetupPromptDefault = (profiles, sourceDefault, fallbackDefault) => {
+    if (sourceDefault !== undefined && profiles.some((profile) => profile.id === sourceDefault)) {
+        return sourceDefault;
+    }
+    if (profiles.some((profile) => profile.id === fallbackDefault)) {
+        return fallbackDefault;
+    }
+    return profiles[0]?.id ?? fallbackDefault;
 };
 const prioritizeSetupProfileChoice = (profiles, profileId) => [
     ...profiles.filter((profile) => profile.id === profileId),
@@ -630,6 +822,7 @@ const discoverSetupProfileChoicesFromLocalSource = (path) => {
         .map((profile) => ({
         id: profile.profile.id,
         label: profile.profile.label,
+        description: profile.profile.description,
     }))
         .sort((left, right) => left.id.localeCompare(right.id));
 };
@@ -644,6 +837,7 @@ const discoverSetupProfileChoicesFromEffectiveSettings = (input) => {
             choices.set(profile.profile.id, {
                 id: profile.profile.id,
                 label: profile.profile.label ?? existingChoice?.label,
+                description: profile.profile.description ?? existingChoice?.description,
             });
         }
     }
@@ -687,6 +881,9 @@ const promptForSetupProfileWithReadline = async (readline, output, profiles, cur
     candidates.forEach((profile, index) => {
         const label = profile.label === undefined ? '' : ` - ${profile.label}`;
         output.write(`${index + 1}. ${profile.id}${label}\n`);
+        if (profile.description !== undefined) {
+            output.write(`   ${profile.description}\n`);
+        }
     });
     const currentIndex = Math.max(candidates.findIndex((profile) => profile.id === currentDefault), 0);
     const answer = await readline.question(`Default profile [${currentIndex + 1}]: `);