@fluado/enmetu 0.0.0-stage → 0.1.0

package/dist/halt/haltGuardGitWriter.d.ts

@@ -0,0 +1,23 @@
+import type { FetchResult, PushResult, RebaseResult, StageResult } from '../contracts/gitTypes.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { IHaltStore } from '../contracts/IHaltStore.js';
+/**
+ * Decorator: reads the halt marker before every IGitWriter method and rejects
+ * with HaltedError while it exists, never calling the wrapped writer (D3).
+ */
+export declare class HaltGuardGitWriter implements IGitWriter {
+    private readonly inner;
+    private readonly halt;
+    constructor(inner: IGitWriter, halt: IHaltStore);
+    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>;
+    rebase(ontoSha: string, reflogAction: string): Promise<RebaseResult>;
+    abortRebase(): Promise<void>;
+    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>;
+    private refuseWhileHalted;
+}

package/dist/halt/haltGuardGitWriter.js

@@ -0,0 +1,61 @@
+import { HaltedError } from '../contracts/errors.js';
+/**
+ * Decorator: reads the halt marker before every IGitWriter method and rejects
+ * with HaltedError while it exists, never calling the wrapped writer (D3).
+ */
+export class HaltGuardGitWriter {
+    inner;
+    halt;
+    constructor(inner, halt) {
+        this.inner = inner;
+        this.halt = halt;
+    }
+    async stageAll() {
+        await this.refuseWhileHalted();
+        return this.inner.stageAll();
+    }
+    async unstage(paths) {
+        await this.refuseWhileHalted();
+        return this.inner.unstage(paths);
+    }
+    async fetch(remote, remoteRef, intoRef) {
+        await this.refuseWhileHalted();
+        return this.inner.fetch(remote, remoteRef, intoRef);
+    }
+    async updateRef(ref, newSha, oldSha) {
+        await this.refuseWhileHalted();
+        return this.inner.updateRef(ref, newSha, oldSha);
+    }
+    async rebase(ontoSha, reflogAction) {
+        await this.refuseWhileHalted();
+        return this.inner.rebase(ontoSha, reflogAction);
+    }
+    async abortRebase() {
+        await this.refuseWhileHalted();
+        return this.inner.abortRebase();
+    }
+    async endRebaseAtBranch(branchRef) {
+        await this.refuseWhileHalted();
+        return this.inner.endRebaseAtBranch(branchRef);
+    }
+    async push(remote, sha, remoteRef) {
+        await this.refuseWhileHalted();
+        return this.inner.push(remote, sha, remoteRef);
+    }
+    async storeBlob(path) {
+        await this.refuseWhileHalted();
+        return this.inner.storeBlob(path);
+    }
+    async restoreFromIndex(paths) {
+        await this.refuseWhileHalted();
+        return this.inner.restoreFromIndex(paths);
+    }
+    // Read on every call, never cached: a halt set by an earlier step of the
+    // same cycle must stop the very next write.
+    async refuseWhileHalted() {
+        const record = await this.halt.read();
+        if (record !== null) {
+            throw new HaltedError(`refusing a git write while halted (${record.code}): ${record.message}`, record.code);
+        }
+    }
+}

package/dist/halt/haltStore.d.ts

@@ -0,0 +1,13 @@
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { HaltRecord, IHaltStore } from '../contracts/IHaltStore.js';
+export declare const HALT_FILE_NAME = "halt.json";
+/** Service: the persisted halt marker <stateDir>/halt.json (D3, Decision 12). */
+export declare class HaltStore implements IHaltStore {
+    private readonly fs;
+    private readonly stateDir;
+    constructor(fs: IFileSystem, stateDir: string);
+    read(): Promise<HaltRecord | null>;
+    set(record: HaltRecord): Promise<void>;
+    clear(): Promise<void>;
+    private path;
+}

package/dist/halt/haltStore.js

