@fluado/enmetu 0.2.0 → 0.3.0

package/README.md

@@ -4,6 +4,8 @@
 
 <h1 align="center">enmetu</h1>
 
+<p align="center"><sub>/enˈme.tu/, Esperanto for "commit!"</sub></p>
+
 Commits and syncs a git working tree automatically. Run it inside a repository: it commits after you stop editing, rebases onto the upstream, pushes, and pulls new commits.
 
 ## Why enmetu
@@ -20,7 +22,7 @@ Most auto-commit tools commit and push. enmetu also handles what goes wrong:
 
 ## Prerequisites
 
-- Node 24+ or Bun 1.3.6+
+- Node 24+ or Bun 1.4.4+
 - git 2.38+
 - A checked-out branch with an upstream, at least one commit, and a committer identity
 
@@ -50,7 +52,7 @@ Keep `--bun`: without it, `bunx` runs enmetu with Node when Node is installed.
 
 ### Pinning
 
-Add the version for repeatable runs: `@fluado/enmetu@0.2.0`.
+Add the version for repeatable runs: `@fluado/enmetu@0.3.0`.
 
 ## Commands
 
@@ -82,6 +84,21 @@ const { liveness, record } = await readEnmetuState('.')
 const exitCode = await enmetu.stop()
 ```
 
+`commitMessage` lets the host program write each commit message:
+
+```js
+startEnmetu({
+  repo: '.',
+  commitMessage: async ({ root, parent, tree, runCommand, signal }) =>
+    (await runCommand()) ?? 'Update notes',
+})
+```
+
+- `git diff-tree -r <parent> <tree>` in `root` lists the change.
+- Return the message, its first line the subject, or `null` for `commitSubject`.
+- `runCommand()` runs the person's `commitMessageCommand` on this change, at most once, and gives its message or `null`. With `commitMessage` set, the command runs only through this call.
+- 10 seconds, then `signal` aborts and enmetu commits with `commitSubject`. So does a throw, or text without a subject; the log says `MESSAGE_WRITER_FAILED`.
+
 ## Configuration
 
 `enmetu.config.json` at the repository root, optional:
@@ -91,7 +108,7 @@ const exitCode = await enmetu.stop()
 | `quietMs` | `5000` | wait after the last change before committing |
 | `maxDelayMs` | `60000` | maximum delay while changes keep coming |
 | `pollMs` | `5000` | remote check interval |
-| `commitSubject` | `"enmetu: local changes"` | commit message |
+| `commitSubject` | `"enmetu: local changes"` | commit message, and the fallback of `commitMessageCommand` |
 | `installHook` | `true` | install the pre-commit hook |
 | `skipJsonCheck` | `[]` | files exempt from the JSON check, such as `tsconfig.json` |
 | `gitTimeoutMs` | `120000` | timeout per git command |
@@ -102,6 +119,35 @@ const exitCode = await enmetu.stop()
 
 Unknown settings are logged and ignored.
 
+### Your own settings
+
+`git config enmetu.<key>` overrides the file for you alone, with the same names and checks: `--global` for all your repositories, `--local` for one clone. Local beats global. `enmetu run` logs each override at start, such as `CONFIG_FROM_GIT quietMs 2000 (git config, local)`.
+
+```sh
+git config --global enmetu.quietMs 2000
+git config --local --add enmetu.skipJsonCheck tsconfig.json
+```
+
+`skipJsonCheck` takes one path per entry; the list of the most specific scope replaces the file's.
+
+### Commit message command
+
+A command that writes the commit message. Set it in git config only; enmetu ignores it in `enmetu.config.json`.
+
+```sh
+git config --global enmetu.commitMessageCommand 'your-command'
+```
+
+For each commit, enmetu runs it through the shell in the repository root:
+
+- stdin: the patch, its first 64 KiB
+- environment: `ENMETU_PARENT` and `ENMETU_TREE`, for your own `git diff "$ENMETU_PARENT" "$ENMETU_TREE"`
+- stdout: the first line is the subject (at most 100 characters), the lines after it the body
+
+After 5 seconds, or when the command fails or prints no usable subject, enmetu commits with `commitSubject` and logs `MESSAGE_COMMAND_FAILED`. The start line shows that a command is set, never the command.
+
+Example: [`examples/commit-message`](https://codefloe.com/fluado/enmetu/src/branch/main/examples/commit-message), a Node or Bun script that names the changed document and adds a detail from a local model through [llm](https://llm.datasette.io), such as Apple's on-device model. Not part of the package.
+
 ## Status
 
 ```
