@hubspot/cli 8.2.0 → 8.2.1-experimental.0

package/commands/project/release/info.js

@@ -0,0 +1,148 @@
+import { getReleaseInfo, listReleases } from '../../../api/releases.js';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+import { logError, ApiErrorContext } from '../../../lib/errorHandlers/index.js';
+import { getProjectConfig, validateProjectConfig, } from '../../../lib/projects/config.js';
+import { listPrompt } from '../../../lib/prompts/promptUtils.js';
+import { EXIT_CODES } from '../../../lib/enums/exitCodes.js';
+import { uiLogger } from '../../../lib/ui/logger.js';
+import { makeYargsBuilder } from '../../../lib/yargsUtils.js';
+import { commands } from '../../../lang/en.js';
+import { renderTable } from '../../../ui/render.js';
+import { makeWrappedYargsHandler } from '../../../lib/yargs/makeWrappedYargsHandler.js';
+import { isPromptExitError } from '../../../lib/errors/PromptExitError.js';
+import { mapToUserFacingType } from '@hubspot/project-parsing-lib/transform';
+import { AUTO_GENERATED_COMPONENT_TYPES } from '@hubspot/project-parsing-lib/constants';
+import { ReleaseSchema, mapReleaseToJsonOutput, } from '../../../lib/jsonOutput.js';
+const command = 'info';
+// const describe = commands.project.release.info.describe;
+const describe = undefined;
+// const verboseDescribe = commands.project.release.info.verboseDescribe;
+const verboseDescribe = undefined;
+function normalizeTag(rawTag) {
+    return rawTag.startsWith('v') ? rawTag : `v${rawTag}`;
+}
+async function selectReleasePrompt(accountId, projectName) {
+    const { data: { results, paging }, } = await listReleases(accountId, projectName);
+    if (results.length === 0) {
+        return null;
+    }
+    if (paging?.next?.after) {
+        uiLogger.info(commands.project.release.info.moreReleasesHint);
+    }
+    return listPrompt(commands.project.release.info.selectRelease(projectName), {
+        choices: results.map(release => ({
+            name: `${release.releaseTag} (build #${release.buildId}, ${new Date(release.createdAt).toLocaleString()})`,
+            value: release.releaseTag,
+        })),
+    });
+}
+async function handler(args) {
+    const { derivedAccountId, tag: rawTag, json: formatOutputAsJson, exit, addJsonOutput, } = args;
+    const { projectConfig, projectDir } = await getProjectConfig();
+    try {
+        validateProjectConfig(projectConfig, projectDir);
+    }
+    catch (error) {
+        logError(error);
+        return exit(EXIT_CODES.ERROR);
+    }
+    const projectName = projectConfig.name;
+    let tag;
+    if (rawTag) {
+        tag = normalizeTag(rawTag);
+    }
+    else {
+        try {
+            const selected = await selectReleasePrompt(derivedAccountId, projectName);
+            if (!selected) {
+                uiLogger.error(commands.project.release.info.errors.noReleases);
+                return exit(EXIT_CODES.ERROR);
+            }
+            tag = selected;
+        }
+        catch (e) {
+            if (isPromptExitError(e)) {
+                throw e;
+            }
+            logError(e);
+            return exit(EXIT_CODES.ERROR);
+        }
+    }
+    try {
+        const { data: release } = await getReleaseInfo(derivedAccountId, projectName, tag);
+        addJsonOutput(mapReleaseToJsonOutput(release));
+        if (!formatOutputAsJson) {
+            uiLogger.log(commands.project.release.info.releaseDetails(release.releaseTag, projectName));
+            renderTable(['Release', 'Build', 'Created'], [
+                [
+                    release.releaseTag,
+                    `#${release.buildId}`,
+                    new Date(release.createdAt).toLocaleString(),
+                ],
+            ]);
+            const visibleComponents = (release.components ?? []).filter(component => !AUTO_GENERATED_COMPONENT_TYPES.includes(component.buildType));
+            if (visibleComponents.length > 0) {
+                uiLogger.log('');
+                uiLogger.log(commands.project.release.info.components);
+                const componentRows = visibleComponents.map(component => [
+                    mapToUserFacingType(component.buildType),
+                    component.buildName ?? '',
+                    component.rootPath ?? '',
+                ]);
+                renderTable(['Type', 'Name', 'Path'], componentRows);
+            }
+            else {
+                uiLogger.log('');
+                uiLogger.log(commands.project.release.info.noComponents);
+            }
+        }
+    }
+    catch (e) {
+        if (isHubSpotHttpError(e) && e.status === 404) {
+            uiLogger.error(commands.project.release.info.errors.releaseNotFound(tag, projectName));
+        }
+        else {
+            logError(e, new ApiErrorContext({
+                accountId: derivedAccountId,
+                request: 'project release info',
+            }));
+        }
+        return exit(EXIT_CODES.ERROR);
+    }
+    return exit(EXIT_CODES.SUCCESS);
+}
+function projectReleaseInfoBuilder(yargs) {
+    yargs.options({
+        tag: {
+            describe: commands.project.release.info.options.tag,
+            type: 'string',
+        },
+    });
+    yargs.example([
+        [
+            '$0 project release info --tag=v1.0.0',
+            commands.project.release.info.examples.default,
+        ],
+        [
+            '$0 project release info --tag=v1.0.0 --json',
+            commands.project.release.info.examples.json,
+        ],
+    ]);
+    return yargs;
+}
+const builder = makeYargsBuilder(projectReleaseInfoBuilder, command, verboseDescribe, {
+    useGlobalOptions: true,
+    useConfigOptions: true,
+    useAccountOptions: true,
+    useEnvironmentOptions: true,
+    useJSONOutputOptions: true,
+});
+const projectReleaseInfoCommand = {
+    command,
+    describe,
+    builder,
+    handler: makeWrappedYargsHandler('project-release-info', handler, {
+        jsonOutputSchema: ReleaseSchema,
+    }),
+};
+export default projectReleaseInfoCommand;

