@fluado/enmetu 0.0.0-stage → 0.1.0

package/dist/library/readStateController.js

@@ -0,0 +1,32 @@
+import { PreflightError } from '../contracts/errors.js';
+import { stateLiveness } from '../core/state/stateLiveness.js';
+/**
+ * Controller:
+ * 1. locator.locate(startDir); not found throws PreflightError
+ *    NOT_A_REPOSITORY, bare throws BARE_REPOSITORY.
+ * 2. state.read(), lock.inspect(), state.read() again: a daemon that writes
+ *    stopped and releases between the first read and the inspect would
+ *    otherwise look crashed; the second record is judged with the holder
+ *    (Decision 86).
+ * 3. { liveness: stateLiveness(second record, holder), record: second record }.
+ * Reads only: no git command beyond the locator, no network.
+ */
+export async function readStateController(input, deps) {
+    // --- Step 1: the repository root through git (D9) ---
+    const location = await deps.locator.locate(input.startDir);
+    if (location.kind === 'not-a-repository') {
+        throw new PreflightError(`${input.startDir} is not inside a git work tree`, 'NOT_A_REPOSITORY');
+    }
+    if (location.kind === 'bare') {
+        throw new PreflightError(`${input.startDir} is a bare repository; enmetu needs a work tree`, 'BARE_REPOSITORY');
+    }
+    const { state, lock } = deps.openSources(location.paths);
+    // --- Step 2: state, lock, state again (Decision 86) ---
+    // The first read only orders the inspect after any write already under
+    // way; the second record is the one judged.
+    await state.read();
+    const holder = await lock.inspect();
+    const record = await state.read();
+    // --- Step 3: liveness of the second record ---
+    return { liveness: stateLiveness(record, holder), record };
+}

package/dist/library/requestedStopProcessHost.d.ts

@@ -0,0 +1,28 @@
+import type { IProcessHost, StopSignal } from '../contracts/IProcessHost.js';
+type StopHandler = (signal: StopSignal) => void;
+/**
+ * Decorator over IProcessHost for enmetu inside a host program (design
+ * 12.5): pid, hostname and isAlive come from the wrapped host; stop signals
+ * come from requestStop() instead of the operating system, so the library
+ * installs no signal handler in the host process and never exits it.
+ * requestStop() calls each subscribed handler once with 'SIGTERM' (later calls
+ * do nothing, so the daemon's second-signal path is unreachable). The request
+ * is latched: a handler subscribed after a stop was requested is called at once
+ * from onStopSignal, so a stop() during the daemon's startup (before its step
+ * 7) is never lost; the scheduler already ends a run whose stop came before it
+ * started (Decision 87). exitNow() throws instead of exiting.
+ */
+export declare class RequestedStopProcessHost implements IProcessHost {
+    private readonly inner;
+    private readonly handlers;
+    private stopRequested;
+    constructor(inner: IProcessHost);
+    get pid(): number;
+    get hostname(): string;
+    isAlive(pid: number): boolean;
+    onStopSignal(handler: StopHandler): () => void;
+    exitNow(code: number): never;
+    /** Asks the daemon to stop after the running cycle. */
+    requestStop(): void;
+}
+export {};

package/dist/library/requestedStopProcessHost.js

