@hncode/hncode 0.3.2 → 0.3.4

package/src/mcp.js

@@ -0,0 +1,384 @@
+// MCP client — connect to Model Context Protocol servers and expose their tools.
+//
+// The Model Context Protocol is an open JSON-RPC 2.0 standard. A server speaks it
+// over stdio (a child process) or HTTP. This module implements the CLIENT side so
+// an hncode session can use tools from servers the user configures.
+//
+// Config (`~/.hncode/mcp.json`, or a per-project `<workspace>/.hncode/mcp.json`):
+//
+//   {
+//     "mcpServers": {
+//       "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] },
+//       "remote":     { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." } }
+//     }
+//   }
+//
+// Lifecycle, per the spec:
+//   1. start the transport
+//   2. `initialize`                 (protocolVersion + clientInfo) -> capabilities
+//   3. `notifications/initialized`
+//   4. `tools/list`                 -> tool definitions
+//   5. `tools/call`                 -> per invocation
+//
+// Discovered tools are registered through plugin.registerTool() so they reach the
+// model with no changes to the toolbelt, the agent loop, or the LLM adapters.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import cp from 'node:child_process';
+
+// The protocol revision this client speaks. Servers negotiate down if needed.
+export const PROTOCOL_VERSION = '2024-11-05';
+export const CLIENT_INFO = { name: 'hncode', version: '0.3.1' };
+
+// How long a server gets to complete the initialize + tools/list handshake. This
+// runs BEFORE the TUI opens, so it is deliberately short: a wedged server should
+// cost a few seconds, not the 30s a tool call is allowed.
+export const CONNECT_TIMEOUT_MS = 8_000;
+
+// Live connections made at startup, shared by every consumer of the MCP client
+// (the CLI startup and the TUI's /mcp). Kept in this module rather than passed
+// around so the status view can always see the real state.
+let liveConnections = [];
+export function setLiveConnections(conns) { liveConnections = conns || []; }
+export function getLiveConnections() { return liveConnections; }
+
+export function globalMcpFile() {
+  return process.env.HNCODE_MCP_FILE || path.join(os.homedir(), '.hncode', 'mcp.json');
+}
+export function projectMcpFile(workspace) {
+  return path.join(workspace || process.cwd(), '.hncode', 'mcp.json');
+}
+
+// Merge global + project server definitions (project wins on a name clash).
+// Returns { servers: {name: def}, errors: [string] }. Never throws.
+export function loadMcpConfig(workspace) {
+  const out = { servers: {}, errors: [] };
+  const files = workspace ? [globalMcpFile(), projectMcpFile(workspace)] : [globalMcpFile()];
+  const seen = new Set();
+  for (const f of files) {
+    const abs = path.resolve(f);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { out.errors.push(`${abs}: invalid JSON (${e.message})`); continue; }
+    const servers = (doc && doc.mcpServers) || {};
+    for (const [name, def] of Object.entries(servers)) {
+      if (!def || typeof def !== 'object') { out.errors.push(`${abs}: server "${name}" must be an object`); continue; }
+      if (!def.command && !def.url) { out.errors.push(`${abs}: server "${name}" needs "command" or "url"`); continue; }
+      out.servers[name] = { ...def, _source: abs };
+    }
+  }
+  return out;
+}
+
+// ---- JSON-RPC framing -------------------------------------------------------
+
+// A stdio connection: newline-delimited JSON-RPC over the child's stdin/stdout.
+// MCP's stdio transport is line-delimited (NOT Content-Length framed — that is
+// the LSP convention, and mixing them up is the usual way this breaks).
+export function createStdioTransport(command, args, opts = {}) {
+  const child = cp.spawn(command, args || [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, ...(opts.env || {}) },
+    cwd: opts.cwd || process.cwd(),
+    windowsHide: true,
+    // npm-installed shims are `.cmd` on Windows and need a shell to run.
+    shell: process.platform === 'win32' && /\.(cmd|bat)$/i.test(command),
+  });
+  const state = {
+    child,
+    buffer: '',
+    nextId: 1,
+    pending: new Map(),   // id -> { resolve, reject, timer }
+    closed: false,
+    stderr: '',
+    handlers: [],
+  };
+  child.stdout.on('data', (d) => {
+    state.buffer += d.toString('utf8');
+    let i;
+    while ((i = state.buffer.indexOf('\n')) >= 0) {
+      const line = state.buffer.slice(0, i).trim();
+      state.buffer = state.buffer.slice(i + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }   // ignore non-JSON noise
+      handleMessage(state, msg);
+    }
+  });
+  child.stderr.on('data', (d) => { state.stderr = (state.stderr + d.toString('utf8')).slice(-4000); });
+  child.on('error', (e) => failAll(state, `server process error: ${e.message}`));
+  child.on('close', (code) => { state.closed = true; failAll(state, `server exited (code ${code})`); });
+  return state;
+}
+
+function handleMessage(state, msg) {
+  if (msg.id != null && state.pending.has(msg.id)) {
+    const p = state.pending.get(msg.id);
+    state.pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.error) p.reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+    else p.resolve(msg.result);
+    return;
+  }
+  // A server-initiated REQUEST (e.g. sampling). Answer politely so the server
+  // does not hang; hncode does not implement sampling, so it is "not supported".
+  if (msg.method && msg.id != null) {
+    try {
+      writeMessage(state, { jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: `method not supported: ${msg.method}` } });
+    } catch { /* transport closed */ }
+    return;
+  }
+  for (const h of state.handlers) { try { h(msg); } catch { /* a notification handler must not throw */ } }
+}
+
+function failAll(state, reason) {
+  for (const [, p] of state.pending) { clearTimeout(p.timer); p.reject(new Error(reason)); }
+  state.pending.clear();
+}
+
+function writeMessage(state, msg) {
+  if (state.closed || !state.child.stdin || state.child.stdin.destroyed) throw new Error('transport closed');
+  state.child.stdin.write(JSON.stringify(msg) + '\n');
+}
+
+// Send a request and await its reply. `timeoutMs` guards a wedged server.
+export function request(state, method, params, timeoutMs = 30_000) {
+  const id = state.nextId++;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      state.pending.delete(id);
+      reject(new Error(`${method} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    state.pending.set(id, { resolve, reject, timer });
+    try { writeMessage(state, { jsonrpc: '2.0', id, method, params: params || {} }); }
+    catch (e) { state.pending.delete(id); clearTimeout(timer); reject(e); }
+  });
+}
+
+function notify(state, method, params) {
+  try { writeMessage(state, { jsonrpc: '2.0', method, params: params || {} }); } catch { /* best-effort */ }
+}
+
+// ---- HTTP transport ---------------------------------------------------------
+
+// Streamable-HTTP transport: one POST per JSON-RPC message. The server may reply
+// with JSON or an SSE stream; both are parsed here.
+export function createHttpTransport(url, headers) {
+  return {
+    kind: 'http',
+    url,
+    headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...(headers || {}) },
+    sessionId: null,
+    nextId: 1,
+  };
+}
+
+export async function httpRequest(state, method, params, timeoutMs = 30_000) {
+  const id = state.nextId++;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(state.url, {
+      method: 'POST',
+      headers: state.sessionId ? { ...state.headers, 'mcp-session-id': state.sessionId } : state.headers,
+      body: JSON.stringify({ jsonrpc: '2.0', id, method, params: params || {} }),
+      signal: ctrl.signal,
+    });
+    const sid = res.headers.get('mcp-session-id');
+    if (sid) state.sessionId = sid;
+    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+    const ct = (res.headers.get('content-type') || '').toLowerCase();
+    if (ct.includes('text/event-stream')) {
+      const msg = parseSseForId(await res.text(), id);
+      if (!msg) throw new Error('no response message in SSE stream');
+      if (msg.error) throw new Error(msg.error.message || JSON.stringify(msg.error));
+      return msg.result;
+    }
+    const json = await res.json();
+    if (json.error) throw new Error(json.error.message || JSON.stringify(json.error));
+    return json.result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Pull the JSON-RPC reply for `id` out of an SSE body.
+export function parseSseForId(body, id) {
+  for (const line of String(body || '').split('\n')) {
+    const l = line.trim();
+    if (!l.startsWith('data:')) continue;
+    const payload = l.slice(5).trim();
+    if (!payload || payload === '[DONE]') continue;
+    try {
+      const msg = JSON.parse(payload);
+      if (msg && msg.id === id) return msg;
+    } catch { /* not JSON: skip */ }
+  }
+  return null;
+}
+
+// ---- connection + tool discovery -------------------------------------------
+
+// Connect to one server, handshake, and list its tools.
+// Returns { ok, tools, error, serverInfo, transport, isHttp } — never throws.
+export async function connectServer(name, def, opts = {}) {
+  // CONNECT_TIMEOUT (not the 30s tool-call timeout): this runs during startup, so
+  // a wedged server must not hold the session hostage. 8s is generous for a
+  // handshake while keeping a dead server's cost to single-digit seconds.
+  const timeoutMs = opts.timeoutMs || CONNECT_TIMEOUT_MS;
+  let transport;
+  const isHttp = !!def.url;
+  try {
+    transport = isHttp
+      ? createHttpTransport(def.url, def.headers)
+      : createStdioTransport(def.command, def.args, { env: def.env, cwd: def.cwd });
+  } catch (e) {
+    return { ok: false, tools: [], error: `could not start "${name}": ${e.message}` };
+  }
+
+  const send = (method, params) => (isHttp
+    ? httpRequest(transport, method, params, timeoutMs)
+    : request(transport, method, params, timeoutMs));
+
+  try {
+    const init = await send('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      clientInfo: CLIENT_INFO,
+    });
+    if (!isHttp) notify(transport, 'notifications/initialized', {});
+    const list = await send('tools/list', {});
+    const tools = Array.isArray(list && list.tools) ? list.tools : [];
+    return { ok: true, tools, error: null, serverInfo: (init && init.serverInfo) || {}, transport, isHttp };
+  } catch (e) {
+    try { if (!isHttp) transport.child.kill(); } catch { /* already gone */ }
+    return { ok: false, tools: [], error: `"${name}": ${e.message}` };
+  }
+}
+
+// Call one tool on a connected server. Returns { ok, text, error, raw }.
+export async function callTool(transport, isHttp, toolName, args, timeoutMs = 60_000) {
+  try {
+    const result = isHttp
+      ? await httpRequest(transport, 'tools/call', { name: toolName, arguments: args || {} }, timeoutMs)
+      : await request(transport, 'tools/call', { name: toolName, arguments: args || {} }, timeoutMs);
+    return { ok: true, text: flattenContent(result), error: null, raw: result };
+  } catch (e) {
+    return { ok: false, text: '', error: e.message, raw: null };
+  }
+}
+
+// MCP tool results carry a `content` array of typed blocks. Flatten to text for
+// the model; non-text blocks are described rather than dropped silently.
+export function flattenContent(result) {
+  if (!result) return '';
+  if (typeof result === 'string') return result;
+  const blocks = Array.isArray(result.content) ? result.content : [];
+  const parts = [];
+  for (const b of blocks) {
+    if (!b || typeof b !== 'object') continue;
+    if (b.type === 'text' && typeof b.text === 'string') parts.push(b.text);
+    else if (b.type === 'resource' && b.resource) parts.push(`[resource ${b.resource.uri || ''}]`);
+    else if (b.type === 'image') parts.push(`[image ${b.mimeType || ''}]`);
+    else parts.push(`[${b.type || 'unknown'} block]`);
+  }
+  if (!parts.length && typeof result.text === 'string') parts.push(result.text);
+  return parts.join('\n');
+}
+
+// A tool name safe for every provider's function-name rules and for matching
+// back to its server + original name. Providers want [A-Za-z0-9_-], so
+// "server.tool" becomes "mcp__server__tool".
+export function mcpToolName(server, tool) {
+  const clean = (s) => String(s || '').replace(/[^A-Za-z0-9_-]/g, '_');
+  return `mcp__${clean(server)}__${clean(tool)}`;
+}
+
+// Convert an MCP tool definition into an hncode tool spec whose execute() calls
+// back into the server.
+export function toHncodeSpec(server, tool, transport, isHttp) {
+  return {
+    name: mcpToolName(server, tool.name),
+    description: (tool.description || `MCP tool ${tool.name} from ${server}.`).slice(0, 4000),
+    parameters: tool.inputSchema && typeof tool.inputSchema === 'object'
+      ? tool.inputSchema
+      : { type: 'object', properties: {} },
+    _mcp: { server, tool: tool.name },
+    async execute(args) {
+      const r = await callTool(transport, isHttp, tool.name, args);
+      if (!r.ok) return `Error calling ${server}/${tool.name}: ${r.error}`;
+      // MCP signals tool-level failure with isError, not a JSON-RPC error.
+      if (r.raw && r.raw.isError) return `Error from ${server}/${tool.name}: ${r.text}`;
+      return r.text || '(no output)';
+    },
+  };
+}
+
+// Connect every configured server and register its tools through the plugin API.
+// Returns { servers: [...], toolCount }.
+export async function connectAll(config, registerTool, opts = {}) {
+  const only = opts.only;
+  const entries = Object.entries((config && config.servers) || {}).filter(([name]) => !only || only.includes(name));
+  // Connect in PARALLEL. This runs on the startup path, before the TUI opens, so
+  // a serial loop meant one slow/wedged server delayed every later one — N dead
+  // servers cost N × timeout before the user saw anything. Runs concurrently, the
+  // whole set costs the SLOWEST single server instead of their sum.
+  const results = await Promise.all(entries.map(async ([name, def]) => {
+    const conn = await connectServer(name, def, opts);
+    if (!conn.ok) return { name, ok: false, toolCount: 0, error: conn.error, serverInfo: {} };
+    let registered = 0;
+    let err = null;
+    for (const tool of conn.tools) {
+      if (!tool || !tool.name) continue;
+      try {
+        registerTool(toHncodeSpec(name, tool, conn.transport, conn.isHttp));
+        registered++;
+      } catch (e) {
+        // A name clash with a built-in is reported, not fatal: keep the rest.
+        err = err || `tool "${tool.name}": ${e.message}`;
+      }
+    }
+    return { name, ok: true, toolCount: registered, error: err, serverInfo: conn.serverInfo, transport: conn.transport, isHttp: conn.isHttp };
+  }));
+  const toolCount = results.reduce((n, r) => n + (r.toolCount || 0), 0);
+  return { servers: results, toolCount };
+}
+// Disconnect every connected server (kills stdio children). HTTP needs nothing.
+
+// Disconnect every connected server (kills stdio children). HTTP needs nothing.
+export function disconnectAll(connections) {
+  for (const c of connections || []) {
+    if (c && c.transport && c.transport.child) {
+      try { c.transport.child.kill(); } catch { /* already gone */ }
+    }
+  }
+}
+
+// Human-readable status for /mcp.
+export function describeServers(config, connections) {
+  const names = Object.keys((config && config.servers) || {});
+  if (!names.length) {
+    return ['No MCP servers configured.', '', `Config file: ${globalMcpFile()}`,
+      'Add one with /mcp-config add <name> <command|url> [args...]'];
+  }
+  const byName = new Map((connections || []).map((c) => [c.name, c]));
+  const lines = [`MCP servers (${names.length}) — config: ${globalMcpFile()}`, ''];
+  for (const n of names) {
+    const def = config.servers[n];
+    const conn = byName.get(n);
+    const target = def.url ? def.url : `${def.command || ''} ${(def.args || []).join(' ')}`.trim();
+    let status;
+    if (!conn) status = 'not connected';
+    else if (!conn.ok) status = `FAILED: ${conn.error}`;
+    else status = `connected — ${conn.toolCount} tool(s)${conn.serverInfo && conn.serverInfo.name ? ` (${conn.serverInfo.name})` : ''}`;
+    lines.push(`  ${n}: ${status}`);
+    lines.push(`      ${target}`);
+    if (conn && conn.error) lines.push(`      ! ${conn.error}`);
+  }
+  return lines;
+}

package/src/plan.js

@@ -0,0 +1,127 @@
+// Plan review helpers — turning a model's <plan> block into something the user
+// can actually review before any file is touched.
+//
+// Plan mode already asks the model for a <plan>…</plan> block and prompts to
+// approve it. What this module adds is the review material and the persistence:
+//
+//   * filesReferenced(plan)  — which paths the plan says it will touch, so the
+//                              user sees the blast radius instead of prose.
+//   * planStats(plan)        — step/line counts for a compact summary line.
+//   * savePlan()             — write the approved plan to
+//                              <workspace>/.hncode/plans/<timestamp>.md so it
+//                              survives the session and can be handed to a
+//                              subagent or pasted into an issue.
+//
+// Everything here is pure except savePlan(). The parsing is deliberately
+// tolerant: a plan is free-form Markdown, so a missed file reference degrades to
+// "fewer files listed", never to an error.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Paths that appear in a plan: backticked spans, and bare tokens that look like
+// a path (contains a slash and a file-ish extension, or a well-known filename).
+// Ordered by first appearance, de-duplicated, and filtered to plausible files.
+const PATH_EXT = /\.(?:[a-z0-9]{1,8})$/i;
+const KNOWN_FILES = /^(?:AGENTS\.md|README(?:\.[a-z]+)?|package\.json|pyproject\.toml|Cargo\.toml|go\.mod|Makefile|Dockerfile|\.gitignore|tsconfig\.json)$/i;
+
+export function filesReferenced(plan) {
+  const text = String(plan || '');
+  const found = [];
+  const seen = new Set();
+  const push = (raw) => {
+    let p = String(raw || '').trim();
+    // Strip trailing punctuation the prose adds around a path.
+    p = p.replace(/^[`'"(\[]+/, '').replace(/[`'")\],.;:]+$/, '');
+    if (!p || p.length > 200) return;
+    if (/\s/.test(p)) return;
+    if (p.includes('://')) return;                 // a URL, not a path
+    if (/^[-*#>]/.test(p)) return;
+    // A token is a plausible path when it has a separator, a file-ish extension,
+    // or is a well-known project filename. This keeps a bare word like "config"
+    // from being reported as a file.
+    const looksPath = p.includes('/') || p.includes('\\') || PATH_EXT.test(p) || KNOWN_FILES.test(p);
+    if (!looksPath) return;
+    const key = p.replace(/\\/g, '/');
+    if (seen.has(key)) return;
+    seen.add(key);
+    found.push(p);
+  };
+
+  // 1. backticked spans (the prompt asks for files in backticks)
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) push(m[1]);
+  // 2. bare tokens that look like paths (covers un-backticked mentions)
+  for (const m of text.matchAll(/(?:^|[\s(])((?:[\w.@-]+\/)+[\w.@-]+|\b[\w.-]+\.[a-z0-9]{1,8}\b)/gi)) push(m[1]);
+  return found;
+}
+
+// Compact summary for the review box: how many steps and how many lines.
+export function planStats(plan) {
+  const text = String(plan || '');
+  const lines = text.split('\n');
+  const nonEmpty = lines.filter((l) => l.trim()).length;
+  // A "step" is a heading (## / ###) or a top-level numbered item.
+  const steps = lines.filter((l) => /^\s*(?:#{1,6}\s+\S|\d+[.)]\s+\S)/.test(l)).length;
+  const words = text.split(/\s+/).filter(Boolean).length;
+  return { lines: nonEmpty, steps, words, files: filesReferenced(text).length };
+}
+
+// Where a saved plan goes: <workspace>/.hncode/plans/<id>.md. Kept inside the
+// project (not ~/.hncode) so it can be committed or reviewed with the change.
+export function plansDir(workspace) {
+  return path.join(workspace || process.cwd(), '.hncode', 'plans');
+}
+
+// Persist a plan. `id` defaults to a timestamp slug. Returns
+// { ok, path, error }. Never throws.
+export function savePlan(plan, workspace, id) {
+  const text = String(plan || '').trim();
+  if (!text) return { ok: false, path: '', error: 'empty plan' };
+  const dir = plansDir(workspace);
+  const slug = id || new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+  const file = path.join(dir, `${slug}.md`);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, `# Plan (${new Date().toISOString()})\n\n${text}\n`, 'utf8');
+  } catch (e) {
+    return { ok: false, path: file, error: e.message };
+  }
+  return { ok: true, path: file, error: null };
+}
+
+export function listPlans(workspace) {
+  const dir = plansDir(workspace);
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    if (!n.endsWith('.md')) continue;
+    const full = path.join(dir, n);
+    try { const st = fs.statSync(full); if (st.isFile()) out.push({ name: n, path: full, mtimeMs: st.mtimeMs }); }
+    catch { /* unreadable: skip */ }
+  }
+  // Newest first. Tie-break by name DESCENDING so that two plans written in the
+  // same millisecond still come back in a deterministic (and, for the
+  // timestamp-slug naming, newest-looking) order.
+  out.sort((a, b) => (b.mtimeMs - a.mtimeMs) || (a.name < b.name ? 1 : a.name > b.name ? -1 : 0));
+  return out;
+}
+
+// The review panel's lines. Kept here (not the TUI) so it can be unit-tested.
+export function reviewLines(plan, workspace) {
+  const stats = planStats(plan);
+  const files = filesReferenced(plan);
+  const lines = [];
+  lines.push(`Steps: ${stats.steps}   Lines: ${stats.lines}   Files mentioned: ${files.length}`);
+  lines.push('');
+  if (files.length) {
+    lines.push('Files this plan will touch:');
+    for (const f of files.slice(0, 40)) lines.push(`  ${f}`);
+    if (files.length > 40) lines.push(`  … and ${files.length - 40} more`);
+  } else {
+    lines.push('No specific files named in the plan.');
+  }
+  lines.push('');
+  lines.push('Enter = approve & execute   e = edit the plan   Esc = keep planning');
+  return lines;
+}

package/src/skills.js

@@ -0,0 +1,150 @@
+// Skills — user-supplied reusable prompt packages.
+//
+// A skill is a Markdown file under ~/.hncode/skills/<name>.md. Its body is
+// text that gets injected into the conversation when the user activates it, so
+// a skill is essentially a saved prompt fragment ("review this PR for security
+// issues", "write tests in this project's style", …).
+//
+// Two ways a skill comes into being:
+//   * /import-skill <file.md>  — copies (or overwrites) an external .md into the
+//     skills directory. A duplicate name is REPLACED, not rejected.
+//   * hand-authoring a file in the skills directory.
+//
+// Activation is /skill:<name>. The file body is what gets sent; an optional YAML
+// front-matter block (--- … ---) is stripped from the body and only used for the
+// display name / description, so a skill file can stay self-describing without
+// leaking its metadata into the prompt.
+//
+// Everything here is filesystem-only and side-effect free apart from the
+// explicit import/write helpers.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const SKILL_PREFIX = 'skill:';
+
+// The skills directory. Kept next to the other hncode state (~/.hncode/…), and
+// overridable through the environment for tests.
+export function skillsDir() {
+  return process.env.HNCODE_SKILLS_DIR || path.join(os.homedir(), '.hncode', 'skills');
+}
+
+// A skill name is the file's basename without extension. Normalise what the
+// user typed ("Skill:Review", "/skill:review", "review.md") to a bare name.
+export function normalizeSkillName(name) {
+  let n = String(name == null ? '' : name).trim();
+  n = n.replace(/^\/+/, '');                  // leading slash
+  if (n.toLowerCase().startsWith(SKILL_PREFIX)) n = n.slice(SKILL_PREFIX.length);
+  n = n.replace(/\.md$/i, '');                // trailing .md
+  return n.trim();
+}
+
+// Parse an optional leading `---\n…\n---` front-matter block. Returns the body
+// with the block removed, plus whatever fields were found. Tolerates a missing
+// or malformed block (then body === text and meta is empty).
+export function parseFrontMatter(text) {
+  const src = String(text == null ? '' : text);
+  const m = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/.exec(src);
+  if (!m) return { meta: {}, body: src };
+  const meta = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^\s*([A-Za-z0-9_-]+)\s*:\s*(.*?)\s*$/.exec(line);
+    if (!kv) continue;
+    let v = kv[2];
+    // Strip a single layer of matching quotes.
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    meta[kv[1].toLowerCase()] = v;
+  }
+  return { meta, body: src.slice(m[0].length) };
+}
+
+// All skills, sorted by name. Each entry: { name, description, path, size }.
+// Unreadable files are skipped rather than failing the whole listing.
+export function listSkills() {
+  const dir = skillsDir();
+  let files;
+  try { files = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const f of files) {
+    if (!f.toLowerCase().endsWith('.md')) continue;
+    const full = path.join(dir, f);
+    let st;
+    try { st = fs.statSync(full); } catch { continue; }
+    if (!st.isFile()) continue;
+    const name = f.replace(/\.md$/i, '');
+    let description = '';
+    try {
+      const { meta } = parseFrontMatter(fs.readFileSync(full, 'utf8'));
+      description = meta.description || meta.title || '';
+    } catch { /* unreadable: keep it listed with no description */ }
+    out.push({ name, description, path: full, size: st.size });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+// Read a skill's body (front-matter stripped). Returns null when not found.
+export function readSkill(name) {
+  const n = normalizeSkillName(name);
+  if (!n) return null;
+  const full = path.join(skillsDir(), `${n}.md`);
+  let text;
+  try { text = fs.readFileSync(full, 'utf8'); } catch { return null; }
+  const { meta, body } = parseFrontMatter(text);
+  return { name: n, description: meta.description || meta.title || '', body: body.trim(), path: full };
+}
+
+// Import (copy or overwrite) an external Markdown file as a skill.
+// `name` overrides the derived name when given. Returns
+// { ok: true, name, path, replaced } or { ok: false, error }.
+export function importSkill(file, name) {
+  const srcPath = path.resolve(String(file == null ? '' : file));
+  let text;
+  try {
+    const st = fs.statSync(srcPath);
+    if (!st.isFile()) return { ok: false, error: `Not a file: ${srcPath}` };
+    text = fs.readFileSync(srcPath, 'utf8');
+  } catch (e) {
+    return { ok: false, error: `Cannot read ${srcPath}: ${e.message}` };
+  }
+  // Name precedence: explicit argument, else front-matter `name`, else filename.
+  const { meta } = parseFrontMatter(text);
+  const derived = name || meta.name || path.basename(srcPath).replace(/\.md$/i, '');
+  const skillName = normalizeSkillName(derived);
+  if (!skillName) return { ok: false, error: 'Could not derive a skill name (pass one explicitly).' };
+  if (/[\\/]/.test(skillName)) return { ok: false, error: `Invalid skill name: ${skillName}` };
+
+  const dir = skillsDir();
+  const dest = path.join(dir, `${skillName}.md`);
+  const replaced = fs.existsSync(dest);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(dest, text, 'utf8');
+  } catch (e) {
+    return { ok: false, error: `Cannot write ${dest}: ${e.message}` };
+  }
+  return { ok: true, name: skillName, path: dest, replaced };
+}
+
+export function deleteSkill(name) {
+  const n = normalizeSkillName(name);
+  if (!n) return false;
+  try { fs.unlinkSync(path.join(skillsDir(), `${n}.md`)); return true; } catch { return false; }
+}
+
+// Completion candidates for the composer: names prefixed with the marker the
+// user must type, so accepting a candidate yields `/skill:<name>`.
+export function skillCompletions(prefix = '') {
+  const p = normalizeSkillName(prefix).toLowerCase();
+  return listSkills()
+    .filter((s) => !p || s.name.toLowerCase().startsWith(p))
+    .map((s) => ({ name: s.name, description: s.description, insert: SKILL_PREFIX + s.name }));
+}
+
+// Build the text a skill contributes to the conversation. A short header keeps
+// the model from treating the body as the user's own words.
+export function skillPrompt(skill) {
+  if (!skill || !skill.body) return '';
+  return `[skill: ${skill.name}]\n\n${skill.body}`;
+}

package/src/subagent-types.js

@@ -41,7 +41,7 @@ export const SUBAGENT_TYPES = {
     // An explicit allowlist (not `null` = everything) so Agent/AgentSwarm are
     // excluded. Mirrors kimi's CODER_TOOLS.
     tools: [
-      'Read', 'Write', 'Edit', 'Glob', 'Grep', 'FileLines', 'Bash',
+      'Read', 'Write', 'Edit', 'Glob', 'Grep', 'FileLines', 'Bash', 'Git',
       'TodoList', 'FetchURL', 'WebSearch', 'ReadMediaFile',
       'TaskList', 'TaskOutput', 'TaskStop', 'TaskWait',
     ],