@jamesaphoenix/tx-core 0.4.1

package/dist/services/feedback-tracker.d.ts

@@ -0,0 +1,64 @@
+import { Context, Effect, Layer } from "effect";
+import { DatabaseError } from "../errors.js";
+import { EdgeService } from "./edge-service.js";
+/**
+ * Input for recording which learnings were used in a run.
+ */
+export interface LearningUsageFeedback {
+    readonly id: number;
+    readonly helpful: boolean;
+}
+declare const FeedbackTrackerService_base: Context.TagClass<FeedbackTrackerService, "FeedbackTrackerService", {
+    /**
+     * Record which learnings were shown to an agent and whether they were helpful.
+     * Creates USED_IN_RUN edges in the graph for each learning.
+     *
+     * @param runId - Unique identifier for the agent run
+     * @param learnings - Array of learnings with their helpfulness feedback
+     */
+    readonly recordUsage: (runId: string, learnings: readonly LearningUsageFeedback[]) => Effect.Effect<void, DatabaseError>;
+    /**
+     * Get the feedback score for a learning based on historical usage.
+     * Uses Bayesian averaging: (successes + prior) / (total + 2*prior)
+     *
+     * @param learningId - The learning ID to get feedback score for
+     * @returns Score between 0 and 1, with 0.5 being neutral (no feedback)
+     */
+    readonly getFeedbackScore: (learningId: number) => Effect.Effect<number, DatabaseError>;
+    /**
+     * Get feedback scores for multiple learnings in a single batch query.
+     * Uses EdgeService.findFromMultipleSources() to avoid N+1 queries.
+     *
+     * @param learningIds - Array of learning IDs to get feedback scores for
+     * @returns Map from learningId to score (0-1, 0.5 is neutral)
+     */
+    readonly getFeedbackScores: (learningIds: readonly number[]) => Effect.Effect<ReadonlyMap<number, number>, DatabaseError>;
+}>;
+/**
+ * FeedbackTrackerService tracks which learnings were helpful in agent runs
+ * via USED_IN_RUN edges. Uses Bayesian scoring to weight future retrievals.
+ *
+ * Design: DD-016 specifies feedback tracking as part of the graph-expanded
+ * retrieval pipeline. Learnings that are marked helpful receive score boosts.
+ */
+export declare class FeedbackTrackerService extends FeedbackTrackerService_base {
+}
+/**
+ * Noop implementation - returns neutral scores and does nothing on record.
+ * Used when feedback tracking is disabled or for testing.
+ */
+export declare const FeedbackTrackerServiceNoop: Layer.Layer<FeedbackTrackerService, never, never>;
+/**
+ * Live implementation that stores feedback as USED_IN_RUN edges.
+ *
+ * recordUsage: Creates USED_IN_RUN edges from learning to run.
+ * - Weight: 1.0 if helpful, 0.0 if not helpful
+ * - Metadata: { position, recordedAt }
+ *
+ * getFeedbackScore: Calculates Bayesian average from historical edges.
+ * - Formula: (helpfulCount + prior * priorWeight) / (totalCount + priorWeight)
+ * - Returns 0.5 (neutral) for learnings with no feedback.
+ */
+export declare const FeedbackTrackerServiceLive: Layer.Layer<FeedbackTrackerService, never, EdgeService>;
+export {};
+//# sourceMappingURL=feedback-tracker.d.ts.map

package/dist/services/feedback-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-tracker.d.ts","sourceRoot":"","sources":["../../src/services/feedback-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;;IAYG;;;;;;OAMG;0BACmB,CACpB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,qBAAqB,EAAE,KACxC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAEvC;;;;;;OAMG;+BACwB,CACzB,UAAU,EAAE,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAEzC;;;;;;OAMG;gCACyB,CAC1B,WAAW,EAAE,SAAS,MAAM,EAAE,KAC3B,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC;;AA1ClE;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,2BAqCzC;CAAG;AAUN;;;GAGG;AACH,eAAO,MAAM,0BAA0B,mDAUtC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,yDA0FtC,CAAA"}

package/dist/services/feedback-tracker.js