@@ -0,0 +1,58 @@
+/** The signal the CLI's first stop would carry; the daemon treats it like a first SIGTERM. */
+const REQUESTED_SIGNAL = 'SIGTERM';
+/**
+ * Decorator over IProcessHost for enmetu inside a host program (design
+ * 12.5): pid, hostname and isAlive come from the wrapped host; stop signals
+ * come from requestStop() instead of the operating system, so the library
+ * installs no signal handler in the host process and never exits it.
+ * requestStop() calls each subscribed handler once with 'SIGTERM' (later calls
+ * do nothing, so the daemon's second-signal path is unreachable). The request
+ * is latched: a handler subscribed after a stop was requested is called at once
+ * from onStopSignal, so a stop() during the daemon's startup (before its step
+ * 7) is never lost; the scheduler already ends a run whose stop came before it
+ * started (Decision 87). exitNow() throws instead of exiting.
+ */
+export class RequestedStopProcessHost {
+    inner;
+    handlers = new Set();
+    stopRequested = false;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    get pid() {
+        return this.inner.pid;
+    }
+    get hostname() {
+        return this.inner.hostname;
+    }
+    isAlive(pid) {
+        return this.inner.isAlive(pid);
+    }
+    onStopSignal(handler) {
+        if (this.stopRequested) {
+            // Delivered now and never stored: the request is spent for this handler,
+            // and a stored handler could only receive a second, forbidden call.
+            handler(REQUESTED_SIGNAL);
+            return () => { };
+        }
+        this.handlers.add(handler);
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    exitNow(code) {
+        throw new Error(`enmetu inside a host program never exits the process (exit code ${code} requested)`);
+    }
+    /** Asks the daemon to stop after the running cycle. */
+    requestStop() {
+        if (this.stopRequested) {
+            return;
+        }
+        this.stopRequested = true;
+        const subscribed = [...this.handlers];
+        this.handlers.clear();
+        for (const handler of subscribed) {
+            handler(REQUESTED_SIGNAL);
+        }
+    }
+}

package/dist/lock/instanceLock.d.ts

@@ -0,0 +1,26 @@
+import type { IClock } from '../contracts/IClock.js';
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IInstanceLock, LockAcquisition, LockHolder } from '../contracts/IInstanceLock.js';
+import type { IProcessHost } from '../contracts/IProcessHost.js';
+export declare const LOCK_FILE_NAME = "instance.lock";
+/**
+ * Service: <stateDir>/instance.lock (D13, Decision 13). Created with
+ * createExclusive; a holder whose pid is dead is taken over by an atomic
+ * rename to instance.lock.stale-<token>, so exactly one of two concurrent
+ * takers wins. release() compares the per-process token, not pid or hostname.
+ */
+export declare class InstanceLock implements IInstanceLock {
+    private readonly fs;
+    private readonly processHost;
+    private readonly clock;
+    private readonly stateDir;
+    private readonly token;
+    constructor(fs: IFileSystem, processHost: IProcessHost, clock: IClock, stateDir: string, token: string);
+    acquire(): Promise<LockAcquisition>;
+    release(): Promise<void>;
+    inspect(): Promise<LockHolder | null>;
+    private examineExisting;
+    /** Restores a fresh lock renamed by mistake and reports its holder. */
+    private putBack;
+    private lockPath;
+}

package/dist/lock/instanceLock.js