@@ -145,6 +191,7 @@ stderr, one line per event:
 | `CONFLICT`, `UNPUSHED` | local commits not pushed |
 | `WAITING`, `PAUSED`, `OFFLINE` | sync on hold |
 | `HALTED` | see `enmetu status` |
+| `MESSAGE_COMMAND_FAILED`, `MESSAGE_WRITER_FAILED` | message from the fallback named in the line |
 | `COMMIT_ORPHANED`, `STAGED_RESET`, `STAGED_REVERT`, `QUARANTINE_KEPT` | see Known limitations |
 
 ## State file
@@ -181,8 +228,9 @@ if command -v enmetu >/dev/null 2>&1; then enmetu hook pre-commit || exit 1; els
 
 - One repository per process. No system service, no notifications.
 - A partial staging pauses sync for up to `partialStagingWaitMs` (5 minutes by default), then enmetu commits everything. A case-only rename staged with `git mv` pauses it until you commit it.
-- `commit-msg` and `prepare-commit-msg` hooks don't run on enmetu's commits.
+- `commit-msg` and `prepare-commit-msg` hooks don't run on enmetu's commits; `commitMessageCommand` writes the message instead.
 - Under Bun without file-watching permission, enmetu commits on its poll interval.
+- Under Node on Linux, enmetu does not watch files: from Node 24.22, Node's recursive watch there can end the process ([nodejs/node#66791](https://github.com/nodejs/node/issues/66791)). enmetu commits on its poll interval (`pollMs`, 5 seconds by default) and says so once at start (`WATCHER_FAILED`). Bun watches.
 - A save during enmetu's pull can be overwritten by git without notice.
 
 Overlapping git commands:
@@ -194,7 +242,7 @@ Overlapping git commands:
 | `QUARANTINE_KEPT` | your edit collided with a version enmetu held aside | command in the log line |
 | `COMMIT_ORPHANED` | committed during enmetu's pull | `git cherry-pick -x` command in `enmetu status` |
 | `STAGED_REVERT` | a refused `git merge` restored old content | `git restore` command in the log line |
-| `could not write index` on a refused merge | git stashed your edits | `git fsck --no-reflogs --unreachable`, then `git stash apply <id>` |
+| `could not write index` on a refused merge, or with older git (2.39) your edits gone after `would be overwritten by merge` | git stashed your edits | `git fsck --no-reflogs --unreachable`, then `git stash apply <id>` |
 | `git rebase` fails, no rebase in progress | started together with enmetu's | `git rebase --quit` if needed, `git reset --merge`, `git checkout <branch>`, retry |
 
 ## Contributing

package/dist/adapters/git/gitFacade.d.ts

@@ -1,3 +1,4 @@
+import type { GitConfigEntry } from '../../contracts/config.js';
 import type { Divergence, FetchResult, HeadMove, PushResult, RebaseResult, RebaseStart, RemoteHead, RepositoryState, StagedFile, StageResult, StatusEntry, Upstream } from '../../contracts/gitTypes.js';
 import type { IFileSystem } from '../../contracts/IFileSystem.js';
 import type { CommitHookName, CommitTreeInput, HookRun, IGitCommitter } from '../../contracts/IGitCommitter.js';
