@fluado/enmetu 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,23 @@
-# enmetu
+<p align="center">
+  <img src="logo.svg" width="80" height="80" alt="enmetu">
+</p>
+
+<h1 align="center">enmetu</h1>
 
 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
+
+Most auto-commit tools commit and push. enmetu also handles what goes wrong:
+
+- **Conflicts.** A pull that conflicts is undone and held. Your commits stay local, and enmetu retries when either side changes. It never commits conflict markers and never force-pushes.
+- **No stash.** A file it won't commit (conflict markers, invalid JSON) stays on disk and doesn't block the rest of the sync. Its pre-commit hook applies the same check to your own commits.
+- **Plain git.** You and your agents keep using git. enmetu commits through its own index, waits up to 5 minutes on a partial staging, and pauses during your merge or rebase.
+- **Halts.** A rewritten upstream, or a state it cannot verify, halts it. The halt survives restarts until you run `enmetu resume`.
+- **Status.** `enmetu status` says whether your work is committed and pushed, and during a conflict prints the commands to end it.
+- **Dependencies.** None besides git. Runs under Node or Bun, as a command or as a library.
+- **Tests.** Real git against [28 conflict shapes](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/conflictMatrix.scenario.integration.test.ts) (renames against deletions, binary files, case-only renames, line endings, a merge in progress), [several clones converging on one history](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/convergence.scenario.integration.test.ts), and [a stress test](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/concurrencyStress.scenario.integration.test.ts) where a scripted person runs git next to enmetu as fast as it can, with every write checked against the final history.
+
 ## Prerequisites
 
 - Node 24+ or Bun 1.3.6+
@@ -10,15 +26,31 @@ Commits and syncs a git working tree automatically. Run it inside a repository:
 
 ## Install
 
+### Node
+
 Inside a repository:
 
 ```sh
 npx @fluado/enmetu run
 ```
 
-Pin a version for repeatable runs: `npx @fluado/enmetu@0.1.0 run`.
+As a project dependency: `npm install -D @fluado/enmetu`, then `npx enmetu run`.
 
-In a Node project: `npm install -D @fluado/enmetu`, then `npx enmetu run`.
+### Bun
+
+Inside a repository:
+
+```sh
+bunx --bun @fluado/enmetu run
+```
+
+As a project dependency: `bun add -d @fluado/enmetu`, then `bunx --bun enmetu run`.
+
+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`.
 
 ## Commands
 
@@ -64,11 +96,12 @@ const exitCode = await enmetu.stop()
 | `skipJsonCheck` | `[]` | files exempt from the JSON check, such as `tsconfig.json` |
 | `gitTimeoutMs` | `120000` | timeout per git command |
 | `stateHistory` | `20` | state changes kept in the state file (0 to 100) |
-| `stagedSelection` | `"wait"` | with a partial staging: `"wait"`, or `"commit"` everything |
-| `stagedSelectionMaxWaitMs` | `null` | with `"wait"`: commit everything after this long |
+| `partialStagingWaitMs` | `300000` | with a partial staging: commit everything after this long; `0` at once |
 | `commitHooks` | `true` | run your commit hooks on enmetu's commits |
 | `hookTimeoutMs` | `600000` | timeout per hook |
 
+Unknown settings are logged and ignored.
+
 ## Status
 
 ```
@@ -147,7 +180,7 @@ if command -v enmetu >/dev/null 2>&1; then enmetu hook pre-commit || exit 1; els
 ## Known limitations
 
 - One repository per process. No system service, no notifications.
-- A partial staging pauses sync until you commit or unstage it (`stagedSelection: "wait"`).
+- 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.
 - Under Bun without file-watching permission, enmetu commits on its poll interval.
 - A save during enmetu's pull can be overwritten by git without notice.
@@ -164,6 +197,14 @@ Overlapping git commands:
 | `could not write index` on a refused 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