package/commands/project/release/list.d.ts

@@ -0,0 +1,7 @@
+import { CommonArgs, ConfigArgs, AccountArgs, EnvironmentArgs, JSONOutputArgs, YargsCommandModule } from '../../../types/Yargs.js';
+import { ReleaseListJsonOutput } from '../../../lib/jsonOutput.js';
+export type ProjectReleaseListArgs = CommonArgs & ConfigArgs & AccountArgs & EnvironmentArgs & JSONOutputArgs<ReleaseListJsonOutput> & {
+    limit?: number;
+};
+declare const projectReleaseListCommand: YargsCommandModule<unknown, ProjectReleaseListArgs>;
+export default projectReleaseListCommand;

package/commands/project/release/list.js

@@ -0,0 +1,119 @@
+import { listReleases } from '../../../api/releases.js';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+import { isPromptExitError } from '../../../lib/errors/PromptExitError.js';
+import { logError, ApiErrorContext } from '../../../lib/errorHandlers/index.js';
+import { getProjectConfig, validateProjectConfig, } from '../../../lib/projects/config.js';
+import { promptUser } from '../../../lib/prompts/promptUtils.js';
+import { EXIT_CODES } from '../../../lib/enums/exitCodes.js';
+import { uiLogger } from '../../../lib/ui/logger.js';
+import { makeYargsBuilder } from '../../../lib/yargsUtils.js';
+import { commands } from '../../../lang/en.js';
+import { renderTable } from '../../../ui/render.js';
+import { makeWrappedYargsHandler } from '../../../lib/yargs/makeWrappedYargsHandler.js';
+import { ReleaseListSchema, mapReleaseToJsonOutput, } from '../../../lib/jsonOutput.js';
+const command = 'list';
+// const describe = commands.project.release.list.describe;
+const describe = undefined;
+// const verboseDescribe = commands.project.release.list.verboseDescribe;
+const verboseDescribe = undefined;
+async function fetchAndDisplayReleases(accountId, projectName, options) {
+    const { data: { results, paging }, } = await listReleases(accountId, projectName, options);
+    if (results.length === 0) {
+        uiLogger.log(commands.project.release.list.noReleases);
+    }
+    else {
+        const rows = results.map(release => [
+            release.releaseTag,
+            `#${release.buildId}`,
+            new Date(release.createdAt).toLocaleString(),
+        ]);
+        renderTable(['Release', 'Build', 'Created'], rows);
+        uiLogger.log(commands.project.release.list.showingReleases(results.length, projectName));
+    }
+    if (paging?.next?.after) {
+        await promptUser({
+            name: 'more',
+            message: commands.project.release.list.continueOrExitPrompt,
+        });
+        await fetchAndDisplayReleases(accountId, projectName, {
+            limit: options.limit,
+            after: paging.next.after,
+        });
+    }
+}
+async function handler(args) {
+    const { derivedAccountId, limit, json: formatOutputAsJson, exit, addJsonOutput, } = args;
+    const { projectConfig, projectDir } = await getProjectConfig();
+    try {
+        validateProjectConfig(projectConfig, projectDir);
+    }
+    catch (error) {
+        logError(error);
+        return exit(EXIT_CODES.ERROR);
+    }
+    const projectName = projectConfig.name;
+    try {
+        if (formatOutputAsJson) {
+            const { data } = await listReleases(derivedAccountId, projectName, {
+                limit,
+            });
+            addJsonOutput({
+                results: data.results.map(mapReleaseToJsonOutput),
+                paging: data.paging
+                    ? { next: { after: data.paging.next.after } }
+                    : undefined,
+            });
+        }
+        else {
+            await fetchAndDisplayReleases(derivedAccountId, projectName, { limit });
+        }
+    }
+    catch (e) {
+        if (isPromptExitError(e)) {
+            throw e;
+        }
+        if (isHubSpotHttpError(e) && e.status === 404) {
+            uiLogger.error(commands.project.release.list.errors.projectNotFound(derivedAccountId, projectName));
+        }
+        else {
+            logError(e, new ApiErrorContext({
+                accountId: derivedAccountId,
+                request: 'project release list',
+            }));
+        }
+        return exit(EXIT_CODES.ERROR);
+    }
+    return exit(EXIT_CODES.SUCCESS);
+}
+function projectReleaseListBuilder(yargs) {
+    yargs.options({
+        limit: {
+            describe: commands.project.release.list.options.limit,
+            type: 'number',
+        },
+    });
+    yargs.example([
+        ['$0 project release list', commands.project.release.list.examples.default],
+        [
+            '$0 project release list --limit=5',
+            commands.project.release.list.examples.withLimit,
+        ],
+    ]);
+    return yargs;
+}
+const builder = makeYargsBuilder(projectReleaseListBuilder, command, verboseDescribe, {
+    useGlobalOptions: true,
+    useConfigOptions: true,
+    useAccountOptions: true,
+    useEnvironmentOptions: true,
+    useJSONOutputOptions: true,
+});
+const projectReleaseListCommand = {
+    command,
+    describe,
+    builder,
+    handler: makeWrappedYargsHandler('project-release-list', handler, {
+        jsonOutputSchema: ReleaseListSchema,
+    }),
+};
+export default projectReleaseListCommand;

