gent-cli 15.0.0 → 21.0.0

package/src/index.js

@@ -30,33 +30,34 @@ const { program } = require('commander');
 const chalk = require('chalk');
 const packageJson = require('../package.json');
 const interactive = require('./utils/interactive');
+const { route } = require('./commands/canonical');
 
 // Import core commands
-const autoCommand = require('./commands/auto');
-const initCommand = require('./commands/init');
+const autoCommand = route('auto', require('./commands/auto'));
+const initCommand = route('init', require('./commands/init'));
 const cloneCommand = require('./commands/clone');
-const statusCommand = require('./commands/status');
-const addCommand = require('./commands/add');
-const rmCommand = require('./commands/rm');
-const resetCommand = require('./commands/reset');
-const diffCommand = require('./commands/diff');
-const commitCommand = require('./commands/commit');
-const logCommand = require('./commands/log');
-const showCommand = require('./commands/show');
-const tagCommand = require('./commands/tag');
-const branchCommand = require('./commands/branch');
-const checkoutCommand = require('./commands/checkout');
-const mergeCommand = require('./commands/merge');
-const stashCommand = require('./commands/stash');
-const remoteCommand = require('./commands/remote');
-const pushCommand = require('./commands/push');
-const pullCommand = require('./commands/pull');
+const statusCommand = route('status', require('./commands/status'));
+const addCommand = route('add', require('./commands/add'));
+const rmCommand = route('rm', require('./commands/rm'));
+const resetCommand = route('reset', require('./commands/reset'));
+const diffCommand = route('diff', require('./commands/diff'));
+const commitCommand = route('commit', require('./commands/commit'));
+const logCommand = route('log', require('./commands/log'));
+const showCommand = route('show', require('./commands/show'));
+const tagCommand = route('tag', require('./commands/tag'));
+const branchCommand = route('branch', require('./commands/branch'));
+const checkoutCommand = route('checkout', require('./commands/checkout'));
+const mergeCommand = route('merge', require('./commands/merge'));
+const stashCommand = route('stash', require('./commands/stash'));
+const remoteCommand = route('remote', require('./commands/remote'));
+const pushCommand = route('push', require('./commands/push'));
+const pullCommand = route('pull', require('./commands/pull'));
 const reposCommand = require('./commands/repos');
 const membersCommand = require('./commands/members');
-const undoCommand = require('./commands/undo');
-const resolveCommand = require('./commands/resolve');
-const summaryCommand = require('./commands/summary');
-const explainCommand = require('./commands/explain');
+const undoCommand = route('undo', require('./commands/undo'));
+const resolveCommand = route('resolve', require('./commands/resolve'));
+const summaryCommand = route('summary', require('./commands/summary'));
+const explainCommand = route('explain', require('./commands/explain'));
 
 // Import auth commands
 const registerCommand = require('./commands/register');
@@ -66,16 +67,16 @@ const whoamiCommand = require('./commands/whoami');
 const passwordCommand = require('./commands/password');
 
 // Import new gent-platform commands
-const configCommand = require('./commands/config');
+const configCommand = route('config', require('./commands/config'));
 const doctorCommand = require('./commands/doctor');
 const setupCommand = require('./commands/setup');
 const aiCommand = require('./commands/ai');
-const askCommand = require('./commands/ask');
-const reviewCommand = require('./commands/review');
-const docsCommand = require('./commands/docs');
-const changelogCommand = require('./commands/changelog');
+const askCommand = route('ask', require('./commands/ask'));
+const reviewCommand = route('review', require('./commands/review'));
+const docsCommand = route('docs', require('./commands/docs'));
+const changelogCommand = route('changelog', require('./commands/changelog'));
 const webCommand = require('./commands/web');
-const shareCommand = require('./commands/share');
+const shareCommand = route('share', require('./commands/share'));
 const searchCommand = require('./commands/search');
 const templateCommand = require('./commands/template');
 const petCommand = require('./commands/pet');
@@ -97,9 +98,21 @@ program
     .command('init')
     .description('Initialize a new gent repository')
     .option('-y, --yes', 'Skip prompts and use defaults')
