@hubspot/project-parsing-lib 0.2.2-experimental.0 → 0.2.2-experimental.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/project-parsing-lib",
-    "version": "0.2.2-experimental.0",
+    "version": "0.2.2-experimental.1",
     "description": "Parsing library for converting projects directory structures to their intermediate representation",
     "license": "Apache-2.0",
     "type": "module",
@@ -111,7 +111,7 @@
         "@inquirer/prompts": "^7.1.0",
         "@types/node": "^24.9.0",
         "@types/npm-packlist": "7.0.3",
-        "@types/npmcli__map-workspaces": "^3.0.4",
+        "@types/npmcli__map-workspaces": "3.0.4",
         "@types/semver": "^7.5.8",
         "@typescript-eslint/eslint-plugin": "8.54.0",
         "@typescript-eslint/parser": "8.54.0",
@@ -127,7 +127,7 @@
     },
     "dependencies": {
         "@hubspot/local-dev-lib": "4.0.4",
-        "@npmcli/map-workspaces": "^4.0.2",
+        "@npmcli/map-workspaces": "4.0.2",
         "ajv": "8.18.0",
         "ajv-formats": "3.0.1",
         "glob": "13.0.0",

package/src/exports/projects.d.ts

@@ -1,4 +1,4 @@
 export { getProjectMetadata } from '../lib/project.js';
 export { projectContainsHsMetaFiles } from '../lib/files.js';
 export type { ProjectMetadata } from '../lib/project.js';
-export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isLegacyProject, } from '../lib/platformVersion.js';
+export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isLegacyProject, supportsComponentPermissions, } from '../lib/platformVersion.js';

package/src/exports/projects.js

@@ -1,3 +1,3 @@
 export { getProjectMetadata } from '../lib/project.js';
 export { projectContainsHsMetaFiles } from '../lib/files.js';
-export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isLegacyProject, } from '../lib/platformVersion.js';
+export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isLegacyProject, supportsComponentPermissions, } from '../lib/platformVersion.js';

package/src/exports/translate.d.ts

@@ -1,3 +1,3 @@
 export { translate, translateForLocalDev } from '../lib/translate.js';
 export { isTranslationError, type TranslationError } from '../lib/errors.js';
-export type { IntermediateRepresentation, IntermediateRepresentationLocalDev, IntermediateRepresentationNodeLocalDev, IntermediateRepresentationNode, TranslationContext, TranslationOptions, TranslationOptionsLocalDev, ComponentMeta, } from '../lib/types.js';
+export type { IntermediateRepresentation, IntermediateRepresentationLocalDev, IntermediateRepresentationNodeLocalDev, IntermediateRepresentationNode, TranslationContext, TranslationOptions, TranslationOptionsLocalDev, ComponentMeta, ComponentPermissions, } from '../lib/types.js';

package/src/lang/copy.d.ts

@@ -33,6 +33,7 @@ export declare const errorMessages: {
         unsupportedType: (type: string) => string;
         errorWithField: (field: string, error: string | undefined) => string;
         invalidJson: string;
+        permissionsNotSupported: (platformVersion: string) => string;
         unexpectedToplevelFields: (unexpectedFields: string) => string;
         wrongDirectoryForComponent: (directory: string, componentType: string, componentMetadata: ComponentMetadata, correctDir: string) => string;
     };
@@ -51,4 +52,7 @@ export declare const logMessages: {
     files: {
         skippingPath: (path: string) => string;
     };
+    workspaces: {
+        cannotAccessDirectory: (dir: string, e: unknown) => string;
+    };
 };

package/src/lang/copy.js

@@ -34,6 +34,7 @@ export const errorMessages = {
         unsupportedType: (type) => `Unsupported type: ${mapToUserFacingType(type)}`,
         errorWithField: (field, error) => `${field}: ${error || 'Unknown error'}`,
         invalidJson: 'Invalid JSON',
+        permissionsNotSupported: (platformVersion) => `The "permissions" field is not supported on platform version "${platformVersion}". Upgrade to "2026.09" or later to use component-level permissions.`,
         unexpectedToplevelFields: (unexpectedFields) => `Unexpected top-level properties found: ${unexpectedFields}`,
         wrongDirectoryForComponent: (directory, componentType, componentMetadata, correctDir) => `The directory '${directory}' is incorrect for type '${componentType}'. ${componentMetadata.userFriendlyName} ${componentMetadata.userFriendlyTypePlural} should only be placed in the '${correctDir}' directory`,
     },
@@ -66,4 +67,7 @@ export const logMessages = {
     files: {
         skippingPath: (path) => `Skipping ${path} as it is not in a valid directory`,
     },
+    workspaces: {
+        cannotAccessDirectory: (dir, e) => `Cannot access directory ${dir}: ${e}`,
+    },
 };

