cli-surf 0.11.0

package/cliSkills.js

@@ -0,0 +1,264 @@
+/**
+ * Agent Skills для surf — как в Claude Code / Codex, совместимый формат.
+ *
+ * Скилл = папка с SKILL.md (frontmatter name/description + инструкции),
+ * опционально скрипты и ресурсы рядом. Уровни (поздний побеждает):
+ *   1. builtin  — рядом с cli.js (идут в npm-пакете)
+ *   2. user     — ~/.surf-cli/skills/<name>/
+ *   3. project  — <cwd>/.surf/skills/<name>/
+ *
+ * Модель видит каталог (имя + описание) в системном промпте и подгружает
+ * нужный скилл инструментом skill (progressive disclosure).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function userSkillsDir() {
+    return path.join(os.homedir(), '.surf-cli', 'skills');
+}
+const SKILLS_README = `# Свои навыки (skills)
+
+Каждая подпапка здесь — один навык. Внутри обязателен файл SKILL.md:
+
+---
+name: мой-навык
+description: Что он делает и когда нужен. Модель читает это и сама решает когда вызвать.
+---
+
+Инструкции для модели: что делать пошагово, какие команды гнать,
+какой формат ответа. Рядом можно класть скрипты — агент запустит их через bash.
+
+Правила: имя — латиница/цифры/дефисы; описание не пустое, до 500 символов;
+инструкции не пустые. Проверь командой /skills в surf.
+`;
+/** Создать папку пользовательских скиллов и шпаргалку, если их нет. */
+export function ensureUserSkillsDir() {
+    try {
+        fs.mkdirSync(userSkillsDir(), { recursive: true });
+        const readme = path.join(userSkillsDir(), 'README.md');
+        if (!fs.existsSync(readme))
+            fs.writeFileSync(readme, SKILLS_README);
+    }
+    catch { /* необязательно */ }
+}
+export function projectSkillsDir(cwd) {
+    return path.join(path.resolve(cwd), '.surf', 'skills');
+}
+/** Папка встроенных скиллов: работает и из src/, и из dist/, и из npm-пакета. */
+export function builtinSkillsDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    for (const candidate of [path.join(here, '..', 'skills'), path.join(here, 'skills')]) {
+        try {
+            if (fs.statSync(candidate).isDirectory())
+                return candidate;
+        }
+        catch { /* нет */ }
+    }
+    return null;
+}
+function skillRoots(cwd) {
+    const roots = [];
+    const builtin = builtinSkillsDir();
+    if (builtin)
+        roots.push({ dir: builtin, source: 'builtin' });
+    roots.push({ dir: userSkillsDir(), source: 'user' });
+    roots.push({ dir: projectSkillsDir(cwd), source: 'project' });
+    return roots;
+}
+function listSubdirs(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true })
+            .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+            .map(e => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+function parseFrontmatter(input) {
+    // BOM и CRLF (Windows-редакторы, PowerShell) — нормализуем.
+    const text = input.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+    if (!text.startsWith('---'))
+        return null;
+    const end = text.indexOf('\n---', 3);
+    if (end < 0)
+        return null;
+    const fmLines = text.slice(3, end).split('\n');
+    const body = text.slice(end + 4).replace(/^\r?\n/, '');
+    const data = {};
+    let i = 0;
+    while (i < fmLines.length) {
+        const line = fmLines[i];
+        const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!m) {
+            i += 1;
+            continue;
+        }
+        const key = m[1].toLowerCase();
+        const value = (m[2] ?? '').trim();
+        if (value === '|' || value === '>') {
+            // literal / folded блок
+            const folded = value === '>';
+            const collected = [];
+            i += 1;
+            while (i < fmLines.length && /^(?: {2}|\t)/.test(fmLines[i])) {
+                collected.push(fmLines[i].replace(/^(?: {2}|\t)/, ''));
+                i += 1;
+            }
+            data[key] = folded ? collected.join(' ') : collected.join('\n');
+            continue;
+        }
+        if (value === '') {
+            // возможно список "- item"
+            const collected = [];
+            let j = i + 1;
+            while (j < fmLines.length) {
+                const item = fmLines[j].match(/^\s*-\s+(.*)$/);
+                if (!item)
+                    break;
+                collected.push(item[1].trim());
+                j += 1;
+            }
+            if (collected.length > 0) {
+                data[key] = collected;
+                i = j;
+                continue;
+            }
+            data[key] = '';
+            i += 1;
+            continue;
+        }
+        if (value.startsWith('[') && value.endsWith(']')) {
+            data[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+            i += 1;
+            continue;
+        }
+        data[key] = value.replace(/^["']|["']$/g, '');
+        i += 1;
+    }
+    return { data, body };
+}
+function firstString(value) {
+    if (Array.isArray(value))
+        return value.join(' ').trim();
+    return (value ?? '').trim();
+}
+function validSkillName(name) {
+    return /^[a-z0-9][a-z0-9-]{0,63}$/.test(name);
+}
+/** Прочитать и провалидировать один скилл. null = битый, пропускаем. */
+export function readSkillFile(skillDir, source) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const fm = parseFrontmatter(text);
+    if (!fm)
+        return null;
+    const dirName = path.basename(skillDir);
+    const rawName = firstString(fm.data.name) || dirName.toLowerCase();
+    const name = rawName.toLowerCase();
+    const description = firstString(fm.data.description);
+    if (!validSkillName(name))
+        return null;
+    if (!description || description.length > 500)
+        return null;
+    const instructions = fm.body.trim();
+    if (!instructions)
+        return null;
+    const files = [];
+    const walk = (dir, rel) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            const relPath = rel ? `${rel}/${e.name}` : e.name;
+            if (relPath === 'SKILL.md')
+                continue;
+            if (e.isDirectory())
+                walk(path.join(dir, e.name), relPath);
+            else if (e.isFile())
+                files.push(relPath);
+        }
+    };
+    walk(skillDir, '');
+    const versionRaw = firstString(fm.data.version);
+    return {
+        meta: { name, description, version: versionRaw || null, source, dir: skillDir },
+        instructions,
+        files: files.slice(0, 50),
+    };
+}
+/** Все валидные скиллы (project перекрывает user, user — builtin). */
+export function discoverSkills(cwd) {
+    const byName = new Map();
+    let invalid = 0;
+    for (const { dir, source } of skillRoots(cwd)) {
+        for (const name of listSubdirs(dir)) {
+            const parsed = readSkillFile(path.join(dir, name), source);
+            if (!parsed) {
+                try {
+                    fs.statSync(path.join(dir, name, 'SKILL.md'));
+                    invalid += 1;
+                }
+                catch { /* нет SKILL.md — не скилл */ }
+                continue;
+            }
+            byName.set(parsed.meta.name, parsed.meta);
+        }
+    }
+    return { skills: [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)), invalid };
+}
+/** Только имена (дешёвый вариант для автодополнения, без парсинга). */
+export function listSkillNames(cwd) {
+    const names = new Set();
+    for (const { dir } of skillRoots(cwd)) {
+        for (const name of listSubdirs(dir)) {
+            if (validSkillName(name.toLowerCase()))
+                names.add(name.toLowerCase());
+        }
+    }
+    return [...names].sort();
+}
+/** Полный текст скилла для инструмента skill. */
+export function loadSkill(cwd, name) {
+    const normalized = name.trim().toLowerCase();
+    if (!validSkillName(normalized))
+        return null;
+    for (const { dir, source } of [...skillRoots(cwd)].reverse()) {
+        const direct = path.join(dir, normalized);
+        try {
+            if (fs.statSync(direct).isDirectory()) {
+                const parsed = readSkillFile(direct, source);
+                if (parsed)
+                    return parsed;
+            }
+        }
+        catch { /* дальше */ }
+        // имя в SKILL.md может отличаться от имени папки — ищем перебором
+        for (const sub of listSubdirs(dir)) {
+            const parsed = readSkillFile(path.join(dir, sub), source);
+            if (parsed && parsed.meta.name === normalized)
+                return parsed;
+        }
+    }
+    return null;
+}
+/** Компактный каталог для системного промпта. */
+export function skillsCatalog(cwd) {
+    const { skills } = discoverSkills(cwd);
+    if (skills.length === 0)
+        return '';
+    return skills.map(s => `- ${s.name}: ${s.description}`).join('\n');
+}
+//# sourceMappingURL=cliSkills.js.map