gent-cli 15.0.0 → 20.0.0

package/src/utils/smart-http.js

@@ -0,0 +1,195 @@
+/** Independent bounded protocol-v0 client. No external Git engine. */
+const fs = require('fs').promises;
+const path = require('path');
+const axios = require('axios');
+const objects = require('./git-objects');
+const { buildPack, readPackStream } = require('./packfile');
+const { assertRefName: validateRefName } = require('./refs');
+const repository = require('./repository');
+const ops = require('./gent-ops');
+const MAX_BYTES = 128 * 1024 * 1024;
+const ZERO = '0'.repeat(64);
+
+function pkt(value) {
+    const data = Buffer.isBuffer(value) ? value : Buffer.from(value);
+    if (data.length > 65516) throw new Error('packet exceeds limit');
+    return Buffer.concat([Buffer.from((data.length + 4).toString(16).padStart(4, '0')), data]);
+}
+function packet(data, pos) {
+    const raw = data.toString('ascii', pos, pos + 4);
+    if (!/^[0-9a-f]{4}$/i.test(raw)) throw new Error('invalid packet length');
+    const size = parseInt(raw, 16);
+    if (!size) return { line: null, pos: pos + 4 };
+    if (size < 4 || size > 65520 || pos + size > data.length) throw new Error('truncated packet');
+    const line = data.subarray(pos + 4, pos + size);
+    if (line.toString().startsWith('ERR ')) throw new Error(line.toString().trim());
+    return { line, pos: pos + size };
+}
+function remoteUrl(value) {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error('use an HTTP(S) URL without credentials, query or fragment');
+    }
+    if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+        throw new Error('remote connections require HTTPS (HTTP is allowed on loopback for development)');
+    }
+    return url.toString().replace(/\/$/, '');
+}
+async function request(url, service, body) {
+    const headers = {};
+    if (process.env.GENT_HTTP_TOKEN) {
+        if (!process.env.GENT_HTTP_USER) throw new Error('set GENT_HTTP_USER with GENT_HTTP_TOKEN');
+        headers.Authorization = 'Basic ' + Buffer.from(`${process.env.GENT_HTTP_USER}:${process.env.GENT_HTTP_TOKEN}`).toString('base64');
+    }
+    const suffix = body ? service : `info/refs?service=${service}`;
+    if (body) headers['Content-Type'] = `application/x-${service}-request`;
+    const result = await axios({ url: `${remoteUrl(url)}/${suffix}`, method: body ? 'POST' : 'GET', data: body,
+        headers, responseType: 'arraybuffer', timeout: 30000, maxRedirects: 0,
+        maxBodyLength: MAX_BYTES, maxContentLength: MAX_BYTES,
+        validateStatus: () => true });
+    if (result.status !== 200) throw new Error(`remote returned HTTP ${result.status}`);
+    const expected = `application/x-${service}-${body ? 'result' : 'advertisement'}`;
+    if (result.headers['content-type']?.split(';')[0] !== expected) throw new Error('invalid smart HTTP content type');
+    return Buffer.from(result.data);
+}
+async function discover(url, service = 'git-upload-pack') {
+    const data = await request(url, service);
+    let row = packet(data, 0);
+    if (row.line?.toString() !== `# service=${service}\n`) throw new Error('invalid service advertisement');
+    row = packet(data, row.pos);
+    if (row.line !== null) throw new Error('missing service flush');
+    const refs = new Map(); let caps = [], first = true, pos = row.pos;
+    while (pos < data.length) {
+        row = packet(data, pos); pos = row.pos;
+        if (row.line === null) break;
+        const [value, capabilities] = row.line.toString().replace(/\n$/, '').split('\0');
+        if (first) caps = (capabilities || '').split(' ');
+        else if (capabilities) throw new Error('unexpected capabilities');
+        first = false;
+        const [oid, name] = value.split(' ');
+        objects.assertObjectId(oid);
+        if (name === 'capabilities^{}' && oid === ZERO) continue;
+        if (name !== 'HEAD') validateRefName(name.replace(/\^\{\}$/, ''));
+        refs.set(name, oid);
+    }
+    if (!caps.includes('object-format=sha256')) throw new Error('remote must negotiate SHA-256');
+    return { refs, caps, head: caps.find(c => c.startsWith('symref=HEAD:'))?.slice(12) };
+}
+function dependencies(item) {
+    if (item.type === 'blob') return [];
+    if (item.type === 'tree') return objects.parseTree(item.payload).filter(e => e.mode !== 0o160000).map(e => [e.oid, e.type]);
+    if (item.type === 'commit') {
+        const c = objects.parseCommit(item.payload);
+        if (!c.author || !c.committer) throw new Error('commit identities required');
+        return [[c.tree, 'tree'], ...c.parents.map(p => [p, 'commit'])];
+    }
+    if (item.type === 'tag') { const t = objects.parseTag(item.payload); return [[t.object, t.targetType]]; }
+    throw new Error('invalid object type');
+}
+async function closure(roots, resolve) {
+    const result = new Map(), todo = [...roots]; let total = 0;
+    while (todo.length) {
+        const [oid, expected] = todo.pop();
+        const item = result.get(oid) || await resolve(oid);
+        if (!item || (expected && item.type !== expected)) throw new Error(`missing or mistyped object ${oid}`);
+        if (result.has(oid)) continue;
+        if (objects.hashObject(item.type, item.payload) !== oid) throw new Error('object ID mismatch');
+        total += item.payload.length;
+        if (total > MAX_BYTES || result.size >= 10000) throw new Error('history exceeds transfer limits');
+        result.set(oid, { ...item, oid }); todo.push(...dependencies(item));
+    }
+    return result;
+}
+function nameCheck(name) {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error('remote name must use letters, digits, _ or -');
+}
+function configured(repo, name = 'origin') {
+    nameCheck(name);
+    const fetchSpecs = repo.config.getAll(`remote.${name}.fetch`);
+    if (fetchSpecs.some(spec => spec !== `+refs/heads/*:refs/remotes/${name}/*`)) throw new Error('custom fetch refspecs are not supported; use the full branch mapping');
+    for (const key of ['mirror', 'promisor', 'uploadpack', 'receivepack', 'proxy', 'pushurl', 'tagopt']) {
+        if (repo.config.get(`remote.${name}.${key}`) !== undefined) throw new Error(`remote.${name}.${key} is not supported by the canonical transport`);
+    }
+    const url = repo.config.get(`remote.${name}.url`);
+    if (!url) throw new Error(`remote '${name}' is not configured; use gent remote add ${name} <url>`);
+    return remoteUrl(url);
+}
+async function fetch(repo, name = 'origin', url = configured(repo, name)) {
+    nameCheck(name);
+    const ad = await discover(url);
+    const selected = [...ad.refs].filter(([ref]) => ref.startsWith('refs/heads/') || (ref.startsWith('refs/tags/') && !ref.endsWith('^{}')));
+    const updates = [];
+    for (const [ref, oid] of selected) {
+        const target = ref.startsWith('refs/heads/') ? `refs/remotes/${name}/${ref.slice(11)}` : ref;
+        const before = await repo.refs.resolveToOid(target);
+        if (ref.startsWith('refs/tags/') && before && before !== oid) throw new Error(`remote tag differs: ${ref}`);
+        updates.push({ name: target, newOid: oid, expectedOldOid: before });
+    }
+    if (selected.length) {
+        const wants = [...new Set(selected.map(([, oid]) => oid))];
+        const body = Buffer.concat([...wants.map((oid, i) => pkt(`want ${oid}${i ? '' : ' object-format=sha256'}\n`)), Buffer.from('0000'), pkt('done\n')]);
+        const data = await request(url, 'git-upload-pack', body);
+        const first = packet(data, 0);
+        if (first.line?.toString() !== 'NAK\n') throw new Error('unsupported upload response');
+        const incoming = await readPackStream(data.subarray(first.pos), { maxObjects: 10000, resolveBase: oid => repo.objects.has(oid).then(has => has ? repo.objects.read(oid) : null) });
+        const byOid = new Map(incoming.map(item => [item.oid, item]));
+        await closure(selected.map(([ref, oid]) => [oid, ref.startsWith('refs/heads/') ? 'commit' : null]), oid => byOid.get(oid) || repo.objects.read(oid));
+        for (const item of incoming) await repo.objects.writeVerified(item.oid, item.type, item.payload);
+        await repo.refs.updateMany(updates, `fetch ${name}`);
+    }
+    return ad;
+}
+async function push(repo, name = 'origin', branch, options = {}) {
+    const url = configured(repo, name), head = await repo.refs.head();
+    branch ||= head.branch;
+    if (!branch) throw new Error('specify a branch from detached HEAD');
+    const ref = branch.startsWith('refs/') ? branch : `refs/heads/${branch}`;
+    validateRefName(ref);
+    if (!ref.startsWith('refs/heads/') && !ref.startsWith('refs/tags/')) throw new Error('only branches and tags may be pushed');
+    const target = await repo.refs.resolveToOid(ref);
+    if (!target) throw new Error(`unknown ref ${ref}`);
+    const ad = await discover(url, 'git-receive-pack'), old = ad.refs.get(ref) || ZERO;
+    if (target === old) return;
+    if (old !== ZERO && !options.force && (ref.startsWith('refs/tags/') || !(await ops.isAncestor(repo, old, target)))) {
+        throw new Error('non-fast-forward push; fetch and merge first');
+    }
+    if (!ad.caps.includes('report-status')) throw new Error('remote must report ref status');
+    const all = await closure([[target, ref.startsWith('refs/heads/') ? 'commit' : null]], oid => repo.objects.read(oid));
+    const body = Buffer.concat([pkt(`${old} ${target} ${ref}\0report-status object-format=sha256\n`), Buffer.from('0000'), buildPack([...all.values()]).pack]);
+    const data = await request(url, 'git-receive-pack', body);
+    let pos = 0; const lines = [];
+    while (pos < data.length) { const row = packet(data, pos); pos = row.pos; if (row.line === null) break; lines.push(row.line.toString().trim()); }
+    if (lines[0] !== 'unpack ok' || !lines.includes(`ok ${ref}`) || lines.some(line => line.startsWith('ng '))) throw new Error(`push rejected: ${lines.join('; ')}`);
+}
+async function clone(url, directory) {
+    url = remoteUrl(url);
+    const ad = await discover(url);
+    const destination = path.resolve(directory || new URL(url).pathname.split('/').pop().replace(/\.git$/, ''));
+    // Exclusive directory creation avoids touching existing user files on failure.
+    await fs.mkdir(destination);
+    const branch = ad.head?.startsWith('refs/heads/') ? ad.head.slice(11) : 'main';
+    validateRefName(`refs/heads/${branch}`);
+    const { repo } = await repository.init(destination, { defaultBranch: branch });
+    repo.localConfig.set('remote.origin.url', url);
+    repo.localConfig.set('remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*');
+    repo.localConfig.set(`branch.${branch}.remote`, 'origin');
+    repo.localConfig.set(`branch.${branch}.merge`, `refs/heads/${branch}`);
+    await repo.localConfig.save();
+    const current = await fetch(repo, 'origin', url), tip = current.refs.get(`refs/heads/${branch}`);
+    if (tip) {
+        await repo.refs.update(`refs/heads/${branch}`, tip, { expectedOldOid: null, reason: 'clone' });
+        await ops.checkout(repo, branch, { force: true });
+    }
+    return destination;
+}
+async function migrationInfo(url) {
+    const headers = {};
+    if (process.env.GENT_HTTP_TOKEN) {
+        if (!process.env.GENT_HTTP_USER) throw new Error('set GENT_HTTP_USER with GENT_HTTP_TOKEN');
+        headers.Authorization = 'Basic ' + Buffer.from(`${process.env.GENT_HTTP_USER}:${process.env.GENT_HTTP_TOKEN}`).toString('base64');
+    }
+    const result = await axios.get(remoteUrl(url) + '/gent-migration', { headers, timeout: 30000, maxRedirects: 0, maxContentLength: MAX_BYTES });
+    if (result.data?.format !== 'gent-migration-1' || result.data.object_format !== 'sha256') throw new Error('server cutover must finish before connected migration');
+    return result.data;
+}
+module.exports = { migrationInfo, pkt, packet, discover, closure, fetch, push, clone, configured, remoteUrl, nameCheck };

