@fluado/enmetu 0.0.0-stage → 0.2.0

package/dist/contracts/gitTypes.d.ts

@@ -0,0 +1,113 @@
+export type StatusCode = ' ' | 'M' | 'T' | 'A' | 'D' | 'R' | 'C' | 'U' | '?' | '!';
+export interface StatusEntry {
+    readonly index: StatusCode;
+    readonly worktree: StatusCode;
+    /** Root-relative, byte for byte what git reported (NUL-separated, never quoted). */
+    readonly path: string;
+}
+export interface StagedFile {
+    readonly path: string;
+    /** null: not a regular file (symlink, gitlink) or larger than the scan limit. */
+    readonly content: Buffer | null;
+}
+export interface Upstream {
+    /** refs/heads/main */
+    readonly branchRef: string;
+    /** origin */
+    readonly remote: string;
+    /** refs/heads/main, the ref on the remote */
+    readonly remoteRef: string;
+    /** refs/remotes/origin/main */
+    readonly trackingRef: string;
+}
+export type ForeignOperation = 'rebase' | 'merge' | 'cherry-pick' | 'revert' | 'bisect';
+export interface RepositoryState {
+    readonly indexLocked: boolean;
+    readonly operation: ForeignOperation | null;
+    /** null when HEAD is detached. */
+    readonly branchRef: string | null;
+}
+export interface Divergence {
+    readonly ahead: number;
+    readonly behind: number;
+}
+export type RemoteHead = {
+    readonly kind: 'found';
+    readonly sha: string;
+} | {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'unreachable';
+    readonly detail: string;
+};
+export interface StageResult {
+    /** true when `git add --ignore-errors` skipped files it could not read. */
+    readonly partial: boolean;
+    readonly detail: string;
+}
+export type FetchResult = {
+    readonly kind: 'fetched';
+} | {
+    readonly kind: 'failed';
+    readonly detail: string;
+};
+/**
+ * HEAD's newest "(start)" reflog entry, which names who started the rebase
+ * in progress (design 13.2, Decision 104).
+ */
+export type RebaseStart = 
+/** HEAD has no reflog (`git reflog exists HEAD` exits 1): ownership falls back to orig-head and onto. */
+{
+    readonly kind: 'unlogged';
+}
+/** HEAD's reflog holds no start entry. */
+ | {
+    readonly kind: 'none';
+}
+/**
+ * action: the text before " (start): ", which is GIT_REFLOG_ACTION when the
+ * starter set it (enmetu's attempt token) and otherwise git's own label of
+ * the command ("rebase", "pull -q --rebase --no-autostash").
+ */
+ | {
+    readonly kind: 'entry';
+    readonly action: string;
+};
+/**
+ * HEAD moved by another command after enmetu's rebase last moved it (design
+ * 14.14, Decision 124): from is the commit of HEAD's newest reflog entry the
+ * rebase wrote under its own action, to is HEAD's newest entry's commit.
+ */
+export interface HeadMove {
+    readonly from: string;
+    readonly to: string;
+}
+export type RebaseResult = {
+    readonly kind: 'rebased';
+} | {
+    readonly kind: 'stopped';
+    readonly detail: string;
+}
+/** git found a rebase already in progress and started nothing; never aborted. */
+ | {
+    readonly kind: 'refused';
+    readonly detail: string;
+}
+/**
+ * git exited non-zero and left no rebase in progress: it refused before
+ * starting, typically because a person wrote or staged a file after the
+ * commit step (design 12.7). Nothing to abort or verify; retried next cycle.
+ */
+ | {
+    readonly kind: 'not-started';
+    readonly detail: string;
+};
+export type PushResult = {
+    readonly kind: 'pushed';
+} | {
+    readonly kind: 'rejected';
+    readonly detail: string;
+} | {
+    readonly kind: 'failed';
+    readonly detail: string;
+};

package/dist/contracts/gitTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/library.d.ts

