claude-code-swarm 0.3.3 → 0.3.5

package/references/minimem/src/store/__tests__/store-graph.test.ts

@@ -0,0 +1,228 @@
+/**
+ * StoreGraph integration tests (requires node:sqlite)
+ *
+ * Run with: npx tsx --test src/store/__tests__/store-graph.test.ts
+ */
+
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+import { StoreGraph } from "../store-graph.js";
+import type { StoreManifest } from "../manifest.js";
+
+describe("StoreGraph", () => {
+  let tmpDir: string;
+  let storeADir: string;
+  let storeBDir: string;
+  let storeCDir: string;
+
+  before(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "minimem-storegraph-test-"));
+    storeADir = path.join(tmpDir, "store-a");
+    storeBDir = path.join(tmpDir, "store-b");
+    storeCDir = path.join(tmpDir, "store-c");
+
+    // Create store directories with minimal structure
+    for (const dir of [storeADir, storeBDir, storeCDir]) {
+      await fs.mkdir(path.join(dir, ".minimem"), { recursive: true });
+      await fs.writeFile(path.join(dir, "MEMORY.md"), `# Memory\n\nTest content for ${path.basename(dir)}\n`);
+      await fs.writeFile(
+        path.join(dir, ".minimem", "config.json"),
+        JSON.stringify({ embedding: { provider: "none" } }),
+      );
+    }
+
+    // Store C links to A and B
+    await fs.writeFile(
+      path.join(storeCDir, ".minimem", "links.json"),
+      JSON.stringify({ links: ["store-a", "store-b"] }),
+    );
+  });
+
+  after(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  function createManifest(): StoreManifest {
+    return {
+      stores: {
+        "store-a": { path: storeADir },
+        "store-b": { path: storeBDir, remote: "git@example.com:store-b.git" },
+        "store-c": { path: storeCDir },
+      },
+    };
+  }
+
+  function makeConfigFactory() {
+    return async (memoryDir: string) => ({
+      memoryDir,
+      embedding: { provider: "none" as const },
+      watch: { enabled: false },
+    });
+  }
+
+  it("creates from manifest", () => {
+    const manifest = createManifest();
+    const graph = StoreGraph.fromManifest(manifest);
+    assert.deepStrictEqual(
+      Object.keys(graph.getManifest().stores).sort(),
+      ["store-a", "store-b", "store-c"],
+    );
+  });
+
+  it("resolves a store with its linked stores", async () => {
+    const manifest = createManifest();
+    const graph = StoreGraph.fromManifest(manifest, {
+      configFactory: makeConfigFactory(),
+    });
+
+    try {
+      const instances = await graph.resolve("store-c");
+      assert.strictEqual(instances.length, 3);
+      assert.strictEqual(instances[0].name, "store-c");
+      assert.deepStrictEqual(
+        instances.map((i) => i.name).sort(),
+        ["store-a", "store-b", "store-c"],
+      );
+    } finally {
+      await graph.close();
+    }
+  });
+
+  it("resolves a store with no links as single instance", async () => {
+    const manifest = createManifest();
+    const graph = StoreGraph.fromManifest(manifest, {
+      configFactory: makeConfigFactory(),
+    });
+
+    try {
+      const instances = await graph.resolve("store-a");
+      assert.strictEqual(instances.length, 1);
+      assert.strictEqual(instances[0].name, "store-a");
+    } finally {
+      await graph.close();
+    }
+  });
+
+  it("resolves by directory path", async () => {
+    const manifest = createManifest();
+    const graph = StoreGraph.fromManifest(manifest, {
+      configFactory: makeConfigFactory(),
+    });
+
+    try {
+      const instances = await graph.resolveByPath(storeCDir);
+      assert.strictEqual(instances.length, 3);
+      assert.strictEqual(instances[0].name, "store-c");
+    } finally {
+      await graph.close();
+    }
+  });
+
+  it("resolves unknown directory as standalone", async () => {
+    const unknownDir = path.join(tmpDir, "unknown");
+    await fs.mkdir(path.join(unknownDir, ".minimem"), { recursive: true });
+    await fs.writeFile(path.join(unknownDir, "MEMORY.md"), "# Memory\n");
+    await fs.writeFile(
+      path.join(unknownDir, ".minimem", "config.json"),
+      JSON.stringify({ embedding: { provider: "none" } }),
+    );
+
+    const manifest = createManifest();
+    const graph = StoreGraph.fromManifest(manifest, {
+      configFactory: makeConfigFactory(),
+    });
+
+    try {
+      const instances = await graph.resolveByPath(unknownDir);
+      assert.strictEqual(instances.length, 1);
+      assert.strictEqual(instances[0].memoryDir, unknownDir);
+    } finally {
+      await graph.close();
+    }
+  });
+
+  it("throws for unknown store name", async () => {
+    const manifest = createManifest();
+    const graph = StoreGraph.fromManifest(manifest, {
+      configFactory: makeConfigFactory(),
+    });
+
+    try {
+      await assert.rejects(
+        () => graph.resolve("nonexistent"),
+        { message: /Store "nonexistent" not found/ },
+      );
+    } finally {
+      await graph.close();
+    }
+  });
+
+  it("skips unavailable linked stores gracefully", async () => {
+    const manifest: StoreManifest = {
+      stores: {
+        "store-a": { path: storeADir },
+        "store-b": { path: "/nonexistent/path" },
+        "store-c": { path: storeCDir },
+      },
+    };
+
+    const graph = StoreGraph.fromManifest(manifest, {
+      configFactory: makeConfigFactory(),
+    });
+
+    try {
+      const instances = await graph.resolve("store-c");
+      const names = instances.map((i) => i.name);
+      assert.ok(names.includes("store-c"));
+      assert.ok(names.includes("store-a"));
+      assert.ok(!names.includes("store-b"));
+    } finally {
+      await graph.close();
+    }
+  });
+
+  it("lists stores with their info", async () => {
+    const manifest = createManifest();
+    const graph = StoreGraph.fromManifest(manifest);
+
+    const stores = await graph.listStores();
+    assert.strictEqual(stores.length, 3);
+
+    const storeC = stores.find((s) => s.name === "store-c");
+    assert.ok(storeC);
+    assert.deepStrictEqual(storeC.links, ["store-a", "store-b"]);
+
+    const storeA = stores.find((s) => s.name === "store-a");
+    assert.ok(storeA);
+    assert.deepStrictEqual(storeA.links, []);
+  });
+
+  it("caches resolved instances", async () => {
+    const manifest = createManifest();
+    let createCount = 0;
+    const graph = StoreGraph.fromManifest(manifest, {
+      configFactory: async (memoryDir) => {
+        createCount++;
+        return {
+          memoryDir,
+          embedding: { provider: "none" as const },
+          watch: { enabled: false },
+        };
+      },
+    });
+
+    try {
+      await graph.resolve("store-c");
+      const firstCount = createCount;
+
+      await graph.resolve("store-a");
+      assert.strictEqual(createCount, firstCount);
+    } finally {
+      await graph.close();
+    }
+  });
+});

