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:

.\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):

.\start-cd.ps1 start

Change the interval to 1 minute:

.\start-cd.ps1 start -Interval 60

Option 3: One-Time Commit

Manually trigger a single commit and push:

.\start-cd.ps1 once

Configuration

Edit .cd-config.json to customize behavior:

{
  "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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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)

# 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

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

For Active Development

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

Integration with IDE

VS Code

Add to .vscode/tasks.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

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

# 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

# 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!