package/commands/project/release.d.ts

@@ -0,0 +1,3 @@
+import { YargsCommandModuleBucket } from '../../types/Yargs.js';
+declare const projectReleaseCommand: YargsCommandModuleBucket;
+export default projectReleaseCommand;

package/commands/project/release.js

@@ -0,0 +1,20 @@
+import create from './release/create.js';
+import info from './release/info.js';
+import list from './release/list.js';
+import { makeYargsBuilder } from '../../lib/yargsUtils.js';
+// import { commands } from '../../lang/en.js';
+const command = 'release';
+// const describe = commands.project.release.describe;
+const describe = undefined;
+function projectReleaseBuilder(yargs) {
+    yargs.command(create).command(info).command(list).demandCommand(1, '');
+    return yargs;
+}
+const builder = makeYargsBuilder(projectReleaseBuilder, command, describe);
+const projectReleaseCommand = {
+    command,
+    describe,
+    builder,
+    handler: () => { },
+};
+export default projectReleaseCommand;

package/commands/project/updateDeps.js

@@ -1,23 +1,23 @@
 import { updatePackages, getProjectPackageJsonLocations, } from '../../lib/dependencyManagement.js';
 import { EXIT_CODES } from '../../lib/enums/exitCodes.js';
+import { isPromptExitError } from '../../lib/errors/PromptExitError.js';
 import { getProjectConfig } from '../../lib/projects/config.js';
 import { promptUser } from '../../lib/prompts/promptUtils.js';
 import path from 'path';
 import { commands } from '../../lang/en.js';
 import { uiLogger } from '../../lib/ui/logger.js';
