@vibe-agent-toolkit/utils 0.1.8 → 0.1.10

package/README.md

@@ -29,6 +29,50 @@ import {
 
 ## Available Utilities
 
+### Zod Type Introspection (Version-Agnostic)
+
+**Purpose**: Runtime Zod type detection that works across Zod v3 and v4.
+
+Uses duck typing via `_def.typeName` instead of `instanceof` checks, which fail when library and user Zod versions differ. Essential for libraries that accept user-provided Zod schemas.
+
+**Quick Example**:
+```typescript
+import { getZodTypeName, isZodType, ZodTypeNames } from '@vibe-agent-toolkit/utils';
+import { z } from 'zod';
+
+const schema = z.string().optional();
+
+// Get type name (works with Zod v3 or v4)
+const typeName = getZodTypeName(schema);
+console.log(typeName); // 'ZodOptional'
+
+// Check if matches expected type
+if (isZodType(schema, ZodTypeNames.STRING)) {
+  console.log('String type!');
+}
+```
+
+**Available Functions**:
+- `getZodTypeName(zodType)` - Extract `_def.typeName` safely
+- `isZodType(zodType, typeName)` - Check if type matches expected name
+- `unwrapZodType(zodType)` - Unwrap optional/nullable to get inner type
+- `isZodOptional(zodType)` - Check if type is optional
+- `isZodNullable(zodType)` - Check if type is nullable
+
+**Available Constants** (`ZodTypeNames`):
+```typescript
+STRING, NUMBER, BOOLEAN, ARRAY, OBJECT, ENUM,
+OPTIONAL, NULLABLE, DATE, BIGINT, NATIVENUM,
+UNION, INTERSECTION, TUPLE, RECORD, MAP, SET,
+FUNCTION, LAZY, PROMISE, and more...
+```
+
+**See**: [docs/zod-compatibility.md](../../docs/zod-compatibility.md) for complete guide
+
+**Peer Dependency**: Requires `zod ^3.25.0 || ^4.0.0`
+
+---
+
 ### Process Spawning
 - `safeExecSync()` - Cross-platform secure command execution without shell
 

package/dist/git-utils.d.ts

@@ -37,9 +37,32 @@ export declare function gitLsFiles(options: {
  *
  * Uses git check-ignore which respects .gitignore, .git/info/exclude, and global gitignore
  *
+ * **Performance warning**: This spawns a git subprocess for each file.
+ * For checking multiple files, use `gitCheckIgnoredBatch()` instead.
+ *
  * @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;
+/**
+ * Batch check if multiple file paths are ignored by git
+ *
+ * Much more efficient than calling `isGitIgnored()` in a loop - uses a single
+ * git subprocess with stdin instead of N subprocesses.
+ *
+ * @param filePaths - Array of absolute or relative paths to check
+ * @param cwd - Working directory (defaults to process.cwd())
+ * @returns Map of filePath -> isIgnored (true if gitignored, false otherwise)
+ *
+ * @example
+ * ```typescript
+ * const files = ['src/foo.ts', 'dist/bar.js', 'node_modules/baz.js'];
+ * const ignoreMap = gitCheckIgnoredBatch(files, '/project');
+ * // ignoreMap.get('src/foo.ts') === false
+ * // ignoreMap.get('dist/bar.js') === true
+ * // ignoreMap.get('node_modules/baz.js') === true
+ * ```
+ */
+export declare function gitCheckIgnoredBatch(filePaths: string[], cwd?: string): Map<string, boolean>;
 //# sourceMappingURL=git-utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../src/git-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,MAAM,EAAE,GAAG,IAAI,CA0ClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,OAAO,CAkBnF"}
+{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../src/git-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,MAAM,EAAE,GAAG,IAAI,CA0ClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,OAAO,CAkBnF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EAAE,EACnB,GAAG,GAAE,MAAsB,GAC1B,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CA8DtB"}

package/dist/git-utils.js

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { dirname, join, parse, resolve } from 'node:path';
 import which from 'which';
+import { toForwardSlash } from './path-utils.js';
 /**
  * Find the git repository root by walking up from the given directory.
  *
@@ -85,6 +86,9 @@ export function gitLsFiles(options) {
  *
  * Uses git check-ignore which respects .gitignore, .git/info/exclude, and global gitignore
  *
+ * **Performance warning**: This spawns a git subprocess for each file.
+ * For checking multiple files, use `gitCheckIgnoredBatch()` instead.
+ *
  * @param filePath - Absolute or relative path to check
  * @param cwd - Working directory (defaults to process.cwd())
  * @returns true if file is gitignored, false otherwise
@@ -107,4 +111,78 @@ export function isGitIgnored(filePath, cwd = process.cwd()) {
         return false;
     }
 }
+/**
+ * Batch check if multiple file paths are ignored by git
+ *
+ * Much more efficient than calling `isGitIgnored()` in a loop - uses a single
+ * git subprocess with stdin instead of N subprocesses.
+ *
+ * @param filePaths - Array of absolute or relative paths to check
+ * @param cwd - Working directory (defaults to process.cwd())
+ * @returns Map of filePath -> isIgnored (true if gitignored, false otherwise)
+ *
+ * @example
+ * ```typescript
+ * const files = ['src/foo.ts', 'dist/bar.js', 'node_modules/baz.js'];
+ * const ignoreMap = gitCheckIgnoredBatch(files, '/project');
+ * // ignoreMap.get('src/foo.ts') === false
+ * // ignoreMap.get('dist/bar.js') === true
+ * // ignoreMap.get('node_modules/baz.js') === true
+ * ```
+ */
+export function gitCheckIgnoredBatch(filePaths, cwd = process.cwd()) {
+    const result = new Map();
+    // No files to check
+    if (filePaths.length === 0) {
+        return result;
+    }
+    // Normalize paths to forward slashes for cross-platform consistency
+    // Git on Windows returns forward slashes, so we normalize input paths to match
+    const normalizedPaths = filePaths.map(p => toForwardSlash(p));
+    // Create map with normalized paths as keys
+    const pathMap = new Map(); // normalized -> original
+    for (const [index, normalizedPath] of normalizedPaths.entries()) {
+        const originalPath = filePaths[index];
+        if (originalPath !== undefined) {
+            pathMap.set(normalizedPath, originalPath);
+        }
+    }
+    // Initialize all as not ignored (using original paths as keys)
+    for (const filePath of filePaths) {
+        result.set(filePath, false);
+    }
+    try {
+        // Resolve git path using which for security (avoids PATH manipulation)
+        const gitPath = which.sync('git');
+        // git check-ignore --stdin reads paths from stdin and outputs ignored ones
+        // Send normalized paths to git
+        const gitResult = spawnSync(gitPath, ['check-ignore', '--stdin'], {
+            cwd,
+            encoding: 'utf-8',
+            input: normalizedPaths.join('\n'),
+            stdio: 'pipe',
+            shell: false, // No shell interpreter for security
+        });
+        // Exit code 0 = at least one file ignored, 1 = none ignored
+        // Parse stdout to get which files are ignored
+        if (gitResult.status === 0 && gitResult.stdout) {
+            const ignoredPaths = gitResult.stdout
+                .split('\n')
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            // Mark ignored files (convert back to original paths)
+            for (const ignoredPath of ignoredPaths) {
+                const originalPath = pathMap.get(ignoredPath);
+                if (originalPath !== undefined) {
+                    result.set(originalPath, true);
+                }
+            }
+        }
+        return result;
+    }
+    catch {
+        // If git is not available or other error, return all as not ignored
+        return result;
+    }
+}
 //# sourceMappingURL=git-utils.js.map

package/dist/git-utils.js.map

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

package/dist/index.d.ts

@@ -12,4 +12,5 @@ export * from './gitignore-checker.js';
 export * from './git-utils.js';
 export * from './git-tracker.js';
 export * from './test-helpers.js';
+export * from './zod-introspection.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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;AAG/B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC"}
+{"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;AAG/B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -20,4 +20,6 @@ export * from './git-utils.js';
 export * from './git-tracker.js';
 // Test helpers for isolated test output directories
 export * from './test-helpers.js';
+// Zod type introspection (version-agnostic)
+export * from './zod-introspection.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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;AAE/B,yDAAyD;AACzD,cAAc,kBAAkB,CAAC;AAEjC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC"}
+{"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;AAE/B,yDAAyD;AACzD,cAAc,kBAAkB,CAAC;AAEjC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC"}

package/dist/test-helpers.d.ts

@@ -35,4 +35,68 @@ export declare function getTestOutputDir(packageName: string, testType: 'unit' |
  * ```
  */
 export declare function getTestOutputBase(packageName: string): string;
+/**
+ * Per-suite temp directory pattern (async version)
+ * Creates a single temp directory for the entire test suite,
+ * with subdirectories for each test. This is 3-5x faster on Windows
+ * than creating a new mkdtemp for each test.
+ *
+ * @param prefix - Prefix for the suite temp directory name
+ * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ *
+ * @example
+ * ```typescript
+ * const suite = setupAsyncTempDirSuite('my-test');
+ *
+ * describe('my tests', () => {
+ *   beforeAll(suite.beforeAll);
+ *   afterAll(suite.afterAll);
+ *   beforeEach(suite.beforeEach);
+ *
+ *   it('test 1', async () => {
+ *     const tempDir = suite.getTempDir();
+ *     // Use tempDir...
+ *   });
+ * });
+ * ```
+ */
+export declare function setupAsyncTempDirSuite(prefix: string): {
+    beforeAll: () => Promise<void>;
+    afterAll: () => Promise<void>;
+    beforeEach: () => Promise<void>;
+    afterEach: () => Promise<void>;
+    getTempDir: () => string;
+};
+/**
+ * Per-suite temp directory pattern (sync version)
+ * Creates a single temp directory for the entire test suite,
+ * with subdirectories for each test. This is 3-5x faster on Windows
+ * than creating a new mkdtemp for each test.
+ *
+ * @param prefix - Prefix for the suite temp directory name
+ * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ *
+ * @example
+ * ```typescript
+ * const suite = setupSyncTempDirSuite('my-test');
+ *
+ * describe('my tests', () => {
+ *   beforeAll(suite.beforeAll);
+ *   afterAll(suite.afterAll);
+ *   beforeEach(suite.beforeEach);
+ *
+ *   it('test 1', () => {
+ *     const tempDir = suite.getTempDir();
+ *     // Use tempDir...
+ *   });
+ * });
+ * ```
+ */
+export declare function setupSyncTempDirSuite(prefix: string): {
+    beforeAll: () => void;
+    afterAll: () => void;
+    beforeEach: () => void;
+    afterEach: () => void;
+    getTempDir: () => string;
+};
 //# sourceMappingURL=test-helpers.d.ts.map

package/dist/test-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ,EAC3C,GAAG,OAAO,EAAE,MAAM,EAAE,GACnB,MAAM,CAuBR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG7D"}
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ,EAC3C,GAAG,OAAO,EAAE,MAAM,EAAE,GACnB,MAAM,CAuBR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG;IACtD,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B,CAyBA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG;IACrD,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B,CAwBA"}

package/dist/test-helpers.js

@@ -1,6 +1,8 @@
 import { randomBytes } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import fs from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { mkdirSyncReal } from './path-utils.js';
+import { mkdirSyncReal, normalizedTmpdir } from './path-utils.js';
 /**
  * Get isolated test output directory for current test run
  *
@@ -52,4 +54,103 @@ export function getTestOutputBase(packageName) {
     const projectRoot = resolve(process.cwd());
     return join(projectRoot, 'packages', packageName, '.test-output');
 }
+/**
+ * Per-suite temp directory pattern (async version)
+ * Creates a single temp directory for the entire test suite,
+ * with subdirectories for each test. This is 3-5x faster on Windows
+ * than creating a new mkdtemp for each test.
+ *
+ * @param prefix - Prefix for the suite temp directory name
+ * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ *
+ * @example
+ * ```typescript
+ * const suite = setupAsyncTempDirSuite('my-test');
+ *
+ * describe('my tests', () => {
+ *   beforeAll(suite.beforeAll);
+ *   afterAll(suite.afterAll);
+ *   beforeEach(suite.beforeEach);
+ *
+ *   it('test 1', async () => {
+ *     const tempDir = suite.getTempDir();
+ *     // Use tempDir...
+ *   });
+ * });
+ * ```
+ */
+export function setupAsyncTempDirSuite(prefix) {
+    let suiteDir = '';
+    let tempDir = '';
+    let testCounter = 0;
+    return {
+        beforeAll: async () => {
+            suiteDir = await fs.mkdtemp(join(normalizedTmpdir(), `${prefix}-suite-`));
+        },
+        afterAll: async () => {
+            if (suiteDir) {
+                await fs.rm(suiteDir, { recursive: true, force: true });
+            }
+        },
+        beforeEach: async () => {
+            testCounter++;
+            tempDir = join(suiteDir, `test-${testCounter}`);
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- tempDir is from mkdtemp
+            await fs.mkdir(tempDir, { recursive: true });
+        },
+        afterEach: async () => {
+            // Per-test cleanup handled by suite cleanup
+        },
+        getTempDir: () => tempDir,
+    };
+}
+/**
+ * Per-suite temp directory pattern (sync version)
+ * Creates a single temp directory for the entire test suite,
+ * with subdirectories for each test. This is 3-5x faster on Windows
+ * than creating a new mkdtemp for each test.
+ *
+ * @param prefix - Prefix for the suite temp directory name
+ * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ *
+ * @example
+ * ```typescript
+ * const suite = setupSyncTempDirSuite('my-test');
+ *
+ * describe('my tests', () => {
+ *   beforeAll(suite.beforeAll);
+ *   afterAll(suite.afterAll);
+ *   beforeEach(suite.beforeEach);
+ *
+ *   it('test 1', () => {
+ *     const tempDir = suite.getTempDir();
+ *     // Use tempDir...
+ *   });
+ * });
+ * ```
+ */
+export function setupSyncTempDirSuite(prefix) {
+    let suiteDir = '';
+    let tempDir = '';
+    let testCounter = 0;
+    return {
+        beforeAll: () => {
+            suiteDir = mkdtempSync(join(normalizedTmpdir(), `${prefix}-suite-`));
+        },
+        afterAll: () => {
+            if (suiteDir) {
+                rmSync(suiteDir, { recursive: true, force: true });
+            }
+        },
+        beforeEach: () => {
+            testCounter++;
+            tempDir = join(suiteDir, `test-${testCounter}`);
+            mkdirSyncReal(tempDir);
+        },
+        afterEach: () => {
+            // Per-test cleanup handled by suite cleanup
+        },
+        getTempDir: () => tempDir,
+    };
+}
 //# sourceMappingURL=test-helpers.js.map

package/dist/test-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAAmB,EACnB,QAA2C,EAC3C,GAAG,OAAiB;IAEpB,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjF,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,GAAG,SAAS,IAAI,QAAQ,EAAE,CAAC;IAEzC,iEAAiE;IACjE,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3C,kFAAkF;IAClF,MAAM,aAAa,GAAG,IAAI,CACxB,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,KAAK,EACL,GAAG,OAAO,CACX,CAAC;IAEF,wDAAwD;IAExD,OAAO,aAAa,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;AACpE,CAAC"}
+{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"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"}

package/dist/zod-introspection.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Zod type introspection utilities
+ *
+ * Provides version-agnostic type detection using duck typing instead of
+ * instanceof checks, which fail across Zod v3/v4 boundaries.
+ *
+ * @module zod-introspection
+ */
+/**
+ * Zod type names from _def.typeName
+ *
+ * These internal type names are stable across Zod v3 and v4.
+ * Using these constants instead of instanceof checks ensures
+ * compatibility when user's Zod version differs from library's.
+ *
+ * @see https://github.com/colinhacks/zod/issues/2543
+ */
+export declare const ZodTypeNames: {
+    readonly STRING: "ZodString";
+    readonly NUMBER: "ZodNumber";
+    readonly BOOLEAN: "ZodBoolean";
+    readonly ARRAY: "ZodArray";
+    readonly OBJECT: "ZodObject";
+    readonly ENUM: "ZodEnum";
+    readonly OPTIONAL: "ZodOptional";
+    readonly NULLABLE: "ZodNullable";
+    readonly DATE: "ZodDate";
+    readonly LITERAL: "ZodLiteral";
+    readonly UNION: "ZodUnion";
+    readonly INTERSECTION: "ZodIntersection";
+    readonly TUPLE: "ZodTuple";
+    readonly RECORD: "ZodRecord";
+    readonly MAP: "ZodMap";
+    readonly SET: "ZodSet";
+    readonly FUNCTION: "ZodFunction";
+    readonly LAZY: "ZodLazy";
+    readonly PROMISE: "ZodPromise";
+    readonly BRANDED: "ZodBranded";
+    readonly PIPELINE: "ZodPipeline";
+    readonly READONLY: "ZodReadonly";
+    readonly SYMBOL: "ZodSymbol";
+    readonly UNDEFINED: "ZodUndefined";
+    readonly NULL: "ZodNull";
+    readonly ANY: "ZodAny";
+    readonly UNKNOWN: "ZodUnknown";
+    readonly NEVER: "ZodNever";
+    readonly VOID: "ZodVoid";
+    readonly BIGINT: "ZodBigInt";
+    readonly EFFECTS: "ZodEffects";
+    readonly NATIVENUM: "ZodNativeEnum";
+    readonly DISCRIMINATED_UNION: "ZodDiscriminatedUnion";
+    readonly DEFAULT: "ZodDefault";
+    readonly CATCH: "ZodCatch";
+    readonly NAN: "ZodNaN";
+};
+/**
+ * Type representing valid Zod type names
+ */
+export type ZodTypeName = (typeof ZodTypeNames)[keyof typeof ZodTypeNames];
+/**
+ * Get Zod type name in version-agnostic way
+ *
+ * Supports both Zod v3 and v4:
+ * - Zod v3: Uses _def.typeName (e.g., 'ZodString')
+ * - Zod v4: Uses _def.type (e.g., 'string'), converts to v3 format
+ *
+ * Uses duck typing instead of instanceof checks, which fail when
+ * user's Zod version differs from library's Zod version.
+ *
+ * @param zodType - Zod type to introspect
+ * @returns Type name string (e.g., 'ZodString') or undefined if not a Zod type
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { getZodTypeName, ZodTypeNames } from '@vibe-agent-toolkit/utils';
+ *
+ * const schema = z.string();
+ * const typeName = getZodTypeName(schema);
+ * console.log(typeName); // 'ZodString' (both v3 and v4)
+ *
+ * if (typeName === ZodTypeNames.STRING) {
+ *   console.log('It\'s a string schema!');
+ * }
+ * ```
+ */
+export declare function getZodTypeName(zodType: unknown): string | undefined;
+/**
+ * Check if Zod type matches expected type name
+ *
+ * Version-agnostic type checking using duck typing.
+ * Safer than instanceof when Zod versions may differ.
+ *
+ * @param zodType - Zod type to check
+ * @param typeName - Expected type name constant from ZodTypeNames
+ * @returns True if type matches, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { isZodType, ZodTypeNames } from '@vibe-agent-toolkit/utils';
+ *
+ * const schema = z.array(z.string());
+ *
+ * if (isZodType(schema, ZodTypeNames.ARRAY)) {
+ *   console.log('It\'s an array schema!');
+ * }
+ * ```
+ */
+export declare function isZodType(zodType: unknown, typeName: ZodTypeName): boolean;
+/**
+ * Unwrap optional/nullable Zod types to get inner type
+ *
+ * Recursively unwraps ZodOptional and ZodNullable to reach
+ * the underlying type. Returns original type if not wrapped.
+ *
+ * @param zodType - Zod type to unwrap
+ * @returns Unwrapped Zod type
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { unwrapZodType, getZodTypeName, ZodTypeNames } from '@vibe-agent-toolkit/utils';
+ *
+ * const schema = z.string().optional();
+ * const unwrapped = unwrapZodType(schema);
+ *
+ * console.log(getZodTypeName(unwrapped)); // 'ZodString'
+ * ```
+ */
+export declare function unwrapZodType(zodType: unknown): unknown;
+/**
+ * Check if Zod type is optional (ZodOptional)
+ *
+ * @param zodType - Zod type to check
+ * @returns True if type is optional
+ */
+export declare function isZodOptional(zodType: unknown): boolean;
+/**
+ * Check if Zod type is nullable (ZodNullable)
+ *
+ * @param zodType - Zod type to check
+ * @returns True if type is nullable
+ */
+export declare function isZodNullable(zodType: unknown): boolean;
+//# sourceMappingURL=zod-introspection.d.ts.map

package/dist/zod-introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-introspection.d.ts","sourceRoot":"","sources":["../src/zod-introspection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCf,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAkC3E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAiBnE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAE1E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAUvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEvD"}

package/dist/zod-introspection.js

@@ -0,0 +1,200 @@
+/**
+ * Zod type introspection utilities
+ *
+ * Provides version-agnostic type detection using duck typing instead of
+ * instanceof checks, which fail across Zod v3/v4 boundaries.
+ *
+ * @module zod-introspection
+ */
+/**
+ * Zod type names from _def.typeName
+ *
+ * These internal type names are stable across Zod v3 and v4.
+ * Using these constants instead of instanceof checks ensures
+ * compatibility when user's Zod version differs from library's.
+ *
+ * @see https://github.com/colinhacks/zod/issues/2543
+ */
+export const ZodTypeNames = {
+    STRING: 'ZodString',
+    NUMBER: 'ZodNumber',
+    BOOLEAN: 'ZodBoolean',
+    ARRAY: 'ZodArray',
+    OBJECT: 'ZodObject',
+    ENUM: 'ZodEnum',
+    OPTIONAL: 'ZodOptional',
+    NULLABLE: 'ZodNullable',
+    DATE: 'ZodDate',
+    LITERAL: 'ZodLiteral',
+    UNION: 'ZodUnion',
+    INTERSECTION: 'ZodIntersection',
+    TUPLE: 'ZodTuple',
+    RECORD: 'ZodRecord',
+    MAP: 'ZodMap',
+    SET: 'ZodSet',
+    FUNCTION: 'ZodFunction',
+    LAZY: 'ZodLazy',
+    PROMISE: 'ZodPromise',
+    BRANDED: 'ZodBranded',
+    PIPELINE: 'ZodPipeline',
+    READONLY: 'ZodReadonly',
+    SYMBOL: 'ZodSymbol',
+    UNDEFINED: 'ZodUndefined',
+    NULL: 'ZodNull',
+    ANY: 'ZodAny',
+    UNKNOWN: 'ZodUnknown',
+    NEVER: 'ZodNever',
+    VOID: 'ZodVoid',
+    BIGINT: 'ZodBigInt',
+    EFFECTS: 'ZodEffects',
+    NATIVENUM: 'ZodNativeEnum',
+    DISCRIMINATED_UNION: 'ZodDiscriminatedUnion',
+    DEFAULT: 'ZodDefault',
+    CATCH: 'ZodCatch',
+    NAN: 'ZodNaN',
+};
+/**
+ * Convert Zod v4 lowercase type to v3 PascalCase format
+ *
+ * Zod v4 changed from _def.typeName ('ZodString') to _def.type ('string').
+ * This function normalizes v4 types to match v3 format for consistency.
+ *
+ * @param v4Type - Lowercase type from Zod v4 _def.type
+ * @returns PascalCase type name with 'Zod' prefix
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * zodV4TypeToV3Name('string')  // 'ZodString'
+ * zodV4TypeToV3Name('array')   // 'ZodArray'
+ * zodV4TypeToV3Name('optional') // 'ZodOptional'
+ * ```
+ */
+function zodV4TypeToV3Name(v4Type) {
+    // Handle special cases with different naming
+    const specialCases = {
+        nativeenum: 'ZodNativeEnum',
+        bigint: 'ZodBigInt',
+    };
+    if (specialCases[v4Type]) {
+        return specialCases[v4Type];
+    }
+    // Convert: 'string' → 'ZodString', 'array' → 'ZodArray'
+    return 'Zod' + v4Type.charAt(0).toUpperCase() + v4Type.slice(1);
+}
+/**
+ * Get Zod type name in version-agnostic way
+ *
+ * Supports both Zod v3 and v4:
+ * - Zod v3: Uses _def.typeName (e.g., 'ZodString')
+ * - Zod v4: Uses _def.type (e.g., 'string'), converts to v3 format
+ *
+ * Uses duck typing instead of instanceof checks, which fail when
+ * user's Zod version differs from library's Zod version.
+ *
+ * @param zodType - Zod type to introspect
+ * @returns Type name string (e.g., 'ZodString') or undefined if not a Zod type
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { getZodTypeName, ZodTypeNames } from '@vibe-agent-toolkit/utils';
+ *
+ * const schema = z.string();
+ * const typeName = getZodTypeName(schema);
+ * console.log(typeName); // 'ZodString' (both v3 and v4)
+ *
+ * if (typeName === ZodTypeNames.STRING) {
+ *   console.log('It\'s a string schema!');
+ * }
+ * ```
+ */
+export function getZodTypeName(zodType) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const def = zodType?._def;
+    if (!def)
+        return undefined;
+    // Zod v3: uses _def.typeName (e.g., 'ZodString')
+    if (def.typeName) {
+        return def.typeName;
+    }
+    // Zod v4: uses _def.type (e.g., 'string')
+    // Convert to Zod v3 format for consistency
+    if (def.type) {
+        return zodV4TypeToV3Name(def.type);
+    }
+    return undefined;
+}
+/**
+ * Check if Zod type matches expected type name
+ *
+ * Version-agnostic type checking using duck typing.
+ * Safer than instanceof when Zod versions may differ.
+ *
+ * @param zodType - Zod type to check
+ * @param typeName - Expected type name constant from ZodTypeNames
+ * @returns True if type matches, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { isZodType, ZodTypeNames } from '@vibe-agent-toolkit/utils';
+ *
+ * const schema = z.array(z.string());
+ *
+ * if (isZodType(schema, ZodTypeNames.ARRAY)) {
+ *   console.log('It\'s an array schema!');
+ * }
+ * ```
+ */
+export function isZodType(zodType, typeName) {
+    return getZodTypeName(zodType) === typeName;
+}
+/**
+ * Unwrap optional/nullable Zod types to get inner type
+ *
+ * Recursively unwraps ZodOptional and ZodNullable to reach
+ * the underlying type. Returns original type if not wrapped.
+ *
+ * @param zodType - Zod type to unwrap
+ * @returns Unwrapped Zod type
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { unwrapZodType, getZodTypeName, ZodTypeNames } from '@vibe-agent-toolkit/utils';
+ *
+ * const schema = z.string().optional();
+ * const unwrapped = unwrapZodType(schema);
+ *
+ * console.log(getZodTypeName(unwrapped)); // 'ZodString'
+ * ```
+ */
+export function unwrapZodType(zodType) {
+    const typeName = getZodTypeName(zodType);
+    if (typeName === ZodTypeNames.OPTIONAL || typeName === ZodTypeNames.NULLABLE) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const inner = zodType.unwrap?.() ?? zodType._def?.innerType;
+        return inner ? unwrapZodType(inner) : zodType;
+    }
+    return zodType;
+}
+/**
+ * Check if Zod type is optional (ZodOptional)
+ *
+ * @param zodType - Zod type to check
+ * @returns True if type is optional
+ */
+export function isZodOptional(zodType) {
+    return isZodType(zodType, ZodTypeNames.OPTIONAL);
+}
+/**
+ * Check if Zod type is nullable (ZodNullable)
+ *
+ * @param zodType - Zod type to check
+ * @returns True if type is nullable
+ */
+export function isZodNullable(zodType) {
+    return isZodType(zodType, ZodTypeNames.NULLABLE);
+}
+//# sourceMappingURL=zod-introspection.js.map

package/dist/zod-introspection.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "Core utility functions with no external dependencies",
   "keywords": [
@@ -34,12 +34,16 @@
     "picomatch": "^4.0.3",
     "which": "^5.0.0"
   },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
+  },
   "devDependencies": {
     "@types/picomatch": "^4.0.2",
     "@types/which": "^3.0.4",
     "rimraf": "^6.0.1",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^3.25.0"
   },
   "publishConfig": {
     "access": "public"