opkg 0.6.1 → 0.7.0

package/dist/utils/index-based-installer.js

@@ -1,25 +1,79 @@
 import { dirname, join, relative, parse as parsePath, sep } from 'path';
 import { promises as fs } from 'fs';
-import { exists, ensureDir, listDirectories, listFiles, remove, removeEmptyDirectories, walkFiles } from './fs.js';
+import { exists, ensureDir, listDirectories, listFiles, remove, removeEmptyDirectories, walkFiles, readTextFile } from './fs.js';
 import { writeIfChanged } from '../core/install/file-updater.js';
-import { getLocalPackagesDir } from './paths.js';
 import { packageManager } from '../core/package.js';
+import { getRegistryDirectories } from '../core/directory.js';
 import { logger } from './logger.js';
-import { FILE_PATTERNS, UNIVERSAL_SUBDIRS } from '../constants/index.js';
+import { FILE_PATTERNS, } from '../constants/index.js';
+import { getPlatformRootFileNames, stripRootCopyPrefix } from './platform-root-files.js';
+import { getAllUniversalSubdirs, platformUsesFlows } from '../core/platforms.js';
 import { normalizePathForProcessing } from './path-normalization.js';
+import { formatPathForWorkspaceIndex } from './path-resolution.js';
 import { isAllowedRegistryPath, isRootRegistryPath, isSkippableRegistryPath, normalizeRegistryPath, extractUniversalSubdirInfo } from './registry-entry-filter.js';
 import { mapUniversalToPlatform } from './platform-mapper.js';
 import { safePrompts } from './prompts.js';
-import { mergePlatformYamlOverride, loadRegistryYamlOverrides } from './platform-yaml-merge.js';
+import { mergeInlinePlatformOverride } from './platform-yaml-merge.js';
 import { parseUniversalPath } from './platform-file.js';
 import { getPlatformDefinition } from '../core/platforms.js';
