@hubspot/ui-extensions-dev-server 1.1.0 → 1.1.1

package/dist/lib/bin/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { exec } from 'node:child_process';
+import { Command } from 'commander';
+import ora from 'ora';
+import chalk from 'chalk';
+import { remoteBuild, buildSingleExtension } from "../build.js";
+const program = new Command()
+    .name('ui-extension-tools')
+    .alias('uie')
+    .description('Tools for managing and building HubSpot UI Extensions.');
+const buildSteps = {
+    lockfile: {
+        start: 'Processing lockfile...',
+        fn: generateLockfile,
+        success: 'Lockfile ready',
+        error: 'Error generating lockfile',
+    },
+    install: {
+        start: 'Installing dependencies...',
+        fn: installDeps,
+        success: 'Dependencies installed',
+        error: 'Error installing dependencies',
+    },
+    build: {
+        start: 'Building remote extension...',
+        fn: build,
+        success: 'Extension build complete',
+        error: 'Error building extension',
+    },
+    devBuild: {
+        start: 'Building single extension in development mode...',
+        fn: devBuild,
+        success: 'Extension build complete',
+        error: 'Error building extension',
+    },
+};
+program
+    .option('-v, --profile-variables <path>', 'path to a json file with profile variables')
+    .command('build <module>', { isDefault: true })
+    .description('Build extension source code.')
+    .action(async (module) => {
+    const options = getOptions(module);
+    await runCommand('lockfile', options);
+    await runCommand('install', options);
+    await runCommand('build', options);
+});
+program
+    .command('build-dev <module>')
+    .description('Build extension source code in development mode (no minification).')
+    .action(async (module) => {
+    const options = getOptions(module);
+    await runCommand('devBuild', options);
+});
+program.parse(process.argv);
+async function runCommand(command, options) {
+    const { start, fn, success, error } = buildSteps[command];
+    const spinner = ora();
+    try {
+        spinner.start(start);
+        await fn(options);
+        spinner.succeed(chalk.green(success));
+    }
+    catch (err) {
+        spinner.fail(chalk.red(error));
+        process.exit(1);
+    }
+    finally {
+        spinner.stop();
+    }
+}
+// Mirrors: https://git.hubteam.com/HubSpot/Artifactor/blob/f5cbea91d7a7dfb6278e878ae583e69022384fb5/ArtifactorFunctions/functions/node_18x/uie-remote-build/index.js#L59-L63
+function build({ extensionRoot, extensionDist, entrypoint, profileVariables, }) {
+    return remoteBuild({
+        root: extensionRoot,
+        entryPoint: entrypoint,
+        outputDir: extensionDist,
+        appConfig: {
+            variables: profileVariables,
+        },
+    });
+}
+async function devBuild({ extensionRoot, extensionDist, entrypoint, profileVariables, }) {
+    return buildSingleExtension({
+        file: entrypoint,
+        outputDir: extensionDist,
+        root: extensionRoot,
+        minify: false,
+        appConfig: {
+            variables: profileVariables,
+        },
+        codeCheckingPluginEnabled: true,
+    });
+}
+// Mirrors: https://git.hubteam.com/HubSpot/Artifactor/blob/f5cbea91d7a7dfb6278e878ae583e69022384fb5/ArtifactorFunctions/functions/node_18x/uie-remote-build/index.js#L53-L57
+async function installDeps(options) {
+    await execAsync('npm ci --ignore-scripts --no-audit --no-optional --no-fund', options);
+}
+// Mirrors: https://git.hubteam.com/HubSpot/Artifactor/blob/f5cbea91d7a7dfb6278e878ae583e69022384fb5/ArtifactorFunctions/functions/node_18x/uie-remote-build/index.js#L131-L136
+async function generateLockfile(options) {
+    const { extensionRoot, spinner } = options;
+    if (fs.existsSync(path.join(extensionRoot, 'package-lock.json'))) {
+        spinner.info('Existing lockfile found, skipping generation');
+    }
+    else {
+        spinner.info('No lockfile found, generating...');
+        await execAsync('npm install --package-lock-only', options);
+    }
+}
+function getOptions(modulePath) {
+    const entrypoint = path.isAbsolute(modulePath)
+        ? modulePath
+        : path.resolve(process.cwd(), modulePath);
+    const extensionRoot = path.dirname(entrypoint);
+    const extensionDist = path.join(extensionRoot, 'dist');
+    const spinner = ora();
+    // The Artifactor changes related to this are not yet available.
+    // When it is, this will mirror the process where if applicable, a profile-variables.json file is available in the build bundle.
+    const programOptions = program.opts();
+    let profileVariables = {};
+    if (programOptions.profileVariables) {
+        const profileVariablePath = programOptions.profileVariables;
+        const profileVariableFullPath = path.isAbsolute(profileVariablePath)
+            ? profileVariablePath
+            : path.resolve(process.cwd(), profileVariablePath);
+        if (fs.existsSync(profileVariableFullPath) &&
+            path.extname(profileVariableFullPath) === '.json') {
+            profileVariables = JSON.parse(fs.readFileSync(profileVariableFullPath, 'utf-8'));
+        }
+    }
+    return {
+        extensionRoot,
+        extensionDist,
+        entrypoint,
+        spinner,
+        profileVariables,
+    };
+}
+function execAsync(command, options) {
+    return promisify(exec)(command, { cwd: options.extensionRoot });
+}

