@hubspot/cli 8.16.0 → 8.17.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/bin/cli.js +19 -1
  2. package/commands/cms/lighthouseScore.js +1 -1
  3. package/commands/mcp/setup.d.ts +1 -0
  4. package/commands/mcp/setup.js +8 -1
  5. package/commands/project/download.d.ts +2 -0
  6. package/commands/project/download.js +56 -16
  7. package/lang/en.d.ts +61 -6
  8. package/lang/en.js +168 -11
  9. package/lib/agentHelp.d.ts +17 -0
  10. package/lib/agentHelp.js +90 -0
  11. package/lib/app/migrate.js +2 -5
  12. package/lib/commonOpts.js +4 -0
  13. package/lib/jsonOutput/projectDownload.d.ts +1 -0
  14. package/lib/jsonOutput/projectDownload.js +1 -0
  15. package/lib/mcp/clients.d.ts +2 -1
  16. package/lib/mcp/clients.js +7 -7
  17. package/lib/mcp/setup.d.ts +1 -1
  18. package/lib/mcp/setup.js +21 -36
  19. package/lib/mcp/skills.d.ts +8 -0
  20. package/lib/mcp/skills.js +64 -0
  21. package/lib/projects/archive.d.ts +8 -0
  22. package/lib/projects/archive.js +104 -0
  23. package/lib/projects/archiveDiff.d.ts +12 -0
  24. package/lib/projects/archiveDiff.js +68 -0
  25. package/lib/projects/config.js +1 -1
  26. package/lib/projects/download.d.ts +37 -0
  27. package/lib/projects/download.js +123 -0
  28. package/lib/projects/localDev/LocalDevWatcher.js +2 -1
  29. package/lib/prompts/importDataTestAccountSelectPrompt.js +1 -1
  30. package/lib/validation.js +16 -1
  31. package/lib/yargs/makeWrappedYargsHandler.d.ts +1 -0
  32. package/lib/yargs/makeWrappedYargsHandler.js +7 -0
  33. package/mcp-server/skills/hubspot-fix-build/SKILL.md +61 -0
  34. package/mcp-server/skills/hubspot-new-app/SKILL.md +84 -0
  35. package/mcp-server/tools/project/DocFetchTool.d.ts +4 -1
  36. package/mcp-server/tools/project/DocFetchTool.js +52 -7
  37. package/mcp-server/tools/project/FindProjectsTool.js +4 -1
  38. package/mcp-server/tools/project/GetBuildLogsTool.d.ts +1 -1
  39. package/package.json +6 -8
