@fluado/enmetu 0.2.0 → 0.3.0

package/dist/cli/commands/hookCommand.js

@@ -7,7 +7,8 @@ const HOOK_CYCLE_ID = 'hook';
 /**
  * Controller:
  * 1. locator.locate(startDir); anything but found: notice, exit 0 (the hook fails open).
- * 2. parseConfig of <root>/enmetu.config.json; a ConfigError prints a notice and
+ * 2. parseConfig of <root>/enmetu.config.json with git config over it, as the
+ *    daemon reads it (design 14.18); a ConfigError prints a notice and
  *    applies the defaults, so a broken config never blocks the commit that fixes it.
  *    Unknown keys are ignored without a word: the daemon names them at start (design 14.17).
  * 3. preCommitCheckController with the config's skipJsonCheck.
@@ -21,10 +22,11 @@ export async function hookCommand(input, deps) {
         return { exitCode: EXIT.OK };
     }
     const { paths } = location;
-    // --- Step 2: the config at the root; defaults when it is broken ---
-    const config = await configForCheck(paths.root, deps);
+    const git = deps.openGit(paths);
+    // --- Step 2: the config at the root and git config; defaults when it is broken ---
+    const config = await configForCheck(paths.root, git, deps);
     // --- Step 3: the shared content rules over the staged blobs (D11) ---
-    const { violations } = await preCommitCheckController({ cycleId: HOOK_CYCLE_ID }, { git: deps.openGit(paths), skipJsonCheck: config.skipJsonCheck });
+    const { violations } = await preCommitCheckController({ cycleId: HOOK_CYCLE_ID }, { git, skipJsonCheck: config.skipJsonCheck });
     // --- Step 4: the refusal, or silence ---
     if (violations.length === 0) {
         return { exitCode: EXIT.OK };
@@ -56,16 +58,20 @@ async function locateOrReason(startDir, deps) {
             };
     }
 }
-async function configForCheck(root, deps) {
+async function configForCheck(root, git, deps) {
+    const text = await deps.fs.readText(join(root, CONFIG_FILE_NAME));
+    const gitEntries = await git.enmetuEntries();
     try {
-        return parseConfig(await deps.fs.readText(join(root, CONFIG_FILE_NAME)))
-            .config;
+        return parseConfig(text, gitEntries).config;
     }
     catch (error) {
         if (!(error instanceof ConfigError)) {
             throw error;
         }
-        deps.stderr.write(`enmetu: ignoring ${CONFIG_FILE_NAME} (${error.code}: ${error.message}); using the defaults for this check\n`);
+        const source = error.gitScope === null
+            ? CONFIG_FILE_NAME
+            : `git config enmetu.${error.key ?? ''} (${error.gitScope})`;
+        deps.stderr.write(`enmetu: ignoring ${source} (${error.code}: ${error.message}); using the defaults for this check\n`);
         return DEFAULT_CONFIG;
     }
 }

package/dist/cli/commands/runCommand.d.ts

@@ -1,4 +1,4 @@
-import type { EnmetuConfig } from '../../contracts/config.js';
+import type { EnmetuConfig, GitConfigEntry } from '../../contracts/config.js';
 import { type ExitCode } from '../../contracts/exitCode.js';
 import type { IDaemon } from '../../contracts/IDaemon.js';
 import type { IFileSystem } from '../../contracts/IFileSystem.js';
@@ -11,6 +11,8 @@ export interface RunCommandInput {
 export interface RunCommandDeps {
     readonly locator: IRepositoryLocator;
     readonly fs: IFileSystem;
+    /** Every enmetu.* entry of git config for the resolved repository (design 14.18). */
+    readonly readGitConfig: (paths: RepositoryPaths) => Promise<readonly GitConfigEntry[]>;
     readonly logger: ILogger;
     /** Composition-root closure; builds the daemon for the resolved repository. */
     readonly createDaemon: (paths: RepositoryPaths, config: EnmetuConfig) => IDaemon;
