Skip to content

project-structure.md

Latest commit

 

History

History
247 lines (218 loc) · 9.65 KB

project-structure.md

File metadata and controls

247 lines (218 loc) · 9.65 KB

Project Structure Specification

Directory Structure

proudnerds-git-flow-poc/
├── src/                           # PHP source code
│   ├── CLI/                      # Command line interface
│   │   ├── Application.php       # Main CLI application
│   │   ├── Commands/             # Command implementations
│   │   │   ├── BaseCommand.php   # Base command class
│   │   │   ├── PromptsBaseCommand.php # Laravel Prompts integration base
│   │   │   ├── InitCommand.php   # {app} init
│   │   │   ├── ConfigCommand.php # {app} config
│   │   │   ├── StatusCommand.php # {app} status
│   │   │   ├── FeatureCommand.php # {app} feature (epic-aware)
│   │   │   ├── EpicCommand.php    # {app} epic
│   │   │   ├── ReleaseCommand.php # {app} release (epic-aware)
│   │   │   ├── HotfixCommand.php  # {app} hotfix
│   │   │   ├── CommitCommand.php  # {app} commit
│   │   │   ├── SyncCommand.php    # {app} sync
│   │   │   ├── ModeCommand.php    # {app} mode
│   │   │   ├── DeployCommand.php  # {app} deploy
│   │   │   └── CleanCommand.php   # {app} clean
│   ├── Core/                     # Core functionality
│   │   ├── Branding.php          # Application branding/naming
│   │   ├── Repository.php        # Git repository wrapper
│   │   ├── BranchManager.php     # Branch operations
│   │   └── ConfigManager.php     # Configuration handling
│   ├── Integration/              # Git provider integrations
│   │   ├── AbstractProvider.php  # Base for Git providers
│   │   ├── GitHubProvider.php    # GitHub API integration
│   │   └── BitBucketProvider.php # BitBucket API integration
│   ├── Hooks/                    # Git hooks management
│   │   └── HookManager.php       # Git hooks management
│   ├── Validators/               # Safety validators
│   │   └── SafetyValidator.php   # Repository safety checks
│   └── Exceptions/               # Custom exceptions
│       ├── Git StreamException.php    # Base exception
│       ├── ConfigException.php   # Configuration errors
│       ├── RepositoryException.php # Git repository errors
│       └── ValidationException.php # Validation errors
├── bin/                          # Executable scripts
│   └── gstr                     # Main executable (configurable name)
├── build/                        # Build and distribution tools
│   ├── customize-branding.php    # Branding customization script
│   └── package.php               # Distribution packaging
├── docs/                         # Documentation
│   ├── plan.md                   # Implementation plan
│   ├── project-structure.md      # This file
│   ├── commands.md               # Command reference
│   └── configuration.md          # Configuration guide
├── tests/                        # Unit and integration tests
│   ├── Unit/                     # Unit tests
│   └── Integration/              # Integration tests
├── composer.json                 # PHP dependencies
├── composer.lock                 # Locked dependency versions
├── phpunit.xml                   # PHPUnit configuration
├── .gitignore                    # Git ignore rules
└── README.md                     # Project README

Epic Integration Components

New Components for Epic Support

EpicCommand (src/CLI/Commands/EpicCommand.php)

The main epic command handler supporting:

  • gstr epic start [key] [description] - Create new epic branch
  • gstr epic finish [key] - Complete and merge epic
  • gstr epic list - Show active and completed epics
  • Interactive parameter prompting when arguments omitted
  • Automatic branch detection for finish operations

Interactive Command System (src/CLI/Commands/PromptsBaseCommand.php)

All commands extend PromptsBaseCommand which provides:

  • Laravel Prompts integration for modern interactive CLI experience
  • Unified prompt methods (text, password, confirm, select, multiselect, suggest, search)
  • Git Stream-specific helpers (selectBranch, selectFeatures, confirmWithRecovery)
  • Standardized output helpers (space, bulletList, step, stepSuccess, stepError, section, subsection, keyValue, suggestCommand)
  • Terminal capability detection and non-interactive fallback
  • Consistent user experience across all commands

See: Laravel Prompts System and Output Style Guide

