@hubspot/local-dev-lib 0.7.8-experimental.0 → 0.7.9-experimental.1

package/api/projects.d.ts

@@ -1,5 +1,5 @@
 import { HubSpotPromise, QueryParams } from '../types/Http.js';
-import { Project, FetchProjectResponse, UploadProjectResponse, ProjectSettings, FetchPlatformVersionResponse, WarnLogsResponse, UploadIRResponse, Release, FetchListReleasesResponse } from '../types/Project.js';
+import { Project, FetchProjectResponse, UploadProjectResponse, ProjectSettings, FetchPlatformVersionResponse, WarnLogsResponse, UploadIRResponse } from '../types/Project.js';
 import { Build, FetchProjectBuildsResponse } from '../types/Build.js';
 import { ComponentStructureResponse, ProjectComponentsMetadata } from '../types/ComponentStructure.js';
 import { Deploy, ProjectDeployResponse, ProjectDeployResponseV1, ProjectDeletionResponse } from '../types/Deploy.js';
@@ -39,9 +39,6 @@ export declare function deleteFileFromBuild(accountId: number, projectName: stri
 export declare function cancelStagedBuild(accountId: number, projectName: string): HubSpotPromise<void>;
 export declare function fetchBuildWarnLogs(accountId: number, projectName: string, buildId: number): HubSpotPromise<WarnLogsResponse>;
 export declare function fetchDeployWarnLogs(accountId: number, projectName: string, deployId: number): HubSpotPromise<WarnLogsResponse>;
-export declare function createRelease(accountId: number, projectName: string, buildId: number): HubSpotPromise<Release>;
-export declare function listReleases(accountId: number, projectName: string, params?: QueryParams): HubSpotPromise<FetchListReleasesResponse>;
-export declare function getReleaseInfo(accountId: number, projectName: string, releaseTag: string): HubSpotPromise<Release>;
 /**
  * @deprecated
  */

package/api/projects.js

@@ -215,23 +215,6 @@ export function fetchDeployWarnLogs(accountId, projectName, deployId) {
         url: `${PROJECTS_LOGS_API_PATH}/logs/projects/${encodeURIComponent(projectName)}/deploys/${deployId}/combined/warn`,
     });
 }
-export function createRelease(accountId, projectName, buildId) {
-    return http.post(accountId, {
-        url: `${PROJECTS_API_PATH}/${encodeURIComponent(projectName)}/releases`,
-        data: { buildId },
-    });
-}
-export function listReleases(accountId, projectName, params = {}) {
-    return http.get(accountId, {
-        url: `${PROJECTS_API_PATH}/${encodeURIComponent(projectName)}/releases`,
-        params,
-    });
-}
-export function getReleaseInfo(accountId, projectName, releaseTag) {
-    return http.get(accountId, {
-        url: `${PROJECTS_API_PATH}/${encodeURIComponent(projectName)}/releases/${encodeURIComponent(releaseTag)}`,
-    });
-}
 /**
  * @deprecated
  */

package/api/sandboxHubs.js

