@loopover/miner 0.1.0

package/lib/repo-clone.js

@@ -0,0 +1,102 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+// Per-repo base-clone cache (#5132, Wave 3.5 follow-up). packages/gittensory-engine/src/miner/
+// worktree-allocator.ts's real `addWorktree` primitive (git worktree add -b <branch> <path> <baseBranch>)
+// requires an EXISTING git clone to branch off -- it has never been wired into this package because that
+// clone-management step didn't exist yet. This module is that step: clone a target repo once, then keep it
+// current (fetch + hard-reset to the base branch) on every subsequent attempt, so `addWorktree` always
+// branches off real, fresh content. Relies entirely on whatever git/gh credentials are already configured
+// on this machine -- same assumption execute-local-write.js's `gh pr create` already makes; this module
+// never embeds a token in a clone URL.
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_CLONE_DIR_NAME = "repos";
+const DEFAULT_BASE_BRANCH = "main";
+
+export function resolveRepoCloneBaseDir(env = process.env) {
+  const explicitPath = typeof env.GITTENSORY_MINER_REPO_CLONE_DIR === "string" ? env.GITTENSORY_MINER_REPO_CLONE_DIR.trim() : "";
+  if (explicitPath) return explicitPath;
+
+  const explicitConfigDir = typeof env.GITTENSORY_MINER_CONFIG_DIR === "string" ? env.GITTENSORY_MINER_CONFIG_DIR.trim() : "";
+  if (explicitConfigDir) return join(explicitConfigDir, DEFAULT_CLONE_DIR_NAME);
+
+  const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim() ? env.XDG_CONFIG_HOME.trim() : join(homedir(), ".config");
+  return join(configHome, "gittensory-miner", DEFAULT_CLONE_DIR_NAME);
+}
+
+// GitHub owner/repo names are restricted to alphanumerics, hyphens, underscores, and periods, and are never
+// exactly "." or ".." -- both are rejected here so a value like "../foo" can't make resolveRepoCloneDir's
+// join(cloneBaseDir, owner, repo) escape the intended clone directory (a real path-traversal finding).
+const REPO_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+function isPathTraversalSegment(segment) {
+  return segment === "." || segment === "..";
+}
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.trim().split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  if (!REPO_SEGMENT_PATTERN.test(owner) || !REPO_SEGMENT_PATTERN.test(repo)) throw new Error("invalid_repo_full_name");
+  if (isPathTraversalSegment(owner) || isPathTraversalSegment(repo)) throw new Error("invalid_repo_full_name");
+  return { owner, repo, repoFullName: `${owner}/${repo}` };
+}
+
+export function resolveRepoCloneDir(repoFullName, env = process.env) {
+  const target = normalizeRepoFullName(repoFullName);
+  return join(resolveRepoCloneBaseDir(env), target.owner, target.repo);
+}
+
+async function defaultRunGit(args, cwd, timeoutMs) {
+  try {
+    const { stdout, stderr } = await execFileAsync("git", args, { cwd, timeout: timeoutMs });
+    return { ok: true, stdout, stderr };
+  } catch (error) {
+    const stderr = typeof error?.stderr === "string" ? error.stderr : "";
+    return { ok: false, stdout: "", stderr: stderr || (error instanceof Error ? error.message : String(error)) };
+  }
+}
+
+/**
+ * Ensure a real, current local clone of `repoFullName` exists at the deterministic per-repo cache path.
+ * First use: `git clone`. Subsequent use: `git fetch origin` + hard-reset the base branch to
+ * `origin/<baseBranch>`, so every attempt branches off fresh content, not a stale prior checkout.
+ *
+ * @param {string} repoFullName
+ * @param {{
+ *   baseBranch?: string, cloneBaseDir?: string, env?: Record<string, string | undefined>, timeoutMs?: number,
+ *   remoteUrl?: string, runGit?: (args: string[], cwd: string, timeoutMs: number) => Promise<{ ok: boolean, stdout: string, stderr: string }>,
+ * }} [options]
+ * @returns {Promise<{ ok: boolean, repoPath: string, error?: string }>}
+ */
+export async function ensureRepoCloned(repoFullName, options = {}) {
+  const target = normalizeRepoFullName(repoFullName);
+  const baseBranch = typeof options.baseBranch === "string" && options.baseBranch.trim() ? options.baseBranch.trim() : DEFAULT_BASE_BRANCH;
+  const cloneBaseDir = typeof options.cloneBaseDir === "string" && options.cloneBaseDir.trim() ? options.cloneBaseDir.trim() : resolveRepoCloneBaseDir(options.env);
+  const repoPath = join(cloneBaseDir, target.owner, target.repo);
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 120_000;
+  const runGit = options.runGit ?? defaultRunGit;
+
+  if (!existsSync(repoPath)) {
+    mkdirSync(join(cloneBaseDir, target.owner), { recursive: true, mode: 0o700 });
+    const cloneUrl = typeof options.remoteUrl === "string" && options.remoteUrl.trim() ? options.remoteUrl.trim() : `https://github.com/${target.owner}/${target.repo}.git`;
+    const cloned = await runGit(["clone", cloneUrl, repoPath], cloneBaseDir, timeoutMs);
+    if (!cloned.ok) return { ok: false, repoPath, error: cloned.stderr || "git_clone_failed" };
+    return { ok: true, repoPath };
+  }
+
+  const fetched = await runGit(["fetch", "origin"], repoPath, timeoutMs);
+  if (!fetched.ok) return { ok: false, repoPath, error: fetched.stderr || "git_fetch_failed" };
+
+  const checkedOut = await runGit(["checkout", baseBranch], repoPath, timeoutMs);
+  if (!checkedOut.ok) return { ok: false, repoPath, error: checkedOut.stderr || "git_checkout_failed" };
+
+  const reset = await runGit(["reset", "--hard", `origin/${baseBranch}`], repoPath, timeoutMs);
+  if (!reset.ok) return { ok: false, repoPath, error: reset.stderr || "git_reset_failed" };
+
+  return { ok: true, repoPath };
+}

