@samaksh/git-worker 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# Git Worker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A safe, composable TypeScript CLI/TUI for applying reviewed file changes across many Git branches.
+
+## Overview
+
+Git Worker lets you target a Git repository, select branches and a file, edit a reusable template, preview exact per-branch changes without checking out branches, approve/reject them, and then commit and optionally push approved changes. It works with a handful or 100+ branches without requiring one persistent worktree per branch.
+
+## Design Principles
+
+- **Readable over clever** - Small functions, explicit types, straightforward control flow
+- **Functional core, imperative shell** - Pure transformations/validation; side effects injected via services
+- **Inspect without checkout** - Uses `git show`, `git ls-tree`, `git cat-file` to plan changes
+- **Review before mutation** - Collect missing values and build diffs before any checkout/commit
+- **Safe by default** - Never modifies your original repository; only commits to managed disposable checkouts
+- **Per-branch fault isolation** - One branch failure doesn't corrupt others
+
+## How It Works
+
+1. **Resolve & sync** - Detects current Git repository or prompts to clone a remote URL into `~/.git-worker`. If already cloned, reuses the cached clone and fetches latest branches.
+2. **Select** - Choose branches (glob e.g. `uat/*`, regex e.g. `/uat.*/`, select all, or invert selection) and target file
+3. **Template** - Edit a template in VS Code or Vim (or restore previously applied template):
+   - **For `.env` files (AST Reconciliation)**: `KEY=value` sets static values; `KEY={KEY}` reads existing branch values; unmanaged keys and comments are preserved.
+   - **For other files (`Dockerfile`, JSON, YAML, configs)**: The template is the declarative **Source of Truth**; variables like `${VAR}` or `${VAR:-default}` are resolved per-branch from that branch's `.env`, alongside built-ins (`${BRANCH_NAME}`, `${BRANCH_SLUG}`). The evaluated template overrides or creates the file.
+   - **Syntax Validation**: Checks JSON/YAML syntax immediately before planning.
+4. **Plan & review** - See exact diffs per branch, approve/reject individually
+5. **Apply & push** - Commits approved changes in a managed checkout, optionally pushes with confirmation
+
+## Configuration Defaults (Chosen)
+
+We made reasonable defaults for the open decisions. These are easy to change later.
+
+| Decision | Default | Rationale |
+|---|---|---|
+| **Remove key from template** | **Preserve** on branches | Safest - never deletes keys implicitly. If you need deletion, use an explicit delete operation in the future. |
+| **Source repo with no remote** | **Prompt or reject with error** | When outside a repo, prompts to clone remote or target path. Requires a remote to avoid mutating local-only repos unexpectedly. |
+| **Save template on partial success** | **Save after first successful commit** (or after explicit approval if no commits but reviewed) | Preserves progress if some branches succeed and others fail. Partial status is clearly reported. |
+| **Editable review snapshots** | **Read-only diff for MVP** | Much safer. To change results, re-edit the template and re-run the plan. Prevents accidental manual edits creating inconsistent diffs. |
+| **Secrets in diffs** | **Show in interactive diff with warning**; **redact from exported reports by default** | You need to see secrets to review `.env` changes, but exports (JSON/Markdown) redact by default to avoid accidental leaks. |
+
+## CLI Usage
+
+```bash
+# Interactive mode (prompts to use current repo, select cached repo, or clone remote)
+git-worker
+
+# Select from previously cloned/cached repositories directly
+git-worker --cached
+
+# Target a remote repository URL directly
+git-worker --repo https://github.com/my-org/my-project.git
+
+# Target a local repo with specific branches and file
+git-worker --repo ../my-repo --branch 'uat/*' --file .env
+
+# Non-interactive CI mode
+git-worker --repo git@github.com:org/repo.git --branch 'uat/*' --file .env --ci --push never
+
+# Cache management
+git-worker cache list               # List all cached repositories in ~/.git-worker
+git-worker cache clean [target]     # Clean a specific project or select interactively
+git-worker cache clean --all        # Clean all cached checkouts (or: git-worker clean -a -y)
+```
+
+Key flags: `--repo/-r`, `--cached/-c`, `--branch/-b`, `--invert-branch/-i`, `--file/-f`, `--editor/-e`, `--commit-msg/-m`, `--push/-p`, `--remote`, `--auto-approve`, `--ci`
+
+## Workspace Layout
+
+Git Worker stores all checkouts, templates, and state under `~/.git-worker/` in the user's home directory:
+
+```
+~/.git-worker/
+  projects/
+    <stable-project-id>/
+      repo/                # Disposable checkout owned by git-worker
+      staging/<run-id>/    # Before/after snapshots outside repo
+      state/               # Saved templates (per project+target)
+      reports/             # Run reports (optional)
+      .git-worker-marker   # Ownership verification marker
+      .git-worker-lock     # Process lock
+```
+
+**Safety guarantees:**
+- Never touches your original repository
+- Only stages target paths (`git add -- <path>`)
+- Revalidates branch tips before applying (skips if changed)
+- Resets/cleans only inside verified managed checkout
+- Commits/pushes per-branch with fault isolation
+
+## Supported Editors
+
+- **VS Code (preferred)**: `code --wait` for editing, `code --diff` for review
+- **Vim**: `vim` for editing, `vim -d`/`vimdiff` for review
+
+## Development Status
+
+This is the implementation blueprint. See [GIT_WORKER_PROJECT_PLAN.md](./GIT_WORKER_PROJECT_PLAN.md) for the full architecture, API contracts, and roadmap.
+
+## Non-Goals (MVP)
+
+- One-worktree-per-branch persistent checkout farm
+- Remote/team-shared template state  
+- Complex drift database or three-way merge
+- Automatic guessing of missing values
+- Implicit deletion of unmanaged keys
+- Multi-repo distributed transactions
+- Full support for arbitrary YAML/JSON/Dockerfile/Groovy (only `.env` in MVP)
+
+## Documentation
+
+- [Architecture](docs/architecture.md) - Pipeline design, safety model, and structure
+- [Features](docs/FEATURES.md) - Complete feature list and capabilities  
+- [Services](docs/SERVICES.md) - Service APIs and dependency injection
+- [Usage Guide](docs/usage.md) - Detailed usage examples
+- [Implementation Plan](GIT_WORKER_PROJECT_PLAN.md) - Full blueprint and roadmap

