@samaksh/git-worker 0.0.0-stage → 0.2.0

package/docs/usage.md

@@ -0,0 +1,337 @@
+# Git Worker CLI & Usage Guide
+
+`git-worker` is a safe, interactive CLI tool for synchronizing templates and environment files across many Git branches without needing to checkout each branch manually in your working directory.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Interactive wizard (run from anywhere)
+git-worker
+
+# 2. Target a remote repository URL directly
+git-worker --repo https://github.com/my-org/my-project.git
+
+# 3. Target a local repository with specific branches and file
+git-worker --repo ./my-project --branch "uat/*" --file .env
+
+# 4. Non-interactive CI mode (auto-approve, never push)
+git-worker --repo https://github.com/my-org/my-project.git --branch "uat/*" --file .env --ci --auto-approve --push never
+```
+
+---
+
+## 1. Repository Resolution & First Step
+
+When you execute `git-worker` without arguments, it begins by checking your current environment and available cached repositories:
+
+1. **Inside a Git Repository:**  
+   If the current working directory is a Git repository, `git-worker` detects it and gives you the choice to use it, select from cached repositories, clone a new remote, or target a different path:
+   ```text
+   ◆ What repository would you like to target?
+   │  ● Use current repository (/Users/username/project)
+   │  ○ 📦 Select from cached repositories (2 available)
+   │  ○ Clone a remote repository URL
+   │  ○ Specify a different local repository path
+   ```
+2. **Outside a Git Repository:**  
+   If run from a non-git directory, the TUI presents:
+   ```text
+   ◆ How would you like to target a repository?
+   │  ● 📦 Select from cached repositories (2 available)
+   │  ○ Clone a remote repository URL
+   │  ○ Specify path to a local Git repository
+   ```
+
+### Listing & Selecting Cached Repositories
+Choosing **Select from cached repositories** displays all previously cloned and cached repositories in `~/.git-worker`, showing their **name**, **remote URL**, and cached date:
+
+```text
+  Name                 Remote URL / Path                              Cached Date
+  ────────────────────────────────────────────────────────────────────────────────
+  remote               https://github.com/my-org/my-project.git       2026-10-29
+  express              https://github.com/expressjs/express.git       2026-10-28
+  ────────────────────────────────────────────────────────────────────────────────
+
+? Select a cached repository to target:
+  ● ◆ my-project (https://github.com/my-org/my-project.git)
+  ○ ◆ express (https://github.com/expressjs/express.git)
+  ○ ← Back to repository menu
+```
+
+Selecting any repository immediately loads it and fetches any new branch updates from the remote, skipping the full clone.
+
+> [!TIP]
+> - Jump straight to cached repository selection from the CLI using `-c` or `--cached`:
+>   ```bash
+>   git-worker --cached
+>   ```
+> - Bypass the prompt at any time by passing `--repo <url-or-path>` or `-r <url-or-path>`.
+
+---
+
+## 2. Interactive Branch Selection
+
+In the branch selection stage, `git-worker` provides an interactive selection menu designed for repositories with many branches:
+
+```text
+  Branch & Target Selection
+  ────────────────────────────────────────
+│
+◇  Found 10 branches
+
+? Branch selection (0 of 10 branches selected):
+  ● 🔍 Filter by pattern or regex (glob e.g. uat/*, or regex /uat.*/)
+  ○ 🌟 Select ALL branches (10 branches)
+  ○ 📋 Choose individually from list
+  ○ 🔄 Invert selection (select all 10 branches)
+```
+
+### Selection Capabilities
+
+1. **Regex & Glob Pattern Matching:**
+   Choose **Filter by pattern or regex** and enter:
+   - **Regex:** `/uat.*/`, `/^feat\//`, or `/release/i`
+   - **Glob:** `uat/*`, `*orders`, or `uat*`
+   - **Prefix / Substring:** `uat/` or `payments`
+   
+   Matched branches are highlighted and selected immediately:
+   ```text
+   ✓ Pattern '/uat.*/' matched 4 branch(es):
+       • uat/inventory
+       • uat/notifications
+       • uat/orders
+       • uat/payments
+   ```
+
+2. **Select ALL Branches:**
+   Selects every branch in the repository with a single action.
+
+3. **Invert Selection:**
+   Flips the current selection against all repository branches. For example, if 4 `uat/*` branches are selected out of 10, choosing **Invert selection** selects the other 6 branches.
+
+4. **Customize from List:**
+   Opens a checkbox multiselect with current selections pre-checked, allowing you to toggle individual branches on or off using the Space key.
+
+5. **Instant Confirmation:**
+   As soon as branches are selected, **➜ Confirm and proceed** is the top default option: press Enter to immediately advance to target file selection.
+
+> [!TIP]
+> From the CLI, you can combine `--branch <pattern>` with `--invert-branch` (`-i`) to filter or invert non-interactively:
+> ```bash
+> git-worker --branch "uat/*" --invert-branch
+> ```
+
+---
+
+## 3. Workspace Storage in `~/.git-worker`
+
+To guarantee that your active working tree and uncommitted changes are never touched or corrupted, `git-worker` performs all operations inside an isolated, dedicated directory in your home folder:
+
+```text
+~/.git-worker/
+└── projects/
+    └── <project-id>/               # Deterministic SHA-256 hash of repository remote/path
+        ├── repo/                   # Managed Git clone with all remotes/branches
+        ├── state/                  # Saved templates and branch resolution states
+        ├── reports/                # Run summaries and execution audit logs
+        ├── .git-worker-marker      # Workspace ownership marker
+        └── .git-worker-lock        # Process lock (prevents concurrent collisions)
+```
+
+- **Zero pollution:** Your project worktree stays clean and untouched.
+- **Safe isolation:** Re-indexes, resets, and path-scoped commits happen only within `repo/`.
+- **Fault-tolerant locking:** Stale lock files from crashed processes are automatically detected and cleaned.
+
+---
+
+## 4. Cached Clone Detection & Reuse
+
+When targeting a remote repository URL that was previously cloned into `~/.git-worker`:
+
+1. `git-worker` detects that a managed clone is already present for this remote.
+2. It notifies you in the console:
+   ```text
+   ◇  Project workspace ready
+     • Using cached repository clone (already downloaded)
+       https://github.com/org/repo.git
+   │
+   ◒  Using cached repository — fetching latest branches…
+   ◇  Repository synced
+   ```
+3. Instead of re-downloading the entire repository, it executes a fast `git fetch origin` to retrieve any new branches or updated commits.
+
+---
+
+## 5. Cache Management (`cache list` & `cache clean`)
+
+`git-worker` provides built-in commands to inspect and clean cached workspaces and templates in `~/.git-worker`.
+
+### List Cached Projects
+
+View all cached repositories, their project IDs, remote URLs, and creation dates:
+
+```bash
+git-worker cache list
+# or shorthand alias:
+git-worker cache ls
+```
+
+**Example output:**
+```text
+  Cached Projects (~/.git-worker)
+  ────────────────────────────────────────
+
+  ID                 Target Repository / Remote                    Cached Date
+  ──────────────────────────────────────────────────────────────────────────────
+  b3676ac05b37f54c   https://github.com/my-org/my-project.git      2026-10-28 09:50:52
+  ──────────────────────────────────────────────────────────────────────────────
+  Total: 1 project(s) cached in /Users/username/.git-worker/projects
+```
+
+---
+
+### Clean Cache
+
+Remove cached repositories to reclaim disk space or force a clean re-clone.
+
+#### A. Interactive Clean Menu
+Running clean without arguments displays an interactive picker:
+```bash
+git-worker cache clean
+# or shorthand alias:
+git-worker clean
+```
+```text
+  Select cache to remove:
+  ● Clear ALL cached projects (1 projects)
+  ○ https://github.com/my-org/my-project.git (ID: b3676ac05b37f54c)
+```
+
+#### B. Clean a Specific Project
+Specify a project ID, remote URL, or path fragment:
+```bash
+git-worker cache clean b3676ac05b37f54c
+# or
+git-worker clean https://github.com/my-org/my-project.git
+```
+
+#### C. Clean All Projects
+Remove all cached repositories from `~/.git-worker/projects`:
+```bash
+git-worker cache clean --all
+# or with non-interactive confirmation:
+git-worker clean -a -y
+```
+
+---
+
+## 6. CLI Command Reference
+
+### Main Command Options
+
+```text
+git-worker [options]
+```
+
+| Option | Shorthand | Description | Default |
+|---|---|---|---|
+| `--repo <path-or-url>` | `-r` | Target local repository path or remote URL | CWD or interactive prompt |
+| `--cached` | `-c` | Select from previously cloned and cached repositories | `false` |
+| `--branch <pattern>` | `-b` | Glob (e.g. `uat/*`) or regex (e.g. `/uat.*/`) pattern | Interactive selection |
+| `--invert-branch` | `-i` | Invert the branch selection pattern | `false` |
+| `--file <path>` | `-f` | Path to target file within repo (e.g. `.env`) | Interactive prompt |
+| `--editor <editor>` | `-e` | Editor for template editing (`vscode`, `vim`, or command) | Configured default |
+| `--commit-msg <msg>`| `-m` | Git commit message to use for applied changes | `"chore(config): sync <file> via git-worker"` |
+| `--push <policy>` | `-p` | Push policy: `prompt`, `always`, or `never` | `prompt` |
+| `--remote <remote>` | | Git remote name to push to | `origin` |
+| `--auto-approve` | | Auto-approve all planned branch changes | `false` |
+| `--ci` | | Non-interactive CI mode (fails on missing input) | `false` |
+| `--version` | `-v` | Output current git-worker version | |
+| `--help` | `-h` | Display CLI help text | |
+
+### Cache Subcommands
+
+| Command | Shorthand Alias | Description |
+|---|---|---|
+| `git-worker cache list` | `git-worker cache ls` | List all cached repositories in `~/.git-worker` |
+| `git-worker cache clean [target]` | `git-worker clean [target]` | Remove cache for target ID/URL or prompt interactively |
+| `git-worker cache clean -a -y` | `git-worker clean -a -y` | Remove all cached checkouts without confirmation prompt |
+
+---
+
+## 7. `.env` Template Syntax & Rules
+
+### Static Values (Enforced on All Branches)
+Values written as standard `KEY=VALUE` are applied identically across every selected branch:
+```dotenv
+DB_NAME=uat_database
+PORT=8080
+LOG_LEVEL=info
+```
+If `DB_NAME` had a different value on `uat/service-a`, it is updated to `uat_database`.
+
+### Dynamic Placeholders (Read from Branch)
+Values written with curly braces `{KEY}` instruct git-worker to look up the existing value on each branch:
+```dotenv
+SERVICE_NAME={SERVICE_NAME}
+CLIENT_SECRET={CLIENT_SECRET}
+```
+- If the branch already has `SERVICE_NAME=billing`, `billing` is preserved.
+- If the branch **does not** contain `CLIENT_SECRET`, git-worker prompts you for that branch's value before generating the diff. In CI mode, missing values fail cleanly without hanging.
+
+### Processing Rules
+- **Unmanaged keys preserved:** Any key in a branch's `.env` that is **not** mentioned in the template is kept intact in its original location.
+- **Export syntax preserved:** `export KEY=value` declarations retain their `export` prefix.
+- **Comments and spacing:** Comments (`# ...`) and blank lines are maintained.
+- **Path-scoped staging:** Git worker stages strictly the target file (`git add -- .env`).
+- **Safety checks:** Pre-apply branch tip verification ensures no commits were pushed upstream while the review was pending.
+
+---
+
+## 8. Source-of-Truth Templates (Dockerfile, JSON, YAML, configs)
+
+For any file format other than `.env` (such as `Dockerfile`, `package.json`, `.github/workflows/deploy.yml`, `config.json`), the template serves as the **declarative Source of Truth**.
+
+### How It Works
+- The template content is interpolated with variables and completely replaces the target file on each target branch (or creates a brand-new file if it didn't exist).
+- Variables use standard `${VAR}` and `${VAR:-default}` syntax.
+- Values for `${VAR}` are pulled automatically from each branch's own `.env` file!
+
+### Example: Multi-Branch `Dockerfile`
+```dockerfile
+# Source of truth Dockerfile template
+FROM node:20-alpine AS base
+ENV SERVICE_NAME=${SERVICE_NAME}
+ENV BRANCH_NAME=${BRANCH_NAME}
+ENV BRANCH_SLUG=${BRANCH_SLUG}
+EXPOSE ${PORT:-8080}
+```
+
+### Available Built-in Variables
+| Variable | Description | Example |
+|---|---|---|
+| `${BRANCH_NAME}` | Full current branch name | `uat/payments-service` |
+| `${BRANCH_SLUG}` | Sanitized DNS/Docker-safe branch name | `uat-payments-service` |
+| `${REPO_NAME}` | Current repository name | `gitworker` |
+| `${COMMIT_SHA}` | Branch commit SHA-256 | `99b3cff8...` |
+| `${SHORT_SHA}` | 7-character commit SHA | `99b3cff` |
+
+### Fallback Defaults (`${VAR:-default}`)
+If a variable is optional or has a standard fallback:
+```yaml
+# deploy.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ${BRANCH_SLUG}
+spec:
+  replicas: ${REPLICAS:-2}
+```
+If `REPLICAS` is not defined in a branch's `.env`, it defaults to `2`.
+
+### Syntax Validation & State Persistence
+- **Automatic Syntax Checking:** Immediately upon saving in your editor, `git-worker` validates that JSON is valid JSON, YAML is valid YAML, and all `${...}` delimiters are properly closed. If an error is found, you can re-edit to fix it before any changes are planned.
+- **Persistent Template State:** When a template is applied, it is saved in `~/.git-worker/projects/<id>/state/`. The next time you open `git-worker` for that file, it loads your previously applied template so you don't lose any changes.
+

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@samaksh/git-worker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Safe, composable TypeScript CLI/TUI for applying reviewed file changes across many Git branches",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "git-worker": "dist/cli/index.js",
+    "gitworker": "dist/cli/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/cli/index.ts",
+    "demo": "tsx demo/index.ts",
+    "demo:ci": "tsx demo/index.ts --ci",
+    "demo:clean": "tsx demo/index.ts --clean",
+    "test": "vitest",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "git",
+    "cli",
+    "env",
+    "branches",
+    "multi-branch"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "diff": "^5.2.0",
+    "inquirer": "^9.2.0",
+    "picocolors": "^1.1.1",
+    "simple-git": "^3.22.0",
+    "yaml": "^2.4.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^5.0.0",
+    "@types/inquirer": "^9.0.0",
+    "@types/node": "^20.11.0",
+    "eslint": "^8.56.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  }
+}