sprout-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{sprout_cli-0.2.0 → sprout_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sprout-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: CLI tool to automate git worktree and Docker Compose development workflows
 Author: SecDevLab Inc.
 License: MIT
@@ -56,7 +56,7 @@ pip install -e ".[dev]"
 
 ## Quick Start
 
-1. Create a `.env.example` template in your project root:
+1. Create a `.env.example` template in your project root (and optionally in subdirectories):
 ```env
 # API Configuration
 API_KEY={{ API_KEY }}
@@ -71,35 +71,104 @@ DB_PORT={{ auto_port() }}
 # DB_NAME=${DB_NAME}
 ```
 
-2. Create a new development environment:
-```bash
-sprout create feature-branch
+For monorepo or multi-service projects, you can create `.env.example` files in subdirectories:
+```
+repo/
+  .env.example          # Root configuration
+  service-a/
+    .env.example        # Service A specific config
+  service-b/
+    .env.example        # Service B specific config
 ```
 
-3. Navigate to your new environment:
+2. Create and navigate to a new development environment in one command:
 ```bash
-cd $(sprout path feature-branch)
+cd $(sprout create feature-branch --path)
 ```
 
-4. Start your services:
+This single command:
+- Creates a new git worktree for `feature-branch`
+- Generates a `.env` file from your template
+- Outputs the path to the new environment
+- Changes to that directory when wrapped in `cd $(...)`
+
+3. Start your services:
 ```bash
 docker compose up -d
 ```
 
+### Alternative: Two-Step Process
+
+If you prefer to see the creation output first:
+```bash
+# Create the environment
+sprout create feature-branch
+
+# Then navigate to it
+cd $(sprout path feature-branch)
+```
+
 ## Commands
 
-### `sprout create <branch-name>`
+### `sprout create <branch-name> [--path]`
 Create a new development environment with automated setup.
 
+Options:
+- `--path`: Output only the worktree path (useful for shell command substitution)
+
+Examples:
+```bash
+# Create and see progress messages
+sprout create feature-xyz
+
+# Create and navigate in one command
+cd $(sprout create feature-xyz --path)
+```
+
 ### `sprout ls`
 List all managed development environments with their status.
 
-### `sprout rm <branch-name>`
+The output includes index numbers that can be used with other commands:
+```bash
+sprout ls
+# Output:
+# ┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+# ┃ No.  ┃ Branch          ┃ Path            ┃ Status ┃ Last Modified    ┃
+# ┡━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+# │ 1    │ feature-auth    │ .sprout/feat... │        │ 2025-06-27 14:30 │
+# │ 2    │ bugfix-api      │ .sprout/bugf... │        │ 2025-06-27 15:45 │
+# └──────┴─────────────────┴─────────────────┴────────┴──────────────────┘
+```
+
+### `sprout rm <branch-name-or-index>`
 Remove a development environment (with confirmation prompts).
 
-### `sprout path <branch-name>`
+You can use either the branch name or the index number from `sprout ls`:
+```bash
+# Remove by branch name
+sprout rm feature-auth
+
+# Remove by index number
+sprout rm 1
+```
+
+### `sprout path <branch-name-or-index>`
 Get the filesystem path of a development environment.
 
+You can use either the branch name or the index number from `sprout ls`:
+```bash
+# Get path by branch name
+sprout path feature-auth
+# Output: /path/to/project/.sprout/feature-auth
+
+# Get path by index number
+sprout path 1
+# Output: /path/to/project/.sprout/feature-auth
+
+# Use with cd command
+cd $(sprout path 2)
+```
+
 ### `sprout --version`
 Show the version of sprout.
 
@@ -114,8 +183,9 @@ sprout supports two types of placeholders in `.env.example`:
 
 2. **Auto Port Assignment**: `{{ auto_port() }}`
    - Automatically assigns available ports
-   - Avoids conflicts with other sprout environments
+   - Avoids conflicts across ALL services in ALL sprout environments
    - Checks system port availability
+   - Ensures global uniqueness even in monorepo setups
 
 3. **Docker Compose Syntax (Preserved)**: `${VARIABLE}`
    - NOT processed by sprout - passed through as-is
@@ -137,6 +207,54 @@ sprout create another-branch
 # → Enter a value for 'DATABASE_URL': [user input required]
 ```
 
+## Monorepo Tutorial
+
+Try out the monorepo functionality with the included sample:
+
+1. **Navigate to the sample monorepo**:
+   ```bash
+   cd sample/monorepo
+   ```
+
+2. **Set required environment variables**:
+   ```bash
+   export API_KEY="your-api-key"
+   export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myapp"
+   export REACT_APP_API_KEY="your-frontend-api-key"
+   export JWT_SECRET="your-jwt-secret"
+   export SMTP_USER="your-smtp-username"
+   export SMTP_PASS="your-smtp-password"
+   ```
+
+3. **Create a development environment**:
+   ```bash
+   sprout create monorepo-feature
+   ```
+
+4. **Navigate to the created environment**:
+   ```bash
+   cd .sprout/monorepo-feature
+   ```
+
+5. **Verify all services have unique ports**:
+   ```bash
+   find . -name "*.env" -exec echo "=== {} ===" \; -exec cat {} \;
+   ```
+
+6. **Start all services**:
+   ```bash
+   cd sample/monorepo
+   docker-compose up -d
+   ```
+
+The sample includes:
+- **Root service**: Database and Redis with shared configuration
+- **Frontend**: React app with API integration
+- **Backend**: REST API with authentication
+- **Shared**: Utilities with message queue and monitoring
+
+Each service gets unique, conflict-free ports automatically!
+
 ## Documentation
 
 - [Architecture Overview](docs/sprout-cli/overview.md) - Design philosophy, architecture, and implementation details

sprout_cli-0.4.0/README.md

@@ -0,0 +1,272 @@
+# sprout
+
+A CLI tool to automate git worktree and Docker Compose development workflows.
+
+## Features
+
+- 🌱 Create isolated development environments using git worktrees
+- 🔧 Automatic `.env` file generation from templates
+- 🚢 Smart port allocation to avoid conflicts
+- 📁 Centralized worktree management in `.sprout/` directory
+- 🎨 Beautiful CLI interface with colors and tables
+
+## Installation
+
+```bash
+pip install sprout
+```
+
+For development:
+```bash
+# Clone the repository
+git clone https://github.com/SecDev-Lab/sprout.git
+cd sprout
+
+# Install in development mode
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+1. Create a `.env.example` template in your project root (and optionally in subdirectories):
+```env
+# API Configuration
+API_KEY={{ API_KEY }}
+API_PORT={{ auto_port() }}
+
+# Database Configuration  
+DB_HOST=localhost
+DB_PORT={{ auto_port() }}
+
+# Example: Docker Compose variables (preserved as-is)
+# sprout will NOT process ${...} syntax - it's passed through unchanged
+# DB_NAME=${DB_NAME}
+```
+
+For monorepo or multi-service projects, you can create `.env.example` files in subdirectories:
+```
+repo/
+  .env.example          # Root configuration
+  service-a/
+    .env.example        # Service A specific config
+  service-b/
+    .env.example        # Service B specific config
+```
+
+2. Create and navigate to a new development environment in one command:
+```bash
+cd $(sprout create feature-branch --path)
+```
+
+This single command:
+- Creates a new git worktree for `feature-branch`
+- Generates a `.env` file from your template
+- Outputs the path to the new environment
+- Changes to that directory when wrapped in `cd $(...)`
+
+3. Start your services:
+```bash
+docker compose up -d
+```
+
+### Alternative: Two-Step Process
+
+If you prefer to see the creation output first:
+```bash
+# Create the environment
+sprout create feature-branch
+
+# Then navigate to it
+cd $(sprout path feature-branch)
+```
+
+## Commands
+
+### `sprout create <branch-name> [--path]`
+Create a new development environment with automated setup.
+
+Options:
+- `--path`: Output only the worktree path (useful for shell command substitution)
+
+Examples:
+```bash
+# Create and see progress messages
+sprout create feature-xyz
+
+# Create and navigate in one command
+cd $(sprout create feature-xyz --path)
+```
+
+### `sprout ls`
+List all managed development environments with their status.
+
+The output includes index numbers that can be used with other commands:
+```bash
+sprout ls
+# Output:
+# ┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+# ┃ No.  ┃ Branch          ┃ Path            ┃ Status ┃ Last Modified    ┃
+# ┡━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+# │ 1    │ feature-auth    │ .sprout/feat... │        │ 2025-06-27 14:30 │
+# │ 2    │ bugfix-api      │ .sprout/bugf... │        │ 2025-06-27 15:45 │
+# └──────┴─────────────────┴─────────────────┴────────┴──────────────────┘
+```
+
+### `sprout rm <branch-name-or-index>`
+Remove a development environment (with confirmation prompts).
+
+You can use either the branch name or the index number from `sprout ls`:
+```bash
+# Remove by branch name
+sprout rm feature-auth
+
+# Remove by index number
+sprout rm 1
+```
+
+### `sprout path <branch-name-or-index>`
+Get the filesystem path of a development environment.
+
+You can use either the branch name or the index number from `sprout ls`:
+```bash
+# Get path by branch name
+sprout path feature-auth
+# Output: /path/to/project/.sprout/feature-auth
+
+# Get path by index number
+sprout path 1
+# Output: /path/to/project/.sprout/feature-auth
+
+# Use with cd command
+cd $(sprout path 2)
+```
+
+### `sprout --version`
+Show the version of sprout.
+
+## Template Syntax
+
+sprout supports two types of placeholders in `.env.example`:
+
+1. **Variable Placeholders**: `{{ VARIABLE_NAME }}`
+   - **First**: Checks if the variable exists in your environment (e.g., `export API_KEY=xxx`)
+   - **Then**: If not found in environment, prompts for user input
+   - Example: `{{ API_KEY }}` will use `$API_KEY` if set, otherwise asks you to enter it
+
+2. **Auto Port Assignment**: `{{ auto_port() }}`
+   - Automatically assigns available ports
+   - Avoids conflicts across ALL services in ALL sprout environments
+   - Checks system port availability
+   - Ensures global uniqueness even in monorepo setups
+
+3. **Docker Compose Syntax (Preserved)**: `${VARIABLE}`
+   - NOT processed by sprout - passed through as-is
+   - Useful for Docker Compose variable substitution
+   - Example: `${DB_NAME:-default}` remains unchanged in generated `.env`
+
+### Environment Variable Resolution Example
+
+```bash
+# Set environment variable
+export API_KEY="my-secret-key"
+
+# Create sprout environment - API_KEY will be automatically used
+sprout create feature-branch
+# → API_KEY in .env will be set to "my-secret-key" without prompting
+
+# For unset variables, sprout will prompt
+sprout create another-branch
+# → Enter a value for 'DATABASE_URL': [user input required]
+```
+
+## Monorepo Tutorial
+
+Try out the monorepo functionality with the included sample:
+
+1. **Navigate to the sample monorepo**:
+   ```bash
+   cd sample/monorepo
+   ```
+
+2. **Set required environment variables**:
+   ```bash
+   export API_KEY="your-api-key"
+   export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myapp"
+   export REACT_APP_API_KEY="your-frontend-api-key"
+   export JWT_SECRET="your-jwt-secret"
+   export SMTP_USER="your-smtp-username"
+   export SMTP_PASS="your-smtp-password"
+   ```
+
+3. **Create a development environment**:
+   ```bash
+   sprout create monorepo-feature
+   ```
+
+4. **Navigate to the created environment**:
+   ```bash
+   cd .sprout/monorepo-feature
+   ```
+
+5. **Verify all services have unique ports**:
+   ```bash
+   find . -name "*.env" -exec echo "=== {} ===" \; -exec cat {} \;
+   ```
+
+6. **Start all services**:
+   ```bash
+   cd sample/monorepo
+   docker-compose up -d
+   ```
+
+The sample includes:
+- **Root service**: Database and Redis with shared configuration
+- **Frontend**: React app with API integration
+- **Backend**: REST API with authentication
+- **Shared**: Utilities with message queue and monitoring
+
+Each service gets unique, conflict-free ports automatically!
+
+## Documentation
+
+- [Architecture Overview](docs/sprout-cli/overview.md) - Design philosophy, architecture, and implementation details
+- [Detailed Usage Guide](docs/sprout-cli/usage.md) - Comprehensive usage examples and troubleshooting
+
+## Development
+
+### Setup
+```bash
+# Install development dependencies
+make setup
+```
+
+### Testing
+```bash
+# Run tests
+make test
+
+# Run tests with coverage
+make test-cov
+```
+
+### Code Quality
+```bash
+# Run linter
+make lint
+
+# Format code
+make format
+
+# Run type checking
+make typecheck
+```
+
+## Requirements
+
+- Python 3.11+
+- Git
+- Docker Compose (optional, for Docker-based workflows)
+
+## License
+
+See LICENSE file.

{sprout_cli-0.2.0 → sprout_cli-0.4.0}/pyproject.toml

@@ -122,4 +122,10 @@ ignore_missing_imports = true
 [[tool.mypy.overrides]]
 module = "tests.*"
 disallow_untyped_defs = false
-disallow_incomplete_defs = false
+disallow_incomplete_defs = false
+
+[dependency-groups]
+dev = [
+    "pytest-mock>=3.14.1",
+    "ruff>=0.12.1",
+]

{sprout_cli-0.2.0 → sprout_cli-0.4.0}/src/sprout/__init__.py

@@ -1,3 +1,3 @@
 """sprout - CLI tool to automate git worktree and Docker Compose development workflows."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{sprout_cli-0.2.0 → sprout_cli-0.4.0}/src/sprout/cli.py

@@ -46,9 +46,14 @@ def create(
         ...,
         help="Name of the branch to create worktree for",
     ),
+    path: bool = typer.Option(
+        False,
+        "--path",
+        help="Output only the worktree path (for use with shell command substitution)",
+    ),
 ) -> None:
     """Create a new development environment."""
-    create_worktree(branch_name)
+    create_worktree(branch_name, path_only=path)
 
 
 @app.command()
@@ -59,24 +64,24 @@ def ls() -> None:
 
 @app.command()
 def rm(
-    branch_name: BranchName = typer.Argument(
+    identifier: str = typer.Argument(
         ...,
-        help="Name of the branch to remove",
+        help="Branch name or index number to remove",
     ),
 ) -> None:
     """Remove a development environment."""
-    remove_worktree(branch_name)
+    remove_worktree(identifier)
 
 
 @app.command()
 def path(
-    branch_name: BranchName = typer.Argument(
+    identifier: str = typer.Argument(
         ...,
-        help="Name of the branch to get path for",
+        help="Branch name or index number to get path for",
     ),
 ) -> None:
     """Get the path of a development environment."""
-    get_worktree_path(branch_name)
+    get_worktree_path(identifier)
 
 
 if __name__ == "__main__":

sprout_cli-0.4.0/src/sprout/commands/create.py

@@ -0,0 +1,153 @@
+"""Implementation of the create command."""
+
+import re
+from pathlib import Path
+from typing import Never
+
+import typer
+from rich.console import Console
+
+from sprout.exceptions import SproutError
+from sprout.types import BranchName
+from sprout.utils import (
+    branch_exists,
+    ensure_sprout_dir,
+    get_git_root,
+    get_used_ports,
+    is_git_repository,
+    parse_env_template,
+    run_command,
+    worktree_exists,
+)
+
+console = Console()
+
+
+def create_worktree(branch_name: BranchName, path_only: bool = False) -> Never:
+    """Create a new worktree with development environment."""
+    # Check prerequisites
+    if not is_git_repository():
+        if not path_only:
+            console.print("[red]Error: Not in a git repository[/red]")
+            console.print("Please run this command from the root of a git repository.")
+        else:
+            typer.echo("Error: Not in a git repository", err=True)
+        raise typer.Exit(1)
+
+    git_root = get_git_root()
+
+    # Find all .env.example files that are tracked by git
+    result = run_command(["git", "ls-files", "*.env.example", "**/*.env.example"])
+    env_examples = []
+    if result.stdout.strip():
+        for file_path in result.stdout.strip().split("\n"):
+            full_path = git_root / file_path
+            if full_path.exists():
+                env_examples.append(full_path)
+
+    if not env_examples:
+        if not path_only:
+            console.print("[red]Error: No .env.example files found[/red]")
+            console.print(f"Expected at least one .env.example file in: {git_root}")
+        else:
+            typer.echo(f"Error: No .env.example files found in {git_root}", err=True)
+        raise typer.Exit(1)
+
+    # Check if worktree already exists
+    if worktree_exists(branch_name):
+        if not path_only:
+            console.print(f"[red]Error: Worktree for branch '{branch_name}' already exists[/red]")
+        else:
+            typer.echo(f"Error: Worktree for branch '{branch_name}' already exists", err=True)
+        raise typer.Exit(1)
+
+    # Ensure .sprout directory exists
+    sprout_dir = ensure_sprout_dir()
+    worktree_path = sprout_dir / branch_name
+
+    # Create the worktree
+    if not path_only:
+        console.print(f"Creating worktree for branch [cyan]{branch_name}[/cyan]...")
+
+    # Check if branch exists, create if it doesn't
+    if not branch_exists(branch_name):
+        if not path_only:
+            console.print(f"Branch '{branch_name}' doesn't exist. Creating new branch...")
+        # Create branch with -b flag
+        cmd = ["git", "worktree", "add", "-b", branch_name, str(worktree_path)]
+    else:
+        cmd = ["git", "worktree", "add", str(worktree_path), branch_name]
+
+    try:
+        run_command(cmd)
+    except SproutError as e:
+        if not path_only:
+            console.print(f"[red]Error creating worktree: {e}[/red]")
+        else:
+            typer.echo(f"Error creating worktree: {e}", err=True)
+        raise typer.Exit(1) from e
+
+    # Generate .env files
+    if not path_only:
+        console.print(f"Generating .env files from {len(env_examples)} template(s)...")
+
+    # Get all currently used ports to avoid conflicts
+    all_used_ports = get_used_ports()
+    session_ports: set[int] = set()
+
+    try:
+        for env_example in env_examples:
+            # Calculate relative path from git root
+            relative_dir = env_example.parent.relative_to(git_root)
+
+            # Create target directory in worktree if needed
+            if relative_dir != Path("."):
+                target_dir = worktree_path / relative_dir
+                target_dir.mkdir(parents=True, exist_ok=True)
+                env_file = target_dir / ".env"
+            else:
+                env_file = worktree_path / ".env"
+
+            # Parse template with combined used ports
+            env_content = parse_env_template(
+                env_example, silent=path_only, used_ports=all_used_ports | session_ports
+            )
+
+            # Extract ports from generated content and add to session_ports
+            port_matches = re.findall(r"=(\d{4,5})\b", env_content)
+            for port_str in port_matches:
+                port = int(port_str)
+                if 1024 <= port <= 65535:
+                    session_ports.add(port)
+
+            # Write the .env file
+            env_file.write_text(env_content)
+
+    except SproutError as e:
+        if not path_only:
+            console.print(f"[red]Error generating .env file: {e}[/red]")
+        else:
+            typer.echo(f"Error generating .env file: {e}", err=True)
+        # Clean up worktree on failure
+        run_command(["git", "worktree", "remove", str(worktree_path)], check=False)
+        raise typer.Exit(1) from e
+    except KeyboardInterrupt:
+        if not path_only:
+            console.print("\n[yellow]Cancelled by user[/yellow]")
+        else:
+            typer.echo("Cancelled by user", err=True)
+        # Clean up worktree on cancellation
+        run_command(["git", "worktree", "remove", str(worktree_path)], check=False)
+        raise typer.Exit(130) from None
+
+    # Success message or path output
+    if path_only:
+        # Output only the path for shell command substitution
+        print(str(worktree_path))
+    else:
+        console.print(f"\n[green]✅ Workspace '{branch_name}' created successfully![/green]\n")
+        console.print("Navigate to your new environment with:")
+        console.print(f"  [cyan]cd {worktree_path.relative_to(Path.cwd())}[/cyan]")
+
+    # Exit successfully
+    raise typer.Exit(0)