gent-cli 20.0.0 → 22.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gent-cli",
-  "version": "20.0.0",
+  "version": "22.0.0",
   "description": "A modern, Git-like version control CLI with cloud sync, AI-powered superpowers (ask/review/docs/changelog), and zero-friction setup (gent setup/doctor/config).",
   "main": "src/index.js",
   "bin": {

package/src/commands/canonical.js

@@ -155,11 +155,15 @@ const handlers = {
         if (options.abort) return merge.abortMerge(repo);
         if (options.continue) return merge.concludeMerge(repo, options.message);
         const result = await merge.merge(repo, branch, options);
-        console.log(result.status);
         if (result.status === 'conflicts') {
+            for (const conflict of result.conflicts) {
+                if (conflict.kind === 'content') console.log(`Auto-merging ${conflict.path}`);
+                console.log(`CONFLICT (${conflict.kind}): Merge conflict in ${conflict.path}`);
+            }
+            console.log('Automatic merge failed; fix conflicts and then commit the result.');
             console.log('Resolve files, stage with gent add, then gent merge --continue or gent commit -m <message>.');
             process.exitCode = 1;
-        }
+        } else console.log(result.status);
     },
     async resolve(repo) {
         const index = await GitIndex.read(repo.indexPath);

package/src/commands/checkout.js

@@ -3,12 +3,77 @@
  * Changes the current working branch
  */
 
+const fs = require('fs').promises;
 const path = require('path');
 const chalk = require('chalk');
 const { getGentPath, readJSON, writeJSON } = require('../utils/fileSystem');
-const { COMMITS_FILE } = require('../utils/constants');
+const { COMMITS_FILE, STAGING_FILE } = require('../utils/constants');
+const { hashBlob, readBlob } = require('../utils/hash-engine');
 const journal = require('../utils/journal');
 
+function treeOf(repository, commitHash) {
+    if (!commitHash) return [];
+    const commit = (repository.commits || []).find(item => item.hash === commitHash);
+    if (!commit) throw new Error(`Commit '${commitHash}' not found`);
+    return commit.tree || (commit.files || []).map(file => ({
+        mode: '100644', name: file.path || file.name, hash: file.hash, type: 'blob'
+    }));
+}
+
+function safePath(cwd, relativePath) {
+    if (!relativePath || path.isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes('..')) {
+        throw new Error(`Unsafe repository path '${relativePath}'`);
+    }
+    const fullPath = path.resolve(cwd, relativePath);
+    if (fullPath !== cwd && !fullPath.startsWith(cwd + path.sep)) {
+        throw new Error(`Unsafe repository path '${relativePath}'`);
+    }
+    return fullPath;
+}
+
+async function switchWorkingTree(gentPath, cwd, repository, currentHash, targetHash) {
+    const staging = await readJSON(path.join(gentPath, STAGING_FILE));
+    if ((staging.entries || []).length || (staging.files || []).length || staging.mergeState) {
+        throw new Error('Commit or stash staged changes before switching branches');
+    }
+
+    const currentTree = new Map(treeOf(repository, currentHash).map(entry => [entry.name || entry.path, entry]));
+    const targetTree = new Map(treeOf(repository, targetHash).map(entry => [entry.name || entry.path, entry]));
+    const changedPaths = [...new Set([...currentTree.keys(), ...targetTree.keys()])]
+        .filter(name => currentTree.get(name)?.hash !== targetTree.get(name)?.hash);
+    const writes = new Map();
+
+    // Read and validate every affected path before changing any file.
+    for (const name of changedPaths) {
+        const fullPath = safePath(cwd, name);
+        const current = currentTree.get(name);
+        const target = targetTree.get(name);
+        const stat = await fs.lstat(fullPath).catch(() => null);
+
+        if (current) {
+            if (!stat || !stat.isFile()) throw new Error(`Local changes would be overwritten by checkout: ${name}`);
+            const bytes = await fs.readFile(fullPath);
+            if (hashBlob(bytes) !== current.hash) {
+                throw new Error(`Local changes would be overwritten by checkout: ${name}`);
+            }
+        } else if (target && stat) {
+            throw new Error(`Untracked file would be overwritten by checkout: ${name}`);
+        }
+
+        if (target) writes.set(name, await readBlob(gentPath, target.hash));
+    }
+
+    for (const name of changedPaths) {
+        if (targetTree.has(name)) continue;
+        await fs.unlink(safePath(cwd, name));
+    }
+    for (const [name, bytes] of writes) {
+        const fullPath = safePath(cwd, name);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, bytes);
+    }
+}
+
 /**
  * Switch to a different branch
  * @param {String} branch - Branch name
@@ -55,7 +120,11 @@ async function checkout(branch, options) {
             return;
         }
 
-        await journal.recordOp(gentPath, 'checkout', `switch to branch '${branch}'`);
+        const cwd = path.dirname(gentPath);
+        const currentCommit = branches[repository.currentBranch] || null;
+        const targetCommit = branches[branch] || null;
+        await switchWorkingTree(gentPath, cwd, repository, currentCommit, targetCommit);
+        await journal.recordOp(gentPath, 'checkout', `switch to branch '${branch}'`, { restoreTree: true });
 
         repository.currentBranch = branch;
         await writeJSON(path.join(gentPath, COMMITS_FILE), repository);

package/src/commands/commit.js

@@ -76,6 +76,10 @@ async function commit(options) {
 
         const config = await readJSON(path.join(gentPath, CONFIG_FILE));
         const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const mergeState = staging.mergeState || null;
+        if (mergeState && repository.branches[repository.currentBranch] !== mergeState.oursHash) {
+            throw new Error('Current branch changed after the merge started; abort and retry the merge');
+        }
 
         // Resolve author identity
         let authorName = config.user.name;
@@ -105,13 +109,17 @@ async function commit(options) {
         if (stagedEntries.length > 0) {
             // New format: entries already have blob hashes from gent add
             // Carry forward unchanged files from parent commit
-            const parentHash = repository.branches[repository.currentBranch] || null;
+            const parentHash = mergeState
+                ? mergeState.oursHash
+                : repository.branches[repository.currentBranch] || null;
             const parentCommit = parentHash
                 ? (repository.commits || []).find(c => c.hash === parentHash)
                 : null;
-            const parentTree = parentCommit && parentCommit.tree
-                ? parentCommit.tree
-                : (parentCommit ? parentCommit.files.map(f => ({ mode: '100644', name: f.path, hash: f.hash, type: 'blob' })) : []);
+            const parentTree = mergeState
+                ? (mergeState.mergedEntries || [])
+                : parentCommit && parentCommit.tree
+                    ? parentCommit.tree
+                    : (parentCommit ? parentCommit.files.map(f => ({ mode: '100644', name: f.path, hash: f.hash, type: 'blob' })) : []);
 
             // Start from parent tree, overlay staged changes
             const treeMap = new Map(parentTree.map(e => [e.name, e]));
@@ -162,7 +170,8 @@ async function commit(options) {
                 email: authorEmail
             },
             timestamp: new Date().toISOString(),
-            parent: repository.branches[repository.currentBranch] || null,
+            parent: mergeState ? mergeState.oursHash : repository.branches[repository.currentBranch] || null,
+            ...(mergeState ? { mergeParent: mergeState.theirsHash } : {}),
             treeHash,
             tree: treeEntries,
             files: treeEntries.map(e => ({ path: e.name, hash: e.hash })), // backward compat
@@ -185,6 +194,7 @@ async function commit(options) {
         // Clear staging
         staging.entries = [];
         staging.files = [];
+        staging.mergeState = null;
         await writeJSON(path.join(gentPath, STAGING_FILE), staging);
 
         spinner.succeed(chalk.green('Changes committed successfully!'));

package/src/commands/merge.js

@@ -12,7 +12,7 @@ const { COMMITS_FILE, STAGING_FILE, CONFIG_FILE } = require('../utils/constants'
 const { generateCommitHash } = require('../utils/helpers');
 const authStorage = require('../utils/auth-storage');
 const { findMergeBase, mergeTreeEntries, autoMerge } = require('../utils/merge-engine');
-const { storeTree, readBlobAsString, storeBlob } = require('../utils/hash-engine');
+const { storeTree, readBlob, hashBlob } = require('../utils/hash-engine');
 const pet = require('./pet');
 const journal = require('../utils/journal');
 
@@ -26,7 +26,7 @@ async function merge(sourceBranch, options) {
 
     try {
         const gentPath = await getGentPath();
-        const cwd = process.cwd();
+        const cwd = path.dirname(gentPath);
         const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
         const commits = repository.commits || [];
         const branches = repository.branches || {};
@@ -35,11 +35,12 @@ async function merge(sourceBranch, options) {
         // Validate branches
         if (!branches.hasOwnProperty(sourceBranch)) {
             spinner.fail(chalk.red(`Branch '${sourceBranch}' not found`));
+            process.exitCode = 1;
             return;
         }
 
         if (sourceBranch === currentBranch) {
-            spinner.fail(chalk.red('Cannot merge a branch into itself'));
+            spinner.succeed(chalk.green('Already up to date'));
             return;
         }
 
@@ -48,14 +49,19 @@ async function merge(sourceBranch, options) {
 
         if (!oursHash) {
             spinner.fail(chalk.red(`Current branch '${currentBranch}' has no commits`));
+            process.exitCode = 1;
             return;
         }
 
         if (!theirsHash) {
             spinner.fail(chalk.red(`Branch '${sourceBranch}' has no commits`));
+            process.exitCode = 1;
             return;
         }
 
+        const oursCommit = commits.find(c => c.hash === oursHash);
+        const theirsCommit = commits.find(c => c.hash === theirsHash);
+
         // Fast-forward check: if ours is ancestor of theirs
         if (oursHash === theirsHash) {
             spinner.succeed(chalk.green('Already up to date'));
@@ -65,19 +71,28 @@ async function merge(sourceBranch, options) {
         // Find merge base (common ancestor)
         const baseHash = findMergeBase(commits, oursHash, theirsHash);
 
+        // The incoming branch is already contained in the current branch.
+        if (baseHash === theirsHash) {
+            spinner.succeed(chalk.green('Already up to date'));
+            return;
+        }
+
+        if (!baseHash) {
+            spinner.fail(chalk.red('Refusing to merge unrelated histories'));
+            process.exitCode = 1;
+            return;
+        }
+
+        await assertCleanWorkingTree(gentPath, cwd, oursCommit);
+
         // Fast-forward: current branch is merge base → just move pointer
         if (baseHash === oursHash) {
             spinner.text = 'Fast-forward merge...';
             await journal.recordOp(gentPath, 'merge', `fast-forward '${sourceBranch}' into ${currentBranch}`, { restoreTree: true });
+            await checkoutTree(gentPath, cwd, treeOf(oursCommit), treeOf(theirsCommit));
             repository.branches[currentBranch] = theirsHash;
             await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
 
-            // Restore working tree from theirs commit
-            const theirsCommit = commits.find(c => c.hash === theirsHash);
-            if (theirsCommit) {
-                await restoreWorkingTree(gentPath, cwd, theirsCommit);
-            }
-
             spinner.succeed(chalk.green(`Fast-forward merge: ${currentBranch} → ${theirsHash.substring(0, 7)}`));
             await pet.celebrate('merge');
             return;
@@ -86,26 +101,21 @@ async function merge(sourceBranch, options) {
         // 3-way merge
         spinner.text = 'Computing 3-way merge...';
 
-        const oursCommit = commits.find(c => c.hash === oursHash);
-        const theirsCommit = commits.find(c => c.hash === theirsHash);
         const baseCommit = baseHash ? commits.find(c => c.hash === baseHash) : null;
 
         // Extract tree entries from commits
-        const getTree = (commit) => {
-            if (!commit) return [];
-            if (commit.tree && Array.isArray(commit.tree)) return commit.tree;
-            if (commit.files) return commit.files.map(f => ({
-                mode: '100644', name: f.path || f.name, hash: f.hash, type: 'blob'
-            }));
-            return [];
-        };
-
-        const baseTree = getTree(baseCommit);
-        const oursTree = getTree(oursCommit);
-        const theirsTree = getTree(theirsCommit);
+        const baseTree = treeOf(baseCommit);
+        const oursTree = treeOf(oursCommit);
+        const theirsTree = treeOf(theirsCommit);
 
         // Perform tree-level merge
-        const mergeResult = await mergeTreeEntries(gentPath, baseTree, oursTree, theirsTree);
+        const mergeResult = await mergeTreeEntries(
+            gentPath,
+            baseTree,
+            oursTree,
+            theirsTree,
+            { ours: 'HEAD', theirs: sourceBranch }
+        );
 
         if (mergeResult.hasConflicts) {
             spinner.warn(chalk.yellow(`Merged with ${mergeResult.conflicts.length} conflict(s)`));
@@ -124,7 +134,7 @@ async function merge(sourceBranch, options) {
                 }
             }
 
-            console.log(chalk.yellow('\nConflict markers: <<<<<<< ours / ======= / >>>>>>> theirs'));
+            console.log(chalk.yellow(`\nConflict markers: <<<<<<< HEAD / ======= / >>>>>>> ${sourceBranch}`));
             console.log(chalk.cyan('Resolve conflicts, then run "gent add" and "gent commit"'));
         }
 
@@ -132,7 +142,7 @@ async function merge(sourceBranch, options) {
         const mergedTreeHash = await storeTree(gentPath, mergeResult.mergedEntries);
 
         // Write merged files to working directory
-        await writeTreeToWorkDir(gentPath, cwd, mergeResult.mergedEntries);
+        await checkoutTree(gentPath, cwd, oursTree, mergeResult.mergedEntries);
 
         // If no conflicts, create merge commit automatically
         if (!mergeResult.hasConflicts) {
@@ -148,6 +158,7 @@ async function merge(sourceBranch, options) {
                     if (!authorEmail) authorEmail = globalUser.email;
                 }
             }
+            if (!authorName && authorEmail) authorName = authorEmail;
 
             const mergeCommit = {
                 hash: generateCommitHash(),
@@ -201,6 +212,7 @@ async function merge(sourceBranch, options) {
                 conflicts: mergeResult.conflicts
             };
             await writeJSON(path.join(gentPath, STAGING_FILE), staging);
+            process.exitCode = 1;
         }
 
     } catch (error) {
@@ -221,31 +233,58 @@ async function merge(sourceBranch, options) {
  * @param {String} cwd
  * @param {Array} entries
  */
