opkg 0.5.0 → 0.6.0

package/dist/commands/install.js

@@ -1,688 +1,48 @@
-import * as semver from 'semver';
-import { ensureRegistryDirectories, listPackageVersions } from '../core/directory.js';
-import { displayDependencyTree } from '../core/dependency-resolver.js';
-import { exists } from '../utils/fs.js';
-import { logger } from '../utils/logger.js';
-import { withErrorHandling, UserCancellationError, PackageNotFoundError } from '../utils/errors.js';
-import { createPlatformDirectories } from '../core/platforms.js';
+import { DIR_PATTERNS, PACKAGE_PATHS } from '../constants/index.js';
+import { runBulkInstallPipeline } from '../core/install/bulk-install-pipeline.js';
+import { runInstallPipeline, determineResolutionMode } from '../core/install/install-pipeline.js';
+import { withErrorHandling } from '../utils/errors.js';
 import { normalizePlatforms } from '../utils/platform-mapper.js';
-import { resolvePlatforms } from '../core/install/platform-resolution.js';
-import { prepareInstallEnvironment, resolveDependenciesForInstall, processConflictResolution, performIndexBasedInstallationPhases, VersionResolutionAbortError } from '../core/install/install-flow.js';
-import { getLocalPackageYmlPath, getAIDir, isRootPackage } from '../utils/paths.js';
-import { createBasicPackageYml, addPackageToYml, writeLocalPackageFromRegistry } from '../utils/package-management.js';
-import { displayInstallationSummary, displayInstallationResults, } from '../utils/package-installation.js';
-import { planConflictsForPackage } from '../utils/index-based-installer.js';
-import { withOperationErrorHandling, } from '../utils/error-handling.js';
-import { extractPackagesFromConfig } from '../utils/install-helpers.js';
-import { parsePackageYml } from '../utils/package-yml.js';
-import { parsePackageInput, arePackageNamesEquivalent } from '../utils/package-name.js';
-import { safePrompts } from '../utils/prompts.js';
-import { createCaretRange, isExactVersion, parseVersionRange, resolveVersionRange } from '../utils/version-ranges.js';
-import { aggregateRecursiveDownloads } from '../core/remote-pull.js';
-import { computeMissingDownloadKeys } from '../core/install/download-keys.js';
-import { fetchMissingDependencyMetadata, pullMissingDependencies } from '../core/install/remote-flow.js';
-import { recordBatchOutcome } from '../core/install/remote-reporting.js';
-import { handleDryRunMode } from '../core/install/dry-run.js';
-import { extractRemoteErrorReason } from '../utils/error-reasons.js';
-import { selectInstallVersionUnified } from '../core/install/version-selection.js';
-export function determineResolutionMode(options) {
-    if (options.resolutionMode) {
-        return options.resolutionMode;
-    }
-    if (options.remote) {
-        return 'remote-primary';
+import { parsePackageInput } from '../utils/package-name.js';
+import { logger } from '../utils/logger.js';
+import { normalizePathForProcessing } from '../utils/path-normalization.js';
+function assertTargetDirOutsideMetadata(targetDir) {
+    const normalized = normalizePathForProcessing(targetDir ?? '.');
+    if (!normalized || normalized === '.') {
+        return; // default install root
     }
-    if (options.local) {
-        return 'local-only';
+    if (normalized === DIR_PATTERNS.OPENPACKAGE ||
+        normalized.startsWith(`${DIR_PATTERNS.OPENPACKAGE}/`)) {
+        throw new Error(`Installation target '${targetDir}' cannot point inside ${DIR_PATTERNS.OPENPACKAGE} (reserved for metadata like ${PACKAGE_PATHS.INDEX_RELATIVE}). Choose a workspace path outside metadata.`);
     }
-    return 'default';
 }
 export function validateResolutionFlags(options) {
     if (options.remote && options.local) {
         throw new Error('--remote and --local cannot be used together. Choose one resolution mode.');
     }
 }
-/**
- * Install all packages from CWD package.yml file
- * @param targetDir - Target directory for installation
- * @param options - Installation options including dev flag
- * @returns Command result with installation summary
- */
-async function installAllPackagesCommand(targetDir, options) {
-    const cwd = process.cwd();
-    logger.info(`Installing all packages from package.yml to: ${getAIDir(cwd)}`, { options });
-    await ensureRegistryDirectories();
-    // Auto-create basic package.yml if it doesn't exist
-    await createBasicPackageYml(cwd);
-    const packageYmlPath = getLocalPackageYmlPath(cwd);
-    const cwdConfig = await withOperationErrorHandling(() => parsePackageYml(packageYmlPath), 'parse package.yml', packageYmlPath);
-    const allPackagesToInstall = extractPackagesFromConfig(cwdConfig);
-    // Filter out any packages that match the root package name
-    const packagesToInstall = [];
-    const skippedRootPackages = [];
-    for (const pkg of allPackagesToInstall) {
-        if (await isRootPackage(cwd, pkg.name)) {
-            skippedRootPackages.push(pkg);
-            console.log(`⚠️  Skipping ${pkg.name} - it matches your project's root package name`);
-        }
-        else {
-            packagesToInstall.push(pkg);
-        }
-    }
-    if (packagesToInstall.length === 0) {
-        if (skippedRootPackages.length > 0) {
-            console.log('✓ All packages in package.yml were skipped (matched root package)');
-            console.log('\nTips:');
-            console.log('• Root packages cannot be installed as dependencies');
-            console.log('• Use "opkg install <package-name>" to install external packages');
-            console.log('• Use "opkg save" to create a WIP copy of your root package in the registry');
-        }
-        else {
-            console.log('⚠️ No packages found in package.yml');
-            console.log('\nTips:');
-            console.log('• Add packages to the "packages" array in package.yml');
-            console.log('• Add development packages to the "dev-packages" array in package.yml');
-            console.log('• Use "opkg install <package-name>" to install a specific package');
-        }
-        return { success: true, data: { installed: 0, skipped: skippedRootPackages.length } };
-    }
-    console.log(`✓ Installing ${packagesToInstall.length} packages from package.yml:`);
-    packagesToInstall.forEach(pkg => {
-        const prefix = pkg.isDev ? '[dev] ' : '';
-        const label = pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name;
-        console.log(`  • ${prefix}${label}`);
-    });
-    if (skippedRootPackages.length > 0) {
-        console.log(`  • ${skippedRootPackages.length} packages skipped (matched root package)`);
-    }
-    console.log('');
-    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-    const normalizedPlatforms = normalizePlatforms(options.platforms);
-    const resolvedPlatforms = await resolvePlatforms(cwd, normalizedPlatforms, { interactive });
-    // Install packages sequentially to avoid conflicts
-    let totalInstalled = 0;
-    let totalSkipped = 0;
-    const results = [];
-    const aggregateWarnings = new Set();
-    for (const pkg of packagesToInstall) {
-        try {
-            const label = pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name;
-            const baseConflictDecisions = options.conflictDecisions
-                ? { ...options.conflictDecisions }
-                : undefined;
-            const installOptions = {
-                ...options,
-                dev: pkg.isDev,
-                resolvedPlatforms,
-                conflictDecisions: baseConflictDecisions
-            };
-            let conflictPlanningVersion = pkg.version;
-            if (pkg.version && !isExactVersion(pkg.version)) {
-                try {
-                    const localVersions = await listPackageVersions(pkg.name);
-                    conflictPlanningVersion = resolveVersionRange(pkg.version, localVersions) ?? undefined;
-                }
-                catch {
-                    conflictPlanningVersion = undefined;
-                }
-            }
-            if (conflictPlanningVersion) {
-                try {
-                    const conflicts = await planConflictsForPackage(cwd, pkg.name, conflictPlanningVersion, resolvedPlatforms);
-                    if (conflicts.length > 0) {
-                        const shouldPrompt = interactive && (!installOptions.conflictStrategy || installOptions.conflictStrategy === 'ask');
-                        if (shouldPrompt) {
-                            console.log(`\n⚠️  Detected ${conflicts.length} potential file conflict${conflicts.length === 1 ? '' : 's'} for ${label}.`);
-                            const preview = conflicts.slice(0, 5);
-                            for (const conflict of preview) {
-                                const ownerInfo = conflict.ownerPackage ? `owned by ${conflict.ownerPackage}` : 'already exists locally';
-                                console.log(`  • ${conflict.relPath} (${ownerInfo})`);
-                            }
-                            if (conflicts.length > preview.length) {
-                                console.log(`  • ... and ${conflicts.length - preview.length} more`);
-                            }
-                            const selection = await safePrompts({
-                                type: 'select',
-                                name: 'strategy',
-                                message: `Choose conflict handling for ${label}:`,
-                                choices: [
-                                    { title: 'Keep both (rename existing files)', value: 'keep-both' },
-                                    { title: 'Overwrite existing files', value: 'overwrite' },
-                                    { title: 'Skip conflicting files', value: 'skip' },
-                                    { title: 'Review individually', value: 'ask' }
-                                ],
-                                initial: installOptions.conflictStrategy === 'ask' ? 3 : 0
-                            });
-                            const chosenStrategy = selection.strategy;
-                            installOptions.conflictStrategy = chosenStrategy;
-                            if (chosenStrategy === 'ask') {
-                                const decisions = {};
-                                for (const conflict of conflicts) {
-                                    const detail = await safePrompts({
-                                        type: 'select',
-                                        name: 'decision',
-                                        message: `${conflict.relPath}${conflict.ownerPackage ? ` (owned by ${conflict.ownerPackage})` : ''}:`,
-                                        choices: [
-                                            { title: 'Keep both (rename existing)', value: 'keep-both' },
-                                            { title: 'Overwrite existing', value: 'overwrite' },
-                                            { title: 'Skip (keep existing)', value: 'skip' }
-                                        ],
-                                        initial: 0
-                                    });
-                                    const decisionValue = detail.decision;
-                                    decisions[conflict.relPath] = decisionValue;
-                                }
-                                installOptions.conflictDecisions = decisions;
-                            }
-                        }
-                        else if (!interactive && (!installOptions.conflictStrategy || installOptions.conflictStrategy === 'ask')) {
-                            logger.warn(`Detected ${conflicts.length} potential conflict${conflicts.length === 1 ? '' : 's'} for ${label}, but running in non-interactive mode. Conflicting files will be skipped unless '--conflicts' is provided.`);
-                        }
-                    }
-                }
-                catch (planError) {
-                    logger.warn(`Failed to evaluate conflicts for ${label}: ${planError}`);
-                }
-            }
-            console.log(`\n🔧 Installing ${pkg.isDev ? '[dev] ' : ''}${label}...`);
-            const result = await installPackageCommand(pkg.name, targetDir, installOptions, pkg.version);
-            if (result.success) {
-                totalInstalled++;
-                results.push({ name: pkg.name, success: true });
-                console.log(`✓ Successfully installed ${pkg.name}`);
-                if (result.warnings && result.warnings.length > 0) {
-                    result.warnings.forEach(warning => aggregateWarnings.add(warning));
-                }
-            }
-            else {
-                totalSkipped++;
-                results.push({ name: pkg.name, success: false, error: result.error });
-                console.log(`❌ Failed to install ${pkg.name}: ${result.error}`);
-            }
-        }
-        catch (error) {
-            if (error instanceof UserCancellationError) {
-                throw error; // Re-throw to allow clean exit
-            }
-            totalSkipped++;
-            results.push({ name: pkg.name, success: false, error: String(error) });
-            console.log(`❌ Failed to install ${pkg.name}: ${error}`);
-        }
-    }
-    displayInstallationSummary(totalInstalled, totalSkipped, packagesToInstall.length, results);
-    if (aggregateWarnings.size > 0) {
-        console.log('\n⚠️  Warnings during installation:');
-        aggregateWarnings.forEach(warning => {
-            console.log(`  • ${warning}`);
-        });
-    }
-    const allSuccessful = totalSkipped === 0;
-    return {
-        success: allSuccessful,
-        data: {
-            installed: totalInstalled,
-            skipped: totalSkipped,
-            results
-        },
-        error: allSuccessful ? undefined : `${totalSkipped} packages failed to install`,
-        warnings: totalSkipped > 0 ? [`${totalSkipped} packages failed to install`] : undefined
-    };
-}
-/**
- * Install package command implementation with recursive dependency resolution
- * @param packageName - Name of the package to install
- * @param targetDir - Target directory for installation
- * @param options - Installation options including force, dry-run, and dev flags
- * @param version - Specific version to install (optional)
- * @returns Command result with detailed installation information
- */
-async function installPackageCommand(packageName, targetDir, options, version) {
-    const cwd = process.cwd();
-    const resolutionMode = options.resolutionMode ?? determineResolutionMode(options);
-    // 1) Validate root package and early return
-    if (await isRootPackage(cwd, packageName)) {
-        console.log(`⚠️  Cannot install ${packageName} - it matches your project's root package name`);
-        console.log(`   This would create a circular dependency.`);
-        console.log(`💡 Tip: Use 'opkg install' without specifying a package name to install all packages`);
-        console.log(`   referenced in your .openpackage/package.yml file.`);
-        return {
-            success: true,
-            data: { skipped: true, reason: 'root package' }
-        };
-    }
-    logger.debug(`Installing package '${packageName}' with dependencies to: ${getAIDir(cwd)}`, { options });
-    const dryRun = !!options.dryRun;
-    const forceRemote = resolutionMode === 'remote-primary';
-    const warnings = [];
-    const warnedPackages = new Set();
-    const canonicalPlan = await determineCanonicalInstallPlan({
-        cwd,
-        packageName,
-        cliSpec: version,
-        devFlag: options.dev ?? false
-    });
-    if (canonicalPlan.compatibilityMessage) {
-        console.log(`ℹ️  ${canonicalPlan.compatibilityMessage}`);
-    }
-    let versionConstraint = canonicalPlan.effectiveRange;
-    const selectionOptions = options.stable ? { preferStable: true } : undefined;
-    const preselection = await selectInstallVersionUnified({
-        packageName,
-        constraint: versionConstraint,
-        mode: resolutionMode,
-        selectionOptions,
-        profile: options.profile,
-        apiKey: options.apiKey
-    });
-    if (preselection.sources.warnings.length > 0) {
-        preselection.sources.warnings.forEach(message => {
-            warnings.push(message);
-            console.log(`⚠️  ${message}`);
-        });
-    }
-    const selectedRootVersion = preselection.selectedVersion;
-    if (!selectedRootVersion) {
-        const constraintLabel = canonicalPlan.dependencyState === 'existing' && canonicalPlan.canonicalRange
-            ? canonicalPlan.canonicalRange
-            : versionConstraint;
-        throw buildNoVersionFoundError(packageName, constraintLabel, preselection.selection, resolutionMode);
-    }
-    const source = preselection.resolutionSource ?? 'local';
-    console.log(formatSelectionSummary(source, packageName, selectedRootVersion));
-    // 2) Prepare env via prepareInstallEnvironment
-    const { specifiedPlatforms } = await prepareInstallEnvironment(cwd, options);
-    let resolvedPackages = [];
-    let missingPackages = [];
-    const resolveDependenciesOutcome = async () => {
-        try {
-            const data = await resolveDependenciesForInstall(packageName, cwd, versionConstraint, options);
-            if (data.warnings && data.warnings.length > 0) {
-                data.warnings.forEach(message => {
-                    warnings.push(message);
-                    // Surface resolver warnings (including circular dependency notices)
-                    // directly to the user for better visibility.
-                    console.log(`⚠️  ${message}`);
-                    const match = message.match(/Remote pull failed for `([^`]+)`/);
-                    if (match) {
-                        warnedPackages.add(match[1]);
-                    }
-                });
-            }
-            return { success: true, data };
-        }
-        catch (error) {
-            if (error instanceof VersionResolutionAbortError) {
-                return { success: false, commandResult: { success: false, error: error.message } };
-            }
-            if (error instanceof PackageNotFoundError ||
-                (error instanceof Error && (error.message.includes('not available in local registry') ||
-                    (error.message.includes('Package') && error.message.includes('not found'))))) {
-                console.log('❌ Package not found');
-                return { success: false, commandResult: { success: false, error: 'Package not found' } };
-            }
-            throw error;
-        }
-    };
-    // 3) Resolve dependencies
-    const initialResolution = await resolveDependenciesOutcome();
-    if (!initialResolution.success) {
-        return initialResolution.commandResult;
-    }
-    resolvedPackages = initialResolution.data.resolvedPackages;
-    missingPackages = initialResolution.data.missingPackages;
-    const remoteOutcomes = {
-        ...(initialResolution.data.remoteOutcomes ?? {})
-    };
-    const computeRetryEligibleMissing = (names) => {
-        return names.filter(name => {
-            const outcome = remoteOutcomes[name];
-            if (!outcome) {
-                return true;
-            }
-            return outcome.reason !== 'not-found' && outcome.reason !== 'access-denied';
-        });
-    };
-    let retryEligibleMissing = computeRetryEligibleMissing(missingPackages);
-    // Track packages that were already warned about during resolution
-    // to avoid duplicate warnings when fetching metadata
-    const pullMissingFromRemote = async () => {
-        if (retryEligibleMissing.length === 0) {
-            return null;
-        }
-        const metadataResults = await fetchMissingDependencyMetadata(retryEligibleMissing, resolvedPackages, {
-            dryRun,
-            profile: options.profile,
-            apiKey: options.apiKey,
-            alreadyWarnedPackages: warnedPackages,
-            onFailure: (name, failure) => {
-                remoteOutcomes[name] = {
-                    name,
-                    reason: failure.reason,
-                    message: failure.message
-                };
-            }
-        });
-        if (metadataResults.length === 0) {
-            return null;
-        }
-        const keysToDownload = new Set();
-        for (const metadata of metadataResults) {
-            const aggregated = aggregateRecursiveDownloads([metadata.response]);
-            const missingKeys = await computeMissingDownloadKeys(aggregated);
-            missingKeys.forEach((key) => keysToDownload.add(key));
-        }
-        const batchResults = await pullMissingDependencies(metadataResults, keysToDownload, {
-            dryRun,
-            profile: options.profile,
-            apiKey: options.apiKey
-        });
-        for (const batchResult of batchResults) {
-            recordBatchOutcome('Pulled dependencies', batchResult, warnings, dryRun);
-            updateRemoteOutcomesFromBatch(batchResult, remoteOutcomes);
-        }
-        const refreshedResolution = await resolveDependenciesOutcome();
-        if (!refreshedResolution.success) {
-            return refreshedResolution.commandResult;
-        }
-        resolvedPackages = refreshedResolution.data.resolvedPackages;
-        missingPackages = refreshedResolution.data.missingPackages;
-        if (refreshedResolution.data.remoteOutcomes) {
-            Object.assign(remoteOutcomes, refreshedResolution.data.remoteOutcomes);
-        }
-        retryEligibleMissing = computeRetryEligibleMissing(missingPackages);
-        return null;
-    };
-    if (missingPackages.length > 0) {
-        if (resolutionMode === 'local-only') {
-            logger.info('Local-only mode: missing dependencies will not be pulled from remote', {
-                missingPackages: Array.from(new Set(missingPackages))
-            });
-        }
-        else if (retryEligibleMissing.length > 0) {
-            const pullResult = await pullMissingFromRemote();
-            if (pullResult) {
-                return pullResult;
-            }
-        }
-    }
-    // 7) Warn if still missing
-    if (missingPackages.length > 0) {
-        const missingSummary = `Missing packages: ${Array.from(new Set(missingPackages)).join(', ')}`;
-        console.log(`⚠️  ${missingSummary}`);
-        warnings.push(missingSummary);
-    }
-    // 8) Process conflicts
-    const conflictProcessing = await processConflictResolution(resolvedPackages, options);
-    if ('cancelled' in conflictProcessing) {
-        console.log(`Installation cancelled by user`);
-        return {
-            success: true,
-            data: {
-                packageName,
-                targetDir: getAIDir(cwd),
-                resolvedPackages: [],
-                totalPackages: 0,
-                installed: 0,
-                skipped: 1,
-                totalGroundzeroFiles: 0
-            }
-        };
-    }
-    const { finalResolvedPackages, conflictResult } = conflictProcessing;
-    displayDependencyTree(finalResolvedPackages, true);
-    const packageYmlPath = getLocalPackageYmlPath(cwd);
-    const packageYmlExists = await exists(packageYmlPath);
-    // 9) If dryRun, delegate to handleDryRunMode and return
-    if (options.dryRun) {
-        return await handleDryRunMode(finalResolvedPackages, packageName, targetDir, options, packageYmlExists);
-    }
-    // 10) Resolve platforms, create dirs, perform phases, write metadata, update package.yml, display results, return
-    const canPromptForPlatforms = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-    const finalPlatforms = options.resolvedPlatforms && options.resolvedPlatforms.length > 0
-        ? options.resolvedPlatforms
-        : await resolvePlatforms(cwd, specifiedPlatforms, { interactive: canPromptForPlatforms });
-    const createdDirs = await createPlatformDirectories(cwd, finalPlatforms);
-    const mainPackage = finalResolvedPackages.find((f) => f.isRoot);
-    const installationOutcome = await performIndexBasedInstallationPhases({
-        cwd,
-        packages: finalResolvedPackages,
-        platforms: finalPlatforms,
-        conflictResult,
-        options,
-        targetDir
-    });
-    for (const resolved of finalResolvedPackages) {
-        await writeLocalPackageFromRegistry(cwd, resolved.name, resolved.version);
-    }
-    if (packageYmlExists && mainPackage) {
-        const persistTarget = resolvePersistRange(canonicalPlan.persistDecision, mainPackage.version);
-        if (persistTarget) {
-            await addPackageToYml(cwd, packageName, mainPackage.version, persistTarget.target === 'dev-packages', persistTarget.range, true);
-        }
-    }
-    displayInstallationResults(packageName, finalResolvedPackages, { platforms: finalPlatforms, created: createdDirs }, options, mainPackage, installationOutcome.allAddedFiles, installationOutcome.allUpdatedFiles, installationOutcome.rootFileResults, missingPackages, remoteOutcomes);
-    return {
-        success: true,
-        data: {
-            packageName,
-            targetDir: getAIDir(cwd),
-            resolvedPackages: finalResolvedPackages,
-            totalPackages: finalResolvedPackages.length,
-            installed: installationOutcome.installedCount,
-            skipped: installationOutcome.skippedCount,
-            totalGroundzeroFiles: installationOutcome.totalGroundzeroFiles
-        },
-        warnings: warnings.length > 0 ? Array.from(new Set(warnings)) : undefined
-    };
-}
-export function formatSelectionSummary(source, packageName, version) {
-    const packageSpecifier = packageName.startsWith('@') ? packageName : `@${packageName}`;
-    return `✓ Selected ${source} ${packageSpecifier}@${version}`;
-}
-function updateRemoteOutcomesFromBatch(batchResult, remoteOutcomes) {
-    if (!batchResult.failed || batchResult.failed.length === 0) {
-        return;
-    }
-    for (const failure of batchResult.failed) {
-        const reasonLabel = extractRemoteErrorReason(failure.error ?? 'Unknown error');
-        const reasonTag = mapReasonLabelToOutcome(reasonLabel);
-        const packageName = failure.name;
-        const message = `Remote pull failed for \`${packageName}\` (reason: ${reasonLabel})`;
-        remoteOutcomes[packageName] = {
-            name: packageName,
-            reason: reasonTag,
-            message
-        };
-    }
-}
-function mapReasonLabelToOutcome(reasonLabel) {
-    switch (reasonLabel) {
-        case 'not found in remote registry':
-        case 'not found in registry':
-            return 'not-found';
-        case 'access denied':
-            return 'access-denied';
-        case 'network error':
-            return 'network';
-        case 'integrity check failed':
-            return 'integrity';
-        default:
-            return 'unknown';
-    }
-}
-async function determineCanonicalInstallPlan(args) {
-    const normalizedCliSpec = args.cliSpec?.trim() || undefined;
-    const existing = await findCanonicalDependency(args.cwd, args.packageName);
-    const target = args.devFlag ? 'dev-packages' : 'packages';
-    if (existing) {
-        const canonicalConstraint = parseConstraintOrThrow('package', existing.range, args.packageName);
-        if (normalizedCliSpec) {
-            const cliConstraint = parseConstraintOrThrow('cli', normalizedCliSpec, args.packageName);
-            if (!isRangeSubset(cliConstraint.resolverRange, canonicalConstraint.resolverRange)) {
-                throw buildCanonicalConflictError(args.packageName, cliConstraint.displayRange, existing.range);
-            }
-            return {
-                effectiveRange: canonicalConstraint.resolverRange,
-                dependencyState: 'existing',
-                canonicalRange: existing.range,
-                canonicalTarget: existing.target,
-                persistDecision: { type: 'none' },
-                compatibilityMessage: `Using version range from package.yml (${existing.range}); CLI spec '${cliConstraint.displayRange}' is compatible.`
-            };
-        }
-        return {
-            effectiveRange: canonicalConstraint.resolverRange,
-            dependencyState: 'existing',
-            canonicalRange: existing.range,
-            canonicalTarget: existing.target,
-            persistDecision: { type: 'none' }
-        };
-    }
-    if (normalizedCliSpec) {
-        const cliConstraint = parseConstraintOrThrow('cli', normalizedCliSpec, args.packageName);
-        return {
-            effectiveRange: cliConstraint.resolverRange,
-            dependencyState: 'fresh',
-            persistDecision: {
-                type: 'explicit',
-                target,
-                range: cliConstraint.displayRange
-            }
-        };
-    }
-    return {
-        effectiveRange: '*',
-        dependencyState: 'fresh',
-        persistDecision: {
-            type: 'derive',
-            target,
-            mode: 'caret-or-exact'
-        }
-    };
-}
-async function findCanonicalDependency(cwd, packageName) {
-    const packageYmlPath = getLocalPackageYmlPath(cwd);
-    if (!(await exists(packageYmlPath))) {
-        return null;
-    }
-    try {
-        const config = await parsePackageYml(packageYmlPath);
-        const match = locateDependencyInArray(config.packages, packageName, 'packages') ||
-            locateDependencyInArray(config['dev-packages'], packageName, 'dev-packages');
-        return match;
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to parse ${packageYmlPath}: ${detail}`);
-    }
-}
-function locateDependencyInArray(deps, packageName, target) {
-    if (!deps) {
-        return null;
-    }
-    const entry = deps.find(dep => arePackageNamesEquivalent(dep.name, packageName));
-    if (!entry) {
-        return null;
-    }
-    if (!entry.version || !entry.version.trim()) {
-        throw new Error(`Dependency '${packageName}' in .openpackage/package.yml must declare a version range. Edit the file and try again.`);
-    }
-    return {
-        range: entry.version.trim(),
-        target
-    };
-}
-function parseConstraintOrThrow(source, raw, packageName) {
-    try {
-        const parsed = parseVersionRange(raw);
-        return { resolverRange: parsed.range, displayRange: parsed.original };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (source === 'cli') {
-            throw new Error(`Invalid version spec '${raw}' provided via CLI for '${packageName}'. ${message}. Adjust the CLI input and try again.`);
-        }
-        throw new Error(`Dependency '${packageName}' in .openpackage/package.yml has invalid version '${raw}'. ${message}. Edit the file and try again.`);
-    }
-}
-function isRangeSubset(candidate, canonical) {
-    try {
-        return semver.subset(candidate, canonical, { includePrerelease: true });
-    }
-    catch {
-        return false;
-    }
-}
-function buildCanonicalConflictError(packageName, cliSpec, canonicalRange) {
-    return new Error(`Requested '${packageName}@${cliSpec}', but .openpackage/package.yml declares '${packageName}' with range '${canonicalRange}'. Edit package.yml to change the dependency line, then re-run opkg install.`);
-}
-function resolvePersistRange(decision, selectedVersion) {
-    if (decision.type === 'none') {
-        return null;
-    }
-    if (decision.type === 'explicit') {
-        return { range: decision.range, target: decision.target };
-    }
-    // Create caret range from the selected version
-    const derivedRange = createCaretRange(selectedVersion);
-    return { range: derivedRange, target: decision.target };
-}
-function buildNoVersionFoundError(packageName, constraint, selection, mode) {
-    const stableList = formatVersionList(selection.availableStable);
-    const prereleaseList = formatVersionList(selection.availablePrerelease);
-    const suggestions = [
-        'Edit .openpackage/package.yml or adjust the CLI range, then retry.',
-        'Use opkg save/pack to create a compatible version in the local registry.'
-    ];
-    if (mode === 'local-only') {
-        suggestions.push('Re-run without --local to include remote versions in resolution.');
-    }
-    const message = [
-        `No version of '${packageName}' satisfies '${constraint}'.`,
-        `Available stable versions: ${stableList}`,
-        `Available WIP/pre-release versions: ${prereleaseList}`,
-        'Suggested next steps:',
-        ...suggestions.map(suggestion => `  • ${suggestion}`)
-    ].join('\n');
-    return new Error(message);
-}
-function formatVersionList(versions) {
-    if (!versions || versions.length === 0) {
-        return 'none';
-    }
-    return versions.join(', ');
-}
-/**
- * Main install command router - handles both individual and bulk install
- * @param packageName - Name of package to install (optional, installs all if not provided)
- * @param targetDir - Target directory for installation
- * @param options - Installation options
- * @returns Command result with installation status and data
- */
 async function installCommand(packageName, targetDir, options) {
-    const mode = determineResolutionMode(options);
-    options.resolutionMode = mode;
-    logger.debug('Install resolution mode selected', { mode });
-    // If no package name provided, install all from package.yml
+    assertTargetDirOutsideMetadata(targetDir);
+    options.resolutionMode = determineResolutionMode(options);
+    logger.debug('Install resolution mode selected', { mode: options.resolutionMode });
     if (!packageName) {
-        return await installAllPackagesCommand(targetDir, options);
+        return await runBulkInstallPipeline(targetDir, options);
     }
-    // Parse package name and version from input
-    const { name, version: inputVersion } = parsePackageInput(packageName);
-    // Install the specific package with version
-    return await installPackageCommand(name, targetDir, options, inputVersion);
+    const { name, version } = parsePackageInput(packageName);
+    return await runInstallPipeline({
+        ...options,
+        packageName: name,
+        version,
+        targetDir
+    });
 }
-/**
- * Setup the install command
- * @param program - Commander program instance to register the command with
- */
 export function setupInstallCommand(program) {
     program
         .command('install')
         .alias('i')
         .description('Install packages from the local (and optional remote) registry into this workspace. Works with WIP copies from `opkg save` and stable releases from `opkg pack`.')
         .argument('[package-name]', 'name of the package to install (optional - installs all from package.yml if not specified). Supports package@version syntax.')
-        .argument('[target-dir]', 'target directory relative to cwd/ai for /ai files only (defaults to ai root)', '.')
+        .argument('[target-dir]', 'target directory relative to the workspace install root (defaults to ./ai)', '.')
         .option('--dry-run', 'preview changes without applying them')
         .option('--force', 'overwrite existing files')
         .option('--conflicts <strategy>', 'conflict handling strategy: keep-both, overwrite, skip, or ask')
@@ -694,7 +54,6 @@ export function setupInstallCommand(program) {
         .option('--profile <profile>', 'profile to use for authentication')
         .option('--api-key <key>', 'API key for authentication (overrides profile)')
         .action(withErrorHandling(async (packageName, targetDir, options) => {
-        // Normalize platforms option early for downstream logic
         options.platforms = normalizePlatforms(options.platforms);
         const commandOptions = options;
         const rawConflictStrategy = commandOptions.conflicts ?? options.conflictStrategy;
@@ -711,7 +70,6 @@ export function setupInstallCommand(program) {
         const result = await installCommand(packageName, targetDir, options);
         if (!result.success) {
             if (result.error === 'Package not found') {
-                // Handled case: already printed minimal message, do not bubble to global handler
                 return;
             }
             throw new Error(result.error || 'Installation operation failed');