@hubspot/project-parsing-lib 0.13.0 → 0.14.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/project-parsing-lib",
-    "version": "0.13.0",
+    "version": "0.14.0-beta.0",
     "description": "Parsing library for converting projects directory structures to their intermediate representation",
     "license": "Apache-2.0",
     "type": "module",
@@ -40,15 +40,20 @@
         "./uid": {
             "import": "./src/exports/uid.js",
             "types": "./src/exports/uid.d.ts"
+        },
+        "./workspaces": {
+            "import": "./src/exports/workspaces.js",
+            "types": "./src/exports/workspaces.d.ts"
         }
     },
     "devDependencies": {
         "@hubspot/npm-scripts": "0.0.6",
         "@inquirer/prompts": "^7.1.0",
         "@types/node": "^24.9.0",
+        "@types/npm-packlist": "7.0.3",
         "@types/semver": "^7.5.8",
-        "@typescript-eslint/eslint-plugin": "8.46.3",
-        "@typescript-eslint/parser": "8.46.3",
+        "@typescript-eslint/eslint-plugin": "8.54.0",
+        "@typescript-eslint/parser": "8.54.0",
         "eslint": "^9.38.0",
         "eslint-plugin-import": "^2.31.0",
         "husky": "^9.1.7",
@@ -62,7 +67,9 @@
     "dependencies": {
         "@hubspot/local-dev-lib": "4.0.4",
         "ajv": "8.18.0",
-        "ajv-formats": "3.0.1"
+        "ajv-formats": "3.0.1",
+        "glob": "13.0.0",
+        "npm-packlist": "8.0.1"
     },
     "scripts": {
         "build": "tsx ./scripts/build.ts",

package/src/exports/projects.d.ts

@@ -1,3 +1,4 @@
 export { getProjectMetadata } from '../lib/project.js';
 export { projectContainsHsMetaFiles } from '../lib/files.js';
 export type { ProjectMetadata } from '../lib/project.js';
+export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isUnifiedProject, } from '../lib/platformVersion.js';

package/src/exports/projects.js

@@ -1,2 +1,3 @@
 export { getProjectMetadata } from '../lib/project.js';
 export { projectContainsHsMetaFiles } from '../lib/files.js';
+export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isUnifiedProject, } from '../lib/platformVersion.js';

package/src/exports/workspaces.d.ts

@@ -0,0 +1,2 @@
+export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, } from '../lib/workspaces.js';
+export type { ParsedPackageJson, WorkspaceMapping, FileDependencyMapping, } from '../lib/workspaces.js';

package/src/exports/workspaces.js

@@ -0,0 +1 @@
+export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, } from '../lib/workspaces.js';

package/src/lang/copy.d.ts

