@tiens.nguyen/gu-cli 1.0.738 → 1.0.740

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;
+}