package/references/minimem/src/store/index.ts

@@ -0,0 +1,27 @@
+export {
+  StoreGraph,
+  type StoreGraphOptions,
+  type ResolvedStore,
+} from "./store-graph.js";
+
+export {
+  loadManifest,
+  saveManifest,
+  loadStoreLinks,
+  saveStoreLinks,
+  resolveStore,
+  resolveStoreName,
+  getLinkedStoreNames,
+  getManifestPath,
+  type StoreManifest,
+  type StoreDefinition,
+  type StoreLinks,
+} from "./manifest.js";
+
+export {
+  materializeStore,
+  getRemoteCacheDir,
+  listCachedStores,
+  clearStoreCache,
+  type MaterializeResult,
+} from "./materialize.js";

package/references/minimem/src/store/manifest.ts

@@ -0,0 +1,203 @@
+/**
+ * Store manifest: defines known stores and their relationships.
+ *
+ * Manifests can live in two places:
+ * 1. Global: ~/.config/minimem/stores.json (user-wide registry)
+ * 2. Per-store: .minimem/links.json (declares that store's dependencies)
+ *
+ * The global manifest is the source of truth for store metadata (path, remote).
+ * Per-store link files declare which other stores a store depends on.
+ */
+
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * A single store definition in the global manifest.
+ */
+export type StoreDefinition = {
+  /** Absolute path to the store's memory directory */
+  path: string;
+  /** Git remote URL for remote materialization */
+  remote?: string;
+  /** Human-readable description */
+  description?: string;
+};
+
+/**
+ * Global store manifest (~/.config/minimem/stores.json)
+ */
+export type StoreManifest = {
+  stores: Record<string, StoreDefinition>;
+};
+
+/**
+ * Per-store links file (.minimem/links.json or .swarm/minimem/links.json)
+ * Declares which other stores this store depends on.
+ */
+export type StoreLinks = {
+  /** Store names that this store links to (depth-1 only) */
+  links: string[];
+};
+
+const GLOBAL_MANIFEST_PATH = path.join(
+  os.homedir(),
+  ".config",
+  "minimem",
+  "stores.json",
+);
+
+const LINKS_FILENAME = "links.json";
+
+/**
+ * Load the global store manifest.
+ * Returns an empty manifest if the file doesn't exist.
+ */
+export async function loadManifest(
+  manifestPath?: string,
+): Promise<StoreManifest> {
+  const filePath = manifestPath ?? GLOBAL_MANIFEST_PATH;
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(content) as StoreManifest;
+    // Expand ~ in paths
+    for (const [name, def] of Object.entries(parsed.stores ?? {})) {
+      parsed.stores[name] = {
+        ...def,
+        path: expandHome(def.path),
+      };
+    }
+    return { stores: parsed.stores ?? {} };
+  } catch {
+    return { stores: {} };
+  }
+}
+
+/**
+ * Save the global store manifest.
+ */
+export async function saveManifest(
+  manifest: StoreManifest,
+  manifestPath?: string,
+): Promise<void> {
+  const filePath = manifestPath ?? GLOBAL_MANIFEST_PATH;
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(manifest, null, 2), "utf-8");
+}
+
+/**
+ * Load per-store links from a memory directory.
+ * Checks .minimem/links.json, .swarm/minimem/links.json, and links.json (contained layout).
+ */
+export async function loadStoreLinks(memoryDir: string): Promise<StoreLinks> {
+  const candidates = [
+    path.join(memoryDir, ".minimem", LINKS_FILENAME),
+    path.join(memoryDir, ".swarm", "minimem", LINKS_FILENAME),
+    path.join(memoryDir, LINKS_FILENAME),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      const content = await fs.readFile(candidate, "utf-8");
+      const parsed = JSON.parse(content) as StoreLinks;
+      return { links: parsed.links ?? [] };
+    } catch {
+      continue;
+    }
+  }
+
+  return { links: [] };
+}
+
+/**
+ * Save per-store links to a memory directory.
+ * Writes to the first config subdirectory that exists.
+ */
+export async function saveStoreLinks(
+  memoryDir: string,
+  links: StoreLinks,
+): Promise<void> {
+  // Find existing config subdirectory
+  const candidates = [
+    path.join(memoryDir, ".minimem"),
+    path.join(memoryDir, ".swarm", "minimem"),
+    memoryDir, // contained layout
+  ];
+
+  let targetDir = candidates[0]; // default to .minimem
+  for (const candidate of candidates) {
+    if (fsSync.existsSync(candidate)) {
+      targetDir = candidate;
+      break;
+    }
+  }
+
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.writeFile(
+    path.join(targetDir, LINKS_FILENAME),
+    JSON.stringify(links, null, 2),
+    "utf-8",
+  );
+}
+
+/**
+ * Resolve store name to its definition.
+ * Looks up the store in the global manifest.
+ */
+export function resolveStore(
+  manifest: StoreManifest,
+  storeName: string,
+): StoreDefinition | null {
+  return manifest.stores[storeName] ?? null;
+}
+
+/**
+ * Resolve a directory path to its store name in the manifest.
+ * Returns the first store whose path matches.
+ */
+export function resolveStoreName(
+  manifest: StoreManifest,
+  dirPath: string,
+): string | null {
+  const resolved = path.resolve(dirPath);
+  for (const [name, def] of Object.entries(manifest.stores)) {
+    if (path.resolve(def.path) === resolved) {
+      return name;
+    }
+  }
+  return null;
+}
+
+/**
+ * Get all linked store names for a given store (depth 1 only).
+ * Merges links from the global manifest and per-store links file.
+ */
+export async function getLinkedStoreNames(
+  manifest: StoreManifest,
+  storeName: string,
+): Promise<string[]> {
+  const storeDef = manifest.stores[storeName];
+  if (!storeDef) return [];
+
+  // Load per-store links
+  const storeLinks = await loadStoreLinks(storeDef.path);
+
+  // Deduplicate
+  return [...new Set(storeLinks.links)];
+}
+
+/**
+ * Get the default global manifest path.
+ */
+export function getManifestPath(): string {
+  return GLOBAL_MANIFEST_PATH;
+}
+
+function expandHome(filePath: string): string {
+  if (filePath.startsWith("~/")) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}

