zcf 3.1.2 → 3.1.4

package/templates/codex/en/workflow/git/prompts/git-rollback.md

@@ -0,0 +1,90 @@
+---
+description: Interactively rollback Git branch to historical version; lists branches, versions, then executes reset/revert after confirmation
+allowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()
+argument-hint: [--branch <branch>] [--target <rev>] [--mode reset|revert] [--depth <n>] [--dry-run] [--yes]
+# examples:
+#   - /git-rollback                # Full interactive mode, dry-run
+#   - /git-rollback --branch dev   # Select dev directly, other interactive
+#   - /git-rollback --branch dev --target v1.2.0 --mode reset --yes
+---
+
+# Claude Command: Git Rollback
+
+**Purpose**: Safely and visually rollback a specified branch to an older version.
+Defaults to **read-only preview (`--dry-run`)**; actual execution requires `--yes` or interactive confirmation.
+
+---
+
+## Usage
+
+```bash
+# Pure interactive: list branches → select branch → list recent 20 versions → select target → choose reset or revert → confirm
+/git-rollback
+
+# Specify branch, other interactive
+/git-rollback --branch feature/calculator
+
+# Specify branch and target commit, execute with hard-reset in one go (dangerous)
+/git-rollback --branch main --target 1a2b3c4d --mode reset --yes
+
+# Generate revert commit only (non-destructive rollback), preview
+/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run
+```
+
+### Options
+
+| Option                 | Description                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `--branch <branch>`    | Branch to rollback; interactively selected if omitted.                                                             |
+| `--target <rev>`       | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |
+| `--mode reset\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default.     |
+| `--depth <n>`          | List recent n versions in interactive mode (default 20).                                                           |
+| `--dry-run`            | **Enabled by default**, only preview commands to be executed.                                                      |
+| `--yes`                | Skip all confirmations and execute directly, suitable for CI/CD scripts.                                           |
+
+---
+
+## Interactive Flow
+
+1. **Sync remote** → `git fetch --all --prune`
+2. **List branches** → `git branch -a` (local + remote, filter protected branches)
+3. **Select branch** → User input or parameter
+4. **List versions** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`
+5. **Select target** → User inputs commit hash / tag
+6. **Select mode** → `reset` or `revert`
+7. **Final confirmation** (unless `--yes`)
+8. **Execute rollback**
+   - `reset`: `git switch <branch> && git reset --hard <target>`
+   - `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`
+9. **Push suggestion** → Prompt whether to `git push --force-with-lease` (reset) or regular `git push` (revert)
+
+---
+
+## Safety Guards
+
+- **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.
+- **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.
+- **--dry-run enabled by default**: Prevents accidental operations.
+- **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.
+
+---
+
+## Use Case Examples
+
+| Scenario                                                                    | Command Example                                                  |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0`            | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |
+| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert`     |
+| Research historical bugs, guide newcomers through branch history            | `/git-rollback` (full interactive, dry-run)                      |
+
+---
+
+## Notes
+
+1. **reset vs revert**
+   - **reset** changes history, requires force push and may affect other collaborators, use with caution.
+   - **revert** is safer, generates new commits preserving history, but adds one more record.
+2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.
+3. If repository has CI forced validation, rollback may trigger pipelines automatically; confirm control policies to avoid accidental deployment of old versions.
+
+---

package/templates/codex/en/workflow/git/prompts/git-worktree.md