@@ -0,0 +1,125 @@
+import { join } from 'node:path';
+import { parseLockRecord } from '../core/state/stateGuards.js';
+export const LOCK_FILE_NAME = 'instance.lock';
+/**
+ * Service: <stateDir>/instance.lock (D13, Decision 13). Created with
+ * createExclusive; a holder whose pid is dead is taken over by an atomic
+ * rename to instance.lock.stale-<token>, so exactly one of two concurrent
+ * takers wins. release() compares the per-process token, not pid or hostname.
+ */
+export class InstanceLock {
+    fs;
+    processHost;
+    clock;
+    stateDir;
+    token;
+    constructor(fs, processHost, clock, stateDir, token) {
+        this.fs = fs;
+        this.processHost = processHost;
+        this.clock = clock;
+        this.stateDir = stateDir;
+        this.token = token;
+    }
+    async acquire() {
+        const content = serialiseLock({
+            pid: this.processHost.pid,
+            hostname: this.processHost.hostname,
+            startedAt: new Date(this.clock.now()).toISOString(),
+            token: this.token,
+        });
+        let tookOverStale = false;
+        // Every pass that does not finish was caused by another process changing
+        // the lock file in between (it vanished, or another taker renamed it
+        // first); each such change is atomic, so the loop converges.
+        for (;;) {
+            if (await this.fs.createExclusive(this.lockPath(), content)) {
+                return { kind: 'acquired', tookOverStale };
+            }
+            const step = await this.examineExisting();
+            if (step.kind === 'done') {
+                return step.result;
+            }
+            tookOverStale = tookOverStale || step.tookOverStale;
+        }
+    }
+    async release() {
+        const text = await this.fs.readText(this.lockPath());
+        const record = text === null ? null : parseLockRecord(text);
+        // The token, not pid or hostname: macOS renames the host with the network,
+        // and only the process that wrote this token may remove the file.
+        if (record !== null && record.token === this.token) {
+            await this.fs.remove(this.lockPath());
+        }
+    }
+    async inspect() {
+        const text = await this.fs.readText(this.lockPath());
+        const record = text === null ? null : parseLockRecord(text);
+        if (record === null || !this.processHost.isAlive(record.pid)) {
+            return null;
+        }
+        return toHolder(record);
+    }
+    async examineExisting() {
+        const lockPath = this.lockPath();
+        const staleText = await this.fs.readText(lockPath);
+        if (staleText === null) {
+            return { kind: 'retry', tookOverStale: false };
+        }
+        const stale = parseLockRecord(staleText);
+        if (stale === null) {
+            // Never removed: it may be a lock from a newer enmetu or a person's
+            // file, and the LOCKED line names it for the person to inspect.
+            return { kind: 'done', result: { kind: 'unreadable', path: lockPath } };
+        }
+        // Liveness by pid alone; the hostname is reported, never compared.
+        if (this.processHost.isAlive(stale.pid)) {
+            return { kind: 'done', result: { kind: 'held', holder: toHolder(stale) } };
+        }
+        const asidePath = `${lockPath}.stale-${this.token}`;
+        if (!(await this.fs.rename(lockPath, asidePath))) {
+            return { kind: 'retry', tookOverStale: false };
+        }
+        // Between the read and the rename another taker may have replaced the
+        // stale lock with its own; the renamed bytes tell which file was moved.
+        const movedText = await this.fs.readText(asidePath);
+        if (movedText === staleText) {
+            await this.fs.remove(asidePath);
+            return { kind: 'retry', tookOverStale: true };
+        }
+        if (movedText === null) {
+            return { kind: 'retry', tookOverStale: false };
+        }
+        return { kind: 'done', result: await this.putBack(asidePath, movedText) };
+    }
+    /** Restores a fresh lock renamed by mistake and reports its holder. */
+    async putBack(asidePath, movedText) {
+        const lockPath = this.lockPath();
+        await this.fs.createExclusive(lockPath, movedText);
+        await this.fs.remove(asidePath);
+        const fresh = parseLockRecord(movedText);
+        if (fresh === null) {
+            return { kind: 'unreadable', path: lockPath };
+        }
+        return { kind: 'held', holder: toHolder(fresh) };
+    }
+    lockPath() {
+        return join(this.stateDir, LOCK_FILE_NAME);
+    }
+}
+/** Fields in LockRecord order, so the file is byte-stable. */
+function serialiseLock(record) {
+    const ordered = {
+        pid: record.pid,
+        hostname: record.hostname,
+        startedAt: record.startedAt,
+        token: record.token,
+    };
+    return `${JSON.stringify(ordered)}\n`;
+}
+function toHolder(record) {
+    return {
+        pid: record.pid,
+        hostname: record.hostname,
+        startedAt: record.startedAt,
+    };
+}

package/dist/preflight/repositoryPreflight.d.ts

@@ -0,0 +1,20 @@
+import type { Upstream } from '../contracts/gitTypes.js';
+import type { IGitReader } from '../contracts/IGitReader.js';
+export interface PreflightInput {
+    /** Always 'startup'. */
+    readonly cycleId: string;
+}
+export interface PreflightDeps {
+    readonly git: IGitReader;
+}
+/** The upstream STARTED reports. */
+export type PreflightResult = Upstream;
+/**
+ * Controller: startup eligibility (design 1.16, Decision 28). Throws
+ * PreflightError carrying the cycle id, refusing in order:
+ * 1. OPERATION_IN_PROGRESS, 2. DETACHED_HEAD, 3. HEAD_UNBORN, 4. NO_UPSTREAM,
+ * 5. UPSTREAM_NOT_REMOTE (remote '.'), 6. IDENTITY_MISSING.
+ * During a run the same conditions pause the cycle instead; refusing at
+ * startup gives the person the reason while they are still looking.
+ */
+export declare function repositoryPreflight(input: PreflightInput, deps: PreflightDeps): Promise<PreflightResult>;

