@office-ai/aioncli-core 0.30.0 → 0.30.1

package/dist/src/utils/compatibility.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Detects if the current OS is Windows 10.
+ * Windows 11 also reports as version 10.0, but with build numbers >= 22000.
+ */
+export declare function isWindows10(): boolean;
+/**
+ * Detects if the current terminal is a JetBrains-based IDE terminal.
+ */
+export declare function isJetBrainsTerminal(): boolean;
+/**
+ * Detects if the current terminal is the default Apple Terminal.app.
+ */
+export declare function isAppleTerminal(): boolean;
+/**
+ * Detects if the current terminal supports 256 colors (8-bit).
+ */
+export declare function supports256Colors(): boolean;
+/**
+ * Detects if the current terminal supports true color (24-bit).
+ */
+export declare function supportsTrueColor(): boolean;
+export declare enum WarningPriority {
+    Low = "low",
+    High = "high"
+}
+export interface StartupWarning {
+    id: string;
+    message: string;
+    priority: WarningPriority;
+}
+/**
+ * Returns a list of compatibility warnings based on the current environment.
+ */
+export declare function getCompatibilityWarnings(options?: {
+    isAlternateBuffer?: boolean;
+}): StartupWarning[];

package/dist/src/utils/compatibility.js

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import os from 'node:os';
+/**
+ * Detects if the current OS is Windows 10.
+ * Windows 11 also reports as version 10.0, but with build numbers >= 22000.
+ */
+export function isWindows10() {
+    if (os.platform() !== 'win32') {
+        return false;
+    }
+    const release = os.release();
+    const parts = release.split('.');
+    if (parts.length >= 3 && parts[0] === '10' && parts[1] === '0') {
+        const build = parseInt(parts[2], 10);
+        return build < 22000;
+    }
+    return false;
+}
+/**
+ * Detects if the current terminal is a JetBrains-based IDE terminal.
+ */
+export function isJetBrainsTerminal() {
+    return process.env['TERMINAL_EMULATOR'] === 'JetBrains-JediTerm';
+}
+/**
+ * Detects if the current terminal is the default Apple Terminal.app.
+ */
+export function isAppleTerminal() {
+    return process.env['TERM_PROGRAM'] === 'Apple_Terminal';
+}
+/**
+ * Detects if the current terminal supports 256 colors (8-bit).
+ */
+export function supports256Colors() {
+    // Check if stdout supports at least 8-bit color depth
+    if (process.stdout.getColorDepth && process.stdout.getColorDepth() >= 8) {
+        return true;
+    }
+    // Check TERM environment variable
+    const term = process.env['TERM'] || '';
+    if (term.includes('256color')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Detects if the current terminal supports true color (24-bit).
+ */
+export function supportsTrueColor() {
+    // Check COLORTERM environment variable
+    if (process.env['COLORTERM'] === 'truecolor' ||
+        process.env['COLORTERM'] === '24bit') {
+        return true;
+    }
+    // Check if stdout supports 24-bit color depth
+    if (process.stdout.getColorDepth && process.stdout.getColorDepth() >= 24) {
+        return true;
+    }
+    return false;
+}
+export var WarningPriority;
+(function (WarningPriority) {
+    WarningPriority["Low"] = "low";
+    WarningPriority["High"] = "high";
+})(WarningPriority || (WarningPriority = {}));
+/**
+ * Returns a list of compatibility warnings based on the current environment.
+ */
+export function getCompatibilityWarnings(options) {
+    const warnings = [];
+    if (isWindows10()) {
+        warnings.push({
+            id: 'windows-10',
+            message: 'Warning: Windows 10 detected. Some UI features like smooth scrolling may be degraded. Windows 11 is recommended for the best experience.',
+            priority: WarningPriority.High,
+        });
+    }
+    if (isJetBrainsTerminal() && options?.isAlternateBuffer) {
+        const platformTerminals = {
+            win32: 'Windows Terminal',
+            darwin: 'iTerm2 or Ghostty',
+            linux: 'Ghostty',
+        };
+        const suggestion = platformTerminals[os.platform()];
+        const suggestedTerminals = suggestion ? ` (e.g., ${suggestion})` : '';
+        warnings.push({
+            id: 'jetbrains-terminal',
+            message: `Warning: JetBrains mouse scrolling is unreliable. Disabling alternate buffer mode in settings or using an external terminal${suggestedTerminals} is recommended.`,
+            priority: WarningPriority.High,
+        });
+    }
+    if (!supports256Colors()) {
+        warnings.push({
+            id: '256-color',
+            message: 'Warning: 256-color support not detected. Using a terminal with at least 256-color support is recommended for a better visual experience.',
+            priority: WarningPriority.High,
+        });
+    }
+    else if (!supportsTrueColor() && !isAppleTerminal()) {
+        warnings.push({
+            id: 'true-color',
+            message: 'Warning: True color (24-bit) support not detected. Using a terminal with true color enabled will result in a better visual experience.',
+            priority: WarningPriority.Low,
+        });
+    }
+    return warnings;
+}
+//# sourceMappingURL=compatibility.js.map

package/dist/src/utils/compatibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.js","sourceRoot":"","sources":["../../../src/utils/compatibility.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/compatibility.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/utils/compatibility.test.js

@@ -0,0 +1,233 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import os from 'node:os';
+import { isWindows10, isJetBrainsTerminal, supports256Colors, supportsTrueColor, getCompatibilityWarnings, WarningPriority, } from './compatibility.js';
+vi.mock('node:os', () => ({
+    default: {
+        platform: vi.fn(),
+        release: vi.fn(),
+    },
+}));
+describe('compatibility', () => {
+    const originalGetColorDepth = process.stdout.getColorDepth;
+    afterEach(() => {
+        process.stdout.getColorDepth = originalGetColorDepth;
+        vi.restoreAllMocks();
+        vi.unstubAllEnvs();
+    });
+    describe('isWindows10', () => {
+        it.each([
+            {
+                platform: 'win32',
+                release: '10.0.19041',
+                expected: true,
+                desc: 'Windows 10 (build < 22000)',
+            },
+            {
+                platform: 'win32',
+                release: '10.0.22000',
+                expected: false,
+                desc: 'Windows 11 (build >= 22000)',
+            },
+            {
+                platform: 'darwin',
+                release: '20.6.0',
+                expected: false,
+                desc: 'non-Windows platforms',
+            },
+        ])('should return $expected for $desc', ({ platform, release, expected }) => {
+            vi.mocked(os.platform).mockReturnValue(platform);
+            vi.mocked(os.release).mockReturnValue(release);
+            expect(isWindows10()).toBe(expected);
+        });
+    });
+    describe('isJetBrainsTerminal', () => {
+        it.each([
+            {
+                env: 'JetBrains-JediTerm',
+                expected: true,
+                desc: 'TERMINAL_EMULATOR is JetBrains-JediTerm',
+            },
+            { env: 'something-else', expected: false, desc: 'other terminals' },
+            { env: '', expected: false, desc: 'TERMINAL_EMULATOR is not set' },
+        ])('should return $expected when $desc', ({ env, expected }) => {
+            vi.stubEnv('TERMINAL_EMULATOR', env);
+            expect(isJetBrainsTerminal()).toBe(expected);
+        });
+    });
+    describe('supports256Colors', () => {
+        it.each([
+            {
+                depth: 8,
+                term: undefined,
+                expected: true,
+                desc: 'getColorDepth returns >= 8',
+            },
+            {
+                depth: 4,
+                term: 'xterm-256color',
+                expected: true,
+                desc: 'TERM contains 256color',
+            },
+            {
+                depth: 4,
+                term: 'xterm',
+                expected: false,
+                desc: '256 colors are not supported',
+            },
+        ])('should return $expected when $desc', ({ depth, term, expected }) => {
+            process.stdout.getColorDepth = vi.fn().mockReturnValue(depth);
+            if (term !== undefined) {
+                vi.stubEnv('TERM', term);
+            }
+            expect(supports256Colors()).toBe(expected);
+        });
+    });
+    describe('supportsTrueColor', () => {
+        it.each([
+            {
+                colorterm: 'truecolor',
+                depth: 8,
+                expected: true,
+                desc: 'COLORTERM is truecolor',
+            },
+            {
+                colorterm: '24bit',
+                depth: 8,
+                expected: true,
+                desc: 'COLORTERM is 24bit',
+            },
+            {
+                colorterm: '',
+                depth: 24,
+                expected: true,
+                desc: 'getColorDepth returns >= 24',
+            },
+            {
+                colorterm: '',
+                depth: 8,
+                expected: false,
+                desc: 'true color is not supported',
+            },
+        ])('should return $expected when $desc', ({ colorterm, depth, expected }) => {
+            vi.stubEnv('COLORTERM', colorterm);
+            process.stdout.getColorDepth = vi.fn().mockReturnValue(depth);
+            expect(supportsTrueColor()).toBe(expected);
+        });
+    });
+    describe('getCompatibilityWarnings', () => {
+        beforeEach(() => {
+            // Default to supporting true color to keep existing tests simple
+            vi.stubEnv('COLORTERM', 'truecolor');
+            process.stdout.getColorDepth = vi.fn().mockReturnValue(24);
+        });
+        it('should return Windows 10 warning when detected', () => {
+            vi.mocked(os.platform).mockReturnValue('win32');
+            vi.mocked(os.release).mockReturnValue('10.0.19041');
+            vi.stubEnv('TERMINAL_EMULATOR', '');
+            const warnings = getCompatibilityWarnings();
+            expect(warnings).toContainEqual(expect.objectContaining({
+                id: 'windows-10',
+                message: expect.stringContaining('Windows 10 detected'),
+            }));
+        });
+        it.each([
+            {
+                platform: 'darwin',
+                release: '20.6.0',
+                externalTerminal: 'iTerm2 or Ghostty',
+                desc: 'macOS',
+            },
+            {
+                platform: 'win32',
+                release: '10.0.22000',
+                externalTerminal: 'Windows Terminal',
+                desc: 'Windows',
+            }, // Valid Windows 11 release to not trigger the Windows 10 warning
+            {
+                platform: 'linux',
+                release: '5.10.0',
+                externalTerminal: 'Ghostty',
+                desc: 'Linux',
+            },
+        ])('should return JetBrains warning when detected and in alternate buffer ($desc)', ({ platform, release, externalTerminal }) => {
+            vi.mocked(os.platform).mockReturnValue(platform);
+            vi.mocked(os.release).mockReturnValue(release);
+            vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
+            const warnings = getCompatibilityWarnings({ isAlternateBuffer: true });
+            expect(warnings).toContainEqual(expect.objectContaining({
+                id: 'jetbrains-terminal',
+                message: expect.stringContaining(`Warning: JetBrains mouse scrolling is unreliable. Disabling alternate buffer mode in settings or using an external terminal (e.g., ${externalTerminal}) is recommended.`),
+                priority: WarningPriority.High,
+            }));
+        });
+        it('should not return JetBrains warning when detected but NOT in alternate buffer', () => {
+            vi.mocked(os.platform).mockReturnValue('darwin');
+            vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
+            const warnings = getCompatibilityWarnings({ isAlternateBuffer: false });
+            expect(warnings.find((w) => w.id === 'jetbrains-terminal')).toBeUndefined();
+        });
+        it('should return 256-color warning when 256 colors are not supported', () => {
+            vi.mocked(os.platform).mockReturnValue('linux');
+            vi.stubEnv('TERMINAL_EMULATOR', '');
+            vi.stubEnv('COLORTERM', '');
+            vi.stubEnv('TERM', 'xterm');
+            process.stdout.getColorDepth = vi.fn().mockReturnValue(4);
+            const warnings = getCompatibilityWarnings();
+            expect(warnings).toContainEqual(expect.objectContaining({
+                id: '256-color',
+                message: expect.stringContaining('256-color support not detected'),
+                priority: WarningPriority.High,
+            }));
+            // Should NOT show true-color warning if 256-color warning is shown
+            expect(warnings.find((w) => w.id === 'true-color')).toBeUndefined();
+        });
+        it('should return true color warning when 256 colors are supported but true color is not, and not Apple Terminal', () => {
+            vi.mocked(os.platform).mockReturnValue('linux');
+            vi.stubEnv('TERMINAL_EMULATOR', '');
+            vi.stubEnv('COLORTERM', '');
+            vi.stubEnv('TERM_PROGRAM', 'xterm');
+            process.stdout.getColorDepth = vi.fn().mockReturnValue(8);
+            const warnings = getCompatibilityWarnings();
+            expect(warnings).toContainEqual(expect.objectContaining({
+                id: 'true-color',
+                message: expect.stringContaining('True color (24-bit) support not detected'),
+                priority: WarningPriority.Low,
+            }));
+        });
+        it('should NOT return true color warning for Apple Terminal', () => {
+            vi.mocked(os.platform).mockReturnValue('darwin');
+            vi.stubEnv('TERMINAL_EMULATOR', '');
+            vi.stubEnv('COLORTERM', '');
+            vi.stubEnv('TERM_PROGRAM', 'Apple_Terminal');
+            process.stdout.getColorDepth = vi.fn().mockReturnValue(8);
+            const warnings = getCompatibilityWarnings();
+            expect(warnings.find((w) => w.id === 'true-color')).toBeUndefined();
+        });
+        it('should return all warnings when all are detected', () => {
+            vi.mocked(os.platform).mockReturnValue('win32');
+            vi.mocked(os.release).mockReturnValue('10.0.19041');
+            vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
+            vi.stubEnv('COLORTERM', '');
+            vi.stubEnv('TERM_PROGRAM', 'xterm');
+            process.stdout.getColorDepth = vi.fn().mockReturnValue(8);
+            const warnings = getCompatibilityWarnings({ isAlternateBuffer: true });
+            expect(warnings).toHaveLength(3);
+            expect(warnings[0].message).toContain('Windows 10 detected');
+            expect(warnings[1].message).toContain('JetBrains');
+            expect(warnings[2].message).toContain('True color (24-bit) support not detected');
+        });
+        it('should return no warnings in a standard environment with true color', () => {
+            vi.mocked(os.platform).mockReturnValue('darwin');
+            vi.stubEnv('TERMINAL_EMULATOR', '');
+            vi.stubEnv('COLORTERM', 'truecolor');
+            const warnings = getCompatibilityWarnings();
+            expect(warnings).toHaveLength(0);
+        });
+    });
+});
+//# sourceMappingURL=compatibility.test.js.map

package/dist/src/utils/compatibility.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.test.js","sourceRoot":"","sources":["../../../src/utils/compatibility.test.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/envExpansion.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Expands environment variables in a string using the provided environment record.
+ * Uses the standard `dotenv-expand` library to handle expansion consistently with
+ * other tools.
+ *
+ * Supports POSIX/Bash syntax ($VAR, ${VAR}).
+ * Note: Windows syntax (%VAR%) is not natively supported by dotenv-expand.
+ *
+ * @param str - The string containing environment variable placeholders.
+ * @param env - A record of environment variable names and their values.
+ * @returns The string with environment variables expanded. Missing variables resolve to an empty string.
+ */
+export declare function expandEnvVars(str: string, env: Record<string, string | undefined>): string;

package/dist/src/utils/envExpansion.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { expand } from 'dotenv-expand';
+/**
+ * Expands environment variables in a string using the provided environment record.
+ * Uses the standard `dotenv-expand` library to handle expansion consistently with
+ * other tools.
+ *
+ * Supports POSIX/Bash syntax ($VAR, ${VAR}).
+ * Note: Windows syntax (%VAR%) is not natively supported by dotenv-expand.
+ *
+ * @param str - The string containing environment variable placeholders.
+ * @param env - A record of environment variable names and their values.
+ * @returns The string with environment variables expanded. Missing variables resolve to an empty string.
+ */
+export function expandEnvVars(str, env) {
+    if (!str)
+        return str;
+    // 1. Pre-process Windows-style variables (%VAR%) since dotenv-expand only handles POSIX ($VAR).
+    // We only do this on Windows to limit the blast radius and avoid conflicts with other
+    // systems where % might be a literal character (e.g. in URLs or shell commands).
+    const isWindows = process.platform === 'win32';
+    const processedStr = isWindows
+        ? str.replace(/%(\w+)%/g, (_, name) => env[name] ?? '')
+        : str;
+    // 2. Use dotenv-expand for POSIX/Bash syntax ($VAR, ${VAR}).
+    // dotenv-expand is designed to process an object of key-value pairs (like a .env file).
+    // To expand a single string, we wrap it in an object with a temporary key.
+    const dummyKey = '__GCLI_EXPAND_TARGET__';
+    // Filter out undefined values to satisfy the Record<string, string> requirement safely
+    const processEnv = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined) {
+            processEnv[key] = value;
+        }
+    }
+    const result = expand({
+        parsed: { [dummyKey]: processedStr },
+        processEnv,
+    });
+    return result.parsed?.[dummyKey] ?? '';
+}
+//# sourceMappingURL=envExpansion.js.map

