opkg 0.9.0 → 0.9.2

package/packages/core/dist/core/install/operations/conflict-handler.d.ts

@@ -0,0 +1,13 @@
+import { InstallOptions } from '../../../types/index.js';
+import type { InteractionPolicy } from '../../../core/interaction-policy.js';
+import type { ResolvedPackage } from '../../dependency-resolver/types.js';
+import type { PromptPort } from '../../ports/prompt.js';
+/**
+ * Check for conflicts with all packages in the dependency tree
+ */
+export declare function checkAndHandleAllPackageConflicts(resolvedPackages: ResolvedPackage[], options: InstallOptions, policy?: InteractionPolicy, prompt?: PromptPort): Promise<{
+    shouldProceed: boolean;
+    skippedPackages: string[];
+    forceOverwritePackages: Set<string>;
+}>;
+//# sourceMappingURL=conflict-handler.d.ts.map

package/packages/core/dist/core/install/operations/conflict-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-handler.d.ts","sourceRoot":"","sources":["../../../../src/core/install/operations/conflict-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAQ1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAoBxD;;GAEG;AACH,wBAAsB,iCAAiC,CACrD,gBAAgB,EAAE,eAAe,EAAE,EACnC,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAC;IAAC,sBAAsB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAiDrG"}

package/packages/core/dist/core/install/operations/conflict-handler.js

@@ -0,0 +1,73 @@
+import { join } from 'path';
+import { PromptTier } from '../../../core/interaction-policy.js';
+import { checkExistingPackageInMarkdownFiles } from '../../openpackage.js';
+import { parsePackageYml } from '../../../utils/package-yml.js';
+import { exists } from '../../../utils/fs.js';
+import { logger } from '../../../utils/logger.js';
+import { getLocalPackageDir } from '../../../utils/paths.js';
+import { FILE_PATTERNS } from '../../../constants/index.js';
+import { getVersionInfoFromDependencyTree } from '../install-helpers.js';
+import { resolvePrompt, resolveOutput } from '../../ports/resolve.js';
+/**
+ * Get currently installed version from .openpackage/packages/<package>/openpackage.yml
+ */
+async function getInstalledPackageVersion(cwd, packageName) {
+    try {
+        const packageDir = getLocalPackageDir(cwd, packageName);
+        const packageYmlPath = join(packageDir, FILE_PATTERNS.OPENPACKAGE_YML);
+        if (await exists(packageYmlPath)) {
+            const config = await parsePackageYml(packageYmlPath);
+            return config.version;
+        }
+    }
+    catch {
+        // ignore parse errors; treat as unknown
+    }
+    return undefined;
+}
+/**
+ * Check for conflicts with all packages in the dependency tree
+ */
+export async function checkAndHandleAllPackageConflicts(resolvedPackages, options, policy, prompt) {
+    const cwd = process.cwd();
+    const skippedPackages = [];
+    const forceOverwritePackages = new Set();
+    const p = prompt ?? resolvePrompt();
+    const out = resolveOutput();
+    // Check each package in the dependency tree for conflicts
+    for (const resolved of resolvedPackages) {
+        const existingCheck = await checkExistingPackageInMarkdownFiles(cwd, resolved.name);
+        if (existingCheck.found) {
+            const versionInfo = await getVersionInfoFromDependencyTree(resolved.name, resolvedPackages);
+            const existingVersion = existingCheck.version || await getInstalledPackageVersion(cwd, resolved.name);
+            if (options.dryRun) {
+                // In dry run mode, proceed; per-file logic will report decisions
+                continue;
+            }
+            if (options.force) {
+                // When --force is used, automatically overwrite all conflicts
+                logger.info(`Force flag set - automatically overwriting package '${resolved.name}' v${existingVersion}`);
+                forceOverwritePackages.add(resolved.name);
+                continue;
+            }
+            // Prompt per package overwrite confirmation when existing detected
+            if (policy && !policy.canPrompt(PromptTier.Confirmation)) {
+                out.warn(`Skipping '${resolved.name}' (already exists). Use --force to overwrite.`);
+                skippedPackages.push(resolved.name);
+            }
+            else {
+                const versionSuffix = existingVersion ? ` (${existingVersion})` : '';
+                const confirmed = await p.confirm(`Package '${resolved.name}' already exists${versionSuffix}. Overwrite all files?`);
+                if (confirmed) {
+                    forceOverwritePackages.add(resolved.name);
+                }
+                else {
+                    skippedPackages.push(resolved.name);
+                }
+            }
+            continue;
+        }
+    }
+    return { shouldProceed: true, skippedPackages, forceOverwritePackages };
+}
+//# sourceMappingURL=conflict-handler.js.map

