@fluado/enmetu 0.2.0 → 0.4.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';
+import type { CommitMemory, HoldPolicy, 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. */
@@ -56,11 +66,19 @@ export interface CommitLocalChangesDeps {
     readonly clock: IClock;
     readonly settings: CommitSettings;
 }
+/**
+ * hold on nothing and committed (design 14.21, Decision 147): the dirty paths
+ * a pull may set aside, which are the ones this step could not commit. `only`
+ * names the paths the content guard excluded from the build whose tree was
+ * committed or found empty; `all` says every dirty path is the hooks' residue.
+ */
 export type CommitLocalChangesResult = {
     readonly kind: 'nothing';
+    readonly hold: HoldPolicy;
     readonly memory: CommitMemory;
 } | {
     readonly kind: 'committed';
+    readonly hold: HoldPolicy;
     readonly memory: CommitMemory;
 } | {
     readonly kind: 'waiting';
@@ -98,16 +116,29 @@ export type CommitLocalChanges = (input: CommitLocalChangesInput) => Promise<Com
  *    SELECTION_WAIT_ENDED and goes on; 0 goes on at once (design 14.17).
  * 2. Build: parent = git.headCommit(); fs.copy(realIndex, commit index);
  *    committer.seedFrom(parent); stageGuardedChanges on the commit index.
- *    Nothing staged returns nothing.
- * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing;
- *    equal to memory.rejection.tree within HOOK_RETRY_MS returns waiting
+ *    Nothing staged returns nothing, hold only the excluded paths (14.21).
+ * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing
+ *    with hold all (the residue is every dirty path); equal to
+ *    memory.rejection.tree within HOOK_RETRY_MS returns waiting
  *    COMMIT_HOOK_REJECTED without running a hook.
  * 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.
+ *    residueLogger: its EXCLUDED lines repeat the first build's; its excluded
+ *    paths are the ones committed's hold names (14.21).
+ * 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';
+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).
@@ -21,16 +23,29 @@ export const HOOK_RETRY_MS = 600000;
  *    SELECTION_WAIT_ENDED and goes on; 0 goes on at once (design 14.17).
  * 2. Build: parent = git.headCommit(); fs.copy(realIndex, commit index);
  *    committer.seedFrom(parent); stageGuardedChanges on the commit index.
- *    Nothing staged returns nothing.
- * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing;
- *    equal to memory.rejection.tree within HOOK_RETRY_MS returns waiting
+ *    Nothing staged returns nothing, hold only the excluded paths (14.21).
+ * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing
+ *    with hold all (the residue is every dirty path); equal to
+ *    memory.rejection.tree within HOOK_RETRY_MS returns waiting
  *    COMMIT_HOOK_REJECTED without running a hook.
  * 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.
+ *    residueLogger: its EXCLUDED lines repeat the first build's; its excluded
+ *    paths are the ones committed's hold names (14.21).
+ * 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
@@ -98,13 +113,16 @@ export async function commitLocalChangesController(input, deps) {
         // The preflight refuses an unborn HEAD; this guards the type.
         throw new EnmetuError('HEAD is unborn; there is nothing to commit onto', 'HEAD_UNBORN', cycleId);
     }
-    if (!(await build(parent, cycleId, deps.logger, deps))) {
-        return { kind: 'nothing', memory: unchanged };
+    const built = await build(parent, cycleId, deps.logger, deps);
+    let hold = { kind: 'only', paths: built.excluded };
+    if (!built.staged) {
+        return { kind: 'nothing', hold, memory: unchanged };
     }
     // --- Step 3: trees enmetu already knows ---
     let tree = await deps.commitIndex.committer.writeTree();
     if (tree === memory.residueTree) {
-        return { kind: 'nothing', memory: unchanged };
+        // Every dirty path is what the hooks wrote after the last commit (Decision 90).
+        return { kind: 'nothing', hold: { kind: 'all' }, memory: unchanged };
     }
     const rejection = memory.rejection;
     if (rejection !== null &&
@@ -143,17 +161,21 @@ export async function commitLocalChangesController(input, deps) {
             logger: deps.residueLogger,
             skipJsonCheck: settings.skipJsonCheck,
         });
+        hold = { kind: 'only', paths: restaged.excluded };
         if (!restaged.staged) {
-            return { kind: 'nothing', memory: unchanged };
+            return { kind: 'nothing', hold, memory: unchanged };
         }
         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 ---
@@ -176,6 +198,7 @@ export async function commitLocalChangesController(input, deps) {
     }
     return {
         kind: 'committed',
+        hold,
         memory: {
             partialStagingSince: null,
             rejection: null,
@@ -197,7 +220,7 @@ export async function commitLocalChangesController(input, deps) {
 async function runPostCommitHooks(commit, tree, cycleId, deps) {
     const mayWrite = (await deps.realHooks.hookExists('post-index-change')) ||
         (await deps.realHooks.hookExists('post-commit'));
-    const pendingBefore = mayWrite && (await build(commit, cycleId, deps.residueLogger, deps));
+    const pendingBefore = mayWrite && (await build(commit, cycleId, deps.residueLogger, deps)).staged;
     // Both run through `git hook run --ignore-missing` whatever hookExists
     // said, so what runs is git's decision alone; git ignores both exit codes,
     // and so does enmetu.
@@ -206,16 +229,110 @@ async function runPostCommitHooks(commit, tree, cycleId, deps) {
     if (!mayWrite || pendingBefore) {
         return null;
     }
-    if (!(await build(commit, cycleId, deps.residueLogger, deps))) {
+    if (!(await build(commit, cycleId, deps.residueLogger, deps)).staged) {
         return null;
     }
     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
- * tree, stage the guarded working tree. true when anything is staged.
+ * tree, stage the guarded working tree; staged when anything is, with the
+ * paths the content rules kept out (design 14.21).
  */
 async function build(seed, cycleId, logger, deps) {
     const { commitIndex } = deps;
@@ -225,13 +342,12 @@ async function build(seed, cycleId, logger, deps) {
         await deps.fs.remove(commitIndex.path);
     }
     await commitIndex.committer.seedFrom(seed);
-    const { staged } = await stageGuardedChanges({ cycleId }, {
+    return stageGuardedChanges({ cycleId }, {
         git: commitIndex.reader,
         writer: commitIndex.writer,
         logger,
         skipJsonCheck: deps.settings.skipJsonCheck,
     });
-    return staged;
 }
 /**
  * Step 6: under index.lock, in this order (Decisions 72, 81, 121):

package/dist/commit/stageGuardedChanges.d.ts

@@ -12,6 +12,8 @@ export interface StageGuardedDeps {
 }
 export interface StageGuardedResult {
     readonly staged: boolean;
+    /** The paths unstaged by the content rules, in git's order: the EXCLUDED lines (design 14.21). */
+    readonly excluded: readonly string[];
 }
 /**
  * Controller: stage everything, inspect the staged blobs with the shared
@@ -20,7 +22,7 @@ export interface StageGuardedResult {
  * 1. writer.stageAll(); partial logs STAGE_PARTIAL.
  * 2. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation.
  * 3. Violations: one writer.unstage(paths) call, EXCLUDED logged per path.
- * 4. staged = git.hasStagedChanges().
+ * 4. staged = git.hasStagedChanges(); excluded = the violations' paths.
  *
  * Inspecting the staged blobs rather than the working tree means what is
  * inspected is exactly what the next commit records (Decision 5). The

package/dist/commit/stageGuardedChanges.js

@@ -6,7 +6,7 @@ import { findContentViolation, MAX_SCAN_BYTES, } from '../core/content/contentRu
  * 1. writer.stageAll(); partial logs STAGE_PARTIAL.
  * 2. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation.
  * 3. Violations: one writer.unstage(paths) call, EXCLUDED logged per path.
- * 4. staged = git.hasStagedChanges().
+ * 4. staged = git.hasStagedChanges(); excluded = the violations' paths.
  *
  * Inspecting the staged blobs rather than the working tree means what is
  * inspected is exactly what the next commit records (Decision 5). The
@@ -34,10 +34,11 @@ export async function stageGuardedChanges(input, deps) {
         }
     }
     // --- Step 3: unstage the violations in one call, in git's order ---
+    const excluded = violations.map((violation) => violation.path);
     if (violations.length > 0) {
         // reset also clears unmerged entries, which git add has already turned
         // into stage-0 marker text; the bytes stay on disk for the person.
-        await deps.writer.unstage(violations.map((violation) => violation.path));
+        await deps.writer.unstage(excluded);
         for (const violation of violations) {
             deps.logger.log({
                 level: 'WARN',
@@ -47,6 +48,6 @@ export async function stageGuardedChanges(input, deps) {
             });
         }
     }
-    // --- Step 4: report whether anything is left to commit ---
-    return { staged: await deps.git.hasStagedChanges() };
+    // --- Step 4: report whether anything is left to commit, and what was kept out ---
+    return { staged: await deps.git.hasStagedChanges(), excluded };
 }

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 {};