@iloom/cli 0.3.1 → 0.3.3

package/dist/{chunk-HBYZH6GD.js → chunk-2IJEMXOB.js}

@@ -1,10 +1,4 @@
 #!/usr/bin/env node
-import {
-  formatEnvLine,
-  loadEnvIntoProcess,
-  parseEnvFile,
-  validateEnvVariable
-} from "./chunk-IP7SMKIF.js";
 import {
   calculatePortForBranch
 } from "./chunk-VU3QMIP2.js";
@@ -16,36 +10,220 @@ import {
   hasScript,
   readPackageJson
 } from "./chunk-2ZPFJQ3B.js";
-import {
-  SettingsManager
-} from "./chunk-O5OH5MRX.js";
 import {
   branchExists,
   ensureRepositoryHasCommits,
   executeGitCommand,
   extractIssueNumber,
   findMainWorktreePathWithSettings,
-  hasUncommittedChanges
-} from "./chunk-4BGK7T6X.js";
+  hasUncommittedChanges,
+  isFileTrackedByGit
+} from "./chunk-5Q3NDNNV.js";
+import {
+  SettingsManager
+} from "./chunk-CDZERT7Z.js";
 import {
   calculateForegroundColor,
   generateColorFromBranchName,
   hexToRgb,
   lightenColor,
-  rgbToHex
-} from "./chunk-ZZZWQGTS.js";
+  rgbToHex,
+  selectDistinctColor
+} from "./chunk-CFFQ2Z7A.js";
+import {
+  findEnvFileForDatabaseUrl,
+  formatEnvLine,
+  hasVariableInAnyEnvFile,
+  loadEnvIntoProcess,
+  parseEnvFile,
+  validateEnvVariable
+} from "./chunk-UJL4HI2R.js";
 import {
   createLogger,
   logger
 } from "./chunk-GEHQXLEI.js";
 
