@iloom/cli 0.1.14

package/dist/index.d.ts

@@ -0,0 +1,1341 @@
+import { z } from 'zod';
+
+declare class WorkspaceManager {
+}
+
+/**
+ * Represents a Git worktree with all relevant metadata
+ */
+interface GitWorktree {
+    /** Absolute path to the worktree directory */
+    path: string;
+    /** Branch name associated with the worktree */
+    branch: string;
+    /** Current commit SHA */
+    commit: string;
+    /** Whether this is the main worktree */
+    bare: boolean;
+    /** Whether this is a detached HEAD state */
+    detached: boolean;
+    /** Whether this worktree is locked */
+    locked: boolean;
+    /** Reason for lock if locked */
+    lockReason?: string;
+}
+/**
+ * Configuration for creating a new worktree
+ */
+interface WorktreeCreateOptions {
+    /** Path where worktree should be created */
+    path: string;
+    /** Branch name to checkout/create */
+    branch: string;
+    /** Base branch to branch from (defaults to current branch) */
+    baseBranch?: string;
+    /** Whether to create a new branch */
+    createBranch?: boolean;
+    /** Whether to force creation (overwrite existing) */
+    force?: boolean;
+}
+/**
+ * Options for listing worktrees
+ */
+interface WorktreeListOptions {
+    /** Include porcelain output format */
+    porcelain?: boolean;
+    /** Include verbose information */
+    verbose?: boolean;
+}
+/**
+ * Result of a worktree operation
+ * @deprecated Use exception-based error handling instead
+ */
+interface WorktreeOperationResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Output message from Git command */
+    message: string;
+    /** Error message if operation failed */
+    error?: string;
+    /** Exit code from Git command */
+    exitCode: number;
+}
+/**
+ * Pattern matching for PR worktrees based on naming conventions
+ */
+interface PRWorktreePattern {
+    /** Regex pattern to match PR branch names */
+    branchPattern: RegExp;
+    /** Regex pattern to match PR worktree paths */
+    pathPattern: RegExp;
+    /** Function to extract PR number from branch name */
+    extractPRNumber: (branchName: string) => number | null;
+}
+/**
+ * Worktree validation result
+ */
+interface WorktreeValidation {
+    /** Whether the worktree is valid */
+    isValid: boolean;
+    /** List of validation issues found */
+    issues: string[];
+    /** Whether the worktree exists on disk */
+    existsOnDisk: boolean;
+    /** Whether the Git repository is valid */
+    isValidRepo: boolean;
+    /** Whether the branch reference is valid */
+    hasValidBranch: boolean;
+}
+/**
+ * Git worktree status information
+ */
+interface WorktreeStatus {
+    /** Number of modified files */
+    modified: number;
+    /** Number of added/staged files */
+    staged: number;
+    /** Number of deleted files */
+    deleted: number;
+    /** Number of untracked files */
+    untracked: number;
+    /** Whether there are uncommitted changes */
+    hasChanges: boolean;
+    /** Current branch name */
+    branch: string;
+    /** Whether in detached HEAD state */
+    detached: boolean;
+    /** Commits ahead of upstream */
+    ahead: number;
+    /** Commits behind upstream */
+    behind: number;
+}
+/**
+ * Worktree cleanup options
+ */
+interface WorktreeCleanupOptions {
+    /** Remove worktree directory from disk */
+    removeDirectory?: boolean;
+    /** Force removal even with uncommitted changes */
+    force?: boolean;
+    /** Remove associated branch if safe */
+    removeBranch?: boolean;
+    /** Dry run - show what would be done */
+    dryRun?: boolean;
+}
+
+/**
+ * Manages Git worktrees for the iloom CLI
+ * Ports functionality from bash scripts into TypeScript
+ */
+declare class GitWorktreeManager {
+    private readonly _workingDirectory;
+    constructor(workingDirectory?: string);
+    /**
+     * Get the working directory for git operations (main worktree path)
+     */
+    get workingDirectory(): string;
+    /**
+     * List all worktrees in the repository
+     * Defaults to porcelain format for reliable machine parsing
+     * Equivalent to: git worktree list --porcelain
+     */
+    listWorktrees(options?: WorktreeListOptions): Promise<GitWorktree[]>;
+    /**
+     * Find worktree for a specific branch
+     * Ports: find_worktree_for_branch() from find-worktree-for-branch.sh
+     */
+    findWorktreeForBranch(branchName: string): Promise<GitWorktree | null>;
+    /**
+     * Check if a worktree is the main repository worktree
+     * The main worktree is the first one listed by git worktree list (Git guarantee)
+     * This cannot be determined by path comparison because --show-toplevel returns
+     * the same value for all worktrees.
+     */
+    isMainWorktree(worktree: GitWorktree): Promise<boolean>;
+    /**
+     * Check if a worktree is a PR worktree based on naming patterns
+     * Ports: is_pr_worktree() from worktree-utils.sh
+     */
+    isPRWorktree(worktree: GitWorktree): boolean;
+    /**
+     * Get PR number from worktree branch name
+     * Ports: get_pr_number_from_worktree() from worktree-utils.sh
+     */
+    getPRNumberFromWorktree(worktree: GitWorktree): number | null;
+    /**
+     * Create a new worktree
+     * Ports worktree creation logic from new-branch-workflow.sh
+     * @returns The absolute path to the created worktree
+     */
+    createWorktree(options: WorktreeCreateOptions): Promise<string>;
+    /**
+     * Remove a worktree and optionally clean up associated files
+     * Ports worktree removal logic from cleanup-worktree.sh
+     * @returns A message describing what was done (for dry-run mode)
+     */
+    removeWorktree(worktreePath: string, options?: WorktreeCleanupOptions): Promise<string | void>;
+    /**
+     * Validate worktree state and integrity
+     */
+    validateWorktree(worktreePath: string): Promise<WorktreeValidation>;
+    /**
+     * Get detailed status information for a worktree
+     */
+    getWorktreeStatus(worktreePath: string): Promise<WorktreeStatus>;
+    /**
+     * Generate a suggested worktree path for a branch
+     */
+    generateWorktreePath(branchName: string, customRoot?: string, options?: {
+        isPR?: boolean;
+        prNumber?: number;
+        prefix?: string;
+    }): string;
+    /**
+     * Sanitize a branch name for use as a directory name
+     * Replaces slashes with dashes and removes invalid filesystem characters
+     * Ports logic from bash script line 593: ${BRANCH_NAME//\\//-}
+     */
+    sanitizeBranchName(branchName: string): string;
+    /**
+     * Check if repository is in a valid state for worktree operations
+     */
+    isRepoReady(): Promise<boolean>;
+    /**
+     * Get repository information
+     */
+    getRepoInfo(): Promise<{
+        root: string | null;
+        defaultBranch: string;
+        currentBranch: string | null;
+    }>;
+    /**
+     * Prune stale worktree entries (worktrees that no longer exist on disk)
+     */
+    pruneWorktrees(): Promise<void>;
+    /**
+     * Lock a worktree to prevent it from being pruned or moved
+     */
+    lockWorktree(worktreePath: string, reason?: string): Promise<void>;
+    /**
+     * Unlock a previously locked worktree
+     */
+    unlockWorktree(worktreePath: string): Promise<void>;
+    /**
+     * Find worktrees matching an identifier (branch name, path, or PR number)
+     */
+    findWorktreesByIdentifier(identifier: string): Promise<GitWorktree[]>;
+    /**
+     * Find worktree for a specific issue number using exact pattern matching
+     * Matches: issue-{N} at start OR after /, -, _ (but NOT issue-{N}X where X is a digit)
+     * Supports patterns like: issue-44, feat/issue-44-feature, feat-issue-44, bugfix_issue-44, etc.
+     * Avoids false matches like: tissue-44, myissue-44
+     * Ports: find_existing_worktree() from bash script lines 131-165
+     */
+    findWorktreeForIssue(issueNumber: number): Promise<GitWorktree | null>;
+    /**
+     * Find worktree for a specific PR by branch name
+     * Ports: find_existing_worktree() for PR type from bash script lines 149-160
+     */
+    findWorktreeForPR(prNumber: number, branchName: string): Promise<GitWorktree | null>;
+    /**
+     * Remove multiple worktrees
+     * Returns a summary of successes and failures
+     * Automatically filters out the main worktree
+     */
+    removeWorktrees(worktrees: GitWorktree[], options?: WorktreeCleanupOptions): Promise<{
+        successes: Array<{
+            worktree: GitWorktree;
+        }>;
+        failures: Array<{
+            worktree: GitWorktree;
+            error: string;
+        }>;
+        skipped: Array<{
+            worktree: GitWorktree;
+            reason: string;
+        }>;
+    }>;
+    /**
+     * Format worktree information for display
+     */
+    formatWorktree(worktree: GitWorktree): {
+        title: string;
+        path: string;
+        commit: string;
+    };
+}
+
+interface EnvVariable {
+    key: string;
+    value: string;
+}
+interface EnvFileOptions {
+    path: string;
+    backup?: boolean;
+    encoding?: BufferEncoding;
+}
+/**
+ * @deprecated Use exception-based error handling instead
+ */
+interface EnvOperationResult {
+    success: boolean;
+    backupPath?: string;
+    error?: string;
+}
+interface PortAssignmentOptions {
+    basePort?: number;
+    issueNumber?: number;
+    prNumber?: number;
+    branchName?: string;
+}
+
+type ProjectCapability = 'cli' | 'web';
+type Capability = ProjectCapability;
+interface Loom {
+    id: string;
+    path: string;
+    branch: string;
+    type: 'issue' | 'pr' | 'branch';
+    identifier: string | number;
+    port: number;
+    databaseBranch?: string;
+    createdAt: Date;
+    lastAccessed: Date;
+    githubData?: {
+        title?: string;
+        body?: string;
+        url?: string;
+        state?: string;
+    };
+    capabilities?: ProjectCapability[];
+    binEntries?: Record<string, string>;
+    cliSymlinks?: string[];
+}
+interface CreateLoomInput {
+    type: 'issue' | 'pr' | 'branch';
+    identifier: string | number;
+    originalInput: string;
+    baseBranch?: string;
+    options?: {
+        skipDatabase?: boolean;
+        skipColorSync?: boolean;
+        enableClaude?: boolean;
+        enableCode?: boolean;
+        enableDevServer?: boolean;
+        enableTerminal?: boolean;
+        oneShot?: OneShotMode;
+        setArguments?: string[];
+        executablePath?: string;
+    };
+}
+type LaunchMode = 'editor' | 'terminal' | 'both';
+interface LoomSummary {
+    id: string;
+    type: 'issue' | 'pr' | 'branch';
+    identifier: string | number;
+    title?: string;
+    branch: string;
+    port: number;
+    status: 'active' | 'stale' | 'error';
+    lastAccessed: string;
+}
+
+/**
+ * Options for ResourceCleanup operations
+ */
+interface ResourceCleanupOptions {
+    /** Preview operations without executing */
+    dryRun?: boolean;
+    /** Skip confirmations and safety checks */
+    force?: boolean;
+    /** Delete the associated branch */
+    deleteBranch?: boolean;
+    /** Keep database branch instead of deleting */
+    keepDatabase?: boolean;
+    /** Prompt for confirmation before operations */
+    interactive?: boolean;
+}
+/**
+ * Result of a cleanup operation
+ */
+interface CleanupResult {
+    /** Identifier that was cleaned up */
+    identifier: string;
+    /** Actual branch name that was found (will differ from identifier) */
+    branchName?: string;
+    /** Overall success status */
+    success: boolean;
+    /** Individual operation results */
+    operations: OperationResult[];
+    /** Errors encountered during cleanup */
+    errors: Error[];
+    /** Whether rollback is required */
+    rollbackRequired?: boolean;
+}
+/**
+ * Result of an individual cleanup operation
+ */
+interface OperationResult {
+    /** Type of operation performed */
+    type: 'dev-server' | 'worktree' | 'branch' | 'database' | 'cli-symlinks';
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Human-readable message */
+    message: string;
+    /** Error message if operation failed */
+    error?: string;
+    /** For database operations: whether branch was actually deleted (vs not found) */
+    deleted?: boolean;
+}
+/**
+ * Safety check result
+ */
+interface SafetyCheck {
+    /** Whether cleanup is safe to proceed */
+    isSafe: boolean;
+    /** Non-blocking warnings */
+    warnings: string[];
+    /** Blocking issues that prevent cleanup */
+    blockers: string[];
+}
+/**
+ * Options for branch deletion
+ */
+interface BranchDeleteOptions {
+    /** Force delete unmerged branch */
+    force?: boolean;
+    /** Also delete remote branch */
+    remote?: boolean;
+    /** Preview without executing */
+    dryRun?: boolean;
+}
+/**
+ * Target for batch cleanup - represents a branch that may or may not have a worktree
+ */
+interface BranchCleanupTarget {
+    /** Branch name */
+    branchName: string;
+    /** Whether this branch has an associated worktree */
+    hasWorktree: boolean;
+    /** Path to worktree if it exists */
+    worktreePath?: string;
+}
+/**
+ * Result of batch cleanup operation for an issue
+ */
+interface BatchCleanupResult {
+    /** Issue number that was cleaned up */
+    issueNumber: number;
+    /** Number of branches found matching the issue */
+    targetsFound: number;
+    /** Number of worktrees successfully removed */
+    worktreesRemoved: number;
+    /** Number of branches successfully deleted */
+    branchesDeleted: number;
+    /** Number of failed operations */
+    failed: number;
+    /** Individual cleanup results for each branch */
+    results: CleanupResult[];
+}
+
+/**
+ * Information about a running process
+ */
+interface ProcessInfo {
+    /** Process ID */
+    pid: number;
+    /** Process name (e.g., "node", "pnpm") */
+    name: string;
+    /** Full command line */
+    command: string;
+    /** Port the process is listening on */
+    port: number;
+    /** Whether this appears to be a dev server */
+    isDevServer: boolean;
+}
+
+interface Workspace {
+    id: string;
+    path: string;
+    branch: string;
+    issueNumber?: number;
+    prNumber?: number;
+    port: number;
+    databaseBranch?: string;
+    createdAt: Date;
+    lastAccessed: Date;
+}
+interface WorkspaceInput {
+    identifier: string;
+    type: 'issue' | 'pr' | 'branch';
+    skipClaude?: boolean;
+}
+interface WorkspaceSummary {
+    id: string;
+    issueNumber?: number;
+    prNumber?: number;
+    title: string;
+    branch: string;
+    port: number;
+    status: 'active' | 'stale' | 'error';
+    lastAccessed: string;
+}
+interface Worktree {
+    path: string;
+    branch: string;
+    commit: string;
+    isPR: boolean;
+    prNumber?: number;
+    issueNumber?: number;
+    port?: number;
+}
+interface GitStatus {
+    hasUncommittedChanges: boolean;
+    unstagedFiles: string[];
+    stagedFiles: string[];
+    currentBranch: string;
+    isAheadOfRemote: boolean;
+    isBehindRemote: boolean;
+}
+interface Issue {
+    number: number;
+    title: string;
+    body: string;
+    state: 'open' | 'closed';
+    labels: string[];
+    assignees: string[];
+    url: string;
+}
+interface PullRequest {
+    number: number;
+    title: string;
+    body: string;
+    state: 'open' | 'closed' | 'merged';
+    branch: string;
+    baseBranch: string;
+    url: string;
+    isDraft: boolean;
+}
+/**
+ * Result of database branch deletion operation
+ * Distinguishes between successful deletion, branch not found, and errors
+ */
+interface DatabaseDeletionResult {
+    /** Overall operation succeeded (true even if branch didn't exist) */
+    success: boolean;
+    /** True only if a branch was actually deleted */
+    deleted: boolean;
+    /** True if branch didn't exist (not an error, just nothing to do) */
+    notFound: boolean;
+    /** Error message if operation failed */
+    error?: string;
+    /** User declined deletion (for preview databases) */
+    userDeclined?: boolean;
+    /** Name of the branch that was processed */
+    branchName?: string;
+}
+interface DatabaseProvider {
+    createBranch(name: string, fromBranch?: string, cwd?: string): Promise<string>;
+    deleteBranch(name: string, isPreview?: boolean, cwd?: string): Promise<DatabaseDeletionResult>;
+    getConnectionString(branch: string, cwd?: string): Promise<string>;
+    listBranches(cwd?: string): Promise<string[]>;
+    branchExists(name: string, cwd?: string): Promise<boolean>;
+    findPreviewBranch(branchName: string, cwd?: string): Promise<string | null>;
+    getBranchNameFromEndpoint(endpointId: string, cwd?: string): Promise<string | null>;
+    sanitizeBranchName(branchName: string): string;
+    isAuthenticated(cwd?: string): Promise<boolean>;
+    isCliAvailable(): Promise<boolean>;
+    isConfigured(): boolean;
+}
+interface Config {
+    defaultPort: number;
+    databaseProvider?: 'neon' | 'supabase' | 'planetscale';
+    claudeModel?: 'opus' | 'sonnet' | 'haiku';
+    skipClaude?: boolean;
+    customWorkspaceRoot?: string;
+}
+type OneShotMode = 'default' | 'noReview' | 'bypassPermissions';
+interface StartOptions {
+    claude?: boolean;
+    code?: boolean;
+    devServer?: boolean;
+    terminal?: boolean;
+    oneShot?: OneShotMode;
+}
+interface AddIssueOptions {
+}
+interface FeedbackOptions {
+}
+interface EnhanceOptions {
+    noBrowser?: boolean;
+}
+interface FinishOptions {
+    force?: boolean;
+    dryRun?: boolean;
+    pr?: number;
+    skipBuild?: boolean;
+}
+/**
+ * Options for the cleanup command
+ * All flags are optional and can be combined (subject to validation)
+ */
+interface CleanupOptions {
+    /** List all worktrees without removing anything */
+    list?: boolean;
+    /** Remove all worktrees (interactive confirmation required unless --force) */
+    all?: boolean;
+    /** Cleanup by specific issue number */
+    issue?: number;
+    /** Skip confirmations and force removal */
+    force?: boolean;
+    /** Show what would be done without actually doing it */
+    dryRun?: boolean;
+}
+interface ListOptions {
+    json?: boolean;
+}
+interface MockOptions {
+    scenario: 'empty' | 'existing' | 'conflicts' | 'error';
+    data?: unknown;
+}
+
+interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+interface ColorData {
+    rgb: RgbColor;
+    hex: string;
+    index: number;
+}
+type Platform = 'darwin' | 'linux' | 'win32' | 'unsupported';
+interface ValidationOptions {
+    dryRun?: boolean;
+    skipTypecheck?: boolean;
+    skipLint?: boolean;
+    skipTests?: boolean;
+}
+interface ValidationStepResult {
+    step: 'typecheck' | 'lint' | 'test';
+    passed: boolean;
+    skipped: boolean;
+    output?: string;
+    error?: string;
+    duration?: number;
+}
+interface ValidationResult {
+    success: boolean;
+    steps: ValidationStepResult[];
+    totalDuration: number;
+}
+interface CommitOptions {
+    dryRun?: boolean;
+    issueNumber?: number;
+    message?: string;
+    noReview?: boolean;
+    skipVerify?: boolean;
+}
+interface MergeOptions {
+    dryRun?: boolean;
+    force?: boolean;
+    repoRoot?: string;
+}
+interface MergeResult {
+    success: boolean;
+    branchName: string;
+    commitsMerged: number;
+    rebaseCompleted: boolean;
+    mergeCompleted: boolean;
+}
+interface UpdateCheckCache {
+    lastCheck: number;
+    latestVersion: string;
+}
+interface UpdateCheckResult {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+}
+type InstallationMethod = 'global' | 'local' | 'linked' | 'unknown';
+
+interface GitHubInputDetection {
+    type: 'issue' | 'pr' | 'unknown';
+    number: number | null;
+    rawInput: string;
+}
+interface BranchNameStrategy {
+    generate(issueNumber: number, title: string): Promise<string>;
+}
+interface BranchGenerationOptions {
+    issueNumber: number;
+    title: string;
+    strategy?: BranchNameStrategy;
+}
+
+declare class GitHubService {
+    private defaultBranchNameStrategy;
+    private prompter;
+    constructor(options?: {
+        branchNameStrategy?: BranchNameStrategy;
+        useClaude?: boolean;
+        claudeModel?: string;
+        prompter?: (message: string) => Promise<boolean>;
+    });
+    detectInputType(input: string): Promise<GitHubInputDetection>;
+    fetchIssue(issueNumber: number): Promise<Issue>;
+    isValidIssue(issueNumber: number): Promise<Issue | false>;
+    private fetchIssueInternal;
+    validateIssueState(issue: Issue): Promise<void>;
+    fetchPR(prNumber: number): Promise<PullRequest>;
+    isValidPR(prNumber: number): Promise<PullRequest | false>;
+    private fetchPRInternal;
+    validatePRState(pr: PullRequest): Promise<void>;
+    generateBranchName(options: BranchGenerationOptions): Promise<string>;
+    createIssue(title: string, body: string, repository?: string, labels?: string[]): Promise<{
+        number: number;
+        url: string;
+    }>;
+    getIssueUrl(issueNumber: number, repo?: string): Promise<string>;
+    moveIssueToInProgress(issueNumber: number): Promise<void>;
+    private updateIssueStatusInProject;
+    extractContext(entity: Issue | PullRequest): string;
+    private mapGitHubIssueToIssue;
+    private mapGitHubPRToPullRequest;
+    private promptUserConfirmation;
+    setDefaultBranchNameStrategy(strategy: BranchNameStrategy): void;
+    getBranchNameStrategy(): BranchNameStrategy;
+}
+
+declare class EnvironmentManager {
+    private readonly backupSuffix;
+    /**
+     * Set or update an environment variable in a .env file
+     * Ports functionality from bash/utils/env-utils.sh:setEnvVar()
+     * @returns The backup path if a backup was created
+     */
+    setEnvVar(filePath: string, key: string, value: string, backup?: boolean): Promise<string | void>;
+    /**
+     * Read and parse a .env file
+     */
+    readEnvFile(filePath: string): Promise<Map<string, string>>;
+    /**
+     * Generic file copy helper that only copies if source exists
+     * Does not throw if source file doesn't exist - just logs and returns
+     * @private
+     */
+    copyIfExists(source: string, destination: string): Promise<void>;
+    /**
+     * Calculate unique port for workspace
+     * Implements:
+     * - Issue/PR: 3000 + issue/PR number
+     * - Branch: 3000 + deterministic hash offset (1-999)
+     */
+    calculatePort(options: PortAssignmentOptions): number;
+    /**
+     * Set port environment variable for workspace
+     */
+    setPortForWorkspace(envFilePath: string, issueNumber?: number, prNumber?: number, branchName?: string): Promise<number>;
+    /**
+     * Validate environment configuration
+     */
+    validateEnvFile(filePath: string): Promise<{
+        valid: boolean;
+        errors: string[];
+    }>;
+    /**
+     * Create backup of existing file
+     */
+    private createBackup;
+}
+
+/**
+ * Database Manager - orchestrates database operations with conditional execution
+ * Ports functionality from bash scripts with guard conditions:
+ *   1. Database provider must be properly configured (provider.isConfigured())
+ *   2. The worktree's .env file must contain the configured database URL variable (default: DATABASE_URL)
+ *
+ * This ensures database branching only occurs for projects that actually use databases
+ */
+declare class DatabaseManager {
+    private provider;
+    private environment;
+    private databaseUrlEnvVarName;
+    constructor(provider: DatabaseProvider, environment: EnvironmentManager, databaseUrlEnvVarName?: string);
+    /**
+     * Get the configured database URL environment variable name
+     */
+    getConfiguredVariableName(): string;
+    /**
+     * Check if database branching should be used
+     * Requires BOTH conditions:
+     *   1. Database provider is properly configured (checked via provider.isConfigured())
+     *   2. .env file contains the configured database URL variable
+     */
+    shouldUseDatabaseBranching(envFilePath: string): Promise<boolean>;
+    /**
+     * Create database branch only if configured
+     * Returns connection string if branch was created, null if skipped
+     *
+     * @param branchName - Name of the branch to create
+     * @param envFilePath - Path to .env file for configuration checks
+     * @param cwd - Optional working directory to run commands from
+     */
+    createBranchIfConfigured(branchName: string, envFilePath: string, cwd?: string): Promise<string | null>;
+    /**
+     * Delete database branch only if configured
+     * Returns result object indicating what happened
+     *
+     * @param branchName - Name of the branch to delete
+     * @param shouldCleanup - Boolean indicating if database cleanup should be performed (pre-fetched config)
+     * @param isPreview - Whether this is a preview database branch
+     * @param cwd - Optional working directory to run commands from (prevents issues with deleted directories)
+     */
+    deleteBranchIfConfigured(branchName: string, shouldCleanup: boolean, isPreview?: boolean, cwd?: string): Promise<DatabaseDeletionResult>;
+    /**
+     * Check if .env has the configured database URL variable
+     * CRITICAL: If user explicitly configured a custom variable name (not default),
+     * throw an error if it's missing from .env
+     */
+    private hasDatabaseUrlInEnv;
+}
+
+/**
+ * Zod schema for iloom settings
+ */
+declare const IloomSettingsSchema: z.ZodObject<{
+    mainBranch: z.ZodOptional<z.ZodString>;
+    worktreePrefix: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    protectedBranches: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    workflows: z.ZodOptional<z.ZodObject<{
+        issue: z.ZodOptional<z.ZodObject<{
+            permissionMode: z.ZodOptional<z.ZodEnum<["plan", "acceptEdits", "bypassPermissions", "default"]>>;
+            noVerify: z.ZodOptional<z.ZodBoolean>;
+            startIde: z.ZodDefault<z.ZodBoolean>;
+            startDevServer: z.ZodDefault<z.ZodBoolean>;
+            startAiAgent: z.ZodDefault<z.ZodBoolean>;
+            startTerminal: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        }, {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        }>>;
+        pr: z.ZodOptional<z.ZodObject<{
+            permissionMode: z.ZodOptional<z.ZodEnum<["plan", "acceptEdits", "bypassPermissions", "default"]>>;
+            noVerify: z.ZodOptional<z.ZodBoolean>;
+            startIde: z.ZodDefault<z.ZodBoolean>;
+            startDevServer: z.ZodDefault<z.ZodBoolean>;
+            startAiAgent: z.ZodDefault<z.ZodBoolean>;
+            startTerminal: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        }, {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        }>>;
+        regular: z.ZodOptional<z.ZodObject<{
+            permissionMode: z.ZodOptional<z.ZodEnum<["plan", "acceptEdits", "bypassPermissions", "default"]>>;
+            noVerify: z.ZodOptional<z.ZodBoolean>;
+            startIde: z.ZodDefault<z.ZodBoolean>;
+            startDevServer: z.ZodDefault<z.ZodBoolean>;
+            startAiAgent: z.ZodDefault<z.ZodBoolean>;
+            startTerminal: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        }, {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        issue?: {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        } | undefined;
+        pr?: {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        } | undefined;
+        regular?: {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        } | undefined;
+    }, {
+        issue?: {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        } | undefined;
+        pr?: {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        } | undefined;
+        regular?: {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        } | undefined;
+    }>>;
+    agents: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        model: z.ZodOptional<z.ZodEnum<["sonnet", "opus", "haiku"]>>;
+    }, "strip", z.ZodTypeAny, {
+        model?: "sonnet" | "opus" | "haiku" | undefined;
+    }, {
+        model?: "sonnet" | "opus" | "haiku" | undefined;
+    }>>>>;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        web: z.ZodOptional<z.ZodObject<{
+            basePort: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            basePort?: number | undefined;
+        }, {
+            basePort?: number | undefined;
+        }>>;
+        database: z.ZodOptional<z.ZodObject<{
+            databaseUrlEnvVarName: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            databaseUrlEnvVarName: string;
+        }, {
+            databaseUrlEnvVarName?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        web?: {
+            basePort?: number | undefined;
+        } | undefined;
+        database?: {
+            databaseUrlEnvVarName: string;
+        } | undefined;
+    }, {
+        web?: {
+            basePort?: number | undefined;
+        } | undefined;
+        database?: {
+            databaseUrlEnvVarName?: string | undefined;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    mainBranch?: string | undefined;
+    worktreePrefix?: string | undefined;
+    protectedBranches?: string[] | undefined;
+    workflows?: {
+        issue?: {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        } | undefined;
+        pr?: {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        } | undefined;
+        regular?: {
+            startIde: boolean;
+            startDevServer: boolean;
+            startAiAgent: boolean;
+            startTerminal: boolean;
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+        } | undefined;
+    } | undefined;
+    agents?: Record<string, {
+        model?: "sonnet" | "opus" | "haiku" | undefined;
+    }> | null | undefined;
+    capabilities?: {
+        web?: {
+            basePort?: number | undefined;
+        } | undefined;
+        database?: {
+            databaseUrlEnvVarName: string;
+        } | undefined;
+    } | undefined;
+}, {
+    mainBranch?: string | undefined;
+    worktreePrefix?: string | undefined;
+    protectedBranches?: string[] | undefined;
+    workflows?: {
+        issue?: {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        } | undefined;
+        pr?: {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        } | undefined;
+        regular?: {
+            permissionMode?: "plan" | "acceptEdits" | "bypassPermissions" | "default" | undefined;
+            noVerify?: boolean | undefined;
+            startIde?: boolean | undefined;
+            startDevServer?: boolean | undefined;
+            startAiAgent?: boolean | undefined;
+            startTerminal?: boolean | undefined;
+        } | undefined;
+    } | undefined;
+    agents?: Record<string, {
+        model?: "sonnet" | "opus" | "haiku" | undefined;
+    }> | null | undefined;
+    capabilities?: {
+        web?: {
+            basePort?: number | undefined;
+        } | undefined;
+        database?: {
+            databaseUrlEnvVarName?: string | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+/**
+ * TypeScript type for iloom settings derived from Zod schema
+ */
+type IloomSettings = z.infer<typeof IloomSettingsSchema>;
+/**
+ * Manages project-level settings from .iloom/settings.json
+ */
+declare class SettingsManager {
+    /**
+     * Load settings from <PROJECT_ROOT>/.iloom/settings.json and settings.local.json
+     * Merges settings.local.json over settings.json with priority
+     * CLI overrides have highest priority if provided
+     * Returns empty object if both files don't exist (not an error)
+     */
+    loadSettings(projectRoot?: string, cliOverrides?: Partial<IloomSettings>): Promise<IloomSettings>;
+    /**
+     * Log the final merged configuration for debugging
+     */
+    private logFinalConfiguration;
+    /**
+     * Load and parse a single settings file
+     * Returns empty object if file doesn't exist (not an error)
+     */
+    private loadSettingsFile;
+    /**
+     * Deep merge two settings objects with priority to override
+     * Uses deepmerge library with array replacement strategy
+     */
+    private mergeSettings;
+    /**
+     * Format all Zod validation errors into a single error message
+     */
+    private formatAllZodErrors;
+    /**
+     * Validate settings structure and model names using Zod schema
+     * This method is kept for testing purposes but uses Zod internally
+     * @internal - Only used in tests via bracket notation
+     */
+    private validateSettings;
+    /**
+     * Get project root (defaults to process.cwd())
+     */
+    private getProjectRoot;
+    /**
+     * Get effective protected branches list with mainBranch always included
+     *
+     * This method provides a single source of truth for protected branches logic:
+     * 1. Use configured protectedBranches if provided
+     * 2. Otherwise use defaults: [mainBranch, 'main', 'master', 'develop']
+     * 3. ALWAYS ensure mainBranch is included even if user configured custom list
+     *
+     * @param projectRoot - Optional project root directory (defaults to process.cwd())
+     * @returns Array of protected branch names with mainBranch guaranteed to be included
+     */
+    getProtectedBranches(projectRoot?: string): Promise<string[]>;
+}
+
+interface TemplateVariables {
+    ISSUE_NUMBER?: number;
+    PR_NUMBER?: number;
+    ISSUE_TITLE?: string;
+    PR_TITLE?: string;
+    WORKSPACE_PATH?: string;
+    PORT?: number;
+    ONE_SHOT_MODE?: boolean;
+}
+declare class PromptTemplateManager {
+    private templateDir;
+    constructor(templateDir?: string);
+    /**
+     * Load a template file by name
+     */
+    loadTemplate(templateName: 'issue' | 'pr' | 'regular'): Promise<string>;
+    /**
+     * Substitute variables in a template string
+     */
+    substituteVariables(template: string, variables: TemplateVariables): string;
+    /**
+     * Process conditional sections in template
+     * Format: {{#IF ONE_SHOT_MODE}}content{{/IF ONE_SHOT_MODE}}
+     *
+     * Note: /s flag allows . to match newlines
+     */
+    private processConditionalSections;
+    /**
+     * Get a fully processed prompt for a workflow type
+     */
+    getPrompt(type: 'issue' | 'pr' | 'regular', variables: TemplateVariables): Promise<string>;
+}
+
+interface ClaudeWorkflowOptions {
+    type: 'issue' | 'pr' | 'regular';
+    issueNumber?: number;
+    prNumber?: number;
+    title?: string;
+    workspacePath: string;
+    port?: number;
+    headless?: boolean;
+    branchName?: string;
+    oneShot?: OneShotMode;
+    setArguments?: string[];
+    executablePath?: string;
+}
+declare class ClaudeService {
+    private templateManager;
+    private settingsManager;
+    private settings?;
+    constructor(templateManager?: PromptTemplateManager, settingsManager?: SettingsManager);
+    /**
+     * Check if Claude CLI is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get the appropriate model for a workflow type
+     */
+    private getModelForWorkflow;
+    /**
+     * Get the appropriate permission mode for a workflow type
+     */
+    private getPermissionModeForWorkflow;
+    /**
+     * Launch Claude for a specific workflow
+     */
+    launchForWorkflow(options: ClaudeWorkflowOptions): Promise<string | void>;
+    /**
+     * Generate branch name with Claude, with fallback on failure
+     */
+    generateBranchNameWithFallback(issueTitle: string, issueNumber: number): Promise<string>;
+}
+
+interface ClaudeContext {
+    type: 'issue' | 'pr' | 'regular';
+    identifier: number | string;
+    title?: string;
+    workspacePath: string;
+    port?: number;
+    branchName?: string;
+    oneShot?: OneShotMode;
+    setArguments?: string[];
+    executablePath?: string;
+}
+declare class ClaudeContextManager {
+    private claudeService;
+    constructor(claudeService?: ClaudeService, _promptTemplateManager?: PromptTemplateManager, settingsManager?: SettingsManager);
+    /**
+     * Prepare context for Claude launch
+     * Placeholder for future .claude-context.md generation (Issue #11)
+     */
+    prepareContext(context: ClaudeContext): Promise<void>;
+    /**
+     * Launch Claude with the prepared context
+     */
+    launchWithContext(context: ClaudeContext, headless?: boolean): Promise<string | void>;
+}
+
+/**
+ * Execute a Git command and return the stdout result
+ * Throws an error if the command fails
+ */
+declare function executeGitCommand(args: string[], options?: {
+    cwd?: string;
+    timeout?: number;
+    stdio?: 'inherit' | 'pipe';
+}): Promise<string>;
+/**
+ * Parse git worktree list output into structured data
+ * @param output - The output from git worktree list --porcelain
+ * @param defaultBranch - Default branch name to use for bare repositories (defaults to 'main')
+ */
+declare function parseWorktreeList(output: string, defaultBranch?: string): GitWorktree[];
+/**
+ * Check if a branch name follows PR naming patterns
+ */
+declare function isPRBranch(branchName: string): boolean;
+/**
+ * Extract PR number from branch name
+ */
+declare function extractPRNumber(branchName: string): number | null;
+/**
+ * Check if a path follows worktree naming patterns
+ */
+declare function isWorktreePath(path: string): boolean;
+/**
+ * Generate a worktree path based on branch name and root directory
+ * For PRs, adds _pr_<PR_NUM> suffix to distinguish from issue branches
+ */
+declare function generateWorktreePath(branchName: string, rootDir?: string, options?: {
+    isPR?: boolean;
+    prNumber?: number;
+    prefix?: string;
+}): string;
+/**
+ * Validate that a directory is a valid Git repository
+ */
+declare function isValidGitRepo(path: string): Promise<boolean>;
+/**
+ * Get the current branch name for a repository
+ */
+declare function getCurrentBranch(path?: string): Promise<string | null>;
+/**
+ * Check if a branch exists (local or remote)
+ */
+declare function branchExists(branchName: string, path?: string, includeRemote?: boolean): Promise<boolean>;
+/**
+ * Get repository root directory
+ */
+declare function getRepoRoot(path?: string): Promise<string | null>;
+/**
+ * Find the worktree path where main branch is checked out
+ * Copies bash script approach: parse git worktree list to find main
+ */
+declare function findMainWorktreePath(path?: string, options?: {
+    mainBranch?: string;
+}): Promise<string>;
+/**
+ * Find main worktree path with automatic settings loading
+ *
+ * This is a convenience wrapper that:
+ * 1. Loads project settings from .iloom/settings.json
+ * 2. Extracts mainBranch configuration if present
+ * 3. Calls findMainWorktreePath with appropriate options
+ *
+ * @param path - Path to search from (defaults to process.cwd())
+ * @param settingsManager - Optional SettingsManager instance (for DI/testing)
+ * @returns Path to main worktree
+ * @throws Error if main worktree cannot be found
+ */
+declare function findMainWorktreePathWithSettings(path?: string, settingsManager?: SettingsManager): Promise<string>;
+/**
+ * Check if there are uncommitted changes in a repository
+ */
+declare function hasUncommittedChanges(path?: string): Promise<boolean>;
+/**
+ * Get the default branch name for a repository
+ */
+declare function getDefaultBranch(path?: string): Promise<string>;
+/**
+ * Find all branches related to a GitHub issue or PR number
+ * Matches patterns like:
+ * - Issue patterns: issue-25, issue/25, 25-feature, feat-25, feat/issue-25
+ * - PR patterns: pr/25, pull/25, pr-25, feature/pr-25
+ *
+ * Based on bash cleanup-worktree.sh find_issue_branches() (lines 133-154)
+ *
+ * @param issueNumber - The issue or PR number to search for
+ * @param path - Working directory to search from (defaults to process.cwd())
+ * @param settingsManager - Optional SettingsManager instance (for DI/testing)
+ */
+declare function findAllBranchesForIssue(issueNumber: number, path?: string, settingsManager?: SettingsManager): Promise<string[]>;
+/**
+ * Check if a repository is empty (has no commits yet)
+ * @param path - Repository path to check (defaults to process.cwd())
+ * @returns true if repository has no commits, false otherwise
+ */
+declare function isEmptyRepository(path?: string): Promise<boolean>;
+/**
+ * Ensure repository has at least one commit
+ * Creates an initial empty commit if repository is empty
+ * @param path - Repository path (defaults to process.cwd())
+ */
+declare function ensureRepositoryHasCommits(path?: string): Promise<void>;
+/**
+ * Push a branch to remote repository
+ * Used for PR workflow to push changes to remote without merging locally
+ *
+ * @param branchName - The branch name to push
+ * @param worktreePath - The worktree path where the branch is checked out
+ * @param options - Push options
+ * @throws Error if push fails
+ */
+declare function pushBranchToRemote(branchName: string, worktreePath: string, options?: {
+    dryRun?: boolean;
+}): Promise<void>;
+
+interface LoggerOptions {
+    prefix?: string;
+    timestamp?: boolean;
+    silent?: boolean;
+    forceColor?: boolean | undefined | null;
+    debug?: boolean;
+}
+interface Logger {
+    info: (message: string, ...args: unknown[]) => void;
+    success: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
+    setDebug: (enabled: boolean) => void;
+    isDebugEnabled: () => boolean;
+}
+declare const logger: Logger;
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { type AddIssueOptions, type BatchCleanupResult, type BranchCleanupTarget, type BranchDeleteOptions, type Capability, type ClaudeContext, ClaudeContextManager, type CleanupOptions, type CleanupResult, type ColorData, type CommitOptions, type Config, type CreateLoomInput, type DatabaseDeletionResult, DatabaseManager, type DatabaseProvider, type EnhanceOptions, type EnvFileOptions, type EnvOperationResult, type EnvVariable, EnvironmentManager, type FeedbackOptions, type FinishOptions, GitHubService, type GitStatus, type GitWorktree, GitWorktreeManager, type InstallationMethod, type Issue, type LaunchMode, type ListOptions, type Logger, type LoggerOptions, type Loom, type LoomSummary, type MergeOptions, type MergeResult, type MockOptions, type OneShotMode, type OperationResult, type PRWorktreePattern, type Platform, type PortAssignmentOptions, type ProcessInfo, type ProjectCapability, type PullRequest, type ResourceCleanupOptions, type RgbColor, type SafetyCheck, type StartOptions, type UpdateCheckCache, type UpdateCheckResult, type ValidationOptions, type ValidationResult, type ValidationStepResult, type Workspace, type WorkspaceInput, WorkspaceManager, type WorkspaceSummary, type Worktree, type WorktreeCleanupOptions, type WorktreeCreateOptions, type WorktreeListOptions, type WorktreeOperationResult, type WorktreeStatus, type WorktreeValidation, branchExists, createLogger, ensureRepositoryHasCommits, executeGitCommand, extractPRNumber, findAllBranchesForIssue, findMainWorktreePath, findMainWorktreePathWithSettings, generateWorktreePath, getCurrentBranch, getDefaultBranch, getRepoRoot, hasUncommittedChanges, isEmptyRepository, isPRBranch, isValidGitRepo, isWorktreePath, logger, parseWorktreeList, pushBranchToRemote };