package/references/minimem/src/store/materialize.ts

@@ -0,0 +1,185 @@
+/**
+ * Store materialization strategies.
+ *
+ * Two strategies for making a linked store accessible:
+ *
+ * A. Remote materialization: clone/fetch a git remote into a cache directory
+ *    Used when the store isn't available locally.
+ *
+ * B. Symlink materialization: create temporary symlinks to a local store
+ *    Used when the store is already present on disk.
+ *    Symlinks go into a temp directory with unique subdirectory names
+ *    to avoid path collisions between stores.
+ */
+
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import type { StoreDefinition } from "./manifest.js";
+
+const execFileAsync = promisify(execFile);
+
+const CACHE_BASE = path.join(os.homedir(), ".cache", "minimem", "stores");
+
+export type MaterializeResult = {
+  /** The directory path to use for creating a Minimem instance */
+  path: string;
+  /** How the store was materialized */
+  strategy: "local" | "symlink" | "remote";
+  /** Cleanup function to call when done (removes symlinks, etc.) */
+  cleanup: () => Promise<void>;
+};
+
+/**
+ * Materialize a store so it can be accessed by a Minimem instance.
+ *
+ * Resolution order:
+ * 1. If the store path exists locally → use directly (no materialization needed)
+ * 2. If the store has a remote → clone/fetch into cache
+ * 3. Otherwise → return null (store unavailable)
+ */
+export async function materializeStore(
+  storeName: string,
+  storeDef: StoreDefinition,
+  opts?: {
+    /** Force refresh from remote even if cache exists */
+    refresh?: boolean;
+  },
+): Promise<MaterializeResult | null> {
+  // Strategy B: local store exists — use symlink to temp dir
+  if (fsSync.existsSync(storeDef.path)) {
+    return materializeLocal(storeName, storeDef.path);
+  }
+
+  // Strategy A: remote store — clone/fetch into cache
+  if (storeDef.remote) {
+    return materializeRemote(storeName, storeDef, opts?.refresh ?? false);
+  }
+
+  // Store is unavailable
+  return null;
+}
+
+/**
+ * Strategy B: symlink materialization for local stores.
+ *
+ * Creates a temporary directory with a uniquely-named subdirectory
+ * containing a symlink to the source store. This avoids collisions
+ * when multiple stores are materialized simultaneously.
+ */
+async function materializeLocal(
+  storeName: string,
+  storePath: string,
+): Promise<MaterializeResult> {
+  // Create temp dir: /tmp/minimem-stores-<random>/<storeName>/
+  const tmpBase = await fs.mkdtemp(
+    path.join(os.tmpdir(), "minimem-stores-"),
+  );
+  const symlinkDir = path.join(tmpBase, storeName);
+
+  // Create symlink: tmpBase/<storeName> → storePath
+  await fs.symlink(storePath, symlinkDir, "dir");
+
+  return {
+    // The Minimem instance should use the original path for its DB,
+    // but the symlink path can be used for discovery/resolution.
+    // We return the original path since Minimem works directly with it.
+    path: storePath,
+    strategy: "symlink",
+    cleanup: async () => {
+      try {
+        await fs.unlink(symlinkDir);
+        await fs.rmdir(tmpBase);
+      } catch {
+        // Best-effort cleanup
+      }
+    },
+  };
+}
+
+/**
+ * Strategy A: remote materialization via git clone/fetch.
+ *
+ * Clones the remote into ~/.cache/minimem/stores/<storeName>/
+ * On subsequent calls, does a git fetch + reset to update.
+ */
+async function materializeRemote(
+  storeName: string,
+  storeDef: StoreDefinition,
+  refresh: boolean,
+): Promise<MaterializeResult | null> {
+  const cacheDir = path.join(CACHE_BASE, storeName);
+
+  try {
+    if (fsSync.existsSync(path.join(cacheDir, ".git"))) {
+      // Cache exists — optionally refresh
+      if (refresh) {
+        await gitFetch(cacheDir);
+      }
+    } else {
+      // Clone fresh
+      await gitClone(storeDef.remote!, cacheDir);
+    }
+
+    return {
+      path: cacheDir,
+      strategy: "remote",
+      cleanup: async () => {
+        // Remote cache is persistent — no cleanup needed per session.
+        // Users can manually clear ~/.cache/minimem/stores/ if desired.
+      },
+    };
+  } catch {
+    // Git operation failed — store unavailable
+    return null;
+  }
+}
+
+async function gitClone(remote: string, targetDir: string): Promise<void> {
+  await fs.mkdir(path.dirname(targetDir), { recursive: true });
+  await execFileAsync("git", ["clone", "--depth", "1", remote, targetDir], {
+    timeout: 60_000,
+  });
+}
+
+async function gitFetch(cacheDir: string): Promise<void> {
+  await execFileAsync("git", ["fetch", "--depth", "1", "origin"], {
+    cwd: cacheDir,
+    timeout: 60_000,
+  });
+  await execFileAsync("git", ["reset", "--hard", "origin/HEAD"], {
+    cwd: cacheDir,
+    timeout: 30_000,
+  });
+}
+
+/**
+ * Get the cache directory for remote stores.
+ */
+export function getRemoteCacheDir(): string {
+  return CACHE_BASE;
+}
+
+/**
+ * List cached remote stores.
+ */
+export async function listCachedStores(): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(CACHE_BASE);
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Clear the cache for a specific remote store.
+ */
+export async function clearStoreCache(storeName: string): Promise<void> {
+  const cacheDir = path.join(CACHE_BASE, storeName);
+  await fs.rm(cacheDir, { recursive: true, force: true });
+}