@@ -0,0 +1,49 @@
+import { join } from 'node:path';
+import { parseHaltRecord } from '../core/state/stateGuards.js';
+export const HALT_FILE_NAME = 'halt.json';
+// The store has no clock, and the moment a marker became unreadable is not
+// knowable from its bytes; status prints this where it prints the time.
+const UNKNOWN_TIME = 'unknown';
+/** Service: the persisted halt marker <stateDir>/halt.json (D3, Decision 12). */
+export class HaltStore {
+    fs;
+    stateDir;
+    constructor(fs, stateDir) {
+        this.fs = fs;
+        this.stateDir = stateDir;
+    }
+    async read() {
+        const path = this.path();
+        const text = await this.fs.readText(path);
+        if (text === null) {
+            return null;
+        }
+        // A marker that exists but cannot be parsed still means "stop": treating it
+        // like an absent one would let a corrupt file silently resume writes (fail-safe).
+        return (parseHaltRecord(text) ?? {
+            code: 'HALT_MARKER_UNREADABLE',
+            message: `the halt marker ${path} cannot be parsed`,
+            cycleId: null,
+            at: UNKNOWN_TIME,
+        });
+    }
+    async set(record) {
+        // Built field by field in interface order, so the file is byte-stable.
+        const persisted = {
+            code: record.code,
+            message: record.message,
+            cycleId: record.cycleId,
+            at: record.at,
+        };
+        await this.fs.writeAtomic(this.path(), `${JSON.stringify(persisted)}\n`, {
+            executable: false,
+            tempDir: this.stateDir,
+        });
+    }
+    async clear() {
+        await this.fs.remove(this.path());
+    }
+    path() {
+        return join(this.stateDir, HALT_FILE_NAME);
+    }
+}

package/dist/halt/recordHalt.d.ts

@@ -0,0 +1,19 @@
+import type { IClock } from '../contracts/IClock.js';
+import type { HaltCode, IHaltStore } from '../contracts/IHaltStore.js';
+import type { ILogger } from '../contracts/ILogger.js';
+export interface RecordHaltInput {
+    readonly code: HaltCode;
+    readonly message: string;
+    readonly cycleId: string;
+}
+export interface RecordHaltDeps {
+    readonly halt: IHaltStore;
+    readonly logger: ILogger;
+    readonly clock: IClock;
+}
+/**
+ * Persists the halt marker, then logs HALTED with the reason at the moment it
+ * is set (D3). The marker comes first: a log line for a halt that was never
+ * written would claim a stop that the next start does not honour.
+ */
+export declare function recordHalt(input: RecordHaltInput, deps: RecordHaltDeps): Promise<void>;

package/dist/halt/recordHalt.js

@@ -0,0 +1,20 @@
+/**
+ * Persists the halt marker, then logs HALTED with the reason at the moment it
+ * is set (D3). The marker comes first: a log line for a halt that was never
+ * written would claim a stop that the next start does not honour.
+ */
+export async function recordHalt(input, deps) {
+    const { code, message, cycleId } = input;
+    await deps.halt.set({
+        code,
+        message,
+        cycleId,
+        at: new Date(deps.clock.now()).toISOString(),
+    });
+    deps.logger.log({
+        level: 'ERROR',
+        code: 'HALTED',
+        message: `${code}: ${message}`,
+        cycleId,
+    });
+}

package/dist/hooks/hookScript.d.ts

@@ -0,0 +1,22 @@
+export declare const HOOK_MARKER = "# enmetu-managed-hook v1";
+export interface HookScriptPaths {
+    /**
+     * The interpreter recorded at install time: an absolute path, or the bare
+     * name no search path entry held (design 13.1).
+     */
+    readonly nodePath: string;
+    /** Absolute enmetu CLI script recorded at install time. */
+    readonly cliPath: string;
+}
+/** The POSIX sh pre-commit hook of design 1.7; a single quote becomes '\''. */
+export declare function renderHookScript(paths: HookScriptPaths): string;
+/** true when the content carries the enmetu marker line. */
+export declare function isEnmetuHook(content: string): boolean;
+/**
+ * The line a person adds to a hook setup enmetu does not own (design 12.5,
+ * Decision 70). It names no path, because a hook is shared through the
+ * repository and a path recorded on one machine blocks every commit on a
+ * clone where it does not exist; it resolves enmetu through PATH and fails
+ * open like the installed hook, with a notice on stderr.
+ */
+export declare function pathInvocationLine(): string;

