@hncode/hncode 0.4.1 → 0.5.0

package/src/prompt-presets.js

@@ -61,7 +61,7 @@ const RULES = {
     ],
     // Only for models with no dedicated reasoning channel.
     tagFallback: [
-      'Put all internal reasoning inside <think>...</think> and close the block before your answer. Reasoning must never appear outside it.',
+      'Put all internal reasoning inside <|thinking|>...<|/thinking|> and close the block before your answer. Reasoning must never appear outside it.',
     ],
   },
   scope: [

package/src/registry-browser.js

@@ -0,0 +1,317 @@
+// RegistryBrowser — the full-screen /skills and /plugins manager.
+//
+// Modelled on kimi-code's PluginsPanelComponent (a tabbed list where every row has a
+// DESCRIPTION under its label) and on this project's own /tasks browser: pure
+// rendering plus key handling, returning ACTION STRINGS to the caller so all state
+// stays in one place.
+//
+//   ────────────────────────────────────────────────────────────────
+//    Skills
+//    Tab switch · ↑↓ select · Enter install/remove · Esc close
+//
+//    [Installed (1)]  Available (3)
+//
+//    ❯ demo                          installed
+//        A demo skill
+//      review-pr                     install
+//        Review a pull request for bugs
+//    ────────────────────────────────────────────────────────────────
+//
+// The description line is the reason this exists instead of the plain list panel: a
+// skill or plugin is meaningless without knowing what it does, and the picker's inline
+// `sub` truncates on a narrow terminal.
+//
+// Tabs differ per kind, because the two halves mean different things:
+//   TABS_LOCAL  = what is on disk here (installed skills / plugins on disk)
+//   TABS_REMOTE = what the repo offers, with an `installed` badge when present
+
+import { C } from './colors.js';
+import { visualWidth } from './term.js';
+
+const ELLIPSIS = '\u2026';
+const ESC = '\x1b';
+const MIN_WIDTH = 44;
+const MIN_HEIGHT = 8;
+
+function visWidth(s) { return visualWidth(String(s).replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')); }
+
+function truncateToWidth(s, width) {
+  const str = String(s);
+  let out = '';
+  let n = 0;
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] === ESC) {
+      const m = /^\x1b\[[0-9;?]*[a-zA-Z]/.exec(str.slice(i));
+      if (m) { out += m[0]; i += m[0].length; continue; }
+    }
+    const cp = str.codePointAt(i);
+    const ch = String.fromCodePoint(cp);
+    const cw = visWidth(ch);
+    if (n + cw > width - 1) return out + ELLIPSIS + ' '.repeat(Math.max(0, width - n - 1));
+    n += cw;
+    out += ch;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return out;
+}
+
+function fitExactly(line, width) {
+  const w = visWidth(line);
+  if (w === width) return line;
+  if (w > width) return truncateToWidth(line, width);
+  return line + ' '.repeat(width - w);
+}
+
+/** Plain-text wrap so a long description keeps its own indented lines. */
+function wrapText(text, width) {
+  const words = String(text || '').trim().split(/\s+/).filter(Boolean);
+  const out = [];
+  let cur = '';
+  for (const w of words) {
+    const next = cur ? cur + ' ' + w : w;
+    if (visWidth(next) <= width) { cur = next; continue; }
+    if (cur) out.push(cur);
+    cur = visWidth(w) <= width ? w : w.slice(0, Math.max(1, width));
+  }
+  if (cur) out.push(cur);
+  return out.length ? out : [''];
+}
+
+// Tabs. `id` is what the key handler switches on; `label` is shown with the count.
+export const SKILL_TABS = [
+  { id: 'installed', label: 'Installed' },
+  { id: 'available', label: 'Available' },
+];
+export const PLUGIN_TABS = [
+  { id: 'loaded', label: 'Loaded' },
+  { id: 'ondisk', label: 'On disk' },
+  { id: 'available', label: 'Available' },
+];
+
+/** The rows for one tab. Each row: { label, description, status, statusTone, name, action }. */
+export function rowsForTab(state, tabId) {
+  const d = state.data || {};
+  if (state.kind === 'skills') {
+    if (tabId === 'installed') {
+      return (d.installed || []).map((s) => ({
+        name: s.name,
+        label: s.name,
+        description: s.description || '(no description)',
+        status: 'installed',
+        statusTone: 'dim',
+        action: 'remove-skill',
+      }));
+    }
+    const local = new Set((d.installed || []).map((s) => s.name));
+    return (d.remote || []).map((r) => ({
+      name: r.name,
+      label: r.name,
+      description: r.description || (r.readable === false ? '(no SKILL.md — cannot install)' : '(no description)'),
+      status: local.has(r.name) ? 'Installed' : 'Not Install',
+      statusTone: local.has(r.name) ? 'ok' : 'warn',
+      action: local.has(r.name) ? 'reinstall-skill' : 'install-skill',
+      disabled: r.readable === false,
+    }));
+  }
+  // plugins
+  if (tabId === 'loaded') {
+    return (d.loaded || []).map((p) => ({
+      name: p.name,
+      label: p.name,
+      description: `v${p.version || '0.0.0'} · ${p.id}`,
+      status: 'loaded',
+      statusTone: 'ok',
+      action: 'none',
+    }));
+  }
+  if (tabId === 'ondisk') {
+    const loadedNames = new Set((d.loaded || []).map((p) => p.name));
+    return (d.onDisk || []).map((p) => ({
+      name: p.name,
+      label: p.name + (p.kind === 'dir' ? '/' : ''),
+      description: loadedNames.has(p.name)
+        ? 'loaded in this session'
+        : 'not loaded — Need Restart',
+      status: loadedNames.has(p.name) ? 'loaded' : 'Need Restart',
+      statusTone: loadedNames.has(p.name) ? 'ok' : 'warn',
+      action: 'remove-plugin',
+    }));
+  }
+  const local = new Set((d.onDisk || []).map((p) => p.name));
+  return (d.remote || []).map((r) => ({
+    name: r.name,
+    label: r.name,
+    description: local.has(r.name) ? 'already installed locally' : 'available in the repository',
+    status: local.has(r.name) ? 'Installed' : 'Not Install',
+    statusTone: local.has(r.name) ? 'ok' : 'warn',
+    action: local.has(r.name) ? 'reinstall-plugin' : 'install-plugin',
+  }));
+}
+
+function statusColor(tone) {
+  if (tone === 'ok') return C.green;
+  if (tone === 'warn') return C.orange;
+  if (tone === 'dim') return C.gray;
+  return C.blue;
+}
+
+export function renderRegistryBrowser(state, cols, rows) {
+  if (cols < MIN_WIDTH || rows < MIN_HEIGHT) {
+    const lines = [fitExactly(C.red + 'Terminal too small (need >= ' + MIN_WIDTH + ' x ' + MIN_HEIGHT + ')' + C.reset, cols)];
+    for (let i = 1; i < rows; i++) lines.push(' '.repeat(cols));
+    return lines;
+  }
+  const title = state.kind === 'skills' ? ' Skills' : ' Plugins';
+  const tabs = state.kind === 'skills' ? SKILL_TABS : PLUGIN_TABS;
+  const tabIdx = Math.max(0, tabs.findIndex((t) => t.id === state.tab));
+  const tab = tabs[tabIdx] || tabs[0];
+  const all = rowsForTab(state, tab.id);
+  const sel = Math.max(0, Math.min(all.length - 1, state.selectedIndex || 0));
+
+  const out = [];
+  const rule = C.border + '\u2500'.repeat(cols) + C.reset;
+  // Mouse targets for this frame. The browser is pure render + key, so it records
+  // its own hitboxes here and the caller (tui.js) maps mouse events onto them —
+  // exactly like the tasks browser does with `_taskHits`. Row is a FRAME row
+  // (0 = the top rule); the caller converts the 1-based screen row.
+  const hits = [];
+  state._regHits = hits;
+  out.push(rule);
+  out.push(fitExactly(C.cyan + C.bold + title + C.reset, cols));
+  // The key hints stay visible while the fetch runs: the panel is usable during it
+  // (the local tabs are already loaded), so replacing the hints with a status message
+  // would hide the keys exactly when the user is most likely to press them.
+  const hint = ' Tab switch \u00b7 \u2191\u2193 select \u00b7 Enter install/remove \u00b7 Esc close';
+  out.push(fitExactly(C.gray + hint + (state.busy ? C.gray + `  ${state.busy}` : '') + C.reset, cols));
+  out.push('');
+
+  // Tab strip, with the count of each tab's rows.
+  {
+    const stripRow = out.length;
+    let col = 0;
+    const segs = tabs.map((t) => {
+      const n = rowsForTab(state, t.id).length;
+      const text = t.id === tab.id ? `[${t.label} (${n})]` : ` ${t.label} (${n}) `;
+      const col0 = col;
+      col += visWidth(text) + 1;   // +1 for the joining space
+      return { id: t.id, text, col0, col1: col0 + visWidth(text) - 1 };
+    });
+    out.push(segs.map((s) => (s.id === tab.id
+      ? C.cyan + C.bold + s.text + C.reset
+      : C.gray + s.text + C.reset)).join(' '));
+    for (const s of segs) hits.push({ row: stripRow, col0: s.col0, col1: s.col1, kind: 'regTab', tab: s.id });
+  }
+  out.push('');
+
+  // Body: each row is a label line plus its wrapped description, so the footer must be
+  // sized against the ROWS, not the lines. A row is 2+ lines tall.
+  const listTop = out.length;
+  const bodyRows = Math.max(1, rows - listTop - 3);      // leave room for the footer
+  if (!all.length) {
+    // The message must describe THIS tab. A failed remote fetch used to win over
+    // everything, so "Loaded" and "On disk" — which are read straight off the local
+    // filesystem and cannot fail from the network — reported "fetch failed" whenever
+    // the repo lookup did. That reads as "your local plugins are broken", which is
+    // both wrong and alarming. Only the Available tab can talk about the fetch.
+    const isRemoteTab = tab.id === 'available';
+    // "Loading" only applies to the tab that is actually waiting on the fetch; a local
+    // tab is empty because there is genuinely nothing there, and saying "Loading" for
+    // data that is already on screen reads as a stall.
+    const msg = (isRemoteTab && state.busy) ? '  Loading\u2026'
+      : (isRemoteTab && state.data && state.data.remoteError)
+        ? '  Could not fetch from the repo: ' + state.data.remoteError
+        : isRemoteTab ? '  Nothing published in the repo yet.'
+          : '  Nothing here.';
+    out.push(C.gray + msg + C.reset);
+  }
+  for (let i = 0; i < all.length; i++) {
+    const r = all[i];
+    const isSel = i === sel;
+    const ptr = isSel ? C.cyan + '\u276f ' + C.reset : '  ';
+    const nameStyle = isSel ? (C.cyan + C.bold) : C.white;
+    const badge = r.status ? '  ' + statusColor(r.statusTone) + r.status + C.reset : '';
+    const dis = r.disabled ? C.gray : '';
+    const labelRow = out.length;   // the clickable row for this item
+    out.push(fitExactly(ptr + nameStyle + dis + r.label + C.reset + badge, cols));
+    // The whole label row is a click target: clicking selects the item (and a
+    // second click / the footer activates it), mirroring the tasks browser.
+    hits.push({ row: labelRow, col0: 0, col1: cols - 1, kind: 'regRow', index: i });
+    for (const line of wrapText(r.description, Math.max(8, cols - 6))) {
+      out.push(C.gray + '    ' + line + C.reset);
+    }
+  }
+  // A fetch failure has to show even when the LOCAL half has rows, or the Available
+  // tab silently looks empty and the user cannot tell why.
+  if (all.length && state.data && state.data.remoteError && tab.id === 'available') {
+    out.push('');
+    out.push(C.orange + '  Could not fetch the list: ' + state.data.remoteError + C.reset);
+  }
+  // The last action's outcome (installed / removed / failed) sits above the hint line.
+  if (state.flash) {
+    out.push('');
+    out.push(C.cyan + '  ' + state.flash + C.reset);
+  }
+
+  // Footer: what the highlighted row would DO, so the effect of Enter is never a
+  // surprise. A row already installed says "reinstall", because that is what Enter
+  // does there (and it is the only way to pick up a newer version).
+  const cur = all[sel];
+  const action = !cur ? ''
+    : cur.disabled ? 'Enter does nothing \u2014 this entry has no SKILL.md'
+      : cur.action === 'reinstall-skill' || cur.action === 'reinstall-plugin'
+        ? 'Enter reinstalls ' + cur.name + ' (replaces the local copy)'
+        : cur.action === 'install-skill' || cur.action === 'install-plugin'
+          ? 'Enter installs ' + cur.name + ' from the repository'
+          : cur.action.startsWith('remove') ? 'Enter removes the local copy of ' + cur.name
+            : 'loaded plugin \u2014 switch to the On disk tab to remove it';
+  while (out.length < rows - 2) out.push('');
+  out.push(fitExactly(C.gray + ' ' + action + C.reset, cols));
+  out.push(rule);
+  return out.slice(0, rows);
+}
+
+/**
+ * One key. Returns an action string for the caller:
+ * 'close' | 'switchTab' | 'select' | 'install' | 'remove' | 'reload' | null
+ */
+export function handleRegistryBrowserKey(state, t) {
+  const tabs = state.kind === 'skills' ? SKILL_TABS : PLUGIN_TABS;
+  const all = rowsForTab(state, state.tab);
+  const ch = t.ch;
+
+  if (t.key === 'escape' || ch === 'q' || ch === 'Q') return 'close';
+  if (t.key === 'tab') {
+    const i = Math.max(0, tabs.findIndex((x) => x.id === state.tab));
+    state.tab = tabs[(i + 1) % tabs.length].id;
+    state.selectedIndex = 0;
+    return 'switchTab';
+  }
+  if (t.key === 'up' || ch === 'k') {
+    state.selectedIndex = Math.max(0, (state.selectedIndex || 0) - 1);
+    return 'select';
+  }
+  if (t.key === 'down' || ch === 'j') {
+    state.selectedIndex = Math.min(Math.max(0, all.length - 1), (state.selectedIndex || 0) + 1);
+    return 'select';
+  }
+  if (t.key === 'home') { state.selectedIndex = 0; return 'select'; }
+  if (t.key === 'end') { state.selectedIndex = Math.max(0, all.length - 1); return 'select'; }
+  if (ch === 'r' || ch === 'R') return 'reload';
+  if (t.key === 'enter' || t.key === 'space' || ch === ' ') {
+    const row = all[state.selectedIndex || 0];
+    if (!row || row.disabled) return null;
+    // `installed` on the Available tab still reinstalls: that is how you pick up a
+    // newer version of something you already have, and refusing it would leave no way
+    // to update.
+    if (row.action.startsWith('install')) return 'install';
+    if (row.action.startsWith('remove')) return 'remove';
+    return null;
+  }
+  if (ch === 'd' || ch === 'D') {
+    const row = all[state.selectedIndex || 0];
+    if (row && row.action.startsWith('remove')) return 'remove';
+    return null;
+  }
+  return null;
+}

package/src/remote.js

@@ -0,0 +1,289 @@
+// Remote skills and plugins — pull them from the hncode GitHub repo.
+//
+// Both live in the repo under a folder per item:
+//
+//   skills/<name>/SKILL.md      ->  ~/.hncode/skills/<name>.md
+//   plugins/<name>/…            ->  ~/.hncode/plugins/…
+//
+// The layout differs on purpose. A SKILL is a single Markdown prompt fragment, so it
+// is FLATTENED to `<name>.md`: that is what `skills.js` already reads (and what makes
+// `/skill:<name>` work without teaching the loader about directories). A PLUGIN is an
+// ESM module that may sit beside helper files, so it is copied as a directory or, when
+// it is a single file, as that file — see installPlugin.
+//
+// Discovery uses the GitHub Contents API and downloads use raw.githubusercontent.com.
+// No git, no dependencies: a user who has never installed git can still pull a skill,
+// and fetching one item does not drag down the whole repository.
+//
+// Everything network-facing is best-effort and reports failure as a value rather than
+// throwing, so a command can print what went wrong instead of killing the TUI.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { skillsDir, normalizeSkillName } from './skills.js';
+
+// TLS verification is ON by default. If a local proxy / AV breaks the cert
+// chain, set HNCODE_DISABLE_TLS_VERIFY to skip verification for GitHub fetches.
+if (process.env.HNCODE_DISABLE_TLS_VERIFY) {
+  // Node prints an "insecure TLS" warning for this intentional opt-out. Replace the
+  // default `warning` handler with one that swallows only that message, so the rest
+  // of Node's warnings still come through.
+  process.removeAllListeners('warning');
+  process.on('warning', (warning) => {
+    if (warning && /NODE_TLS_REJECT_UNAUTHORIZED/i.test(warning.message || '')) return;
+    const pid = process.pid;
+    const name = warning && warning.name ? `${warning.name}: ` : '';
+    let line = `(node:${pid}) ${name}${warning && warning.message ? warning.message : String(warning)}`;
+    if (warning && warning.detail) line += `\n${warning.detail}`;
+    process.stderr.write(line + '\n');
+  });
+  process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+}
+
+// The canonical source. Overridable so a fork (or a test) can point elsewhere.
+export const DEFAULT_REPO = process.env.HNCODE_REPO || 'NiceHello666/hncode';
+export const DEFAULT_REF = process.env.HNCODE_REPO_REF || 'main';
+
+// Where remote plugins land. `plugin.js` loads *.js/*.mjs from this directory.
+export function pluginsDir() {
+  return process.env.HNCODE_PLUGINS || path.join(os.homedir(), '.hncode', 'plugins');
+}
+
+// Plugin files that are never worth downloading or dangerous to copy blindly.
+const PLUGIN_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.md']);
+
+const USER_AGENT = 'hncode-remote';
+
+async function ghJson(url, { timeoutMs = 15000 } = {}) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: ctl.signal,
+      headers: { accept: 'application/vnd.github+json', 'user-agent': USER_AGENT },
+    });
+    if (!res.ok) {
+      // 404 is the normal "the folder does not exist yet" case, so it gets its own
+      // wording: the repo simply has not had anything contributed to that folder.
+      if (res.status === 404) return { ok: false, error: 'not-found' };
+      if (res.status === 403) return { ok: false, error: 'rate-limited' };
+      return { ok: false, error: `HTTP ${res.status}` };
+    }
+    return { ok: true, data: await res.json() };
+  } catch (e) {
+    return { ok: false, error: e && e.name === 'AbortError' ? 'timed out' : String((e && e.message) || e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchText(url, { timeoutMs = 20000 } = {}) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctl.signal, headers: { 'user-agent': USER_AGENT } });
+    if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
+    return { ok: true, text: await res.text() };
+  } catch (e) {
+    return { ok: false, error: e && e.name === 'AbortError' ? 'timed out' : String((e && e.message) || e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function apiContents(repo, ref, dir) {
+  return `https://api.github.com/repos/${repo}/contents/${dir}${ref ? `?ref=${encodeURIComponent(ref)}` : ''}`;
+}
+
+function rawUrl(repo, ref, file) {
+  return `https://raw.githubusercontent.com/${repo}/${ref}/${file}`;
+}
+
+// Each item is a DIRECTORY in the repo (skills/<name>/, plugins/<name>/). A loose file
+// at the top level is ignored: the convention is the contract, and accepting both
+// would make the listing ambiguous about what a name refers to.
+function dirsOnly(entries) {
+  return (Array.isArray(entries) ? entries : [])
+    .filter((e) => e && e.type === 'dir' && e.name && !e.name.startsWith('.'))
+    .map((e) => ({ name: e.name, path: e.path }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** List the skills available in the repo: [{ name, path }]. */
+export async function listRemoteSkills({ repo = DEFAULT_REPO, ref = DEFAULT_REF } = {}) {
+  const r = await ghJson(apiContents(repo, ref, 'skills'));
+  if (!r.ok) return r;
+  return { ok: true, items: dirsOnly(r.data) };
+}
+
+/** List the plugins available in the repo: [{ name, path }]. */
+export async function listRemotePlugins({ repo = DEFAULT_REPO, ref = DEFAULT_REF } = {}) {
+  const r = await ghJson(apiContents(repo, ref, 'plugins'));
+  if (!r.ok) return r;
+  return { ok: true, items: dirsOnly(r.data) };
+}
+
+// A skill's description comes from its front-matter (the same field `skills.js` reads
+// for a local skill), so the local and remote listings describe a skill identically.
+function describeSkill(text) {
+  const m = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''));
+  if (!m) return '';
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^\s*(?:description|title)\s*:\s*(.*?)\s*$/.exec(line);
+    if (kv) {
+      let v = kv[1];
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+      return v;
+    }
+  }
+  return '';
+}
+
+/**
+ * Fetch the SKILL.md inside each remote skill directory, so the list can show what a
+ * skill is before the user installs it. One request per skill; failures leave the
+ * description empty rather than dropping the entry.
+ */
+export async function listRemoteSkillsDetailed({ repo = DEFAULT_REPO, ref = DEFAULT_REF } = {}) {
+  const listed = await listRemoteSkills({ repo, ref });
+  if (!listed.ok) return listed;
+  const items = await Promise.all(listed.items.map(async (it) => {
+    const file = `${it.path}/SKILL.md`;
+    const r = await fetchText(rawUrl(repo, ref, file));
+    return { ...it, file, description: r.ok ? describeSkill(r.text) : '', readable: r.ok };
+  }));
+  return { ok: true, items };
+}
+
+/**
+ * Install one remote skill as `~/.hncode/skills/<name>.md`.
+ *
+ * The repo requires the file to be named SKILL.md; a directory without one is skipped
+ * (returns ok:false) instead of creating a nameless entry. Returns
+ * { ok, name, path, replaced } or { ok: false, error }.
+ */
+export async function installRemoteSkill(name, { repo = DEFAULT_REPO, ref = DEFAULT_REF, overwrite = true } = {}) {
+  const clean = normalizeSkillName(name);
+  // A name is a path SEGMENT in the repo URL. Reject anything that could escape it or
+  // name a hidden directory, before the request is even made — `.hidden` used to slip
+  // through and only fail later as a confusing "no SKILL.md" 404.
+  if (!clean || /[\\/]/.test(clean) || clean.startsWith('.') || /[\u0000-\u001f]/.test(clean)) {
+    return { ok: false, error: `Invalid skill name: ${name}` };
+  }
+
+  const file = `skills/${clean}/SKILL.md`;
+  const r = await fetchText(rawUrl(repo, ref, file));
+  if (!r.ok) {
+    return { ok: false, error: r.error === 'HTTP 404'
+      ? `No SKILL.md at ${file} (each skill directory must contain SKILL.md).`
+      : `Could not download ${file}: ${r.error}` };
+  }
+  if (!r.text.trim()) return { ok: false, error: `${file} is empty.` };
+
+  const dir = skillsDir();
+  const dest = path.join(dir, `${clean}.md`);
+  const replaced = fs.existsSync(dest);
+  if (replaced && !overwrite) return { ok: false, error: 'exists', replaced: true, path: dest };
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(dest, r.text, 'utf8');
+  } catch (e) {
+    return { ok: false, error: `Cannot write ${dest}: ${e.message}` };
+  }
+  return { ok: true, name: clean, path: dest, replaced, description: describeSkill(r.text) };
+}
+
+/** Remove an installed skill by name (thin alias so the command reads uniformly). */
+export function removeLocalSkill(name) {
+  const clean = normalizeSkillName(name);
+  if (!clean) return false;
+  try { fs.unlinkSync(path.join(skillsDir(), `${clean}.md`)); return true; } catch { return false; }
+}
+
+// ---- plugins ---------------------------------------------------------------
+
+// Flatten a Contents API tree into { path, type, size } for one plugin directory.
+async function listDir(repo, ref, dir) {
+  const r = await ghJson(apiContents(repo, ref, dir));
+  if (!r.ok) return r;
+  return { ok: true, entries: Array.isArray(r.data) ? r.data : [] };
+}
+
+/**
+ * Install one remote plugin into `~/.hncode/plugins/`.
+ *
+ * Two shapes are accepted, because a plugin is either one file or a small package:
+ *   plugins/<name>/index.js (+ helpers)
+ *   plugins/<name>/<name>.js
+ * Sub-directories are copied recursively; only the extensions plugins can actually be
+ * loaded from are fetched, so a stray asset cannot land in the plugin directory.
+ */
+export async function installRemotePlugin(name, { repo = DEFAULT_REPO, ref = DEFAULT_REF, overwrite = true } = {}) {
+  const clean = String(name == null ? '' : name).trim();
+  if (!clean || /[\\/]/.test(clean) || clean.startsWith('.')) {
+    return { ok: false, error: `Invalid plugin name: ${name}` };
+  }
+  const srcDir = `plugins/${clean}`;
+  const listed = await listDir(repo, ref, srcDir);
+  if (!listed.ok) {
+    return { ok: false, error: listed.error === 'not-found'
+      ? `No plugins/${clean} directory in the repo.`
+      : `Could not list ${srcDir}: ${listed.error}` };
+  }
+
+  const files = listed.entries.filter((e) => e.type === 'file'
+    && PLUGIN_EXT.has(path.extname(e.name).toLowerCase()));
+  if (!files.length) return { ok: false, error: `plugins/${clean} has no .js/.mjs/.json files.` };
+
+  const destDir = path.join(pluginsDir(), clean);
+  const dest = path.join(destDir, files[0].name);
+  const existed = fs.existsSync(destDir);
+  if (existed && !overwrite) return { ok: false, error: 'exists', replaced: true, path: destDir };
+
+  const written = [];
+  for (const f of files) {
+    const r = await fetchText(rawUrl(repo, ref, f.path));
+    if (!r.ok) return { ok: false, error: `Could not download ${f.path}: ${r.error}` };
+    const out = path.join(destDir, path.basename(f.path));
+    try {
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, r.text, 'utf8');
+    } catch (e) {
+      return { ok: false, error: `Cannot write ${out}: ${e.message}` };
+    }
+    written.push(path.basename(f.path));
+  }
+  return { ok: true, name: clean, path: destDir, files: written, replaced: existed };
+}
+
+/** Remove an installed plugin directory (or a single-file plugin) by name. */
+export function removeLocalPlugin(name) {
+  const clean = String(name == null ? '' : name).trim();
+  if (!clean || /[\\/]/.test(clean)) return false;
+  const dir = path.join(pluginsDir(), clean);
+  if (fs.existsSync(dir)) { try { fs.rmSync(dir, { recursive: true, force: true }); return true; } catch { return false; } }
+  // A single-file plugin installs as <name>.js.
+  for (const ext of ['.js', '.mjs', '.cjs']) {
+    const f = path.join(pluginsDir(), clean + ext);
+    if (fs.existsSync(f)) { try { fs.unlinkSync(f); return true; } catch { return false; } }
+  }
+  return false;
+}
+
+/** Installed plugin names, read from the plugin directory. */
+export function listLocalPlugins() {
+  let entries;
+  try { entries = fs.readdirSync(pluginsDir()); } catch { return []; }
+  const out = [];
+  for (const e of entries) {
+    if (e.startsWith('.')) continue;
+    const full = path.join(pluginsDir(), e);
+    let st;
+    try { st = fs.statSync(full); } catch { continue; }
+    if (st.isDirectory()) out.push({ name: e, kind: 'dir', path: full });
+    else if (/\.(mjs?|cjs)$/i.test(e)) out.push({ name: e.replace(/\.[^.]+$/, ''), kind: 'file', path: full });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}