haroo 1.0.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "haroo",
+  "version": "1.0.0",
+  "description": "AI-powered personal logging CLI with memory, diary, and calendar features",
+  "main": "dist/index.js",
+  "bin": {
+    "haroo": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "keywords": [
+    "cli",
+    "ai",
+    "logging",
+    "diary",
+    "memory",
+    "langchain"
+  ],
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "module": "index.ts",
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outdir ./dist --target node",
+    "prepublishOnly": "bun run build && bun run test",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:file": "bun test",
+    "test:watch": "bun test --watch",
+    "lint": "eslint . --fix && prettier --write .",
+    "lint:check": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "prepare": "husky"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@langchain/core": "^0.3.54",
+    "@langchain/langgraph": "^0.3.4",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "dotenv": "^17.2.3",
+    "inquirer": "^13.1.0",
+    "ora": "^9.0.0",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

package/src/__tests__/e2e/EventService.test.ts

@@ -0,0 +1,211 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { EventService } from "../../application/services/EventService";
+import type { Event } from "../../domain/entities/Event";
+import type { IEventsRepository } from "../../domain/interfaces/IEventsRepository";
+
+// Mock repository for testing
+class MockEventsRepository implements IEventsRepository {
+  private events: Map<string, Event> = new Map();
+
+  async create(event: Event): Promise<Event> {
+    this.events.set(event.id, event);
+    return event;
+  }
+
+  async getById(id: string): Promise<Event | null> {
+    return this.events.get(id) || null;
+  }
+
+  async getByDateRange(start: Date, end: Date): Promise<Event[]> {
+    const events = Array.from(this.events.values());
+    return events.filter((event) => {
+      return event.datetime >= start && event.datetime < end;
+    });
+  }
+
+  async getToday(): Promise<Event[]> {
+    const now = new Date();
+    const startOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const endOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1);
+    return this.getByDateRange(startOfDay, endOfDay);
+  }
+
+  async searchByTitle(query: string): Promise<Event[]> {
+    const events = Array.from(this.events.values());
+    return events.filter((event) => event.title.toLowerCase().includes(query.toLowerCase()));
+  }
+
+  async update(id: string, data: Partial<Event>): Promise<Event | null> {
+    const event = this.events.get(id);
+    if (!event) return null;
+
+    const updated = { ...event, ...data };
+    this.events.set(id, updated);
+    return updated;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    return this.events.delete(id);
+  }
+
+  async getUpcoming(limit = 10): Promise<Event[]> {
+    const now = new Date();
+    const events = Array.from(this.events.values());
+    return events
+      .filter((event) => event.datetime >= now)
+      .sort((a, b) => a.datetime.getTime() - b.datetime.getTime())
+      .slice(0, limit);
+  }
+
+  // Helper for testing
+  clear(): void {
+    this.events.clear();
+  }
+}
+
+describe("EventService E2E", () => {
+  let repository: MockEventsRepository;
+  let service: EventService;
+
+  beforeEach(() => {
+    repository = new MockEventsRepository();
+    service = new EventService(repository);
+  });
+
+  describe("Event lifecycle", () => {
+    it("should create, retrieve, update, and delete an event", async () => {
+      // Create
+      const eventData = {
+        title: "Team Meeting",
+        datetime: new Date("2024-03-15T10:00:00Z"),
+        notes: "Discuss Q1 goals",
+        tags: ["work", "meeting"],
+      };
+
+      const created = await service.add(eventData);
+      expect(created.id).toBeDefined();
+      expect(created.title).toBe("Team Meeting");
+      expect(created.createdAt).toBeInstanceOf(Date);
+
+      // Retrieve
+      const retrieved = await service.getById(created.id);
+      expect(retrieved).not.toBeNull();
+      expect(retrieved?.title).toBe("Team Meeting");
+
+      // Update
+      const updated = await service.update(created.id, {
+        title: "Updated Team Meeting",
+        notes: "Discuss Q1 and Q2 goals",
+      });
+      expect(updated.title).toBe("Updated Team Meeting");
+      expect(updated.notes).toBe("Discuss Q1 and Q2 goals");
+
+      // Delete
+      const deleted = await service.delete(created.id);
+      expect(deleted).toBe(true);
+
+      const afterDelete = await service.getById(created.id);
+      expect(afterDelete).toBeNull();
+    });
+  });
+
+  describe("Date-based queries", () => {
+    beforeEach(async () => {
+      // Create test events
+      await service.add({
+        title: "Event 1",
+        datetime: new Date("2024-03-15T10:00:00Z"),
+        tags: [],
+      });
+
+      await service.add({
+        title: "Event 2",
+        datetime: new Date("2024-03-15T14:00:00Z"),
+        tags: [],
+      });
+
+      await service.add({
+        title: "Event 3",
+        datetime: new Date("2024-03-16T10:00:00Z"),
+        tags: [],
+      });
+    });
+
+    it("should retrieve events by specific date", async () => {
+      const events = await service.getByDate(new Date("2024-03-15"));
+      expect(events).toHaveLength(2);
+      expect(events.every((e) => e.title.startsWith("Event"))).toBe(true);
+    });
+
+    it("should retrieve events by date range", async () => {
+      const start = new Date("2024-03-15T00:00:00Z");
+      const end = new Date("2024-03-17T00:00:00Z");
+      const events = await service.getByRange(start, end);
+      expect(events).toHaveLength(3);
+    });
+
+    it("should retrieve upcoming events", async () => {
+      // This test depends on current date, so we'll just check it returns an array
+      const events = await service.getUpcoming(7);
+      expect(Array.isArray(events)).toBe(true);
+    });
+  });
+
+  describe("Search functionality", () => {
+    beforeEach(async () => {
+      await service.add({
+        title: "Team Meeting",
+        datetime: new Date("2024-03-15T10:00:00Z"),
+        tags: [],
+      });
+
+      await service.add({
+        title: "Client Call",
+        datetime: new Date("2024-03-15T14:00:00Z"),
+        tags: [],
+      });
+
+      await service.add({
+        title: "Team Building",
+        datetime: new Date("2024-03-16T10:00:00Z"),
+        tags: [],
+      });
+    });
+
+    it("should search events by title", async () => {
+      const results = await service.search("team");
+      expect(results).toHaveLength(2);
+      expect(results.every((e) => e.title.toLowerCase().includes("team"))).toBe(true);
+    });
+
+    it("should return empty array for non-matching search", async () => {
+      const results = await service.search("nonexistent");
+      expect(results).toHaveLength(0);
+    });
+
+    it("should be case-insensitive", async () => {
+      const results = await service.search("TEAM");
+      expect(results).toHaveLength(2);
+    });
+  });
+
+  describe("Error handling", () => {
+    it("should throw error when updating non-existent event", async () => {
+      const fakeId = "550e8400-e29b-41d4-a716-446655440000";
+
+      await expect(service.update(fakeId, { title: "Updated" })).rejects.toThrow(
+        `Event with id ${fakeId} not found`
+      );
+    });
+
+    it("should return null when getting non-existent event", async () => {
+      const result = await service.getById("550e8400-e29b-41d4-a716-446655440000");
+      expect(result).toBeNull();
+    });
+
+    it("should return false when deleting non-existent event", async () => {
+      const result = await service.delete("550e8400-e29b-41d4-a716-446655440000");
+      expect(result).toBe(false);
+    });
+  });
+});

