teapot-coding-agent 0.22.13 → 0.24.0

package/dist/agent/skills.js

@@ -19,56 +19,227 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 export const SKILL_FILE = "SKILL.md";
+/**
+ * Cheap change-detector for a set of skill roots. Returns a stable string
+ * that changes whenever a root is added, removed, or modified — so callers
+ * can skip a full rescan (a readdir per root plus a read of every SKILL.md)
+ * on the overwhelmingly common "nothing changed" path.
+ *
+ * The fingerprint covers each root's own mtime/size AND the mtime/size of
+ * every SKILL.md one level down, because writing SKILL.md does not bump the
+ * parent directory's mtime. Helper scripts edited in place are covered by
+ * the SKILL.md stat only in aggregate; a rewritten SKILL.md always lands
+ * here too (saveSkill rewrites it), so bundled-file edits ride along with
+ * the next skill write rather than triggering their own rescan.
+ */
+export async function skillRootsFingerprint(roots) {
+    const parts = [];
+    for (const root of roots) {
+        parts.push(root.dir);
+        let st = null;
+        try {
+            st = await fs.stat(root.dir);
+        }
+        catch {
+            parts.push("-"); // root missing → no skills here (same as discoverSkills)
+            continue;
+        }
+        parts.push(`${st.mtimeMs}:${st.size}`);
+        let entries;
+        try {
+            entries = await fs.readdir(root.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith("."))
+                continue;
+            try {
+                const s = await fs.stat(path.join(root.dir, e.name, SKILL_FILE));
+                parts.push(`${e.name}=${s.mtimeMs}:${s.size}`);
+            }
+            catch {
+                parts.push(`${e.name}=none`);
+            }
+        }
+    }
+    return parts.join("|");
+}
 export function isValidSkillName(name) {
     return /^[a-z0-9][a-z0-9._-]{0,63}$/.test(name);
 }
 /**
  * Minimal frontmatter parser for the subset we need: a leading `---` block of
  * `key: value` lines. No YAML dependency by design.
+ *
+ * It does understand the two YAML shapes that are common in REAL third-party
+ * skills (#28), because without them those files are unreadable:
+ *  - FOLDED/LITERAL BLOCK SCALARS (`description: >-` … or `|` …), which is how
+ *    most skill authors write a long description. Reading them naively yields
+ *    the literal ">-" as the description, which silently destroys the one field
+ *    the model matches its task against.
+ *  - QUOTED values, whose surrounding quotes are stripped so a description
+ *    containing a colon survives.
+ * A key whose value is empty (e.g. a nested `metadata:` block) is left out rather
+ * than recorded as an empty string.
  */
 export function parseSkillMd(text) {
     const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
     if (!m)
         return { meta: {}, body: text.trim() };
+    const lines = m[1].split(/\r?\n/);
     const meta = {};
-    for (const line of m[1].split(/\r?\n/)) {
-        const kv = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
-        if (kv)
-            meta[kv[1].toLowerCase()] = kv[2].trim();
+    for (let i = 0; i < lines.length; i++) {
+        const kv = lines[i].match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+        if (!kv)
+            continue;
+        const key = kv[1].toLowerCase();
+        const raw = kv[2].trim();
+        // folded (>-, >, |-, |) or literal (|, |-) block scalar: the value is the
+        // following, more-indented lines
+        if (/^[>|][-+]?$/.test(raw)) {
+            const parts = [];
+            let j = i + 1;
+            for (; j < lines.length; j++) {
+                const l = lines[j];
+                if (l.trim() === "") {
+                    parts.push("");
+                    continue;
+                }
+                if (!/^\s/.test(l))
+                    break; // dedented → block ended
+                parts.push(l.trim());
+            }
+            i = j - 1;
+            const joined = parts.join(/^[>|][-+]?$/.test(raw) && raw.startsWith("|") ? "\n" : " ").trim();
+            if (joined)
+                meta[key] = joined;
+            continue;
+        }
+        if (raw === "")
+            continue; // `metadata:` with a nested block below
+        meta[key] = unquote(raw);
     }
     return { meta, body: m[2].trim() };
 }
+/** Strip one layer of matching quotes; a quoted value may itself contain `:`. */
+function unquote(v) {
+    const s = v.trim();
+    if (s.length >= 2 && ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")))) {
+        return s
+            .slice(1, -1)
+            .replace(/\\"/g, '"')
+            .replace(/''/g, "'");
+    }
+    return s;
+}
+/** Root dirs in priority order: [0] overrides later ones on name clash. */
+/**
+ * Skill directories owned by OTHER coding harnesses (#28).
+ *
+ * SKILL.md is a shared convention, so these are readable as-is — the only
+ * thing that ever blocked them was our frontmatter parser (folded scalars and
+ * quoted values), now handled. Paths are the documented native locations,
+ * plus the cross-tool directories several tools also read.
+ *
+ * Priority is deliberately the LOWEST of the user-supplied roots: a project
+ * should never be shadowed by another tool's copy of the same skill. Missing
+ * directories are skipped silently, and nothing is read unless it exists.
+ */
+export function foreignSkillRoots(workspace) {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const out = [];
+    const add = (dir) => {
+        if (dir && !out.some((r) => r.dir === dir))
+            out.push({ dir, source: "foreign" });
+    };
+    if (workspace) {
+        // project-local locations other tools read
+        for (const rel of [
+            path.join(".agents", "skills"), // cross-tool convention
+            path.join(".claude", "skills"),
+            path.join(".codex", "skills"),
+            path.join(".cursor", "skills"),
+            path.join(".gemini", "skills"),
+            path.join(".github", "skills"), // Copilot CLI + VS Code
+            path.join(".opencode", "skills"),
+        ]) {
+            add(path.join(workspace, rel));
+        }
+    }
+    if (home) {
+        add(path.join(home, ".agents", "skills")); // cross-tool, personal
+        for (const rel of [
+            [".claude", "skills"],
+            [".codex", "skills"],
+            [".cursor", "skills"],
+            [".gemini", "skills"],
+            [".copilot", "skills"], // GitHub Copilot CLI + VS Code share this
+            [".config", "opencode", "skills"],
+        ]) {
+            add(path.join(home, ...rel));
+        }
+    }
+    return out;
+}
+/**
+ * How deep to look for nested skills (#27).
+ *
+ * Bounded because a skill directory also holds BUNDLED FILES (helper scripts)
+ * and arbitrary payload, so an unbounded walk is not safe. Depth is not the
+ * thing that makes a directory a skill, though — holding a SKILL.md is — so the
+ * bound only limits how far we look, never what counts.
+ */
+const MAX_SKILL_DEPTH = 4;
 /** Root dirs in priority order: [0] overrides later ones on name clash. */
 export async function discoverSkills(roots) {
     const byName = new Map();
+    // name -> depth, so a SHALLOWER skill wins over a nested namesake rather than
+    // a deep one silently shadowing the obvious skill (#27)
+    const depthByName = new Map();
     for (const root of roots) {
-        let entries;
-        try {
-            entries = await fs.readdir(root.dir, { withFileTypes: true });
-        }
-        catch {
-            continue; // root missing → simply no skills there
-        }
-        for (const e of entries) {
-            if (!e.isDirectory() || e.name.startsWith("."))
-                continue;
-            const filePath = path.join(root.dir, e.name, SKILL_FILE);
-            let text;
-            try {
-                text = await fs.readFile(filePath, "utf8");
-            }
-            catch {
-                continue; // directory without SKILL.md is not a skill
-            }
-            const parsed = parseSkillMd(text);
-            const name = parsed.meta.name || e.name;
-            if (byName.has(name))
-                continue; // higher-priority root already defined it
-            // collect bundled files (helper scripts, templates, ...) next to SKILL.md
+        await walkSkills(root.dir, root.source, 0, byName, depthByName);
+    }
+    return [...byName.values()];
+}
+/**
+ * Depth-first walk collecting every directory that holds a SKILL.md (#27).
+ *
+ * A directory WITHOUT its own SKILL.md is only a container to descend into — we
+ * never treat one as a skill, which is what keeps bundled helper directories
+ * from being reported as skills themselves.
+ */
+async function walkSkills(dir, source, depth, byName, depthByName) {
+    if (depth > MAX_SKILL_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // root missing → simply no skills there
+    }
+    // a SKILL.md sitting directly in `dir` makes `dir` a skill AND a container
+    const here = path.join(dir, SKILL_FILE);
+    let hereText = null;
+    try {
+        hereText = await fs.readFile(here, "utf8");
+    }
+    catch {
+        hereText = null;
+    }
+    if (hereText !== null && depth > 0) {
+        const parsed = parseSkillMd(hereText);
+        const name = parsed.meta.name || path.basename(dir);
+        const prevDepth = depthByName.get(name);
+        // first root wins on a name clash, and a shallower skill beats a deeper one
+        const wins = prevDepth === undefined ||
+            (prevDepth !== undefined && depth < prevDepth && byName.get(name)?.source === source);
+        if (wins) {
             let files = [];
             try {
-                const siblings = await fs.readdir(path.join(root.dir, e.name), { withFileTypes: true });
-                files = siblings
+                files = (await fs.readdir(dir, { withFileTypes: true }))
                     .filter((f) => f.isFile() && f.name !== SKILL_FILE && !f.name.startsWith("."))
                     .map((f) => f.name)
                     .sort();
@@ -79,13 +250,22 @@ export async function discoverSkills(roots) {
             byName.set(name, {
                 name,
                 description: parsed.meta.description || "",
-                source: root.source,
-                filePath,
+                source,
+                filePath: here,
                 files,
             });
+            depthByName.set(name, depth);
         }
     }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith("."))
+            continue;
+        // Recurse into every subdirectory: nesting means a skill can sit at ANY depth
+        // (skills/stage1/template/SKILL.md), and "stage1" itself has no SKILL.md.
+        // Bundled helper payloads are not mistaken for skills because a directory
+        // only BECOMES a skill when it holds its own SKILL.md (#27).
+        await walkSkills(path.join(dir, e.name), source, depth + 1, byName, depthByName);
+    }
 }
 export async function readSkillFile(def) {
     return fs.readFile(def.filePath, "utf8");