@fluado/enmetu 0.0.0-stage → 0.1.0

package/dist/cli/commands/statusCommand.js

@@ -0,0 +1,249 @@
+import { EXIT } from '../../contracts/exitCode.js';
+import { verifiedRefFor } from '../../core/git/enmetuRefs.js';
+import { resumeHint } from '../../core/halt/resumeHint.js';
+import { stateLiveness } from '../../core/state/stateLiveness.js';
+import { conflictGuide, pathsOnBothSides, } from '../../core/status/conflictGuide.js';
+import { orphanedCommitLines } from '../../core/status/orphanedCommits.js';
+import { statusHeadline, } from '../../core/status/statusHeadline.js';
+/** Labels padded to one column, so the values line up (design 1.18). */
+const LABEL_WIDTH = 12;
+const NO_DIVERGENCE = '-';
+/** The uncommitted line names this many paths, then "and <n> more" (design 12.2). */
+export const MAX_UNCOMMITTED_PATHS = 20;
+/**
+ * Controller:
+ * 1. locator.locate(startDir); not found or bare: exit 5.
+ * 2. Gather the facts, all local (no network, no write): state.read(),
+ *    lock.inspect(), state.read() again, liveness judged with the second
+ *    record and the holder (Decision 86); halt.read(), journal.read(),
+ *    quarantine.hasPending(); branch and upstream, divergence against
+ *    trackingSha ?? verifiedSha (Decision 66); uncommitted paths from
+ *    git.status(), which runs with GIT_OPTIONAL_LOCKS=0, so no index write
+ *    (Decision 85). While a conflict is held at HEAD, the conflict guide
+ *    (design 12.3) from merge-base and two name-only diffs, which write no
+ *    object (Decision 67). Each recorded orphaned commit asked of git
+ *    (design 14.15).
+ * 3. Print the headline, then one labelled line per fact (design 1.18, 12.2:
+ *    state after instance, uncommitted after divergence, then the pending
+ *    orphaned commits, then the guide);
+ *    halted exits 3, else 0. The exit codes answer scripts and are unchanged
+ *    (Decision 66).
+ */
+export async function statusCommand(input, deps) {
+    // --- Step 1: the repository root through git ---
+    const location = await deps.locator.locate(input.startDir);
+    if (location.kind !== 'found') {
+        const reason = location.kind === 'bare'
+            ? 'is a bare repository'
+            : 'is not inside a git work tree';
+        deps.stdout.write(line('repository', `${input.startDir} ${reason}`));
+        return { exitCode: EXIT.NOT_ELIGIBLE, report: null };
+    }
+    const sources = deps.openSources(location.paths);
+    // --- Step 2: local facts only ---
+    // The first read only orders the lock between two reads: a stop or a start
+    // between them then yields the second record, which is judged (Decision 86).
+    await sources.state.read();
+    const holder = await sources.lock.inspect();
+    const record = await sources.state.read();
+    const halt = await sources.halt.read();
+    const branch = await describeBranch(sources.git);
+    const uncommitted = await sources.git.status();
+    const orphaned = await pendingOrphans(record, sources.git);
+    const report = {
+        headline: statusHeadline({
+            halt,
+            liveness: stateLiveness(record, holder),
+            record,
+            unpushed: branch.unpushed,
+            uncommitted: uncommitted.length,
+            orphaned,
+        }),
+        repository: location.paths.root,
+        instance: describeInstance(holder),
+        state: describeState(record),
+        halt: describeHalt(halt),
+        recovery: describeRecovery((await sources.journal.read()) !== null, await sources.quarantine.hasPending()),
+        branch: branch.branch,
+        divergence: branch.divergence,
+        uncommitted: describeUncommitted(uncommitted),
+        orphaned: orphanedCommitLines(orphaned),
+        conflictGuide: await guideFor(record, halt, branch, sources.git),
+    };
+    // --- Step 3: print, the headline first, then one fact per line ---
+    deps.stdout.write([
+        `${report.headline}\n`,
+        line('repository', report.repository),
+        line('instance', report.instance),
+        line('state', report.state),
+        line('halt', report.halt),
+        line('recovery', report.recovery),
+        line('branch', report.branch),
+        line('divergence', report.divergence),
+        line('uncommitted', report.uncommitted),
+        ...report.orphaned.map((orphan) => line(orphan.label, orphan.value)),
+        ...report.conflictGuide.map((guide) => line(guide.label, guide.value)),
+    ].join(''));
+    return { exitCode: halt === null ? EXIT.OK : EXIT.HALTED, report };
+}
+function line(label, value) {
+    return `${label.padEnd(LABEL_WIDTH)}${value}\n`;
+}
+function describeInstance(holder) {
+    if (holder === null) {
+        return 'not running';
+    }
+    return `running, pid ${holder.pid} on ${holder.hostname} since ${holder.startedAt}`;
+}
+function describeState(record) {
+    if (record === null) {
+        return 'none recorded';
+    }
+    const reason = record.reason === null ? '' : ` ${record.reason}`;
+    const cycle = record.lastCycle === null
+        ? 'no cycle finished yet'
+        : `last cycle ${record.lastCycle.cycleId} ${record.lastCycle.outcome} at ${record.lastCycle.at}`;
+    return `${record.state}${reason} since ${record.since}; ${cycle}`;
+}
+function describeHalt(record) {
+    if (record === null) {
+        return 'none';
+    }
+    return `${record.code} at ${record.at} (${record.cycleId ?? '-'}): ${record.message}. ${resumeHint(record.code)}`;
+}
+function describeRecovery(journal, memento) {
+    if (journal && memento) {
+        return 'rebase journal and quarantine memento pending';
+    }
+    if (journal) {
+        return 'rebase journal pending';
+    }
+    if (memento) {
+        return 'quarantine memento pending';
+    }
+    return 'none';
+}
+/**
+ * Names the paths only; why one is uncommitted (quiet window, content guard,
+ * hook) would need every changed file read and the content rules run, and
+ * the EXCLUDED and HOOK_REJECTED log lines already say it (Decision 85).
+ */
+function describeUncommitted(entries) {
+    if (entries.length === 0) {
+        return 'none';
+    }
+    const named = entries
+        .slice(0, MAX_UNCOMMITTED_PATHS)
+        .map((entry) => entry.path)
+        .join(', ');
+    if (entries.length === 1) {
+        return `1 path: ${named}`;
+    }
+    const rest = entries.length - MAX_UNCOMMITTED_PATHS;
+    const more = rest > 0 ? ` and ${rest} more` : '';
+    return `${entries.length} paths: ${named}${more}`;
+}
+async function describeBranch(git) {
+    const { branchRef } = await git.repositoryState();
+    if (branchRef === null) {
+        return {
+            branch: 'detached HEAD',
+            divergence: NO_DIVERGENCE,
+            unpushed: { kind: 'no-upstream' },
+            upstream: null,
+        };
+    }
+    const upstream = await git.upstream(branchRef);
+    if (upstream === null) {
+        return {
+            branch: `${branchRef} has no upstream`,
+            divergence: NO_DIVERGENCE,
+            unpushed: { kind: 'no-upstream' },
+            upstream: null,
+        };
+    }
+    const branch = `${branchRef} -> ${upstream.remote} ${upstream.remoteRef}`;
+    // The tracking ref, never ls-remote: status makes no network call. A prune
+    // can remove it from a fully pushed clone; the verified ref is the base the
+    // cycle's UNPUSHED line falls back to (Decision 59), so status uses it too.
+    const trackingSha = await git.resolveCommit(upstream.trackingRef);
+    if (trackingSha !== null) {
+        const { ahead, behind } = await git.divergence(trackingSha);
+        return {
+            branch,
+            divergence: `${ahead} ahead, ${behind} behind (against the last fetched upstream)`,
+            unpushed: { kind: 'counted', ahead },
+            upstream,
+        };
+    }
+    const verifiedSha = await git.resolveCommit(verifiedRefFor(branchRef));
+    if (verifiedSha !== null) {
+        const { ahead, behind } = await git.divergence(verifiedSha);
+        return {
+            branch,
+            divergence: `${ahead} ahead, ${behind} behind (against the upstream enmetu last verified; the tracking ref is gone)`,
+            unpushed: { kind: 'counted', ahead },
+            upstream,
+        };
+    }
+    return {
+        branch,
+        divergence: 'unknown (the upstream was never fetched or verified)',
+        unpushed: { kind: 'unknown' },
+        upstream,
+    };
+}
+/**
+ * The recorded orphaned commits git still finds on no local branch (design
+ * 14.15). Asked here, at every status, not at cycle end: status is the one
+ * reader that shows them, a stopped daemon's record must lose an orphan the
+ * person picked meanwhile, and a cycle-end check would spend spawns every
+ * poll for a list nobody reads then. An orphan git can no longer resolve
+ * (gc pruned it) is gone; reading is all this does, the file keeps the entry
+ * until newer orphans push it out.
+ */
+async function pendingOrphans(record, git) {
+    const pending = [];
+    for (const orphan of record?.orphaned ?? []) {
+        if ((await git.resolveCommit(orphan.commit)) !== null &&
+            !(await git.onLocalBranch(orphan.commit, orphan.at))) {
+            pending.push(orphan);
+        }
+    }
+    return pending;
+}
+/**
+ * The guide only while the record holds a conflict, no halt marker exists and
+ * HEAD is still the conflict's head: a person who already rebased, merged or
+ * reset would otherwise be told to resolve a conflict that is gone. The paths
+ * come from merge-base and two name-only diffs, which write nothing; merge-tree
+ * --write-tree would name exactly the conflicting paths but writes objects
+ * (Decision 67). Without an upstream there is no command to give.
+ */
+async function guideFor(record, halt, branch, git) {
+    if (record === null ||
+        record.state !== 'conflict' ||
+        record.conflict === null ||
+        halt !== null ||
+        branch.upstream === null) {
+        return [];
+    }
+    const { conflict } = record;
+    if ((await git.headCommit()) !== conflict.head) {
+        return [];
+    }
+    const base = await git.mergeBase(conflict.head, conflict.upstream);
+    // Unrelated histories have no base; the guide then says none were found
+    // and names the diff a person can read instead.
+    const paths = base === null
+        ? []
+        : pathsOnBothSides(await git.changedPaths(base, conflict.head), await git.changedPaths(base, conflict.upstream));
+    return conflictGuide({
+        since: record.since,
+        conflict,
+        branchRef: branch.upstream.branchRef,
+        upstream: branch.upstream,
+        unpushed: branch.unpushed.kind === 'counted' ? branch.unpushed.ahead : null,
+        paths,
+    });
+}