package/src/__tests__/unit/Event.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "bun:test";
+import { EventSchema } from "../../domain/entities/Event";
+
+describe("Event Entity", () => {
+  describe("EventSchema validation", () => {
+    it("should validate a valid event with required fields", () => {
+      const validEvent = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        title: "Team Meeting",
+        datetime: new Date("2024-01-15T10:00:00Z"),
+      };
+
+      const result = EventSchema.safeParse(validEvent);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.title).toBe("Team Meeting");
+        expect(result.data.tags).toEqual([]);
+      }
+    });
+
+    it("should validate an event with all optional fields", () => {
+      const fullEvent = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        title: "Conference",
+        datetime: new Date("2024-03-20T09:00:00Z"),
+        endTime: new Date("2024-03-20T17:00:00Z"),
+        notes: "Annual tech conference",
+        tags: ["work", "conference", "networking"],
+      };
+
+      const result = EventSchema.safeParse(fullEvent);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.tags).toHaveLength(3);
+        expect(result.data.notes).toBe("Annual tech conference");
+      }
+    });
+
+    it("should reject event with invalid UUID", () => {
+      const invalidEvent = {
+        id: "not-a-uuid",
+        title: "Meeting",
+        datetime: new Date(),
+      };
+
+      const result = EventSchema.safeParse(invalidEvent);
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject event with empty title", () => {
+      const invalidEvent = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        title: "",
+        datetime: new Date(),
+      };
+
+      const result = EventSchema.safeParse(invalidEvent);
+      expect(result.success).toBe(false);
+    });
+
+    it("should coerce string dates to Date objects", () => {
+      const eventWithStringDate = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        title: "Meeting",
+        datetime: "2024-01-15T10:00:00Z",
+      };
+
+      const result = EventSchema.safeParse(eventWithStringDate);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.datetime).toBeInstanceOf(Date);
+      }
+    });
+
+    it("should set default createdAt if not provided", () => {
+      const event = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        title: "Meeting",
+        datetime: new Date(),
+      };
+
+      const result = EventSchema.safeParse(event);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.createdAt).toBeInstanceOf(Date);
+      }
+    });
+  });
+});

