@karmaniverous/jeeves-watcher 0.18.9 → 0.18.11

package/dist/cli/jeeves-watcher/index.js

@@ -226,7 +226,7 @@ async function startFromConfig(configPath, descriptor) {
     const config = await loadConfig(resolvedPath);
     // Dynamic import breaks the circular dependency between this module
     // and app/index.ts (which defines JeevesWatcher and re-exports startFromConfig).
-    const { JeevesWatcher } = await import('./index-xP2XrV4W.js');
+    const { JeevesWatcher } = await import('./index-ZbXuE9a7.js');
     const app = new JeevesWatcher(config, resolvedPath, descriptor);
     installShutdownHandlers(() => app.stop());
     await app.start();
@@ -621,6 +621,39 @@ async function retry(fn, options) {
  */
 /** Promisified execFile for git commands. */
 const execFileAsync = promisify(execFile);
+/** Standard timeout (ms) for most git operations. */
+const GIT_TIMEOUT_STANDARD = 30_000;
+/** Extended timeout (ms) for cherry-pick operations. */
+const GIT_TIMEOUT_CHERRY_PICK = 120_000;
+/** Timeout (ms) for push operations. */
+const GIT_TIMEOUT_PUSH = 60_000;
+/**
+ * Extract string fields from a child-process error.
+ * Node's execFile wraps failures in an Error with `stderr`, `stdout`, and
+ * `code` properties that aren't part of the Error type.
+ */
+function getExecErrorFields(error) {
+    if (!(error instanceof Error)) {
+        return { message: String(error), stderr: '', stdout: '' };
+    }
+    const rec = error;
+    const stderr = typeof rec['stderr'] === 'string' ? rec['stderr'] : '';
+    const stdout = typeof rec['stdout'] === 'string' ? rec['stdout'] : '';
+    return { message: error.message || '', stderr, stdout };
+}
+/**
+ * Build an authenticated push URL by injecting a token into an HTTPS remote.
+ * Non-HTTPS URLs are returned as-is.
+ *
+ * @param remoteUrl - The remote repository URL.
+ * @param accessToken - Optional access token to inject.
+ * @returns The URL with the token injected if applicable.
+ */
+function buildAuthenticatedPushUrl(remoteUrl, accessToken) {
+    if (!accessToken)
+        return remoteUrl;
+    return remoteUrl.replace(/^https:\/\//, `https://${encodeURIComponent(accessToken)}@`);
+}
 /**
  * Stage files via stdin to avoid ENAMETOOLONG on Windows.
  *
@@ -632,22 +665,34 @@ const execFileAsync = promisify(execFile);
  *
  * @param files - Absolute paths of files to stage.
  * @param cwd   - Repository root (working directory for git).
+ * @param timeoutMs - Kill the child process after this many milliseconds. Default: 30000.
  */
-function gitAddViaStdin(files, cwd) {
+function gitAddViaStdin(files, cwd, timeoutMs = 30_000) {
     return new Promise((resolve, reject) => {
+        let timedOut = false;
         const child = execFile('git', ['add', '--pathspec-from-file=-', '--pathspec-file-nul'], { cwd }, (error) => {
+            clearTimeout(timer);
+            if (timedOut)
+                return;
             if (error)
                 reject(error);
             else
                 resolve();
         });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+            reject(new Error(`git add timed out after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
         if (!child.stdin) {
+            clearTimeout(timer);
             reject(new Error('Failed to open stdin for git add'));
             return;
         }
         // Suppress EPIPE — expected if git exits before we finish writing
         child.stdin.on('error', (err) => {
             if (err.code !== 'EPIPE') {
+                clearTimeout(timer);
                 reject(err);
             }
         });
@@ -1581,4 +1626,4 @@ const watcherDescriptor = {
 const program = createServiceCli(watcherDescriptor);
 program.parse();
 
-export { CONFIG_WATCH_VALID_SCOPES as C, GitignoreFilter as G, VALID_REINDEX_SCOPES as V, executeReindex as a, gitAddViaStdin as b, normalizePathCase as c, normalizeSlashes as d, execFileAsync as e, findRootForPath as f, getWatchRootBases as g, startFromConfig as h, isPathWatched as i, loadConfig as l, mergeInferenceRules as m, normalizeError as n, retry as r, sleep as s };
+export { CONFIG_WATCH_VALID_SCOPES as C, GIT_TIMEOUT_CHERRY_PICK as G, VALID_REINDEX_SCOPES as V, GIT_TIMEOUT_PUSH as a, GIT_TIMEOUT_STANDARD as b, GitignoreFilter as c, buildAuthenticatedPushUrl as d, execFileAsync as e, executeReindex as f, findRootForPath as g, getExecErrorFields as h, getWatchRootBases as i, gitAddViaStdin as j, isPathWatched as k, loadConfig as l, mergeInferenceRules as m, normalizeError as n, normalizePathCase as o, normalizeSlashes as p, startFromConfig as q, retry as r, sleep as s };

package/dist/index.d.ts

@@ -1276,7 +1276,7 @@ interface PushError {
  * Per-root VCS manager for git-backed content versioning.
  *
  * Each VCS-enabled watch root gets its own VcsManager instance, which owns
- * a debounced commit pipeline: file changes are batched, staged, committed
+ * a throttled commit pipeline: file changes are batched, staged, committed
  * (with optional AI-generated messages), and optionally pushed to a remote.
  *
  * Concurrency: only one commit is in-flight at a time per root. Index.lock
@@ -1293,10 +1293,11 @@ declare class VcsManager {
     private readonly pendingReversions;
     private readonly _pushErrors;
     private readonly squashManager;
-    private debounceTimer;
+    private throttleTimer;
     private commitInFlight;
     private consecutiveCommitFailures;
     private started;
+    private paused;
     private isBaseline;
     private _lastPushTime;
     constructor(rootPath: string, config: VcsConfig, logger: pino.Logger, commitMessageGenerator?: CommitMessageGenerator, remoteUrl?: string, accessToken?: string);
@@ -1306,17 +1307,20 @@ declare class VcsManager {
      * Begin accepting file changes. Sets the manager to started state and
      * starts the squash manager if configured.
      *
+     * Performs startup orphan detection/recovery before starting the squash
+     * manager, ensuring the repo is on the configured branch.
+     *
      * Baseline mode (commit prefix `"baseline:"`) remains active until
      * {@link endBaseline} is called by the coordinator after the initial scan.
      */
-    start(): void;
+    start(): Promise<void>;
     /**
      * Signal that the initial filesystem scan is complete.
      * Clears the baseline flag so subsequent commits use normal "watcher: batch" messages.
      */
     endBaseline(): void;
     /**
-     * Add a file to the pending set and reset the debounce timer.
+     * Add a file to the pending set and start the throttle timer.
      * If the pending set exceeds maxBatchSize, flush immediately.
      *
      * @param filePath - Absolute path of the changed file.
@@ -1335,6 +1339,18 @@ declare class VcsManager {
      * @param filePath - Absolute path of the deleted file.
      */
     handleUnlink(filePath: string): void;
+    /**
+     * Pause the commit pipeline. Drains pending commits via flush(), then
+     * sets a flag that makes commitBatch queue instead of execute.
+     * Used by SquashManager to coordinate squash operations.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the commit pipeline after a pause.
+     * Re-enables normal commit operations and starts a throttle timer
+     * if there are pending files that accumulated during the pause.
+     */
+    resume(): void;
     /**
      * Flush all pending files immediately.
      */
@@ -1348,20 +1364,26 @@ declare class VcsManager {
      */
     private takeBatch;
     /**
-     * Clear the debounce timer.
+     * Clear the throttle timer.
      */
-    private clearDebounce;
+    private clearThrottle;
     /**
-     * Reset the debounce timer to fire flush() after commitDebounceMs.
+     * Start the throttle timer to fire flush() after commitThrottleMs.
+     * If a timer is already running, do not reset it — this is throttle, not debounce.
      */
-    private resetDebounce;
+    private resetThrottle;
     /**
      * Check for and remove stale index.lock files before retrying.
      */
     private removeStaleLock;
+    /**
+     * Check whether a git error represents a "nothing to commit" state.
+     * Git outputs this message to stdout (not stderr) on exit code 1.
+     */
+    private isNothingToCommitError;
     /**
      * Commit a batch of files to the git repo with index.lock retry,
-     * stale lock detection, circuit breaker, and re-queue cap.
+     * stale lock detection, circuit breaker, pause support, and re-queue cap.
      */
     private commitBatch;
 }
@@ -1382,8 +1404,9 @@ declare class VcsCoordinator {
     constructor(config: JeevesWatcherConfig, logger: pino.Logger);
     /**
      * Start all VcsManager instances.
+     * Runs startup orphan detection/recovery for each root.
      */
-    start(): void;
+    start(): Promise<void>;
     /**
      * Route a file event to the correct root's VcsManager.
      *
@@ -1394,8 +1417,8 @@ declare class VcsCoordinator {
     /**
      * Signal that the initial filesystem scan is complete.
      *
-     * Flushes each manager's debounce buffer before ending baseline mode, ensuring
-     * any files still pending in the VCS debounce are committed with a
+     * Flushes each manager's throttle buffer before ending baseline mode, ensuring
+     * any files still pending in the VCS throttle are committed with a
      * `"baseline:"` prefix rather than `"watcher:"`. AI generation is not enabled
      * until all managers have completed their flush.
      */
@@ -1938,15 +1961,31 @@ interface CommitInfo {
  * then cherry-picks retained commits on top. Force-pushes to remote
  * if configured (D13).
  */
+/** Options for SquashManager construction beyond the required params. */
+interface SquashManagerOptions {
+    /** Git branch name for squash operations. Default: "master". */
+    branch?: string;
+    /** Called before squash to drain and pause the commit pipeline. */
+    pauseCommits?: () => Promise<void>;
+    /** Called after squash to resume the commit pipeline. */
+    resumeCommits?: () => void;
+    /** Remote URL for force-push after squash. */
+    remoteUrl?: string;
+    /** Access token for HTTPS push authentication. */
+    accessToken?: string;
+}
 declare class SquashManager {
     private readonly rootPath;
     private readonly retention;
+    private readonly branch;
+    private readonly pauseCommits;
+    private readonly resumeCommits;
     private readonly remoteUrl;
     private readonly accessToken;
     private readonly logger;
     private intervalTimer;
     private running;
-    constructor(rootPath: string, retention: VcsRetentionConfig, logger: pino.Logger, remoteUrl?: string, accessToken?: string);
+    constructor(rootPath: string, retention: VcsRetentionConfig, logger: pino.Logger, options?: SquashManagerOptions);
     /**
      * Start the cron-based squash scheduler.
      * Checks every 60 seconds if the cron expression matches.
@@ -1958,6 +1997,9 @@ declare class SquashManager {
     stop(): void;
     /**
      * Run the squash operation. Exposed publicly for testing.
+     *
+     * Coordinates with VcsManager by calling pause/resume callbacks
+     * to drain and suspend the commit pipeline during the squash.
      */
     runSquash(): Promise<SquashResult>;
     /**
@@ -1977,6 +2019,7 @@ declare class SquashManager {
     calculateRetentionBoundary(commits: CommitInfo[]): number;
     /**
      * Perform the squash: create orphan with baseline + cherry-pick retained commits.
+     * Uses the configured branch name instead of dynamic detection (Bug 1).
      */
     private performSquash;
     /**