package/dist/cli/exitCodes.d.ts

@@ -0,0 +1,7 @@
+import { type ExitCode } from '../contracts/exitCode.js';
+/**
+ * The one mapping from errors to exit codes: USAGE and CONFIG_* to 2, HALTED
+ * to 3, LOCK_* to 4, repository and git eligibility codes to 5, anything else
+ * (unknown values included) to 1.
+ */
+export declare function exitCodeFor(error: unknown): ExitCode;

package/dist/cli/exitCodes.js

@@ -0,0 +1,39 @@
+import { EnmetuError } from '../contracts/errors.js';
+import { EXIT } from '../contracts/exitCode.js';
+/** Every code named, so a new error code fails the type check until it is mapped. */
+const EXIT_CODE_BY_ERROR = {
+    USAGE: EXIT.USAGE,
+    CONFIG_INVALID_JSON: EXIT.USAGE,
+    CONFIG_UNKNOWN_KEY: EXIT.USAGE,
+    CONFIG_INVALID_VALUE: EXIT.USAGE,
+    HALTED: EXIT.HALTED,
+    LOCK_HELD: EXIT.LOCKED,
+    LOCK_UNREADABLE: EXIT.LOCKED,
+    GIT_NOT_FOUND: EXIT.NOT_ELIGIBLE,
+    GIT_TOO_OLD: EXIT.NOT_ELIGIBLE,
+    NOT_A_REPOSITORY: EXIT.NOT_ELIGIBLE,
+    BARE_REPOSITORY: EXIT.NOT_ELIGIBLE,
+    PATH_UNSUPPORTED: EXIT.NOT_ELIGIBLE,
+    OPERATION_IN_PROGRESS: EXIT.NOT_ELIGIBLE,
+    DETACHED_HEAD: EXIT.NOT_ELIGIBLE,
+    HEAD_UNBORN: EXIT.NOT_ELIGIBLE,
+    NO_UPSTREAM: EXIT.NOT_ELIGIBLE,
+    UPSTREAM_NOT_REMOTE: EXIT.NOT_ELIGIBLE,
+    IDENTITY_MISSING: EXIT.NOT_ELIGIBLE,
+    GIT_TIMEOUT: EXIT.FAILURE,
+    GIT_ABORTED: EXIT.FAILURE,
+    GIT_FAILED: EXIT.FAILURE,
+    GIT_INDEX_LOCKED: EXIT.FAILURE,
+    GIT_OUTPUT_UNPARSEABLE: EXIT.FAILURE,
+};
+/**
+ * The one mapping from errors to exit codes: USAGE and CONFIG_* to 2, HALTED
+ * to 3, LOCK_* to 4, repository and git eligibility codes to 5, anything else
+ * (unknown values included) to 1.
+ */
+export function exitCodeFor(error) {
+    if (error instanceof EnmetuError) {
+        return EXIT_CODE_BY_ERROR[error.code];
+    }
+    return EXIT.FAILURE;
+}

