@hubspot/cli 8.1.0 → 8.1.1-experimental.0

package/lib/ui/accountTable.js

@@ -0,0 +1,67 @@
+import { HUBSPOT_ACCOUNT_TYPES, HUBSPOT_ACCOUNT_TYPE_STRINGS, } from '@hubspot/local-dev-lib/constants/config';
+import { isSandbox, isDeveloperTestAccount } from '../accountTypes.js';
+import { getAllConfigAccounts } from '@hubspot/local-dev-lib/config';
+import { commands } from '../../lang/en.js';
+import { renderTable } from '../../ui/render.js';
+import { uiLogger } from './logger.js';
+export function sortAndMapAccounts(accounts) {
+    const mappedAccountData = {};
+    // Standard and app developer accounts
+    accounts
+        .filter(p => p.accountType &&
+        (p.accountType === HUBSPOT_ACCOUNT_TYPES.STANDARD ||
+            p.accountType === HUBSPOT_ACCOUNT_TYPES.APP_DEVELOPER))
+        .forEach(account => {
+        mappedAccountData[account.accountId] = [account];
+    });
+    // Non-standard accounts (sandbox, developer test account)
+    accounts
+        .filter(p => p.accountType && (isSandbox(p) || isDeveloperTestAccount(p)))
+        .forEach(p => {
+        if (p.parentAccountId) {
+            mappedAccountData[p.parentAccountId] = [
+                ...(mappedAccountData[p.parentAccountId] || []),
+                p,
+            ];
+        }
+        else {
+            mappedAccountData[p.accountId] = [p];
+        }
+    });
+    return mappedAccountData;
+}
+export function getAccountData(mappedAccountData) {
+    const accountData = [];
+    Object.entries(mappedAccountData).forEach(([key, set]) => {
+        const hasParentAccount = set.filter(p => p.accountId === parseInt(key, 10))[0];
+        set.forEach(account => {
+            let name = `${account.name} [${HUBSPOT_ACCOUNT_TYPE_STRINGS[account.accountType]}]`;
+            if (isSandbox(account)) {
+                if (hasParentAccount && set.length > 1) {
+                    name = `↳ ${name}`;
+                }
+            }
+            else if (isDeveloperTestAccount(account)) {
+                if (hasParentAccount && set.length > 1) {
+                    name = `↳ ${name}`;
+                }
+            }
+            accountData.push([name, String(account.accountId), account.authType]);
+        });
+    });
+    return accountData;
+}
+export function renderAccountTable(showAllLabel = false) {
+    const accountsList = getAllConfigAccounts();
+    const mappedAccountData = sortAndMapAccounts(accountsList);
+    const accountData = getAccountData(mappedAccountData);
+    const tableHeader = [
+        commands.account.subcommands.list.labels.name,
+        commands.account.subcommands.list.labels.accountId,
+        commands.account.subcommands.list.labels.authType,
+    ];
+    uiLogger.log(showAllLabel
+        ? commands.account.subcommands.list.allAccounts
+        : commands.account.subcommands.list.accounts);
+    renderTable(tableHeader, accountData, true);
+}

package/lib/ui/spinniesUtils.d.ts

@@ -28,5 +28,4 @@ export declare function breakText(text: string, prefixLength: number): string;
 export declare function getLinesLength(text: string, prefixLength: number): number[];
 export declare function writeStream(stream: NodeJS.WriteStream, output: string, rawLines: number[]): void;
 export declare function cleanStream(stream: NodeJS.WriteStream, rawLines: number[]): void;
-export declare function terminalSupportsUnicode(): boolean;
 export {};

package/lib/ui/spinniesUtils.js

@@ -9,6 +9,8 @@ The above copyright notice and this permission notice shall be included in all c
 **/
 import readline from 'readline';
 import stripAnsi from 'strip-ansi';