package/src/utils/stash-ops.js

@@ -0,0 +1,355 @@
+/**
+ * ============================================================================
+ * Stash Ops - real stash commits on refs/stash
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   Shelve working-tree and index state as genuine commits, so a stash Gent
+ *   creates can be inspected, applied or dropped by Git and vice versa.
+ *   The v12 JSON stack could do none of that.
+ *
+ * TOPOLOGY (Git's):
+ *   i = commit(tree = index tree,        parents = [HEAD])
+ *   u = commit(tree = untracked files,   parents = [])          (optional)
+ *   W = commit(tree = working tree,      parents = [HEAD, i, u?])
+ *   refs/stash -> W, and the *stack* is refs/stash's reflog: stash@{0} is the
+ *   newest entry, stash@{1} the one before it, and so on.
+ *
+ * DROPPING:
+ *   Removing stash@{N} means rewriting the reflog and repointing refs/stash at
+ *   the new newest entry — exactly what Git does. Dropping the last entry
+ *   deletes the ref.
+ * ============================================================================
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+const { serializeCommit, serializeTree, MODE, NULL_OID } = require('./git-objects');
+const { GitIndex, IndexEntry } = require('./git-index');
+const { AttributesMatcher } = require('./attributes');
+const { IgnoreMatcher, walkWorktree } = require('./ignore');
+const worktree = require('./worktree');
+const ops = require('./gent-ops');
+const { writeAtomic, readFileOrNull, withLock } = require('./lockfile');
+
+const STASH_REF = 'refs/stash';
+
+class StashError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = 'StashError';
+        this.code = code || 'GENT_STASH';
+    }
+}
+
+/**
+ * Build a tree from an explicit path -> {mode, oid} map.
+ * @param {Object} repo
+ * @param {Map} entries
+ * @returns {Promise<String>}
+ */
+async function buildTree(repo, entries) {
+    const root = new Map();
+    for (const [filePath, entry] of entries) {
+        const parts = filePath.split('/');
+        let node = root;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (!node.has(parts[i])) node.set(parts[i], new Map());
+            node = node.get(parts[i]);
+        }
+        node.set(parts[parts.length - 1], entry);
+    }
+
+    async function store(node) {
+        const list = [];
+        for (const [name, child] of node) {
+            list.push(child instanceof Map
+                ? { mode: MODE.TREE, name, oid: await store(child) }
+                : { mode: child.mode, name, oid: child.oid });
+        }
+        return repo.objects.write('tree', serializeTree(list));
+    }
+    return store(root);
+}
+
+/**
+ * Shelve the current changes.
+ *
+ * @param {Object} repo
+ * @param {Object} [options]
+ * @param {String} [options.message]
+ * @param {Boolean} [options.includeUntracked]
+ * @param {Boolean} [options.keepIndex]
+ * @returns {Promise<{oid: String, message: String}>}
+ */
+async function push(repo, options = {}) {
+    await repo.assertNoExternalOperation('gent stash');
+    repo.requireWorktree('gent stash');
+
+    const head = await repo.refs.head();
+    if (!head.oid) throw new StashError('cannot stash before the first commit');
+
+    const index = await GitIndex.read(repo.indexPath);
+    if (index.hasConflicts()) throw new StashError('cannot stash while a merge is unresolved');
+
+    const state = await ops.status(repo, { index });
+    const untracked = options.includeUntracked ? state.untracked : [];
+    if (!state.staged.length && !state.unstaged.length && !untracked.length) {
+        throw new StashError('there is nothing to stash', 'GENT_NOTHING_TO_STASH');
+    }
+
+    const identity = await repo.identity('committer');
+    if (!identity) throw new StashError('stashing needs user.name and user.email', 'GENT_NO_IDENTITY');
+
+    const headCommit = await repo.objects.readCommit(head.oid);
+    const branchLabel = head.branch || `(no branch) ${head.oid.slice(0, 7)}`;
+    const subject = headCommit.message.toString('utf-8').split('\n')[0];
+
+    // i: the index exactly as it stands.
+    const indexTree = await worktree.buildTreeFromIndex(repo, index);
+    const indexCommit = await repo.objects.write('commit', serializeCommit({
+        tree: indexTree,
+        parents: [head.oid],
+        author: identity,
+        committer: identity,
+        message: Buffer.from(`index on ${branchLabel}: ${head.oid.slice(0, 7)} ${subject}\n`, 'utf-8')
+    }));
+
+    // u: untracked files, parentless.
+    let untrackedCommit = null;
+    if (untracked.length) {
+        const attributes = new AttributesMatcher(repo);
+        const entries = new Map();
+        for (const relativePath of untracked) {
+            const staged = await worktree.stageWorktreeFile(repo, attributes, relativePath);
+            entries.set(relativePath, { mode: staged.mode, oid: staged.oid });
+        }
+        const untrackedTree = await buildTree(repo, entries);
+        untrackedCommit = await repo.objects.write('commit', serializeCommit({
+            tree: untrackedTree,
+            parents: [],
+            author: identity,
+            committer: identity,
+            message: Buffer.from(`untracked files on ${branchLabel}: ${head.oid.slice(0, 7)} ${subject}\n`, 'utf-8')
+        }));
+    }
+
+    // W: the working tree as it stands.
+    const attributes = new AttributesMatcher(repo);
+    const worktreeEntries = new Map();
+    for (const entry of index.staged()) {
+        const absolute = path.join(repo.worktree, ...entry.path.split('/'));
+        const stat = await fs.lstat(absolute).catch(() => null);
+        if (!stat) continue;                                   // deleted in the working tree
+        const staged = await worktree.stageWorktreeFile(repo, attributes, entry.path);
+        worktreeEntries.set(entry.path, { mode: staged.mode, oid: staged.oid });
+    }
+    const worktreeTree = await buildTree(repo, worktreeEntries);
+
+    const parents = [head.oid, indexCommit];
+    if (untrackedCommit) parents.push(untrackedCommit);
+
+    const message = options.message
+        ? `On ${branchLabel}: ${options.message}`
+        : `WIP on ${branchLabel}: ${head.oid.slice(0, 7)} ${subject}`;
+
+    const stashCommit = await repo.objects.write('commit', serializeCommit({
+        tree: worktreeTree,
+        parents,
+        author: identity,
+        committer: identity,
+        message: Buffer.from(message + '\n', 'utf-8')
+    }));
+
+    const previous = await repo.refs.resolveToOid(STASH_REF);
+    await repo.refs.update(STASH_REF, stashCommit, { expectedOldOid: previous, reason: message });
+
+    // Restore the worktree and index to HEAD, then drop untracked files.
+    await ops.reset(repo, 'hard', 'HEAD');
+    for (const relativePath of untracked) {
+        await fs.rm(path.join(repo.worktree, ...relativePath.split('/')), { force: true });
+        await worktree.removeEmptyParents(repo, relativePath);
+    }
+    if (options.keepIndex) {
+        const restored = await worktree.readTreeRecursive(repo, indexTree);
+        const rebuilt = await GitIndex.read(repo.indexPath);
+        const current = new Map(rebuilt.staged().map(e => [e.path, { mode: e.mode, oid: e.oid }]));
+        const plan = await worktree.planCheckout(repo, { from: current, to: restored, index: rebuilt, force: true });
+        await worktree.applyCheckout(repo, plan, { index: rebuilt });
+        await rebuilt.write(repo.indexPath);
+        await worktree.completeCheckout(repo);
+    }
+
+    return { oid: stashCommit, message };
+}
+
+/**
+ * The stash stack, newest first, read from refs/stash's reflog.
+ * @param {Object} repo
+ * @returns {Promise<Array<{index: Number, oid: String, message: String}>>}
+ */
+async function list(repo) {
+    const reflog = await repo.refs.readReflog(STASH_REF);
+    return reflog
+        .map((entry, position) => ({ position, oid: entry.newOid, message: entry.message }))
+        .reverse()
+        .map((entry, index) => ({ index, oid: entry.oid, message: entry.message, position: entry.position }));
+}
+
+/**
+ * @param {Object} repo
+ * @param {Number} index
+ * @returns {Promise<{index, oid, message, position}>}
+ */
+async function at(repo, index = 0) {
+    const stack = await list(repo);
+    const found = stack[index];
+    if (!found) throw new StashError(`stash@{${index}} does not exist (the stack holds ${stack.length})`);
+    return found;
+}
+
+/**
+ * Restore a stash into the working tree.
+ *
+ * @param {Object} repo
+ * @param {Number} index
+ * @param {Object} [options]
+ * @param {Boolean} [options.restoreIndex] - also restore the staged state
+ * @returns {Promise<{written: Number, deleted: Number, untracked: Number}>}
+ */
+async function apply(repo, index = 0, options = {}) {
+    await repo.assertNoExternalOperation('gent stash apply');
+    repo.requireWorktree('gent stash apply');
+
+    const entry = await at(repo, index);
+    const stash = await repo.objects.readCommit(entry.oid);
+    if (stash.parents.length < 2) throw new StashError(`${entry.oid.slice(0, 12)} is not a stash commit`);
+
+    await worktree.assertNoPendingCheckout(repo, 'gent stash apply');
+    const currentIndex = await GitIndex.read(repo.indexPath);
+    const state = await ops.status(repo, { index: currentIndex });
+    if (state.staged.length || state.unstaged.length || state.conflicted.length) {
+        throw new StashError('commit or stash local changes before applying a stash');
+    }
+    const current = new Map(currentIndex.staged().map(e => [e.path, { mode: e.mode, oid: e.oid }]));
+    const base = await worktree.readTreeRecursive(repo, (await repo.objects.readCommit(stash.parents[0])).tree);
+    const saved = await worktree.readTreeRecursive(repo, stash.tree);
+    const target = await mergeStashTrees(repo, base, current, saved);
+    let stagedTarget = current;
+    if (options.restoreIndex) {
+        const savedIndex = await worktree.readTreeRecursive(repo, (await repo.objects.readCommit(stash.parents[1])).tree);
+        stagedTarget = await mergeStashTrees(repo, base, current, savedIndex);
+    }
+
+    let untrackedCount = 0;
+    if (stash.parents.length >= 3) {
+        const files = await worktree.readTreeRecursive(repo, (await repo.objects.readCommit(stash.parents[2])).tree);
+        for (const [name, item] of files) {
+            if (current.has(name) || await worktree.snapshotPath(repo, name)) {
+                throw new StashError(`cannot restore untracked '${name}': path already exists`);
+            }
+            target.set(name, item);
+            untrackedCount++;
+        }
+    }
+    const plan = await worktree.planCheckout(repo, { from: current, to: target, index: currentIndex });
+    // The working snapshot is not the staged snapshot. Default apply leaves
+    // the index untouched; --index restores only the saved staged changes.
+    if (options.restoreIndex) {
+        currentIndex.entries = [];
+        currentIndex.extensions.clear();
+        for (const [name, item] of stagedTarget) currentIndex.add(new IndexEntry({ path: name, ...item }));
+        currentIndex.serialize();
+    }
+    const applied = await worktree.applyCheckout(repo, plan);
+    if (options.restoreIndex) await currentIndex.write(repo.indexPath);
+    await worktree.completeCheckout(repo);
+
+    return { ...applied, untracked: untrackedCount };
+}
+
+/**
+ * Remove one entry from the stack, rewriting the reflog as Git does.
+ * @param {Object} repo
+ * @param {Number} index
+ * @returns {Promise<String>} the dropped oid
+ */
+async function drop(repo, index = 0) {
+    await repo.assertNoExternalOperation('gent stash drop');
+    const entry = await at(repo, index);
+    const reflogPath = repo.refs.reflogPath(STASH_REF);
+
+    const raw = await readFileOrNull(reflogPath);
+    const lines = raw ? raw.toString('utf-8').split('\n').filter(Boolean) : [];
+    if (entry.position >= lines.length) throw new StashError(`stash@{${index}} is no longer in the reflog`);
+    lines.splice(entry.position, 1);
+
+    if (!lines.length) {
+        await repo.refs.delete(STASH_REF, { expectedOldOid: undefined });
+        await fs.rm(reflogPath, { force: true });
+        return entry.oid;
+    }
+
+    await writeAtomic(reflogPath, lines.join('\n') + '\n');
+
+    // refs/stash must name the newest surviving entry.
+    const newest = lines[lines.length - 1].trim().split(/\s+/)[1];
+    await withLock(repo.refs.refPath(STASH_REF), async (lock) => {
+        await lock.write(`${newest}\n`);
+    });
+    repo.refs.invalidate();
+    return entry.oid;
+}
+
+/**
+ * Apply then drop.
+ * @param {Object} repo
+ * @param {Number} index
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function pop(repo, index = 0, options = {}) {
+    const result = await apply(repo, index, options);
+    await drop(repo, index);
+    return result;
+}
+
+/** Merge stash changes relative to their original HEAD, preserving later commits.
+ * Conflicting applications refuse before mutation; the stash remains available.
+ */
+async function mergeStashTrees(repo, base, current, saved) {
+    const { mergeFileContent } = require('./merge-engine');
+    const { looksBinary } = require('./attributes');
+    const result = new Map();
+    const same = (a, b) => (!a && !b) || (a && b && a.oid === b.oid && a.mode === b.mode);
+    for (const name of new Set([...base.keys(), ...current.keys(), ...saved.keys()])) {
+        const b = base.get(name), ours = current.get(name), theirs = saved.get(name);
+        let item;
+        if (same(b, theirs) || same(ours, theirs)) item = ours;
+        else if (same(b, ours)) item = theirs;
+        else {
+            if (!ours || !theirs || ours.mode !== theirs.mode || ![MODE.REGULAR, MODE.EXECUTABLE].includes(ours.mode)) {
+                throw new StashError(`stash conflicts at '${name}'; no changes applied`);
+            }
+            const bytes = await Promise.all([b ? repo.objects.readBlob(b.oid) : Buffer.alloc(0), repo.objects.readBlob(ours.oid), repo.objects.readBlob(theirs.oid)]);
+            if (bytes.some(looksBinary)) throw new StashError(`binary stash conflict at '${name}'; no changes applied`);
+            const merged = mergeFileContent(...bytes.map(value => value.toString('utf8')), name);
+            if (merged.hasConflicts) throw new StashError(`stash conflicts at '${name}'; no changes applied`);
+            item = { mode: ours.mode, oid: await repo.objects.write('blob', Buffer.from(merged.content)) };
+        }
+        if (item) result.set(name, item);
+    }
+    return result;
+}
+
+module.exports = {
+    StashError,
+    STASH_REF,
+    push,
+    list,
+    at,
+    apply,
+    pop,
+    drop
+};