+// src/lib/MetadataManager.ts
+import path from "path";
+import os from "os";
+import fs from "fs-extra";
+var MetadataManager = class {
+  constructor() {
+    this.loomsDir = path.join(os.homedir(), ".config", "iloom-ai", "looms");
+  }
+  /**
+   * Convert worktree path to filename slug per spec section 2.2
+   *
+   * Algorithm:
+   * 1. Trim trailing slashes
+   * 2. Replace all path separators (/ or \) with __ (double underscore)
+   * 3. Replace any other non-alphanumeric characters (except _ and -) with -
+   * 4. Append .json
+   *
+   * Example:
+   * - Worktree: /Users/jane/dev/repo
+   * - Filename: _Users__jane__dev__repo.json
+   */
+  slugifyPath(worktreePath) {
+    let slug = worktreePath.replace(/[/\\]+$/, "");
+    slug = slug.replace(/[/\\]/g, "___");
+    slug = slug.replace(/[^a-zA-Z0-9_-]/g, "-");
+    return `${slug}.json`;
+  }
+  /**
+   * Get the full path to the metadata file for a worktree
+   */
+  getFilePath(worktreePath) {
+    const filename = this.slugifyPath(worktreePath);
+    return path.join(this.loomsDir, filename);
+  }
+  /**
+   * Write metadata for a worktree (spec section 3.1)
+   *
+   * @param worktreePath - Absolute path to the worktree (used for file naming)
+   * @param input - Metadata to write (description plus additional fields)
+   */
+  async writeMetadata(worktreePath, input) {
+    try {
+      await fs.ensureDir(this.loomsDir, { mode: 493 });
+      const content = {
+        description: input.description,
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        version: 1,
+        branchName: input.branchName,
+        worktreePath: input.worktreePath,
+        issueType: input.issueType,
+        issue_numbers: input.issue_numbers,
+        pr_numbers: input.pr_numbers,
+        issueTracker: input.issueTracker,
+        colorHex: input.colorHex
+      };
+      const filePath = this.getFilePath(worktreePath);
+      await fs.writeFile(filePath, JSON.stringify(content, null, 2), { mode: 420 });
+      logger.debug(`Metadata written for worktree: ${worktreePath}`);
+    } catch (error) {
+      logger.warn(
+        `Failed to write metadata for worktree: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Read metadata for a worktree (spec section 3.2)
+   *
+   * @param worktreePath - Absolute path to the worktree
+   * @returns The metadata object with all fields, or null if not found/invalid
+   */
+  async readMetadata(worktreePath) {
+    try {
+      const filePath = this.getFilePath(worktreePath);
+      if (!await fs.pathExists(filePath)) {
+        return null;
+      }
+      const content = await fs.readFile(filePath, "utf8");
+      const data = JSON.parse(content);
+      if (!data.description) {
+        return null;
+      }
+      return {
+        description: data.description,
+        created_at: data.created_at ?? null,
+        branchName: data.branchName ?? null,
+        worktreePath: data.worktreePath ?? null,
+        issueType: data.issueType ?? null,
+        issue_numbers: data.issue_numbers ?? [],
+        pr_numbers: data.pr_numbers ?? [],
+        issueTracker: data.issueTracker ?? null,
+        colorHex: data.colorHex ?? null
+      };
+    } catch (error) {
+      logger.debug(
+        `Could not read metadata for worktree ${worktreePath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return null;
+    }
+  }
+  /**
+   * List all stored loom metadata files
+   *
+   * Returns an array of LoomMetadata objects for all valid metadata files
+   * in the looms directory. Invalid or unreadable files are skipped.
+   *
+   * @returns Array of LoomMetadata objects from all stored files
+   */
+  async listAllMetadata() {
+    const results = [];
+    try {
+      if (!await fs.pathExists(this.loomsDir)) {
+        return results;
+      }
+      const files = await fs.readdir(this.loomsDir);
+      for (const file of files) {
+        if (!file.endsWith(".json")) {
+          continue;
+        }
+        try {
+          const filePath = path.join(this.loomsDir, file);
+          const content = await fs.readFile(filePath, "utf8");
+          const data = JSON.parse(content);
+          if (!data.description) {
+            continue;
+          }
+          results.push({
+            description: data.description,
+            created_at: data.created_at ?? null,
+            branchName: data.branchName ?? null,
+            worktreePath: data.worktreePath ?? null,
+            issueType: data.issueType ?? null,
+            issue_numbers: data.issue_numbers ?? [],
+            pr_numbers: data.pr_numbers ?? [],
+            issueTracker: data.issueTracker ?? null,
+            colorHex: data.colorHex ?? null
+          });
+        } catch (error) {
+          logger.debug(
+            `Skipping metadata file ${file}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+    } catch (error) {
+      logger.debug(
+        `Could not list metadata files: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    return results;
+  }
+  /**
+   * Delete metadata for a worktree (spec section 3.3)
+   *
+   * Idempotent: silently succeeds if file doesn't exist
+   * Non-fatal: logs warning on permission errors but doesn't throw
+   *
+   * @param worktreePath - Absolute path to the worktree
+   */
+  async deleteMetadata(worktreePath) {
+    try {
+      const filePath = this.getFilePath(worktreePath);
+      if (!await fs.pathExists(filePath)) {
+        logger.debug(`No metadata file to delete for worktree: ${worktreePath}`);
+        return;
+      }
+      await fs.unlink(filePath);
+      logger.debug(`Metadata deleted for worktree: ${worktreePath}`);
+    } catch (error) {
+      logger.warn(
+        `Failed to delete metadata for worktree: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+};
+
 // src/lib/LoomManager.ts
-import path2 from "path";
-import fs2 from "fs-extra";
+import path3 from "path";
+import fs3 from "fs-extra";
 
 // src/lib/VSCodeIntegration.ts
-import fs from "fs-extra";
-import path from "path";
+import fs2 from "fs-extra";
+import path2 from "path";
 import { parse, modify, applyEdits } from "jsonc-parser";
 var VSCodeIntegration = class {
   /**
@@ -55,10 +233,10 @@ var VSCodeIntegration = class {
    * @param hexColor - Hex color string (e.g., "#dcebf8")
    */
   async setTitleBarColor(workspacePath, hexColor) {
-    const vscodeDir = path.join(workspacePath, ".vscode");
-    const settingsPath = path.join(vscodeDir, "settings.json");
+    const vscodeDir = path2.join(workspacePath, ".vscode");
+    const settingsPath = path2.join(vscodeDir, "settings.json");
     try {
-      await fs.ensureDir(vscodeDir);
+      await fs2.ensureDir(vscodeDir);
       const settings = await this.readSettings(settingsPath);
       const updatedSettings = this.mergeColorSettings(settings, hexColor);
       await this.writeSettings(settingsPath, updatedSettings);
@@ -78,10 +256,10 @@ var VSCodeIntegration = class {
    */
   async readSettings(settingsPath) {
     try {
-      if (!await fs.pathExists(settingsPath)) {
+      if (!await fs2.pathExists(settingsPath)) {
         return {};
       }
-      const content = await fs.readFile(settingsPath, "utf8");
+      const content = await fs2.readFile(settingsPath, "utf8");
       const errors = [];
       const settings = parse(content, errors, { allowTrailingComma: true });
       if (errors.length > 0) {
@@ -105,8 +283,8 @@ var VSCodeIntegration = class {
   async writeSettings(settingsPath, settings) {
     try {
       let content;
-      if (await fs.pathExists(settingsPath)) {
-        const existingContent = await fs.readFile(settingsPath, "utf8");
+      if (await fs2.pathExists(settingsPath)) {
+        const existingContent = await fs2.readFile(settingsPath, "utf8");
         if (existingContent.includes("//") || existingContent.includes("/*")) {
           content = await this.modifyWithCommentsPreserved(existingContent, settings);
         } else {
@@ -116,8 +294,8 @@ var VSCodeIntegration = class {
         content = JSON.stringify(settings, null, 2) + "\n";
       }
       const tempPath = `${settingsPath}.tmp`;
-      await fs.writeFile(tempPath, content, "utf8");
-      await fs.rename(tempPath, settingsPath);
+      await fs2.writeFile(tempPath, content, "utf8");
+      await fs2.rename(tempPath, settingsPath);
     } catch (error) {
       throw new Error(
         `Failed to write settings.json: ${error instanceof Error ? error.message : "Unknown error"}`
@@ -181,6 +359,7 @@ var LoomManager = class {
     this.cliIsolation = cliIsolation;
     this.settings = settings;
     this.database = database;
+    this.metadataManager = new MetadataManager();
   }
   /**
    * Get database branch name for a loom by reading its .env file
@@ -194,7 +373,7 @@ var LoomManager = class {
       return null;
     }
     try {
-      const envFilePath = path2.join(loomPath, ".env");
+      const envFilePath = path3.join(loomPath, ".env");
       const settings = await this.settings.loadSettings();
       const databaseUrlVarName = ((_b = (_a = settings.capabilities) == null ? void 0 : _a.database) == null ? void 0 : _b.databaseUrlEnvVarName) ?? "DATABASE_URL";
       const connectionString = await this.environment.getEnvVariable(envFilePath, databaseUrlVarName);
@@ -213,7 +392,7 @@ var LoomManager = class {
    * NEW: Checks for existing worktrees and reuses them if found
    */
   async createIloom(input) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
     logger.info("Fetching issue data...");
     const issueData = await this.fetchIssueData(input);
     if (input.type === "issue" || input.type === "pr" || input.type === "branch") {
@@ -249,16 +428,25 @@ var LoomManager = class {
       try {
         const connectionString = await this.database.createBranchIfConfigured(
           branchName,
-          path2.join(worktreePath, ".env"),
+          worktreePath,
+          // workspace path - checks all dotenv-flow files
           void 0,
           // cwd
           (_e = input.parentLoom) == null ? void 0 : _e.databaseBranch
           // fromBranch - use parent's database branch for child looms
         );
         if (connectionString) {
+          const varName = this.database.getConfiguredVariableName();
+          const targetFile = await findEnvFileForDatabaseUrl(
+            worktreePath,
+            varName,
+            isFileTrackedByGit,
+            async (p) => fs3.pathExists(p),
+            async (p, v) => this.environment.getEnvVariable(p, v)
+          );
           await this.environment.setEnvVar(
-            path2.join(worktreePath, ".env"),
-            this.database.getConfiguredVariableName(),
+            path3.join(worktreePath, targetFile),
+            varName,
             connectionString
           );
           logger.success("Database branch configured");
@@ -286,15 +474,17 @@ var LoomManager = class {
         );
       }
     }
-    if (!((_f = input.options) == null ? void 0 : _f.skipColorSync)) {
-      try {
-        await this.applyColorSynchronization(worktreePath, branchName);
-      } catch (error) {
-        logger.warn(
-          `Failed to apply color synchronization: ${error instanceof Error ? error.message : "Unknown error"}`,
-          error
-        );
-      }
+    const allMetadata = await this.metadataManager.listAllMetadata();
+    const usedHexColors = allMetadata.filter((metadata) => metadata.colorHex !== null).map((metadata) => metadata.colorHex);
+    const colorData = selectDistinctColor(branchName, usedHexColors);
+    logger.debug(`Selected color ${colorData.hex} for branch ${branchName} (${usedHexColors.length} colors in use globally)`);
+    try {
+      await this.applyColorSynchronization(worktreePath, branchName, colorData, settingsData, input.options);
+    } catch (error) {
+      logger.warn(
+        `Failed to apply color synchronization: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
     }
     if (input.type === "issue") {
       try {
@@ -309,16 +499,16 @@ var LoomManager = class {
         );
       }
     }
-    const enableClaude = ((_g = input.options) == null ? void 0 : _g.enableClaude) !== false;
-    const enableCode = ((_h = input.options) == null ? void 0 : _h.enableCode) !== false;
-    const enableDevServer = ((_i = input.options) == null ? void 0 : _i.enableDevServer) !== false;
-    const enableTerminal = ((_j = input.options) == null ? void 0 : _j.enableTerminal) ?? false;
-    const oneShot = ((_k = input.options) == null ? void 0 : _k.oneShot) ?? "default";
-    const setArguments = (_l = input.options) == null ? void 0 : _l.setArguments;
-    const executablePath = (_m = input.options) == null ? void 0 : _m.executablePath;
+    const enableClaude = ((_f = input.options) == null ? void 0 : _f.enableClaude) !== false;
+    const enableCode = ((_g = input.options) == null ? void 0 : _g.enableCode) !== false;
+    const enableDevServer = ((_h = input.options) == null ? void 0 : _h.enableDevServer) !== false;
+    const enableTerminal = ((_i = input.options) == null ? void 0 : _i.enableTerminal) ?? false;
+    const oneShot = ((_j = input.options) == null ? void 0 : _j.oneShot) ?? "default";
+    const setArguments = (_k = input.options) == null ? void 0 : _k.setArguments;
+    const executablePath = (_l = input.options) == null ? void 0 : _l.executablePath;
     if (enableClaude || enableCode || enableDevServer || enableTerminal) {
-      const { LoomLauncher } = await import("./LoomLauncher-JF7JZMTZ.js");
-      const { ClaudeContextManager } = await import("./ClaudeContextManager-3VXA6UPR.js");
+      const { LoomLauncher } = await import("./LoomLauncher-ZV3ZZIBA.js");
+      const { ClaudeContextManager } = await import("./ClaudeContextManager-BN7RE5ZQ.js");
       const claudeContext = new ClaudeContextManager(void 0, void 0, this.settings);
       const launcher = new LoomLauncher(claudeContext, this.settings);
       await launcher.launchLoom({
@@ -336,9 +526,25 @@ var LoomManager = class {
         oneShot,
         ...setArguments && { setArguments },
         ...executablePath && { executablePath },
-        sourceEnvOnStart: settingsData.sourceEnvOnStart ?? false
+        sourceEnvOnStart: settingsData.sourceEnvOnStart ?? false,
+        colorTerminal: ((_m = input.options) == null ? void 0 : _m.colorTerminal) ?? ((_n = settingsData.colors) == null ? void 0 : _n.terminal) ?? true,
+        colorHex: colorData.hex
       });
     }
+    const description = (issueData == null ? void 0 : issueData.title) ?? branchName;
+    const issue_numbers = input.type === "issue" ? [String(input.identifier)] : [];
+    const pr_numbers = input.type === "pr" ? [String(input.identifier)] : [];
+    const metadataInput = {
+      description,
+      branchName,
+      worktreePath,
+      issueType: input.type,
+      issue_numbers,
+      pr_numbers,
+      issueTracker: this.issueTracker.providerName,
+      colorHex: colorData.hex
+    };
+    await this.metadataManager.writeMetadata(worktreePath, metadataInput);
     const loom = {
       id: this.generateLoomId(input),
       path: worktreePath,
@@ -346,6 +552,7 @@ var LoomManager = class {
       type: input.type,
       identifier: input.identifier,
       port,
+      description,
       createdAt: /* @__PURE__ */ new Date(),
       lastAccessed: /* @__PURE__ */ new Date(),
       ...databaseBranch !== void 0 && { databaseBranch },
@@ -376,6 +583,9 @@ var LoomManager = class {
    */
   async listLooms() {
     const worktrees = await this.gitWorktree.listWorktrees();
+    if (!worktrees) {
+      return [];
+    }
     return await this.mapWorktreesToLooms(worktrees);
   }
   /**
@@ -420,7 +630,7 @@ var LoomManager = class {
   async checkAndWarnChildLooms(branchName) {
     let targetBranch = branchName;
     if (!targetBranch) {
-      const { getCurrentBranch } = await import("./git-34Z6QVDS.js");
+      const { getCurrentBranch } = await import("./git-IYA53VIC.js");
       targetBranch = await getCurrentBranch();
     }
     if (!targetBranch) {
@@ -543,19 +753,39 @@ var LoomManager = class {
   }
   /**
    * Copy user application environment files (.env) from main repo to worktree
+   * Copies all dotenv-flow patterns: .env, .env.local, .env.{NODE_ENV}, .env.{NODE_ENV}.local
+   * Only copies files that exist and are NOT tracked by git (tracked files exist via worktree)
    * Always called regardless of project capabilities
    */
   async copyEnvironmentFiles(worktreePath) {
-    const envFilePath = path2.join(worktreePath, ".env");
-    try {
-      const mainEnvPath = path2.join(process.cwd(), ".env");
-      if (await fs2.pathExists(envFilePath)) {
-        logger.warn(".env file already exists in worktree, skipping copy");
-      } else {
-        await this.environment.copyIfExists(mainEnvPath, envFilePath);
+    const mainWorkspacePath = this.gitWorktree.workingDirectory;
+    const nodeEnv = process.env.DOTENV_FLOW_NODE_ENV ?? "development";
+    const envFilePatterns = [
+      ".env",
+      ".env.local",
+      `.env.${nodeEnv}`,
+      `.env.${nodeEnv}.local`
+    ];
+    for (const pattern of envFilePatterns) {
+      try {
+        const mainEnvPath = path3.join(mainWorkspacePath, pattern);
+        const worktreeEnvPath = path3.join(worktreePath, pattern);
+        if (!await fs3.pathExists(mainEnvPath)) {
+          continue;
+        }
+        if (await isFileTrackedByGit(pattern, mainWorkspacePath)) {
+          logger.debug(`Skipping ${pattern} (tracked by git, already in worktree)`);
+          continue;
+        }
+        if (await fs3.pathExists(worktreeEnvPath)) {
+          logger.warn(`${pattern} already exists in worktree, skipping copy`);
+          continue;
+        }
+        await this.environment.copyIfExists(mainEnvPath, worktreeEnvPath);
+        logger.debug(`Copied ${pattern} to worktree`);
+      } catch (error) {
+        logger.warn(`Warning: Failed to copy ${pattern}: ${error instanceof Error ? error.message : "Unknown error"}`);
       }
-    } catch (error) {
-      logger.warn(`Warning: Failed to copy main .env file: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
   }
   /**
@@ -565,12 +795,12 @@ var LoomManager = class {
    * @param parentBranchName Optional parent branch name for child looms (sets mainBranch)
    */
   async copyIloomSettings(worktreePath, parentBranchName) {
-    const mainSettingsLocalPath = path2.join(process.cwd(), ".iloom", "settings.local.json");
+    const mainSettingsLocalPath = path3.join(process.cwd(), ".iloom", "settings.local.json");
     try {
-      const worktreeIloomDir = path2.join(worktreePath, ".iloom");
-      await fs2.ensureDir(worktreeIloomDir);
-      const worktreeSettingsLocalPath = path2.join(worktreeIloomDir, "settings.local.json");
-      if (await fs2.pathExists(worktreeSettingsLocalPath)) {
+      const worktreeIloomDir = path3.join(worktreePath, ".iloom");
+      await fs3.ensureDir(worktreeIloomDir);
+      const worktreeSettingsLocalPath = path3.join(worktreeIloomDir, "settings.local.json");
+      if (await fs3.pathExists(worktreeSettingsLocalPath)) {
         logger.warn("settings.local.json already exists in worktree, skipping copy");
       } else {
         await this.environment.copyIfExists(mainSettingsLocalPath, worktreeSettingsLocalPath);
@@ -578,7 +808,7 @@ var LoomManager = class {
       if (parentBranchName) {
         let existingSettings = {};
         try {
-          const content = await fs2.readFile(worktreeSettingsLocalPath, "utf8");
+          const content = await fs3.readFile(worktreeSettingsLocalPath, "utf8");
           existingSettings = JSON.parse(content);
         } catch {
         }
@@ -586,7 +816,7 @@ var LoomManager = class {
           ...existingSettings,
           mainBranch: parentBranchName
         };
-        await fs2.writeFile(worktreeSettingsLocalPath, JSON.stringify(updatedSettings, null, 2));
+        await fs3.writeFile(worktreeSettingsLocalPath, JSON.stringify(updatedSettings, null, 2));
         logger.info(`Set mainBranch to ${parentBranchName} for child loom`);
       }
     } catch (error) {
@@ -598,7 +828,7 @@ var LoomManager = class {
    * Only called when project has web capabilities
    */
   async setupPortForWeb(worktreePath, input, basePort) {
-    const envFilePath = path2.join(worktreePath, ".env");
+    const envFilePath = path3.join(worktreePath, ".env.local");
     const options = { basePort };
     if (input.type === "issue") {
       options.issueNumber = input.identifier;
@@ -655,16 +885,34 @@ var LoomManager = class {
   /**
    * Apply color synchronization to both VSCode and terminal
    * Colors are cosmetic - errors are logged but don't block workflow
+   * Respects colors settings for independent control
+   *
+   * DEFAULTS:
+   * - terminal: true (always safe, only affects macOS Terminal.app)
+   * - vscode: false (safe default, prevents unexpected file modifications)
+   *
+   * @param colorData - Pre-computed color data (from collision avoidance)
    */
-  async applyColorSynchronization(worktreePath, branchName) {
-    const colorData = generateColorFromBranchName(branchName);
-    const vscode = new VSCodeIntegration();
-    await vscode.setTitleBarColor(worktreePath, colorData.hex);
-    logger.info(`Applied VSCode title bar color: ${colorData.hex} for branch: ${branchName}`);
+  async applyColorSynchronization(worktreePath, branchName, colorData, settings, options) {
+    var _a, _b;
+    const colorVscode = (options == null ? void 0 : options.colorVscode) ?? ((_a = settings.colors) == null ? void 0 : _a.vscode) ?? false;
+    const colorTerminal = (options == null ? void 0 : options.colorTerminal) ?? ((_b = settings.colors) == null ? void 0 : _b.terminal) ?? true;
+    if (!colorVscode && !colorTerminal) {
+      logger.debug("Color synchronization disabled for both VSCode and terminal");
+      return;
+    }
+    if (colorVscode) {
+      const vscode = new VSCodeIntegration();
+      await vscode.setTitleBarColor(worktreePath, colorData.hex);
+      logger.info(`Applied VSCode title bar color: ${colorData.hex} for branch: ${branchName}`);
+    } else {
+      logger.debug("VSCode color sync disabled (default: false for safety)");
+    }
   }
   /**
    * Map worktrees to loom objects
    * This is a simplified conversion - in production we'd store loom metadata
+   * Now reads metadata from MetadataManager (spec section 3.2)
    */
   async mapWorktreesToLooms(worktrees) {
     return await Promise.all(worktrees.map(async (wt) => {
@@ -677,6 +925,7 @@ var LoomManager = class {
         type = "pr";
         identifier = parseInt(wt.branch.replace("pr-", ""), 10);
       }
+      const loomMetadata = await this.metadataManager.readMetadata(wt.path);
       return {
         id: `${type}-${identifier}`,
         path: wt.path,
@@ -684,6 +933,7 @@ var LoomManager = class {
         type,
         identifier,
         port: await this.calculatePort({ type, identifier, originalInput: "" }),
+        ...(loomMetadata == null ? void 0 : loomMetadata.description) && { description: loomMetadata.description },
         createdAt: /* @__PURE__ */ new Date(),
         lastAccessed: /* @__PURE__ */ new Date()
       };
@@ -712,7 +962,7 @@ var LoomManager = class {
    * Ports: handle_existing_worktree() from bash script lines 168-215
    */
   async reuseIloom(worktree, input, issueData) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
     const worktreePath = worktree.path;
     const branchName = worktree.branch;
     this.loadMainEnvFile();
@@ -727,6 +977,25 @@ var LoomManager = class {
     }
     logger.info("Database branch assumed to be already configured for existing worktree");
     const databaseBranch = void 0;
+    const existingMetadata = await this.metadataManager.readMetadata(worktreePath);
+    let colorHex;
+    if (existingMetadata == null ? void 0 : existingMetadata.colorHex) {
+      colorHex = existingMetadata.colorHex;
+      logger.debug(`Reusing stored color ${colorHex} for branch ${branchName}`);
+    } else {
+      const colorData = generateColorFromBranchName(branchName);
+      colorHex = colorData.hex;
+      logger.debug(`No stored color, using hash-based color ${colorHex} for branch ${branchName}`);
+    }
+    try {
+      const colorData = { hex: colorHex, rgb: hexToRgb(colorHex), index: 0 };
+      await this.applyColorSynchronization(worktreePath, branchName, colorData, settingsData, input.options);
+    } catch (error) {
+      logger.warn(
+        `Failed to apply color synchronization: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
     if (input.type === "issue") {
       try {
         logger.info("Moving issue to In Progress...");
@@ -749,8 +1018,8 @@ var LoomManager = class {
     const executablePath = (_i = input.options) == null ? void 0 : _i.executablePath;
     if (enableClaude || enableCode || enableDevServer || enableTerminal) {
       logger.info("Launching workspace components...");
-      const { LoomLauncher } = await import("./LoomLauncher-JF7JZMTZ.js");
-      const { ClaudeContextManager } = await import("./ClaudeContextManager-3VXA6UPR.js");
+      const { LoomLauncher } = await import("./LoomLauncher-ZV3ZZIBA.js");
+      const { ClaudeContextManager } = await import("./ClaudeContextManager-BN7RE5ZQ.js");
       const claudeContext = new ClaudeContextManager(void 0, void 0, this.settings);
       const launcher = new LoomLauncher(claudeContext, this.settings);
       await launcher.launchLoom({
@@ -768,9 +1037,27 @@ var LoomManager = class {
         oneShot,
         ...setArguments && { setArguments },
         ...executablePath && { executablePath },
-        sourceEnvOnStart: settingsData.sourceEnvOnStart ?? false
+        sourceEnvOnStart: settingsData.sourceEnvOnStart ?? false,
+        colorTerminal: ((_j = input.options) == null ? void 0 : _j.colorTerminal) ?? ((_k = settingsData.colors) == null ? void 0 : _k.terminal) ?? true,
+        colorHex
       });
     }
+    const description = (existingMetadata == null ? void 0 : existingMetadata.description) ?? (issueData == null ? void 0 : issueData.title) ?? branchName;
+    if (!existingMetadata) {
+      const issue_numbers = input.type === "issue" ? [String(input.identifier)] : [];
+      const pr_numbers = input.type === "pr" ? [String(input.identifier)] : [];
+      const metadataInput = {
+        description,
+        branchName,
+        worktreePath,
+        issueType: input.type,
+        issue_numbers,
+        pr_numbers,
+        issueTracker: this.issueTracker.providerName,
+        colorHex
+      };
+      await this.metadataManager.writeMetadata(worktreePath, metadataInput);
+    }
     const loom = {
       id: this.generateLoomId(input),
       path: worktreePath,
@@ -778,6 +1065,7 @@ var LoomManager = class {
       type: input.type,
       identifier: input.identifier,
       port,
+      description,
       createdAt: /* @__PURE__ */ new Date(),
       // We don't have actual creation date, use now
       lastAccessed: /* @__PURE__ */ new Date(),
@@ -799,7 +1087,7 @@ var LoomManager = class {
 };
 
 // src/lib/EnvironmentManager.ts
-import fs3 from "fs-extra";
+import fs4 from "fs-extra";
 var logger2 = createLogger({ prefix: "\u{1F4DD}" });
 var EnvironmentManager = class {
   constructor() {
@@ -815,15 +1103,15 @@ var EnvironmentManager = class {
     if (!validation.valid) {
       throw new Error(validation.error ?? "Invalid variable name");
     }
-    const fileExists = await fs3.pathExists(filePath);
+    const fileExists = await fs4.pathExists(filePath);
     if (!fileExists) {
       logger2.info(`Creating ${filePath} with ${key}...`);
       const content = formatEnvLine(key, value);
-      await fs3.writeFile(filePath, content, "utf8");
+      await fs4.writeFile(filePath, content, "utf8");
       logger2.success(`${filePath} created with ${key}`);
       return;
     }
-    const existingContent = await fs3.readFile(filePath, "utf8");
+    const existingContent = await fs4.readFile(filePath, "utf8");
     const envMap = parseEnvFile(existingContent);
     let backupPath;
     if (backup) {
@@ -860,7 +1148,7 @@ var EnvironmentManager = class {
       logger2.success(`${key} updated successfully`);
     }
     const newContent = newLines.join("\n");
-    await fs3.writeFile(filePath, newContent, "utf8");
+    await fs4.writeFile(filePath, newContent, "utf8");
     return backupPath;
   }
   /**
@@ -868,7 +1156,7 @@ var EnvironmentManager = class {
    */
   async readEnvFile(filePath) {
     try {
-      const content = await fs3.readFile(filePath, "utf8");
+      const content = await fs4.readFile(filePath, "utf8");
       return parseEnvFile(content);
     } catch (error) {
       logger2.debug(
@@ -891,12 +1179,12 @@ var EnvironmentManager = class {
    * @private
    */
   async copyIfExists(source, destination) {
-    const sourceExists = await fs3.pathExists(source);
+    const sourceExists = await fs4.pathExists(source);
     if (!sourceExists) {
       logger2.debug(`Source file ${source} does not exist, skipping copy`);
       return;
     }
-    await fs3.copy(source, destination, { overwrite: false });
+    await fs4.copy(source, destination, { overwrite: false });
     logger2.success(`Copied ${source} to ${destination}`);
   }
   /**
@@ -957,7 +1245,7 @@ var EnvironmentManager = class {
    */
   async validateEnvFile(filePath) {
     try {
-      const content = await fs3.readFile(filePath, "utf8");
+      const content = await fs4.readFile(filePath, "utf8");
       const envMap = parseEnvFile(content);
       const errors = [];
       for (const [key, value] of envMap.entries()) {
@@ -985,19 +1273,19 @@ var EnvironmentManager = class {
   async createBackup(filePath) {
     const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     const backupPath = `${filePath}${this.backupSuffix}-${timestamp}`;
-    await fs3.copy(filePath, backupPath);
+    await fs4.copy(filePath, backupPath);
     logger2.debug(`Created backup at ${backupPath}`);
     return backupPath;
   }
 };
 
 // src/lib/CLIIsolationManager.ts
-import fs4 from "fs-extra";
-import path3 from "path";
-import os from "os";
+import fs5 from "fs-extra";
+import path4 from "path";
+import os2 from "os";
 var CLIIsolationManager = class {
   constructor() {
-    this.iloomBinDir = path3.join(os.homedir(), ".iloom", "bin");
+    this.iloomBinDir = path4.join(os2.homedir(), ".iloom", "bin");
   }
   /**
    * Setup CLI isolation for a worktree
@@ -1012,7 +1300,7 @@ var CLIIsolationManager = class {
   async setupCLIIsolation(worktreePath, identifier, binEntries) {
     await this.buildProject(worktreePath);
     await this.verifyBinTargets(worktreePath, binEntries);
-    await fs4.ensureDir(this.iloomBinDir);
+    await fs5.ensureDir(this.iloomBinDir);
     const symlinkNames = await this.createVersionedSymlinks(
       worktreePath,
       identifier,
@@ -1042,13 +1330,13 @@ var CLIIsolationManager = class {
    */
   async verifyBinTargets(worktreePath, binEntries) {
     for (const binPath of Object.values(binEntries)) {
-      const targetPath = path3.resolve(worktreePath, binPath);
-      const exists = await fs4.pathExists(targetPath);
+      const targetPath = path4.resolve(worktreePath, binPath);
+      const exists = await fs5.pathExists(targetPath);
       if (!exists) {
         throw new Error(`Bin target does not exist: ${targetPath}`);
       }
       try {
-        await fs4.access(targetPath, fs4.constants.X_OK);
+        await fs5.access(targetPath, fs5.constants.X_OK);
       } catch {
       }
     }
@@ -1064,9 +1352,9 @@ var CLIIsolationManager = class {
     const symlinkNames = [];
     for (const [binName, binPath] of Object.entries(binEntries)) {
       const versionedName = `${binName}-${identifier}`;
-      const targetPath = path3.resolve(worktreePath, binPath);
-      const symlinkPath = path3.join(this.iloomBinDir, versionedName);
-      await fs4.symlink(targetPath, symlinkPath);
+      const targetPath = path4.resolve(worktreePath, binPath);
+      const symlinkPath = path4.join(this.iloomBinDir, versionedName);
+      await fs5.symlink(targetPath, symlinkPath);
       logger.success(`CLI available: ${versionedName}`);
       symlinkNames.push(versionedName);
     }
@@ -1119,12 +1407,12 @@ var CLIIsolationManager = class {
   async cleanupVersionedExecutables(identifier) {
     const removed = [];
     try {
-      const files = await fs4.readdir(this.iloomBinDir);
+      const files = await fs5.readdir(this.iloomBinDir);
       for (const file of files) {
         if (this.matchesIdentifier(file, identifier)) {
-          const symlinkPath = path3.join(this.iloomBinDir, file);
+          const symlinkPath = path4.join(this.iloomBinDir, file);
           try {
-            await fs4.unlink(symlinkPath);
+            await fs5.unlink(symlinkPath);
             removed.push(file);
           } catch (error) {
             const isEnoent = error && typeof error === "object" && "code" in error && error.code === "ENOENT";
@@ -1160,15 +1448,15 @@ var CLIIsolationManager = class {
   async findOrphanedSymlinks() {
     const orphaned = [];
     try {
-      const files = await fs4.readdir(this.iloomBinDir);
+      const files = await fs5.readdir(this.iloomBinDir);
       for (const file of files) {
-        const symlinkPath = path3.join(this.iloomBinDir, file);
+        const symlinkPath = path4.join(this.iloomBinDir, file);
         try {
-          const stats = await fs4.lstat(symlinkPath);
+          const stats = await fs5.lstat(symlinkPath);
           if (stats.isSymbolicLink()) {
-            const target = await fs4.readlink(symlinkPath);
+            const target = await fs5.readlink(symlinkPath);
             try {
-              await fs4.access(target);
+              await fs5.access(target);
             } catch {
               orphaned.push({
                 name: file,
@@ -1203,7 +1491,7 @@ var CLIIsolationManager = class {
     let removedCount = 0;
     for (const symlink of orphaned) {
       try {
-        await fs4.unlink(symlink.path);
+        await fs5.unlink(symlink.path);
         removedCount++;
         logger.success(`Removed orphaned symlink: ${symlink.name}`);
       } catch (error) {
@@ -1229,6 +1517,7 @@ var CLIIsolationManager = class {
 };
 
 // src/lib/DatabaseManager.ts
+import fs6 from "fs-extra";
 var logger3 = createLogger({ prefix: "\u{1F5C2}\uFE0F" });
 var DatabaseManager = class {
   constructor(provider, environment, databaseUrlEnvVarName = "DATABASE_URL") {
@@ -1251,17 +1540,17 @@ var DatabaseManager = class {
    * 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
+   *   2. Any dotenv-flow file contains the configured database URL variable
    */
-  async shouldUseDatabaseBranching(envFilePath) {
+  async shouldUseDatabaseBranching(workspacePath) {
     if (!this.provider.isConfigured()) {
       logger3.debug("Skipping database branching: Database provider not configured");
       return false;
     }
-    const hasDatabaseUrl = await this.hasDatabaseUrlInEnv(envFilePath);
+    const hasDatabaseUrl = await this.hasDatabaseUrlInEnv(workspacePath);
     if (!hasDatabaseUrl) {
       logger3.debug(
-        "Skipping database branching: configured database URL variable not found in .env file"
+        "Skipping database branching: configured database URL variable not found in any env file"
       );
       return false;
     }
@@ -1272,12 +1561,12 @@ var DatabaseManager = class {
    * 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 workspacePath - Path to workspace for configuration checks (checks all dotenv-flow files)
    * @param cwd - Optional working directory to run commands from
    * @param fromBranch - Optional parent branch to create from (for child looms)
    */
-  async createBranchIfConfigured(branchName, envFilePath, cwd, fromBranch) {
-    if (!await this.shouldUseDatabaseBranching(envFilePath)) {
+  async createBranchIfConfigured(branchName, workspacePath, cwd, fromBranch) {
+    if (!await this.shouldUseDatabaseBranching(workspacePath)) {
       return null;
     }
     if (!await this.provider.isCliAvailable()) {
@@ -1404,19 +1693,24 @@ var DatabaseManager = class {
     return null;
   }
   /**
-   * Check if .env has the configured database URL variable
+   * Check if any dotenv-flow file 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
+   * throw an error if it's missing from all env files
    */
-  async hasDatabaseUrlInEnv(envFilePath) {
+  async hasDatabaseUrlInEnv(workspacePath) {
     try {
-      const envMap = await this.environment.readEnvFile(envFilePath);
       if (this.databaseUrlEnvVarName !== "DATABASE_URL") {
         logger3.debug(`Looking for custom database URL variable: ${this.databaseUrlEnvVarName}`);
       } else {
         logger3.debug("Looking for default database URL variable: DATABASE_URL");
       }
-      if (envMap.has(this.databaseUrlEnvVarName)) {
+      const hasConfiguredVar = await hasVariableInAnyEnvFile(
+        workspacePath,
+        this.databaseUrlEnvVarName,
+        async (p) => fs6.pathExists(p),
+        async (p, v) => this.environment.getEnvVariable(p, v)
+      );
+      if (hasConfiguredVar) {
         if (this.databaseUrlEnvVarName !== "DATABASE_URL") {
           logger3.debug(`\u2705 Found custom database URL variable: ${this.databaseUrlEnvVarName}`);
         } else {
@@ -1425,20 +1719,25 @@ var DatabaseManager = class {
         return true;
       }
       if (this.databaseUrlEnvVarName !== "DATABASE_URL") {
-        logger3.debug(`\u274C Custom database URL variable '${this.databaseUrlEnvVarName}' not found in .env file`);
+        logger3.debug(`\u274C Custom database URL variable '${this.databaseUrlEnvVarName}' not found in any env file`);
         throw new Error(
-          `Configured database URL environment variable '${this.databaseUrlEnvVarName}' not found in .env file. Please add it to your .env file or update your iloom configuration.`
+          `Configured database URL environment variable '${this.databaseUrlEnvVarName}' not found in any dotenv-flow file. Please add it to an .env file or update your iloom configuration.`
         );
       }
-      const hasDefaultVar = envMap.has("DATABASE_URL");
+      const hasDefaultVar = await hasVariableInAnyEnvFile(
+        workspacePath,
+        "DATABASE_URL",
+        async (p) => fs6.pathExists(p),
+        async (p, v) => this.environment.getEnvVariable(p, v)
+      );
       if (hasDefaultVar) {
         logger3.debug("\u2705 Found fallback DATABASE_URL variable");
       } else {
-        logger3.debug("\u274C No DATABASE_URL variable found in .env file");
+        logger3.debug("\u274C No DATABASE_URL variable found in any env file");
       }
       return hasDefaultVar;
     } catch (error) {
-      if (error instanceof Error && error.message.includes("not found in .env")) {
+      if (error instanceof Error && error.message.includes("not found in")) {
         throw error;
       }
       return false;
@@ -1447,7 +1746,7 @@ var DatabaseManager = class {
 };
 
 // src/lib/ResourceCleanup.ts
-import path4 from "path";
+import path5 from "path";
 var ResourceCleanup = class {
   constructor(gitWorktree, processManager, database, cliIsolation, settingsManager) {
     this.gitWorktree = gitWorktree;
@@ -1455,6 +1754,7 @@ var ResourceCleanup = class {
     this.database = database;
     this.cliIsolation = cliIsolation;
     this.settingsManager = settingsManager ?? new SettingsManager();
+    this.metadataManager = new MetadataManager();
   }
   /**
    * Cleanup a worktree and associated resources
@@ -1542,7 +1842,7 @@ ${blockerMessage}`);
     }
     let databaseConfig = null;
     if (!options.keepDatabase && worktree) {
-      const envFilePath = path4.join(worktree.path, ".env");
+      const envFilePath = path5.join(worktree.path, ".env");
       try {
         const shouldCleanup = this.database ? await this.database.shouldUseDatabaseBranching(envFilePath) : false;
         databaseConfig = { shouldCleanup, envFilePath };
@@ -1585,6 +1885,8 @@ ${blockerMessage}`);
           success: true,
           message: `Worktree removed: ${worktree.path}`
         });
+        await this.metadataManager.deleteMetadata(worktree.path);
+        logger.debug(`Metadata file cleanup attempted for: ${worktree.path}`);
       } catch (error) {
         const err = error instanceof Error ? error : new Error("Unknown error");
         errors.push(err);
@@ -1845,7 +2147,7 @@ ${blockerMessage}`);
       return false;
     }
     try {
-      const envFilePath = path4.join(worktreePath, ".env");
+      const envFilePath = path5.join(worktreePath, ".env");
       const shouldCleanup = await this.database.shouldUseDatabaseBranching(envFilePath);
       let cwd;
       try {
@@ -1980,10 +2282,11 @@ Please resolve before cleanup - you have some options:
 };
 
 export {
+  MetadataManager,
   LoomManager,
   EnvironmentManager,
   CLIIsolationManager,
   DatabaseManager,
   ResourceCleanup
 };
-//# sourceMappingURL=chunk-HBYZH6GD.js.map
+//# sourceMappingURL=chunk-2IJEMXOB.js.map