@tiens.nguyen/gu-cli 1.0.739 → 1.0.741

package/mcp-config.mjs

@@ -0,0 +1,329 @@
+/**
+ * MCP SERVERS — where they are configured, and who may call their tools (task #269).
+ *
+ *   ~/.gonext/mcp.json   yours: { mcpServers, disabled, permissions: { allow, deny }, approvedProjects }
+ *   <project>/.mcp.json  the project's — Claude Code's own file and format, so one file serves both
+ *
+ * The shapes are Claude Code's: `mcpServers: { name: { type: "stdio", command, args, env } }`, and
+ * permission rules `mcp__<server>` / `mcp__<server>__*` / `mcp__<server>__<tool>`. A command copied
+ * from an MCP server's README (`claude mcp add …`) works as `gu mcp add …`.
+ *
+ * A PROJECT'S SERVERS DO NOT START UNTIL YOU APPROVE THEM. Starting a stdio server runs a command,
+ * and a project's .mcp.json came with the repository — cloning something is not agreeing to run
+ * what it names. Claude Code asks before connecting them for the same reason. Approval is per
+ * folder and per server, and lives in YOUR file, never in the project's.
+ *
+ * PERMISSIONS: deny, then ask, then allow — the first rule that matches decides, and a deny can
+ * never be carved open by a narrower allow (Claude Code's order). No rule = ask. A server saying a
+ * tool is read-only (readOnlyHint) is NOT a rule: the MCP spec says clients must treat those hints
+ * as untrusted, and a hostile server would simply claim it.
+ *
+ * ONE WRITER SHAPE. Both `gu mcp` and `/mcp` go through updateUserConfig, which re-reads the file,
+ * changes one thing and writes it back atomically — keys it does not know are kept. Rebuilding the
+ * object from what one side knows is how a settings screen once deleted the other side's entries.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export const SERVER_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function userConfigPath(home = homedir()) {
+  return join(home, ".gonext", "mcp.json");
+}
+export function projectConfigPath(cwd) {
+  return join(cwd, ".mcp.json");
+}
+
+function readJson(file) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return { data: null }; // no file: nothing configured, not an error
+  }
+  try {
+    const data = JSON.parse(text);
+    if (!data || typeof data !== "object" || Array.isArray(data)) return { data: null, error: "not a JSON object" };
+    return { data };
+  } catch (e) {
+    return { data: null, error: `not valid JSON (${e.message})` };
+  }
+}
+
+export function readUserConfig(home = homedir()) {
+  const { data, error } = readJson(userConfigPath(home));
+  const cfg = data ?? {};
+  return {
+    raw: cfg,
+    error,
+    mcpServers: isObj(cfg.mcpServers) ? cfg.mcpServers : {},
+    disabled: Array.isArray(cfg.disabled) ? cfg.disabled.map(String) : [],
+    allow: Array.isArray(cfg.permissions?.allow) ? cfg.permissions.allow.map(String) : [],
+    deny: Array.isArray(cfg.permissions?.deny) ? cfg.permissions.deny.map(String) : [],
+    approvedProjects: isObj(cfg.approvedProjects) ? cfg.approvedProjects : {},
+  };
+}
+
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** Write ~/.gonext/mcp.json atomically: a crash mid-write leaves the old file, never half of one. */
+function writeUserRaw(raw, home) {
+  const file = userConfigPath(home);
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(raw, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/**
+ * Re-read, change, write back. `mutate(raw)` edits the parsed file in place. A file that is not
+ * valid JSON is refused rather than overwritten — it may be hand-edited and one typo from fine.
+ */
+export function updateUserConfig(mutate, home = homedir()) {
+  const { data, error } = readJson(userConfigPath(home));
+  if (error) throw new Error(`${userConfigPath(home)} is ${error} — fix or remove it first`);
+  const raw = data ?? {};
+  mutate(raw);
+  writeUserRaw(raw, home);
+  return raw;
+}
+
+/** Normalize one server entry → { type, command, args, env } | { error }. */
+export function normalizeServer(entry) {
+  if (!isObj(entry)) return { error: "not an object" };
+  const type = String(entry.type ?? (entry.url ? "http" : "stdio"));
+  if (type !== "stdio") return { error: `transport "${type}" is not supported yet — only stdio` };
+  const command = String(entry.command ?? "").trim();
+  if (!command) return { error: "no command" };
+  const args = Array.isArray(entry.args) ? entry.args.map(String) : [];
+  const env = isObj(entry.env) ? Object.fromEntries(Object.entries(entry.env).map(([k, v]) => [k, String(v)])) : {};
+  return { type, command, args, env };
+}
+
+/**
+ * Every server this folder knows of, with its state.
+ * → { servers: [{ name, scope, type, command, args, env, disabled, approved, runnable, error? }], warnings }
+ */
+export function listServers({ cwd = process.cwd(), home = homedir() } = {}) {
+  const user = readUserConfig(home);
+  const warnings = [];
+  if (user.error) warnings.push(`${userConfigPath(home)} is ${user.error} — its servers are skipped`);
+  const servers = [];
+  const seen = new Set();
+  const add = (name, entry, scope, approved) => {
+    if (!SERVER_NAME_RE.test(name)) {
+      warnings.push(`${scope} MCP server "${name}": the name must be letters, digits, _ or - — skipped`);
+      return;
+    }
+    if (seen.has(name)) return; // yours wins over the project's
+    seen.add(name);
+    const n = normalizeServer(entry);
+    const disabled = user.disabled.includes(name);
+    servers.push({
+      name,
+      scope,
+      ...(n.error ? { error: n.error } : n),
+      disabled,
+      approved,
+      runnable: !n.error && !disabled && approved,
+    });
+  };
+  for (const [name, entry] of Object.entries(user.mcpServers)) add(name, entry, "user", true);
+  if (cwd) {
+    const proj = readJson(projectConfigPath(cwd));
+    if (proj.error) warnings.push(`${projectConfigPath(cwd)} is ${proj.error} — its servers are skipped`);
+    const approvedHere = (user.approvedProjects[resolve(cwd)] ?? []).map(String);
+    for (const [name, entry] of Object.entries(isObj(proj.data?.mcpServers) ? proj.data.mcpServers : {})) {
+      add(name, entry, "project", approvedHere.includes(name));
+    }
+  }
+  return { servers, warnings };
+}
+
+/** What the worker hands the agent for one turn: the servers it may start, and the rules. */
+export function mcpForTurn({ cwd, home = homedir() } = {}) {
+  const { servers } = listServers({ cwd, home });
+  const user = readUserConfig(home);
+  return {
+    servers: servers
+      .filter((s) => s.runnable)
+      .map(({ name, command, args, env, scope }) => ({ name, command, args, env, scope })),
+    allow: user.allow,
+    deny: user.deny,
+    configPath: userConfigPath(home),
+  };
+}
+
+/* ---------------------------------------------------------------- permissions ---------- */
+
+/** Does a rule name this server's tool? `mcp__s`, `mcp__s__*`, `mcp__s__tool`, `mcp__s__get_*`, `mcp__*`. */
+export function ruleMatches(rule, server, tool) {
+  const r = String(rule).trim();
+  if (r === "mcp__*" || r === "*") return true;
+  if (r === `mcp__${server}`) return true;
+  const full = `mcp__${server}__${tool}`;
+  if (!r.includes("*")) return r === full;
+  const re = new RegExp("^" + r.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
+  return re.test(full);
+}
+
+/** → "deny" | "allow" | "ask". Deny first, then allow; nothing matching = ask. */
+export function decide({ allow = [], deny = [] }, server, tool) {
+  if (deny.some((r) => ruleMatches(r, server, tool))) return "deny";
+  if (allow.some((r) => ruleMatches(r, server, tool))) return "allow";
+  return "ask";
+}
+
+/* ---------------------------------------------------------------- changes -------------- */
+
+export function addServer({ name, command, args = [], env = {}, scope = "user", cwd, home = homedir() }) {
+  if (!SERVER_NAME_RE.test(name ?? "")) throw new Error(`"${name}" is not a valid name — use letters, digits, _ or -`);
+  if (!String(command ?? "").trim()) throw new Error("no command given");
+  const entry = { type: "stdio", command: String(command), args: args.map(String), env };
+  if (scope === "project") {
+    if (!cwd) throw new Error("no project folder");
+    const file = projectConfigPath(cwd);
+    const { data, error } = readJson(file);
+    if (error) throw new Error(`${file} is ${error} — fix or remove it first`);
+    const raw = data ?? {};
+    raw.mcpServers = isObj(raw.mcpServers) ? raw.mcpServers : {};
+    raw.mcpServers[name] = entry;
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(raw, null, 2) + "\n", "utf8");
+    renameSync(tmp, file);
+    // You added it yourself, from this folder: that IS the approval.
+    approveProjectServer({ name, cwd, home });
+    return { file };
+  }
+  updateUserConfig((raw) => {
+    raw.mcpServers = isObj(raw.mcpServers) ? raw.mcpServers : {};
+    raw.mcpServers[name] = entry;
+    if (Array.isArray(raw.disabled)) raw.disabled = raw.disabled.filter((d) => d !== name);
+  }, home);
+  return { file: userConfigPath(home) };
+}
+
+/** Remove from YOUR file. A project's server cannot be removed from here — only not approved. */
+export function removeServer({ name, home = homedir() }) {
+  let found = false;
+  updateUserConfig((raw) => {
+    if (isObj(raw.mcpServers) && name in raw.mcpServers) {
+      delete raw.mcpServers[name];
+      found = true;
+    }
+    if (Array.isArray(raw.disabled)) raw.disabled = raw.disabled.filter((d) => d !== name);
+    if (isObj(raw.permissions)) {
+      for (const k of ["allow", "deny"]) {
+        if (Array.isArray(raw.permissions[k])) {
+          raw.permissions[k] = raw.permissions[k].filter((r) => !(r === `mcp__${name}` || String(r).startsWith(`mcp__${name}__`)));
+        }
+      }
+    }
+  }, home);
+  return found;
+}
+
+export function setDisabled({ name, disabled, home = homedir() }) {
+  updateUserConfig((raw) => {
+    const list = Array.isArray(raw.disabled) ? raw.disabled.filter((d) => d !== name) : [];
+    if (disabled) list.push(name);
+    raw.disabled = list;
+  }, home);
+}
+
+export function approveProjectServer({ name, cwd, home = homedir(), approve = true }) {
+  const key = resolve(cwd);
+  updateUserConfig((raw) => {
+    raw.approvedProjects = isObj(raw.approvedProjects) ? raw.approvedProjects : {};
+    const list = (raw.approvedProjects[key] ?? []).filter((n) => n !== name);
+    if (approve) list.push(name);
+    raw.approvedProjects[key] = list;
+  }, home);
+}
+
+/** Add an allow rule (no duplicates). Used by "Always allow" at the approval prompt. */
+export function addAllowRule({ rule, home = homedir() }) {
+  updateUserConfig((raw) => {
+    raw.permissions = isObj(raw.permissions) ? raw.permissions : {};
+    const allow = Array.isArray(raw.permissions.allow) ? raw.permissions.allow : [];
+    if (!allow.includes(rule)) allow.push(rule);
+    raw.permissions.allow = allow;
+  }, home);
+}
+
+export function removeAllowRules({ server, home = homedir() }) {
+  updateUserConfig((raw) => {
+    if (isObj(raw.permissions) && Array.isArray(raw.permissions.allow)) {
+      raw.permissions.allow = raw.permissions.allow.filter(
+        (r) => !(r === `mcp__${server}` || String(r).startsWith(`mcp__${server}__`))
+      );
+    }
+  }, home);
+}
+
+/* ---------------------------------------------------------------- display -------------- */
+
+const SECRET_KEY_RE = /TOKEN|SECRET|PASSWORD|PASSWD|KEY|AUTH|CREDENTIAL/i;
+
+/** Env for display: values of secret-looking names become "****" + last 2. */
+export function maskEnv(env = {}) {
+  return Object.fromEntries(
+    Object.entries(env).map(([k, v]) => [k, SECRET_KEY_RE.test(k) ? (String(v).length > 6 ? `****${String(v).slice(-2)}` : "****") : v])
+  );
+}
+
+/** One line naming the command, with secret env values masked. */
+export function describeServer(s) {
+  const env = Object.entries(maskEnv(s.env ?? {})).map(([k, v]) => `${k}=${v}`);
+  return [...env, s.command, ...(s.args ?? [])].map((w) => (/\s/.test(w) ? JSON.stringify(w) : w)).join(" ");
+}
+
+/* ---------------------------------------------------------------- `add` arguments ------ */
+
+export const ADD_USAGE =
+  "gu mcp add [--scope user|project] [-e KEY=value …] <name> -- <command> [args…]";
+
+/**
+ * `claude mcp add`'s shape: options, then the name, then `--`, then the command. Without a `--`
+ * the first word after the name starts the command (a common way people type it).
+ * → { name, command, args, env, scope } | { error }
+ */
+export function parseAddArgs(words) {
+  const w = (words ?? []).map(String);
+  const dash = w.indexOf("--");
+  const head = dash >= 0 ? w.slice(0, dash) : w;
+  let tail = dash >= 0 ? w.slice(dash + 1) : [];
+  const env = {};
+  let scope = "user";
+  let name = null;
+  for (let i = 0; i < head.length; i++) {
+    const a = head[i];
+    if (a === "-e" || a === "--env") {
+      const kv = head[++i] ?? "";
+      const eq = kv.indexOf("=");
+      if (eq <= 0) return { error: `-e needs KEY=value, got "${kv}" — ${ADD_USAGE}` };
+      env[kv.slice(0, eq)] = kv.slice(eq + 1);
+    } else if (a === "-s" || a === "--scope") {
+      scope = head[++i] ?? "";
+      if (scope === "local") scope = "user"; // Claude Code's default scope; gu's user file is the same idea
+      if (!["user", "project"].includes(scope)) return { error: `--scope must be user or project — ${ADD_USAGE}` };
+    } else if (a === "-t" || a === "--transport") {
+      const t = head[++i] ?? "";
+      if (t !== "stdio") return { error: `transport "${t}" is not supported yet — only stdio` };
+    } else if (a.startsWith("-")) {
+      return { error: `unknown option ${a} — ${ADD_USAGE}` };
+    } else if (name === null) {
+      name = a;
+    } else if (dash < 0) {
+      tail = head.slice(i);
+      break;
+    } else {
+      return { error: `unexpected "${a}" before -- — ${ADD_USAGE}` };
+    }
+  }
+  if (!name) return { error: `no name — ${ADD_USAGE}` };
+  if (!SERVER_NAME_RE.test(name)) return { error: `"${name}" is not a valid name — use letters, digits, _ or -` };
+  if (!tail.length) return { error: `no command — ${ADD_USAGE}` };
+  return { name, command: tail[0], args: tail.slice(1), env, scope };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.739",
+  "version": "1.0.741",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -89,8 +89,16 @@
     "add-server.mjs",
     "powershell-alias.mjs",
     "install-path.mjs",
+    "skills.mjs",
+    "mcp-config.mjs",
+    "mcp-command.mjs",
+    "hooks-config.mjs",
+    "hooks-command.mjs",
     "gonext_probe_agent.py",
     "gonext_agent_chat.py",
+    "gu_mcp.py",
+    "gu_skills.py",
+    "gu_hooks.py",
     "prompt_scaffold_check.py",
     "gonext_transcribe.py",
     "gonext_mlx_embed.py",

package/skills.mjs

@@ -0,0 +1,175 @@
+/**
+ * SKILLS — folders with a SKILL.md, the way Claude Code does them (task #269).
+ *
+ *   ~/.gonext/skills/<name>/SKILL.md        yours, every folder
+ *   <project>/.gonext/skills/<name>/SKILL.md this project only
+ *
+ * A SKILL.md is YAML frontmatter (name, description) and a body of instructions. Only the name and
+ * description go into every prompt; the body is read when the agent calls use_skill(name) or the
+ * user types /<name> — never pasted into every turn. Same split as Claude Code, and for the same
+ * reason: a dozen skills must not cost a dozen bodies on every step.
+ *
+ * READ FROM DISK EVERY TIME, NOTHING CACHED. The user edits these files, renames them and deletes
+ * them while gu is running, and each of those has to take effect on the next scan with no restart,
+ * no reinstall and no code change. Nothing in gu names a skill or knows what one says.
+ *
+ * A REMOVED SKILL IS NOT AN ERROR. A folder with no SKILL.md in it, a skills folder that does not
+ * exist, no skills at all: every one of those is "the user has no such skill", which is a normal
+ * state and says nothing. Only a file that EXISTS and cannot be used (no frontmatter, no
+ * description, a bad name) earns a warning — that one is a mistake the user would want to hear about.
+ *
+ * WHEN BOTH HAVE ONE: yours wins over the project's, which is Claude Code's order (personal over
+ * project) — a repository you cloned should not be able to replace a skill you wrote.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const SKILL_FILE = "SKILL.md";
+/** Claude Code's rule: lowercase letters, digits and hyphens, at most 64. It is also a slash command. */
+export const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export function userSkillsDir(home = homedir()) {
+  return join(home, ".gonext", "skills");
+}
+export function projectSkillsDir(cwd) {
+  return join(cwd, ".gonext", "skills");
+}
+
+/** Strip one pair of matching quotes. */
+function unquote(v) {
+  const s = v.trim();
+  if (s.length >= 2 && ((s[0] === '"' && s.at(-1) === '"') || (s[0] === "'" && s.at(-1) === "'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/**
+ * The frontmatter a SKILL.md actually uses: `key: value` lines, quoted or not, plus the block
+ * scalars `key: >` / `key: |` for a long description. Not a YAML parser — nothing here needs one,
+ * and a dependency for two fields is a dependency to install on every machine. Unknown keys are
+ * kept and ignored, so a file written for Claude Code (allowed-tools, model, …) loads unchanged.
+ *
+ * → { data, body } | { error }
+ */
+export function parseFrontmatter(text) {
+  const src = String(text ?? "").replace(/^/, "").replace(/\r\n/g, "\n");
+  if (!src.startsWith("---\n")) return { error: "no frontmatter (the file must start with a --- line)" };
+  const end = src.indexOf("\n---", 4);
+  if (end < 0) return { error: "the frontmatter is never closed (no second --- line)" };
+  const lines = src.slice(4, end).split("\n");
+  const after = src.slice(end + 4);
+  const body = after.replace(/^[^\n]*\n?/, ""); // the rest of the closing --- line
+  const data = {};
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^([A-Za-z0-9_-]+):\s?(.*)$/.exec(lines[i]);
+    if (!m) continue; // a comment, a blank, or a nested line of a key we do not read
+    const [, key, rest] = m;
+    const v = rest.trim();
+    if (v === ">" || v === "|" || v === ">-" || v === "|-") {
+      const block = [];
+      while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || lines[i + 1].trim() === "")) {
+        block.push(lines[++i].trim());
+      }
+      data[key] = v.startsWith(">") ? block.filter(Boolean).join(" ") : block.join("\n").trim();
+    } else {
+      data[key] = unquote(v);
+    }
+  }
+  return { data, body };
+}
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** One skills folder → { skills, warnings }. A folder that is not there is simply empty. */
+function scanDir(dir, scope) {
+  const skills = [];
+  const warnings = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return { skills, warnings }; // no skills folder: no skills, nothing to say
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue; // .DS_Store and friends
+    const folder = join(dir, e.name);
+    if (!(e.isDirectory() || (e.isSymbolicLink() && isDir(folder)))) continue;
+    const file = join(folder, SKILL_FILE);
+    let text;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch {
+      continue; // SKILL.md removed (or never written): the skill does not exist — silently
+    }
+    const parsed = parseFrontmatter(text);
+    const where = `${scope} skill "${e.name}"`;
+    if (parsed.error) {
+      warnings.push(`${where}: ${parsed.error} — skipped`);
+      continue;
+    }
+    // Claude Code: `name` is optional and defaults to the folder's name.
+    const name = (parsed.data.name || e.name).trim();
+    const description = (parsed.data.description || "").trim();
+    if (!SKILL_NAME_RE.test(name)) {
+      warnings.push(`${where}: name "${name}" must be lowercase letters, digits and hyphens (max 64) — skipped`);
+      continue;
+    }
+    if (!description) {
+      // Without one the agent has nothing to decide by: the skill could only ever be typed.
+      warnings.push(`${where}: no description in the frontmatter — skipped`);
+      continue;
+    }
+    skills.push({ name, description, path: file, dir: folder, scope });
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  return { skills, warnings };
+}
+
+/**
+ * Every skill that exists right now. `reserved` = names that are already commands (/help, /mcp…):
+ * the built-in wins, and the skill is still usable by the agent, just not as a slash command —
+ * that is `slash: false`.
+ *
+ * → { skills: [{ name, description, path, dir, scope, slash }], warnings: string[] }
+ */
+export function discoverSkills({ cwd = process.cwd(), home = homedir(), reserved = [] } = {}) {
+  const user = scanDir(userSkillsDir(home), "user");
+  const project =
+    cwd && projectSkillsDir(cwd) !== userSkillsDir(home)
+      ? scanDir(projectSkillsDir(cwd), "project")
+      : { skills: [], warnings: [] };
+  const byName = new Map();
+  for (const s of user.skills) byName.set(s.name, s);
+  for (const s of project.skills) if (!byName.has(s.name)) byName.set(s.name, s);
+  const taken = new Set(reserved.map((r) => r.replace(/^\//, "")));
+  const skills = [...byName.values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((s) => ({ ...s, slash: !taken.has(s.name) }));
+  return { skills, warnings: [...user.warnings, ...project.warnings] };
+}
+
+/** What the worker hands the agent for one turn: enough to list them and to read one. */
+export function skillsForTurn(opts) {
+  return discoverSkills(opts).skills.map(({ name, description, path, dir }) => ({
+    name,
+    description,
+    path,
+    dir,
+  }));
+}
+
+/** "/name rest" → { name, args } when `name` is one of `skills` usable as a slash command, else null. */
+export function matchSkillCommand(line, skills) {
+  const m = /^\/([a-z0-9][a-z0-9-]*)(?:\s+([\s\S]*))?$/.exec(String(line ?? "").trim());
+  if (!m) return null;
+  const skill = skills.find((s) => s.name === m[1] && s.slash !== false);
+  return skill ? { name: skill.name, args: (m[2] ?? "").trim() } : null;
+}

package/terminal-layout.mjs

@@ -2653,3 +2653,51 @@ export function shouldCancelPrompt(awaiting, key) {
   if (key.ctrl) return false;
   return key.sequence === "\u001b";
 }
+
+/**
+ * THE SLASH MENU SHOWS A FEW, AND NARROWS AS YOU TYPE (task #271), the way Claude Code's does.
+ *
+ * A bare "/" used to print every command at once: sixteen built-ins plus every skill, most of them
+ * settings nobody touches twice, so the one you wanted was somewhere in a wall of text. Now the
+ * menu is a short window (SLASH_MENU_ROWS) over the ranked matches, ↑/↓ scroll it, and each typed
+ * character narrows it. /help still prints everything.
+ *
+ * MATCHING, best first, so the command whose name you are typing is always on top:
+ *   0  the name starts with it            /mo     → /model
+ *   1  a word of the name starts with it  /model  → then /agent-model, /embed-model
+ *   2  the name contains it               /del    → /model …
+ *   3  the description contains it        /coding → /model ("switch the CODING model"); 3+ chars
+ * Only the first word counts: "/proxy set" is /proxy with an argument. No match → [] (the menu
+ * says so), never "everything", which is what it used to fall back to.
+ */
+export const SLASH_MENU_ROWS = 6;
+
+export function rankSlashCommands(cmds, typed) {
+  const list = cmds ?? [];
+  const word = String(typed ?? "").trim().split(/\s+/)[0].toLowerCase().replace(/^\//, "");
+  if (!word) return list.slice();
+  const scored = [];
+  list.forEach((c, i) => {
+    const names = [c.name, ...(c.aliases ?? [])].map((n) => String(n).toLowerCase().replace(/^\//, ""));
+    let score = -1;
+    if (names.some((n) => n.startsWith(word))) score = 0;
+    else if (names.some((n) => n.split(/[-_]/).some((part) => part.startsWith(word)))) score = 1;
+    else if (names.some((n) => n.includes(word))) score = 2;
+    else if (word.length >= 3 && String(c.desc ?? "").toLowerCase().includes(word)) score = 3;
+    if (score >= 0) scored.push({ c, score, i });
+  });
+  scored.sort((a, b) => a.score - b.score || a.i - b.i);
+  return scored.map((s) => s.c);
+}
+
+/**
+ * Which slice of the ranked list is on screen. `sel` -1 = nothing highlighted (window at the top).
+ * → { from, to, above, below, top } — above/below are how many are hidden on each side.
+ */
+export function slashMenuWindow(total, sel, top, rows = SLASH_MENU_ROWS) {
+  const n = Math.max(0, total);
+  if (n <= rows) return { from: 0, to: n, above: 0, below: 0, top: 0 };
+  // listWindow spends two of its rows on the indicators; give it room for exactly `rows` items.
+  const w = listWindow(n, sel < 0 ? 0 : sel, sel < 0 ? 0 : top, rows + 2);
+  return { from: w.from, to: w.to, above: w.above, below: w.below, top: w.top };
+}