+    .option('--object-format <format>', 'Opt into the canonical SHA-256 engine')
     .option('--remote [name]', 'Create a remote repository on the backend')
     .action(initCommand);
 
+program
+    .command('migrate')
+    .description('Migrate an offline legacy repository with a verified backup')
+    .option('--dry-run', 'Inspect and validate without changing repository state')
+    .option('--continue', 'Complete an interrupted migration')
+    .option('--abort', 'Roll back an interrupted migration if no newer state exists')
+    .action(async options => {
+        try { console.log(JSON.stringify(await require('./utils/migrate').migrate(process.cwd(), options), null, 2)); }
+        catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; }
+    });
+
 program
     .command('clone [url] [directory]')
     .description('Clone a remote repository')
@@ -111,6 +124,11 @@ program
             console.error(chalk.red('error: missing url — usage: gent clone <url> [directory]'));
             process.exit(1);
         }
+        if (/^https?:/.test(url) && /\.git\/?$/.test(url)) {
+            try { console.log(`Cloned to ${await require('./utils/smart-http').clone(url, directory)}`); }
+            catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; }
+            return;
+        }
         return cloneCommand(url, directory, options);
     });
 
@@ -152,8 +170,8 @@ program
 program
     .command('reset [files...]')
     .description('Unstage files or reset HEAD to a commit')
-    .option('--hard <hash>', 'Reset HEAD and working tree to commit')
-    .option('--soft <hash>', 'Reset HEAD but keep staging')
+    .option('--hard [hash]', 'Reset HEAD and working tree to commit')
+    .option('--soft [hash]', 'Reset HEAD but keep staging')
     .action(resetCommand);
 
 program
@@ -221,13 +239,15 @@ program
     .command('checkout [branch]')
     .description('Switch branches or restore working tree files')
     .option('-b, --create', 'Create a new branch')
