leetcode-capture-helper 0.0.0-stage → 0.1.0

package/cli.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// leetcode-capture-helper install | uninstall | status
+//
+//   install [--chrome-id <id>]... [--browser <id>]... [--root <folder>]
+//     Registers the helper with the browsers found for this user (or only the
+//     ones named with --browser). Chrome, Chromium, Edge and Brave need the
+//     extension's id, which the extension's settings page shows in the
+//     command to copy. --root is the LeetCode Capture folder holding
+//     companion/ and relay-server/ (by default the one this helper is in).
+//   uninstall  Removes exactly what install wrote.
+//   status     Shows what is registered where.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BROWSER_IDS, install, status, uninstall } from './install.js';
+import { resolveRoot } from './host.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+export function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const options = { command, chromeIds: [], browsers: [], root: null };
+  for (let i = 0; i < rest.length; i += 1) {
+    const flag = rest[i];
+    const value = rest[i + 1];
+    const take = () => {
+      if (value === undefined || value.startsWith('--')) throw new Error(`${flag} needs a value`);
+      i += 1;
+      return value;
+    };
+    if (flag === '--chrome-id') options.chromeIds.push(...take().split(','));
+    else if (flag === '--browser') options.browsers.push(...take().split(','));
+    else if (flag === '--root') options.root = take();
+    else throw new Error(`unknown option ${flag}`);
+  }
+  return options;
+}
+
+const USAGE = `usage: leetcode-capture-helper <install|uninstall|status> [options]
+
+  install [--chrome-id <id>]... [--browser <${BROWSER_IDS.join('|')}>]... [--root <folder>]
+  uninstall
+  status`;
+
+export function run(argv, { home = os.homedir(), env = process.env, platform = process.platform, reg, print = console.log } = {}) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (err) {
+    print(`${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+  const common = { home, env, platform, ...(reg ? { reg } : {}) };
+  try {
+    if (options.command === 'install') {
+      const result = install({
+        ...common,
+        root: options.root ? path.resolve(options.root) : resolveRoot(env, HERE),
+        chromeIds: options.chromeIds,
+        browsers: options.browsers.length ? options.browsers : null,
+      });
+      if (result.registered.length) print(`Registered the LeetCode Capture helper with: ${result.registered.join(', ')}.`);
+      for (const note of result.notes) print(note);
+      print(`Files are in ${result.dataDir}. Reload the extension's settings page to see the helper.`);
+      return result.registered.length ? 0 : 1;
+    }
+    if (options.command === 'uninstall') {
+      const result = uninstall(common);
+      print(result.nothing ? 'The helper is not installed.' : `Removed the helper (${result.removed.length} items).`);
+      return 0;
+    }
+    if (options.command === 'status') {
+      const s = status(common);
+      print(s.installed ? `Installed (version ${s.version}) in ${s.dataDir}` : 'Not installed.');
+      if (s.root) print(`LeetCode Capture folder: ${s.root}${s.rootError ? ` (problem: ${s.rootError})` : ''}`);
+      for (const b of s.browsers) print(`  ${b.label}: ${b.registered ? `registered for ${b.allowed.join(', ')}` : 'not registered'}`);
+      return s.installed ? 0 : 1;
+    }
+  } catch (err) {
+    print(`leetcode-capture-helper: ${err.message}`);
+    return 1;
+  }
+  print(USAGE);
+  return 2;
+}
+
+// npx and global installs run this through a symlink in node_modules/.bin.
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = run(process.argv.slice(2));
+}

package/config.js

