@blackbox_ai/blackbox-cli-core 0.0.4

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

@@ -0,0 +1,363 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import mock from 'mock-fs';
+import * as path from 'node:path';
+import { WorkspaceContext } from './workspaceContext.js';
+import { readPathFromWorkspace } from './pathReader.js';
+import { StandardFileSystemService } from '../services/fileSystemService.js';
+// --- Helper for creating a mock Config object ---
+// We use the actual implementations of WorkspaceContext and FileSystemService
+// to test the integration against mock-fs.
+const createMockConfig = (cwd, otherDirs = [], mockFileService) => {
+    const workspace = new WorkspaceContext(cwd, otherDirs);
+    const fileSystemService = new StandardFileSystemService();
+    return {
+        getWorkspaceContext: () => workspace,
+        // TargetDir is used by processSingleFileContent to generate relative paths in errors/output
+        getTargetDir: () => cwd,
+        getFileSystemService: () => fileSystemService,
+        getFileService: () => mockFileService,
+    };
+};
+describe('readPathFromWorkspace', () => {
+    const CWD = path.resolve('/test/cwd');
+    const OTHER_DIR = path.resolve('/test/other');
+    const OUTSIDE_DIR = path.resolve('/test/outside');
+    afterEach(() => {
+        mock.restore();
+        vi.resetAllMocks();
+    });
+    it('should read a text file from the CWD', async () => {
+        mock({
+            [CWD]: {
+                'file.txt': 'hello from cwd',
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [], mockFileService);
+        const result = await readPathFromWorkspace('file.txt', config);
+        // Expect [string] for text content
+        expect(result).toEqual(['hello from cwd']);
+        expect(mockFileService.filterFiles).toHaveBeenCalled();
+    });
+    it('should read a file from a secondary workspace directory', async () => {
+        mock({
+            [CWD]: {},
+            [OTHER_DIR]: {
+                'file.txt': 'hello from other dir',
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [OTHER_DIR], mockFileService);
+        const result = await readPathFromWorkspace('file.txt', config);
+        expect(result).toEqual(['hello from other dir']);
+    });
+    it('should prioritize CWD when file exists in both CWD and secondary dir', async () => {
+        mock({
+            [CWD]: {
+                'file.txt': 'hello from cwd',
+            },
+            [OTHER_DIR]: {
+                'file.txt': 'hello from other dir',
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [OTHER_DIR], mockFileService);
+        const result = await readPathFromWorkspace('file.txt', config);
+        expect(result).toEqual(['hello from cwd']);
+    });
+    it('should read an image file and return it as inlineData (Part object)', async () => {
+        // Use a real PNG header for robustness
+        const imageData = Buffer.from([
+            0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+        ]);
+        mock({
+            [CWD]: {
+                'image.png': imageData,
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [], mockFileService);
+        const result = await readPathFromWorkspace('image.png', config);
+        // Expect [Part] for image content
+        expect(result).toEqual([
+            {
+                inlineData: {
+                    mimeType: 'image/png',
+                    data: imageData.toString('base64'),
+                },
+            },
+        ]);
+    });
+    it('should read a generic binary file and return an info string', async () => {
+        // Data that is clearly binary (null bytes)
+        const binaryData = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+        mock({
+            [CWD]: {
+                'data.bin': binaryData,
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [], mockFileService);
+        const result = await readPathFromWorkspace('data.bin', config);
+        // Expect [string] containing the skip message from fileUtils
+        expect(result).toEqual(['Cannot display content of binary file: data.bin']);
+    });
+    it('should read a file from an absolute path if within workspace', async () => {
+        const absPath = path.join(OTHER_DIR, 'abs.txt');
+        mock({
+            [CWD]: {},
+            [OTHER_DIR]: {
+                'abs.txt': 'absolute content',
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [OTHER_DIR], mockFileService);
+        const result = await readPathFromWorkspace(absPath, config);
+        expect(result).toEqual(['absolute content']);
+    });
+    describe('Directory Expansion', () => {
+        it('should expand a directory and read the content of its files', async () => {
+            mock({
+                [CWD]: {
+                    'my-dir': {
+                        'file1.txt': 'content of file 1',
+                        'file2.md': 'content of file 2',
+                    },
+                },
+            });
+            const mockFileService = {
+                filterFiles: vi.fn((files) => files),
+            };
+            const config = createMockConfig(CWD, [], mockFileService);
+            const result = await readPathFromWorkspace('my-dir', config);
+            // Convert to a single string for easier, order-independent checking
+            const resultText = result
+                .map((p) => {
+                if (typeof p === 'string')
+                    return p;
+                if (typeof p === 'object' && p && 'text' in p)
+                    return p.text;
+                // This part is important for handling binary/image data which isn't just text
+                if (typeof p === 'object' && p && 'inlineData' in p)
+                    return '';
+                return p;
+            })
+                .join('');
+            expect(resultText).toContain('--- Start of content for directory: my-dir ---');
+            expect(resultText).toContain('--- file1.txt ---');
+            expect(resultText).toContain('content of file 1');
+            expect(resultText).toContain('--- file2.md ---');
+            expect(resultText).toContain('content of file 2');
+            expect(resultText).toContain('--- End of content for directory: my-dir ---');
+        });
+        it('should recursively expand a directory and read all nested files', async () => {
+            mock({
+                [CWD]: {
+                    'my-dir': {
+                        'file1.txt': 'content of file 1',
+                        'sub-dir': {
+                            'nested.txt': 'nested content',
+                        },
+                    },
+                },
+            });
+            const mockFileService = {
+                filterFiles: vi.fn((files) => files),
+            };
+            const config = createMockConfig(CWD, [], mockFileService);
+            const result = await readPathFromWorkspace('my-dir', config);
+            const resultText = result
+                .map((p) => {
+                if (typeof p === 'string')
+                    return p;
+                if (typeof p === 'object' && p && 'text' in p)
+                    return p.text;
+                return '';
+            })
+                .join('');
+            expect(resultText).toContain('content of file 1');
+            expect(resultText).toContain('nested content');
+            expect(resultText).toContain(`--- ${path.join('sub-dir', 'nested.txt')} ---`);
+        });
+        it('should handle mixed content and include files from subdirectories', async () => {
+            const imageData = Buffer.from([
+                0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+            ]);
+            mock({
+                [CWD]: {
+                    'mixed-dir': {
+                        'info.txt': 'some text',
+                        'photo.png': imageData,
+                        'sub-dir': {
+                            'nested.txt': 'this should be included',
+                        },
+                        'empty-sub-dir': {},
+                    },
+                },
+            });
+            const mockFileService = {
+                filterFiles: vi.fn((files) => files),
+            };
+            const config = createMockConfig(CWD, [], mockFileService);
+            const result = await readPathFromWorkspace('mixed-dir', config);
+            // Check for the text part
+            const textContent = result
+                .map((p) => {
+                if (typeof p === 'string')
+                    return p;
+                if (typeof p === 'object' && p && 'text' in p)
+                    return p.text;
+                return ''; // Ignore non-text parts for this assertion
+            })
+                .join('');
+            expect(textContent).toContain('some text');
+            expect(textContent).toContain('this should be included');
+            // Check for the image part
+            const imagePart = result.find((p) => typeof p === 'object' && 'inlineData' in p);
+            expect(imagePart).toEqual({
+                inlineData: {
+                    mimeType: 'image/png',
+                    data: imageData.toString('base64'),
+                },
+            });
+        });
+        it('should handle an empty directory', async () => {
+            mock({
+                [CWD]: {
+                    'empty-dir': {},
+                },
+            });
+            const mockFileService = {
+                filterFiles: vi.fn((files) => files),
+            };
+            const config = createMockConfig(CWD, [], mockFileService);
+            const result = await readPathFromWorkspace('empty-dir', config);
+            expect(result).toEqual([
+                { text: '--- Start of content for directory: empty-dir ---\n' },
+                { text: '--- End of content for directory: empty-dir ---' },
+            ]);
+        });
+    });
+    describe('File Ignoring', () => {
+        it('should return an empty array for an ignored file', async () => {
+            mock({
+                [CWD]: {
+                    'ignored.txt': 'ignored content',
+                },
+            });
+            const mockFileService = {
+                filterFiles: vi.fn(() => []), // Simulate the file being filtered out
+            };
+            const config = createMockConfig(CWD, [], mockFileService);
+            const result = await readPathFromWorkspace('ignored.txt', config);
+            expect(result).toEqual([]);
+            expect(mockFileService.filterFiles).toHaveBeenCalledWith(['ignored.txt'], {
+                respectGitIgnore: true,
+                respectGeminiIgnore: true,
+            });
+        });
+        it('should not read ignored files when expanding a directory', async () => {
+            mock({
+                [CWD]: {
+                    'my-dir': {
+                        'not-ignored.txt': 'visible',
+                        'ignored.log': 'invisible',
+                    },
+                },
+            });
+            const mockFileService = {
+                filterFiles: vi.fn((files) => files.filter((f) => !f.endsWith('ignored.log'))),
+            };
+            const config = createMockConfig(CWD, [], mockFileService);
+            const result = await readPathFromWorkspace('my-dir', config);
+            const resultText = result
+                .map((p) => {
+                if (typeof p === 'string')
+                    return p;
+                if (typeof p === 'object' && p && 'text' in p)
+                    return p.text;
+                return '';
+            })
+                .join('');
+            expect(resultText).toContain('visible');
+            expect(resultText).not.toContain('invisible');
+            expect(mockFileService.filterFiles).toHaveBeenCalled();
+        });
+    });
+    it('should throw an error for an absolute path outside the workspace', async () => {
+        const absPath = path.join(OUTSIDE_DIR, 'secret.txt');
+        mock({
+            [CWD]: {},
+            [OUTSIDE_DIR]: {
+                'secret.txt': 'secrets',
+            },
+        });
+        // OUTSIDE_DIR is not added to the config's workspace
+        const config = createMockConfig(CWD);
+        await expect(readPathFromWorkspace(absPath, config)).rejects.toThrow(`Absolute path is outside of the allowed workspace: ${absPath}`);
+    });
+    it('should throw an error if a relative path is not found anywhere', async () => {
+        mock({
+            [CWD]: {},
+            [OTHER_DIR]: {},
+        });
+        const config = createMockConfig(CWD, [OTHER_DIR]);
+        await expect(readPathFromWorkspace('not-found.txt', config)).rejects.toThrow('Path not found in workspace: not-found.txt');
+    });
+    // mock-fs permission simulation is unreliable on Windows.
+    it.skipIf(process.platform === 'win32')('should return an error string if reading a file with no permissions', async () => {
+        mock({
+            [CWD]: {
+                'unreadable.txt': mock.file({
+                    content: 'you cannot read me',
+                    mode: 0o222, // Write-only
+                }),
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [], mockFileService);
+        // processSingleFileContent catches the error and returns an error string.
+        const result = await readPathFromWorkspace('unreadable.txt', config);
+        const textResult = result[0];
+        // processSingleFileContent formats errors using the relative path from the target dir (CWD).
+        expect(textResult).toContain('Error reading file unreadable.txt');
+        expect(textResult).toMatch(/(EACCES|permission denied)/i);
+    });
+    it('should return an error string for files exceeding the size limit', async () => {
+        // Mock a file slightly larger than the 20MB limit defined in fileUtils.ts
+        const largeContent = 'a'.repeat(21 * 1024 * 1024); // 21MB
+        mock({
+            [CWD]: {
+                'large.txt': largeContent,
+            },
+        });
+        const mockFileService = {
+            filterFiles: vi.fn((files) => files),
+        };
+        const config = createMockConfig(CWD, [], mockFileService);
+        const result = await readPathFromWorkspace('large.txt', config);
+        const textResult = result[0];
+        // The error message comes directly from processSingleFileContent
+        expect(textResult).toBe('File size exceeds the 20MB limit.');
+    });
+});
+//# sourceMappingURL=pathReader.test.js.map

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

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

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

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare const BLACKBOX_DIR = ".blackboxcli";
+export declare const GOOGLE_ACCOUNTS_FILENAME = "google_accounts.json";
+/**
+ * Special characters that need to be escaped in file paths for shell compatibility.
+ * Includes: spaces, parentheses, brackets, braces, semicolons, ampersands, pipes,
+ * asterisks, question marks, dollar signs, backticks, quotes, hash, and other shell metacharacters.
+ */
+export declare const SHELL_SPECIAL_CHARS: RegExp;
+/**
+ * Replaces the home directory with a tilde.
+ * @param path - The path to tildeify.
+ * @returns The tildeified path.
+ */
+export declare function tildeifyPath(path: string): string;
+/**
+ * Shortens a path string if it exceeds maxLen, prioritizing the start and end segments.
+ * Example: /path/to/a/very/long/file.txt -> /path/.../long/file.txt
+ */
+export declare function shortenPath(filePath: string, maxLen?: number): string;
+/**
+ * Calculates the relative path from a root directory to a target path.
+ * Ensures both paths are resolved before calculating.
+ * Returns '.' if the target path is the same as the root directory.
+ *
+ * @param targetPath The absolute or relative path to make relative.
+ * @param rootDirectory The absolute path of the directory to make the target path relative to.
+ * @returns The relative path from rootDirectory to targetPath.
+ */
+export declare function makeRelative(targetPath: string, rootDirectory: string): string;
+/**
+ * Escapes special characters in a file path like macOS terminal does.
+ * Escapes: spaces, parentheses, brackets, braces, semicolons, ampersands, pipes,
+ * asterisks, question marks, dollar signs, backticks, quotes, hash, and other shell metacharacters.
+ */
+export declare function escapePath(filePath: string): string;
+/**
+ * Unescapes special characters in a file path.
+ * Removes backslash escaping from shell metacharacters.
+ */
+export declare function unescapePath(filePath: string): string;
+/**
+ * Generates a unique hash for a project based on its root path.
+ * @param projectRoot The absolute path to the project's root directory.
+ * @returns A SHA256 hash of the project root path.
+ */
+export declare function getProjectHash(projectRoot: string): string;
+/**
+ * Checks if a path is a subpath of another path.
+ * @param parentPath The parent path.
+ * @param childPath The child path.
+ * @returns True if childPath is a subpath of parentPath, false otherwise.
+ */
+export declare function isSubpath(parentPath: string, childPath: string): boolean;

package/dist/src/utils/paths.js

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import path from 'node:path';
+import os from 'node:os';
+import * as crypto from 'node:crypto';
+export const BLACKBOX_DIR = '.blackboxcli';
+export const GOOGLE_ACCOUNTS_FILENAME = 'google_accounts.json';
+/**
+ * Special characters that need to be escaped in file paths for shell compatibility.
+ * Includes: spaces, parentheses, brackets, braces, semicolons, ampersands, pipes,
+ * asterisks, question marks, dollar signs, backticks, quotes, hash, and other shell metacharacters.
+ */
+export const SHELL_SPECIAL_CHARS = /[ \t()[\]{};|*?$`'"#&<>!~]/;
+/**
+ * Replaces the home directory with a tilde.
+ * @param path - The path to tildeify.
+ * @returns The tildeified path.
+ */
+export function tildeifyPath(path) {
+    const homeDir = os.homedir();
+    if (path.startsWith(homeDir)) {
+        return path.replace(homeDir, '~');
+    }
+    return path;
+}
+/**
+ * Shortens a path string if it exceeds maxLen, prioritizing the start and end segments.
+ * Example: /path/to/a/very/long/file.txt -> /path/.../long/file.txt
+ */
+export function shortenPath(filePath, maxLen = 35) {
+    if (filePath.length <= maxLen) {
+        return filePath;
+    }
+    const parsedPath = path.parse(filePath);
+    const root = parsedPath.root;
+    const separator = path.sep;
+    // Get segments of the path *after* the root
+    const relativePath = filePath.substring(root.length);
+    const segments = relativePath.split(separator).filter((s) => s !== ''); // Filter out empty segments
+    // Handle cases with no segments after root (e.g., "/", "C:\") or only one segment
+    if (segments.length <= 1) {
+        // Fall back to simple start/end truncation for very short paths or single segments
+        const keepLen = Math.floor((maxLen - 3) / 2);
+        // Ensure keepLen is not negative if maxLen is very small
+        if (keepLen <= 0) {
+            return filePath.substring(0, maxLen - 3) + '...';
+        }
+        const start = filePath.substring(0, keepLen);
+        const end = filePath.substring(filePath.length - keepLen);
+        return `${start}...${end}`;
+    }
+    const firstDir = segments[0];
+    const lastSegment = segments[segments.length - 1];
+    const startComponent = root + firstDir;
+    const endPartSegments = [];
+    // Base length: separator + "..." + lastDir
+    let currentLength = separator.length + lastSegment.length;
+    // Iterate backwards through segments (excluding the first one)
+    for (let i = segments.length - 2; i >= 0; i--) {
+        const segment = segments[i];
+        // Length needed if we add this segment: current + separator + segment
+        const lengthWithSegment = currentLength + separator.length + segment.length;
+        if (lengthWithSegment <= maxLen) {
+            endPartSegments.unshift(segment); // Add to the beginning of the end part
+            currentLength = lengthWithSegment;
+        }
+        else {
+            break;
+        }
+    }
+    let result = endPartSegments.join(separator) + separator + lastSegment;
+    if (currentLength > maxLen) {
+        return result;
+    }
+    // Construct the final path
+    result = startComponent + separator + result;
+    // As a final check, if the result is somehow still too long
+    // truncate the result string from the beginning, prefixing with "...".
+    if (result.length > maxLen) {
+        return '...' + result.substring(result.length - maxLen - 3);
+    }
+    return result;
+}
+/**
+ * Calculates the relative path from a root directory to a target path.
+ * Ensures both paths are resolved before calculating.
+ * Returns '.' if the target path is the same as the root directory.
+ *
+ * @param targetPath The absolute or relative path to make relative.
+ * @param rootDirectory The absolute path of the directory to make the target path relative to.
+ * @returns The relative path from rootDirectory to targetPath.
+ */
+export function makeRelative(targetPath, rootDirectory) {
+    const resolvedTargetPath = path.resolve(targetPath);
+    const resolvedRootDirectory = path.resolve(rootDirectory);
+    const relativePath = path.relative(resolvedRootDirectory, resolvedTargetPath);
+    // If the paths are the same, path.relative returns '', return '.' instead
+    return relativePath || '.';
+}
+/**
+ * Escapes special characters in a file path like macOS terminal does.
+ * Escapes: spaces, parentheses, brackets, braces, semicolons, ampersands, pipes,
+ * asterisks, question marks, dollar signs, backticks, quotes, hash, and other shell metacharacters.
+ */
+export function escapePath(filePath) {
+    let result = '';
+    for (let i = 0; i < filePath.length; i++) {
+        const char = filePath[i];
+        // Count consecutive backslashes before this character
+        let backslashCount = 0;
+        for (let j = i - 1; j >= 0 && filePath[j] === '\\'; j--) {
+            backslashCount++;
+        }
+        // Character is already escaped if there's an odd number of backslashes before it
+        const isAlreadyEscaped = backslashCount % 2 === 1;
+        // Only escape if not already escaped
+        if (!isAlreadyEscaped && SHELL_SPECIAL_CHARS.test(char)) {
+            result += '\\' + char;
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+/**
+ * Unescapes special characters in a file path.
+ * Removes backslash escaping from shell metacharacters.
+ */
+export function unescapePath(filePath) {
+    return filePath.replace(new RegExp(`\\\\([${SHELL_SPECIAL_CHARS.source.slice(1, -1)}])`, 'g'), '$1');
+}
+/**
+ * Generates a unique hash for a project based on its root path.
+ * @param projectRoot The absolute path to the project's root directory.
+ * @returns A SHA256 hash of the project root path.
+ */
+export function getProjectHash(projectRoot) {
+    return crypto.createHash('sha256').update(projectRoot).digest('hex');
+}
+/**
+ * Checks if a path is a subpath of another path.
+ * @param parentPath The parent path.
+ * @param childPath The child path.
+ * @returns True if childPath is a subpath of parentPath, false otherwise.
+ */
+export function isSubpath(parentPath, childPath) {
+    const isWindows = os.platform() === 'win32';
+    const pathModule = isWindows ? path.win32 : path;
+    // On Windows, path.relative is case-insensitive. On POSIX, it's case-sensitive.
+    const relative = pathModule.relative(parentPath, childPath);
+    return (!relative.startsWith(`..${pathModule.sep}`) &&
+        relative !== '..' &&
+        !pathModule.isAbsolute(relative));
+}
+//# sourceMappingURL=paths.js.map

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

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

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

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