@llmkb/claude-code 0.1.0

package/lib/sync-spaces-config.ts

@@ -0,0 +1,180 @@
+/** Sync related spaces from the backend into ``.llmkb/spaces.yml``.
+
+Reads the ``project_space`` ID from the local config, fetches all
+related spaces from the backend ``space_relations`` endpoint, and
+appends any that are not yet listed in the ``spaces`` array.
+
+Called by:
+  - ``llmkb doctor`` (LD-1) — sync before checking space access
+  - ``llmkb sync`` (LS-4)  — sync as the final post-sync step
+  - ``llmkb login`` (LL-2) — sync after discovering user spaces
+*/
+
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readSpaceConfig, addSpaceEntry, removeSpaceEntry, writeSpaceConfig } from "./parser.js";
+
+// ---------------------------------------------------------------------------
+// Response shapes from the backend
+// ---------------------------------------------------------------------------
+
+interface RelationsResponse {
+  data?: Array<{
+    attributes?: {
+      relatedSpaceId?: string;
+      relatedSpaceName?: string;
+      relatedSpaceSlug?: string;
+    };
+  }>;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface SyncSpacesResult {
+  added: number;
+  alreadyPresent: number;
+  removed: number;
+}
+
+/**
+ * Fetch all related spaces from the backend and sync them into
+ * ``.llmkb/spaces.yml``.
+ *
+ * 1. Adds any new related spaces not yet in the ``spaces`` list.
+ * 2. Removes any spaces that were previously synced but are no
+ *    longer related (tracked via ``.llmkb/sync-relations.json``).
+ *
+ * Manually-added spaces (not added by this sync) are never removed.
+ */
+export async function syncRelatedSpaces(
+  projectDir: string,
+  endpoint: string,
+  token: string,
+): Promise<SyncSpacesResult> {
+  const config = await readSpaceConfig(projectDir);
+  if (!config?.project_space?.length) {
+    return { added: 0, alreadyPresent: 0, removed: 0 };
+  }
+
+  const projectSpaceId = config.project_space[0]!.id;
+
+  // Fetch related spaces from the backend (authoritative list)
+  const relations = await fetchRelatedSpaces(endpoint, token, projectSpaceId);
+  const backendIds = new Set(relations.map((r) => r.id));
+
+  // Read previously synced relation IDs
+  const syncedIdsPath = join(projectDir, ".llmkb", "sync-relations.json");
+  const prevSyncedIds = await readSyncedIds(syncedIdsPath);
+
+  let added = 0;
+  let alreadyPresent = 0;
+  let removed = 0;
+
+  // Phase 0: Remove duplicate project_space entries from the spaces list
+  if (config.spaces) {
+    for (const s of config.spaces) {
+      if (s.id === projectSpaceId) {
+        await removeSpaceEntry(projectDir, s.id);
+        removed++;
+      }
+    }
+  }
+
+  // Phase 1: Add new relations
+  for (const rel of relations) {
+    if (rel.id === projectSpaceId) continue;
+
+    const existingIds = new Set([
+      ...(config.spaces ?? []).map((s) => s.id),
+      ...(config.project_space ?? []).map((s) => s.id),
+    ]);
+
+    if (existingIds.has(rel.id)) {
+      alreadyPresent++;
+    } else {
+      await addSpaceEntry(projectDir, rel.id, rel.name);
+      added++;
+    }
+  }
+
+  // Phase 2: Remove stale entries that were previously synced
+  // Only remove entries that OUR sync added (tracked in sync-relations.json),
+  // never manually-added spaces.
+  if (prevSyncedIds.size > 0 && config.spaces) {
+    for (const s of config.spaces) {
+      if (prevSyncedIds.has(s.id) && !backendIds.has(s.id)) {
+        await removeSpaceEntry(projectDir, s.id);
+        removed++;
+      }
+    }
+  }
+
+  // Update the synced IDs tracking file
+  await writeSyncedIds(syncedIdsPath, backendIds);
+
+  return { added, alreadyPresent, removed };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Synced-IDs tracking
+// ---------------------------------------------------------------------------
+
+const SYNC_RELATIONS_FILE = "sync-relations.json";
+
+async function readSyncedIds(filePath: string): Promise<Set<string>> {
+  try {
+    if (existsSync(filePath)) {
+      const raw = await readFile(filePath, "utf-8");
+      const parsed = JSON.parse(raw) as string[];
+      return new Set(parsed);
+    }
+  } catch {
+    // Corrupted file — start fresh
+  }
+  return new Set();
+}
+
+async function writeSyncedIds(
+  filePath: string,
+  ids: Set<string>,
+): Promise<void> {
+  await writeFile(filePath, JSON.stringify([...ids], null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function fetchRelatedSpaces(
+  endpoint: string,
+  token: string,
+  spaceId: string,
+): Promise<Array<{ id: string; name?: string }>> {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/spaces/${encodeURIComponent(spaceId)}/relations`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!res.ok) return [];
+
+    const body = (await res.json()) as RelationsResponse;
+    if (!body.data) return [];
+
+    return body.data
+      .filter((d) => d.attributes?.relatedSpaceId)
+      .map((d) => ({
+        id: d.attributes!.relatedSpaceId!,
+        name: d.attributes?.relatedSpaceName ?? undefined,
+      }));
+  } catch {
+    return [];
+  }
+}

package/lib/sync-state.ts

@@ -0,0 +1,152 @@
+/** Content-addressed sync-state manager (.llmkb/sync-state.json).
+
+Tracks file uploads by SHA256 hash, enabling incremental sync where
+unchanged files skip server reprocessing entirely.
+
+Pattern: read -> compute -> compare -> classify -> write
+*/
+
+import { readFile, writeFile, unlink, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { join, resolve } from "node:path";
+import type { SyncState, SyncFileEntry, FileChangeSet, RenameEntry } from "./types.js";
+
+const SYNC_STATE_FILE = ".llmkb/sync-state.json";
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+function statePath(projectDir: string): string {
+  return resolve(projectDir, SYNC_STATE_FILE);
+}
+
+function llmkbDir(projectDir: string): string {
+  return resolve(projectDir, ".llmkb");
+}
+
+// ---------------------------------------------------------------------------
+// SHA256 streaming computation (memory-safe for large files)
+// ---------------------------------------------------------------------------
+
+/** Compute SHA256 hash of a file using streaming reads (O(1) memory). */
+export async function computeSha256(filePath: string): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolve(hash.digest("hex")));
+    stream.on("error", reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Read / Write
+// ---------------------------------------------------------------------------
+
+/** Read the sync state file. Returns null if missing or malformed. */
+export async function readSyncState(projectDir: string): Promise<SyncState | null> {
+  const filePath = statePath(projectDir);
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = await readFile(filePath, "utf-8");
+    return JSON.parse(raw) as SyncState;
+  } catch {
+    return null;
+  }
+}
+
+/** Write the sync state file. Creates .llmkb/ if missing. */
+export async function writeSyncState(projectDir: string, state: SyncState): Promise<void> {
+  const dir = llmkbDir(projectDir);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  await writeFile(statePath(projectDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Update helpers
+// ---------------------------------------------------------------------------
+
+/** Update a single file entry in the sync state. */
+export async function updateSyncEntry(
+  projectDir: string,
+  relativePath: string,
+  entry: SyncFileEntry,
+): Promise<void> {
+  const state = (await readSyncState(projectDir)) ?? {
+    space: "",
+    lastSyncAt: new Date().toISOString(),
+    files: {},
+  };
+  state.files[relativePath] = entry;
+  state.lastSyncAt = new Date().toISOString();
+  await writeSyncState(projectDir, state);
+}
+
+/** Clear the sync state entirely (e.g., on space switch). */
+export async function clearSyncState(projectDir: string): Promise<void> {
+  const filePath = statePath(projectDir);
+  if (existsSync(filePath)) {
+    await unlink(filePath);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+
+/** Classify an array of (relativePath, absolutePath) pairs against the current
+ * sync state into new/changed/unchanged/renamed groups.
+ *
+ * @param files  Array of [relativePath, absolutePath] tuples.
+ * @param state  Current sync state (null for first run).
+ * @returns      Classified file sets with computed SHA256 hashes.
+ */
+export async function getChangedFiles(
+  files: Array<[string, string]>,
+  state: SyncState | null,
+): Promise<FileChangeSet> {
+  const newFiles: string[] = [];
+  const changedFiles: string[] = [];
+  const unchangedFiles: string[] = [];
+  const renamed: RenameEntry[] = [];
+
+  // Build a reverse index: sha256 -> old path (for rename detection)
+  const hashToPath = new Map<string, string>();
+  if (state) {
+    for (const [path, entry] of Object.entries(state.files)) {
+      hashToPath.set(entry.sha256, path);
+    }
+  }
+
+  for (const [relPath, absPath] of files) {
+    const hash = await computeSha256(absPath);
+
+    if (!state) {
+      // First run — everything is new
+      newFiles.push(relPath);
+      continue;
+    }
+
+    const existingEntry = state.files[relPath];
+    if (!existingEntry) {
+      // Check if it's a rename (same hash, different path)
+      const oldPath = hashToPath.get(hash);
+      if (oldPath && oldPath !== relPath) {
+        renamed.push({ oldPath, newPath: relPath });
+        continue;
+      }
+      newFiles.push(relPath);
+    } else if (existingEntry.sha256 !== hash) {
+      changedFiles.push(relPath);
+    } else {
+      unchangedFiles.push(relPath);
+    }
+  }
+
+  return { newFiles, changedFiles, unchangedFiles, renamed };
+}