Modified Existing Components

  • FeatureCommand.php - Enhanced with epic selection during feature start
  • ReleaseCommand.php - Epic-aware feature selection showing complete epics
  • Repository.php - Epic branch detection and validation
  • SafetyValidator.php - Epic branch validation rules

Epic Branch Model

main (stable base for all new development)
├── epic/AUTH-123 (from main)
│   ├── epic/AUTH-123/login-form
│   ├── epic/AUTH-123/oauth-flow
│   └── epic/AUTH-123/password-reset
├── epic/PAY-456 (from main)
│   ├── epic/PAY-456/stripe-integration
│   └── epic/PAY-456/billing-ui
├── feature/standalone-fix (from main)
└── feature/quick-update (from main)

All branches merge to develop when finished

Interactive Experience Enhancements

All commands now support interactive parameter prompting:

  • Start Commands: Prompt for missing keys/names with smart defaults
  • Finish Commands: Auto-detect current branch or show selection
  • Epic Selection: Visual tree showing epic hierarchy
  • Feature Selection: Epic-aware selection with grouping

Composer Dependencies

Required Dependencies

  • symfony/console - CLI framework for commands and input/output
  • laravel/prompts - Modern interactive prompts and menus
  • guzzlehttp/guzzle - HTTP client for GitHub/BitBucket API calls
  • symfony/filesystem - File system operations
  • symfony/process - Execute git commands safely

Development Dependencies

  • phpunit/phpunit - Unit testing framework
  • phpstan/phpstan - Static analysis
  • squizlabs/php_codesniffer - Code style checking
  • friendsofphp/php-cs-fixer - Code style fixing

Configuration Files

Global Configuration Structure

Git Stream uses a global configuration directory at ~/.gstr/ that contains:

  • config.json - Global user settings and credentials shared across all projects
  • cache/ - Cached API responses and temporary data

Repository Configuration Structure

Repository-specific data is stored inside the git directory: .git/gstr/

  • config.json - Repository-specific settings (no credentials ever stored here) (Git hooks live in the existing .git/hooks/ directory; Git Stream does not create a root-level .gstr/ directory)

Branch and PR tracking is done via git-based discovery, analyzing branches and commit history directly rather than maintaining separate state files.

composer.json Structure

{
    "name": "proudnerds/gstr",
    "description": "Advanced Git workflow tool for multiple simultaneous releases",
    "type": "project",
    "license": "MIT",
    "require": {
        "php": "^8.4",
        "symfony/console": "^7.0",
        "guzzlehttp/guzzle": "^7.0",
        "laravel/prompts": "^0.1",
        "symfony/filesystem": "^7.0",
        "symfony/process": "^7.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0",
        "phpstan/phpstan": "^1.10",
        "squizlabs/php_codesniffer": "^3.7",
        "friendsofphp/php-cs-fixer": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "Git Stream\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Git Stream\\Tests\\": "tests/"
        }
    },
    "bin": ["bin/gstr"],
    "config": {
        "optimize-autoloader": true,
        "sort-packages": true
    },
    "scripts": {
        "test": "phpunit",
        "analyse": "phpstan analyse src",
        "cs-check": "phpcs",
        "cs-fix": "phpcbf"
    }
}

.gitignore Contents

/vendor/
composer.lock
.phpunit.result.cache
.phpstan.neon
.php-cs-fixer.cache

Note: Repository configuration and state are stored within the existing .git/ directory structure, which is already ignored by git. Global credentials are stored in ~/.gstr/ and never committed to repositories.

phpunit.xml Configuration

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php"
         colors="true"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true"
         processIsolation="false"
         stopOnFailure="false">
    <testsuites>
        <testsuite name="Unit">
            <directory suffix="Test.php">./tests/Unit</directory>
        </testsuite>
        <testsuite name="Integration">
            <directory suffix="Test.php">./tests/Integration</directory>
        </testsuite>
    </testsuites>
    <source>
        <include>
            <directory suffix=".php">./src</directory>
        </include>
    </source>
</phpunit>

Executable Script (bin/gstr)

#!/usr/bin/env php
<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use Git Stream\CLI\Application;

$application = new Application();
$application->run();

This structure provides:

  • Clear separation of concerns with organized directories
  • PSR-4 autoloading for clean class loading
  • Comprehensive testing setup
  • Modern PHP 8.4+ features and strict typing
  • Professional development tools and standards