package/lib/run-state-cli.d.ts

@@ -0,0 +1,27 @@
+export type ParsedStateGetArgs =
+  | {
+      repoFullName: string;
+      json: boolean;
+      apiBaseUrl: string | undefined;
+    }
+  | { error: string };
+
+export type ParsedStateSetArgs =
+  | {
+      repoFullName: string;
+      state: "idle" | "discovering" | "planning" | "preparing";
+      dryRun: boolean;
+      json: boolean;
+      apiBaseUrl: string | undefined;
+    }
+  | { error: string };
+
+export function parseStateGetArgs(args: string[]): ParsedStateGetArgs;
+
+export function parseStateSetArgs(args: string[]): ParsedStateSetArgs;
+
+export function runStateGet(args: string[]): number;
+
+export function runStateSet(args: string[]): number;
+
+export function runStateCli(subcommand: string | undefined, args: string[]): number;

package/lib/run-state-cli.js

@@ -0,0 +1,154 @@
+import { RUN_STATES, getRunState, setRunState } from "./run-state.js";
+import { argsWantJson, describeCliError, reportCliFailure } from "./cli-error.js";
+
+const STATE_GET_USAGE = "Usage: gittensory-miner state get <owner/repo> [--api-base-url <url>] [--json]";
+const STATE_SET_USAGE =
+  "Usage: gittensory-miner state set <owner/repo> <idle|discovering|planning|preparing> [--api-base-url <url>] [--dry-run] [--json]";
+
+const allowedRunStates = new Set(RUN_STATES);
+
+function parseRepoArg(value, usage) {
+  if (!value) return { error: usage };
+  const trimmed = value.trim();
+  const [owner, repo, extra] = trimmed.split("/");
+  if (!owner || !repo || extra !== undefined) {
+    return { error: "Repository must be in owner/repo form." };
+  }
+  return { repoFullName: `${owner}/${repo}` };
+}
+
+export function parseStateGetArgs(args) {
+  const options = { json: false, apiBaseUrl: undefined };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    // #5563: scope the lookup to a non-default forge host, so it doesn't collide with (or get confused for) a
+    // same-named repo on the default github.com host.
+    if (token === "--api-base-url") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        return { error: STATE_GET_USAGE };
+      }
+      options.apiBaseUrl = value;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    positional.push(token);
+  }
+
+  if (positional.length !== 1) {
+    return { error: STATE_GET_USAGE };
+  }
+
+  const repo = parseRepoArg(positional[0], STATE_GET_USAGE);
+  if ("error" in repo) return repo;
+
+  return { repoFullName: repo.repoFullName, ...options };
+}
+
+export function parseStateSetArgs(args) {
+  const options = { json: false, dryRun: false, apiBaseUrl: undefined };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    // #4847: reports what a real state set would do and returns before writing to the run-state store.
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--api-base-url") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        return { error: STATE_SET_USAGE };
+      }
+      options.apiBaseUrl = value;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    positional.push(token);
+  }
+
+  if (positional.length !== 2) {
+    return { error: STATE_SET_USAGE };
+  }
+
+  const repo = parseRepoArg(positional[0], STATE_SET_USAGE);
+  if ("error" in repo) return repo;
+
+  const state = positional[1];
+  if (!allowedRunStates.has(state)) {
+    return { error: `Invalid state: ${state}. Expected one of ${RUN_STATES.join(", ")}.` };
+  }
+
+  return { repoFullName: repo.repoFullName, state, ...options };
+}
+
+export function runStateGet(args) {
+  const parsed = parseStateGetArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  try {
+    const state = getRunState(parsed.repoFullName, parsed.apiBaseUrl);
+    if (parsed.json) {
+      console.log(JSON.stringify({ repoFullName: parsed.repoFullName, state }));
+    } else {
+      console.log(state ?? "none");
+    }
+    return 0;
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+export function runStateSet(args) {
+  const parsed = parseStateSetArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  if (parsed.dryRun) {
+    const dryRunResult = { outcome: "dry_run", repoFullName: parsed.repoFullName, state: parsed.state };
+    if (parsed.json) {
+      console.log(JSON.stringify(dryRunResult));
+    } else {
+      console.log(`DRY RUN: would set ${parsed.repoFullName}'s run state to "${parsed.state}". No run-state write was made.`);
+    }
+    return 0;
+  }
+
+  try {
+    const write = setRunState(parsed.repoFullName, parsed.state, parsed.apiBaseUrl);
+    if (parsed.json) {
+      console.log(JSON.stringify(write));
+    } else {
+      console.log(write.state);
+    }
+    return 0;
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+export function runStateCli(subcommand, args) {
+  if (subcommand === "get") return runStateGet(args);
+  if (subcommand === "set") return runStateSet(args);
+  return reportCliFailure(argsWantJson(args), `Unknown state subcommand: ${subcommand ?? ""}. ${STATE_GET_USAGE}`);
+}

package/lib/run-state.d.ts

@@ -0,0 +1,37 @@
+export type RunState = "idle" | "discovering" | "planning" | "preparing";
+
+export type RunStateWrite = {
+  apiBaseUrl: string;
+  repoFullName: string;
+  state: RunState;
+  updatedAt: string;
+};
+
+export type RunStateRow = {
+  apiBaseUrl: string;
+  repoFullName: string;
+  state: RunState;
+  updatedAt: string;
+};
+
+export type RunStateStore = {
+  dbPath: string;
+  getRunState(repoFullName: string, apiBaseUrl?: string): RunState | null;
+  setRunState(repoFullName: string, state: RunState, apiBaseUrl?: string): RunStateWrite;
+  listRunStates(): RunStateRow[];
+  close(): void;
+};
+
+export const RUN_STATES: readonly RunState[];
+
+export function resolveRunStateDbPath(env?: Record<string, string | undefined>): string;
+
+export function initRunStateStore(dbPath?: string): RunStateStore;
+
+export function getRunState(repoFullName: string, apiBaseUrl?: string): RunState | null;
+
+export function setRunState(repoFullName: string, state: RunState, apiBaseUrl?: string): RunStateWrite;
+
+export function listRunStates(): RunStateRow[];
+
+export function closeDefaultRunStateStore(): void;

package/lib/run-state.js

@@ -0,0 +1,150 @@
+import { DEFAULT_FORGE_CONFIG } from "./forge-config.js";
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+import { applySchemaMigrations } from "./schema-version.js";
+
+export const RUN_STATES = Object.freeze(["idle", "discovering", "planning", "preparing"]);
+
+const runStateSet = new Set(RUN_STATES);
+const defaultDbFileName = "run-state.sqlite3";
+let defaultRunStateStore = null;
+
+export function resolveRunStateDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_RUN_STATE_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolveRunStateDbPath(), "invalid_run_state_db_path");
+}
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const trimmed = repoFullName.trim();
+  const [owner, repo, extra] = trimmed.split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  return `${owner}/${repo}`;
+}
+
+function normalizeRunState(state) {
+  if (runStateSet.has(state)) return state;
+  throw new Error("invalid_run_state");
+}
+
+/** Optional forge host, scoping rows so two hosts serving the same owner/repo name never collide (#5563).
+ *  Omitted/nullish → the github.com default, so every pre-existing single-forge caller is unaffected. */
+function normalizeApiBaseUrl(apiBaseUrl) {
+  if (apiBaseUrl === undefined || apiBaseUrl === null) return DEFAULT_FORGE_CONFIG.apiBaseUrl;
+  if (typeof apiBaseUrl !== "string" || !apiBaseUrl.trim()) throw new Error("invalid_api_base_url");
+  return apiBaseUrl.trim();
+}
+
+// v1 -> v2 (#5563): rebuild the bare `repo_full_name` PRIMARY KEY into a (api_base_url, repo_full_name) composite
+// -- two forge hosts serving a same-named owner/repo must not share one "current state" row. SQLite cannot ALTER
+// a PRIMARY KEY in place, so this rebuilds the table: create the new shape, copy every existing row with the
+// pre-#4784 implicit single-forge default backfilled, drop the old table, rename the new one in.
+function addApiBaseUrlScope(db) {
+  db.exec(`
+    CREATE TABLE miner_run_state_v2 (
+      api_base_url TEXT NOT NULL,
+      repo_full_name TEXT NOT NULL,
+      state TEXT NOT NULL CHECK (state IN ('idle', 'discovering', 'planning', 'preparing')),
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (api_base_url, repo_full_name)
+    )
+  `);
+  // OR IGNORE: a row this store's own read path already treats as unusable garbage (an unrecognized `state`,
+  // e.g. from a hand-edited or otherwise corrupted file -- getRunState/listRunStates fail closed on it too)
+  // would violate the CHECK constraint above and abort the whole migration. Skipping it here is consistent with
+  // that same fail-closed posture, rather than turning one bad row into a permanently unmigratable file.
+  db.prepare(
+    `INSERT OR IGNORE INTO miner_run_state_v2 (api_base_url, repo_full_name, state, updated_at)
+     SELECT ?, repo_full_name, state, updated_at FROM miner_run_state`,
+  ).run(DEFAULT_FORGE_CONFIG.apiBaseUrl);
+  db.exec("DROP TABLE miner_run_state");
+  db.exec("ALTER TABLE miner_run_state_v2 RENAME TO miner_run_state");
+}
+
+/**
+ * Opens the 100% local/client-side miner run-state store. The database only lives on this machine;
+ * this module never uploads, syncs, or phones home with its contents. (#2289, #5563)
+ */
+export function initRunStateStore(dbPath = resolveRunStateDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS miner_run_state (
+      repo_full_name TEXT PRIMARY KEY,
+      state TEXT NOT NULL CHECK (state IN ('idle', 'discovering', 'planning', 'preparing')),
+      updated_at TEXT NOT NULL
+    )
+  `);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations.
+  applySchemaMigrations(db, [addApiBaseUrlScope]);
+
+  const getStatement = db.prepare(
+    "SELECT state FROM miner_run_state WHERE api_base_url = ? AND repo_full_name = ?",
+  );
+  const setStatement = db.prepare(`
+    INSERT INTO miner_run_state (api_base_url, repo_full_name, state, updated_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(api_base_url, repo_full_name) DO UPDATE SET
+      state = excluded.state,
+      updated_at = excluded.updated_at
+  `);
+  const listStatement = db.prepare(
+    "SELECT api_base_url, repo_full_name, state, updated_at FROM miner_run_state ORDER BY repo_full_name",
+  );
+
+  return {
+    dbPath: resolvedPath,
+    getRunState(repoFullName, apiBaseUrl) {
+      const row = getStatement.get(normalizeApiBaseUrl(apiBaseUrl), normalizeRepoFullName(repoFullName));
+      return runStateSet.has(row?.state) ? row.state : null;
+    },
+    setRunState(repoFullName, state, apiBaseUrl) {
+      const normalizedForge = normalizeApiBaseUrl(apiBaseUrl);
+      const normalizedRepo = normalizeRepoFullName(repoFullName);
+      const normalizedState = normalizeRunState(state);
+      const updatedAt = new Date().toISOString();
+      setStatement.run(normalizedForge, normalizedRepo, normalizedState, updatedAt);
+      return { apiBaseUrl: normalizedForge, repoFullName: normalizedRepo, state: normalizedState, updatedAt };
+    },
+    /** Every repo with a recorded run state, across the whole store — the per-repo discover/plan/prepare
+     *  signal a "run portfolio" view folds alongside managed PR rows (#4279). */
+    listRunStates() {
+      return listStatement.all()
+        .filter((row) => runStateSet.has(row.state))
+        .map((row) => ({
+          apiBaseUrl: row.api_base_url,
+          repoFullName: row.repo_full_name,
+          state: row.state,
+          updatedAt: row.updated_at,
+        }));
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultRunStateStore() {
+  defaultRunStateStore ??= initRunStateStore();
+  return defaultRunStateStore;
+}
+
+export function getRunState(repoFullName, apiBaseUrl) {
+  return getDefaultRunStateStore().getRunState(repoFullName, apiBaseUrl);
+}
+
+export function setRunState(repoFullName, state, apiBaseUrl) {
+  return getDefaultRunStateStore().setRunState(repoFullName, state, apiBaseUrl);
+}
+
+export function listRunStates() {
+  return getDefaultRunStateStore().listRunStates();
+}
+
+export function closeDefaultRunStateStore() {
+  if (!defaultRunStateStore) return;
+  defaultRunStateStore.close();
+  defaultRunStateStore = null;
+}

package/lib/schema-version.d.ts

@@ -0,0 +1,17 @@
+import type { DatabaseSync } from "node:sqlite";
+
+/** A single post-baseline schema migration: mutate the store in place to advance it exactly one version. */
+export type SchemaMigration = (db: DatabaseSync) => void;
+
+/** The bootstrap schema every store creates inline is, by convention, schema version 1. */
+export const BASELINE_SCHEMA_VERSION: number;
+
+/** Read a store's current `PRAGMA user_version`, coercing any absent/invalid value to 0 (pre-versioning). */
+export function readSchemaVersion(db: DatabaseSync): number;
+
+/**
+ * Run pending post-baseline migrations in order and stamp the resulting `user_version`. `migrations[i]` upgrades
+ * from version i+1 to i+2, so the target version is `BASELINE_SCHEMA_VERSION + migrations.length`. Returns the
+ * resulting version.
+ */
+export function applySchemaMigrations(db: DatabaseSync, migrations?: SchemaMigration[]): number;

package/lib/schema-version.js

@@ -0,0 +1,71 @@
+// Lightweight schema-versioning convention shared across the miner's local SQLite stores (#4832).
+//
+// Every store bootstraps its tables with `CREATE TABLE IF NOT EXISTS ...` but, until now, carried no
+// `user_version`/migration mechanism at all — so an older on-disk file was silently reused with a stale shape.
+// This module adds the missing convention without the weight of the main product's `migrations/` runner: each
+// store's bootstrap schema is treated as version 1 (BASELINE_SCHEMA_VERSION), and a store's `migrations` array
+// describes ONLY the changes AFTER that baseline (`migrations[i]` upgrades the schema from version i+1 to i+2).
+// `applySchemaMigrations` reads the file's current `PRAGMA user_version`, runs exactly the pending migrations in
+// order, and stamps the new version — so opening an older-schema file runs its outstanding migrations instead of
+// silently continuing on an incompatible shape. A pre-versioning file (user_version 0) already carries the
+// baseline tables (the idempotent `CREATE TABLE IF NOT EXISTS` ran), so it is treated as the baseline before any
+// post-baseline migration is applied. Pure control flow over an injected `DatabaseSync` handle: no IO of its own
+// beyond the PRAGMA read/write and the caller-supplied migration functions, and deterministic given the same
+// handle + migration list.
+
+/** The bootstrap schema every store creates inline is, by convention, schema version 1. */
+export const BASELINE_SCHEMA_VERSION = 1;
+
+/** Read a store's current `PRAGMA user_version`, coercing any absent/invalid value to 0 (pre-versioning). */
+export function readSchemaVersion(db) {
+  const row = db.prepare("PRAGMA user_version").get();
+  const raw = row ? Number(row.user_version) : 0;
+  return Number.isInteger(raw) && raw >= 0 ? raw : 0;
+}
+
+/**
+ * Bring a store's on-disk schema up to date, then stamp its `user_version`. `migrations[i]` upgrades from
+ * version i+1 to i+2, so the target version is `BASELINE_SCHEMA_VERSION + migrations.length`. Every migration
+ * whose resulting version is above the file's current version runs, in order; a file already at (or past) the
+ * target runs none. Returns the resulting version. Never runs a migration twice (the stamped `user_version`
+ * gates re-runs on the next open) and never DOWNGRADES: a file written by newer code with more migrations is
+ * left at its higher version rather than stamped back down. Each migration and its version stamp are applied in
+ * one transaction, so a failure part-way through the sequence leaves the file at the last fully-applied version
+ * and re-opening resumes at the failed migration (a throwing migration rethrows after its changes roll back).
+ *
+ * @param {import("node:sqlite").DatabaseSync} db - an open store handle whose baseline tables already exist.
+ * @param {Array<(db: import("node:sqlite").DatabaseSync) => void>} [migrations] - post-baseline migrations.
+ * @returns {number} the schema version after applying any pending migrations.
+ */
+export function applySchemaMigrations(db, migrations = []) {
+  const target = BASELINE_SCHEMA_VERSION + migrations.length;
+  const current = readSchemaVersion(db);
+  // A pre-versioning file (0) already holds the baseline schema, so advance from the baseline, not from 0.
+  const effective = current < BASELINE_SCHEMA_VERSION ? BASELINE_SCHEMA_VERSION : current;
+  // Stamp a pre-versioning file up to the baseline first, so a store with NO post-baseline migrations still
+  // records a version. Only ever stamp UPWARD: a file already at or past the baseline (including one written by
+  // newer code with more migrations) is never downgraded. `user_version` is an integer PRAGMA that cannot be
+  // parameterized; every stamped value here is a computed integer, never caller text, so interpolating is safe.
+  if (current < BASELINE_SCHEMA_VERSION) {
+    db.exec(`PRAGMA user_version = ${BASELINE_SCHEMA_VERSION}`);
+  }
+  for (let version = effective; version < target; version += 1) {
+    // Apply each migration AND stamp its resulting version in ONE transaction, so a failure part-way through the
+    // sequence leaves the file at the LAST fully-applied version: the next open resumes at the failed migration
+    // rather than re-running the ones that already succeeded (which, for a non-idempotent ALTER, would be a hard
+    // duplicate-column error). PRAGMA user_version is transactional in SQLite, so ROLLBACK undoes the migration's
+    // partial changes and its version stamp together.
+    db.exec("BEGIN");
+    try {
+      migrations[version - BASELINE_SCHEMA_VERSION](db);
+      db.exec(`PRAGMA user_version = ${version + 1}`);
+      db.exec("COMMIT");
+    } catch (error) {
+      db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+  // The resulting on-disk version: `target` after an upgrade, or the file's own higher version when it was
+  // written by newer code (never downgraded).
+  return Math.max(current, target);
+}

package/lib/self-review-context.d.ts

@@ -0,0 +1,28 @@
+import type { SelfReviewContext } from "@loopover/engine";
+
+// bounties/issueQuality are always omitted (see this file's own header comment for why), so the result is
+// SelfReviewContext minus those two optional fields rather than the full type.
+export type SelfReviewContextResult = Omit<SelfReviewContext, "bounties" | "issueQuality">;
+
+// A narrower shape than `typeof fetch` on purpose: this module only ever calls it with a string URL and a
+// plain GET init, and the ambient `fetch` type in this repo's TS program is Cloudflare-Workers-flavored
+// (RequestInfo<CfProperties> | URL), which is both irrelevant here (this package runs under plain Node) and
+// stricter than any real caller needs -- same rationale as live-issue-snapshot.js's own LiveIssueSnapshotFetch.
+export type SelfReviewContextFetch = (
+  url: string,
+  init?: { method?: string; headers?: Record<string, string> },
+) => Promise<{ ok: boolean; status: number; json: () => Promise<unknown>; text: () => Promise<string> }>;
+
+export type FetchSelfReviewContextOptions = {
+  githubToken?: string;
+  contributorLogin?: string;
+  linkedIssues?: number[];
+  apiBaseUrl?: string;
+  rawContentBaseUrl?: string;
+  gittensorApiBase?: string;
+  fetchImpl?: SelfReviewContextFetch;
+  perPage?: number;
+  maxPages?: number;
+};
+
+export function fetchSelfReviewContext(repoFullName: string, options?: FetchSelfReviewContextOptions): Promise<SelfReviewContextResult>;