package/dist/hooks/hookScript.js

@@ -0,0 +1,52 @@
+export const HOOK_MARKER = '# enmetu-managed-hook v1';
+/** The POSIX sh pre-commit hook of design 1.7; a single quote becomes '\''. */
+export function renderHookScript(paths) {
+    return [
+        '#!/bin/sh',
+        HOOK_MARKER,
+        '# Written by enmetu at startup; set "installHook": false in enmetu.config.json to stop that.',
+        '# Refuses a commit that records conflict markers or a .json file that does not parse.',
+        '# To commit anyway: git commit --no-verify',
+        `ENMETU_NODE=${shellQuote(paths.nodePath)}`,
+        `ENMETU_CLI=${shellQuote(paths.cliPath)}`,
+        // The recorded interpreter may vanish with an upgrade (nvm, a moved Bun)
+        // or be a bare name no PATH entry held at install time: the same name on
+        // the commit's PATH keeps a Bun-only machine checking, node on PATH is
+        // the next best interpreter, and failing open beats blocking every commit
+        // (design 13.1, Decision 102). The ${...} is shell parameter expansion.
+        '[ -x "$ENMETU_NODE" ] || ENMETU_NODE="$(command -v "${ENMETU_NODE##*/}" 2>/dev/null || command -v node 2>/dev/null)"',
+        'if [ -n "$ENMETU_NODE" ] && [ -f "$ENMETU_CLI" ]; then',
+        '  exec "$ENMETU_NODE" "$ENMETU_CLI" hook pre-commit',
+        'fi',
+        // The recorded CLI is gone after a reinstall or on another clone; an
+        // enmetu on PATH (node_modules/.bin under husky, a global install) still
+        // checks the commit before the hook gives up.
+        'if command -v enmetu >/dev/null 2>&1; then',
+        '  exec enmetu hook pre-commit',
+        'fi',
+        'echo "enmetu: pre-commit check skipped (node or enmetu not found)" >&2',
+        'exit 0',
+        '',
+    ].join('\n');
+}
+/** true when the content carries the enmetu marker line. */
+export function isEnmetuHook(content) {
+    // A whole-line match, so a foreign hook that merely mentions the marker in
+    // a longer comment is still foreign and left alone.
+    return content.split(/\r?\n/).some((line) => line === HOOK_MARKER);
+}
+/**
+ * The line a person adds to a hook setup enmetu does not own (design 12.5,
+ * Decision 70). It names no path, because a hook is shared through the
+ * repository and a path recorded on one machine blocks every commit on a
+ * clone where it does not exist; it resolves enmetu through PATH and fails
+ * open like the installed hook, with a notice on stderr.
+ */
+export function pathInvocationLine() {
+    return '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';
+}
+// Inside single quotes sh interprets nothing, so the only character to escape
+// is the single quote itself: close the quote, emit \', reopen.
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/hooks/nullHookInstaller.d.ts

@@ -0,0 +1,5 @@
+import type { HookInstallResult, IHookInstaller } from '../contracts/IHookInstaller.js';
+/** Null Object for installHook: false; returns disabled and touches nothing. */
+export declare class NullHookInstaller implements IHookInstaller {
+    ensure(): Promise<HookInstallResult>;
+}

package/dist/hooks/nullHookInstaller.js

@@ -0,0 +1,6 @@
+/** Null Object for installHook: false; returns disabled and touches nothing. */
+export class NullHookInstaller {
+    async ensure() {
+        return { kind: 'disabled' };
+    }
+}

package/dist/hooks/preCommitCheckController.d.ts

