@vibe-agent-toolkit/utils 0.1.0-rc.7

package/README.md

@@ -0,0 +1,34 @@
+# @vibe-agent-toolkit/utils
+
+Core shared utilities with no dependencies on other packages.
+
+## Philosophy
+
+This package provides utilities that are needed by multiple packages in the toolkit. Utilities are **added as real needs arise**, not speculatively.
+
+If you need a utility function and multiple packages would benefit from it, add it here. Otherwise, keep it local to the package that needs it.
+
+## Installation
+
+```bash
+bun add @vibe-agent-toolkit/utils
+```
+
+## Usage
+
+```typescript
+import { /* utilities will be added here */ } from '@vibe-agent-toolkit/utils';
+```
+
+## Current Utilities
+
+Currently minimal - utilities will be added as needed by other packages.
+
+Future additions may include:
+- Schema validation utilities (Zod helpers, JSON Schema conversion)
+- Cross-platform helpers (process spawning, file operations)
+- Common type guards and assertions
+
+## License
+
+MIT

package/dist/file-crawler.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Options for directory crawling
+ */
+export interface CrawlOptions {
+    /** Base directory to start crawl */
+    baseDir: string;
+    /** Include patterns (glob) - default: ['**\/*'] */
+    include?: string[];
+    /** Exclude patterns (glob) - default: ['**\/node_modules/**', '**\/.git/**'] */
+    exclude?: string[];
+    /** Follow symbolic links (default: false) */
+    followSymlinks?: boolean;
+    /** Return absolute paths in results (default: true) */
+    absolute?: boolean;
+    /** Only return files (not directories) - default: true */
+    filesOnly?: boolean;
+    /** Respect .gitignore files (default: true) */
+    respectGitignore?: boolean;
+}
+/**
+ * Crawl a directory tree and return matching files (async)
+ *
+ * Uses picomatch for glob pattern matching (same as Vitest)
+ * Cross-platform compatible
+ *
+ * @param options - Crawl options
+ * @returns Promise resolving to array of matching file paths
+ *
+ * @example
+ * const files = await crawlDirectory({
+ *   baseDir: '/project',
+ *   include: ['**\/*.md'],
+ *   exclude: ['**\/node_modules/**'],
+ * });
+ */
+export declare function crawlDirectory(options: CrawlOptions): Promise<string[]>;
+/**
+ * Crawl a directory tree and return matching files (synchronous)
+ *
+ * Uses picomatch for glob pattern matching (same as Vitest)
+ * Cross-platform compatible
+ *
+ * @param options - Crawl options
+ * @returns Array of matching file paths
+ *
+ * @example
+ * const files = crawlDirectorySync({
+ *   baseDir: '/project',
+ *   include: ['**\/*.md'],
+ *   exclude: ['**\/node_modules/**'],
+ * });
+ */
+export declare function crawlDirectorySync(options: CrawlOptions): string[];
+//# sourceMappingURL=file-crawler.d.ts.map

package/dist/file-crawler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-crawler.d.ts","sourceRoot":"","sources":["../src/file-crawler.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAgKlE"}