@@ -0,0 +1,25 @@
+// The one place that names this helper and the extensions allowed to talk to
+// it. The installer writes these into the browsers' registration files.
+
+// Native Messaging host name: lowercase letters, digits, dots and underscores.
+// The extension's background worker connects to this exact name.
+export const HOST_NAME = 'dev.thomsonklee.leetcode_capture';
+
+export const HOST_DESCRIPTION = 'LeetCode Capture helper (starts the local tutor companion and relay)';
+
+// Firefox: the gecko id from extension/manifest.json
+// (browser_specific_settings.gecko.id). It never changes.
+export const GECKO_ID = 'leetcode-capture@thomsonklee.dev';
+
+// Chrome, Chromium, Edge and Brave identify an extension by a 32-letter id.
+// An unpacked copy gets an id from its folder path (or from a `key` in its
+// manifest), and a store copy gets the store's id, so there is no single
+// built-in value yet.
+// Set the published Chrome Web Store id (and the Edge Add-ons id, if it
+// differs) here once they exist; until then `install --chrome-id <id>` adds
+// the id the options page shows (chrome://extensions lists it too).
+export const CHROME_EXTENSION_IDS = [];
+
+export const CHROME_ID_RE = /^[a-p]{32}$/;
+
+export const VERSION = '0.1.0';

package/framing.js

@@ -0,0 +1,57 @@
+// Native Messaging framing: every message, in both directions, is a 4-byte
+// little-endian length followed by that many bytes of UTF-8 JSON.
+// https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging
+// Firefox uses the same framing.
+
+// The browser refuses a message from the host above 1 MB.
+export const MAX_OUTGOING_BYTES = 1024 * 1024;
+// Messages from the extension are small commands; anything far larger is a
+// broken stream, not a message.
+export const MAX_INCOMING_BYTES = 1024 * 1024;
+
+export function encodeMessage(message) {
+  const body = Buffer.from(JSON.stringify(message), 'utf8');
+  if (body.length > MAX_OUTGOING_BYTES) throw new Error(`message too large (${body.length} bytes)`);
+  const header = Buffer.alloc(4);
+  header.writeUInt32LE(body.length, 0);
+  return Buffer.concat([header, body]);
+}
+
+// Feed it chunks as they arrive; it calls onMessage once per whole message,
+// however the chunks split them. onError is called once for a length over
+// the limit or a body that is not JSON, and nothing more is decoded after
+// that (the stream can no longer be trusted to be in step).
+export function createDecoder({ onMessage, onError, maxBytes = MAX_INCOMING_BYTES }) {
+  let buffered = Buffer.alloc(0);
+  let broken = false;
+  return {
+    push(chunk) {
+      if (broken) return;
+      buffered = buffered.length ? Buffer.concat([buffered, chunk]) : Buffer.from(chunk);
+      while (buffered.length >= 4) {
+        const length = buffered.readUInt32LE(0);
+        if (length > maxBytes) {
+          broken = true;
+          onError(new Error(`incoming message too large (${length} bytes)`));
+          return;
+        }
+        if (buffered.length < 4 + length) return;
+        const body = buffered.subarray(4, 4 + length).toString('utf8');
+        buffered = buffered.subarray(4 + length);
+        let message;
+        try {
+          message = JSON.parse(body);
+        } catch {
+          broken = true;
+          onError(new Error('incoming message is not JSON'));
+          return;
+        }
+        onMessage(message);
+      }
+    },
+    // Bytes of a message that never finished (for a clean-shutdown check).
+    get pending() {
+      return buffered.length;
+    },
+  };
+}

