@vybestack/llxprt-code-tools 0.10.0-nightly.260613.1adad3b34

package/dist/src/utils/ast-grep-utils.js

@@ -0,0 +1,140 @@
+/**
+ * Shared AST-grep utilities for all tools that use @ast-grep/napi.
+ * Single source of truth for language mapping, parsing, and error normalization.
+ *
+ * @plan PLAN-20260211-ASTGREP.P03
+ */
+import { parse, Lang, findInFiles, registerDynamicLanguage, } from '@ast-grep/napi';
+import python from '@ast-grep/lang-python';
+import go from '@ast-grep/lang-go';
+import rust from '@ast-grep/lang-rust';
+import java from '@ast-grep/lang-java';
+import cpp from '@ast-grep/lang-cpp';
+import c from '@ast-grep/lang-c';
+import json from '@ast-grep/lang-json';
+import ruby from '@ast-grep/lang-ruby';
+import * as path from 'node:path';
+let dynamicLanguagesRegistered = false;
+function ensureDynamicLanguages() {
+    if (dynamicLanguagesRegistered)
+        return;
+    registerDynamicLanguage({
+        python,
+        go,
+        rust,
+        java,
+        cpp,
+        c,
+        json,
+        ruby,
+    }); // eslint-disable-line @typescript-eslint/no-explicit-any -- Required for ast-grep dynamic language registration (third-party API limitation)
+    dynamicLanguagesRegistered = true;
+}
+// Register on module load
+ensureDynamicLanguages();
+/**
+ * File extension to ast-grep language mapping.
+ * Single source of truth across all AST tools.
+ */
+export const LANGUAGE_MAP = {
+    ts: Lang.TypeScript,
+    js: Lang.JavaScript,
+    tsx: Lang.Tsx,
+    jsx: Lang.Tsx,
+    py: 'python',
+    rb: 'ruby',
+    go: 'go',
+    rs: 'rust',
+    java: 'java',
+    cpp: 'cpp',
+    c: 'c',
+    html: Lang.Html,
+    css: Lang.Css,
+    json: 'json',
+};
+/**
+ * Reverse mapping from full language names to Lang/string values.
+ */
+const LANGUAGE_NAME_MAP = {
+    typescript: Lang.TypeScript,
+    javascript: Lang.JavaScript,
+    tsx: Lang.Tsx,
+    jsx: Lang.Tsx,
+    python: 'python',
+    ruby: 'ruby',
+    go: 'go',
+    rust: 'rust',
+    java: 'java',
+    cpp: 'cpp',
+    c: 'c',
+    html: Lang.Html,
+    css: Lang.Css,
+    json: 'json',
+};
+/**
+ * File extensions that belong to the JavaScript/TypeScript language family.
+ */
+export const JAVASCRIPT_FAMILY_EXTENSIONS = [
+    'ts',
+    'js',
+    'tsx',
+    'jsx',
+];
+/**
+ * Resolve a file extension or language name to an ast-grep language.
+ * Accepts both extensions ('ts', 'py') and full names ('typescript', 'python').
+ * Returns undefined for unrecognized inputs.
+ */
+export function getAstLanguage(extOrName) {
+    // Try extension first
+    if (extOrName in LANGUAGE_MAP) {
+        return LANGUAGE_MAP[extOrName];
+    }
+    // Try full name (case-insensitive)
+    const lower = extOrName.toLowerCase();
+    if (lower in LANGUAGE_NAME_MAP) {
+        return LANGUAGE_NAME_MAP[lower];
+    }
+    return undefined;
+}
+/**
+ * Detect the ast-grep language from a file path's extension.
+ * Returns undefined if the extension is not recognized.
+ */
+export function resolveLanguageFromPath(filePath) {
+    const ext = path.extname(filePath).slice(1); // remove the dot
+    if (!ext)
+        return undefined;
+    return LANGUAGE_MAP[ext];
+}
+/**
+ * Check if @ast-grep/napi is available and usable.
+ */
+export function isAstGrepAvailable() {
+    try {
+        // If we got this far, the import succeeded
+        return typeof parse === 'function' && typeof findInFiles === 'function';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse source code with error normalization.
+ * Returns { root } on success or { error } on failure.
+ * Does not throw.
+ */
+export function parseSource(language, content) {
+    try {
+        ensureDynamicLanguages();
+        const result = parse(language, content);
+        return { root: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { error: `Failed to parse source: ${message}` };
+    }
+}
+// Re-export ast-grep APIs for convenience
+export { parse, Lang, findInFiles } from '@ast-grep/napi';
+//# sourceMappingURL=ast-grep-utils.js.map

package/dist/src/utils/ast-grep-utils.js.map

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

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

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare const debugLogger: {
+    error: (..._args: unknown[]) => void;
+    warn: (..._args: unknown[]) => void;
+    debug: (..._args: unknown[]) => void;
+    log: (..._args: unknown[]) => void;
+};

package/dist/src/utils/debugLogger.js

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export const debugLogger = {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    error: (..._args) => { },
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    warn: (..._args) => { },
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    debug: (..._args) => { },
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    log: (..._args) => { },
+};
+//# sourceMappingURL=debugLogger.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"debugLogger.js","sourceRoot":"","sources":["../../../src/utils/debugLogger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,6DAA6D;IAC7D,KAAK,EAAE,CAAC,GAAG,KAAgB,EAAQ,EAAE,GAAE,CAAC;IACxC,6DAA6D;IAC7D,IAAI,EAAE,CAAC,GAAG,KAAgB,EAAQ,EAAE,GAAE,CAAC;IACvC,6DAA6D;IAC7D,KAAK,EAAE,CAAC,GAAG,KAAgB,EAAQ,EAAE,GAAE,CAAC;IACxC,6DAA6D;IAC7D,GAAG,EAAE,CAAC,GAAG,KAAgB,EAAQ,EAAE,GAAE,CAAC;CACvC,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * @plan:PLAN-20260608-ISSUE1585.P11
+ * @requirement:REQ-PKG-BOUNDARY
+ */
+import type { StructuredPatchOptionsNonabortable, CreatePatchOptionsNonabortable } from 'diff';
+export interface DiffStat {
+    ai_removed_lines: number;
+    ai_added_lines: number;
+    user_added_lines: number;
+    user_removed_lines: number;
+}
+export declare const DEFAULT_DIFF_OPTIONS: StructuredPatchOptionsNonabortable;
+export declare const DEFAULT_CREATE_PATCH_OPTIONS: CreatePatchOptionsNonabortable;
+export declare function getDiffStat(fileName: string, oldStr: string, aiStr: string, userStr: string): DiffStat;

package/dist/src/utils/diffOptions.js

@@ -0,0 +1,46 @@
+/**
+ * @plan:PLAN-20260608-ISSUE1585.P11
+ * @requirement:REQ-PKG-BOUNDARY
+ */
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as Diff from 'diff';
+export const DEFAULT_DIFF_OPTIONS = {
+    context: 3,
+    ignoreWhitespace: true,
+};
+export const DEFAULT_CREATE_PATCH_OPTIONS = {
+    context: 3,
+    ignoreWhitespace: true,
+};
+export function getDiffStat(fileName, oldStr, aiStr, userStr) {
+    const countLines = (patch) => {
+        let added = 0;
+        let removed = 0;
+        patch.hunks.forEach((hunk) => {
+            hunk.lines.forEach((line) => {
+                if (line.startsWith('+')) {
+                    added++;
+                }
+                else if (line.startsWith('-')) {
+                    removed++;
+                }
+            });
+        });
+        return { added, removed };
+    };
+    const patch = Diff.structuredPatch(fileName, fileName, oldStr, aiStr, 'Current', 'Proposed', DEFAULT_DIFF_OPTIONS);
+    const { added: aiAddedLines, removed: aiRemovedLines } = countLines(patch);
+    const userPatch = Diff.structuredPatch(fileName, fileName, aiStr, userStr, 'Proposed', 'User', DEFAULT_DIFF_OPTIONS);
+    const { added: userAddedLines, removed: userRemovedLines } = countLines(userPatch);
+    return {
+        ai_added_lines: aiAddedLines,
+        ai_removed_lines: aiRemovedLines,
+        user_added_lines: userAddedLines,
+        user_removed_lines: userRemovedLines,
+    };
+}
+//# sourceMappingURL=diffOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diffOptions.js","sourceRoot":"","sources":["../../../src/utils/diffOptions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAe7B,MAAM,CAAC,MAAM,oBAAoB,GAAuC;IACtE,OAAO,EAAE,CAAC;IACV,gBAAgB,EAAE,IAAI;CACvB,CAAC;AAEF,MAAM,CAAC,MAAM,4BAA4B,GAAmC;IAC1E,OAAO,EAAE,CAAC;IACV,gBAAgB,EAAE,IAAI;CACvB,CAAC;AAEF,MAAM,UAAU,WAAW,CACzB,QAAgB,EAChB,MAAc,EACd,KAAa,EACb,OAAe;IAEf,MAAM,UAAU,GAAG,CAAC,KAAsB,EAAE,EAAE;QAC5C,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAyB,EAAE,EAAE;YAChD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAY,EAAE,EAAE;gBAClC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,KAAK,EAAE,CAAC;gBACV,CAAC;qBAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAChC,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC5B,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAChC,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,KAAK,EACL,SAAS,EACT,UAAU,EACV,oBAAoB,CACrB,CAAC;IACF,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAE3E,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CACpC,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,OAAO,EACP,UAAU,EACV,MAAM,EACN,oBAAoB,CACrB,CAAC;IACF,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,EAAE,GACxD,UAAU,CAAC,SAAS,CAAC,CAAC;IAExB,OAAO;QACL,cAAc,EAAE,YAAY;QAC5B,gBAAgB,EAAE,cAAc;QAChC,gBAAgB,EAAE,cAAc;QAChC,kBAAkB,EAAE,gBAAgB;KACrC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+declare const GUI_EDITORS: readonly ["vscode", "vscodium", "windsurf", "cursor", "zed", "antigravity"];
+declare const TERMINAL_EDITORS: readonly ["vim", "neovim", "emacs", "hx"];
+declare const EDITORS: readonly ["vscode", "vscodium", "windsurf", "cursor", "zed", "antigravity", "vim", "neovim", "emacs", "hx"];
+export declare const DEFAULT_GUI_EDITOR: GuiEditorType;
+export type GuiEditorType = (typeof GUI_EDITORS)[number];
+export type TerminalEditorType = (typeof TERMINAL_EDITORS)[number];
+export type EditorType = (typeof EDITORS)[number];
+export declare function isGuiEditor(editor: EditorType): editor is GuiEditorType;
+export declare function isTerminalEditor(editor: EditorType): editor is TerminalEditorType;
+export declare const EDITOR_DISPLAY_NAMES: Record<EditorType, string>;
+export declare function getEditorDisplayName(editor: EditorType): string;
+interface DiffCommand {
+    command: string;
+    args: string[];
+}
+export declare function checkHasEditorType(editor: EditorType): boolean;
+export declare function getEditorCommand(editor: EditorType): string;
+export declare function allowEditorTypeInSandbox(editor: EditorType): boolean;
+/**
+ * Check if the editor is valid and can be used.
+ * Returns false if preferred editor is not set / invalid / not available / not allowed in sandbox.
+ */
+export declare function isEditorAvailable(editor: string | undefined): boolean;
+/**
+ * Get the diff command for a specific editor.
+ */
+export declare function getDiffCommand(oldPath: string, newPath: string, editor: EditorType): DiffCommand | null;
+/**
+ * Opens a diff tool to compare two files.
+ * Terminal-based editors by default blocks parent process until the editor exits.
+ * GUI-based editors require args such as "--wait" to block parent process.
+ */
+export declare function openDiff(oldPath: string, newPath: string, editor: EditorType, onEditorClose?: () => void): Promise<void>;
+export {};

package/dist/src/utils/editor.js

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { execSync, spawn, spawnSync } from 'node:child_process';
+const debugLogger = {
+    error: (..._args) => { },
+};
+const GUI_EDITORS = [
+    'vscode',
+    'vscodium',
+    'windsurf',
+    'cursor',
+    'zed',
+    'antigravity',
+];
+const TERMINAL_EDITORS = ['vim', 'neovim', 'emacs', 'hx'];
+const EDITORS = [...GUI_EDITORS, ...TERMINAL_EDITORS];
+const GUI_EDITORS_SET = new Set(GUI_EDITORS);
+const TERMINAL_EDITORS_SET = new Set(TERMINAL_EDITORS);
+const EDITORS_SET = new Set(EDITORS);
+export const DEFAULT_GUI_EDITOR = 'vscode';
+export function isGuiEditor(editor) {
+    return GUI_EDITORS_SET.has(editor);
+}
+export function isTerminalEditor(editor) {
+    return TERMINAL_EDITORS_SET.has(editor);
+}
+export const EDITOR_DISPLAY_NAMES = {
+    vscode: 'VS Code',
+    vscodium: 'VSCodium',
+    windsurf: 'Windsurf',
+    cursor: 'Cursor',
+    vim: 'Vim',
+    neovim: 'Neovim',
+    zed: 'Zed',
+    emacs: 'Emacs',
+    antigravity: 'Antigravity',
+    hx: 'Helix',
+};
+export function getEditorDisplayName(editor) {
+    return EDITOR_DISPLAY_NAMES[editor] || editor;
+}
+function isValidEditorType(editor) {
+    return EDITORS_SET.has(editor);
+}
+function commandExists(cmd) {
+    try {
+        // eslint-disable-next-line sonarjs/os-command -- Project intentionally invokes platform tooling at this trusted boundary; arguments remain explicit and behavior is preserved.
+        execSync(process.platform === 'win32' ? `where.exe ${cmd}` : `command -v ${cmd}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Editor command configurations for different platforms.
+ * Each editor can have multiple possible command names, listed in order of preference.
+ */
+const editorCommands = {
+    vscode: { win32: ['code.cmd'], default: ['code'] },
+    vscodium: { win32: ['codium.cmd'], default: ['codium'] },
+    windsurf: { win32: ['windsurf'], default: ['windsurf'] },
+    cursor: { win32: ['cursor'], default: ['cursor'] },
+    vim: { win32: ['vim'], default: ['vim'] },
+    neovim: { win32: ['nvim'], default: ['nvim'] },
+    zed: { win32: ['zed'], default: ['zed', 'zeditor'] },
+    emacs: { win32: ['emacs.exe'], default: ['emacs'] },
+    antigravity: { win32: ['agy.cmd'], default: ['agy'] },
+    hx: { win32: ['hx'], default: ['hx'] },
+};
+export function checkHasEditorType(editor) {
+    const commandConfig = editorCommands[editor];
+    const commands = process.platform === 'win32' ? commandConfig.win32 : commandConfig.default;
+    return commands.some((cmd) => commandExists(cmd));
+}
+export function getEditorCommand(editor) {
+    const commandConfig = editorCommands[editor];
+    const commands = process.platform === 'win32' ? commandConfig.win32 : commandConfig.default;
+    return (
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional falsy coalescing: commandExists returns boolean, falsy means command not found
+    commands.slice(0, -1).find((cmd) => commandExists(cmd)) ||
+        commands[commands.length - 1]);
+}
+export function allowEditorTypeInSandbox(editor) {
+    const notUsingSandbox = !process.env['SANDBOX'];
+    if (isGuiEditor(editor)) {
+        return notUsingSandbox;
+    }
+    // For terminal-based editors like vim and emacs, allow in sandbox.
+    return true;
+}
+/**
+ * Check if the editor is valid and can be used.
+ * Returns false if preferred editor is not set / invalid / not available / not allowed in sandbox.
+ */
+export function isEditorAvailable(editor) {
+    if (editor && isValidEditorType(editor)) {
+        return checkHasEditorType(editor) && allowEditorTypeInSandbox(editor);
+    }
+    return false;
+}
+/**
+ * Get the diff command for a specific editor.
+ */
+export function getDiffCommand(oldPath, newPath, editor) {
+    if (!isValidEditorType(editor)) {
+        return null;
+    }
+    const command = getEditorCommand(editor);
+    switch (editor) {
+        case 'vscode':
+        case 'vscodium':
+        case 'windsurf':
+        case 'cursor':
+        case 'zed':
+        case 'antigravity':
+            return { command, args: ['--wait', '--diff', oldPath, newPath] };
+        case 'vim':
+        case 'neovim':
+            return {
+                command,
+                args: [
+                    '-d',
+                    // skip viminfo file to avoid E138 errors
+                    '-i',
+                    'NONE',
+                    // make the left window read-only and the right window editable
+                    '-c',
+                    'wincmd h | set readonly | wincmd l',
+                    // set up colors for diffs
+                    '-c',
+                    'highlight DiffAdd cterm=bold ctermbg=22 guibg=#005f00 | highlight DiffChange cterm=bold ctermbg=24 guibg=#005f87 | highlight DiffText ctermbg=21 guibg=#0000af | highlight DiffDelete ctermbg=52 guibg=#5f0000',
+                    // Show helpful messages
+                    '-c',
+                    'set showtabline=2 | set tabline=[Instructions]\\ :wqa(save\\ &\\ quit)\\ \\|\\ i/esc(toggle\\ edit\\ mode)',
+                    '-c',
+                    'wincmd h | setlocal statusline=OLD\\ FILE',
+                    '-c',
+                    'wincmd l | setlocal statusline=%#StatusBold#NEW\\ FILE\\ :wqa(save\\ &\\ quit)\\ \\|\\ i/esc(toggle\\ edit\\ mode)',
+                    // Auto close all windows when one is closed
+                    '-c',
+                    'autocmd BufWritePost * wqa',
+                    oldPath,
+                    newPath,
+                ],
+            };
+        case 'emacs':
+            return {
+                command: 'emacs',
+                args: ['--eval', `(ediff "${oldPath}" "${newPath}")`],
+            };
+        case 'hx':
+            return {
+                command: 'hx',
+                args: ['--vsplit', '--', oldPath, newPath],
+            };
+        default:
+            return null;
+    }
+}
+/**
+ * Opens a diff tool to compare two files.
+ * Terminal-based editors by default blocks parent process until the editor exits.
+ * GUI-based editors require args such as "--wait" to block parent process.
+ */
+export async function openDiff(oldPath, newPath, editor, onEditorClose) {
+    const diffCommand = getDiffCommand(oldPath, newPath, editor);
+    if (!diffCommand) {
+        debugLogger.error('No diff tool available. Install a supported editor.');
+        return undefined;
+    }
+    if (isTerminalEditor(editor)) {
+        try {
+            const result = spawnSync(diffCommand.command, diffCommand.args, {
+                stdio: 'inherit',
+            });
+            if (result.error) {
+                throw result.error;
+            }
+            if (result.status !== 0) {
+                throw new Error(`${editor} exited with code ${result.status}`);
+            }
+        }
+        finally {
+            onEditorClose?.();
+        }
+        return undefined;
+    }
+    await new Promise((resolve, reject) => {
+        const childProcess = spawn(diffCommand.command, diffCommand.args, {
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        childProcess.on('close', (code) => {
+            onEditorClose?.();
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`${editor} exited with code ${code}`));
+            }
+        });
+        childProcess.on('error', (error) => {
+            reject(error);
+        });
+    });
+    return undefined;
+}
+//# sourceMappingURL=editor.js.map

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

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

package/dist/src/utils/ensure-dirs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Ensures that the parent directories for a file path exist, creating them if necessary.
+ * @param filePath - The absolute path to the file
+ */
+export declare function ensureParentDirectoriesExist(filePath: string): Promise<void>;

package/dist/src/utils/ensure-dirs.js

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { promises as fsPromises } from 'fs';
+import * as path from 'path';
+/**
+ * Ensures that the parent directories for a file path exist, creating them if necessary.
+ * @param filePath - The absolute path to the file
+ */
+export async function ensureParentDirectoriesExist(filePath) {
+    const dirName = path.dirname(filePath);
+    await fsPromises.mkdir(dirName, { recursive: true });
+}
+//# sourceMappingURL=ensure-dirs.js.map

package/dist/src/utils/ensure-dirs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-dirs.js","sourceRoot":"","sources":["../../../src/utils/ensure-dirs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,IAAI,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,QAAgB;IAEhB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACvD,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
+export declare function getErrorMessage(error: unknown): string;
+export declare class FatalError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number);
+}
+export declare class FatalAuthenticationError extends FatalError {
+    constructor(message: string);
+}
+export declare class FatalInputError extends FatalError {
+    constructor(message: string);
+}
+export declare class FatalSandboxError extends FatalError {
+    constructor(message: string);
+}
+export declare class FatalConfigError extends FatalError {
+    constructor(message: string);
+}
+export declare class FatalTurnLimitedError extends FatalError {
+    constructor(message: string);
+}
+export declare class FatalToolExecutionError extends FatalError {
+    constructor(message: string);
+}
+export declare class FatalCancellationError extends FatalError {
+    constructor(message: string);
+}
+export declare class ForbiddenError extends Error {
+}
+export declare class UnauthorizedError extends Error {
+}
+export declare class BadRequestError extends Error {
+}
+export declare class NotYetImplemented extends Error {
+    constructor(message?: string);
+}
+export declare function toFriendlyError(error: unknown): unknown;
+/**
+ * Checks if an error is a 401 authentication error.
+ * Uses structured error properties from MCP SDK errors first.
+ *
+ * @plan PLAN-20250219-GMERGE021.R3.P03
+ * @requirement REQ-GMERGE021-R3-002
+ */
+export declare function isAuthenticationError(error: unknown): boolean;
+/**
+ * Checks if an error is a 404 Not Found error with proper detection.
+ * Uses typed error checking first, falls back to anchored pattern matching.
+ * Avoids false positives from strings like "port 40404" or "code 4040".
+ *
+ * @param error - The error to check
+ * @returns True if the error is a 404 error
+ */
+export declare function is404Error(error: unknown): boolean;