@@ -16,6 +16,7 @@ export function createSandbox(accountId, name, type) {
 export function deleteSandbox(parentAccountId, sandboxAccountId) {
     return http.delete(parentAccountId, {
         url: `${SANDBOX_API_PATH}/${sandboxAccountId}`,
+        timeout: SANDBOX_TIMEOUT,
     });
 }
 export function getSandboxUsageLimits(parentAccountId) {
@@ -27,6 +28,7 @@ export function createV2Sandbox(accountId, name, type, syncObjectRecords) {
     return http.post(accountId, {
         url: `${SANDBOX_API_PATH_V2}/sandboxes`,
         data: { name, type, syncObjectRecords },
+        timeout: SANDBOX_TIMEOUT,
     });
 }
 export function getSandboxPersonalAccessKey(accountId, sandboxId) {

package/config/hsSettings.js

@@ -36,12 +36,15 @@ export function getHsSettingsFileIfExists() {
     }
 }
 export function writeHsSettingsFile(settingsFile) {
+    const existingFilePath = getHsSettingsFilePath();
     const dir = getCwd();
-    const hsFolderPath = path.join(dir, HS_FOLDER);
+    const hsFolderPath = existingFilePath
+        ? path.dirname(existingFilePath)
+        : path.join(dir, HS_FOLDER);
     const isFirstScaffold = !fs.existsSync(hsFolderPath);
     try {
         fs.mkdirSync(hsFolderPath, { recursive: true });
-        fs.writeFileSync(path.join(dir, HS_FOLDER, HS_SETTINGS_FILENAME), JSON.stringify(settingsFile, null, 2), 'utf8');
+        fs.writeFileSync(path.join(hsFolderPath, HS_SETTINGS_FILENAME), JSON.stringify(settingsFile, null, 2), 'utf8');
         if (isFirstScaffold) {
             fs.writeFileSync(path.join(hsFolderPath, HS_README_FILENAME), HS_README_CONTENTS, 'utf8');
         }

package/constants/ports.js

@@ -1,3 +1,5 @@
 export const MIN_PORT_NUMBER = 1024;
 export const MAX_PORT_NUMBER = 65535;
+// TODO: rename to PORT_MANAGER_SERVER_DEFAULT_PORT and update value to 4828
+// on the next major version of @hubspot/local-dev-lib
 export const PORT_MANAGER_SERVER_PORT = 8080;

package/constants/projects.d.ts

@@ -10,5 +10,6 @@ export declare const PLATFORM_VERSIONS: {
     v2025_2: string;
     v2026_03_beta: string;
     v2026_03: string;
+    v2026_09_beta: string;
     unstable: string;
 };

package/constants/projects.js

@@ -10,5 +10,6 @@ export const PLATFORM_VERSIONS = {
     v2025_2: '2025.2',
     v2026_03_beta: '2026.03-beta',
     v2026_03: '2026.03',
+    v2026_09_beta: '2026.09-beta',
     unstable: 'unstable',
 };

package/lib/LogBuffer.d.ts

@@ -0,0 +1,26 @@
+export type LogBufferOptions = {
+    byteLimit?: number;
+};
+export type WriteBufferedLogsOptions = {
+    dir: string;
+    filenamePrefix: string;
+    maxFiles?: number;
+};
+/**
+ * In-memory ring buffer of log entries with a byte cap. Designed to be
+ * composed into a logger so that recent log output can be flushed to a file
+ * after a failure. Each record is timestamped and tagged with the level the
+ * caller provides.
+ */
+export declare class LogBuffer {
+    private entries;
+    private bytes;
+    private byteLimit;
+    constructor(options?: LogBufferOptions);
+    private static entrySize;
+    private trimToByteLimit;
+    record(level: string, args: unknown[]): void;
+    view(): string;
+    flush(): string;
+    writeToFile(options: WriteBufferedLogsOptions): string | null;
+}

package/lib/LogBuffer.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import path from 'path';
+// 128 MiB
+const DEFAULT_BYTE_LIMIT = 128 * 1024 * 1024;
+const DEFAULT_MAX_LOG_FILES = 3;
+function sanitizeFilenamePart(name) {
+    return name.replace(/[^a-zA-Z0-9._-]+/g, '-');
+}
+function timestampForFilename() {
+    const d = new Date();
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+    const time = `${pad(d.getHours())}-${pad(d.getMinutes())}-${pad(d.getSeconds())}`;
+    return `${date}T${time}-${pad(d.getMilliseconds(), 3)}`;
+}
+function rotateLogFiles(dir, maxFiles) {
+    const entries = fs
+        .readdirSync(dir)
+        .map(name => {
+        const full = path.join(dir, name);
+        const stat = fs.statSync(full);
+        return { full, mtimeMs: stat.mtimeMs, isFile: stat.isFile() };
+    })
+        .filter(entry => entry.isFile)
+        .sort((a, b) => a.mtimeMs - b.mtimeMs);
+    while (entries.length >= maxFiles) {
+        const oldest = entries.shift();
+        if (oldest) {
+            fs.unlinkSync(oldest.full);
+        }
+    }
+}
+/**
+ * In-memory ring buffer of log entries with a byte cap. Designed to be
+ * composed into a logger so that recent log output can be flushed to a file
+ * after a failure. Each record is timestamped and tagged with the level the
+ * caller provides.
+ */
+export class LogBuffer {
+    entries = [];
+    bytes = 0;
+    byteLimit;
+    constructor(options = {}) {
+        this.byteLimit = options.byteLimit ?? DEFAULT_BYTE_LIMIT;
+    }
+    // +1 accounts for the '\n' separator that join('\n') will insert between entries.
+    static entrySize(entry) {
+        return Buffer.byteLength(entry, 'utf8') + 1;
+    }
+    // Drop oldest entries until under the cap. Always retains at least the most
+    // recent entry so a single oversized message is still captured.
+    trimToByteLimit() {
+        while (this.bytes > this.byteLimit && this.entries.length > 1) {
+            const removed = this.entries.shift();
+            this.bytes -= LogBuffer.entrySize(removed);
+        }
+    }
+    record(level, args) {
+        const message = args.map(arg => String(arg)).join(' ');
+        const entry = `[${new Date().toISOString()}] [${level}] ${message}`;
+        this.entries.push(entry);
+        this.bytes += LogBuffer.entrySize(entry);
+        this.trimToByteLimit();
+    }
+    view() {
+        return this.entries.join('\n');
+    }
+    flush() {
+        const out = this.entries.join('\n');
+        this.entries.length = 0;
+        this.bytes = 0;
+        return out;
+    }
+    // Flush the buffer to a rotating log file. Always clears the buffer (even
+    // on write failure). Returns the written file path on success, or null if
+    // the buffer was empty or the write failed.
+    writeToFile(options) {
+        const { dir, filenamePrefix, maxFiles = DEFAULT_MAX_LOG_FILES } = options;
+        const contents = this.flush();
+        if (!contents) {
+            return null;
+        }
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            rotateLogFiles(dir, maxFiles);
+            const filename = `${sanitizeFilenamePart(filenamePrefix)}-${timestampForFilename()}.log`;
+            const filePath = path.join(dir, filename);
+            fs.writeFileSync(filePath, contents, 'utf8');
+            return filePath;
+        }
+        catch (_e) {
+            return null;
+        }
+    }
+}

package/lib/cms/functions.js

@@ -19,7 +19,7 @@ export function createEndpoint(endpointMethod, filename) {
 }
 export function createConfig({ endpointPath, endpointMethod, functionFile, }) {
     return {
-        runtime: 'nodejs18.x',
+        runtime: 'nodejs20.x',
         version: '1.0',
         environment: {},
         secrets: [],

package/lib/github.js

@@ -96,7 +96,7 @@ export async function fetchGitHubRepoContentFromDownloadUrl(dest, downloadUrl) {
     const resp = await fetchRepoFileByDownloadUrl(downloadUrl);
     const contentType = resp.headers['content-type'];
     let fileContents;
-    if (contentType.startsWith('text')) {
+    if (typeof contentType === 'string' && contentType.startsWith('text')) {
         fileContents = Buffer.from(resp.data).toString('utf8');
     }
     else {

package/lib/logger.d.ts

@@ -1,4 +1,6 @@
 import { type ChalkInstance } from 'chalk';
+import { WriteBufferedLogsOptions } from './LogBuffer.js';
+export type { WriteBufferedLogsOptions };
 export declare const LOG_LEVEL: {
     NONE: number;
     DEBUG: number;
@@ -50,5 +52,7 @@ export declare const logger: {
     debug(...args: any[]): void;
     group(...args: any[]): void;
     groupEnd(): void;
+    viewLogBuffer(): string;
+    flushLogBuffer(): string;
+    writeBufferedLogsToFile(options: WriteBufferedLogsOptions): string | null;
 };
-export {};

package/lib/logger.js

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import chalk from 'chalk';
 import { isUnicodeSupported } from './isUnicodeSupported.js';
+import { LogBuffer } from './LogBuffer.js';
 export const LOG_LEVEL = {
     NONE: 0,
     DEBUG: 1,
@@ -127,41 +128,58 @@ export function getLogLevel() {
             return LOG_LEVEL.NONE;
     }
 }
+const _logBuffer = new LogBuffer();
 export const logger = {
     error(...args) {
+        _logBuffer.record('ERROR', args);
         if (shouldLog(LOG_LEVEL.ERROR)) {
             currentLogger.error(...args);
         }
     },
     warn(...args) {
+        _logBuffer.record('WARN', args);
         if (shouldLog(LOG_LEVEL.WARN)) {
             currentLogger.warn(...args);
         }
     },
     log(...args) {
+        _logBuffer.record('LOG', args);
         if (shouldLog(LOG_LEVEL.LOG)) {
             currentLogger.log(...args);
         }
     },
     success(...args) {
+        _logBuffer.record('SUCCESS', args);
         if (shouldLog(LOG_LEVEL.LOG)) {
             currentLogger.success(...args);
         }
     },
     info(...args) {
+        _logBuffer.record('INFO', args);
         if (shouldLog(LOG_LEVEL.LOG)) {
             currentLogger.info(...args);
         }
     },
     debug(...args) {
+        _logBuffer.record('DEBUG', args);
         if (shouldLog(LOG_LEVEL.DEBUG)) {
             currentLogger.debug(...args);
         }
     },
     group(...args) {
+        _logBuffer.record('GROUP', args);
         currentLogger.group(...args);
     },
     groupEnd() {
         currentLogger.groupEnd();
     },
+    viewLogBuffer() {
+        return _logBuffer.view();
+    },
+    flushLogBuffer() {
+        return _logBuffer.flush();
+    },
+    writeBufferedLogsToFile(options) {
+        return _logBuffer.writeToFile(options);
+    },
 };

package/lib/portManager.d.ts

@@ -1,8 +1,8 @@
 import { RequestPortsData, ServerPortMap } from '../types/PortManager.js';
-export declare const BASE_URL = "http://localhost:8080";
+export declare function isPortAvailable(port: number): Promise<boolean>;
 export declare function isPortManagerPortAvailable(): Promise<boolean>;
 export declare function isPortManagerServerRunning(): Promise<boolean>;
-export declare function startPortManagerServer(): Promise<void>;
+export declare function startPortManagerServer(port?: number): Promise<void>;
 export declare function stopPortManagerServer(): Promise<void>;
 export declare function requestPorts(portData: Array<RequestPortsData>): Promise<{
     [instanceId: string]: number;

package/lib/portManager.js

@@ -1,14 +1,16 @@
 import axios from 'axios';
 import { HEALTH_CHECK_PATH, PortManagerServer, SERVICE_HEALTHY, } from '../utils/PortManagerServer.js';
-import { PORT_MANAGER_SERVER_PORT } from '../constants/ports.js';
+import { detectPort } from '../utils/detectPort.js';
 import { logger } from './logger.js';
-export const BASE_URL = `http://localhost:${PORT_MANAGER_SERVER_PORT}`;
+export async function isPortAvailable(port) {
+    return (await detectPort(port)) === port;
+}
 export async function isPortManagerPortAvailable() {
     return PortManagerServer.portAvailable();
 }
 export async function isPortManagerServerRunning() {
     try {
-        const { data } = await axios.get(`${BASE_URL}${HEALTH_CHECK_PATH}`);
+        const { data } = await axios.get(`${PortManagerServer.baseUrl}${HEALTH_CHECK_PATH}`);
         return data.status === SERVICE_HEALTHY;
     }
     catch (e) {
@@ -16,36 +18,36 @@ export async function isPortManagerServerRunning() {
         return false;
     }
 }
-export async function startPortManagerServer() {
+export async function startPortManagerServer(port) {
     const isRunning = await isPortManagerServerRunning();
     if (!isRunning) {
-        await PortManagerServer.init();
+        await PortManagerServer.init(port);
     }
 }
 export async function stopPortManagerServer() {
     const isRunning = await isPortManagerServerRunning();
     if (isRunning) {
-        await axios.post(`${BASE_URL}/close`);
+        await axios.post(`${PortManagerServer.baseUrl}/close`);
     }
 }
 export async function requestPorts(portData) {
-    const { data } = await axios.post(`${BASE_URL}/servers`, {
+    const { data } = await axios.post(`${PortManagerServer.baseUrl}/servers`, {
         portData: portData,
     });
     return data.ports;
 }
 export async function getActiveServers() {
-    const { data } = await axios.get(`${BASE_URL}/servers`);
+    const { data } = await axios.get(`${PortManagerServer.baseUrl}/servers`);
     return data.servers;
 }
 export async function getServerPortByInstanceId(serverInstanceId) {
-    const { data } = await axios.get(`${BASE_URL}/servers/${serverInstanceId}`);
+    const { data } = await axios.get(`${PortManagerServer.baseUrl}/servers/${serverInstanceId}`);
     return data.port;
 }
 export async function deleteServerInstance(serverInstanceId) {
-    await axios.delete(`${BASE_URL}/servers/${serverInstanceId}`);
+    await axios.delete(`${PortManagerServer.baseUrl}/servers/${serverInstanceId}`);
 }
 export async function portManagerHasActiveServers() {
-    const { data } = await axios.get(`${BASE_URL}/servers`);
+    const { data } = await axios.get(`${PortManagerServer.baseUrl}/servers`);
     return data.count > 0;
 }

package/models/HubSpotHttpError.js

@@ -101,7 +101,13 @@ export class HubSpotHttpError extends Error {
             return;
         }
         generatedContext.accountId = cause.config?.params?.portalId;
-        generatedContext.payload = JSON.stringify(cause.config?.data);
+        // Axios serializes request bodies before the error fires, so `config.data`
+        // is often already a JSON string. Avoid re-stringifying so debug output is
+        // readable instead of escape-soup.
+        generatedContext.payload =
+            typeof cause.config?.data === 'string'
+                ? cause.config.data
+                : JSON.stringify(cause.config?.data);
         // This will just be the url path
         generatedContext.request = cause.config?.url;
         // Allow the provided context to override the generated context

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/local-dev-lib",
-    "version": "0.7.8-experimental.0",
+    "version": "0.7.9-experimental.1",
     "type": "module",
     "description": "Provides library functionality for HubSpot local development tooling, including the HubSpot CLI",
     "files": [
@@ -71,13 +71,13 @@
     },
     "dependencies": {
         "address": "2.0.2",
-        "axios": "1.12.0",
+        "axios": "1.15.2",
         "chalk": "5.6.2",
         "chokidar": "3.6.0",
         "content-disposition": "0.5.4",
         "cors": "2.8.5",
         "debounce": "1.2.1",
-        "express": "4.21.2",
+        "express": "4.22.1",
         "extract-zip": "2.0.1",
         "findup-sync": "5.0.0",
         "form-data": "^4.0.4",

package/types/Project.d.ts

@@ -1,8 +1,6 @@
 import type { Build } from './Build.js';
 import { GithubSourceData } from './Github.js';
 import { ProjectLog } from './ProjectLog.js';
-import { ValueOf } from './Utils.js';
-import { SUBBUILD_TYPES } from '../enums/build.js';
 export type Project = {
     createdAt: number;
     deletedAt: number;
@@ -50,22 +48,3 @@ export type FetchPlatformVersionResponse = {
 export type WarnLogsResponse = {
     logs: Array<ProjectLog>;
 };
-export type Release = {
-    releaseTag: string;
-    buildId: number;
-    createdAt: string;
-    components?: Array<{
-        buildType: ValueOf<typeof SUBBUILD_TYPES>;
-        buildName?: string;
-        rootPath?: string;
-        id?: string;
-    }>;
-};
-export type FetchListReleasesResponse = {
-    results: Array<Release>;
-    paging: {
-        next: {
-            after: string;
-        };
-    };
-};

package/utils/PortManagerServer.d.ts

@@ -1,14 +1,13 @@
-import { Express } from 'express';
-import { Server } from 'http';
-import { ServerPortMap } from '../types/PortManager.js';
 export declare const HEALTH_CHECK_PATH = "/port-manager-health-check";
 export declare const SERVICE_HEALTHY = "OK";
 declare class _PortManagerServer {
-    app?: Express;
-    server?: Server;
-    serverPortMap: ServerPortMap;
+    private app?;
+    private server?;
+    private serverPortMap;
+    private port;
     constructor();
-    init(): Promise<void>;
+    get baseUrl(): string;
+    init(port?: number): Promise<void>;
     private reset;
     portAvailable(): Promise<boolean>;
     private listen;

package/utils/PortManagerServer.js

@@ -11,13 +11,21 @@ class _PortManagerServer {
     app;
     server;
     serverPortMap;
+    port;
     constructor() {
         this.serverPortMap = {};
+        this.port = PORT_MANAGER_SERVER_PORT;
     }
-    async init() {
+    get baseUrl() {
+        return `http://localhost:${this.port}`;
+    }
+    async init(port) {
+        if (port) {
+            this.port = port;
+        }
         if (!(await this.portAvailable())) {
             throw new Error(i18n(`${i18nKey}.errors.portInUse`, {
-                port: PORT_MANAGER_SERVER_PORT,
+                port: this.port,
             }));
         }
         if (this.app) {
@@ -34,15 +42,16 @@ class _PortManagerServer {
         this.app = undefined;
         this.server = undefined;
         this.serverPortMap = {};
+        this.port = PORT_MANAGER_SERVER_PORT;
     }
     async portAvailable() {
-        return ((await detectPort(PORT_MANAGER_SERVER_PORT)) === PORT_MANAGER_SERVER_PORT);
+        return (await detectPort(this.port)) === this.port;
     }
     listen() {
         return new Promise((resolve, reject) => {
-            const server = this.app.listen(PORT_MANAGER_SERVER_PORT, () => {
+            const server = this.app.listen(this.port, () => {
                 logger.debug(i18n(`${i18nKey}.started`, {
-                    port: PORT_MANAGER_SERVER_PORT,
+                    port: this.port,
                 }));
                 resolve(server);
             }).on('error', (err) => {