package/src/utils/user-config.js

@@ -21,6 +21,10 @@
  *     ai.api_key        Anthropic API key
  *     ai.model          Model id (e.g. claude-opus-4-7, claude-haiku-4-5)
  *     api.base_url      Backend base URL (e.g. http://localhost:8000)
+ *     web.base_url      Web app (frontend) base URL (e.g. https://gent-nu2e.onrender.com)
+ *                       Used by `gent web` / `gent share`. This is a SEPARATE
+ *                       deployment from api.base_url — never derive one from
+ *                       the other.
  *     user.name         Default author name
  *     user.email        Default author email
  *
@@ -42,6 +46,7 @@ const ALLOWED_KEYS = new Set([
     'ai.api_key',
     'ai.model',
     'api.base_url',
+    'web.base_url',
     'user.name',
     'user.email',
 ]);
@@ -49,12 +54,17 @@ const ALLOWED_KEYS = new Set([
 const DEFAULTS = {
     'ai.model': 'claude-opus-4-7',
     'api.base_url': 'https://gent-api.onrender.com',
+    // The frontend has no production deployment yet; the server's own
+    // FRONTEND_URL setting defaults to the same value. Override with
+    // `gent config set web.base_url <url>` or GENT_WEB_URL.
+    'web.base_url': 'https://gent-nu2e.onrender.com',
 };
 
 const ENV_OVERRIDES = {
     'ai.api_key': 'ANTHROPIC_API_KEY',
     'ai.model': 'GENT_AI_MODEL',
     'api.base_url': 'GENT_API_URL',
+    'web.base_url': 'GENT_WEB_URL',
 };
 
 function getConfigPath() {