@@ -79,6 +80,11 @@ export declare class GitFacade implements IGitReader, IGitWriter, IGitCommitter
     mergeBase(left: string, right: string): Promise<string | null>;
     /** git diff --name-only -z --no-renames <from> <to> (design 12.3). */
     changedPaths(from: string, to: string): Promise<readonly string[]>;
+    /**
+     * git diff-tree -r -p --no-color --no-ext-diff --no-textconv <from> <toTree>,
+     * stdout capped at maxBytes, the rest read and dropped (design 14.18).
+     */
+    patch(from: string, toTree: string, maxBytes: number): Promise<Buffer>;
     /**
      * git -c core.hooksPath=/dev/null read-tree --reset <commit> (design 12.7):
      * -m's one-tree merge, which keeps the stat data of matching entries, except
@@ -102,6 +108,8 @@ export declare class GitFacade implements IGitReader, IGitWriter, IGitCommitter
      */
     runHook(name: CommitHookName, args: readonly string[]): Promise<HookRun>;
     configValue(key: string): Promise<string | null>;
+    /** git config -z --show-scope --get-regexp ^enmetu\. ; exit 1 means none is set (design 14.18). */
+    enmetuEntries(): Promise<readonly GitConfigEntry[]>;
     stageAll(): Promise<StageResult>;
     unstage(paths: readonly string[]): Promise<void>;
     fetch(remote: string, remoteRef: string, intoRef: string): Promise<FetchResult>;

package/dist/adapters/git/gitFacade.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { GitCommandError, GitOutputError } from '../../contracts/errors.js';
-import { hasRejectedRef, parseBatch, parseBatchCheck, parseDivergence, parseLsRemote, parseRawDiff, parseStatus, parseUpstream, } from '../../core/git/porcelain.js';
+import { hasRejectedRef, parseBatch, parseBatchCheck, parseConfigEntries, parseDivergence, parseLsRemote, parseRawDiff, parseStatus, parseUpstream, } from '../../core/git/porcelain.js';
 /** At most this much blob content is requested from one `git cat-file --batch` call. */
 export const GIT_BATCH_CHUNK_BYTES = 67108864;
 /** A hook's stdout and stderr beyond this are dropped, never a failure (design 12.7, Decision 83). */
@@ -347,6 +347,27 @@ export class GitFacade {
         const args = ['diff', '--name-only', '-z', '--no-renames', from, to];
         return parseNulPaths((await this.gitOk(args)).stdout, 'git diff --name-only');
     }
+    /**
+     * git diff-tree -r -p --no-color --no-ext-diff --no-textconv <from> <toTree>,
+     * stdout capped at maxBytes, the rest read and dropped (design 14.18).
+     */
+    async patch(from, toTree, maxBytes) {
+        const args = [
+            'diff-tree',
+            '-r',
+            '-p',
+            '--no-color',
+            '--no-ext-diff',
+            '--no-textconv',
+            from,
+            toTree,
+        ];
+        const result = await this.git(args, { outputCapBytes: maxBytes });
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return result.stdout;
+    }
     /**
      * git -c core.hooksPath=/dev/null read-tree --reset <commit> (design 12.7):
      * -m's one-tree merge, which keeps the stat data of matching entries, except
@@ -448,6 +469,18 @@ export class GitFacade {
         }
         return stripOneTrailingNewline(result.stdout.toString('utf8'));
     }
+    /** git config -z --show-scope --get-regexp ^enmetu\. ; exit 1 means none is set (design 14.18). */
+    async enmetuEntries() {
+        const args = ['config', '-z', '--show-scope', '--get-regexp', '^enmetu\\.'];
+        const result = await this.git(args);
+        if (result.exitCode === 1) {
+            return [];
+        }
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return parseConfigEntries(result.stdout);
+    }
     async stageAll() {
         const args = [...HOOKLESS, 'add', '-A', '--ignore-errors'];
         const result = await this.git(args);

package/dist/adapters/git/gitProcessAdapter.js

@@ -1,6 +1,6 @@
 import { execFile, spawn } from 'node:child_process';
-import { kill } from 'node:process';
 import { GitCommandError } from '../../contracts/errors.js';
+import { CappedOutput, errorCode, killGroup } from '../process/processGroup.js';
 /** 128 MiB: a cat-file batch chunk (64 MiB of content) plus headers fits with room. */
 export const GIT_MAX_BUFFER_BYTES = 134217728;
 const KILL_SIGNAL = 'SIGTERM';
@@ -184,53 +184,6 @@ export class GitProcessAdapter {
         return new GitCommandError(`${command} ended by signal ${error.signal ?? 'unknown'}`, 'GIT_FAILED', args, null, stderr);
     }
 }