package/dist/app.d.ts

@@ -0,0 +1,2 @@
+import { CliInput, RunContext, Result } from "./core/types.js";
+export declare function run(input: CliInput): Promise<Result<RunContext>>;

package/dist/app.js

@@ -0,0 +1,48 @@
+import { loadConfig } from "./config/load.js";
+import { pipeline } from "./core/pipeline.js";
+// Services
+import { createGitReader } from "./services/git/reader.js";
+import { createGitOps } from "./services/git/ops.js";
+import { createWorkspaceManager } from "./services/workspace/manager.js";
+import { createTemplateService } from "./services/template/transform.js";
+import { createStateService } from "./services/state/index.js";
+import { createEditorService } from "./services/editor/index.js";
+import { createReviewService } from "./services/review/index.js";
+// Stages
+import { resolveProjectStage } from "./stages/resolve-project.js";
+import { syncRepositoryStage } from "./stages/sync.js";
+import { selectTargetsStage } from "./stages/select.js";
+import { checkEligibilityStage } from "./stages/eligibility.js";
+import { loadTemplateStage } from "./stages/load-template.js";
+import { editTemplateStage } from "./stages/edit-template.js";
+import { planChangesStage } from "./stages/plan.js";
+import { reviewChangesStage } from "./stages/review.js";
+import { applyChangesStage } from "./stages/apply.js";
+import { pushChangesStage } from "./stages/push.js";
+import { reportResultsStage } from "./stages/report.js";
+function createServices() {
+    return {
+        git: createGitReader(),
+        gitOps: createGitOps(),
+        workspace: createWorkspaceManager(),
+        template: createTemplateService(),
+        state: createStateService(),
+        editor: createEditorService(),
+        review: createReviewService(),
+    };
+}
+export async function run(input) {
+    const config = loadConfig(input);
+    const services = createServices();
+    const deps = { config, services };
+    const context = {
+        runId: `${Date.now()}`,
+        input,
+    };
+    const runPipeline = pipeline(resolveProjectStage, syncRepositoryStage, selectTargetsStage, checkEligibilityStage, loadTemplateStage, editTemplateStage, planChangesStage, reviewChangesStage, applyChangesStage, pushChangesStage, reportResultsStage);
+    const result = await runPipeline(context, deps);
+    if (result.ok && result.value.project) {
+        services.workspace.releaseLock(result.value.project);
+    }
+    return result;
+}