package/src/lib/constants.d.ts

@@ -30,6 +30,7 @@ export declare const WEBHOOKS_KEY = "webhooks";
 export declare const WEBHOOKS_JOURNAL_KEY = "webhooks-journal";
 export declare const WORKFLOW_ACTIONS_KEY = "workflow-action";
 export declare const ACTIONS_KEY = "action";
+export declare const BREEZE_TOOL_KEY = "breeze-tool";
 export declare const APP_FUNCTIONS_PACKAGE_KEY = "serverless-package";
 export declare const AUTO_GENERATED_COMPONENT_TYPES: string[];
 export interface ComponentMetadata {

package/src/lib/constants.js

@@ -34,6 +34,7 @@ export const WEBHOOKS_KEY = 'webhooks';
 export const WEBHOOKS_JOURNAL_KEY = 'webhooks-journal';
 export const WORKFLOW_ACTIONS_KEY = 'workflow-action';
 export const ACTIONS_KEY = 'action';
+export const BREEZE_TOOL_KEY = 'breeze-tool';
 // Auto-generated component types
 export const APP_FUNCTIONS_PACKAGE_KEY = 'serverless-package';
 export const AUTO_GENERATED_COMPONENT_TYPES = [APP_FUNCTIONS_PACKAGE_KEY];
@@ -54,6 +55,9 @@ const PAGE_COMPONENT = {
     userFriendlyName: 'Page',
     singularComponent: true,
 };
+// Breeze components share a `breeze/` group directory so future breeze features
+// (e.g. breeze/skills, breeze/subagents) can sit alongside breeze/tools.
+const BREEZE_COMPONENT_DIR = 'breeze';
 export const Components = {
     [APP_KEY]: {
         dir: APP_KEY,
@@ -182,6 +186,12 @@ export const Components = {
         singularComponent: true,
         ...SUB_COMPONENT_FIELDS,
     },
+    [BREEZE_TOOL_KEY]: {
+        dir: `${BREEZE_COMPONENT_DIR}/tools`,
+        parentComponent: APP_KEY,
+        userFriendlyName: 'Breeze Tool',
+        ...SUB_COMPONENT_FIELDS,
+    },
 };
 export const USER_FACING_TO_INTERNAL_TYPE = {
     [APP_KEY]: 'APPLICATION',
@@ -231,4 +241,5 @@ export const ALLOWED_TOP_LEVEL_FIELDS = new Set([
     'type',
     'config',
     'dependencies',
+    'permissions',
 ]);

package/src/lib/platformVersion.d.ts

@@ -1,3 +1,4 @@
 export declare const LATEST_SUPPORTED_PLATFORM_VERSION: string;
 export declare function isSupportedPlatformVersion(platformVersion?: string | null): boolean;
 export declare function isLegacyProject(platformVersion?: string | null): boolean;
+export declare function supportsComponentPermissions(platformVersion: string): boolean;

package/src/lib/platformVersion.js

@@ -6,11 +6,25 @@ export function isSupportedPlatformVersion(platformVersion) {
     if (!platformVersion || typeof platformVersion !== 'string') {
         return false;
     }
+    if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
+        return true;
     const supportedPlatformVersions = Object.values(PLATFORM_VERSIONS);
     return supportedPlatformVersions.includes(platformVersion);
 }
 export function isLegacyProject(platformVersion) {
     if (!platformVersion)
         return false;
+    if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
+        return false;
     return [PLATFORM_VERSIONS.v2023_2, PLATFORM_VERSIONS.v2025_1].includes(platformVersion);
 }
+const PRE_PERMISSIONS_VERSIONS = new Set([
+    PLATFORM_VERSIONS.v2023_2,
+    PLATFORM_VERSIONS.v2025_1,
+    PLATFORM_VERSIONS.v2025_2,
+    PLATFORM_VERSIONS.v2026_03_BETA,
+    PLATFORM_VERSIONS.v2026_03,
+]);
+export function supportsComponentPermissions(platformVersion) {
+    return !PRE_PERMISSIONS_VERSIONS.has(platformVersion);
+}

package/src/lib/transform.js

@@ -7,11 +7,13 @@ import { errorMessages } from '../lang/copy.js';
 import { getJavaNumberType } from './utils.js';
 import { convertPathToPosixPath } from './files.js';
 function calculateComponentDeps(fileValidationResult, parentComponents, appObjects, appFunctionsPackageUid) {
-    let dependencies = {};
-    // If there are dependencies in the config file, pass them through
-    if (!fileValidationResult.content?.dependencies) {
-        dependencies = { ...fileValidationResult.content?.dependencies };
-    }
+    // Pass through any developer-authored dependencies declared in the hsmeta
+    // file. Framework-injected structural dependencies (app, allAppObjects,
+    // serverlessPackage) are layered on top below and take precedence over any
+    // authored value for those reserved keys.
+    const dependencies = {
+        ...fileValidationResult.content?.dependencies,
+    };
     const { type } = fileValidationResult.content;
     // If the component is a child of the App component, add the app and appObjects as dependencies
     if (Components[type]?.parentComponent === APP_KEY) {
@@ -95,7 +97,7 @@ export function transform(fileParseResults, translationContext, hsProfileContent
                 fileParseResult: currentFile,
             };
         }
-        const { config, uid, type } = currentFile.content;
+        const { config, uid, type, permissions } = currentFile.content;
         const { dependencies, errors } = calculateComponentDeps(currentFile, parentComponents, allAppObjects, serverlessPackageUid);
         if (errors) {
             currentFile.errors?.push(...errors);
@@ -108,6 +110,7 @@ export function transform(fileParseResults, translationContext, hsProfileContent
                 componentDeps: dependencies,
                 metaFilePath: convertPathToPosixPath(currentFile.file),
                 files: {},
+                ...(permissions ? { permissions } : {}),
             },
             fileParseResult: currentFile,
         };

package/src/lib/types.d.ts

@@ -1,10 +1,16 @@
 import type { ErrorObject } from 'ajv';
 export type Dependencies = Record<string, string | string[]>;
+export interface ComponentPermissions {
+    requiredScopes?: string[];
+    optionalScopes?: string[];
+    conditionallyRequiredScopes?: string[];
+}
 export interface ComponentMeta {
     uid: string;
     type: string;
     config: unknown;
     dependencies?: Dependencies;
+    permissions?: ComponentPermissions;
 }
 export interface FileActionResult {
     file: string;
@@ -24,6 +30,7 @@ export interface IntermediateRepresentationNode {
     uid: string;
     config: unknown;
     files: unknown;
+    permissions?: ComponentPermissions;
 }
 export type BEProfileVariableType = 'PROFILE_INT' | 'PROFILE_LONG' | 'PROFILE_STRING' | 'PROFILE_BOOLEAN';
 export interface BEProfileVariables {

package/src/lib/validation.js

@@ -5,6 +5,7 @@ import { errorMessages } from '../lang/copy.js';
 import { AUTO_GENERATED_COMPONENT_TYPES, Components } from './constants.js';
 import path from 'path';
 import { findTransformationByUid, mapToUserFacingType } from './transform.js';
+import { supportsComponentPermissions } from './platformVersion.js';
 import { validateUid } from './uid.js';
 // ajv-formats does not play nicely with ESM and TS
 import addFormatsModule from 'ajv-formats';
@@ -47,6 +48,10 @@ function validateIntermediateRepresentationNode(schema, transformation, irNode,
         // If there is no config block, there is nothing to validation
         shouldSkipValidation = true;
     }
+    if (irNode.permissions &&
+        !supportsComponentPermissions(translationContext.platformVersion)) {
+        transformation.fileParseResult.errors.push(errorMessages.validation.permissionsNotSupported(translationContext.platformVersion));
+    }
     if (!schema[irNode.componentType]) {
         if (!irNode.componentType) {
             transformation.fileParseResult.errors.push(errorMessages.validation.missingType);

package/src/lib/workspaces.js

@@ -8,6 +8,7 @@ import packlist from 'npm-packlist';
 import { logger } from '@hubspot/local-dev-lib/logger';
 import { walk } from '@hubspot/local-dev-lib/fs';
 import { createMinimalTree } from './minimalArboristTree.js';
+import { logMessages } from '../lang/copy.js';
 /**
  * Error thrown when a workspace directory cannot be resolved
  */
@@ -60,10 +61,9 @@ export class OrphanWorkspaceProtocolError extends Error {
         this.name = 'OrphanWorkspaceProtocolError';
     }
 }
-const TARBALL_EXTENSIONS = ['.tgz', '.tar.gz', '.tar'];
 function hasTarballExtension(p) {
-    const lower = p.toLowerCase();
-    return TARBALL_EXTENSIONS.some(ext => lower.endsWith(ext));
+    const { ext, name } = path.parse(p.toLowerCase());
+    return (ext === '.tgz' || ext === '.tar' || (ext === '.gz' && name.endsWith('.tar')));
 }
 /**
  * Expands tilde (~) in paths to the user's home directory
@@ -181,7 +181,7 @@ export async function resolveWorkspaceDirectories(baseDir, workspaceGlobs) {
             }
         }
         catch (e) {
-            logger.warn(`Cannot access directory ${dir}: ${e}`);
+            logger.warn(logMessages.workspaces.cannotAccessDirectory(dir, e));
         }
     }
     return Array.from(resolved);