@hubspot/cli 8.0.3-experimental.0 → 8.0.3-experimental.1

package/lang/en.d.ts

@@ -3179,6 +3179,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

@@ -3202,6 +3202,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,207 @@
+import { describe, it, expect, vi } from 'vitest';
+import path from 'path';
+import fs from 'fs-extra';
+import { computeExternalArchivePath, shortHash, updatePackageJsonInArchive, } from '../workspaces.js';
+describe('computeExternalArchivePath', () => {
+    it('places external workspace in _workspaces/ with basename-hash', () => {
+        const localPath = '/Users/test/company-libs/utils';
+        const result = computeExternalArchivePath(localPath);
+        const expectedHash = shortHash(path.resolve(localPath));
+        expect(result).toBe(path.join('_workspaces', `utils-${expectedHash}`));
+    });
+    it('does not include an external/ subdirectory', () => {
+        const result = computeExternalArchivePath('/Users/test/libs/utils');
+        expect(result).not.toContain('external');
+        expect(result.startsWith('_workspaces')).toBe(true);
+    });
+    it('produces different paths for different directories with same basename', () => {
+        const path1 = computeExternalArchivePath('/Users/test/project-a/utils');
+        const path2 = computeExternalArchivePath('/Users/test/project-b/utils');
+        expect(path1).not.toBe(path2);
+        expect(path1).toContain('utils-');
+        expect(path2).toContain('utils-');
+    });
+    it('is deterministic', () => {
+        const localPath = '/Users/test/libs/utils';
+        expect(computeExternalArchivePath(localPath)).toBe(computeExternalArchivePath(localPath));
+    });
+    it('produces paths matching _workspaces/<name>-[8 hex chars]', () => {
+        const result = computeExternalArchivePath('/Users/test/libs/utils');
+        // Normalize path separators for cross-platform compatibility
+        const normalized = result.replace(/\\/g, '/');
+        expect(normalized).toMatch(/_workspaces\/utils-[a-f0-9]{8}$/);
+    });
+    it('uses the last path segment as basename', () => {
+        const result = computeExternalArchivePath('/Users/test/libs/@company/shared-utils');
+        expect(result).toContain('shared-utils-');
+        const normalized = result.replace(/\\/g, '/');
+        expect(normalized).toMatch(/_workspaces\/shared-utils-[a-f0-9]{8}$/);
+    });
+    it('never produces paths with .. segments', () => {
+        const testCases = [
+            '/Users/other/libs/utils',
+            '/completely/different/path',
+            '/Users/test/other-project/shared',
+        ];
+        testCases.forEach(localPath => {
+            expect(computeExternalArchivePath(localPath)).not.toContain('..');
+        });
+    });
+});
+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('updatePackageJsonInArchive', () => {
+    const srcDir = '/project/src';
+    function createMockArchive() {
+        const appended = [];
+        const mock = {
+            append: (content, opts) => {
+                appended.push({ content, name: opts.name });
+                return mock;
+            },
+        };
+        return {
+            archive: mock,
+            getAppended: () => appended,
+        };
+    }
+    it('writes external workspace entries as absolute archive paths', async () => {
+        const packageJsonPath = '/project/src/app/functions/package.json';
+        const originalPackageJson = {
+            name: 'my-app',
+            workspaces: ['../../packages/utils'],
+            dependencies: {},
+        };
+        vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+        vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(originalPackageJson));
+        const { archive, getAppended } = createMockArchive();
+        const packageWorkspaces = new Map();
+        packageWorkspaces.set(packageJsonPath, [
+            '/_workspaces/packages-utils-a1b2c3d4',
+            '/_workspaces/packages-core-e5f6a7b8',
+        ]);
+        await updatePackageJsonInArchive(archive, srcDir, packageWorkspaces, new Map());
+        const appended = getAppended();
+        expect(appended).toHaveLength(1);
+        const written = JSON.parse(appended[0].content);
+        expect(written.workspaces).toEqual([
+            '/_workspaces/packages-utils-a1b2c3d4',
+            '/_workspaces/packages-core-e5f6a7b8',
+        ]);
+        vi.restoreAllMocks();
+    });
+    it('preserves internal workspace entries as relative paths', async () => {
+        const packageJsonPath = '/project/src/app/functions/package.json';
+        const originalPackageJson = {
+            name: 'my-app',
+            workspaces: ['../packages/utils'],
+        };
+        vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+        vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(originalPackageJson));
+        const { archive, getAppended } = createMockArchive();
+        const packageWorkspaces = new Map();
+        packageWorkspaces.set(packageJsonPath, ['../packages/utils']);
+        await updatePackageJsonInArchive(archive, srcDir, packageWorkspaces, new Map());
+        const written = JSON.parse(getAppended()[0].content);
+        expect(written.workspaces).toEqual(['../packages/utils']);
+        vi.restoreAllMocks();
+    });
+    it('writes mixed internal and external workspace entries', async () => {
+        const packageJsonPath = '/project/src/app/functions/package.json';
+        const originalPackageJson = {
+            name: 'my-app',
+            workspaces: ['../packages/utils', '/_workspaces/logger-a1b2c3d4'],
+        };
+        vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+        vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(originalPackageJson));
+        const { archive, getAppended } = createMockArchive();
+        const packageWorkspaces = new Map();
+        packageWorkspaces.set(packageJsonPath, [
+            '../packages/utils',
+            '/_workspaces/logger-a1b2c3d4',
+        ]);
+        await updatePackageJsonInArchive(archive, srcDir, packageWorkspaces, new Map());
+        const written = JSON.parse(getAppended()[0].content);
+        expect(written.workspaces).toEqual([
+            '../packages/utils',
+            '/_workspaces/logger-a1b2c3d4',
+        ]);
+        vi.restoreAllMocks();
+    });
+    it('rewrites external file: dependencies as absolute archive paths', async () => {
+        const packageJsonPath = '/project/src/app/functions/package.json';
+        const originalPackageJson = {
+            name: 'my-app',
+            dependencies: {
+                '@company/logger': 'file:../../external/logger',
+                react: '^18.0.0',
+            },
+        };
+        vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+        vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(originalPackageJson));
+        const { archive, getAppended } = createMockArchive();
+        const packageFileDeps = new Map();
+        packageFileDeps.set(packageJsonPath, new Map([['@company/logger', '_workspaces/logger-a1b2c3d4']]));
+        await updatePackageJsonInArchive(archive, srcDir, new Map(), packageFileDeps);
+        const appended = getAppended();
+        expect(appended).toHaveLength(1);
+        const written = JSON.parse(appended[0].content);
+        expect(written.dependencies['@company/logger']).toBe('file:/_workspaces/logger-a1b2c3d4');
+        expect(written.dependencies['react']).toBe('^18.0.0');
+        vi.restoreAllMocks();
+    });
+    it('leaves internal file: dependencies untouched when not in packageFileDeps', async () => {
+        const originalPackageJson = {
+            name: 'my-app',
+            dependencies: {
+                '@internal/utils': 'file:../packages/utils',
+                react: '^18.0.0',
+            },
+        };
+        vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+        vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(originalPackageJson));
+        const { archive, getAppended } = createMockArchive();
+        await updatePackageJsonInArchive(archive, srcDir, new Map(), new Map());
+        // Nothing to update, so no package.json should be appended
+        expect(getAppended()).toHaveLength(0);
+        vi.restoreAllMocks();
+    });
+    it('uses same absolute path regardless of package.json depth', async () => {
+        const shallowPath = '/project/src/package.json';
+        const deepPath = '/project/src/app/functions/nested/package.json';
+        const archivePath = '/_workspaces/utils-a1b2c3d4';
+        const makePackageJson = () => ({
+            name: 'test',
+            workspaces: ['placeholder'],
+        });
+        vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+        const { archive: archive1, getAppended: getAppended1 } = createMockArchive();
+        vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(makePackageJson()));
+        const workspaces1 = new Map();
+        workspaces1.set(shallowPath, [archivePath]);
+        await updatePackageJsonInArchive(archive1, srcDir, workspaces1, new Map());
+        const { archive: archive2, getAppended: getAppended2 } = createMockArchive();
+        vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(makePackageJson()));
+        const workspaces2 = new Map();
+        workspaces2.set(deepPath, [archivePath]);
+        await updatePackageJsonInArchive(archive2, srcDir, workspaces2, new Map());
+        const written1 = JSON.parse(getAppended1()[0].content);
+        const written2 = JSON.parse(getAppended2()[0].content);
+        expect(written1.workspaces).toEqual(['/_workspaces/utils-a1b2c3d4']);
+        expect(written2.workspaces).toEqual(['/_workspaces/utils-a1b2c3d4']);
+        vi.restoreAllMocks();
+    });
+});

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,36 @@
+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: absolute 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>;
+/**
+ * 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,224 @@
+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 absolute archive paths (`/_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 });
+            }
+            // Store absolute archive path so DFS can locate it in the project tree
+            packageWorkspaceEntries
+                .get(sourcePackageJsonPath)
+                .push(`/${archivePath}`);
+        }
+    }
+    // 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());
+        }
+        packageFileDeps.get(sourcePackageJsonPath).set(packageName, archivePath);
+        // 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: absolute 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;
+        }
+        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);
+        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}`));
+                }
+            }
+        }
+        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 (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);
+    return { packageWorkspaces: packageWorkspaceEntries, packageFileDeps };
+}

package/mcp-server/tools/project/AddFeatureToProjectTool.d.ts

@@ -5,26 +5,9 @@ declare const inputSchemaZodObject: z.ZodObject<{
     absoluteProjectPath: z.ZodString;
     absoluteCurrentWorkingDirectory: z.ZodString;
     addApp: z.ZodBoolean;
-    distribution: z.ZodOptional<z.ZodEnum<{
-        marketplace: "marketplace";
-        private: "private";
-    }>>;
-    auth: z.ZodOptional<z.ZodEnum<{
-        oauth: "oauth";
-        static: "static";
-    }>>;
-    features: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        card: "card";
-        settings: "settings";
-        "app-event": "app-event";
-        page: "page";
-        "workflow-action-tool": "workflow-action-tool";
-        webhooks: "webhooks";
-        "workflow-action": "workflow-action";
-        "app-function": "app-function";
-        "app-object": "app-object";
-        scim: "scim";
-    }>>>;
+    distribution: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"marketplace">, z.ZodLiteral<"private">]>>;
+    auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"static">, z.ZodLiteral<"oauth">]>>;
+    features: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"card">, z.ZodLiteral<"settings">, z.ZodLiteral<"app-function">, z.ZodLiteral<"webhooks">, z.ZodLiteral<"workflow-action">, z.ZodLiteral<"workflow-action-tool">, z.ZodLiteral<"app-object">, z.ZodLiteral<"app-event">, z.ZodLiteral<"scim">, z.ZodLiteral<"page">]>>>;
 }, z.core.$strip>;
 export type AddFeatureInputSchema = z.infer<typeof inputSchemaZodObject>;
 export declare class AddFeatureToProjectTool extends Tool<AddFeatureInputSchema> {

package/mcp-server/tools/project/AddFeatureToProjectTool.js

@@ -15,13 +15,17 @@ const inputSchema = {
         .boolean()
         .describe('Should an app be added?  If there is no app in the project, an app must be added to add a feature'),
     distribution: z
-        .enum([APP_DISTRIBUTION_TYPES.MARKETPLACE, APP_DISTRIBUTION_TYPES.PRIVATE])
-        .describe('If not specified by the user, DO NOT choose for them.  This cannot be changed after a project is uploaded. Private is used if you do not wish to distribute your app on the HubSpot marketplace. ')
-        .optional(),
+        .optional(z.union([
+        z.literal(APP_DISTRIBUTION_TYPES.MARKETPLACE),
+        z.literal(APP_DISTRIBUTION_TYPES.PRIVATE),
+    ]))
+        .describe('If not specified by the user, DO NOT choose for them.  This cannot be changed after a project is uploaded. Private is used if you do not wish to distribute your app on the HubSpot marketplace. '),
     auth: z
-        .enum([APP_AUTH_TYPES.STATIC, APP_AUTH_TYPES.OAUTH])
-        .describe('If not specified by the user, DO NOT choose for them.  This cannot be changed after a project is uploaded. Static uses a static non changing authentication token, and is only available for private distribution. ')
-        .optional(),
+        .optional(z.union([
+        z.literal(APP_AUTH_TYPES.STATIC),
+        z.literal(APP_AUTH_TYPES.OAUTH),
+    ]))
+        .describe('If not specified by the user, DO NOT choose for them.  This cannot be changed after a project is uploaded. Static uses a static non changing authentication token, and is only available for private distribution. '),
     features,
 };
 // eslint-disable-next-line @typescript-eslint/no-unused-vars

package/mcp-server/tools/project/CreateProjectTool.d.ts

@@ -5,30 +5,10 @@ declare const inputSchemaZodObject: z.ZodObject<{
     absoluteCurrentWorkingDirectory: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
     destination: z.ZodString;
-    projectBase: z.ZodEnum<{
-        app: "app";
-        empty: "empty";
-    }>;
-    distribution: z.ZodOptional<z.ZodEnum<{
-        marketplace: "marketplace";
-        private: "private";
-    }>>;
-    auth: z.ZodOptional<z.ZodEnum<{
-        oauth: "oauth";
-        static: "static";
-    }>>;
-    features: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        card: "card";
-        settings: "settings";
-        "app-event": "app-event";
-        page: "page";
-        "workflow-action-tool": "workflow-action-tool";
-        webhooks: "webhooks";
-        "workflow-action": "workflow-action";
-        "app-function": "app-function";
-        "app-object": "app-object";
-        scim: "scim";
-    }>>>;
+    projectBase: z.ZodUnion<readonly [z.ZodLiteral<"empty">, z.ZodLiteral<"app">]>;
+    distribution: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"marketplace">, z.ZodLiteral<"private">]>>;
+    auth: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"static">, z.ZodLiteral<"oauth">]>>>;
+    features: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"card">, z.ZodLiteral<"settings">, z.ZodLiteral<"app-function">, z.ZodLiteral<"webhooks">, z.ZodLiteral<"workflow-action">, z.ZodLiteral<"workflow-action-tool">, z.ZodLiteral<"app-object">, z.ZodLiteral<"app-event">, z.ZodLiteral<"scim">, z.ZodLiteral<"page">]>>>;
 }, z.core.$strip>;
 export type CreateProjectInputSchema = z.infer<typeof inputSchemaZodObject>;
 export declare class CreateProjectTool extends Tool<CreateProjectInputSchema> {

package/mcp-server/tools/project/CreateProjectTool.js

@@ -18,14 +18,19 @@ const inputSchema = {
         .string()
         .describe('DO NOT use the current directory unless the user has explicitly stated to do so. Relative path to the directory the project will be created in.'),
     projectBase: z
-        .enum([EMPTY_PROJECT, PROJECT_WITH_APP])
+        .union([z.literal(EMPTY_PROJECT), z.literal(PROJECT_WITH_APP)])
         .describe('Empty will create an empty project, and app will create a project with an app inside of it.'),
     distribution: z
-        .enum([APP_DISTRIBUTION_TYPES.MARKETPLACE, APP_DISTRIBUTION_TYPES.PRIVATE])
-        .describe('If not specified by the user, DO NOT choose for them.  This cannot be changed after a project is uploaded. Private is used if you do not wish to distribute your app on the HubSpot marketplace. ')
-        .optional(),
+        .optional(z.union([
+        z.literal(APP_DISTRIBUTION_TYPES.MARKETPLACE),
+        z.literal(APP_DISTRIBUTION_TYPES.PRIVATE),
+    ]))
+        .describe('If not specified by the user, DO NOT choose for them.  This cannot be changed after a project is uploaded. Private is used if you do not wish to distribute your app on the HubSpot marketplace. '),
     auth: z
-        .enum([APP_AUTH_TYPES.STATIC, APP_AUTH_TYPES.OAUTH])
+        .optional(z.union([
+        z.literal(APP_AUTH_TYPES.STATIC),
+        z.literal(APP_AUTH_TYPES.OAUTH),
+    ]))
         .describe('If not specified by the user, DO NOT choose for them.  This cannot be changed after a project is uploaded. Static uses a static non changing authentication token, and is only available for private distribution. ')
         .optional(),
     features,

package/mcp-server/tools/project/GetApiUsagePatternsByAppIdTool.js

@@ -12,15 +12,18 @@ const inputSchema = {
     absoluteCurrentWorkingDirectory,
     appId: z
         .string()
-        .describe('The numeric app ID as a string (e.g., "3003909"). Must contain only digits. Use get-apps-info to find available app IDs.'),
+        .regex(/^\d+$/, 'App ID must be a numeric string')
+        .describe('The numeric app ID as a string (e.g., "3003909"). Use get-apps-info to find available app IDs.'),
     startDate: z
         .string()
-        .describe('Start date for the usage patterns query in YYYY-MM-DD format (e.g., 2025-01-01).')
-        .optional(),
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Start date must be in YYYY-MM-DD format')
+        .optional()
+        .describe('Start date for the usage patterns query in ISO 8601 format (e.g., 2025-01-01).'),
     endDate: z
         .string()
-        .describe('End date for the usage patterns query in YYYY-MM-DD format (e.g., 2025-12-31).')
-        .optional(),
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'End date must be in YYYY-MM-DD format')
+        .optional()
+        .describe('End date for the usage patterns query in ISO 8601 format (e.g., 2025-12-31).'),
 };
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const inputSchemaZodObject = z.object({ ...inputSchema });

package/mcp-server/tools/project/GetBuildLogsTool.d.ts

@@ -5,12 +5,12 @@ declare const inputSchemaZodObject: z.ZodObject<{
     absoluteProjectPath: z.ZodString;
     absoluteCurrentWorkingDirectory: z.ZodString;
     buildId: z.ZodNumber;
-    logLevel: z.ZodOptional<z.ZodEnum<{
+    logLevel: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         ERROR: "ERROR";
         WARN: "WARN";
         INFO: "INFO";
         ALL: "ALL";
-    }>>;
+    }>>>;
 }, z.core.$strip>;
 export type GetBuildLogsInputSchema = z.infer<typeof inputSchemaZodObject>;
 export declare class GetBuildLogsTool extends Tool<GetBuildLogsInputSchema> {

package/mcp-server/tools/project/GetBuildLogsTool.js

@@ -18,8 +18,9 @@ const inputSchema = {
         .describe('Build ID to fetch logs for. Use get-build-status to find recent build IDs.'),
     logLevel: z
         .enum(['ERROR', 'WARN', 'INFO', 'ALL'])
-        .describe('Filter logs by level. ERROR: Show only errors, WARN: Show only warnings, INFO: Show only info, ALL: Show all logs. Defaults to ALL if not specified.')
-        .optional(),
+        .optional()
+        .default('ALL')
+        .describe('Filter logs by level. ERROR: Show only errors, WARN: Show only warnings, INFO: Show only info, ALL: Show all logs.'),
 };
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const inputSchemaZodObject = z.object({ ...inputSchema });
@@ -84,7 +85,7 @@ export class GetBuildLogsTool extends Tool {
             if (allLogs.length === 0) {
                 return formatTextContents(absoluteCurrentWorkingDirectory, `No logs found for build #${buildId} in project '${projectName}'.`);
             }
-            const filteredLogs = filterLogsByLevel(allLogs, logLevel || 'ALL');
+            const filteredLogs = filterLogsByLevel(allLogs, logLevel);
             let output;
             if (filteredLogs.length === 0) {
                 // No logs match filter, show all logs instead

package/mcp-server/tools/project/GetBuildStatusTool.d.ts

@@ -5,7 +5,7 @@ declare const inputSchemaZodObject: z.ZodObject<{
     absoluteProjectPath: z.ZodString;
     absoluteCurrentWorkingDirectory: z.ZodString;
     buildId: z.ZodOptional<z.ZodNumber>;
-    limit: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, z.core.$strip>;
 export type GetBuildStatusInputSchema = z.infer<typeof inputSchemaZodObject>;
 export declare class GetBuildStatusTool extends Tool<GetBuildStatusInputSchema> {

package/mcp-server/tools/project/GetBuildStatusTool.js

@@ -19,8 +19,9 @@ const inputSchema = {
         .describe('Optional: Specific build ID to inspect. If omitted, shows recent builds to help identify the latest build.'),
     limit: z
         .number()
-        .describe('Number of recent builds to fetch when buildId is not specified. Defaults to 3 if not specified.')
-        .optional(),
+        .optional()
+        .default(3)
+        .describe('Number of recent builds to fetch when buildId is not specified.'),
 };
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const inputSchemaZodObject = z.object({ ...inputSchema });
@@ -126,7 +127,7 @@ export class GetBuildStatusTool extends Tool {
             }
             else {
                 const response = await fetchProjectBuilds(accountId, projectName, {
-                    limit: limit || 3,
+                    limit,
                 });
                 const { results } = response.data;
                 if (!results || results.length === 0) {

package/mcp-server/tools/project/GuidedWalkthroughTool.d.ts

@@ -3,12 +3,7 @@ import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.
 import { z } from 'zod';
 declare const inputSchemaZodObject: z.ZodObject<{
     absoluteCurrentWorkingDirectory: z.ZodString;
-    command: z.ZodOptional<z.ZodEnum<{
-        "hs auth": "hs auth";
-        "hs project create": "hs project create";
-        "hs project upload": "hs project upload";
-        "hs init": "hs init";
-    }>>;
+    command: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"hs init">, z.ZodLiteral<"hs auth">, z.ZodLiteral<"hs project create">, z.ZodLiteral<"hs project upload">]>>;
 }, z.core.$strip>;
 type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
 export declare class GuidedWalkthroughTool extends Tool<InputSchemaType> {

package/mcp-server/tools/project/GuidedWalkthroughTool.js

@@ -14,7 +14,12 @@ const nextCommands = {
 const inputSchema = {
     absoluteCurrentWorkingDirectory,
     command: z
-        .enum(['hs init', 'hs auth', 'hs project create', 'hs project upload'])
+        .union([
+        z.literal('hs init'),
+        z.literal('hs auth'),
+        z.literal('hs project create'),
+        z.literal('hs project upload'),
+    ])
         .describe('The command to learn more about.  Start with `hs init`')
         .optional(),
 };

package/mcp-server/tools/project/constants.d.ts

@@ -1,17 +1,6 @@
 import z from 'zod';
 export declare const absoluteProjectPath: z.ZodString;
 export declare const absoluteCurrentWorkingDirectory: z.ZodString;
-export declare const features: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-    card: "card";
-    settings: "settings";
-    "app-event": "app-event";
-    page: "page";
-    "workflow-action-tool": "workflow-action-tool";
-    webhooks: "webhooks";
-    "workflow-action": "workflow-action";
-    "app-function": "app-function";
-    "app-object": "app-object";
-    scim: "scim";
-}>>>;
+export declare const features: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"card">, z.ZodLiteral<"settings">, z.ZodLiteral<"app-function">, z.ZodLiteral<"webhooks">, z.ZodLiteral<"workflow-action">, z.ZodLiteral<"workflow-action-tool">, z.ZodLiteral<"app-object">, z.ZodLiteral<"app-event">, z.ZodLiteral<"scim">, z.ZodLiteral<"page">]>>>;
 export declare const docsSearchQuery: z.ZodString;
 export declare const docUrl: z.ZodString;

package/mcp-server/tools/project/constants.js

@@ -6,19 +6,23 @@ export const absoluteCurrentWorkingDirectory = z
     .string()
     .describe('The absolute path to the current working directory.');
 export const features = z
-    .array(z.enum([
-    'card',
-    'settings',
-    'app-function',
-    'webhooks',
-    'workflow-action',
-    'workflow-action-tool',
-    'app-object',
-    'app-event',
-    'scim',
-    'page',
+    .array(z.union([
+    z.literal('card'),
+    z.literal('settings'),
+    z
+        .literal('app-function')
+        .describe('Also known as a public serverless function'),
+    z.literal('webhooks'),
+    z
+        .literal('workflow-action')
+        .describe('Also known as a custom workflow action.'),
+    z.literal('workflow-action-tool').describe('Also known as agent tools.'),
+    z.literal('app-object'),
+    z.literal('app-event'),
+    z.literal('scim'),
+    z.literal('page'),
 ]))
-    .describe('The features to include in the project, multiple options can be selected. "app-function" is also known as a public serverless function. "workflow-action" is also known as a custom workflow action. "workflow-action-tool" is also known as agent tools.')
+    .describe('The features to include in the project, multiple options can be selected')
     .optional();
 export const docsSearchQuery = z
     .string()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/cli",
-    "version": "8.0.3-experimental.0",
+    "version": "8.0.3-experimental.1",
     "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.16",
         "@hubspot/local-dev-lib": "5.1.1",
-        "@hubspot/project-parsing-lib": "0.12.0",
+        "@hubspot/project-parsing-lib": "0.2.0-experimental.0",
         "@hubspot/serverless-dev-runtime": "7.0.7",
         "@hubspot/ui-extensions-dev-server": "1.1.8",
         "@inquirer/prompts": "7.1.0",