package/dist/lib/build.d.ts

@@ -0,0 +1,24 @@
+import { InlineConfig } from 'vite';
+import { ManifestConfig } from './types.ts';
+interface BuildSingleExtensionArgs {
+    file: string;
+    outputDir?: string;
+    emptyOutDir?: boolean;
+    minify?: boolean;
+    root?: string;
+    logLevel?: InlineConfig['logLevel'];
+    appConfig?: ManifestConfig;
+    codeCheckingPluginEnabled?: boolean;
+}
+interface RemoteBuildArgs {
+    root: string;
+    entryPoint: string;
+    outputDir?: string;
+    logLevel?: BuildSingleExtensionArgs['logLevel'];
+    appConfig?: ManifestConfig;
+}
+export declare const extensionErrorBaseMessage: string;
+export declare function buildSingleExtension({ file, outputDir, emptyOutDir, minify, root, // This is the vite default, so using that as our default
+logLevel, appConfig, codeCheckingPluginEnabled, }: BuildSingleExtensionArgs): Promise<void>;
+export declare function remoteBuild(args: RemoteBuildArgs): Promise<void>;
+export {};

package/dist/lib/build.js

@@ -0,0 +1,73 @@
+import { build } from 'vite';
+import { ROLLUP_OPTIONS, OUTPUT_DIR } from "./constants.js";
+import manifestPlugin from "./plugins/manifestPlugin.js";
+import path from 'path';
+import { getUrlSafeFileName } from "./utils.js";
+import codeBlockingPlugin from "./plugins/codeBlockingPlugin.js";
+import friendlyLoggingPlugin from "./plugins/friendlyLoggingPlugin.js";
+import codeCheckingPlugin from "./plugins/codeCheckingPlugin.js";
+const allowedExtensions = ['.js', '.ts', '.tsx', '.jsx'];
+export const extensionErrorBaseMessage = `Supported file extensions are [${allowedExtensions.join(', ')}], received:`;
+export async function buildSingleExtension({ file, outputDir = OUTPUT_DIR, emptyOutDir = true, minify = false, root = process.cwd(), // This is the vite default, so using that as our default
+logLevel = 'info', appConfig, codeCheckingPluginEnabled = false, }) {
+    const output = getUrlSafeFileName(file);
+    await build({
+        logLevel,
+        root,
+        define: {
+            'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'production'),
+        },
+        build: {
+            lib: {
+                entry: file,
+                name: output,
+                formats: ['iife'],
+                fileName: () => output,
+            },
+            rollupOptions: {
+                ...ROLLUP_OPTIONS,
+                plugins: [
+                    manifestPlugin({
+                        output,
+                        extensionPath: root,
+                        logger: console,
+                        manifestConfig: appConfig,
+                    }),
+                    friendlyLoggingPlugin({ logger: console }),
+                    codeBlockingPlugin({ logger: console, extensionPath: root }),
+                    codeCheckingPluginEnabled &&
+                        codeCheckingPlugin({
+                            logger: console,
+                        }),
+                ],
+            },
+            outDir: outputDir,
+            emptyOutDir,
+            minify,
+        },
+    });
+}
+export async function remoteBuild(args) {
+    const { root, entryPoint, outputDir = OUTPUT_DIR, logLevel, appConfig, } = args;
+    if (!root) {
+        console.error('remoteBuild Error: root is required');
+        return;
+    }
+    if (!entryPoint) {
+        console.error('remoteBuild Error: entryPoint is required');
+        return;
+    }
+    const fileInfo = path.parse(entryPoint);
+    if (!allowedExtensions.includes(fileInfo.ext)) {
+        throw new Error(`${extensionErrorBaseMessage} ${fileInfo.ext}`);
+    }
+    await buildSingleExtension({
+        file: entryPoint,
+        outputDir,
+        minify: true,
+        root,
+        logLevel,
+        appConfig,
+        codeCheckingPluginEnabled: false,
+    });
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,7 @@
+import { AppConfig, ExtensionConfigMap, LocalAppConfig, Logger } from './types.ts';
+export declare function loadConfigByPath<T = unknown>(configPath: string): T;
+export declare function validateCardConfig(config?: unknown): Error | true;
+export declare function loadExtensionConfig(appConfig: AppConfig, appPath: string): ExtensionConfigMap;
+export declare function validateProxyConfigKey(urlKey: string, logger: Logger, localConfigPath: string): void;
+export declare function validateProxyConfigValue(value: string, key: string, logger: Logger, localConfigPath: string): void;
+export declare function loadLocalConfig(appPath: string, logger: Logger): LocalAppConfig | undefined;

package/dist/lib/config.js

@@ -0,0 +1,124 @@
+import fs from 'fs';
+import path from 'path';
+import { buildSourceId, getUrlSafeFileName } from "./utils.js";
+export function loadConfigByPath(configPath) {
+    const source = fs.readFileSync(configPath).toString();
+    return JSON.parse(source);
+}
+export function validateCardConfig(config) {
+    if (!config || typeof config !== 'object') {
+        return new Error('Card config must be an object');
+    }
+    if (!('type' in config) || config.type !== 'crm-card') {
+        return new Error('`type` must be "crm-card"');
+    }
+    if (!('data' in config) ||
+        typeof config.data !== 'object' ||
+        config.data === null) {
+        return new Error('`data` must be an object');
+    }
+    const { data } = config;
+    if (!('title' in data) || typeof data.title !== 'string') {
+        return new Error('`data` must have a `title` string');
+    }
+    if (!('location' in data) || typeof data.location !== 'string') {
+        return new Error('`data` must have a `location` string');
+    }
+    if (!('module' in data) ||
+        typeof data.module !== 'object' ||
+        data.module === null) {
+        return new Error('`data` must have a `module` object');
+    }
+    if (!('file' in data.module) || typeof data.module.file !== 'string') {
+        return new Error('`data.module` must have a `file` string');
+    }
+    if (!('objectTypes' in data) || !Array.isArray(data.objectTypes)) {
+        return new Error('`data.module` must have an `objectTypes` array');
+    }
+    if (data.objectTypes.length === 0 ||
+        data.objectTypes.some(({ name }) => typeof name !== 'string')) {
+        return new Error('all `data.module.objectTypes` objects must have `name` strings');
+    }
+    return true;
+}
+export function loadExtensionConfig(appConfig, appPath) {
+    const crmCardsSubConfigFiles = appConfig?.extensions?.crm?.cards;
+    if (!crmCardsSubConfigFiles) {
+        throw new Error("Unable to find extensions files, make sure the 'extensions.crm.cards' array is defined in the application configuration file");
+    }
+    const outputConfig = {};
+    crmCardsSubConfigFiles.forEach((card) => {
+        const cardConfigPath = path.join(appPath, card.file);
+        try {
+            const cardConfig = loadConfigByPath(cardConfigPath);
+            const validation = validateCardConfig(cardConfig);
+            if (validation !== true) {
+                console.error(`[DevServer] Extension config ${cardConfigPath} is invalid: ${validation.message}`);
+            }
+            if (cardConfig && cardConfig.data) {
+                const cardConfigDir = path.parse(cardConfigPath).dir;
+                const entryPointPath = path.join(cardConfigDir, cardConfig.data?.module?.file);
+                cardConfig.data.module.file = entryPointPath;
+                const sourceId = buildSourceId(appConfig, cardConfig);
+                outputConfig[sourceId || `${entryPointPath}-${cardConfig.data.location}`] = {
+                    ...cardConfig,
+                    output: getUrlSafeFileName(entryPointPath),
+                    path: appPath,
+                    extensionPath: path.parse(entryPointPath).dir,
+                    extensionConfigPath: cardConfigPath,
+                    data: {
+                        ...cardConfig.data,
+                        appName: appConfig.name,
+                        sourceId,
+                    },
+                    appConfig,
+                };
+            }
+        }
+        catch (e) {
+            throw new Error(`Unable to load ${cardConfigPath}`);
+        }
+    });
+    return outputConfig;
+}
+export function validateProxyConfigKey(urlKey, logger, localConfigPath) {
+    try {
+        const url = new URL(urlKey);
+        if (url.pathname !== '/') {
+            logger.warn(`The key "${urlKey}" in "${localConfigPath}" is invalid, paths are not supported for keys`);
+        }
+    }
+    catch (e) {
+        logger.warn(`The key "${urlKey}" in "${localConfigPath}" is an invalid url`);
+    }
+}
+export function validateProxyConfigValue(value, key, logger, localConfigPath) {
+    try {
+        // eslint-disable-next-line no-new
+        new URL(value);
+    }
+    catch (e) {
+        logger.warn(`The value "${value}" for key "${key}" in "${localConfigPath}" is an invalid url`);
+    }
+}
+export function loadLocalConfig(appPath, logger) {
+    const localConfigFilename = 'local.json';
+    const localConfigPath = path.join(appPath, localConfigFilename);
+    if (!fs.existsSync(localConfigPath)) {
+        return undefined;
+    }
+    try {
+        const localConfig = JSON.parse(fs.readFileSync(localConfigPath).toString());
+        const { proxy = {} } = localConfig;
+        Object.entries(proxy).forEach((entry) => {
+            const [key, value] = entry;
+            validateProxyConfigKey(key, logger, localConfigFilename);
+            validateProxyConfigValue(value, key, logger, localConfigFilename);
+        });
+        return localConfig;
+    }
+    catch (e) {
+        logger.error(`Error loading and parsing ${localConfigPath}, ${e}`);
+        return undefined;
+    }
+}

package/dist/lib/constants.d.ts

@@ -0,0 +1,32 @@
+export declare const OUTPUT_DIR = "dist";
+export declare const MANIFEST_FILE = "manifest.json";
+export declare const EXPRESS_SERVER_ID = "ui-extensions-dev-server";
+export declare const EXPRESS_DEFAULT_PORT = 5173;
+export declare const ROLLUP_OPTIONS: {
+    external: string[];
+    output: {
+        globals: {
+            react: string;
+            '@remote-ui/react': string;
+        };
+        extend: boolean;
+    };
+};
+export declare const EXTENSIONS_MESSAGE_VERSION = 2;
+export declare const WEBSOCKET_MESSAGE_VERSION = 1;
+export declare const PROXY_CAPABILITY = "app-backend-proxy-server";
+export declare const SERVER_CAPABILITIES: string[];
+export declare const PLATFORM_VERSION: {
+    readonly V20231: "2023.1";
+    readonly V20232: "2023.2";
+    readonly V20251: "2025.1";
+    readonly V20252: "2025.2";
+    readonly UNSTABLE: "unstable";
+};
+export declare const PUBLIC_APP = "public-app";
+export declare const PRIVATE_APP = "private-app";
+export declare const CARD_EXTENSION = "CARD";
+export declare const SETTINGS_EXTENSION = "SETTINGS";
+export declare const PAGE_EXTENSION = "PAGE";
+export declare const SUPPORTED_APP_TYPES: string[];
+export declare const SUPPORTED_EXTENSION_TYPES: string[];

package/dist/lib/constants.js

@@ -0,0 +1,43 @@
+export const OUTPUT_DIR = 'dist';
+export const MANIFEST_FILE = 'manifest.json';
+export const EXPRESS_SERVER_ID = 'ui-extensions-dev-server';
+export const EXPRESS_DEFAULT_PORT = 5173;
+export const ROLLUP_OPTIONS = {
+    // Deps to exclude from the bundle
+    external: ['react', 'react-dom', '@remote-ui/react'],
+    output: {
+        // Maps libs to the variables to be injected via the window
+        globals: {
+            react: 'React',
+            '@remote-ui/react': 'RemoteUI',
+        },
+        extend: true,
+    },
+};
+export const EXTENSIONS_MESSAGE_VERSION = 2;
+export const WEBSOCKET_MESSAGE_VERSION = 1;
+export const PROXY_CAPABILITY = 'app-backend-proxy-server';
+export const SERVER_CAPABILITIES = [
+    // Supports running app functions locally
+    'app-functions-local-dev',
+    'source-id',
+    'account-id',
+];
+export const PLATFORM_VERSION = {
+    V20231: '2023.1',
+    V20232: '2023.2',
+    V20251: '2025.1',
+    V20252: '2025.2',
+    UNSTABLE: 'unstable',
+};
+export const PUBLIC_APP = 'public-app';
+export const PRIVATE_APP = 'private-app';
+export const CARD_EXTENSION = 'CARD';
+export const SETTINGS_EXTENSION = 'SETTINGS';
+export const PAGE_EXTENSION = 'PAGE';
+export const SUPPORTED_APP_TYPES = [PUBLIC_APP, PRIVATE_APP];
+export const SUPPORTED_EXTENSION_TYPES = [
+    CARD_EXTENSION,
+    SETTINGS_EXTENSION,
+    PAGE_EXTENSION,
+];

package/dist/lib/dev.d.ts

@@ -0,0 +1,2 @@
+import { DevServerState } from './DevServerState.ts';
+export declare function startDevMode(devServerState: DevServerState): Promise<() => Promise<void>>;

package/dist/lib/dev.js

@@ -0,0 +1,58 @@
+import { createServer } from 'vite';
+import path from 'path';
+import startDevServer from "./server.js";
+import devBuildPlugin from "./plugins/devBuildPlugin.js";
+import { ALLOWED_ORIGIN_PATTERNS } from "./ExtensionsWebSocket.js";
+import detect from 'detect-port';
+async function _createViteDevServer(devServerState) {
+    return await createServer({
+        root: devServerState.appPath,
+        logLevel: 'silent',
+        appType: 'custom',
+        mode: 'development',
+        server: {
+            middlewareMode: true,
+            hmr: {
+                server: null, // We use our own WebSocket server (ExtensionsWebSocket) instead of Vite's
+            },
+            cors: {
+                origin: ALLOWED_ORIGIN_PATTERNS,
+                credentials: true,
+            },
+            watch: {
+                ignored: [
+                    path.join(devServerState.outputDir, '/**/*'),
+                    '**/src/app/app.functions/**/*',
+                    '**/app.json',
+                    '**/package.json',
+                    '**/package-lock.json',
+                ],
+            },
+        },
+        plugins: [
+            devBuildPlugin({
+                devServerState,
+            }),
+        ],
+        clearScreen: false,
+    });
+}
+async function throwIfPortTaken(port) {
+    // detect takes a port and returns the next available port
+    // so a mismatch means the requested port was not available
+    if ((await detect(port)) !== port) {
+        throw new Error(`Unable to start because port ${port} is already in use`);
+    }
+}
+export async function startDevMode(devServerState) {
+    if (!devServerState || !devServerState.extensionsMetadata) {
+        throw new Error('Unable to determine which extension to run');
+    }
+    await throwIfPortTaken(devServerState.expressPort);
+    const viteDevServer = await _createViteDevServer(devServerState);
+    const { shutdown } = await startDevServer({
+        devServerState,
+        viteDevServer,
+    });
+    return shutdown;
+}

package/dist/lib/extensionsService.d.ts

@@ -0,0 +1,10 @@
+import { DevServerState } from './DevServerState.ts';
+import { Request, Response, Application } from 'express';
+declare class ExtensionsService {
+    endpoint: string;
+    constructor();
+    add(server: Application, devServerState: DevServerState, capabilities: string[]): string[];
+    generateExtensionsHandler(devServerState: DevServerState, capabilities?: string[]): (_req: Request, res: Response) => void;
+}
+declare const _default: ExtensionsService;
+export default _default;

package/dist/lib/extensionsService.js

@@ -0,0 +1,45 @@
+import path from 'path';
+import { EXTENSIONS_MESSAGE_VERSION } from "./constants.js";
+import { loadManifest } from "./utils.js";
+class ExtensionsService {
+    endpoint;
+    constructor() {
+        this.endpoint = '/extensions';
+    }
+    add(server, devServerState, capabilities) {
+        server.get(this.endpoint, this.generateExtensionsHandler(devServerState, capabilities));
+        return [this.endpoint];
+    }
+    generateExtensionsHandler(devServerState, capabilities = []) {
+        return function extensionsHandler(_req, res) {
+            try {
+                const extensions = devServerState.extensionsMetadata.map((metadata) => {
+                    const { baseMessage } = metadata;
+                    const output = path.parse(baseMessage.callback).name;
+                    return {
+                        ...baseMessage,
+                        manifest: loadManifest(devServerState.outputDir, output),
+                    };
+                });
+                const response = {
+                    websocket: `ws://localhost:${devServerState.expressPort}`,
+                    version: EXTENSIONS_MESSAGE_VERSION,
+                    capabilities,
+                    portalId: devServerState.portalId,
+                    extensions,
+                    ...(devServerState.functionsConfig.platformVersion && {
+                        platformVersion: devServerState.functionsConfig.platformVersion,
+                    }),
+                };
+                res.status(200).json(response);
+            }
+            catch (e) {
+                devServerState.logger.error(`Error in /extensions endpoint: ${e}`);
+                res.status(500).json({
+                    message: 'Unable to determine which extensions are running',
+                });
+            }
+        };
+    }
+}
+export default new ExtensionsService();

package/dist/lib/parsing-utils.d.ts

@@ -0,0 +1,31 @@
+import { Node } from 'estree';
+import { NodeValue, SourceCodeMetadata } from './types.ts';
+/**
+ * Extracts the value from a given AST node based on its type.
+ * This function handles various node types such as Literal, Identifier (aka variables), ArrayExpression,
+ * ObjectExpression, SpreadElement, TemplateLiteral, UnaryExpression, and MemberExpression (accessing props on objects).
+ * It also supports nested structures and handles special cases like undefined, NaN, and Infinity.
+ *
+ * It does not handle function calls, complex expressions, or anything that requires evaluation of code logic.
+ * This is not a full JavaScript interpreter, but rather a utility to extract static values from the AST.
+ *
+ * Use this function carefully, as it assumes that the AST is well-formed and that the node types are as expected.
+ * Many types are not yet supported. Anything this function is used for should have a backup runtime evaluation,
+ * or be set up to fail gracefully if parsing fails.
+ *
+ * @param node - The AST node from which to extract the value.
+ * @param state - The current state of the source code metadata, including variable declarations.
+ * @returns An object containing the status of the operation, the extracted node value,
+ *          or an error message if the extraction fails.
+ *          The status can be 'SUCCESS' or 'FAIL'.
+ *          If the status is 'SUCCESS', nodeValue will contain the extracted value.
+ *          If the status is 'FAIL', error will contain the error message.
+ */
+export declare function getValueFromNode(node: Node, state: SourceCodeMetadata): {
+    status: 'SUCCESS' | 'FAIL';
+    nodeValue?: NodeValue;
+    error?: string;
+};
+export declare function isVariableImported(node: Node, variableName: string): boolean;
+export declare function isIdentifierDefined(node: Node, parent: Node | null, name: string): boolean;
+export declare function isFunctionInvoked(node: Node, functionName: string): boolean;