-/** Keeps the first `cap` bytes of a stream and counts that more arrived. */
-class CappedOutput {
-    cap;
-    chunks = [];
-    length = 0;
-    dropped = false;
-    constructor(cap) {
-        this.cap = cap;
-    }
-    add(chunk) {
-        const room = this.cap - this.length;
-        if (room <= 0) {
-            this.dropped = this.dropped || chunk.length > 0;
-            return;
-        }
-        const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
-        this.dropped = this.dropped || kept.length < chunk.length;
-        this.chunks.push(kept);
-        this.length += kept.length;
-    }
-    bytes() {
-        return Buffer.concat(this.chunks);
-    }
-    text() {
-        return this.bytes().toString('utf8');
-    }
-}
-/** Signals git's whole process group; a group that is already gone is fine. */
-function killGroup(pid, signal) {
-    if (pid === undefined) {
-        return;
-    }
-    try {
-        kill(-pid, signal);
-    }
-    catch (error) {
-        if (errorCode(error) !== 'ESRCH') {
-            throw error;
-        }
-    }
-}
-function errorCode(error) {
-    if (typeof error === 'object' && error !== null && 'code' in error) {
-        return typeof error.code === 'string' ? error.code : 'unknown';
-    }
-    return 'unknown';
-}
 /**
  * The adapter's environment, plus GIT_REFLOG_ACTION when the call names one.
  * The shared environment is never changed, so no other call inherits it.

package/dist/adapters/host/hostMessageWriterAdapter.d.ts

@@ -0,0 +1,23 @@
+import type { HostMessageInput, HostMessageRun, IHostMessageWriter } from '../../contracts/IHostMessageWriter.js';
+import type { CommitMessageWriter } from '../../contracts/library.js';
+export interface HostMessageWriterOptions {
+    /** The repository root, handed to the writer. */
+    readonly root: string;
+    readonly timeoutMs: number;
+    /** A stop request ends the wait at once (design 14.19). */
+    readonly abort?: AbortSignal | undefined;
+}
+/**
+ * Adapter: the host program's CommitMessageWriter with a time limit (design
+ * 14.19, Decision 135). The writer runs in enmetu's own process, so nothing
+ * can end it: at the limit or a stop request enmetu stops waiting, aborts the
+ * signal it handed over and commits with commitSubject, and a writer that
+ * ignores the signal finishes into nothing. Never throws; a writer's throw,
+ * synchronous or not, is a value.
+ */
+export declare class HostMessageWriterAdapter implements IHostMessageWriter {
+    private readonly writer;
+    private readonly options;
+    constructor(writer: CommitMessageWriter, options: HostMessageWriterOptions);
+    write(input: HostMessageInput): Promise<HostMessageRun>;
+}

package/dist/adapters/host/hostMessageWriterAdapter.js