package/src/__tests__/unit/Memory.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "bun:test";
+import { MemorySchema } from "../../domain/entities/Memory";
+
+describe("Memory Entity", () => {
+  describe("MemorySchema validation", () => {
+    it("should validate a valid memory with all required fields", () => {
+      const validMemory = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        type: "fact" as const,
+        content: "User prefers dark mode",
+        lastAccessed: new Date("2024-01-15T10:00:00Z"),
+        createdAt: new Date("2024-01-01T00:00:00Z"),
+      };
+
+      const result = MemorySchema.safeParse(validMemory);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.type).toBe("fact");
+        expect(result.data.importance).toBe(5); // default value
+      }
+    });
+
+    it("should validate memory with custom importance", () => {
+      const memory = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        type: "preference" as const,
+        content: "User loves TypeScript",
+        importance: 9,
+        lastAccessed: new Date(),
+        createdAt: new Date(),
+      };
+
+      const result = MemorySchema.safeParse(memory);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.importance).toBe(9);
+      }
+    });
+
+    it("should validate memory with optional source", () => {
+      const memory = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        type: "routine" as const,
+        content: "User checks email at 9 AM",
+        source: "conversation-2024-01-15",
+        lastAccessed: new Date(),
+        createdAt: new Date(),
+      };
+
+      const result = MemorySchema.safeParse(memory);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.source).toBe("conversation-2024-01-15");
+      }
+    });
+
+    it("should validate all memory types", () => {
+      const types = ["fact", "preference", "routine", "relationship"] as const;
+
+      for (const type of types) {
+        const memory = {
+          id: "550e8400-e29b-41d4-a716-446655440000",
+          type,
+          content: `Test ${type}`,
+          lastAccessed: new Date(),
+          createdAt: new Date(),
+        };
+
+        const result = MemorySchema.safeParse(memory);
+        expect(result.success).toBe(true);
+      }
+    });
+
+    it("should reject memory with invalid type", () => {
+      const invalidMemory = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        type: "invalid-type",
+        content: "Some content",
+        lastAccessed: new Date(),
+        createdAt: new Date(),
+      };
+
+      const result = MemorySchema.safeParse(invalidMemory);
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject memory with importance out of range", () => {
+      const memoryTooHigh = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        type: "fact" as const,
+        content: "Test",
+        importance: 11,
+        lastAccessed: new Date(),
+        createdAt: new Date(),
+      };
+
+      const resultHigh = MemorySchema.safeParse(memoryTooHigh);
+      expect(resultHigh.success).toBe(false);
+
+      const memoryTooLow = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        type: "fact" as const,
+        content: "Test",
+        importance: 0,
+        lastAccessed: new Date(),
+        createdAt: new Date(),
+      };
+
+      const resultLow = MemorySchema.safeParse(memoryTooLow);
+      expect(resultLow.success).toBe(false);
+    });
+
+    it("should coerce string dates to Date objects", () => {
+      const memory = {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        type: "fact" as const,
+        content: "Test content",
+        lastAccessed: "2024-01-15T10:00:00Z",
+        createdAt: "2024-01-01T00:00:00Z",
+      };
+
+      const result = MemorySchema.safeParse(memory);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.lastAccessed).toBeInstanceOf(Date);
+        expect(result.data.createdAt).toBeInstanceOf(Date);
+      }
+    });
+  });
+});

package/src/application/graph/builder.ts