package/dist/cli/helpText.d.ts

@@ -0,0 +1 @@
+export declare const HELP_TEXT = "Usage: enmetu <command> [options]\n\nKeeps the git working tree of the current repository committed and in sync\nwith the upstream of its checked-out branch.\n\nCommands:\n  run [--repo <path>]       Start the daemon in the foreground\n  status [--repo <path>]    Print instance, halt, recovery, branch and divergence\n  resume [--repo <path>] [--accept-upstream]\n                            Clear a halt after verifying the repository\n  hook pre-commit           The pre-commit check (called by the installed hook)\n\nOptions:\n  -h, --help                Print this text\n  -v, --version             Print the version\n";

package/dist/cli/helpText.js

@@ -0,0 +1,16 @@
+export const HELP_TEXT = `Usage: enmetu <command> [options]
+
+Keeps the git working tree of the current repository committed and in sync
+with the upstream of its checked-out branch.
+
+Commands:
+  run [--repo <path>]       Start the daemon in the foreground
+  status [--repo <path>]    Print instance, halt, recovery, branch and divergence
+  resume [--repo <path>] [--accept-upstream]
+                            Clear a halt after verifying the repository
+  hook pre-commit           The pre-commit check (called by the installed hook)
+
+Options:
+  -h, --help                Print this text
+  -v, --version             Print the version
+`;

