import { z } from "zod";
import type { ArchLayer } from "./types.js";
/**
 * Zod preprocessor that accepts either a real string array OR a JSON-string-
 * encoded array (e.g. '["a","b"]'). Required because some MCP clients (including
 * Claude Code) occasionally serialize optional array parameters as JSON strings
 * instead of native JSON arrays, causing z.array() to reject them with
 * "Expected array, received string".
 *
 * Usage:  tags: coerceStringArray().optional()
 *         (replaces: z.array(z.string()).optional())
 */
export declare function coerceStringArray(): z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
/**
 * Zod preprocessor that accepts either a real number array OR a JSON-string-
 * encoded array (e.g. '[1,2,3]'). Mirrors coerceStringArray() for integer
 * array parameters like `depends_on`, `blocked_by`, `ids`, etc.
 *
 * Usage:  depends_on: coerceNumberArray().optional()
 *         (replaces: z.array(z.number().int()).optional())
 */
export declare function coerceNumberArray(): z.ZodEffects<z.ZodArray<z.ZodNumber, "many">, number[], unknown>;
/**
 * Normalize a file path for consistent storage as a database key.
 * 1. Replace backslashes with forward slashes
 * 2. If absolute and projectRoot provided, convert to relative
 * 3. Strip leading ./
 * 4. Collapse consecutive /
 * 5. Strip trailing /
 */
export declare function normalizePath(filePath: string, projectRoot?: string): string;
/**
 * Auto-detect the project root using a 6-tier priority chain.
 *
 * @param startDir  Starting directory for filesystem walk (default: cwd)
 * @returns         Absolute path to the detected or fallback project root
 */
export declare function findProjectRoot(startDir?: string): string;
/**
 * Scan the project file tree, respecting exclusions and depth limits.
 */
export declare function scanFileTree(rootDir: string, maxDepth?: number, maxEntries?: number): string[];
/**
 * Detect the architectural layer of a file based on its path.
 */
export declare function detectLayer(filePath: string): ArchLayer;
/**
 * Run a git command in the project root. Returns empty string on failure.
 */
export declare function gitCommand(projectRoot: string, command: string): string;
/**
 * Check if the project is a git repository.
 */
export declare function isGitRepo(projectRoot: string): boolean;
/**
 * Get git log since a given timestamp.
 */
export declare function getGitLogSince(projectRoot: string, since: string, limit?: number): string;
/**
 * Get git diff stat (files changed, insertions, deletions).
 */
export declare function getGitDiffStat(projectRoot: string, since: string): string;
/**
 * Get files changed in git since a timestamp.
 */
export declare function getGitFilesChanged(projectRoot: string, since: string): string[];
/**
 * Get the current git branch name.
 */
export declare function getGitBranch(projectRoot: string): string;
/**
 * Get the latest git commit hash (short).
 */
export declare function getGitHead(projectRoot: string): string;
/**
 * Safely parse a JSON string, returning a default value on failure.
 */
export declare function safeJsonParse<T>(json: string | null | undefined, fallback: T): T;
/**
 * Format a response as either JSON or Markdown.
 */
export declare function formatResponse(data: unknown, format?: "json" | "markdown"): string;
/**
 * Calculate minutes between now and a given ISO timestamp.
 */
export declare function minutesSince(isoTimestamp: string): number;
/**
 * Truncate a string to a max length with ellipsis.
 */
export declare function truncate(str: string, maxLength: number): string;
/**
 * Escape a query string for safe use in SQLite FTS5 MATCH expressions.
 * Each word is wrapped in double quotes for exact-word matching.
 * Multiple words are joined with OR so any match surfaces the row.
 *
 * Example: "auth refactor" → `"auth" OR "refactor"`
 */
export declare function ftsEscape(query: string): string;
/**
 * Get the actual modification time (Unix ms) of a file on disk.
 * Resolves relative paths against projectRoot when provided.
 * Returns null if the file does not exist or stat fails.
 */
export declare function getFileMtime(filePath: string, projectRoot?: string): number | null;
/**
 * Compute a SHA-256 hex digest of a file's contents.
 * Returns null if the file cannot be read.
 */
export declare function getFileHash(filePath: string, projectRoot?: string): string | null;
/**
 * Derive a stable machine ID from OS hardware identifiers.
 * Falls back to a SHA-256 hash of hostname + username + homedir.
 *
 * Priority:
 *   Windows:  MachineGuid from registry
 *   macOS:    IOPlatformUUID via ioreg
 *   Linux:    /etc/machine-id or /var/lib/dbus/machine-id
 *   Fallback: SHA-256(hostname + username + homedir)
 */
export declare function getMachineId(): string;
/**
 * Generate a human-readable instance label from the project root path.
 * Format: "<project_basename>" (e.g., "Engram", "fundi-smart", "MCP-Builder")
 */
export declare function generateInstanceLabel(projectRoot: string): string;
//# sourceMappingURL=utils.d.ts.map