@@ -0,0 +1,110 @@
+import { Context, Effect, Layer } from "effect";
+import { DatabaseError } from "../errors.js";
+import { EdgeService } from "./edge-service.js";
+/**
+ * FeedbackTrackerService tracks which learnings were helpful in agent runs
+ * via USED_IN_RUN edges. Uses Bayesian scoring to weight future retrievals.
+ *
+ * Design: DD-016 specifies feedback tracking as part of the graph-expanded
+ * retrieval pipeline. Learnings that are marked helpful receive score boosts.
+ */
+export class FeedbackTrackerService extends Context.Tag("FeedbackTrackerService")() {
+}
+/**
+ * Bayesian scoring constants.
+ * Prior of 0.5 means neutral (neither helpful nor unhelpful).
+ * Prior weight of 2 provides moderate regularization toward the prior.
+ */
+const BAYESIAN_PRIOR = 0.5;
+const BAYESIAN_PRIOR_WEIGHT = 2;
+/**
+ * Noop implementation - returns neutral scores and does nothing on record.
+ * Used when feedback tracking is disabled or for testing.
+ */
+export const FeedbackTrackerServiceNoop = Layer.succeed(FeedbackTrackerService, {
+    recordUsage: (_runId, _learnings) => Effect.void,
+    getFeedbackScore: (_learningId) => Effect.succeed(0.5),
+    getFeedbackScores: (learningIds) => Effect.succeed(new Map(learningIds.map((id) => [id, 0.5])))
+});
+/**
+ * Live implementation that stores feedback as USED_IN_RUN edges.
+ *
+ * recordUsage: Creates USED_IN_RUN edges from learning to run.
+ * - Weight: 1.0 if helpful, 0.0 if not helpful
+ * - Metadata: { position, recordedAt }
+ *
+ * getFeedbackScore: Calculates Bayesian average from historical edges.
+ * - Formula: (helpfulCount + prior * priorWeight) / (totalCount + priorWeight)
+ * - Returns 0.5 (neutral) for learnings with no feedback.
+ */
+export const FeedbackTrackerServiceLive = Layer.effect(FeedbackTrackerService, Effect.gen(function* () {
+    const edgeService = yield* EdgeService;
+    return {
+        recordUsage: (runId, learnings) => Effect.gen(function* () {
+            const recordedAt = new Date().toISOString();
+            for (let i = 0; i < learnings.length; i++) {
+                const learning = learnings[i];
+                yield* edgeService.createEdge({
+                    edgeType: "USED_IN_RUN",
+                    sourceType: "learning",
+                    sourceId: learning.id.toString(),
+                    targetType: "run",
+                    targetId: runId,
+                    weight: learning.helpful ? 1.0 : 0.0,
+                    metadata: {
+                        position: i,
+                        recordedAt
+                    }
+                }).pipe(
+                // Map ValidationError to DatabaseError - validation errors here would be internal issues
+                Effect.mapError(e => e._tag === "ValidationError"
+                    ? new DatabaseError({ cause: e.reason })
+                    : e));
+            }
+        }),
+        getFeedbackScore: (learningId) => Effect.gen(function* () {
+            // Find all USED_IN_RUN edges from this learning
+            const edges = yield* edgeService.findFromSource("learning", learningId.toString());
+            const usedInRunEdges = edges.filter(e => e.edgeType === "USED_IN_RUN");
+            // No feedback = neutral score
+            if (usedInRunEdges.length === 0) {
+                return BAYESIAN_PRIOR;
+            }
+            // Count helpful (weight > 0) edges
+            const totalCount = usedInRunEdges.length;
+            const helpfulCount = usedInRunEdges.filter(e => e.weight > 0).length;
+            // Bayesian average: (successes + prior * priorWeight) / (total + priorWeight)
+            // = (helpfulCount + 0.5 * 2) / (totalCount + 2)
+            // = (helpfulCount + 1) / (totalCount + 2)
+            return (helpfulCount + BAYESIAN_PRIOR * BAYESIAN_PRIOR_WEIGHT) / (totalCount + BAYESIAN_PRIOR_WEIGHT);
+        }),
+        getFeedbackScores: (learningIds) => Effect.gen(function* () {
+            // Handle empty input
+            if (learningIds.length === 0) {
+                return new Map();
+            }
+            // Batch fetch all edges from all learnings
+            const sourceIds = learningIds.map(id => id.toString());
+            const edgesBySource = yield* edgeService.findFromMultipleSources("learning", sourceIds);
+            // Compute Bayesian score for each learning
+            const result = new Map();
+            for (const learningId of learningIds) {
+                const edges = edgesBySource.get(learningId.toString()) ?? [];
+                const usedInRunEdges = edges.filter(e => e.edgeType === "USED_IN_RUN");
+                // No feedback = neutral score
+                if (usedInRunEdges.length === 0) {
+                    result.set(learningId, BAYESIAN_PRIOR);
+                    continue;
+                }
+                // Count helpful (weight > 0) edges
+                const totalCount = usedInRunEdges.length;
+                const helpfulCount = usedInRunEdges.filter(e => e.weight > 0).length;
+                // Bayesian average
+                const score = (helpfulCount + BAYESIAN_PRIOR * BAYESIAN_PRIOR_WEIGHT) / (totalCount + BAYESIAN_PRIOR_WEIGHT);
+                result.set(learningId, score);
+            }
+            return result;
+        })
+    };
+}));
+//# sourceMappingURL=feedback-tracker.js.map