package/dist/cli/main.d.ts

@@ -0,0 +1,8 @@
+import { type ExitCode } from '../contracts/exitCode.js';
+import type { Runtime } from '../contracts/runtime.js';
+/**
+ * Entry dispatch: parseCommandLine, then the command's controller with deps
+ * from the composition root; help and version print to stdout; any error is
+ * mapped by exitCodeFor and printed to stderr in the form `enmetu: <message>`.
+ */
+export declare function main(runtime: Runtime): Promise<ExitCode>;

package/dist/cli/main.js

@@ -0,0 +1,49 @@
+import { resolve } from 'node:path';
+import { EXIT } from '../contracts/exitCode.js';
+import { errorMessage } from '../core/errors/errorMessage.js';
+import { createHookCheckDeps, createResumeDeps, createRunDeps, createStatusDeps, } from '../enmetuInstances.js';
+import { hookCommand } from './commands/hookCommand.js';
+import { resumeCommand } from './commands/resumeCommand.js';
+import { runCommand } from './commands/runCommand.js';
+import { statusCommand } from './commands/statusCommand.js';
+import { exitCodeFor } from './exitCodes.js';
+import { HELP_TEXT } from './helpText.js';
+import { parseCommandLine } from './parseArgs.js';
+/**
+ * Entry dispatch: parseCommandLine, then the command's controller with deps
+ * from the composition root; help and version print to stdout; any error is
+ * mapped by exitCodeFor and printed to stderr in the form `enmetu: <message>`.
+ */
+export async function main(runtime) {
+    try {
+        const command = parseCommandLine(runtime.argv);
+        switch (command.kind) {
+            case 'help':
+                runtime.stdout.write(HELP_TEXT);
+                return EXIT.OK;
+            case 'version':
+                runtime.stdout.write(`${runtime.version}\n`);
+                return EXIT.OK;
+            case 'run':
+                return (await runCommand({ startDir: startDirOf(command.repo, runtime) }, createRunDeps(runtime))).exitCode;
+            case 'status':
+                return (await statusCommand({ startDir: startDirOf(command.repo, runtime) }, createStatusDeps(runtime))).exitCode;
+            case 'resume':
+                return (await resumeCommand({
+                    startDir: startDirOf(command.repo, runtime),
+                    acceptUpstream: command.acceptUpstream,
+                }, createResumeDeps(runtime))).exitCode;
+            case 'hook-pre-commit':
+                // Git runs hooks from the root of the work tree being committed.
+                return (await hookCommand({ startDir: runtime.cwd }, createHookCheckDeps(runtime))).exitCode;
+        }
+    }
+    catch (error) {
+        runtime.stderr.write(`enmetu: ${errorMessage(error)}\n`);
+        return exitCodeFor(error);
+    }
+}
+/** --repo relative to the working directory, else the working directory. */
+function startDirOf(repo, runtime) {
+    return repo === null ? runtime.cwd : resolve(runtime.cwd, repo);
+}