package/dist/file-crawler.js

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { findGitRoot, loadGitignoreRules } from './gitignore-checker.js';
+/**
+ * Default exclude patterns that are almost always unwanted
+ */
+const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/coverage/**'];
+/**
+ * Crawl a directory tree and return matching files (async)
+ *
+ * Uses picomatch for glob pattern matching (same as Vitest)
+ * Cross-platform compatible
+ *
+ * @param options - Crawl options
+ * @returns Promise resolving to array of matching file paths
+ *
+ * @example
+ * const files = await crawlDirectory({
+ *   baseDir: '/project',
+ *   include: ['**\/*.md'],
+ *   exclude: ['**\/node_modules/**'],
+ * });
+ */
+export async function crawlDirectory(options) {
+    return crawlDirectorySync(options);
+}
+/**
+ * Crawl a directory tree and return matching files (synchronous)
+ *
+ * Uses picomatch for glob pattern matching (same as Vitest)
+ * Cross-platform compatible
+ *
+ * @param options - Crawl options
+ * @returns Array of matching file paths
+ *
+ * @example
+ * const files = crawlDirectorySync({
+ *   baseDir: '/project',
+ *   include: ['**\/*.md'],
+ *   exclude: ['**\/node_modules/**'],
+ * });
+ */
+export function crawlDirectorySync(options) {
+    const { baseDir, include = ['**/*'], exclude = DEFAULT_EXCLUDE, followSymlinks = false, absolute = true, filesOnly = true, respectGitignore = true, } = options;
+    // Resolve base directory to absolute path
+    const resolvedBaseDir = path.resolve(baseDir);
+    // Ensure base directory exists
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- baseDir is from controlled config, not user input
+    if (!fs.existsSync(resolvedBaseDir)) {
+        throw new Error(`Base directory does not exist: ${resolvedBaseDir}`);
+    }
+    // Ensure base directory is actually a directory
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved path validated above
+    const baseStat = fs.statSync(resolvedBaseDir);
+    if (!baseStat.isDirectory()) {
+        throw new Error(`Base path is not a directory: ${resolvedBaseDir}`);
+    }
+    // Load gitignore rules if requested
+    let gitignoreChecker = null;
+    let gitRoot = null;
+    if (respectGitignore) {
+        gitRoot = findGitRoot(resolvedBaseDir);
+        if (gitRoot) {
+            gitignoreChecker = loadGitignoreRules(gitRoot, resolvedBaseDir);
+        }
+    }
+    // Compile glob patterns using picomatch
+    const isIncluded = picomatch(include);
+    const isExcluded = exclude.length > 0 ? picomatch(exclude) : () => false;
+    const results = [];
+    /**
+     * Check if a path should be excluded based on patterns and gitignore
+     */
+    function shouldExclude(normalizedPath, fullPath) {
+        // Check explicit exclude patterns
+        if (isExcluded(normalizedPath) || isExcluded(normalizedPath + '/')) {
+            return true;
+        }
+        // Check gitignore rules if enabled
+        if (gitignoreChecker && gitRoot) {
+            // Get path relative to git root for gitignore checking
+            const relativeToGitRoot = path.relative(gitRoot, fullPath);
+            const normalizedGitPath = relativeToGitRoot.split(path.sep).join('/');
+            if (gitignoreChecker.ignores(normalizedGitPath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Add a path to results if it matches include patterns
+     */
+    function addToResults(normalizedPath, fullPath, relativePath) {
+        if (isIncluded(normalizedPath)) {
+            results.push(absolute ? fullPath : relativePath);
+        }
+    }
+    /**
+     * Process a symbolic link entry
+     */
+    function processSymlink(fullPath, normalizedPath, relativePath) {
+        if (!followSymlinks) {
+            return;
+        }
+        // Resolve symlink and check if it's a directory or file
+        let targetStat;
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- path constructed from validated baseDir + entries
+            targetStat = fs.statSync(fullPath);
+        }
+        catch {
+            // Skip broken symlinks
+            return;
+        }
+        if (targetStat.isDirectory()) {
+            walkDirectory(fullPath);
+        }
+        else if (targetStat.isFile()) {
+            addToResults(normalizedPath, fullPath, relativePath);
+        }
+    }
+    /**
+     * Process a directory entry
+     */
+    function processDirectory(fullPath, normalizedPath, relativePath) {
+        // Recurse into subdirectory
+        walkDirectory(fullPath);
+        // Add directory to results if not filesOnly
+        if (!filesOnly) {
+            addToResults(normalizedPath, fullPath, relativePath);
+        }
+    }
+    /**
+     * Process a file entry
+     */
+    function processFile(normalizedPath, fullPath, relativePath) {
+        addToResults(normalizedPath, fullPath, relativePath);
+    }
+    /**
+     * Recursively walk directory tree
+     */
+    function walkDirectory(currentDir) {
+        let entries;
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- path constructed from validated baseDir, recursively walking
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            // Skip directories we don't have permission to read
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            const relativePath = path.relative(resolvedBaseDir, fullPath);
+            const normalizedPath = relativePath.split(path.sep).join('/');
+            // Skip excluded paths
+            if (shouldExclude(normalizedPath, fullPath)) {
+                continue;
+            }
+            // Dispatch to appropriate handler based on entry type
+            if (entry.isSymbolicLink()) {
+                processSymlink(fullPath, normalizedPath, relativePath);
+            }
+            else if (entry.isDirectory()) {
+                processDirectory(fullPath, normalizedPath, relativePath);
+            }
+            else if (entry.isFile()) {
+                processFile(normalizedPath, fullPath, relativePath);
+            }
+        }
+    }
+    // Start recursive walk from base directory
+    walkDirectory(resolvedBaseDir);
+    return results;
+}
+//# sourceMappingURL=file-crawler.js.map

package/dist/file-crawler.js.map

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

package/dist/fs-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Filesystem utilities
+ */
+/**
+ * Recursively copy a directory
+ *
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ *
+ * @example
+ * await copyDirectory('/source/dir', '/dest/dir');
+ */
+export declare function copyDirectory(src: string, dest: string): Promise<void>;
+//# sourceMappingURL=fs-utils.d.ts.map

package/dist/fs-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-utils.d.ts","sourceRoot":"","sources":["../src/fs-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E"}

package/dist/fs-utils.js

@@ -0,0 +1,31 @@
+/**
+ * Filesystem utilities
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Recursively copy a directory
+ *
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ *
+ * @example
+ * await copyDirectory('/source/dir', '/dest/dir');
+ */
+export async function copyDirectory(src, dest) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Paths from validated sources
+    await fs.mkdir(dest, { recursive: true });
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Paths from validated sources
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectory(srcPath, destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+//# sourceMappingURL=fs-utils.js.map

package/dist/fs-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../src/fs-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,IAAY;IAC3D,mGAAmG;IACnG,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,mGAAmG;IACnG,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAE7C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/git-utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Check if a file path is ignored by git
+ *
+ * Uses git check-ignore which respects .gitignore, .git/info/exclude, and global gitignore
+ *
+ * @param filePath - Absolute or relative path to check
+ * @param cwd - Working directory (defaults to process.cwd())
+ * @returns true if file is gitignored, false otherwise
+ */
+export declare function isGitIgnored(filePath: string, cwd?: string): boolean;
+//# sourceMappingURL=git-utils.d.ts.map

package/dist/git-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../src/git-utils.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,OAAO,CAkBnF"}

package/dist/git-utils.js

@@ -0,0 +1,30 @@
+import { spawnSync } from 'node:child_process';
+import which from 'which';
+/**
+ * Check if a file path is ignored by git
+ *
+ * Uses git check-ignore which respects .gitignore, .git/info/exclude, and global gitignore
+ *
+ * @param filePath - Absolute or relative path to check
+ * @param cwd - Working directory (defaults to process.cwd())
+ * @returns true if file is gitignored, false otherwise
+ */
+export function isGitIgnored(filePath, cwd = process.cwd()) {
+    try {
+        // Resolve git path using which for security (avoids PATH manipulation)
+        const gitPath = which.sync('git');
+        // git check-ignore returns exit code 0 if file is ignored, 1 if not
+        const result = spawnSync(gitPath, ['check-ignore', '-q', filePath], {
+            cwd,
+            encoding: 'utf-8',
+            stdio: 'pipe',
+            shell: false, // No shell interpreter for security
+        });
+        return result.status === 0;
+    }
+    catch {
+        // If git is not available or other error, assume not ignored
+        return false;
+    }
+}
+//# sourceMappingURL=git-utils.js.map

package/dist/git-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.js","sourceRoot":"","sources":["../src/git-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACxE,IAAI,CAAC;QACH,uEAAuE;QACvE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAElC,oEAAoE;QACpE,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,cAAc,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE;YAClE,GAAG;YACH,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,MAAM;YACb,KAAK,EAAE,KAAK,EAAE,oCAAoC;SACnD,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;QAC7D,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/gitignore-checker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Utilities for checking if files are gitignored.
+ * Used by file-crawler and link validation.
+ */
+import { type Ignore } from 'ignore';
+/**
+ * Find the git repository root by walking up from the given directory.
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Path to git root, or null if not in a git repository
+ */
+export declare function findGitRoot(startDir: string): string | null;
+/**
+ * Load and parse .gitignore files from git root to baseDir.
+ * Returns an ignore instance configured with all applicable .gitignore rules.
+ *
+ * @param gitRoot - Git repository root directory
+ * @param baseDir - Base directory being checked (optional, defaults to gitRoot)
+ * @returns Configured ignore instance, or null if no gitignore files found
+ */
+export declare function loadGitignoreRules(gitRoot: string, baseDir?: string): Ignore | null;
+/**
+ * Check if a file path is ignored by git.
+ *
+ * @param filePath - Absolute path to check
+ * @param gitRoot - Git repository root (optional, will auto-detect if not provided)
+ * @returns True if file is gitignored, false otherwise
+ */
+export declare function isGitignored(filePath: string, gitRoot?: string): boolean;
+//# sourceMappingURL=gitignore-checker.d.ts.map

package/dist/gitignore-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore-checker.d.ts","sourceRoot":"","sources":["../src/gitignore-checker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAe,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqCnF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAsBxE"}

package/dist/gitignore-checker.js

@@ -0,0 +1,95 @@
+/**
+ * Utilities for checking if files are gitignored.
+ * Used by file-crawler and link validation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import ignore from 'ignore';
+/**
+ * Find the git repository root by walking up from the given directory.
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Path to git root, or null if not in a git repository
+ */
+export function findGitRoot(startDir) {
+    let currentDir = path.resolve(startDir);
+    const root = path.parse(currentDir).root;
+    while (currentDir !== root) {
+        const gitDir = path.join(currentDir, '.git');
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- walking up from validated startDir
+        if (fs.existsSync(gitDir)) {
+            return currentDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return null;
+}
+/**
+ * Load and parse .gitignore files from git root to baseDir.
+ * Returns an ignore instance configured with all applicable .gitignore rules.
+ *
+ * @param gitRoot - Git repository root directory
+ * @param baseDir - Base directory being checked (optional, defaults to gitRoot)
+ * @returns Configured ignore instance, or null if no gitignore files found
+ */
+export function loadGitignoreRules(gitRoot, baseDir) {
+    const ig = ignore();
+    let hasRules = false;
+    // Always ignore .git directory
+    ig.add('.git');
+    hasRules = true;
+    // Collect all directories from gitRoot to baseDir
+    const dirsToCheck = [];
+    let currentDir = path.resolve(baseDir ?? gitRoot);
+    const resolvedGitRoot = path.resolve(gitRoot);
+    while (currentDir.startsWith(resolvedGitRoot)) {
+        dirsToCheck.unshift(currentDir);
+        if (currentDir === resolvedGitRoot) {
+            break;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    // Load .gitignore files from git root down to baseDir
+    for (const dir of dirsToCheck) {
+        const gitignorePath = path.join(dir, '.gitignore');
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from validated gitRoot and baseDir
+        if (fs.existsSync(gitignorePath)) {
+            try {
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated above
+                const content = fs.readFileSync(gitignorePath, 'utf-8');
+                ig.add(content);
+            }
+            catch {
+                // Skip gitignore files we can't read
+            }
+        }
+    }
+    return hasRules ? ig : null;
+}
+/**
+ * Check if a file path is ignored by git.
+ *
+ * @param filePath - Absolute path to check
+ * @param gitRoot - Git repository root (optional, will auto-detect if not provided)
+ * @returns True if file is gitignored, false otherwise
+ */
+export function isGitignored(filePath, gitRoot) {
+    const resolvedPath = path.resolve(filePath);
+    // Find git root if not provided
+    const root = gitRoot ?? findGitRoot(resolvedPath);
+    if (!root) {
+        // Not in a git repository
+        return false;
+    }
+    // Load gitignore rules
+    const ig = loadGitignoreRules(root);
+    if (!ig) {
+        // No gitignore rules
+        return false;
+    }
+    // Get path relative to git root
+    const relativePath = path.relative(root, resolvedPath);
+    const normalizedPath = relativePath.split(path.sep).join('/');
+    return ig.ignores(normalizedPath);
+}
+//# sourceMappingURL=gitignore-checker.js.map

package/dist/gitignore-checker.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @vibe-agent-toolkit/utils
+ * Core shared utilities with no dependencies on other packages
+ *
+ * Utilities are added as needed by other packages, not speculatively.
+ */
+export * from './safe-exec.js';
+export * from './path-utils.js';
+export * from './fs-utils.js';
+export * from './file-crawler.js';
+export * from './gitignore-checker.js';
+export * from './git-utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @vibe-agent-toolkit/utils
+ * Core shared utilities with no dependencies on other packages
+ *
+ * Utilities are added as needed by other packages, not speculatively.
+ */
+// Safe command execution (cross-platform, no shell injection)
+export * from './safe-exec.js';
+// Cross-platform path utilities
+export * from './path-utils.js';
+// Filesystem utilities
+export * from './fs-utils.js';
+// Directory crawling with glob patterns
+export * from './file-crawler.js';
+// Git ignore checking
+export * from './gitignore-checker.js';
+// Git utilities (using git commands directly)
+export * from './git-utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,cAAc,gBAAgB,CAAC;AAE/B,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,uBAAuB;AACvB,cAAc,eAAe,CAAC;AAE9B,wCAAwC;AACxC,cAAc,mBAAmB,CAAC;AAElC,sBAAsB;AACtB,cAAc,wBAAwB,CAAC;AAEvC,8CAA8C;AAC9C,cAAc,gBAAgB,CAAC"}

package/dist/path-utils.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Normalize a path for cross-platform comparison
+ *
+ * - Converts to absolute path (if baseDir provided)
+ * - Normalizes separators (/ vs \)
+ * - Resolves . and ..
+ * - Removes trailing slashes
+ *
+ * @param p - Path to normalize
+ * @param baseDir - Optional base directory for relative path resolution
+ * @returns Normalized absolute path
+ *
+ * @example
+ * normalizePath('./docs/../README.md', '/project')
+ * // Returns: '/project/README.md'
+ */
+export declare function normalizePath(p: string, baseDir?: string): string;
+/**
+ * Check if a path is absolute
+ *
+ * Cross-platform detection of absolute paths:
+ * - Unix: /path/to/file
+ * - Windows: C:\path\to\file or C:/path/to/file
+ *
+ * @param p - Path to check
+ * @returns True if path is absolute
+ *
+ * @example
+ * isAbsolutePath('/path/to/file')  // true
+ * isAbsolutePath('./relative')      // false
+ * isAbsolutePath('C:/Windows')      // true (Windows)
+ */
+export declare function isAbsolutePath(p: string): boolean;
+/**
+ * Convert a relative path to absolute
+ *
+ * If path is already absolute, returns it normalized.
+ * Otherwise resolves relative to baseDir.
+ *
+ * @param p - Path to convert
+ * @param baseDir - Base directory for resolution
+ * @returns Absolute path
+ *
+ * @example
+ * toAbsolutePath('./docs/README.md', '/project')
+ * // Returns: '/project/docs/README.md'
+ *
+ * toAbsolutePath('/absolute/path.md', '/project')
+ * // Returns: '/absolute/path.md'
+ */
+export declare function toAbsolutePath(p: string, baseDir: string): string;
+/**
+ * Get the relative path from one file to another
+ *
+ * Useful for generating relative links between markdown files.
+ *
+ * @param from - Source file path (absolute)
+ * @param to - Target file path (absolute)
+ * @returns Relative path from source to target
+ *
+ * @example
+ * getRelativePath('/project/docs/guide.md', '/project/README.md')
+ * // Returns: '../README.md'
+ *
+ * getRelativePath('/project/README.md', '/project/docs/api.md')
+ * // Returns: 'docs/api.md'
+ */
+export declare function getRelativePath(from: string, to: string): string;
+/**
+ * Convert a path to Unix-style forward slashes
+ *
+ * Useful for glob pattern matching, which expects forward slashes.
+ * On Windows, path.resolve() and path.normalize() return backslashes,
+ * but glob matchers like picomatch expect forward slashes by default.
+ *
+ * @param p - Path to convert
+ * @returns Path with forward slashes
+ *
+ * @example
+ * toUnixPath('C:\\Users\\docs\\README.md')
+ * // Returns: 'C:/Users/docs/README.md'
+ *
+ * toUnixPath('/project/docs/README.md')
+ * // Returns: '/project/docs/README.md' (unchanged on Unix)
+ */
+export declare function toUnixPath(p: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAWjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C"}