@@ -27,8 +29,13 @@ export declare const MIN_GIT_VERSION: {
  * Controller:
  * 1. locator.locate(startDir): not a repository, bare, or PATH_UNSUPPORTED log NOT_ELIGIBLE, exit 5.
  * 2. Git older than 2.38: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
- * 3. parseConfig of <root>/enmetu.config.json: ConfigError logs CONFIG_INVALID, exit 2;
- *    each unknown key logs CONFIG_KEY_IGNORED once and is ignored (design 14.17).
+ * 3. parseConfig of <root>/enmetu.config.json and readGitConfig(paths), git
+ *    config overriding the file (design 14.18): ConfigError logs
+ *    CONFIG_INVALID naming the file or the git config key and scope, exit 2;
+ *    each unknown key of the file, each key of the file only git config may
+ *    set and each unknown enmetu.* key of git config logs CONFIG_KEY_IGNORED
+ *    once and is ignored (design 14.17); each setting git config set logs
+ *    CONFIG_FROM_GIT with its scope.
  * 4. createDaemon(paths, config).run(), its exit code returned.
  */
 export declare function runCommand(input: RunCommandInput, deps: RunCommandDeps): Promise<RunCommandResult>;

package/dist/cli/commands/runCommand.js

@@ -8,8 +8,13 @@ export const MIN_GIT_VERSION = { major: 2, minor: 38 };
  * Controller:
  * 1. locator.locate(startDir): not a repository, bare, or PATH_UNSUPPORTED log NOT_ELIGIBLE, exit 5.
  * 2. Git older than 2.38: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
- * 3. parseConfig of <root>/enmetu.config.json: ConfigError logs CONFIG_INVALID, exit 2;
- *    each unknown key logs CONFIG_KEY_IGNORED once and is ignored (design 14.17).
+ * 3. parseConfig of <root>/enmetu.config.json and readGitConfig(paths), git
+ *    config overriding the file (design 14.18): ConfigError logs
+ *    CONFIG_INVALID naming the file or the git config key and scope, exit 2;
+ *    each unknown key of the file, each key of the file only git config may
+ *    set and each unknown enmetu.* key of git config logs CONFIG_KEY_IGNORED
+ *    once and is ignored (design 14.17); each setting git config set logs
+ *    CONFIG_FROM_GIT with its scope.
  * 4. createDaemon(paths, config).run(), its exit code returned.
  */
 export async function runCommand(input, deps) {
@@ -35,34 +40,65 @@ export async function runCommand(input, deps) {
     if (olderThanMinimum(version)) {
         return notEligible(deps, 'GIT_TOO_OLD', `git ${version.major}.${version.minor}.${version.patch} is older than ${MIN_GIT_VERSION.major}.${MIN_GIT_VERSION.minor}`);
     }
-    // --- Step 3: the config at the resolved root, defaults when absent ---
+    // --- Step 3: the config at the resolved root, then git config over it ---
     const configPath = join(paths.root, CONFIG_FILE_NAME);
     let parsed;
     try {
-        parsed = parseConfig(await deps.fs.readText(configPath));
+        parsed = parseConfig(await deps.fs.readText(configPath), await deps.readGitConfig(paths));
     }
     catch (error) {
         if (!(error instanceof ConfigError)) {
             throw error;
         }
+        const source = error.gitScope === null
+            ? configPath
+            : `git config enmetu.${error.key ?? ''} (${error.gitScope})`;
         deps.logger.log({
             level: 'ERROR',
             code: 'CONFIG_INVALID',
-            message: `${configPath}: ${error.code}: ${error.message}`,
+            message: `${source}: ${error.code}: ${error.message}`,
         });
         return { exitCode: EXIT.USAGE };
     }
+    logConfigSources(parsed, deps.logger);
+    const { config } = parsed;
+    // --- Step 4: the daemon for this repository ---
+    return { exitCode: await deps.createDaemon(paths, config).run() };
+}
+/**
+ * Step 3's lines, before the daemon starts: what was ignored, then every
+ * setting git config set, so nobody wonders why one clone behaves differently.
+ */
+function logConfigSources(parsed, logger) {
     // A key only a newer enmetu knows must not stop this one (design 14.17).
     for (const key of parsed.unknownKeys) {
-        deps.logger.log({
+        logger.log({
             level: 'WARN',
             code: 'CONFIG_KEY_IGNORED',
             message: `${CONFIG_FILE_NAME}: unknown setting "${key}", ignored`,
         });
     }
-    const { config } = parsed;
-    // --- Step 4: the daemon for this repository ---
-    return { exitCode: await deps.createDaemon(paths, config).run() };
+    for (const key of parsed.gitOnlyKeysInFile) {
+        logger.log({
+            level: 'WARN',
+            code: 'CONFIG_KEY_IGNORED',
+            message: `${CONFIG_FILE_NAME}: ${key} is read from git config only, ignored`,
+        });
+    }
+    for (const { key, scope } of parsed.unknownGitKeys) {
+        logger.log({
+            level: 'WARN',
+            code: 'CONFIG_KEY_IGNORED',
+            message: `git config (${scope}): unknown setting "${key}", ignored`,
+        });
+    }
+    for (const { key, scope, shown } of parsed.fromGit) {
+        logger.log({
+            level: 'INFO',
+            code: 'CONFIG_FROM_GIT',
+            message: `${key} ${shown} (git config, ${scope})`,
+        });
+    }
 }
 function olderThanMinimum(version) {
     return (version.major < MIN_GIT_VERSION.major ||

package/dist/cli.js

@@ -26,6 +26,8 @@ const runtime = {
     // an empty path, finds no CLI there and lets commits through (fail open).
     cliPath: process.argv[1] ?? '',
     version: packageVersion(),
+    platform: process.platform,
+    engine: process.versions.bun === undefined ? 'node' : 'bun',
     stdout: process.stdout,
     stderr: process.stderr,
 };

package/dist/commit/commitLocalChangesController.d.ts

@@ -1,13 +1,17 @@
 import type { IClock } from '../contracts/IClock.js';
+import type { ICommitMessageCommand } from '../contracts/ICommitMessageCommand.js';
 import type { IFileSystem } from '../contracts/IFileSystem.js';
 import type { IGitCommitter, IGitHookRunner } from '../contracts/IGitCommitter.js';
 import type { IGitIndexLock } from '../contracts/IGitIndexLock.js';
 import type { IGitReader } from '../contracts/IGitReader.js';
 import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { IHostMessageWriter } from '../contracts/IHostMessageWriter.js';
 import type { ILogger } from '../contracts/ILogger.js';
 import type { CommitMemory, WaitReason } from '../contracts/syncTypes.js';
 /** An unchanged tree a hook rejected is offered to the hooks again after this long (design 12.7). */
 export declare const HOOK_RETRY_MS = 600000;
+/** commitMessageCommand reads at most this much of the patch on stdin (design 14.18). */
+export declare const MESSAGE_PATCH_CAP_BYTES = 65536;
 export interface CommitLocalChangesInput {
     readonly cycleId: string;
     readonly memory: CommitMemory;
@@ -31,6 +35,8 @@ export interface CommitIndexGit {
 }
 export interface CommitSettings {
     readonly commitSubject: string;
+    /** null: the message is commitSubject alone (design 14.18). */
+    readonly commitMessageCommand: string | null;
     readonly skipJsonCheck: readonly string[];
     /** How long a partial staging holds the commit back; 0 commits at once (design 14.17). */
     readonly partialStagingWaitMs: number;
@@ -49,6 +55,10 @@ export interface CommitLocalChangesDeps {
     /** Hooks on the real index: post-commit and post-index-change run after the branch moved. */
     readonly realHooks: IGitHookRunner;
     readonly indexLock: IGitIndexLock;
+    /** Runs commitMessageCommand; called only when it is set (design 14.18). */
+    readonly messageCommand: ICommitMessageCommand;
+    /** The host program's writer (library option commitMessage); null for the CLI (design 14.19). */
+    readonly hostMessage: IHostMessageWriter | null;
     readonly fs: IFileSystem;
     readonly logger: ILogger;
     /** NullLogger from the root: the residue build must not log EXCLUDED a second time. */
@@ -105,9 +115,20 @@ export type CommitLocalChanges = (input: CommitLocalChangesInput) => Promise<Com
  * 4. commitHooks: pre-commit on the commit index (rejected, timed out or
  *    killed: HOOK_REJECTED, waiting, rejection remembered); then re-stage and
  *    write the tree again, so a formatter's rewrite is in this commit. The
- *    message is commitSubject plus a newline, with or without hooks; the
  *    message hooks do not run (Decision 80). The re-stage logs through
  *    residueLogger: its EXCLUDED lines repeat the first build's.
+ * 4b. The message (design 14.18, 14.19), before index.lock, so no writer
+ *    ever holds up a person's git. The command's message: when
+ *    commitMessageCommand is set, messageCommand runs with
+ *    git.patch(parent, tree, MESSAGE_PATCH_CAP_BYTES) on stdin and
+ *    messageFromText turns its stdout into the message; a failed patch, a
+ *    failed command or output messageFromText refuses log one
+ *    MESSAGE_COMMAND_FAILED line and give none. Without hostMessage: the
+ *    command's message, else commitSubject plus a newline. With hostMessage:
+ *    its write decides, given a runCommand that yields the command's message,
+ *    run at most once however often it is called; declined is commitSubject;
+ *    failed, or text messageFromText refuses, logs MESSAGE_WRITER_FAILED and
+ *    is commitSubject.
  * 5. commit = committer.commitTree({ tree, parent, message, sign: gitBoolean(commit.gpgSign) }).
  * 6. Critical section: indexLock.acquire(commit) (false: busy);
  *    6.1 repositoryState() with an operation: release, paused; HEAD naming

package/dist/commit/commitLocalChangesController.js

@@ -1,10 +1,12 @@
 import { EnmetuError, GitCommandError } from '../contracts/errors.js';
 import { withLastMove } from '../core/commit/commitMemory.js';
-import { gitBoolean } from '../core/commit/commitMessage.js';
+import { gitBoolean, messageFromText } from '../core/commit/commitMessage.js';
 import { repairStaleIndexController } from './repairStaleIndexController.js';
 import { stageGuardedChanges } from './stageGuardedChanges.js';
 /** An unchanged tree a hook rejected is offered to the hooks again after this long (design 12.7). */
 export const HOOK_RETRY_MS = 600000;
+/** commitMessageCommand reads at most this much of the patch on stdin (design 14.18). */
+export const MESSAGE_PATCH_CAP_BYTES = 65536;
 /**
  * Controller: enmetu's commit without touching the person's index (design
  * 12.7, Decisions 72 to 74, 80, 81).
@@ -28,9 +30,20 @@ export const HOOK_RETRY_MS = 600000;
  * 4. commitHooks: pre-commit on the commit index (rejected, timed out or
  *    killed: HOOK_REJECTED, waiting, rejection remembered); then re-stage and
  *    write the tree again, so a formatter's rewrite is in this commit. The
- *    message is commitSubject plus a newline, with or without hooks; the
  *    message hooks do not run (Decision 80). The re-stage logs through
  *    residueLogger: its EXCLUDED lines repeat the first build's.
+ * 4b. The message (design 14.18, 14.19), before index.lock, so no writer
+ *    ever holds up a person's git. The command's message: when
+ *    commitMessageCommand is set, messageCommand runs with
+ *    git.patch(parent, tree, MESSAGE_PATCH_CAP_BYTES) on stdin and
+ *    messageFromText turns its stdout into the message; a failed patch, a
+ *    failed command or output messageFromText refuses log one
+ *    MESSAGE_COMMAND_FAILED line and give none. Without hostMessage: the
+ *    command's message, else commitSubject plus a newline. With hostMessage:
+ *    its write decides, given a runCommand that yields the command's message,
+ *    run at most once however often it is called; declined is commitSubject;
+ *    failed, or text messageFromText refuses, logs MESSAGE_WRITER_FAILED and
+ *    is commitSubject.
  * 5. commit = committer.commitTree({ tree, parent, message, sign: gitBoolean(commit.gpgSign) }).
  * 6. Critical section: indexLock.acquire(commit) (false: busy);
  *    6.1 repositoryState() with an operation: release, paused; HEAD naming
@@ -148,12 +161,15 @@ export async function commitLocalChangesController(input, deps) {
         }
         tree = await deps.commitIndex.committer.writeTree();
     }
+    // --- Step 4b: the message, outside the lock ---
+    const message = await commitMessage(parent, tree, cycleId, deps);
     // --- Step 5: the commit object; HEAD is its only parent, never MERGE_HEAD ---
-    // The subject is the whole message: no path ever reaches it (D1).
+    // enmetu itself puts no path into the message (D1); a person's
+    // commitMessageCommand may (design 14.18).
     const commit = await deps.commitIndex.committer.commitTree({
         tree,
         parent,
-        message: `${settings.commitSubject}\n`,
+        message,
         sign: gitBoolean(await deps.git.configValue('commit.gpgSign')),
     });
     // --- Step 6: critical section under git's own index.lock ---
@@ -212,6 +228,99 @@ async function runPostCommitHooks(commit, tree, cycleId, deps) {
     const residue = await deps.commitIndex.committer.writeTree();
     return residue === tree ? null : residue;
 }
+/**
+ * Step 4b (design 14.18, 14.19): the message. Without a host writer, the
+ * person's commitMessageCommand's, else commitSubject. With one, the
+ * writer's: it decides, and the person's command runs only when the writer
+ * asks for it, at most once. Messages are optional and cosmetic, so nothing
+ * about them ever stops a commit: every failure falls back to commitSubject
+ * with one line.
+ */
+async function commitMessage(parent, tree, cycleId, deps) {
+    const subjectOnly = `${deps.settings.commitSubject}\n`;
+    if (deps.hostMessage === null) {
+        return (await commandMessage(parent, tree, cycleId, deps)) ?? subjectOnly;
+    }
+    let command = null;
+    const run = await deps.hostMessage.write({
+        parent,
+        tree,
+        runCommand: () => {
+            command ??= commandMessage(parent, tree, cycleId, deps);
+            return command;
+        },
+    });
+    if (run.kind === 'declined') {
+        return subjectOnly;
+    }
+    let failure;
+    if (run.kind === 'failed') {
+        failure = run.detail;
+    }
+    else {
+        const parsed = messageFromText(run.text);
+        if (parsed.kind === 'message') {
+            return parsed.message;
+        }
+        failure = `returned ${parsed.reason}`;
+    }
+    deps.logger.log({
+        level: 'WARN',
+        code: 'MESSAGE_WRITER_FAILED',
+        message: `the host program's commitMessage ${failure}; committing with commitSubject`,
+        cycleId,
+    });
+    return subjectOnly;
+}
+/**
+ * commitMessageCommand on the patch from the parent to the tree (design
+ * 14.18, Decision 131): its message, or null when the setting is unset or
+ * anything failed, a failure logged once as MESSAGE_COMMAND_FAILED naming
+ * what comes instead: commitSubject, or the host writer's own message.
+ */
+async function commandMessage(parent, tree, cycleId, deps) {
+    const { commitMessageCommand } = deps.settings;
+    if (commitMessageCommand === null) {
+        return null;
+    }
+    let failure;
+    try {
+        const stdin = await deps.git.patch(parent, tree, MESSAGE_PATCH_CAP_BYTES);
+        const run = await deps.messageCommand.run({
+            command: commitMessageCommand,
+            stdin,
+            parent,
+            tree,
+        });
+        if (run.kind === 'failed') {
+            failure = run.detail;
+        }
+        else {
+            const parsed = messageFromText(run.stdout);
+            if (parsed.kind === 'message') {
+                return parsed.message;
+            }
+            failure = `printed ${parsed.reason}`;
+        }
+    }
+    catch (error) {
+        if (!(error instanceof GitCommandError)) {
+            throw error;
+        }
+        failure = `got no patch (${error.message})`;
+    }
+    // With a host writer the fallback is the writer's, not commitSubject.
+    const next = deps.hostMessage === null
+        ? 'committing with commitSubject'
+        : "the host program's commitMessage writes the message";
+    deps.logger.log({
+        level: 'WARN',
+        code: 'MESSAGE_COMMAND_FAILED',
+        message: `commitMessageCommand ${failure}; ${next}`,
+        cycleId,
+    });
+    return null;
+}
 /**
  * Step 2 of the chain: copy the real index (git's stat data and skip-worktree
  * bits, so add -A does not re-hash every file), seed it with the commit's

package/dist/contracts/ICommitMessageCommand.d.ts

@@ -0,0 +1,32 @@
+export interface CommitMessageCommandInput {
+    /** commitMessageCommand, run by the shell in the repository root. */
+    readonly command: string;
+    /** Written to the command's stdin, then stdin is closed. */
+    readonly stdin: Buffer;
+    /** The commit's parent, as ENMETU_PARENT. */
+    readonly parent: string;
+    /** The commit's tree, as ENMETU_TREE. */
+    readonly tree: string;
+}
+export type CommitMessageCommandRun = 
+/** Exit code 0; stdout up to the output cap. */
+{
+    readonly kind: 'printed';
+    readonly stdout: string;
+}
+/**
+ * Not started, a non-zero exit, a signal, the time limit, or a stop
+ * request; detail says which, with the first line of stderr when there is one.
+ */
+ | {
+    readonly kind: 'failed';
+    readonly detail: string;
+};
+/**
+ * Runs commitMessageCommand for one commit (design 14.18): a shell command
+ * leading its own process group, ended with the whole group at the time
+ * limit or a stop request. Never throws.
+ */
+export interface ICommitMessageCommand {
+    run(input: CommitMessageCommandInput): Promise<CommitMessageCommandRun>;
+}

package/dist/contracts/ICommitMessageCommand.js

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

package/dist/contracts/IGitConfigReader.d.ts

@@ -1,5 +1,8 @@
-/** The one git question the hook installer needs; it cannot write configuration through it. */
+import type { GitConfigEntry } from './config.js';
+/** The git config questions enmetu asks; it cannot write configuration through it. */
 export interface IGitConfigReader {
     /** null when unset at every scope. */
     configValue(key: string): Promise<string | null>;
+    /** Every enmetu.* entry at every scope, in git's reading order; none set: empty (design 14.18). */
+    enmetuEntries(): Promise<readonly GitConfigEntry[]>;
 }

package/dist/contracts/IGitReader.d.ts

@@ -78,4 +78,9 @@ export interface IGitReader extends IGitConfigReader {
     mergeBase(left: string, right: string): Promise<string | null>;
     /** Root-relative paths that differ between two commits, a rename being a delete plus an add, in git's order. */
     changedPaths(from: string, to: string): Promise<readonly string[]>;
+    /**
+     * `git diff-tree -p` from a commit to a tree, without colour, external
+     * diffs or textconv; the first maxBytes bytes, the rest dropped (design 14.18).
+     */
+    patch(from: string, toTree: string, maxBytes: number): Promise<Buffer>;
 }

package/dist/contracts/IHostMessageWriter.d.ts

@@ -0,0 +1,28 @@
+export interface HostMessageInput {
+    readonly parent: string;
+    readonly tree: string;
+    /** The person's command for this change, its message or null; see CommitChange.runCommand. */
+    readonly runCommand: () => Promise<string | null>;
+}
+export type HostMessageRun = 
+/** The writer returned text; enmetu still checks that it holds a subject. */
+{
+    readonly kind: 'wrote';
+    readonly text: string;
+}
+/** The writer returned null: commitSubject, nothing logged. */
+ | {
+    readonly kind: 'declined';
+}
+/** A throw, the time limit, a stop request or a value that is neither text nor null. */
+ | {
+    readonly kind: 'failed';
+    readonly detail: string;
+};
+/**
+ * The host program's commit message writer (EnmetuStartOptions.commitMessage)
+ * with its time limit, behind one call that never throws (design 14.19).
+ */
+export interface IHostMessageWriter {
+    write(input: HostMessageInput): Promise<HostMessageRun>;
+}

package/dist/contracts/IHostMessageWriter.js

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

package/dist/contracts/config.d.ts

@@ -17,10 +17,43 @@ export interface EnmetuConfig {
     readonly commitHooks: boolean;
     /** How long one repository hook may run before it is a rejection (design 12.7, Decision 83). */
     readonly hookTimeoutMs: number;
+    /**
+     * A shell command that writes the commit message; null: commitSubject alone.
+     * Read from git config only, never from enmetu.config.json (design 14.18).
+     */
+    readonly commitMessageCommand: string | null;
+}
+/**
+ * One entry of `git config --show-scope --get-regexp ^enmetu\.`, in git's
+ * reading order (design 14.18). key is as git prints it: section and variable
+ * name lower case. value null: the key is written without a value.
+ */
+export interface GitConfigEntry {
+    readonly scope: string;
+    readonly key: string;
+    readonly value: string | null;
 }
-/** What parseConfig read: the config, and the keys it does not know, in file order (design 14.17). */
+/** A setting git config set: the start line names it with its scope (design 14.18). */
+export interface ConfigFromGit {
+    /** The setting's name as enmetu.config.json spells it, such as quietMs. */
+    readonly key: string;
+    readonly scope: string;
+    /** The value as the start line shows it; commitMessageCommand shows "set", never the command. */
+    readonly shown: string;
+}
+/** What parseConfig read: the config, and what it ignored, in reading order (design 14.17, 14.18). */
 export interface ParsedConfig {
     readonly config: EnmetuConfig;
     /** Ignored; the run command names each once at start. */
     readonly unknownKeys: readonly string[];
+    /** Keys of enmetu.config.json only git config may set (commitMessageCommand); ignored, named at start. */
+    readonly gitOnlyKeysInFile: readonly string[];
+    /** enmetu.* entries of git config enmetu does not know, once per key and scope; ignored, named at start. */
+    readonly unknownGitKeys: readonly GitConfigEntryName[];
+    /** Every setting git config set, in the order of the configuration table. */
+    readonly fromGit: readonly ConfigFromGit[];
+}
+export interface GitConfigEntryName {
+    readonly scope: string;
+    readonly key: string;
 }

package/dist/contracts/errors.d.ts

@@ -21,7 +21,11 @@ export declare class GitOutputError extends EnmetuError {
 }
 export declare class ConfigError extends EnmetuError {
     readonly key: string | null;
-    constructor(message: string, code: ConfigErrorCode, key: string | null);
+    /** The git config scope the invalid value came from; null: enmetu.config.json (design 14.18). */
+    readonly gitScope: string | null;
+    constructor(message: string, code: ConfigErrorCode, key: string | null, 
+    /** The git config scope the invalid value came from; null: enmetu.config.json (design 14.18). */
+    gitScope?: string | null);
 }
 export declare class PreflightError extends EnmetuError {
     constructor(message: string, code: PreflightErrorCode, cycleId?: string | undefined);

package/dist/contracts/errors.js

@@ -29,9 +29,13 @@ export class GitOutputError extends EnmetuError {
 }
 export class ConfigError extends EnmetuError {
     key;
-    constructor(message, code, key) {
+    gitScope;
+    constructor(message, code, key, 
+    /** The git config scope the invalid value came from; null: enmetu.config.json (design 14.18). */
+    gitScope = null) {
         super(message, code);
         this.key = key;
+        this.gitScope = gitScope;
         this.name = 'ConfigError';
     }
 }

package/dist/contracts/library.d.ts

@@ -9,6 +9,36 @@ export interface EnmetuStartOptions {
     readonly log?: ITextSink | undefined;
     /** The environment git children start from; default the process environment. */
     readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    /**
+     * Writes the message of each commit enmetu makes (design 14.19); without
+     * it, the person's commitMessageCommand does, else commitSubject.
+     */
+    readonly commitMessage?: CommitMessageWriter | undefined;
+}
+/**
+ * A host program's commit message writer (design 14.19). It returns the
+ * message, its first line the subject (at most 100 characters, not starting
+ * with #) and the lines after it the body, or null for commitSubject. It has
+ * 10 s; a throw, a timeout, or text without a subject also falls back to
+ * commitSubject, with one MESSAGE_WRITER_FAILED line.
+ */
+export type CommitMessageWriter = (change: CommitChange) => Promise<string | null>;
+/** One commit enmetu is about to make, as a host's writer sees it (design 14.19). */
+export interface CommitChange {
+    /** The repository root. */
+    readonly root: string;
+    /** The commit's only parent. */
+    readonly parent: string;
+    /** The commit's tree; `git diff-tree -r <parent> <tree>` lists the change. */
+    readonly tree: string;
+    /**
+     * The person's commitMessageCommand on this change: its message, or null
+     * when none is set or it failed (enmetu logs the failure). With a writer,
+     * the command runs only through this call, at most once per commit.
+     */
+    runCommand(): Promise<string | null>;
+    /** Aborted when the writer's time is up or enmetu stops. */
+    readonly signal: AbortSignal;
 }
 export interface EnmetuInstance {
     /**

package/dist/contracts/logCodes.d.ts

@@ -1 +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';
+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' | 'CONFIG_FROM_GIT' | 'MESSAGE_COMMAND_FAILED' | 'MESSAGE_WRITER_FAILED' | '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/runtime.d.ts

@@ -11,6 +11,10 @@ export interface Runtime {
     /** Absolute path of the CLI script (Node resolves argv[1]), recorded in the hook. */
     readonly cliPath: string;
     readonly version: string;
+    /** process.platform: 'linux', 'darwin', 'win32', ... */
+    readonly platform: string;
+    /** The JavaScript runtime enmetu runs on: 'bun' when process.versions.bun is set. */
+    readonly engine: 'node' | 'bun';
     readonly stdout: ITextSink;
     readonly stderr: ITextSink;
 }

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

@@ -1,6 +1,33 @@
+/** The longest subject enmetu commits with, from commitSubject or commitMessageCommand. */
+export declare 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
  * everything else are false.
  */
 export declare function gitBoolean(value: string | null): boolean;
+/**
+ * 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 declare function isCommitSubject(value: string): boolean;
+export type ParsedMessage = {
+    readonly kind: 'message';
+    readonly message: string;
+}
+/** What the text holds instead, read after "printed" or "returned", such as "no subject". */
+ | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+/**
+ * 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 declare function messageFromText(text: string): ParsedMessage;