@@ -0,0 +1,106 @@
+import type { BaseCheckpointSaver } from "@langchain/langgraph";
+import { END, START, StateGraph } from "@langchain/langgraph";
+import type { ILanguageModel } from "../../domain/interfaces/ILanguageModel";
+import type {
+  EmbeddingFunction,
+  IMemoriesRepository,
+} from "../../domain/interfaces/IMemoriesRepository";
+import { GraphState, type GraphStateType } from "../../domain/state/AgentState";
+import type { EventService } from "../services/EventService";
+import { routeByIntent, shouldExtractMemory } from "./edges";
+import type { ToolRegistry } from "./nodes";
+import {
+  addEventNode,
+  chatNode,
+  extractMemoryNode,
+  toolExecutorNode,
+  hasToolCalls,
+  routerNode,
+  respondNode,
+  queryNode,
+} from "./nodes";
+
+export interface GraphConfig {
+  llm: ILanguageModel;
+  tools: ToolRegistry;
+  eventService: EventService;
+  memoriesRepository: IMemoriesRepository;
+  embeddingFn?: EmbeddingFunction;
+  checkpointer?: BaseCheckpointSaver;
+}
+
+/**
+ * Determines whether to execute tools or proceed to respond.
+ * If the chat node returned tool calls, route to toolExecutor.
+ */
+function shouldExecuteTools(state: GraphStateType): "toolExecutor" | "respond" {
+  if (hasToolCalls(state)) {
+    return "toolExecutor";
+  }
+  return "respond";
+}
+
+/**
+ * Builds and compiles the LangGraph StateGraph with all nodes and edges.
+ *
+ * Graph Flow:
+ *   START → router → [conditional]
+ *                       ├── "add_event" → addEvent → respond → extractMemory → END
+ *                       ├── "query" → query → respond → END
+ *                       └── "chat" → chat → [conditional]
+ *                                              ├── hasToolCalls → toolExecutor → chat (loop)
+ *                                              └── noToolCalls → respond → extractMemory → END
+ */
+export function buildGraph(config: GraphConfig) {
+  const graph = new StateGraph(GraphState)
+    // Add all nodes with their dependencies
+    .addNode("router", (state: GraphStateType) => routerNode(state, { llm: config.llm }))
+    .addNode("addEvent", (state: GraphStateType) =>
+      addEventNode(state, { llm: config.llm, eventService: config.eventService })
+    )
+    .addNode("query", (state: GraphStateType) =>
+      queryNode(state, { llm: config.llm, eventService: config.eventService })
+    )
+    .addNode("chat", (state: GraphStateType) =>
+      chatNode(state, { llm: config.llm, tools: config.tools })
+    )
+    .addNode("toolExecutor", (state: GraphStateType) =>
+      toolExecutorNode(state, { tools: config.tools })
+    )
+    .addNode("respond", respondNode)
+    .addNode("extractMemory", (state: GraphStateType) =>
+      extractMemoryNode(state, {
+        llm: config.llm,
+        memoriesRepository: config.memoriesRepository,
+        embeddingFn: config.embeddingFn,
+      })
+    )
+    // Define edges
+    .addEdge(START, "router")
+    .addConditionalEdges("router", routeByIntent)
+    .addEdge("addEvent", "respond")
+    .addEdge("query", "respond")
+    // Chat can trigger tool execution loop
+    .addConditionalEdges("chat", shouldExecuteTools)
+    .addEdge("toolExecutor", "chat") // Loop back to chat after tool execution
+    .addConditionalEdges("respond", shouldExtractMemory)
+    .addEdge("extractMemory", END);
+
+  // Compile with optional checkpointer for state persistence
+  return graph.compile({
+    checkpointer: config.checkpointer,
+  });
+}
+
+/**
+ * Runs the graph with the given initial state.
+ * This is a convenience wrapper that builds and invokes the graph.
+ */
+export async function runGraph(
+  initialState: GraphStateType,
+  config: GraphConfig
+): Promise<GraphStateType> {
+  const compiledGraph = buildGraph(config);
+  const result = await compiledGraph.invoke(initialState);
+  return result as GraphStateType;
+}

package/src/application/graph/edges.ts

@@ -0,0 +1,37 @@
+import { END } from "@langchain/langgraph";
+import type { GraphStateType } from "../../domain/state/AgentState";
+
+/**
+ * Routes from the router node based on the classified intent.
+ * Maps each intent to its corresponding handler node.
+ */
+export function routeByIntent(state: GraphStateType): "addEvent" | "query" | "chat" {
+  const intent = state.intent;
+
+  switch (intent) {
+    case "add_event":
+      return "addEvent";
+    case "query":
+      return "query";
+    default:
+      return "chat";
+  }
+}
+
+/**
+ * Determines whether to extract memories after responding.
+ * Memory extraction is performed for add_event and chat intents,
+ * as these are likely to contain useful information to remember.
+ * Query intents are read-only operations and skip memory extraction.
+ */
+export function shouldExtractMemory(state: GraphStateType): "extractMemory" | typeof END {
+  const intent = state.intent;
+
+  // Extract memories for add_event and chat intents
+  // Skip for query intents (read-only operations)
+  if (intent === "add_event" || intent === "chat") {
+    return "extractMemory";
+  }
+
+  return END;
+}