@@ -0,0 +1,76 @@
+import { errorMessage } from '../../core/errors/errorMessage.js';
+/**
+ * Adapter: the host program's CommitMessageWriter with a time limit (design
+ * 14.19, Decision 135). The writer runs in enmetu's own process, so nothing
+ * can end it: at the limit or a stop request enmetu stops waiting, aborts the
+ * signal it handed over and commits with commitSubject, and a writer that
+ * ignores the signal finishes into nothing. Never throws; a writer's throw,
+ * synchronous or not, is a value.
+ */
+export class HostMessageWriterAdapter {
+    writer;
+    options;
+    constructor(writer, options) {
+        this.writer = writer;
+        this.options = options;
+    }
+    write(input) {
+        const { abort, timeoutMs } = this.options;
+        if (abort?.aborted === true) {
+            return Promise.resolve(stopped());
+        }
+        const handover = new AbortController();
+        const deadline = AbortSignal.timeout(timeoutMs);
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (run) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                deadline.removeEventListener('abort', onDeadline);
+                abort?.removeEventListener('abort', onAbort);
+                resolve(run);
+            };
+            const end = (run) => {
+                handover.abort();
+                settle(run);
+            };
+            const onDeadline = () => end({ kind: 'failed', detail: `took longer than ${timeoutMs} ms` });
+            const onAbort = () => end(stopped());
+            deadline.addEventListener('abort', onDeadline, { once: true });
+            abort?.addEventListener('abort', onAbort, { once: true });
+            let pending;
+            try {
+                pending = Promise.resolve(this.writer({
+                    root: this.options.root,
+                    parent: input.parent,
+                    tree: input.tree,
+                    runCommand: input.runCommand,
+                    signal: handover.signal,
+                }));
+            }
+            catch (error) {
+                settle(threw(error));
+                return;
+            }
+            pending.then((value) => settle(runOf(value)), (error) => settle(threw(error)));
+        });
+    }
+}
+/** A JavaScript host can return anything; only text and null mean something. */
+function runOf(value) {
+    if (typeof value === 'string') {
+        return { kind: 'wrote', text: value };
+    }
+    if (value === null) {
+        return { kind: 'declined' };
+    }
+    return { kind: 'failed', detail: 'returned neither text nor null' };
+}
+function threw(error) {
+    return { kind: 'failed', detail: `threw: ${errorMessage(error)}` };
+}
+function stopped() {
+    return { kind: 'failed', detail: 'was ended because enmetu is stopping' };
+}

package/dist/adapters/process/processGroup.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Plumbing shared by the two adapters that run a child in its own process
+ * group: git with a budget (a repository hook) and commitMessageCommand.
+ */
+/** Keeps the first `cap` bytes of a stream and counts that more arrived. */
+export declare class CappedOutput {
+    private readonly cap;
+    private readonly chunks;
+    private length;
+    dropped: boolean;
+    constructor(cap: number);
+    add(chunk: Buffer): void;
+    bytes(): Buffer;
+    text(): string;
+}
+/** Signals a child's whole process group; a group that is already gone is fine. */
+export declare function killGroup(pid: number | undefined, signal: NodeJS.Signals): void;
+export declare function errorCode(error: unknown): string;

package/dist/adapters/process/processGroup.js

@@ -0,0 +1,52 @@
+import { kill } from 'node:process';
+/**
+ * Plumbing shared by the two adapters that run a child in its own process
+ * group: git with a budget (a repository hook) and commitMessageCommand.
+ */
+/** Keeps the first `cap` bytes of a stream and counts that more arrived. */
+export class CappedOutput {
+    cap;
+    chunks = [];
+    length = 0;
+    dropped = false;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    add(chunk) {
+        const room = this.cap - this.length;
+        if (room <= 0) {
+            this.dropped = this.dropped || chunk.length > 0;
+            return;
+        }
+        const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
+        this.dropped = this.dropped || kept.length < chunk.length;
+        this.chunks.push(kept);
+        this.length += kept.length;
+    }
+    bytes() {
+        return Buffer.concat(this.chunks);
+    }
+    text() {
+        return this.bytes().toString('utf8');
+    }
+}
+/** Signals a child's whole process group; a group that is already gone is fine. */
+export function killGroup(pid, signal) {
+    if (pid === undefined) {
+        return;
+    }
+    try {
+        kill(-pid, signal);
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ESRCH') {
+            throw error;
+        }
+    }
+}
+export function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return typeof error.code === 'string' ? error.code : 'unknown';
+    }
+    return 'unknown';
+}