package/dist/preflight/repositoryPreflight.js

@@ -0,0 +1,42 @@
+import { PreflightError } from '../contracts/errors.js';
+/** A remote named '.' is the local repository itself: there is nothing to sync with. */
+const LOCAL_REMOTE = '.';
+/**
+ * Controller: startup eligibility (design 1.16, Decision 28). Throws
+ * PreflightError carrying the cycle id, refusing in order:
+ * 1. OPERATION_IN_PROGRESS, 2. DETACHED_HEAD, 3. HEAD_UNBORN, 4. NO_UPSTREAM,
+ * 5. UPSTREAM_NOT_REMOTE (remote '.'), 6. IDENTITY_MISSING.
+ * During a run the same conditions pause the cycle instead; refusing at
+ * startup gives the person the reason while they are still looking.
+ */
+export async function repositoryPreflight(input, deps) {
+    const { cycleId } = input;
+    // --- Step 1: a person's rebase, merge, cherry-pick, revert or bisect ---
+    const state = await deps.git.repositoryState();
+    if (state.operation !== null) {
+        throw new PreflightError(`a ${state.operation} is in progress; finish or abort it, then start enmetu again`, 'OPERATION_IN_PROGRESS', cycleId);
+    }
+    // --- Step 2: a checked-out branch ---
+    const branchRef = state.branchRef;
+    if (branchRef === null) {
+        throw new PreflightError('HEAD is detached; check out a branch with an upstream', 'DETACHED_HEAD', cycleId);
+    }
+    // --- Step 3: at least one commit ---
+    if ((await deps.git.headCommit()) === null) {
+        throw new PreflightError(`${branchRef} has no commit yet; make the first commit by hand`, 'HEAD_UNBORN', cycleId);
+    }
+    // --- Step 4: an upstream for the checked-out branch (D6) ---
+    const upstream = await deps.git.upstream(branchRef);
+    if (upstream === null) {
+        throw new PreflightError(`${branchRef} has no upstream; set one with git branch --set-upstream-to`, 'NO_UPSTREAM', cycleId);
+    }
+    // --- Step 5: the upstream lives on a remote ---
+    if (upstream.remote === LOCAL_REMOTE) {
+        throw new PreflightError(`the upstream of ${branchRef} is the local branch ${upstream.remoteRef}, not a remote`, 'UPSTREAM_NOT_REMOTE', cycleId);
+    }
+    // --- Step 6: a committer identity, without which every commit fails ---
+    if (!(await deps.git.hasCommitterIdentity())) {
+        throw new PreflightError('git has no committer identity; set user.name and user.email', 'IDENTITY_MISSING', cycleId);
+    }
+    return upstream;
+}

package/dist/quarantine/pathQuarantine.d.ts

