@karmaniverous/jeeves-watcher 0.17.11 → 0.18.0

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

@@ -2,7 +2,7 @@
 import { substituteEnvVars, DEFAULT_PORTS, postJson, fetchJson, getPackageVersion, createServiceCli } from '@karmaniverous/jeeves';
 import { dirname, resolve, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { jeevesWatcherConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
+import { jeevesWatcherConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, extractWatchPathStrings, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
 import { packageDirectorySync } from 'package-directory';
 import { readFileSync, existsSync, mkdirSync, renameSync, statSync, readdirSync } from 'node:fs';
 import { cosmiconfig } from 'cosmiconfig';
@@ -224,7 +224,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-DXiOIyDK.js');
+    const { JeevesWatcher } = await import('./index-DtyqhT2s.js');
     const app = new JeevesWatcher(config, resolvedPath, descriptor);
     installShutdownHandlers(() => app.stop());
     await app.start();
@@ -891,7 +891,7 @@ async function computePrunePlan(deps) {
                     continue;
                 }
                 seenFiles.add(filePath);
-                const watched = isPathWatched(filePath, config.watch.paths, config.watch.ignored);
+                const watched = isPathWatched(filePath, extractWatchPathStrings(config.watch.paths), config.watch.ignored);
                 const gitignored = gitignoreFilter
                     ? gitignoreFilter.isIgnored(filePath)
                     : false;
@@ -911,7 +911,7 @@ async function computePrunePlan(deps) {
         incomplete = true;
     }
     const orphanedFileList = [...orphanedFiles];
-    const byRoot = groupByRoot(orphanedFileList, config.watch.paths);
+    const byRoot = groupByRoot(orphanedFileList, extractWatchPathStrings(config.watch.paths));
     return {
         plan: {
             total: totalPoints,
@@ -1027,18 +1027,18 @@ async function executeReindex(deps, scope, path, dryRun = false) {
     }
     else if (scope === 'rules' && pathArray && pathArray.length > 0) {
         // Rules scope with path filter: list from watch roots intersected with caller globs
-        fileList = await listFilesFromWatchRoots(config.watch.paths, config.watch.ignored, pathArray, isGitignored);
+        fileList = await listFilesFromWatchRoots(extractWatchPathStrings(config.watch.paths), config.watch.ignored, pathArray, isGitignored);
     }
     else {
         // rules or full: list files from globs
-        fileList = await listFilesFromGlobs(config.watch.paths, config.watch.ignored, isGitignored);
+        fileList = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
     }
     if (fileList !== undefined) {
         plan = {
             total: fileList.length,
             toProcess: fileList.length,
             toDelete: 0,
-            byRoot: groupByRoot(fileList, config.watch.paths),
+            byRoot: groupByRoot(fileList, extractWatchPathStrings(config.watch.paths)),
         };
     }
     if (dryRun) {
@@ -1049,7 +1049,7 @@ async function executeReindex(deps, scope, path, dryRun = false) {
                 total: pathFiles.length,
                 toProcess: pathFiles.length,
                 toDelete: 0,
-                byRoot: groupByRoot(pathFiles, config.watch.paths),
+                byRoot: groupByRoot(pathFiles, extractWatchPathStrings(config.watch.paths)),
             };
         }
         return { filesProcessed: 0, durationMs: 0, errors: 0, plan };
@@ -1076,7 +1076,7 @@ async function executeReindex(deps, scope, path, dryRun = false) {
             });
         }
         else if (scope === 'rules') {
-            filesProcessed = await processAllFiles(config.watch.paths, config.watch.ignored, processor, 'processRulesUpdate', concurrency, {
+            filesProcessed = await processAllFiles(extractWatchPathStrings(config.watch.paths), config.watch.ignored, processor, 'processRulesUpdate', concurrency, {
                 onTotal: (total) => reindexTracker?.setTotal(total),
                 onFileProcessed: () => reindexTracker?.incrementProcessed(),
             }, isGitignored, fileList);
@@ -1087,7 +1087,7 @@ async function executeReindex(deps, scope, path, dryRun = false) {
                 total: uniqueFiles.length,
                 toProcess: uniqueFiles.length,
                 toDelete: 0,
-                byRoot: groupByRoot(uniqueFiles, config.watch.paths),
+                byRoot: groupByRoot(uniqueFiles, extractWatchPathStrings(config.watch.paths)),
             };
             reindexTracker?.setTotal(uniqueFiles.length);
             await parallel(concurrency, uniqueFiles, async (filePath) => {
@@ -1098,7 +1098,7 @@ async function executeReindex(deps, scope, path, dryRun = false) {
         }
         else {
             // Full reindex
-            filesProcessed = await processAllFiles(config.watch.paths, config.watch.ignored, processor, 'processFile', concurrency, {
+            filesProcessed = await processAllFiles(extractWatchPathStrings(config.watch.paths), config.watch.ignored, processor, 'processFile', concurrency, {
                 onTotal: (total) => reindexTracker?.setTotal(total),
                 onFileProcessed: () => reindexTracker?.incrementProcessed(),
             }, isGitignored, fileList);
@@ -1146,7 +1146,7 @@ async function collectPathFiles(pathArray, config, gitignoreFilter) {
  * Get the file list for a path-scoped reindex (for plan computation).
  */
 async function getPathFileList(targetPath, config, gitignoreFilter) {
-    const watched = isPathWatched(targetPath, config.watch.paths, config.watch.ignored);
+    const watched = isPathWatched(targetPath, extractWatchPathStrings(config.watch.paths), config.watch.ignored);
     if (!watched) {
         throw new Error(`Path is outside watch scope: ${targetPath}`);
     }
@@ -1158,7 +1158,7 @@ async function getPathFileList(targetPath, config, gitignoreFilter) {
         return [targetPath];
     if (stats.isDirectory()) {
         const isGitignored = createIsGitignored(gitignoreFilter);
-        const allWatchedFiles = await listFilesFromGlobs(config.watch.paths, config.watch.ignored, isGitignored);
+        const allWatchedFiles = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
         const targetAbsPath = resolve(targetPath);
         return allWatchedFiles.filter((f) => resolve(f).startsWith(targetAbsPath));
     }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { JeevesComponentDescriptor } from '@karmaniverous/jeeves';
 import { FastifyInstance } from 'fastify';
 import pino from 'pino';
-import { EmbeddingConfig, InferenceRule, SchemaEntry, VectorStoreConfig, WatchConfig, JeevesWatcherConfig, LoggingConfig } from '@karmaniverous/jeeves-watcher-core';
+import { EmbeddingConfig, InferenceRule, SchemaEntry, VectorStoreConfig, VcsConfig, JeevesWatcherConfig, WatchConfig, LoggingConfig, VcsRetentionConfig } from '@karmaniverous/jeeves-watcher-core';
 export { ApiConfig, ConfigWatchConfig, EmbeddingConfig, InferenceRule, JeevesWatcherConfig, JeevesWatcherConfigInput, LoggingConfig, VectorStoreConfig, WatchConfig, apiConfigSchema, configWatchConfigSchema, embeddingConfigSchema, inferenceRuleSchema, jeevesWatcherConfigSchema, loggingConfigSchema, vectorStoreConfigSchema, watchConfigSchema } from '@karmaniverous/jeeves-watcher-core';
 import { z } from 'zod';
 import Handlebars from 'handlebars';
@@ -1227,6 +1227,192 @@ declare class EventQueue {
     private maybeResolveIdleWorkers;
 }
 
+/**
+ * @module vcs/CommitMessageGenerator
+ * Generates AI-powered commit messages via the Anthropic Messages API.
+ */
+
+/**
+ * Generates AI commit messages using the Anthropic Messages API.
+ */
+declare class CommitMessageGenerator {
+    private readonly provider;
+    private readonly model;
+    private readonly apiKey;
+    private readonly logger;
+    constructor(provider: string, model: string, apiKey: string | undefined, logger: pino.Logger);
+    /**
+     * Generate a commit message from file changes.
+     *
+     * @param files - List of changed file paths.
+     * @param diffSummary - Combined diff output (stat + patch).
+     * @returns A one-line commit message, or null on failure.
+     */
+    generate(files: string[], diffSummary: string): Promise<string | null>;
+}
+
+/**
+ * @module vcs/VcsManager
+ * Per-root VCS manager for git-backed content versioning.
+ */
+
+/** Metadata for a pending reversion to include in the commit message. */
+interface PendingReversion {
+    glob: string;
+    commit: string;
+    paths: string[];
+}
+/** Push error record for status reporting. */
+interface PushError {
+    timestamp: string;
+    message: string;
+}
+/**
+ * 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
+ * (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
+ * contention is handled with exponential backoff retries (D10).
+ */
+declare class VcsManager {
+    readonly config: VcsConfig;
+    readonly rootPath: string;
+    readonly remoteUrl: string | undefined;
+    private readonly accessToken;
+    private readonly logger;
+    private readonly commitMessageGenerator;
+    private readonly pending;
+    private readonly pendingReversions;
+    private readonly _pushErrors;
+    private readonly squashManager;
+    private debounceTimer;
+    private commitInFlight;
+    private started;
+    private _lastPushTime;
+    constructor(rootPath: string, config: VcsConfig, logger: pino.Logger, commitMessageGenerator?: CommitMessageGenerator, remoteUrl?: string, accessToken?: string);
+    get lastPushTime(): string | null;
+    get pushErrors(): readonly PushError[];
+    /**
+     * Begin accepting file changes. Sets up the debounce mechanism.
+     */
+    start(): void;
+    /**
+     * Add a file to the pending set and reset the debounce timer.
+     * If the pending set exceeds maxBatchSize, flush immediately.
+     *
+     * @param filePath - Absolute path of the changed file.
+     */
+    fileChanged(filePath: string): void;
+    /**
+     * Record reversion metadata so the next commit uses a revert-prefixed message.
+     *
+     * @param reversion - The reversion metadata to record.
+     */
+    addPendingReversion(reversion: PendingReversion): void;
+    /**
+     * Stage a file deletion and add to pending set.
+     * git add handles deleted files when the file is gone from disk.
+     *
+     * @param filePath - Absolute path of the deleted file.
+     */
+    handleUnlink(filePath: string): void;
+    /**
+     * Flush all pending files immediately.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop accepting file changes, flush pending, and clean up timers.
+     */
+    stop(): Promise<void>;
+    /**
+     * Take up to N items from the pending set.
+     */
+    private takeBatch;
+    /**
+     * Clear the debounce timer.
+     */
+    private clearDebounce;
+    /**
+     * Reset the debounce timer to fire flush() after commitDebounceMs.
+     */
+    private resetDebounce;
+    /**
+     * Get the cached diff for staged files, for AI context.
+     */
+    private getStagedDiff;
+    /**
+     * Build the template commit message (no AI).
+     */
+    private buildTemplateMessage;
+    /**
+     * Build the commit message, using AI when available with template fallback.
+     */
+    private buildCommitMessage;
+    /**
+     * Commit a batch of files to the git repo with index.lock retry.
+     */
+    private commitBatch;
+    /**
+     * Push to the configured remote if remoteUrl is set.
+     * On failure: logs the error and records it in pushErrors; never throws.
+     */
+    private pushIfConfigured;
+}
+
+/**
+ * @module vcs/VcsCoordinator
+ * Orchestrates VCS across all watch roots. Routes file events to the correct
+ * root's VcsManager instance.
+ */
+
+/**
+ * Orchestrates VCS across all VCS-enabled watch roots.
+ */
+declare class VcsCoordinator {
+    private readonly managers;
+    private readonly roots;
+    private readonly logger;
+    constructor(config: JeevesWatcherConfig, logger: pino.Logger);
+    /**
+     * Start all VcsManager instances.
+     */
+    start(): void;
+    /**
+     * Route a file event to the correct root's VcsManager.
+     *
+     * @param filePath - Absolute path of the changed file.
+     * @param event - The event type: add, change, or unlink.
+     */
+    onFileChange(filePath: string, event: 'add' | 'change' | 'unlink'): void;
+    /**
+     * Flush all managers and clean up.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the sorted root paths (longest-first).
+     */
+    getRoots(): readonly string[];
+    /**
+     * Get the VcsManager for a specific root path.
+     */
+    getManager(root: string): VcsManager | undefined;
+    /**
+     * Get all managers as [root, manager] pairs.
+     */
+    getAllManagers(): ReadonlyMap<string, VcsManager>;
+    /**
+     * Find the VcsManager that owns the given normalized file path.
+     * Uses longest-prefix-match against resolved watch roots.
+     *
+     * @param normalizedPath - Normalized absolute path (forward slashes).
+     * @returns The matching VcsManager, or undefined.
+     */
+    findManagerForPath(normalizedPath: string): VcsManager | undefined;
+}
+
 /**
  * @module api/InitialScanTracker
  * Tracks initial filesystem scan state for status reporting.
@@ -1344,6 +1530,8 @@ interface FileSystemWatcherOptions {
     initialScanTracker?: InitialScanTracker;
     /** Optional content hash cache for move detection. */
     contentHashCache?: ContentHashCache;
+    /** Optional callback for VCS file change notifications. */
+    onVcsFileChange?: (filePath: string, event: 'add' | 'change' | 'unlink') => void;
 }
 /**
  * Filesystem watcher that maps chokidar events to the processing queue.
@@ -1357,6 +1545,7 @@ declare class FileSystemWatcher {
     private readonly gitignoreFilter?;
     private readonly initialScanTracker?;
     private readonly contentHashCache?;
+    private readonly onVcsFileChange?;
     private moveCorrelator?;
     private globMatches;
     private watcher;
@@ -1496,6 +1685,8 @@ interface ApiServerOptions {
     getFileSystemWatcher?: () => FileSystemWatcher | undefined;
     /** Optional enrichment store for persisted enrichment metadata. */
     enrichmentStore?: EnrichmentStoreInterface;
+    /** VCS coordinator for git-backed versioning API routes. */
+    vcsCoordinator?: VcsCoordinator;
 }
 /**
  * Create the Fastify API server with all routes registered.
@@ -1601,6 +1792,7 @@ declare class JeevesWatcher {
     private gitignoreFilter;
     private enrichmentStore;
     private contentHashCache;
+    private vcsCoordinator;
     private readonly initialScanTracker;
     private readonly version;
     /** Create a new JeevesWatcher instance. */
@@ -1685,5 +1877,91 @@ declare function contentHash(text: string): string;
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-export { ContentHashCache, DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, VirtualRuleStore, applyRules, buildAttributes, buildTemplateEngine, compileRules, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, extractText, issueRecordSchema, loadConfig, loadCustomHelpers, mergeEnrichment, pointId, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, watcherDescriptor };
-export type { AllHelpersIntrospection, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingProvider, EnrichmentStoreInterface, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, InitialScanStatus, IssueRecord, IssuesFile, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, PayloadFieldSchema, ProcessFn, ProcessorConfig, ProviderFactory, ReindexStatus, RenderResult, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStore, WatchEvent };
+/**
+ * @module vcs/resolveWatchRoot
+ * Resolves which VCS-enabled watch root(s) own a given absolute path or glob.
+ */
+
+/** Result of resolving a path to its watch root. */
+interface ResolvedWatchRoot {
+    /** Absolute root path (normalized forward slashes). */
+    root: string;
+    /** Path relative to the root. */
+    relativePath: string;
+}
+
+/**
+ * @module vcs/SquashManager
+ * Handles scheduled squash retention for git-backed VCS roots.
+ */
+
+/** Result of a squash operation. */
+interface SquashResult {
+    squashed: boolean;
+    commitsRemoved?: number;
+    commitsRetained?: number;
+    error?: string;
+}
+/** Commit metadata for retention calculation. */
+interface CommitInfo {
+    hash: string;
+    date: Date;
+}
+/**
+ * Manages scheduled squash retention for a single VCS root.
+ *
+ * Runs on a cron schedule (checked every 60s). When triggered, squashes
+ * commits older than the retention boundary (the tighter of maxAgeDays
+ * and maxVersions) into a single "historical baseline" orphan commit,
+ * then cherry-picks retained commits on top. Force-pushes to remote
+ * if configured (D13).
+ */
+declare class SquashManager {
+    private readonly rootPath;
+    private readonly retention;
+    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);
+    /**
+     * Start the cron-based squash scheduler.
+     * Checks every 60 seconds if the cron expression matches.
+     */
+    start(): void;
+    /**
+     * Stop the cron scheduler.
+     */
+    stop(): void;
+    /**
+     * Run the squash operation. Exposed publicly for testing.
+     */
+    runSquash(): Promise<SquashResult>;
+    /**
+     * Get all commits in chronological order (oldest first).
+     */
+    getCommitLog(): Promise<CommitInfo[]>;
+    /**
+     * Calculate the retention boundary index.
+     * Returns the index of the oldest commit to KEEP.
+     * All commits before this index will be squashed into a baseline.
+     *
+     * Strategy: find the tighter constraint between age and count.
+     * - Age: keep commits newer than maxAgeDays
+     * - Count: keep the last maxVersions commits
+     * The boundary is the one that retains FEWER old commits (tighter).
+     */
+    calculateRetentionBoundary(commits: CommitInfo[]): number;
+    /**
+     * Perform the squash: create orphan with baseline + cherry-pick retained commits.
+     */
+    private performSquash;
+    /**
+     * Force push to remote after squash (history rewrite requires force).
+     */
+    private forcePushIfConfigured;
+}
+
+export { CommitMessageGenerator, ContentHashCache, DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SquashManager, SystemHealth, TemplateEngine, ValuesManager, VcsCoordinator, VcsManager, VectorStoreClient, VirtualRuleStore, applyRules, buildAttributes, buildTemplateEngine, compileRules, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, extractText, issueRecordSchema, loadConfig, loadCustomHelpers, mergeEnrichment, pointId, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, watcherDescriptor };
+export type { AllHelpersIntrospection, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CollectionInfo, CommitInfo, CompiledRule, CompiledTemplate, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingProvider, EnrichmentStoreInterface, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, InitialScanStatus, IssueRecord, IssuesFile, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, PayloadFieldSchema, PendingReversion, ProcessFn, ProcessorConfig, ProviderFactory, PushError, ReindexStatus, RenderResult, ResolvedWatchRoot, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SquashResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStore, WatchEvent };