package/dist/adapters/process/shellMessageCommandAdapter.d.ts

@@ -0,0 +1,24 @@
+import type { CommitMessageCommandInput, CommitMessageCommandRun, ICommitMessageCommand } from '../../contracts/ICommitMessageCommand.js';
+export interface ShellMessageCommandOptions {
+    /** The repository root; the command runs there. */
+    readonly cwd: string;
+    /** The environment the command starts from (Runtime.env); the adapter reads no global environment. */
+    readonly baseEnv: Readonly<Record<string, string | undefined>>;
+    readonly timeoutMs: number;
+    /** stdout beyond this is dropped, never a failure. */
+    readonly outputCapBytes: number;
+    /** A stop request ends a running command at once (design 14.18). */
+    readonly abort?: AbortSignal | undefined;
+}
+/**
+ * Adapter: commitMessageCommand through the shell (design 14.18, Decision
+ * 131). The command leads its own process group, so the time limit and a
+ * stop request end it and everything it started, with SIGKILL at once: a
+ * message writer holds nothing that needs a graceful end, and the commit does
+ * not wait for it. Never throws; every way the command can fail is a value.
+ */
+export declare class ShellMessageCommandAdapter implements ICommitMessageCommand {
+    private readonly options;
+    constructor(options: ShellMessageCommandOptions);
+    run(input: CommitMessageCommandInput): Promise<CommitMessageCommandRun>;
+}