package/dist/cli/parseArgs.d.ts

@@ -0,0 +1,19 @@
+export type ParsedCommand = {
+    readonly kind: 'run';
+    readonly repo: string | null;
+} | {
+    readonly kind: 'status';
+    readonly repo: string | null;
+} | {
+    readonly kind: 'resume';
+    readonly repo: string | null;
+    readonly acceptUpstream: boolean;
+} | {
+    readonly kind: 'hook-pre-commit';
+} | {
+    readonly kind: 'help';
+} | {
+    readonly kind: 'version';
+};
+/** node:util parseArgs with strict: true. Throws UsageError. No arguments is help. */
+export declare function parseCommandLine(argv: readonly string[]): ParsedCommand;

package/dist/cli/parseArgs.js

@@ -0,0 +1,106 @@
+import { parseArgs } from 'node:util';
+import { UsageError } from '../contracts/errors.js';
+/** node:util parseArgs with strict: true. Throws UsageError. No arguments is help. */
+export function parseCommandLine(argv) {
+    const line = parseLine(argv);
+    if (line.help) {
+        return { kind: 'help' };
+    }
+    if (line.version) {
+        return { kind: 'version' };
+    }
+    const [name, ...rest] = line.positionals;
+    if (name === undefined) {
+        if (line.repo !== null || line.acceptUpstream) {
+            throw new UsageError('missing command');
+        }
+        return { kind: 'help' };
+    }
+    switch (name) {
+        case 'run':
+        case 'status':
+            refuseExtraArguments(name, rest);
+            refuseAcceptUpstream(name, line);
+            return { kind: name, repo: line.repo };
+        case 'resume':
+            refuseExtraArguments(name, rest);
+            return {
+                kind: 'resume',
+                repo: line.repo,
+                acceptUpstream: line.acceptUpstream,
+            };
+        case 'hook':
+            return parseHook(rest, line);
+        default:
+            throw new UsageError(`unknown command '${name}'`);
+    }
+}
+function parseLine(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: [...argv],
+            strict: true,
+            allowPositionals: true,
+            options: {
+                repo: { type: 'string' },
+                'accept-upstream': { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        });
+        return {
+            positionals,
+            repo: values.repo ?? null,
+            acceptUpstream: values['accept-upstream'] ?? false,
+            help: values.help ?? false,
+            version: values.version ?? false,
+        };
+    }
+    catch (error) {
+        const message = parseArgsMessage(error);
+        if (message === null) {
+            throw error;
+        }
+        throw new UsageError(message);
+    }
+}
+function parseHook(rest, line) {
+    const [hookName, ...extra] = rest;
+    if (hookName !== 'pre-commit') {
+        throw new UsageError(hookName === undefined
+            ? "hook needs a hook name: 'enmetu hook pre-commit'"
+            : `unknown hook '${hookName}'`);
+    }
+    refuseExtraArguments('hook pre-commit', extra);
+    if (line.repo !== null) {
+        // The hook runs where git runs it, the root of the work tree being committed.
+        throw new UsageError("'hook pre-commit' takes no --repo");
+    }
+    refuseAcceptUpstream('hook pre-commit', line);
+    return { kind: 'hook-pre-commit' };
+}
+function refuseExtraArguments(command, extra) {
+    const [first] = extra;
+    if (first !== undefined) {
+        throw new UsageError(`unexpected argument '${first}' after '${command}'`);
+    }
+}
+function refuseAcceptUpstream(command, line) {
+    if (line.acceptUpstream) {
+        throw new UsageError(`--accept-upstream belongs to 'resume', not to '${command}'`);
+    }
+}
+// Structural, not instanceof: parseArgs throws a TypeError from Node's core
+// realm, which differs from the caller's realm under Jest.
+function parseArgsMessage(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        error.code.startsWith('ERR_PARSE_ARGS_') &&
+        'message' in error &&
+        typeof error.message === 'string') {
+        return error.message;
+    }
+    return null;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { main } from './cli/main.js';
+/**
+ * Entry: the only file that reads process.argv, process.env, process.cwd(),
+ * process.execPath, process.stdout and process.stderr and sets
+ * process.exitCode. It gathers them into a Runtime and calls main.
+ */
+/** package.json sits next to dist/ and src/, one level up from this file in both. */
+function packageVersion() {
+    const manifest = createRequire(import.meta.url)('../package.json');
+    if (typeof manifest === 'object' &&
+        manifest !== null &&
+        'version' in manifest &&
+        typeof manifest.version === 'string') {
+        return manifest.version;
+    }
+    return 'unknown';
+}
+const runtime = {
+    argv: process.argv.slice(2),
+    env: process.env,
+    cwd: process.cwd(),
+    execPath: process.execPath,
+    // Node makes argv[1] absolute. Should it ever be missing, the hook records
+    // an empty path, finds no CLI there and lets commits through (fail open).
+    cliPath: process.argv[1] ?? '',
+    version: packageVersion(),
+    stdout: process.stdout,
+    stderr: process.stderr,
+};
+process.exitCode = await main(runtime);