-import { trackCommandUsage } from '../../lib/usageTracking.js';
+import { makeWrappedYargsHandler } from '../../lib/yargs/makeWrappedYargsHandler.js';
 import { logError } from '../../lib/errorHandlers/index.js';
 import { makeYargsBuilder } from '../../lib/yargsUtils.js';
 const command = 'update-deps [packages..]';
 const describe = commands.project.updateDeps.help.describe;
 async function handler(args) {
-    const { derivedAccountId, packages } = args;
+    const { packages, exit } = args;
     try {
-        trackCommandUsage('project-update-deps', undefined, derivedAccountId);
         const projectConfig = await getProjectConfig();
         if (!projectConfig || !projectConfig.projectDir) {
             uiLogger.error(commands.project.updateDeps.noProjectConfig);
-            return process.exit(EXIT_CODES.ERROR);
+            return exit(EXIT_CODES.ERROR);
         }
         const { projectDir } = projectConfig;
         let installLocations = await getProjectPackageJsonLocations();
@@ -50,8 +50,11 @@ async function handler(args) {
         });
     }
     catch (e) {
+        if (isPromptExitError(e)) {
+            throw e;
+        }
         logError(e);
-        return process.exit(EXIT_CODES.ERROR);
+        return exit(EXIT_CODES.ERROR);
     }
 }
 function projectUpdateDepsBuilder(yargs) {
@@ -74,7 +77,7 @@ const builder = makeYargsBuilder(projectUpdateDepsBuilder, command, describe, {
 const projectUpdateDepsCommand = {
     command,
     describe,
-    handler,
+    handler: makeWrappedYargsHandler('project-update-deps', handler),
     builder,
 };
 export default projectUpdateDepsCommand;

package/commands/project/upload.d.ts

@@ -1,10 +1,16 @@
 import { CommonArgs, JSONOutputArgs, YargsCommandModule } from '../../types/Yargs.js';
-export type ProjectUploadArgs = CommonArgs & JSONOutputArgs & {
+import { UploadJsonOutput } from '../../lib/jsonOutput.js';
+export type ProjectUploadArgs = CommonArgs & JSONOutputArgs<UploadJsonOutput> & {
+    force: boolean;
     forceCreate: boolean;
     message: string;
     m: string;
     skipValidation: boolean;
+    skipNpmAudit: boolean;
+    skipAutoDeploy: boolean;
     profile?: string;
+    preview: boolean;
+    target?: number;
 };
 declare const projectUploadCommand: YargsCommandModule<unknown, ProjectUploadArgs>;
 export default projectUploadCommand;

package/commands/project/upload.js

@@ -2,58 +2,101 @@ import chalk from 'chalk';
 import { uiLogger } from '../../lib/ui/logger.js';
 import { getConfigAccountById } from '@hubspot/local-dev-lib/config';
 import { isSpecifiedError } from '@hubspot/local-dev-lib/errors/index';
-import { isV2Project } from '../../lib/projects/platformVersion.js';
-import { trackCommandUsage } from '../../lib/usageTracking.js';
+import { isLegacyProject, meetsMinimumPlatformVersion, } from '@hubspot/project-parsing-lib/projects';
 import { getProjectConfig, validateProjectConfig, } from '../../lib/projects/config.js';
 import { logFeedbackMessage } from '../../lib/projects/ui.js';
 import { handleProjectUpload } from '../../lib/projects/upload.js';
 import { loadAndValidateProfile } from '../../lib/projects/projectProfiles.js';
 import { displayWarnLogs, pollProjectBuildAndDeploy, } from '../../lib/projects/pollProjectBuildAndDeploy.js';
-import { commands } from '../../lang/en.js';
+import { triggerAndPollPreview } from '../../lib/projects/preview.js';
+import { commands, lib } from '../../lang/en.js';
 import { PROJECT_ERROR_TYPES } from '../../lib/constants.js';
 import { logError, ApiErrorContext } from '../../lib/errorHandlers/index.js';
 import { EXIT_CODES } from '../../lib/enums/exitCodes.js';
+import { makeWrappedYargsHandler } from '../../lib/yargs/makeWrappedYargsHandler.js';
+import { UploadSchema, } from '../../lib/jsonOutput.js';
 import { makeYargsBuilder } from '../../lib/yargsUtils.js';
+import { projectProfilePrompt } from '../../lib/prompts/projectProfilePrompt.js';
+import { uiDeprecatedTag } from '../../lib/ui/index.js';
+import { showMcpPromotionNudge } from '../../lib/mcp/promotion.js';
+import { PLATFORM_VERSIONS } from '@hubspot/project-parsing-lib/constants';
 const command = 'upload';
 const describe = commands.project.upload.describe;
+async function handlePreview(accountId, projectId, buildId, targetPortalId) {
+    if (!projectId) {
+        uiLogger.warn(lib.projectPreview.missingProjectId);
+        return;
+    }
+    const previewResult = await triggerAndPollPreview(accountId, projectId, buildId, targetPortalId);
+    if (!previewResult.succeeded) {
+        uiLogger.warn(lib.projectPreview.warning);
+    }
+    return {
+        releaseTag: previewResult.releaseTag,
+        succeeded: previewResult.succeeded,
+    };
+}
 async function handler(args) {
-    const { forceCreate, message, derivedAccountId, skipValidation, formatOutputAsJson, profile, } = args;
-    const jsonOutput = {};
+    const { force = false, forceCreate = false, message, derivedAccountId, skipValidation, skipNpmAudit, skipAutoDeploy, formatOutputAsJson, profile: profileOption, useEnv: useEnvOption, preview, target: targetPortalId, exit, addUsageMetadata, addJsonOutput, } = args;
+    if (forceCreate) {
+        uiDeprecatedTag(commands.project.upload.logs.forceCreateDeprecated);
+    }
     const { projectConfig, projectDir } = await getProjectConfig();
     try {
         validateProjectConfig(projectConfig, projectDir);
     }
     catch (error) {
         logError(error);
-        process.exit(EXIT_CODES.ERROR);
+        return exit(EXIT_CODES.ERROR);
+    }
+    if (!projectDir) {
+        uiLogger.error(commands.project.upload.errors.noProjectConfig);
+        return exit(EXIT_CODES.ERROR);
     }
     let targetAccountId;
-    try {
-        if (isV2Project(projectConfig.platformVersion)) {
-            targetAccountId = await loadAndValidateProfile(projectConfig, projectDir, profile);
+    let profileName = args.profile;
+    if (!isLegacyProject(projectConfig?.platformVersion)) {
+        try {
+            const profileNamePromptResult = await projectProfilePrompt(projectDir, projectConfig, profileOption, !!useEnvOption);
+            if (profileNamePromptResult) {
+                profileName = profileNamePromptResult;
+                const profile = await loadAndValidateProfile(projectConfig, projectDir, profileName);
+                targetAccountId = profile.accountId;
+            }
+        }
+        catch (error) {
+            logError(error);
+            return exit(EXIT_CODES.ERROR);
         }
-    }
-    catch (err) {
-        logError(err);
-        process.exit(EXIT_CODES.ERROR);
     }
     targetAccountId = targetAccountId || derivedAccountId;
     const accountConfig = getConfigAccountById(targetAccountId);
     const accountType = accountConfig && accountConfig.accountType;
-    trackCommandUsage('project-upload', { type: accountType, assetType: projectConfig.platformVersion }, targetAccountId);
+    addUsageMetadata({
+        type: accountType,
+        assetType: projectConfig.platformVersion,
+    });
     try {
-        const { result, uploadError } = await handleProjectUpload({
+        const { result, uploadError, projectId, userDeclined } = await handleProjectUpload({
             accountId: targetAccountId,
             projectConfig,
-            projectDir: projectDir,
-            callbackFunc: pollProjectBuildAndDeploy,
+            projectDir,
+            callbackFunc: preview || skipAutoDeploy
+                ? (...args) => pollProjectBuildAndDeploy(...args, { skipDeploy: true })
+                : pollProjectBuildAndDeploy,
             uploadMessage: message,
-            forceCreate,
+            forceCreate: forceCreate || force,
             isUploadCommand: true,
-            sendIR: isV2Project(projectConfig.platformVersion),
+            sendIR: !isLegacyProject(projectConfig.platformVersion),
             skipValidation,
-            profile: args.profile,
+            skipNpmAudit,
+            skipAutoDeploy,
+            profile: profileName,
+            force,
         });
+        if (userDeclined) {
+            return exit(EXIT_CODES.SUCCESS);
+        }
         if (uploadError) {
             if (isSpecifiedError(uploadError, {
                 subCategory: PROJECT_ERROR_TYPES.PROJECT_LOCKED,
@@ -68,39 +111,71 @@ async function handler(args) {
                     request: 'project upload',
                 }));
             }
-            process.exit(EXIT_CODES.ERROR);
+            return exit(EXIT_CODES.ERROR);
         }
-        if (result && result.succeeded && !result.buildResult.isAutoDeployEnabled) {
+        if (result &&
+            result.succeeded &&
+            (!result.buildResult.isAutoDeployEnabled || preview || skipAutoDeploy)) {
             uiLogger.log(chalk.bold(commands.project.upload.logs.buildSucceeded(result.buildId)));
-            uiLogger.log(commands.project.upload.logs.autoDeployDisabled(`hs project deploy --build=${result.buildId}`));
-            logFeedbackMessage(result.buildId);
+            if (!preview) {
+                if (meetsMinimumPlatformVersion(result.buildResult.platformVersion, PLATFORM_VERSIONS.v2026_09_BETA)) {
+                    const releaseCommand = `hs project release create --build=${result.buildId}`;
+                    uiLogger.log(commands.project.upload.logs.releaseManagementRequired(releaseCommand));
+                }
+                else {
+                    const deployCommand = `hs project deploy --build=${result.buildId}`;
+                    uiLogger.log(skipAutoDeploy
+                        ? commands.project.upload.logs.autoDeploySkipped(deployCommand)
+                        : commands.project.upload.logs.autoDeployDisabled(deployCommand));
+                }
+                logFeedbackMessage(result.buildId);
+            }
             await displayWarnLogs(targetAccountId, projectConfig.name, result.buildId);
         }
-        if (result && result.succeeded && formatOutputAsJson) {
-            jsonOutput.buildId = result.buildId;
+        if (result && result.succeeded && preview && targetPortalId) {
+            const previewJson = await handlePreview(targetAccountId, projectId, result.buildId, targetPortalId);
+            if (previewJson) {
+                addJsonOutput({ preview: previewJson });
+            }
+        }
+        if (result) {
+            addJsonOutput({ buildId: result.buildId });
             if (result.deployResult) {
-                jsonOutput.deployId = result.deployResult.deployId;
+                addJsonOutput({ deployId: result.deployResult.deployId });
             }
         }
+        if (result && !result.succeeded) {
+            return exit(EXIT_CODES.ERROR);
+        }
+        if (!result && !uploadError) {
+            return exit(EXIT_CODES.ERROR);
+        }
     }
     catch (e) {
         logError(e, new ApiErrorContext({
             accountId: targetAccountId,
             request: 'project upload',
         }));
-        process.exit(EXIT_CODES.ERROR);
+        return exit(EXIT_CODES.ERROR);
     }
-    if (formatOutputAsJson) {
-        uiLogger.json(jsonOutput);
+    if (!formatOutputAsJson) {
+        await showMcpPromotionNudge(args._.join(' '));
     }
-    process.exit(EXIT_CODES.SUCCESS);
+    return exit(EXIT_CODES.SUCCESS);
 }
 function projectUploadBuilder(yargs) {
     yargs.options({
+        force: {
+            alias: 'f',
+            describe: commands.project.upload.options.force.describe,
+            type: 'boolean',
+            default: false,
+        },
         'force-create': {
             describe: commands.project.upload.options.forceCreate.describe,
             type: 'boolean',
             default: false,
+            hidden: true,
         },
         message: {
             alias: 'm',
@@ -113,11 +188,42 @@ function projectUploadBuilder(yargs) {
             hidden: true,
             default: false,
         },
+        'skip-npm-audit': {
+            describe: commands.project.upload.options.skipNpmAudit.describe,
+            type: 'boolean',
+            default: false,
+        },
+        'skip-auto-deploy': {
+            describe: commands.project.upload.options.skipAutoDeploy.describe,
+            type: 'boolean',
+            default: false,
+        },
         profile: {
             type: 'string',
             alias: 'p',
             describe: commands.project.upload.options.profile.describe,
         },
+        preview: {
+            describe: commands.project.upload.options.preview.describe,
+            type: 'boolean',
+            default: false,
+            hidden: true,
+        },
+        target: {
+            describe: commands.project.upload.options.target.describe,
+            type: 'number',
+            requiresArg: true,
+            hidden: true,
+        },
+    });
+    yargs.check(argv => {
+        if (argv.preview && argv.target == null) {
+            throw new Error(commands.project.upload.errors.previewRequiresTarget);
+        }
+        if (argv.target != null && !argv.preview) {
+            throw new Error(commands.project.upload.errors.targetRequiresPreview);
+        }
+        return true;
     });
     yargs.conflicts('profile', 'account');
     yargs.example([
@@ -126,6 +232,11 @@ function projectUploadBuilder(yargs) {
             '$0 project upload --profile=profileName',
             commands.project.upload.examples.withProfile,
         ],
+        // TODO: Unhide when 2026.09 ships
+        // [
+        //   '$0 project upload --preview --target=12345',
+        //   commands.project.upload.examples.withPreview,
+        // ],
     ]);
     return yargs;
 }
@@ -139,7 +250,9 @@ const builder = makeYargsBuilder(projectUploadBuilder, command, describe, {
 const projectUploadCommand = {
     command,
     describe,
-    handler,
+    handler: makeWrappedYargsHandler('project-upload', handler, {
+        jsonOutputSchema: UploadSchema,
+    }),
     builder,
 };
 export default projectUploadCommand;

package/commands/project/validate.d.ts

@@ -1,5 +1,5 @@
 import { CommonArgs, YargsCommandModule } from '../../types/Yargs.js';
-type ProjectValidateArgs = CommonArgs & {
+export type ProjectValidateArgs = CommonArgs & {
     profile?: string;
 };
 declare const projectValidateCommand: YargsCommandModule<unknown, ProjectValidateArgs>;