@hubspot/cli 8.0.11-experimental.0 → 8.0.11-experimental.2

package/lib/projects/projectInfo.js

@@ -1,15 +1,11 @@
-import React from 'react';
+import chalk from 'chalk';
 import { fetchAppMetadataBySourceId } from '@hubspot/local-dev-lib/api/appsDev';
+import { APP_KEY, USER_FACING_TO_INTERNAL_TYPE, } from '@hubspot/project-parsing-lib/constants';
 import { debugError } from '../errorHandlers/index.js';
 import { getProjectDetailUrl } from './urls.js';
 import { commands } from '../../lang/en.js';
-import { uiLink } from '../ui/index.js';
-import { renderInline } from '../../ui/render.js';
-import { getBoxWithTitle } from '../../ui/components/BoxWithTitle.js';
-import { getTable } from '../../ui/components/Table.js';
-import { mapTableDataToObjects } from '../../ui/lib/table.js';
-import { INK_COLORS } from '../../ui/styles.js';
-const APPLICATION_BUILD_TYPE = 'APPLICATION';
+import { uiLine, uiLink } from '../ui/index.js';
+import { uiLogger } from '../ui/logger.js';
 export async function getProjectInfo(project, platformVersion, accountId) {
     const deployedBuild = project.deployedBuild;
     const projectInfo = {
@@ -24,7 +20,7 @@ export async function getProjectInfo(project, platformVersion, accountId) {
     if (projectUrl) {
         projectInfo.projectUrl = projectUrl;
     }
-    const appSubbuild = deployedBuild.subbuildStatuses.find(s => s.buildType === APPLICATION_BUILD_TYPE);
+    const appSubbuild = deployedBuild.subbuildStatuses.find(s => s.buildType === USER_FACING_TO_INTERNAL_TYPE[APP_KEY]);
     if (appSubbuild) {
         try {
             const { data: appMetadata } = await fetchAppMetadataBySourceId(project.id, appSubbuild.buildName, accountId);
@@ -41,64 +37,46 @@ export async function getProjectInfo(project, platformVersion, accountId) {
         }
     }
     projectInfo.components = deployedBuild.subbuildStatuses
-        .filter(s => s.buildType !== APPLICATION_BUILD_TYPE)
+        .filter(s => s.buildType !== USER_FACING_TO_INTERNAL_TYPE[APP_KEY])
         .map(s => ({
-        uid: s.userDefinedId ||
-            s.buildName,
+        uid: s.buildName,
         type: s.buildType,
     }));
     return projectInfo;
 }
-export async function renderProjectInfo(projectInfo) {
-    const projectInfoLines = [
-        commands.project.info.project.name(projectInfo.projectName),
-        commands.project.info.project.platformVersion(projectInfo.platformVersion),
-        commands.project.info.project.id(projectInfo.projectId),
-        commands.project.info.project.deployedBuild(projectInfo.deployedBuildId),
-        commands.project.info.project.autoDeploy(projectInfo.autoDeployEnabled),
-    ];
+export function logProjectInfo(projectInfo) {
+    uiLogger.log(chalk.bold(commands.project.info.project.title(projectInfo.projectName)));
+    uiLine();
+    uiLogger.log(commands.project.info.project.platformVersion(projectInfo.platformVersion));
+    uiLogger.log(commands.project.info.project.id(projectInfo.projectId));
+    uiLogger.log(commands.project.info.project.deployedBuild(projectInfo.deployedBuildId));
+    uiLogger.log(commands.project.info.project.autoDeploy(projectInfo.autoDeployEnabled));
     if (projectInfo.projectUrl) {
-        projectInfoLines.push(uiLink(commands.project.info.viewProjectLink, projectInfo.projectUrl));
+        uiLogger.log('');
+        uiLogger.log(uiLink(commands.project.info.viewProjectLink, projectInfo.projectUrl));
     }
-    const childBoxes = [];
     if (projectInfo.app) {
-        const appInfoLines = [
-            commands.project.info.app.name(projectInfo.app.name),
-            commands.project.info.app.id(projectInfo.app.id),
-            commands.project.info.app.uid(projectInfo.app.uid),
-        ];
+        uiLogger.log('');
+        uiLogger.log(chalk.bold(commands.project.info.app.title));
+        uiLine();
+        uiLogger.log(commands.project.info.app.name(projectInfo.app.name));
+        uiLogger.log(commands.project.info.app.id(projectInfo.app.id));
+        uiLogger.log(commands.project.info.app.uid(projectInfo.app.uid));
         if (projectInfo.app.authType) {
-            appInfoLines.push(commands.project.info.app.authType(projectInfo.app.authType));
+            uiLogger.log(commands.project.info.app.authType(projectInfo.app.authType));
         }
         if (projectInfo.app.distributionType) {
-            appInfoLines.push(commands.project.info.app.distributionType(projectInfo.app.distributionType));
+            uiLogger.log(commands.project.info.app.distributionType(projectInfo.app.distributionType));
         }
-        childBoxes.push(getBoxWithTitle({
-            title: commands.project.info.app.title,
-            message: appInfoLines.join('\n'),
-            titleBackgroundColor: INK_COLORS.WHITE,
-            borderColor: INK_COLORS.WHITE,
-        }));
     }
     if (projectInfo.components.length > 0) {
-        const tableHeader = [
-            commands.project.info.labels.uid,
-            commands.project.info.labels.type,
-        ];
-        const tableData = projectInfo.components.map(c => [c.uid, c.type]);
-        const tableObjects = mapTableDataToObjects(tableHeader, tableData);
-        childBoxes.push(getBoxWithTitle({
-            title: commands.project.info.componentsHeader,
-            titleBackgroundColor: INK_COLORS.WHITE,
-            borderColor: INK_COLORS.WHITE,
-            children: getTable({ data: tableObjects, borderless: true }),
-        }));
+        uiLogger.log('');
+        uiLogger.log(chalk.bold(commands.project.info.componentsHeader));
+        uiLine();
+        const typeColWidth = Math.max(commands.project.info.labels.type.length, ...projectInfo.components.map(c => c.type.length));
+        uiLogger.log(`${commands.project.info.labels.type.padEnd(typeColWidth)}   ${commands.project.info.labels.uid}`);
+        for (const component of projectInfo.components) {
+            uiLogger.log(`${component.type.padEnd(typeColWidth)}   ${component.uid}`);
+        }
     }
-    await renderInline(getBoxWithTitle({
-        title: commands.project.info.project.title,
-        message: projectInfoLines.join('\n'),
-        titleBackgroundColor: INK_COLORS.INFO_BLUE,
-        borderColor: INK_COLORS.INFO_BLUE,
-        children: React.createElement(React.Fragment, null, ...childBoxes),
-    }));
 }

package/lib/projects/projectProfiles.d.ts

@@ -3,8 +3,7 @@ import { ProjectConfig } from '../../types/Projects.js';
 export declare function logProfileHeader(profileName: string): void;
 export declare function logProfileFooter(profile: HsProfileFile, includeVariables?: boolean): void;
 export declare function loadProfile(projectConfig: ProjectConfig | null, projectDir: string | null, profileName: string): HsProfileFile | never;
-export declare function enforceProfileUsage(projectConfig: ProjectConfig | null, projectDir: string | null): Promise<void>;
-export declare function loadAndValidateProfile(projectConfig: ProjectConfig | null, projectDir: string | null, profileName: string | undefined, silent?: boolean): Promise<number | undefined>;
+export declare function loadAndValidateProfile(projectConfig: ProjectConfig | null, projectDir: string | null, profileName: string, silent?: boolean): Promise<HsProfileFile | never>;
 type ValidateProjectForProfileOptions = {
     projectConfig: ProjectConfig;
     projectDir: string;

package/lib/projects/projectProfiles.js

@@ -1,7 +1,7 @@
 import path from 'path';
-import { loadHsProfileFile, getHsProfileFilename, getAllHsProfiles, validateProfileVariables, } from '@hubspot/project-parsing-lib/profiles';
+import { loadHsProfileFile, getHsProfileFilename, validateProfileVariables, } from '@hubspot/project-parsing-lib/profiles';
 import { commands, lib } from '../../lang/en.js';
-import { indent, uiBetaTag, uiLine } from '../ui/index.js';
+import { indent, uiLine } from '../ui/index.js';
 import { uiLogger } from '../ui/logger.js';
 import { getConfigAccountById } from '@hubspot/local-dev-lib/config';
 import SpinniesManager from '../ui/SpinniesManager.js';
@@ -9,7 +9,7 @@ import { handleTranslate } from './upload.js';
 import { getErrorMessage } from '../errorHandlers/index.js';
 export function logProfileHeader(profileName) {
     uiLine();
-    uiBetaTag(lib.projectProfiles.logs.usingProfile(getHsProfileFilename(profileName)));
+    uiLogger.log(lib.projectProfiles.logs.usingProfile(getHsProfileFilename(profileName)));
     uiLogger.log('');
 }
 export function logProfileFooter(profile, includeVariables = false) {
@@ -51,19 +51,7 @@ export function loadProfile(projectConfig, projectDir, profileName) {
     }
     return profile;
 }
-export async function enforceProfileUsage(projectConfig, projectDir) {
-    if (projectConfig && projectDir) {
-        const existingProfiles = await getAllHsProfiles(path.join(projectDir, projectConfig.srcDir));
-        if (existingProfiles.length > 0) {
-            throw new Error(lib.projectProfiles.exitIfUsingProfiles.errors.noProfileSpecified);
-        }
-    }
-}
 export async function loadAndValidateProfile(projectConfig, projectDir, profileName, silent = false) {
-    if (!profileName) {
-        await enforceProfileUsage(projectConfig, projectDir);
-        return;
-    }
     if (!silent) {
         logProfileHeader(profileName);
     }
@@ -77,7 +65,7 @@ export async function loadAndValidateProfile(projectConfig, projectDir, profileN
             throw new Error(lib.projectProfiles.loadProfile.errors.profileNotValid(profileName, validationResult.errors));
         }
     }
-    return profile.accountId;
+    return profile;
 }
 function formatProfileValidationError(error, leadingIndentationLevel = 0) {
     // Trim leading whitespace and replace tabs with spaces to reducing indentations
@@ -97,7 +85,7 @@ export async function validateProjectForProfile({ projectConfig, projectDir, pro
         });
     }
     try {
-        const accountId = await loadAndValidateProfile(projectConfig, projectDir, profileName, true);
+        const { accountId } = await loadAndValidateProfile(projectConfig, projectDir, profileName, true);
         targetAccountId = accountId || derivedAccountId;
     }
     catch (error) {

package/lib/projects/upload.js

@@ -6,16 +6,18 @@ import { uploadProject } from '@hubspot/local-dev-lib/api/projects';
 import { shouldIgnoreFile } from '@hubspot/local-dev-lib/ignoreRules';
 import { isTranslationError, translate, } from '@hubspot/project-parsing-lib/translate';
 import { projectContainsHsMetaFiles } from '@hubspot/project-parsing-lib/projects';
+import { findAndParsePackageJsonFiles, collectWorkspaceDirectories, collectFileDependencies, } from '@hubspot/project-parsing-lib/workspaces';
 import SpinniesManager from '../ui/SpinniesManager.js';
 import { uiAccountDescription } from '../ui/index.js';
 import util from 'node:util';
 import { lib } from '../../lang/en.js';
 import { ensureProjectExists } from './ensureProjectExists.js';
 import { uiLogger } from '../ui/logger.js';
-import { isV2Project } from './platformVersion.js';
 import ProjectValidationError from '../errors/ProjectValidationError.js';
 import { walk } from '@hubspot/local-dev-lib/fs';
 import { LEGACY_CONFIG_FILES } from '../constants.js';
+import { archiveWorkspacesAndDependencies, getPackageJsonPathsToUpdate, getLockfilePathsToUpdate, } from './workspaces.js';
+import { isLegacyProject } from '@hubspot/project-parsing-lib/projects';
 async function uploadProjectFiles(accountId, projectName, filePath, uploadMessage, platformVersion, intermediateRepresentation) {
     const accountIdentifier = uiAccountDescription(accountId) || `${accountId}`;
     SpinniesManager.add('upload', {
@@ -48,6 +50,15 @@ export async function handleProjectUpload({ accountId, projectConfig, projectDir
     await validateNoHSMetaMismatch(srcDir, projectConfig);
     const tempFile = tmp.fileSync({ postfix: '.zip' });
     uiLogger.debug(lib.projectUpload.handleProjectUpload.compressing(tempFile.name));
+    // Collect workspace directories and file: dependencies for v2+ projects only.
+    // Versions <= 2025.1 do not support the new npm workspaces bundling behavior.
+    let workspaceMappings = [];
+    let fileDependencyMappings = [];
+    if (!isLegacyProject(projectConfig.platformVersion)) {
+        const parsedPackageJsons = await findAndParsePackageJsonFiles(srcDir);
+        workspaceMappings = await collectWorkspaceDirectories(parsedPackageJsons);
+        fileDependencyMappings = await collectFileDependencies(parsedPackageJsons);
+    }
     const output = fs.createWriteStream(tempFile.name);
     const archive = archiver('zip');
     const result = new Promise((resolve, reject) => output.on('close', async function () {
@@ -91,8 +102,14 @@ export async function handleProjectUpload({ accountId, projectConfig, projectDir
         }
     }));
     archive.pipe(output);
+    const modifiedPackageJsonPaths = getPackageJsonPathsToUpdate(srcDir, workspaceMappings, fileDependencyMappings);
+    const lockfilePathsToUpdate = getLockfilePathsToUpdate(srcDir, workspaceMappings, fileDependencyMappings);
     let loggedIgnoredNodeModule = false;
     archive.directory(srcDir, false, file => {
+        if (modifiedPackageJsonPaths.has(file.name) ||
+            lockfilePathsToUpdate.has(file.name)) {
+            return false;
+        }
         const ignored = shouldIgnoreFile(file.name, true);
         if (ignored) {
             const isNodeModule = file.name.includes('node_modules');
@@ -105,6 +122,8 @@ export async function handleProjectUpload({ accountId, projectConfig, projectDir
         }
         return ignored ? false : file;
     });
+    // Archive workspaces and file: dependencies
+    await archiveWorkspacesAndDependencies(archive, srcDir, projectDir, workspaceMappings, fileDependencyMappings);
     archive.finalize();
     return result;
 }
@@ -113,7 +132,7 @@ export async function validateSourceDirectory(srcDir, projectConfig, projectDir)
     if (!projectFilePaths || projectFilePaths.length === 0) {
         throw new ProjectValidationError(lib.projectUpload.handleProjectUpload.emptySource(projectConfig.srcDir));
     }
-    if (isV2Project(projectConfig.platformVersion)) {
+    if (!isLegacyProject(projectConfig.platformVersion)) {
         projectFilePaths.forEach(filePath => {
             const filename = path.basename(filePath);
             if (LEGACY_CONFIG_FILES.includes(filename)) {
@@ -124,7 +143,7 @@ export async function validateSourceDirectory(srcDir, projectConfig, projectDir)
 }
 export async function validateNoHSMetaMismatch(srcDir, projectConfig) {
     const hasHsMetaFiles = await projectContainsHsMetaFiles(srcDir);
-    if (!isV2Project(projectConfig.platformVersion) && hasHsMetaFiles) {
+    if (isLegacyProject(projectConfig.platformVersion) && hasHsMetaFiles) {
         throw new ProjectValidationError(lib.projectUpload.wrongPlatformVersionMetaFiles);
     }
 }

package/lib/projects/workspaces.d.ts

@@ -0,0 +1,42 @@
+import archiver from 'archiver';
+import { WorkspaceMapping, FileDependencyMapping } from '@hubspot/project-parsing-lib/workspaces';
+/**
+ * Result of archiving workspaces and file dependencies
+ */
+export type WorkspaceArchiveResult = {
+    packageWorkspaces: Map<string, string[]>;
+    packageFileDeps: Map<string, Map<string, string>>;
+};
+/**
+ * Generates a short hash of the input string for use in workspace paths.
+ * Uses SHA256 truncated to 8 hex characters (4 billion possibilities).
+ */
+export declare function shortHash(input: string): string;
+/**
+ * Determines the archive path for an external workspace or file: dependency.
+ * Produces `_workspaces/<basename>-<hash>` with no subdirectory.
+ * The hash prevents collisions between different directories with the same basename.
+ */
+export declare function computeExternalArchivePath(absolutePath: string): string;
+/**
+ * Updates package.json files in the archive to reflect new workspace and file: dependency paths.
+ *
+ * Workspace entries in packageWorkspaces are already in final form:
+ * - Internal workspaces: relative paths (e.g. "../packages/utils")
+ * - External workspaces: relative paths (e.g. "../_workspaces/logger-abc")
+ *
+ * Only external file: dependencies appear in packageFileDeps; internal ones
+ * keep their original file: references and are left untouched.
+ */
+export declare function updatePackageJsonInArchive(archive: archiver.Archiver, srcDir: string, packageWorkspaces: Map<string, string[]>, packageFileDeps: Map<string, Map<string, string>>): Promise<void>;
+export declare function rewriteLockfileForExternalDeps(lockfileContent: Record<string, unknown>, pathMappings: Array<{
+    oldPath: string;
+    newPath: string;
+}>): Record<string, unknown>;
+export declare function getPackageJsonPathsToUpdate(srcDir: string, workspaceMappings: WorkspaceMapping[], fileDependencyMappings: FileDependencyMapping[]): Set<string>;
+export declare function getLockfilePathsToUpdate(srcDir: string, workspaceMappings: WorkspaceMapping[], fileDependencyMappings: FileDependencyMapping[]): Set<string>;
+/**
+ * Main orchestration function that handles archiving of workspaces and file dependencies.
+ * This is the clean integration point for upload.ts.
+ */
+export declare function archiveWorkspacesAndDependencies(archive: archiver.Archiver, srcDir: string, projectDir: string, workspaceMappings: WorkspaceMapping[], fileDependencyMappings: FileDependencyMapping[]): Promise<WorkspaceArchiveResult>;

package/lib/projects/workspaces.js

@@ -0,0 +1,350 @@
+import fs from 'fs-extra';
+import path from 'path';
+import crypto from 'crypto';
+import { shouldIgnoreFile } from '@hubspot/local-dev-lib/ignoreRules';
+import { getPackableFiles, } from '@hubspot/project-parsing-lib/workspaces';
+import { uiLogger } from '../ui/logger.js';
+import { lib } from '../../lang/en.js';
+/**
+ * Generates a short hash of the input string for use in workspace paths.
+ * Uses SHA256 truncated to 8 hex characters (4 billion possibilities).
+ */
+export function shortHash(input) {
+    return crypto.createHash('sha256').update(input).digest('hex').slice(0, 8);
+}
+/**
+ * Determines the archive path for an external workspace or file: dependency.
+ * Produces `_workspaces/<basename>-<hash>` with no subdirectory.
+ * The hash prevents collisions between different directories with the same basename.
+ */
+export function computeExternalArchivePath(absolutePath) {
+    const resolved = path.resolve(absolutePath);
+    const name = path.basename(resolved);
+    return path.join('_workspaces', `${name}-${shortHash(resolved)}`);
+}
+/**
+ * Returns true if dir is inside srcDir (i.e. it will already be included
+ * in the archive from the srcDir walk and must not be copied again).
+ */
+function isInsideSrcDir(dir, srcDir) {
+    const rel = path.relative(path.resolve(srcDir), path.resolve(dir));
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/**
+ * Creates a file filter function for workspace archiving.
+ * Filters files based on packable files list and ignore rules.
+ */
+function createWorkspaceFileFilter(packableFiles) {
+    return (file) => {
+        if (packableFiles.size > 0 && !packableFiles.has(file.name)) {
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.fileFiltered(file.name));
+            return false;
+        }
+        const ignored = shouldIgnoreFile(file.name, true);
+        if (ignored) {
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.fileFiltered(file.name));
+            return false;
+        }
+        return file;
+    };
+}
+/**
+ * Archives workspace directories and returns mapping information.
+ *
+ * Internal workspaces (inside srcDir) are not archived — they are already
+ * included via the srcDir walk. Their relative paths (from the package.json
+ * directory to the workspace directory) are stored directly in the entries.
+ *
+ * External workspaces (outside srcDir) are copied to `_workspaces/<name>-<hash>`
+ * and their relative archive paths (e.g. `../_workspaces/<name>-<hash>`) are stored.
+ */
+async function archiveWorkspaceDirectories(archive, srcDir, workspaceMappings) {
+    const externalArchivePaths = new Map(); // resolvedDir -> archivePath
+    const archivePathToDir = new Map(); // archivePath -> resolvedDir (collision detection)
+    const packageWorkspaceEntries = new Map();
+    const externalsToArchive = [];
+    for (const mapping of workspaceMappings) {
+        const { workspaceDir, sourcePackageJsonPath } = mapping;
+        if (!packageWorkspaceEntries.has(sourcePackageJsonPath)) {
+            packageWorkspaceEntries.set(sourcePackageJsonPath, []);
+        }
+        if (isInsideSrcDir(workspaceDir, srcDir)) {
+            // Internal: already in archive from srcDir walk.
+            // Store the relative path from the package.json directory so npm can resolve it.
+            const relPath = path.relative(path.dirname(sourcePackageJsonPath), path.resolve(workspaceDir));
+            packageWorkspaceEntries.get(sourcePackageJsonPath).push(relPath);
+        }
+        else {
+            // External: archive to _workspaces/<name>-<hash>.
+            const archivePath = computeExternalArchivePath(workspaceDir);
+            const resolvedDir = path.resolve(workspaceDir);
+            // Detect hash collisions (different dirs mapping to the same archive path)
+            const existing = archivePathToDir.get(archivePath);
+            if (existing && existing !== resolvedDir) {
+                throw new Error(lib.projectUpload.handleProjectUpload.workspaceCollision(archivePath, workspaceDir, existing));
+            }
+            if (!externalArchivePaths.has(resolvedDir)) {
+                externalArchivePaths.set(resolvedDir, archivePath);
+                archivePathToDir.set(archivePath, resolvedDir);
+                externalsToArchive.push({ dir: workspaceDir, archivePath });
+            }
+            const relPkgJsonDir = path.relative(srcDir, path.dirname(sourcePackageJsonPath));
+            const relativeEntry = path.relative(relPkgJsonDir, archivePath);
+            packageWorkspaceEntries.get(sourcePackageJsonPath).push(relativeEntry);
+        }
+    }
+    // Fetch packable files in parallel (I/O optimization)
+    const withPackableFiles = await Promise.all(externalsToArchive.map(async (item) => ({
+        ...item,
+        packableFiles: await getPackableFiles(item.dir),
+    })));
+    // Archive directories sequentially (archiver requires sequential operations)
+    for (const { dir, archivePath, packableFiles } of withPackableFiles) {
+        uiLogger.log(lib.projectUpload.handleProjectUpload.workspaceIncluded(dir, archivePath));
+        archive.directory(dir, archivePath, createWorkspaceFileFilter(packableFiles));
+    }
+    return { externalArchivePaths, packageWorkspaceEntries };
+}
+/**
+ * Archives file: dependencies and returns mapping information.
+ *
+ * Internal file: dependencies (inside srcDir) are skipped — their original
+ * `file:` references in package.json remain valid after upload.
+ *
+ * External file: dependencies are archived to `_workspaces/<name>-<hash>`
+ * and tracked in the returned map so package.json can be rewritten.
+ */
+async function archiveFileDependencies(archive, srcDir, fileDependencyMappings, externalArchivePaths) {
+    const packageFileDeps = new Map();
+    const toArchive = [];
+    for (const mapping of fileDependencyMappings) {
+        const { packageName, localPath, sourcePackageJsonPath } = mapping;
+        if (isInsideSrcDir(localPath, srcDir)) {
+            // Internal: original file: reference stays unchanged, nothing to do
+            continue;
+        }
+        // External: archive to _workspaces/<name>-<hash>
+        const archivePath = computeExternalArchivePath(localPath);
+        const resolvedPath = path.resolve(localPath);
+        if (!packageFileDeps.has(sourcePackageJsonPath)) {
+            packageFileDeps.set(sourcePackageJsonPath, new Map());
+        }
+        const relPkgJsonDir = path.relative(srcDir, path.dirname(sourcePackageJsonPath));
+        const relativeArchivePath = path.relative(relPkgJsonDir, archivePath);
+        packageFileDeps
+            .get(sourcePackageJsonPath)
+            .set(packageName, relativeArchivePath);
+        // Only archive each unique path once
+        if (!externalArchivePaths.has(resolvedPath)) {
+            externalArchivePaths.set(resolvedPath, archivePath);
+            toArchive.push({ localPath, archivePath, packageName });
+        }
+    }
+    // Fetch packable files in parallel (I/O optimization)
+    const withPackableFiles = await Promise.all(toArchive.map(async (item) => ({
+        ...item,
+        packableFiles: await getPackableFiles(item.localPath),
+    })));
+    // Archive directories sequentially (archiver requires sequential operations)
+    for (const { localPath, archivePath, packageName, packableFiles, } of withPackableFiles) {
+        uiLogger.log(lib.projectUpload.handleProjectUpload.fileDependencyIncluded(packageName, localPath, archivePath));
+        archive.directory(localPath, archivePath, createWorkspaceFileFilter(packableFiles));
+    }
+    return packageFileDeps;
+}
+/**
+ * Updates package.json files in the archive to reflect new workspace and file: dependency paths.
+ *
+ * Workspace entries in packageWorkspaces are already in final form:
+ * - Internal workspaces: relative paths (e.g. "../packages/utils")
+ * - External workspaces: relative paths (e.g. "../_workspaces/logger-abc")
+ *
+ * Only external file: dependencies appear in packageFileDeps; internal ones
+ * keep their original file: references and are left untouched.
+ */
+export async function updatePackageJsonInArchive(archive, srcDir, packageWorkspaces, packageFileDeps) {
+    // Collect all package.json paths that need updating
+    const allPackageJsonPaths = new Set([
+        ...packageWorkspaces.keys(),
+        ...packageFileDeps.keys(),
+    ]);
+    for (const packageJsonPath of allPackageJsonPaths) {
+        if (!fs.existsSync(packageJsonPath)) {
+            continue;
+        }
+        const relativePackageJsonPath = path.relative(srcDir, packageJsonPath);
+        let rawContent;
+        try {
+            rawContent = fs.readFileSync(packageJsonPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let packageJson;
+        try {
+            packageJson = JSON.parse(rawContent);
+        }
+        catch (e) {
+            uiLogger.warn(lib.projectUpload.handleProjectUpload.malformedPackageJson(packageJsonPath, e instanceof Error ? e.message : String(e)));
+            archive.append(rawContent, { name: relativePackageJsonPath });
+            continue;
+        }
+        let modified = false;
+        // Update workspaces field — entries are already in their final form
+        const workspaceEntries = packageWorkspaces.get(packageJsonPath);
+        if (workspaceEntries && packageJson.workspaces) {
+            packageJson.workspaces = workspaceEntries;
+            modified = true;
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.updatingPackageJsonWorkspaces(relativePackageJsonPath));
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.updatedWorkspaces(workspaceEntries.join(', ')));
+        }
+        // Update external file: dependencies; internal ones are left untouched
+        const fileDeps = packageFileDeps.get(packageJsonPath);
+        if (fileDeps && fileDeps.size > 0 && packageJson.dependencies) {
+            for (const [packageName, archivePath] of fileDeps.entries()) {
+                if (packageJson.dependencies[packageName]?.startsWith('file:')) {
+                    packageJson.dependencies[packageName] = `file:${archivePath}`;
+                    modified = true;
+                    uiLogger.debug(lib.projectUpload.handleProjectUpload.updatedFileDependency(packageName, archivePath));
+                }
+            }
+        }
+        archive.append(modified ? JSON.stringify(packageJson, null, 2) : rawContent, { name: relativePackageJsonPath });
+    }
+    // Ensure all append operations are queued before finalize is called
+    // Use setImmediate to yield control and let archiver process the queue
+    await new Promise(resolve => setImmediate(resolve));
+}
+export function rewriteLockfileForExternalDeps(lockfileContent, pathMappings) {
+    if (pathMappings.length === 0) {
+        return lockfileContent;
+    }
+    const packages = lockfileContent.packages;
+    if (!packages) {
+        return lockfileContent;
+    }
+    const newPackages = {};
+    for (const [key, value] of Object.entries(packages)) {
+        const mapping = pathMappings.find(m => m.oldPath === key);
+        newPackages[mapping ? mapping.newPath : key] = value;
+    }
+    for (const [key, value] of Object.entries(newPackages)) {
+        if (key.startsWith('node_modules/') &&
+            typeof value === 'object' &&
+            value !== null) {
+            const entry = value;
+            if (entry.link === true && typeof entry.resolved === 'string') {
+                const mapping = pathMappings.find(m => m.oldPath === entry.resolved);
+                if (mapping) {
+                    newPackages[key] = { ...entry, resolved: mapping.newPath };
+                }
+            }
+        }
+    }
+    const rootEntry = newPackages[''];
+    if (rootEntry && typeof rootEntry === 'object' && rootEntry !== null) {
+        const root = rootEntry;
+        if (Array.isArray(root.workspaces)) {
+            newPackages[''] = {
+                ...root,
+                workspaces: root.workspaces.map((ws) => {
+                    if (typeof ws !== 'string')
+                        return ws;
+                    const mapping = pathMappings.find(m => m.oldPath === ws);
+                    return mapping ? mapping.newPath : ws;
+                }),
+            };
+        }
+    }
+    return { ...lockfileContent, packages: newPackages };
+}
+export function getPackageJsonPathsToUpdate(srcDir, workspaceMappings, fileDependencyMappings) {
+    const paths = new Set();
+    for (const { sourcePackageJsonPath } of workspaceMappings) {
+        paths.add(path.relative(srcDir, sourcePackageJsonPath));
+    }
+    for (const { localPath, sourcePackageJsonPath } of fileDependencyMappings) {
+        if (!isInsideSrcDir(localPath, srcDir)) {
+            paths.add(path.relative(srcDir, sourcePackageJsonPath));
+        }
+    }
+    return paths;
+}
+function getDirsWithExternalDeps(srcDir, workspaceMappings, fileDependencyMappings) {
+    const dirs = new Set();
+    for (const { workspaceDir, sourcePackageJsonPath } of workspaceMappings) {
+        if (!isInsideSrcDir(workspaceDir, srcDir)) {
+            dirs.add(path.dirname(sourcePackageJsonPath));
+        }
+    }
+    for (const { localPath, sourcePackageJsonPath } of fileDependencyMappings) {
+        if (!isInsideSrcDir(localPath, srcDir)) {
+            dirs.add(path.dirname(sourcePackageJsonPath));
+        }
+    }
+    return dirs;
+}
+export function getLockfilePathsToUpdate(srcDir, workspaceMappings, fileDependencyMappings) {
+    const dirsWithExternalDeps = getDirsWithExternalDeps(srcDir, workspaceMappings, fileDependencyMappings);
+    const paths = new Set();
+    for (const dir of dirsWithExternalDeps) {
+        const lockfilePath = path.join(dir, 'package-lock.json');
+        if (fs.existsSync(lockfilePath)) {
+            paths.add(path.relative(srcDir, lockfilePath));
+        }
+    }
+    return paths;
+}
+async function rewriteLockfilesInArchive(archive, srcDir, externalArchivePaths, dirsWithExternalDeps) {
+    if (externalArchivePaths.size === 0)
+        return;
+    for (const dir of dirsWithExternalDeps) {
+        const lockfilePath = path.join(dir, 'package-lock.json');
+        if (!fs.existsSync(lockfilePath))
+            continue;
+        let rawContent;
+        try {
+            rawContent = fs.readFileSync(lockfilePath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let lockfileContent;
+        try {
+            lockfileContent = JSON.parse(rawContent);
+        }
+        catch {
+            continue;
+        }
+        const pathMappings = [];
+        for (const [absoluteExternalPath, archivePath] of externalArchivePaths) {
+            pathMappings.push({
+                oldPath: path.relative(dir, absoluteExternalPath),
+                newPath: path.relative(dir, path.join(srcDir, archivePath)),
+            });
+        }
+        const rewritten = rewriteLockfileForExternalDeps(lockfileContent, pathMappings);
+        const relativeLockfilePath = path.relative(srcDir, lockfilePath);
+        uiLogger.debug(lib.projectUpload.handleProjectUpload.updatingLockfile(relativeLockfilePath));
+        archive.append(JSON.stringify(rewritten, null, 2), {
+            name: relativeLockfilePath,
+        });
+    }
+    await new Promise(resolve => setImmediate(resolve));
+}
+/**
+ * Main orchestration function that handles archiving of workspaces and file dependencies.
+ * This is the clean integration point for upload.ts.
+ */
+export async function archiveWorkspacesAndDependencies(archive, srcDir, projectDir, workspaceMappings, fileDependencyMappings) {
+    // Archive workspace directories (internal ones are skipped, externals are copied)
+    const { externalArchivePaths, packageWorkspaceEntries } = await archiveWorkspaceDirectories(archive, srcDir, workspaceMappings);
+    // Archive external file: dependencies (internals are skipped)
+    const packageFileDeps = await archiveFileDependencies(archive, srcDir, fileDependencyMappings, externalArchivePaths);
+    // Update package.json files with new paths
+    await updatePackageJsonInArchive(archive, srcDir, packageWorkspaceEntries, packageFileDeps);
+    // Rewrite lock files to point to archive paths for external deps
+    const dirsWithExternalDeps = getDirsWithExternalDeps(srcDir, workspaceMappings, fileDependencyMappings);
+    await rewriteLockfilesInArchive(archive, srcDir, externalArchivePaths, dirsWithExternalDeps);
+    return { packageWorkspaces: packageWorkspaceEntries, packageFileDeps };
+}