+
+We built enmetu for ourselves. We use it every day at [fluado](https://fluado.com) and we're sharing it because it might be useful to others.
+
+This is not a community project. We don't have the bandwidth to review PRs, triage issues, or maintain a roadmap for external contributors. If you open an issue with a good idea, we might pick it up when it aligns with what we need. No promises.
+
+Fork it, break it, make it yours. Have fun.
+
 ## Licence
 
 MIT, Copyright (c) 2026 Yves Van Goethem, fluado UG (haftungsbeschränkt). See `LICENSE`.

package/dist/adapters/git/gitLocatorFacade.js

@@ -36,13 +36,16 @@ export class GitLocatorFacade {
         if (insideWorkTree !== 'true') {
             return { kind: 'not-a-repository' };
         }
+        // Not --git-path hooks: it honours core.hooksPath, and git refuses an
+        // empty one as a path (exit 128) although it runs hooks with it; the
+        // installer writes only to the repository's own hooks directory, and only
+        // while core.hooksPath is unset (design 14.17).
         const paths = parseRevParsePaths((await runOk(runner, [
             'rev-parse',
             '--path-format=absolute',
             '--show-toplevel',
             '--git-dir',
-            '--git-path',
-            'hooks',
+            '--git-common-dir',
         ])).stdout.toString('utf8'));
         if (paths === null) {
             throw new PreflightError('a repository path contains a newline, which enmetu does not support', 'PATH_UNSUPPORTED');
@@ -52,7 +55,7 @@ export class GitLocatorFacade {
             paths: {
                 root: paths.root,
                 gitDir: paths.gitDir,
-                hooksDir: paths.hooksDir,
+                hooksDir: join(paths.commonDir, 'hooks'),
                 stateDir: join(paths.gitDir, 'enmetu'),
             },
             version,

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

@@ -22,6 +22,7 @@ export interface HookCommandResult {
  * 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
  *    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.
  * 4. Violations: print the refusal of design 1.18 to stderr, exit 1. None: print nothing, exit 0.
  */

package/dist/cli/commands/hookCommand.js

@@ -9,6 +9,7 @@ const HOOK_CYCLE_ID = 'hook';
  * 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
  *    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.
  * 4. Violations: print the refusal of design 1.18 to stderr, exit 1. None: print nothing, exit 0.
  */
@@ -57,7 +58,8 @@ async function locateOrReason(startDir, deps) {
 }
 async function configForCheck(root, deps) {
     try {
-        return parseConfig(await deps.fs.readText(join(root, CONFIG_FILE_NAME)));
+        return parseConfig(await deps.fs.readText(join(root, CONFIG_FILE_NAME)))
+            .config;
     }
     catch (error) {
         if (!(error instanceof ConfigError)) {

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

@@ -27,7 +27,8 @@ 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.
+ * 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).
  * 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,7 +8,8 @@ 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.
+ * 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).
  * 4. createDaemon(paths, config).run(), its exit code returned.
  */
 export async function runCommand(input, deps) {
@@ -36,9 +37,9 @@ export async function runCommand(input, deps) {
     }
     // --- Step 3: the config at the resolved root, defaults when absent ---
     const configPath = join(paths.root, CONFIG_FILE_NAME);
-    let config;
+    let parsed;
     try {
-        config = parseConfig(await deps.fs.readText(configPath));
+        parsed = parseConfig(await deps.fs.readText(configPath));
     }
     catch (error) {
         if (!(error instanceof ConfigError)) {
@@ -51,6 +52,15 @@ export async function runCommand(input, deps) {
         });
         return { exitCode: EXIT.USAGE };
     }
+    // A key only a newer enmetu knows must not stop this one (design 14.17).
+    for (const key of parsed.unknownKeys) {
+        deps.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() };
 }

package/dist/cli/exitCodes.js

@@ -4,7 +4,6 @@ import { EXIT } from '../contracts/exitCode.js';
 const EXIT_CODE_BY_ERROR = {
     USAGE: EXIT.USAGE,
     CONFIG_INVALID_JSON: EXIT.USAGE,
-    CONFIG_UNKNOWN_KEY: EXIT.USAGE,
     CONFIG_INVALID_VALUE: EXIT.USAGE,
     HALTED: EXIT.HALTED,
     LOCK_HELD: EXIT.LOCKED,

package/dist/commit/commitLocalChangesController.d.ts

@@ -1,4 +1,3 @@
-import type { StagedSelectionMode } from '../contracts/config.js';
 import type { IClock } from '../contracts/IClock.js';
 import type { IFileSystem } from '../contracts/IFileSystem.js';
 import type { IGitCommitter, IGitHookRunner } from '../contracts/IGitCommitter.js';
@@ -33,8 +32,8 @@ export interface CommitIndexGit {
 export interface CommitSettings {
     readonly commitSubject: string;
     readonly skipJsonCheck: readonly string[];
-    readonly stagedSelection: StagedSelectionMode;
-    readonly stagedSelectionMaxWaitMs: number | null;
+    /** How long a partial staging holds the commit back; 0 commits at once (design 14.17). */
+    readonly partialStagingWaitMs: number;
     readonly commitHooks: boolean;
     /** <gitDir>/index, copied to seed the commit index with its stat data. */
     readonly realIndex: string;
@@ -93,9 +92,10 @@ export type CommitLocalChanges = (input: CommitLocalChangesInput) => Promise<Com
  *    differs and memory.lastMove is set, repairStaleIndexController first
  *    (Decision 98): moved, repaired or reverted (Decision 108) forgets lastMove; repaired reads
  *    before and the verdict again, so a stale index is never taken for a
- *    person's selection. "wait"
- *    without a reached cap returns waiting PARTIAL_SELECTION_STAGED; a reached
- *    cap logs SELECTION_WAIT_ENDED and goes on; "commit" goes on.
+ *    person's selection. While less than partialStagingWaitMs has passed
+ *    since memory.partialStagingSince (the first cycle that saw the staging)
+ *    it returns waiting PARTIAL_SELECTION_STAGED; once it has passed it logs
+ *    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.

package/dist/commit/commitLocalChangesController.js

@@ -15,9 +15,10 @@ export const HOOK_RETRY_MS = 600000;
  *    differs and memory.lastMove is set, repairStaleIndexController first
  *    (Decision 98): moved, repaired or reverted (Decision 108) forgets lastMove; repaired reads
  *    before and the verdict again, so a stale index is never taken for a
- *    person's selection. "wait"
- *    without a reached cap returns waiting PARTIAL_SELECTION_STAGED; a reached
- *    cap logs SELECTION_WAIT_ENDED and goes on; "commit" goes on.
+ *    person's selection. While less than partialStagingWaitMs has passed
+ *    since memory.partialStagingSince (the first cycle that saw the staging)
+ *    it returns waiting PARTIAL_SELECTION_STAGED; once it has passed it logs
+ *    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.
@@ -73,24 +74,22 @@ export async function commitLocalChangesController(input, deps) {
         }
     }
     let since = null;
-    if (staged) {
-        if (settings.stagedSelection === 'wait') {
-            since = memory.stagedSelectionSince ?? now;
-            const cap = settings.stagedSelectionMaxWaitMs;
-            if (cap === null || now - since < cap) {
-                return {
-                    kind: 'waiting',
-                    reason: 'PARTIAL_SELECTION_STAGED',
-                    memory: rememberSince(memory, since),
-                };
-            }
-            deps.logger.log({
-                level: 'WARN',
-                code: 'SELECTION_WAIT_ENDED',
-                message: `a staged selection waited ${cap} ms, the configured cap; committing everything, the selection included`,
-                cycleId,
-            });
+    const wait = settings.partialStagingWaitMs;
+    if (staged && wait > 0) {
+        since = memory.partialStagingSince ?? now;
+        if (now - since < wait) {
+            return {
+                kind: 'waiting',
+                reason: 'PARTIAL_SELECTION_STAGED',
+                memory: rememberSince(memory, since),
+            };
         }
+        deps.logger.log({
+            level: 'WARN',
+            code: 'SELECTION_WAIT_ENDED',
+            message: `a staged selection waited ${wait} ms, the configured cap; committing everything, the selection included`,
+            cycleId,
+        });
     }
     const unchanged = rememberSince(memory, since);
     // --- Step 2: build on the commit index, seeded from HEAD ---
@@ -131,7 +130,7 @@ export async function commitLocalChangesController(input, deps) {
                 kind: 'waiting',
                 reason: 'COMMIT_HOOK_REJECTED',
                 memory: {
-                    stagedSelectionSince: since,
+                    partialStagingSince: since,
                     rejection: { tree, at: now },
                     residueTree: memory.residueTree,
                     lastMove: memory.lastMove,
@@ -178,7 +177,7 @@ export async function commitLocalChangesController(input, deps) {
     return {
         kind: 'committed',
         memory: {
-            stagedSelectionSince: null,
+            partialStagingSince: null,
             rejection: null,
             residueTree,
             lastMove: { from: parent, to: commit },
@@ -347,7 +346,7 @@ async function rollBack(branchRef, commit, parent, cycleId, deps) {
 }
 function rememberSince(memory, since) {
     return {
-        stagedSelectionSince: since,
+        partialStagingSince: since,
         rejection: memory.rejection,
         residueTree: memory.residueTree,
         lastMove: memory.lastMove,

package/dist/contracts/IRepositoryLocator.d.ts

@@ -3,7 +3,11 @@ export interface RepositoryPaths {
     readonly root: string;
     /** Per worktree; state files live under it. */
     readonly gitDir: string;
-    /** Effective hooks directory (honours core.hooksPath). */
+    /**
+     * The repository's own hooks directory, <git common dir>/hooks, whatever
+     * core.hooksPath says; git runs hooks from it only while core.hooksPath is
+     * unset, which is also the only case the installer writes there (design 14.17).
+     */
     readonly hooksDir: string;
     /** <gitDir>/enmetu */
     readonly stateDir: string;

package/dist/contracts/config.d.ts

@@ -1,5 +1,3 @@
-/** What enmetu does while a person has a selection staged (design 12.7). */
-export type StagedSelectionMode = 'wait' | 'commit';
 export interface EnmetuConfig {
     readonly quietMs: number;
     readonly maxDelayMs: number;
@@ -10,11 +8,19 @@ export interface EnmetuConfig {
     readonly gitTimeoutMs: number;
     /** Transitions kept in state.json; 0 keeps none (design 12.1). */
     readonly stateHistory: number;
-    readonly stagedSelection: StagedSelectionMode;
-    /** With stagedSelection "wait": commit anyway after this long; null waits without a cap. */
-    readonly stagedSelectionMaxWaitMs: number | null;
+    /**
+     * While a person has a partial staging, how long enmetu waits before it
+     * commits everything, the staging included; 0 commits at once (design 14.17).
+     */
+    readonly partialStagingWaitMs: number;
     /** Run the repository's commit hooks for enmetu's commits (design 12.7). */
     readonly commitHooks: boolean;
     /** How long one repository hook may run before it is a rejection (design 12.7, Decision 83). */
     readonly hookTimeoutMs: number;
 }
+/** What parseConfig read: the config, and the keys it does not know, in file order (design 14.17). */
+export interface ParsedConfig {
+    readonly config: EnmetuConfig;
+    /** Ignored; the run command names each once at start. */
+    readonly unknownKeys: readonly string[];
+}

package/dist/contracts/errors.d.ts

@@ -1,7 +1,7 @@
 import type { HaltCode } from './IHaltStore.js';
-export type EnmetuErrorCode = 'GIT_NOT_FOUND' | 'GIT_TIMEOUT' | 'GIT_ABORTED' | 'GIT_FAILED' | 'GIT_INDEX_LOCKED' | 'GIT_OUTPUT_UNPARSEABLE' | 'CONFIG_INVALID_JSON' | 'CONFIG_UNKNOWN_KEY' | 'CONFIG_INVALID_VALUE' | 'NOT_A_REPOSITORY' | 'BARE_REPOSITORY' | 'GIT_TOO_OLD' | 'PATH_UNSUPPORTED' | 'OPERATION_IN_PROGRESS' | 'DETACHED_HEAD' | 'HEAD_UNBORN' | 'NO_UPSTREAM' | 'UPSTREAM_NOT_REMOTE' | 'IDENTITY_MISSING' | 'LOCK_HELD' | 'LOCK_UNREADABLE' | 'HALTED' | 'USAGE';
+export type EnmetuErrorCode = 'GIT_NOT_FOUND' | 'GIT_TIMEOUT' | 'GIT_ABORTED' | 'GIT_FAILED' | 'GIT_INDEX_LOCKED' | 'GIT_OUTPUT_UNPARSEABLE' | 'CONFIG_INVALID_JSON' | 'CONFIG_INVALID_VALUE' | 'NOT_A_REPOSITORY' | 'BARE_REPOSITORY' | 'GIT_TOO_OLD' | 'PATH_UNSUPPORTED' | 'OPERATION_IN_PROGRESS' | 'DETACHED_HEAD' | 'HEAD_UNBORN' | 'NO_UPSTREAM' | 'UPSTREAM_NOT_REMOTE' | 'IDENTITY_MISSING' | 'LOCK_HELD' | 'LOCK_UNREADABLE' | 'HALTED' | 'USAGE';
 export type GitCommandErrorCode = 'GIT_NOT_FOUND' | 'GIT_TIMEOUT' | 'GIT_ABORTED' | 'GIT_FAILED' | 'GIT_INDEX_LOCKED';
-export type ConfigErrorCode = 'CONFIG_INVALID_JSON' | 'CONFIG_UNKNOWN_KEY' | 'CONFIG_INVALID_VALUE';
+export type ConfigErrorCode = 'CONFIG_INVALID_JSON' | 'CONFIG_INVALID_VALUE';
 export type PreflightErrorCode = 'NOT_A_REPOSITORY' | 'BARE_REPOSITORY' | 'GIT_TOO_OLD' | 'PATH_UNSUPPORTED' | 'OPERATION_IN_PROGRESS' | 'DETACHED_HEAD' | 'HEAD_UNBORN' | 'NO_UPSTREAM' | 'UPSTREAM_NOT_REMOTE' | 'IDENTITY_MISSING';
 export type LockErrorCode = 'LOCK_HELD' | 'LOCK_UNREADABLE';
 export declare class EnmetuError extends Error {

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' | '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' | '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/syncTypes.d.ts

@@ -12,8 +12,8 @@ export type PauseReason = 'FOREIGN_OPERATION' | 'DETACHED_HEAD' | 'NO_UPSTREAM'
  | 'REBASE_REFUSED';
 /**
  * Why a cycle committed nothing although the tree has changes (design 12.7):
- * a person has a selection staged (stagedSelection "wait"), or a repository
- * commit hook rejected enmetu's commit.
+ * a person has a selection staged and partialStagingWaitMs has not passed
+ * (design 14.17), or a repository commit hook rejected enmetu's commit.
  */
 export type WaitReason = 'PARTIAL_SELECTION_STAGED' | 'COMMIT_HOOK_REJECTED';
 export type CycleOutcome = {
@@ -61,7 +61,7 @@ export interface HeadMove {
  */
 export interface CommitMemory {
     /** Epoch ms of the first cycle that found the real index differing from HEAD; null when it does not. */
-    readonly stagedSelectionSince: number | null;
+    readonly partialStagingSince: number | null;
     readonly rejection: HookRejection | null;
     /** The tree a fresh build gave right after enmetu's last commit with hooks; null when hooks left nothing. */
     readonly residueTree: string | null;

package/dist/contracts/syncTypes.js

@@ -1,5 +1,5 @@
 export const EMPTY_COMMIT_MEMORY = {
-    stagedSelectionSince: null,
+    partialStagingSince: null,
     rejection: null,
     residueTree: null,
     lastMove: null,

package/dist/core/commit/commitMemory.js

@@ -1,7 +1,7 @@
 /** The memory with lastMove replaced, every other field kept (Decision 98); the commit step and the cycle both set it. */
 export function withLastMove(memory, lastMove) {
     return {
-        stagedSelectionSince: memory.stagedSelectionSince,
+        partialStagingSince: memory.partialStagingSince,
         rejection: memory.rejection,
         residueTree: memory.residueTree,
         lastMove,

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

@@ -1,5 +1,8 @@
-import type { EnmetuConfig } from '../../contracts/config.js';
+import type { EnmetuConfig, ParsedConfig } from '../../contracts/config.js';
 export declare const CONFIG_FILE_NAME = "enmetu.config.json";
 export declare const DEFAULT_CONFIG: EnmetuConfig;
-/** text null: the file is absent, every default applies. Throws ConfigError. */
-export declare function parseConfig(text: string | null): EnmetuConfig;
+/**
+ * text null: the file is absent, every default applies. Throws ConfigError
+ * for text that does not parse and for an invalid value of a known key.
+ */
+export declare function parseConfig(text: string | null): ParsedConfig;

package/dist/core/config/parseConfig.js

@@ -11,8 +11,7 @@ export const DEFAULT_CONFIG = {
     skipJsonCheck: [],
     gitTimeoutMs: 120000,
     stateHistory: 20,
-    stagedSelection: 'wait',
-    stagedSelectionMaxWaitMs: null,
+    partialStagingWaitMs: 300000,
     commitHooks: true,
     hookTimeoutMs: 600000,
 };
@@ -25,33 +24,32 @@ const KNOWN_KEYS = [
     'skipJsonCheck',
     'gitTimeoutMs',
     'stateHistory',
-    'stagedSelection',
-    'stagedSelectionMaxWaitMs',
+    'partialStagingWaitMs',
     'commitHooks',
     'hookTimeoutMs',
 ];
 const MAX_SUBJECT_CHARACTERS = 100;
-/** The range of stagedSelectionMaxWaitMs and hookTimeoutMs: one second to one day (design 12.7). */
-const MIN_WAIT_MS = 1000;
-const MAX_WAIT_MS = 86400000;
-/** text null: the file is absent, every default applies. Throws ConfigError. */
+/** The range of hookTimeoutMs: one second to one day (design 12.7). */
+const MIN_HOOK_TIMEOUT_MS = 1000;
+const MAX_HOOK_TIMEOUT_MS = 86400000;
+/**
+ * text null: the file is absent, every default applies. Throws ConfigError
+ * for text that does not parse and for an invalid value of a known key.
+ */
 export function parseConfig(text) {
     if (text === null) {
-        return DEFAULT_CONFIG;
+        return { config: DEFAULT_CONFIG, unknownKeys: [] };
     }
     const parsed = parseJson(text);
     if (!isRecord(parsed)) {
         throw new ConfigError('the top level must be a JSON object', 'CONFIG_INVALID_VALUE', null);
     }
-    // Refused rather than ignored, so a misspelt key never falls back to its default.
-    for (const key of Object.keys(parsed)) {
-        if (!KNOWN_KEYS.includes(key)) {
-            throw new ConfigError(`unknown key '${key}'`, 'CONFIG_UNKNOWN_KEY', key);
-        }
-    }
+    // Ignored rather than refused, so a key only a newer enmetu knows never
+    // stops an older one; the caller names each, so a typo is not silent
+    // (design 14.17).
+    const unknownKeys = Object.keys(parsed).filter((key) => !KNOWN_KEYS.includes(key));
     const quietMs = readInteger(parsed, 'quietMs', 100, 600000);
-    const stagedSelection = readStagedSelection(parsed);
-    return {
+    const config = {
         quietMs,
         maxDelayMs: readInteger(parsed, 'maxDelayMs', quietMs, 3600000),
         pollMs: readInteger(parsed, 'pollMs', 100, 3600000),
@@ -60,11 +58,11 @@ export function parseConfig(text) {
         skipJsonCheck: readSkipJsonCheck(parsed),
         gitTimeoutMs: readInteger(parsed, 'gitTimeoutMs', 1000, 3600000),
         stateHistory: readStateHistory(parsed),
-        stagedSelection,
-        stagedSelectionMaxWaitMs: readStagedSelectionMaxWaitMs(parsed, stagedSelection),
+        partialStagingWaitMs: readPartialStagingWaitMs(parsed),
         commitHooks: readBoolean(parsed, 'commitHooks'),
         hookTimeoutMs: readHookTimeoutMs(parsed),
     };
+    return { config, unknownKeys };
 }
 function parseJson(text) {
     try {
@@ -158,39 +156,21 @@ function readSkipJsonCheck(parsed) {
 function readStateHistory(parsed) {
     return readInteger(parsed, 'stateHistory', 0, MAX_STATE_HISTORY);
 }
-/** stagedSelection: "wait" or "commit" (design 12.7). */
-function readStagedSelection(parsed) {
-    const value = parsed.stagedSelection;
-    if (value === undefined) {
-        return DEFAULT_CONFIG.stagedSelection;
-    }
-    if (value === 'wait' || value === 'commit') {
-        return value;
-    }
-    throw invalid('stagedSelection', 'must be "wait" or "commit"');
-}
 /**
- * stagedSelectionMaxWaitMs: null or an integer 1000..86400000, and only with
- * stagedSelection "wait" (a cap on "commit" is a contradiction, refused).
+ * partialStagingWaitMs: an integer of 0 or more (design 14.17). There is no
+ * wait without an end, so null is refused like any other non-integer.
  */
-function readStagedSelectionMaxWaitMs(parsed, mode) {
-    const value = parsed.stagedSelectionMaxWaitMs;
-    if (value === undefined || value === null) {
-        return DEFAULT_CONFIG.stagedSelectionMaxWaitMs;
-    }
-    const rule = `must be null or an integer from ${MIN_WAIT_MS} to ${MAX_WAIT_MS}`;
-    if (typeof value !== 'number' ||
-        !Number.isInteger(value) ||
-        value < MIN_WAIT_MS ||
-        value > MAX_WAIT_MS) {
-        throw invalid('stagedSelectionMaxWaitMs', rule);
+function readPartialStagingWaitMs(parsed) {
+    const value = parsed.partialStagingWaitMs;
+    if (value === undefined) {
+        return DEFAULT_CONFIG.partialStagingWaitMs;
     }
-    if (mode !== 'wait') {
-        throw invalid('stagedSelectionMaxWaitMs', 'is only valid with stagedSelection "wait"');
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw invalid('partialStagingWaitMs', 'must be an integer of 0 or more');
     }
     return value;
 }
 /** hookTimeoutMs: integer 1000..86400000 (design 12.7, Decision 83). */
 function readHookTimeoutMs(parsed) {
-    return readInteger(parsed, 'hookTimeoutMs', MIN_WAIT_MS, MAX_WAIT_MS);
+    return readInteger(parsed, 'hookTimeoutMs', MIN_HOOK_TIMEOUT_MS, MAX_HOOK_TIMEOUT_MS);
 }

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

@@ -27,7 +27,8 @@ export interface BatchBlob {
 export interface RevParsePaths {
     readonly root: string;
     readonly gitDir: string;
-    readonly hooksDir: string;
+    /** --git-common-dir: the main repository's git dir, also from a linked worktree. */
+    readonly commonDir: string;
 }
 /** `git status --porcelain=v1 -z` records; a rename or copy record consumes its source path field. */
 export declare function parseStatus(stdout: Buffer): readonly StatusEntry[];

package/dist/core/git/porcelain.js

@@ -173,11 +173,11 @@ 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 };
 }
 /** 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.js

@@ -292,8 +292,7 @@ function commitOf(parts, paths, config, runtime, hookStop) {
         settings: {
             commitSubject: config.commitSubject,
             skipJsonCheck: config.skipJsonCheck,
-            stagedSelection: config.stagedSelection,
-            stagedSelectionMaxWaitMs: config.stagedSelectionMaxWaitMs,
+            partialStagingWaitMs: config.partialStagingWaitMs,
             commitHooks: config.commitHooks,
             realIndex: join(paths.gitDir, 'index'),
             root: paths.root,

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/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.2.0",
   "description": "Keeps one git working tree committed and in sync with its upstream.",
   "license": "MIT",
   "author": "fluado UG (haftungsbeschränkt)",