package/dist/cli/commands.d.ts

@@ -0,0 +1,6 @@
+export declare function handleCacheList(): Promise<void>;
+export declare function handleCacheClean(target?: string, options?: {
+    all?: boolean;
+    yes?: boolean;
+    force?: boolean;
+}): Promise<void>;

package/dist/cli/commands.js

@@ -0,0 +1,111 @@
+import chalk from "chalk";
+import { clack, sectionHeader, statusLine } from "../utils/ui.js";
+import { listCachedProjects, clearProjectCache, clearAllCache, } from "../services/workspace/cache.js";
+import { getWorkspaceRoot } from "../services/workspace/manager.js";
+export async function handleCacheList() {
+    const root = getWorkspaceRoot();
+    sectionHeader("Cached Projects (~/.git-worker)");
+    const projects = await listCachedProjects();
+    if (projects.length === 0) {
+        console.log("");
+        clack.log.info(`No cached repositories found in ${root}/projects`);
+        console.log("");
+        return;
+    }
+    console.log("");
+    console.log(chalk.bold(`  ${"Name".padEnd(20)} ${"Remote URL / Path".padEnd(46)} Cached Date`));
+    console.log(chalk.gray("  " + "─".repeat(80)));
+    for (const p of projects) {
+        const name = chalk.cyan(p.name.slice(0, 18).padEnd(20));
+        const target = (p.remoteUrl || p.sourceRepoPath || "(unknown)").slice(0, 44).padEnd(46);
+        const date = p.createdAt ? p.createdAt.slice(0, 10) : "unknown";
+        console.log(`  ${name} ${chalk.white(target)} ${chalk.gray(date)}`);
+    }
+    console.log(chalk.gray("  " + "─".repeat(80)));
+    console.log(chalk.gray(`  Total: ${projects.length} repository/repositories cached in ${root}/projects`));
+    console.log("");
+}
+export async function handleCacheClean(target, options) {
+    const root = getWorkspaceRoot();
+    const projects = await listCachedProjects();
+    if (projects.length === 0) {
+        clack.log.info(`No cached repositories found in ${root}/projects`);
+        return;
+    }
+    const skipConfirm = options?.yes || options?.force || Boolean(process.env.CI);
+    // 1. If explicit --all flag provided
+    if (options?.all) {
+        if (!skipConfirm) {
+            const confirm = await clack.confirm({
+                message: `Are you sure you want to remove ALL ${projects.length} cached project(s) from ${root}?`,
+                initialValue: true,
+            });
+            if (clack.isCancel(confirm) || !confirm) {
+                clack.log.warn("Cache clean cancelled.");
+                return;
+            }
+        }
+        const result = await clearAllCache();
+        if (!result.ok) {
+            clack.log.error(result.error.message);
+            process.exit(1);
+        }
+        statusLine("ok", `Cleared all cached projects (${result.value.count} removed)`);
+        return;
+    }
+    // 2. If a specific target ID / URL / path was passed as positional argument
+    if (target) {
+        const result = await clearProjectCache(target);
+        if (!result.ok) {
+            clack.log.error(result.error.message);
+            process.exit(1);
+        }
+        statusLine("ok", `Removed cache for: ${result.value.removed}`);
+        return;
+    }
+    // 3. Interactive prompt
+    sectionHeader("Clean Cache");
+    const choice = await clack.select({
+        message: "Select cache to remove:",
+        options: [
+            {
+                value: "__ALL__",
+                label: `Clear ALL cached projects (${projects.length} projects)`,
+                hint: `removes all checkouts in ${root}/projects`,
+            },
+            ...projects.map((p) => ({
+                value: p.id,
+                label: `${p.name}  (${p.remoteUrl || p.sourceRepoPath})`,
+                hint: `ID: ${p.id}  (${p.createdAt ? p.createdAt.slice(0, 10) : ""})`,
+            })),
+        ],
+    });
+    if (clack.isCancel(choice)) {
+        clack.log.warn("Cancelled.");
+        return;
+    }
+    if (choice === "__ALL__") {
+        const confirm = await clack.confirm({
+            message: `Are you sure you want to remove ALL ${projects.length} cached project(s)?`,
+            initialValue: true,
+        });
+        if (clack.isCancel(confirm) || !confirm) {
+            clack.log.warn("Cancelled.");
+            return;
+        }
+        const result = await clearAllCache();
+        if (!result.ok) {
+            clack.log.error(result.error.message);
+            process.exit(1);
+        }
+        statusLine("ok", `Cleared all cached projects (${result.value.count} removed)`);
+        return;
+    }
+    // Specific selected project
+    const result = await clearProjectCache(choice);
+    if (!result.ok) {
+        clack.log.error(result.error.message);
+        process.exit(1);
+    }
+    statusLine("ok", `Removed cache for: ${result.value.removed}`);
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { run } from "../app.js";
+import { handleCacheList, handleCacheClean } from "./commands.js";
+import chalk from "chalk";
+const program = new Command();
+program
+    .name("git-worker")
+    .description("Safe, composable CLI/TUI for applying reviewed file changes across many Git branches")
+    .version("0.2.0")
+    .option("-r, --repo <path>", "Repository path or remote URL (default: current directory)")
+    .option("-c, --cached", "Select from previously cloned and cached repositories")
+    .option("-b, --branch <pattern>", "Branch pattern — glob (uat/*) or regex (/uat.*/)")
+    .option("-i, --invert-branch", "Invert the branch selection pattern")
+    .option("-f, --file <path>", "Target file path inside the repository (e.g. .env)")
+    .option("-e, --editor <name>", "Editor to use: code (VS Code) or vim")
+    .option("-m, --commit-msg <message>", "Commit message")
+    .option("-p, --push <policy>", "Push policy: prompt (default) | always | never")
+    .option("--remote <name>", "Git remote name (default: origin)")
+    .option("--auto-approve", "Auto-approve all changes (skip interactive review)")
+    .option("--ci", "CI mode: non-interactive, fail on missing dynamic values")
+    .action(async (opts) => {
+    // Validate push policy
+    if (opts.push && !["prompt", "always", "never"].includes(opts.push)) {
+        console.error(chalk.red(`  ✗ Invalid push policy '${opts.push}'. Must be: prompt | always | never`));
+        process.exit(1);
+    }
+    // Validate incompatible combinations
+    if (opts.ci && opts.push === "prompt") {
+        console.error(chalk.yellow(`  ⚠ Warning: --ci with --push prompt will not push (no interactive prompt in CI). Use --push always or --push never.`));
+    }
+    try {
+        const result = await run({
+            repo: opts.repo,
+            cached: opts.cached ?? false,
+            branch: opts.branch,
+            invertBranch: opts.invertBranch ?? false,
+            file: opts.file,
+            editor: opts.editor,
+            commitMsg: opts.commitMsg,
+            push: opts.push,
+            remote: opts.remote,
+            autoApprove: opts.autoApprove ?? false,
+            ci: opts.ci ?? false,
+        });
+        if (!result.ok) {
+            const { error } = result;
+            if (error.category === "INPUT_CANCELLED") {
+                console.log(chalk.gray("\n  Cancelled."));
+                process.exit(0);
+            }
+            console.error(chalk.red(`\n  ✗ [${error.category}] ${error.message}`));
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    catch (e) {
+        console.error(chalk.red(`\n  ✗ Fatal: ${e.message}`));
+        if (process.env.DEBUG) {
+            console.error(e.stack);
+        }
+        process.exit(1);
+    }
+});
+// ── Cache management subcommands ──────────────────────────────────────────
+const cacheCmd = program
+    .command("cache")
+    .description("Manage git-worker's cached workspaces and repositories (~/.git-worker)");
+cacheCmd
+    .command("list")
+    .alias("ls")
+    .description("List all cached projects")
+    .action(async () => {
+    try {
+        await handleCacheList();
+        process.exit(0);
+    }
+    catch (e) {
+        console.error(chalk.red(`  ✗ Error: ${e.message}`));
+        process.exit(1);
+    }
+});
+cacheCmd
+    .command("clean [target]")
+    .alias("clear")
+    .description("Clean workspace cache (all or a specific project)")
+    .option("-a, --all", "Clean all cached projects")
+    .option("-y, --yes", "Skip confirmation prompt")
+    .action(async (target, opts) => {
+    try {
+        await handleCacheClean(target, opts);
+        process.exit(0);
+    }
+    catch (e) {
+        console.error(chalk.red(`  ✗ Error: ${e.message}`));
+        process.exit(1);
+    }
+});
+// Convenient top-level alias: git-worker clean [target] [-a]
+program
+    .command("clean [target]")
+    .description("Shorthand to clean cached workspace(s)")
+    .option("-a, --all", "Clean all cached projects")
+    .option("-y, --yes", "Skip confirmation prompt")
+    .action(async (target, opts) => {
+    try {
+        await handleCacheClean(target, opts);
+        process.exit(0);
+    }
+    catch (e) {
+        console.error(chalk.red(`  ✗ Error: ${e.message}`));
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/config/defaults.d.ts

@@ -0,0 +1,2 @@
+import { AppConfig } from "./schema.js";
+export declare const DEFAULT_CONFIG: AppConfig;

package/dist/config/defaults.js

@@ -0,0 +1,44 @@
+export const DEFAULT_CONFIG = {
+    git: {
+        remote: "origin",
+        fetchPrune: true,
+        cleanMode: "tracked-and-untracked",
+        pushPolicy: "prompt",
+        commitMessage: "chore: sync configuration",
+    },
+    workspace: {
+        root: ".git-worker",
+        lockTimeoutMs: 30000,
+    },
+    editor: {
+        name: "code",
+        editCommand: ["code", "--wait", "{file}"],
+        diffCommand: ["code", "--diff", "{before}", "{after}"],
+    },
+    template: {
+        placeholderOpen: "{",
+        placeholderClose: "}",
+        missingValuePolicy: "prompt-each-branch",
+        emptyValueIsPresent: true,
+        unmanagedKeyPolicy: "preserve",
+        removedTemplateKeyPolicy: "preserve",
+    },
+    review: {
+        autoApprove: false,
+        readOnlySnapshots: true,
+    },
+    execution: {
+        concurrency: 1,
+        stopOnBranchError: false,
+    },
+    report: {
+        writeJson: false,
+        writeMarkdown: false,
+        redactValues: true,
+        warnOnSecrets: true,
+    },
+    safety: {
+        rejectNoRemote: true,
+        saveOnPartialSuccess: true,
+    },
+};

package/dist/config/load.d.ts

@@ -0,0 +1,3 @@
+import { AppConfig } from "./schema.js";
+import { CliInput } from "../core/types.js";
+export declare function loadConfig(cliInput: CliInput): AppConfig;

package/dist/config/load.js

@@ -0,0 +1,65 @@
+import { AppConfigSchema } from "./schema.js";
+import { DEFAULT_CONFIG } from "./defaults.js";
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+function loadProjectConfig(repoPath) {
+    const candidates = [
+        join(resolve(repoPath), "git-worker.config.json"),
+        join(resolve(repoPath), ".git-worker.config.json"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            try {
+                const raw = readFileSync(candidate, "utf-8");
+                return JSON.parse(raw);
+            }
+            catch {
+                // ignore malformed
+            }
+        }
+    }
+    return {};
+}
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        const overrideVal = override[key];
+        if (overrideVal === undefined)
+            continue;
+        if (typeof overrideVal === "object" &&
+            overrideVal !== null &&
+            !Array.isArray(overrideVal) &&
+            typeof result[key] === "object" &&
+            result[key] !== null) {
+            result[key] = deepMerge(result[key], overrideVal);
+        }
+        else {
+            result[key] = overrideVal;
+        }
+    }
+    return result;
+}
+export function loadConfig(cliInput) {
+    // Load project config from repo directory
+    const repoPath = cliInput.repo || process.cwd();
+    const projectConfig = loadProjectConfig(repoPath);
+    // Merge: defaults < project config < CLI overrides
+    const cliOverrides = {
+        git: {
+            ...DEFAULT_CONFIG.git,
+            ...(cliInput.push ? { pushPolicy: cliInput.push } : {}),
+            ...(cliInput.commitMsg ? { commitMessage: cliInput.commitMsg } : {}),
+            ...(cliInput.remote ? { remote: cliInput.remote } : {}),
+        },
+        editor: {
+            ...DEFAULT_CONFIG.editor,
+            ...(cliInput.editor ? { name: cliInput.editor } : {}),
+        },
+        review: {
+            ...DEFAULT_CONFIG.review,
+            ...(cliInput.autoApprove !== undefined ? { autoApprove: cliInput.autoApprove } : {}),
+        },
+    };
+    const merged = deepMerge(deepMerge(DEFAULT_CONFIG, projectConfig), cliOverrides);
+    return Object.freeze(AppConfigSchema.parse(merged));
+}