worktree-flow 0.0.14 → 0.0.16

package/README.md

@@ -22,9 +22,8 @@ Stop juggling branches across repos. `flow` creates isolated workspaces with git
 ```bash
 npm install -g worktree-flow
 
-# Point flow at your repos and workspace directory
-flow config set source-path ~/repos
-flow config set dest-path ~/workspaces
+# Guided setup wizard
+flow quickstart
 
 # Create a workspace with new branches
 flow branch TICKET-123
@@ -104,7 +103,6 @@ Settings are stored in `~/.config/flow/config.json`.
 |-----|-------------|---------|
 | `source-path` | Directory containing your source repos | *required* |
 | `dest-path` | Directory where workspaces are created | *required* |
-| `main-branch` | Main branch name | `master` |
 | `tmux` | Create tmux sessions with split panes (root + each worktree) | `false` |
 | `copy-files` | Files to copy from source repos to worktrees | `.env` |
 | `post-checkout` | Command to run after checkout (e.g. `npm ci`) | *none* |

package/dist/cli.js

@@ -11,6 +11,7 @@ import { registerStatusCommand } from './commands/status.js';
 import { registerPruneCommand } from './commands/prune.js';
 import { registerFetchCommand } from './commands/fetch.js';
 import { registerTmuxCommand } from './commands/tmux.js';
+import { registerQuickstartCommand } from './commands/quickstart.js';
 const program = new Command();
 program
     .name('flow')
@@ -27,4 +28,5 @@ registerStatusCommand(program);
 registerPruneCommand(program);
 registerFetchCommand(program);
 registerTmuxCommand(program);
+registerQuickstartCommand(program);
 program.parse();

package/dist/commands/branch.js

@@ -1,4 +1,5 @@
-import checkbox from '@inquirer/checkbox';
+import path from 'node:path';
+import checkbox, { Separator } from '@inquirer/checkbox';
 import input from '@inquirer/input';
 import confirm from '@inquirer/confirm';
 import chalk from 'chalk';
@@ -13,10 +14,30 @@ export async function runBranch(branchName, useCases, services, deps) {
         throw new NoReposFoundError(sourcePath);
     }
     // User prompts
+    const choices = services.repos.formatRepoChoices(repos).map((choice) => ({
+        ...choice,
+        checked: config.branchAutoSelectRepos.includes(choice.name),
+    }));
+    const recentlyUsed = new Set(services.fetchCache.getRecentlyUsedRepos(8));
+    const commonlyUsed = choices.filter((c) => recentlyUsed.has(c.name));
+    let checkboxChoices;
+    if (commonlyUsed.length > 0) {
+        const commonlyUsedNames = new Set(commonlyUsed.map((c) => c.name));
+        const remaining = choices.filter((c) => !commonlyUsedNames.has(c.name));
+        checkboxChoices = [
+            new Separator('Recently Used'),
+            ...commonlyUsed,
+            ...(remaining.length > 0 ? [new Separator(), ...remaining] : []),
+        ];
+    }
+    else {
+        checkboxChoices = choices;
+    }
     const selected = await deps.checkbox({
         message: `Select repos for branch "${branchName}":`,
-        choices: services.repos.formatRepoChoices(repos),
+        choices: checkboxChoices,
         pageSize: 20,
+        loop: false,
     });
     if (selected.length === 0) {
         services.console.log('No repos selected.');
@@ -50,6 +71,8 @@ export async function runBranch(branchName, useCases, services, deps) {
         postCheckout: shouldRunPostCheckout ? config.postCheckout : undefined,
         perRepoPostCheckout: shouldRunPostCheckout ? config.perRepoPostCheckout : {},
     });
+    // Track which repos were branched from
+    services.fetchCache.trackBranchUsage(selected.map((r) => path.basename(r)));
     // Display results
     services.console.log(`\nCreated workspace at ${chalk.cyan(result.workspacePath)} with ${result.successCount}/${result.totalCount} repos.`);
     if (result.tmuxCreated) {

package/dist/commands/config.js

@@ -8,7 +8,7 @@ export function registerConfigCommand(program) {
         .description('Manage flow configuration');
     configCmd
         .command('set <key> <value>')
-        .description('Set a config value (source-path, dest-path, copy-files, tmux, main-branch, post-checkout)')
+        .description('Set a config value (source-path, dest-path, copy-files, tmux, post-checkout)')
         .action((key, value) => {
         const services = createServices();
         if (!isValidKey(key)) {
@@ -34,6 +34,7 @@ export function registerConfigCommand(program) {
     });
     configCmd
         .command('list')
+        .alias('ls')
         .description('List all config options and their current values')
         .action(() => {
         const services = createServices();

package/dist/commands/helpers.js

@@ -1,4 +1,52 @@
 import chalk from 'chalk';
+import { StatusService } from '../lib/status.js';
+/**
+ * Format a single repo's status as a display line, consistent across list and status commands.
+ */
+export function formatRepoStatusLine(repoName, status, baseBranch) {
+    const statusMessage = StatusService.getStatusMessage(status, baseBranch);
+    const hasIssues = StatusService.hasIssues(status);
+    const indicator = hasIssues ? chalk.red('✗') : chalk.green('✓');
+    const message = hasIssues ? chalk.red(statusMessage) : chalk.green(statusMessage);
+    const trackingInfo = status.upstreamBranch
+        ? chalk.dim(` → ${status.upstreamBranch}`)
+        : chalk.dim(' (no upstream)');
+    return `    ${indicator} ${chalk.yellow(repoName)}: ${message}${trackingInfo}`;
+}
+/**
+ * Render Phase 1: print a header and workspace rows with a "fetching..." indicator.
+ * Returns the number of lines printed so the caller can clear them later.
+ */
+export function logStatusFetching(header, workspaces, console) {
+    console.log(chalk.bold(`\n${header}`));
+    for (const ws of workspaces) {
+        const repoCount = chalk.dim(`(${ws.repoCount} repo${ws.repoCount === 1 ? '' : 's'})`);
+        console.log(`  ${chalk.cyan(ws.name)} ${repoCount} ${chalk.dim('fetching...')}`);
+    }
+    console.log('');
+    // blank line + header + N workspace lines + trailing blank
+    return workspaces.length + 3;
+}
+/**
+ * Render Phase 2: clear the Phase 1 lines then print the header and full workspace status.
+ */
+export function logStatus(header, workspaces, linesToClear, getBaseBranch, console) {
+    for (let i = 0; i < linesToClear; i++) {
+        console.write('\x1b[1A'); // Move cursor up one line
+        console.write('\x1b[2K'); // Clear entire line
+    }
+    console.log(chalk.bold(`\n${header}`));
+    for (const workspace of workspaces) {
+        const activeIndicator = workspace.isActive ? chalk.green('* ') : '  ';
+        const repoCount = chalk.dim(`(${workspace.repoCount} repo${workspace.repoCount === 1 ? '' : 's'})`);
+        console.log(`${activeIndicator}${chalk.cyan(workspace.name)} ${repoCount}`);
+        for (const { repoName, status } of workspace.statuses) {
+            const baseBranch = getBaseBranch(workspace.path, repoName);
+            console.log(formatRepoStatusLine(repoName, status, baseBranch));
+        }
+        console.log('');
+    }
+}
 /**
  * Get a human-readable status indicator for a workspace based on its worktree statuses.
  */

package/dist/commands/list.js

@@ -1,7 +1,6 @@
-import chalk from 'chalk';
 import { createServices } from '../lib/services.js';
 import { createUseCases } from '../usecases/usecases.js';
-import { StatusService } from '../lib/status.js';
+import { logStatusFetching, logStatus } from './helpers.js';
 export async function runList(useCases, services) {
     const { destPath, sourcePath } = services.config.getRequired();
     const config = services.config.load();
@@ -13,12 +12,7 @@ export async function runList(useCases, services) {
         return;
     }
     // Phase 1: Show basic list immediately
-    services.console.log(chalk.bold('\nWorkspaces:'));
-    for (const workspace of basicWorkspaces) {
-        const repoCount = chalk.dim(`(${workspace.repoCount} repo${workspace.repoCount === 1 ? '' : 's'})`);
-        services.console.log(`  ${chalk.cyan(workspace.name)} ${repoCount} ${chalk.dim('fetching...')}`);
-    }
-    services.console.log('');
+    const loadingLines = logStatusFetching('Workspaces:', basicWorkspaces, services.console);
     // Phase 2: Fetch repos used across all workspaces
     await useCases.fetchUsedRepos.execute({
         destPath,
@@ -32,39 +26,8 @@ export async function runList(useCases, services) {
         sourcePath,
         cwd,
     });
-    // Phase 4: Clear previous output and re-print with status
-    // Lines to clear:
-    // - 2 lines from '\nWorkspaces:' (blank line + header)
-    // - N workspace lines
-    // - 1 empty line after workspaces
-    const linesToClear = 2 + basicWorkspaces.length + 1;
-    for (let i = 0; i < linesToClear; i++) {
-        services.console.write('\x1b[1A'); // Move cursor up one line
-        services.console.write('\x1b[2K'); // Clear entire line
-    }
-    // Re-print with full status information
-    services.console.log(chalk.bold('\nWorkspaces:'));
-    for (const workspace of result.workspaces) {
-        const activeIndicator = workspace.isActive ? chalk.green('* ') : '  ';
-        const repoCount = chalk.dim(`(${workspace.repoCount} repo${workspace.repoCount === 1 ? '' : 's'})`);
-        services.console.log(`${activeIndicator}${chalk.cyan(workspace.name)} ${repoCount}`);
-        // Load workspace config to get per-repo base branches
-        const workspaceConfig = services.workspaceConfig.load(workspace.path);
-        const getBaseBranch = (repoName) => workspaceConfig.baseBranches[repoName] || 'master';
-        // Display each repo with its status and tracking branch
-        for (const { repoName, status } of workspace.statuses) {
-            const baseBranch = getBaseBranch(repoName);
-            const statusMessage = StatusService.getStatusMessage(status, baseBranch);
-            const hasIssues = StatusService.hasIssues(status);
-            const indicator = hasIssues ? chalk.red('✗') : chalk.green('✓');
-            const message = hasIssues ? chalk.red(statusMessage) : chalk.green(statusMessage);
-            const trackingInfo = status.upstreamBranch
-                ? chalk.dim(` → ${status.upstreamBranch}`)
-                : chalk.dim(' (no upstream)');
-            services.console.log(`    ${indicator} ${chalk.yellow(repoName)}: ${message}${trackingInfo}`);
-        }
-        services.console.log(''); // Blank line between workspaces
-    }
+    // Phase 4: Clear previous output and re-print with full status
+    logStatus('Workspaces:', result.workspaces, loadingLines, (wsPath, repoName) => services.workspaceConfig.load(wsPath).baseBranches[repoName] || 'master', services.console);
 }
 export function registerListCommand(program) {
     program

package/dist/commands/quickstart.js

@@ -0,0 +1,161 @@
+import os from 'node:os';
+import path from 'node:path';
+import input from '@inquirer/input';
+import chalk from 'chalk';
+import { createServices } from '../lib/services.js';
+import { NodeShell } from '../adapters/node.js';
+const DIVIDER = chalk.dim('  ─────────────────────────────────────────────────');
+const DEFAULT_DEST_PATH = '~/dev/workspaces';
+const MAX_NAMES_SHOWN = 3;
+function expandTilde(p) {
+    return p.replace(/^~/, os.homedir());
+}
+function summariseNames(names, noun) {
+    const count = names.length;
+    if (count === 0)
+        return `no ${noun}s found`;
+    const shown = names.slice(0, MAX_NAMES_SHOWN).join(', ');
+    if (count <= MAX_NAMES_SHOWN)
+        return `${count} ${count === 1 ? noun : noun + 's'}: ${shown}`;
+    return `${count} ${noun}s including ${shown}`;
+}
+async function isTmuxInstalled(shell) {
+    try {
+        await shell.execFile('which', ['tmux']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runQuickstart(services, deps) {
+    const existing = services.config.loadRaw();
+    services.console.log('');
+    services.console.log(chalk.bold('  Welcome to flow!'));
+    services.console.log('');
+    services.console.log('  flow creates isolated workspaces with git worktrees across multiple');
+    services.console.log('  repos — work on a feature branch in all your repos at once.');
+    services.console.log('');
+    services.console.log(DIVIDER);
+    services.console.log(chalk.bold('  Required'));
+    services.console.log(DIVIDER);
+    services.console.log('');
+    // Loop until user provides a source path that contains git repositories
+    services.console.log(chalk.dim('  Source directory containing your repos (e.g. ~/dev)'));
+    let sourcePath;
+    while (true) {
+        const sourcePathRaw = await deps.input({
+            message: 'Where are your git repositories?',
+            default: existing['source-path'] ?? '',
+            prefill: 'editable',
+        });
+        const resolved = path.resolve(expandTilde(sourcePathRaw));
+        try {
+            const repos = services.repos.discoverRepos(resolved);
+            if (repos.length === 0) {
+                services.console.log(chalk.yellow('  ⚠ No git repositories found — please try a different path \n'));
+                continue;
+            }
+            const names = repos.map(r => path.basename(r));
+            services.console.log(chalk.dim(`  Found ${summariseNames(names, 'repository')}`));
+            sourcePath = resolved;
+            break;
+        }
+        catch (err) {
+            const msg = err.code === 'ENOENT'
+                ? '  ⚠ Directory not found — please try again \n'
+                : '  ⚠ Could not read directory — please try again \n';
+            services.console.log(chalk.yellow(msg));
+        }
+    }
+    services.console.log('');
+    services.console.log(chalk.dim('  Each branch gets its own folder here — should be an empty directory (e.g. ~/dev/workspaces)'));
+    const destPathRaw = await deps.input({
+        message: 'Where should workspaces be created?',
+        default: existing['dest-path'] ?? DEFAULT_DEST_PATH,
+        prefill: 'editable',
+    });
+    const destPath = path.resolve(expandTilde(destPathRaw));
+    const workspaces = services.workspaceDir.listWorkspaces(destPath);
+    if (workspaces.length > 0) {
+        const names = workspaces.map(w => w.name);
+        services.console.log(chalk.dim(`  Found ${summariseNames(names, 'workspace')}`));
+    }
+    services.console.log('');
+    services.console.log(DIVIDER);
+    services.console.log(chalk.bold('  Optional') + chalk.dim('  (press Enter to skip)'));
+    services.console.log(DIVIDER);
+    services.console.log('');
+    services.console.log(chalk.dim('  Runs in each worktree after a workspace is created'));
+    const postCheckout = await deps.input({
+        message: 'Post-checkout command?',
+        default: existing['post-checkout'] ?? '',
+        prefill: 'editable',
+    });
+    let tmuxEnabled = existing['tmux'] === 'true';
+    const tmuxAvailable = await isTmuxInstalled(deps.shell);
+    if (tmuxAvailable) {
+        services.console.log('');
+        services.console.log(chalk.dim('  Opens a tmux session with split panes, one per worktree'));
+        const tmuxRaw = await deps.input({
+            message: 'Enable tmux integration (yes/no)?',
+            default: existing['tmux'] === 'true' ? 'yes' : 'no',
+            prefill: 'editable',
+        });
+        tmuxEnabled = /^(y|yes)$/i.test(tmuxRaw.trim());
+    }
+    // All-or-nothing save — only reached if all prompts complete without throwing
+    const newConfig = {
+        ...existing,
+        'source-path': sourcePath,
+        'dest-path': destPath,
+        'tmux': tmuxEnabled ? 'true' : 'false',
+    };
+    if (postCheckout) {
+        newConfig['post-checkout'] = postCheckout;
+    }
+    else {
+        delete newConfig['post-checkout'];
+    }
+    services.config.saveRaw(newConfig);
+    // Summary
+    services.console.log('');
+    services.console.log(DIVIDER);
+    services.console.log('');
+    services.console.log(chalk.green('  ✓ Configuration saved!'));
+    services.console.log('');
+    services.console.log(`    ${chalk.cyan('source-path')}    ${sourcePath}`);
+    services.console.log(`    ${chalk.cyan('dest-path')}      ${destPath}`);
+    if (postCheckout) {
+        services.console.log(`    ${chalk.cyan('post-checkout')}  ${postCheckout}`);
+    }
+    services.console.log(`    ${chalk.cyan('tmux')}           ${tmuxEnabled}`);
+    services.console.log('');
+    services.console.log(chalk.bold('  Get started:'));
+    services.console.log('');
+    services.console.log(`    ${chalk.cyan('flow branch my-feature')}     Create a new branch across repos`);
+    services.console.log(`    ${chalk.cyan('flow checkout my-feature')}   Checkout an existing branch`);
+    services.console.log(`    ${chalk.cyan('flow list')}                  See all your workspaces`);
+    services.console.log('');
+    services.console.log(chalk.dim('  Run `flow config list` to see all settings.'));
+    services.console.log('');
+}
+export function registerQuickstartCommand(program) {
+    program
+        .command('quickstart')
+        .description('Interactive setup wizard for first-time configuration')
+        .action(async () => {
+        const services = createServices();
+        try {
+            await runQuickstart(services, { input, shell: new NodeShell() });
+        }
+        catch (error) {
+            // Suppress ExitPromptError — user Ctrl-C'd a prompt, exit silently
+            if (error?.name === 'ExitPromptError') {
+                return;
+            }
+            services.console.error(error.message);
+            services.process.exit(1);
+        }
+    });
+}

package/dist/commands/status.js

@@ -1,48 +1,35 @@
-import chalk from 'chalk';
+import path from 'node:path';
 import { createServices } from '../lib/services.js';
 import { createUseCases } from '../usecases/usecases.js';
-import { StatusService } from '../lib/status.js';
 import { resolveWorkspace } from '../lib/workspaceResolver.js';
+import { logStatusFetching, logStatus } from './helpers.js';
 export async function runStatus(branchName, useCases, services) {
     const { sourcePath } = services.config.getRequired();
     const config = services.config.load();
     const { workspacePath } = resolveWorkspace(branchName, services.workspaceDir, services.config, services.process);
-    services.console.log(`Workspace: ${chalk.cyan(workspacePath)}`);
     const worktreeDirs = services.workspaceDir.getWorktreeDirs(workspacePath);
     if (worktreeDirs.length === 0) {
         services.console.log('\nNo worktrees found in workspace.');
         return;
     }
+    const workspaceName = path.basename(workspacePath);
+    const repoCount = worktreeDirs.length;
+    // Phase 1: Show header with fetching indicator
+    const loadingLines = logStatusFetching('Workspace:', [{ name: workspaceName, repoCount }], services.console);
     // Fetch workspace repos
     await useCases.fetchWorkspaceRepos.execute({
         workspacePath,
         sourcePath,
         fetchCacheTtlSeconds: config.fetchCacheTtlSeconds,
+        silent: true,
     });
-    services.console.log('');
-    services.console.log(`\nStatus:\n`);
     const result = await useCases.checkWorkspaceStatus.execute({
         workspacePath,
     });
     // Load workspace config to get per-repo base branches
     const workspaceConfig = services.workspaceConfig.load(workspacePath);
-    const getBaseBranch = (repoName) => workspaceConfig.baseBranches[repoName] || 'master';
-    let cleanCount = 0;
-    let issuesCount = 0;
-    for (const { repoName, status } of result.statuses) {
-        const baseBranch = getBaseBranch(repoName);
-        const message = StatusService.getStatusMessage(status, baseBranch);
-        if (StatusService.hasIssues(status)) {
-            services.console.log(`  ${chalk.red('✗')} ${repoName}: ${chalk.red(message)}`);
-            issuesCount++;
-        }
-        else {
-            services.console.log(`  ${chalk.green('✓')} ${repoName}: ${chalk.green(message)}`);
-            cleanCount++;
-        }
-    }
-    services.console.log('');
-    services.console.log(`Summary: ${chalk.green(`${cleanCount} up to date`)}, ${issuesCount > 0 ? chalk.red(`${issuesCount} with issues`) : chalk.green('0 with issues')}`);
+    // Phase 2: Clear Phase 1 lines and re-render with full status
+    logStatus('Workspace:', [{ name: workspaceName, path: workspacePath, repoCount, isActive: false, statuses: result.statuses }], loadingLines, (_, repoName) => workspaceConfig.baseBranches[repoName] || 'master', services.console);
 }
 export function registerStatusCommand(program) {
     program

package/dist/lib/config.js

@@ -11,6 +11,7 @@ const RawConfigSchema = z.object({
     'post-checkout': z.string().optional(),
     'fetch-cache-ttl-seconds': z.string().optional(),
     'per-repo-post-checkout': z.record(z.string(), z.string()).optional(),
+    'branch-auto-select-repos': z.string().optional(),
 });
 // Parsed config schema (with proper types)
 const ParsedConfigSchema = z.object({
@@ -21,6 +22,7 @@ const ParsedConfigSchema = z.object({
     postCheckout: z.string().optional(),
     fetchCacheTtlSeconds: z.number().default(300),
     perRepoPostCheckout: z.record(z.string(), z.string()).default({}),
+    branchAutoSelectRepos: z.array(z.string()).default([]),
 });
 // Required config schema (for getRequired)
 const RequiredConfigSchema = z.object({
@@ -38,8 +40,9 @@ const ConfigValueSchemas = {
         const num = parseInt(val, 10);
         return !isNaN(num) && num >= 0;
     }, { message: 'Must be a non-negative integer' }),
+    'branch-auto-select-repos': z.string(),
 };
-export const CONFIG_KEYS = ['source-path', 'dest-path', 'copy-files', 'tmux', 'post-checkout', 'fetch-cache-ttl-seconds'];
+export const CONFIG_KEYS = ['source-path', 'dest-path', 'copy-files', 'tmux', 'post-checkout', 'fetch-cache-ttl-seconds', 'branch-auto-select-repos'];
 /**
  * Pure utility functions (no I/O)
  */
@@ -88,6 +91,9 @@ export class ConfigService {
                 ? parseInt(raw['fetch-cache-ttl-seconds'], 10)
                 : undefined,
             perRepoPostCheckout: raw['per-repo-post-checkout'],
+            branchAutoSelectRepos: raw['branch-auto-select-repos']
+                ? raw['branch-auto-select-repos'].split(',').map((s) => s.trim()).filter(Boolean)
+                : undefined,
         });
     }
     getRequired() {
@@ -134,6 +140,10 @@ export class ConfigService {
                 value: raw['fetch-cache-ttl-seconds'] ?? `${config.fetchCacheTtlSeconds} (default)`,
                 isDefault: !raw['fetch-cache-ttl-seconds'],
             },
+            'branch-auto-select-repos': {
+                value: raw['branch-auto-select-repos'] ?? '(not set)',
+                isDefault: !raw['branch-auto-select-repos'],
+            },
             perRepoPostCheckout: config.perRepoPostCheckout,
         };
     }

package/dist/lib/fetchCache.js

@@ -15,7 +15,7 @@ export class FetchCacheService {
             return true; // Caching disabled
         }
         const cache = this.loadCache();
-        const cachedTimestamp = cache[repoPath];
+        const cachedTimestamp = cache.fetchTimestamps[repoPath];
         if (!cachedTimestamp) {
             return true; // Cache miss
         }
@@ -31,7 +31,7 @@ export class FetchCacheService {
     markFetched(repoPath) {
         try {
             const cache = this.loadCache();
-            cache[repoPath] = Date.now();
+            cache.fetchTimestamps[repoPath] = Date.now();
             this.saveCache(cache);
         }
         catch (error) {
@@ -48,18 +48,58 @@ export class FetchCacheService {
     filterReposToFetch(repoPaths, ttlSeconds) {
         return repoPaths.filter(repoPath => this.shouldFetch(repoPath, ttlSeconds));
     }
+    /**
+     * Record that a branch was created from these repos (appends raw events)
+     * @param repoNames Array of repository names (basenames)
+     */
+    trackBranchUsage(repoNames) {
+        try {
+            const cache = this.loadCache();
+            const date = new Date().toISOString();
+            for (const repo of repoNames) {
+                cache.branchRepoUsage.push({ repo, date });
+            }
+            this.saveCache(cache);
+        }
+        catch (error) {
+            // Don't block operations on cache write errors
+            console.warn('Warning: Failed to update branch usage cache:', error);
+        }
+    }
+    /**
+     * Get the most recently used repo names, derived from raw events
+     * @param limit Maximum number of repos to return
+     * @returns Repo names sorted by most recent usage, descending
+     */
+    getRecentlyUsedRepos(limit) {
+        const events = this.loadCache().branchRepoUsage;
+        const latestByRepo = new Map();
+        for (const event of events) {
+            const existing = latestByRepo.get(event.repo);
+            if (!existing || event.date > existing) {
+                latestByRepo.set(event.repo, event.date);
+            }
+        }
+        return [...latestByRepo.entries()]
+            .sort((a, b) => b[1].localeCompare(a[1]))
+            .slice(0, limit)
+            .map(([repo]) => repo);
+    }
     /**
      * Load cache from disk
-     * @returns Cache data object
      */
     loadCache() {
         const cachePath = this.getFetchCachePath();
         try {
             if (!this.fs.existsSync(cachePath)) {
-                return {};
+                return { fetchTimestamps: {}, branchRepoUsage: [] };
             }
             const content = this.fs.readFileSync(cachePath, 'utf-8');
-            return JSON.parse(content);
+            const parsed = JSON.parse(content);
+            return {
+                fetchTimestamps: parsed.fetchTimestamps ?? {},
+                branchRepoUsage: parsed.branchRepoUsage ?? [],
+            };
         }
         catch (error) {
             // Corrupted cache - delete and start fresh
@@ -70,12 +110,11 @@ export class FetchCacheService {
             catch {
                 // Ignore errors deleting corrupted cache
             }
-            return {};
+            return { fetchTimestamps: {}, branchRepoUsage: [] };
         }
     }
     /**
      * Save cache to disk
-     * @param cache Cache data to save
      */
     saveCache(cache) {
         const cachePath = this.getFetchCachePath();
@@ -88,10 +127,9 @@ export class FetchCacheService {
     }
     /**
      * Get path to fetch cache file
-     * @returns Absolute path to ~/.config/flow/fetch-cache.json
      */
     getFetchCachePath() {
         const home = process.env.HOME || process.env.USERPROFILE || '';
-        return path.join(home, '.config', 'flow', 'fetch-cache.json');
+        return path.join(home, '.config', 'flow', 'flow-cache.json');
     }
 }

package/dist/lib/workspaceConfig.js

@@ -29,10 +29,18 @@ export class WorkspaceConfigService {
         const parsed = JSON.parse(raw);
         return WorkspaceConfigSchema.parse(parsed);
     }
+    savePlaceholder(workspacePath) {
+        const configPath = this.getConfigPath(workspacePath);
+        this.fs.writeFileSync(configPath, JSON.stringify({ baseBranches: {} }, null, 2) + '\n');
+    }
     save(workspacePath, config) {
         const configPath = this.getConfigPath(workspacePath);
         const validated = WorkspaceConfigSchema.parse(config);
-        this.fs.writeFileSync(configPath, JSON.stringify(validated, null, 2) + '\n');
+        const existing = this.load(workspacePath);
+        const merged = {
+            baseBranches: { ...existing.baseBranches, ...validated.baseBranches },
+        };
+        this.fs.writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n');
     }
     getBaseBranch(workspacePath, repoName) {
         const config = this.load(workspacePath);

package/dist/lib/workspaceDirectory.js

@@ -39,8 +39,16 @@ export class WorkspaceDirectoryService {
         if (!this.fs.existsSync(workspacePath)) {
             return null;
         }
+        const configPath = path.join(workspacePath, 'flow-config.json');
+        if (!this.fs.existsSync(configPath)) {
+            return null;
+        }
         return workspacePath;
     }
+    /**
+     * Returns the paths of git worktrees (repos) inside a workspace directory.
+     * @example getWorktreeDirs('/workspaces/feature-123') → ['/workspaces/feature-123/repo-a', ...]
+     */
     getWorktreeDirs(workspacePath) {
         const entries = this.fs.readdirSync(workspacePath, { withFileTypes: true });
         return entries
@@ -54,13 +62,22 @@ export class WorkspaceDirectoryService {
         })
             .map((entry) => path.join(workspacePath, entry.name));
     }
+    /**
+     * Returns all workspaces under destPath, identified by the presence of flow-config.json.
+     * @example listWorkspaces('/workspaces') → [{ name: 'feature-123', path: '...', repoCount: 2 }, ...]
+     */
     listWorkspaces(destPath) {
         if (!this.fs.existsSync(destPath)) {
             return [];
         }
         const entries = this.fs.readdirSync(destPath, { withFileTypes: true });
         return entries
-            .filter((entry) => entry.isDirectory())
+            .filter((entry) => {
+            if (!entry.isDirectory())
+                return false;
+            const configPath = path.join(destPath, entry.name, 'flow-config.json');
+            return this.fs.existsSync(configPath);
+        })
             .map((entry) => {
             const workspacePath = path.join(destPath, entry.name);
             try {
@@ -75,7 +92,7 @@ export class WorkspaceDirectoryService {
                 return null;
             }
         })
-            .filter((ws) => ws !== null && ws.repoCount > 0);
+            .filter((ws) => ws !== null);
     }
     removeWorkspaceDir(workspacePath) {
         this.fs.rmSync(workspacePath, { recursive: true, force: true });

package/dist/usecases/checkoutWorkspace.js

@@ -37,6 +37,7 @@ export class CheckoutWorkspaceUseCase {
         }
         // 3. Create workspace directory
         const workspacePath = this.workspaceDir.createWorkspaceDir(params.destPath, params.branchName);
+        this.workspaceConfig.savePlaceholder(workspacePath);
         // 4. Create worktrees in parallel
         const successCount = await this.parallel.processInParallel(matching, (repoPath) => RepoService.getRepoName(repoPath), async (repoPath) => {
             const name = RepoService.getRepoName(repoPath);

package/dist/usecases/createBranchWorkspace.js

@@ -26,6 +26,7 @@ export class CreateBranchWorkspaceUseCase {
     async execute(params) {
         // 1. Create workspace directory
         const workspacePath = this.workspaceDir.createWorkspaceDir(params.destPath, params.branchName);
+        this.workspaceConfig.savePlaceholder(workspacePath);
         // Track base branches for each repo
         const baseBranches = {};
         // 2. Create worktrees in parallel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-flow",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Manage git worktrees across a poly-repo environment",
   "type": "module",
   "bin": {