@hncode/hncode 0.4.2 → 0.5.1

package/src/index.js

@@ -34,6 +34,8 @@ Options:
                                 json prints one result object; stream-json streams events then a result.
                                 Exit code reflects the outcome: 0 ok, 1 failure, 2 config, 3 no answer, 4 interrupted.
   --control                     Expose a local control socket (prompt/status/interrupt) while the TUI runs.
+  --timeout <seconds>           Prompt mode: abort the run after this many seconds (default: no limit).
+  --retries <n>                 Prompt mode: HTTP retries per request before failing (default: 3).
   --control <path>              Same, at an explicit socket path.
   --web                         Serve this session to a browser on 127.0.0.1 (random port).
   --web [ip][:port]             Same, on a chosen address/port (e.g. --web 0.0.0.0:8080).
@@ -45,7 +47,7 @@ Options:
 Commands:
   session list                  List sessions, most recent first.
   provider list                 Show configured providers.
-  doctor config [path]          Validate a config.toml (default: merged config).
+  doctor [config] [path]        Environment self-check (default), or validate a config.toml.
   init                          Create ~/.hncode/config.toml with defaults.
   export [id]                   Export a session to ~/.hncode/export/<id>.json.
   control status                Ask a running session (started with --control) for its status.
@@ -70,7 +72,7 @@ export function parseArgs(argv) {
       else { key = a.slice(2); val = null; }
       if (key === 'resume') key = 'session'; // `--resume <id>` is an alias for `--session <id>`
       if (['session', 'control', 'web'].includes(key) && val === null) { const nx = argv[i + 1]; out[key] = nx !== undefined && !nx.startsWith('-') ? (i++, nx) : true; }
-else if (key === 'model' || key === 'prompt' || key === 'output-format' || key === 'add-dir') {
+else if (key === 'model' || key === 'prompt' || key === 'output-format' || key === 'add-dir' || key === 'timeout' || key === 'retries') {
         if (val === null) {
           const nx = argv[i + 1];
           // Only consume the next token if it is a real value, not another flag
@@ -151,6 +153,75 @@ async function cmdDoctorConfig(p) {
   }
 }
 
+// `hncode doctor` — environment self-check. Answers "will hncode actually work in
+// THIS terminal?" for the things that silently break it: too-old Node, a non-TTY
+// or odd terminal, Windows consoles that do not forward mouse sequences, a missing
+// git, an unreadable config. Every line is OK / WARN / FAIL so one paste answers a
+// support question.
+async function cmdDoctorEnv() {
+  const rows = [];
+  const add = (level, label, detail) => rows.push({ level, label, detail });
+
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 22) add('OK', 'node', process.version);
+  else if (major >= 20) add('WARN', 'node', process.version + ' — 20/21 work, but 22+ has TTY fixes');
+  else add('FAIL', 'node', process.version + ' — hncode needs Node >= 20');
+
+  add('OK', 'platform', process.platform + ' ' + os.release());
+  const isWin = process.platform === 'win32';
+  const term = process.env.TERM || '';
+  const wt = process.env.WT_SESSION ? 'windows-terminal' : (process.env.TERM_PROGRAM || (isWin ? 'conhost/other' : 'unknown'));
+  add(process.stdout.isTTY ? 'OK' : 'WARN', 'stdout isatty', process.stdout.isTTY ? 'yes' : 'no — colors/mouse assume a real terminal');
+  add('OK', 'terminal', wt + (term ? ' (TERM=' + term + ')' : ''));
+  if (isWin && !process.env.WT_SESSION) {
+    add('WARN', 'mouse', 'not inside Windows Terminal (WT_SESSION unset); some consoles do not forward mouse input');
+  }
+  add('OK', 'truecolor', (process.env.COLORTERM === 'truecolor' || /256color|truecolor/.test(term)) ? 'yes' : 'no — 256-color fallback in use');
+
+  try {
+    const { spawnSync } = await import('node:child_process');
+    const r = spawnSync('git', ['--version'], { encoding: 'utf8' });
+    add(r.status === 0 ? 'OK' : 'WARN', 'git', r.status === 0 ? String(r.stdout).trim() : 'not found — git tools limited');
+  } catch { add('WARN', 'git', 'not found on PATH'); }
+
+  const cfgFile = process.env.HNCODE_CONFIG || path.join(os.homedir(), '.hncode', 'config.toml');
+  if (!fs.existsSync(cfgFile)) {
+    add('WARN', 'config', 'no file at ' + cfgFile + ' (run hncode init)');
+  } else {
+    try {
+      const { parse } = await import('./toml.js');
+      parse(fs.readFileSync(cfgFile, 'utf8'));
+      add('OK', 'config', cfgFile);
+    } catch (e) {
+      add('FAIL', 'config', cfgFile + ': ' + e.message);
+    }
+  }
+
+  try {
+    const cfg = resolveConfig();
+    const model = cfg.innerModel || cfg.model;
+    add(model ? 'OK' : 'WARN', 'model', model || 'none configured (run /model or set default_model)');
+    add(cfg.apiKey ? 'OK' : 'WARN', 'api key', cfg.apiKey ? 'set' : 'missing — requests will 401');
+  } catch (e) {
+    add('WARN', 'config resolve', e.message);
+  }
+
+  try {
+    const dir = path.join(os.homedir(), '.hncode', 'plugins');
+    const n = fs.existsSync(dir) ? fs.readdirSync(dir).filter((x) => fs.statSync(path.join(dir, x)).isDirectory()).length : 0;
+    add('OK', 'plugins', n + ' installed (' + dir + ')');
+  } catch { /* ignore */ }
+
+  const order = { FAIL: 0, WARN: 1, OK: 2 };
+  rows.sort((a, b) => order[a.level] - order[b.level]);
+  console.log('hncode doctor — environment check\n');
+  for (const r of rows) console.log('  [' + r.level.padEnd(4) + '] ' + r.label.padEnd(16) + ' ' + r.detail);
+  const fails = rows.filter((r) => r.level === 'FAIL').length;
+  console.log('\n' + (fails ? fails + ' problem(s) found' : 'No blocking problems found.'));
+  return fails ? 1 : 0;
+}
+
+
 function cmdInit() {
   const cfg = resolveConfig();
   const target = path.join(os.homedir(), '.hncode', 'config.toml');
@@ -222,8 +293,9 @@ async function cmdControl(sub, arg) {
 }
 
 // ---- headless prompt mode ----
-async function runPrompt({ cfg, prompt, format, session, modelArg }) {
+async function runPrompt({ cfg, prompt, format, session, modelArg, timeoutSeconds, maxRetries }) {
   cfg = resolveModelArg(cfg, modelArg);
+  if (maxRetries !== undefined) cfg.maxRetries = maxRetries;
   if (!cfg.apiKey) {
     console.error('hncode: no api_key configured. Set HNCODE_API_KEY or configure a provider first. Run `hncode doctor config` to check.');
     return EXIT.CONFIG;
@@ -265,7 +337,25 @@ async function runPrompt({ cfg, prompt, format, session, modelArg }) {
     },
   });
   saved.messages = messages;
-  await agent.run();
+  // `--timeout <seconds>`: hard wall-clock cap on the whole run, so an unattended
+  // scripted prompt cannot hang forever on a stuck model or a wedged tool. The
+  // timer calls the SAME interrupt() the TUI's Esc uses — it aborts the in-flight
+  // request and kills the tool's AbortSignal — rather than process.exit, so the
+  // session is still saved and any final output is emitted.
+  let timedOut = false;
+  let timer = null;
+  if (timeoutSeconds > 0) {
+    timer = setTimeout(() => {
+      timedOut = true;
+      try { agent.interrupt(); } catch { /* best-effort */ }
+    }, timeoutSeconds * 1000);
+    if (timer.unref) timer.unref();
+  }
+  try {
+    await agent.run();
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
   sess.saveSession(saved);
 
   const reply = finalReply(messages, tracker.text);
@@ -278,6 +368,7 @@ async function runPrompt({ cfg, prompt, format, session, modelArg }) {
     durationMs: Date.now() - startedAt,
     model: cfg.model,
     sessionId: saved.id,
+    timedOut,
   });
 
   if (format === 'json') {
@@ -369,7 +460,7 @@ export async function main(argv) {
   // subcommands
   const [cmd, sub] = args.positional;
   if (cmd) {
-    if (cmd === 'doctor' && !sub) { printHelp(); return 0; }
+    if (cmd === 'doctor' && !sub) { return await cmdDoctorEnv(); }
     const handler = SUBCOMMANDS[cmd];
     if (handler) {
       if (sub !== undefined) {
@@ -387,11 +478,20 @@ export async function main(argv) {
   const baseCfg = resolveConfig();
   const cfg = resolveModelArg(baseCfg, args.model);
 
-  // Load plugins (if enabled) before anything else so their tools and commands
-  // are available in both headless and TUI modes.
-  if (cfg.pluginDir) {
-    const { loadPlugins } = await import('./plugin.js');
-    await loadPlugins(cfg.pluginDir);
+  // Plugins are normally loaded by bootstrap (bin/hncode) BEFORE this module is
+  // imported, because symbol patching has to register targets before the patched
+  // modules load. Only load them here when bootstrap did NOT already do it (e.g.
+  // index.js imported directly, or a test), so tools/commands still appear in
+  // both modes without a second load tripping "tool already registered".
+  try {
+    const { pluginsAlreadyLoaded } = await import('./bootstrap.js');
+    if (cfg.pluginDir && !pluginsAlreadyLoaded() && !globalThis.__hncodePluginsLoaded) {
+      const { loadPlugins } = await import('./plugin.js');
+      await loadPlugins(cfg.pluginDir);
+      globalThis.__hncodePluginsLoaded = true;
+    }
+  } catch (e) {
+    console.error('[hncode] plugin load step failed, continuing without plugins:', e && e.message);
   }
 
   // Connect configured MCP servers and register their tools.
@@ -437,7 +537,19 @@ export async function main(argv) {
     let session = null;
     if (args.session) session = typeof args.session === 'string' ? sess.loadSession(args.session) : sess.latestSession(undefined, undefined, { skipEmpty: true });
     else if (args.continue) session = sess.latestSession(undefined, undefined, { skipEmpty: true });
-    return runPrompt({ cfg, prompt: args.prompt, format, session, modelArg: args.model });
+    // --timeout / --retries are validated here so a typo fails loudly instead of
+    // being parsed as NaN and silently ignored.
+    const timeoutSeconds = args.timeout !== undefined ? Number.parseInt(String(args.timeout), 10) : 0;
+    if (args.timeout !== undefined && (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1)) {
+      console.error(`hncode: --timeout needs a positive integer (seconds), got "${args.timeout}".`);
+      return EXIT.CONFIG;
+    }
+    const maxRetries = args.retries !== undefined ? Number.parseInt(String(args.retries), 10) : undefined;
+    if (args.retries !== undefined && (!Number.isInteger(maxRetries) || maxRetries < 0)) {
+      console.error(`hncode: --retries needs a non-negative integer, got "${args.retries}".`);
+      return EXIT.CONFIG;
+    }
+    return runPrompt({ cfg, prompt: args.prompt, format, session, modelArg: args.model, timeoutSeconds, maxRetries });
   }
 
   if (!process.stdout.isTTY) {

package/src/keybindings.js

@@ -0,0 +1,229 @@
+// User keybindings — remap a key to another key, or to a slash command.
+//
+// WHY AN ALIAS TABLE AND NOT A PLUGIN-STYLE HANDLER LIST
+// -----------------------------------------------------
+// The TUI dispatches keys in one large switch whose cases are also the ONLY place the
+// key's meaning is defined. Rewriting that switch into a registry would be a much larger
+// change than the feature is worth, and it would put a layer between every keystroke and
+// the handler — on the one path where latency is visible.
+//
+// So a binding is an ALIAS: it names a target the switcher already understands.
+//
+//   key       -> the key to send instead      ("ctrl-j" = "enter")
+//   command   -> the slash command to run     ("ctrl-e" = "/theme")
+//
+// One key, one target, applied before dispatch. That covers what people actually rebind
+// for — a key their terminal eats, a chord they prefer, a command they run constantly —
+// with no change to the dispatch path and no way for a binding to leave the UI in a
+// state the switcher does not know how to handle. A key with no binding passes through
+// untouched, which is what keeps the default experience identical.
+//
+// WHY THE FILE IS THE SOURCE OF TRUTH
+// -----------------------------------
+// Bindings live in ~/.hncode/keybindings.json, read per keypress rather than cached: it is
+// a small file, the read costs microseconds, and it means an edit takes effect immediately
+// instead of after a restart. A malformed file is reported ONCE and then ignored — a typo
+// must not silently swallow every key the user presses.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Where user bindings live. `HNCODE_HOME` moves it, like the rest of the config. */
+export function keybindingsFile(home) {
+  const base = home || process.env.HNCODE_HOME || path.join(os.homedir(), '.hncode');
+  return path.join(base, 'keybindings.json');
+}
+
+// Names people will reasonably write, mapped to the tokens the tokenizer emits. Without
+// this, `ctrl+o` (how every other tool spells it) would not match `c-o`, and the binding
+// would silently do nothing — the worst outcome for a config feature.
+const KEY_ALIASES = {
+  return: 'enter', cr: 'enter',
+  esc: 'escape',
+  del: 'delete',
+  pageup: 'pgup', pagedown: 'pgdn',
+  space: ' ',
+};
+
+// Modifier names, recognised on their own so they can be joined with a base key.
+const MODIFIERS = {
+  ctrl: 'c', control: 'c', ctl: 'c',
+  shift: 's',
+  alt: 'm', meta: 'm', option: 'm', opt: 'm', cmd: 'm', command: 'm', super: 'm', win: 'm',
+};
+
+/**
+ * Normalise a key spelling to this TUI's token vocabulary.
+ * `ctrl+o` -> `c-o`, `Return` -> `enter`, `C-T` -> `c-t`.
+ *
+ * A spec that names only modifiers, or ends on the separator (`ctrl+`), is malformed and
+ * returns '' — the caller treats that as an error. Returning a made-up token instead would
+ * create a binding the tokenizer can never emit, which is a key that silently does nothing.
+ */
+export function normalizeKey(spec) {
+  const s = String(spec == null ? '' : spec).trim().toLowerCase();
+  if (!s) return '';
+  // A leading/trailing `+`, or a trailing `-`, means a half-written chord. `ctrl+` would
+  // otherwise split into one part and be returned verbatim as the literal string "ctrl+".
+  if (/[+\s]$/.test(s) && !/^-+$/.test(s)) return '';
+  if (/^[+\s]/.test(s)) return '';
+  // `ctrl-o` is the other common spelling of a chord: split it on `-` when the first
+  // segment is a modifier name, so it is not returned whole as an unknown key.
+  let parts = s.split(/[+\s]+/).filter(Boolean);
+  if (parts.length === 1 && parts[0].includes('-')) {
+    const seg = parts[0].split('-').filter(Boolean);
+    if (seg.length > 1 && seg.slice(0, -1).every((p) => MODIFIERS[p])) parts = seg;
+  }
+  if (!parts.length) return '';
+  if (parts.length === 1) {
+    // A bare modifier name is not a key: nothing emits `ctrl` on its own.
+    if (MODIFIERS[parts[0]]) return '';
+    return KEY_ALIASES[parts[0]] || parts[0];
+  }
+  const mods = [];
+  let base = '';
+  for (const p of parts) {
+    const m = MODIFIERS[p];
+    if (m) { if (!mods.includes(m)) mods.push(m); continue; }
+    // A second non-modifier means the spec is not a chord at all (`ctrl+a+b`); the last one
+    // wins, matching how the single-part path treats an unknown name.
+    base = KEY_ALIASES[p] || p;
+  }
+  if (!base) return '';                 // `ctrl+shift` names no key
+  if (!mods.length) return base;
+  // Ctrl is emitted as `c-<letter>`; a modified non-letter (ctrl+up) is `c-up`; and a
+  // shift-modified control is the `c-s-<x>` form the CSI-u path produces.
+  if (mods.length === 1 && mods[0] === 'c') return `c-${base}`;
+  // Shift alone is emitted as `shift-<base>` for the named keys the tokenizer handles
+  // specially (shift-tab, shift-up, shift-home, …).
+  if (mods.length === 1 && mods[0] === 's') return `shift-${base}`;
+  if (mods.includes('c') && mods.includes('s')) return `c-s-${base}`;
+  // Any other combination resolves to the base key rather than to a token nothing emits,
+  // so `alt+x` still does something sensible instead of becoming a dead key.
+  return base;
+}
+
+const isCommand = (s) => typeof s === 'string' && s.trim().startsWith('/');
+
+/**
+ * Read and validate the bindings file.
+
+/**
+ * Read and validate the bindings file.
+ *
+ * @returns {{bindings: Map<string, {key?:string, command?:string}>, errors: string[], file: string}}
+ *   `bindings` maps a NORMALISED source key to exactly one target.
+ */
+export function loadKeybindings(home) {
+  const file = keybindingsFile(home);
+  const out = { bindings: new Map(), errors: [], file };
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); }
+  catch (e) {
+    // Absent is the normal case and deserves no complaint. Anything else is worth saying.
+    if (e && e.code !== 'ENOENT') out.errors.push(`could not read ${file}: ${e.message}`);
+    return out;
+  }
+  let doc;
+  try { doc = JSON.parse(raw); }
+  catch (e) { out.errors.push(`${file} is not valid JSON: ${e.message}`); return out; }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    out.errors.push(`${file} must contain a JSON object of "key": "target" pairs`);
+    return out;
+  }
+  // Accept both a flat map and a `{ bindings: { … } }` wrapper, because both spellings are
+  // natural and refusing one would be a pointless papercut.
+  const table = (doc.bindings && typeof doc.bindings === 'object' && !Array.isArray(doc.bindings))
+    ? doc.bindings : doc;
+  for (const [from, to] of Object.entries(table)) {
+    if (from === 'bindings') continue;
+    const src = normalizeKey(from);
+    if (!src) { out.errors.push(`"${from}": not a usable key name`); continue; }
+    let target;
+    if (typeof to === 'string' && isCommand(to)) {
+      target = { command: to.trim() };
+    } else if (typeof to === 'string') {
+      const dst = normalizeKey(to);
+      if (!dst) { out.errors.push(`"${from}": "${to}" is not a usable key name or a /command`); continue; }
+      if (dst === src) { out.errors.push(`"${from}": a key cannot be bound to itself`); continue; }
+      target = { key: dst };
+    } else if (to && typeof to === 'object' && typeof to.command === 'string' && isCommand(to.command)) {
+      target = { command: to.command.trim() };
+    } else if (to && typeof to === 'object' && typeof to.key === 'string') {
+      const dst = normalizeKey(to.key);
+      if (!dst || dst === src) { out.errors.push(`"${from}": bad target key`); continue; }
+      target = { key: dst };
+    } else {
+      out.errors.push(`"${from}": the target must be a key name (e.g. "enter") or a command (e.g. "/theme")`);
+      continue;
+    }
+    out.bindings.set(src, target);
+  }
+  return out;
+}
+
+/**
+ * Resolve one incoming key through the bindings.
+ *
+ * A command binding is CAPPED: resolving a command binding that points at another command
+ * binding, or a chain of key aliases, must not loop. One hop for a command, and a bounded
+ * walk for keys, is enough to be useful and impossible to hang on.
+ *
+ * @returns {{key: string, command: string|null}} the key to dispatch, plus a command to run.
+ */
+export function resolveKey(key, bindings, maxHops = 8) {
+  const k = String(key == null ? '' : key);
+  if (!bindings || typeof bindings.get !== 'function') return { key: k, command: null };
+  let cur = k;
+  let command = null;
+  for (let hop = 0; hop < maxHops; hop++) {
+    const hit = bindings.get(cur);
+    if (!hit) break;
+    if (hit.command) {
+      // The command replaces the key entirely: running it and ALSO dispatching the
+      // original key would fire two unrelated actions from one press.
+      if (command) break;      // already found one; do not chain commands
+      command = hit.command;
+      break;
+    }
+    if (!hit.key || hit.key === cur) break;
+    cur = hit.key;
+  }
+  return { key: cur, command };
+}
+
+/** A JSON body for the bindings file, used by `/keybindings add` on first write. */
+export function readOrEmpty(home) {
+  const file = keybindingsFile(home);
+  try { return { file, doc: JSON.parse(fs.readFileSync(file, 'utf8')) || {} }; }
+  catch { return { file, doc: {} }; }
+}
+
+/** Write the bindings file, creating the directory if needed. */
+export function writeKeybindings(home, doc) {
+  const file = keybindingsFile(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+  return file;
+}
+
+/**
+ * A human-readable table of the settings, for `/keybindings`.
+ * Sorted so the output is stable across runs.
+ */
+export function describeKeybindings(loaded) {
+  const out = [];
+  if (!loaded.bindings.size) {
+    out.push('No keybindings set.', '', `File: ${loaded.file}`, 'Add one with /keybindings add <key> <key|/command>');
+  } else {
+    out.push(`Keybindings (${loaded.bindings.size}) — ${loaded.file}`, '');
+    for (const [from, to] of [...loaded.bindings.entries()].sort()) {
+      out.push(`  ${from.padEnd(12)} -> ${to.command ? to.command : to.key}`);
+    }
+  }
+  if (loaded.errors.length) {
+    out.push('', 'Problems:', ...loaded.errors.map((e) => `  ! ${e}`));
+  }
+  return out;
+}