package/dist/adapters/process/shellMessageCommandAdapter.js

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process';
+import { CappedOutput, errorCode, killGroup } from './processGroup.js';
+/** Enough of stderr for the first line the failure names. */
+const STDERR_CAP_BYTES = 4096;
+/**
+ * Adapter: commitMessageCommand through the shell (design 14.18, Decision
+ * 131). The command leads its own process group, so the time limit and a
+ * stop request end it and everything it started, with SIGKILL at once: a
+ * message writer holds nothing that needs a graceful end, and the commit does
+ * not wait for it. Never throws; every way the command can fail is a value.
+ */
+export class ShellMessageCommandAdapter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    run(input) {
+        const { abort, timeoutMs } = this.options;
+        if (abort?.aborted === true) {
+            return Promise.resolve(stopped());
+        }
+        return new Promise((resolve) => {
+            const child = spawn(input.command, {
+                cwd: this.options.cwd,
+                env: commandEnvironment(this.options.baseEnv, input),
+                shell: true,
+                detached: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+            const stdout = new CappedOutput(this.options.outputCapBytes);
+            const stderr = new CappedOutput(STDERR_CAP_BYTES);
+            const deadline = AbortSignal.timeout(timeoutMs);
+            let settled = false;
+            const settle = (run) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                deadline.removeEventListener('abort', onDeadline);
+                abort?.removeEventListener('abort', onAbort);
+                resolve(run);
+            };
+            const end = (run) => {
+                killGroup(child.pid, 'SIGKILL');
+                // A process that left the group (setsid) may still hold the pipes
+                // open; the run ends here regardless.
+                child.stdout.destroy();
+                child.stderr.destroy();
+                settle(run);
+            };
+            const onDeadline = () => end({ kind: 'failed', detail: `timed out after ${timeoutMs} ms` });
+            const onAbort = () => end(stopped());
+            deadline.addEventListener('abort', onDeadline, { once: true });
+            abort?.addEventListener('abort', onAbort, { once: true });
+            child.stdout.on('data', (chunk) => stdout.add(chunk));
+            child.stderr.on('data', (chunk) => stderr.add(chunk));
+            child.on('error', (error) => {
+                settle({
+                    kind: 'failed',
+                    detail: `could not be started in ${this.options.cwd} (${errorCode(error)})`,
+                });
+            });
+            child.on('close', (code, signal) => {
+                if (code === 0) {
+                    settle({ kind: 'printed', stdout: stdout.text() });
+                    return;
+                }
+                const ended = code === null
+                    ? `ended by signal ${signal ?? 'unknown'}`
+                    : `exited ${code}`;
+                const reason = firstLine(stderr.text());
+                settle({
+                    kind: 'failed',
+                    detail: reason === '' ? ended : `${ended}: ${reason}`,
+                });
+            });
+            // A command that ignores its input may exit before reading it; the
+            // resulting EPIPE must not become an uncaught exception.
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(input.stdin);
+        });
+    }
+}
+function stopped() {
+    return { kind: 'failed', detail: 'was ended because enmetu is stopping' };
+}
+/** The base environment plus the commit's parent and tree, so a command can ask git itself. */
+function commandEnvironment(baseEnv, input) {
+    const env = {};
+    for (const [key, value] of Object.entries(baseEnv)) {
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+    env.ENMETU_PARENT = input.parent;
+    env.ENMETU_TREE = input.tree;
+    return env;
+}
+function firstLine(text) {
+    return (text.trim().split('\n')[0] ?? '').trim();
+}

package/dist/adapters/watch/watcherFor.d.ts

@@ -0,0 +1,22 @@
+import type { IWatcher, WatchListener } from '../../contracts/IWatcher.js';
+import type { Runtime } from '../../contracts/runtime.js';
+/** Why no file watch starts under Node on Linux (design 14.20, Decision 137). */
+export declare const NODE_LINUX_WATCH_OFF = "file watching is off under Node on Linux, where its recursive watch can end the process (nodejs/node#66791)";
+/**
+ * Null Object: a watcher that never starts and says so at once, so the
+ * daemon takes its existing path for a lost watch, one WATCHER_FAILED line,
+ * then the poll (Decision 21).
+ */
+export declare class PollOnlyWatcher implements IWatcher {
+    private readonly reason;
+    constructor(reason: string);
+    start(listener: WatchListener): void;
+    close(): void;
+}
+/**
+ * The watcher for a runtime, chosen at the composition root (design 14.20):
+ * Node's recursive fs.watch on Linux throws ENOTDIR, EACCES or ELOOP inside
+ * its own event handler from 24.22.0 on, where no error listener sees it, so
+ * Node on Linux polls; Bun, and Node on every other platform, watch.
+ */
+export declare function watcherFor(root: string, runtime: Pick<Runtime, 'platform' | 'engine'>): IWatcher;

package/dist/adapters/watch/watcherFor.js

@@ -0,0 +1,29 @@
+import { FsWatchAdapter, nodeWatch } from './fsWatchAdapter.js';
+/** Why no file watch starts under Node on Linux (design 14.20, Decision 137). */
+export const NODE_LINUX_WATCH_OFF = 'file watching is off under Node on Linux, where its recursive watch can end the process (nodejs/node#66791)';
+/**
+ * Null Object: a watcher that never starts and says so at once, so the
+ * daemon takes its existing path for a lost watch, one WATCHER_FAILED line,
+ * then the poll (Decision 21).
+ */
+export class PollOnlyWatcher {
+    reason;
+    constructor(reason) {
+        this.reason = reason;
+    }
+    start(listener) {
+        listener.onFailure(this.reason);
+    }
+    close() { }
+}
+/**
+ * The watcher for a runtime, chosen at the composition root (design 14.20):
+ * Node's recursive fs.watch on Linux throws ENOTDIR, EACCES or ELOOP inside
+ * its own event handler from 24.22.0 on, where no error listener sees it, so
+ * Node on Linux polls; Bun, and Node on every other platform, watch.
+ */
+export function watcherFor(root, runtime) {
+    return runtime.platform === 'linux' && runtime.engine === 'node'
+        ? new PollOnlyWatcher(NODE_LINUX_WATCH_OFF)
+        : new FsWatchAdapter(root, nodeWatch);
+}

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

@@ -20,7 +20,8 @@ export interface HookCommandResult {
 /**
  * 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.