@hubspot/cli 8.0.0-beta.1 → 8.0.0-experimental.0

package/lang/en.d.ts

@@ -3132,6 +3132,14 @@ export declare const lib: {
             fileFiltered: (filename: string) => string;
             legacyFileDetected: (filename: string, platformVersion: string) => string;
             projectDoesNotExist: (accountId: number) => string;
+            workspaceIncluded: (workspaceDir: string, archivePath: string) => string;
+            fileDependencyIncluded: (packageName: string, localPath: string, archivePath: string) => string;
+            malformedPackageJson: (packageJsonPath: string, error: string) => string;
+            workspaceCollision: (archivePath: string, workspaceDir: string, existingWorkspace: string) => string;
+            fileDependencyAlreadyIncluded: (packageName: string, archivePath: string) => string;
+            updatingPackageJsonWorkspaces: (packageJsonPath: string) => string;
+            updatedWorkspaces: (workspaces: string) => string;
+            updatedFileDependency: (packageName: string, relativePath: string) => string;
         };
     };
     importData: {

package/lang/en.js

@@ -3155,6 +3155,14 @@ export const lib = {
             fileFiltered: (filename) => `Ignore rule triggered for "${filename}"`,
             legacyFileDetected: (filename, platformVersion) => `The ${chalk.bold(filename)} file is not supported on platform version ${chalk.bold(platformVersion)} and will be ignored.`,
             projectDoesNotExist: (accountId) => `Upload cancelled. Run ${uiCommandReference('hs project upload')} again to create the project in ${uiAccountDescription(accountId)}.`,
+            workspaceIncluded: (workspaceDir, archivePath) => `Including workspace: ${workspaceDir} → ${archivePath}`,
+            fileDependencyIncluded: (packageName, localPath, archivePath) => `Including file: dependency ${packageName}: ${localPath} → ${archivePath}`,
+            malformedPackageJson: (packageJsonPath, error) => `Skipping malformed package.json at ${packageJsonPath}: ${error}`,
+            workspaceCollision: (archivePath, workspaceDir, existingWorkspace) => `Workspace collision: ${archivePath} from ${workspaceDir} and ${existingWorkspace}`,
+            fileDependencyAlreadyIncluded: (packageName, archivePath) => `file: dependency ${packageName} already included as workspace: ${archivePath}`,
+            updatingPackageJsonWorkspaces: (packageJsonPath) => `Updating package.json workspaces in archive: ${packageJsonPath}`,
+            updatedWorkspaces: (workspaces) => `  Updated workspaces: ${workspaces}`,
+            updatedFileDependency: (packageName, relativePath) => `  Updated dependencies.${packageName}: file:${relativePath}`,
         },
     },
     importData: {

package/lib/projects/__tests__/upload.test.js

@@ -13,6 +13,7 @@ import { walk } from '@hubspot/local-dev-lib/fs';
 import { uploadProject } from '@hubspot/local-dev-lib/api/projects';
 import { ensureProjectExists } from '../ensureProjectExists.js';
 import { projectContainsHsMetaFiles } from '@hubspot/project-parsing-lib/projects';
+import { findAndParsePackageJsonFiles, collectWorkspaceDirectories, collectFileDependencies, } from '@hubspot/project-parsing-lib/workspaces';
 import { shouldIgnoreFile } from '@hubspot/local-dev-lib/ignoreRules';
 import { getConfigAccountIfExists } from '@hubspot/local-dev-lib/config';
 // Mock dependencies
@@ -22,6 +23,11 @@ vi.mock('@hubspot/local-dev-lib/fs');
 vi.mock('@hubspot/local-dev-lib/api/projects');
 vi.mock('../ensureProjectExists.js');
 vi.mock('@hubspot/project-parsing-lib/projects');
+vi.mock('@hubspot/project-parsing-lib/workspaces', () => ({
+    findAndParsePackageJsonFiles: vi.fn(),
+    collectWorkspaceDirectories: vi.fn(),
+    collectFileDependencies: vi.fn(),
+}));
 vi.mock('@hubspot/local-dev-lib/ignoreRules');
 vi.mock('@hubspot/local-dev-lib/config');
 vi.mock('archiver');
@@ -122,6 +128,10 @@ describe('lib/projects/upload', () => {
             vi.mocked(shouldIgnoreFile).mockReturnValue(false);
             vi.mocked(projectContainsHsMetaFiles).mockResolvedValue(false);
             vi.mocked(isV2Project).mockReturnValue(false);
+            // Mock workspace functions to return empty arrays
+            vi.mocked(findAndParsePackageJsonFiles).mockResolvedValue([]);
+            vi.mocked(collectWorkspaceDirectories).mockResolvedValue([]);
+            vi.mocked(collectFileDependencies).mockResolvedValue([]);
             vi.mocked(tmp.fileSync).mockReturnValue({
                 name: path.join(tempDir, 'test.zip'),
                 fd: 1,

package/lib/projects/__tests__/workspaceArchive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/projects/__tests__/workspaceArchive.test.js

@@ -0,0 +1,237 @@
+import { describe, it, expect } from 'vitest';
+import path from 'path';
+import { determineWorkspaceArchivePath, determineFileDependencyArchivePath, shortHash, } from '../workspaces.js';
+describe('determineWorkspaceArchivePath', () => {
+    const projectDir = '/Users/test/my-project';
+    describe('internal workspaces', () => {
+        it('handles workspace in src directory', () => {
+            const workspaceDir = path.join(projectDir, 'src/app/workspaces/utils');
+            const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+            expect(result).toBe(path.join('_workspaces', 'src/app/workspaces/utils'));
+            expect(result).not.toContain('..');
+        });
+        it('handles workspace at project root', () => {
+            const workspaceDir = path.join(projectDir, 'packages/core');
+            const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+            expect(result).toBe(path.join('_workspaces', 'packages/core'));
+            expect(result).not.toContain('..');
+        });
+        it('handles deeply nested workspace', () => {
+            const workspaceDir = path.join(projectDir, 'src/app/functions/shared/utils/http');
+            const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+            expect(result).toBe(path.join('_workspaces', 'src/app/functions/shared/utils/http'));
+            expect(result).not.toContain('..');
+        });
+    });
+    describe('external workspaces', () => {
+        it('handles workspace outside project directory', () => {
+            const workspaceDir = '/Users/test/company-libs/utils';
+            const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+            const expectedHash = shortHash(path.resolve(workspaceDir));
+            expect(result).toBe(path.join('_workspaces', 'external', `utils-${expectedHash}`));
+            expect(result).not.toContain('..');
+        });
+        it('handles workspace in home directory', () => {
+            const workspaceDir = '/Users/test/shared-code/helpers';
+            const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+            const expectedHash = shortHash(path.resolve(workspaceDir));
+            expect(result).toBe(path.join('_workspaces', 'external', `helpers-${expectedHash}`));
+            expect(result).not.toContain('..');
+        });
+        it('handles workspace with parent directory navigation', () => {
+            const workspaceDir = '/Users/test/other-project/shared';
+            const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+            const expectedHash = shortHash(path.resolve(workspaceDir));
+            expect(result).toBe(path.join('_workspaces', 'external', `shared-${expectedHash}`));
+            expect(result).not.toContain('..');
+        });
+        it('detects path traversal vulnerability with similar project names', () => {
+            // This tests the vulnerability where /Users/test/my-project-malicious
+            // would incorrectly be treated as internal with startsWith() check
+            const maliciousWorkspace = '/Users/test/my-project-malicious/evil';
+            const result = determineWorkspaceArchivePath(maliciousWorkspace, projectDir);
+            const expectedHash = shortHash(path.resolve(maliciousWorkspace));
+            // Should be treated as external, not internal
+            expect(result).toBe(path.join('_workspaces', 'external', `evil-${expectedHash}`));
+            expect(result).not.toContain('my-project-malicious');
+        });
+        it('includes hash suffix for deterministic collision prevention', () => {
+            const workspaceDir = '/Users/test/libs/utils';
+            const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+            // Normalize path separators for cross-platform compatibility (Windows uses backslashes)
+            const normalized = result.replace(/\\/g, '/');
+            // Verify the hash suffix format: basename-8hexchars
+            expect(normalized).toMatch(/_workspaces\/external\/utils-[a-f0-9]{8}$/);
+        });
+    });
+    describe('path validity', () => {
+        it('never produces paths with .. segments', () => {
+            const testCases = [
+                path.join(projectDir, 'src/utils'),
+                '/Users/other/libs/utils',
+                '/completely/different/path',
+                path.join(projectDir, '../sibling-project/shared'),
+            ];
+            testCases.forEach(workspaceDir => {
+                const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+                expect(result).not.toContain('..');
+            });
+        });
+        it('always starts with _workspaces/', () => {
+            const testCases = [
+                path.join(projectDir, 'src/utils'),
+                '/Users/other/libs/utils',
+                path.join(projectDir, 'packages/core'),
+            ];
+            testCases.forEach(workspaceDir => {
+                const result = determineWorkspaceArchivePath(workspaceDir, projectDir);
+                expect(result.startsWith('_workspaces')).toBe(true);
+            });
+        });
+    });
+});
+describe('workspace collision prevention', () => {
+    const projectDir = '/Users/test/my-project';
+    it('prevents collision when two external workspaces have same basename', () => {
+        const workspace1 = '/Users/test/project-a/utils';
+        const workspace2 = '/Users/test/project-b/utils';
+        const path1 = determineWorkspaceArchivePath(workspace1, projectDir);
+        const path2 = determineWorkspaceArchivePath(workspace2, projectDir);
+        // Paths should be DIFFERENT due to hash suffix
+        expect(path1).not.toBe(path2);
+        // Both should contain the basename
+        expect(path1).toContain('utils-');
+        expect(path2).toContain('utils-');
+        // Both should be in external folder
+        expect(path1).toContain('external');
+        expect(path2).toContain('external');
+    });
+    it('produces deterministic paths for the same workspace', () => {
+        const workspaceDir = '/Users/test/libs/utils';
+        const path1 = determineWorkspaceArchivePath(workspaceDir, projectDir);
+        const path2 = determineWorkspaceArchivePath(workspaceDir, projectDir);
+        // Same input should always produce same output
+        expect(path1).toBe(path2);
+    });
+    it('no collision when workspaces have different names', () => {
+        const workspace1 = '/Users/test/libs/utils';
+        const workspace2 = '/Users/test/libs/helpers';
+        const path1 = determineWorkspaceArchivePath(workspace1, projectDir);
+        const path2 = determineWorkspaceArchivePath(workspace2, projectDir);
+        expect(path1).not.toBe(path2);
+    });
+    it('no collision between internal and external with same basename', () => {
+        const internalWorkspace = path.join(projectDir, 'src/utils');
+        const externalWorkspace = '/Users/test/other/utils';
+        const path1 = determineWorkspaceArchivePath(internalWorkspace, projectDir);
+        const path2 = determineWorkspaceArchivePath(externalWorkspace, projectDir);
+        const expectedHash = shortHash(path.resolve(externalWorkspace));
+        expect(path1).not.toBe(path2);
+        expect(path1).toBe(path.join('_workspaces', 'src/utils'));
+        expect(path2).toBe(path.join('_workspaces', 'external', `utils-${expectedHash}`));
+    });
+});
+describe('package.json workspace mapping', () => {
+    const projectDir = '/project';
+    it('maps workspaces to correct package.json files using determineWorkspaceArchivePath', () => {
+        const mappings = [
+            {
+                workspaceDir: '/project/src/app/workspaces/functions-utils',
+                sourcePackageJsonPath: '/project/src/app/functions/package.json',
+            },
+            {
+                workspaceDir: '/project/src/app/workspaces/cards-utils',
+                sourcePackageJsonPath: '/project/src/app/cards/package.json',
+            },
+        ];
+        const packageWorkspaces = new Map();
+        for (const mapping of mappings) {
+            // Use the actual function to determine archive path
+            const archivePath = determineWorkspaceArchivePath(mapping.workspaceDir, projectDir);
+            if (!packageWorkspaces.has(mapping.sourcePackageJsonPath)) {
+                packageWorkspaces.set(mapping.sourcePackageJsonPath, []);
+            }
+            packageWorkspaces.get(mapping.sourcePackageJsonPath).push(archivePath);
+        }
+        // Internal workspaces use relative paths (no hash)
+        expect(packageWorkspaces.get('/project/src/app/functions/package.json')).toEqual([path.join('_workspaces', 'src/app/workspaces/functions-utils')]);
+        expect(packageWorkspaces.get('/project/src/app/cards/package.json')).toEqual([path.join('_workspaces', 'src/app/workspaces/cards-utils')]);
+    });
+    it('handles multiple external workspaces per package.json with hash suffixes', () => {
+        const mappings = [
+            {
+                workspaceDir: '/external/utils-a',
+                sourcePackageJsonPath: '/project/package.json',
+            },
+            {
+                workspaceDir: '/external/utils-b',
+                sourcePackageJsonPath: '/project/package.json',
+            },
+        ];
+        const packageWorkspaces = new Map();
+        for (const mapping of mappings) {
+            const archivePath = determineWorkspaceArchivePath(mapping.workspaceDir, projectDir);
+            if (!packageWorkspaces.has(mapping.sourcePackageJsonPath)) {
+                packageWorkspaces.set(mapping.sourcePackageJsonPath, []);
+            }
+            packageWorkspaces.get(mapping.sourcePackageJsonPath).push(archivePath);
+        }
+        const workspaces = packageWorkspaces.get('/project/package.json');
+        expect(workspaces).toHaveLength(2);
+        // External workspaces should have hash suffixes
+        expect(workspaces[0]).toMatch(/_workspaces\/external\/utils-a-[a-f0-9]{8}/);
+        expect(workspaces[1]).toMatch(/_workspaces\/external\/utils-b-[a-f0-9]{8}/);
+    });
+});
+describe('shortHash', () => {
+    it('produces 8-character hex string', () => {
+        const hash = shortHash('/some/path');
+        expect(hash).toMatch(/^[a-f0-9]{8}$/);
+    });
+    it('is deterministic', () => {
+        const input = '/Users/test/workspace';
+        expect(shortHash(input)).toBe(shortHash(input));
+    });
+    it('produces different hashes for different inputs', () => {
+        const hash1 = shortHash('/path/a');
+        const hash2 = shortHash('/path/b');
+        expect(hash1).not.toBe(hash2);
+    });
+});
+describe('determineFileDependencyArchivePath', () => {
+    it('places file: dependencies in _workspaces/external/', () => {
+        const localPath = '/Users/test/my-local-lib';
+        const result = determineFileDependencyArchivePath(localPath);
+        expect(result).toContain('_workspaces');
+        expect(result).toContain('external');
+        expect(result).toContain('my-local-lib');
+    });
+    it('includes hash suffix for collision prevention', () => {
+        const localPath = '/Users/test/libs/utils';
+        const result = determineFileDependencyArchivePath(localPath);
+        // Should match pattern: _workspaces/external/utils-[8 hex chars]
+        expect(result).toMatch(/_workspaces\/external\/utils-[a-f0-9]{8}$/);
+    });
+    it('produces different paths for different local paths with same basename', () => {
+        const path1 = '/Users/test/project-a/utils';
+        const path2 = '/Users/test/project-b/utils';
+        const result1 = determineFileDependencyArchivePath(path1);
+        const result2 = determineFileDependencyArchivePath(path2);
+        expect(result1).not.toBe(result2);
+        expect(result1).toContain('utils-');
+        expect(result2).toContain('utils-');
+    });
+    it('is deterministic', () => {
+        const localPath = '/Users/test/my-lib';
+        const result1 = determineFileDependencyArchivePath(localPath);
+        const result2 = determineFileDependencyArchivePath(localPath);
+        expect(result1).toBe(result2);
+    });
+    it('handles scoped package directories', () => {
+        const localPath = '/Users/test/libs/@company/shared-utils';
+        const result = determineFileDependencyArchivePath(localPath);
+        // Should use the last path segment (shared-utils) as the basename
+        expect(result).toContain('shared-utils-');
+        expect(result).toMatch(/_workspaces\/external\/shared-utils-[a-f0-9]{8}$/);
+    });
+});

package/lib/projects/upload.js

@@ -6,6 +6,7 @@ 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 { logError } from '../errorHandlers/index.js';
@@ -18,6 +19,7 @@ import { EXIT_CODES } from '../enums/exitCodes.js';
 import ProjectValidationError from '../errors/ProjectValidationError.js';
 import { walk } from '@hubspot/local-dev-lib/fs';
 import { LEGACY_CONFIG_FILES } from '../constants.js';
+import { archiveWorkspacesAndDependencies } from './workspaces.js';
 async function uploadProjectFiles(accountId, projectName, filePath, uploadMessage, platformVersion, intermediateRepresentation) {
     const accountIdentifier = uiAccountDescription(accountId) || `${accountId}`;
     SpinniesManager.add('upload', {
@@ -62,6 +64,11 @@ export async function handleProjectUpload({ accountId, projectConfig, projectDir
     }
     const tempFile = tmp.fileSync({ postfix: '.zip' });
     uiLogger.debug(lib.projectUpload.handleProjectUpload.compressing(tempFile.name));
+    // Find and parse all package.json files once (avoids duplicate filesystem walks)
+    const parsedPackageJsons = await findAndParsePackageJsonFiles(srcDir);
+    // Collect workspace directories and file: dependencies from parsed data
+    const workspaceMappings = await collectWorkspaceDirectories(parsedPackageJsons);
+    const fileDependencyMappings = await collectFileDependencies(parsedPackageJsons);
     const output = fs.createWriteStream(tempFile.name);
     const archive = archiver('zip');
     const result = new Promise(resolve => output.on('close', async function () {
@@ -114,6 +121,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;
 }

package/lib/projects/workspaces.d.ts

@@ -0,0 +1,35 @@
+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 a workspace directory.
+ * Internal workspaces use their relative path from projectDir.
+ * External workspaces use 'external' subdirectory + basename + hash.
+ */
+export declare function determineWorkspaceArchivePath(workspaceDir: string, projectDir: string): string;
+/**
+ * Determines the archive path for a file: dependency.
+ * All file: dependencies are treated as external and placed in _workspaces/external/
+ * with a hash suffix to prevent collisions.
+ */
+export declare function determineFileDependencyArchivePath(localPath: string): string;
+/**
+ * Updates package.json files in the archive to reflect new workspace and file: dependency paths.
+ */
+export declare function updatePackageJsonInArchive(archive: archiver.Archiver, srcDir: string, packageWorkspaces: Map<string, string[]>, packageFileDeps: Map<string, Map<string, string>>): Promise<void>;
+/**
+ * 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,216 @@
+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 a workspace directory.
+ * Internal workspaces use their relative path from projectDir.
+ * External workspaces use 'external' subdirectory + basename + hash.
+ */
+export function determineWorkspaceArchivePath(workspaceDir, projectDir) {
+    const normalizedWorkspace = path.resolve(workspaceDir);
+    const normalizedProject = path.resolve(projectDir);
+    const relPath = path.relative(normalizedProject, normalizedWorkspace);
+    if (!relPath.startsWith('..') && !path.isAbsolute(relPath)) {
+        // Internal workspace - use relative path from projectDir
+        return path.join('_workspaces', relPath);
+    }
+    else {
+        // External workspace - use 'external' subdirectory + basename + hash
+        const workspaceName = path.basename(normalizedWorkspace);
+        const hash = shortHash(normalizedWorkspace);
+        return path.join('_workspaces', 'external', `${workspaceName}-${hash}`);
+    }
+}
+/**
+ * Determines the archive path for a file: dependency.
+ * All file: dependencies are treated as external and placed in _workspaces/external/
+ * with a hash suffix to prevent collisions.
+ */
+export function determineFileDependencyArchivePath(localPath) {
+    const normalizedPath = path.resolve(localPath);
+    const depName = path.basename(normalizedPath);
+    const hash = shortHash(normalizedPath);
+    return path.join('_workspaces', 'external', `${depName}-${hash}`);
+}
+/**
+ * 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.
+ */
+async function archiveWorkspaceDirectories(archive, projectDir, workspaceMappings) {
+    const workspacePaths = new Map();
+    const archivePathToWorkspace = new Map();
+    const packageWorkspaces = new Map();
+    // First pass: determine archive paths and check for collisions (O(n) with reverse map)
+    for (const mapping of workspaceMappings) {
+        const { workspaceDir, sourcePackageJsonPath } = mapping;
+        const archivePath = determineWorkspaceArchivePath(workspaceDir, projectDir);
+        // Check for name collisions using reverse map (O(1) lookup)
+        const existingWorkspace = archivePathToWorkspace.get(archivePath);
+        if (existingWorkspace) {
+            throw new Error(lib.projectUpload.handleProjectUpload.workspaceCollision(archivePath, workspaceDir, existingWorkspace));
+        }
+        archivePathToWorkspace.set(archivePath, workspaceDir);
+        workspacePaths.set(workspaceDir, archivePath);
+        // Track which archive paths belong to which package.json
+        if (!packageWorkspaces.has(sourcePackageJsonPath)) {
+            packageWorkspaces.set(sourcePackageJsonPath, []);
+        }
+        packageWorkspaces.get(sourcePackageJsonPath).push(archivePath);
+    }
+    // Fetch all packable files in parallel (I/O optimization)
+    const workspacePackableFiles = await Promise.all(workspaceMappings.map(async (mapping) => ({
+        mapping,
+        packableFiles: await getPackableFiles(mapping.workspaceDir),
+    })));
+    // Archive directories sequentially (archiver requires sequential operations)
+    for (const { mapping, packableFiles } of workspacePackableFiles) {
+        const { workspaceDir } = mapping;
+        const archivePath = workspacePaths.get(workspaceDir);
+        uiLogger.log(lib.projectUpload.handleProjectUpload.workspaceIncluded(workspaceDir, archivePath));
+        archive.directory(workspaceDir, archivePath, createWorkspaceFileFilter(packableFiles));
+    }
+    return { workspacePaths, archivePathToWorkspace, packageWorkspaces };
+}
+/**
+ * Archives file: dependencies and returns mapping information.
+ */
+async function archiveFileDependencies(archive, fileDependencyMappings, workspacePaths, archivePathToWorkspace) {
+    const packageFileDeps = new Map();
+    const fileDepPathsToArchive = [];
+    // First pass: determine which file deps need archiving and track mappings
+    for (const mapping of fileDependencyMappings) {
+        const { packageName, localPath, sourcePackageJsonPath } = mapping;
+        const archivePath = determineFileDependencyArchivePath(localPath);
+        // Check for path collisions using reverse map (O(1) lookup)
+        if (archivePathToWorkspace.has(archivePath)) {
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.fileDependencyAlreadyIncluded(packageName, archivePath));
+            // Still track the dependency mapping even if already archived
+            if (!packageFileDeps.has(sourcePackageJsonPath)) {
+                packageFileDeps.set(sourcePackageJsonPath, new Map());
+            }
+            packageFileDeps.get(sourcePackageJsonPath).set(packageName, archivePath);
+            continue;
+        }
+        // Only archive each unique path once
+        if (!workspacePaths.has(localPath)) {
+            workspacePaths.set(localPath, archivePath);
+            archivePathToWorkspace.set(archivePath, localPath);
+            fileDepPathsToArchive.push({ localPath, archivePath, packageName });
+        }
+        // Track which package.json has which file: dependencies
+        if (!packageFileDeps.has(sourcePackageJsonPath)) {
+            packageFileDeps.set(sourcePackageJsonPath, new Map());
+        }
+        packageFileDeps.get(sourcePackageJsonPath).set(packageName, archivePath);
+    }
+    // Fetch all packable files in parallel (I/O optimization)
+    const fileDepPackableFiles = await Promise.all(fileDepPathsToArchive.map(async ({ localPath, archivePath, packageName }) => ({
+        localPath,
+        archivePath,
+        packageName,
+        packableFiles: await getPackableFiles(localPath),
+    })));
+    // Archive directories sequentially (archiver requires sequential operations)
+    for (const { localPath, archivePath, packageName, packableFiles, } of fileDepPackableFiles) {
+        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.
+ */
+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;
+        }
+        let packageJson;
+        try {
+            packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        }
+        catch (e) {
+            uiLogger.warn(lib.projectUpload.handleProjectUpload.malformedPackageJson(packageJsonPath, e instanceof Error ? e.message : String(e)));
+            continue;
+        }
+        const relativePackageJsonPath = path.relative(srcDir, packageJsonPath);
+        const packageJsonDir = path.dirname(relativePackageJsonPath);
+        let modified = false;
+        // Update workspaces field if this package.json has workspaces
+        const workspaceArchivePaths = packageWorkspaces.get(packageJsonPath);
+        if (workspaceArchivePaths && packageJson.workspaces) {
+            packageJson.workspaces = workspaceArchivePaths;
+            modified = true;
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.updatingPackageJsonWorkspaces(relativePackageJsonPath));
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.updatedWorkspaces(workspaceArchivePaths.join(', ')));
+        }
+        // Update file: dependencies if this package.json has any
+        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:')) {
+                    // Calculate relative path from package.json location to archive path
+                    const relativePath = path.relative(packageJsonDir, archivePath);
+                    packageJson.dependencies[packageName] = `file:${relativePath}`;
+                    modified = true;
+                    uiLogger.debug(lib.projectUpload.handleProjectUpload.updatedFileDependency(packageName, relativePath));
+                }
+            }
+        }
+        if (modified) {
+            // Add modified package.json to archive (will replace the original)
+            archive.append(JSON.stringify(packageJson, null, 2), {
+                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));
+}
+/**
+ * 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
+    const { workspacePaths, archivePathToWorkspace, packageWorkspaces } = await archiveWorkspaceDirectories(archive, projectDir, workspaceMappings);
+    // Archive file: dependencies
+    const packageFileDeps = await archiveFileDependencies(archive, fileDependencyMappings, workspacePaths, archivePathToWorkspace);
+    // Update package.json files with new paths
+    await updatePackageJsonInArchive(archive, srcDir, packageWorkspaces, packageFileDeps);
+    return { packageWorkspaces, packageFileDeps };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/cli",
-    "version": "8.0.0-beta.1",
+    "version": "8.0.0-experimental.0",
     "description": "The official CLI for developing on HubSpot",
     "license": "Apache-2.0",
     "repository": "https://github.com/HubSpot/hubspot-cli",
@@ -8,7 +8,7 @@
     "dependencies": {
         "@hubspot/cms-dev-server": "1.2.1",
         "@hubspot/local-dev-lib": "5.1.1",
-        "@hubspot/project-parsing-lib": "0.11.2",
+        "@hubspot/project-parsing-lib": "0.1.0-experimental.0",
         "@hubspot/serverless-dev-runtime": "7.0.7",
         "@hubspot/ui-extensions-dev-server": "1.1.3",
         "@inquirer/prompts": "7.1.0",