-async function writeTreeToWorkDir(gentPath, cwd, entries) {
-    for (const entry of entries) {
-        const fullPath = path.join(cwd, entry.name);
-        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+function treeOf(commit) {
+    if (!commit) return [];
+    if (Array.isArray(commit.tree)) return commit.tree;
+    return (commit.files || []).map(file => ({
+        mode: '100644', name: file.path || file.name, hash: file.hash, type: 'blob'
+    }));
+}
 
-        const content = await readBlobAsString(gentPath, entry.hash);
-        await fs.writeFile(fullPath, content, 'utf-8');
+function safePath(cwd, relativePath) {
+    if (!relativePath || path.isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes('..')) {
+        throw new Error(`Unsafe repository path '${relativePath}'`);
+    }
+    const fullPath = path.resolve(cwd, relativePath);
+    if (fullPath !== cwd && !fullPath.startsWith(cwd + path.sep)) {
+        throw new Error(`Unsafe repository path '${relativePath}'`);
     }
+    return fullPath;
 }
 
-/**
- * Restore working tree from a commit's tree entries.
- * @param {String} gentPath
- * @param {String} cwd
- * @param {Object} commit
- */
-async function restoreWorkingTree(gentPath, cwd, commit) {
-    const tree = commit.tree || (commit.files || []).map(f => ({
-        mode: '100644', name: f.path || f.name, hash: f.hash, type: 'blob'
-    }));
+async function assertCleanWorkingTree(gentPath, cwd, commit) {
+    const staging = await readJSON(path.join(gentPath, STAGING_FILE));
+    if ((staging.entries || []).length || (staging.files || []).length || staging.mergeState) {
+        throw new Error('Commit or stash staged changes before merging');
+    }
+    for (const entry of treeOf(commit)) {
+        const fullPath = safePath(cwd, entry.name || entry.path);
+        const stat = await fs.lstat(fullPath).catch(() => null);
+        if (!stat || !stat.isFile() || hashBlob(await fs.readFile(fullPath)) !== entry.hash) {
+            throw new Error(`Local changes would be overwritten by merge: ${entry.name || entry.path}`);
+        }
+    }
+}
 
-    try {
-        await writeTreeToWorkDir(gentPath, cwd, tree);
-    } catch {
-        // Best-effort restore — blobs may not exist for legacy commits
+async function checkoutTree(gentPath, cwd, previousEntries, nextEntries) {
+    const previous = new Map(previousEntries.map(entry => [entry.name || entry.path, entry]));
+    const next = new Map(nextEntries.map(entry => [entry.name || entry.path, entry]));
+    const writes = new Map();
+
+    for (const [name, entry] of next) {
+        const fullPath = safePath(cwd, name);
+        if (!previous.has(name) && await fs.lstat(fullPath).catch(() => null)) {
+            throw new Error(`Untracked file would be overwritten by merge: ${name}`);
+        }
+        writes.set(name, await readBlob(gentPath, entry.hash));
+    }
+    for (const name of previous.keys()) {
+        if (!next.has(name)) await fs.unlink(safePath(cwd, name));
+    }
+    for (const [name, bytes] of writes) {
+        const fullPath = safePath(cwd, name);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, bytes);
     }
 }
 

package/src/commands/pull.js

@@ -24,10 +24,10 @@ const path = require('path');
 const chalk = require('chalk');
 const ora = require('ora');
 const { getGentPath, readJSON, writeJSON } = require('../utils/fileSystem');
-const { COMMITS_FILE, CONFIG_FILE, API_ENDPOINTS, buildRepoUrl, parseRemoteUrl } = require('../utils/constants');
+const { COMMITS_FILE, CONFIG_FILE, STAGING_FILE, API_ENDPOINTS, buildRepoUrl, parseRemoteUrl } = require('../utils/constants');
 const apiClient = require('../utils/api-client');
 const authStorage = require('../utils/auth-storage');
-const { storeBlob, readBlob } = require('../utils/hash-engine');
+const { storeBlob, readBlob, hashBlob } = require('../utils/hash-engine');
 const { findMergeBase, mergeTreeEntries } = require('../utils/merge-engine');
 const pet = require('./pet');
 const { generateCommitHash } = require('../utils/helpers');
@@ -68,8 +68,12 @@ async function pull(remoteName, branchName, options) {
         }
 
         const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
-        const branch = branchName || repository.currentBranch;
-        const localHead = repository.branches[branch] || null;
+        const currentBranch = repository.currentBranch;
+        const branch = branchName || currentBranch;
+        const localHead = repository.branches[currentBranch] || null;
+        const cwd = path.dirname(gentPath);
+
+        await assertCleanWorkingTree(gentPath, cwd, getCommitTree(repository.commits || [], localHead));
 
         // 1. Fetch commits + objects for this branch in a single call. `since`
         //    lets the server send only what we don't have on a fast-forward.
@@ -130,9 +134,9 @@ async function pull(remoteName, branchName, options) {
             // Fast-forward
             const previousTree = localHead ? getCommitTree(repository.commits, localHead) : [];
             const nextTree = getCommitTree(repository.commits, remoteHead);
-            repository.branches[branch] = remoteHead;
+            await checkoutTree(gentPath, cwd, previousTree, nextTree);
+            repository.branches[currentBranch] = remoteHead;
             await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
-            await checkoutTree(gentPath, process.cwd(), previousTree, nextTree);
 
             config.remoteRefs[`${remote}/${branch}`] = remoteHead;
             await writeJSON(path.join(gentPath, CONFIG_FILE), config);
@@ -156,12 +160,45 @@ async function pull(remoteName, branchName, options) {
             const oursTree = getTree(localHead);
             const theirsTree = getTree(remoteHead);
 
-            const mergeResult = await mergeTreeEntries(gentPath, baseTree, oursTree, theirsTree);
+            const mergeResult = await mergeTreeEntries(
+                gentPath,
+                baseTree,
+                oursTree,
+                theirsTree,
+                { ours: 'HEAD', theirs: `${remote}/${branch}` }
+            );
 
             // Build merge commit
             const { storeTree } = require('../utils/hash-engine');
             const mergedTreeHash = await storeTree(gentPath, mergeResult.mergedEntries);
 
+            if (mergeResult.hasConflicts) {
+                await checkoutTree(gentPath, cwd, oursTree, mergeResult.mergedEntries);
+                const staging = await readJSON(path.join(gentPath, STAGING_FILE));
+                staging.mergeState = {
+                    sourceBranch: `${remote}/${branch}`,
+                    oursHash: localHead,
+                    theirsHash: remoteHead,
+                    baseHash,
+                    mergedTreeHash,
+                    mergedEntries: mergeResult.mergedEntries,
+                    conflicts: mergeResult.conflicts
+                };
+                await writeJSON(path.join(gentPath, STAGING_FILE), staging);
+                await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
+
+                config.remoteRefs[`${remote}/${branch}`] = remoteHead;
+                await writeJSON(path.join(gentPath, CONFIG_FILE), config);
+
+                spinner.warn(chalk.yellow(`Pulled with ${mergeResult.conflicts.length} conflict(s)`));
+                for (const c of mergeResult.conflicts) {
+                    console.log(chalk.red(`  CONFLICT: ${c.file} (${c.type})`));
+                }
+                console.log(chalk.yellow('\nResolve conflicts, then "gent add" + "gent commit"'));
+                process.exitCode = 1;
+                return;
+            }
+
             const mergeCommit = {
                 hash: generateCommitHash(),
                 message: `Merge remote-tracking branch '${remote}/${branch}'`,
@@ -176,25 +213,15 @@ async function pull(remoteName, branchName, options) {
             };
 
             repository.commits.push(mergeCommit);
-            repository.branches[branch] = mergeCommit.hash;
+            repository.branches[currentBranch] = mergeCommit.hash;
             await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
-            if (!mergeResult.hasConflicts) {
-                await checkoutTree(gentPath, process.cwd(), oursTree, mergeResult.mergedEntries);
-            }
+            await checkoutTree(gentPath, cwd, oursTree, mergeResult.mergedEntries);
 
             config.remoteRefs[`${remote}/${branch}`] = remoteHead;
             await writeJSON(path.join(gentPath, CONFIG_FILE), config);
 
-            if (mergeResult.hasConflicts) {
-                spinner.warn(chalk.yellow(`Pulled with ${mergeResult.conflicts.length} conflict(s)`));
-                for (const c of mergeResult.conflicts) {
-                    console.log(chalk.red(`  CONFLICT: ${c.file} (${c.type})`));
-                }
-                console.log(chalk.yellow('\nResolve conflicts, then "gent add" + "gent commit"'));
-            } else {
-                spinner.succeed(chalk.green(`Merged ${newCount} remote commit(s)`));
-                console.log(chalk.gray(`  Merge commit: ${mergeCommit.hash.substring(0, 7)}`));
-            }
+            spinner.succeed(chalk.green(`Merged ${newCount} remote commit(s)`));
+            console.log(chalk.gray(`  Merge commit: ${mergeCommit.hash.substring(0, 7)}`));
         }
     } catch (error) {
         spinner.fail(chalk.red('Pull failed'));
@@ -216,15 +243,46 @@ async function pull(remoteName, branchName, options) {
  */
 function isAncestor(commits, hashA, hashB) {
     const commitMap = new Map(commits.map(c => [c.hash, c]));
-    let cur = hashB;
-    while (cur) {
+    const pending = [hashB];
+    const seen = new Set();
+    while (pending.length) {
+        const cur = pending.pop();
+        if (!cur || seen.has(cur)) continue;
         if (cur === hashA) return true;
+        seen.add(cur);
         const c = commitMap.get(cur);
-        cur = c ? c.parent : null;
+        if (c?.parent) pending.push(c.parent);
+        if (c?.mergeParent) pending.push(c.mergeParent);
     }
     return false;
 }
 
+function safePath(cwd, relativePath) {
+    if (!relativePath || path.isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes('..')) {
+        throw new Error(`Unsafe repository path '${relativePath}'`);
+    }
+    const fullPath = path.resolve(cwd, relativePath);
+    if (fullPath !== cwd && !fullPath.startsWith(cwd + path.sep)) {
+        throw new Error(`Unsafe repository path '${relativePath}'`);
+    }
+    return fullPath;
+}
+
+async function assertCleanWorkingTree(gentPath, cwd, tree) {
+    const staging = await readJSON(path.join(gentPath, STAGING_FILE));
+    if ((staging.entries || []).length || (staging.files || []).length || staging.mergeState) {
+        throw new Error('Commit or stash staged changes before pulling');
+    }
+    for (const entry of tree) {
+        const relPath = entry.name || entry.path;
+        const fullPath = safePath(cwd, relPath);
+        const stat = await fs.lstat(fullPath).catch(() => null);
+        if (!stat || !stat.isFile() || hashBlob(await fs.readFile(fullPath)) !== entry.hash) {
+            throw new Error(`Local changes would be overwritten by pull: ${relPath}`);
+        }
+    }
+}
+
 function getCommitTree(commits, hash) {
     const commit = commits.find(c => c.hash === hash);
     if (!commit) return [];
@@ -237,26 +295,35 @@ function getCommitTree(commits, hash) {
 }
 
 async function checkoutTree(gentPath, cwd, previousTree, nextTree) {
+    const previousPaths = new Set(previousTree.map(e => e.name || e.path));
     const nextPaths = new Set(nextTree.map(e => e.name || e.path));
+    const writes = new Map();
+
+    // Validate collisions and read every required blob before mutating files.
+    for (const entry of nextTree) {
+        if (entry.type && entry.type !== 'blob') continue;
+        const relPath = entry.name || entry.path;
+        if (!relPath || !entry.hash) continue;
+        const fullPath = safePath(cwd, relPath);
+        if (!previousPaths.has(relPath) && await fs.lstat(fullPath).catch(() => null)) {
+            throw new Error(`Untracked file would be overwritten by pull: ${relPath}`);
+        }
+        writes.set(relPath, await readBlob(gentPath, entry.hash));
+    }
 
     for (const entry of previousTree) {
         const relPath = entry.name || entry.path;
         if (!relPath || nextPaths.has(relPath)) continue;
         try {
-            await fs.unlink(path.join(cwd, relPath));
+            await fs.unlink(safePath(cwd, relPath));
         } catch {
             // File already absent.
         }
     }
 
-    for (const entry of nextTree) {
-        if (entry.type && entry.type !== 'blob') continue;
-        const relPath = entry.name || entry.path;
-        if (!relPath || !entry.hash) continue;
-
+    for (const [relPath, buf] of writes) {
         // Write the raw Buffer so binary blobs round-trip byte-exact.
-        const buf = await readBlob(gentPath, entry.hash);
-        const fullPath = path.join(cwd, relPath);
+        const fullPath = safePath(cwd, relPath);
         await fs.mkdir(path.dirname(fullPath), { recursive: true });
         await fs.writeFile(fullPath, buf);
     }

package/src/commands/resolve.js

@@ -245,6 +245,7 @@ async function finalizeMerge(gentPath, staging, mergeState, entriesByName) {
             if (!authorEmail) authorEmail = globalUser.email;
         }
     }
+    if (!authorName && authorEmail) authorName = authorEmail;
 
     const mergedEntries = [...entriesByName.values()];
     const treeHash = await storeTree(gentPath, mergedEntries);

package/src/utils/merge-engine.js

@@ -130,9 +130,10 @@ function matchBaseToOther(baseLines, otherLines) {
  * @param {String[]} baseLines
  * @param {String[]} oursLines
  * @param {String[]} theirsLines
+ * @param {{ours?: String, theirs?: String}} [labels]
  * @returns {{merged: String[], conflicts: Array, hasConflicts: Boolean}}
  */
-function threeWayMerge(baseLines, oursLines, theirsLines) {
+function threeWayMerge(baseLines, oursLines, theirsLines, labels = {}) {
     const oMatch = matchBaseToOther(baseLines, oursLines);
     const tMatch = matchBaseToOther(baseLines, theirsLines);
 
@@ -157,7 +158,7 @@ function threeWayMerge(baseLines, oursLines, theirsLines) {
         const oursSeg = oursLines.slice(prevO, a.o);
         const theirsSeg = theirsLines.slice(prevT, a.t);
 
-        resolveRegion(baseSeg, oursSeg, theirsSeg, merged, conflicts);
+        resolveRegion(baseSeg, oursSeg, theirsSeg, merged, conflicts, labels);
 
         // Emit the synchronized anchor line (skip the end sentinel).
         if (a.b < baseLines.length) {
@@ -180,8 +181,9 @@ function threeWayMerge(baseLines, oursLines, theirsLines) {
  * @param {String[]} theirsSeg
  * @param {String[]} merged - output accumulator (mutated)
  * @param {Array} conflicts - output accumulator (mutated)
+ * @param {{ours?: String, theirs?: String}} [labels]
  */
-function resolveRegion(baseSeg, oursSeg, theirsSeg, merged, conflicts) {
+function resolveRegion(baseSeg, oursSeg, theirsSeg, merged, conflicts, labels = {}) {
     if (baseSeg.length === 0 && oursSeg.length === 0 && theirsSeg.length === 0) {
         return;
     }
@@ -213,11 +215,11 @@ function resolveRegion(baseSeg, oursSeg, theirsSeg, merged, conflicts) {
         oursContent: oursSeg,
         theirsContent: theirsSeg
     });
-    merged.push('<<<<<<< ours');
+    merged.push(`<<<<<<< ${labels.ours || 'ours'}`);
     merged.push(...oursSeg);
     merged.push('=======');
     merged.push(...theirsSeg);
-    merged.push('>>>>>>> theirs');
+    merged.push(`>>>>>>> ${labels.theirs || 'theirs'}`);
 }
 
 // ─── Sub-Merge (fine-grained) ───────────────────────────
@@ -390,9 +392,10 @@ function parseConflictMarkers(content) {
  * @param {String} oursContent
  * @param {String} theirsContent
  * @param {String} [fileName] - used to pick a language-aware strategy
+ * @param {{ours?: String, theirs?: String}} [labels] - conflict marker labels
  * @returns {{content: String, hasConflicts: Boolean, conflicts: Array}}
  */
-function mergeFileContent(baseContent, oursContent, theirsContent, fileName) {
+function mergeFileContent(baseContent, oursContent, theirsContent, fileName, labels) {
     if (fileName && /\.json$/i.test(fileName)) {
         const jsonResult = mergeJsonContent(baseContent || '', oursContent || '', theirsContent || '');
         if (jsonResult) return jsonResult;
@@ -401,7 +404,7 @@ function mergeFileContent(baseContent, oursContent, theirsContent, fileName) {
     const base = splitLines(baseContent || '');
     const ours = splitLines(oursContent || '');
     const theirs = splitLines(theirsContent || '');
-    const result = threeWayMerge(base, ours, theirs);
+    const result = threeWayMerge(base, ours, theirs, labels);
     return { content: result.merged.join('\n'), hasConflicts: result.hasConflicts, conflicts: result.conflicts };
 }
 
@@ -442,7 +445,7 @@ function autoMerge(baseText, oursText, theirsText) {
  * @param {Array} theirsEntries
  * @returns {Promise<{mergedEntries: Array, conflicts: Array, hasConflicts: Boolean}>}
  */
-async function mergeTreeEntries(gentPath, baseEntries, oursEntries, theirsEntries) {
+async function mergeTreeEntries(gentPath, baseEntries, oursEntries, theirsEntries, labels) {
     const baseMap = treeToMap(baseEntries);
     const oursMap = treeToMap(oursEntries);
     const theirsMap = treeToMap(theirsEntries);
@@ -479,7 +482,7 @@ async function mergeTreeEntries(gentPath, baseEntries, oursEntries, theirsEntrie
                 readBlobAsString(gentPath, oH),
                 readBlobAsString(gentPath, tH)
             ]);
-            const result = mergeFileContent(baseC, oursC, theirsC, filePath);
+            const result = mergeFileContent(baseC, oursC, theirsC, filePath, labels);
             const mergedHash = await storeBlob(gentPath, result.content);
             mergedEntries.push({ mode: '100644', name: filePath, hash: mergedHash, type: 'blob' });
             if (result.hasConflicts) conflicts.push({ file: filePath, type: 'content', details: result.conflicts });
@@ -504,7 +507,7 @@ async function mergeTreeEntries(gentPath, baseEntries, oursEntries, theirsEntrie
                 readBlobAsString(gentPath, oH),
                 readBlobAsString(gentPath, tH)
             ]);
-            const result = mergeFileContent('', oursC, theirsC, filePath);
+            const result = mergeFileContent('', oursC, theirsC, filePath, labels);
             const mergedHash = await storeBlob(gentPath, result.content);
             mergedEntries.push({ mode: '100644', name: filePath, hash: mergedHash, type: 'blob' });
             if (result.hasConflicts) conflicts.push({ file: filePath, type: 'add-add', details: result.conflicts });

package/src/utils/merge-ops.js

@@ -158,7 +158,8 @@ async function merge(repo, theirRevision, options = {}) {
             baseBytes.toString('utf-8'),
             oursBytes.toString('utf-8'),
             theirsBytes.toString('utf-8'),
-            filePath
+            filePath,
+            { ours: 'HEAD', theirs: label }
         );
         const content = Buffer.from(result.content, 'utf-8');
         const oid = await repo.objects.write('blob', content);
@@ -183,7 +184,7 @@ async function merge(repo, theirRevision, options = {}) {
     }
     await index.write(repo.indexPath);
 
-    const message = options.message || `Merge ${label} into ${head.branch || 'HEAD'}`;
+    const message = options.message || `Merge branch '${label}'`;
 
     if (conflicts.length) {
         await ops.writeMergeState(repo, [theirs], `${message}\n\nConflicts:\n${conflicts.map(c => '  ' + c.path).join('\n')}\n`);