@fluado/enmetu 0.2.0 → 0.3.0

package/dist/core/commit/commitMessage.js

@@ -1,4 +1,6 @@
 const GIT_TRUE = ['true', 'yes', 'on', '1', ''];
+/** The longest subject enmetu commits with, from commitSubject or commitMessageCommand. */
+export const MAX_SUBJECT_CHARACTERS = 100;
 /**
  * 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
@@ -10,3 +12,62 @@ export function gitBoolean(value) {
     }
     return GIT_TRUE.includes(value.toLowerCase());
 }
+/**
+ * One line of 1 to MAX_SUBJECT_CHARACTERS characters, not blank and not
+ * starting with #. git aborts a commit whose message is empty after cleanup,
+ * and a person's commit.cleanup=strip removes a line starting with #.
+ */
+export function isCommitSubject(value) {
+    const characters = Array.from(value).length;
+    return (characters >= 1 &&
+        characters <= MAX_SUBJECT_CHARACTERS &&
+        !/[\r\n]/.test(value) &&
+        !value.startsWith('#') &&
+        value.trim() !== '');
+}
+/**
+ * A message writer's text as a commit message: commitMessageCommand's stdout
+ * (design 14.18) or a host program's return value (design 14.19). Line
+ * endings become \n, every line loses its trailing whitespace, the subject
+ * its leading whitespace too; the first non-blank line is the subject, the
+ * lines after it, without the blank lines around them, the body. Refused: no
+ * subject, a NUL byte (git refuses one in a message), or a subject
+ * isCommitSubject refuses.
+ */
+export function messageFromText(text) {
+    if (text.includes('\0')) {
+        return { kind: 'refused', reason: 'a NUL byte' };
+    }
+    const lines = withoutOuterBlankLines(text
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.trimEnd()));
+    const subject = (lines[0] ?? '').trim();
+    if (subject === '') {
+        return { kind: 'refused', reason: 'no subject' };
+    }
+    if (!isCommitSubject(subject)) {
+        return {
+            kind: 'refused',
+            reason: subject.startsWith('#')
+                ? 'a subject starting with #'
+                : `a subject of ${Array.from(subject).length} characters, more than ${MAX_SUBJECT_CHARACTERS}`,
+        };
+    }
+    const body = withoutOuterBlankLines(lines.slice(1)).join('\n');
+    return {
+        kind: 'message',
+        message: body === '' ? `${subject}\n` : `${subject}\n\n${body}\n`,
+    };
+}
+function withoutOuterBlankLines(lines) {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && lines[start] === '') {
+        start += 1;
+    }
+    while (end > start && lines[end - 1] === '') {
+        end -= 1;
+    }
+    return lines.slice(start, end);
+}

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