package/dist/src/utils/envExpansion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envExpansion.js","sourceRoot":"","sources":["../../../src/utils/envExpansion.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAA2B,MAAM,eAAe,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,GAAuC;IAEvC,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IAErB,gGAAgG;IAChG,sFAAsF;IACtF,iFAAiF;IACjF,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC/C,MAAM,YAAY,GAAG,SAAS;QAC5B,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACvD,CAAC,CAAC,GAAG,CAAC;IAER,6DAA6D;IAC7D,wFAAwF;IACxF,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,wBAAwB,CAAC;IAE1C,uFAAuF;IACvF,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,UAAU,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAuB,MAAM,CAAC;QACxC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE;QACpC,UAAU;KACX,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;AACzC,CAAC"}

package/dist/src/utils/envExpansion.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/utils/envExpansion.test.js

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { expandEnvVars } from './envExpansion.js';
+describe('expandEnvVars', () => {
+    const defaultEnv = {
+        USER: 'morty',
+        HOME: '/home/morty',
+        TEMP: 'C:\\Temp',
+        EMPTY: '',
+    };
+    describe('POSIX behavior (non-Windows)', () => {
+        beforeEach(() => {
+            vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin');
+        });
+        afterEach(() => {
+            vi.restoreAllMocks();
+        });
+        it.each([
+            ['$VAR (POSIX)', 'Hello $USER', defaultEnv, 'Hello morty'],
+            [
+                '${VAR} (POSIX)',
+                'Welcome to ${HOME}',
+                defaultEnv,
+                'Welcome to /home/morty',
+            ],
+            [
+                'should NOT expand %VAR% on non-Windows',
+                'Data in %TEMP%',
+                defaultEnv,
+                'Data in %TEMP%',
+            ],
+            [
+                'mixed formats (only POSIX expanded)',
+                '$USER lives in ${HOME} on %TEMP%',
+                defaultEnv,
+                'morty lives in /home/morty on %TEMP%',
+            ],
+            [
+                'missing variables (POSIX only)',
+                'Missing $UNDEFINED and ${NONE} and %MISSING%',
+                defaultEnv,
+                'Missing  and  and %MISSING%',
+            ],
+            [
+                'empty or undefined values',
+                'Value is "$EMPTY"',
+                defaultEnv,
+                'Value is ""',
+            ],
+            [
+                'original string if no variables',
+                'No vars here',
+                defaultEnv,
+                'No vars here',
+            ],
+            ['literal values like "1234"', '1234', defaultEnv, '1234'],
+            ['empty input string', '', defaultEnv, ''],
+            [
+                'complex paths',
+                '${HOME}/bin:$PATH',
+                { ...defaultEnv, PATH: '/usr/bin' },
+                '/home/morty/bin:/usr/bin',
+            ],
+        ])('should handle %s', (_, input, env, expected) => {
+            expect(expandEnvVars(input, env)).toBe(expected);
+        });
+    });
+    describe('Windows behavior', () => {
+        beforeEach(() => {
+            vi.spyOn(process, 'platform', 'get').mockReturnValue('win32');
+        });
+        afterEach(() => {
+            vi.restoreAllMocks();
+        });
+        it.each([
+            ['$VAR (POSIX)', 'Hello $USER', defaultEnv, 'Hello morty'],
+            [
+                '${VAR} (POSIX)',
+                'Welcome to ${HOME}',
+                defaultEnv,
+                'Welcome to /home/morty',
+            ],
+            [
+                'should expand %VAR% on Windows',
+                'Data in %TEMP%',
+                defaultEnv,
+                'Data in C:\\Temp',
+            ],
+            [
+                'mixed formats (both expanded)',
+                '$USER lives in ${HOME} on %TEMP%',
+                defaultEnv,
+                'morty lives in /home/morty on C:\\Temp',
+            ],
+            [
+                'missing variables (all expanded to empty)',
+                'Missing $UNDEFINED and ${NONE} and %MISSING%',
+                defaultEnv,
+                'Missing  and  and ',
+            ],
+        ])('should handle %s', (_, input, env, expected) => {
+            expect(expandEnvVars(input, env)).toBe(expected);
+        });
+    });
+});
+//# sourceMappingURL=envExpansion.test.js.map