@@ -0,0 +1,276 @@
+---
+description: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration
+allowed-tools: Read(**), Exec(git worktree add, git worktree list, git worktree remove, git worktree prune, git branch, git checkout, git rev-parse, git stash, git cp, detect-ide, open-ide, which, command, basename, dirname)
+argument-hint: <add|list|remove|prune|migrate> [path] [-b <branch>] [-o|--open] [--track] [--guess-remote] [--detach] [--checkout] [--lock] [--migrate-from <source-path>] [--migrate-stash]
+# examples:
+#   - /git-worktree add feature-ui                     # create new branch 'feature-ui' from main/master
+#   - /git-worktree add feature-ui -o                  # create worktree and open directly in IDE
+#   - /git-worktree add hotfix -b fix/login -o         # create new branch 'fix/login' with path 'hotfix'
+#   - /git-worktree migrate feature-ui --from main     # migrate uncommitted content from main to feature-ui
+#   - /git-worktree migrate feature-ui --stash         # migrate current stash to feature-ui
+---
+
+# Claude Command: Git Worktree
+
+Manage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.
+
+Execute commands directly and provide concise results.
+
+---
+
+## Usage
+
+```bash
+# Basic operations
+/git-worktree add <path>                           # create new branch named <path> from main/master
+/git-worktree add <path> -b <branch>               # create new branch with specified name
+/git-worktree add <path> -o                        # create and open directly in IDE
+/git-worktree list                                 # show all worktree status
+/git-worktree remove <path>                        # remove specified worktree
+/git-worktree prune                                # clean invalid worktree references
+
+# Content migration
+/git-worktree migrate <target> --from <source>     # migrate uncommitted content
+/git-worktree migrate <target> --stash             # migrate stash content
+```
+
+### Options
+
+| Option             | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `add [<path>]`     | Add new worktree in `../.zcf/project-name/<path>`      |
+| `migrate <target>` | Migrate content to specified worktree                  |
+| `list`             | List all worktrees and their status                    |
+| `remove <path>`    | Remove worktree at specified path                      |
+| `prune`            | Clean invalid worktree references                      |
+| `-b <branch>`      | Create new branch and checkout to worktree             |
+| `-o, --open`       | Open directly in IDE after creation (skip prompt)      |
+| `--from <source>`  | Specify migration source path (migrate only)           |
+| `--stash`          | Migrate current stash content (migrate only)           |
+| `--track`          | Set new branch to track corresponding remote branch    |
+| `--guess-remote`   | Auto guess remote branch for tracking                  |
+| `--detach`         | Create detached HEAD worktree                          |
+| `--checkout`       | Checkout immediately after creation (default behavior) |
+| `--lock`           | Lock worktree after creation                           |
+
+---
+
+## What This Command Does
+
+1. **Environment Check**
+   - Verify Git repository using `git rev-parse --is-inside-work-tree`
+   - Detect whether in main repo or existing worktree for smart path calculation
+
+2. **Smart Path Management**
+   - Auto-calculate project name from main repository path using worktree detection
+   - Create worktrees in structured `../.zcf/project-name/<path>` directory
+   - Handle both main repo and worktree execution contexts correctly
+
+```bash
+# Core path calculation logic for worktree detection
+get_main_repo_path() {
+  local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+  local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)
+
+  # Check if in worktree
+  if [[ "$git_common_dir" != "$current_toplevel/.git" ]]; then
+    # In worktree, derive main repo path from git-common-dir
+    dirname "$git_common_dir"
+  else
+    # In main repository
+    echo "$current_toplevel"
+  fi
+}
+
+MAIN_REPO_PATH=$(get_main_repo_path)
+PROJECT_NAME=$(basename "$MAIN_REPO_PATH")
+WORKTREE_BASE="$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME"
+
+# Always use absolute path to prevent nesting issues
+ABSOLUTE_WORKTREE_PATH="$WORKTREE_BASE/<path>"
+```
+
+**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.
+
+3. **Worktree Operations**
+   - **add**: Create new worktree with smart branch/path defaults
+   - **list**: Display all worktrees with branches and status
+   - **remove**: Safely remove worktree and clean references
+   - **prune**: Clean orphaned worktree records
+
+4. **Smart Defaults**
+   - **Branch creation**: When no `-b` specified, create new branch using path name
+   - **Base branch**: New branches created from main/master branch
+   - **Path resolution**: Use branch name as path when unspecified
+   - **IDE integration**: Auto-detect and prompt for IDE opening
+
+5. **Content Migration**
+   - Migrate uncommitted changes between worktrees
+   - Apply stash content to target worktree
+   - Safety checks to prevent conflicts
+
+6. **Safety Features**
+   - **Path conflict prevention**: Check for existing directories before creation
+   - **Branch checkout validation**: Ensure branches aren't already in use
+   - **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree
+   - **Auto-cleanup on removal**: Clean both directory and git references
+   - **Clear status reporting**: Display worktree locations and branch status
+
+7. **Environment File Handling**
+   - **Auto-detection**: Scan `.gitignore` for environment variable file patterns
+   - **Smart copying**: Copy `.env` and `.env.*` files that are listed in `.gitignore`
+   - **Exclusion logic**: Skip `.env.example` and other template files
+   - **Permission preservation**: Maintain original file permissions and timestamps
+   - **User feedback**: Provide clear status on copied environment files
+
+```bash
+# Environment file copying implementation
+copy_environment_files() {
+    local main_repo="$MAIN_REPO_PATH"
+    local target_worktree="$ABSOLUTE_WORKTREE_PATH"
+    local gitignore_file="$main_repo/.gitignore"
+    
+    # Check if .gitignore exists
+    if [[ ! -f "$gitignore_file" ]]; then
+        return 0
+    fi
+    
+    local copied_count=0
+    
+    # Detect .env file
+    if [[ -f "$main_repo/.env" ]] && grep -q "^\.env$" "$gitignore_file"; then
+        cp "$main_repo/.env" "$target_worktree/.env"
+        echo "✅ Copied .env"
+        ((copied_count++))
+    fi
+    
+    # Detect .env.* pattern files (excluding .env.example)
+    for env_file in "$main_repo"/.env.*; do
+        if [[ -f "$env_file" ]] && [[ "$(basename "$env_file")" != ".env.example" ]]; then
+            local filename=$(basename "$env_file")
+            if grep -q "^\.env\.\*$" "$gitignore_file"; then
+                cp "$env_file" "$target_worktree/$filename"
+                echo "✅ Copied $filename"
+                ((copied_count++))
+            fi
+        fi
+    done
+    
+    if [[ $copied_count -gt 0 ]]; then
+        echo "📋 Copied $copied_count environment file(s) from .gitignore"
+    fi
+}
+```
+
+---
+
+## Enhanced Features
+
+### IDE Integration
+
+- **Auto-detection**: VS Code → Cursor → WebStorm → Sublime Text → Vim
+- **Smart prompting**: Ask to open in IDE after worktree creation
+- **Direct open**: Use `-o` flag to skip prompt and open immediately
+- **Custom configuration**: Configurable via git config
+
+### Content Migration System
+
+```bash
+# Migrate uncommitted changes
+/git-worktree migrate feature-ui --from main
+/git-worktree migrate hotfix --from ../other-worktree
+
+# Migrate stash content
+/git-worktree migrate feature-ui --stash
+```
+
+**Migration Flow**:
+
+1. Verify source has uncommitted content
+2. Ensure target worktree is clean
+3. Show changes to be migrated
+4. Execute safe migration using git commands
+5. Confirm results and suggest next steps
+
+---
+
+## Examples
+
+```bash
+# Basic usage
+/git-worktree add feature-ui                       # create new branch 'feature-ui' from main/master
+/git-worktree add feature-ui -b my-feature         # create new branch 'my-feature' with path 'feature-ui'
+/git-worktree add feature-ui -o                    # create and open in IDE directly
+
+# Content migration scenarios
+/git-worktree add feature-ui -b feature/new-ui     # create new feature worktree
+/git-worktree migrate feature-ui --from main       # migrate uncommitted changes
+/git-worktree migrate hotfix --stash               # migrate stash content
+
+# Management operations
+/git-worktree list                                 # view all worktrees
+/git-worktree remove feature-ui                    # remove unneeded worktree
+/git-worktree prune                                # clean invalid references
+```
+
+**Example Output**:
+
+```
+✅ Worktree created at ../.zcf/project-name/feature-ui
+✅ Copied .env
+✅ Copied .env.local
+📋 Copied 2 environment file(s) from .gitignore
+🖥️ Open ../.zcf/project-name/feature-ui in IDE? [y/n]: y
+🚀 Opening ../.zcf/project-name/feature-ui in VS Code...
+```
+
+---
+
+## Directory Structure
+
+```
+parent-directory/
+├── your-project/            # main project
+│   ├── .git/
+│   └── src/
+└── .zcf/                    # worktree management
+    └── your-project/        # project worktrees
+        ├── feature-ui/      # feature branch
+        ├── hotfix/          # hotfix branch
+        └── debug/           # debug worktree
+```
+
+---
+
+## Configuration
+
+### IDE Configuration
+
+- Supports VS Code, Cursor, WebStorm, Sublime Text, Vim
+- Configurable via git config for custom IDEs
+- Auto-detection with priority-based selection
+
+### Custom IDE Setup
+
+```bash
+# Configure custom IDE
+git config worktree.ide.custom.sublime "subl %s"
+git config worktree.ide.preferred "sublime"
+
+# Control auto-detection
+git config worktree.ide.autodetect true  # default
+```
+
+---
+
+## Notes
+
+- **Performance**: Worktrees share `.git` directory, saving disk space
+- **Safety**: Path conflict prevention and branch checkout validation
+- **Migration**: Only uncommitted changes; use `git cherry-pick` for commits
+- **IDE requirement**: Command-line tools must be in PATH
+- **Cross-platform**: Supports Windows, macOS, Linux
+- **Environment files**: Automatically copies environment files listed in `.gitignore` to new worktrees
+- **File exclusions**: Template files like `.env.example` are preserved in main repo only
+
+---