@fluado/enmetu 0.1.0 → 0.3.0

package/dist/core/git/porcelain.js

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

package/dist/core/status/statusHeadline.js

@@ -64,7 +64,7 @@ function runningHeadline(record, uncommitted, unpushed) {
             return `attention: pushes failing since ${since}, ${work}`;
         case 'waiting':
             if (record.reason === 'PARTIAL_SELECTION_STAGED') {
-                return `waiting: a partial selection is staged since ${since}; nothing is committed or pulled until it is committed or unstaged, ${work}`;
+                return `waiting: a partial selection is staged since ${since}; nothing is committed or pulled until you commit or unstage it, and after partialStagingWaitMs enmetu commits everything, ${work}`;
             }
             if (record.reason === 'COMMIT_HOOK_REJECTED') {
                 return `waiting: a commit hook rejected the last commit since ${since}, ${work}`;

package/dist/enmetuInstances.d.ts

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

package/dist/enmetuInstances.js

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

package/dist/hooks/preCommitHookInstaller.js

@@ -45,6 +45,16 @@ export class PreCommitHookInstaller {
         //    repository sharing it); writing there would install enmetu into all
         //    of them, so the person adds the line themselves.
         const hooksPath = await this.config.configValue('core.hooksPath');
+        if (hooksPath === '') {
+            // git looks for an empty hooks path's hooks at /<name>, so no hook of
+            // the repository runs (measured with git 2.52.0, design 14.17); there
+            // is no hook to add the line to.
+            return {
+                kind: 'skipped',
+                reason: 'HOOKS_PATH_SET',
+                instruction: 'core.hooksPath is empty, so git runs no hooks and enmetu installs none; unset it to have enmetu install its pre-commit check.',
+            };
+        }
         if (hooksPath !== null) {
             return {
                 kind: 'skipped',

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { ExitCode } from './contracts/exitCode.js';
 export { EXIT } from './contracts/exitCode.js';
 export type { DaemonState, LastCycle, StateInstance, StateReason, StateRecord, StateTransition, } from './contracts/IStateStore.js';
 export type { ITextSink } from './contracts/ITextSink.js';
-export type { EnmetuInstance, EnmetuStartOptions, EnmetuStateView, StateLiveness, } from './contracts/library.js';
+export type { CommitChange, CommitMessageWriter, EnmetuInstance, EnmetuStartOptions, EnmetuStateView, StateLiveness, } from './contracts/library.js';
 export type { ConflictKey, CycleOutcomeKind, PauseReason, WaitReason, } from './contracts/syncTypes.js';
 /** Starts enmetu for the repository containing options.repo, in this process. */
 export declare function startEnmetu(options: EnmetuStartOptions): EnmetuInstance;

package/dist/index.js

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

package/dist/library/enmetuLibrary.d.ts

@@ -5,7 +5,8 @@ import type { Runtime } from '../contracts/runtime.js';
  * without src/index.ts (which reads the process and its own module URL). startEmbedded
  * runs runCommand with createEmbeddedRunDeps: the same locate, git version
  * gate, config and daemon `enmetu run` uses, but with RequestedStopProcessHost,
- * so stop() takes the place of the first SIGTERM. options.repo is resolved
+ * so stop() takes the place of the first SIGTERM, and with the host's
+ * commitMessage writer when it passed one (design 14.19). options.repo is resolved
  * against runtime.cwd. It returns at once; done resolves when the run ends and
  * never rejects: an error runCommand throws is written to the log sink in the
  * form `enmetu: <message>` and mapped by exitCodeFor, like the CLI's main, so a

package/dist/library/enmetuLibrary.js

@@ -9,7 +9,8 @@ import { readStateController } from './readStateController.js';
  * without src/index.ts (which reads the process and its own module URL). startEmbedded
  * runs runCommand with createEmbeddedRunDeps: the same locate, git version
  * gate, config and daemon `enmetu run` uses, but with RequestedStopProcessHost,
- * so stop() takes the place of the first SIGTERM. options.repo is resolved
+ * so stop() takes the place of the first SIGTERM, and with the host's
+ * commitMessage writer when it passed one (design 14.19). options.repo is resolved
  * against runtime.cwd. It returns at once; done resolves when the run ends and
  * never rejects: an error runCommand throws is written to the log sink in the
  * form `enmetu: <message>` and mapped by exitCodeFor, like the CLI's main, so a
@@ -17,7 +18,7 @@ import { readStateController } from './readStateController.js';
  */
 export function startEmbedded(options, runtime) {
     const embedded = embeddedRuntime(options, runtime);
-    const run = createEmbeddedRunDeps(embedded);
+    const run = createEmbeddedRunDeps(embedded, options.commitMessage);
     const done = settledRun({ startDir: resolve(runtime.cwd, options.repo) }, run.deps, embedded.stderr);
     return {
         done,
@@ -41,6 +42,8 @@ function embeddedRuntime(options, runtime) {
         execPath: runtime.execPath,
         cliPath: runtime.cliPath,
         version: runtime.version,
+        platform: runtime.platform,
+        engine: runtime.engine,
         stdout: runtime.stdout,
         stderr: options.log ?? runtime.stderr,
     };

package/dist/quarantine/pathQuarantine.d.ts

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

package/dist/quarantine/pathQuarantine.js

@@ -70,7 +70,13 @@ export class PathQuarantine {
         // --- Step 5: a file written since step 3 is stored again (Decision 114) ---
         await this.storeAgainIfWritten(entries, []);
         // --- Step 6: the held paths now match the index, so the rebase may run ---
-        await this.writer.restoreFromIndex(paths);
+        try {
+            await this.writer.restoreFromIndex(paths);
+        }
+        catch (error) {
+            await this.forgetUnheld(0);
+            throw error;
+        }
         return { kind: 'held', count: entries.length };
     }
     async extend(paths) {
@@ -102,9 +108,45 @@ export class PathQuarantine {
         // --- Step 6: a file written since step 4 is stored again (Decision 114) ---
         await this.storeAgainIfWritten(entries, earlier);
         // --- Step 7: the captured paths now match the index ---
-        await this.writer.restoreFromIndex(paths);
+        try {
+            await this.writer.restoreFromIndex(paths);
+        }
+        catch (error) {
+            await this.forgetUnheld(earlier.length);
+            throw error;
+        }
         return { kind: 'held', count: entries.length };
     }
+    /**
+     * git refused the checkout (a person's merge left a held path unmerged,
+     * design 14.20): an entry whose file still holds the bytes stored for it was
+     * never set aside, and restoring it later would write those bytes over the
+     * person's newer work, conflict markers included. Such entries leave the
+     * memento (the memento goes when none is left); an entry whose file changed
+     * stays, so no write goes unrecorded. Entries before `from` (an earlier
+     * hold that extend added to) stay as they are.
+     */
+    async forgetUnheld(from) {
+        const text = await this.fs.readText(this.mementoPath());
+        const memento = text === null ? null : parseQuarantineMemento(text);
+        if (memento === null) {
+            return;
+        }
+        const kept = memento.entries.slice(0, from);
+        for (const entry of memento.entries.slice(from)) {
+            const target = join(this.paths.root, entry.path);
+            const seen = await this.observe(entry.path, target);
+            if (seen !== (entry.blobId ?? OBSERVED_ABSENT)) {
+                kept.push(entry);
+            }
+        }
+        if (kept.length === 0) {
+            await this.fs.remove(this.mementoPath());
+        }
+        else {
+            await this.writeMemento({ version: 1, entries: kept });
+        }
+    }
     /**
      * git's checkout writes the index's version over a file whatever the file
      * holds, so a write that landed after storeEntries read it would be gone

package/dist/sync/syncCycleController.d.ts

@@ -37,7 +37,7 @@ export interface SyncCycleDeps {
  *    a local one (remote '.') pauses UPSTREAM_NOT_REMOTE (Decision 28).
  * 4. Pending quarantine memento: restore it; failed halts QUARANTINE_RESTORE_FAILED.
  * 5. Commit local changes, skipped on a clean status (which also clears the
- *    memory's stagedSelectionSince): after the status read the repository
+ *    memory's partialStagingSince): after the status read the repository
  *    state is read again (Decision 52), then deps.commit runs with the commit
  *    memory (design 12.7); busy and paused return, committed and nothing go
  *    on, waiting goes on and is the outcome unless a later step returns

package/dist/sync/syncCycleController.js

@@ -23,7 +23,7 @@ export const REBASE_REFUSED_AFTER = 3;
  *    a local one (remote '.') pauses UPSTREAM_NOT_REMOTE (Decision 28).
  * 4. Pending quarantine memento: restore it; failed halts QUARANTINE_RESTORE_FAILED.
  * 5. Commit local changes, skipped on a clean status (which also clears the
- *    memory's stagedSelectionSince): after the status read the repository
+ *    memory's partialStagingSince): after the status read the repository
  *    state is read again (Decision 52), then deps.commit runs with the commit
  *    memory (design 12.7); busy and paused return, committed and nothing go
  *    on, waiting goes on and is the outcome unless a later step returns
@@ -143,7 +143,7 @@ async function runCycle(input, deps, carried, outcome) {
     else if (carried.commitMemory !== undefined) {
         // A clean tree has no staged selection, so a wait for one is over.
         carried.commitMemory = {
-            stagedSelectionSince: null,
+            partialStagingSince: null,
             rejection: carried.commitMemory.rejection,
             residueTree: carried.commitMemory.residueTree,
             lastMove: carried.commitMemory.lastMove,

package/dist/sync/syncCycleRunner.js

@@ -1,7 +1,7 @@
 import { EMPTY_COMMIT_MEMORY, } from '../contracts/syncTypes.js';
 import { errorMessage } from '../core/errors/errorMessage.js';
 const WAITING_MESSAGES = {
-    PARTIAL_SELECTION_STAGED: 'waiting: a partial selection is staged; nothing is committed or pulled until it is committed or unstaged',
+    PARTIAL_SELECTION_STAGED: 'waiting: a partial selection is staged; nothing is committed or pulled until you commit or unstage it, and after partialStagingWaitMs enmetu commits everything',
     COMMIT_HOOK_REJECTED: 'waiting: a commit hook rejected the commit; enmetu tries again when the files change',
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluado/enmetu",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Keeps one git working tree committed and in sync with its upstream.",
   "license": "MIT",
   "author": "fluado UG (haftungsbeschränkt)",