@@ -13,6 +13,7 @@ export declare const errorMessages: {
         duplicateComponent: (componentType: string) => string;
         noPackageJsonForServerless: (appFunctionsPackageFile: string) => string;
         fileContentMissingFor: (file: string) => string;
+        unsupportedPlatformVersion: (platformVersion: string) => string;
     };
     profile: {
         noProfileSpecified: string;

package/src/lang/copy.js

@@ -14,6 +14,7 @@ export const errorMessages = {
         duplicateComponent: (componentType) => `Only one ${componentType} component is allowed`,
         noPackageJsonForServerless: (appFunctionsPackageFile) => `${appFunctionsPackageFile} does not exist. ${Components[APP_FUNCTIONS_KEY].userFriendlyName} requires a ${PACKAGE_JSON} file to exist in this location`,
         fileContentMissingFor: (file) => `File content is missing for ${file}`,
+        unsupportedPlatformVersion: (platformVersion) => `Unsupported platform version: '${platformVersion}'`,
     },
     profile: {
         noProfileSpecified: 'No profile specified',

package/src/lib/constants.d.ts

@@ -1,3 +1,11 @@
+export declare const PLATFORM_VERSIONS: {
+    v2023_2: string;
+    v2025_1: string;
+    v2025_2: string;
+    v2026_03_BETA: string;
+    v2026_03: string;
+    UNSTABLE: string;
+};
 import { Components as ComponentsTopLevel } from './types.js';
 export declare const APP_KEY = "app";
 export declare const THEME_KEY = "theme";

package/src/lib/constants.js

@@ -1,3 +1,12 @@
+// Project Platform Versions
+export const PLATFORM_VERSIONS = {
+    v2023_2: '2023.2',
+    v2025_1: '2025.1',
+    v2025_2: '2025.2',
+    v2026_03_BETA: '2026.03-beta',
+    v2026_03: '2026.03',
+    UNSTABLE: 'unstable',
+};
 // Top Level Component types
 import * as path from 'path';
 // Component types

package/src/lib/minimalArboristTree.d.ts

@@ -0,0 +1,118 @@
+/**
+ * MINIMAL ARBORIST TREE
+ *
+ * This module provides a lightweight alternative to @npmcli/arborist for use
+ * with npm-packlist. Instead of importing the full arborist package (~3.4MB
+ * with 35+ transitive dependencies), we create a minimal tree object that
+ * satisfies npm-packlist's runtime requirements.
+ *
+ * WHY THIS EXISTS:
+ * - @npmcli/arborist adds ~3.4MB to the bundle
+ * - npm-packlist only uses a small subset of the Arborist Node interface
+ * - For our use case (determining packable files in workspace directories),
+ *   we don't need the full dependency resolution capabilities of arborist
+ *
+ * CONTEXT: HUBSPOT DEVELOPER PROJECTS UPLOAD FLOW
+ *
+ * This library is used to collect files from npm workspace packages for upload
+ * to HubSpot's build system. Important constraints:
+ *
+ * - node_modules/ directories are EXCLUDED from uploads
+ * - The build system runs `npm install` to fetch dependencies
+ * - Source files, package.json, and config files are included
+ *
+ * This means bundleDependencies (which includes files from node_modules/) would
+ * not work even if we used full arborist, because node_modules/ is excluded
+ * from the upload archive. Developers with private registry packages should use
+ * file: dependencies instead, which ARE supported.
+ *
+ * HOW NPM-PACKLIST USES THE TREE (as of npm-packlist@8.0.1):
+ *
+ *   tree.path              - Directory path (REQUIRED)
+ *   tree.package           - Parsed package.json content (REQUIRED)
+ *     .files               - Files array for inclusion
+ *     .main                - Main entry point (always included)
+ *     .bin                 - Binary files (always included)
+ *     .browser             - Browser field (always included)
+ *     .bundleDependencies  - Only used when isProjectRoot=true
+ *     .dependencies        - Only used when isProjectRoot=true
+ *     .optionalDependencies - Only used when isProjectRoot=true
+ *   tree.workspaces        - Map of workspace paths (OPTIONAL, guarded by if-check)
+ *   tree.isProjectRoot     - Boolean for bundled deps handling (OPTIONAL)
+ *   tree.edgesOut          - Dependency edges (only accessed when isProjectRoot=true)
+ *
+ * KNOWN LIMITATIONS:
+ *
+ * 1. BUNDLED DEPENDENCIES NOT SUPPORTED
+ *    We set isProjectRoot=false, which skips bundled dependency handling.
+ *    If a workspace package has "bundleDependencies" in package.json, those
+ *    files will NOT be included in the packlist result.
+ *
+ *    NOTE: This would not work anyway because bundleDependencies includes files
+ *    from node_modules/, and node_modules/ is excluded from project uploads.
+ *    Even with full arborist, bundled dependencies would be filtered out.
+ *    Developers needing to include private/local packages should use file:
+ *    dependencies instead (e.g., "my-pkg": "file:../my-pkg").
+ *
+ * 2. WORKSPACE-AWARE FILTERING DISABLED
+ *    We set workspaces=null, so npm-packlist won't exclude workspace
+ *    directories. This is fine for our use case since we process each
+ *    workspace independently.
+ *
+ * 3. VERSION COUPLING
+ *    This minimal interface is based on npm-packlist@8.0.1. Future versions
+ *    may access additional properties, causing runtime errors. If packlist
+ *    behavior changes unexpectedly, check for new property accesses:
+ *
+ *      grep -E "this\.tree\." node_modules/npm-packlist/lib/index.js
+ *
+ * DEBUGGING:
+ *
+ * If getPackableFiles() returns unexpected results:
+ *
+ * 1. Check if npm-packlist version changed (package.json)
+ * 2. Compare tree property accesses (grep command above)
+ * 3. Test with full arborist to isolate the issue:
+ *
+ *      import Arborist from '@npmcli/arborist';
+ *      const arb = new Arborist({ path: dir });
+ *      const tree = await arb.loadActual();
+ *      const files = await packlist(tree);
+ *
+ * 4. If full arborist works but minimal tree doesn't, add the missing
+ *    properties to MinimalArboristTree interface and createMinimalTree()
+ */
+/**
+ * Minimal subset of package.json fields used by npm-packlist
+ */
+interface PackageJsonForPacklist {
+    name?: string;
+    files?: string[];
+    main?: string;
+    bin?: string | Record<string, string>;
+    browser?: string | Record<string, string>;
+    bundleDependencies?: string[];
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+}
+/**
+ * Minimal tree interface that satisfies npm-packlist's runtime requirements.
+ * This is NOT the full Arborist Node interface - only the properties that
+ * npm-packlist actually accesses at runtime.
+ */
+export interface MinimalArboristTree {
+    path: string;
+    package: PackageJsonForPacklist;
+    workspaces: null;
+    isProjectRoot: false;
+    edgesOut: Map<string, unknown>;
+}
+/**
+ * Creates a minimal tree object that satisfies npm-packlist's requirements
+ * without importing the heavy @npmcli/arborist package.
+ *
+ * @param dir - Directory containing the package
+ * @returns Minimal tree object compatible with npm-packlist
+ */
+export declare function createMinimalTree(dir: string): MinimalArboristTree;
+export {};

package/src/lib/minimalArboristTree.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Creates a minimal tree object that satisfies npm-packlist's requirements
+ * without importing the heavy @npmcli/arborist package.
+ *
+ * @param dir - Directory containing the package
+ * @returns Minimal tree object compatible with npm-packlist
+ */
+export function createMinimalTree(dir) {
+    let pkgJson = {};
+    try {
+        const content = fs.readFileSync(path.join(dir, 'package.json'), 'utf8');
+        pkgJson = JSON.parse(content);
+    }
+    catch {
+        // Use empty package.json if not found or invalid
+        // npm-packlist handles this gracefully
+    }
+    return {
+        path: dir,
+        package: pkgJson,
+        // Set to null to skip workspace-aware filtering
+        // (we process each workspace independently)
+        workspaces: null,
+        // Set to false to skip bundled dependency handling
+        // (not needed for workspace file collection)
+        isProjectRoot: false,
+        // Empty map - only accessed when isProjectRoot is true
+        edgesOut: new Map(),
+    };
+}

package/src/lib/platformVersion.d.ts

@@ -0,0 +1,3 @@
+export declare const LATEST_SUPPORTED_PLATFORM_VERSION: string;
+export declare function isSupportedPlatformVersion(platformVersion?: string | null): boolean;
+export declare function isUnifiedProject(platformVersion?: string | null): boolean;

package/src/lib/platformVersion.js

@@ -0,0 +1,20 @@
+import { PLATFORM_VERSIONS } from './constants.js';
+// Used for logging suggestions to users whenever we encouter an unknown version
+export const LATEST_SUPPORTED_PLATFORM_VERSION = PLATFORM_VERSIONS.v2026_03;
+// We are unable to reliably interact versions of projects that are not officially supported by this library
+export function isSupportedPlatformVersion(platformVersion) {
+    if (!platformVersion || typeof platformVersion !== 'string') {
+        return false;
+    }
+    const supportedPlatformVersions = Object.values(PLATFORM_VERSIONS);
+    return supportedPlatformVersions.includes(platformVersion);
+}
+export function isUnifiedProject(platformVersion) {
+    if (!isSupportedPlatformVersion(platformVersion)) {
+        return false;
+    }
+    const [year, minor] = platformVersion.split(/[.-]/);
+    const yearNum = Number(year);
+    const minorNum = Number(minor);
+    return (yearNum === 2025 && minorNum >= 2) || yearNum > 2025;
+}

package/src/lib/translate.js

@@ -3,18 +3,23 @@ import { validateIntermediateRepresentation } from './validation.js';
 import { getIntermediateRepresentation, getParsingErrors, transform, } from './transform.js';
 import { errorMessages } from '../lang/copy.js';
 import { getLocalDevProfileData, getLocalDevProjectNodes, getRemovedNodesAndNodesWithErrors, } from './localDev.js';
+import { isSupportedPlatformVersion } from './platformVersion.js';
 const defaultOptions = {
     skipValidation: false,
 };
 export async function translate(translationContext, translationOptions = defaultOptions) {
-    const { skipValidation } = translationOptions;
+    const { skipValidation, profile } = translationOptions;
+    if (!skipValidation &&
+        !isSupportedPlatformVersion(translationContext.platformVersion)) {
+        throw new Error(errorMessages.project.unsupportedPlatformVersion(translationContext.platformVersion));
+    }
     const metafileContents = await loadHsMetaFiles(translationContext);
     if (metafileContents.length === 0) {
         throw new Error(errorMessages.project.noHsMetaFiles);
     }
     let hsProfileContents;
-    if (translationOptions.profile) {
-        hsProfileContents = loadHsProfileFile(translationContext.projectSourceDir, translationOptions.profile);
+    if (profile) {
+        hsProfileContents = loadHsProfileFile(translationContext.projectSourceDir, profile);
     }
     const transformations = transform(metafileContents, translationContext, hsProfileContents);
     const intermediateRepresentation = getIntermediateRepresentation(transformations, hsProfileContents, skipValidation);
@@ -25,21 +30,26 @@ export async function translate(translationContext, translationOptions = default
     return intermediateRepresentation;
 }
 export async function translateForLocalDev(translationContext, translationOptions) {
+    const { skipValidation, profile, projectNodesAtLastUpload } = translationOptions || {};
+    if (!skipValidation &&
+        !isSupportedPlatformVersion(translationContext.platformVersion)) {
+        throw new Error(errorMessages.project.unsupportedPlatformVersion(translationContext.platformVersion));
+    }
     const metafileContents = await loadHsMetaFiles(translationContext);
     if (metafileContents.length === 0) {
         throw new Error(errorMessages.project.noHsMetaFiles);
     }
     let hsProfileContents;
-    if (translationOptions?.profile) {
-        hsProfileContents = loadHsProfileFile(translationContext.projectSourceDir, translationOptions.profile);
+    if (profile) {
+        hsProfileContents = loadHsProfileFile(translationContext.projectSourceDir, profile);
     }
     const transformation = transform(metafileContents, translationContext, hsProfileContents);
     const baseIntermediateRepresentation = getIntermediateRepresentation(transformation, hsProfileContents, true);
     const parsingErrors = getParsingErrors(transformation);
-    const projectNodes = getLocalDevProjectNodes(baseIntermediateRepresentation.intermediateNodesIndexedByUid, translationContext.projectSourceDir, translationOptions?.projectNodesAtLastUpload);
+    const projectNodes = getLocalDevProjectNodes(baseIntermediateRepresentation.intermediateNodesIndexedByUid, translationContext.projectSourceDir, projectNodesAtLastUpload);
     let projectNodesWithErrors = {};
-    if (translationOptions?.projectNodesAtLastUpload) {
-        projectNodesWithErrors = getRemovedNodesAndNodesWithErrors(baseIntermediateRepresentation.intermediateNodesIndexedByUid, translationOptions.projectNodesAtLastUpload, parsingErrors);
+    if (projectNodesAtLastUpload) {
+        projectNodesWithErrors = getRemovedNodesAndNodesWithErrors(baseIntermediateRepresentation.intermediateNodesIndexedByUid, projectNodesAtLastUpload, parsingErrors);
     }
     const profileData = getLocalDevProfileData(baseIntermediateRepresentation.profileData?.vars.profileVariables);
     return {

package/src/lib/types.d.ts

@@ -74,7 +74,7 @@ export interface TranslationOptions {
     skipValidation?: boolean;
     profile?: string;
 }
-export interface TranslationOptionsLocalDev extends Omit<TranslationOptions, 'skipValidation'> {
+export interface TranslationOptionsLocalDev extends TranslationOptions {
     projectNodesAtLastUpload?: {
         [key: string]: IntermediateRepresentationNodeLocalDev;
     };

package/src/lib/workspaces.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Error thrown when a workspace directory cannot be resolved
+ */
+export declare class WorkspaceResolutionError extends Error {
+    workspaceDir: string;
+    sourcePackageJson: string;
+    constructor(workspaceDir: string, sourcePackageJson: string, cause?: Error);
+}
+/**
+ * Error thrown when a file: dependency cannot be resolved
+ */
+export declare class FileDependencyResolutionError extends Error {
+    packageName: string;
+    dependencyPath: string;
+    sourcePackageJson: string;
+    constructor(packageName: string, dependencyPath: string, sourcePackageJson: string, cause?: Error);
+}
+interface PackageJson {
+    name?: string;
+    workspaces?: string[] | {
+        packages?: string[];
+        nohoist?: string[];
+    };
+    dependencies?: Record<string, string>;
+}
+export interface ParsedPackageJson {
+    path: string;
+    dir: string;
+    content: PackageJson | null;
+}
+export interface WorkspaceMapping {
+    workspaceDir: string;
+    sourcePackageJsonPath: string;
+}
+export interface FileDependencyMapping {
+    packageName: string;
+    localPath: string;
+    sourcePackageJsonPath: string;
+}
+/**
+ * Finds and parses all package.json files in a directory.
+ * This is the single entry point for discovering package.json files and parsing their contents.
+ */
+export declare function findAndParsePackageJsonFiles(srcDir: string): Promise<ParsedPackageJson[]>;
+/**
+ * Resolves workspace glob patterns to actual directories
+ */
+export declare function resolveWorkspaceDirectories(baseDir: string, workspaceGlobs: string[]): Promise<string[]>;
+/**
+ * Collects all workspace directories that need to be uploaded.
+ * Handles edge cases like circular references, symlinks, and overlapping paths.
+ * Returns mappings that track which package.json defined each workspace.
+ */
+export declare function collectWorkspaceDirectories(parsedPackageJsons: ParsedPackageJson[]): Promise<WorkspaceMapping[]>;
+/**
+ * Collects all file: dependencies that need to be uploaded.
+ * Returns mappings that track the package name, resolved path, and source package.json.
+ */
+export declare function collectFileDependencies(parsedPackageJsons: ParsedPackageJson[]): Promise<FileDependencyMapping[]>;
+/**
+ * Returns the set of files that npm would include when publishing a package.
+ * Uses npm-packlist which respects the "files" field in package.json,
+ * .npmignore, and .gitignore rules.
+ *
+ * @throws Error if packlist fails to generate the file list
+ */
+export declare function getPackableFiles(dir: string): Promise<Set<string>>;
+export {};

package/src/lib/workspaces.js

@@ -0,0 +1,290 @@
+import fs from 'fs';
+import fsPromises from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { glob } from 'glob';
+import packlist from 'npm-packlist';
+import { logger } from '@hubspot/local-dev-lib/logger';
+import { walk } from '@hubspot/local-dev-lib/fs';
+import { createMinimalTree } from './minimalArboristTree.js';
+/**
+ * Error thrown when a workspace directory cannot be resolved
+ */
+export class WorkspaceResolutionError extends Error {
+    workspaceDir;
+    sourcePackageJson;
+    constructor(workspaceDir, sourcePackageJson, cause) {
+        super(`Failed to resolve workspace directory "${workspaceDir}" declared in ${sourcePackageJson}${cause ? `: ${cause.message}` : ''}`);
+        this.workspaceDir = workspaceDir;
+        this.sourcePackageJson = sourcePackageJson;
+        this.name = 'WorkspaceResolutionError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * Error thrown when a file: dependency cannot be resolved
+ */
+export class FileDependencyResolutionError extends Error {
+    packageName;
+    dependencyPath;
+    sourcePackageJson;
+    constructor(packageName, dependencyPath, sourcePackageJson, cause) {
+        super(`Failed to resolve file: dependency "${packageName}" at path "${dependencyPath}" declared in ${sourcePackageJson}${cause ? `: ${cause.message}` : ''}`);
+        this.packageName = packageName;
+        this.dependencyPath = dependencyPath;
+        this.sourcePackageJson = sourcePackageJson;
+        this.name = 'FileDependencyResolutionError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * Expands tilde (~) in paths to the user's home directory
+ */
+function expandTildePath(filePath) {
+    return filePath.startsWith('~')
+        ? path.join(os.homedir(), filePath.slice(1))
+        : filePath;
+}
+/**
+ * Finds and parses all package.json files in a directory.
+ * This is the single entry point for discovering package.json files and parsing their contents.
+ */
+export async function findAndParsePackageJsonFiles(srcDir) {
+    const allFiles = await walk(srcDir, ['node_modules']);
+    const packageJsonPaths = allFiles.filter(file => path.basename(file) === 'package.json');
+    return packageJsonPaths.map(filePath => {
+        try {
+            return {
+                path: filePath,
+                dir: path.dirname(filePath),
+                content: JSON.parse(fs.readFileSync(filePath, 'utf8')),
+            };
+        }
+        catch (e) {
+            logger.debug(`Failed to parse package.json at ${filePath}: ${e}`);
+            return {
+                path: filePath,
+                dir: path.dirname(filePath),
+                content: null,
+            };
+        }
+    });
+}
+/**
+ * Extracts workspace patterns from parsed package.json content
+ */
+function extractWorkspaceGlobs(packageJson) {
+    const workspaces = packageJson.workspaces;
+    if (!workspaces) {
+        return [];
+    }
+    // Handle array format: "workspaces": ["packages/*"]
+    if (Array.isArray(workspaces)) {
+        return workspaces;
+    }
+    // Handle object format: "workspaces": {"packages": ["packages/*"]}
+    if (workspaces.packages && Array.isArray(workspaces.packages)) {
+        return workspaces.packages;
+    }
+    return [];
+}
+/**
+ * Resolves workspace glob patterns to actual directories
+ */
+export async function resolveWorkspaceDirectories(baseDir, workspaceGlobs) {
+    const resolvedDirs = new Set();
+    for (const pattern of workspaceGlobs) {
+        const expandedPattern = expandTildePath(pattern);
+        const absolutePattern = path.resolve(baseDir, expandedPattern);
+        try {
+            // Use glob to find matching directories
+            const matches = await glob(absolutePattern, {
+                absolute: true,
+                withFileTypes: false,
+            });
+            // Filter to directories that contain package.json
+            for (const match of matches) {
+                try {
+                    const stats = await fsPromises.stat(match);
+                    if (stats.isDirectory()) {
+                        const packageJsonPath = path.join(match, 'package.json');
+                        try {
+                            await fsPromises.access(packageJsonPath, fs.constants.F_OK);
+                            resolvedDirs.add(match);
+                        }
+                        catch {
+                            // Directory exists but doesn't contain package.json - skip silently
+                        }
+                    }
+                }
+                catch (e) {
+                    // Inaccessible directories may indicate permission issues or broken symlinks
+                    logger.warn(`Cannot access directory ${match}: ${e}`);
+                }
+            }
+        }
+        catch (e) {
+            logger.debug(`Failed to resolve workspace pattern "${pattern}": ${e}`);
+        }
+    }
+    return Array.from(resolvedDirs);
+}
+/**
+ * Collects all workspace directories that need to be uploaded.
+ * Handles edge cases like circular references, symlinks, and overlapping paths.
+ * Returns mappings that track which package.json defined each workspace.
+ */
+export async function collectWorkspaceDirectories(parsedPackageJsons) {
+    const workspaceMappings = [];
+    // Track (sourcePackageJsonPath, workspaceDir) pairs to avoid duplicates within
+    // the same source, while still allowing the same workspace dir to appear in
+    // mappings from multiple different package.json files. This ensures every
+    // package.json that declares a workspace gets its workspaces field rewritten,
+    // regardless of whether another package.json already references the same dir.
+    const visited = new Set();
+    for (const parsed of parsedPackageJsons) {
+        if (!parsed.content) {
+            continue;
+        }
+        const workspaceGlobs = extractWorkspaceGlobs(parsed.content);
+        if (workspaceGlobs.length === 0) {
+            continue;
+        }
+        logger.debug(`Found workspaces in ${parsed.path}: ${workspaceGlobs.join(', ')}`);
+        const resolved = await resolveWorkspaceDirectories(parsed.dir, workspaceGlobs);
+        for (const dir of resolved) {
+            // Resolve symlinks to real path
+            let realDir;
+            try {
+                realDir = await fsPromises.realpath(dir);
+            }
+            catch (e) {
+                throw new WorkspaceResolutionError(dir, parsed.path, e instanceof Error ? e : undefined);
+            }
+            // Skip duplicate (source, workspace) pairs only — the same workspace dir
+            // may legitimately be referenced by multiple package.json files and each
+            // needs its own mapping so its workspaces field is rewritten correctly.
+            const pairKey = `${parsed.path}::${realDir}`;
+            if (visited.has(pairKey)) {
+                logger.debug(`Skipping duplicate workspace mapping: ${realDir} from ${parsed.path}`);
+                continue;
+            }
+            visited.add(pairKey);
+            // Include all workspaces - both internal (inside srcDir) and external.
+            // The CLI determines the archive path:
+            // - Internal: preserved as-is (already included via srcDir walk)
+            // - External: _workspaces/<name>-<hash>
+            workspaceMappings.push({
+                workspaceDir: realDir,
+                sourcePackageJsonPath: parsed.path,
+            });
+            logger.debug(`Resolved workspace: ${realDir}`);
+        }
+    }
+    return workspaceMappings;
+}
+/**
+ * Extracts file: dependencies from parsed package.json content.
+ * Only scans production dependencies since devDependencies and optionalDependencies
+ * are not needed for the build pipeline.
+ */
+function extractFileDependencies(packageJson) {
+    const fileDeps = [];
+    const deps = packageJson.dependencies;
+    if (!deps) {
+        return fileDeps;
+    }
+    for (const [packageName, version] of Object.entries(deps)) {
+        // Only handle file: dependencies. workspace: dependencies reference packages
+        // already collected via the workspaces field, so they don't need separate handling.
+        if (typeof version === 'string' && version.startsWith('file:')) {
+            const filePath = version.slice(5); // Remove 'file:' prefix
+            fileDeps.push({ packageName, filePath });
+        }
+    }
+    return fileDeps;
+}
+/**
+ * Collects all file: dependencies that need to be uploaded.
+ * Returns mappings that track the package name, resolved path, and source package.json.
+ */
+export async function collectFileDependencies(parsedPackageJsons) {
+    const fileDependencyMappings = [];
+    const visited = new Set();
+    for (const parsed of parsedPackageJsons) {
+        if (!parsed.content) {
+            continue;
+        }
+        const fileDeps = extractFileDependencies(parsed.content);
+        if (fileDeps.length === 0) {
+            continue;
+        }
+        logger.debug(`Found file: dependencies in ${parsed.path}: ${fileDeps.map(d => d.packageName).join(', ')}`);
+        for (const { packageName, filePath } of fileDeps) {
+            const expandedPath = expandTildePath(filePath);
+            const absolutePath = path.resolve(parsed.dir, expandedPath);
+            // Resolve symlinks to real path
+            let realPath;
+            try {
+                realPath = await fsPromises.realpath(absolutePath);
+            }
+            catch (e) {
+                throw new FileDependencyResolutionError(packageName, absolutePath, parsed.path, e instanceof Error ? e : undefined);
+            }
+            // Verify it's a directory with a package.json
+            const stats = await fsPromises.stat(realPath);
+            if (!stats.isDirectory()) {
+                throw new FileDependencyResolutionError(packageName, realPath, parsed.path, new Error('Path is not a directory'));
+            }
+            const depPackageJsonPath = path.join(realPath, 'package.json');
+            try {
+                await fsPromises.access(depPackageJsonPath, fs.constants.F_OK);
+            }
+            catch {
+                throw new FileDependencyResolutionError(packageName, realPath, parsed.path, new Error('Directory does not contain package.json'));
+            }
+            // Skip if already visited (same path referenced multiple times)
+            if (visited.has(realPath)) {
+                logger.debug(`Skipping already visited file: dependency: ${realPath}`);
+                continue;
+            }
+            visited.add(realPath);
+            // Include all file: dependencies - both internal (inside srcDir) and external
+            // The CLI determines the archive path:
+            // - Internal: _workspaces/<relative-path>
+            // - External: _workspaces/external/<name>-<hash>
+            fileDependencyMappings.push({
+                packageName,
+                localPath: realPath,
+                sourcePackageJsonPath: parsed.path,
+            });
+            logger.debug(`Resolved file: dependency ${packageName}: ${realPath}`);
+        }
+    }
+    return fileDependencyMappings;
+}
+/**
+ * Returns the set of files that npm would include when publishing a package.
+ * Uses npm-packlist which respects the "files" field in package.json,
+ * .npmignore, and .gitignore rules.
+ *
+ * @throws Error if packlist fails to generate the file list
+ */
+export async function getPackableFiles(dir) {
+    try {
+        const tree = createMinimalTree(dir);
+        // Cast to Parameters<typeof packlist>[0] since npm-packlist only uses
+        // a subset of the Arborist Node properties at runtime
+        const files = await packlist(tree);
+        return new Set(files);
+    }
+    catch (e) {
+        const errorMessage = `Failed to get packlist for ${dir}: ${e instanceof Error ? e.message : String(e)}`;
+        logger.error(errorMessage);
+        throw new Error(errorMessage, { cause: e });
+    }
+}