+    .option('--abort', 'Recover an interrupted canonical checkout')
+    .option('-f, --force', 'Discard local changes when switching')
     .action(async (branch, options) => {
-        if (!branch && interactive.isInteractive()) {
+        if (!branch && !options.abort && interactive.isInteractive()) {
             const picked = await interactive.promptCheckout();
             branch = picked.branch;
             options.create = picked.create; // picker decides: existing branch ⇒ switch, not create
         }
-        if (!branch) {
+        if (!branch && !options.abort) {
             console.error(chalk.red('error: missing branch — usage: gent checkout <branch>'));
             process.exit(1);
         }
@@ -238,8 +258,10 @@ program
     .command('merge [branch]')
     .description('Merge a branch into the current branch (3-way smart merge)')
     .option('-m, --message <message>', 'Merge commit message')
+    .option('--continue', 'Finish a resolved canonical merge')
+    .option('--abort', 'Abort a canonical merge')
     .action(async (branch, options) => {
-        if (!branch && interactive.isInteractive()) {
+        if (!branch && !options.continue && !options.abort && interactive.isInteractive()) {
             const picked = await interactive.promptMerge();
             if (!picked.branch) {
                 // In a repo with only one branch → nothing to merge; otherwise
@@ -252,7 +274,7 @@ program
                 branch = picked.branch;
             }
         }
-        if (!branch && !interactive.isInteractive()) {
+        if (!branch && !options.continue && !options.abort && !interactive.isInteractive()) {
             console.error(chalk.red('error: missing branch — usage: gent merge <branch>'));
             process.exit(1);
         }
@@ -268,6 +290,9 @@ program
     .command('stash [subcommand]')
     .description('Stash working tree changes (pop|list|drop|apply)')
     .option('-m, --message <message>', 'Stash message')
+    .option('--restore-index', 'Restore canonical stash staged state')
+    .option('--keep-index', 'Keep staged changes when stashing')
+    .option('-u, --include-untracked', 'Include untracked files')
     .option('-i, --index <index>', 'Stash index for pop/apply/drop')
     .action(stashCommand);
 
@@ -311,6 +336,11 @@ program
     .option('-f, --force', 'Force push (overwrite remote)')
     .action(pushCommand);
 
+program
+    .command('fetch [remote]')
+    .description('Fetch canonical remote branches and tags')
+    .action(route('fetch', async () => { throw new Error('fetch requires a canonical repository'); }));
+
 program
     .command('pull [remote] [branch]')
     .description('Pull and merge remote commits')
@@ -373,17 +403,17 @@ program
 
 program
     .command('web')
-    .description('Open the current repo (or a branch/commit) on the gent web app')
-    .option('--branch <name>', 'Open a specific branch')
-    .option('--commit <hash>', 'Open a specific commit')
+    .description('Open the current repo on the gent web app')
+    .option('--branch <name>', 'Branch context (opens the repo page — no branch page yet)')
+    .option('--commit <hash>', 'Commit context (opens the repo page — no commit page yet)')
     .option('--print', 'Print the URL instead of launching a browser')
     .action(webCommand);
 
 program
     .command('share')
-    .description('Print a shareable link to current branch tip (or --branch/--commit)')
-    .option('--branch <name>', 'Link to a specific branch')
-    .option('--commit <hash>', 'Link to a specific commit')
+    .description('Print a shareable link to the current repository')
+    .option('--branch <name>', 'Branch context (link resolves to the repo page)')
+    .option('--commit <hash>', 'Commit context (link resolves to the repo page)')
     .action(shareCommand);
 
 program

package/src/utils/api-client.js

@@ -80,8 +80,13 @@ apiClient.interceptors.response.use(
     async (error) => {
         const originalRequest = error.config;
 
-        // If error is 401 and we haven't tried to refresh yet
+        // A public request made without credentials should keep its original
+        // 401 response. Commands such as `gent clone` use that response to
+        // explain that a private repository needs sign-in.
         if (error.response?.status === 401 && !originalRequest._retry) {
+            const refreshToken = await authStorage.getRefreshToken();
+            if (!refreshToken) return Promise.reject(error);
+
             if (isRefreshing) {
                 // If already refreshing, queue this request
                 return new Promise((resolve, reject) => {
@@ -100,14 +105,6 @@ apiClient.interceptors.response.use(
             isRefreshing = true;
 
             try {
-                const refreshToken = await authStorage.getRefreshToken();
-
-                if (!refreshToken) {
-                    // No refresh token, user needs to login again
-                    await authStorage.clearAuth();
-                    throw new Error('Session expired. Please login again.');
-                }
-
                 // Call refresh endpoint (raw axios — bypasses our interceptor
                 // intentionally so a 401 here doesn't loop back into refresh).
                 const baseUrl = await resolveBaseUrl();

package/src/utils/attributes.js

@@ -0,0 +1,280 @@
+/**
+ * ============================================================================
+ * Attributes - gitattributes lookup and text/EOL conversion
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   Decide how a path's bytes differ between the object store and the working
+ *   tree, and refuse — before writing anything — when the answer depends on a
+ *   transformation Gent does not implement.
+ *
+ * SUPPORTED:
+ *   text, -text, text=auto, eol=lf, eol=crlf, the `binary` macro,
+ *   core.autocrlf and core.eol.
+ *
+ * REFUSED (never guessed):
+ *   filter=* (including Git LFS) and working-tree-encoding. A path carrying
+ *   either raises UnsupportedFeatureError, so an operation stops before it
+ *   corrupts content by storing the wrong bytes.
+ *
+ * DIRECTION:
+ *   toIndex()    working tree -> object store ("clean")
+ *   toWorktree() object store -> working tree ("smudge")
+ *   Blobs are stored with LF line endings; CRLF is a working-tree property.
+ * ============================================================================
+ */
+
+const path = require('path');
+
+const { readFileOrNull } = require('./lockfile');
+const { IgnorePattern } = require('./ignore');
+const { UnsupportedFeatureError, feature } = require('./feature-support');
+
+/** Attributes that decide content transformation. */
+const BINARY_MACRO = { text: false, diff: false, merge: false };
+
+/**
+ * @param {Buffer} buffer
+ * @returns {Boolean} Git's heuristic: a NUL byte in the first 8000 bytes
+ */
+function looksBinary(buffer) {
+    const limit = Math.min(buffer.length, 8000);
+    return buffer.indexOf(0, 0) >= 0 && buffer.indexOf(0, 0) < limit;
+}
+
+/**
+ * One `<pattern> <attr>...` line.
+ */
+class AttributeRule {
+    /**
+     * @param {String} line
+     * @param {String} base - POSIX directory the file sits in
+     */
+    constructor(line, base) {
+        const parts = line.trim().split(/\s+/);
+        const pattern = parts.shift();
+        this.matcher = new IgnorePattern(pattern.endsWith('/') ? pattern : pattern, base);
+        this.attributes = {};
+
+        for (const token of parts) {
+            if (token.startsWith('-')) { this.attributes[token.slice(1)] = false; continue; }
+            if (token.startsWith('!')) { this.attributes[token.slice(1)] = undefined; continue; }
+            const eq = token.indexOf('=');
+            if (eq < 0) { this.attributes[token] = true; continue; }
+            this.attributes[token.slice(0, eq)] = token.slice(eq + 1);
+        }
+    }
+
+    /**
+     * @param {String} relativePath
+     * @param {Boolean} isDirectory
+     * @returns {Boolean}
+     */
+    matches(relativePath, isDirectory) {
+        return this.matcher.matches(relativePath, isDirectory);
+    }
+}
+
+/**
+ * @param {String} text
+ * @param {String} base
+ * @returns {Array<AttributeRule>}
+ */
+function parseAttributes(text, base = '') {
+    const rules = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\r$/, '').trim();
+        if (!line || line.startsWith('#')) continue;
+        rules.push(new AttributeRule(line, base));
+    }
+    return rules;
+}
+
+class AttributesMatcher {
+    /**
+     * @param {Object} repo
+     */
+    constructor(repo) {
+        this.repo = repo;
+        this.baseRules = [];
+        this.perDirectory = new Map();
+        this.loaded = false;
+
+        this.autocrlf = repo.config.get('core.autocrlf', 'false').toLowerCase();
+        this.eol = repo.config.get('core.eol', 'native').toLowerCase();
+        this.safecrlf = repo.config.get('core.safecrlf', 'false').toLowerCase();
+    }
+
+    async load() {
+        if (this.loaded) return;
+        this.loaded = true;
+
+        const infoAttributes = await readFileOrNull(path.join(this.repo.commondir, 'info', 'attributes'));
+        if (infoAttributes) this.baseRules.push(...parseAttributes(infoAttributes.toString('utf-8')));
+    }
+
+    /**
+     * @param {String} directory
+     * @returns {Promise<Array<AttributeRule>>}
+     */
+    async rulesFor(directory) {
+        if (this.perDirectory.has(directory)) return this.perDirectory.get(directory);
+
+        const filePath = path.join(this.repo.worktree, ...(directory ? directory.split('/') : []), '.gitattributes');
+        const text = await readFileOrNull(filePath);
+        const rules = text ? parseAttributes(text.toString('utf-8'), directory) : [];
+        this.perDirectory.set(directory, rules);
+        return rules;
+    }
+
+    /**
+     * @param {String} relativePath
+     * @returns {Promise<Object>} resolved attribute values
+     */
+    async attributesFor(relativePath) {
+        await this.load();
+
+        const resolved = {};
+        const apply = (rule) => {
+            if (!rule.matches(relativePath, false)) return;
+            const source = rule.attributes.binary === true ? { ...BINARY_MACRO, ...rule.attributes } : rule.attributes;
+            for (const [key, value] of Object.entries(source)) {
+                if (key === 'binary') continue;
+                resolved[key] = value;
+            }
+        };
+
+        for (const rule of this.baseRules) apply(rule);
+
+        const components = relativePath.split('/');
+        for (let depth = 0; depth < components.length; depth++) {
+            for (const rule of await this.rulesFor(components.slice(0, depth).join('/'))) apply(rule);
+        }
+        return resolved;
+    }
+
+    /**
+     * Refuse paths whose bytes depend on an unimplemented transformation.
+     * @param {String} relativePath
+     * @param {Object} attributes
+     * @param {String} what
+     */
+    assertConvertible(relativePath, attributes, what) {
+        const problems = [];
+        if (attributes.filter !== undefined && attributes.filter !== false) {
+            problems.push({
+                ...feature('attributes.filter'),
+                detail: `'${relativePath}' has filter=${attributes.filter}; its stored bytes are produced by an external program.`
+            });
+        }
+        if (attributes['working-tree-encoding'] !== undefined && attributes['working-tree-encoding'] !== false) {
+            problems.push({
+                id: 'attributes.encoding',
+                status: 'unsupported',
+                title: 'working-tree-encoding attribute',
+                detail: `'${relativePath}' declares working-tree-encoding=${attributes['working-tree-encoding']}.`,
+                remedy: 'Check this path out with Git, or remove the attribute.'
+            });
+        }
+        if (problems.length) throw new UnsupportedFeatureError(problems, what);
+    }
+
+    /**
+     * Decide whether CRLF conversion applies to a path.
+     * @param {String} relativePath
+     * @param {Buffer} sample - content used for the text=auto heuristic
+     * @returns {Promise<{convert: Boolean, worktreeEol: 'lf'|'crlf'}>}
+     */
+    async conversionFor(relativePath, sample) {
+        const attributes = await this.attributesFor(relativePath);
+        this.assertConvertible(relativePath, attributes, 'converting line endings');
+
+        let isText;
+        if (attributes.text === false) isText = false;
+        else if (attributes.text === true) isText = true;
+        else if (attributes.text === 'auto') isText = !looksBinary(sample);
+        else if (this.autocrlf === 'true' || this.autocrlf === 'input') isText = !looksBinary(sample);
+        else isText = false;
+
+        if (!isText) return { convert: false, worktreeEol: 'lf' };
+
+        let worktreeEol;
+        if (attributes.eol === 'crlf') worktreeEol = 'crlf';
+        else if (attributes.eol === 'lf') worktreeEol = 'lf';
+        else if (this.autocrlf === 'true') worktreeEol = 'crlf';
+        else if (this.autocrlf === 'input') worktreeEol = 'lf';
+        else if (this.eol === 'crlf') worktreeEol = 'crlf';
+        else if (this.eol === 'native') worktreeEol = process.platform === 'win32' ? 'crlf' : 'lf';
+        else worktreeEol = 'lf';
+
+        return { convert: true, worktreeEol };
+    }
+
+    /**
+     * Working tree bytes -> stored blob bytes.
+     * @param {String} relativePath
+     * @param {Buffer} content
+     * @returns {Promise<Buffer>}
+     */
+    async toIndex(relativePath, content) {
+        const { convert } = await this.conversionFor(relativePath, content);
+        if (!convert) return content;
+        return normalizeToLf(content);
+    }
+
+    /**
+     * Stored blob bytes -> working tree bytes.
+     * @param {String} relativePath
+     * @param {Buffer} content
+     * @returns {Promise<Buffer>}
+     */
+    async toWorktree(relativePath, content) {
+        const { convert, worktreeEol } = await this.conversionFor(relativePath, content);
+        if (!convert || worktreeEol !== 'crlf') return content;
+        return normalizeToCrlf(content);
+    }
+}
+
+/**
+ * @param {Buffer} content
+ * @returns {Buffer}
+ */
+function normalizeToLf(content) {
+    if (!content.includes(0x0d)) return content;
+
+    const out = Buffer.allocUnsafe(content.length);
+    let written = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === 0x0d && content[i + 1] === 0x0a) continue;   // drop the CR of a CRLF
+        out[written++] = content[i];
+    }
+    return out.subarray(0, written);
+}
+
+/**
+ * @param {Buffer} content
+ * @returns {Buffer}
+ */
+function normalizeToCrlf(content) {
+    const lf = normalizeToLf(content);
+    let count = 0;
+    for (let i = 0; i < lf.length; i++) if (lf[i] === 0x0a) count++;
+    if (count === 0) return lf;
+
+    const out = Buffer.allocUnsafe(lf.length + count);
+    let written = 0;
+    for (let i = 0; i < lf.length; i++) {
+        if (lf[i] === 0x0a) out[written++] = 0x0d;
+        out[written++] = lf[i];
+    }
+    return out;
+}
+
+module.exports = {
+    AttributesMatcher,
+    AttributeRule,
+    parseAttributes,
+    looksBinary,
+    normalizeToLf,
+    normalizeToCrlf
+};

package/src/utils/canonical-journal.js

@@ -0,0 +1,122 @@
+/** Exact local checkpoints for canonical undo/redo. Private refs retain every
+ * object needed by a checkpoint when external Git runs garbage collection.
+ */
+const fs = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+const { GitIndex, IndexEntry } = require('./git-index');
+const { IgnoreMatcher, walkWorktree } = require('./ignore');
+const { serializeCommit, serializeTree, MODE } = require('./git-objects');
+const { writeAtomic, readFileOrNull } = require('./lockfile');
+const worktree = require('./worktree');
+
+const journalPath = repo => path.join(repo.gentWorktreeMetaDir, 'journal.json');
+async function read(repo) {
+    const bytes = await readFileOrNull(journalPath(repo));
+    return bytes ? JSON.parse(bytes.toString()) : { undo: [], redo: [] };
+}
+async function save(repo, journal) { await writeAtomic(journalPath(repo), JSON.stringify(journal)); }
+
+async function capture(repo) {
+    const index = await GitIndex.read(repo.indexPath);
+    const files = {};
+    const matcher = new IgnoreMatcher(repo);
+    const names = new Set(index.entries.map(e => e.path));
+    for await (const entry of walkWorktree(repo, matcher, { tracked: names })) names.add(entry.path);
+    for (const name of [...names].sort()) {
+        const file = await worktree.snapshotPath(repo, name);
+        if (file) files[name] = { mode: file.mode, oid: await repo.objects.write('blob', Buffer.from(file.content, 'base64')) };
+    }
+    const refs = Object.fromEntries([...(await repo.refs.list())].filter(([name]) => !name.startsWith('refs/gent/')).sort(([a], [b]) => a.localeCompare(b)));
+    const merge = {};
+    for (const name of ['MERGE_HEAD', 'MERGE_MSG', 'MERGE_MODE', 'ORIG_HEAD']) merge[name] = (await readFileOrNull(repo.gitPath(name)))?.toString('base64') ?? null;
+    return { head: await repo.refs.head(), refs, index: index.sourceBytes?.toString('base64') ?? null, files, merge };
+}
+
+async function retain(repo, state, prefix) {
+    const entries = [];
+    // These are retention objects, not worktree trees. Numeric names allow
+    // conflicted index stages and staged/unstaged versions to coexist.
+    for (const item of Object.values(state.files)) entries.push({ name: String(entries.length), mode: MODE.REGULAR, oid: item.oid });
+    if (state.index) {
+        for (const item of GitIndex.parse(Buffer.from(state.index, 'base64')).entries) {
+            if (item.mode === MODE.GITLINK) throw new Error('journal checkpoints do not support submodules');
+            entries.push({ name: String(entries.length), mode: MODE.REGULAR, oid: item.oid });
+        }
+    }
+    const tree = await repo.objects.write('tree', serializeTree(entries));
+    const identity = { name: 'Gent checkpoint', email: 'checkpoint@gent.local', timestamp: Math.floor(Date.now() / 1000), timezone: '+0000' };
+    const oid = await repo.objects.write('commit', serializeCommit({ tree, parents: state.head.oid ? [state.head.oid] : [], author: identity, committer: identity, message: Buffer.from('Gent undo checkpoint\n') }));
+    await repo.refs.update(`${prefix}/snapshot`, oid, { expectedOldOid: null, reason: 'retain undo checkpoint' });
+    let n = 0;
+    for (const target of new Set(Object.values(state.refs))) await repo.refs.update(`${prefix}/ref-${n++}`, target, { expectedOldOid: null, reason: 'retain undo ref' });
+}
+
+async function begin(repo, name) {
+    const before = await capture(repo);
+    const id = crypto.randomUUID();
+    await retain(repo, before, `refs/gent/journal/${id}/before`);
+    return { id, name, before };
+}
+
+async function finish(repo, entry) {
+    entry.after = await capture(repo);
+    await retain(repo, entry.after, `refs/gent/journal/${entry.id}/after`);
+    const journal = await read(repo);
+    journal.undo.push(entry);
+    journal.redo = [];
+    await save(repo, journal);
+}
+
+function sameState(a, b) {
+    // Index stat refreshes by other tools are harmless. Compare staged content
+    // and flags, not filesystem cache timestamps.
+    const semantic = state => {
+        const entries = state.index ? GitIndex.parse(Buffer.from(state.index, 'base64')).entries : [];
+        return { ...state, index: entries.map(e => ({ path: e.path, oid: e.oid, mode: e.mode, stage: e.stage, assumeValid: e.assumeValid, skipWorktree: e.skipWorktree, intentToAdd: e.intentToAdd })) };
+    };
+    return JSON.stringify(semantic(a)) === JSON.stringify(semantic(b));
+}
+
+async function restore(repo, redo = false) {
+    await worktree.assertNoPendingCheckout(repo, 'undo/redo');
+    const journal = await read(repo);
+    const source = redo ? journal.redo : journal.undo;
+    const entry = source[source.length - 1];
+    if (!entry) throw new Error(`nothing to ${redo ? 'redo' : 'undo'}`);
+    const expected = redo ? entry.before : entry.after;
+    const target = redo ? entry.after : entry.before;
+    const current = await capture(repo);
+    if (!sameState(current, expected)) throw new Error('repository changed since the recorded operation; refusing to overwrite intervening work');
+    const index = await GitIndex.read(repo.indexPath);
+    const targetIndex = target.index ? GitIndex.parse(Buffer.from(target.index, 'base64')) : new GitIndex();
+    const from = new Map(Object.entries(current.files));
+    const to = new Map(Object.entries(target.files));
+    const plan = await worktree.planCheckout(repo, { from, to, index, force: true });
+    // Snapshots store exact working bytes, so EOL conversion must not run twice.
+    for (const write of plan.writes) write.content = (await repo.objects.readBlob(write.oid)).toString('base64');
+    await worktree.applyCheckout(repo, plan, { index });
+    index.entries = targetIndex.entries;
+    index.extensions.clear();
+    await index.write(repo.indexPath);
+    for (const name of new Set([...Object.keys(current.refs), ...Object.keys(target.refs)])) {
+        if (current.refs[name] === target.refs[name]) continue;
+        if (target.refs[name]) await repo.refs.update(name, target.refs[name], { expectedOldOid: current.refs[name] || null, reason: redo ? 'redo' : 'undo' });
+        else await repo.refs.delete(name, { expectedOldOid: current.refs[name], reason: redo ? 'redo' : 'undo' });
+    }
+    // A branch ref may already have moved above; HEAD's expected oid follows it.
+    const expectedHead = { ...current.head, oid: current.head.ref ? (target.refs[current.head.ref] || null) : current.head.oid };
+    if (target.head.ref) await repo.refs.setHeadSymbolic(target.head.ref, redo ? 'redo' : 'undo', expectedHead);
+    else await repo.refs.setHeadDetached(target.head.oid, redo ? 'redo' : 'undo', expectedHead);
+    for (const [name, bytes] of Object.entries(target.merge)) {
+        if (bytes === null) await fs.rm(repo.gitPath(name), { force: true });
+        else await writeAtomic(repo.gitPath(name), Buffer.from(bytes, 'base64'));
+    }
+    source.pop();
+    (redo ? journal.undo : journal.redo).push(entry);
+    await save(repo, journal);
+    await worktree.completeCheckout(repo);
+    return entry.name;
+}
+
+module.exports = { begin, finish, restore, read };