worktree-flow 0.0.1

package/README.md

@@ -0,0 +1,156 @@
+# worktree-flow
+
+Manage git worktrees across a poly-repo environment.
+
+## What is worktree-flow?
+
+`flow` helps you work on multi-repo features by creating isolated workspace directories with git worktrees. Instead of switching branches across multiple repositories manually, flow creates a workspace folder containing worktrees for all relevant repos on the same branch.
+
+**Before:**
+```
+~/repos/
+├── AGENTS.md
+├── my-api-1/          (main branch)
+├── my-api-2/          (main branch)
+└── my-client/         (main branch)
+```
+
+**After running `flow branch TICKET-123`:**
+```
+~/workspaces/TICKET-123/
+├── AGENTS.md          (copied from ~/repos)
+├── my-api-1/          (TICKET-123 branch - new worktree)
+└── my-client/         (TICKET-123 branch - new worktree)
+```
+
+## Installation
+
+```bash
+npm install -g worktree-flow
+```
+
+Or install locally:
+
+```bash
+npm install worktree-flow
+npm link
+```
+
+## Configuration
+
+Set the paths where your repos live and where workspaces should be created:
+
+```bash
+flow config set source-path ~/repos
+flow config set dest-path ~/workspaces
+```
+
+Optional configuration:
+
+```bash
+# Set the main branch name (default: master)
+flow config set main-branch main
+
+# Enable tmux session creation (default: false)
+flow config set tmux true
+
+# Set config files to copy to worktrees (default: .env)
+flow config set copy-files .env,.env.local
+
+# Set command to run after checkout/branching (optional, prompts if set)
+flow config set post-checkout "npm ci"
+```
+
+Configuration is stored in `~/.config/flow/config.json`.
+
+## Usage
+
+### Create a new branch across repos
+
+Interactively select which repos to branch:
+
+```bash
+flow branch TICKET-123
+```
+
+Use spacebar to select repos, enter to confirm. Creates new branches and worktrees.
+
+If you've configured a post-checkout command, flow will prompt you to run it in all workspaces in parallel. This is useful for tasks like installing dependencies after branching.
+
+### Checkout an existing branch
+
+Automatically detects which repos have the branch:
+
+```bash
+flow checkout TICKET-123
+```
+
+Fetches all repos and creates worktrees for repos that have the branch.
+
+If you've configured a post-checkout command, flow will prompt you to run it in all workspaces in parallel. This is useful for tasks like installing dependencies after switching branches.
+
+### Pull changes in a workspace
+
+From anywhere inside a workspace directory:
+
+```bash
+cd ~/workspaces/TICKET-123
+flow pull
+```
+
+Pulls latest changes for all repos in the workspace.
+
+### Push changes in a workspace
+
+From anywhere inside a workspace directory:
+
+```bash
+cd ~/workspaces/TICKET-123/my-api-1
+flow push
+```
+
+Pushes all repos in the workspace. Automatically sets upstream on first push.
+
+### Check workspace status
+
+Check the status of all repos in a workspace:
+
+```bash
+flow status TICKET-123
+```
+
+Fetches latest changes from remote, then shows which repos have:
+- Uncommitted changes
+- Commits ahead of the main branch
+- Are up to date
+
+This helps you quickly see what needs attention before removing a workspace.
+
+### Remove a workspace
+
+Remove a workspace and all its worktrees:
+
+```bash
+flow remove TICKET-123
+```
+
+This command will:
+1. Fetch latest changes from remote
+2. Check all worktrees for uncommitted changes and changes ahead of main (diff against configured main branch)
+3. Abort if any uncommitted changes or commits ahead of main are found
+4. Show what will be removed and ask for confirmation (y/n)
+5. Remove all worktrees from their source repos
+6. Delete the workspace folder
+7. Kill the tmux session (if tmux is enabled)
+
+The "ahead of main" check compares your branch against the configured main branch (default: `master`) to detect actual code differences, so it's safe to remove branches even after they've been squash-merged and the remote branch deleted.
+
+Use this to clean up when you're done with a branch.
+
+## AGENTS.md
+
+If an `AGENTS.md` file exists at the root of your source-path, it will be copied to each workspace root.
+
+## License
+
+MIT

package/dist/adapters/node.js