@@ -0,0 +1,23 @@
+import type { IGitReader } from '../contracts/IGitReader.js';
+import { type ContentViolation } from '../core/content/contentRules.js';
+export interface PreCommitCheckInput {
+    /** Always 'hook'. */
+    readonly cycleId: string;
+}
+export interface PreCommitCheckDeps {
+    readonly git: IGitReader;
+    readonly skipJsonCheck: readonly string[];
+}
+export interface PreCommitCheckResult {
+    readonly violations: readonly ContentViolation[];
+}
+/**
+ * Controller: the hook's check over the index git is about to commit.
+ * 1. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation (the guard's function, D11).
+ * 2. Return the violations in the order git listed the files.
+ *
+ * The check writes no log line and raises no error of its own, so the cycle
+ * id has nothing to be threaded into; a git failure propagates unchanged to
+ * hookCommand, which owns the exit code.
+ */
+export declare function preCommitCheckController(_input: PreCommitCheckInput, deps: PreCommitCheckDeps): Promise<PreCommitCheckResult>;

package/dist/hooks/preCommitCheckController.js

@@ -0,0 +1,22 @@
+import { findContentViolation, MAX_SCAN_BYTES, } from '../core/content/contentRules.js';
+/**
+ * Controller: the hook's check over the index git is about to commit.
+ * 1. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation (the guard's function, D11).
+ * 2. Return the violations in the order git listed the files.
+ *
+ * The check writes no log line and raises no error of its own, so the cycle
+ * id has nothing to be threaded into; a git failure propagates unchanged to
+ * hookCommand, which owns the exit code.
+ */
+export async function preCommitCheckController(_input, deps) {
+    // 1. Inspect one staged blob at a time, so memory stays at one chunk.
+    const violations = [];
+    for await (const file of deps.git.stagedFiles(MAX_SCAN_BYTES)) {
+        const violation = findContentViolation(file, deps.skipJsonCheck);
+        if (violation !== null) {
+            violations.push(violation);
+        }
+    }
+    // 2. Git's listing order, so the refusal reads like `git status`.
+    return { violations };
+}

package/dist/hooks/preCommitHookInstaller.d.ts

@@ -0,0 +1,32 @@
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IGitConfigReader } from '../contracts/IGitConfigReader.js';
+import type { HookInstallResult, IHookInstaller } from '../contracts/IHookInstaller.js';
+import { type HookScriptPaths } from './hookScript.js';
+/**
+ * Service: installs <hooksDir>/pre-commit following rules 1 to 5 of design
+ * 1.7 (D10). Reads git configuration only through IGitConfigReader, so it
+ * cannot write any; never overwrites a hook without the enmetu marker.
+ * A bare-name interpreter (Bun started by name reports the bare name "bun"
+ * for its own executable path) is resolved through searchPath before the
+ * hook is rendered (design 13.1, Decision 102).
+ */
+export declare class PreCommitHookInstaller implements IHookInstaller {
+    private readonly config;
+    private readonly fs;
+    private readonly hooksDir;
+    private readonly script;
+    /** The PATH the daemon was started with (Runtime.env.PATH); absent: no resolution. */
+    private readonly searchPath?;
+    constructor(config: IGitConfigReader, fs: IFileSystem, hooksDir: string, script: HookScriptPaths, 
+    /** The PATH the daemon was started with (Runtime.env.PATH); absent: no resolution. */
+    searchPath?: string | undefined);
+    ensure(): Promise<HookInstallResult>;
+    private install;
+    /**
+     * The interpreter to record: an absolute nodePath unchanged; for a bare
+     * name, <dir>/<name> for the first absolute search path entry where that
+     * is an executable file or a link; else the bare name, which the hook
+     * looks up on the commit's PATH.
+     */
+    private interpreterPath;
+}

package/dist/hooks/preCommitHookInstaller.js

