vskill 0.5.106 → 0.5.108

package/dist/eval-server/api-routes.js

@@ -286,58 +286,242 @@ const EMPTY_METADATA = {
     sizeBytes: null,
     sourceAgent: null,
 };
+/**
+ * Allow-list of metadata children that may be surfaced at the top level
+ * during the metadata-nesting migration. Surfacing is intentional for these
+ * keys (existing consumers read them as `fm.<key>`); other metadata children
+ * stay nested under `fm.metadata.<key>` only, so they cannot accidentally
+ * shadow future top-level fields. (0679 review F-004.)
+ *
+ * Includes every key that `buildSkillMetadata` (below) reads at the root, so
+ * that if a future hand-edit moves them under `metadata:` per the spec, the
+ * /api/skills payload still recovers them.
+ */
+const SURFACED_METADATA_KEYS = new Set([
+    // Spec-required keys (agentskills.io/specification — `metadata:` block)
+    "tags",
+    "target-agents",
+    "version",
+    "homepage",
+    "category",
+    "author",
+    "license",
+    // Dependency keys read by buildSkillMetadata. Both kebab-case (canonical)
+    // and camelCase (legacy SKILL.md) are surfaced so the migration is total.
+    "skill-deps",
+    "skillDeps",
+    "deps",
+    "mcp-deps",
+    "mcpDeps",
+    "mcpDependencies",
+    // Path / file metadata
+    "entryPoint",
+    "entry-point",
+]);
 /**
  * Minimal YAML frontmatter parser — handles scalars and arrays (inline [a, b]
- * or YAML list form). We intentionally avoid pulling gray-matter into the
+ * or YAML list form), folded scalars (`key: >` + indented continuation), and
+ * the `metadata:` block. We intentionally avoid pulling gray-matter into the
  * eval-server bundle; SKILL.md frontmatter is a well-bounded subset.
+ *
+ * 0679: also recognizes the canonical agentskills.io shape where `tags` and
+ * `target-agents` are nested under a `metadata:` block. Allow-listed children
+ * of `metadata:` (see SURFACED_METADATA_KEYS) are surfaced both as top-level
+ * keys (`fm.tags`) AND under `metadata.<key>` (e.g., `fm.metadata.tags`), so
+ * existing consumers that read `fm.tags` keep working without changes. Other
+ * metadata children stay nested-only. If a SKILL.md somehow has BOTH a
+ * top-level `tags:` AND a `metadata.tags:` (hand-edited transitional file),
+ * the top-level value wins — explicit beats nested.
  */
 export function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match)
         return {};
     const lines = match[1].split("\n");
-    const out = {};
+    const rootOut = {};
+    const metaOut = {};
+    let scope = "root";
     let currentKey = null;
     let currentList = null;
