cognitive-core 0.1.0 → 0.2.0

package/references/minimem/src/cli/commands/conflicts.ts

@@ -0,0 +1,413 @@
+/**
+ * minimem sync:conflicts - Conflict management commands
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+import {
+  resolveMemoryDir,
+  isInitialized,
+  formatPath,
+  getSyncConfig,
+  exitWithError,
+  warn,
+} from "../config.js";
+import {
+  listQuarantinedConflicts,
+  getConflictsDir,
+  getShadowsDir,
+} from "../sync/conflicts.js";
+import { getSyncStatePath, loadSyncState } from "../sync/state.js";
+
+export type ConflictsOptions = {
+  dir?: string;
+  global?: boolean;
+  json?: boolean;
+};
+
+/**
+ * List all quarantined conflicts
+ */
+export async function conflictsCommand(options: ConflictsOptions): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.dir,
+    global: options.global,
+  });
+
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(`${formatPath(memoryDir)} is not initialized.`);
+  }
+
+  try {
+    const conflicts = await listQuarantinedConflicts(memoryDir);
+
+    if (options.json) {
+      console.log(JSON.stringify(conflicts, null, 2));
+      return;
+    }
+
+    if (conflicts.length === 0) {
+      console.log("No quarantined conflicts.");
+      return;
+    }
+
+    console.log(`Quarantined conflicts in ${formatPath(memoryDir)}`);
+    console.log("-".repeat(50));
+
+    for (const conflict of conflicts) {
+      console.log(`\n${conflict.timestamp}:`);
+      for (const file of conflict.files) {
+        console.log(`  - ${file}`);
+      }
+    }
+
+    console.log(`\nTotal: ${conflicts.length} conflict set(s)`);
+    console.log("\nUse 'minimem sync:resolve <timestamp>' to resolve a conflict.");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithError(message);
+  }
+}
+
+export type ResolveOptions = {
+  dir?: string;
+  global?: boolean;
+  tool?: string;
+};
+
+/**
+ * Resolve a quarantined conflict
+ */
+export async function resolveCommand(
+  timestamp: string,
+  options: ResolveOptions
+): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.dir,
+    global: options.global,
+  });
+
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(`${formatPath(memoryDir)} is not initialized.`);
+  }
+
+  const conflictDir = path.join(getConflictsDir(memoryDir), timestamp);
+
+  try {
+    await fs.access(conflictDir);
+  } catch {
+    exitWithError(
+      `Conflict '${timestamp}' not found.`,
+      "Use 'minimem sync:conflicts' to list available conflicts."
+    );
+  }
+
+  try {
+    const files = await fs.readdir(conflictDir);
+
+    // Group files by base name
+    const fileGroups = new Map<string, { local?: string; remote?: string; base?: string }>();
+    for (const file of files) {
+      const match = file.match(/^(.+)\.(local|remote|base)$/);
+      if (match) {
+        const [, baseName, type] = match;
+        if (!fileGroups.has(baseName)) {
+          fileGroups.set(baseName, {});
+        }
+        const group = fileGroups.get(baseName)!;
+        group[type as "local" | "remote" | "base"] = path.join(conflictDir, file);
+      }
+    }
+
+    if (fileGroups.size === 0) {
+      exitWithError("No conflict files found in this directory.");
+    }
+
+    // Determine merge tool
+    const mergeTool = options.tool || process.env.MERGE_TOOL || await detectMergeTool();
+
+    if (!mergeTool) {
+      console.log("No merge tool detected. Available conflict files:");
+      for (const [baseName, group] of fileGroups) {
+        console.log(`\n${baseName.replace(/_/g, "/")}:`);
+        if (group.local) console.log(`  Local:  ${group.local}`);
+        if (group.remote) console.log(`  Remote: ${group.remote}`);
+        if (group.base) console.log(`  Base:   ${group.base}`);
+      }
+      console.log("\nManually edit the files or set MERGE_TOOL environment variable.");
+      return;
+    }
+
+    console.log(`Using merge tool: ${mergeTool}`);
+
+    for (const [baseName, group] of fileGroups) {
+      const fileName = baseName.replace(/_/g, "/");
+      console.log(`\nResolving: ${fileName}`);
+
+      if (group.local && group.remote) {
+        // Launch merge tool
+        const args = group.base
+          ? [group.local, group.base, group.remote]
+          : [group.local, group.remote];
+
+        const child = spawn(mergeTool, args, { stdio: "inherit" });
+
+        await new Promise<void>((resolve, reject) => {
+          child.on("close", (code) => {
+            if (code === 0) {
+              resolve();
+            } else {
+              reject(new Error(`Merge tool exited with code ${code}`));
+            }
+          });
+          child.on("error", reject);
+        });
+      }
+    }
+
+    console.log("\nMerge complete. Remove conflict directory when satisfied:");
+    console.log(`  rm -rf "${conflictDir}"`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithError(message);
+  }
+}
+
+/**
+ * Detect available merge tool
+ */
+async function detectMergeTool(): Promise<string | null> {
+  const tools = ["code", "meld", "kdiff3", "vimdiff", "opendiff"];
+
+  for (const tool of tools) {
+    try {
+      const { execSync } = await import("node:child_process");
+      execSync(`which ${tool}`, { stdio: "ignore" });
+      return tool;
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+export type CleanupOptions = {
+  dir?: string;
+  global?: boolean;
+  days?: number;
+  dryRun?: boolean;
+};
+
+/**
+ * Clean up old quarantined conflicts
+ */
+export async function cleanupCommand(options: CleanupOptions): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.dir,
+    global: options.global,
+  });
+
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(`${formatPath(memoryDir)} is not initialized.`);
+  }
+
+  const maxAgeDays = options.days ?? 30;
+  const cutoffDate = new Date(Date.now() - maxAgeDays * 24 * 60 * 60 * 1000);
+
+  try {
+    const conflictsDir = getConflictsDir(memoryDir);
+    let entries: string[] = [];
+
+    try {
+      entries = await fs.readdir(conflictsDir);
+    } catch {
+      console.log("No conflicts directory found.");
+      return;
+    }
+
+    let cleaned = 0;
+    let kept = 0;
+
+    for (const entry of entries) {
+      // Timestamps are in ISO format with : and . replaced with -
+      // e.g., 2026-02-03T07-20-56-704Z
+      const timestamp = entry.replace(/-(\d{2})-(\d{2})-(\d{3})Z$/, ":$1:$2.$3Z");
+      const entryDate = new Date(timestamp);
+
+      if (isNaN(entryDate.getTime())) {
+        console.log(`  Skipping invalid timestamp: ${entry}`);
+        continue;
+      }
+
+      const entryPath = path.join(conflictsDir, entry);
+
+      if (entryDate < cutoffDate) {
+        if (options.dryRun) {
+          console.log(`  Would remove: ${entry}`);
+        } else {
+          await fs.rm(entryPath, { recursive: true, force: true });
+          console.log(`  Removed: ${entry}`);
+        }
+        cleaned++;
+      } else {
+        kept++;
+      }
+    }
+
+    if (options.dryRun) {
+      console.log(`\nWould remove ${cleaned} conflict(s), keep ${kept}`);
+    } else {
+      console.log(`\nRemoved ${cleaned} conflict(s), kept ${kept}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithError(message);
+  }
+}
+
+/**
+ * Sync logging
+ */
+const SYNC_LOG_FILE = "sync.log";
+const MAX_LOG_ENTRIES = 1000;
+
+export type SyncLogEntry = {
+  timestamp: string;
+  operation: "push" | "pull" | "sync";
+  result: "success" | "partial" | "failure";
+  pushed?: number;
+  pulled?: number;
+  conflicts?: number;
+  errors?: string[];
+};
+
+/**
+ * Get sync log path
+ */
+export function getSyncLogPath(memoryDir: string): string {
+  return path.join(memoryDir, ".minimem", SYNC_LOG_FILE);
+}
+
+/**
+ * Append to sync log
+ */
+export async function appendSyncLog(
+  memoryDir: string,
+  entry: SyncLogEntry
+): Promise<void> {
+  const logPath = getSyncLogPath(memoryDir);
+
+  try {
+    await fs.mkdir(path.dirname(logPath), { recursive: true });
+
+    // Read existing log
+    let entries: SyncLogEntry[] = [];
+    try {
+      const content = await fs.readFile(logPath, "utf-8");
+      entries = content
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+    } catch {
+      // No existing log
+    }
+
+    // Add new entry and trim if needed
+    entries.push(entry);
+    if (entries.length > MAX_LOG_ENTRIES) {
+      entries = entries.slice(-MAX_LOG_ENTRIES);
+    }
+
+    // Write back
+    const content = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    await fs.writeFile(logPath, content);
+  } catch (error) {
+    // Log failures are non-fatal
+    const message = error instanceof Error ? error.message : String(error);
+    warn(`Failed to write sync log: ${message}`);
+  }
+}
+
+/**
+ * Read sync log
+ */
+export async function readSyncLog(memoryDir: string): Promise<SyncLogEntry[]> {
+  const logPath = getSyncLogPath(memoryDir);
+
+  try {
+    const content = await fs.readFile(logPath, "utf-8");
+    return content
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+export type LogOptions = {
+  dir?: string;
+  global?: boolean;
+  limit?: number;
+  json?: boolean;
+};
+
+/**
+ * Show sync log
+ */
+export async function logCommand(options: LogOptions): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.dir,
+    global: options.global,
+  });
+
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(`${formatPath(memoryDir)} is not initialized.`);
+  }
+
+  try {
+    let entries = await readSyncLog(memoryDir);
+
+    const limit = options.limit ?? 20;
+    entries = entries.slice(-limit);
+
+    if (options.json) {
+      console.log(JSON.stringify(entries, null, 2));
+      return;
+    }
+
+    if (entries.length === 0) {
+      console.log("No sync history.");
+      return;
+    }
+
+    console.log(`Sync history for ${formatPath(memoryDir)}`);
+    console.log("-".repeat(60));
+
+    for (const entry of entries) {
+      const time = new Date(entry.timestamp).toLocaleString();
+      const status =
+        entry.result === "success" ? "OK" :
+        entry.result === "partial" ? "PARTIAL" : "FAILED";
+
+      let details = "";
+      if (entry.pushed) details += ` +${entry.pushed}`;
+      if (entry.pulled) details += ` -${entry.pulled}`;
+      if (entry.conflicts) details += ` !${entry.conflicts}`;
+
+      console.log(`${time}  ${entry.operation.padEnd(6)}  ${status.padEnd(8)}${details}`);
+
+      if (entry.errors && entry.errors.length > 0) {
+        for (const error of entry.errors.slice(0, 3)) {
+          console.log(`    Error: ${error}`);
+        }
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithError(message);
+  }
+}

package/references/minimem/src/cli/commands/daemon.ts

@@ -0,0 +1,169 @@
+/**
+ * minimem daemon - Background sync daemon commands
+ */
+
+import fs from "node:fs/promises";
+
+import {
+  startDaemon,
+  startDaemonBackground,
+  stopDaemon,
+  getDaemonStatus,
+  isDaemonRunning,
+  getDaemonLogPath,
+} from "../sync/daemon.js";
+import { exitWithError } from "../config.js";
+
+export type DaemonOptions = {
+  background?: boolean;
+  foreground?: boolean;
+};
+
+/**
+ * Start the daemon
+ */
+export async function daemonCommand(options: DaemonOptions): Promise<void> {
+  // If --foreground is specified, run in foreground (used by background spawn)
+  if (options.foreground) {
+    console.log("Starting daemon in foreground...");
+    try {
+      await startDaemon();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      exitWithError(`Daemon: ${message}`);
+    }
+    return;
+  }
+
+  // Check if already running
+  if (await isDaemonRunning()) {
+    console.log("Daemon is already running.");
+    console.log("Use 'minimem daemon:stop' to stop it.");
+    return;
+  }
+
+  if (options.background) {
+    console.log("Starting daemon in background...");
+    try {
+      const pid = await startDaemonBackground();
+      console.log(`Daemon started with PID ${pid}`);
+      console.log(`Log file: ${getDaemonLogPath()}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      exitWithError(`Failed to start daemon: ${message}`);
+    }
+  } else {
+    console.log("Starting daemon in foreground...");
+    console.log("Press Ctrl+C to stop.");
+    console.log("");
+    try {
+      await startDaemon();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      exitWithError(`Daemon: ${message}`);
+    }
+  }
+}
+
+/**
+ * Stop the daemon
+ */
+export async function daemonStopCommand(): Promise<void> {
+  const status = await getDaemonStatus();
+
+  if (!status.running) {
+    console.log("Daemon is not running.");
+    return;
+  }
+
+  console.log(`Stopping daemon (PID ${status.pid})...`);
+
+  const stopped = await stopDaemon();
+
+  if (stopped) {
+    console.log("Daemon stopped.");
+  } else {
+    exitWithError("Failed to stop daemon.");
+  }
+}
+
+/**
+ * Show daemon status
+ */
+export async function daemonStatusCommand(): Promise<void> {
+  const status = await getDaemonStatus();
+
+  if (status.running) {
+    console.log("Daemon status: running");
+    console.log(`  PID: ${status.pid}`);
+    console.log(`  Log: ${getDaemonLogPath()}`);
+  } else {
+    console.log("Daemon status: stopped");
+  }
+}
+
+export type LogOptions = {
+  lines?: number;
+  follow?: boolean;
+};
+
+/**
+ * Show daemon logs
+ */
+export async function daemonLogsCommand(options: LogOptions): Promise<void> {
+  const logPath = getDaemonLogPath();
+
+  try {
+    const content = await fs.readFile(logPath, "utf-8");
+    const lines = content.split("\n").filter(Boolean);
+
+    const numLines = options.lines ?? 50;
+    const displayLines = lines.slice(-numLines);
+
+    for (const line of displayLines) {
+      console.log(line);
+    }
+
+    if (options.follow) {
+      console.log("\n--- Following log (Ctrl+C to stop) ---\n");
+
+      // Simple follow implementation using polling
+      let lastSize = (await fs.stat(logPath)).size;
+
+      const poll = async () => {
+        try {
+          const stats = await fs.stat(logPath);
+          if (stats.size > lastSize) {
+            const fd = await fs.open(logPath, "r");
+            const buffer = Buffer.alloc(stats.size - lastSize);
+            await fd.read(buffer, 0, buffer.length, lastSize);
+            await fd.close();
+
+            process.stdout.write(buffer.toString());
+            lastSize = stats.size;
+          }
+        } catch {
+          // File may have been rotated
+          lastSize = 0;
+        }
+      };
+
+      const interval = setInterval(poll, 1000);
+
+      process.on("SIGINT", () => {
+        clearInterval(interval);
+        process.exit(0);
+      });
+
+      // Keep running
+      await new Promise(() => {});
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      console.log("No daemon log found.");
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      exitWithError(`Error reading log: ${message}`);
+    }
+  }
+}