package/dist/src/utils/envExpansion.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envExpansion.test.js","sourceRoot":"","sources":["../../../src/utils/envExpansion.test.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/errors_timeout.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/utils/errors_timeout.test.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { getErrorMessage } from './errors.js';
+import {} from './httpErrors.js';
+describe('getErrorMessage with timeout errors', () => {
+    it('should handle undici HeadersTimeoutError correctly', () => {
+        // Simulate what undici might throw if it's not a proper Error instance
+        // or has a specific code.
+        const timeoutError = {
+            name: 'HeadersTimeoutError',
+            code: 'UND_ERR_HEADERS_TIMEOUT',
+            message: 'Headers timeout error',
+        };
+        // If it's a plain object, getErrorMessage might struggle if it expects an Error
+        const message = getErrorMessage(timeoutError);
+        // Based on existing implementation:
+        // friendlyError = toFriendlyError(timeoutError) -> returns timeoutError
+        // if (friendlyError instanceof Error) -> false
+        // return String(friendlyError) -> "[object Object]"
+        expect(message).toBe('Headers timeout error');
+    });
+    it('should handle undici HeadersTimeoutError as an Error instance', () => {
+        const error = new Error('Headers timeout error');
+        error.name = 'HeadersTimeoutError';
+        error.status = 504; // simulate status for test
+        error.code = 'UND_ERR_HEADERS_TIMEOUT';
+        const message = getErrorMessage(error);
+        expect(message).toBe('Headers timeout error');
+    });
+    it('should return String representation for objects without a message property', () => {
+        const error = { some: 'other', object: 123 };
+        const message = getErrorMessage(error);
+        expect(message).toBe('[object Object]');
+    });
+});
+//# sourceMappingURL=errors_timeout.test.js.map