@@ -0,0 +1,35 @@
+import type { ExitCode } from './exitCode.js';
+import type { StateRecord } from './IStateStore.js';
+import type { ITextSink } from './ITextSink.js';
+/** The public library entry (design 12.5): start, stop and read state inside a host program. */
+export interface EnmetuStartOptions {
+    /** Any directory inside the work tree; the root is resolved through git (D9). */
+    readonly repo: string;
+    /** Where enmetu's log lines go; default the process's stderr. */
+    readonly log?: ITextSink | undefined;
+    /** The environment git children start from; default the process environment. */
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+export interface EnmetuInstance {
+    /**
+     * Resolves once the run ends and never rejects: 0 stopped, 1 unexpected
+     * error (its line written to the log sink the way the CLI writes it to stderr),
+     * 2 invalid config, 3 halted, 4 locked, 5 not eligible (design 1.18, 12.5).
+     */
+    readonly done: Promise<ExitCode>;
+    /** Stops after the running cycle, like the first SIGTERM for the CLI; idempotent; resolves with done. */
+    stop(): Promise<ExitCode>;
+}
+/**
+ * How the state record relates to a live process (design 12.1):
+ * running: the lock's live holder wrote the record;
+ * unrecorded: an instance holds the lock but has not written a record yet;
+ * stopped: no live holder and the record says stopped;
+ * crashed: no live holder and the record says anything else;
+ * never: no live holder and no readable record.
+ */
+export type StateLiveness = 'running' | 'unrecorded' | 'stopped' | 'crashed' | 'never';
+export interface EnmetuStateView {
+    readonly liveness: StateLiveness;
+    readonly record: StateRecord | null;
+}

package/dist/contracts/library.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/logCodes.d.ts

@@ -0,0 +1 @@
+export type LogCode = 'STARTED' | 'STOPPING' | 'STOPPED' | 'LOCK_STALE_TAKEN' | 'RECOVERED' | 'HOOK_INSTALLED' | 'HOOK_UPDATED' | 'HOOK_SKIPPED' | 'HOOK_FAILED' | 'WATCHER_FAILED' | 'COMMITTED' | 'STAGE_PARTIAL' | 'EXCLUDED' | 'PULLED' | 'PUSHED' | 'PUSH_REJECTED' | 'PUSH_FAILED' | 'OFFLINE' | 'CONFLICT' | 'UNPUSHED' | 'PAUSED' | 'BUSY' | 'RESUMED' | 'QUARANTINE_KEPT' | 'HALTED' | 'CYCLE_FAILED' | 'NOT_ELIGIBLE' | 'LOCKED' | 'CONFIG_INVALID' | 'CONFIG_KEY_IGNORED' | 'STATE_WRITE_FAILED' | 'WAITING' | 'SELECTION_WAIT_ENDED' | 'HOOK_REJECTED' | 'COMMIT_DISCARDED' | 'INDEX_REPAIRED' | 'QUARANTINE_UPSTREAM_CHANGED' | 'REBASE_NOT_STARTED' | 'STAGED_RESET' | 'STAGED_REVERT' | 'REBASE_BRANCH_MOVED' | 'COMMIT_ORPHANED';

package/dist/contracts/logCodes.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { ITextSink } from './ITextSink.js';
+/** Everything the process gives enmetu, gathered once by src/cli.ts. */
+export interface Runtime {
+    /** Arguments after the node binary and the script. */
+    readonly argv: readonly string[];
+    /** Base environment for every git child. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly cwd: string;
+    /** Absolute node binary, recorded in the hook. */
+    readonly execPath: string;
+    /** Absolute path of the CLI script (Node resolves argv[1]), recorded in the hook. */
+    readonly cliPath: string;
+    readonly version: string;
+    readonly stdout: ITextSink;
+    readonly stderr: ITextSink;
+}

package/dist/contracts/runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/syncTypes.d.ts

@@ -0,0 +1,75 @@
+import type { HaltCode } from './IHaltStore.js';
+/** The inputs of a rebase that stopped; an identical pair is not re-run (Decision 11). */
+export interface ConflictKey {
+    readonly head: string;
+    readonly upstream: string;
+}
+export type PauseReason = 'FOREIGN_OPERATION' | 'DETACHED_HEAD' | 'NO_UPSTREAM' | 'UPSTREAM_NOT_REMOTE' | 'UPSTREAM_GONE' | 'BRANCH_CHANGED' | 'QUARANTINE_UNSUPPORTED'
+/**
+ * git refused to start enmetu's rebase on REBASE_REFUSED_AFTER consecutive
+ * cycles (design 12.7, Decision 82): a cause that does not go away by itself.
+ */
+ | 'REBASE_REFUSED';
+/**
+ * Why a cycle committed nothing although the tree has changes (design 12.7):
+ * a person has a selection staged and partialStagingWaitMs has not passed
+ * (design 14.17), or a repository commit hook rejected enmetu's commit.
+ */
+export type WaitReason = 'PARTIAL_SELECTION_STAGED' | 'COMMIT_HOOK_REJECTED';
+export type CycleOutcome = {
+    readonly kind: 'synced';
+} | {
+    readonly kind: 'paused';
+    readonly reason: PauseReason;
+} | {
+    readonly kind: 'busy';
+} | {
+    readonly kind: 'offline';
+} | {
+    readonly kind: 'conflict';
+} | {
+    readonly kind: 'push-failed';
+} | {
+    readonly kind: 'halted';
+    readonly code: HaltCode;
+} | {
+    readonly kind: 'waiting';
+    readonly reason: WaitReason;
+};
+/** What the scheduler sees of a cycle; 'failed' is a cycle that threw. */
+export type CycleOutcomeKind = CycleOutcome['kind'] | 'failed';
+/** A commit a repository hook rejected: the tree it was built from and when (epoch ms). */
+export interface HookRejection {
+    readonly tree: string;
+    readonly at: number;
+}
+/**
+ * The last move of HEAD enmetu made within one cycle, its commit, its pull or
+ * both (design 12.7, Decision 98): from is HEAD before the first of them
+ * (the commit's parent when the cycle committed), to is HEAD after the last.
+ */
+export interface HeadMove {
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * What the commit step remembers across cycles (design 12.7): plain state the
+ * cycle returns and SyncCycleRunner hands to the next cycle, like the conflict
+ * key. git cannot tell how long a selection has been staged, which tree a hook
+ * rejected, what a post-commit hook left, or which commit an index written
+ * back by a person's git command is stale against.
+ */
+export interface CommitMemory {
+    /** Epoch ms of the first cycle that found the real index differing from HEAD; null when it does not. */
+    readonly partialStagingSince: number | null;
+    readonly rejection: HookRejection | null;
+    /** The tree a fresh build gave right after enmetu's last commit with hooks; null when hooks left nothing. */
+    readonly residueTree: string | null;
+    /**
+     * Kept while HEAD is still lastMove.to and no repair was applied for it,
+     * so a later cycle can set back index entries a person's git command wrote
+     * back from before the move (Decision 98); null otherwise.
+     */
+    readonly lastMove: HeadMove | null;
+}
+export declare const EMPTY_COMMIT_MEMORY: CommitMemory;

package/dist/contracts/syncTypes.js

@@ -0,0 +1,6 @@
+export const EMPTY_COMMIT_MEMORY = {
+    partialStagingSince: null,
+    rejection: null,
+    residueTree: null,
+    lastMove: null,
+};

package/dist/core/commit/commitMemory.d.ts

@@ -0,0 +1,3 @@
+import type { CommitMemory, HeadMove } from '../../contracts/syncTypes.js';
+/** The memory with lastMove replaced, every other field kept (Decision 98); the commit step and the cycle both set it. */
+export declare function withLastMove(memory: CommitMemory, lastMove: HeadMove | null): CommitMemory;

package/dist/core/commit/commitMemory.js

@@ -0,0 +1,9 @@
+/** The memory with lastMove replaced, every other field kept (Decision 98); the commit step and the cycle both set it. */
+export function withLastMove(memory, lastMove) {
+    return {
+        partialStagingSince: memory.partialStagingSince,
+        rejection: memory.rejection,
+        residueTree: memory.residueTree,
+        lastMove,
+    };
+}

package/dist/core/commit/commitMessage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * git's boolean config reading for commit.gpgSign: true, yes, on, 1 (any
+ * case) and '' (a key written without a value) are true; null (unset) and
+ * everything else are false.
+ */
+export declare function gitBoolean(value: string | null): boolean;

package/dist/core/commit/commitMessage.js

@@ -0,0 +1,12 @@
+const GIT_TRUE = ['true', 'yes', 'on', '1', ''];
+/**
+ * git's boolean config reading for commit.gpgSign: true, yes, on, 1 (any
+ * case) and '' (a key written without a value) are true; null (unset) and
+ * everything else are false.
+ */
+export function gitBoolean(value) {
+    if (value === null) {
+        return false;
+    }
+    return GIT_TRUE.includes(value.toLowerCase());
+}

package/dist/core/config/parseConfig.d.ts

@@ -0,0 +1,8 @@
+import type { EnmetuConfig, ParsedConfig } from '../../contracts/config.js';
+export declare const CONFIG_FILE_NAME = "enmetu.config.json";
+export declare const DEFAULT_CONFIG: EnmetuConfig;
+/**
+ * text null: the file is absent, every default applies. Throws ConfigError
+ * for text that does not parse and for an invalid value of a known key.
+ */
+export declare function parseConfig(text: string | null): ParsedConfig;

package/dist/core/config/parseConfig.js

@@ -0,0 +1,176 @@
+import { ConfigError } from '../../contracts/errors.js';
+import { errorMessage } from '../errors/errorMessage.js';
+import { MAX_STATE_HISTORY } from '../state/stateRecordStep.js';
+export const CONFIG_FILE_NAME = 'enmetu.config.json';
+export const DEFAULT_CONFIG = {
+    quietMs: 5000,
+    maxDelayMs: 60000,
+    pollMs: 5000,
+    commitSubject: 'enmetu: local changes',
+    installHook: true,
+    skipJsonCheck: [],
+    gitTimeoutMs: 120000,
+    stateHistory: 20,
+    partialStagingWaitMs: 300000,
+    commitHooks: true,
+    hookTimeoutMs: 600000,
+};
+const KNOWN_KEYS = [
+    'quietMs',
+    'maxDelayMs',
+    'pollMs',
+    'commitSubject',
+    'installHook',
+    'skipJsonCheck',
+    'gitTimeoutMs',
+    'stateHistory',
+    'partialStagingWaitMs',
+    'commitHooks',
+    'hookTimeoutMs',
+];
+const MAX_SUBJECT_CHARACTERS = 100;
+/** The range of hookTimeoutMs: one second to one day (design 12.7). */
+const MIN_HOOK_TIMEOUT_MS = 1000;
+const MAX_HOOK_TIMEOUT_MS = 86400000;
+/**
+ * text null: the file is absent, every default applies. Throws ConfigError
+ * for text that does not parse and for an invalid value of a known key.
+ */
+export function parseConfig(text) {
+    if (text === null) {
+        return { config: DEFAULT_CONFIG, unknownKeys: [] };
+    }
+    const parsed = parseJson(text);
+    if (!isRecord(parsed)) {
+        throw new ConfigError('the top level must be a JSON object', 'CONFIG_INVALID_VALUE', null);
+    }
+    // Ignored rather than refused, so a key only a newer enmetu knows never
+    // stops an older one; the caller names each, so a typo is not silent
+    // (design 14.17).
+    const unknownKeys = Object.keys(parsed).filter((key) => !KNOWN_KEYS.includes(key));
+    const quietMs = readInteger(parsed, 'quietMs', 100, 600000);
+    const config = {
+        quietMs,
+        maxDelayMs: readInteger(parsed, 'maxDelayMs', quietMs, 3600000),
+        pollMs: readInteger(parsed, 'pollMs', 100, 3600000),
+        commitSubject: readCommitSubject(parsed),
+        installHook: readBoolean(parsed, 'installHook'),
+        skipJsonCheck: readSkipJsonCheck(parsed),
+        gitTimeoutMs: readInteger(parsed, 'gitTimeoutMs', 1000, 3600000),
+        stateHistory: readStateHistory(parsed),
+        partialStagingWaitMs: readPartialStagingWaitMs(parsed),
+        commitHooks: readBoolean(parsed, 'commitHooks'),
+        hookTimeoutMs: readHookTimeoutMs(parsed),
+    };
+    return { config, unknownKeys };
+}
+function parseJson(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed;
+    }
+    catch (error) {
+        const detail = errorMessage(error);
+        throw new ConfigError(detail, 'CONFIG_INVALID_JSON', null);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function invalid(key, rule) {
+    return new ConfigError(`${key} ${rule}`, 'CONFIG_INVALID_VALUE', key);
+}
+function readInteger(parsed, key, min, max) {
+    const value = parsed[key];
+    if (value === undefined) {
+        // A default can fall outside a range that depends on another key
+        // (maxDelayMs below a raised quietMs), so defaults are checked too.
+        return checkedInteger(DEFAULT_CONFIG[key], key, min, max);
+    }
+    if (typeof value !== 'number') {
+        throw invalid(key, `must be an integer from ${min} to ${max}`);
+    }
+    return checkedInteger(value, key, min, max);
+}
+function checkedInteger(value, key, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw invalid(key, `must be an integer from ${min} to ${max}`);
+    }
+    return value;
+}
+function readCommitSubject(parsed) {
+    const value = parsed.commitSubject;
+    if (value === undefined) {
+        return DEFAULT_CONFIG.commitSubject;
+    }
+    const rule = `must be one line of 1 to ${MAX_SUBJECT_CHARACTERS} characters, not blank and not starting with #`;
+    if (typeof value !== 'string') {
+        throw invalid('commitSubject', rule);
+    }
+    const characters = Array.from(value).length;
+    // git aborts a commit whose message is empty after cleanup, and a person's
+    // commit.cleanup=strip removes a line starting with #; either would make
+    // every daemon commit fail.
+    if (characters < 1 ||
+        characters > MAX_SUBJECT_CHARACTERS ||
+        /[\r\n]/.test(value) ||
+        value.startsWith('#') ||
+        value.trim() === '') {
+        throw invalid('commitSubject', rule);
+    }
+    return value;
+}
+function readBoolean(parsed, key) {
+    const value = parsed[key];
+    if (value === undefined) {
+        return DEFAULT_CONFIG[key];
+    }
+    if (typeof value !== 'boolean') {
+        throw invalid(key, 'must be true or false');
+    }
+    return value;
+}
+function readSkipJsonCheck(parsed) {
+    const value = parsed.skipJsonCheck;
+    if (value === undefined) {
+        return DEFAULT_CONFIG.skipJsonCheck;
+    }
+    if (!Array.isArray(value)) {
+        throw invalid('skipJsonCheck', 'must be an array of non-empty strings');
+    }
+    const items = value;
+    const entries = [];
+    for (const item of items) {
+        if (typeof item !== 'string' || item === '') {
+            throw invalid('skipJsonCheck', 'must be an array of non-empty strings');
+        }
+        entries.push(item);
+    }
+    return entries;
+}
+/**
+ * stateHistory: integer 0..MAX_STATE_HISTORY (100); 0 keeps no transitions
+ * (design 12.1). Refused above the maximum rather than clamped, so the file
+ * never silently keeps fewer transitions than the person asked for.
+ */
+function readStateHistory(parsed) {
+    return readInteger(parsed, 'stateHistory', 0, MAX_STATE_HISTORY);
+}
+/**
+ * partialStagingWaitMs: an integer of 0 or more (design 14.17). There is no
+ * wait without an end, so null is refused like any other non-integer.
+ */
+function readPartialStagingWaitMs(parsed) {
+    const value = parsed.partialStagingWaitMs;
+    if (value === undefined) {
+        return DEFAULT_CONFIG.partialStagingWaitMs;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw invalid('partialStagingWaitMs', 'must be an integer of 0 or more');
+    }
+    return value;
+}
+/** hookTimeoutMs: integer 1000..86400000 (design 12.7, Decision 83). */
+function readHookTimeoutMs(parsed) {
+    return readInteger(parsed, 'hookTimeoutMs', MIN_HOOK_TIMEOUT_MS, MAX_HOOK_TIMEOUT_MS);
+}

package/dist/core/content/contentRules.d.ts

@@ -0,0 +1,11 @@
+import type { StagedFile } from '../../contracts/gitTypes.js';
+/** 32 MiB, used by the guard and the hook alike (D11). */
+export declare const MAX_SCAN_BYTES = 33554432;
+export type ContentRule = 'CONFLICT_MARKERS' | 'INVALID_JSON';
+export interface ContentViolation {
+    readonly path: string;
+    readonly rule: ContentRule;
+    readonly detail: string;
+}
+/** One staged file at a time, so a caller never holds more than the reader's chunk. */
+export declare function findContentViolation(file: StagedFile, skipJsonCheck: readonly string[]): ContentViolation | null;

package/dist/core/content/contentRules.js

@@ -0,0 +1,50 @@
+import { errorMessage } from '../errors/errorMessage.js';
+/** 32 MiB, used by the guard and the hook alike (D11). */
+export const MAX_SCAN_BYTES = 33554432;
+// Exactly seven markers at the start of a line, then a space, a tab or the
+// end of the line (CRLF included). Eight are not a marker, and the lone
+// ======= separator is not checked because it is also a setext heading.
+const OPENING_MARKER = /(?:^|\n)<{7}(?:[ \t]|\r?\n|\r?$)/;
+const CLOSING_MARKER = /(?:^|\n)>{7}(?:[ \t]|\r?\n|\r?$)/;
+const BYTE_ORDER_MARK = String.fromCharCode(0xfeff);
+/** One staged file at a time, so a caller never holds more than the reader's chunk. */
+export function findContentViolation(file, skipJsonCheck) {
+    const content = file.content;
+    if (content === null || content.includes(0)) {
+        return null;
+    }
+    const text = content.toString('utf8');
+    if (OPENING_MARKER.test(text) && CLOSING_MARKER.test(text)) {
+        return {
+            path: file.path,
+            rule: 'CONFLICT_MARKERS',
+            detail: 'opening and closing marker lines',
+        };
+    }
+    if (!isJsonPath(file.path) || isExempt(file.path, skipJsonCheck)) {
+        return null;
+    }
+    const detail = jsonParseFailure(text);
+    if (detail === null) {
+        return null;
+    }
+    return { path: file.path, rule: 'INVALID_JSON', detail };
+}
+function isJsonPath(path) {
+    return path.toLowerCase().endsWith('.json');
+}
+/** An entry with a slash names one root-relative path; one without names a basename anywhere. */
+function isExempt(path, skipJsonCheck) {
+    const basename = path.slice(path.lastIndexOf('/') + 1);
+    return skipJsonCheck.some((entry) => entry.includes('/') ? entry === path : entry === basename);
+}
+function jsonParseFailure(text) {
+    const body = text.startsWith(BYTE_ORDER_MARK) ? text.slice(1) : text;
+    try {
+        JSON.parse(body);
+        return null;
+    }
+    catch (error) {
+        return errorMessage(error);
+    }
+}

package/dist/core/errors/errorMessage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The message of anything thrown. Not instanceof Error: an error from Node's
+ * core can come from another realm (Jest's test context), where instanceof
+ * is false.
+ */
+export declare function errorMessage(error: unknown): string;

package/dist/core/errors/errorMessage.js

@@ -0,0 +1,14 @@
+/**
+ * The message of anything thrown. Not instanceof Error: an error from Node's
+ * core can come from another realm (Jest's test context), where instanceof
+ * is false.
+ */
+export function errorMessage(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        'message' in error &&
+        typeof error.message === 'string') {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/core/errors/withCycleId.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The cycle id threaded into an error that escapes a controller. Errors raised
+ * below the controllers (adapters, stores) do not know the cycle; the classes
+ * that carry one are rebuilt with it and keep their stack, anything else
+ * passes unchanged.
+ */
+export declare function withCycleId(error: unknown, cycleId: string): unknown;

package/dist/core/errors/withCycleId.js

@@ -0,0 +1,38 @@
+import { EnmetuError, GitCommandError, GitOutputError, HaltedError, } from '../../contracts/errors.js';
+/**
+ * The cycle id threaded into an error that escapes a controller. Errors raised
+ * below the controllers (adapters, stores) do not know the cycle; the classes
+ * that carry one are rebuilt with it and keep their stack, anything else
+ * passes unchanged.
+ */
+export function withCycleId(error, cycleId) {
+    if (!(error instanceof EnmetuError) || error.cycleId !== undefined) {
+        return error;
+    }
+    let threaded;
+    if (error instanceof GitCommandError && isGitCommandErrorCode(error.code)) {
+        threaded = new GitCommandError(error.message, error.code, error.args, error.exitCode, error.stderr, cycleId);
+    }
+    else if (error instanceof HaltedError) {
+        threaded = new HaltedError(error.message, error.haltCode, cycleId);
+    }
+    else if (error instanceof GitOutputError) {
+        threaded = new GitOutputError(error.message, cycleId);
+    }
+    else if (error.constructor === EnmetuError) {
+        threaded = new EnmetuError(error.message, error.code, cycleId);
+    }
+    else {
+        return error;
+    }
+    if (error.stack !== undefined) {
+        threaded.stack = error.stack;
+    }
+    return threaded;
+}
+function isGitCommandErrorCode(code) {
+    return (code === 'GIT_NOT_FOUND' ||
+        code === 'GIT_TIMEOUT' ||
+        code === 'GIT_FAILED' ||
+        code === 'GIT_INDEX_LOCKED');
+}

package/dist/core/git/enmetuRefs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * enmetu's own refs. They live outside refs/heads, refs/remotes and refs/tags,
+ * so no fetch refspec, push or person's command moves them, and a push that
+ * names branchRef never sends them.
+ */
+/** The last upstream sha enmetu verified to be a fast-forward or pushed itself: refs/enmetu/verified/<branch>. */
+export declare function verifiedRefFor(branchRef: string): string;
+/** Where enmetu fetches before verifying: refs/enmetu/incoming/<branch>. */
+export declare function incomingRefFor(branchRef: string): string;

package/dist/core/git/enmetuRefs.js

@@ -0,0 +1,22 @@
+/**
+ * enmetu's own refs. They live outside refs/heads, refs/remotes and refs/tags,
+ * so no fetch refspec, push or person's command moves them, and a push that
+ * names branchRef never sends them.
+ */
+const BRANCH_PREFIX = 'refs/heads/';
+/** The last upstream sha enmetu verified to be a fast-forward or pushed itself: refs/enmetu/verified/<branch>. */
+export function verifiedRefFor(branchRef) {
+    return `refs/enmetu/verified/${branchName(branchRef)}`;
+}
+/** Where enmetu fetches before verifying: refs/enmetu/incoming/<branch>. */
+export function incomingRefFor(branchRef) {
+    return `refs/enmetu/incoming/${branchName(branchRef)}`;
+}
+// Callers pass the branchRef of `git symbolic-ref HEAD`, always under
+// refs/heads/. Anything else keeps its full name, so two inputs never map
+// to the same enmetu ref.
+function branchName(branchRef) {
+    return branchRef.startsWith(BRANCH_PREFIX)
+        ? branchRef.slice(BRANCH_PREFIX.length)
+        : branchRef;
+}