package/references/minimem/src/cli/commands/index.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI Commands
+ */
+
+export { init, type InitOptions } from "./init.js";
+export { search, type SearchOptions } from "./search.js";
+export { sync, type SyncOptions } from "./sync.js";
+export { status, type StatusOptions } from "./status.js";
+export { append, type AppendOptions } from "./append.js";
+export { upsert, type UpsertOptions } from "./upsert.js";
+export { mcp, type McpOptions } from "./mcp.js";
+export { config, type ConfigOptions } from "./config.js";

package/references/minimem/src/cli/commands/init.ts

@@ -0,0 +1,88 @@
+/**
+ * minimem init - Initialize memory directory
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  resolveMemoryDir,
+  saveConfig,
+  getInitConfig,
+  isInitialized,
+  formatPath,
+} from "../config.js";
+
+const MEMORY_TEMPLATE = `# Memory
+
+This is your memory file. Add notes, decisions, and context here.
+
+## Quick Start
+
+- Add daily logs in the \`memory/\` directory (e.g., \`memory/2024-01-15.md\`)
+- Use \`minimem search <query>\` to find relevant memories
+- Use \`minimem append <text>\` to quickly add to today's log
+
+## Notes
+
+`;
+
+export type InitOptions = {
+  global?: boolean;
+  force?: boolean;
+};
+
+export async function init(
+  dir: string | undefined,
+  options: InitOptions,
+): Promise<void> {
+  const memoryDir = resolveMemoryDir({ dir, global: options.global });
+  const displayPath = formatPath(memoryDir);
+
+  // Check if already initialized
+  if (!options.force && (await isInitialized(memoryDir))) {
+    console.log(`Already initialized: ${displayPath}`);
+    console.log("Use --force to reinitialize");
+    return;
+  }
+
+  console.log(`Initializing minimem in ${displayPath}...`);
+
+  // Create directories
+  await fs.mkdir(memoryDir, { recursive: true });
+  await fs.mkdir(path.join(memoryDir, "memory"), { recursive: true });
+  await fs.mkdir(path.join(memoryDir, ".minimem"), { recursive: true });
+
+  // Create MEMORY.md if it doesn't exist
+  const memoryFilePath = path.join(memoryDir, "MEMORY.md");
+  try {
+    await fs.access(memoryFilePath);
+    console.log("  MEMORY.md already exists, skipping");
+  } catch {
+    await fs.writeFile(memoryFilePath, MEMORY_TEMPLATE, "utf-8");
+    console.log("  Created MEMORY.md");
+  }
+
+  // Create config
+  const config = getInitConfig();
+  await saveConfig(memoryDir, config);
+  console.log("  Created .minimem/config.json");
+
+  // Create .gitignore for .minimem directory
+  const gitignorePath = path.join(memoryDir, ".minimem", ".gitignore");
+  await fs.writeFile(gitignorePath, "index.db\nindex.db-*\n", "utf-8");
+  console.log("  Created .minimem/.gitignore");
+
+  console.log();
+  console.log("Done! Your memory directory is ready.");
+  console.log();
+  console.log("Next steps:");
+  console.log(`  1. Set your embedding API key:`);
+  console.log(`     export OPENAI_API_KEY=your-key`);
+  console.log(`     # or: export GOOGLE_API_KEY=your-key`);
+  console.log();
+  console.log(`  2. Add some memories to MEMORY.md or memory/*.md`);
+  console.log();
+  console.log(`  3. Search your memories:`);
+  console.log(`     minimem search "your query"${dir ? ` --dir ${dir}` : ""}`);
+}