@fluado/enmetu 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yves Van Goethem, fluado UG (haftungsbeschränkt)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="logo.svg" width="80" height="80" alt="enmetu">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">enmetu</h1>
+
+Commits and syncs a git working tree automatically. Run it inside a repository: it commits after you stop editing, rebases onto the upstream, pushes, and pulls new commits.
+
+## Why enmetu
+
+Most auto-commit tools commit and push. enmetu also handles what goes wrong:
+
+- **Conflicts.** A pull that conflicts is undone and held. Your commits stay local, and enmetu retries when either side changes. It never commits conflict markers and never force-pushes.
+- **No stash.** A file it won't commit (conflict markers, invalid JSON) stays on disk and doesn't block the rest of the sync. Its pre-commit hook applies the same check to your own commits.
+- **Plain git.** You and your agents keep using git. enmetu commits through its own index, waits up to 5 minutes on a partial staging, and pauses during your merge or rebase.
+- **Halts.** A rewritten upstream, or a state it cannot verify, halts it. The halt survives restarts until you run `enmetu resume`.
+- **Status.** `enmetu status` says whether your work is committed and pushed, and during a conflict prints the commands to end it.
+- **Dependencies.** None besides git. Runs under Node or Bun, as a command or as a library.
+- **Tests.** Real git against [28 conflict shapes](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/conflictMatrix.scenario.integration.test.ts) (renames against deletions, binary files, case-only renames, line endings, a merge in progress), [several clones converging on one history](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/convergence.scenario.integration.test.ts), and [a stress test](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/concurrencyStress.scenario.integration.test.ts) where a scripted person runs git next to enmetu as fast as it can, with every write checked against the final history.
+
+## Prerequisites
+
+- Node 24+ or Bun 1.3.6+
+- git 2.38+
+- A checked-out branch with an upstream, at least one commit, and a committer identity
+
+## Install
+
+### Node
+
+Inside a repository:
+
+```sh
+npx @fluado/enmetu run
+```
+
+As a project dependency: `npm install -D @fluado/enmetu`, then `npx enmetu run`.
+
+### Bun
+
+Inside a repository:
+
+```sh
+bunx --bun @fluado/enmetu run
+```
+
+As a project dependency: `bun add -d @fluado/enmetu`, then `bunx --bun enmetu run`.
+
+Keep `--bun`: without it, `bunx` runs enmetu with Node when Node is installed.
+
+### Pinning
+
+Add the version for repeatable runs: `@fluado/enmetu@0.2.0`.
+
+## Commands
+
+```
+enmetu run [--repo <path>]                          run in the foreground
+enmetu status [--repo <path>]                       show whether your work is committed and pushed
+enmetu resume [--repo <path>] [--accept-upstream]   clear a halt
+enmetu hook pre-commit                              run the pre-commit check
+enmetu --help | --version
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | error, or the hook refused the commit |
+| 2 | bad arguments or invalid config |
+| 3 | halted, or resume refused |
+| 4 | another enmetu runs on this worktree |
+| 5 | repository not usable: bare, detached HEAD, no upstream, no commit, git too old, operation in progress |
+| 130 | second Ctrl-C |
+
+## Library
+
+```js
+import { startEnmetu, readEnmetuState } from '@fluado/enmetu'
+
+const enmetu = startEnmetu({ repo: '.' })
+const { liveness, record } = await readEnmetuState('.')
+const exitCode = await enmetu.stop()
+```
+
+## Configuration
+
+`enmetu.config.json` at the repository root, optional:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `quietMs` | `5000` | wait after the last change before committing |
+| `maxDelayMs` | `60000` | maximum delay while changes keep coming |
+| `pollMs` | `5000` | remote check interval |
+| `commitSubject` | `"enmetu: local changes"` | commit message |
+| `installHook` | `true` | install the pre-commit hook |
+| `skipJsonCheck` | `[]` | files exempt from the JSON check, such as `tsconfig.json` |
+| `gitTimeoutMs` | `120000` | timeout per git command |
+| `stateHistory` | `20` | state changes kept in the state file (0 to 100) |
+| `partialStagingWaitMs` | `300000` | with a partial staging: commit everything after this long; `0` at once |
+| `commitHooks` | `true` | run your commit hooks on enmetu's commits |
+| `hookTimeoutMs` | `600000` | timeout per hook |
+
+Unknown settings are logged and ignored.
+
+## Status
+
+```
+safe: pushed 3f2a9c1, 0 unpushed
+repository  /work/notes
+instance    running, pid 4242 on devbox.example.com since 2026-11-01T12:00:00.000Z
+state       synced since 2026-11-01T12:00:05.000Z; last cycle c3 synced at 2026-11-01T12:01:10.000Z
+halt        none
+recovery    none
+branch      refs/heads/main -> origin refs/heads/main
+divergence  0 ahead, 0 behind (against the last fetched upstream)
+uncommitted none
+```
+
+| First word | Meaning |
+|---|---|
+| `safe` | committed and pushed |
+| `pending` | uncommitted changes |
+| `syncing` | unpushed commits |
+| `waiting` | partial staging, or a hook rejected the commit |
+| `attention` | conflict, push failure, orphaned commit, or failed cycle |
+| `paused` | your git operation in progress, detached HEAD, or no upstream |
+| `offline` | remote unreachable |
+| `busy` | another git command holds the repository |
+| `halted` | fix the cause, then `enmetu resume` |
+| `not running` | stopped, crashed, or never started |
+
+## Logs
+
+stderr, one line per event:
+
+```
+2026-11-01T12:00:05.120Z INFO  c2  COMMITTED local changes
+2026-11-01T12:00:05.122Z WARN  c2  EXCLUDED state.json: CONFLICT_MARKERS (opening and closing marker lines)
+2026-11-01T12:01:10.341Z WARN  c15 UNPUSHED 2 local commits not on origin refs/heads/main
+```
+
+| Code | Meaning |
+|---|---|
+| `EXCLUDED` | file not committed: conflict markers or invalid JSON |
+| `CONFLICT`, `UNPUSHED` | local commits not pushed |
+| `WAITING`, `PAUSED`, `OFFLINE` | sync on hold |
+| `HALTED` | see `enmetu status` |
+| `COMMIT_ORPHANED`, `STAGED_RESET`, `STAGED_REVERT`, `QUARANTINE_KEPT` | see Known limitations |
+
+## State file
+
+`.git/enmetu/state.json`, one line of JSON:
+
+| Field | Meaning |
+|---|---|
+| `state` | `starting`, `synced`, `waiting`, `conflict`, `paused`, `busy`, `offline`, `push-failed`, `halted`, `stopped` |
+| `reason` | code for `paused`, `waiting` and `halted` |
+| `message` | summary |
+| `since` | time of the last state change |
+| `pushed` | last commit verified on the upstream |
+| `unpushed` | local commits not on the upstream |
+| `lastCycle` | id, outcome and time of the last cycle |
+| `conflict` | conflicting commits |
+| `history` | recent state changes |
+| `orphaned` | commits left on no branch |
+| `instance`, `version` | writer process, format version |
+
+Stale after a crash; use `enmetu status` to check whether enmetu runs.
+
+## Pre-commit
+
+Installs `.git/hooks/pre-commit`, which refuses commits with conflict markers or invalid JSON. Bypass with `git commit --no-verify`.
+
+Skipped when `core.hooksPath` is set or a `pre-commit` hook exists. Add this to your hook instead:
+
+```sh
+if command -v enmetu >/dev/null 2>&1; then enmetu hook pre-commit || exit 1; else echo "enmetu: pre-commit check skipped (enmetu not on PATH)" >&2; fi
+```
+
+## Known limitations
+
+- One repository per process. No system service, no notifications.
+- A partial staging pauses sync for up to `partialStagingWaitMs` (5 minutes by default), then enmetu commits everything. A case-only rename staged with `git mv` pauses it until you commit it.
+- `commit-msg` and `prepare-commit-msg` hooks don't run on enmetu's commits.
+- Under Bun without file-watching permission, enmetu commits on its poll interval.
+- A save during enmetu's pull can be overwritten by git without notice.
+
+Overlapping git commands:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `cannot lock ref 'HEAD'` | raced enmetu's commit | after `INDEX_REPAIRED` in the log: `git reset --merge`, retry. If `not uptodate`: `git merge --quit`, `git reset` |
+| `STAGED_RESET` | staged during enmetu's rebase | command in the log line |
+| `QUARANTINE_KEPT` | your edit collided with a version enmetu held aside | command in the log line |
+| `COMMIT_ORPHANED` | committed during enmetu's pull | `git cherry-pick -x` command in `enmetu status` |
+| `STAGED_REVERT` | a refused `git merge` restored old content | `git restore` command in the log line |
+| `could not write index` on a refused merge | git stashed your edits | `git fsck --no-reflogs --unreachable`, then `git stash apply <id>` |
+| `git rebase` fails, no rebase in progress | started together with enmetu's | `git rebase --quit` if needed, `git reset --merge`, `git checkout <branch>`, retry |
+
+## Contributing
+
+We built enmetu for ourselves. We use it every day at [fluado](https://fluado.com) and we're sharing it because it might be useful to others.
+
+This is not a community project. We don't have the bandwidth to review PRs, triage issues, or maintain a roadmap for external contributors. If you open an issue with a good idea, we might pick it up when it aligns with what we need. No promises.
+
+Fork it, break it, make it yours. Have fun.
+
+## Licence
+
+MIT, Copyright (c) 2026 Yves Van Goethem, fluado UG (haftungsbeschränkt). See `LICENSE`.

package/dist/adapters/clock/systemClockAdapter.d.ts

@@ -0,0 +1,6 @@
+import type { IClock, TimerHandle } from '../../contracts/IClock.js';
+/** Adapter: Date.now and setTimeout to IClock; the only file touching them. */
+export declare class SystemClockAdapter implements IClock {
+    now(): number;
+    after(ms: number, callback: () => void): TimerHandle;
+}

package/dist/adapters/clock/systemClockAdapter.js

@@ -0,0 +1,12 @@
+/** Adapter: Date.now and setTimeout to IClock; the only file touching them. */
+export class SystemClockAdapter {
+    now() {
+        return Date.now();
+    }
+    after(ms, callback) {
+        // Not unref'd: in poll-only mode (watcher failed) the pending timer is the
+        // only handle that keeps the daemon's event loop alive.
+        const timer = setTimeout(callback, ms);
+        return { cancel: () => clearTimeout(timer) };
+    }
+}

package/dist/adapters/fs/nodeFileSystemAdapter.d.ts

@@ -0,0 +1,18 @@
+import type { FileFacts, IFileSystem, WriteOptions } from '../../contracts/IFileSystem.js';
+/** Adapter: node:fs/promises to IFileSystem; the only file importing it. */
+export declare class NodeFileSystemAdapter implements IFileSystem {
+    readText(path: string): Promise<string | null>;
+    writeAtomic(path: string, content: string | Buffer, options: WriteOptions): Promise<void>;
+    createExclusive(path: string, content: string): Promise<boolean>;
+    rename(from: string, to: string): Promise<boolean>;
+    remove(path: string): Promise<void>;
+    facts(path: string): Promise<FileFacts | null>;
+    /** copyFile (COPYFILE_FICLONE where offered), then the source's time rounded down to the second; false when the source is absent (design 12.7). */
+    copy(from: string, to: string): Promise<boolean>;
+    /** stat with bigint times: `${dev}:${ino}:${size}:${mtimeNs}:${ctimeNs}`; null when absent (design 12.7). */
+    identity(path: string): Promise<string | null>;
+    /** link(2); false when the source is absent; EEXIST propagates (design 12.7). */
+    link(existing: string, target: string): Promise<boolean>;
+    /** stat's device of both paths, compared (design 13.11, Decision 117). */
+    sameFileSystem(left: string, right: string): Promise<boolean>;
+}

package/dist/adapters/fs/nodeFileSystemAdapter.js

@@ -0,0 +1,230 @@
+import { randomBytes } from 'node:crypto';
+import { constants, copyFile, link, lstat, mkdir, open, readFile, rename, stat, unlink, utimes, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+// The umask applies to these, the same way it does when git checks a file out.
+const FILE_MODE = 0o666;
+const EXECUTABLE_MODE = 0o777;
+/** Adapter: node:fs/promises to IFileSystem; the only file importing it. */
+export class NodeFileSystemAdapter {
+    async readText(path) {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (isAbsent(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async writeAtomic(path, content, options) {
+        const targetDir = dirname(path);
+        await mkdir(targetDir, { recursive: true });
+        await mkdir(options.tempDir, { recursive: true });
+        const mode = options.executable ? EXECUTABLE_MODE : FILE_MODE;
+        try {
+            await writeThenRename(options.tempDir, path, content, mode);
+        }
+        catch (error) {
+            // rename(2) cannot cross file systems; next to the target it always can.
+            if (errorCode(error) !== 'EXDEV') {
+                throw error;
+            }
+            await writeThenRename(targetDir, path, content, mode);
+        }
+    }
+    async createExclusive(path, content) {
+        const targetDir = dirname(path);
+        await mkdir(targetDir, { recursive: true });
+        // link(2) publishes the complete file in one step and fails on an existing
+        // target, so a reader never sees a half-written lock; it needs the temp
+        // file on the target's file system.
+        const temp = await writeTempFile(targetDir, path, content, FILE_MODE);
+        try {
+            await link(temp, path);
+            return true;
+        }
+        catch (error) {
+            if (errorCode(error) === 'EEXIST') {
+                return false;
+            }
+            throw error;
+        }
+        finally {
+            await removeIfPresent(temp);
+        }
+    }
+    async rename(from, to) {
+        try {
+            await rename(from, to);
+            return true;
+        }
+        catch (error) {
+            // ENOENT also means a missing directory of the target; only an absent
+            // source is the documented false.
+            if (!isAbsent(error)) {
+                throw error;
+            }
+            if ((await this.facts(from)) === null) {
+                return false;
+            }
+            // The source exists, so the target's directory is missing (the
+            // quarantine's temp directory before its first write); created only
+            // then, so an absent source creates nothing.
+            await mkdir(dirname(to), { recursive: true });
+        }
+        try {
+            await rename(from, to);
+            return true;
+        }
+        catch (error) {
+            if (isAbsent(error) && (await this.facts(from)) === null) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async remove(path) {
+        await removeIfPresent(path);
+    }
+    async facts(path) {
+        try {
+            const stats = await lstat(path);
+            if (stats.isSymbolicLink()) {
+                return { kind: 'symlink', executable: false };
+            }
+            if (stats.isFile()) {
+                // git decides a file is executable by the owner's execute bit alone.
+                return { kind: 'file', executable: (stats.mode & 0o100) !== 0 };
+            }
+            if (stats.isDirectory()) {
+                return { kind: 'directory', executable: false };
+            }
+            return { kind: 'other', executable: false };
+        }
+        catch (error) {
+            if (isAbsent(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /** copyFile (COPYFILE_FICLONE where offered), then the source's time rounded down to the second; false when the source is absent (design 12.7). */
+    async copy(from, to) {
+        // Read before the copy: a source replaced in between gives newer bytes an
+        // older time, which only makes git re-check more entries, never fewer.
+        let source;
+        try {
+            source = await stat(from);
+        }
+        catch (error) {
+            if (isAbsent(error)) {
+                return false;
+            }
+            throw error;
+        }
+        try {
+            await copyFile(from, to, constants.COPYFILE_FICLONE);
+        }
+        catch (error) {
+            if (!isAbsent(error)) {
+                throw error;
+            }
+            if ((await this.facts(from)) === null) {
+                return false;
+            }
+            // The source exists, so the target's directory is missing (the state
+            // directory before the first write); created only then, so an absent
+            // source creates nothing.
+            await mkdir(dirname(to), { recursive: true });
+            await copyFile(from, to, constants.COPYFILE_FICLONE);
+        }
+        await utimes(to, source.atime, Math.floor(source.mtimeMs / 1000));
+        return true;
+    }
+    /** stat with bigint times: `${dev}:${ino}:${size}:${mtimeNs}:${ctimeNs}`; null when absent (design 12.7). */
+    async identity(path) {
+        try {
+            const stats = await stat(path, { bigint: true });
+            return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
+        }
+        catch (error) {
+            if (isAbsent(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /** link(2); false when the source is absent; EEXIST propagates (design 12.7). */
+    async link(existing, target) {
+        try {
+            await link(existing, target);
+            return true;
+        }
+        catch (error) {
+            if (isAbsent(error) && (await this.facts(existing)) === null) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /** stat's device of both paths, compared (design 13.11, Decision 117). */
+    async sameFileSystem(left, right) {
+        const [a, b] = await Promise.all([
+            stat(left, { bigint: true }),
+            stat(right, { bigint: true }),
+        ]);
+        return a.dev === b.dev;
+    }
+}
+async function writeThenRename(tempDir, path, content, mode) {
+    const temp = await writeTempFile(tempDir, path, content, mode);
+    try {
+        await rename(temp, path);
+    }
+    catch (error) {
+        await removeIfPresent(temp);
+        throw error;
+    }
+}
+/** Writes and flushes a uniquely named temp file; removes it again on failure. */
+async function writeTempFile(dir, path, content, mode) {
+    const temp = join(dir, `.${basename(path)}.${randomBytes(6).toString('hex')}.tmp`);
+    const handle = await open(temp, 'wx', mode);
+    try {
+        await handle.writeFile(content);
+        // Without the flush a crash after the rename can leave the target empty
+        // on file systems that persist the rename before the data.
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await removeIfPresent(temp);
+        throw error;
+    }
+    await handle.close();
+    return temp;
+}
+async function removeIfPresent(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (!isAbsent(error)) {
+            throw error;
+        }
+    }
+}
+// ENOTDIR: a component of the path is a file, so the path cannot exist.
+function isAbsent(error) {
+    const code = errorCode(error);
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+// Not instanceof Error: an error from Node's core can come from another realm
+// (Jest's test context), where instanceof is false.
+function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return typeof error.code === 'string' ? error.code : undefined;
+    }
+    return undefined;
+}

package/dist/adapters/git/gitFacade.d.ts

@@ -0,0 +1,148 @@
+import type { Divergence, FetchResult, HeadMove, PushResult, RebaseResult, RebaseStart, RemoteHead, RepositoryState, StagedFile, StageResult, StatusEntry, Upstream } from '../../contracts/gitTypes.js';
+import type { IFileSystem } from '../../contracts/IFileSystem.js';
+import type { CommitHookName, CommitTreeInput, HookRun, IGitCommitter } from '../../contracts/IGitCommitter.js';
+import type { IGitReader } from '../../contracts/IGitReader.js';
+import type { IGitRunner } from '../../contracts/IGitRunner.js';
+import type { IGitWriter } from '../../contracts/IGitWriter.js';
+/** At most this much blob content is requested from one `git cat-file --batch` call. */
+export declare const GIT_BATCH_CHUNK_BYTES = 67108864;
+/** A hook's stdout and stderr beyond this are dropped, never a failure (design 12.7, Decision 83). */
+export declare const HOOK_OUTPUT_CAP_BYTES = 65536;
+/**
+ * Facade: typed questions and commands over the git CLI, with exactly the
+ * argv and interpretations of design section 1.3. gitDir locates the state
+ * files repositoryState and the rebase readers check.
+ */
+export declare class GitFacade implements IGitReader, IGitWriter, IGitCommitter {
+    private readonly runner;
+    private readonly fs;
+    private readonly gitDir;
+    /** A repository hook's own budget (hookTimeoutMs); only runHook uses it (design 12.7, Decision 83). */
+    private readonly hookTimeoutMs?;
+    /** Aborted by a stop request: a running hook is ended, which is a rejection (Decision 92); only runHook uses it. */
+    private readonly hookAbort?;
+    constructor(runner: IGitRunner, fs: IFileSystem, gitDir: string, 
+    /** A repository hook's own budget (hookTimeoutMs); only runHook uses it (design 12.7, Decision 83). */
+    hookTimeoutMs?: number | undefined, 
+    /** Aborted by a stop request: a running hook is ended, which is a rejection (Decision 92); only runHook uses it. */
+    hookAbort?: AbortSignal | undefined);
+    repositoryState(): Promise<RepositoryState>;
+    headCommit(): Promise<string | null>;
+    hasCommitterIdentity(): Promise<boolean>;
+    upstream(branchRef: string): Promise<Upstream | null>;
+    status(paths?: readonly string[] | undefined): Promise<readonly StatusEntry[]>;
+    stagedFiles(maxBytes: number): AsyncIterable<StagedFile>;
+    hasStagedChanges(): Promise<boolean>;
+    /** git diff --cached --name-only -z --no-renames --ignore-submodules=dirty (Decision 98). */
+    stagedPaths(): Promise<readonly string[]>;
+    remoteHead(remote: string, remoteRef: string): Promise<RemoteHead>;
+    resolveCommit(ref: string): Promise<string | null>;
+    isAncestor(ancestor: string, descendant: string): Promise<boolean>;
+    divergence(upstreamSha: string): Promise<Divergence>;
+    hasUnmergedPaths(): Promise<boolean>;
+    rebaseOrigHead(): Promise<string | null>;
+    rebaseOnto(): Promise<string | null>;
+    /**
+     * The branch a rebase in progress returns to: rebase-merge/head-name, else
+     * rebase-apply/head-name (design 14.4). git writes `detached HEAD` there for
+     * a rebase that started without a branch.
+     */
+    rebaseHeadName(): Promise<string | null>;
+    /**
+     * git reflog exists HEAD, then git log -g -1 --format=%gs
+     * --grep-reflog=" (start): " HEAD (design 13.2, Decision 104). Without a
+     * reflog `git log -g` prints nothing with exit 0, exactly like a reflog
+     * without a start entry, so the first call keeps the two apart.
+     */
+    rebaseStart(): Promise<RebaseStart>;
+    /**
+     * git log -g -n HEAD_MOVE_SCAN --format="%H %gs" HEAD, newest first (design
+     * 14.14). Without a reflog git prints nothing with exit 0, which is also
+     * what a reflog holding no entry of the rebase's yields: null either way.
+     */
+    headMovedSince(reflogAction: string): Promise<HeadMove | null>;
+    commitSubject(commit: string): Promise<string>;
+    /**
+     * Two reads, the cheap one first (design 14.15). --since bounds the log's
+     * walk to commits made after enmetu named the orphan (in whole seconds, a
+     * second early, since git's committer dates have no fraction); a time that
+     * does not parse walks every branch.
+     */
+    onLocalBranch(commit: string, since: string): Promise<boolean>;
+    readBlob(blobId: string): Promise<Buffer>;
+    hashFile(path: string): Promise<string>;
+    worktreeBlobId(path: string): Promise<string>;
+    entryBlobId(path: string, commit: string | null): Promise<string | null>;
+    /** git merge-file -p: exit 0 is clean; a conflict count or an error (binary input) is null. */
+    mergeFile(current: string, base: string, other: string): Promise<Buffer | null>;
+    /** git merge-base <left> <right>: exit 1 is null (design 12.3). */
+    mergeBase(left: string, right: string): Promise<string | null>;
+    /** git diff --name-only -z --no-renames <from> <to> (design 12.3). */
+    changedPaths(from: string, to: string): Promise<readonly string[]>;
+    /**
+     * git -c core.hooksPath=/dev/null read-tree --reset <commit> (design 12.7):
+     * -m's one-tree merge, which keeps the stat data of matching entries, except
+     * that unmerged entries a copied index carries (a conflicted stash pop, a
+     * person's merge) are discarded instead of refused (measured with git 2.52:
+     * -m exits 128 with "You need to resolve your current index first").
+     */
+    seedFrom(commit: string): Promise<void>;
+    /** git -c core.hooksPath=/dev/null write-tree (design 12.7). */
+    writeTree(): Promise<string>;
+    /** git commit-tree <tree> -p <parent> -S|--no-gpg-sign -F - (design 12.7). */
+    commitTree(input: CommitTreeInput): Promise<string>;
+    hookExists(name: CommitHookName): Promise<boolean>;
+    /**
+     * git hook run --ignore-missing <name> [-- <args>] with the runner options
+     * { timeoutMs: hookTimeoutMs, outputCapBytes: HOOK_OUTPUT_CAP_BYTES }
+     * (design 12.7, Decision 83): exit 0 passed; any other exit rejected with
+     * stderr; GIT_TIMEOUT rejected with 'timed out after <n> ms'; GIT_FAILED
+     * without an exit code (ended by a signal) rejected with the error's
+     * message. Throws only GIT_NOT_FOUND.
+     */
+    runHook(name: CommitHookName, args: readonly string[]): Promise<HookRun>;
+    configValue(key: string): Promise<string | null>;
+    stageAll(): Promise<StageResult>;
+    unstage(paths: readonly string[]): Promise<void>;
+    fetch(remote: string, remoteRef: string, intoRef: string): Promise<FetchResult>;
+    updateRef(ref: string, newSha: string, oldSha: string | null): Promise<void>;
+    /**
+     * reflogAction is the attempt's token: git writes it into HEAD's reflog
+     * with the rebase's checkout, which rebaseStart reads back (Decision 104).
+     */
+    rebase(ontoSha: string, reflogAction: string): Promise<RebaseResult>;
+    abortRebase(): Promise<void>;
+    /**
+     * git rebase --quit, then git switch -q --discard-changes <name>, both
+     * hookless (design 14.4, Decision 122). Neither exit code nor an index.lock
+     * message is interpreted: the caller verifies HEAD, the branch and the tip.
+     */
+    endRebaseAtBranch(branchRef: string): Promise<void>;
+    push(remote: string, sha: string, remoteRef: string): Promise<PushResult>;
+    storeBlob(path: string): Promise<string>;
+    restoreFromIndex(paths: readonly string[]): Promise<void>;
+    /** Runs git and turns an index.lock collision into GIT_INDEX_LOCKED; every other exit code is the caller's to read. */
+    private git;
+    /**
+     * Runs a command that talks to the remote. A timeout there is the network or
+     * a credential prompt (ssh connect, passphrase, pinentry), so it comes back as
+     * a value the cycle reports (OFFLINE, or PUSH_FAILED with UNPUSHED, D2),
+     * never an error that ends the cycle in CYCLE_FAILED.
+     */
+    private remoteGit;
+    /** Runs git and expects exit code 0. */
+    private gitOk;
+    private verifyCommit;
+    private exists;
+    private rebaseStateFile;
+    /** The staged files in diff order, with the size of each blob whose content will be read. */
+    private stagedBlobs;
+    /** Sizes in request order; the blob ids of a staged diff must all exist. */
+    private blobSizes;
+    /**
+     * Reads the readable blobs from `start` on, in diff order, until the next
+     * one would push the chunk past GIT_BATCH_CHUNK_BYTES; the first blob is
+     * always taken, so a blob larger than a chunk is read alone.
+     */
+    private readChunk;
+}