leetcode-capture-helper 0.0.0-stage → 0.1.1

package/runtime/relay-server/server.js

@@ -0,0 +1,241 @@
+// LeetCode Capture - local relay server
+//
+// Listens on localhost only. Accepts POSTs from the browser extension and
+// durably appends each capture as one JSON line to a local log file, adding
+// a per-problem monotonic attempt sequence number.
+//
+// Log file location: ./data/captures.jsonl (relative to this file), unless
+// overridden with the CAPTURE_LOG_PATH environment variable.
+// The log is cleared as the companion consumes it (see trimCaptureLog).
+
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const { createPanelBroker, companionOnlyRejection } = require("./panel-broker");
+
+const HOST = "127.0.0.1";
+const PORT = process.env.CAPTURE_PORT ? Number(process.env.CAPTURE_PORT) : 8135;
+const LOG_PATH = process.env.CAPTURE_LOG_PATH ||
+  path.join(__dirname, "data", "captures.jsonl");
+
+const MAX_BODY_BYTES = 5 * 1024 * 1024; // 5MB, generous for a single file's code
+
+fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+
+// Per-problem attempt sequence numbers, rebuilt from the existing log on
+// startup so restarts don't reset the counter.
+const attemptSeq = new Map();
+
+function loadExistingSequences() {
+  if (!fs.existsSync(LOG_PATH)) return;
+  const lines = fs.readFileSync(LOG_PATH, "utf8").split("\n").filter(Boolean);
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      const key = entry.problemSlug || "unknown";
+      const current = attemptSeq.get(key) || 0;
+      if (entry.attemptSeq > current) {
+        attemptSeq.set(key, entry.attemptSeq);
+      }
+    } catch {
+      // Skip malformed lines rather than fail startup.
+    }
+  }
+}
+
+function nextAttemptSeq(problemSlug) {
+  const key = problemSlug || "unknown";
+  const next = (attemptSeq.get(key) || 0) + 1;
+  attemptSeq.set(key, next);
+  return next;
+}
+
+function isValidCapture(body) {
+  return (
+    body &&
+    typeof body === "object" &&
+    typeof body.problemSlug === "string" &&
+    typeof body.language === "string" &&
+    typeof body.code === "string" &&
+    (body.trigger === "run" || body.trigger === "submit") &&
+    typeof body.timestamp === "string"
+  );
+}
+
+function appendCapture(body) {
+  const entry = {
+    receivedAt: new Date().toISOString(),
+    problemSlug: body.problemSlug,
+    problemTitle: body.problemTitle || null,
+    problemDescription: body.problemDescription || null,
+    problemTags: Array.isArray(body.problemTags) ? body.problemTags : [],
+    language: body.language,
+    trigger: body.trigger,
+    timestamp: body.timestamp,
+    url: body.url || null,
+    code: body.code,
+    attemptSeq: nextAttemptSeq(body.problemSlug),
+  };
+  fs.appendFileSync(LOG_PATH, JSON.stringify(entry) + "\n");
+  return entry;
+}
+
+// The log is only a short-lived delivery queue from this relay to the
+// companion, which tails it by byte offset. Once the companion has read a
+// prefix of it (and moved on from that problem, or just started), it asks for
+// that prefix to be dropped (the companion-only POST /panel/trim-captures,
+// see panel-broker.js). `before` is the companion's own read offset, so only
+// lines it already handled are dropped. Everything here is synchronous, like
+// appendCapture, so a capture that arrives meanwhile is appended wholly
+// before or wholly after the trim and is never lost or doubled; the rest of
+// the file is written to a temporary file and renamed over the log, so a
+// crash leaves either the old log or the new one. A future setting that
+// keeps old captures (for studying later) would copy the dropped prefix
+// somewhere first, here.
+// Returns { removed, size }, or { error } for a request that cannot be met.
+function trimCaptureLog(before) {
+  let size;
+  try {
+    size = fs.statSync(LOG_PATH).size;
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    size = 0;
+  }
+  if (before > size) return { error: `the log is only ${size} bytes` };
+  if (before === 0) return { removed: 0, size };
+  const fd = fs.openSync(LOG_PATH, "r");
+  let rest;
+  try {
+    const last = Buffer.alloc(1);
+    fs.readSync(fd, last, 0, 1, before - 1);
+    if (last[0] !== 0x0a) return { error: "that offset is not at the end of a line" };
+    rest = Buffer.alloc(size - before);
+    fs.readSync(fd, rest, 0, rest.length, before);
+  } finally {
+    fs.closeSync(fd);
+  }
+  const tmp = `${LOG_PATH}.trim-tmp`;
+  fs.writeFileSync(tmp, rest);
+  fs.renameSync(tmp, LOG_PATH);
+  return { removed: before, size: rest.length };
+}
+
+// CORS headers, sent on every response to /capture (including the OPTIONS
+// preflight). Chrome's content-script fetch() inherits the extension's
+// host_permissions grant and skips CORS entirely, but Firefox/Zen run
+// content-script fetch() as the page's own origin (https://leetcode.com),
+// so a cross-origin POST with a JSON body triggers a real preflight. This
+// server only binds to 127.0.0.1 and only ingests capture data (no
+// secrets, no destructive actions), so a permissive `*` origin is fine -
+// no need for an origin allowlist on a localhost-only dev tool.
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+};
+
+// The in-page tutor panel's broker (see panel-broker.js). Its routes do their
+// own, much stricter origin checks, so they run before the permissive
+// /capture handling below.
+const panelBroker = createPanelBroker({ port: PORT, captureLog: { path: LOG_PATH, trim: trimCaptureLog } });
+
+// Run by the Native Messaging helper (helper/host.js), the relay quits on its
+// own when nothing has been heard for RELAY_IDLE_EXIT_MS, so a browser or
+// helper that vanished cannot leave it holding the port. Heard means a
+// request from anything but the companion (a panel, a capture, the options
+// page), an open panel stream, or the helper's POST /helper/keepalive, which
+// the helper sends while the extension keeps talking to it. Off (0) unless
+// set, so a relay started by hand runs until stopped.
+const IDLE_EXIT_MS = Number(process.env.RELAY_IDLE_EXIT_MS) || 0;
+let lastHeard = Date.now();
+
+const server = http.createServer((req, res) => {
+  if (req.headers["x-lc-companion"] === undefined) lastHeard = Date.now();
+  if (req.method === "POST" && req.url === "/helper/keepalive") {
+    const rejection = companionOnlyRejection(req);
+    res.writeHead(rejection ? 403 : 204, { "Content-Type": "application/json" });
+    if (!rejection) lastHeard = Date.now();
+    res.end(rejection ? JSON.stringify({ error: rejection }) : undefined);
+    req.resume();
+    return;
+  }
+  if (panelBroker.handle(req, res)) return;
+
+  if (req.method === "OPTIONS" && req.url === "/capture") {
+    res.writeHead(204, CORS_HEADERS);
+    res.end();
+    return;
+  }
+
+  if (req.method !== "POST" || req.url !== "/capture") {
+    res.writeHead(404, { "Content-Type": "application/json", ...CORS_HEADERS });
+    res.end(JSON.stringify({ error: "not found" }));
+    return;
+  }
+
+  let received = 0;
+  const chunks = [];
+  let aborted = false;
+
+  req.on("data", (chunk) => {
+    received += chunk.length;
+    if (received > MAX_BODY_BYTES) {
+      aborted = true;
+      res.writeHead(413, { "Content-Type": "application/json", ...CORS_HEADERS });
+      res.end(JSON.stringify({ error: "payload too large" }));
+      req.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+
+  req.on("end", () => {
+    if (aborted) return;
+    let body;
+    try {
+      body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json", ...CORS_HEADERS });
+      res.end(JSON.stringify({ error: "invalid JSON" }));
+      return;
+    }
+
+    if (!isValidCapture(body)) {
+      res.writeHead(400, { "Content-Type": "application/json", ...CORS_HEADERS });
+      res.end(JSON.stringify({ error: "missing or invalid required fields" }));
+      return;
+    }
+
+    const entry = appendCapture(body);
+    res.writeHead(200, { "Content-Type": "application/json", ...CORS_HEADERS });
+    res.end(JSON.stringify({ ok: true, attemptSeq: entry.attemptSeq }));
+  });
+
+  req.on("error", () => {
+    // Client disconnected mid-request; nothing to do.
+  });
+});
+
+loadExistingSequences();
+
+if (IDLE_EXIT_MS > 0) {
+  setInterval(() => {
+    if (panelBroker.openPanelStreams() > 0) lastHeard = Date.now();
+    if (Date.now() - lastHeard < IDLE_EXIT_MS) return;
+    console.log(`nothing heard for ${Math.round(IDLE_EXIT_MS / 1000)} s, exiting`);
+    process.exit(0);
+  }, Math.min(IDLE_EXIT_MS, 10000)).unref();
+}
+
+// Started by the helper with a pipe for stdin: the helper closing it (or
+// dying, which closes it too) means stop.
+if (/^(1|true|yes)$/i.test(process.env.RELAY_EXIT_WITH_STDIN || "")) {
+  process.stdin.on("end", () => process.exit(0));
+  process.stdin.on("error", () => process.exit(0));
+  process.stdin.resume();
+}
+
+server.listen(PORT, HOST, () => {
+  console.log(`leetcode-capture relay server listening on http://${HOST}:${PORT}`);
+  console.log(`logging captures to ${LOG_PATH}`);
+});

package/runtime/vault-tool/log-session.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// LeetCode Capture - vault-logging tool
+//
+// Manual, explicit v1: given a captured problem's log entries (from the
+// relay server's captures.jsonl), produces a short struggle/proficiency
+// note and appends it into Thomson's Obsidian vault.
+//
+// Usage:
+//   node log-session.js --slug <problem-slug> [options]
+//
+// Options:
+//   --log <path>       Path to the captures.jsonl log file
+//                       (default: ../relay-server/data/captures.jsonl)
+//   --vault <path>     Path to the Obsidian vault root
+//                       (default: VAULT_PATH env var, then vault.config.json's
+//                       "vaultPath", then ~/Documents/My Brain - see
+//                       vault-notes.js's resolveVaultConfig)
+//   --note <text>      Freeform note text to include (optional)
+//   --accepted         Mark the session as accepted (last Submit passed)
+//   --dry-run          Print the note instead of writing it
+//
+// Matching: searches Study/Algorithms/*.md in the vault for a markdown
+// link containing /problems/<slug>/. If found, the note is appended under
+// that file's "## LeetCode Problems" section. Otherwise, a new per-problem
+// note is created under Study/Algorithms/Problems/<Title>.md following the
+// vault's existing note conventions (frontmatter tags, etc).
+
+const fs = require("fs");
+const path = require("path");
+const {
+  safeFileName,
+  findTopicNoteByProblemLink,
+  resolveVaultConfig,
+  validateVaultPath,
+} = require("./vault-notes");
+
+function parseArgs(argv) {
+  const args = { dryRun: false, accepted: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--slug") args.slug = argv[++i];
+    else if (arg === "--log") args.log = argv[++i];
+    else if (arg === "--vault") args.vault = argv[++i];
+    else if (arg === "--note") args.note = argv[++i];
+    else if (arg === "--accepted") args.accepted = true;
+    else if (arg === "--dry-run") args.dryRun = true;
+    else {
+      console.error(`Unknown argument: ${arg}`);
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+function loadCaptures(logPath, slug) {
+  if (!fs.existsSync(logPath)) {
+    throw new Error(`log file not found: ${logPath}`);
+  }
+  const lines = fs.readFileSync(logPath, "utf8").split("\n").filter(Boolean);
+  const entries = [];
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue; // skip malformed lines
+    }
+    if (entry.problemSlug === slug) entries.push(entry);
+  }
+  entries.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+  return entries;
+}
+
+function formatDuration(ms) {
+  if (ms < 0) ms = 0;
+  const totalSeconds = Math.round(ms / 1000);
+  const h = Math.floor(totalSeconds / 3600);
+  const m = Math.floor((totalSeconds % 3600) / 60);
+  const s = totalSeconds % 60;
+  const parts = [];
+  if (h > 0) parts.push(`${h}h`);
+  if (m > 0 || h > 0) parts.push(`${m}m`);
+  parts.push(`${s}s`);
+  return parts.join(" ");
+}
+
+function summarize(entries, accepted) {
+  if (entries.length === 0) {
+    throw new Error("no captures found for this problem slug");
+  }
+
+  const runs = entries.filter((e) => e.trigger === "run");
+  const submits = entries.filter((e) => e.trigger === "submit");
+  const firstRun = runs[0] || entries[0];
+  const lastSubmit = submits[submits.length - 1];
+
+  const elapsedMs = lastSubmit
+    ? new Date(lastSubmit.timestamp) - new Date(firstRun.timestamp)
+    : null;
+
+  // Not every capture necessarily carries a description (older captures
+  // predate this field, or the DOM panel wasn't found at capture time), so
+  // take the first one that has it.
+  const withDescription = entries.find((e) => e.problemDescription);
+
+  return {
+    problemSlug: entries[0].problemSlug,
+    problemTitle: entries[0].problemTitle || entries[0].problemSlug,
+    problemDescription: withDescription ? withDescription.problemDescription : null,
+    language: entries[entries.length - 1].language,
+    attemptCount: entries.length,
+    runCount: runs.length,
+    submitCount: submits.length,
+    elapsedMs,
+    accepted,
+    sessionDate: firstRun.timestamp.slice(0, 10),
+  };
+}
+
+function buildNoteBlock(summary, freeformNote) {
+  const elapsed = summary.elapsedMs !== null
+    ? formatDuration(summary.elapsedMs)
+    : "n/a (no Submit captured)";
+  const status = summary.submitCount === 0
+    ? "no submit captured"
+    : summary.accepted
+      ? "accepted"
+      : "not accepted";
+
+  const lines = [
+    `### Capture session: ${summary.sessionDate}`,
+    `- Problem: ${summary.problemTitle} (${summary.problemSlug})`,
+    `- Language: ${summary.language}`,
+    `- Attempts: ${summary.attemptCount} (${summary.runCount} run, ${summary.submitCount} submit)`,
+    `- Elapsed (first Run -> ${summary.submitCount ? "last Submit" : "n/a"}): ${elapsed}`,
+    `- Result: ${status}`,
+  ];
+  if (freeformNote) {
+    lines.push(`- Note: ${freeformNote}`);
+  }
+  let block = lines.join("\n") + "\n";
+  if (summary.problemDescription) {
+    block += `\n**Problem statement:**\n\n${summary.problemDescription}\n`;
+  }
+  return block;
+}
+
+function appendToTopicNote(filePath, noteBlock) {
+  let content = fs.readFileSync(filePath, "utf8");
+  const sectionHeader = "## LeetCode Problems";
+  const sectionIdx = content.indexOf(sectionHeader);
+
+  if (sectionIdx === -1) {
+    // No existing problems section; append at end of file.
+    content = content.replace(/\n*$/, "\n\n") + noteBlock;
+  } else {
+    // Insert a "Capture Sessions" subsection right after the
+    // "## LeetCode Problems" section, before the next "## " heading (or EOF).
+    const afterHeader = sectionIdx + sectionHeader.length;
+    const nextSectionMatch = content.slice(afterHeader).match(/\n## /);
+    const insertAt = nextSectionMatch
+      ? afterHeader + nextSectionMatch.index
+      : content.length;
+
+    const before = content.slice(0, insertAt).replace(/\n*$/, "\n");
+    const after = content.slice(insertAt);
+    content = `${before}\n${noteBlock}${after}`;
+  }
+
+  fs.writeFileSync(filePath, content);
+}
+
+function createPerProblemNote(vaultPath, summary, noteBlock, algorithmsSubfolder) {
+  const problemsDir = path.join(vaultPath, algorithmsSubfolder, "Problems");
+  fs.mkdirSync(problemsDir, { recursive: true });
+
+  const filePath = path.join(problemsDir, `${safeFileName(summary.problemTitle)}.md`);
+
+  const frontmatter = "---\ntags:\n  - study/algorithms\n---\n\n";
+  const heading = `[${summary.problemTitle}](https://leetcode.com/problems/${summary.problemSlug}/)\n\n`;
+  const sectionHeader = "## LeetCode Problems\n\n";
+
+  let content;
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, "utf8");
+    content = content.replace(/\n*$/, "\n\n") + noteBlock;
+  } else {
+    content = frontmatter + heading + sectionHeader + noteBlock;
+  }
+
+  fs.writeFileSync(filePath, content);
+  return filePath;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.slug) {
+    console.error("Usage: node log-session.js --slug <problem-slug> [--log <path>] [--vault <path>] [--note <text>] [--accepted] [--dry-run]");
+    process.exit(1);
+  }
+
+  const logPath = args.log || path.join(__dirname, "..", "relay-server", "data", "captures.jsonl");
+  const vaultConfig = resolveVaultConfig();
+  // --vault is an explicit per-invocation override, so it outranks both the
+  // env var and the config file resolveVaultConfig() already applied.
+  const vaultPath = args.vault || vaultConfig.vaultPath;
+  const algorithmsSubfolder = vaultConfig.algorithmsSubfolder;
+
+  const entries = loadCaptures(logPath, args.slug);
+  const summary = summarize(entries, args.accepted);
+  const noteBlock = buildNoteBlock(summary, args.note);
+
+  if (args.dryRun) {
+    console.log(noteBlock);
+    return;
+  }
+
+  validateVaultPath(vaultPath);
+
+  const topicNote = findTopicNoteByProblemLink(vaultPath, args.slug, algorithmsSubfolder);
+  if (topicNote) {
+    appendToTopicNote(topicNote, noteBlock);
+    console.log(`Appended capture session to ${topicNote}`);
+  } else {
+    const created = createPerProblemNote(vaultPath, summary, noteBlock, algorithmsSubfolder);
+    console.log(`No matching topic note found; wrote per-problem note to ${created}`);
+  }
+}
+
+main();

package/runtime/vault-tool/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "commonjs"
+}

package/runtime/vault-tool/vault-notes.js

@@ -0,0 +1,206 @@
+// vault-tool/vault-notes.js - shared vault note helpers
+//
+// Extracted so both the manual CLI (log-session.js) and the companion's
+// automatic vault-summary feature (companion/companion.js) build on the same
+// per-problem/per-topic note-linking logic instead of two parallel
+// implementations. Node CommonJS, no deps, same as the rest of vault-tool.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+function defaultVaultPath() {
+  return path.join(os.homedir(), "Documents", "My Brain");
+}
+
+const DEFAULT_ALGORITHMS_SUBFOLDER = path.join("Study", "Algorithms");
+
+// Optional, gitignored config file at the repo root letting a user other
+// than Thomson point this tool at their own vault without touching code or
+// setting env vars every session. Plain JSON, parsed with JSON.parse, per
+// this project's no-external-deps convention (see CLAUDE.md). Both keys are
+// optional; a missing file is not an error - it just means "use env vars
+// and/or the built-in defaults", which is what Thomson's own setup already
+// relies on.
+function vaultConfigFilePath() {
+  return path.join(__dirname, "..", "vault.config.json");
+}
+
+function loadVaultConfigFile() {
+  const configPath = vaultConfigFilePath();
+  if (!fs.existsSync(configPath)) return {};
+
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch (err) {
+    throw new Error(`Could not read vault config file at ${configPath}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Vault config file at ${configPath} is not valid JSON: ${err.message}`);
+  }
+}
+
+// Single place both log-session.js and companion/vault-summary.js resolve
+// the vault path and the algorithm-notes subfolder through, so the two
+// consumers can never disagree on precedence. Precedence, highest first:
+// explicit env var, then the config file, then the built-in default - so a
+// vault.config.json with no VAULT_PATH/VAULT_ALGORITHMS_SUBFOLDER set still
+// lets a stray env var win, and no config file at all reproduces Thomson's
+// existing behavior exactly.
+function resolveVaultConfig() {
+  const fileConfig = loadVaultConfigFile();
+  const vaultPath = process.env.VAULT_PATH || fileConfig.vaultPath || defaultVaultPath();
+  const algorithmsSubfolder =
+    process.env.VAULT_ALGORITHMS_SUBFOLDER || fileConfig.algorithmsSubfolder || DEFAULT_ALGORITHMS_SUBFOLDER;
+  return { vaultPath, algorithmsSubfolder };
+}
+
+// Fails loudly, naming the exact path and how to fix it, rather than letting
+// a wrong or unset vault path silently fabricate a brand-new folder tree
+// (the old behavior - ensurePerProblemNoteFile used to mkdirSync the whole
+// path unconditionally). A missing .obsidian folder only warns, since a
+// legitimate vault path passed via config/env could plausibly not carry one
+// (e.g. .obsidian excluded from a synced copy) - that's a much lower-risk
+// false negative than treating a bare "does this directory exist" check as
+// fatal would be.
+function validateVaultPath(vaultPath) {
+  if (!fs.existsSync(vaultPath) || !fs.statSync(vaultPath).isDirectory()) {
+    throw new Error(
+      `Vault path does not exist: ${vaultPath}\n` +
+        "Set VAULT_PATH, or \"vaultPath\" in vault.config.json (see README.md), to your Obsidian vault's absolute path."
+    );
+  }
+  if (!fs.existsSync(path.join(vaultPath, ".obsidian"))) {
+    console.warn(`Warning: ${vaultPath} exists but has no .obsidian folder - is this really an Obsidian vault?`);
+  }
+}
+
+// Shared with log-session.js's per-problem note filenames, so the manual CLI
+// and the automatic feature always agree on where a given problem's note
+// lives.
+function safeFileName(title) {
+  return title.replace(/[\\/:*?"<>|]/g, "-");
+}
+
+// Searches Study/Algorithms/*.md for a note whose content already links to
+// this problem (https://leetcode.com/problems/<slug>/...). This is the
+// original log-session.js matching strategy: it finds a topic note Thomson
+// has already curated to include this specific problem, regardless of the
+// note's filename.
+function findTopicNoteByProblemLink(vaultPath, slug, algorithmsSubfolder = DEFAULT_ALGORITHMS_SUBFOLDER) {
+  const algDir = path.join(vaultPath, algorithmsSubfolder);
+  if (!fs.existsSync(algDir)) return null;
+
+  const files = fs.readdirSync(algDir).filter((f) => f.endsWith(".md"));
+  const needle = `/problems/${slug}/`;
+  for (const file of files) {
+    const fullPath = path.join(algDir, file);
+    const content = fs.readFileSync(fullPath, "utf8");
+    if (content.includes(needle)) {
+      return fullPath;
+    }
+  }
+  return null;
+}
+
+// Matches a LeetCode topic tag (e.g. "Dynamic Programming") to an existing
+// Study/Algorithms/<Tag>.md note by filename, case-insensitively. Used by
+// the automatic vault-summary feature: LeetCode's own tags are the source of
+// truth for what topic(s) a problem belongs to (see README.md), but only
+// tags that already have a curated topic note in the vault get linked -
+// this deliberately does not auto-create a new topic note for every raw
+// LeetCode tag (e.g. "Array", "Hash Table" have no note of their own yet),
+// since those are curated concept notes with real prose, not stubs to
+// generate. Returns the absolute path, or null if no matching note exists.
+function findTopicNoteByTagName(vaultPath, tagName, algorithmsSubfolder = DEFAULT_ALGORITHMS_SUBFOLDER) {
+  const algDir = path.join(vaultPath, algorithmsSubfolder);
+  if (!fs.existsSync(algDir)) return null;
+
+  const target = `${tagName}.md`.toLowerCase();
+  const files = fs.readdirSync(algDir).filter((f) => f.endsWith(".md"));
+  const match = files.find((f) => f.toLowerCase() === target);
+  return match ? path.join(algDir, match) : null;
+}
+
+// Finds (or creates, with minimal frontmatter + a heading link) the
+// per-problem note under Study/Algorithms/Problems/. Mirrors
+// log-session.js's createPerProblemNote frontmatter/heading shape exactly,
+// so a note this creates and one log-session.js creates are
+// indistinguishable, and either tool can safely extend a note the other one
+// started.
+function ensurePerProblemNoteFile(
+  vaultPath,
+  { problemSlug, problemTitle },
+  algorithmsSubfolder = DEFAULT_ALGORITHMS_SUBFOLDER
+) {
+  validateVaultPath(vaultPath);
+  const problemsDir = path.join(vaultPath, algorithmsSubfolder, "Problems");
+  fs.mkdirSync(problemsDir, { recursive: true });
+
+  const filePath = path.join(problemsDir, `${safeFileName(problemTitle)}.md`);
+  if (!fs.existsSync(filePath)) {
+    const frontmatter = "---\ntags:\n  - study/algorithms\n---\n\n";
+    const heading = `[${problemTitle}](https://leetcode.com/problems/${problemSlug}/)\n`;
+    fs.writeFileSync(filePath, frontmatter + heading);
+  }
+  return filePath;
+}
+
+// Returns the current body text of a "## <Header>" section (everything up
+// to the next "## " heading or EOF), trimmed - or null if the section
+// doesn't exist yet. Used to read what's already there before rewriting it,
+// so a rewrite can factor in prior content instead of blindly discarding it.
+function readSection(content, header) {
+  const idx = content.indexOf(header);
+  if (idx === -1) return null;
+  const rest = content.slice(idx + header.length);
+  const nextMatch = rest.match(/\n##[ \t]/);
+  const body = nextMatch ? rest.slice(0, nextMatch.index) : rest;
+  const trimmed = body.trim();
+  return trimmed || null;
+}
+
+// Replaces a "## <Header>" section's body in place with bodyText, or
+// appends a new "## <Header>" section at the end of the file if it doesn't
+// exist yet. Leaves everything else in the file untouched, including
+// whatever section follows. Idempotent: calling this twice with the same
+// bodyText produces the same content both times.
+function upsertSection(content, header, bodyText) {
+  const newSection = `${header}\n\n${bodyText.trim()}\n`;
+  const idx = content.indexOf(header);
+
+  if (idx === -1) {
+    const base = content.replace(/\n*$/, "\n\n");
+    return `${base}${newSection}`;
+  }
+
+  const rest = content.slice(idx + header.length);
+  const nextMatch = rest.match(/\n##[ \t]/);
+  const sectionEndInRest = nextMatch ? nextMatch.index + 1 : rest.length; // +1 keeps the \n that starts the next heading
+  const before = content.slice(0, idx);
+  const after = rest.slice(sectionEndInRest);
+
+  // newSection already ends in \n; only add a separating blank line when
+  // there's a following section to separate from. Without this check,
+  // upserting the last section in a file grows it by one blank line on
+  // every call - breaking the idempotency callers rely on for "repeated
+  // submits on the same problem update the same section in place".
+  return after ? `${before}${newSection}\n${after}` : `${before}${newSection}`;
+}
+
+module.exports = {
+  defaultVaultPath,
+  DEFAULT_ALGORITHMS_SUBFOLDER,
+  vaultConfigFilePath,
+  resolveVaultConfig,
+  validateVaultPath,
+  safeFileName,
+  findTopicNoteByProblemLink,
+  findTopicNoteByTagName,
+  ensurePerProblemNoteFile,
+  readSection,
+  upsertSection,
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.