forge-server 0.1.0

package/src/knowledge/hydrator.ts

@@ -0,0 +1,246 @@
+// KnowledgeHydrator — syncs knowledge from YAML files into Qdrant's knowledge collection.
+//
+// The YAML files in .forge/knowledge/ are the source of truth. Qdrant is the
+// search index. The hydrator reads all items from the YAML store, embeds them,
+// and upserts into Qdrant. On re-hydration (after a manifest hash change) it
+// first deletes all Qdrant points for the repo to handle removals cleanly.
+//
+// Design notes:
+// - embedBatch() is used for bulk hydration instead of embedText() per item
+//   to amortise model inference overhead across all items.
+// - If Qdrant is unavailable the method logs a warning and returns 0 — the
+//   caller (RepoRegistry) treats this as a non-fatal result and records the
+//   item count as 0 in the registration response.
+// - The class accepts `embedder` as a constructor parameter (a reference to
+//   the embedBatch function) so tests can substitute a deterministic fake
+//   without dynamic import mocking.
+
+import { logger } from '../util/logger.js';
+import type { KnowledgeYamlStore } from './store.js';
+import type { QdrantVectorStore } from '../storage/qdrant-store.js';
+import type { KnowledgeItem, KnowledgePayload } from '../util/types.js';
+import { embedBatch, embedText } from '../ingestion/embedder.js';
+
+export class KnowledgeHydrator {
+  constructor(
+    private readonly yamlStore: KnowledgeYamlStore,
+    private readonly vectorStore: QdrantVectorStore,
+    // Accept embedder as a parameter for testability. Defaults to the real embedBatch.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private readonly embedder: typeof embedText = embedText,
+  ) {}
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Hydrate the Qdrant knowledge collection from all YAML files for a given
+   * repo. Deletes any existing points for this repo first (handles removals),
+   * then upserts all current items.
+   *
+   * Returns the count of items successfully loaded.
+   * Returns 0 and logs a warning if Qdrant is unavailable.
+   */
+  async hydrate(repoId: string, sharing: string): Promise<number> {
+    const items = this.yamlStore.readAll();
+
+    if (items.length === 0) {
+      logger.debug('KnowledgeHydrator: no items to hydrate', { repoId });
+      return 0;
+    }
+
+    // Check Qdrant availability before attempting any operations.
+    const qdrantHealthy = await this.vectorStore.isHealthy();
+    if (!qdrantHealthy) {
+      logger.warn('KnowledgeHydrator: Qdrant unavailable, skipping hydration', { repoId });
+      return 0;
+    }
+
+    try {
+      // Remove all existing Qdrant points for this repo so that deletions
+      // in the YAML are reflected — a simple upsert-only approach would leave
+      // orphaned points for removed items.
+      await this.removeRepo(repoId);
+
+      // Embed all items in one batch call to amortise model init cost.
+      const texts = items.map((item) => `${item.title} ${item.content}`);
+      let vectors: number[][];
+
+      // embedBatch returns parallel arrays; embedText (the embedder param)
+      // is a single-text function. When the injected embedder is embedText
+      // we upgrade to batch mode internally. This gives tests a simple stub
+      // interface while production uses the efficient batch path.
+      if (this.embedder === embedText) {
+        vectors = await embedBatch(texts);
+      } else {
+        // Fallback: call the injected embedder once per item. Used in tests.
+        vectors = await Promise.all(texts.map((t) => this.embedder(t)));
+      }
+
+      // Upsert each item with its vector and full KnowledgePayload.
+      const now = Date.now();
+      let loadedCount = 0;
+
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i]!;
+        const vector = vectors[i]!;
+
+        const payload: KnowledgePayload = {
+          id: item.id,
+          repo_id: repoId,
+          category: this._categoryFromId(item.id),
+          title: item.title,
+          content: item.content,
+          stack_tags: item.stack_tags,
+          confidence: item.confidence,
+          source: item.source,
+          source_phase: item.source_phase,
+          source_agent: item.source_agent,
+          sharing,
+          created_at: item.created_at,
+          updated_at: item.updated_at,
+          accessed_at: now,
+          access_count: 0,
+        };
+
+        await this.vectorStore.upsertKnowledge(
+          item.id,
+          vector,
+          payload as unknown as Record<string, unknown>,
+        );
+        loadedCount++;
+      }
+
+      logger.info('KnowledgeHydrator: hydration complete', {
+        repoId,
+        itemCount: loadedCount,
+        sharing,
+      });
+
+      return loadedCount;
+    } catch (err) {
+      logger.warn('KnowledgeHydrator: hydration failed', {
+        repoId,
+        error: String(err),
+      });
+      return 0;
+    }
+  }
+
+  /**
+   * Hydrate a single knowledge item into Qdrant.
+   * Used for incremental updates (e.g. after a single item is added via the
+   * knowledge-keeper agent) without re-hydrating the entire corpus.
+   */
+  async hydrateItem(item: KnowledgeItem, repoId: string, sharing: string): Promise<void> {
+    const qdrantHealthy = await this.vectorStore.isHealthy();
+    if (!qdrantHealthy) {
+      logger.warn('KnowledgeHydrator.hydrateItem: Qdrant unavailable', { id: item.id, repoId });
+      return;
+    }
+
+    try {
+      const text = `${item.title} ${item.content}`;
+      const vector = await this.embedder(text);
+
+      const now = Date.now();
+      const payload: KnowledgePayload = {
+        id: item.id,
+        repo_id: repoId,
+        category: this._categoryFromId(item.id),
+        title: item.title,
+        content: item.content,
+        stack_tags: item.stack_tags,
+        confidence: item.confidence,
+        source: item.source,
+        source_phase: item.source_phase,
+        source_agent: item.source_agent,
+        sharing,
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+        accessed_at: now,
+        access_count: 0,
+      };
+
+      await this.vectorStore.upsertKnowledge(
+        item.id,
+        vector,
+        payload as unknown as Record<string, unknown>,
+      );
+
+      logger.debug('KnowledgeHydrator.hydrateItem: item hydrated', {
+        id: item.id,
+        repoId,
+      });
+    } catch (err) {
+      logger.warn('KnowledgeHydrator.hydrateItem: failed', {
+        id: item.id,
+        repoId,
+        error: String(err),
+      });
+      throw err;
+    }
+  }
+
+  /**
+   * Remove all knowledge items for a repo from Qdrant.
+   * Called by hydrate() before re-upserting, and by RepoRegistry.removeRepo().
+   * Silently succeeds if Qdrant is unavailable.
+   */
+  async removeRepo(repoId: string): Promise<void> {
+    try {
+      // QdrantVectorStore.deleteKnowledge deletes by point ID.
+      // To delete ALL points for a repo we use the scroll+delete pattern via
+      // the Qdrant client's filter-based delete which the QdrantVectorStore
+      // exposes as deleteKnowledgeByRepo.
+      //
+      // The QdrantVectorStore may not have a deleteKnowledgeByRepo method yet.
+      // We call it if present; otherwise we fall through to the no-op with a
+      // log so the caller knows why old points were not removed.
+      const store = this.vectorStore as QdrantVectorStore & {
+        deleteKnowledgeByRepo?: (repoId: string) => Promise<void>;
+      };
+
+      if (typeof store.deleteKnowledgeByRepo === 'function') {
+        await store.deleteKnowledgeByRepo(repoId);
+        logger.debug('KnowledgeHydrator.removeRepo: deleted existing points', { repoId });
+      } else {
+        // Fallback: the store does not yet expose bulk-delete-by-repo for the
+        // knowledge collection. Log so the operator is aware that stale items
+        // may accumulate. This is non-fatal — upserts will overwrite matching
+        // IDs and only truly removed items will remain as orphans.
+        logger.debug(
+          'KnowledgeHydrator.removeRepo: deleteKnowledgeByRepo not available, ' +
+          'orphaned points may remain for removed items. Upserts will overwrite matching IDs.',
+          { repoId },
+        );
+      }
+    } catch (err) {
+      // Graceful degradation: if Qdrant is down or the delete fails, hydration
+      // should still proceed with upserts — better to have stale items than
+      // to completely block registration.
+      logger.warn('KnowledgeHydrator.removeRepo: delete failed (continuing)', {
+        repoId,
+        error: String(err),
+      });
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Derive category string from item id prefix.
+   * Mirrors the logic in KnowledgeYamlStore._categoryFromItem().
+   */
+  private _categoryFromId(id: string): string {
+    const lower = id.toLowerCase();
+    if (lower.startsWith('gotcha')) return 'gotcha';
+    if (lower.startsWith('pattern')) return 'pattern';
+    if (lower.startsWith('decision')) return 'decision';
+    if (lower.startsWith('convention')) return 'convention';
+    return 'pattern';
+  }
+}

package/src/knowledge/registry.ts

@@ -0,0 +1,463 @@
+// RepoRegistry — manages repo registration, manifest reading, and git detection.
+//
+// Registration flow:
+//   1. Resolve the repo path (absolute)
+//   2. Read .forge/manifest.yaml — required; if absent, returns an error result
+//   3. Resolve git remote origin URL (best-effort; local-only repos work too)
+//   4. Compute a stable repo ID: SHA-256(remote URL) first 12 hex chars, or
+//      SHA-256(absolute path) if no remote
+//   5. Upsert the repo row in SQLite
+//   6. Check if knowledge YAML content hash changed (compare manifest_hash)
+//   7. If changed (or newly registered), trigger KnowledgeHydrator to re-sync
+//      all knowledge items into Qdrant's knowledge collection
+//   8. Return registration result
+//
+// The registry operates standalone (no pipeline project required). Used by
+// both the MCP registration tools and the CLI `forge register` command.
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { parse, stringify } from 'yaml';
+import type { PipelineDB } from '../storage/sqlite.js';
+import type { QdrantVectorStore } from '../storage/qdrant-store.js';
+import { KnowledgeYamlStore } from './store.js';
+import { KnowledgeHydrator } from './hydrator.js';
+import type { Repo, RepoRow, ForgeManifest, SharingMode } from '../util/types.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const FORGE_DIR_NAME = '.forge';
+const MANIFEST_FILE = 'manifest.yaml';
+const KNOWLEDGE_CATEGORY_FILES = [
+  'gotchas.yaml',
+  'patterns.yaml',
+  'decisions.yaml',
+  'conventions.yaml',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Public interfaces
+// ---------------------------------------------------------------------------
+
+export interface RegisterOptions {
+  auto?: boolean;
+}
+
+/**
+ * Matches the spec B5 return shape (snake_case for MCP tool compat).
+ */
+export interface RegisterResult {
+  repo_id: string;
+  name: string;
+  path: string;
+  remote?: string;
+  stack: string[];
+  sharing: string;
+  newly_registered: boolean;
+  knowledge_items_loaded: number;
+}
+
+export interface InitOptions {
+  name: string;
+  stack: string[];
+  sharing?: SharingMode;
+  org?: string;
+}
+
+// Backward-compat camelCase result (used internally)
+export interface RegisterResultCamel {
+  repoId: string;
+  name: string;
+  path: string;
+  remote?: string;
+  stack: string[];
+  sharing: SharingMode;
+  newlyRegistered: boolean;
+  knowledgeItemsLoaded: number;
+}
+
+// ---------------------------------------------------------------------------
+// RepoRegistry
+// ---------------------------------------------------------------------------
+
+export class RepoRegistry {
+  constructor(
+    private readonly db: PipelineDB,
+    private readonly hydrator?: KnowledgeHydrator,
+  ) {}
+
+  // ---------------------------------------------------------------------------
+  // register — primary entry point (spec B5 signature)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Register (or update) a repo at `path`.
+   *
+   * Requires a .forge/manifest.yaml to exist at <path>/.forge/manifest.yaml.
+   * If the manifest is absent, throws an error describing the fix.
+   *
+   * Steps:
+   *   1. Read manifest from .forge/manifest.yaml
+   *   2. Resolve git origin URL
+   *   3. Generate repo_id from origin URL (or path hash if no remote)
+   *   4. Upsert into SQLite repos table
+   *   5. Compute knowledge content hash and compare with stored hash
+   *   6. If hash changed (or newly registered), hydrate Qdrant knowledge collection
+   *   7. Return RegisterResult
+   */
+  async register(
+    path: string,
+    options?: RegisterOptions,
+  ): Promise<RegisterResult> {
+    const repoPath = resolve(path);
+    const forgePath = join(repoPath, FORGE_DIR_NAME);
+    const manifestPath = join(forgePath, MANIFEST_FILE);
+
+    // Manifest is required. Return a clear error if absent.
+    if (!existsSync(manifestPath)) {
+      throw new Error(
+        `No .forge/manifest.yaml found at ${forgePath}. ` +
+        `Run \`forge init\` in the repo first, or call initForge() to create the directory structure.`,
+      );
+    }
+
+    const manifest = this.readManifest(forgePath);
+    if (!manifest) {
+      throw new Error(
+        `Failed to parse .forge/manifest.yaml at ${forgePath}. ` +
+        `Check the file for syntax errors.`,
+      );
+    }
+
+    // Resolve git remote and generate repo ID.
+    const remote = this.resolveGitOrigin(repoPath);
+    const repoId = manifest.repo_id_override
+      ? manifest.repo_id_override
+      : this.generateRepoId(remote ?? repoPath);
+
+    const name = manifest.name;
+    const stack = manifest.stack;
+    const sharing = manifest.sharing;
+    const org = manifest.org ?? null;
+
+    const now = Date.now();
+
+    // Compute knowledge content hash for change detection.
+    const yamlStore = new KnowledgeYamlStore(forgePath);
+    const knowledgeHash = yamlStore.getContentHash();
+
+    // Check existing row.
+    const existing = this.db.get<RepoRow>(`SELECT * FROM repos WHERE id = ?`, [repoId]);
+    const newlyRegistered = !existing;
+    const knowledgeChanged = !existing || existing.manifest_hash !== knowledgeHash;
+
+    if (existing) {
+      this.db.run(
+        `UPDATE repos
+         SET name = ?, path = ?, remote = ?, stack = ?, sharing = ?,
+             org = ?, last_seen_at = ?, manifest_hash = ?
+         WHERE id = ?`,
+        [
+          name, repoPath, remote ?? null, JSON.stringify(stack),
+          sharing, org, now, knowledgeHash, repoId,
+        ],
+      );
+      logger.info('RepoRegistry.register: repo updated', { repoId, name });
+    } else {
+      this.db.run(
+        `INSERT INTO repos
+           (id, name, path, remote, stack, sharing, org, registered_at, last_seen_at, manifest_hash)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          repoId, name, repoPath, remote ?? null, JSON.stringify(stack),
+          sharing, org, now, now, knowledgeHash,
+        ],
+      );
+      logger.info('RepoRegistry.register: repo registered', { repoId, name });
+    }
+
+    // Hydrate Qdrant knowledge collection if content changed.
+    let knowledgeItemsLoaded = 0;
+    if (knowledgeChanged && this.hydrator) {
+      try {
+        knowledgeItemsLoaded = await this.hydrator.hydrate(repoId, sharing);
+        logger.info('RepoRegistry.register: knowledge hydrated', {
+          repoId,
+          itemCount: knowledgeItemsLoaded,
+        });
+      } catch (err) {
+        // Hydration failure is non-fatal — registration proceeds.
+        logger.warn('RepoRegistry.register: knowledge hydration failed (non-fatal)', {
+          repoId,
+          error: String(err),
+        });
+      }
+    } else if (!this.hydrator) {
+      logger.debug('RepoRegistry.register: no hydrator configured, skipping knowledge sync', {
+        repoId,
+      });
+    }
+
+    return {
+      repo_id: repoId,
+      name,
+      path: repoPath,
+      remote: remote ?? undefined,
+      stack,
+      sharing,
+      newly_registered: newlyRegistered,
+      knowledge_items_loaded: knowledgeItemsLoaded,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // initForge — create .forge/ directory structure (spec B5 method)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Initialize the .forge/ directory in a repo at `repoPath`.
+   * Creates:
+   *   .forge/manifest.yaml          — from provided manifest
+   *   .forge/knowledge/gotchas.yaml
+   *   .forge/knowledge/patterns.yaml
+   *   .forge/knowledge/decisions.yaml
+   *   .forge/knowledge/conventions.yaml
+   *   .forge/.gitignore             — excludes .forge.db
+   *
+   * All files are created only if they do not already exist.
+   * Returns { forgePath, filesCreated } listing the paths that were created.
+   */
+  initForge(
+    repoPath: string,
+    manifest: ForgeManifest,
+  ): { forgePath: string; filesCreated: string[] } {
+    const absRepoPath = resolve(repoPath);
+    const forgePath = join(absRepoPath, FORGE_DIR_NAME);
+    const knowledgeDir = join(forgePath, 'knowledge');
+    const filesCreated: string[] = [];
+
+    // Create .forge/ directory
+    if (!existsSync(forgePath)) {
+      mkdirSync(forgePath, { recursive: true });
+      filesCreated.push(forgePath);
+    }
+
+    // Create .forge/knowledge/ subdirectory
+    if (!existsSync(knowledgeDir)) {
+      mkdirSync(knowledgeDir, { recursive: true });
+      filesCreated.push(knowledgeDir);
+    }
+
+    // Write manifest.yaml
+    const manifestPath = join(forgePath, MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+      const yamlContent = stringify(manifest, { indent: 2 });
+      writeFileSync(manifestPath, yamlContent, 'utf8');
+      filesCreated.push(manifestPath);
+    }
+
+    // Create empty YAML category files
+    for (const file of KNOWLEDGE_CATEGORY_FILES) {
+      const filePath = join(knowledgeDir, file);
+      if (!existsSync(filePath)) {
+        writeFileSync(filePath, '[]\n', 'utf8');
+        filesCreated.push(filePath);
+      }
+    }
+
+    // Create .gitignore to exclude local SQLite database
+    const gitignorePath = join(forgePath, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+      writeFileSync(gitignorePath, '.forge.db\n', 'utf8');
+      filesCreated.push(gitignorePath);
+    }
+
+    logger.info('RepoRegistry.initForge: .forge/ directory initialized', {
+      forgePath,
+      filesCreated: filesCreated.length,
+    });
+
+    return { forgePath, filesCreated };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Manifest reading (spec B5 signature: takes forgePath, not repoPath)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Read and parse .forge/manifest.yaml from `forgePath` (the .forge/ directory).
+   * Returns null if the file is absent or unparseable.
+   *
+   * NOTE: This method takes the .forge/ directory path, NOT the repo root.
+   * Callers that have the repo root should pass join(repoPath, '.forge').
+   */
+  readManifest(forgePath: string): ForgeManifest | null {
+    const manifestPath = join(forgePath, MANIFEST_FILE);
+    if (!existsSync(manifestPath)) return null;
+    return this._parseManifestFile(manifestPath);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Git origin resolution (public — spec B5)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Resolve the git remote origin URL for the repo at `repoPath`.
+   * Uses `git -C <repoPath> config --get remote.origin.url`.
+   * Returns null if the path is not a git repo or has no origin.
+   */
+  resolveGitOrigin(repoPath: string): string | null {
+    try {
+      const output = execFileSync(
+        'git',
+        ['-C', repoPath, 'config', '--get', 'remote.origin.url'],
+        {
+          encoding: 'utf-8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 3000,
+        },
+      ).trim();
+      return output || null;
+    } catch {
+      return null;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Repo ID generation (public — spec B5)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Generate a stable repo ID from a remote URL or local path.
+   * Uses SHA-256, returns first 12 hex characters.
+   *
+   * For remote URLs: normalises to strip .git suffix and trailing slashes
+   * before hashing so that git@github.com:org/repo and
+   * https://github.com/org/repo.git produce the same ID.
+   */
+  generateRepoId(remoteOrPath: string): string {
+    const normalised = remoteOrPath
+      .trim()
+      .replace(/\.git$/, '')
+      .replace(/\/$/, '')
+      .toLowerCase();
+    return createHash('sha256').update(normalised).digest('hex').slice(0, 12);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Query helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get a registered repo by ID.
+   * Returns null if not found.
+   */
+  getRepo(repoId: string): Repo | null {
+    const row = this.db.get<RepoRow>(`SELECT * FROM repos WHERE id = ?`, [repoId]);
+    return row ? this._rowToRepo(row) : null;
+  }
+
+  /**
+   * List all registered repos sorted by last_seen_at descending.
+   * Returns repos augmented with knowledge_count (total items in Qdrant).
+   * knowledge_count is always 0 when Qdrant is not available — it is a
+   * best-effort annotation, not a blocking query.
+   */
+  listRepos(): Array<Repo & { knowledge_count: number }> {
+    const rows = this.db.all<RepoRow>(`SELECT * FROM repos ORDER BY last_seen_at DESC`);
+    return rows.map((row) => ({
+      ...this._rowToRepo(row),
+      // knowledge_count: Qdrant query is async; this is a synchronous method.
+      // Return 0 — callers that need counts should call vectorStore.getKnowledgeCount()
+      // separately or use async listReposWithCounts() if added later.
+      knowledge_count: 0,
+    }));
+  }
+
+  /**
+   * Update the last_seen_at timestamp for a repo.
+   * Called on session-start to record that the repo is actively being used.
+   */
+  touch(repoId: string): void {
+    this.db.run(
+      `UPDATE repos SET last_seen_at = ? WHERE id = ?`,
+      [Date.now(), repoId],
+    );
+  }
+
+  /**
+   * Remove a repo from the registry.
+   * Does NOT remove Qdrant knowledge items — call hydrator.removeRepo() separately
+   * if you want to clean up vector data.
+   */
+  removeRepo(repoId: string): void {
+    this.db.run(`DELETE FROM repos WHERE id = ?`, [repoId]);
+    logger.info('RepoRegistry.removeRepo: repo removed from SQLite', { repoId });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Backward-compat helpers (camelCase API — kept for existing callers)
+  // ---------------------------------------------------------------------------
+
+  /** Whether a .forge/ directory exists in the given repo path. */
+  forgeDirectoryExists(repoPath?: string): boolean {
+    const targetPath = resolve(repoPath ?? process.cwd());
+    return existsSync(join(targetPath, FORGE_DIR_NAME));
+  }
+
+  /** Find a registered repo by its filesystem path. */
+  findRepoByPath(repoPath: string): Repo | null {
+    const absPath = resolve(repoPath);
+    const row = this.db.get<RepoRow>(`SELECT * FROM repos WHERE path = ?`, [absPath]);
+    return row ? this._rowToRepo(row) : null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private _parseManifestFile(manifestPath: string): ForgeManifest | null {
+    try {
+      const content = readFileSync(manifestPath, 'utf8');
+      const parsed = parse(content) as ForgeManifest;
+      return parsed ?? null;
+    } catch (err) {
+      logger.warn('RepoRegistry._parseManifestFile: failed to read manifest', {
+        path: manifestPath,
+        error: String(err),
+      });
+      return null;
+    }
+  }
+
+  private _repoNameFromPath(repoPath: string): string {
+    // basename handles both forward and backslash separators via path.basename
+    return basename(repoPath) || 'unknown';
+  }
+
+  private _rowToRepo(row: RepoRow): Repo {
+    let stack: string[];
+    try {
+      stack = JSON.parse(row.stack) as string[];
+    } catch {
+      stack = [];
+    }
+    return {
+      id: row.id,
+      name: row.name,
+      path: row.path,
+      remote: row.remote,
+      stack,
+      sharing: row.sharing,
+      org: row.org,
+      registeredAt: row.registered_at,
+      lastSeenAt: row.last_seen_at,
+      manifestHash: row.manifest_hash,
+    };
+  }
+}