@@ -0,0 +1,61 @@
+/**
+ * Production adapters using real Node.js APIs.
+ */
+import fs from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export class NodeFileSystem {
+    existsSync(path) {
+        return fs.existsSync(path);
+    }
+    readFileSync(path, encoding) {
+        return fs.readFileSync(path, encoding);
+    }
+    writeFileSync(path, content) {
+        fs.writeFileSync(path, content);
+    }
+    mkdirSync(path, options) {
+        fs.mkdirSync(path, options);
+    }
+    readdirSync(path, options) {
+        return fs.readdirSync(path, options);
+    }
+    copyFileSync(src, dest) {
+        fs.copyFileSync(src, dest);
+    }
+    rmSync(path, options) {
+        fs.rmSync(path, options);
+    }
+}
+export class NodeShell {
+    async execFile(command, args, options) {
+        const result = await execFileAsync(command, args, {
+            ...options,
+            encoding: options?.encoding || 'utf-8',
+        });
+        return {
+            stdout: result.stdout.trim(),
+            stderr: result.stderr.trim(),
+        };
+    }
+}
+export class NodeConsole {
+    log(message) {
+        console.log(message);
+    }
+    error(message) {
+        console.error(message);
+    }
+    write(message) {
+        process.stdout.write(message);
+    }
+}
+export class NodeProcess {
+    exit(code) {
+        process.exit(code);
+    }
+    cwd() {
+        return process.cwd();
+    }
+}

package/dist/adapters/types.js

