/** * Find Project Root Utility * * CRITICAL: This utility finds the SpecWeave project root by searching for .specweave directory. * Use this instead of process.cwd() when the working directory may not be the project root. * * Common scenarios where CWD != project root: * - Hooks executed from parent directory * - CI/CD pipelines with different working directories * - Background jobs spawned from different locations * - Multi-repo setups where scripts run from umbrella root * * @module utils/find-project-root */ /** * Find project root by searching for .specweave/config.json * * Walks up the directory tree from startDir until it finds a directory * containing .specweave/config.json. Requires config.json to distinguish * real projects from stale .specweave/ folders (created by runtime bugs). * * @param startDir - Directory to start searching from (defaults to process.cwd()) * @returns Project root path or null if not found * * @example * // From /projects/my-app/src/components * findProjectRoot() * // Returns: "/projects/my-app" (if .specweave/config.json exists there) * * @example * // No .specweave/config.json found anywhere in tree * findProjectRoot() * // Returns: null */ export declare function findProjectRoot(startDir?: string): string | null; /** * Get project root, falling back to CWD if not found * * This is the RECOMMENDED function to use in most cases. * It returns a valid path even if .specweave doesn't exist. * * NOTE: This returns the NEAREST project root (for config reading). * For increment operations in multi-repo setups, use resolveEffectiveRoot() * which returns the umbrella root. * * NOTE: Never use the returned path as the root of a recursive filesystem * scan. Outside a project it is process.cwd(), which may be $HOME or /. * Use findProjectRoot() and stop on null instead. * * @param startDir - Directory to start searching from (defaults to process.cwd()) * @returns Project root path or process.cwd() if not found * * @example * // .specweave exists * getProjectRoot() // Returns: "/projects/my-app" * * // .specweave doesn't exist * getProjectRoot() // Returns: process.cwd() (e.g., "/projects/my-app") */ export declare function getProjectRoot(startDir?: string): string; /** * Check if current directory is within a SpecWeave project * * @param startDir - Directory to check (defaults to process.cwd()) * @returns true if .specweave directory exists in tree */ export declare function isInsideSpecWeaveProject(startDir?: string): boolean; /** * Check if a directory has an initialized SpecWeave project with actual increments. * * A repo is considered "initialized" only when `.specweave/increments/` exists * and contains at least one non-hidden entry. A `.specweave/` folder with just * logs, state, or config is NOT considered initialized. * * @param dir - Directory to check (the repo root, not .specweave/ itself) * @returns true if the directory has .specweave/increments/ with content */ export declare function hasSpecweaveIncrements(dir: string): boolean; /** * Find the umbrella root by walking up from the nearest project root. * * In a multi-repo umbrella project, nested repos each have their own * .specweave/config.json, but the umbrella root is the TOPMOST one * with `umbrella.enabled: true` or a sibling `repositories/` directory. * * @param startDir - Directory to start searching from (defaults to process.cwd()) * @returns Umbrella root path or null if not inside an umbrella project */ export declare function findUmbrellaRoot(startDir?: string): string | null; /** * Resolve the effective project root, or null when not inside a project. * * - In a multi-repo umbrella: returns the umbrella root (increments belong there) * - In a single-repo project: returns the nearest project root * - In a linked Git worktree outside the project (SpecWithCode threads): the * same lookups from the worktree's main checkout * - Otherwise: null * * Use this instead of resolveEffectiveRoot() for any command that scans or * mutates the tree under the root: outside a project the cwd fallback would be * $HOME or /, and a walk from there is unbounded (0879). * * @param startDir - Directory to start searching from (defaults to process.cwd()) * @returns Effective project root path or null if not inside a SpecWeave project */ export declare function findEffectiveRoot(startDir?: string): string | null; /** * Resolve the effective project root for increment operations. * * - In a multi-repo umbrella: returns the umbrella root (increments belong there) * - In a single-repo project: returns the nearest project root * - Fallback: returns process.cwd() * * NOTE: Never use the returned path as the root of a recursive filesystem * scan; outside a project it is process.cwd(). Use findEffectiveRoot() and * stop on null instead. * * @param startDir - Directory to start searching from (defaults to process.cwd()) * @returns Effective project root path */ export declare function resolveEffectiveRoot(startDir?: string): string; /** * Get the umbrella-aware .specweave directory path. * * Uses resolveEffectiveRoot() to find the correct root — returns the * umbrella root's .specweave/ when inside an umbrella workspace, or * the nearest project root's .specweave/ in standalone mode. * * This is the RECOMMENDED function for code that writes to .specweave/. * Unlike getSpecWeaveDir() which uses findProjectRoot() (nearest root, * returns null), this always returns a valid path. * * @param startDir - Directory to start searching from (defaults to process.cwd()) * @returns Absolute path to the effective .specweave directory */ export declare function getSpecweavePath(startDir?: string): string; /** * Get SpecWeave directory path (.specweave folder) * * @param projectRoot - Project root (will search if not provided) * @returns Path to .specweave directory or null if not found */ export declare function getSpecWeaveDir(projectRoot?: string): string | null; /** * Resolve a path relative to project root * * Useful for constructing paths that should be relative to project root, * not the current working directory. * * @param relativePath - Path relative to project root * @param startDir - Directory to start search from (defaults to process.cwd()) * @returns Resolved absolute path or null if project root not found * * @example * // From any subdirectory * resolveFromProjectRoot('.specweave/config.json') * // Returns: "/projects/my-app/.specweave/config.json" */ export declare function resolveFromProjectRoot(relativePath: string, startDir?: string): string | null; //# sourceMappingURL=find-project-root.d.ts.map