@hubspot/cli 8.1.0 → 8.1.2-experimental.0

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/uieLinting.d.ts

@@ -1,10 +1,19 @@
 export declare const REQUIRED_PACKAGES_AND_MIN_VERSIONS: {
     readonly eslint: "9.0.0";
-    readonly '@typescript-eslint/eslint-plugin': "8.46.4";
-    readonly '@typescript-eslint/parser': "8.46.4";
+    readonly '@eslint/js': "9.0.0";
     readonly 'typescript-eslint': "8.46.4";
+    readonly '@hubspot/eslint-config-ui-extensions': "1.0.0";
+    readonly 'eslint-config-prettier': "10.0.0";
+    readonly 'eslint-plugin-react': "7.0.0";
+    readonly 'eslint-plugin-react-hooks': "7.0.0";
+    readonly 'eslint-plugin-unused-imports': "4.0.0";
+    readonly prettier: "3.0.0";
     readonly jiti: "2.6.1";
 };
+export declare const LINT_SCRIPTS: {
+    readonly lint: "eslint .";
+    readonly 'lint:fix': "eslint . --fix";
+};
 export declare function isEslintInstalled(directory: string): boolean;
 export declare function areAllLintPackagesInstalled(directory: string): boolean;
 export declare function getMissingLintPackages(directory: string): {
@@ -13,7 +22,7 @@ export declare function getMissingLintPackages(directory: string): {
 export declare function hasEslintConfig(directory: string): boolean;
 export declare function hasDeprecatedEslintConfig(directory: string): boolean;
 export declare function getDeprecatedEslintConfigFiles(directory: string): string[];
-export declare function createEslintConfig(directory: string): string;
+export declare function createEslintConfig(directory: string, platformVersion?: string | null): Promise<string>;
 export declare function lintPackagesInDirectory(directory: string, projectDir?: string): Promise<{
     success: boolean;
     output: string;
@@ -31,3 +40,8 @@ export declare function displayLintResults(results: Array<{
     success: boolean;
     output: string;
 }>): void;
+export declare function getMissingLintScripts(directory: string): string[];
+export declare function addLintScriptsToPackageJson(directory: string): {
+    added: string[];
+    relativePath: string;
+};

package/lib/projects/uieLinting.js

@@ -3,17 +3,27 @@ import path from 'path';
 import util from 'util';
 import semver from 'semver';
 import { exec as execAsync } from 'node:child_process';
+import { fetchRepoFile } from '@hubspot/local-dev-lib/api/github';
 import { getProjectPackageJsonLocations, isPackageInstalled, } from '../dependencyManagement.js';
 import { commands } from '../../lang/en.js';
 import { uiLogger } from '../ui/logger.js';
-import { safeGetPackageJsonCached } from '../npm/packageJson.js';
+import { clearPackageJsonCache, safeGetPackageJsonCached, } from '../npm/packageJson.js';
+import { debugError } from '../errorHandlers/index.js';
+import { isLegacyProject } from '@hubspot/project-parsing-lib/projects';
+import { HUBSPOT_PROJECT_COMPONENTS_GITHUB_PATH, DEFAULT_PROJECT_TEMPLATE_BRANCH, } from '../constants.js';
 export const REQUIRED_PACKAGES_AND_MIN_VERSIONS = {
     eslint: '9.0.0',
-    '@typescript-eslint/eslint-plugin': '8.46.4',
-    '@typescript-eslint/parser': '8.46.4',
+    '@eslint/js': '9.0.0',
     'typescript-eslint': '8.46.4',
+    '@hubspot/eslint-config-ui-extensions': '1.0.0',
+    'eslint-config-prettier': '10.0.0',
+    'eslint-plugin-react': '7.0.0',
+    'eslint-plugin-react-hooks': '7.0.0',
+    'eslint-plugin-unused-imports': '4.0.0',
+    prettier: '3.0.0',
     jiti: '2.6.1',
 };
+const UIE_ESLINT_CONFIG_PATH_IN_REPO = 'components/cards/src/app/cards/eslint.config.js';
 const ESLINT_CONFIG_FILES = [
     'eslint.config.mts',
     'eslint.config.ts',
@@ -30,28 +40,10 @@ const DEPRECATED_ESLINT_CONFIG_FILES = [
     '.eslintrc.json',
     '.eslintrc',
 ];
-const ESLINT_CONFIG_TEMPLATE = `import { defineConfig } from "eslint/config";
-import tsParser from "@typescript-eslint/parser";
-
-export default defineConfig([
-  {
-    files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
-    languageOptions: {
-      parser: tsParser,
-      parserOptions: {
-        ecmaVersion: "latest",
-        sourceType: "module",
-        ecmaFeatures: {
-          jsx: true
-        }
-      }
-    },
-    rules: {
-      "no-console": ["warn", { allow: ["warn", "error"] }]
-    }
-  },
-]);
-`;
+export const LINT_SCRIPTS = {
+    lint: 'eslint .',
+    'lint:fix': 'eslint . --fix',
+};
 function getPackageVersionFromPackageJson(directory, packageName) {
     const packageJsonPath = path.join(directory, 'package.json');
     const packageJson = safeGetPackageJsonCached(packageJsonPath);
@@ -127,10 +119,43 @@ export function getDeprecatedEslintConfigFiles(directory) {
         return fs.existsSync(configPath);
     });
 }
-export function createEslintConfig(directory) {
-    const configPath = path.join(directory, 'eslint.config.mts');
+function repoFileDataToString(data) {
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (Buffer.isBuffer(data)) {
+        return data.toString('utf-8');
+    }
+    return String(data);
+}
+export async function createEslintConfig(directory, platformVersion) {
+    const versionForRemote = platformVersion && !isLegacyProject(platformVersion)
+        ? platformVersion
+        : null;
+    if (versionForRemote === null) {
+        const message = commands.project.lint.createEslintConfigRequiresV2Platform(platformVersion);
+        uiLogger.error(message);
+        throw new Error(message);
+    }
+    let fetchedContent = null;
     try {
-        fs.writeFileSync(configPath, ESLINT_CONFIG_TEMPLATE, 'utf-8');
+        const { data } = await fetchRepoFile(HUBSPOT_PROJECT_COMPONENTS_GITHUB_PATH, `${versionForRemote}/${UIE_ESLINT_CONFIG_PATH_IN_REPO}`, DEFAULT_PROJECT_TEMPLATE_BRANCH);
+        const content = repoFileDataToString(data);
+        if (content.trim().length > 0) {
+            fetchedContent = content;
+        }
+    }
+    catch (error) {
+        debugError(error);
+    }
+    if (fetchedContent === null) {
+        const message = commands.project.lint.failedToFetchRemoteEslintConfig(versionForRemote);
+        uiLogger.error(message);
+        throw new Error(message);
+    }
+    const configPath = path.join(directory, 'eslint.config.js');
+    try {
+        fs.writeFileSync(configPath, fetchedContent, 'utf-8');
         return path.relative(process.cwd(), configPath);
     }
     catch (error) {
@@ -218,3 +243,43 @@ export function displayLintResults(results) {
         });
     }
 }
+export function getMissingLintScripts(directory) {
+    const packageJsonPath = path.join(directory, 'package.json');
+    const packageJson = safeGetPackageJsonCached(packageJsonPath);
+    if (!packageJson) {
+        return [];
+    }
+    return Object.keys(LINT_SCRIPTS).filter(scriptName => !packageJson.scripts?.[scriptName]);
+}
+export function addLintScriptsToPackageJson(directory) {
+    const packageJsonPath = path.join(directory, 'package.json');
+    try {
+        const rawContent = fs.readFileSync(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(rawContent);
+        if (!packageJson.scripts) {
+            packageJson.scripts = {};
+        }
+        const added = [];
+        for (const [scriptName, scriptValue] of Object.entries(LINT_SCRIPTS)) {
+            if (!packageJson.scripts[scriptName]) {
+                packageJson.scripts[scriptName] = scriptValue;
+                added.push(scriptName);
+            }
+        }
+        if (added.length > 0) {
+            fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
+            clearPackageJsonCache();
+        }
+        return {
+            added,
+            relativePath: path.relative(process.cwd(), packageJsonPath),
+        };
+    }
+    catch {
+        uiLogger.warn(commands.project.lint.failedToAddLintScripts(packageJsonPath));
+        return {
+            added: [],
+            relativePath: path.relative(process.cwd(), packageJsonPath),
+        };
+    }
+}

package/lib/projects/upload.d.ts

@@ -4,6 +4,8 @@ type ProjectUploadCallbackFunction<T> = (accountId: number, projectConfig: Proje
 type ProjectUploadResult<T> = {
     result?: T;
     uploadError?: unknown;
+    projectNotFound?: boolean;
+    projectId?: number;
 };
 type HandleProjectUploadArg<T> = {
     accountId: number;
@@ -15,9 +17,10 @@ type HandleProjectUploadArg<T> = {
     isUploadCommand?: boolean;
     sendIR?: boolean;
     skipValidation?: boolean;
+    skipNpmAudit?: boolean;
     profile?: string;
 };
-export declare function handleProjectUpload<T>({ accountId, projectConfig, projectDir, callbackFunc, profile, uploadMessage, forceCreate, isUploadCommand, sendIR, skipValidation, }: HandleProjectUploadArg<T>): Promise<ProjectUploadResult<T>>;
+export declare function handleProjectUpload<T>({ accountId, projectConfig, projectDir, callbackFunc, profile, uploadMessage, forceCreate, isUploadCommand, sendIR, skipValidation, skipNpmAudit, }: HandleProjectUploadArg<T>): Promise<ProjectUploadResult<T>>;
 export declare function validateSourceDirectory(srcDir: string, projectConfig: ProjectConfig, projectDir: string): Promise<void>;
 export declare function validateNoHSMetaMismatch(srcDir: string, projectConfig: ProjectConfig): Promise<void>;
 type HandleTranslateArg = {

package/lib/projects/upload.js

@@ -6,18 +6,19 @@ 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';
 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 { 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, getPackageJsonPathsToUpdate, getLockfilePathsToUpdate, } from './workspaces.js';
+import { isLegacyProject } from '@hubspot/project-parsing-lib/projects';
+import { runNpmAuditsBeforeProjectUpload } from './npmAuditOnUpload.js';
 async function uploadProjectFiles(accountId, projectName, filePath, uploadMessage, platformVersion, intermediateRepresentation) {
     const accountIdentifier = uiAccountDescription(accountId) || `${accountId}`;
     SpinniesManager.add('upload', {
@@ -44,64 +45,82 @@ async function uploadProjectFiles(accountId, projectName, filePath, uploadMessag
     }
     return { buildId, error };
 }
-export async function handleProjectUpload({ accountId, projectConfig, projectDir, callbackFunc, profile, uploadMessage = '', forceCreate = false, isUploadCommand = false, sendIR = false, skipValidation = false, }) {
+export async function handleProjectUpload({ accountId, projectConfig, projectDir, callbackFunc, profile, uploadMessage = '', forceCreate = false, isUploadCommand = false, sendIR = false, skipValidation = false, skipNpmAudit = false, }) {
     const srcDir = path.resolve(projectDir, projectConfig.srcDir);
-    try {
-        await validateSourceDirectory(srcDir, projectConfig, projectDir);
-    }
-    catch (e) {
-        logError(e);
-        process.exit(EXIT_CODES.ERROR);
-    }
-    try {
-        await validateNoHSMetaMismatch(srcDir, projectConfig);
-    }
-    catch (e) {
-        logError(e);
-        process.exit(EXIT_CODES.ERROR);
-    }
+    await validateSourceDirectory(srcDir, 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 = [];
+    let parsedPackageJsons = [];
+    if (!isLegacyProject(projectConfig.platformVersion)) {
+        parsedPackageJsons = await findAndParsePackageJsonFiles(srcDir);
+        workspaceMappings = await collectWorkspaceDirectories(parsedPackageJsons);
+        fileDependencyMappings = await collectFileDependencies(parsedPackageJsons);
+    }
+    if (isUploadCommand && !skipNpmAudit) {
+        await runNpmAuditsBeforeProjectUpload({
+            srcDir,
+            projectDir,
+            parsedPackageJsons,
+            isLegacyPlatform: isLegacyProject(projectConfig.platformVersion),
+        });
+    }
     const output = fs.createWriteStream(tempFile.name);
     const archive = archiver('zip');
-    const result = new Promise(resolve => output.on('close', async function () {
-        uiLogger.debug(lib.projectUpload.handleProjectUpload.compressed(archive.pointer()));
-        let intermediateRepresentation;
-        if (sendIR) {
-            try {
-                intermediateRepresentation = await handleTranslate({
-                    projectDir,
-                    projectConfig,
-                    accountId,
-                    skipValidation,
-                    profile,
-                });
+    const result = new Promise((resolve, reject) => output.on('close', async function () {
+        try {
+            uiLogger.debug(lib.projectUpload.handleProjectUpload.compressed(archive.pointer()));
+            let intermediateRepresentation;
+            if (sendIR) {
+                try {
+                    intermediateRepresentation = await handleTranslate({
+                        projectDir,
+                        projectConfig,
+                        accountId,
+                        skipValidation,
+                        profile,
+                    });
+                }
+                catch (e) {
+                    return resolve({ uploadError: e });
+                }
             }
-            catch (e) {
-                resolve({ uploadError: e });
+            const { projectExists, project } = await ensureProjectExists(accountId, projectConfig.name, {
+                forceCreate,
+                uploadCommand: isUploadCommand,
+                noLogs: true,
+            });
+            if (!projectExists) {
+                uiLogger.log(lib.projectUpload.handleProjectUpload.projectDoesNotExist(accountId));
+                return resolve({ projectNotFound: true });
+            }
+            const projectId = project?.id;
+            const { buildId, error } = await uploadProjectFiles(accountId, projectConfig.name, tempFile.name, uploadMessage, projectConfig.platformVersion, intermediateRepresentation);
+            if (error) {
+                resolve({ uploadError: error, projectId });
+            }
+            else if (callbackFunc) {
+                const uploadResult = await callbackFunc(accountId, projectConfig, tempFile, buildId);
+                resolve({ result: uploadResult, projectId });
             }
         }
-        const { projectExists } = await ensureProjectExists(accountId, projectConfig.name, {
-            forceCreate,
-            uploadCommand: isUploadCommand,
-            noLogs: true,
-        });
-        if (!projectExists) {
-            uiLogger.log(lib.projectUpload.handleProjectUpload.projectDoesNotExist(accountId));
-            process.exit(EXIT_CODES.SUCCESS);
-        }
-        const { buildId, error } = await uploadProjectFiles(accountId, projectConfig.name, tempFile.name, uploadMessage, projectConfig.platformVersion, intermediateRepresentation);
-        if (error) {
-            resolve({ uploadError: error });
-        }
-        else if (callbackFunc) {
-            const uploadResult = await callbackFunc(accountId, projectConfig, tempFile, buildId);
-            resolve({ result: uploadResult });
+        catch (e) {
+            reject(e);
         }
     }));
     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');
@@ -114,6 +133,8 @@ export async function handleProjectUpload({ accountId, projectConfig, projectDir
         }
         return ignored ? false : file;
     });
+    // Archive workspaces and file: dependencies
+    await archiveWorkspacesAndDependencies(archive, srcDir, workspaceMappings, fileDependencyMappings);
     archive.finalize();
     return result;
 }
@@ -122,7 +143,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)) {
@@ -133,7 +154,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/watch.d.ts

@@ -1,4 +1,5 @@
 import { ProjectConfig } from '../../types/Projects.js';
 type ProjectWatchHandlerFunction = (accountId: number, projectName: string, currentBuildId: number) => Promise<void> | void;
-export declare function createWatcher(accountId: number, projectConfig: ProjectConfig, projectDir: string, handleBuildStatusFn: ProjectWatchHandlerFunction, handleUserInputFn: ProjectWatchHandlerFunction): Promise<void>;
+type WatchTerminationHandler = (error?: unknown) => void;
+export declare function createWatcher(accountId: number, projectConfig: ProjectConfig, projectDir: string, handleBuildStatusFn: ProjectWatchHandlerFunction, handleUserInputFn: ProjectWatchHandlerFunction, handleWatchTerminationFn: WatchTerminationHandler): Promise<void>;
 export {};

package/lib/projects/watch.js

@@ -18,6 +18,7 @@ const standbyQueue = [];
 let currentBuildId;
 let handleBuildStatus;
 let handleUserInput;
+let handleWatchTermination = () => { };
 let timer;
 async function processStandByQueue(accountId, projectName, platformVersion) {
     queue.addAll(standbyQueue.map(({ filePath, remotePath, action }) => {
@@ -37,33 +38,39 @@ function debounceQueueBuild(accountId, projectName, platformVersion) {
         clearTimeout(timer);
     }
     timer = setTimeout(async () => {
-        uiLogger.debug(commands.project.watch.debug.pause);
-        queue.pause();
-        await queue.onIdle();
         try {
-            await queueBuild(accountId, projectName, platformVersion);
-            uiLogger.debug(commands.project.watch.debug.buildStarted);
-        }
-        catch (err) {
-            if (isSpecifiedError(err, {
-                subCategory: PROJECT_ERROR_TYPES.MISSING_PROJECT_PROVISION,
-            })) {
-                uiLogger.log(commands.project.watch.logs.watchCancelledFromUi);
-                process.exit(0);
+            uiLogger.debug(commands.project.watch.debug.pause);
+            queue.pause();
+            await queue.onIdle();
+            try {
+                await queueBuild(accountId, projectName, platformVersion);
+                uiLogger.debug(commands.project.watch.debug.buildStarted);
+            }
+            catch (err) {
+                if (isSpecifiedError(err, {
+                    subCategory: PROJECT_ERROR_TYPES.MISSING_PROJECT_PROVISION,
+                })) {
+                    uiLogger.log(commands.project.watch.logs.watchCancelledFromUi);
+                    handleWatchTermination();
+                    return;
+                }
+                else {
+                    logError(err, new ApiErrorContext({ accountId }));
+                }
+                return;
             }
-            else {
-                logError(err, new ApiErrorContext({ accountId }));
+            await handleBuildStatus(accountId, projectName, currentBuildId);
+            await createNewStagingBuild(accountId, projectName, platformVersion);
+            if (standbyQueue.length > 0) {
+                await processStandByQueue(accountId, projectName, platformVersion);
             }
-            return;
+            queue.start();
+            uiLogger.log(commands.project.watch.logs.resuming);
+            uiLogger.log(`\n> Press ${chalk.bold('q')} to quit watching\n`);
         }
-        await handleBuildStatus(accountId, projectName, currentBuildId);
-        await createNewStagingBuild(accountId, projectName, platformVersion);
-        if (standbyQueue.length > 0) {
-            await processStandByQueue(accountId, projectName, platformVersion);
+        catch (err) {
+            handleWatchTermination(err);
         }
-        queue.start();
-        uiLogger.log(commands.project.watch.logs.resuming);
-        uiLogger.log(`\n> Press ${chalk.bold('q')} to quit watching\n`);
     }, 2000);
 }
 async function queueFileOrFolder(accountId, projectName, platformVersion, filePath, remotePath, action) {
@@ -111,7 +118,7 @@ async function createNewBuild(accountId, projectName, platformVersion) {
             await cancelStagedBuild(accountId, projectName);
             uiLogger.log(commands.project.watch.logs.previousStagingBuildCancelled);
         }
-        process.exit(1);
+        throw err;
     }
 }
 async function handleWatchEvent(accountId, projectName, platformVersion, projectSourceDir, filePath, action = 'upload') {
@@ -132,10 +139,11 @@ async function handleWatchEvent(accountId, projectName, platformVersion, project
         await queueFileOrFolder(accountId, projectName, platformVersion, filePath, remotePath, action);
     }
 }
-export async function createWatcher(accountId, projectConfig, projectDir, handleBuildStatusFn, handleUserInputFn) {
+export async function createWatcher(accountId, projectConfig, projectDir, handleBuildStatusFn, handleUserInputFn, handleWatchTerminationFn) {
     const projectSourceDir = path.join(projectDir, projectConfig.srcDir);
     handleBuildStatus = handleBuildStatusFn;
     handleUserInput = handleUserInputFn;
+    handleWatchTermination = handleWatchTerminationFn;
     await createNewStagingBuild(accountId, projectConfig.name, projectConfig.platformVersion);
     const watcher = chokidar.watch(projectSourceDir, {
         ignoreInitial: true,

package/lib/projects/workspaces.d.ts

@@ -0,0 +1,52 @@
+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;
+/**
+ * Converts native path separators to POSIX forward slashes.
+ *
+ * Zip entry names and npm workspace globs are POSIX-only. On Windows,
+ * `path.relative` returns backslash-separated paths; archiver normalizes
+ * its appended entry names to forward slashes but its filter callback
+ * receives forward-slashed names too. Without this normalization, lookups
+ * in our exclusion Sets miss on Windows and a file gets archived twice.
+ */
+export declare function toPosixPath(p: 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, workspaceMappings: WorkspaceMapping[], fileDependencyMappings: FileDependencyMapping[]): Promise<WorkspaceArchiveResult>;