+import { isUnicodeSupported } from '@hubspot/local-dev-lib/isUnicodeSupported';
+import { getSymbols } from '@hubspot/local-dev-lib/logger';
 export const VALID_STATUSES = [
     'succeed',
     'fail',
@@ -64,7 +66,7 @@ export function purgeSpinnersOptions({ spinner, disableSpins, ...others }) {
     return { ...colors, ...prefixes, ...disableSpinsOption, spinner };
 }
 function turnToValidSpinner(spinner = {}) {
-    const platformSpinner = terminalSupportsUnicode()
+    const platformSpinner = isUnicodeSupported()
         ? SPINNERS.dots
         : SPINNERS.dashes;
     if (typeof spinner !== 'object') {
@@ -101,14 +103,9 @@ export function colorOptions({ color, succeedColor, failColor, spinnerColor, })
     return colors;
 }
 export function prefixOptions({ succeedPrefix, failPrefix, }) {
-    if (terminalSupportsUnicode()) {
-        succeedPrefix = succeedPrefix || '✓';
-        failPrefix = failPrefix || '✖';
-    }
-    else {
-        succeedPrefix = succeedPrefix || '√';
-        failPrefix = failPrefix || '×';
-    }
+    const symbols = getSymbols();
+    succeedPrefix = succeedPrefix || symbols.success;
+    failPrefix = failPrefix || symbols.error;
     return { succeedPrefix, failPrefix };
 }
 export function breakText(text, prefixLength) {
@@ -142,10 +139,3 @@ export function cleanStream(stream, rawLines) {
     readline.clearScreenDown(stream);
     readline.moveCursor(stream, 0, -rawLines.length);
 }
-export function terminalSupportsUnicode() {
-    // The default command prompt and powershell in Windows do not support Unicode characters.
-    // However, the VSCode integrated terminal and the Windows Terminal both do.
-    return (process.platform !== 'win32' ||
-        process.env.TERM_PROGRAM === 'vscode' ||
-        !!process.env.WT_SESSION);
-}

package/lib/usageTracking.d.ts

@@ -1,32 +1,21 @@
-type Meta = {
-    action?: string;
-    os?: string;
-    nodeVersion?: string;
-    nodeMajorVersion?: string;
-    version?: string;
-    command?: string;
-    authType?: string;
-    step?: string;
-    assetType?: string;
-    mode?: string;
-    type?: string | number;
-    file?: boolean;
-    successful?: boolean;
-};
+import { type UsageTrackingMeta, type ConfigType, type ExecutionSource } from './api/usageTracking.js';
+export type { UsageTrackingMeta, ConfigType, ExecutionSource, } from './api/usageTracking.js';
 export declare const EventClass: {
     USAGE: string;
     INTERACTION: string;
     VIEW: string;
     ACTIVATION: string;
 };
-export declare function getNodeVersionData(): {
+export declare function getExecutionEnvironmentMeta(): {
+    os: string;
     nodeVersion: string;
     nodeMajorVersion: string;
+    version: string;
+    configType?: ConfigType;
+    executionSource: ExecutionSource;
 };
-export declare function getPlatform(): string;
-export declare function trackCommandUsage(command: string, meta?: Meta, accountId?: number): Promise<void>;
+export declare function trackCommandUsage(command: string, meta?: UsageTrackingMeta, accountId?: number): Promise<void>;
 export declare function trackHelpUsage(command: string): Promise<void>;
 export declare function trackConvertFieldsUsage(command: string): Promise<void>;
 export declare function trackAuthAction(command: string, authType: string, step: string, accountId?: number): Promise<void>;
-export declare function trackCommandMetadataUsage(command: string, meta?: Meta, accountId?: number): Promise<void>;
-export {};
+export declare function trackCommandMetadataUsage(command: string, meta?: UsageTrackingMeta, accountId?: number): Promise<void>;

package/lib/usageTracking.js

@@ -1,10 +1,10 @@
-import { trackUsage } from '@hubspot/local-dev-lib/trackUsage';
-import { getConfigAccountById, getConfig } from '@hubspot/local-dev-lib/config';
+import { getConfig, getConfigAccountById, getConfigFilePath, getGlobalConfigFilePath, } from '@hubspot/local-dev-lib/config';
 import { API_KEY_AUTH_METHOD } from '@hubspot/local-dev-lib/constants/auth';
 import { uiLogger } from './ui/logger.js';
 import { pkg } from './jsonLoader.js';
 import { debugError } from './errorHandlers/index.js';
 import { isUsageTrackingDisableFlagSet } from './middleware/usageTrackingMiddleware.js';
+import { sendUsageEvent, } from './api/usageTracking.js';
 const version = pkg.version;
 const usageTrackingDiabled = 'Usage tracking is disabled via the --disable-usage-tracking flag, not sending usage events';
 export const EventClass = {
@@ -13,13 +13,13 @@ export const EventClass = {
     VIEW: 'VIEW',
     ACTIVATION: 'ACTIVATION',
 };
-export function getNodeVersionData() {
+function getNodeVersionData() {
     return {
         nodeVersion: process.version,
         nodeMajorVersion: (process.version || '').split('.')[0],
     };
 }
-export function getPlatform() {
+function getPlatform() {
     switch (process.platform) {
         case 'darwin':
             return 'macos';
@@ -29,6 +29,34 @@ export function getPlatform() {
             return process.platform;
     }
 }
+function getConfigType() {
+    try {
+        return getConfigFilePath() === getGlobalConfigFilePath()
+            ? 'global'
+            : 'local';
+    }
+    catch (_e) {
+        return undefined;
+    }
+}
+function getExecutionSource() {
+    if (process.env.HUBSPOT_MCP_AI_AGENT) {
+        return 'mcp';
+    }
+    if (process.env.CI) {
+        return 'ci';
+    }
+    return 'user';
+}
+export function getExecutionEnvironmentMeta() {
+    return {
+        os: getPlatform(),
+        ...getNodeVersionData(),
+        version,
+        configType: getConfigType(),
+        executionSource: getExecutionSource(),
+    };
+}
 export async function trackCommandUsage(command, meta = {}, accountId) {
     if (isUsageTrackingDisableFlagSet()) {
         uiLogger.debug(usageTrackingDiabled);
@@ -44,11 +72,14 @@ export async function trackCommandUsage(command, meta = {}, accountId) {
     uiLogger.debug(`Attempting to track usage of "${command}" command`);
     let authType = 'unknown';
     if (accountId) {
-        const accountConfig = getConfigAccountById(accountId);
-        authType =
-            accountConfig && accountConfig.authType
-                ? accountConfig.authType
-                : API_KEY_AUTH_METHOD.value;
+        try {
+            const accountConfig = getConfigAccountById(accountId);
+            authType =
+                accountConfig && accountConfig.authType
+                    ? accountConfig.authType
+                    : API_KEY_AUTH_METHOD.value;
+        }
+        catch (e) { }
     }
     return trackCliInteraction({
         action: 'cli-command',
@@ -127,39 +158,25 @@ async function trackCliInteraction({ action, accountId, command, authType, meta
         if (config?.allowUsageTracking === false) {
             return;
         }
+        if (isUsageTrackingDisableFlagSet()) {
+            uiLogger.debug(usageTrackingDiabled);
+            return;
+        }
         const usageTrackingEvent = {
             action,
-            os: getPlatform(),
-            ...getNodeVersionData(),
-            version,
             command,
             authType,
+            ...getExecutionEnvironmentMeta(),
             ...meta,
         };
-        if (process.env.HUBSPOT_MCP_AI_AGENT) {
-            try {
-                await trackUsage('cli-interaction', EventClass.INTERACTION, {
-                    ...usageTrackingEvent,
-                    action: 'cli-mcp-server',
-                    type: process.env.HUBSPOT_MCP_AI_AGENT,
-                }, accountId);
-                uiLogger.debug('Sent AI usage tracking command event:', {
-                    ...usageTrackingEvent,
-                    action: 'cli-mcp-server',
-                    type: process.env.HUBSPOT_MCP_AI_AGENT,
-                });
-            }
-            catch (error) {
-                debugError(error);
-            }
-        }
-        if (isUsageTrackingDisableFlagSet()) {
-            uiLogger.debug(usageTrackingDiabled);
-            return;
-        }
         try {
             uiLogger.debug('Sent usage tracking command event:', usageTrackingEvent);
-            return trackUsage('cli-interaction', EventClass.INTERACTION, usageTrackingEvent, accountId);
+            await sendUsageEvent({
+                eventName: 'cli-interaction',
+                eventClass: EventClass.INTERACTION,
+                meta: usageTrackingEvent,
+                accountId,
+            });
         }
         catch (error) {
             debugError(error);

package/lib/yargs/makeYargsBuilder.d.ts

@@ -0,0 +1,13 @@
+import { Argv } from 'yargs';
+export declare function makeYargsBuilder<T>(callback: (yargs: Argv) => Argv<T>, command: string | string[], describe?: string, options?: {
+    useGlobalOptions?: boolean;
+    useAccountOptions?: boolean;
+    useConfigOptions?: boolean;
+    useEnvironmentOptions?: boolean;
+    useTestingOptions?: boolean;
+    useCmsPublishModeOptions?: boolean | {
+        read?: boolean;
+        write?: boolean;
+    };
+    useJSONOutputOptions?: boolean;
+}): (yargs: Argv) => Promise<Argv<T>>;

package/lib/yargs/makeYargsBuilder.js

@@ -0,0 +1,33 @@
+import { addCustomHelpOutput, addTestingOptions, addAccountOptions, addConfigOptions, addGlobalOptions, addUseEnvironmentOptions, addCmsPublishModeOptions, addJSONOutputOptions, } from '../commonOpts.js';
+export function makeYargsBuilder(callback, command, describe, options = {}) {
+    return async function (yargs) {
+        if (options.useGlobalOptions) {
+            addGlobalOptions(yargs);
+        }
+        if (options.useAccountOptions) {
+            addAccountOptions(yargs);
+        }
+        if (options.useConfigOptions) {
+            addConfigOptions(yargs);
+        }
+        if (options.useEnvironmentOptions) {
+            addUseEnvironmentOptions(yargs);
+        }
+        if (options.useTestingOptions) {
+            addTestingOptions(yargs);
+        }
+        if (options.useJSONOutputOptions) {
+            addJSONOutputOptions(yargs);
+        }
+        if (options.useCmsPublishModeOptions) {
+            const opts = typeof options.useCmsPublishModeOptions === 'object'
+                ? options.useCmsPublishModeOptions
+                : { write: true };
+            addCmsPublishModeOptions(yargs, opts);
+        }
+        const result = callback(yargs);
+        // Must go last to pick up available options
+        await addCustomHelpOutput(result, command, describe);
+        return result;
+    };
+}

package/lib/yargs/makeYargsHandlerWithUsageTracking.d.ts

@@ -0,0 +1,3 @@
+import { ArgumentsCamelCase } from 'yargs';
+import { CommonArgs } from '../../types/Yargs.js';
+export declare function makeYargsHandlerWithUsageTracking<T extends CommonArgs>(trackingName: string, handler: (args: ArgumentsCamelCase<T>) => Promise<void>): (args: ArgumentsCamelCase<T>) => Promise<void>;

package/lib/yargs/makeYargsHandlerWithUsageTracking.js

@@ -0,0 +1,121 @@
+import os from 'os';
+import path from 'path';
+import { getConfig } from '@hubspot/local-dev-lib/config';
+import { getStateValue, setStateValue, } from '@hubspot/local-dev-lib/config/state';
+import { STATE_FLAGS } from '@hubspot/local-dev-lib/constants/config';
+import { logger as ldlLogger } from '@hubspot/local-dev-lib/logger';
+import { trackCommandUsage as _trackCommandUsage } from '../usageTracking.js';
+import { pkg } from '../jsonLoader.js';
+import { uiLogger } from '../ui/logger.js';
+import { lib } from '../../lang/en.js';
+import { EXIT_CODES } from '../enums/exitCodes.js';
+import { isPromptExitError } from '../errors/PromptExitError.js';
+import { debugError } from '../errorHandlers/index.js';
+const HANDLER_LOG_DIR = path.join(os.homedir(), '.hscli', 'logs');
+function logUsageTrackingMessage(isJsonOutput) {
+    if (isJsonOutput) {
+        return;
+    }
+    try {
+        const config = getConfig();
+        if (config?.allowUsageTracking !== true) {
+            return;
+        }
+        const lastShownVersion = getStateValue(STATE_FLAGS.USAGE_TRACKING_MESSAGE_LAST_SHOW_VERSION);
+        if (lastShownVersion === pkg.version) {
+            return;
+        }
+        setStateValue(STATE_FLAGS.USAGE_TRACKING_MESSAGE_LAST_SHOW_VERSION, pkg.version);
+        uiLogger.info(lib.usageTracking.transparencyMessage);
+    }
+    catch (_e) {
+        return;
+    }
+}
+export function makeYargsHandlerWithUsageTracking(trackingName, handler) {
+    return async (args) => {
+        const startTime = Date.now();
+        const meta = {};
+        let trackingFired = false;
+        const trackingArgs = args;
+        const addUsageMetadata = (newMeta) => {
+            Object.assign(meta, newMeta);
+        };
+        trackingArgs.addUsageMetadata = addUsageMetadata;
+        const trackCommandUsage = async (successful) => {
+            if (trackingFired) {
+                return;
+            }
+            trackingFired = true;
+            try {
+                const { accountId: overrideAccountId, ...trackingMeta } = meta;
+                trackingMeta.successful = successful;
+                trackingMeta.executionTime = Date.now() - startTime;
+                await _trackCommandUsage(trackingName, trackingMeta, overrideAccountId ?? args.derivedAccountId);
+            }
+            catch (_e) { }
+        };
+        const onForcedExit = () => {
+            process.exit(EXIT_CODES.SUCCESS);
+        };
+        const onSigint = async () => {
+            process.removeListener('SIGINT', onSigint);
+            process.on('SIGINT', onForcedExit);
+            try {
+                await trackCommandUsage(false);
+            }
+            catch (_e) { }
+            process.removeListener('SIGINT', onForcedExit);
+            process.exit(EXIT_CODES.SUCCESS);
+        };
+        process.on('SIGINT', onSigint);
+        const trackCommandUsageAndRemoveListeners = async (successful) => {
+            await trackCommandUsage(successful);
+            process.removeListener('SIGINT', onSigint);
+            process.removeListener('SIGINT', onForcedExit);
+        };
+        const jsonArgs = args;
+        const isJsonOutput = Boolean(jsonArgs.json || jsonArgs.formatOutputAsJson);
+        const writeFailureLogFile = () => {
+            // Skip in JSON output modes so the side effect + stderr message don't
+            // interfere with structured output consumers.
+            if (isJsonOutput) {
+                return;
+            }
+            const savedPath = ldlLogger.writeBufferedLogsToFile({
+                dir: HANDLER_LOG_DIR,
+                filenamePrefix: trackingName,
+            });
+            if (savedPath) {
+                uiLogger.log('');
+                uiLogger.error(lib.handlerLogFile.saved(savedPath));
+            }
+        };
+        trackingArgs.exit = async (code) => {
+            await trackCommandUsageAndRemoveListeners(code !== EXIT_CODES.ERROR);
+            if (code === EXIT_CODES.ERROR) {
+                writeFailureLogFile();
+            }
+            return process.exit(code);
+        };
+        logUsageTrackingMessage(isJsonOutput);
+        try {
+            await handler(trackingArgs);
+        }
+        catch (e) {
+            const isSuccessfulPromptExit = isPromptExitError(e)
+                ? e.exitCode !== EXIT_CODES.ERROR
+                : false;
+            await trackCommandUsageAndRemoveListeners(isSuccessfulPromptExit);
+            if (isPromptExitError(e)) {
+                return process.exit(e.exitCode);
+            }
+            else {
+                debugError(e);
+                writeFailureLogFile();
+                return process.exit(EXIT_CODES.ERROR);
+            }
+        }
+        await trackCommandUsageAndRemoveListeners(true);
+    };
+}

package/lib/yargs/parseYargsOrExit.d.ts

@@ -0,0 +1,4 @@
+import { ArgumentsCamelCase, Argv } from 'yargs';
+type YargsFailureHandler<T> = (message: string | null, error: unknown, parser: Argv<T>) => never;
+export declare function parseYargsOrExit<T>(parser: Argv<T>, handleFailure: YargsFailureHandler<T>): Promise<ArgumentsCamelCase<T>>;
+export {};

package/lib/yargs/parseYargsOrExit.js

@@ -0,0 +1,25 @@
+function getYargsErrorMessage(error) {
+    return error instanceof Error && error.name === 'YError' ? error.message : '';
+}
+function getYargsFailureMessage(message, error) {
+    if (message) {
+        return message;
+    }
+    return getYargsErrorMessage(error) || message;
+}
+export async function parseYargsOrExit(parser, handleFailure) {
+    let failureHandled = false;
+    const parserWithFailureHandler = parser.fail((message, error, yargs) => {
+        failureHandled = true;
+        return handleFailure(getYargsFailureMessage(message, error), error, yargs);
+    });
+    try {
+        return await parserWithFailureHandler.parseAsync();
+    }
+    catch (error) {
+        if (failureHandled) {
+            throw error;
+        }
+        return handleFailure(getYargsErrorMessage(error), error, parserWithFailureHandler);
+    }
+}

package/lib/yargs/strictEnforceBoolean.d.ts

@@ -0,0 +1 @@
+export declare function strictEnforceBoolean(rawArgs: string[], booleanOptions: string[]): boolean;

package/lib/yargs/strictEnforceBoolean.js

@@ -0,0 +1,13 @@
+import { commands } from '../../lang/en.js';
+export function strictEnforceBoolean(rawArgs, booleanOptions) {
+    for (const option of booleanOptions) {
+        const argIndex = rawArgs.findIndex(arg => arg.startsWith(`--${option}=`));
+        if (argIndex !== -1) {
+            const value = rawArgs[argIndex].split('=')[1];
+            if (value && !['true', 'false'].includes(value.toLowerCase())) {
+                throw new Error(commands.config.subcommands.set.errors.invalidBoolean(option, value));
+            }
+        }
+    }
+    return true;
+}

package/lib/yargsUtils.d.ts

@@ -1,16 +1,3 @@
-import { Argv } from 'yargs';
-import { hasFlag } from './utils/hasFlag.js';
-export { hasFlag };
-export declare function makeYargsBuilder<T>(callback: (yargs: Argv) => Argv<T>, command: string | string[], describe?: string, options?: {
-    useGlobalOptions?: boolean;
-    useAccountOptions?: boolean;
-    useConfigOptions?: boolean;
-    useEnvironmentOptions?: boolean;
-    useTestingOptions?: boolean;
-    useCmsPublishModeOptions?: boolean | {
-        read?: boolean;
-        write?: boolean;
-    };
-    useJSONOutputOptions?: boolean;
-}): (yargs: Argv) => Promise<Argv<T>>;
-export declare function strictEnforceBoolean(rawArgs: string[], booleanOptions: string[]): boolean;
+export { hasFlag } from './utils/hasFlag.js';
+export { makeYargsBuilder } from './yargs/makeYargsBuilder.js';
+export { strictEnforceBoolean } from './yargs/strictEnforceBoolean.js';

package/lib/yargsUtils.js

@@ -1,49 +1,4 @@
-import { addCustomHelpOutput, addTestingOptions, addAccountOptions, addConfigOptions, addGlobalOptions, addUseEnvironmentOptions, addCmsPublishModeOptions, addJSONOutputOptions, } from './commonOpts.js';
-import { hasFlag } from './utils/hasFlag.js';
-import { commands } from '../lang/en.js';
 // Re-export for backwards compatibility
-export { hasFlag };
-export function makeYargsBuilder(callback, command, describe, options = {}) {
-    return async function (yargs) {
-        if (options.useGlobalOptions) {
-            addGlobalOptions(yargs);
-        }
-        if (options.useAccountOptions) {
-            addAccountOptions(yargs);
-        }
-        if (options.useConfigOptions) {
-            addConfigOptions(yargs);
-        }
-        if (options.useEnvironmentOptions) {
-            addUseEnvironmentOptions(yargs);
-        }
-        if (options.useTestingOptions) {
-            addTestingOptions(yargs);
-        }
-        if (options.useJSONOutputOptions) {
-            addJSONOutputOptions(yargs);
-        }
-        if (options.useCmsPublishModeOptions) {
-            const opts = typeof options.useCmsPublishModeOptions === 'object'
-                ? options.useCmsPublishModeOptions
-                : { write: true };
-            addCmsPublishModeOptions(yargs, opts);
-        }
-        const result = callback(yargs);
-        // Must go last to pick up available options
-        await addCustomHelpOutput(result, command, describe);
-        return result;
-    };
-}
-export function strictEnforceBoolean(rawArgs, booleanOptions) {
-    for (const option of booleanOptions) {
-        const argIndex = rawArgs.findIndex(arg => arg.startsWith(`--${option}=`));
-        if (argIndex !== -1) {
-            const value = rawArgs[argIndex].split('=')[1];
-            if (value && !['true', 'false'].includes(value.toLowerCase())) {
-                throw new Error(commands.config.subcommands.set.errors.invalidBoolean(option, value));
-            }
-        }
-    }
-    return true;
-}
+export { hasFlag } from './utils/hasFlag.js';
+export { makeYargsBuilder } from './yargs/makeYargsBuilder.js';
+export { strictEnforceBoolean } from './yargs/strictEnforceBoolean.js';

package/mcp-server/Tool.d.ts

@@ -0,0 +1,15 @@
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpLogger } from './utils/logger.js';
+import { TextContentResponse } from './types.js';
+export declare class Tool<InputSchema> {
+    protected mcpServer: McpServer;
+    protected logger: McpLogger;
+    protected toolName: string;
+    constructor(mcpServer: McpServer, logger: McpLogger, toolName: string);
+    register(): RegisteredTool;
+    handler(input: InputSchema): TextContentResponse | Promise<TextContentResponse>;
+    protected getTrackingMeta(input: InputSchema): {
+        [key: string]: string;
+    } | undefined;
+    protected wrappedHandler(input: InputSchema): Promise<TextContentResponse>;
+}

package/mcp-server/Tool.js

@@ -0,0 +1,53 @@
+import { formatTextContents } from './utils/content.js';
+import { getErrorMessage } from '../lib/errorHandlers/index.js';
+import { trackToolUsage } from './utils/toolUsageTracking.js';
+export class Tool {
+    mcpServer;
+    logger;
+    toolName;
+    constructor(mcpServer, logger, toolName) {
+        this.mcpServer = mcpServer;
+        this.logger = logger;
+        this.toolName = toolName;
+    }
+    register() {
+        throw new Error('Must implement register');
+    }
+    handler(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    input) {
+        throw new Error('Must implement handler');
+    }
+    getTrackingMeta(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    input) {
+        return undefined;
+    }
+    async wrappedHandler(input) {
+        const startTime = Date.now();
+        try {
+            // `input` is logged unredacted. Tool input schemas MUST NOT include
+            // credentials or other sensitive values, since MCP clients (Claude
+            // Desktop, Inspector, etc.) will display these logs.
+            this.logger.debug(this.toolName, {
+                message: 'Tool invoked',
+                args: input,
+            });
+            await trackToolUsage(this.toolName, this.getTrackingMeta(input));
+            const result = await this.handler(input);
+            this.logger.debug(this.toolName, {
+                message: 'Tool completed',
+                durationMs: Date.now() - startTime,
+            });
+            return result;
+        }
+        catch (error) {
+            this.logger.error(this.toolName, {
+                message: 'Tool failed',
+                error: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            });
+            return formatTextContents(getErrorMessage(error));
+        }
+    }
+}