package/packages/core/dist/core/install/operations/conflict-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-handler.js","sourceRoot":"","sources":["../../../../src/core/install/operations/conflict-handler.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/core/install/operations/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Install Operations
+ * Core installation operations exported for use by pipelines
+ */
+export { installOrSyncRootFiles, type RootFileOperationResult, type RootFileInput } from './root-files.js';
+export { checkAndHandleAllPackageConflicts } from './conflict-handler.js';
+export { performIndexBasedInstallationPhases, type InstallationPhasesParams, type InstallationPhasesResult, type ConflictSummary } from './installation-executor.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/core/install/operations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/install/operations/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,sBAAsB,EAAE,KAAK,uBAAuB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3G,OAAO,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EACL,mCAAmC,EACnC,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC"}

package/packages/core/dist/core/install/operations/index.js

@@ -0,0 +1,8 @@
+/**
+ * Install Operations
+ * Core installation operations exported for use by pipelines
+ */
+export { installOrSyncRootFiles } from './root-files.js';
+export { checkAndHandleAllPackageConflicts } from './conflict-handler.js';
+export { performIndexBasedInstallationPhases } from './installation-executor.js';
+//# sourceMappingURL=index.js.map

package/packages/core/dist/core/install/operations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/install/operations/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,sBAAsB,EAAoD,MAAM,iBAAiB,CAAC;AAC3G,OAAO,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EACL,mCAAmC,EAIpC,MAAM,4BAA4B,CAAC"}

package/packages/core/dist/core/install/operations/installation-executor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Installation Executor
+ *
+ * Contains the index-based installation logic for executing package installations.
+ * Migrated from install-flow.ts to support the unified pipeline.
+ */
+import { InstallOptions } from '../../../types/index.js';
+import type { ResolvedPackage } from '../../dependency-resolver/types.js';
+import { type Platform } from '../../platforms.js';
+import type { RelocatedFile } from '../conflicts/file-conflict-resolver.js';
+import { checkAndHandleAllPackageConflicts } from './conflict-handler.js';
+import type { PromptPort } from '../../ports/prompt.js';
+export type ConflictSummary = Awaited<ReturnType<typeof checkAndHandleAllPackageConflicts>>;
+export interface InstallationPhasesParams {
+    cwd: string;
+    packages: ResolvedPackage[];
+    platforms: Platform[];
+    conflictResult?: ConflictSummary;
+    options: InstallOptions;
+    targetDir: string;
+    matchedPattern?: string;
+    prompt?: PromptPort;
+}
+export interface InstallationPhasesResult {
+    installedCount: number;
+    skippedCount: number;
+    errorCount: number;
+    allAddedFiles: string[];
+    allUpdatedFiles: string[];
+    rootFileResults: {
+        installed: string[];
+        updated: string[];
+        skipped: string[];
+    };
+    totalOpenPackageFiles: number;
+    errors?: string[];
+    /** True when namespace conflict resolution was triggered for any package */
+    namespaced?: boolean;
+    /** Files that were physically relocated on disk during namespace resolution */
+    relocatedFiles?: RelocatedFile[];
+}
+/**
+ * Perform the index-based installation process
+ *
+ * Installs each package using the index-based installer and handles root files.
+ */
+export declare function performIndexBasedInstallationPhases(params: InstallationPhasesParams): Promise<InstallationPhasesResult>;
+//# sourceMappingURL=installation-executor.d.ts.map

package/packages/core/dist/core/install/operations/installation-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installation-executor.d.ts","sourceRoot":"","sources":["../../../../src/core/install/operations/installation-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAMnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAG5E,OAAO,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AAG1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,iCAAiC,CAAC,CAAC,CAAC;AAE5F,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC/E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAsB,mCAAmC,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA+L7H"}

package/packages/core/dist/core/install/operations/installation-executor.js