@@ -0,0 +1,113 @@
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IGitReader } from '../contracts/IGitReader.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { HoldResult, IPathQuarantine, RestoreResult } from '../contracts/IPathQuarantine.js';
+export declare const QUARANTINE_FILE_NAME = "quarantine.json";
+/** Temp files of restored worktree paths, outside the tree so a crash cannot leave one to be committed. */
+export declare const QUARANTINE_TEMP_DIR_NAME = "tmp";
+/** How often a restore judges an entry again when the file changed between its decision and its write. */
+export declare const MAX_RESTORE_REJUDGES = 2;
+export interface QuarantinePaths {
+    readonly root: string;
+    readonly stateDir: string;
+}
+/**
+ * Service and Memento caretaker (D4): holds tracked paths that are still
+ * dirty after the commit step aside for the duration of a rebase, without a
+ * stash, and captures writes that land while enmetu's rebase is stopped
+ * before the abort resets them (Decision 45). The memento
+ * (<stateDir>/quarantine.json) is persisted before the tree changes and
+ * removed only after every entry was handled.
+ */
+export declare class PathQuarantine implements IPathQuarantine {
+    private readonly git;
+    private readonly writer;
+    private readonly fs;
+    private readonly paths;
+    constructor(git: IGitReader, writer: IGitWriter, fs: IFileSystem, paths: QuarantinePaths);
+    hold(paths: readonly string[]): Promise<HoldResult>;
+    extend(paths: readonly string[]): Promise<HoldResult>;
+    /**
+     * git's checkout writes the index's version over a file whatever the file
+     * holds, so a write that landed after storeEntries read it would be gone
+     * without a record. Each file is read once more right before the checkout;
+     * one whose bytes changed (or that appeared or went) is stored again and the
+     * memento rewritten first (design 13.11, Decision 114). What stays open is
+     * the time between this read and git's own write, the few milliseconds of
+     * one spawn. A path that is no longer a regular file keeps its entry.
+     */
+    private storeAgainIfWritten;
+    restore(): Promise<RestoreResult>;
+    hasPending(): Promise<boolean>;
+    /**
+     * "Written during the hold" is judged by the working tree alone: the held
+     * version goes back when the file still holds what enmetu left there. The
+     * index is never the judge, because a person may stage the held path during
+     * the hold (git add, git apply --cached) without touching the file, and
+     * keeping the held bytes aside then would take the unstaged part off disk.
+     */
+    private restoreEntry;
+    /** The file holds what the hold's checkout wrote, or HEAD's version (what a rebase or its abort wrote). */
+    private stillAsLeft;
+    /**
+     * The file still holds what enmetu left (Decision 99). When HEAD's version
+     * of the path is no longer heldOver, a rebase changed the path under the
+     * hold and the held bytes are based on the old version: written back as
+     * they are, enmetu's next commit would undo that change. Then the clean
+     * three-way merge of HEAD's version and the held bytes, base heldOver, goes
+     * back, only where no filter applies (raw hash equals filtered hash) and
+     * only while the file is still unchanged; a newer write wins and the held
+     * bytes are kept in a blob. Without a clean merge (a conflict, binary
+     * input, a filter, a deletion on either side) the held version goes back
+     * and the path is reported, so the undo is never silent. seen is the file
+     * the way the decision read it (observe); every write-back is skipped when the
+     * file changed since.
+     */
+    private putBackOnHead;
+    /**
+     * Writes the held version back only while the file is still what the
+     * decision saw. A write that landed since (a person's editor saving
+     * during the restore's own spawns) is judged again from the top, at most
+     * MAX_RESTORE_REJUDGES times; after that the write wins and the held bytes
+     * stay a blob, so a restore never overwrites what it did not judge. The
+     * held bytes are read before the check, so no spawn runs between the check
+     * and the write (Decision 117).
+     */
+    private putBackUnlessChanged;
+    /**
+     * Writes content over the file (null: removes it) only while the file is
+     * what the decision saw (seen), and names a write that lands after that
+     * check (design 13.11, Decision 117). No git command can write a file only
+     * while it is unchanged, so the version being replaced is kept under a
+     * second name in the same step that replaces it:
+     *
+     * 1. content is written and flushed to a staged file first;
+     * 2. the file is checked against seen (one hashFile spawn);
+     * 3. link(2) gives the file's current version a second name, then rename(2)
+     *    puts the staged file in its place (a removal is one rename(2) to the
+     *    second name);
+     * 4. the second name is read: a version other than seen was written after
+     *    step 2, and is stored in a blob and reported, never lost unrecorded.
+     *
+     * What stays open is enmetu's own: a save that replaces the file by
+     * rename(2) between the link and the rename of step 3 (two consecutive
+     * system calls), and a write into the replaced version through a file
+     * descriptor opened before step 3 that lands after step 4's read. Where the
+     * state directory is on another file system than the working tree (a
+     * linked worktree of a repository on another volume), or the file is not a
+     * regular file, link(2) cannot keep it and the plain write runs, with the
+     * window of steps 2 and 3.
+     */
+    private writeOver;
+    /** The file's raw blob id, or a marker for an absent path or one that is not a regular file. */
+    private observe;
+    /** Three-way merge of HEAD's blob with the held bytes on the base the hold left; null unless clean. */
+    private mergeOntoHead;
+    /** Three-way merge of a file with the held bytes on the base the hold left; null unless clean. */
+    private mergeHeld;
+    private tempDir;
+    private inspect;
+    private storeEntries;
+    private writeMemento;
+    private mementoPath;
+}