package/dist/services/feedback-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-tracker.js","sourceRoot":"","sources":["../../src/services/feedback-tracker.ts"],"names":[],"mappings":"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"}

package/dist/services/file-learning-service.d.ts

@@ -0,0 +1,17 @@
+import { Context, Effect, Layer } from "effect";
+import { FileLearningRepository } from "../repo/file-learning-repo.js";
+import { FileLearningNotFoundError, ValidationError, DatabaseError } from "../errors.js";
+import type { FileLearning, CreateFileLearningInput } from "@jamesaphoenix/tx-types";
+declare const FileLearningService_base: Context.TagClass<FileLearningService, "FileLearningService", {
+    readonly create: (input: CreateFileLearningInput) => Effect.Effect<FileLearning, ValidationError | DatabaseError>;
+    readonly get: (id: number) => Effect.Effect<FileLearning, FileLearningNotFoundError | DatabaseError>;
+    readonly remove: (id: number) => Effect.Effect<void, FileLearningNotFoundError | DatabaseError>;
+    readonly getAll: () => Effect.Effect<readonly FileLearning[], DatabaseError>;
+    readonly recall: (path: string) => Effect.Effect<readonly FileLearning[], DatabaseError>;
+    readonly count: () => Effect.Effect<number, DatabaseError>;
+}>;
+export declare class FileLearningService extends FileLearningService_base {
+}
+export declare const FileLearningServiceLive: Layer.Layer<FileLearningService, never, FileLearningRepository>;
+export {};
+//# sourceMappingURL=file-learning-service.d.ts.map

package/dist/services/file-learning-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-learning-service.d.ts","sourceRoot":"","sources":["../../src/services/file-learning-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACtE,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;;qBAK/D,CAAC,KAAK,EAAE,uBAAuB,KAAK,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,eAAe,GAAG,aAAa,CAAC;kBACnG,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,yBAAyB,GAAG,aAAa,CAAC;qBACnF,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,yBAAyB,GAAG,aAAa,CAAC;qBAC9E,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,YAAY,EAAE,EAAE,aAAa,CAAC;qBAC3D,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,YAAY,EAAE,EAAE,aAAa,CAAC;oBACxE,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;;AAR9D,qBAAa,mBAAoB,SAAQ,wBAUtC;CAAG;AAEN,eAAO,MAAM,uBAAuB,iEA8CnC,CAAA"}

package/dist/services/file-learning-service.js

@@ -0,0 +1,41 @@
+import { Context, Effect, Layer } from "effect";
+import { FileLearningRepository } from "../repo/file-learning-repo.js";
+import { FileLearningNotFoundError, ValidationError } from "../errors.js";
+export class FileLearningService extends Context.Tag("FileLearningService")() {
+}
+export const FileLearningServiceLive = Layer.effect(FileLearningService, Effect.gen(function* () {
+    const repo = yield* FileLearningRepository;
+    return {
+        create: (input) => Effect.gen(function* () {
+            if (!input.filePattern || input.filePattern.trim().length === 0) {
+                return yield* Effect.fail(new ValidationError({ reason: "File pattern is required" }));
+            }
+            if (!input.note || input.note.trim().length === 0) {
+                return yield* Effect.fail(new ValidationError({ reason: "Note is required" }));
+            }
+            return yield* repo.insert({
+                ...input,
+                filePattern: input.filePattern.trim(),
+                note: input.note.trim()
+            });
+        }),
+        get: (id) => Effect.gen(function* () {
+            const learning = yield* repo.findById(id);
+            if (!learning) {
+                return yield* Effect.fail(new FileLearningNotFoundError({ id }));
+            }
+            return learning;
+        }),
+        remove: (id) => Effect.gen(function* () {
+            const learning = yield* repo.findById(id);
+            if (!learning) {
+                return yield* Effect.fail(new FileLearningNotFoundError({ id }));
+            }
+            yield* repo.remove(id);
+        }),
+        getAll: () => repo.findAll(),
+        recall: (path) => repo.findByPath(path),
+        count: () => repo.count()
+    };
+}));
+//# sourceMappingURL=file-learning-service.js.map

