@susu-eng/trunk-sync 2.3.0

package/dist/lib/hook-execute.d.ts

@@ -0,0 +1,15 @@
+import type { HookInput, RepoState, HookPlan } from "./hook-types.js";
+/**
+ * Gather the current git repo state needed for planning.
+ * Runs git commands — this is the I/O boundary.
+ */
+export declare function gatherRepoState(input: HookInput): RepoState | null;
+/**
+ * Execute a hook plan: stage files, commit, sync.
+ * Returns exit code and optional stderr for agent feedback.
+ */
+export declare function executePlan(plan: HookPlan, input: HookInput, state: RepoState): {
+    exitCode: number;
+    stderr?: string;
+};
+export declare function findWorktreeForBranch(porcelainOutput: string, branch: string): string | null;

package/dist/lib/hook-execute.js

@@ -0,0 +1,311 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, mkdirSync, copyFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { readConfig } from "../commands/config.js";
+import { HOOK_EXPLAINER } from "./hook-types.js";
+import { extractTaskFromTranscript, buildCommitPlanWithTask } from "./hook-plan.js";
+/**
+ * Gather the current git repo state needed for planning.
+ * Runs git commands — this is the I/O boundary.
+ */
+export function gatherRepoState(input) {
+    const filePath = input.tool_input.file_path ?? null;
+    let repoRoot;
+    try {
+        repoRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
+    }
+    catch {
+        return null; // not in a git repo
+    }
+    const gitDir = execSync("git rev-parse --git-dir", { encoding: "utf-8" }).trim();
+    let insideRepo = true;
+    let gitignored = false;
+    let relPath = null;
+    if (filePath) {
+        // Resolve symlinks so /var/... matches /private/var/... on macOS
+        const resolvedFile = existsSync(filePath) ? realpathSync(filePath) : filePath;
+        insideRepo = resolvedFile.startsWith(repoRoot + "/");
+        if (insideRepo) {
+            relPath = resolvedFile.slice(repoRoot.length + 1);
+            try {
+                execSync(`git check-ignore -q -- "${filePath}"`, { stdio: "ignore" });
+                gitignored = true;
+            }
+            catch {
+                gitignored = false;
+            }
+        }
+    }
+    let hasRemote = true;
+    try {
+        execSync("git remote get-url origin", { stdio: "ignore" });
+    }
+    catch {
+        hasRemote = false;
+    }
+    let targetBranch = "";
+    if (hasRemote) {
+        try {
+            const ref = execSync("git symbolic-ref refs/remotes/origin/HEAD", {
+                encoding: "utf-8",
+            }).trim();
+            targetBranch = ref.replace("refs/remotes/origin/", "");
+        }
+        catch {
+            targetBranch = "main";
+        }
+    }
+    let currentBranch = "";
+    try {
+        currentBranch = execSync("git symbolic-ref --short HEAD", { encoding: "utf-8" }).trim();
+    }
+    catch {
+        // detached HEAD
+    }
+    const inMerge = existsSync(join(gitDir, "MERGE_HEAD"));
+    let hasStagedChanges = false;
+    try {
+        execSync("git diff --cached --quiet", { stdio: "ignore" });
+    }
+    catch {
+        hasStagedChanges = true;
+    }
+    let deletedFiles = [];
+    if (!filePath) {
+        try {
+            const deleted = execSync(`git -C "${repoRoot}" ls-files --deleted`, {
+                encoding: "utf-8",
+            }).trim();
+            if (deleted)
+                deletedFiles = deleted.split("\n");
+        }
+        catch {
+            // ignore
+        }
+    }
+    return {
+        repoRoot,
+        gitDir,
+        relPath,
+        insideRepo,
+        gitignored,
+        hasRemote,
+        targetBranch,
+        currentBranch,
+        inMerge,
+        hasStagedChanges,
+        deletedFiles,
+    };
+}
+/**
+ * Execute a hook plan: stage files, commit, sync.
+ * Returns exit code and optional stderr for agent feedback.
+ */
+export function executePlan(plan, input, state) {
+    if (plan.action === "skip")
+        return { exitCode: 0 };
+    if (plan.action === "commit-merge") {
+        // Stage the file if provided
+        const filePath = input.tool_input.file_path;
+        if (filePath) {
+            execSync(`git add -- "${filePath}"`);
+        }
+        try {
+            execSync(`git commit -m "${escapeForShell(plan.message)}"`);
+        }
+        catch (e) {
+            // Let git's exit code pass through (e.g. 128 for unresolved merge paths)
+            const code = getExitCode(e);
+            return { exitCode: code, stderr: getStdout(e) };
+        }
+        if (plan.sync)
+            return executeSync(plan.sync);
+        return { exitCode: 0 };
+    }
+    // commit-and-sync
+    const { commit, sync } = plan;
+    // Stage deletions
+    for (const file of commit.filesToRemove) {
+        try {
+            execSync(`git -C "${state.repoRoot}" rm --cached --quiet -- "${file}"`, {
+                stdio: "ignore",
+            });
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Stage file edits
+    for (const file of commit.filesToStage) {
+        execSync(`git add -- "${file}"`);
+    }
+    // Check if there's anything staged (may have been a no-op)
+    try {
+        execSync("git diff --cached --quiet", { stdio: "ignore" });
+        return { exitCode: 0 }; // nothing to commit
+    }
+    catch {
+        // has staged changes — continue
+    }
+    // Try to enrich commit message with task from transcript
+    let finalCommit = commit;
+    if (input.transcript_path) {
+        const expanded = input.transcript_path.replace(/^~/, homedir());
+        try {
+            const content = readFileSync(expanded, "utf-8");
+            const task = extractTaskFromTranscript(content);
+            if (task) {
+                finalCommit = buildCommitPlanWithTask(input, state, task);
+            }
+        }
+        catch {
+            // best-effort
+        }
+    }
+    // Commit
+    if (finalCommit.body) {
+        execSync(`git commit -m "${escapeForShell(finalCommit.subject)}" -m "${escapeForShell(finalCommit.body)}"`);
+    }
+    else {
+        execSync(`git commit -m "${escapeForShell(finalCommit.subject)}"`);
+    }
+    // Snapshot transcript into the commit (opt-in via config)
+    amendWithTranscriptSnapshot(input, state);
+    if (sync)
+        return executeSync(sync);
+    return { exitCode: 0 };
+}
+function amendWithTranscriptSnapshot(input, state) {
+    try {
+        const config = readConfig();
+        if (config.get("commit-transcripts") !== "true")
+            return;
+        if (!input.transcript_path || !input.session_id)
+            return;
+        const expanded = input.transcript_path.replace(/^~/, homedir());
+        if (!existsSync(expanded))
+            return;
+        const snapshotDir = join(state.repoRoot, ".transcripts");
+        mkdirSync(snapshotDir, { recursive: true });
+        const shortSession = input.session_id.slice(0, 8);
+        const epoch = Math.floor(Date.now() / 1000);
+        const snapshotName = `${shortSession}-${epoch}.jsonl`;
+        copyFileSync(expanded, join(snapshotDir, snapshotName));
+        execSync(`git add -- "${snapshotDir}"`, { cwd: state.repoRoot });
+        execSync(`git commit --amend --no-edit`, { cwd: state.repoRoot });
+    }
+    catch {
+        // best-effort — don't fail the hook if snapshot fails
+    }
+}
+function executeSync(sync) {
+    const { targetBranch, currentBranch } = sync;
+    // Pull from origin
+    try {
+        execSync(`git pull origin "${targetBranch}" --no-rebase 2>&1`, { encoding: "utf-8" });
+    }
+    catch (e) {
+        return conflictExit(getStdout(e), targetBranch);
+    }
+    // Merge local target branch into worktree branch
+    if (currentBranch && currentBranch !== targetBranch) {
+        try {
+            execSync(`git merge "${targetBranch}" --no-edit 2>&1`, { encoding: "utf-8" });
+        }
+        catch (e) {
+            return conflictExit(getStdout(e), targetBranch);
+        }
+    }
+    // Push, retry once on failure
+    try {
+        execSync(`git push origin "HEAD:${targetBranch}" 2>&1`, { encoding: "utf-8" });
+    }
+    catch {
+        // Retry: pull then push
+        try {
+            execSync(`git pull origin "${targetBranch}" --no-rebase 2>&1`, { encoding: "utf-8" });
+        }
+        catch (e) {
+            return conflictExit(getStdout(e), targetBranch);
+        }
+        try {
+            execSync(`git push origin "HEAD:${targetBranch}" 2>&1`, { encoding: "utf-8" });
+        }
+        catch (e) {
+            return pushExit(getStdout(e), targetBranch);
+        }
+    }
+    // Keep local target branch in sync
+    try {
+        execSync(`git fetch origin "${targetBranch}:${targetBranch}" 2>/dev/null`);
+    }
+    catch {
+        // If fetch fails (branch checked out), try ff-merge in the worktree
+        try {
+            const wtOutput = execSync(`git worktree list --porcelain`, { encoding: "utf-8" });
+            const mainWt = findWorktreeForBranch(wtOutput, targetBranch);
+            if (mainWt) {
+                try {
+                    execSync(`git -C "${mainWt}" merge --ff-only "origin/${targetBranch}" 2>/dev/null`);
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { exitCode: 0 };
+}
+export function findWorktreeForBranch(porcelainOutput, branch) {
+    const blocks = porcelainOutput.split("\n\n");
+    for (const block of blocks) {
+        const lines = block.split("\n");
+        let worktreePath = "";
+        let branchRef = "";
+        for (const line of lines) {
+            if (line.startsWith("worktree "))
+                worktreePath = line.slice(9);
+            if (line.startsWith("branch "))
+                branchRef = line.slice(7);
+        }
+        if (branchRef === `refs/heads/${branch}` && worktreePath) {
+            return worktreePath;
+        }
+    }
+    return null;
+}
+function conflictExit(output, targetBranch) {
+    return {
+        exitCode: 2,
+        stderr: `TRUNK-SYNC CONFLICT: ${HOOK_EXPLAINER} Another agent changed the same file, creating a merge conflict. The file now contains git conflict markers (<<<<<<< / ======= / >>>>>>>).\n\ngit output:\n${output}\n\nTo resolve: just read the conflicting file and edit it to the correct content (remove the conflict markers). This hook will detect the merge state and complete the sync automatically.`,
+    };
+}
+function pushExit(output, targetBranch) {
+    return {
+        exitCode: 2,
+        stderr: `TRUNK-SYNC FAILED: ${HOOK_EXPLAINER} The push to remote failed.\n\ngit output:\n${output}\n\nTo resolve: run "git pull origin ${targetBranch} --no-rebase" then "git push origin HEAD:${targetBranch}". If there are conflicts, read the conflicting files and edit them to remove the conflict markers — the hook will complete the sync on your next edit.`,
+    };
+}
+function escapeForShell(s) {
+    return s.replace(/"/g, '\\"');
+}
+function getExitCode(e) {
+    if (typeof e === "object" && e !== null && "status" in e) {
+        const status = e.status;
+        if (typeof status === "number")
+            return status;
+    }
+    return 1;
+}
+function getStdout(e) {
+    if (typeof e === "object" && e !== null && "stdout" in e) {
+        return String(e.stdout);
+    }
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}

package/dist/lib/hook-plan.d.ts

@@ -0,0 +1,26 @@
+import type { HookInput, RepoState, HookPlan, CommitPlan } from "./hook-types.js";
+/**
+ * Parse the raw JSON string from hook stdin into a typed HookInput.
+ */
+export declare function parseHookInput(json: string): HookInput;
+/**
+ * Pure decision logic: given parsed input and repo state, decide what to do.
+ * No I/O, no git commands — only data in, plan out.
+ */
+export declare function planHook(input: HookInput, state: RepoState): HookPlan;
+/**
+ * Build a commit plan with a task-based subject (when transcript extraction succeeds).
+ */
+export declare function buildCommitPlanWithTask(input: HookInput, state: RepoState, task: string | null): CommitPlan;
+export declare function buildSessionPrefix(sessionId: string | null): string;
+export declare function buildCommitBody(input: HookInput, _relPath: string | null): string | null;
+/**
+ * Extract the first user message from a JSONL transcript.
+ * Filters out hook feedback, plan headers, XML tags, and empty lines.
+ * Returns first 72 chars or null.
+ */
+export declare function extractTaskFromTranscript(content: string): string | null;
+/**
+ * Summarize a list of deleted files: "file.txt (+2 more)"
+ */
+export declare function summarizeDeletions(files: string[]): string;

package/dist/lib/hook-plan.js

@@ -0,0 +1,175 @@
+/**
+ * Parse the raw JSON string from hook stdin into a typed HookInput.
+ */
+export function parseHookInput(json) {
+    const raw = JSON.parse(json);
+    return {
+        tool_name: raw.tool_name ?? null,
+        tool_input: raw.tool_input ?? {},
+        session_id: raw.session_id ?? null,
+        transcript_path: raw.transcript_path ?? null,
+    };
+}
+/**
+ * Pure decision logic: given parsed input and repo state, decide what to do.
+ * No I/O, no git commands — only data in, plan out.
+ */
+export function planHook(input, state) {
+    const filePath = input.tool_input.file_path ?? null;
+    const sync = buildSyncPlan(state);
+    // No file_path and no deleted files → nothing to do
+    if (!filePath && state.deletedFiles.length === 0) {
+        return { action: "skip" };
+    }
+    // File path provided but outside the repo → skip
+    if (filePath && !state.insideRepo) {
+        return { action: "skip" };
+    }
+    // File path provided but gitignored → skip
+    if (filePath && state.gitignored) {
+        return { action: "skip" };
+    }
+    // In merge state → complete the merge
+    if (state.inMerge) {
+        const relPath = filePath ? state.relPath : summarizeDeletions(state.deletedFiles);
+        const sessionPrefix = buildSessionPrefix(input.session_id);
+        const message = `${sessionPrefix}resolve merge conflict in ${relPath}`;
+        const filesToStage = filePath ? [filePath] : [];
+        return {
+            action: "commit-merge",
+            message,
+            sync,
+        };
+    }
+    // Normal commit path
+    const commit = buildCommitPlan(input, state);
+    return { action: "commit-and-sync", commit, sync };
+}
+function buildSyncPlan(state) {
+    if (!state.hasRemote)
+        return null;
+    return {
+        targetBranch: state.targetBranch,
+        currentBranch: state.currentBranch,
+    };
+}
+function buildCommitPlan(input, state) {
+    const filePath = input.tool_input.file_path ?? null;
+    const action = filePath
+        ? (input.tool_name ?? "update").toLowerCase()
+        : "delete";
+    const relPath = filePath
+        ? state.relPath
+        : summarizeDeletions(state.deletedFiles);
+    const filesToStage = filePath ? [filePath] : [];
+    const filesToRemove = filePath ? [] : state.deletedFiles;
+    const sessionPrefix = buildSessionPrefix(input.session_id);
+    const subject = `${sessionPrefix}${action} ${relPath}`;
+    const body = buildCommitBody(input, filePath ? relPath : null);
+    return { filesToStage, filesToRemove, subject, body };
+}
+/**
+ * Build a commit plan with a task-based subject (when transcript extraction succeeds).
+ */
+export function buildCommitPlanWithTask(input, state, task) {
+    const base = buildCommitPlan(input, state);
+    if (!task)
+        return base;
+    const filePath = input.tool_input.file_path ?? null;
+    const relPath = filePath ? state.relPath : summarizeDeletions(state.deletedFiles);
+    const sessionPrefix = buildSessionPrefix(input.session_id);
+    const subject = `${sessionPrefix}${task}`;
+    // When task is present, include File: line in body
+    let body = `File: ${relPath}`;
+    if (input.session_id)
+        body += `\nSession: ${input.session_id}`;
+    return { ...base, subject, body: body || null };
+}
+export function buildSessionPrefix(sessionId) {
+    if (sessionId)
+        return `auto(${sessionId.slice(0, 8)}): `;
+    return "auto: ";
+}
+export function buildCommitBody(input, _relPath) {
+    if (!input.session_id)
+        return null;
+    return `Session: ${input.session_id}`;
+}
+/**
+ * Extract the first user message from a JSONL transcript.
+ * Filters out hook feedback, plan headers, XML tags, and empty lines.
+ * Returns first 72 chars or null.
+ */
+export function extractTaskFromTranscript(content) {
+    const lines = content.split("\n");
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isUserMessage(parsed))
+            continue;
+        const msg = parsed.message;
+        const texts = extractTextContent(msg.content);
+        for (const text of texts) {
+            const candidate = filterTaskLine(text);
+            if (candidate)
+                return candidate.slice(0, 72);
+        }
+    }
+    return null;
+}
+function isUserMessage(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const rec = obj;
+    if (rec.type !== "user")
+        return false;
+    if (typeof rec.message !== "object" || rec.message === null)
+        return false;
+    const msg = rec.message;
+    return msg.role === "user";
+}
+function extractTextContent(content) {
+    if (typeof content === "string")
+        return [content];
+    if (Array.isArray(content)) {
+        return content.filter((item) => typeof item === "string");
+    }
+    return [];
+}
+function filterTaskLine(text) {
+    const lines = text.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith("Stop hook feedback:"))
+            return null;
+        if (trimmed === "Implement the following plan:")
+            continue;
+        if (trimmed.startsWith("<"))
+            continue;
+        // Strip leading markdown headers
+        const stripped = trimmed.replace(/^#{1,}\s+/, "");
+        if (stripped)
+            return stripped;
+    }
+    return null;
+}
+/**
+ * Summarize a list of deleted files: "file.txt (+2 more)"
+ */
+export function summarizeDeletions(files) {
+    if (files.length === 0)
+        return "";
+    const first = files[0];
+    if (files.length === 1)
+        return first;
+    return `${first} (+${files.length - 1} more)`;
+}

package/dist/lib/hook-types.d.ts

@@ -0,0 +1,54 @@
+/** Raw JSON from Claude's PostToolUse hook stdin */
+export interface HookInput {
+    tool_name: string | null;
+    tool_input: {
+        file_path?: string;
+    };
+    session_id: string | null;
+    transcript_path: string | null;
+}
+/** Git state gathered before planning */
+export interface RepoState {
+    repoRoot: string;
+    gitDir: string;
+    /** file_path relative to repoRoot, or null if no file_path */
+    relPath: string | null;
+    /** true when file_path is inside the repo */
+    insideRepo: boolean;
+    /** true when file_path is gitignored */
+    gitignored: boolean;
+    /** true when origin remote exists */
+    hasRemote: boolean;
+    /** default branch on origin (e.g. "main"), empty when no remote */
+    targetBranch: string;
+    /** current branch name */
+    currentBranch: string;
+    /** true when MERGE_HEAD exists */
+    inMerge: boolean;
+    /** true when staging area has changes */
+    hasStagedChanges: boolean;
+    /** tracked files that have been deleted from the working tree */
+    deletedFiles: string[];
+}
+export interface SyncPlan {
+    targetBranch: string;
+    currentBranch: string;
+}
+export interface CommitPlan {
+    filesToStage: string[];
+    filesToRemove: string[];
+    subject: string;
+    body: string | null;
+}
+export type HookPlan = {
+    action: "skip";
+} | {
+    action: "commit-and-sync";
+    commit: CommitPlan;
+    sync: SyncPlan | null;
+} | {
+    action: "commit-merge";
+    message: string;
+    sync: SyncPlan | null;
+};
+export declare const HOOK_EXPLAINER = "A PostToolUse hook automatically commits and syncs every file change to keep multiple agents in sync on trunk.";

package/dist/lib/hook-types.js

@@ -0,0 +1 @@
+export const HOOK_EXPLAINER = "A PostToolUse hook automatically commits and syncs every file change to keep multiple agents in sync on trunk.";

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/trunk-sync.sh",
+            "statusMessage": "Syncing to trunk"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@susu-eng/trunk-sync",
+  "version": "2.3.0",
+  "type": "module",
+  "description": "Maximum continuous integration for multi-agent coding — every edit is committed and pushed to trunk immediately",
+  "bin": {
+    "trunk-sync": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.*",
+    "scripts/",
+    "hooks/",
+    "rules/",
+    ".claude-plugin/"
+  ],
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elimydlarz/trunk-sync"
+  },
+  "keywords": [
+    "claude-code",
+    "multi-agent",
+    "git",
+    "sync",
+    "trunk-based-development"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "test": "node --test --test-reporter spec 'dist/**/*.test.js'"
+  }
+}

package/rules/trunk-sync.md

@@ -0,0 +1,29 @@
+# Trunk Sync
+
+Every file write is auto-committed and pushed by a PostToolUse hook. Every edit is integrated to `origin/main` immediately — maximum continuous integration. This keeps multiple agents working against near-current trunk at all times.
+
+## How it works
+
+Each agent runs in its own git worktree (via `claude -w`), isolated from other agents. After every `Edit` or `Write`, the hook:
+
+1. Commits the changed file with agent context
+2. Pulls from `origin/main` (`--no-rebase`) and pushes to `origin/main`
+3. Retries once if another agent pushed between pull and push
+
+If another agent changed the same file, you get a merge conflict. The conflict and resolution work identically whether the other agent is in a local worktree or on a remote machine.
+
+## When you see TRUNK-SYNC CONFLICT
+
+Another agent changed the same file. Git left conflict markers in the file. Just read the file, edit it to the correct content (remove the `<<<<<<<` / `=======` / `>>>>>>>` markers), and the hook will detect the merge state and complete the sync automatically on your next edit.
+
+Do NOT run git commands to resolve — just fix the file contents.
+
+## Before you start
+
+Run `git pull` once at the beginning of your session to start from the latest trunk. After that, the hook handles all pulls and pushes.
+
+## Don't
+
+- Make manual git commits — the hook handles it
+- Run `git pull` or `git push` after your initial pull — the hook handles it
+- Edit or delete files in `.transcripts/` — these are auto-generated session snapshots

package/scripts/trunk-sync.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+exec node "$SCRIPT_DIR/dist/lib/hook-entry.js"