Package Import and Linking

/**
 * Imports a package using the worker pool with concurrency limit
 * @param opts - Import configuration options (excludes 'type' from LinkPkgMessage)
 * @returns Promise resolving to import results with build status
 */
function importPackage(opts: Omit<LinkPkgMessage, 'type'>): Promise<ImportPackageResult>;

interface LinkPkgMessage {
  type: 'link';
  /** Store directory path where package files are located */
  storeDir: string;
  /** Import method to use for package installation */
  packageImportMethod?: 'auto' | 'hardlink' | 'copy' | 'clone' | 'clone-or-copy';
  /** Package files response containing file metadata */
  filesResponse: PackageFilesResponse;
  /** Optional cache key for side effects */
  sideEffectsCacheKey?: string | undefined;
  /** Target directory where package should be installed */
  targetDir: string;
  /** Whether the package requires a build step */
  requiresBuild?: boolean;
  /** Force import even if target already exists */
  force: boolean;
  /** Keep existing modules directory */
  keepModulesDir?: boolean;
  /** Disable relinking of local directory dependencies */
  disableRelinkLocalDirDeps?: boolean;
}

interface ImportPackageResult {
  /** Whether the package was built during import */
  isBuilt: boolean;
  /** Actual import method used (may differ from requested method) */
  importMethod: string | undefined;
}

import { importPackage } from "@pnpm/worker";

// Basic package import with auto method selection
const result = await importPackage({
  storeDir: "/path/to/pnpm/store",
  filesResponse: {
    /* PackageFilesResponse data */
  },
  targetDir: "/project/node_modules/lodash",
  force: false
});

console.log("Package imported with method:", result.importMethod);
console.log("Package was built:", result.isBuilt);

// Import with specific method and build requirements
const buildResult = await importPackage({
  storeDir: "/path/to/store",
  packageImportMethod: "hardlink",
  filesResponse: packageFiles,
  targetDir: "/project/node_modules/native-package",
  requiresBuild: true,
  force: true,
  keepModulesDir: true
});

/**
 * Creates symbolic links for all modules in dependencies
 * @param opts - Symlinking configuration options (excludes 'type' from SymlinkAllModulesMessage)
 * @returns Promise resolving to symlinking results
 */
function symlinkAllModules(opts: Omit<SymlinkAllModulesMessage, 'type'>): Promise<ImportPackageResult>;

interface SymlinkAllModulesMessage {
  type: 'symlinkAllModules';
  /** Array of dependencies to create symlinks for */
  deps: Array<{
    /** Child dependencies mapping alias to package directory */
    children: Record<string, string>;
    /** Modules directory path */
    modules: string;
    /** Dependency name */
    name: string;
  }>;
}

import { symlinkAllModules } from "@pnpm/worker";

// Create symlinks for multiple dependencies
const symlinkResult = await symlinkAllModules({
  deps: [
    {
      name: "express",
      modules: "/project/node_modules",
      children: {
        "body-parser": "/store/body-parser/1.19.0",
        "cookie-parser": "/store/cookie-parser/1.4.5",
        "debug": "/store/debug/4.3.2"
      }
    },
    {
      name: "lodash",
      modules: "/project/node_modules",
      children: {}
    }
  ]
});

console.log("Symlinks created successfully");

/**
 * Reads package from content-addressable file system store
 * @param storeDir - Store directory path
 * @param verifyStoreIntegrity - Whether to verify file integrity
 * @param filesIndexFile - Path to files index file
 * @param readManifest - Whether to read package manifest
 * @returns Promise resolving to package read results
 */
function readPkgFromCafs(
  storeDir: string,
  verifyStoreIntegrity: boolean,
  filesIndexFile: string,
  readManifest?: boolean
): Promise<ReadPkgFromCafsResult>;

interface ReadPkgFromCafsResult {
  /** Whether integrity verification passed */
  verified: boolean;
  /** Package files index metadata */
  pkgFilesIndex: PackageFilesIndex;
  /** Package manifest if requested and available */
  manifest?: DependencyManifest;
  /** Whether the package requires a build step */
  requiresBuild: boolean;
}

import { readPkgFromCafs } from "@pnpm/worker";

// Read package with integrity verification
const packageData = await readPkgFromCafs(
  "/path/to/pnpm/store",
  true, // verify integrity
  "/path/to/package/index.json",
  true  // read manifest
);

if (packageData.verified) {
  console.log("Package integrity verified");
  console.log("Package name:", packageData.manifest?.name);
  console.log("Requires build:", packageData.requiresBuild);
} else {
  console.log("Package integrity check failed - refetch required");
}

// Quick read without verification
const quickRead = await readPkgFromCafs(
  "/path/to/store",
  false, // skip verification
  "/path/to/index.json"
);

// Error handling for exFAT drives
try {
  await symlinkAllModules({
    deps: [/* dependencies */]
  });
} catch (error) {
  if (error.code === 'EISDIR' && error.message.includes('exFAT')) {
    console.error('ExFAT drive detected - symlinks not supported');
    console.log('Consider setting node-linker to "hoisted"');
  }
}

interface PackageFilesResponse {
  /** File integrity information and metadata */
  files: Record<string, FileInfo>;
  /** Additional package metadata */
  [key: string]: any;
}

interface FileInfo {
  /** File integrity hash */
  integrity: string;
  /** File permissions mode */
  mode: number;
  /** File size in bytes */
  size: number;
  /** Timestamp when file was last checked */
  checkedAt?: number;
}