@@ -0,0 +1,113 @@
+import { isAbsolute, join } from 'node:path';
+import { errorMessage } from '../core/errors/errorMessage.js';
+import { isEnmetuHook, pathInvocationLine, renderHookScript, } from './hookScript.js';
+const HOOK_FILE = 'pre-commit';
+/** For hooks written in another language, where the shell line cannot be pasted (design 12.5). */
+const OTHER_LANGUAGE_NOTE = 'A hook in another language runs "enmetu hook pre-commit" when enmetu is on PATH and refuses the commit when it exits non-zero.';
+/**
+ * Service: installs <hooksDir>/pre-commit following rules 1 to 5 of design
+ * 1.7 (D10). Reads git configuration only through IGitConfigReader, so it
+ * cannot write any; never overwrites a hook without the enmetu marker.
+ * A bare-name interpreter (Bun started by name reports the bare name "bun"
+ * for its own executable path) is resolved through searchPath before the
+ * hook is rendered (design 13.1, Decision 102).
+ */
+export class PreCommitHookInstaller {
+    config;
+    fs;
+    hooksDir;
+    script;
+    searchPath;
+    constructor(config, fs, hooksDir, script, 
+    /** The PATH the daemon was started with (Runtime.env.PATH); absent: no resolution. */
+    searchPath) {
+        this.config = config;
+        this.fs = fs;
+        this.hooksDir = hooksDir;
+        this.script = script;
+        this.searchPath = searchPath;
+    }
+    async ensure() {
+        // The hook is a net, not a cage: every failure here becomes a result the
+        // daemon logs (HOOK_FAILED), never an error that stops it from starting.
+        try {
+            return await this.install();
+        }
+        catch (error) {
+            return {
+                kind: 'failed',
+                detail: errorMessage(error),
+            };
+        }
+    }
+    async install() {
+        // 1. A hooks path set at any scope belongs to the person (or to every
+        //    repository sharing it); writing there would install enmetu into all
+        //    of them, so the person adds the line themselves.
+        const hooksPath = await this.config.configValue('core.hooksPath');
+        if (hooksPath !== null) {
+            return {
+                kind: 'skipped',
+                reason: 'HOOKS_PATH_SET',
+                instruction: `core.hooksPath is ${hooksPath}; enmetu installs nothing there. To add its check, add this line to the shell hook ${join(hooksPath, HOOK_FILE)}: ${pathInvocationLine()}. ${OTHER_LANGUAGE_NOTE}`,
+            };
+        }
+        // 2. The repository's own hooks directory.
+        const target = join(this.hooksDir, HOOK_FILE);
+        const existing = await this.fs.readText(target);
+        // 3. A hook without the marker is someone else's and stays untouched.
+        if (existing !== null && !isEnmetuHook(existing)) {
+            return {
+                kind: 'skipped',
+                reason: 'FOREIGN_HOOK',
+                instruction: `${target} exists and is not enmetu's. To add enmetu's check, add this line to it: ${pathInvocationLine()}. ${OTHER_LANGUAGE_NOTE}`,
+            };
+        }
+        // 4. An enmetu hook is rewritten only when the recorded paths changed.
+        const rendered = renderHookScript({
+            nodePath: await this.interpreterPath(),
+            cliPath: this.script.cliPath,
+        });
+        if (existing === rendered) {
+            return { kind: 'unchanged' };
+        }
+        // 5. The temp file lives in hooksDir, so the rename stays on one file
+        //    system and git never sees a half-written hook.
+        await this.fs.writeAtomic(target, rendered, {
+            executable: true,
+            tempDir: this.hooksDir,
+        });
+        return { kind: existing === null ? 'installed' : 'updated' };
+    }
+    /**
+     * The interpreter to record: an absolute nodePath unchanged; for a bare
+     * name, <dir>/<name> for the first absolute search path entry where that
+     * is an executable file or a link; else the bare name, which the hook
+     * looks up on the commit's PATH.
+     */
+    async interpreterPath() {
+        const name = this.script.nodePath;
+        if (name.includes('/') || this.searchPath === undefined) {
+            return name;
+        }
+        for (const dir of this.searchPath.split(':')) {
+            // An empty or relative entry names the daemon's working directory or a
+            // path below it; git runs the hook from the repository root, where
+            // that entry points somewhere else.
+            if (!isAbsolute(dir)) {
+                continue;
+            }
+            const candidate = join(dir, name);
+            // facts is lstat: a link (Homebrew links every binary into its bin
+            // directory) says nothing about its target, and the hook's [ -x ]
+            // checks the target again at commit time.
+            const facts = await this.fs.facts(candidate);
+            if (facts !== null &&
+                ((facts.kind === 'file' && facts.executable) ||
+                    facts.kind === 'symlink')) {
+                return candidate;
+            }
+        }
+        return name;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { EnmetuInstance, EnmetuStartOptions, EnmetuStateView } from './contracts/library.js';
+/**
+ * The public library entry (package.json "exports", design 12.5). Importing
+ * it has no side effect: no signal handler, no process read, no timer. Besides
+ * src/cli.ts it is the only file that reads the process (environment,
+ * working directory, node binary) and import.meta (the packaged cli.js next
+ * to it, recorded in the pre-commit hook, and package.json's version).
+ */
+export type { ExitCode } from './contracts/exitCode.js';
+export { EXIT } from './contracts/exitCode.js';
+export type { DaemonState, LastCycle, StateInstance, StateReason, StateRecord, StateTransition, } from './contracts/IStateStore.js';
+export type { ITextSink } from './contracts/ITextSink.js';
+export type { EnmetuInstance, EnmetuStartOptions, EnmetuStateView, StateLiveness, } from './contracts/library.js';
+export type { ConflictKey, CycleOutcomeKind, PauseReason, WaitReason, } from './contracts/syncTypes.js';
+/** Starts enmetu for the repository containing options.repo, in this process. */
+export declare function startEnmetu(options: EnmetuStartOptions): EnmetuInstance;
+/** The state record of the repository containing repo, and whether a live instance wrote it. */
+export declare function readEnmetuState(repo: string): Promise<EnmetuStateView>;

package/dist/index.js

@@ -0,0 +1,38 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { readEmbeddedState, startEmbedded } from './library/enmetuLibrary.js';
+export { EXIT } from './contracts/exitCode.js';
+/** Starts enmetu for the repository containing options.repo, in this process. */
+export function startEnmetu(options) {
+    return startEmbedded(options, processRuntime());
+}
+/** The state record of the repository containing repo, and whether a live instance wrote it. */
+export async function readEnmetuState(repo) {
+    return readEmbeddedState(repo, processRuntime());
+}
+/** Read at each call, never at import, so importing the entry touches nothing. */
+function processRuntime() {
+    return {
+        argv: [],
+        env: process.env,
+        cwd: process.cwd(),
+        execPath: process.execPath,
+        // The CLI ships next to this file; the hook records it like `enmetu run`
+        // records its own argv[1].
+        cliPath: fileURLToPath(new URL('./cli.js', import.meta.url)),
+        version: packageVersion(),
+        stdout: process.stdout,
+        stderr: process.stderr,
+    };
+}
+/** 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';
+}

package/dist/library/enmetuLibrary.d.ts

@@ -0,0 +1,16 @@
+import type { EnmetuInstance, EnmetuStartOptions, EnmetuStateView } from '../contracts/library.js';
+import type { Runtime } from '../contracts/runtime.js';
+/**
+ * The library entry's work, with the Runtime passed in so tests can drive it
+ * without src/index.ts (which reads the process and its own module URL). startEmbedded
+ * runs runCommand with createEmbeddedRunDeps: the same locate, git version
+ * gate, config and daemon `enmetu run` uses, but with RequestedStopProcessHost,
+ * so stop() takes the place of the first SIGTERM. options.repo is resolved
+ * against runtime.cwd. It returns at once; done resolves when the run ends and
+ * never rejects: an error runCommand throws is written to the log sink in the
+ * form `enmetu: <message>` and mapped by exitCodeFor, like the CLI's main, so a
+ * host that never awaits done gets no unhandled rejection (Decision 87).
+ */
+export declare function startEmbedded(options: EnmetuStartOptions, runtime: Runtime): EnmetuInstance;
+/** readStateController with createReadStateDeps; repo resolved against runtime.cwd. */
+export declare function readEmbeddedState(repo: string, runtime: Runtime): Promise<EnmetuStateView>;

package/dist/library/enmetuLibrary.js

@@ -0,0 +1,62 @@
+import { resolve } from 'node:path';
+import { runCommand, } from '../cli/commands/runCommand.js';
+import { exitCodeFor } from '../cli/exitCodes.js';
+import { errorMessage } from '../core/errors/errorMessage.js';
+import { createEmbeddedRunDeps, createReadStateDeps, } from '../enmetuInstances.js';
+import { readStateController } from './readStateController.js';
+/**
+ * The library entry's work, with the Runtime passed in so tests can drive it
+ * without src/index.ts (which reads the process and its own module URL). startEmbedded
+ * runs runCommand with createEmbeddedRunDeps: the same locate, git version
+ * gate, config and daemon `enmetu run` uses, but with RequestedStopProcessHost,
+ * so stop() takes the place of the first SIGTERM. options.repo is resolved
+ * against runtime.cwd. It returns at once; done resolves when the run ends and
+ * never rejects: an error runCommand throws is written to the log sink in the
+ * form `enmetu: <message>` and mapped by exitCodeFor, like the CLI's main, so a
+ * host that never awaits done gets no unhandled rejection (Decision 87).
+ */
+export function startEmbedded(options, runtime) {
+    const embedded = embeddedRuntime(options, runtime);
+    const run = createEmbeddedRunDeps(embedded);
+    const done = settledRun({ startDir: resolve(runtime.cwd, options.repo) }, run.deps, embedded.stderr);
+    return {
+        done,
+        stop: () => {
+            run.requestStop();
+            return done;
+        },
+    };
+}
+/** readStateController with createReadStateDeps; repo resolved against runtime.cwd. */
+export async function readEmbeddedState(repo, runtime) {
+    return readStateController({ startDir: resolve(runtime.cwd, repo) }, createReadStateDeps(runtime));
+}
+/** The host's log sink and environment in place of the process's, field by field. */
+function embeddedRuntime(options, runtime) {
+    return {
+        // A host program has no enmetu command line.
+        argv: [],
+        env: options.env ?? runtime.env,
+        cwd: runtime.cwd,
+        execPath: runtime.execPath,
+        cliPath: runtime.cliPath,
+        version: runtime.version,
+        stdout: runtime.stdout,
+        stderr: options.log ?? runtime.stderr,
+    };
+}
+async function settledRun(input, deps, log) {
+    try {
+        return (await runCommand(input, deps)).exitCode;
+    }
+    catch (error) {
+        try {
+            log.write(`enmetu: ${errorMessage(error)}\n`);
+        }
+        catch {
+            // The sink that failed may be the cause; done must still settle, and
+            // the exit code alone tells the host the run failed.
+        }
+        return exitCodeFor(error);
+    }
+}

package/dist/library/readStateController.d.ts

@@ -0,0 +1,28 @@
+import type { ILockInspector } from '../contracts/IInstanceLock.js';
+import type { IRepositoryLocator, RepositoryPaths } from '../contracts/IRepositoryLocator.js';
+import type { IStateStore } from '../contracts/IStateStore.js';
+import type { EnmetuStateView } from '../contracts/library.js';
+export interface ReadStateInput {
+    readonly startDir: string;
+}
+/** The state file and the lock of one repository: the one read seam (design 12.5). */
+export interface StateSources {
+    readonly state: IStateStore;
+    readonly lock: ILockInspector;
+}
+export interface ReadStateDeps {
+    readonly locator: IRepositoryLocator;
+    readonly openSources: (paths: RepositoryPaths) => StateSources;
+}
+/**
+ * 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 declare function readStateController(input: ReadStateInput, deps: ReadStateDeps): Promise<EnmetuStateView>;