@@ -0,0 +1,174 @@
+/**
+ * Installation Executor
+ *
+ * Contains the index-based installation logic for executing package installations.
+ * Migrated from install-flow.ts to support the unified pipeline.
+ */
+import { logger } from '../../../utils/logger.js';
+import { UserCancellationError } from '../../../utils/errors.js';
+import { discoverAndCategorizeFiles } from '../helpers/file-discovery.js';
+import { installOrSyncRootFiles } from './root-files.js';
+import { installPackageByIndexWithFlows as installPackageByIndex } from '../flow-index-installer.js';
+import { ensureDir, exists, writeTextFile } from '../../../utils/fs.js';
+import { dirname, join } from 'path';
+import { readWorkspaceIndex, writeWorkspaceIndex } from '../../../utils/workspace-index-yml.js';
+import { PACKAGE_ROOT_DIRS } from '../../../constants/index.js';
+/**
+ * Perform the index-based installation process
+ *
+ * Installs each package using the index-based installer and handles root files.
+ */
+export async function performIndexBasedInstallationPhases(params) {
+    const { cwd, packages, platforms, conflictResult, options, targetDir, matchedPattern, prompt } = params;
+    let totalInstalled = 0;
+    let totalUpdated = 0;
+    let totalDeleted = 0;
+    let totalSkipped = 0;
+    let totalErrors = 0;
+    const allAddedFiles = [];
+    const allUpdatedFiles = [];
+    const allDeletedFiles = [];
+    const errors = [];
+    let anyNamespaced = false;
+    const allRelocatedFiles = [];
+    for (const resolved of packages) {
+        try {
+            // Extract originalContentRoot if it was stored during conversion
+            const originalContentRoot = resolved.originalContentRoot;
+            // Check if the package-level conflict phase confirmed an overwrite for this package
+            const forceOverwrite = conflictResult?.forceOverwritePackages?.has(resolved.name) ?? false;
+            const installResult = await installPackageByIndex(cwd, resolved.name, resolved.version, platforms, options, resolved.contentRoot, resolved.pkg._format, resolved.marketplaceMetadata, matchedPattern, resolved.resourceVersion, originalContentRoot, // Pass original path for index writing
+            forceOverwrite, // Phase 5: propagate package-level overwrite decision
+            prompt);
+            totalInstalled += installResult.installed;
+            totalUpdated += installResult.updated;
+            totalDeleted += installResult.deleted;
+            totalSkipped += installResult.skipped;
+            allAddedFiles.push(...installResult.installedFiles);
+            allUpdatedFiles.push(...installResult.updatedFiles);
+            allDeletedFiles.push(...installResult.deletedFiles);
+            // Aggregate namespace metadata
+            if (installResult.namespaced) {
+                anyNamespaced = true;
+            }
+            if (installResult.relocatedFiles && installResult.relocatedFiles.length > 0) {
+                allRelocatedFiles.push(...installResult.relocatedFiles);
+            }
+            if (installResult.installed > 0 || installResult.updated > 0 || installResult.deleted > 0) {
+                logger.info(`Index-based install for ${resolved.name}: ${installResult.installed} installed, ${installResult.updated} updated, ${installResult.deleted} deleted`);
+            }
+        }
+        catch (error) {
+            if (error instanceof UserCancellationError) {
+                throw error;
+            }
+            const errorMsg = `Failed index-based install for ${resolved.name}: ${error}`;
+            logger.error(errorMsg);
+            errors.push(errorMsg);
+            totalErrors++;
+        }
+    }
+    // Handle root files separately
+    const rootFileResults = {
+        installed: new Set(),
+        updated: new Set(),
+        skipped: new Set()
+    };
+    /** Per-package root files + root copy paths to augment workspace index */
+    const rootFileAugmentations = new Map();
+    for (const resolved of packages) {
+        try {
+            const categorized = await discoverAndCategorizeFiles(resolved.name, resolved.version, platforms, resolved.contentRoot, matchedPattern);
+            const installResult = await installOrSyncRootFiles(cwd, resolved.name, categorized.rootFiles, platforms);
+            installResult.created.forEach(file => rootFileResults.installed.add(file));
+            installResult.updated.forEach(file => rootFileResults.updated.add(file));
+            installResult.skipped.forEach(file => rootFileResults.skipped.add(file));
+            // Copy root/** files directly to workspace root (strip prefix)
+            for (const file of categorized.rootCopyFiles) {
+                const targetPath = join(cwd, file.path);
+                const parent = dirname(targetPath);
+                await ensureDir(parent);
+                const existed = await exists(targetPath);
+                await writeTextFile(targetPath, file.content, file.encoding ?? 'utf8');
+                if (existed) {
+                    rootFileResults.updated.add(file.path);
+                }
+                else {
+                    rootFileResults.installed.add(file.path);
+                }
+            }
+            // Collect root files + root copy for index augmentation
+            if (!options.dryRun) {
+                const rootFilePaths = [...installResult.created, ...installResult.updated];
+                const rootCopyPaths = categorized.rootCopyFiles.map(f => f.path);
+                if (rootFilePaths.length > 0 || rootCopyPaths.length > 0) {
+                    rootFileAugmentations.set(resolved.name, { rootFilePaths, rootCopyPaths });
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof UserCancellationError) {
+                throw error;
+            }
+            const errorMsg = `Failed root file install for ${resolved.name}: ${error}`;
+            logger.error(errorMsg);
+            errors.push(errorMsg);
+            totalErrors++;
+        }
+    }
+    // Augment workspace index with root files and root copy files (flow-installer writes index before root phase)
+    if (!options.dryRun && rootFileAugmentations.size > 0) {
+        try {
+            const wsRecord = await readWorkspaceIndex(cwd);
+            wsRecord.index.packages = wsRecord.index.packages ?? {};
+            for (const [packageName, { rootFilePaths, rootCopyPaths }] of rootFileAugmentations) {
+                const entry = wsRecord.index.packages[packageName];
+                if (!entry)
+                    continue;
+                const files = { ...(entry.files ?? {}) };
+                for (const path of rootFilePaths) {
+                    const existing = files[path] ?? [];
+                    if (!existing.includes(path)) {
+                        files[path] = [...existing, path];
+                    }
+                }
+                const rootPrefix = `${PACKAGE_ROOT_DIRS.ROOT_COPY}/`;
+                for (const path of rootCopyPaths) {
+                    const registryKey = `${rootPrefix}${path}`;
+                    const existing = files[registryKey] ?? [];
+                    if (!existing.includes(path)) {
+                        files[registryKey] = [...existing, path];
+                    }
+                }
+                wsRecord.index.packages[packageName] = { ...entry, files };
+            }
+            await writeWorkspaceIndex(wsRecord);
+            logger.debug(`Augmented workspace index with root files for ${rootFileAugmentations.size} package(s)`);
+        }
+        catch (error) {
+            logger.warn(`Failed to augment workspace index with root files: ${error}`);
+        }
+    }
+    // Deduplicate: remove any root files that also appear in allAddedFiles/allUpdatedFiles
+    const addedSet = new Set(allAddedFiles);
+    const updatedSet = new Set(allUpdatedFiles);
+    const dedupedRootInstalled = Array.from(rootFileResults.installed).filter(f => !addedSet.has(f));
+    const dedupedRootUpdated = Array.from(rootFileResults.updated).filter(f => !updatedSet.has(f));
+    return {
+        installedCount: totalInstalled,
+        skippedCount: totalSkipped,
+        errorCount: totalErrors,
+        allAddedFiles,
+        errors: errors.length > 0 ? errors : undefined,
+        allUpdatedFiles,
+        rootFileResults: {
+            installed: dedupedRootInstalled,
+            updated: dedupedRootUpdated,
+            skipped: Array.from(rootFileResults.skipped)
+        },
+        totalOpenPackageFiles: totalInstalled + totalUpdated,
+        namespaced: anyNamespaced || undefined,
+        relocatedFiles: allRelocatedFiles.length > 0 ? allRelocatedFiles : undefined
+    };
+}
+//# sourceMappingURL=installation-executor.js.map

package/packages/core/dist/core/install/operations/installation-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installation-executor.js","sourceRoot":"","sources":["../../../../src/core/install/operations/installation-executor.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/core/install/operations/root-files.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Unified Root File Operations
+ * Handles root file installation and synchronization for both install and apply commands
+ */
+import { type Platform } from '../../platforms.js';
+import type { PackageFile } from '../../../types/index.js';
+/**
+ * Input for root file operations - supports both formats
+ */
+export type RootFileInput = Map<string, string> | PackageFile[] | Record<string, string>;
+/**
+ * Result of root file operations
+ */
+export interface RootFileOperationResult {
+    /** Files that were newly created */
+    created: string[];
+    /** Files that were updated (already existed) */
+    updated: string[];
+    /** Files that were skipped (no changes needed) */
+    skipped: string[];
+    /** Legacy alias for created (for backward compatibility) */
+    installed?: string[];
+}
+/**
+ * Universal root file installer/syncer
+ *
+ * Handles root file installation and synchronization for both install and apply commands.
+ * Supports multiple input formats for maximum flexibility.
+ *
+ * @param cwd - Current working directory
+ * @param packageName - Name of the package
+ * @param rootFiles - Root files to install (Map, PackageFile[], or Record)
+ * @param platforms - Target platforms
+ * @returns Operation result with created/updated/skipped files
+ */
+export declare function installOrSyncRootFiles(cwd: string, packageName: string, rootFiles: RootFileInput, platforms: Platform[]): Promise<RootFileOperationResult>;
+//# sourceMappingURL=root-files.d.ts.map

package/packages/core/dist/core/install/operations/root-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-files.d.ts","sourceRoot":"","sources":["../../../../src/core/install/operations/root-files.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAA0C,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAI3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACnB,WAAW,EAAE,GACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,kDAAkD;IAClD,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,QAAQ,EAAE,GACpB,OAAO,CAAC,uBAAuB,CAAC,CA+BlC"}

package/packages/core/dist/core/install/operations/root-files.js

@@ -0,0 +1,173 @@
+/**
+ * Unified Root File Operations
+ * Handles root file installation and synchronization for both install and apply commands
+ */
+import { join } from 'path';
+import { exists, readTextFile, writeTextFile } from '../../../utils/fs.js';
+import { mergePackageContentIntoRootFile } from '../../../utils/root-file-merger.js';
+import { extractPackageContentFromRootFile } from '../../../utils/root-file-extractor.js';
+import { getPlatformDefinition, getAllPlatforms } from '../../platforms.js';
+import { FILE_PATTERNS } from '../../../constants/index.js';
+import { logger } from '../../../utils/logger.js';
+import { getPathLeaf } from '../../../utils/path-normalization.js';
+/**
+ * Universal root file installer/syncer
+ *
+ * Handles root file installation and synchronization for both install and apply commands.
+ * Supports multiple input formats for maximum flexibility.
+ *
+ * @param cwd - Current working directory
+ * @param packageName - Name of the package
+ * @param rootFiles - Root files to install (Map, PackageFile[], or Record)
+ * @param platforms - Target platforms
+ * @returns Operation result with created/updated/skipped files
+ */
+export async function installOrSyncRootFiles(cwd, packageName, rootFiles, platforms) {
+    const result = {
+        created: [],
+        updated: [],
+        skipped: []
+    };
+    // Normalize input to a common format
+    const rootFilesMap = normalizeRootFileInput(rootFiles);
+    if (rootFilesMap.size === 0) {
+        return result;
+    }
+    // Always install/sync universal AGENTS.md regardless of platform detection
+    await installUniversalAgentsFile(cwd, packageName, rootFilesMap, result);
+    // Install platform-specific root files
+    if (platforms.length > 0) {
+        await installPlatformRootFiles(cwd, packageName, rootFilesMap, platforms, result);
+    }
+    // Deduplicate results
+    result.created = Array.from(new Set(result.created));
+    result.updated = Array.from(new Set(result.updated));
+    result.skipped = Array.from(new Set(result.skipped));
+    // Add legacy alias for backward compatibility
+    result.installed = result.created;
+    return result;
+}
+/**
+ * Normalize different input formats to a common Map structure
+ */
+function normalizeRootFileInput(input) {
+    // Already a Map
+    if (input instanceof Map) {
+        return input;
+    }
+    // PackageFile array
+    if (Array.isArray(input)) {
+        const map = new Map();
+        for (const file of input) {
+            const fileName = getPathLeaf(file.path);
+            if (fileName && isRootFile(fileName)) {
+                map.set(fileName, file.content);
+            }
+        }
+        return map;
+    }
+    // Plain object/Record
+    return new Map(Object.entries(input));
+}
+/**
+ * Check if a file name is a root file
+ */
+function isRootFile(fileName) {
+    const rootFileNames = new Set([FILE_PATTERNS.AGENTS_MD]);
+    // Add all platform root files
+    for (const platform of getAllPlatforms()) {
+        const def = getPlatformDefinition(platform);
+        if (def.rootFile) {
+            rootFileNames.add(def.rootFile);
+        }
+    }
+    return rootFileNames.has(fileName);
+}
+/**
+ * Install universal AGENTS.md file
+ */
+async function installUniversalAgentsFile(cwd, packageName, rootFilesMap, result) {
+    const agentsContent = rootFilesMap.get(FILE_PATTERNS.AGENTS_MD);
+    if (!agentsContent || !agentsContent.trim()) {
+        return;
+    }
+    try {
+        const targetPath = join(cwd, FILE_PATTERNS.AGENTS_MD);
+        const wasUpdated = await installSingleRootFile(targetPath, packageName, agentsContent.trim());
+        if (wasUpdated) {
+            result.updated.push(FILE_PATTERNS.AGENTS_MD);
+        }
+        else {
+            result.created.push(FILE_PATTERNS.AGENTS_MD);
+        }
+    }
+    catch (error) {
+        logger.error(`Failed to install universal root file ${FILE_PATTERNS.AGENTS_MD}: ${error}`);
+        result.skipped.push(FILE_PATTERNS.AGENTS_MD);
+    }
+}
+/**
+ * Install platform-specific root files
+ */
+async function installPlatformRootFiles(cwd, packageName, rootFilesMap, platforms, result) {
+    for (const platform of platforms) {
+        const platformDef = getPlatformDefinition(platform);
+        if (!platformDef.rootFile) {
+            continue; // Platform doesn't use root files
+        }
+        // Skip if already handled by universal AGENTS.md
+        if (platformDef.rootFile === FILE_PATTERNS.AGENTS_MD) {
+            continue;
+        }
+        // Prefer platform-specific file, fallback to AGENTS.md
+        let content = rootFilesMap.get(platformDef.rootFile);
+        let sourceFileName = platformDef.rootFile;
+        if (!content && rootFilesMap.has(FILE_PATTERNS.AGENTS_MD)) {
+            content = rootFilesMap.get(FILE_PATTERNS.AGENTS_MD);
+            sourceFileName = FILE_PATTERNS.AGENTS_MD;
+        }
+        if (!content || !content.trim()) {
+            continue;
+        }
+        try {
+            const targetPath = join(cwd, platformDef.rootFile);
+            const wasUpdated = await installSingleRootFile(targetPath, packageName, content.trim());
+            if (wasUpdated) {
+                result.updated.push(platformDef.rootFile);
+            }
+            else {
+                result.created.push(platformDef.rootFile);
+            }
+        }
+        catch (error) {
+            logger.error(`Failed to install root file ${platformDef.rootFile}: ${error}`);
+            result.skipped.push(platformDef.rootFile);
+        }
+    }
+}
+/**
+ * Install or update a single root file
+ * @returns true if file was updated (existed before), false if newly created
+ */
+async function installSingleRootFile(targetPath, packageName, sectionBody) {
+    // Read existing content if file exists
+    let existingContent = '';
+    let fileExists = false;
+    if (await exists(targetPath)) {
+        existingContent = await readTextFile(targetPath);
+        fileExists = true;
+    }
+    // Check if section content is unchanged (optimization)
+    if (fileExists) {
+        const existingSectionContent = extractPackageContentFromRootFile(existingContent, packageName)?.trim();
+        if (existingSectionContent === sectionBody) {
+            return true; // Still counts as "updated" (touched but unchanged)
+        }
+    }
+    // Merge package content into the file
+    const mergedContent = mergePackageContentIntoRootFile(existingContent, packageName, sectionBody);
+    // Write the merged content
+    await writeTextFile(targetPath, mergedContent);
+    return fileExists;
+}
+//# sourceMappingURL=root-files.js.map

package/packages/core/dist/core/install/operations/root-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-files.js","sourceRoot":"","sources":["../../../../src/core/install/operations/root-files.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/core/install/orchestrator/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { InstallOrchestrator, createOrchestrator } from './orchestrator.js';
+export { checkSubsumption, resolveSubsumption } from './subsumption-resolver.js';
+export type { SubsumptionResult, SubsumptionUpgrade, SubsumptionAlreadyCovered } from './subsumption-resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/core/install/orchestrator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/install/orchestrator/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACjF,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC"}

package/packages/core/dist/core/install/orchestrator/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { InstallOrchestrator, createOrchestrator } from './orchestrator.js';
+export { checkSubsumption, resolveSubsumption } from './subsumption-resolver.js';
+//# sourceMappingURL=index.js.map

package/packages/core/dist/core/install/orchestrator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/install/orchestrator/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}