@creeperhost/modlens-mcp 1.6.0

package/prisma/schema.prisma

@@ -0,0 +1,303 @@
+generator client {
+  provider      = "prisma-client-js"
+  binaryTargets = ["native", "windows", "debian-openssl-3.0.x", "rhel-openssl-3.0.x", "linux-musl-openssl-3.0.x", "darwin", "darwin-arm64"]
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model Mod {
+  id            Int      @id @default(autoincrement())
+  modId         String   @map("mod_id")
+  displayName   String   @map("display_name")
+  version       String
+  mcVersion     String   @map("mc_version")
+  loader        String   // fabric | neoforge | forge | quilt | unknown
+  jarPath       String   @unique @map("jar_path")
+  sha256        String?
+  murmur2       String?
+  sha512        String?
+  sourcePath    String?  @map("source_path")
+  decompPath    String?  @map("decomp_path")
+  decompiled    Boolean  @default(false)
+  graphPath     String?  @map("graph_path")
+  modrinthId    String?  @map("modrinth_id")
+  curseforgeId  Int?     @map("curseforge_id")
+  hasMixins     Boolean  @default(false) @map("has_mixins")
+  hasAt         Boolean  @default(false) @map("has_at")
+  hasAw         Boolean  @default(false) @map("has_aw")
+  mixinConfigs  String[] @map("mixin_configs")
+  mixinTargets  Json     @default("[]") @map("mixin_targets")
+  atEntries     Json     @default("[]") @map("at_entries")
+  awEntries     Json     @default("[]") @map("aw_entries")
+  dependencies  Json     @default("[]")
+  metadata      Json     @default("{}")
+  metadataSource String?  @map("metadata_source")
+  /// User-defined labels for filtering/grouping, e.g. ["combat", "storage", "compat"]
+  tags          String[] @default([])
+  ingestedAt    DateTime @default(now()) @map("ingested_at")
+  updatedAt     DateTime @updatedAt @map("updated_at")
+
+  classes       ModClass[]
+  modTags       ModTag[]
+  packFiles     PackFile[]
+  sourceFiles   ModSourceFile[]
+
+  @@unique([modId, version, mcVersion, loader])
+  @@index([modId])
+  @@index([mcVersion])
+  @@index([loader])
+  @@index([modrinthId])
+  @@index([curseforgeId])
+  @@map("mods")
+}
+
+model ModClass {
+  id          Int      @id @default(autoincrement())
+  modId       Int      @map("mod_id")
+  className   String   @map("class_name")
+  superClass  String?  @map("super_class")
+  interfaces  String[] 
+  accessFlags Int      @default(0) @map("access_flags")
+
+  mod         Mod      @relation(fields: [modId], references: [id], onDelete: Cascade)
+
+  @@unique([modId, className])
+  @@index([className])
+  @@index([modId])
+  @@map("mod_classes")
+}
+
+// ── Vanilla Minecraft versions ──────────────────────────────────────────────
+
+model McVersion {
+  id          Int      @id @default(autoincrement())
+  versionId   String   @unique @map("version_id")
+  type        String   @default("release")
+  jarPath     String?  @map("jar_path")
+  decompPath  String?  @map("decomp_path")
+  decompiled  Boolean  @default(false)
+  indexed     Boolean  @default(false)
+  releaseTime DateTime @map("release_time")
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  sourceFiles McSourceFile[]
+
+  @@map("mc_versions")
+}
+
+// ── Cached AST-level version diffs ──────────────────────────────────────────
+// Keyed by (versionA, versionB, packagesHash) to allow per-package scoping.
+// result stores the full VersionDiffResult JSON. Recomputed on force=true.
+
+model McVersionDiff {
+  id           Int      @id @default(autoincrement())
+  versionA     String   @map("version_a")
+  versionB     String   @map("version_b")
+  /// SHA-1 prefix of sorted joined packages filter, or "all" when no filter
+  packagesHash String   @default("all") @map("packages_hash")
+  result       Json
+  createdAt    DateTime @default(now()) @map("created_at")
+
+  @@unique([versionA, versionB, packagesHash])
+  @@index([versionA, versionB])
+  @@map("mc_version_diffs")
+}
+
+// ── Cached AST-level mod version diffs ────────────────────────────────────────
+// Keyed by (modDbIdA, modDbIdB, packagesHash). Integer IDs are stable per-JAR row.
+// Mirrors McVersionDiff but for mod-to-mod comparisons.
+
+model ModVersionDiff {
+  id           Int      @id @default(autoincrement())
+  modDbIdA     Int      @map("mod_db_id_a")
+  modDbIdB     Int      @map("mod_db_id_b")
+  /// SHA-1 prefix of sorted joined packages filter, or "all" when no filter
+  packagesHash String   @default("all") @map("packages_hash")
+  result       Json
+  createdAt    DateTime @default(now()) @map("created_at")
+
+  @@unique([modDbIdA, modDbIdB, packagesHash])
+  @@index([modDbIdA, modDbIdB])
+  @@map("mod_version_diffs")
+}
+
+// ── Mod-shipped tag files ──────────────────────────────────────────────────────
+// One row per data/<namespace>/tags/<registry>/<path>.json file found in a mod JAR.
+// tagPath  = "<namespace>:<subpath>"  e.g. "c:ores/iron", "forge:storage_blocks"
+// registry = folder name under tags/  e.g. "block", "item", "entity_type"
+// entries  = the values array (strings, may include #tag references)
+// replace  = true when the file sets "replace": true (overrides other mods' contributions)
+
+model ModTag {
+  id        Int      @id @default(autoincrement())
+  modId     Int      @map("mod_id")
+  mod       Mod      @relation(fields: [modId], references: [id], onDelete: Cascade)
+  registry  String   // block | item | entity_type | fluid | worldgen/biome | …
+  tagPath   String   // namespace:subpath, e.g. "c:ores/iron"
+  namespace String   // owning namespace of the tag file, e.g. "c", "minecraft", "forge"
+  entries   String[] // values listed in this tag file
+  replace   Boolean  @default(false)
+
+  @@index([modId])
+  @@index([tagPath])
+  @@index([registry, tagPath])
+  @@index([namespace])
+  @@map("mod_tags")
+}
+
+// Stores decompiled vanilla source per class — enables PostgreSQL FTS search.
+// GIN index is created automatically by `npm run db:setup` (scripts/create-fts-index.mjs).
+model McSourceFile {
+  id              Int                      @id @default(autoincrement())
+  mcVersionId     Int                      @map("mc_version_id")
+  className       String                   @map("class_name")
+  content         String
+  /// pgvector embedding — populated by `npm run db:vector` + backfill-embeddings
+  embedding       Unsupported("vector")?   @map("embedding")
+  /// Provenance: "local" (user Ollama), "registry" (public download), "community" (user contribution)
+  embedSource     String?                  @map("embed_source")
+  embedUpdatedAt  DateTime?                @map("embed_updated_at")
+
+  mcVersion   McVersion @relation(fields: [mcVersionId], references: [id], onDelete: Cascade)
+
+  @@unique([mcVersionId, className])
+  @@index([mcVersionId])
+  @@map("mc_source_files")
+}
+
+// ── Documentation entries ────────────────────────────────────────────────────
+
+model DocEntry {
+  id          Int                      @id @default(autoincrement())
+  /// Optional: fully-qualified class name this doc entry describes (slashes or dots).
+  className   String?                  @map("class_name")
+  title       String
+  summary     String?
+  url         String
+  /// One of: minecraft | neoforge | fabric | forge | quilt | mod | other
+  category    String                   @default("minecraft")
+  tags        String[]
+  /// Logical namespace: vanilla | neoforge | fabric | forge | quilt | parchment
+  namespace   String                   @default("vanilla")
+  /// How it was added: manual | seed | parchment | javadoc
+  source      String                   @default("manual")
+  createdAt   DateTime                 @default(now()) @map("created_at")
+  updatedAt   DateTime                 @updatedAt @map("updated_at")
+  /// pgvector embedding — populated by `npm run db:vector` + backfill-embeddings
+  embedding   Unsupported("vector")?   @map("embedding")
+
+  @@index([className])
+  @@index([category])
+  @@map("doc_entries")
+}
+
+// ── Mod decompiled source files (for semantic + FTS search) ─────────────────
+// One row per .java file from a decompiled mod JAR.
+// Mirrors mc_source_files but scoped to ingested mods instead of vanilla MC.
+model ModSourceFile {
+  id              Int                      @id @default(autoincrement())
+  modId           Int                      @map("mod_id")
+  className       String                   @map("class_name")
+  content         String
+  /// pgvector embedding — populated by mod index_semantic action
+  embedding       Unsupported("vector")?   @map("embedding")
+  /// Provenance: "local" (user Ollama), "registry" (public download), "community" (user contribution)
+  embedSource     String?                  @map("embed_source")
+  embedUpdatedAt  DateTime?                @map("embed_updated_at")
+
+  mod       Mod                      @relation(fields: [modId], references: [id], onDelete: Cascade)
+
+  @@unique([modId, className])
+  @@index([modId])
+  @@map("mod_source_files")
+}
+
+// ── Version migration primers ──────────────────────────────────────────────────────────
+// Documents that guide modders through upgrading mods from one MC/loader version to another.
+// fromDataVersion / toDataVersion store the integer data_version from mcmeta for numeric range queries.
+
+model Primer {
+  id              Int      @id @default(autoincrement())
+  /// Minecraft version this primer starts at, e.g. "1.20.4"
+  fromVersion     String   @map("from_version")
+  /// Minecraft version this primer targets, e.g. "1.21.1"
+  toVersion       String   @map("to_version")
+  /// Numeric data_version from mcmeta for ordering/range queries
+  fromDataVersion Int?     @map("from_data_version")
+  toDataVersion   Int?     @map("to_data_version")
+  /// Mod loader: neoforge | forge | fabric | quilt | vanilla | other
+  modloader       String   @default("neoforge")
+  title           String
+  summary         String?
+  url             String   @unique
+  /// Full text of the primer (optional — populated by ingest with fetch=true)
+  content         String?
+  tags            String[]
+  source          String                   @default("manual")
+  createdAt       DateTime                 @default(now()) @map("created_at")
+  updatedAt       DateTime                 @updatedAt @map("updated_at")
+  /// pgvector embedding — populated by `npm run db:vector` + backfill-embeddings
+  embedding       Unsupported("vector")?   @map("embedding")
+
+  @@index([fromVersion, toVersion])
+  @@index([fromDataVersion, toDataVersion])
+  @@index([modloader])
+  @@map("primers")
+}
+
+// ── Modpack version tracking ──────────────────────────────────────────────────
+// One row per (namespace, packId, versionId) that has been synced or inspected.
+
+model PackVersion {
+  id          Int      @id @default(autoincrement())
+  /// "ftb" | "curseforge"
+  namespace   String
+  packId      Int      @map("pack_id")
+  versionId   Int      @map("version_id")
+  packName    String   @map("pack_name")
+  versionName String   @map("version_name")
+  mcVersion   String?  @map("mc_version")
+  modloader   String?
+  syncedAt    DateTime @default(now()) @map("synced_at")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+
+  files       PackFile[]
+
+  @@unique([namespace, packId, versionId])
+  @@index([namespace, packId])
+  @@map("pack_versions")
+}
+
+// One row per file listed in a pack version manifest.
+// Covers mods, configs, scripts, resource packs, and cf-extract overrides ZIPs.
+// modId is set when the file was ingested as a Mod in this database.
+
+model PackFile {
+  id             Int          @id @default(autoincrement())
+  packVersionId  Int          @map("pack_version_id")
+  packVersion    PackVersion  @relation(fields: [packVersionId], references: [id], onDelete: Cascade)
+  /// file.id from the modpacks.ch manifest
+  manifestFileId Int?         @map("manifest_file_id")
+  /// "mod" | "resource" | "config" | "script" | "cf-extract" | "override" | etc.
+  fileType       String       @map("file_type")
+  fileName       String       @map("file_name")
+  /// Destination path relative to the pack root (from manifest file.path)
+  filePath       String?      @map("file_path")
+  cfProject      Int?         @map("cf_project")
+  cfFile         Int?         @map("cf_file")
+  sha1           String?
+  /// "ingested" | "already_ingested" | "downloaded_zip" | "error" | "skipped" | "not_synced"
+  status         String       @default("not_synced")
+  /// Set when this file was successfully ingested as a Mod row.
+  modId          Int?         @map("mod_id")
+  mod            Mod?         @relation(fields: [modId], references: [id], onDelete: SetNull)
+
+  @@unique([packVersionId, manifestFileId])
+  @@index([packVersionId])
+  @@index([modId])
+  @@index([cfProject])
+  @@map("pack_files")
+}

package/scripts/backup.mjs

@@ -0,0 +1,151 @@
+// scripts/backup.mjs
+/**
+ * Backup the active modlens database.
+ * Usage: node scripts/backup.mjs
+ * Or via npm: npm run db:backup
+ *
+ * Backs up to ~/.modlens-backups/<timestamp>-<backend>.<ext>
+ * Appends restore instructions to ~/.modlens-backups/README.md
+ */
+import { execSync } from "child_process";
+import { cpSync, mkdirSync, existsSync, appendFileSync, copyFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+try { require("dotenv").config(); } catch { /* dotenv optional */ }
+
+const DATABASE_URL = process.env.DATABASE_URL ?? "";
+const BACKUP_ROOT = process.env.MODLENS_BACKUP_DIR ?? join(homedir(), ".modlens-backups");
+
+function detectBackend(url) {
+    if (url.startsWith("file:") || url.endsWith(".db")) return "sqlite";
+    if (url.startsWith("pglite://") || url.startsWith("pglite:")) return "pglite";
+    return "postgres";
+}
+
+function timestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+}
+
+function ensureDir(dir) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function appendReadme(root, lines) {
+    ensureDir(root);
+    appendFileSync(join(root, "README.md"), lines.join("\n") + "\n\n");
+}
+
+// ── Postgres backup ──────────────────────────────────────────────────────────
+
+function backupPostgres(url, root = BACKUP_ROOT) {
+    ensureDir(root);
+    const ts = timestamp();
+    const file = join(root, `modlens-postgres-${ts}.sql`);
+
+    try {
+        execSync(`pg_dump "${url}" -f "${file}"`, { stdio: "inherit" });
+    } catch {
+        try {
+            const container = process.env.MODLENS_POSTGRES_CONTAINER ?? "modlens-postgres";
+            execSync(
+                `docker exec ${container} pg_dump "${url}" > "${file}"`,
+                { stdio: "inherit", shell: true },
+            );
+        } catch (e) {
+            throw new Error(
+                `pg_dump failed. Install pg_dump or ensure the postgres container is running.\n${e.message}`,
+            );
+        }
+    }
+
+    const restore = `psql "${url}" < "${file}"`;
+    appendReadme(root, [
+        `## Postgres backup — ${ts}`,
+        `File: ${file}`,
+        `Restore: \`${restore}\``,
+    ]);
+    return { file, restore };
+}
+
+// ── PGlite backup ────────────────────────────────────────────────────────────
+
+function backupPglite(url, root = BACKUP_ROOT) {
+    ensureDir(root);
+    const ts = timestamp();
+    const dataDir = url.replace(/^pglite:\/\//, "");
+    const outDir = join(root, `modlens-pglite-${ts}`);
+
+    if (!existsSync(dataDir)) {
+        throw new Error(`PGlite data directory does not exist: ${dataDir}`);
+    }
+
+    cpSync(dataDir, outDir, { recursive: true });
+
+    const restore = `cp -r "${outDir}" "${dataDir}"`;
+    appendReadme(root, [
+        `## PGlite backup — ${ts}`,
+        `Directory: ${outDir}`,
+        `Restore: \`${restore}\``,
+    ]);
+    return { dir: outDir, restore };
+}
+
+// ── SQLite backup ────────────────────────────────────────────────────────────
+
+function backupSqlite(url, root = BACKUP_ROOT) {
+    ensureDir(root);
+    const ts = timestamp();
+    const dbPath = url.replace(/^file:\/\//, "").replace(/^file:/, "");
+    const file = join(root, `modlens-sqlite-${ts}.db`);
+
+    if (!existsSync(dbPath)) {
+        throw new Error(`SQLite database file does not exist: ${dbPath}`);
+    }
+
+    copyFileSync(dbPath, file);
+
+    const restore = `cp "${file}" "${dbPath}"`;
+    appendReadme(root, [
+        `## SQLite backup — ${ts}`,
+        `File: ${file}`,
+        `Restore: \`${restore}\``,
+    ]);
+    return { file, restore };
+}
+
+// ── Programmatic API ─────────────────────────────────────────────────────────
+
+/**
+ * Backup the database at `url` to `backupRoot` (defaults to ~/.modlens-backups).
+ * @param {string} url
+ * @param {string} [backupRoot]
+ * @returns {{ file?: string, dir?: string, restore: string }}
+ */
+export async function backup(url, backupRoot) {
+    const root = backupRoot ?? BACKUP_ROOT;
+    const backend = detectBackend(url);
+    if (backend === "postgres") return backupPostgres(url, root);
+    if (backend === "pglite")  return backupPglite(url, root);
+    return backupSqlite(url, root);
+}
+
+// ── CLI entry point ───────────────────────────────────────────────────────────
+
+const isCli = process.argv[1]?.replace(/\\/g, "/").endsWith("backup.mjs");
+if (isCli) {
+    if (!DATABASE_URL) {
+        console.error("DATABASE_URL is not set. Create a .env file or set the variable.");
+        process.exit(1);
+    }
+
+    const backend = detectBackend(DATABASE_URL);
+    console.log(`Backing up ${backend} database...`);
+
+    const result = await backup(DATABASE_URL);
+    console.log(`Backup written: ${result.file ?? result.dir}`);
+    console.log(`Restore command: ${result.restore}`);
+    console.log(`Restore instructions also appended to: ${join(BACKUP_ROOT, "README.md")}`);
+}

package/scripts/build-template-db.mjs

@@ -0,0 +1,38 @@
+/**
+ * Builds the prebuilt SQLite template database that ships in the package.
+ *
+ * On first run as an installed package (npx / global), the launcher copies this
+ * template to `~/.modlens/data/modlens.db` so the embedded SQLite backend works
+ * with zero configuration — no `prisma db push`, no Prisma CLI, no engines, and
+ * no interactive setup required at runtime.
+ *
+ * The template is a build artifact (gitignored) regenerated on every `build`,
+ * so its schema is always in sync with `prisma/backends/schema.sqlite.prisma`.
+ */
+import { execSync } from "child_process";
+import { existsSync, rmSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const dbFile = join(ROOT, "prisma", "backends", "template.db");
+
+// Start from a clean slate so the template never carries stale tables/rows.
+if (existsSync(dbFile)) rmSync(dbFile);
+
+// Prisma resolves a relative `file:` URL relative to the schema file's directory
+// (prisma/backends/), so `file:./template.db` lands the db next to the schema.
+execSync(
+    "npx prisma db push --schema prisma/backends/schema.sqlite.prisma --skip-generate --accept-data-loss",
+    {
+        cwd: ROOT,
+        stdio: "inherit",
+        env: { ...process.env, DATABASE_URL: "file:./template.db" },
+    },
+);
+
+if (!existsSync(dbFile)) {
+    console.error(`[build-template-db] expected template at ${dbFile} but it was not created.`);
+    process.exit(1);
+}
+console.log(`[build-template-db] built template database at ${dbFile}`);

package/scripts/check-atm10.mjs

@@ -0,0 +1,27 @@
+import { PrismaClient } from '@prisma/client';
+const db = new PrismaClient();
+
+const stats = await db.mod.aggregate({ _min: { id: true }, _max: { id: true } });
+const totalMods = await db.mod.count();
+const atm10Files = await db.packFile.count({ where: { packVersionId: 1, fileType: 'mod' } });
+const atm10WithModId = await db.packFile.count({ where: { packVersionId: 1, fileType: 'mod', modId: { not: null } } });
+const atm10NotSynced = await db.packFile.count({ where: { packVersionId: 1, fileType: 'mod', status: 'not_synced' } });
+const atm10AlreadyIngested = await db.packFile.count({ where: { packVersionId: 1, fileType: 'mod', status: 'already_ingested' } });
+const atm10Ingested = await db.packFile.count({ where: { packVersionId: 1, fileType: 'mod', status: 'ingested' } });
+
+const lowestAtm10Mod = await db.packFile.findFirst({ where: { packVersionId: 1, modId: { not: null } }, orderBy: { modId: 'asc' }, select: { modId: true, fileName: true } });
+const highestAtm10Mod = await db.packFile.findFirst({ where: { packVersionId: 1, modId: { not: null } }, orderBy: { modId: 'desc' }, select: { modId: true, fileName: true } });
+
+console.log(JSON.stringify({
+    totalModsInDb: totalMods,
+    dbModIdRange: stats,
+    atm10Files,
+    atm10WithModId,
+    atm10Ingested,
+    atm10AlreadyIngested,
+    atm10NotSynced,
+    lowestAtm10Mod,
+    highestAtm10Mod,
+}, null, 2));
+
+await db.$disconnect();

package/scripts/check-sync.mjs

@@ -0,0 +1,13 @@
+import { readFileSync } from 'fs';
+// Load .env
+for (const line of readFileSync('d:/Downloads/modlens-mcp/.env', 'utf8').split('\n')) {
+    const m = line.match(/^([^#=]+)=(.*)$/);
+    if (m) process.env[m[1].trim()] ??= m[2].trim().replace(/^["']|["']$/g, '');
+}
+import { PrismaClient } from '@prisma/client';
+const db = new PrismaClient();
+const cfFilled = await db.mod.count({ where: { curseforgeId: { not: null } } });
+const mrFilled = await db.mod.count({ where: { modrinthId:   { not: null } } });
+console.log(`curseforgeId populated: ${cfFilled} / 821`);
+console.log(`modrinthId populated:   ${mrFilled} / 821`);
+await db.$disconnect();

package/scripts/create-fts-index.mjs

@@ -0,0 +1,50 @@
+/**
+ * Creates the PostgreSQL GIN index for full-text search on mc_source_files.
+ * Run via: npm run db:setup
+ *
+ * CREATE INDEX CONCURRENTLY cannot run inside a Prisma migration transaction,
+ * so it lives here as a post-migrate step.
+ */
+import { PrismaClient } from "@prisma/client";
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = join(__dirname, "..", ".env");
+if (existsSync(envPath)) {
+    for (const line of readFileSync(envPath, "utf8").split("\n")) {
+        const m = line.match(/^([^#=]+)=(.*)$/);
+        if (m) process.env[m[1].trim()] ??= m[2].trim().replace(/^["']|["']$/g, "");
+    }
+}
+
+const prisma = new PrismaClient();
+
+async function main() {
+    // Check if the index already exists to avoid a no-op CONCURRENTLY call
+    const existing = await prisma.$queryRaw`
+        SELECT 1 FROM pg_indexes
+        WHERE schemaname = 'public'
+          AND tablename  = 'mc_source_files'
+          AND indexname  = 'mc_source_files_tsv_idx'
+        LIMIT 1
+    `;
+
+    if (Array.isArray(existing) && existing.length > 0) {
+        console.log("FTS index mc_source_files_tsv_idx already exists — skipping.");
+        return;
+    }
+
+    console.log("Creating GIN FTS index on mc_source_files(content) — this may take a while...");
+    // CONCURRENTLY cannot run inside a transaction; Prisma $executeRaw runs outside one here.
+    await prisma.$executeRawUnsafe(`
+        CREATE INDEX CONCURRENTLY IF NOT EXISTS mc_source_files_tsv_idx
+            ON mc_source_files USING GIN (to_tsvector('simple', content))
+    `);
+    console.log("Done: mc_source_files_tsv_idx created.");
+}
+
+main()
+    .catch((err) => { console.error("Failed to create FTS index:", err); process.exit(1); })
+    .finally(() => prisma.$disconnect());

package/scripts/enable-pgvector.mjs

@@ -0,0 +1,90 @@
+/**
+ * Enables the pgvector extension and adds embedding columns to the three tables
+ * that support semantic search: doc_entries, primers, mc_source_files.
+ *
+ * Run once after `docker compose up`:
+ *   npm run db:vector
+ *
+ * Safe to re-run — all statements use IF NOT EXISTS / IF NOT EXISTS.
+ */
+import { PrismaClient } from "@prisma/client";
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = join(__dirname, "..", ".env");
+if (existsSync(envPath)) {
+    for (const line of readFileSync(envPath, "utf8").split("\n")) {
+        const m = line.match(/^([^#=]+)=(.*)$/);
+        if (m) process.env[m[1].trim()] ??= m[2].trim().replace(/^["']|["']$/g, "");
+    }
+}
+
+const prisma = new PrismaClient();
+
+async function main() {
+    // 1. Enable extension
+    await prisma.$executeRawUnsafe(`CREATE EXTENSION IF NOT EXISTS vector`);
+    console.log("✓ pgvector extension enabled");
+
+    // 2. Add or resize embedding columns
+    const dim = parseInt(process.env.OLLAMA_EMBED_DIM ?? "768", 10);
+    for (const table of ["doc_entries", "primers", "mc_source_files", "mod_source_files"]) {
+        // Check existing column dimension (atttypmod = dimension for pgvector)
+        const rows = await prisma.$queryRawUnsafe(
+            `SELECT atttypmod AS dim FROM pg_attribute
+             JOIN pg_class ON pg_attribute.attrelid = pg_class.oid
+             WHERE pg_class.relname = $1 AND pg_attribute.attname = 'embedding' AND pg_attribute.attnum > 0`,
+            table
+        );
+        const currentDim = Array.isArray(rows) && rows.length > 0 ? Number(rows[0].dim) : null;
+
+        if (currentDim === null) {
+            await prisma.$executeRawUnsafe(
+                `ALTER TABLE ${table} ADD COLUMN embedding vector(${dim})`
+            );
+            console.log(`✓ ${table}.embedding added (dim=${dim})`);
+        } else if (currentDim !== dim) {
+            // Drop the HNSW index first — ALTER TYPE fails if index exists
+            const idxName = `${table}_embedding_idx`;
+            await prisma.$executeRawUnsafe(`DROP INDEX IF EXISTS ${idxName}`);
+            await prisma.$executeRawUnsafe(
+                `ALTER TABLE ${table} ALTER COLUMN embedding TYPE vector(${dim})`
+            );
+            console.log(`✓ ${table}.embedding resized ${currentDim} → ${dim}`);
+        } else {
+            console.log(`  ${table}.embedding already vector(${dim}) — skipping`);
+        }
+    }
+
+    // 3. HNSW indexes for fast approximate nearest-neighbour
+    const indexes = [
+        ["doc_entries_embedding_idx",     "doc_entries"],
+        ["primers_embedding_idx",         "primers"],
+        ["mc_source_files_embedding_idx", "mc_source_files"],
+        ["mod_source_files_embedding_idx","mod_source_files"],
+    ];
+    for (const [idxName, table] of indexes) {
+        const existing = await prisma.$queryRawUnsafe(
+            `SELECT 1 FROM pg_indexes WHERE schemaname='public' AND indexname=$1 LIMIT 1`,
+            idxName,
+        );
+        if (Array.isArray(existing) && existing.length > 0) {
+            console.log(`  (index ${idxName} already exists — skipping)`);
+        } else {
+            console.log(`  Creating HNSW index ${idxName}…`);
+            await prisma.$executeRawUnsafe(
+                `CREATE INDEX ${idxName} ON ${table} USING hnsw (embedding vector_cosine_ops)`
+            );
+            console.log(`✓ ${idxName} created`);
+        }
+    }
+
+    console.log("\nDone — semantic search is ready.");
+    console.log("Next: set OLLAMA_URL in .env and run   node dist/cli.js backfill-embeddings --type docs");
+}
+
+main()
+    .catch((err) => { console.error("Failed:", err); process.exit(1); })
+    .finally(() => prisma.$disconnect());