easystream-main/CONTINUOUS_DELIVERY_GUIDE.md

# EasyStream Continuous Delivery Guide

Automatically commit and push your changes to GitHub with zero manual intervention.

## Features

- **File Watcher Mode**: Detects file changes in real-time and auto-commits after 30 seconds of inactivity
- **Timer Mode**: Commits and pushes at regular intervals (default: 5 minutes)
- **Smart Exclusions**: Automatically excludes temporary files, sessions, cache, and database files
- **Retry Logic**: Automatically retries failed pushes with exponential backoff
- **Change Summaries**: Generates detailed commit messages with file change lists
- **Zero Configuration**: Works out of the box with sensible defaults

## Quick Start

### Option 1: File Watcher Mode (Recommended)

This mode monitors your files and automatically commits changes 30 seconds after you stop editing:

```powershell
.\start-cd.ps1 watch
```

You'll see:
```
========================================
EasyStream File Watcher Started
========================================
Watching: E:\repos\easystream-main
Branch: dev
Debounce: 30 seconds after last change
========================================

✓ File watcher active. Monitoring for changes...
```

When you save a file:
```
[14:23:45] Changed: setup.php
[14:23:47] Changed: f_core/config.href.php
[14:23:50] Changed: docker-compose.yml

Debounce period elapsed. Processing 3 changes...
ℹ Found 3 changed files
✓ Committed changes
✓ Successfully pushed to GitHub
```

### Option 2: Timer Mode

Commits and pushes at regular intervals (every 5 minutes by default):

```powershell
.\start-cd.ps1 start
```

Change the interval to 1 minute:
```powershell
.\start-cd.ps1 start -Interval 60
```

### Option 3: One-Time Commit

Manually trigger a single commit and push:

```powershell
.\start-cd.ps1 once
```

## Configuration

Edit [.cd-config.json](.cd-config.json) to customize behavior:

```json
{
  "intervalSeconds": 300,
  "branch": "dev",
  "commitPrefix": "auto:",
  "excludePatterns": [
    "f_data/data_sessions/*",
    "f_data/data_cache/_c_tpl/*",
    ".setup_complete",
    "*.log",
    "db_data/*",
    "node_modules/*",
    "vendor/*"
  ],
  "enableNotifications": true,
  "autoStart": false
}
```

### Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `intervalSeconds` | Time between auto-commits (timer mode) | 300 (5 min) |
| `branch` | Git branch to push to | "dev" |
| `commitPrefix` | Prefix for auto-generated commit messages | "auto:" |
| `excludePatterns` | File patterns to ignore | See above |
| `enableNotifications` | Show Windows notifications (future) | true |
| `autoStart` | Start CD on system boot (future) | false |

## Commands Reference

### start-cd.ps1 Commands

```powershell
# Start file watcher mode
.\start-cd.ps1 watch

# Start timer mode (default interval: 5 minutes)
.\start-cd.ps1 start

# Start timer mode with custom interval (60 seconds)
.\start-cd.ps1 start -Interval 60

# Run one-time commit and push
.\start-cd.ps1 once

# Check git status
.\start-cd.ps1 status

# Stop all running CD processes
.\start-cd.ps1 stop

# Show help
.\start-cd.ps1 help
```

### auto-deploy.ps1 Advanced Usage

Direct script usage for advanced scenarios:

```powershell
# File watcher mode with verbose output
.\auto-deploy.ps1 -WatchMode -Verbose

# Timer mode with custom interval and branch
.\auto-deploy.ps1 -IntervalSeconds 120 -Branch main -Verbose

# Custom commit prefix
.\auto-deploy.ps1 -CommitPrefix "wip:" -IntervalSeconds 60
```

## How It Works

### File Watcher Mode

1. **Monitors**: Watches all files in the repository using .NET FileSystemWatcher
2. **Debounces**: Waits 30 seconds after the last file change to avoid committing partial edits
3. **Excludes**: Filters out temporary files based on `.gitignore` and config patterns
4. **Commits**: Stages all changes and creates a commit with file change summary
5. **Pushes**: Uploads to GitHub with retry logic
6. **Repeats**: Continues monitoring for the next change

### Timer Mode

1. **Checks**: Scans for changes at regular intervals
2. **Stages**: Adds all modified, new, and deleted files
3. **Commits**: Creates a timestamped commit with change summary
4. **Pushes**: Uploads to GitHub if there are new commits
5. **Waits**: Sleeps for the configured interval before next check

## Commit Message Format

Auto-generated commits include:

```
auto: Update at 2025-10-26 14:30:00

Changed files:
- setup.php
- docker-compose.yml
- f_core/config.href.php
- ... and 5 more files

🤖 Generated with Claude Code Continuous Delivery

Co-Authored-By: Claude <noreply@anthropic.com>
```

## Excluded Files

The following files are automatically excluded from commits:

- Session files: `f_data/data_sessions/sess_*`
- Cache files: `f_data/data_cache/_c_tpl/*`
- Setup marker: `.setup_complete`
- Database files: `db_data/*`
- Log files: `*.log`
- Dependencies: `node_modules/*`, `vendor/*`
- IDE files: `.vscode/*`, `.idea/*`