package/dist/services/file-learning-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-learning-service.js","sourceRoot":"","sources":["../../src/services/file-learning-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACtE,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAiB,MAAM,cAAc,CAAA;AAGxF,MAAM,OAAO,mBAAoB,SAAQ,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,EAUxE;CAAG;AAEN,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC,MAAM,CACjD,mBAAmB,EACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,sBAAsB,CAAA;IAE1C,OAAO;QACL,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAChB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAClB,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAChE,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC,CAAC,CAAA;YACxF,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAClD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAA;YAChF,CAAC;YACD,OAAO,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;gBACxB,GAAG,KAAK;gBACR,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE;gBACrC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;aACxB,CAAC,CAAA;QACJ,CAAC,CAAC;QAEJ,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CACV,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAClB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,yBAAyB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;YAClE,CAAC;YACD,OAAO,QAAQ,CAAA;QACjB,CAAC,CAAC;QAEJ,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CACb,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAClB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,yBAAyB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;YAClE,CAAC;YACD,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACxB,CAAC,CAAC;QAEJ,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE;QAE5B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAEvC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE;KAC1B,CAAA;AACH,CAAC,CAAC,CACH,CAAA"}

package/dist/services/file-watcher-service.d.ts

@@ -0,0 +1,141 @@
+import { Context, Effect, Layer, Queue } from "effect";
+import { FileWatcherError, WatcherAlreadyRunningError, WatcherNotRunningError } from "../errors.js";
+/**
+ * Type of file event detected by the watcher.
+ */
+export type FileEventType = "add" | "change" | "delete";
+/**
+ * Represents a file system event detected by the watcher.
+ */
+export interface FileEvent {
+    /** Type of the event */
+    readonly type: FileEventType;
+    /** Absolute path to the file */
+    readonly path: string;
+    /** Timestamp when the event was detected */
+    readonly timestamp: Date;
+}
+/**
+ * Configuration options for the file watcher.
+ */
+export interface FileWatcherConfig {
+    /** Glob patterns to watch (e.g., "~/.claude/projects/** /*.jsonl") */
+    readonly patterns: readonly string[];
+    /** Debounce delay in milliseconds for rapid file changes */
+    readonly debounceMs?: number;
+    /** Whether to emit events for existing files on start (default: false) */
+    readonly ignoreInitial?: boolean;
+    /** Polling interval in milliseconds (for network drives, etc.) */
+    readonly pollInterval?: number;
+}
+/**
+ * Status information for the file watcher.
+ */
+export interface FileWatcherStatus {
+    /** Whether the watcher is currently running */
+    readonly running: boolean;
+    /** Paths/patterns currently being watched */
+    readonly watchedPaths: readonly string[];
+    /** Timestamp when the watcher was started (null if not running) */
+    readonly startedAt: Date | null;
+    /** Number of events processed since start */
+    readonly eventsProcessed: number;
+}
+declare const FileWatcherService_base: Context.TagClass<FileWatcherService, "FileWatcherService", {
+    /**
+     * Start watching files matching the configured patterns.
+     * Emits FileEvent objects to the event queue.
+     *
+     * @param config - Configuration options for the watcher
+     * @returns Effect that resolves when the watcher is started
+     * @throws WatcherAlreadyRunningError if the watcher is already running
+     * @throws FileWatcherError if the watcher fails to start
+     */
+    readonly start: (config: FileWatcherConfig) => Effect.Effect<void, WatcherAlreadyRunningError | FileWatcherError>;
+    /**
+     * Stop watching files and clean up resources.
+     *
+     * @returns Effect that resolves when the watcher is stopped
+     * @throws WatcherNotRunningError if the watcher is not running
+     * @throws FileWatcherError if the watcher fails to stop cleanly
+     */
+    readonly stop: () => Effect.Effect<void, WatcherNotRunningError | FileWatcherError>;
+    /**
+     * Check if the watcher is currently running.
+     *
+     * @returns Effect that resolves to true if running, false otherwise
+     */
+    readonly isRunning: () => Effect.Effect<boolean>;
+    /**
+     * Get the paths/patterns currently being watched.
+     * Returns an empty array if the watcher is not running.
+     *
+     * @returns Effect that resolves to the list of watched paths
+     */
+    readonly getWatchedPaths: () => Effect.Effect<readonly string[]>;
+    /**
+     * Get the event queue for receiving file events.
+     * Consumers should take events from this queue to process file changes.
+     * The queue is unbounded to avoid blocking the watcher.
+     *
+     * @returns Effect that resolves to the file event queue
+     */
+    readonly getEventQueue: () => Effect.Effect<Queue.Queue<FileEvent>>;
+    /**
+     * Get the current status of the file watcher.
+     *
+     * @returns Effect that resolves to the watcher status
+     */
+    readonly status: () => Effect.Effect<FileWatcherStatus>;
+}>;
+/**
+ * FileWatcherService watches file system paths and emits events when files are
+ * added, changed, or deleted. Events are delivered via an Effect Queue for
+ * decoupled, backpressure-aware processing.
+ *
+ * Used by the telemetry daemon to watch Claude Code transcript files
+ * (~/.claude/projects/** /*.jsonl) and trigger the learning extraction pipeline.
+ *
+ * See DD-015 for the full architecture.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const watcher = yield* FileWatcherService
+ *   const eventQueue = yield* watcher.getEventQueue()
+ *
+ *   // Start watching
+ *   yield* watcher.start({
+ *     patterns: ["~/.claude/projects/** /*.jsonl"],
+ *     debounceMs: 2000
+ *   })
+ *
+ *   // Process events
+ *   while (true) {
+ *     const event = yield* Queue.take(eventQueue)
+ *     yield* Effect.log(`File ${event.type}: ${event.path}`)
+ *   }
+ * })
+ * ```
+ */
+export declare class FileWatcherService extends FileWatcherService_base {
+}
+/**
+ * No-op implementation for testing or when file watching is disabled.
+ * All operations succeed but no actual watching occurs.
+ */
+export declare const FileWatcherServiceNoop: Layer.Layer<FileWatcherService, never, never>;
+/**
+ * Live implementation of FileWatcherService using chokidar.
+ *
+ * Features:
+ * - Uses chokidar for cross-platform file watching
+ * - awaitWriteFinish with 2000ms debounce for chunked writes
+ * - persistent mode to keep process running
+ * - ignoreInitial: false to emit events for existing files
+ * - Effect Queue for backpressure-aware event buffering
+ * - Supports glob patterns (expands ~ and extracts base directories)
+ */
+export declare const FileWatcherServiceLive: Layer.Layer<FileWatcherService, FileWatcherError, never>;
+export {};
+//# sourceMappingURL=file-watcher-service.d.ts.map

package/dist/services/file-watcher-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-watcher-service.d.ts","sourceRoot":"","sources":["../../src/services/file-watcher-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AACtD,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,sBAAsB,EACvB,MAAM,cAAc,CAAA;AAErB;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;;IAmCG;;;;;;;;OAQG;oBACa,CACd,MAAM,EAAE,iBAAiB,KACtB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,0BAA0B,GAAG,gBAAgB,CAAC;IAEvE;;;;;;OAMG;mBACY,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,sBAAsB,GAAG,gBAAgB,CAAC;IAEnF;;;;OAIG;wBACiB,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;IAEhD;;;;;OAKG;8BACuB,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC;IAEhE;;;;;;OAMG;4BACqB,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAEnE;;;;OAIG;qBACc,MAAM,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC;;AApF3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,kBAAmB,SAAQ,uBAwDrC;CAAG;AAEN;;;GAGG;AACH,eAAO,MAAM,sBAAsB,+CAqBlC,CAAA;AAsED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,0DAmOlC,CAAA"}