package/lang/en.js CHANGED
@@ -7,6 +7,7 @@ import { ARCHIVED_HUBSPOT_CONFIG_YAML_FILE_NAME, DEFAULT_HUBSPOT_CONFIG_YAML_FIL
7
7
  import { indent, UI_COLORS, uiAccountDescription, uiAuthCommandReference, uiBetaTag, uiCommandReference, uiDeprecatedTag, uiLink, } from '../lib/ui/index.js';
8
8
  import { getLocalDevUiUrl, getProjectDetailUrl, getProjectSettingsUrl, } from '../lib/projects/urls.js';
9
9
  import { getProductUpdatesUrl } from '../lib/links.js';
10
+ const AGENT_HELP_EXIT_CODES = '0 means success. 1 means an error. 2 means a warning, for example a validation issue or JSON output that does not match its schema.';
10
11
  const MIGRATION_SUPPORT_CUTOFF_NOTICE = 'Automated platform version migrations beyond 2026.09 will not be supported.';
11
12
  export const commands = {
12
13
  generalErrors: {
@@ -1336,7 +1337,6 @@ export const commands = {
1336
1337
  claudeCode: 'Claude Code',
1337
1338
  cursor: 'Cursor',
1338
1339
  devin: 'Devin',
1339
- gemini: 'Gemini CLI',
1340
1340
  opencode: 'OpenCode',
1341
1341
  vsCode: 'VSCode',
1342
1342
  other: 'Other (manual setup)',
@@ -1344,6 +1344,7 @@ export const commands = {
1344
1344
  client: 'Target apps to configure',
1345
1345
  standalone: 'Use npx for all of the hs commands run by the MCP server. This allows you to use the MCP server without having the CLI globally installed.',
1346
1346
  cliVersion: 'Pin a specific CLI version for standalone mode',
1347
+ skills: 'HubSpot skills to install for the selected tools. Pass --skills with no names to skip skills.',
1347
1348
  docsSearch: 'Should the docs search mcp server be installed',
1348
1349
  },
1349
1350
  examples: {
@@ -1372,11 +1373,6 @@ export const commands = {
1372
1373
  cursorNotFound: 'Cursor is not installed. Install it and re-run hs mcp setup.',
1373
1374
  failedToConfigureCursor: 'Failed to configure Cursor',
1374
1375
  configuredCursor: 'Configured Cursor',
1375
- // Gemini
1376
- configuringGemini: 'Configuring Gemini CLI...',
1377
- configuredGemini: 'Configured Gemini CLI',
1378
- geminiNotFound: "Gemini CLI is not installed (missing 'gemini' command). Install it and re-run hs mcp setup.",
1379
- geminiInstallFailed: 'Failed to configure Gemini CLI',
1380
1376
  alreadyInstalled: 'HubSpot CLI mcp server already installed, reinstalling',
1381
1377
  // Devin
1382
1378
  configuringDevin: 'Configuring Devin...',
@@ -1394,18 +1390,28 @@ export const commands = {
1394
1390
  configuredVsCode: 'Configured VSCode',
1395
1391
  vsCodeNotFound: "VSCode CLI is not installed (missing 'code' command). Install it and re-run hs mcp setup.",
1396
1392
  vsCodeVersionUnsupported: 'VSCode 1.99 or later is required for MCP server support. Please update VSCode and try again.',
1393
+ // Skills
1394
+ installingSkills: 'Installing HubSpot skills...',
1395
+ installedSkills: (skillNames, targetDirs) => `Installed ${skillNames.join(', ')} in ${targetDirs.join(', ')}`,
1396
+ failedToInstallSkills: 'Failed to install HubSpot skills',
1397
1397
  },
1398
1398
  otherInstructions: {
1399
1399
  header: 'To connect the HubSpot MCP server to another tool, add the following MCP server configuration.',
1400
1400
  docsNote: "Each tool handles MCP setup differently. Check your tool's documentation for how to add an MCP server using a command or JSON config.",
1401
1401
  commandLabel: 'Command:',
1402
1402
  jsonLabel: 'JSON configuration (for tools that use a config file):',
1403
+ skillsNote: (skillsDir) => `To add HubSpot skills, copy the folders in ${skillsDir} to your tool's skills folder.`,
1403
1404
  },
1404
1405
  prompts: {
1405
1406
  targets: '[--client] Which tools would you like to add the HubSpot CLI MCP server to?',
1406
1407
  targetsRequired: 'Must choose at least one app to configure.',
1407
1408
  standaloneMode: 'Do you want to run in standalone mode? (This will use npx @hubspot/cli instead of the installed hs command)',
1408
1409
  cliVersion: 'Specify a CLI version to pin (leave blank for latest):',
1410
+ selectSkills: '[--skills] Which HubSpot skills do you want to install? (optional)',
1411
+ },
1412
+ skillDescriptions: {
1413
+ newApp: 'Plan and create a HubSpot app project',
1414
+ fixBuild: 'Find and fix a failed project build',
1409
1415
  },
1410
1416
  },
1411
1417
  start: {
@@ -2024,26 +2030,54 @@ export const commands = {
2024
2030
  describe: 'Download your project files from HubSpot.',
2025
2031
  examples: {
2026
2032
  default: 'Download the project myProject into myProjectFolder folder',
2033
+ currentProject: 'Download build 3 of the current project into the current project directory',
2027
2034
  json: 'Output the download result as JSON for scripting',
2028
2035
  },
2029
2036
  logs: {
2030
2037
  downloadCancelled: 'Cancelling project download',
2031
2038
  downloadSucceeded: (buildId, projectName) => `Downloaded build "${buildId}" from project "${projectName}"`,
2039
+ filesOnlyInArchive: (files, hiddenCount, diffFilePath) => [
2040
+ 'These files existed locally but are not in the downloaded build. They are available in the archive directory:',
2041
+ ...files.map(file => `${indent(2)}- ${file}`),
2042
+ ...(hiddenCount > 0
2043
+ ? [`${indent(2)}...and ${hiddenCount} more`]
2044
+ : []),
2045
+ ...(hiddenCount > 0 && diffFilePath
2046
+ ? [`\nThe full list can be viewed in ${chalk.bold(diffFilePath)}`]
2047
+ : []),
2048
+ ].join('\n'),
2049
+ filesCopiedBack: (copiedCount, srcPath) => `Copied ${copiedCount} ${copiedCount === 1 ? 'file' : 'files'} back to ${chalk.bold(srcPath)}`,
2050
+ sourceContentsArchived: (archiveLocation) => `The previous contents of your project have been moved to ${archiveLocation}. Once you have reviewed them, you can safely delete that directory.`,
2032
2051
  },
2033
2052
  errors: {
2034
2053
  downloadFailed: 'Something went wrong downloading the project',
2035
2054
  projectNotFound: (projectName, accountId) => `Your project ${chalk.bold(projectName)} could not be found in ${accountId}`,
2036
2055
  noBuildIdToDownload: 'No build ID available for download',
2056
+ restoreFailed: (archiveDest) => `Extracting the downloaded build failed, and your original project files could not be restored automatically. They are in ${chalk.bold(archiveDest)}.`,
2057
+ archiveAlreadyExists: (archiveDest) => `Cannot download into the current project because ${chalk.bold(archiveDest)} already exists. Delete or rename it and run the command again.`,
2037
2058
  },
2038
2059
  warnings: {
2039
- cannotDownloadWithinProject: 'Cancelling project download. Please run the command again outside the context of an existing project.',
2060
+ filesNotCopiedBack: (failedCount) => `${failedCount} ${failedCount === 1 ? 'file' : 'files'} could not be copied back. ${failedCount === 1 ? 'It is' : 'They are'} still available in the archive directory.`,
2061
+ sourceWillBeArchived: (archiveLocation) => `Your current project source files will be moved to ${archiveLocation}.\nBack up any local changes in this project before you continue.`,
2062
+ sourceRestored: 'Extracting the downloaded build failed. Your original project files have been restored. The archive directory was left in place and can be deleted.',
2063
+ },
2064
+ archiveLocation: (archivePath) => `the archive directory in your project root (${chalk.bold(archivePath)})`,
2065
+ prompts: {
2066
+ confirmCopyFilesBack: (fileCount) => `[--keep-local-files] Copy ${fileCount === 1 ? 'this file' : `these ${fileCount} files`} back into your project source directory?`,
2067
+ confirmDownload: (buildId, projectName) => `[--force] Download build "${buildId}" of project "${projectName}"?`,
2040
2068
  },
2041
2069
  options: {
2042
2070
  build: {
2043
- describe: 'The build to download',
2071
+ describe: 'The build to download (defaults to the latest build)',
2072
+ },
2073
+ force: {
2074
+ describe: 'Skip the confirmation prompt before archiving your source',
2075
+ },
2076
+ keepLocalFiles: {
2077
+ describe: 'Copy local files missing from the build back into the source directory without prompting (--no-keep-local-files skips)',
2044
2078
  },
2045
2079
  project: {
2046
- describe: 'The name of the project to download',
2080
+ describe: 'The name of the project to download (defaults to the current project)',
2047
2081
  },
2048
2082
  dest: {
2049
2083
  describe: 'Destination folder for the project',
@@ -3411,6 +3445,120 @@ export const lib = {
3411
3445
  noSchemaForCommand: 'No schema defined for this command',
3412
3446
  validationFailed: 'JSON output may be missing or malformed fields. The output schema may be out of date.',
3413
3447
  },
3448
+ agentHelp: {
3449
+ headings: {
3450
+ conventions: chalk.bold('Conventions:'),
3451
+ jsonOutput: chalk.bold('JSON output:'),
3452
+ workflows: chalk.bold('Workflows:'),
3453
+ exitCodes: chalk.bold('Exit codes:'),
3454
+ commands: chalk.bold('All commands:'),
3455
+ },
3456
+ conventions: [
3457
+ 'More help: To see the workflows that use one command, run `hs <command> --agent-help`.',
3458
+ 'JSON output: Commands that support `--json` print one JSON object to stdout when they finish. Errors and warnings print to stderr.',
3459
+ 'JSON schemas: To print the JSON Schema for the output of a command, run the command with `--json-schema`.',
3460
+ 'Prompts: Commands prompt for values that you do not pass as flags. To run a command without prompts, pass each value as a flag.',
3461
+ 'Long-running commands: `hs project dev` runs until it is stopped and prompts for input. Ask the user to run it in their own terminal.',
3462
+ 'Accounts: Commands use the default account in the CLI config. To use a different account, pass `--account <name or ID>`. To see the configured accounts, run `hs account list`.',
3463
+ 'Environment variables: To read the account from `HUBSPOT_ACCOUNT_ID` and `HUBSPOT_PERSONAL_ACCESS_KEY` instead of the config file, pass `--use-env`.',
3464
+ 'Config file: The global config file is `~/.hscli/config.yml`. To use a different file, pass `--config <path>`.',
3465
+ 'Color: To remove color from the output, pass `--no-color` or set `NO_COLOR`.',
3466
+ 'Debug logs: To print debug logs, pass `--debug`.',
3467
+ 'MCP server: To connect the HubSpot Dev MCP server to an AI coding tool, run `hs mcp setup`.',
3468
+ ],
3469
+ jsonOutput: {
3470
+ schema: 'With `--json`, the command prints one JSON object to stdout. The object matches this JSON Schema:',
3471
+ noSchema: 'With `--json`, the command prints JSON to stdout. The CLI does not define a schema for this output.',
3472
+ },
3473
+ workflows: [
3474
+ {
3475
+ title: 'Authenticate an account',
3476
+ steps: [
3477
+ {
3478
+ command: 'hs account auth',
3479
+ description: 'Ask the user to run this command in their own terminal. It can open a browser page where the user creates a personal access key, and then it prompts for the key. Do not ask the user to paste the key into the conversation.',
3480
+ },
3481
+ {
3482
+ command: 'hs account list',
3483
+ description: 'List the accounts in the CLI config.',
3484
+ },
3485
+ {
3486
+ command: 'hs account use <account>',
3487
+ description: 'Set the default account. Commands use the default account unless you pass `--account`.',
3488
+ },
3489
+ ],
3490
+ },
3491
+ {
3492
+ title: 'Create a project',
3493
+ steps: [
3494
+ {
3495
+ command: 'hs project create --name <name> --dest <directory> --project-base app --distribution <private|marketplace> --auth <oauth|static> --features --json',
3496
+ description: 'Create a project with an app in a new directory. Pass every flag to skip the prompts. A `--features` flag with no values adds no features.',
3497
+ },
3498
+ {
3499
+ command: 'hs project validate --json',
3500
+ description: 'Run this command in the project directory. It checks the project files before you upload them.',
3501
+ },
3502
+ ],
3503
+ },
3504
+ {
3505
+ title: 'Generate test data',
3506
+ steps: [
3507
+ {
3508
+ command: 'hs test-account create --name <name> --description <description> --marketing-level ENTERPRISE --ops-level ENTERPRISE --service-level ENTERPRISE --sales-level ENTERPRISE --content-level ENTERPRISE --commerce-level ENTERPRISE',
3509
+ description: 'Create a developer test account and save it to the CLI config. Pass every flag to skip the prompts. Do not pass `--json`. With `--json`, the command does not save the account to the config, and the output includes the personal access key of the account.',
3510
+ },
3511
+ {
3512
+ command: 'hs test-account import-data --account <test account> --file-path <import.json> --skip-confirm',
3513
+ description: 'Import CRM records into the test account. The JSON file uses the request format of the CRM imports API: https://developers.hubspot.com/docs/guides/api/crm/imports. Each `fileName` in the file is a path relative to the current directory.',
3514
+ },
3515
+ ],
3516
+ },
3517
+ {
3518
+ title: 'Develop a project',
3519
+ steps: [
3520
+ {
3521
+ command: 'hs project create',
3522
+ description: 'Create the project. The "Create a project" workflow shows the flags that skip the prompts.',
3523
+ },
3524
+ {
3525
+ command: 'hs project upload --json',
3526
+ description: 'Run this command in the project directory. It uploads the project and creates a build. If auto-deploy is on, it also deploys the build, and the output includes `deployId`.',
3527
+ },
3528
+ {
3529
+ command: 'hs project deploy --build <buildId> --json',
3530
+ description: 'Deploy the build. Use this command if the upload output has no `deployId`.',
3531
+ },
3532
+ {
3533
+ command: 'hs project dev',
3534
+ description: 'Ask the user to run this command in their own terminal. It starts local development and runs until it is stopped. Changes upload from the Local Dev Panel, or as you edit with `--auto-upload`. To test on a test account, also pass `--testing-account <test account ID>` and `--project-account <developer account ID>`.',
3535
+ },
3536
+ {
3537
+ command: 'hs project list-builds --limit 1 --json',
3538
+ description: 'Show the status of the latest build. `deployedBuildId` is the build that is deployed now.',
3539
+ },
3540
+ ],
3541
+ },
3542
+ {
3543
+ title: 'Investigate a failed build',
3544
+ steps: [
3545
+ {
3546
+ command: 'hs project list-builds --limit 1 --json',
3547
+ description: 'Get the latest build. Each entry in `subbuildStatuses` has the status and error message of one component.',
3548
+ },
3549
+ {
3550
+ command: 'hs project validate --json',
3551
+ description: 'Validate the local project files.',
3552
+ },
3553
+ {
3554
+ command: 'hs project upload --json',
3555
+ description: 'Upload the project again after you fix the errors.',
3556
+ },
3557
+ ],
3558
+ },
3559
+ ],
3560
+ exitCodes: AGENT_HELP_EXIT_CODES,
3561
+ },
3414
3562
  DevServerManager: {
3415
3563
  portConflict: (port) => `The port ${port} is already in use.`,
3416
3564
  notInitialized: 'The Dev Server Manager must be initialized before it is started.',
@@ -3652,6 +3800,12 @@ export const lib = {
3652
3800
  generateSafeFilenameDifferentiator: {
3653
3801
  failedToCheckFiles: 'Failed to check files for filename differentiator. Falling back to timestamp.',
3654
3802
  },
3803
+ archive: {
3804
+ errors: {
3805
+ archiveNotFound: (archiveDest) => `Archive directory not found: ${archiveDest}`,
3806
+ srcDirInsideArchive: (srcDir) => `The source directory "${srcDir}" cannot be the archive directory or inside it`,
3807
+ },
3808
+ },
3655
3809
  validateProjectConfig: {
3656
3810
  configNotFound: `Unable to locate a project configuration file. Try running again from a project directory, or run ${uiCommandReference('hs project create')} to create a new project.`,
3657
3811
  },
@@ -3905,6 +4059,7 @@ export const lib = {
3905
4059
  useEnv: 'Use environment variable config',
3906
4060
  jsonOutput: 'Format output as JSON',
3907
4061
  jsonSchema: 'Print the JSON output schema and exit',
4062
+ agentHelp: 'Show help with workflows and conventions for AI agents',
3908
4063
  debug: 'Set log level to debug',
3909
4064
  color: 'Enable colored output (use --no-color to disable)',
3910
4065
  },
@@ -3965,6 +4120,7 @@ export const lib = {
3965
4120
  message: (dataFileNames, cliAccount) => `You are importing [${dataFileNames.join(', ')}] into ${uiAccountDescription(cliAccount?.accountId)}. Continue?`,
3966
4121
  },
3967
4122
  importDataTestAccountSelectPrompt: {
4123
+ message: '[--account] Select a developer test account:',
3968
4124
  errors: {
3969
4125
  noAccountsFound: 'No accounts found.',
3970
4126
  noChildTestAccountsFound: (parentAccountId) => `No developer test accounts found under the parent account ${uiAccountDescription(parentAccountId)}`,
@@ -4129,9 +4285,9 @@ export const lib = {
4129
4285
  },
4130
4286
  },
4131
4287
  downloadProjectPrompt: {
4132
- selectProject: 'Select a project to download:',
4288
+ selectProject: '[--project] Select a project to download:',
4133
4289
  errors: {
4134
- projectNotFound: (projectName, accountId) => `Your project ${projectName} could not be found in ${accountId}. Please select a valid project:`,
4290
+ projectNotFound: (projectName, accountId) => `[--project] Your project ${projectName} could not be found in ${uiAccountDescription(accountId)}. Please select a valid project:`,
4135
4291
  accountIdRequired: 'An account ID is required to download a project.',
4136
4292
  },
4137
4293
  },
@@ -4492,6 +4648,7 @@ export const lib = {
4492
4648
  oauth2AccessTokenNotFound: (accountId) => `The OAuth2 access token could not be found for accountId ${uiAccountDescription(accountId)}`,
4493
4649
  personalAccessKeyMissing: (accountId) => `The account "${uiAccountDescription(accountId)}" is configured to use a access key for authentication and is missing a "personalAccessKey" in the configuration file`,
4494
4650
  personalAccessKeyTokenRetrievalFailed: (accountId) => `An OAuth2 access token for account "${uiAccountDescription(accountId)} could not be retrieved using the "personalAccessKey" provided`,
4651
+ accessTokenMissing: (accountId) => `The account "${uiAccountDescription(accountId)}" is configured to use an access token for authentication and is missing an access token`,
4495
4652
  authConfigurationMissing: (accountId) => `The accountId ${uiAccountDescription(accountId)} is missing authentication configuration`,
4496
4653
  availableCMSModes: (modes) => `Available CMS publish modes are: ${modes}`,
4497
4654
  invalidCmsPublishMode: (cmsPublishMode, modesMessage) => `The CMS publish mode "${cmsPublishMode}" is invalid. ${modesMessage}`,
@@ -0,0 +1,17 @@
1
+ import { Argv } from 'yargs';
2
+ type CommandModule = {
3
+ command?: string | readonly string[];
4
+ describe?: string | false;
5
+ builder?: unknown;
6
+ handler?: unknown;
7
+ };
8
+ export declare function recordCommands(instance: Argv): CommandModule[];
9
+ type VisitedCommand = {
10
+ module: CommandModule;
11
+ commandPath: string[];
12
+ usage: string;
13
+ };
14
+ export declare function walkCommands(modules: CommandModule[], visit: (command: VisitedCommand) => void, parentPath?: string[]): Promise<void>;
15
+ export declare function getRootAgentHelp(rootCommands: CommandModule[]): Promise<string>;
16
+ export declare function getCommandAgentHelp(command: string, helpText: string): string;
17
+ export {};
@@ -0,0 +1,90 @@
1
+ import yargs from 'yargs';
2
+ import { z } from 'zod';
3
+ import { lib } from '../lang/en.js';
4
+ import { indent } from './ui/index.js';
5
+ import { debugError } from './errorHandlers/index.js';
6
+ import { getJsonOutputSchema } from './yargs/makeWrappedYargsHandler.js';
7
+ const { agentHelp } = lib;
8
+ function formatSection(heading, lines) {
9
+ return [heading, ...lines.map(line => `${indent(1)}${line}`)].join('\n');
10
+ }
11
+ function formatWorkflows(workflows) {
12
+ return formatSection(agentHelp.headings.workflows, workflows.flatMap(({ title, steps }) => [
13
+ title,
14
+ ...steps.flatMap(({ command, description }, index) => [
15
+ `${indent(1)}${index + 1}. ${command}`,
16
+ `${indent(2)} ${description}`,
17
+ ]),
18
+ ]));
19
+ }
20
+ export function recordCommands(instance) {
21
+ const commands = [];
22
+ const { command } = instance;
23
+ Object.assign(instance, {
24
+ command(...args) {
25
+ const [module] = args;
26
+ if (typeof module === 'object' && module !== null) {
27
+ commands.push(module);
28
+ }
29
+ return Reflect.apply(command, instance, args);
30
+ },
31
+ });
32
+ return commands;
33
+ }
34
+ export async function walkCommands(modules, visit, parentPath = []) {
35
+ for (const module of modules) {
36
+ const [commandString = ''] = [module.command ?? []].flat();
37
+ const commandPath = [...parentPath, commandString.split(' ')[0]];
38
+ visit({
39
+ module,
40
+ commandPath,
41
+ usage: ['hs', ...parentPath, commandString].join(' '),
42
+ });
43
+ const instance = yargs([]);
44
+ const subcommands = recordCommands(instance);
45
+ try {
46
+ if (typeof module.builder === 'function') {
47
+ await module.builder(instance);
48
+ }
49
+ }
50
+ catch (e) {
51
+ debugError(e);
52
+ }
53
+ await walkCommands(subcommands, visit, commandPath);
54
+ }
55
+ }
56
+ function joinSections(sections) {
57
+ return sections.filter(Boolean).join('\n\n');
58
+ }
59
+ function formatExitCodes() {
60
+ return formatSection(agentHelp.headings.exitCodes, [agentHelp.exitCodes]);
61
+ }
62
+ export async function getRootAgentHelp(rootCommands) {
63
+ const commandLines = [];
64
+ await walkCommands(rootCommands, ({ module, usage }) => {
65
+ if (typeof module.describe === 'string') {
66
+ commandLines.push(`- ${usage}: ${module.describe.replace(/\s*\n\s*/g, ' ')}`);
67
+ }
68
+ });
69
+ return joinSections([
70
+ formatSection(agentHelp.headings.conventions, agentHelp.conventions.map(convention => `- ${convention}`)),
71
+ formatWorkflows(agentHelp.workflows),
72
+ formatSection(agentHelp.headings.commands, commandLines),
73
+ formatExitCodes(),
74
+ ]);
75
+ }
76
+ export function getCommandAgentHelp(command, helpText) {
77
+ const jsonOutputSchema = getJsonOutputSchema(command.replace(/^hs /, '').replaceAll(' ', '-'));
78
+ const workflows = agentHelp.workflows.filter(({ steps }) => steps.some(step => `${step.command} `.startsWith(`${command} `)));
79
+ return joinSections([
80
+ helpText.includes('--json') &&
81
+ formatSection(agentHelp.headings.jsonOutput, jsonOutputSchema
82
+ ? [
83
+ agentHelp.jsonOutput.schema,
84
+ ...JSON.stringify(z.toJSONSchema(jsonOutputSchema), null, 2).split('\n'),
85
+ ]
86
+ : [agentHelp.jsonOutput.noSchema]),
87
+ workflows.length > 0 && formatWorkflows(workflows),
88
+ formatExitCodes(),
89
+ ]);
90
+ }
@@ -11,11 +11,11 @@ import { downloadProject, fetchProjectComponentsMetadata, } from '@hubspot/local
11
11
  import { Separator } from '@inquirer/prompts';
12
12
  import { confirmPrompt, inputPrompt, listPrompt, } from '../prompts/promptUtils.js';
13
13
  import { uiAccountDescription, uiCommandReference, uiLine, uiLink, } from '../ui/index.js';
14
+ import { archiveProjectSource } from '../projects/archive.js';
14
15
  import { ensureProjectExists } from '../projects/ensureProjectExists.js';
15
16
  import SpinniesManager from '../ui/SpinniesManager.js';
16
17
  import { DEFAULT_POLLING_STATUS_LOOKUP, poll } from '../polling.js';
17
18
  import { checkMigrationStatusV2, CLI_UNMIGRATABLE_REASONS, continueAppMigration, initializeAppMigration, isMigrationStatus, listAppsForMigration, } from '../../api/migrate.js';
18
- import fs from 'fs';
19
19
  import { lib } from '../../lang/en.js';
20
20
  import { hasUnfiedAppsAccess } from '../hasFeature.js';
21
21
  import { getProjectBuildDetailUrl, getProjectDetailUrl, } from '../projects/urls.js';
@@ -311,11 +311,8 @@ export async function downloadProjectFiles(derivedAccountId, projectName, buildI
311
311
  const { projectDir } = projectConfig;
312
312
  absoluteDestPath = projectDir;
313
313
  const { srcDir } = projectConfig.projectConfig;
314
- const archiveDest = srcDir === '.'
315
- ? path.join(path.dirname(projectDir), `${path.basename(projectDir)}-archive`)
316
- : path.join(projectDir, 'archive');
317
314
  // Move the existing source directory to archive
318
- fs.renameSync(path.join(projectDir, srcDir), archiveDest);
315
+ const archiveDest = archiveProjectSource(projectDir, srcDir);
319
316
  uiLogger.info(lib.migrate.sourceContentsMoved(archiveDest));
320
317
  }
321
318
  else {
package/lib/commonOpts.js CHANGED
@@ -10,6 +10,7 @@ import { uiCommandReference } from './ui/index.js';
10
10
  import { lib } from '../lang/en.js';
11
11
  import { getTerminalUISupport, UI_COLORS } from './ui/index.js';
12
12
  import SpinniesManager from './ui/SpinniesManager.js';
13
+ import { getCommandAgentHelp } from './agentHelp.js';
13
14
  export function addGlobalOptions(yargs) {
14
15
  yargs.version(false);
15
16
  yargs.option('debug', {
@@ -129,6 +130,9 @@ export async function addCustomHelpOutput(yargs, command, describe) {
129
130
  const fullCommand = `${commandBase.trim()} ${commandString}`;
130
131
  // Format the original help output to be more readable
131
132
  let commandHelp = await yargs.getHelp();
133
+ if (parsedArgv.agentHelp) {
134
+ commandHelp = `${commandHelp}\n\n${getCommandAgentHelp(`${commandBase.trim()} ${commandString.split(' ')[0]}`, commandHelp)}`;
135
+ }
132
136
  ['Options:', 'Commands:', 'Examples:', 'Positionals:'].forEach(header => {
133
137
  commandHelp = commandHelp.replace(header, chalk.bold(header));
134
138
  });
@@ -3,5 +3,6 @@ export declare const ProjectDownloadSchema: z.ZodObject<{
3
3
  projectName: z.ZodString;
4
4
  buildId: z.ZodNumber;
5
5
  dest: z.ZodString;
6
+ archiveDest: z.ZodOptional<z.ZodString>;
6
7
  }, z.core.$strip>;
7
8
  export type ProjectDownloadJsonOutput = z.infer<typeof ProjectDownloadSchema>;
@@ -3,4 +3,5 @@ export const ProjectDownloadSchema = z.object({
3
3
  projectName: z.string(),
4
4
  buildId: z.number(),
5
5
  dest: z.string(),
6
+ archiveDest: z.string().optional(),
6
7
  });
@@ -1,5 +1,5 @@
1
1
  export declare const MCP_SERVER_NAME = "HubSpotDev";
2
- export type McpClientId = 'codex' | 'claude' | 'cursor' | 'devin' | 'gemini' | 'opencode' | 'vscode';
2
+ export type McpClientId = 'codex' | 'claude' | 'cursor' | 'devin' | 'opencode' | 'vscode';
3
3
  type McpClientDetection = {
4
4
  type: 'json' | 'text';
5
5
  pathSegments: string[];
@@ -7,6 +7,7 @@ type McpClientDetection = {
7
7
  export type McpClient = {
8
8
  id: McpClientId;
9
9
  detection: McpClientDetection;
10
+ skillsPathSegments: string[];
10
11
  };
11
12
  export declare const MCP_CLIENTS: McpClient[];
12
13
  export declare function getMcpClientPathSegments(id: McpClientId): string[];
@@ -1,4 +1,5 @@
1
1
  export const MCP_SERVER_NAME = 'HubSpotDev';
2
+ const SHARED_SKILLS_PATH_SEGMENTS = ['.agents', 'skills'];
2
3
  function getVsCodeMcpConfigPathSegments() {
3
4
  if (process.platform === 'darwin') {
4
5
  return ['Library', 'Application Support', 'Code', 'User', 'mcp.json'];
@@ -15,21 +16,17 @@ export const MCP_CLIENTS = [
15
16
  type: 'text',
16
17
  pathSegments: ['.codex', 'config.toml'],
17
18
  },
19
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
18
20
  },
19
21
  {
20
22
  id: 'claude',
21
23
  detection: { type: 'json', pathSegments: ['.claude.json'] },
24
+ skillsPathSegments: ['.claude', 'skills'],
22
25
  },
23
26
  {
24
27
  id: 'cursor',
25
28
  detection: { type: 'json', pathSegments: ['.cursor', 'mcp.json'] },
26
- },
27
- {
28
- id: 'gemini',
29
- detection: {
30
- type: 'json',
31
- pathSegments: ['.gemini', 'settings.json'],
32
- },
29
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
33
30
  },
34
31
  {
35
32
  id: 'vscode',
@@ -37,6 +34,7 @@ export const MCP_CLIENTS = [
37
34
  type: 'json',
38
35
  pathSegments: getVsCodeMcpConfigPathSegments(),
39
36
  },
37
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
40
38
  },
41
39
  {
42
40
  id: 'devin',
@@ -44,6 +42,7 @@ export const MCP_CLIENTS = [
44
42
  type: 'json',
45
43
  pathSegments: ['.codeium', 'windsurf', 'mcp_config.json'],
46
44
  },
45
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
47
46
  },
48
47
  {
49
48
  id: 'opencode',
@@ -51,6 +50,7 @@ export const MCP_CLIENTS = [
51
50
  type: 'json',
52
51
  pathSegments: ['.config', 'opencode', 'config.json'],
53
52
  },
53
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
54
54
  },
55
55
  ];
56
56
  export function getMcpClientPathSegments(id) {
@@ -11,6 +11,7 @@ interface ConfigureMcpServerOptions {
11
11
  targets?: string[];
12
12
  standalone?: boolean;
13
13
  cliVersion?: string;
14
+ skills?: string[];
14
15
  }
15
16
  export declare function configureMcpServer(options: ConfigureMcpServerOptions): Promise<string[]>;
16
17
  export declare function setupVsCode(mcpCommand?: McpCommand): Promise<boolean>;
@@ -18,6 +19,5 @@ export declare function setupClaudeCode(mcpCommand?: McpCommand): Promise<boolea
18
19
  export declare function setupCursor(mcpCommand?: McpCommand): boolean;
19
20
  export declare function setupDevin(mcpCommand?: McpCommand): boolean;
20
21
  export declare function setupCodex(mcpCommand?: McpCommand): Promise<boolean>;
21
- export declare function setupGemini(mcpCommand?: McpCommand): Promise<boolean>;
22
22
  export declare function setupOpenCode(mcpCommand?: McpCommand): Promise<boolean>;
23
23
  export {};