+    let currentScope = "root";
+    // Folded-scalar (`key: >`) / literal-scalar (`key: |`) accumulator.
+    // While active, indented continuation lines are joined into a single value.
+    let foldedKey = null;
+    let foldedScope = null;
+    let foldedLines = [];
+    let foldedKind = null;
     const stripQuotes = (s) => s.trim().replace(/^["']|["']$/g, "");
+    const flushList = () => {
+        if (currentKey && currentList) {
+            const target = currentScope === "metadata" ? metaOut : rootOut;
+            target[currentKey] = currentList;
+        }
+        currentKey = null;
+        currentList = null;
+        // 0679 review F-005: keep currentScope coherent with the cleared list.
+        currentScope = scope;
+    };
+    const flushFolded = () => {
+        if (!foldedKey)
+            return;
+        // Folded (`>`): join with single spaces, collapsing blank lines to "\n".
+        // Literal (`|`): preserve newlines.
+        const joined = foldedKind === "|"
+            ? foldedLines.join("\n").trim()
+            : foldedLines.map((l) => l.trim()).filter(Boolean).join(" ").trim();
+        const target = foldedScope === "metadata" ? metaOut : rootOut;
+        target[foldedKey] = joined;
+        foldedKey = null;
+        foldedScope = null;
+        foldedLines = [];
+        foldedKind = null;
+    };
     for (const line of lines) {
-        const listItem = line.match(/^\s+-\s+(.+)$/);
-        if (listItem && currentKey && currentList) {
-            currentList.push(stripQuotes(listItem[1]));
+        // While accumulating a folded/literal scalar, any indented continuation
+        // line belongs to the scalar; an empty line is a paragraph break.
+        if (foldedKey) {
+            if (line.trim() === "") {
+                foldedLines.push("");
+                continue;
+            }
+            if (/^ {2,}/.test(line)) {
+                foldedLines.push(line.replace(/^ +/, ""));
+                continue;
+            }
+            // Non-indented line — fold ends, fall through to normal processing.
+            flushFolded();
+        }
+        if (line.trim() === "")
+            continue;
+        // Metadata-nested list item (exactly 4 spaces indent): `    - value`
+        const nestedListItem = line.match(/^ {4}-\s+(.+)$/);
+        if (nestedListItem && currentKey && currentList && currentScope === "metadata") {
+            currentList.push(stripQuotes(nestedListItem[1]));
             continue;
         }
+        // Root-level list item — accept either `  - value` (2-space, YAML-conventional
+        // for top-level keys followed by indented list) or `- value` (0-space, also
+        // valid YAML). Reject 1-space and 3+ space (malformed) for symmetry with
+        // the strict 2-space metadata-child rule. (0679 review F-002 iter-1, regex
+        // readability cleanup iter-4 F-002: `(?:  )?-` is the conventional form.)
+        const rootListItem = line.match(/^(?:  )?-\s+(.+)$/);
+        if (rootListItem && currentKey && currentList && currentScope === "root") {
+            currentList.push(stripQuotes(rootListItem[1]));
+            continue;
+        }
+        // Metadata child key: `  key:` or `  key: value` (exactly 2-space indent)
+        const metaChild = line.match(/^ {2}([\w-]+):\s*(.*)$/);
+        if (scope === "metadata" && metaChild) {
+            flushList();
+            const key = metaChild[1];
+            const rawValue = metaChild[2].trim();
+            currentScope = "metadata";
+            currentKey = key;
+            if (!rawValue) {
+                currentList = [];
+                continue;
+            }
+            // Folded / literal scalar inside metadata.
+            if (rawValue === ">" || rawValue === "|") {
+                foldedKey = key;
+                foldedScope = "metadata";
+                foldedLines = [];
+                foldedKind = rawValue;
+                currentKey = null;
+                currentList = null;
+                continue;
+            }
+            const arrayMatch = rawValue.match(/^\[(.*)\]$/);
+            if (arrayMatch) {
+                metaOut[key] = arrayMatch[1].split(",").map(stripQuotes).filter(Boolean);
+                currentList = null;
+                currentKey = null;
+            }
+            else {
+                metaOut[key] = stripQuotes(rawValue);
+                currentList = null;
+                currentKey = null;
+            }
+            continue;
+        }
+        // Top-level key: `key:` or `key: value` (no leading whitespace)
         const kv = line.match(/^([\w-]+):\s*(.*)$/);
         if (!kv)
             continue;
-        // Flush pending list
-        if (currentKey && currentList) {
-            out[currentKey] = currentList;
-            currentList = null;
-        }
+        flushList();
         const key = kv[1];
         const rawValue = kv[2].trim();
+        if (key === "metadata") {
+            // 0679 review F-002 + iter-3 F-001: `metadata: <inline-scalar>` is a
+            // malformed file. We open the block (subsequent indented children land
+            // under `metadata`) AND preserve the inline value at a sentinel
+            // top-level key (`metadata-inline`) so callers can detect the mistake
+            // instead of silently losing data. The post-merge step (below) removes
+            // any chance of the block contents overwriting the inline value.
+            if (rawValue && rawValue !== ">" && rawValue !== "|") {
+                rootOut["metadata-inline"] = stripQuotes(rawValue);
+            }
+            // Entering the metadata block; subsequent indented children are nested.
+            scope = "metadata";
+            currentScope = "metadata";
+            currentKey = null;
+            currentList = null;
+            continue;
+        }
+        // Any unindented key resets scope back to root.
+        scope = "root";
+        currentScope = "root";
         currentKey = key;
         if (!rawValue) {
-            // Next lines may be a YAML list
             currentList = [];
             continue;
         }
+        // 0679 review F-001: folded (`>`) and literal (`|`) scalars at root.
+        if (rawValue === ">" || rawValue === "|") {
+            foldedKey = key;
+            foldedScope = "root";
+            foldedLines = [];
+            foldedKind = rawValue;
+            currentKey = null;
+            currentList = null;
+            continue;
+        }
         const arrayMatch = rawValue.match(/^\[(.*)\]$/);
         if (arrayMatch) {
-            out[key] = arrayMatch[1]
-                .split(",")
-                .map(stripQuotes)
-                .filter(Boolean);
+            rootOut[key] = arrayMatch[1].split(",").map(stripQuotes).filter(Boolean);
             currentList = null;
+            currentKey = null;
         }
         else {
-            out[key] = stripQuotes(rawValue);
+            // scope is "root" here — set just above. Top-level scalar.
+            rootOut[key] = stripQuotes(rawValue);
             currentList = null;
+            currentKey = null;
         }
     }
-    if (currentKey && currentList)
-        out[currentKey] = currentList;
-    return out;
+    flushList();
+    flushFolded();
+    // Surface allow-listed metadata children at the top level so existing
+    // consumers (`fm.tags`, `fm["target-agents"]`) keep working post-migration.
+    // A top-level value with the same name takes precedence over the nested
+    // one. Non-allow-listed children stay nested-only — see SURFACED_METADATA_KEYS.
+    // 0679 review iter-4 F-003 + grill G-002: defensive-copy arrays on BOTH
+    // sides (root surfacing and the nested `fm.metadata.<key>`) so neither
+    // path can accidentally mutate the other.
+    const merged = { ...rootOut };
+    for (const [k, v] of Object.entries(metaOut)) {
+        if (SURFACED_METADATA_KEYS.has(k) && !(k in merged)) {
+            merged[k] = Array.isArray(v) ? [...v] : v;
+        }
+    }
+    if (Object.keys(metaOut).length > 0) {
+        const metaCopy = {};
+        for (const [k, v] of Object.entries(metaOut)) {
+            metaCopy[k] = Array.isArray(v) ? [...v] : v;
+        }
+        merged.metadata = metaCopy;
+    }
+    return merged;
 }
 function toStringOrNull(v) {
     return typeof v === "string" && v.trim().length > 0 ? v.trim() : null;
@@ -455,6 +639,43 @@ export function buildSkillMetadata(skillDir, origin, root) {
 // (which only matters for the `vskill eval run` CLI command).
 // ---------------------------------------------------------------------------
 let currentOverrides = { provider: "claude-cli" };
+// 0682 F-001 — Tracks whether the persistent studio.json selection has been
+// loaded for this process lifetime. Initialized to false; set to true once
+// loadStudioSelection(root) has been attempted (regardless of whether a file
+// existed). Without this flag, the prior gate `if (!currentOverrides.provider)`
+// was permanently false (the default `{ provider: "claude-cli" }` already
+// populates `provider`), so the persisted selection at .vskill/studio.json
+// was silently discarded on every server boot — a CRITICAL regression of
+// AC-US1-03 / FR-005.
+let studioLoaded = false;
+/**
+ * 0682 F-001 — Test helper. Resets `currentOverrides` to the default and
+ * clears the `studioLoaded` flag so subsequent /api/config calls re-attempt
+ * loadStudioSelection. Production code never needs this; it exists solely so
+ * vitest can simulate a fresh server boot per-case.
+ */
+export function resetStudioRestoreState() {
+    currentOverrides = { provider: "claude-cli" };
+    studioLoaded = false;
+}
+// 0682 CR-001 — Known ProviderName values, used to validate the activeAgent
+// string read from .vskill/studio.json before assigning into currentOverrides.
+// studio-json.ts only checks `typeof activeAgent === "string"`; without this
+// gate a corrupt or version-mismatched file would flow an unknown provider
+// into getClient() / PROVIDER_MODELS and produce undefined-key lookups.
+const KNOWN_PROVIDER_NAMES = new Set([
+    "anthropic",
+    "claude-cli",
+    "codex-cli",
+    "gemini-cli",
+    "lm-studio",
+    "ollama",
+    "openai",
+    "openrouter",
+]);
+function isKnownProviderName(s) {
+    return KNOWN_PROVIDER_NAMES.has(s);
+}
 /** Return the effective raw model ID (suitable for round-tripping via the API). */
 function getEffectiveRawModel() {
     if (currentOverrides.model)
@@ -571,6 +792,20 @@ const PROBE_CACHE_TTL = 30_000; // re-probe every 30s
 let ollamaCache = null;
 let lmStudioCache = null;
 export const OPENROUTER_CACHE = new Map();
+// 0682 F-003 (review iter 2): cap the cache size so a long-running
+// multi-tenant server doesn't accumulate one ~30KB entry per distinct API
+// key seen since boot. 16 entries is plenty for any realistic deployment
+// (single-developer + occasional team-shared studio); FIFO eviction keeps
+// the cap simple — true LRU isn't worth the bookkeeping cost.
+const OPENROUTER_CACHE_MAX_ENTRIES = 16;
+export function evictOldestOpenRouterCacheIfFull() {
+    if (OPENROUTER_CACHE.size <= OPENROUTER_CACHE_MAX_ENTRIES)
+        return;
+    // Map iteration order is insertion order — first key is oldest.
+    const firstKey = OPENROUTER_CACHE.keys().next().value;
+    if (firstKey !== undefined)
+        OPENROUTER_CACHE.delete(firstKey);
+}
 export function resetOpenRouterCache() {
     OPENROUTER_CACHE.clear();
 }
@@ -590,10 +825,13 @@ async function probeOllama() {
         const baseUrl = resolveOllamaBaseUrl(process.env);
         const resp = await fetch(`${baseUrl}/api/tags`, { signal: AbortSignal.timeout(500) });
         if (resp.ok) {
-            available = true;
             const data = await resp.json();
+            // Only mark available after JSON parses cleanly — protects against 200-with-bad-body proxies.
+            available = true;
             if (data.models?.length) {
-                models = data.models.map((m) => ({ id: m.name, label: m.name }));
+                models = data.models
+                    .filter((m) => typeof m?.name === "string" && m.name.length > 0)
+                    .map((m) => ({ id: m.name, label: m.name }));
             }
         }
     }
@@ -618,10 +856,16 @@ async function probeLmStudio() {
         const baseUrl = process.env.LM_STUDIO_BASE_URL || "http://localhost:1234/v1";
         const resp = await fetch(`${baseUrl}/models`, { signal: AbortSignal.timeout(500) });
         if (resp.ok) {
-            available = true;
             const data = await resp.json();
+            // Only mark available after JSON parses cleanly — protects against 200-with-bad-body proxies.
+            available = true;
             if (data.data?.length) {
-                models = data.data.map((m) => ({ id: m.id, label: m.id }));
+                // Alphabetical sort honors AC-US3-01 (group children ordered alphabetically
+                // in the dropdown). LM Studio returns models in load-order, which is unstable.
+                models = data.data
+                    .filter((m) => typeof m?.id === "string" && m.id.length > 0)
+                    .map((m) => ({ id: m.id, label: m.id }))
+                    .sort((a, b) => a.id.localeCompare(b.id));
             }
         }
     }
@@ -859,6 +1103,9 @@ export function registerRoutes(router, root, projectName) {
                 },
             }));
             OPENROUTER_CACHE.set(cacheKey, { value: models, fetchedAt: now });
+            // 0682 F-003 (review iter 2): bound cache size to avoid unbounded
+            // growth on long-running shared servers.
+            evictOldestOpenRouterCacheIfFull();
             res.setHeader?.("X-Vskill-Catalog-Age", "0");
             sendJson(res, { models, ageSec: 0 });
         }
@@ -969,13 +1216,43 @@ export function registerRoutes(router, root, projectName) {
     // (e.g. "claude-sonnet"). The frontend round-trips config.model back to
     // generate-evals and other endpoints, so it must be a valid CLI model ID.
     router.get("/api/config", async (_req, res) => {
-        // On first load (no currentOverrides), try to restore from .vskill/studio.json.
-        if (!currentOverrides.provider) {
-            const stored = loadStudioSelection(root);
-            if (stored) {
-                currentOverrides.provider = stored.activeAgent;
-                if (stored.activeModel)
-                    currentOverrides.model = stored.activeModel;
+        // 0682 F-001 — Boot-time restoration of .vskill/studio.json selection.
+        // Use a dedicated `studioLoaded` flag rather than checking
+        // `!currentOverrides.provider` because the module default
+        // `{ provider: "claude-cli" }` would make the prior guard permanently
+        // false, silently discarding the persisted selection on every boot.
+        if (!studioLoaded) {
+            // 0682 CR-0682-M1 — Wrap loadStudioSelection() in its own try/catch
+            // and set `studioLoaded = true` ONLY after the load attempt completes.
+            // Pre-fix the flag was flipped before the call, so any thrown error
+            // (fs, permissions, malformed JSON path inside the loader) would
+            // permanently mask studio.json for the process lifetime — exactly the
+            // same class of bug as the F-001 it tried to remedy. Now: on success
+            // OR clean miss, mark loaded; on thrown error, log and leave the flag
+            // unset so the next request retries.
+            try {
+                const stored = loadStudioSelection(root);
+                if (stored) {
+                    // 0682 CR-001 — Validate the persisted activeAgent against the
+                    // ProviderName union before mutating currentOverrides. A tampered
+                    // or version-mismatched studio.json (e.g. "unknown", "claude-code",
+                    // or arbitrary text) silently falls back to the claude-cli default
+                    // rather than poisoning getClient() lookups downstream.
+                    if (isKnownProviderName(stored.activeAgent)) {
+                        currentOverrides.provider = stored.activeAgent;
+                        if (stored.activeModel)
+                            currentOverrides.model = stored.activeModel;
+                    }
+                    else {
+                        console.warn(`[studio.json] Ignoring unknown activeAgent "${stored.activeAgent}" — falling back to claude-cli`);
+                    }
+                }
+                studioLoaded = true;
+            }
+            catch (e) {
+                console.warn(`[studio.json] load failed: ${e.message} — will retry on next /api/config request`);
+                // Intentionally leave studioLoaded=false so transient FS errors don't
+                // permanently mask the persisted selection.
             }
         }
         try {
@@ -1009,6 +1286,21 @@ export function registerRoutes(router, root, projectName) {
     // Update config — change provider/model at runtime and persist atomically.
     router.post("/api/config", async (req, res) => {
         const body = (await readBody(req));
+        // 0682 F-001 (review iter 3): validate the incoming provider against the
+        // ProviderName union BEFORE mutating currentOverrides. Pre-fix, an
+        // unknown provider was eagerly applied and only caught downstream by
+        // `getClient()`, where a hard reset to claude-cli destroyed any prior
+        // valid in-memory selection. Now: reject early with 400 and leave the
+        // existing selection intact.
+        if (body.provider !== undefined && !isKnownProviderName(body.provider)) {
+            sendJson(res, { error: `unknown provider: ${String(body.provider)}` }, 400, req);
+            return;
+        }
+        // 0682 F-001 (review iter 3): snapshot the prior selection so we can
+        // restore it on validation failure, rather than zapping everything to
+        // the default. Spec semantics: a failed POST should leave the previous
+        // good state intact.
+        const priorOverrides = { ...currentOverrides };
         if (body.provider)
             currentOverrides.provider = body.provider;
         if (body.model)
@@ -1038,9 +1330,10 @@ export function registerRoutes(router, root, projectName) {
             sendJson(res, { provider: currentOverrides.provider || null, model: getEffectiveRawModel(), providers });
         }
         catch (err) {
-            // Revert to safe default (not empty — empty triggers auto-detection which
-            // picks ollama inside Claude Code sessions instead of claude-cli)
-            currentOverrides = { provider: "claude-cli" };
+            // 0682 F-001 (review iter 3): revert to the prior good selection, NOT
+            // the hard-coded claude-cli default. Pre-fix any failed POST silently
+            // wiped the user's prior valid choice.
+            currentOverrides = priorOverrides;
             sendJson(res, { error: err.message }, 400, req);
         }
     });
@@ -2186,13 +2479,21 @@ export function registerRoutes(router, root, projectName) {
             const body = (await readBody(req));
             const skillMdPath = join(skillDir, "SKILL.md");
             const skillContent = existsSync(skillMdPath) ? readFileSync(skillMdPath, "utf-8") : "";
-            // Extract description, name, and tags from frontmatter
+            // Extract description, name, and tags from frontmatter.
+            // 0679 F-001: route through parseSkillFrontmatter so the metadata-nested
+            // tags shape (per agentskills.io/specification) is honored. Direct regex
+            // missed indented `metadata.tags:` and silently produced an empty array.
             const description = extractDescription(skillContent);
-            const nameMatch = skillContent.match(/^---[\s\S]*?name:\s*(\S+)[\s\S]*?---/);
-            const tagsMatch = skillContent.match(/^---[\s\S]*?tags:\s*(.+)[\s\S]*?---/m);
+            const fm = parseSkillFrontmatter(skillContent);
+            const fmName = fm.name;
+            const fmTags = fm.tags;
             const meta = {
-                name: nameMatch ? nameMatch[1] : params.skill,
-                tags: tagsMatch ? tagsMatch[1].split(",").map((t) => t.trim()).filter(Boolean) : [],
+                name: typeof fmName === "string" && fmName.trim().length > 0 ? fmName.trim() : params.skill,
+                tags: Array.isArray(fmTags)
+                    ? fmTags.filter((t) => typeof t === "string" && t.length > 0)
+                    : (typeof fmTags === "string"
+                        ? fmTags.split(",").map((t) => t.trim()).filter(Boolean)
+                        : []),
             };
             // Use per-request model overrides if provided, fall back to global config
             const client = body.provider || body.model