@@ -0,0 +1,5 @@
+/**
+ * Adapter interfaces for I/O operations.
+ * These abstractions allow business logic to be tested without real I/O.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerConfigCommand } from './commands/config.js';
+import { registerBranchCommand } from './commands/branch.js';
+import { registerCheckoutCommand } from './commands/checkout.js';
+import { registerListCommand } from './commands/list.js';
+import { registerPullCommand } from './commands/pull.js';
+import { registerPushCommand } from './commands/push.js';
+import { registerRemoveCommand } from './commands/remove.js';
+import { registerStatusCommand } from './commands/status.js';
+import { registerPruneCommand } from './commands/prune.js';
+const program = new Command();
+program
+    .name('flow')
+    .description('Manage git worktrees across a poly-repo environment')
+    .version('0.1.0');
+registerConfigCommand(program);
+registerBranchCommand(program);
+registerCheckoutCommand(program);
+registerListCommand(program);
+registerPullCommand(program);
+registerPushCommand(program);
+registerRemoveCommand(program);
+registerStatusCommand(program);
+registerPruneCommand(program);
+program.parse();

package/dist/commands/branch.js

@@ -0,0 +1,76 @@
+import checkbox from '@inquirer/checkbox';
+import input from '@inquirer/input';
+import confirm from '@inquirer/confirm';
+import chalk from 'chalk';
+import { createServices } from '../lib/services.js';
+import { createUseCases } from '../usecases/usecases.js';
+import { NoReposFoundError } from '../lib/errors.js';
+export async function runBranch(branchName, useCases, services, deps) {
+    const { sourcePath, destPath } = services.config.getRequired();
+    const config = services.config.load();
+    const repos = services.repos.discoverRepos(sourcePath);
+    if (repos.length === 0) {
+        throw new NoReposFoundError(sourcePath);
+    }
+    // User prompts
+    const selected = await deps.checkbox({
+        message: `Select repos for branch "${branchName}":`,
+        choices: services.repos.formatRepoChoices(repos),
+        pageSize: 20,
+    });
+    if (selected.length === 0) {
+        services.console.log('No repos selected.');
+        return;
+    }
+    const sourceBranch = await deps.input({
+        message: 'Branch from which branch?',
+        default: 'master',
+    });
+    let shouldRunPostCheckout = false;
+    if (config.postCheckout) {
+        shouldRunPostCheckout = await deps.confirm({
+            message: `Run "${config.postCheckout}" in all workspaces?`,
+            default: true,
+        });
+    }
+    services.console.log('\nCreating workspace...');
+    // Execute use case
+    const result = await useCases.createBranchWorkspace.execute({
+        repos: selected,
+        branchName,
+        sourceBranch,
+        sourcePath,
+        destPath,
+        copyFiles: config.copyFiles,
+        tmux: config.tmux,
+        postCheckout: shouldRunPostCheckout ? config.postCheckout : undefined,
+    });
+    // Display results
+    services.console.log(`\nCreated workspace at ${chalk.cyan(result.workspacePath)} with ${result.successCount}/${result.totalCount} repos.`);
+    if (result.tmuxCreated) {
+        services.console.log(`Created tmux session: ${chalk.cyan(branchName)}`);
+    }
+    if (result.postCheckoutSuccess !== undefined) {
+        services.console.log(`\nCompleted post-checkout in ${result.postCheckoutSuccess}/${result.postCheckoutTotal} workspace(s).`);
+    }
+    else if (!config.postCheckout) {
+        services.console.log('\nTip: Configure a post-checkout command to run automatically after branching/checkout.');
+        services.console.log('  Example: flow config set post-checkout "npm ci"');
+    }
+}
+export function registerBranchCommand(program) {
+    program
+        .command('branch <branch-name>')
+        .description('Create branches and worktrees for selected repos')
+        .action(async (branchName) => {
+        const services = createServices();
+        const useCases = createUseCases(services);
+        try {
+            await runBranch(branchName, useCases, services, { checkbox, input, confirm });
+        }
+        catch (error) {
+            services.console.error(error.message);
+            services.process.exit(1);
+        }
+    });
+}

package/dist/commands/checkout.js

@@ -0,0 +1,64 @@
+import confirm from '@inquirer/confirm';
+import chalk from 'chalk';
+import { createServices } from '../lib/services.js';
+import { createUseCases } from '../usecases/usecases.js';
+export async function runCheckout(branchName, useCases, services, deps) {
+    const { sourcePath, destPath } = services.config.getRequired();
+    const config = services.config.load();
+    let shouldRunPostCheckout = false;
+    if (config.postCheckout) {
+        shouldRunPostCheckout = await deps.confirm({
+            message: `Run "${config.postCheckout}" in all workspaces?`,
+            default: true,
+        });
+    }
+    services.console.log('\nChecking for branch...');
+    try {
+        // Execute use case
+        const result = await useCases.checkoutWorkspace.execute({
+            branchName,
+            sourcePath,
+            destPath,
+            copyFiles: config.copyFiles,
+            tmux: config.tmux,
+            postCheckout: shouldRunPostCheckout ? config.postCheckout : undefined,
+        });
+        // Display branch check results
+        for (const checkResult of result.branchCheckResults) {
+            if (checkResult.error) {
+                services.console.log(`${checkResult.repoName}... ${chalk.red(`error: ${checkResult.error}`)}`);
+            }
+            else if (checkResult.hasBranch) {
+                services.console.log(`${checkResult.repoName}... ${chalk.green('found')}`);
+            }
+            else {
+                services.console.log(`${checkResult.repoName}... ${chalk.dim('no branch')}`);
+            }
+        }
+        services.console.log(`\nCreated workspace at ${chalk.cyan(result.workspacePath)} with ${result.successCount}/${result.totalCount} repos.`);
+        if (result.tmuxCreated) {
+            services.console.log(`Created tmux session: ${chalk.cyan(branchName)}`);
+        }
+        if (result.postCheckoutSuccess !== undefined) {
+            services.console.log(`\nCompleted post-checkout in ${result.postCheckoutSuccess}/${result.postCheckoutTotal} workspace(s).`);
+        }
+        else if (!config.postCheckout) {
+            services.console.log('\nTip: Configure a post-checkout command to run automatically after branching/checkout.');
+            services.console.log('  Example: flow config set post-checkout "npm ci"');
+        }
+    }
+    catch (error) {
+        services.console.error(error.message);
+        services.process.exit(1);
+    }
+}
+export function registerCheckoutCommand(program) {
+    program
+        .command('checkout <branch-name>')
+        .description('Checkout an existing branch across repos')
+        .action(async (branchName) => {
+        const services = createServices();
+        const useCases = createUseCases(services);
+        await runCheckout(branchName, useCases, services, { confirm });
+    });
+}

package/dist/commands/config.js

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+import { z } from 'zod';
+import { isValidKey, validateAndTransformConfigValue, CONFIG_KEYS, } from '../lib/config.js';
+import { createServices } from '../lib/services.js';
+export function registerConfigCommand(program) {
+    const configCmd = program
+        .command('config')
+        .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)')
+        .action((key, value) => {
+        const services = createServices();
+        if (!isValidKey(key)) {
+            services.console.error(`Unknown config key: ${key}\nValid keys: ${CONFIG_KEYS.join(', ')}`);
+            services.process.exit(1);
+        }
+        try {
+            const config = services.config.loadRaw();
+            const transformedValue = validateAndTransformConfigValue(key, value);
+            config[key] = transformedValue;
+            services.config.saveRaw(config);
+            services.console.log(chalk.green(`Set ${key} = ${transformedValue}`));
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                services.console.error(`Invalid value for ${key}: ${error.issues[0].message}`);
+            }
+            else {
+                services.console.error(`Error setting config: ${error}`);
+            }
+            services.process.exit(1);
+        }
+    });
+    configCmd
+        .command('list')
+        .description('List all config options and their current values')
+        .action(() => {
+        const services = createServices();
+        services.console.log(chalk.bold('\nCurrent configuration:'));
+        services.console.log('');
+        const displayConfig = services.config.getDisplayConfig();
+        for (const key of CONFIG_KEYS) {
+            const { value, isDefault } = displayConfig[key];
+            const displayValue = isDefault ? chalk.gray(value) : chalk.green(value);
+            services.console.log(`  ${chalk.cyan(key)}: ${displayValue}`);
+        }
+        services.console.log('');
+    });
+}

package/dist/commands/list.js

@@ -0,0 +1,30 @@
+import chalk from 'chalk';
+import { createServices } from '../lib/services.js';
+export async function runList(services) {
+    const { destPath } = services.config.getRequired();
+    const workspaces = services.workspaceDir.listWorkspaces(destPath);
+    if (workspaces.length === 0) {
+        services.console.log('No workspaces found.');
+        return;
+    }
+    services.console.log(chalk.bold('\nWorkspaces:'));
+    for (const workspace of workspaces) {
+        services.console.log(`  ${chalk.cyan(workspace.name)} ${chalk.dim(`(${workspace.repoCount} repo${workspace.repoCount === 1 ? '' : 's'})`)}`);
+    }
+    services.console.log('');
+}
+export function registerListCommand(program) {
+    program
+        .command('list')
+        .description('List all workspaces in the target directory')
+        .action(async () => {
+        const services = createServices();
+        try {
+            await runList(services);
+        }
+        catch (error) {
+            services.console.error(error.message);
+            services.process.exit(1);
+        }
+    });
+}

package/dist/commands/prune.js

@@ -0,0 +1,93 @@
+import chalk from 'chalk';
+import confirm from '@inquirer/confirm';
+import { createServices } from '../lib/services.js';
+import { createUseCases } from '../usecases/usecases.js';
+export async function runPrune(useCases, services, deps) {
+    const { sourcePath, destPath } = services.config.getRequired();
+    const config = services.config.load();
+    services.console.log('Analyzing workspaces for pruning...\n');
+    // Analyze workspaces to find prunable ones
+    const result = await useCases.discoverPrunableWorkspaces.execute({
+        destPath,
+        sourcePath,
+        mainBranch: config.mainBranch,
+        daysOld: 7,
+    });
+    if (result.prunable.length === 0) {
+        services.console.log('No workspaces to prune.');
+        services.console.log(`\nWorkspaces are prunable when:`);
+        services.console.log(`  - All worktrees have no uncommitted changes`);
+        services.console.log(`  - All worktrees are not ahead of ${config.mainBranch}`);
+        services.console.log(`  - Last commit is more than 7 days old`);
+        services.process.exit(0);
+    }
+    // Display prunable workspaces
+    services.console.log(`${chalk.yellow('Found')} ${chalk.cyan(result.prunable.length)} ${chalk.yellow('workspace(s) that can be pruned:')}\n`);
+    for (const workspace of result.prunable) {
+        const daysOld = Math.floor((Date.now() - workspace.oldestCommitDate.getTime()) / (1000 * 60 * 60 * 24));
+        services.console.log(`  ${chalk.cyan(workspace.name)}`);
+        services.console.log(`    Repos: ${workspace.repoCount}`);
+        services.console.log(`    Last commit: ${daysOld} days ago`);
+        services.console.log(`    Status: ${chalk.green('clean')}`);
+        services.console.log('');
+    }
+    // Summary
+    const totalRepos = result.prunable.reduce((sum, ws) => sum + ws.repoCount, 0);
+    services.console.log(`${chalk.yellow('This will remove:')}`);
+    services.console.log(`  ${result.prunable.length} workspace(s)`);
+    services.console.log(`  ${totalRepos} worktree(s)`);
+    const confirmed = await deps.confirm({
+        message: 'Are you sure you want to prune these workspaces?',
+        default: false,
+    });
+    if (!confirmed) {
+        services.console.log('\nCancelled.');
+        services.process.exit(0);
+    }
+    // Remove each workspace
+    services.console.log('\nPruning workspaces...\n');
+    let successCount = 0;
+    let errorCount = 0;
+    for (const workspace of result.prunable) {
+        try {
+            services.console.log(`Removing ${chalk.cyan(workspace.name)}...`);
+            await useCases.removeWorkspace.execute({
+                workspacePath: workspace.path,
+                branchName: workspace.name,
+                sourcePath,
+                mainBranch: config.mainBranch,
+                tmux: config.tmux,
+            });
+            services.console.log(`  ${chalk.green('✓')} Removed ${workspace.name}`);
+            successCount++;
+        }
+        catch (error) {
+            services.console.log(`  ${chalk.red('✗')} Failed to remove ${workspace.name}: ${error.message}`);
+            errorCount++;
+        }
+    }
+    // Display summary
+    services.console.log('');
+    if (successCount > 0) {
+        services.console.log(`${chalk.green('Successfully pruned')} ${successCount} workspace(s)`);
+    }
+    if (errorCount > 0) {
+        services.console.log(`${chalk.red('Failed to prune')} ${errorCount} workspace(s)`);
+    }
+}
+export function registerPruneCommand(program) {
+    program
+        .command('prune')
+        .description('Remove old workspaces with no uncommitted changes and commits older than 7 days')
+        .action(async () => {
+        const services = createServices();
+        const useCases = createUseCases(services);
+        try {
+            await runPrune(useCases, services, { confirm });
+        }
+        catch (error) {
+            services.console.error(error.message);
+            services.process.exit(1);
+        }
+    });
+}

package/dist/commands/pull.js

@@ -0,0 +1,31 @@
+import chalk from 'chalk';
+import { createServices } from '../lib/services.js';
+import { createUseCases } from '../usecases/usecases.js';
+import { resolveWorkspace } from '../lib/workspaceResolver.js';
+export async function runPull(branchName, useCases, services) {
+    const { workspacePath } = resolveWorkspace(branchName, services.workspaceDir, services.config, services.process);
+    const dirs = services.workspaceDir.getWorktreeDirs(workspacePath);
+    if (dirs.length === 0) {
+        services.console.error('No repos found in workspace.');
+        services.process.exit(1);
+    }
+    services.console.log(`Pulling ${dirs.length} repo(s) in ${chalk.cyan(workspacePath)}...\n`);
+    const result = await useCases.pullWorkspace.execute({ workspacePath });
+    services.console.log(`\n${result.successCount}/${result.totalCount} repos pulled successfully.`);
+}
+export function registerPullCommand(program) {
+    program
+        .command('pull [branch-name]')
+        .description('Pull all repos in a workspace (auto-detects from current directory if branch not provided)')
+        .action(async (branchName) => {
+        const services = createServices();
+        const useCases = createUseCases(services);
+        try {
+            await runPull(branchName, useCases, services);
+        }
+        catch (error) {
+            services.console.error(error.message);
+            services.process.exit(1);
+        }
+    });
+}

package/dist/commands/push.js

@@ -0,0 +1,31 @@
+import chalk from 'chalk';
+import { createServices } from '../lib/services.js';
+import { createUseCases } from '../usecases/usecases.js';
+import { resolveWorkspace } from '../lib/workspaceResolver.js';
+export async function runPush(branchName, useCases, services) {
+    const { workspacePath } = resolveWorkspace(branchName, services.workspaceDir, services.config, services.process);
+    const dirs = services.workspaceDir.getWorktreeDirs(workspacePath);
+    if (dirs.length === 0) {
+        services.console.error('No repos found in workspace.');
+        services.process.exit(1);
+    }
+    services.console.log(`Pushing ${dirs.length} repo(s) in ${chalk.cyan(workspacePath)}...\n`);
+    const result = await useCases.pushWorkspace.execute({ workspacePath });
+    services.console.log(`\n${result.successCount}/${result.totalCount} repos pushed successfully.`);
+}
+export function registerPushCommand(program) {
+    program
+        .command('push [branch-name]')
+        .description('Push all repos in a workspace (auto-detects from current directory if branch not provided)')
+        .action(async (branchName) => {
+        const services = createServices();
+        const useCases = createUseCases(services);
+        try {
+            await runPush(branchName, useCases, services);
+        }
+        catch (error) {
+            services.console.error(error.message);
+            services.process.exit(1);
+        }
+    });
+}