@@ -1,8 +1,11 @@
-import type { EnmetuConfig, ParsedConfig } from '../../contracts/config.js';
+import type { EnmetuConfig, GitConfigEntry, 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.
+ * text null: the file is absent. gitEntries: every enmetu.* entry of git
+ * config, in git's reading order; a setting there replaces the file's and is
+ * checked the same way (design 14.18). Throws ConfigError for text that does
+ * not parse and for an invalid value of a known key, with gitScope set when
+ * git config gave the value.
  */
-export declare function parseConfig(text: string | null): ParsedConfig;
+export declare function parseConfig(text: string | null, gitEntries?: readonly GitConfigEntry[]): ParsedConfig;

package/dist/core/config/parseConfig.js

@@ -1,4 +1,5 @@
 import { ConfigError } from '../../contracts/errors.js';
+import { isCommitSubject, MAX_SUBJECT_CHARACTERS, } from '../commit/commitMessage.js';
 import { errorMessage } from '../errors/errorMessage.js';
 import { MAX_STATE_HISTORY } from '../state/stateRecordStep.js';
 export const CONFIG_FILE_NAME = 'enmetu.config.json';
@@ -14,6 +15,7 @@ export const DEFAULT_CONFIG = {
     partialStagingWaitMs: 300000,
     commitHooks: true,
     hookTimeoutMs: 600000,
+    commitMessageCommand: null,
 };
 const KNOWN_KEYS = [
     'quietMs',
@@ -27,29 +29,93 @@ const KNOWN_KEYS = [
     'partialStagingWaitMs',
     'commitHooks',
     'hookTimeoutMs',
+    'commitMessageCommand',
 ];
-const MAX_SUBJECT_CHARACTERS = 100;
+/**
+ * Set by git config alone: a repository's file must never make a person's
+ * machine run a program (design 14.18).
+ */
+const GIT_ONLY_KEYS = ['commitMessageCommand'];
+/** How a git config value is read; every other key is an integer (design 14.18). */
+const BOOLEAN_KEYS = ['installHook', 'commitHooks'];
+const TEXT_KEYS = [
+    'commitSubject',
+    'commitMessageCommand',
+];
+const LIST_KEYS = ['skipJsonCheck'];
+/** git's spellings of true and false; a key written without a value is true. */
+const GIT_TRUE_WORDS = ['true', 'yes', 'on', '1'];
+const GIT_FALSE_WORDS = ['false', 'no', 'off', '0', ''];
+const GIT_SECTION = 'enmetu.';
 /** 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.
+ * text null: the file is absent. gitEntries: every enmetu.* entry of git
+ * config, in git's reading order; a setting there replaces the file's and is
+ * checked the same way (design 14.18). Throws ConfigError for text that does
+ * not parse and for an invalid value of a known key, with gitScope set when
+ * git config gave the value.
  */
-export function parseConfig(text) {
-    if (text === null) {
-        return { config: DEFAULT_CONFIG, unknownKeys: [] };
+export function parseConfig(text, gitEntries = []) {
+    const file = text === null ? {} : fileSettings(text);
+    const fileKeys = Object.keys(file);
+    // 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 = fileKeys.filter((key) => configKey(key) === null);
+    const gitOnlyKeysInFile = fileKeys.filter((key) => isGitOnly(key));
+    const git = gitSettings(gitEntries);
+    const settings = {};
+    for (const key of fileKeys) {
+        if (configKey(key) !== null && !isGitOnly(key)) {
+            settings[key] = file[key];
+        }
+    }
+    for (const setting of git.settings) {
+        settings[setting.key] = setting.value;
     }
+    const config = configWithScope(settings, git.settings);
+    return {
+        config,
+        unknownKeys,
+        gitOnlyKeysInFile,
+        unknownGitKeys: git.unknown,
+        fromGit: git.settings.map((setting) => ({
+            key: setting.key,
+            scope: setting.scope,
+            shown: shownValue(setting.key, config),
+        })),
+    };
+}
+function fileSettings(text) {
     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));
+    return parsed;
+}
+/** The checks of every key, with the scope of a git config value named in the error. */
+function configWithScope(settings, git) {
+    try {
+        return configOf(settings);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError)) {
+            throw error;
+        }
+        const { key } = error;
+        const scope = git.find((setting) => setting.key === key)?.scope;
+        if (scope === undefined) {
+            throw error;
+        }
+        // Only invalid() names a key, and it always throws CONFIG_INVALID_VALUE.
+        throw new ConfigError(error.message, 'CONFIG_INVALID_VALUE', key, scope);
+    }
+}
+function configOf(parsed) {
     const quietMs = readInteger(parsed, 'quietMs', 100, 600000);
-    const config = {
+    return {
         quietMs,
         maxDelayMs: readInteger(parsed, 'maxDelayMs', quietMs, 3600000),
         pollMs: readInteger(parsed, 'pollMs', 100, 3600000),
@@ -61,8 +127,89 @@ export function parseConfig(text) {
         partialStagingWaitMs: readPartialStagingWaitMs(parsed),
         commitHooks: readBoolean(parsed, 'commitHooks'),
         hookTimeoutMs: readHookTimeoutMs(parsed),
+        commitMessageCommand: readCommitMessageCommand(parsed),
     };
-    return { config, unknownKeys };
+}
+/**
+ * The enmetu.* entries of git config as settings, in KNOWN_KEYS order, and
+ * the entries enmetu does not know (a subsection is unknown too). git's rule
+ * decides between scopes: the last value read wins, so a local value beats a
+ * global one; a list is every value of that last scope, so a local list
+ * replaces a global one as a whole.
+ */
+function gitSettings(entries) {
+    const unknown = [];
+    const byKey = new Map();
+    for (const entry of entries) {
+        const key = gitConfigKey(entry.key);
+        if (key === null) {
+            if (!unknown.some((name) => name.key === entry.key && name.scope === entry.scope)) {
+                unknown.push({ scope: entry.scope, key: entry.key });
+            }
+            continue;
+        }
+        byKey.set(key, [...(byKey.get(key) ?? []), entry]);
+    }
+    const settings = [];
+    for (const key of KNOWN_KEYS) {
+        const set = byKey.get(key) ?? [];
+        const last = set[set.length - 1];
+        if (last === undefined) {
+            continue;
+        }
+        const value = LIST_KEYS.includes(key)
+            ? set
+                .filter((entry) => entry.scope === last.scope)
+                .map((entry) => entry.value)
+            : gitValue(key, last.value);
+        settings.push({ key, scope: last.scope, value });
+    }
+    return { settings, unknown };
+}
+/** enmetu.quietms (git prints the variable name lower case) to quietMs; null for anything else. */
+function gitConfigKey(gitKey) {
+    if (!gitKey.toLowerCase().startsWith(GIT_SECTION)) {
+        return null;
+    }
+    const name = gitKey.slice(GIT_SECTION.length).toLowerCase();
+    return KNOWN_KEYS.find((key) => key.toLowerCase() === name) ?? null;
+}
+/**
+ * A git config value as the JSON value it stands for, so the file's checks
+ * apply unchanged: digits become an integer, git's boolean words a boolean;
+ * anything else stays text, which the check of a number or boolean refuses.
+ */
+function gitValue(key, value) {
+    if (TEXT_KEYS.includes(key)) {
+        return value;
+    }
+    if (BOOLEAN_KEYS.includes(key)) {
+        if (value === null) {
+            return true;
+        }
+        const word = value.toLowerCase();
+        if (GIT_TRUE_WORDS.includes(word)) {
+            return true;
+        }
+        return GIT_FALSE_WORDS.includes(word) ? false : value;
+    }
+    return value !== null && /^-?[0-9]+$/.test(value) ? Number(value) : value;
+}
+/** The start line shows a setting's value; a command may carry a token, so it shows only that it is set. */
+function shownValue(key, config) {
+    if (key === 'commitMessageCommand') {
+        return 'set';
+    }
+    const value = config[key];
+    return typeof value === 'number' || typeof value === 'boolean'
+        ? String(value)
+        : JSON.stringify(value);
+}
+function configKey(key) {
+    return KNOWN_KEYS.find((known) => known === key) ?? null;
+}
+function isGitOnly(key) {
+    return GIT_ONLY_KEYS.some((gitOnly) => gitOnly === key);
 }
 function parseJson(text) {
     try {
@@ -103,20 +250,8 @@ function readCommitSubject(parsed) {
     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);
+    if (typeof value !== 'string' || !isCommitSubject(value)) {
+        throw invalid('commitSubject', `must be one line of 1 to ${MAX_SUBJECT_CHARACTERS} characters, not blank and not starting with #`);
     }
     return value;
 }
@@ -174,3 +309,14 @@ function readPartialStagingWaitMs(parsed) {
 function readHookTimeoutMs(parsed) {
     return readInteger(parsed, 'hookTimeoutMs', MIN_HOOK_TIMEOUT_MS, MAX_HOOK_TIMEOUT_MS);
 }
+/** commitMessageCommand: text that is not blank; only git config reaches here (design 14.18). */
+function readCommitMessageCommand(parsed) {
+    const value = parsed.commitMessageCommand;
+    if (value === undefined) {
+        return DEFAULT_CONFIG.commitMessageCommand;
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw invalid('commitMessageCommand', 'must be a command, not blank');
+    }
+    return value;
+}

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

@@ -1,3 +1,4 @@
+import type { GitConfigEntry } from '../../contracts/config.js';
 import type { Divergence, StatusEntry, Upstream } from '../../contracts/gitTypes.js';
 import type { GitVersion } from '../../contracts/IRepositoryLocator.js';
 /**
@@ -48,5 +49,11 @@ export declare function parseBatch(stdout: Buffer): readonly BatchBlob[];
 export declare function parseUpstream(stdout: string, branchRef: string): Upstream | null;
 /** The three absolute paths of rev-parse; null unless exactly three absolute lines (a path with a newline). */
 export declare function parseRevParsePaths(stdout: string): RevParsePaths | null;
+/**
+ * `git config -z --show-scope --get-regexp` entries: scope NUL, then the key,
+ * a newline and the value, NUL; a key written without a value has no newline
+ * (measured with git 2.52.0, design 14.18).
+ */
+export declare function parseConfigEntries(stdout: Buffer): readonly GitConfigEntry[];
 /** true when `git push --porcelain` output carries a ref line starting with `!`. */
 export declare function hasRejectedRef(stdout: string): boolean;

package/dist/core/git/porcelain.js

@@ -179,6 +179,30 @@ export function parseRevParsePaths(stdout) {
     }
     return { root, gitDir, commonDir };
 }
+/**
+ * `git config -z --show-scope --get-regexp` entries: scope NUL, then the key,
+ * a newline and the value, NUL; a key written without a value has no newline
+ * (measured with git 2.52.0, design 14.18).
+ */
+export function parseConfigEntries(stdout) {
+    const fields = nulTerminatedFields(stdout, 'git config');
+    if (fields.length % 2 !== 0) {
+        throw unparseable('git config', fields.join('\0'));
+    }
+    const entries = [];
+    for (let i = 0; i < fields.length; i += 2) {
+        const scope = fields[i] ?? '';
+        const field = fields[i + 1] ?? '';
+        const newline = field.indexOf('\n');
+        const key = newline === -1 ? field : field.slice(0, newline);
+        if (scope === '' || key === '') {
+            throw unparseable('git config', `${scope}\0${field}`);
+        }
+        const value = newline === -1 ? null : field.slice(newline + 1);
+        entries.push({ scope, key, value });
+    }
+    return entries;
+}
 /** true when `git push --porcelain` output carries a ref line starting with `!`. */
 export function hasRejectedRef(stdout) {
     return stdout.split('\n').some((line) => line.startsWith('!'));

package/dist/enmetuInstances.d.ts

@@ -7,6 +7,7 @@ import type { IDaemon } from './contracts/IDaemon.js';
 import type { IHookInstaller } from './contracts/IHookInstaller.js';
 import type { IProcessHost } from './contracts/IProcessHost.js';
 import type { IRepositoryLocator, RepositoryPaths } from './contracts/IRepositoryLocator.js';
+import type { CommitMessageWriter } from './contracts/library.js';
 import type { Runtime } from './contracts/runtime.js';
 import type { ReadStateDeps } from './library/readStateController.js';
 import { type RecoveryDeps } from './recovery/recoveryController.js';
@@ -25,9 +26,10 @@ export declare function createRecoveryDeps(paths: RepositoryPaths, config: Enmet
  * their controllers. Recovery, preflight, hook installer and cycle share one
  * set of repository parts, so one halt store guards every writer. processHost
  * defaults to the operating system's signals; the library passes
- * RequestedStopProcessHost so a host program's process is left alone.
+ * RequestedStopProcessHost so a host program's process is left alone, and the
+ * host's commitMessage writer when it has one (design 14.19).
  */
-export declare function createDaemon(paths: RepositoryPaths, config: EnmetuConfig, runtime: Runtime, processHost?: IProcessHost | undefined): IDaemon;
+export declare function createDaemon(paths: RepositoryPaths, config: EnmetuConfig, runtime: Runtime, processHost?: IProcessHost | undefined, commitMessage?: CommitMessageWriter | undefined): IDaemon;
 /**
  * The daemon's hook installer for one repository (design 13.1): it records
  * Runtime.execPath, resolved through the PATH enmetu was started with when it
@@ -58,8 +60,9 @@ export interface EmbeddedRun {
 /**
  * runCommand's deps with one process host shared by the daemon and its lock:
  * the lock still records this process's pid and hostname, while stops come
- * from requestStop() instead of the host program's signals.
+ * from requestStop() instead of the host program's signals. commitMessage is
+ * the host's writer, when it passed one (design 14.19).
  */
-export declare function createEmbeddedRunDeps(runtime: Runtime): EmbeddedRun;
+export declare function createEmbeddedRunDeps(runtime: Runtime, commitMessage?: CommitMessageWriter | undefined): EmbeddedRun;
 /** The library's state read: the state file and the instance lock, nothing else (design 12.5). */
 export declare function createReadStateDeps(runtime: Runtime): ReadStateDeps;

package/dist/enmetuInstances.js

@@ -5,10 +5,12 @@ import { NodeFileSystemAdapter } from './adapters/fs/nodeFileSystemAdapter.js';
 import { GitFacade } from './adapters/git/gitFacade.js';
 import { GitLocatorFacade } from './adapters/git/gitLocatorFacade.js';
 import { GitProcessAdapter } from './adapters/git/gitProcessAdapter.js';
+import { HostMessageWriterAdapter } from './adapters/host/hostMessageWriterAdapter.js';
 import { NullLogger } from './adapters/log/nullLogger.js';
 import { StderrLoggerAdapter } from './adapters/log/stderrLoggerAdapter.js';
 import { NodeProcessAdapter } from './adapters/process/nodeProcessAdapter.js';
-import { FsWatchAdapter, nodeWatch } from './adapters/watch/fsWatchAdapter.js';
+import { ShellMessageCommandAdapter } from './adapters/process/shellMessageCommandAdapter.js';
+import { watcherFor } from './adapters/watch/watcherFor.js';
 import { commitLocalChangesController, } from './commit/commitLocalChangesController.js';
 import { GitIndexLock } from './commit/gitIndexLock.js';
 import { DEFAULT_CONFIG } from './core/config/parseConfig.js';
@@ -73,9 +75,10 @@ export function createRecoveryDeps(paths, config, runtime) {
  * their controllers. Recovery, preflight, hook installer and cycle share one
  * set of repository parts, so one halt store guards every writer. processHost
  * defaults to the operating system's signals; the library passes
- * RequestedStopProcessHost so a host program's process is left alone.
+ * RequestedStopProcessHost so a host program's process is left alone, and the
+ * host's commitMessage writer when it has one (design 14.19).
  */
-export function createDaemon(paths, config, runtime, processHost) {
+export function createDaemon(paths, config, runtime, processHost, commitMessage) {
     const parts = guardedRepositoryParts(paths, config.gitTimeoutMs, runtime);
     const host = processHost ?? new NodeProcessAdapter();
     // One recorder for the daemon's lifecycle events, the Decorator's cycle
@@ -93,7 +96,7 @@ export function createDaemon(paths, config, runtime, processHost) {
     // Aborted by the first stop request, so a running repository hook ends at
     // once instead of holding the stop for up to hookTimeoutMs (Decision 92).
     const hookStop = new AbortController();
-    const cycleDeps = syncCycleDepsOf(parts, commitOf(parts, paths, config, runtime, hookStop.signal), recorder);
+    const cycleDeps = syncCycleDepsOf(parts, commitOf(parts, paths, config, runtime, hookStop.signal, commitMessage), recorder);
     const cycle = new StateRecordingSyncCycle({ run: (input) => syncCycleController(input, cycleDeps) }, state, parts.git);
     const hookInstaller = hookInstallerOf(parts, paths, config, runtime);
     const scheduler = new HookAbortingSyncScheduler(new SyncScheduler(new SyncCycleRunner(cycle, parts.logger), parts.clock, {
@@ -101,7 +104,7 @@ export function createDaemon(paths, config, runtime, processHost) {
         maxDelayMs: config.maxDelayMs,
         pollMs: config.pollMs,
     }), hookStop);
-    return new Daemon({ root: paths.root, quietMs: config.quietMs, pollMs: config.pollMs }, lockFor(paths, parts.fs, host, parts.clock), parts.halt, recovery, preflight, hookInstaller, new FsWatchAdapter(paths.root, nodeWatch), scheduler, host, parts.logger, state, parts.clock);
+    return new Daemon({ root: paths.root, quietMs: config.quietMs, pollMs: config.pollMs }, lockFor(paths, parts.fs, host, parts.clock), parts.halt, recovery, preflight, hookInstaller, watcherFor(paths.root, runtime), scheduler, host, parts.logger, state, parts.clock);
 }
 /**
  * The daemon's hook installer for one repository (design 13.1): it records
@@ -118,13 +121,19 @@ function hookInstallerOf(parts, paths, config, runtime) {
         : new NullHookInstaller();
 }
 export function createRunDeps(runtime) {
+    const fs = new NodeFileSystemAdapter();
     return {
         locator: createLocator(runtime),
-        fs: new NodeFileSystemAdapter(),
+        fs,
+        readGitConfig: gitConfigReaderFor(runtime, fs),
         logger: new StderrLoggerAdapter(runtime.stderr, new SystemClockAdapter()),
         createDaemon: (paths, config) => createDaemon(paths, config, runtime),
     };
 }
+/** The run command's git config read, before the config and its git timeout are known (design 14.18). */
+function gitConfigReaderFor(runtime, fs) {
+    return (paths) => facadeFor(paths, UNCONFIGURED_GIT_TIMEOUT_MS, runtime, fs).enmetuEntries();
+}
 /**
  * Status reads only; its quarantine still sits on the guarded writer, so even
  * a mistaken write from status would honour the halt.
@@ -251,15 +260,27 @@ function lockFor(paths, fs, processHost, clock) {
 }
 /** The commit index of design 12.7, under the state directory, never committed. */
 const COMMIT_INDEX_FILE = 'commit-index';
+/** commitMessageCommand's fixed time limit, then commitSubject (design 14.18, Decision 131). */
+const MESSAGE_COMMAND_TIMEOUT_MS = 5000;
+/** The most of a message command's stdout enmetu reads; a message is far shorter. */
+const MESSAGE_COMMAND_OUTPUT_CAP_BYTES = 65536;
+/**
+ * A host writer's time limit: the command's own limit, which the writer may
+ * wait for through runCommand, plus room for its own git reads (design 14.19,
+ * Decision 135).
+ */
+const HOST_MESSAGE_TIMEOUT_MS = 10000;
 /**
  * The commit step bound into a closure (design 12.7): a second facade whose
  * runner sets GIT_INDEX_FILE to the commit index, its writer behind the same
  * halt Decorator, a real-index facade for post-commit and post-index-change,
  * both facades with the hook timeout and the daemon's hook stop signal
- * (undefined outside the daemon), the index lock and the NullLogger for the
- * residue build.
+ * (undefined outside the daemon), the index lock, the NullLogger for the
+ * residue build, the message command with its fixed time limit and the same
+ * stop signal (design 14.18), and the host's writer with its own limit and
+ * that signal when the library got one (design 14.19).
  */
-function commitOf(parts, paths, config, runtime, hookStop) {
+function commitOf(parts, paths, config, runtime, hookStop, commitMessage) {
     const commitIndexPath = join(paths.stateDir, COMMIT_INDEX_FILE);
     const commitFacade = new GitFacade(new GitProcessAdapter({
         cwd: paths.root,
@@ -285,12 +306,27 @@ function commitOf(parts, paths, config, runtime, hookStop) {
         },
         realHooks,
         indexLock: parts.indexLock,
+        messageCommand: new ShellMessageCommandAdapter({
+            cwd: paths.root,
+            baseEnv: runtime.env,
+            timeoutMs: MESSAGE_COMMAND_TIMEOUT_MS,
+            outputCapBytes: MESSAGE_COMMAND_OUTPUT_CAP_BYTES,
+            abort: hookStop,
+        }),
+        hostMessage: commitMessage === undefined
+            ? null
+            : new HostMessageWriterAdapter(commitMessage, {
+                root: paths.root,
+                timeoutMs: HOST_MESSAGE_TIMEOUT_MS,
+                abort: hookStop,
+            }),
         fs: parts.fs,
         logger: parts.logger,
         residueLogger: new NullLogger(),
         clock: parts.clock,
         settings: {
             commitSubject: config.commitSubject,
+            commitMessageCommand: config.commitMessageCommand,
             skipJsonCheck: config.skipJsonCheck,
             partialStagingWaitMs: config.partialStagingWaitMs,
             commitHooks: config.commitHooks,
@@ -303,16 +339,19 @@ function commitOf(parts, paths, config, runtime, hookStop) {
 /**
  * runCommand's deps with one process host shared by the daemon and its lock:
  * the lock still records this process's pid and hostname, while stops come
- * from requestStop() instead of the host program's signals.
+ * from requestStop() instead of the host program's signals. commitMessage is
+ * the host's writer, when it passed one (design 14.19).
  */
-export function createEmbeddedRunDeps(runtime) {
+export function createEmbeddedRunDeps(runtime, commitMessage) {
     const processHost = new RequestedStopProcessHost(new NodeProcessAdapter());
+    const fs = new NodeFileSystemAdapter();
     return {
         deps: {
             locator: createLocator(runtime),
-            fs: new NodeFileSystemAdapter(),
+            fs,
+            readGitConfig: gitConfigReaderFor(runtime, fs),
             logger: new StderrLoggerAdapter(runtime.stderr, new SystemClockAdapter()),
-            createDaemon: (paths, config) => createDaemon(paths, config, runtime, processHost),
+            createDaemon: (paths, config) => createDaemon(paths, config, runtime, processHost, commitMessage),
         },
         requestStop: () => processHost.requestStop(),
     };

package/dist/index.d.ts

@@ -10,7 +10,7 @@ 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 { CommitChange, CommitMessageWriter, 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;

package/dist/index.js

@@ -21,6 +21,8 @@ function processRuntime() {
         // records its own argv[1].
         cliPath: fileURLToPath(new URL('./cli.js', import.meta.url)),
         version: packageVersion(),
+        platform: process.platform,
+        engine: process.versions.bun === undefined ? 'node' : 'bun',
         stdout: process.stdout,
         stderr: process.stderr,
     };

package/dist/library/enmetuLibrary.d.ts

@@ -5,7 +5,8 @@ import type { Runtime } from '../contracts/runtime.js';
  * 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
+ * so stop() takes the place of the first SIGTERM, and with the host's
+ * commitMessage writer when it passed one (design 14.19). 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

package/dist/library/enmetuLibrary.js

@@ -9,7 +9,8 @@ import { readStateController } from './readStateController.js';
  * 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
+ * so stop() takes the place of the first SIGTERM, and with the host's
+ * commitMessage writer when it passed one (design 14.19). 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
@@ -17,7 +18,7 @@ import { readStateController } from './readStateController.js';
  */
 export function startEmbedded(options, runtime) {
     const embedded = embeddedRuntime(options, runtime);
-    const run = createEmbeddedRunDeps(embedded);
+    const run = createEmbeddedRunDeps(embedded, options.commitMessage);
     const done = settledRun({ startDir: resolve(runtime.cwd, options.repo) }, run.deps, embedded.stderr);
     return {
         done,
@@ -41,6 +42,8 @@ function embeddedRuntime(options, runtime) {
         execPath: runtime.execPath,
         cliPath: runtime.cliPath,
         version: runtime.version,
+        platform: runtime.platform,
+        engine: runtime.engine,
         stdout: runtime.stdout,
         stderr: options.log ?? runtime.stderr,
     };

package/dist/quarantine/pathQuarantine.d.ts

@@ -27,6 +27,16 @@ export declare class PathQuarantine implements IPathQuarantine {
     constructor(git: IGitReader, writer: IGitWriter, fs: IFileSystem, paths: QuarantinePaths);
     hold(paths: readonly string[]): Promise<HoldResult>;
     extend(paths: readonly string[]): Promise<HoldResult>;
+    /**
+     * git refused the checkout (a person's merge left a held path unmerged,
+     * design 14.20): an entry whose file still holds the bytes stored for it was
+     * never set aside, and restoring it later would write those bytes over the
+     * person's newer work, conflict markers included. Such entries leave the
+     * memento (the memento goes when none is left); an entry whose file changed
+     * stays, so no write goes unrecorded. Entries before `from` (an earlier
+     * hold that extend added to) stay as they are.
+     */
+    private forgetUnheld;
     /**
      * 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