-import { getPackageIndexPath, readPackageIndex, writePackageIndex, sortMapping, ensureTrailingSlash, isDirKey, pruneNestedDirectories } from './package-index-yml.js';
-import { createWorkspaceHash } from './version-generator.js';
+import { sortMapping, ensureTrailingSlash, isDirKey, pruneNestedDirectories } from './package-index-yml.js';
+import { getWorkspaceIndexPath, readWorkspaceIndex, writeWorkspaceIndex } from './workspace-index-yml.js';
+import { resolvePackageContentRoot } from '../core/install/local-source-resolution.js';
+import { calculateFileHash } from './hash-utils.js';
+import { getTargetPath } from './workspace-index-helpers.js';
+async function readPackageIndex(cwd, packageName, _location) {
+    const record = await readWorkspaceIndex(cwd);
+    const entry = record.index.packages?.[packageName];
+    if (!entry)
+        return null;
+    return {
+        path: entry.path ?? '',
+        packageName,
+        workspace: {
+            version: entry.version ?? '',
+            hash: undefined
+        },
+        files: entry.files ?? {}
+    };
+}
+async function writePackageIndex(record, cwd) {
+    const resolvedCwd = cwd ??
+        (record.path
+            ? dirname(dirname(record.path))
+            : undefined);
+    if (!resolvedCwd) {
+        logger.warn(`Unable to write workspace index for ${record.packageName}: missing cwd`);
+        return;
+    }
+    const wsRecord = await readWorkspaceIndex(resolvedCwd);
+    // Be defensive: older/invalid index files could sanitize to missing packages map.
+    wsRecord.index.packages = wsRecord.index.packages ?? {};
+    const entry = wsRecord.index.packages[record.packageName];
+    const rawPath = entry?.path ??
+        record.path ??
+        (record.workspace?.version
+            ? join(getRegistryDirectories().packages, record.packageName, record.workspace.version, sep)
+            : '');
+    if (!rawPath) {
+        logger.warn(`Skipping workspace index write for ${record.packageName}: source path is unknown`);
+        return;
+    }
+    // Prefer workspace-relative paths when the source lives under the workspace root.
+    // Otherwise, convert absolute paths under ~/.openpackage/ to tilde notation.
+    const pathToUse = formatPathForWorkspaceIndex(rawPath, resolvedCwd);
+    wsRecord.index.packages[record.packageName] = {
+        ...entry,
+        path: pathToUse,
+        version: entry?.version ?? record.workspace?.version,
+        files: sortMapping(record.files ?? {})
+    };
+    await writeWorkspaceIndex(wsRecord);
+}
 // ============================================================================
 // Conflict Planning Functions
 // ============================================================================
 export async function planConflictsForPackage(cwd, packageName, version, platforms) {
-    const registryEntries = await loadRegistryFileEntries(packageName, version);
+    const registryEntries = await loadRegistryFileEntries(packageName, version, { cwd });
     const plannedFiles = createPlannedFiles(registryEntries);
     attachTargetsToPlannedFiles(cwd, plannedFiles, platforms);
     const otherIndexes = await loadOtherPackageIndexes(cwd, packageName);
@@ -106,7 +160,62 @@ async function promptConflictResolution(message) {
     const choice = response.choice;
     return choice ?? 'skip';
 }
-async function updateOwnerIndexAfterRename(owner, oldRelPath, newRelPath, indexByPackage) {
+/**
+ * Prompt user for action when file content differs
+ */
+async function promptContentDifferenceResolution(workspacePath, packagePath) {
+    // Format package path as relative to package root with leading slash
+    const formattedPackagePath = packagePath
+        ? (packagePath.startsWith('/') ? packagePath : `/${packagePath}`)
+        : undefined;
+    const message = formattedPackagePath
+        ? `Package file ${formattedPackagePath} differs from workspace file ${workspacePath}`
+        : `File ${workspacePath} differs from package version`;
+    const response = await safePrompts({
+        type: 'select',
+        name: 'choice',
+        message,
+        choices: [
+            {
+                title: 'Overwrite (use package version)',
+                value: 'overwrite'
+            },
+            {
+                title: 'Skip (keep workspace version)',
+                value: 'skip'
+            }
+        ]
+    });
+    const choice = response.choice;
+    return choice ?? 'skip';
+}
+/**
+ * Check if file content differs using hash comparison
+ */
+async function hasContentDifference(absPath, newContent) {
+    try {
+        if (!(await exists(absPath))) {
+            return false; // File doesn't exist, so no content difference
+        }
+        const existingContent = await readTextFile(absPath, 'utf8');
+        // Quick check: if content is exactly the same, no need to hash
+        if (existingContent === newContent) {
+            return false;
+        }
+        // Hash comparison for definitive answer
+        const [existingHash, newHash] = await Promise.all([
+            calculateFileHash(existingContent),
+            calculateFileHash(newContent)
+        ]);
+        return existingHash !== newHash;
+    }
+    catch (error) {
+        logger.warn(`Failed to check content difference for ${absPath}: ${error}`);
+        // On error, assume content differs to be safe
+        return true;
+    }
+}
+async function updateOwnerIndexAfterRename(owner, oldRelPath, newRelPath, indexByPackage, cwd) {
     const normalizedOld = normalizePathForProcessing(oldRelPath);
     const normalizedNew = normalizePathForProcessing(newRelPath);
     const record = indexByPackage.get(owner.packageName);
@@ -116,11 +225,21 @@ async function updateOwnerIndexAfterRename(owner, oldRelPath, newRelPath, indexB
         const values = record.files[owner.key];
         if (!values)
             return;
-        const idx = values.findIndex(value => normalizePathForProcessing(value) === normalizedOld);
+        const idx = values.findIndex(mapping => {
+            const target = getTargetPath(mapping);
+            return normalizePathForProcessing(target) === normalizedOld;
+        });
         if (idx === -1)
             return;
-        values[idx] = normalizedNew;
-        await writePackageIndex(record);
+        // Update the mapping (preserve keys if it was a complex mapping)
+        const oldMapping = values[idx];
+        if (typeof oldMapping === 'string') {
+            values[idx] = normalizedNew;
+        }
+        else {
+            values[idx] = { ...oldMapping, target: normalizedNew };
+        }
+        await writePackageIndex(record, cwd);
     }
     else {
         // Directory key still valid; nothing to change.
@@ -182,7 +301,7 @@ async function resolveConflictsForPlannedFiles(cwd, plannedFiles, context, other
                     await ensureDir(dirname(absLocalPath));
                     try {
                         await fs.rename(absTarget, absLocalPath);
-                        await updateOwnerIndexAfterRename(owner, normalizedRel, localRelPath, indexByPackage);
+                        await updateOwnerIndexAfterRename(owner, normalizedRel, localRelPath, indexByPackage, cwd);
                         context.installedPathOwners.delete(normalizedRel);
                         context.installedPathOwners.set(normalizePathForProcessing(localRelPath), owner);
                         warnings.push(`Renamed existing ${normalizedRel} from ${owner.packageName} to ${localRelPath}.`);
@@ -205,23 +324,38 @@ async function resolveConflictsForPlannedFiles(cwd, plannedFiles, context, other
                 continue;
             }
             if (!previousOwnedPaths.has(normalizedRel) && (await exists(absTarget))) {
+                // Check if content actually differs
+                const contentDiffers = await hasContentDifference(absTarget, planned.content);
+                if (!contentDiffers) {
+                    // Content is the same, no conflict - just proceed
+                    filteredTargets.push(target);
+                    continue;
+                }
+                // Content differs - handle as a conflict
                 let decision = perPathDecisions.get(normalizedRel);
                 if (!decision) {
                     if (options.force) {
-                        decision = 'keep-both';
+                        // Force flag: auto-overwrite (not keep-both)
+                        decision = 'overwrite';
+                        warnings.push(`Overwriting ${normalizedRel} (content differs, --force flag active).`);
                     }
                     else if (defaultStrategy && defaultStrategy !== 'ask') {
                         decision = defaultStrategy;
                         if (decision === 'skip') {
-                            warnings.push(`Skipping ${normalizedRel} because it already exists (configured conflict strategy).`);
+                            warnings.push(`Skipping ${normalizedRel} (content differs, configured conflict strategy).`);
+                        }
+                        else if (decision === 'overwrite') {
+                            warnings.push(`Overwriting ${normalizedRel} (content differs, configured conflict strategy).`);
                         }
                     }
                     else if (!interactive) {
-                        warnings.push(`Skipping ${normalizedRel} because it already exists and cannot prompt in non-interactive mode.`);
+                        warnings.push(`Skipping ${normalizedRel} (content differs, cannot prompt in non-interactive mode).`);
                         decision = 'skip';
                     }
                     else {
-                        decision = await promptConflictResolution(`File ${normalizedRel} already exists in your project. How would you like to proceed?`);
+                        // Interactive mode: prompt for content-modified files
+                        const contentDecision = await promptContentDifferenceResolution(normalizedRel, planned.registryPath);
+                        decision = contentDecision;
                     }
                 }
                 if (decision === 'skip') {
@@ -249,7 +383,7 @@ async function resolveConflictsForPlannedFiles(cwd, plannedFiles, context, other
                 }
                 // overwrite
                 if (isDryRun) {
-                    warnings.push(`Would overwrite existing local file ${normalizedRel}.`);
+                    warnings.push(`Would overwrite existing local file ${normalizedRel} (content modified).`);
                     filteredTargets.push(target);
                     continue;
                 }
@@ -270,52 +404,25 @@ function normalizeRelativePath(cwd, absPath) {
     const normalized = normalizePathForProcessing(rel);
     return normalized.replace(/\\/g, '/');
 }
-async function collectPackageDirectories(cwd) {
-    const packagesRoot = getLocalPackagesDir(cwd);
-    if (!(await exists(packagesRoot))) {
-        return [];
-    }
-    const results = [];
-    async function recurse(currentDir, relativeBase) {
-        const packageYmlPath = join(currentDir, FILE_PATTERNS.PACKAGE_YML);
-        if (await exists(packageYmlPath)) {
-            const packageName = relativeBase.replace(new RegExp(`\\${sep}`, 'g'), '/');
-            results.push({ packageName, dir: currentDir });
-            return;
-        }
-        const subdirs = await listDirectories(currentDir).catch(() => []);
-        for (const subdir of subdirs) {
-            const nextDir = join(currentDir, subdir);
-            const nextRelative = relativeBase ? `${relativeBase}${sep}${subdir}` : subdir;
-            await recurse(nextDir, nextRelative);
-        }
-    }
-    const topLevelDirs = await listDirectories(packagesRoot).catch(() => []);
-    for (const dir of topLevelDirs) {
-        const absolute = join(packagesRoot, dir);
-        await recurse(absolute, dir);
-    }
-    return results;
-}
 export async function loadOtherPackageIndexes(cwd, excludePackage) {
-    const directories = await collectPackageDirectories(cwd);
+    const record = await readWorkspaceIndex(cwd);
+    const wsPath = getWorkspaceIndexPath(cwd);
+    const packages = record.index.packages ?? {};
     const results = [];
-    for (const entry of directories) {
-        if (entry.packageName === excludePackage)
-            continue;
-        const indexPath = join(entry.dir, FILE_PATTERNS.PACKAGE_INDEX_YML);
-        if (!(await exists(indexPath)))
+    for (const [name, entry] of Object.entries(packages)) {
+        if (name === excludePackage)
             continue;
-        const record = await readPackageIndex(cwd, entry.packageName);
-        if (record) {
-            record.path = indexPath;
-            results.push(record);
-        }
+        results.push({
+            path: entry?.path ?? wsPath,
+            packageName: name,
+            workspace: { version: entry?.version ?? '' },
+            files: entry?.files ?? {}
+        });
     }
     return results;
 }
-async function collectFilesUnderDirectory(cwd, dirRel) {
-    const directoryRel = ensureTrailingSlash(normalizePathForProcessing(dirRel));
+async function collectFilesUnderDirectory(cwd, dirRelPath) {
+    const directoryRel = ensureTrailingSlash(normalizePathForProcessing(dirRelPath));
     const absDir = join(cwd, directoryRel);
     if (!(await exists(absDir))) {
         return [];
@@ -341,15 +448,15 @@ async function buildExpandedIndexesContext(cwd, indexes) {
             const owner = {
                 packageName: record.packageName,
                 key,
-                type: key.endsWith('/') ? 'dir' : 'file',
-                indexPath: record.path
+                type: key.endsWith('/') ? 'dir' : 'file'
             };
             if (owner.type === 'dir') {
                 if (!dirKeyOwners.has(key)) {
                     dirKeyOwners.set(key, []);
                 }
                 dirKeyOwners.get(key).push(owner);
-                for (const dirRel of values) {
+                for (const mapping of values) {
+                    const dirRel = getTargetPath(mapping);
                     const files = await collectFilesUnderDirectory(cwd, dirRel);
                     for (const filePath of files) {
                         if (!installedPathOwners.has(filePath)) {
@@ -359,7 +466,8 @@ async function buildExpandedIndexesContext(cwd, indexes) {
                 }
             }
             else {
-                for (const fileRel of values) {
+                for (const mapping of values) {
+                    const fileRel = getTargetPath(mapping);
                     const normalizedValue = normalizePathForProcessing(fileRel);
                     if (!installedPathOwners.has(normalizedValue)) {
                         installedPathOwners.set(normalizedValue, owner);
@@ -373,8 +481,15 @@ async function buildExpandedIndexesContext(cwd, indexes) {
 // ============================================================================
 // Registry File Loading Functions
 // ============================================================================
-async function loadRegistryFileEntries(packageName, version) {
-    const pkg = await packageManager.loadPackage(packageName, version);
+async function loadRegistryFileEntries(packageName, version, opts) {
+    const packageRootDir = opts?.contentRoot && (await exists(opts.contentRoot))
+        ? opts.contentRoot
+        : opts?.cwd
+            ? await resolvePackageContentRoot({ cwd: opts.cwd, packageName, version })
+            : undefined;
+    const pkg = await packageManager.loadPackage(packageName, version, {
+        packageRootDir
+    });
     const entries = [];
     for (const file of pkg.files) {
         const normalized = normalizeRegistryPath(file.path);
@@ -382,7 +497,7 @@ async function loadRegistryFileEntries(packageName, version) {
         if (isRootRegistryPath(normalized)) {
             continue;
         }
-        if (!isAllowedRegistryPath(normalized)) {
+        if (!isAllowedRegistryPath(normalized, opts?.cwd)) {
             // Ignore any other top-level paths (e.g., README.md, some/...)
             continue;
         }
@@ -394,15 +509,15 @@ async function loadRegistryFileEntries(packageName, version) {
     }
     return entries;
 }
-function deriveGroupKey(registryPath) {
+function deriveGroupKey(registryPath, cwd) {
     const normalized = normalizeRegistryPath(registryPath);
     const segments = normalized.split('/');
     if (segments.length <= 1) {
         return '';
     }
     const first = segments[0];
-    const universalValues = Object.values(UNIVERSAL_SUBDIRS);
-    if (universalValues.includes(first)) {
+    const universalSubdirs = getAllUniversalSubdirs(cwd);
+    if (universalSubdirs.has(first)) {
         if (segments.length >= 2) {
             return ensureTrailingSlash(`${segments[0]}/${segments[1]}`);
         }
@@ -421,10 +536,10 @@ function createPlannedFiles(entries) {
         targets: []
     }));
 }
-function groupPlannedFiles(plannedFiles) {
+function groupPlannedFiles(plannedFiles, cwd) {
     const groups = new Map();
     for (const planned of plannedFiles) {
-        const key = deriveGroupKey(planned.registryPath);
+        const key = deriveGroupKey(planned.registryPath, cwd);
         if (!groups.has(key)) {
             groups.set(key, []);
         }
@@ -435,7 +550,7 @@ function groupPlannedFiles(plannedFiles) {
 // ============================================================================
 // Planning Functions
 // ============================================================================
-function buildPlannedTargetMap(plannedFiles, yamlOverrides) {
+function buildPlannedTargetMap(plannedFiles, cwd) {
     const map = new Map();
     const universalPlanned = [];
     const platformSuffixedPlanned = [];
@@ -452,16 +567,17 @@ function buildPlannedTargetMap(plannedFiles, yamlOverrides) {
         for (const { planned, parsed } of entries) {
             for (const target of planned.targets) {
                 const normalizedRel = normalizePathForProcessing(target.relPath);
-                // Compute per-target content (apply platform YAML overrides for universal files)
+                // Compute per-target content (apply inline platform overrides for universal files)
                 let content = planned.content;
-                if (parsed && target.platform && target.platform !== 'other') {
-                    content = mergePlatformYamlOverride(planned.content, target.platform, parsed.universalSubdir, parsed.relPath, yamlOverrides);
+                if (parsed && !parsed.platformSuffix && target.platform && target.platform !== 'other') {
+                    content = mergeInlinePlatformOverride(planned.content, target.platform, cwd);
                 }
                 map.set(normalizedRel, {
                     absPath: target.absPath,
                     relPath: normalizedRel,
                     content,
-                    encoding: planned.encoding
+                    encoding: planned.encoding,
+                    sourcePath: planned.registryPath
                 });
             }
         }
@@ -480,7 +596,7 @@ function computeDiff(plannedMap, previousOwnedPaths) {
     }
     return { planned: plannedMap, deletions };
 }
-async function applyFileOperations(cwd, planned, deletions, options) {
+async function applyFileOperations(cwd, planned, deletions, options, packageName, contentRoot) {
     const result = {
         installed: 0,
         updated: 0,
@@ -512,6 +628,53 @@ async function applyFileOperations(cwd, planned, deletions, options) {
     }
     for (const [rel, detail] of planned.entries()) {
         const absPath = detail.absPath;
+        // Check for content differences before writing
+        if (await exists(absPath)) {
+            const contentDiffers = await hasContentDifference(absPath, detail.content);
+            if (contentDiffers) {
+                // Content differs - need to handle conflict
+                const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+                let shouldWrite = false;
+                if (isDryRun) {
+                    logger.warn(`Would overwrite ${rel} (content differs from package)`);
+                    result.skipped++;
+                    continue;
+                }
+                if (options.force) {
+                    logger.warn(`Overwriting ${rel} (content differs, --force flag active)`);
+                    shouldWrite = true;
+                }
+                else if (options.conflictStrategy === 'overwrite') {
+                    logger.warn(`Overwriting ${rel} (content differs, configured conflict strategy)`);
+                    shouldWrite = true;
+                }
+                else if (options.conflictStrategy === 'skip') {
+                    logger.warn(`Skipping ${rel} (content differs, configured conflict strategy)`);
+                    result.skipped++;
+                    continue;
+                }
+                else if (!interactive) {
+                    logger.warn(`Skipping ${rel} (content differs, cannot prompt in non-interactive mode)`);
+                    result.skipped++;
+                    continue;
+                }
+                else {
+                    // Interactive mode: prompt user
+                    // Use registry path (relative to package root)
+                    const decision = await promptContentDifferenceResolution(rel, detail.sourcePath);
+                    if (decision === 'skip') {
+                        logger.info(`Skipped ${rel} (keeping workspace version)`);
+                        result.skipped++;
+                        continue;
+                    }
+                    shouldWrite = true;
+                }
+                if (!shouldWrite) {
+                    result.skipped++;
+                    continue;
+                }
+            }
+        }
         if (isDryRun) {
             result.skipped++;
             continue;
@@ -637,63 +800,42 @@ function buildIndexMappingFromPlans(plans) {
 // ============================================================================
 // Main Install Function
 // ============================================================================
-export async function installPackageByIndex(cwd, packageName, version, platforms, options, includePaths) {
-    const registryEntries = await loadRegistryFileEntries(packageName, version);
-    const normalizedIncludes = includePaths && includePaths.length > 0
-        ? new Set(includePaths.map(p => normalizeRegistryPath(p)))
-        : null;
-    const plannedFiles = createPlannedFiles(registryEntries).filter(planned => {
-        if (!normalizedIncludes)
-            return true;
-        return normalizedIncludes.has(normalizeRegistryPath(planned.registryPath));
-    });
-    if (normalizedIncludes && plannedFiles.length === 0) {
-        const available = registryEntries.map(e => normalizeRegistryPath(e.registryPath)).sort();
-        const message = `Requested specific file(s) not found in ${packageName}@${version}. Available registry paths: ${available.join(', ')}`;
-        // Align with package-missing behavior: warn and skip instead of throwing
-        logger.warn(`${message}. Skipping package install.`);
-        return {
-            installed: 0,
-            updated: 0,
-            deleted: 0,
-            skipped: 1,
-            files: [],
-            installedFiles: [],
-            updatedFiles: [],
-            deletedFiles: []
-        };
-    }
-    attachTargetsToPlannedFiles(cwd, plannedFiles, platforms);
-    const groups = groupPlannedFiles(plannedFiles);
-    const previousIndex = await readPackageIndex(cwd, packageName);
-    const otherIndexes = await loadOtherPackageIndexes(cwd, packageName);
-    const context = await buildExpandedIndexesContext(cwd, otherIndexes);
-    const groupPlans = await decideGroupPlans(cwd, groups, previousIndex, context);
-    const previousOwnedPaths = await expandIndexToFilePaths(cwd, previousIndex);
-    const conflictWarnings = await resolveConflictsForPlannedFiles(cwd, plannedFiles, context, otherIndexes, previousOwnedPaths, options);
-    for (const warning of conflictWarnings) {
-        logger.warn(warning);
-    }
-    // Load platform YAML overrides once per install
-    const yamlOverrides = await loadRegistryYamlOverrides(packageName, version);
-    const plannedTargetMap = buildPlannedTargetMap(plannedFiles, yamlOverrides);
-    const { planned, deletions } = computeDiff(plannedTargetMap, previousOwnedPaths);
-    const operationResult = await applyFileOperations(cwd, planned, deletions, options);
-    if (!options.dryRun) {
-        const mapping = buildIndexMappingFromPlans(groupPlans);
-        const workspaceHash = previousIndex?.workspace?.hash ?? createWorkspaceHash(cwd);
-        const indexRecord = {
-            path: getPackageIndexPath(cwd, packageName),
-            packageName,
-            workspace: {
-                hash: workspaceHash,
-                version
-            },
-            files: mapping
-        };
-        await writePackageIndex(indexRecord);
+export async function installPackageByIndex(cwd, packageName, version, platforms, options, includePaths, contentRoot) {
+    // Check if any platform uses flows
+    const hasFlowPlatforms = platforms.some(platform => platformUsesFlows(platform, cwd));
+    if (hasFlowPlatforms) {
+        logger.debug(`Using flow-based installer for ${packageName} on platforms: ${platforms.join(', ')}`);
+        // Load package to get format metadata (important for plugin conversion)
+        let packageFormat = undefined;
+        if (contentRoot) {
+            try {
+                const { loadPackageFromPath } = await import('../core/install/path-package-loader.js');
+                const pkg = await loadPackageFromPath(contentRoot);
+                // Extract format metadata if available (set by plugin transformer)
+                if (pkg._format) {
+                    packageFormat = pkg._format;
+                    logger.debug(`Package format detected from _format field`, {
+                        type: packageFormat.type,
+                        platform: packageFormat.platform
+                    });
+                }
+            }
+            catch (error) {
+                // If we can't load the package for format detection, that's OK
+                // Format will be detected from files instead
+                logger.debug(`Could not load package for format detection: ${error.message}`);
+            }
+        }
+        // Delegate to flow-based installer
+        const { installPackageByIndexWithFlows } = await import('./flow-index-installer.js');
+        return await installPackageByIndexWithFlows(cwd, packageName, version, platforms, options, includePaths, contentRoot, packageFormat // Pass format metadata
+        );
     }
-    return operationResult;
+    // No platforms use flows - this should not happen with current config
+    throw new Error(`Platform(s) ${platforms.join(', ')} do not use flows. ` +
+        `Flow-based installation is required. Please check platforms.jsonc configuration.`);
+    // Legacy subdirs-based code removed - now using flow-based installation exclusively
+    // See flow-index-installer.ts for the new implementation
 }
 // ============================================================================
 // Target Mapping Functions
@@ -704,7 +846,8 @@ async function expandIndexToFilePaths(cwd, index) {
         return owned;
     for (const [key, values] of Object.entries(index.files)) {
         if (isDirKey(key)) {
-            for (const dirRel of values) {
+            for (const mapping of values) {
+                const dirRel = getTargetPath(mapping);
                 const files = await collectFilesUnderDirectory(cwd, dirRel);
                 for (const rel of files) {
                     owned.add(normalizePathForProcessing(rel));
@@ -712,7 +855,8 @@ async function expandIndexToFilePaths(cwd, index) {
             }
         }
         else {
-            for (const value of values) {
+            for (const mapping of values) {
+                const value = getTargetPath(mapping);
                 owned.add(normalizePathForProcessing(value));
             }
         }
@@ -722,7 +866,7 @@ async function expandIndexToFilePaths(cwd, index) {
 function mapRegistryPathToTargets(cwd, registryPath, platforms) {
     const normalized = normalizeRegistryPath(registryPath);
     const targets = [];
-    const universalInfo = extractUniversalSubdirInfo(normalized);
+    const universalInfo = extractUniversalSubdirInfo(normalized, cwd);
     if (universalInfo) {
         // Parse the universal path to detect platform suffix and normalized relative path
         const parsed = parseUniversalPath(normalized);
@@ -731,8 +875,8 @@ function mapRegistryPathToTargets(cwd, registryPath, platforms) {
             const targetPlatform = parsed.platformSuffix;
             if (platforms.includes(targetPlatform)) {
                 try {
-                    const mapped = mapUniversalToPlatform(targetPlatform, parsed.universalSubdir, parsed.relPath);
-                    const targetAbs = join(cwd, mapped.absFile);
+                    const mapped = mapUniversalToPlatform(targetPlatform, parsed.universalSubdir, parsed.relPath, cwd);
+                    const targetAbs = join(cwd, mapped.relFile);
                     targets.push({
                         absPath: targetAbs,
                         relPath: normalizeRelativePath(cwd, targetAbs),
@@ -749,8 +893,8 @@ function mapRegistryPathToTargets(cwd, registryPath, platforms) {
         const rel = parsed ? parsed.relPath : universalInfo.relPath;
         for (const platform of platforms) {
             try {
-                const mapped = mapUniversalToPlatform(platform, universalInfo.universalSubdir, rel);
-                const targetAbs = join(cwd, mapped.absFile);
+                const mapped = mapUniversalToPlatform(platform, universalInfo.universalSubdir, rel, cwd);
+                const targetAbs = join(cwd, mapped.relFile);
                 targets.push({
                     absPath: targetAbs,
                     relPath: normalizeRelativePath(cwd, targetAbs),
@@ -865,7 +1009,8 @@ function hadPreviousDirForPlatform(previousIndex, groupKey, platform) {
         return false;
     }
     const rootDir = normalizePathForProcessing(getPlatformDefinition(platform).rootDir);
-    for (const value of prevValues) {
+    for (const mapping of prevValues) {
+        const value = getTargetPath(mapping);
         const normalizedValue = normalizePathForProcessing(value);
         if (normalizedValue === rootDir ||
             normalizedValue.startsWith(`${rootDir}/`)) {
@@ -924,6 +1069,62 @@ async function decideGroupPlans(cwd, groups, previousIndex, context) {
 // ============================================================================
 // Shared Helper for Building Index Mappings
 // ============================================================================
+function addMappingValue(mapping, key, value) {
+    if (!mapping[key]) {
+        mapping[key] = [];
+    }
+    if (!mapping[key].includes(value)) {
+        mapping[key].push(value);
+    }
+}
+async function augmentIndexMappingWithRootAndCopyToRoot(cwd, mapping, packageFiles, platforms) {
+    const augmented = { ...mapping };
+    const rootFileNames = getPlatformRootFileNames(platforms);
+    const explicitRootKeys = new Set();
+    const hasAgents = packageFiles.some(file => normalizeRegistryPath(file.path) === FILE_PATTERNS.AGENTS_MD);
+    for (const file of packageFiles) {
+        const normalized = normalizeRegistryPath(file.path);
+        const stripped = stripRootCopyPrefix(normalized);
+        if (stripped !== null) {
+            if (await exists(join(cwd, stripped))) {
+                addMappingValue(augmented, normalized, stripped);
+            }
+            continue;
+        }
+        if (rootFileNames.has(normalized) || isRootRegistryPath(normalized)) {
+            explicitRootKeys.add(normalized);
+            if (await exists(join(cwd, normalized))) {
+                addMappingValue(augmented, normalized, normalized);
+            }
+        }
+    }
+    // For allowed registry paths, if the file already exists at the workspace-relative path,
+    // record that concrete location. This is important for root packages and for "add"/"save"
+    // flows where the source path itself is the only existing workspace location before apply/install.
+    for (const file of packageFiles) {
+        const normalized = normalizeRegistryPath(file.path);
+        if (!isAllowedRegistryPath(normalized, cwd))
+            continue;
+        if (isSkippableRegistryPath(normalized, cwd))
+            continue;
+        if (await exists(join(cwd, normalized))) {
+            addMappingValue(augmented, normalized, normalized);
+        }
+    }
+    // AGENTS.md can populate platform root files when no explicit override exists in the package.
+    if (hasAgents) {
+        for (const rootFile of rootFileNames) {
+            if (rootFile === FILE_PATTERNS.AGENTS_MD)
+                continue;
+            if (explicitRootKeys.has(rootFile))
+                continue;
+            if (await exists(join(cwd, rootFile))) {
+                addMappingValue(augmented, FILE_PATTERNS.AGENTS_MD, rootFile);
+            }
+        }
+    }
+    return sortMapping(augmented);
+}
 /**
  * Build index mapping for package files using the same logic flow as installPackageByIndex
  * This function reuses the planning, grouping, and decision logic to ensure consistency
@@ -944,9 +1145,9 @@ export async function buildIndexMappingForPackageFiles(cwd, packageFiles, platfo
         // Skip root files and skippable paths (same logic as loadRegistryFileEntries)
         if (isRootRegistryPath(normalized))
             return false;
-        if (isSkippableRegistryPath(normalized))
+        if (isSkippableRegistryPath(normalized, cwd))
             return false;
-        return isAllowedRegistryPath(normalized);
+        return isAllowedRegistryPath(normalized, cwd);
     })
         .map(file => ({
         registryPath: normalizeRegistryPath(file.path),
@@ -954,26 +1155,27 @@ export async function buildIndexMappingForPackageFiles(cwd, packageFiles, platfo
         encoding: file.encoding
     }));
     if (registryEntries.length === 0) {
-        return {};
+        return await augmentIndexMappingWithRootAndCopyToRoot(cwd, {}, packageFiles, platforms);
     }
     // Reuse existing planning logic - this ensures consistency with installPackageByIndex
     const plannedFiles = createPlannedFiles(registryEntries);
     attachTargetsToPlannedFiles(cwd, plannedFiles, platforms);
-    const groups = groupPlannedFiles(plannedFiles);
+    const groups = groupPlannedFiles(plannedFiles, cwd);
     const context = await buildExpandedIndexesContext(cwd, otherIndexes);
     const groupPlans = await decideGroupPlans(cwd, groups, previousIndex, context);
     // Build the mapping using the same logic as installPackageByIndex
-    return buildIndexMappingFromPlans(groupPlans);
+    const mapping = buildIndexMappingFromPlans(groupPlans);
+    return await augmentIndexMappingWithRootAndCopyToRoot(cwd, mapping, packageFiles, platforms);
 }
-function filterRegistryEntriesForPackageFiles(packageFiles) {
+function filterRegistryEntriesForPackageFiles(packageFiles, cwd) {
     return packageFiles
         .filter(file => {
         const normalized = normalizeRegistryPath(file.path);
         if (isRootRegistryPath(normalized))
             return false;
-        if (isSkippableRegistryPath(normalized))
+        if (isSkippableRegistryPath(normalized, cwd))
             return false;
-        return isAllowedRegistryPath(normalized);
+        return isAllowedRegistryPath(normalized, cwd);
     })
         .map(file => ({
         registryPath: normalizeRegistryPath(file.path),
@@ -982,36 +1184,27 @@ function filterRegistryEntriesForPackageFiles(packageFiles) {
     }));
 }
 export async function applyPlannedSyncForPackageFiles(cwd, packageName, version, packageFiles, platforms, options, location = 'nested') {
-    const registryEntries = filterRegistryEntriesForPackageFiles(packageFiles);
+    const registryEntries = filterRegistryEntriesForPackageFiles(packageFiles, cwd);
     const plannedFiles = createPlannedFiles(registryEntries);
     attachTargetsToPlannedFiles(cwd, plannedFiles, platforms);
     const previousIndex = await readPackageIndex(cwd, packageName, location);
     const otherIndexes = await loadOtherPackageIndexes(cwd, packageName);
     const context = await buildExpandedIndexesContext(cwd, otherIndexes);
-    const groups = groupPlannedFiles(plannedFiles);
+    const groups = groupPlannedFiles(plannedFiles, cwd);
     const groupPlans = await decideGroupPlans(cwd, groups, previousIndex, context);
     const previousOwnedPaths = await expandIndexToFilePaths(cwd, previousIndex);
     const conflictWarnings = await resolveConflictsForPlannedFiles(cwd, plannedFiles, context, otherIndexes, previousOwnedPaths, options);
     for (const warning of conflictWarnings) {
         logger.warn(warning);
     }
-    const plannedTargetMap = buildPlannedTargetMap(plannedFiles, packageFiles);
+    const plannedTargetMap = buildPlannedTargetMap(plannedFiles, cwd);
     const { planned, deletions } = computeDiff(plannedTargetMap, previousOwnedPaths);
-    const operationResult = await applyFileOperations(cwd, planned, deletions, options);
+    // Try to get contentRoot from previous index for better messaging
+    const contentRoot = previousIndex?.path;
+    const operationResult = await applyFileOperations(cwd, planned, deletions, options, packageName, contentRoot);
     let mapping = {};
     if (!options.dryRun) {
-        mapping = buildIndexMappingFromPlans(groupPlans);
-        const workspaceHash = previousIndex?.workspace?.hash ?? createWorkspaceHash(cwd);
-        const indexRecord = {
-            path: getPackageIndexPath(cwd, packageName, location),
-            packageName,
-            workspace: {
-                hash: workspaceHash,
-                version
-            },
-            files: mapping
-        };
-        await writePackageIndex(indexRecord);
+        mapping = await augmentIndexMappingWithRootAndCopyToRoot(cwd, buildIndexMappingFromPlans(groupPlans), packageFiles, platforms);
     }
     return {
         operation: operationResult,