feat(cli): add branch command for local instance database management

[erayack]

Description

• Add helix branch to snapshot local LMDB data into a new directory (with optional deploy), with safe overwrite prompts and default .helix/.branches output.
• Persist per-instance data_dir in helix.toml and use it for backup/start/push/delete output and Docker volume mounts.
• Add repo-cache locking (process + file lock) in build/check flows and support HELIX_CACHE_DIR plus test-safe cache roots.
• Add new fs2 dependency in helix-cli for cross-process file locking.
• Update CLI docs (helix-cli/README.md) and contributor command list (CONTRIBUTORS.md).
• Add branch command unit tests.
• Normalize and quote Windows absolute volume paths in docker compose generation to avoid C: parsing issues ('src/docker.rs').

Related Issues

#787.

Checklist when merging to main

• No compiler warnings (if applicable)
• Code is formatted with rustfmt
• No useless or dead code (if applicable)
• Code is easy to understand
• Doc comments are used for all functions, enums, structs, and fields (where appropriate)
• All tests pass
• Performance has not regressed (assuming change was not to fix a bug)
• Version number has been updated in helix-cli/Cargo.toml and helixdb/Cargo.toml

Additional Notes

Cache behavior:

• HELIX_CACHE_DIR overrides the default repo cache location for build/check flows.
• Tests use a temp per-thread cache root to avoid collisions with user caches.
• Repo-cache operations are serialized to avoid concurrent cache mutations.
  Dependency note:
• helix-cli now depends on fs2 for file locking.
• Windows absolute paths are normalized to / separators and quoted in host:container volume specs.

Tests

Tests are passing.

Tests Added

• helix-cli/src/tests/branch_tests.rs
  • test_resolve_output_dir_defaults
  • test_resolve_output_dir_relative_path
  • test_branch_persists_deploy_config
  • test_prepare_output_user_dir_rejects_existing_data

Greptile Summary

This PR implements the helix branch command to safely clone LMDB databases for local instances, with optional deployment. The implementation reuses existing LMDB env.copy_to_path() logic from the backup command.

Key Changes

• Branch Command: Creates atomic LMDB snapshots to .helix/.branches/<timestamp> (default). Includes overwrite protection with interactive prompts and size warnings for databases >10GB.

• Data Directory Persistence: Added optional data_dir field to LocalInstanceConfig in helix.toml, enabling custom data locations. Commands like start, delete, and backup now respect this configuration.

• Cache Locking: Implemented dual-locking (in-process Mutex + cross-process file lock via fs2) for the Helix repo cache in build and check commands. Prevents concurrent cache mutations and supports HELIX_CACHE_DIR override.

• Windows Path Handling: Normalized and quoted Windows absolute paths in Docker Compose volume specs to avoid C: parsing issues ("C:/path:/data" format).

• Test Isolation: Tests now use per-thread, per-process temporary cache directories to avoid conflicts with user caches.

Testing

Four unit tests added covering output directory resolution, config persistence, and overwrite protection.

Important Files Changed

Filename	Overview
helix-cli/src/commands/branch.rs	New branch command implementation - safely copies LMDB data and optionally deploys new instance
helix-cli/src/commands/build.rs	Added process and file locking for repo cache operations to prevent concurrent mutations
helix-cli/src/docker.rs	Windows path normalization for Docker volumes - quotes and normalizes absolute paths with colons
helix-cli/src/config.rs	Added optional data_dir field to LocalInstanceConfig with path serialization support
helix-cli/src/project.rs	Added HELIX_CACHE_DIR env var support and thread-safe test cache isolation

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as helix branch
    participant Project as ProjectContext
    participant Config as helix.toml
    participant LMDB as LMDB Env
    participant Docker as DockerManager
    participant Build as build::run

    User->>CLI: helix branch <instance> [--deploy] [--name <name>]
    CLI->>Project: find_and_load()
    Project->>Config: load instance config
    Config-->>CLI: LocalInstanceConfig
    
    CLI->>CLI: resolve_output_dir()
    Note over CLI: Default: .helix/.branches/<timestamp><br/>or .helix/.volumes/<branch-name> if --deploy
    
    CLI->>CLI: prepare_output_user_dir()
    alt Directory exists with data
        CLI->>User: Prompt for overwrite confirmation
        User-->>CLI: Confirm/Cancel
    end
    
    CLI->>LMDB: Open read-only snapshot
    LMDB-->>CLI: Environment handle
    CLI->>LMDB: copy_to_path(output_dir/user/data.mdb)
    LMDB-->>CLI: Atomic copy complete
    
    alt --deploy flag set
        CLI->>CLI: select_available_port()
        CLI->>Config: persist_branch_config()
        Note over Config: Add new instance with data_dir
        Config->>Config: save helix.toml
        
        CLI->>Docker: check_runtime_available()
        CLI->>Build: run(branch_name)
        Note over Build: Builds Docker image<br/>with branched data
        Build-->>CLI: Build complete
        
        CLI->>Docker: start_instance(branch_name)
        Docker-->>CLI: Container running
        CLI->>User: Display connection info
    end
    
    CLI-->>User: Branch created successfully

Loading

[greptile-apps]

Greptile's behavior is changing!

From now on, if a review finishes with no comments, we will not post an additional "statistics" comment to confirm that our review found nothing to comment on. However, you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}

[xav-db]

I think this should start a new instance using the copied files

[xav-db]

@erayack

[erayack]

Hi @xav-db, you want the --deploy branch to spin up the branched instance from the snapshot (data + compiled workspace files) rather than rebuilding from the current project tree.

Is it correct?

[xav-db]

yeah although I think it shouldn't need a --deploy flag. we already have a backup command that copies the lmdb files properly. I would use this then rerun the existing docker build on a new port as a new container. does this sound good? @erayack

[erayack]

Yes, much more simple. Thanks for direction @xav-db

• Removed the --deploy flag from branch and made branching always create a new local instance, to reuse the existing backup flow.
• Reused the backup logic by extracting backup_instance_to_dir in backup.rs and calling it from branch.rs for LMDB snapshotting.
• Simplified branch output paths to always use .helix/.volumes/<branch_name> and added name/port availability checks for safer local instance creation in branch.rs.
• Updated CLI docs and CLI wiring to reflect the new branch behavior in README.md and main.rs.
• Added test coverage for the backup helper in backup_tests.rs.

[xav-db]

Lovely job, will review shortly!

[erayack]

Any update? @xav-db

[xav-db]

Apologies i've been extremely ill the past few days, getting back to it now

[erayack]

Get well soon, no rush. @xav-db