leetcode-capture-helper 0.1.0 → 0.1.1

package/config.js

@@ -22,4 +22,4 @@ export const CHROME_EXTENSION_IDS = [];
 
 export const CHROME_ID_RE = /^[a-p]{32}$/;
 
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.1';

package/host.js

@@ -45,6 +45,7 @@ export const DEFAULTS = {
   relayIdleExitMs: 5 * 60 * 1000,
   stopTimeoutMs: 3000,
   startTimeoutMs: 5000,
+  reviveMs: 10 * 1000,
 };
 
 // Where the companion and relay live: LEETCODE_CAPTURE_ROOT, else the `root`
@@ -107,6 +108,7 @@ export function createHost({
   relayIdleExitMs = DEFAULTS.relayIdleExitMs,
   stopTimeoutMs = DEFAULTS.stopTimeoutMs,
   startTimeoutMs = DEFAULTS.startTimeoutMs,
+  reviveMs = DEFAULTS.reviveMs,
   rootError = null,
 }) {
   const port = env.CAPTURE_PORT ? Number(env.CAPTURE_PORT) : 8135;
@@ -118,6 +120,18 @@ export function createHost({
   let starting = null;
   let shuttingDown = null;
   let lastHeard = now();
+  let wantRunning = false;
+  let lastRevive = 0;
+
+  // One line in helper.log for each thing that matters when a start goes wrong.
+  function note(text) {
+    if (typeof logFd !== 'number') return;
+    try {
+      fs.writeSync(logFd, `[host ${new Date(now()).toISOString()}] ${text}\n`);
+    } catch {
+      // no log then
+    }
+  }
 
   function send(message) {
     try {
@@ -154,6 +168,36 @@ export function createHost({
     }
   }
 
+  // Whether a tutor (the companion) is attached to the relay: true, false, or
+  // null when that cannot be told. The relay's panel stream opens with a
+  // status event that says so.
+  async function companionOnline() {
+    const controller = new AbortController();
+    const timer = timers.setTimeout(() => controller.abort(), 1500);
+    try {
+      const response = await fetchImpl(`${base}/panel/events?after=0`, { signal: controller.signal });
+      if (!response || !response.body || typeof response.body.getReader !== 'function') return null;
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let text = '';
+      for (;;) {
+        // eslint-disable-next-line no-await-in-loop
+        const { done, value } = await reader.read();
+        if (done) return null;
+        text += decoder.decode(value, { stream: true });
+        const match = /"companionOnline":(true|false)/.exec(text);
+        if (match) {
+          controller.abort();
+          return match[1] === 'true';
+        }
+      }
+    } catch {
+      return null;
+    } finally {
+      timers.clearTimeout(timer);
+    }
+  }
+
   function startChild(script, extraEnv) {
     const child = spawn(execPath, [path.basename(script)], {
       cwd: path.join(root, path.dirname(script)),
@@ -167,8 +211,10 @@ export function createHost({
     if (child.stdin) child.stdin.on('error', () => {});
     child.on('error', (err) => {
       lastError = `could not start ${script}: ${err.message}`;
+      note(lastError);
     });
-    child.on('exit', () => {
+    child.on('exit', (code, signal) => {
+      note(`${script} exited (code ${code}, signal ${signal})`);
       if (!shuttingDown) send(status());
     });
     return child;
@@ -180,6 +226,15 @@ export function createHost({
       relayExternal = false;
       if (await relayUp()) {
         relayExternal = true;
+        note('a relay already answers on this port; leaving it alone');
+        // A relay somebody else started may have no tutor attached: then the
+        // extension's Settings page stays locked. Start one unless it is there.
+        if (!alive(companion) && (await companionOnline()) === false) {
+          note('no tutor is attached to that relay; starting the companion');
+          companion = startChild('companion/companion.js', { COMPANION_HEADLESS: '1' });
+        }
+        lastError = null;
+        send(status());
         return;
       }
       relay = startChild('relay-server/server.js', {
@@ -196,12 +251,14 @@ export function createHost({
       }
       if (!up) {
         lastError = `the relay did not start on ${base}`;
+        note(lastError);
         return;
       }
     }
     if (!alive(companion)) {
       companion = startChild('companion/companion.js', { COMPANION_HEADLESS: '1' });
     }
+    note(`started: relay pid ${relay && relay.pid}, companion pid ${companion && companion.pid}`);
     lastError = null;
     send(status());
   }
@@ -265,6 +322,8 @@ export function createHost({
         send(status(id));
         return;
       case 'start':
+        wantRunning = true;
+        note('start requested');
         await ensureStarted();
         send(status(id));
         return;
@@ -294,8 +353,23 @@ export function createHost({
     if (alive(relay)) {
       fetchImpl(`${base}/helper/keepalive`, { method: 'POST', headers: { 'x-lc-companion': '1' } }).catch(() => {});
     }
+    revive();
   }, Math.min(keepaliveMs, idleMs));
 
+  // Once asked to start, notice a relay or tutor that has gone away (a relay
+  // that was somebody else's and stopped, a child that crashed) and bring it
+  // back, at most every reviveMs.
+  async function revive() {
+    if (!wantRunning || starting || shuttingDown || rootError || now() - lastRevive < reviveMs) return;
+    const relayGone = relayExternal ? !(await relayUp()) : !alive(relay);
+    const companionGone = !relayExternal && !alive(companion);
+    if (relayGone || companionGone) {
+      lastRevive = now();
+      note('something went away; starting it again');
+      await ensureStarted().catch(() => {});
+    }
+  }
+
   const decoder = createDecoder({
     onMessage: (message) => {
       handle(message).catch((err) => send({ type: 'error', id: message && message.id, error: err.message }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leetcode-capture-helper",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Native Messaging helper for LeetCode Capture: lets the browser extension start and stop the local companion and relay for the Claude and ChatGPT subscriptions. The package carries its own copy of the companion and relay.",
   "type": "module",
   "bin": {

package/runtime/bundle.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0",
+  "version": "0.1.1",
   "note": "Built by scripts/pack.mjs from the LeetCode Capture repository. Do not edit.",
   "files": [
     "companion/capture-log.js",

package/runtime/companion/companion.js

@@ -24,8 +24,7 @@
 //     built-in fetch. "openai" is the same backend against OpenAI's API.
 //   - "chatgpt": the Codex CLI on a ChatGPT sign-in (codex-backend.js).
 //
-// See the "Companion" section of the top-level README.md for setup,
-// environment variables, and exactly what credentials each backend needs.
+// Setup: the environment variables, and exactly what credentials each backend needs.
 
 import fs from 'node:fs';
 import os from 'node:os';
@@ -202,7 +201,7 @@ const LOCAL_RESERVE_TOKENS = Number(process.env.COMPANION_LOCAL_RESERVE_TOKENS |
 // The other options also come from settings.js (`effective.options`):
 //   - vaultAutoSummary (VAULT_AUTO_SUMMARY), off by default: a portable
 //     checkout won't have this vault's Study/Algorithms structure, or even
-//     use Obsidian. See "Vault auto-summary" below and README.md.
+//     use Obsidian.
 //   - autoClearContext (COMPANION_AUTO_CLEAR_CONTEXT), on by default: see the
 //     "automatic context reset on problem switch" section below for why
 //     leaving it on is the safer default (a stale problem's code and
@@ -467,9 +466,8 @@ function backendLabel() {
 // it exits - one command instead of two. If a server was already running
 // (started separately, or left over from another companion instance), this
 // instance leaves it alone on both ends: it doesn't spawn a second one, and
-// it doesn't stop it on exit. See the "Companion" section of the top-level
-// README.md for the durability tradeoff this implies (captures during a gap
-// where companion.js isn't running are no longer durably logged).
+// it doesn't stop it on exit. The tradeoff: captures during a gap
+// where companion.js isn't running are no longer durably logged.
 
 // Set only if *this* process spawned the relay server; stays null if an
 // already-running server was found instead, so the exit handler below knows
@@ -678,8 +676,7 @@ function resetTutorContext() {
 // session progresses. The actual logic (building the addendum, parsing the
 // model's reply, writing the notes) lives in vault-summary.js, split out so
 // it can be unit-tested without booting this file's readline loop / relay
-// server lifecycle - see that file's header for the full design, and
-// README.md → "Vault auto-summary" for user-facing docs.
+// server lifecycle - see that file's header for the full design.
 
 // --- terminal chat loop ------------------------------------------------------
 //

package/runtime/companion/vault-summary.js

@@ -3,9 +3,8 @@
 // Split out from companion.js so this feature's actual logic (building the
 // addendum, parsing the model's reply, writing the notes) can be exercised
 // directly by tests without booting companion.js's interactive readline
-// loop or relay-server lifecycle. See README.md → "Vault auto-summary" for
-// the full design and companion.js for how this gets wired into the capture
-// handling path.
+// loop or relay-server lifecycle. See companion.js for how this gets wired
+// into the capture handling path.
 //
 // The core constraint shaping this file: reuse the same backend response
 // already being shown in the terminal for a Submit, and never make a

package/runtime/extension/shared/code-ledger.js

@@ -1,7 +1,7 @@
 // extension/shared/code-ledger.js - what code the tutor has already been shown, and
 // what to tell it next.
 //
-// The rules (Thomson's request, see README.md, "What the tutor is sent"):
+// The rules (Thomson's request):
 //   - A Run (the button or Ctrl+') is never sent to the tutor on its own. It
 //     is only recorded, as the newest code for its problem.
 //   - A Submit is sent automatically, but only when its code differs from

package/runtime/extension/shared/roadmap.js

@@ -2,7 +2,7 @@
 // plus the pure logic they share. No Node or browser APIs, so the options
 // page, the background worker and the companion can all import it.
 //
-// A list is { id, title, short, description, kind, topics, edges, subjects }:
+// A list is { id, title, short, kind, topics, edges, subjects }:
 //   topics    its groups in the publisher's order, each { id, title, problems }
 //             where a problem is { slug, title, difficulty, topic } (title and
 //             difficulty come from the one shared catalog, shared/catalog.js)
@@ -24,7 +24,7 @@ import { CATALOG } from './catalog.js';
 const words = (slugs) => slugs.split(/\s+/).filter(Boolean);
 
 // Each group: [id, title, slugs], the slugs one per line in the list's order.
-function defineList({ id, title, short, description, groupNoun, groups, edges = [], subjects = null }) {
+function defineList({ id, title, short, groupNoun, groups, edges = [], subjects = null }) {
   const topics = groups.map(([topicId, topicTitle, slugs]) => ({
     id: topicId,
     title: topicTitle,
@@ -35,7 +35,7 @@ function defineList({ id, title, short, description, groupNoun, groups, edges =
     }),
   }));
   const size = topics.reduce((n, t) => n + t.problems.length, 0);
-  const list = { id, title, short: short || title, description, groupNoun, kind: edges.length ? 'graph' : 'groups', size, topics, edges, subjects: null };
+  const list = { id, title, short: short || title, groupNoun, kind: edges.length ? 'graph' : 'groups', size, topics, edges, subjects: null };
   if (subjects) list.subjects = defineSubjects(list, subjects);
   return list;
 }
@@ -94,7 +94,6 @@ const EDGES = [
 export const NEETCODE_150 = defineList({
   id: 'neetcode-150',
   title: 'NeetCode 150',
-  description: 'NeetCode\'s expanded Blind 75, by topic on a roadmap.',
   groupNoun: 'topic',
   edges: EDGES,
   groups: [
@@ -279,7 +278,6 @@ export const NEETCODE_150 = defineList({
 export const NEETCODE_250 = defineList({
   id: 'neetcode-250',
   title: 'NeetCode 250',
-  description: 'NeetCode 150 and 100 more, by topic on the same roadmap.',
   groupNoun: 'topic',
   edges: EDGES,
   groups: [
@@ -566,7 +564,6 @@ export const NEETCODE_250 = defineList({
 export const BLIND_75 = defineList({
   id: 'blind-75',
   title: 'Blind 75',
-  description: 'The original 75 from Blind, by category. NeetCode 150 extends it.',
   groupNoun: 'category',
   groups: [
   ['array', 'Array', `
@@ -672,7 +669,6 @@ export const BLIND_75 = defineList({
 export const GRIND_75 = defineList({
   id: 'grind-75',
   title: 'Grind 75',
-  description: 'By the Blind 75 author: the site\'s default eight weeks, or by subject.',
   groupNoun: 'week',
   groups: [
   ['week-1', 'Week 1', `
@@ -872,8 +868,7 @@ export const GRIND_75 = defineList({
 // against e2e/leetcode-study-plans.txt by roadmap.test.mjs.
 export const TOP_100_LIKED = defineList({
   id: 'top-100-liked',
-  title: 'Top 100 Liked',
-  description: 'LeetCode\'s 100 most liked problems, by topic.',
+  title: 'Top 100 Liked by LeetCode',
   groupNoun: 'topic',
   groups: [
   ['backtracking', 'Backtracking', `
@@ -999,8 +994,7 @@ export const TOP_100_LIKED = defineList({
 // 2026-11-04: e2e/leetcode-study-plans.txt, which roadmap.test.mjs compares.
 export const TOP_INTERVIEW_150 = defineList({
   id: 'top-interview-150',
-  title: 'Top Interview 150',
-  description: 'LeetCode\'s own interview study plan, section by section.',
+  title: 'Top Interview 150 by LeetCode',
   groupNoun: 'section',
   groups: [
   ['array-string', 'Array / String', `
@@ -1184,7 +1178,6 @@ export const TOP_INTERVIEW_150 = defineList({
 export const SQL_50 = defineList({
   id: 'sql-50',
   title: 'SQL 50',
-  description: 'LeetCode\'s study plan for database problems.',
   groupNoun: 'section',
   groups: [
   ['select', 'Select', `

package/runtime/extension/shared/solved.js

@@ -44,6 +44,10 @@ import { LISTS, NEETCODE_150, ROADMAPS, listById, problemInList, suggestAfterSol
 export const SOLVED_KEY = 'solvedProblems';
 export const STARRED_KEY = 'starredProblems';
 export const ACTIVE_LIST_KEY = 'activeProgressList';
+export const SYNCED_AT_KEY = 'solvedSyncedAt';
+// How long an automatic sync waits for the next one; the button ignores it.
+export const SYNC_EVERY_MS = 12 * 60 * 60 * 1000;
+const MAX_SYNC = 6000;
 
 export function isListId(value) {
   return typeof value === 'string' && Object.hasOwn(ROADMAPS, value);
@@ -85,6 +89,7 @@ export function normalizeSolved(raw) {
     const count = Number.isInteger(entry.count) && entry.count >= 0 ? entry.count : 0;
     const clean = { at: validTime(entry.at) ? entry.at : new Date(0).toISOString(), count };
     if (entry.manual === true) clean.manual = true;
+    else if (entry.synced === true) clean.synced = true;
     out[slug] = clean;
   }
   return out;
@@ -113,6 +118,20 @@ export function markSolved(solved, slug, on, at) {
   return next;
 }
 
+// The problems LeetCode says the account solved, added to the list as
+// "synced". Whatever is marked already stays as it is, and nothing is
+// removed. Returns the new record and how many were added.
+export function mergeSynced(solved, slugs, at) {
+  const next = { ...solved };
+  let added = 0;
+  for (const slug of slugs) {
+    if (next[slug]) continue;
+    next[slug] = { at, count: 0, synced: true };
+    added += 1;
+  }
+  return { solved: next, added };
+}
+
 export function solvedSlugs(solved) {
   return Object.keys(solved);
 }
@@ -243,6 +262,23 @@ export function createSolvedService({ storage, extensionOrigin, now = () => new
     });
   }
 
+  // True when an automatic sync is due: never synced, or not for SYNC_EVERY_MS.
+  async function syncDue() {
+    const stored = (await storage.get([SYNCED_AT_KEY])) || {};
+    const last = Date.parse(stored[SYNCED_AT_KEY]);
+    return { ok: true, due: Number.isNaN(last) || Date.parse(now()) - last >= SYNC_EVERY_MS };
+  }
+
+  // `slugs` is what a signed-in LeetCode tab reported as accepted.
+  async function mergeFromLeetCode(slugs) {
+    if (!Array.isArray(slugs) || slugs.length > MAX_SYNC || !slugs.every(isSlug)) return { ok: false };
+    return update(async (solved) => {
+      const merged = mergeSynced(solved, slugs, now());
+      await storage.set({ [SOLVED_KEY]: merged.solved, [SYNCED_AT_KEY]: now() });
+      return { ok: true, added: merged.added, total: new Set(slugs).size };
+    });
+  }
+
   async function setStarred(message) {
     if (!isSlug(message.slug) || typeof message.starred !== 'boolean') return { ok: false };
     return update(async (_solved, starred) => {
@@ -257,9 +293,12 @@ export function createSolvedService({ storage, extensionOrigin, now = () => new
   return {
     // Resolves to the answer, or undefined when the message is not for this
     // service.
+    mergeFromLeetCode,
     async handleMessage(message, sender) {
       if (!message || typeof message !== 'object') return undefined;
       try {
+        if (message.type === 'lc-tutor:sync-check') return sender && sender.tab && slugFromUrl(sender.url) ? await syncDue() : { ok: false };
+        if (message.type === 'lc-tutor:sync-solved') return sender && sender.tab && slugFromUrl(sender.url) ? await mergeFromLeetCode(message.slugs) : { ok: false };
         if (message.type === 'lc-tutor:accepted') return await accepted(message, sender);
         if (message.type === 'lc-tutor:set-list') return await setList(message, sender);
         if (message.type === 'lc-tutor:practice') return await practice(message, sender);

package/runtime/relay-server/server.js

@@ -5,7 +5,7 @@
 // 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. See README.md.
+// overridden with the CAPTURE_LOG_PATH environment variable.
 // The log is cleared as the companion consumes it (see trimCaptureLog).
 
 const http = require("http");