package/dist/commit/commitLocalChangesController.d.ts

@@ -0,0 +1,132 @@
+import type { StagedSelectionMode } from '../contracts/config.js';
+import type { IClock } from '../contracts/IClock.js';
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IGitCommitter, IGitHookRunner } from '../contracts/IGitCommitter.js';
+import type { IGitIndexLock } from '../contracts/IGitIndexLock.js';
+import type { IGitReader } from '../contracts/IGitReader.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { ILogger } from '../contracts/ILogger.js';
+import type { CommitMemory, WaitReason } from '../contracts/syncTypes.js';
+/** An unchanged tree a hook rejected is offered to the hooks again after this long (design 12.7). */
+export declare const HOOK_RETRY_MS = 600000;
+export interface CommitLocalChangesInput {
+    readonly cycleId: string;
+    readonly memory: CommitMemory;
+    /**
+     * The branch the cycle checked out and syncs (refs/heads/main). Under
+     * index.lock HEAD must still name it; the swap moves this ref, not HEAD,
+     * and a HEAD that then names neither it nor the commit rolls it back
+     * (design 14.3, Decision 121).
+     */
+    readonly branchRef: string;
+}
+/** git bound to the commit index (GIT_INDEX_FILE=<stateDir>/commit-index). */
+export interface CommitIndexGit {
+    /** For stageGuardedChanges: staged files and staged changes of the commit index. */
+    readonly reader: IGitReader;
+    /** Its stageAll and unstage, behind HaltGuardGitWriter. */
+    readonly writer: IGitWriter;
+    readonly committer: IGitCommitter;
+    /** <stateDir>/commit-index */
+    readonly path: string;
+}
+export interface CommitSettings {
+    readonly commitSubject: string;
+    readonly skipJsonCheck: readonly string[];
+    readonly stagedSelection: StagedSelectionMode;
+    readonly stagedSelectionMaxWaitMs: number | null;
+    readonly commitHooks: boolean;
+    /** <gitDir>/index, copied to seed the commit index with its stat data. */
+    readonly realIndex: string;
+    /** The working tree root; the stale-index repair reads a path's working-tree side (Decision 98). */
+    readonly root: string;
+}
+export interface CommitLocalChangesDeps {
+    /** The real index: HEAD, repository state, the person's staged selection, commit.gpgSign. */
+    readonly git: IGitReader;
+    /** Behind HaltGuardGitWriter; moves the synced branch by compare-and-swap. */
+    readonly writer: IGitWriter;
+    readonly commitIndex: CommitIndexGit;
+    /** Hooks on the real index: post-commit and post-index-change run after the branch moved. */
+    readonly realHooks: IGitHookRunner;
+    readonly indexLock: IGitIndexLock;
+    readonly fs: IFileSystem;
+    readonly logger: ILogger;
+    /** NullLogger from the root: the residue build must not log EXCLUDED a second time. */
+    readonly residueLogger: ILogger;
+    readonly clock: IClock;
+    readonly settings: CommitSettings;
+}
+export type CommitLocalChangesResult = {
+    readonly kind: 'nothing';
+    readonly memory: CommitMemory;
+} | {
+    readonly kind: 'committed';
+    readonly memory: CommitMemory;
+} | {
+    readonly kind: 'waiting';
+    readonly reason: WaitReason;
+    readonly memory: CommitMemory;
+}
+/**
+ * index.lock held by another process, the real index changed since the
+ * build, a concurrent commit moved the branch first, or HEAD left the
+ * branch: nothing committed.
+ */
+ | {
+    readonly kind: 'busy';
+    readonly memory: CommitMemory;
+} | {
+    readonly kind: 'paused';
+    readonly reason: 'FOREIGN_OPERATION';
+    readonly memory: CommitMemory;
+};
+/** The step with its deps bound, the type of SyncCycleDeps.commit; the composition root builds it. */
+export type CommitLocalChanges = (input: CommitLocalChangesInput) => Promise<CommitLocalChangesResult>;
+/**
+ * Controller: enmetu's commit without touching the person's index (design
+ * 12.7, Decisions 72 to 74, 80, 81).
+ *
+ * 1. before = fs.identity(realIndex), read first, so the staged-selection
+ *    verdict below still holds when the identity is unchanged under the lock.
+ *    Staged selection: git.hasStagedChanges() on the real index. When it
+ *    differs and memory.lastMove is set, repairStaleIndexController first
+ *    (Decision 98): moved, repaired or reverted (Decision 108) forgets lastMove; repaired reads
+ *    before and the verdict again, so a stale index is never taken for a
+ *    person's selection. "wait"
+ *    without a reached cap returns waiting PARTIAL_SELECTION_STAGED; a reached
+ *    cap logs SELECTION_WAIT_ENDED and goes on; "commit" goes on.
+ * 2. Build: parent = git.headCommit(); fs.copy(realIndex, commit index);
+ *    committer.seedFrom(parent); stageGuardedChanges on the commit index.
+ *    Nothing staged returns nothing.
+ * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing;
+ *    equal to memory.rejection.tree within HOOK_RETRY_MS returns waiting
+ *    COMMIT_HOOK_REJECTED without running a hook.
+ * 4. commitHooks: pre-commit on the commit index (rejected, timed out or
+ *    killed: HOOK_REJECTED, waiting, rejection remembered); then re-stage and
+ *    write the tree again, so a formatter's rewrite is in this commit. The
+ *    message is commitSubject plus a newline, with or without hooks; the
+ *    message hooks do not run (Decision 80). The re-stage logs through
+ *    residueLogger: its EXCLUDED lines repeat the first build's.
+ * 5. commit = committer.commitTree({ tree, parent, message, sign: gitBoolean(commit.gpgSign) }).
+ * 6. Critical section: indexLock.acquire(commit) (false: busy);
+ *    6.1 repositoryState() with an operation: release, paused; HEAD naming
+ *    anything but input.branchRef: release, busy (Decision 121);
+ *    6.2 fs.identity(realIndex) differing from before: release, busy;
+ *    6.3 indexLock.install(commit index);
+ *    6.4 writer.updateRef(input.branchRef, commit, parent) (a mismatch:
+ *    restore, release, COMMIT_DISCARDED, busy; any other throw: restore,
+ *    release, rethrow);
+ *    6.4b HEAD naming input.branchRef, or else resolving to the commit, keeps
+ *    it; otherwise writer.updateRef(input.branchRef, parent, commit),
+ *    restore, COMMIT_DISCARDED, busy (a roll-back failing with GIT_FAILED
+ *    restores and returns busy the same way; any other throw restores and
+ *    rethrows); release.
+ * 7. COMMITTED; with hooks: when realHooks.hookExists says post-index-change
+ *    or post-commit exists, a build with residueLogger before the hooks;
+ *    post-index-change "0 0" and post-commit on the real index (git ignores
+ *    both exit codes, so does enmetu); then, only when such a hook exists and
+ *    the build before found nothing uncommitted, a fresh build whose tree,
+ *    when it differs from the commit's, becomes residueTree (Decision 90).
+ */
+export declare function commitLocalChangesController(input: CommitLocalChangesInput, deps: CommitLocalChangesDeps): Promise<CommitLocalChangesResult>;