## Troubleshooting

### CD not detecting changes

**Problem**: Files changed but no commit triggered

**Solution**:
```powershell
# Check if files are excluded
git status

# Verify .gitignore doesn't over-exclude
cat .gitignore

# Check CD config
cat .cd-config.json
```

### Push failed: Authentication required

**Problem**: Git asks for credentials

**Solution**:
```powershell
# Set up Git credential helper (Windows)
git config --global credential.helper manager

# Or use SSH keys
git remote set-url origin git@github.com:SamiAhmed7777/easystream-main.git
```

### Multiple CD processes running

**Problem**: CD commits too frequently

**Solution**:
```powershell
# Stop all CD processes
.\start-cd.ps1 stop

# Restart with single instance
.\start-cd.ps1 watch
```

### Large files rejected by GitHub

**Problem**: `db_data/*` files are too large

**Solution**:
These files are already excluded in `.gitignore`. If they're already tracked:
```powershell
# Remove from git but keep locally
git rm --cached -r db_data/
git commit -m "Remove database files from tracking"
git push
```

## Running as Background Service

### Option 1: Windows Task Scheduler

1. Open Task Scheduler
2. Create Basic Task
3. Trigger: At system startup
4. Action: Start a program
   - Program: `powershell.exe`
   - Arguments: `-WindowStyle Hidden -File "E:\repos\easystream-main\start-cd.ps1" watch`

### Option 2: PowerShell Background Job

```powershell
# Start in background
Start-Job -ScriptBlock {
    Set-Location "E:\repos\easystream-main"
    .\start-cd.ps1 watch
}

# Check status
Get-Job

# View output
Receive-Job -Id 1 -Keep

# Stop
Stop-Job -Id 1
Remove-Job -Id 1
```

### Option 3: Screen/Tmux (Windows Terminal)

```powershell
# Open new Windows Terminal tab
wt -w 0 nt -d E:\repos\easystream-main powershell -NoExit -Command ".\start-cd.ps1 watch"
```

## Security Considerations

### What Gets Committed

- Application code (PHP, JavaScript, CSS)
- Configuration files (docker-compose.yml, .env templates)
- Documentation (Markdown files)
- SQL schema files

### What's Excluded

- Session data (user sessions)
- Cache (compiled templates)
- Database runtime files (actual data)
- Secrets (`.env` files are tracked but should only contain templates)

### Best Practices

1. **Review `.gitignore`**: Ensure sensitive files are excluded
2. **Use environment variables**: Never commit actual passwords or API keys
3. **Separate repos for secrets**: Use a private repo for production `.env` files
4. **Monitor commits**: Occasionally review auto-commits for unwanted files

## Performance Tips

### For Large Repositories

```json
{
  "intervalSeconds": 600,
  "excludePatterns": [
    "f_data/*",
    "uploads/*",
    "*.mp4",
    "*.mkv"
  ]
}
```

### For Active Development

```json
{
  "intervalSeconds": 180,
  "commitPrefix": "wip:"
}
```

## Integration with IDE

### VS Code

Add to `.vscode/tasks.json`:

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start Continuous Delivery",
      "type": "shell",
      "command": ".\\start-cd.ps1 watch",
      "presentation": {
        "reveal": "always",
        "panel": "dedicated"
      },
      "problemMatcher": []
    }
  ]
}
```

Run with: `Ctrl+Shift+P` → `Tasks: Run Task` → `Start Continuous Delivery`

## FAQ

**Q: Will this commit every keystroke?**
A: No. File watcher mode waits 30 seconds after the last change before committing.

**Q: Can I customize commit messages?**
A: Yes, edit the commit message generation in [auto-deploy.ps1:176-188](auto-deploy.ps1#L176-L188)

**Q: Does this work with pull requests?**
A: Yes, but you may want to squash auto-commits before merging. Consider using a feature branch.

**Q: Can I run this on Linux/Mac?**
A: The scripts are PowerShell-specific. For Linux/Mac, use Git hooks or tools like `watchman` + bash scripts.

**Q: Will this conflict with manual commits?**
A: No. The CD system checks for changes and only commits if there are uncommitted files.

**Q: How do I temporarily pause CD?**
A: Press `Ctrl+C` in the CD terminal, or run `.\start-cd.ps1 stop`

## Examples

### Development Workflow

```powershell
# Morning: Start CD
.\start-cd.ps1 watch

# Work normally - changes auto-commit as you save

# End of day: Review commits
git log --oneline --since="8 hours ago"

# Squash if needed before PR
git rebase -i HEAD~20
```

### Emergency Hotfix

```powershell
# Stop CD
.\start-cd.ps1 stop

# Make critical fix
# ... edit files ...

# Manual commit with detailed message
git add .
git commit -m "fix: Critical security patch for XSS vulnerability"
git push

# Resume CD
.\start-cd.ps1 watch
```

## Support

For issues or questions:
- GitHub Issues: https://github.com/SamiAhmed7777/easystream-main/issues
- Check logs in terminal output
- Use `-Verbose` flag for detailed diagnostics

---

**Next Steps**: [Start using CD now!](#quick-start)