package/host.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+// LeetCode Capture helper: the Native Messaging host.
+//
+// The browser starts this program when the extension calls
+// runtime.connectNative(HOST_NAME) and talks to it over stdin and stdout with
+// the framing in framing.js. stdout is that channel, so nothing else may ever
+// be written to it: the children's output goes to a log file.
+//
+// It owns two children, started on the extension's `start`:
+//   - the relay (relay-server/server.js), unless one already answers on the
+//     port (then it is "external" and left alone, and no companion is started
+//     either, since whoever started that relay runs their own companion);
+//   - the companion (companion/companion.js) in COMPANION_HEADLESS mode.
+// Both get a pipe for stdin, so if this process dies in any way (even
+// SIGKILL) the pipe closes and they exit too. The relay also has an idle exit
+// that this host's keepalive holds off while the extension keeps talking.
+//
+// Messages from the extension (each may carry an `id`, echoed in the answer):
+//   { type: 'ping' }    -> { type: 'pong', version }
+//   { type: 'status' }  -> { type: 'status', ... } (see status() below)
+//   { type: 'start' }   -> starts what is not running, then a status
+//   { type: 'reset' }   -> the companion clears its tutor context: { type: 'reset', ok }
+//   { type: 'stop' }    -> stops both children, answers { type: 'stopped' }, exits
+// A status with no id is also sent whenever a child starts or exits.
+//
+// It stops both children and exits when the browser closes stdin (the
+// extension disconnected, or the browser quit or crashed), on SIGTERM, SIGHUP
+// or SIGINT, on `stop`, and when the extension has not sent anything for
+// idleMs (it pings while a LeetCode tab is open).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { createDecoder, encodeMessage } from './framing.js';
+import { VERSION } from './config.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+export const DEFAULTS = {
+  // The extension pings every 60 s; five quiet minutes means it is gone.
+  idleMs: 5 * 60 * 1000,
+  keepaliveMs: 60 * 1000,
+  // The relay's own idle exit, held off by the keepalive above.
+  relayIdleExitMs: 5 * 60 * 1000,
+  stopTimeoutMs: 3000,
+  startTimeoutMs: 5000,
+};
+
+// Where the companion and relay live: LEETCODE_CAPTURE_ROOT, else the `root`
+// the installer recorded next to this file, else the copy bundled in the npm
+// package (runtime/, built by scripts/pack.mjs), else the folder above this
+// file (a checkout of the repository).
+export function resolveRoot(env = process.env, here = HERE) {
+  if (env.LEETCODE_CAPTURE_ROOT) return path.resolve(env.LEETCODE_CAPTURE_ROOT);
+  try {
+    const saved = JSON.parse(fs.readFileSync(path.join(here, 'helper-config.json'), 'utf8'));
+    if (saved && typeof saved.root === 'string') return saved.root;
+  } catch {
+    // no saved config
+  }
+  const bundled = path.join(here, 'runtime');
+  if (isBundled(bundled)) return bundled;
+  return path.resolve(here, '..');
+}
+
+// A bundled copy carries this marker (scripts/pack.mjs writes it).
+export function isBundled(root) {
+  return fs.existsSync(path.join(root, 'bundle.json'));
+}
+
+export function checkRoot(root) {
+  const missing = ['companion/companion.js', 'relay-server/server.js'].filter((rel) => !fs.existsSync(path.join(root, rel)));
+  return missing.length ? `the LeetCode Capture files are missing from ${root} (${missing.join(', ')})` : null;
+}
+
+// A bundled copy may sit in a read-only or throwaway place (a global npm
+// folder, npx's cache), and a new version is a new folder, so its capture log
+// and companion state go to the helper's own data folder instead. A variable
+// already set wins. A checkout keeps its usual places (relay-server/data/).
+export function dataEnv(root, dataDir, env = process.env) {
+  if (!isBundled(root)) return {};
+  const captures = path.join(dataDir, 'data', 'captures.jsonl');
+  return {
+    CAPTURE_LOG_PATH: env.CAPTURE_LOG_PATH || env.LEETCODE_CAPTURES_FILE || captures,
+    LEETCODE_CAPTURES_FILE: env.LEETCODE_CAPTURES_FILE || env.CAPTURE_LOG_PATH || captures,
+    LEETCODE_COMPANION_STATE_FILE: env.LEETCODE_COMPANION_STATE_FILE || path.join(dataDir, 'data', 'companion-state.json'),
+  };
+}
+
+const alive = (child) => Boolean(child) && child.exitCode === null && child.signalCode === null;
+
+export function createHost({
+  input,
+  output,
+  root,
+  env = process.env,
+  spawn = nodeSpawn,
+  fetchImpl = fetch,
+  execPath = process.execPath,
+  logFd = 'ignore',
+  exit = (code) => process.exit(code),
+  now = () => Date.now(),
+  timers = { setInterval, clearInterval, setTimeout, clearTimeout },
+  idleMs = DEFAULTS.idleMs,
+  keepaliveMs = DEFAULTS.keepaliveMs,
+  relayIdleExitMs = DEFAULTS.relayIdleExitMs,
+  stopTimeoutMs = DEFAULTS.stopTimeoutMs,
+  startTimeoutMs = DEFAULTS.startTimeoutMs,
+  rootError = null,
+}) {
+  const port = env.CAPTURE_PORT ? Number(env.CAPTURE_PORT) : 8135;
+  const base = `http://127.0.0.1:${port}`;
+  let relay = null;
+  let companion = null;
+  let relayExternal = false;
+  let lastError = rootError;
+  let starting = null;
+  let shuttingDown = null;
+  let lastHeard = now();
+
+  function send(message) {
+    try {
+      output.write(encodeMessage(message));
+    } catch {
+      // The browser went away; stdin ending will shut everything down.
+    }
+  }
+
+  function status(id) {
+    const relayState = relayExternal ? 'external' : alive(relay) ? 'running' : 'stopped';
+    return {
+      type: 'status',
+      ...(id === undefined ? {} : { id }),
+      version: VERSION,
+      root,
+      port,
+      relay: { state: relayState, pid: alive(relay) ? relay.pid : null },
+      companion: { state: alive(companion) ? 'running' : 'stopped', pid: alive(companion) ? companion.pid : null },
+      error: lastError,
+    };
+  }
+
+  async function relayUp() {
+    const controller = new AbortController();
+    const timer = timers.setTimeout(() => controller.abort(), 500);
+    try {
+      await fetchImpl(`${base}/capture`, { method: 'OPTIONS', signal: controller.signal });
+      return true;
+    } catch {
+      return false;
+    } finally {
+      timers.clearTimeout(timer);
+    }
+  }
+
+  function startChild(script, extraEnv) {
+    const child = spawn(execPath, [path.basename(script)], {
+      cwd: path.join(root, path.dirname(script)),
+      env: { ...env, ...extraEnv },
+      stdio: ['pipe', logFd, logFd],
+      // Its own process group, so a Ctrl+C or hang-up meant for a terminal
+      // this host was started from reaches the host, which stops it in order.
+      detached: true,
+      windowsHide: true,
+    });
+    if (child.stdin) child.stdin.on('error', () => {});
+    child.on('error', (err) => {
+      lastError = `could not start ${script}: ${err.message}`;
+    });
+    child.on('exit', () => {
+      if (!shuttingDown) send(status());
+    });
+    return child;
+  }
+
+  async function start() {
+    if (rootError) return;
+    if (!alive(relay)) {
+      relayExternal = false;
+      if (await relayUp()) {
+        relayExternal = true;
+        return;
+      }
+      relay = startChild('relay-server/server.js', {
+        RELAY_IDLE_EXIT_MS: String(relayIdleExitMs),
+        RELAY_EXIT_WITH_STDIN: '1',
+      });
+      const deadline = now() + startTimeoutMs;
+      let up = false;
+      while (!up && alive(relay) && now() < deadline) {
+        // eslint-disable-next-line no-await-in-loop
+        await new Promise((resolve) => timers.setTimeout(resolve, 100));
+        // eslint-disable-next-line no-await-in-loop
+        up = await relayUp();
+      }
+      if (!up) {
+        lastError = `the relay did not start on ${base}`;
+        return;
+      }
+    }
+    if (!alive(companion)) {
+      companion = startChild('companion/companion.js', { COMPANION_HEADLESS: '1' });
+    }
+    lastError = null;
+    send(status());
+  }
+
+  function ensureStarted() {
+    if (!starting) starting = start().finally(() => (starting = null));
+    return starting;
+  }
+
+  function stopChild(child) {
+    if (!alive(child)) return Promise.resolve();
+    return new Promise((resolve) => {
+      const killTimer = timers.setTimeout(() => {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          // already gone
+        }
+      }, stopTimeoutMs);
+      child.once('exit', () => {
+        timers.clearTimeout(killTimer);
+        resolve();
+      });
+      try {
+        if (child.stdin) child.stdin.end();
+        child.kill('SIGTERM');
+      } catch {
+        // already gone
+      }
+    });
+  }
+
+  async function stopChildren() {
+    // The companion first, so it never sees its relay vanish mid-turn.
+    await stopChild(companion);
+    await stopChild(relay);
+    relayExternal = false;
+  }
+
+  function shutdown(code = 0) {
+    if (!shuttingDown) {
+      shuttingDown = (async () => {
+        timers.clearInterval(tick);
+        if (starting) await starting.catch(() => {});
+        await stopChildren();
+        exit(code);
+      })();
+    }
+    return shuttingDown;
+  }
+
+  async function handle(message) {
+    lastHeard = now();
+    if (!message || typeof message !== 'object' || shuttingDown) return;
+    const { id } = message;
+    switch (message.type) {
+      case 'ping':
+        send({ type: 'pong', id, version: VERSION });
+        return;
+      case 'status':
+        send(status(id));
+        return;
+      case 'start':
+        await ensureStarted();
+        send(status(id));
+        return;
+      case 'reset': {
+        const ok = alive(companion) && Boolean(companion.stdin) && companion.stdin.writable;
+        if (ok) companion.stdin.write('/reset\n');
+        send({ type: 'reset', id, ok });
+        return;
+      }
+      case 'stop':
+        await stopChildren();
+        send({ type: 'stopped', id });
+        await shutdown(0);
+        return;
+      default:
+        send({ type: 'error', id, error: `unknown message type ${JSON.stringify(message.type)}` });
+    }
+  }
+
+  // The idle exit and the relay keepalive.
+  const tick = timers.setInterval(() => {
+    if (shuttingDown) return;
+    if (now() - lastHeard >= idleMs) {
+      shutdown(0);
+      return;
+    }
+    if (alive(relay)) {
+      fetchImpl(`${base}/helper/keepalive`, { method: 'POST', headers: { 'x-lc-companion': '1' } }).catch(() => {});
+    }
+  }, Math.min(keepaliveMs, idleMs));
+
+  const decoder = createDecoder({
+    onMessage: (message) => {
+      handle(message).catch((err) => send({ type: 'error', id: message && message.id, error: err.message }));
+    },
+    // The stream is out of step; nothing more from it can be trusted.
+    onError: () => shutdown(1),
+  });
+  input.on('data', (chunk) => decoder.push(chunk));
+  input.on('end', () => shutdown(0));
+  input.on('error', () => shutdown(0));
+
+  return { handle, shutdown, status, get children() { return { relay, companion }; } };
+}
+
+// The real program: stdin and stdout are the browser's.
+export function main() {
+  const root = resolveRoot();
+  const logDir = process.env.LEETCODE_CAPTURE_HELPER_LOG_DIR || HERE;
+  let logFd = 'ignore';
+  try {
+    const logPath = path.join(logDir, 'helper.log');
+    // Keep one run's worth, so the log never grows without bound.
+    if (fs.existsSync(logPath) && fs.statSync(logPath).size > 1024 * 1024) fs.truncateSync(logPath, 0);
+    logFd = fs.openSync(logPath, 'a');
+  } catch {
+    // No log then; the children's output is dropped.
+  }
+  const childEnv = { ...process.env, ...dataEnv(root, HERE) };
+  for (const file of [childEnv.CAPTURE_LOG_PATH, childEnv.LEETCODE_COMPANION_STATE_FILE]) {
+    try {
+      if (file) fs.mkdirSync(path.dirname(file), { recursive: true });
+    } catch {
+      // the relay reports a log it cannot write
+    }
+  }
+  const host = createHost({
+    input: process.stdin,
+    output: process.stdout,
+    root,
+    env: childEnv,
+    logFd,
+    rootError: checkRoot(root),
+  });
+  for (const sig of ['SIGTERM', 'SIGHUP', 'SIGINT']) process.on(sig, () => host.shutdown(0));
+  return host;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main();