@volter/supercode-interchange 0.1.22 → 0.1.23

package/skill-toml.mjs

@@ -0,0 +1,80 @@
+// Complete TOML 1.0 grammar, with the native Value admission boundaries. The parser also reads TOML 1.1; the forms only
+// 1.1 admits (inline tables over several lines or with a trailing comma, times without seconds, \x and \e escapes)
+// are refused here, as the native toml 0.8 reader refuses them.
+// The skills overlay reads only string/bool fields; dates remain date values.
+import { parse } from 'smol-toml';
+
+const scalar = value => { if (/[\uD800-\uDFFF]/u.test(value)) throw new Error('invalid TOML Unicode scalar'); };
+function nativeValues(value) {
+  if (typeof value === 'bigint' && (value < -0x8000000000000000n || value > 0x7fffffffffffffffn)) throw new Error('TOML integer is outside signed 64-bit range');
+  if (typeof value === 'string') scalar(value);
+  else if (value != null && typeof value === 'object' && !(value instanceof Date)) {
+    for (const [key, member] of Object.entries(value)) { scalar(key); nativeValues(member); }
+  }
+}
+const dateToken = /(?:\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})?)?|\d{2}:\d{2}:\d{2}(?:\.\d+)?)(?=$|[\s#,\]}])/y;
+const time11 = /(?:\d{4}-\d{2}-\d{2}[Tt ])?\d{2}:\d{2}(?!:\d)/y;
+function nativeDates(source) {
+  let out = '', copied = 0;
+  // Open brackets outside strings and comments: a line break or comment directly inside an inline table, or a comma
+  // closing one, is TOML 1.1 only (an array inside it may still span lines, as TOML 1.0 allows).
+  const open = [];
+  for (let at = 0; at < source.length;) {
+    const char = source[at];
+    if (open.at(-1) === '{' && (char === '\n' || char === '#')) throw new Error('TOML 1.0 inline tables are one line');
+    if (char === '#') { const next = source.indexOf('\n', at); at = next < 0 ? source.length : next + 1; continue; }
+    if (char === '{' || char === '[') { open.push(char); at++; continue; }
+    if (char === '}' || char === ']') {
+      if (char === '}') {
+        let before = at - 1; while (before >= 0 && /\s/.test(source[before])) before--;
+        if (source[before] === ',') throw new Error('TOML 1.0 inline tables take no trailing comma');
+      }
+      open.pop(); at++; continue;
+    }
+    if (char === '"' || char === "'") {
+      const fence = source.startsWith(char.repeat(3), at) ? char.repeat(3) : char; at += fence.length;
+      for (; at < source.length; at++) {
+        if (char === '"' && source[at] === '\\') {
+          if (source[at + 1] === 'x' || source[at + 1] === 'e') throw new Error('TOML 1.0 has no \\x or \\e escape');
+          at++; continue;
+        }
+        if (!source.startsWith(fence, at)) continue;
+        at += fence.length;
+        if (fence.length === 3) for (let extra = 0; extra < 2 && source[at] === char; extra++) at++;
+        break;
+      }
+      continue;
+    }
+    if (/\d/.test(char) && (!at || /[=,\[{\t \r\n]/.test(source[at - 1]))) {
+      time11.lastIndex = at; if (time11.test(source)) throw new Error('TOML 1.0 times carry seconds');
+      dateToken.lastIndex = at; const match = dateToken.exec(source);
+      if (match) {
+        const token = match[0], hasDate = token[4] === '-', timeAt = hasDate ? token.length > 10 ? 11 : null : 0;
+        if (hasDate) {
+          const year = Number(token.slice(0, 4)), month = Number(token.slice(5, 7)), day = Number(token.slice(8, 10));
+          const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+          const last = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+          if (!last || day < 1 || day > last) throw new Error('invalid TOML date');
+        }
+        if (timeAt != null) {
+          const hour = Number(token.slice(timeAt, timeAt + 2)), minute = Number(token.slice(timeAt + 3, timeAt + 5)), second = Number(token.slice(timeAt + 6, timeAt + 8));
+          const offset = /[+-](\d{2}):(\d{2})$/.exec(token);
+          if (hour > 23 || minute > 59 || second > 60 || offset && (Number(offset[1]) > 23 || Number(offset[2]) > 59)) throw new Error('invalid TOML time');
+          // Rust accepts second 60. The parser uses Date, which cannot encode
+          // it. Mask that component only; no date is consulted by this overlay.
+          if (second === 60) {
+            const secondAt = at + timeAt + 6;
+            out += source.slice(copied, secondAt) + '59'; copied = secondAt + 2;
+          }
+        }
+        at += token.length; continue;
+      }
+    }
+    at++;
+  }
+  return out + source.slice(copied);
+}
+export function parseSkillToml(source) {
+  const doc = parse(nativeDates(source.startsWith('\ufeff') ? source.slice(1) : source), { integersAsBigInt: true });
+  nativeValues(doc); return doc;
+}

package/skills-control.mjs

@@ -0,0 +1,193 @@
+// Controlled skill doors. Directory packages belong to the core four loaders;
+// Hermes/OpenClaw own their CLI mutations. A successful command is followed by
+// the same installed-skill reader, never inferred from its exit status alone.
+import { statSync, lstatSync, realpathSync, readdirSync, mkdirSync, copyFileSync, chmodSync, rmSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+import { SKILL_HARNESSES, skillHomes, skillRoots, writableSkillRoots, declaredSkillName, skillPathParent, skillPathName, skillPathKey, listInstalledSkills } from './skills-list.mjs';
+import { childPath } from './session-spend-files.mjs';
+import { nativeTrim } from './text.mjs';
+import { supportRegistryReport } from './support-report.mjs';
+
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const unsupported = message => { throw Object.assign(new Error(message), { rpcCode: -32020 }); };
+const failed = message => { throw Object.assign(new Error(message), { rpcCode: -32000 }); };
+const display = path => Buffer.isBuffer(path) ? path.toString('utf8') : path;
+const same = (left, right) => skillPathKey(left) === skillPathKey(right);
+const file = path => { try { return statSync(path).isFile(); } catch { return false; } };
+const directory = path => { try { return statSync(path).isDirectory(); } catch { return false; } };
+const exists = path => { try { statSync(path); return true; } catch { return false; } };
+const actual = (path, cwd) => !path.length || isAbsolute(display(path)) || process.platform === 'win32' && /^[A-Za-z]:/.test(display(path)) ? path : childPath(cwd, path);
+export const skillShellQuote = value => value && /^[A-Za-z0-9\-_./:@=+,]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+function struct(value, fields, name) {
+  if (Array.isArray(value)) {
+    if (value.length > fields.length) invalid(`${name} has too many fields`);
+    return Object.fromEntries(value.map((entry, at) => [fields[at], entry]));
+  }
+  if (value == null || typeof value !== 'object') invalid(`${name} must be a struct`);
+  return value;
+}
+function mutationParams(params, context) {
+  const value = struct(params, ['harness', 'name', 'source', 'scope', 'cwd', 'homes'], 'skill mutation');
+  if (Object.hasOwn(value, 'harness') && typeof value.harness !== 'string') invalid('harness must be a string');
+  for (const key of ['name', 'source', 'scope', 'cwd']) if (value[key] != null && typeof value[key] !== 'string') invalid(`${key} must be a string`);
+  if (value.scope != null && !['managed', 'user', 'project', 'plugin', 'bundled'].includes(value.scope)) invalid(`unknown skill scope: ${value.scope}`);
+  // This object crosses the same string-valued request boundary as supplied
+  // homes when the mutation re-reads the installed inventory.
+  const homes = Object.fromEntries(Object.entries(skillHomes(context.env)).map(([key, path]) => [key, display(path)]));
+  if (Object.hasOwn(value, 'homes')) {
+    const supplied = struct(value.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string') invalid(`homes.${key} must be a string`);
+      homes[key] = supplied[key];
+    }
+  }
+  return { ...value, harness: value.harness ?? '', homes, scope: value.scope ?? 'user', cwd: value.cwd ?? context.cwd };
+}
+const rows = (mutation, context) => listInstalledSkills({ harness: mutation.harness, cwd: mutation.cwd, homes: mutation.homes }, context);
+const names = (mutation, context) => new Set(rows(mutation, context).map(row => row.name));
+const findName = (mutation, name, context) => rows(mutation, context).find(row => row.name === name);
+function requireSource(mutation) {
+  const source = nativeTrim(mutation.source ?? '');
+  if (!source) invalid('`skills.install` needs a `source`: a local skill directory, or the identifier the harness\'s own install verb accepts');
+  return source;
+}
+function requireName(mutation) {
+  const name = nativeTrim(mutation.name ?? '');
+  if (!name) invalid('`skills.remove` needs the skill `name` to remove');
+  return name;
+}
+function validateName(value) {
+  const name = nativeTrim(value);
+  if (!name || name.startsWith('.') || /[\/\\\0]/.test(name) || process.platform === 'win32' && /^[A-Za-z]:/.test(name)) {
+    invalid(`\`${value}\` is not a skill name: a skill is one directory inside the harness's own root, so a name may not be empty, hidden, or contain a path separator`);
+  }
+  return name;
+}
+function canonical(path, cwd) {
+  try { return realpathSync.native(actual(path, cwd), { encoding: 'buffer' }); } catch { /* resolve the existing prefix */ }
+  const parent = skillPathParent(Buffer.from(path)), leaf = skillPathName(path);
+  if (parent == null || leaf == null) return Buffer.from(path);
+  return childPath(canonical(parent, cwd), leaf);
+}
+function contained(path, roots, context) {
+  const parent = skillPathParent(canonical(path, context.cwd));
+  if (parent != null && roots.some(root => same(parent, canonical(root, context.cwd)))) return;
+  invalid(`${display(path)} is outside the skills roots supercode recognizes (${roots.map(display).join(', ')}); every install and removal stays inside the harness's own root`);
+}
+function copyPackage(source, destination, context) {
+  try { mkdirSync(actual(destination, context.cwd), { recursive: true }); }
+  catch (error) { failed(`${display(destination)} could not be created: ${error.message}`); }
+  let entries;
+  try { entries = readdirSync(actual(source, context.cwd), { encoding: 'buffer' }); }
+  catch (error) { failed(`${display(source)} could not be read: ${error.message}`); }
+  for (const name of entries) {
+    const from = childPath(source, name), to = childPath(destination, name); let kind;
+    try { kind = lstatSync(actual(from, context.cwd)); }
+    catch (error) { failed(`${display(from)} could not be read: ${error.message}`); }
+    if (kind.isSymbolicLink()) invalid(`${display(from)} is a symlink; supercode copies a skill package's own files only, so a link that could point outside it is refused`);
+    if (kind.isDirectory()) copyPackage(from, to, context);
+    else if (kind.isFile()) {
+      try { copyFileSync(actual(from, context.cwd), actual(to, context.cwd)); chmodSync(actual(to, context.cwd), kind.mode & 0o7777); }
+      catch (error) { failed(`${display(from)} could not be copied to ${display(to)}: ${error.message}`); }
+    } else invalid(`${display(from)} is neither a file nor a directory; a skill package holds only its own files`);
+  }
+}
+function refusePresent(mutation, name, ran, context) {
+  const row = findName(mutation, name, context);
+  if (row) failed(`\`${ran}\` reported success but \`${name}\` is still installed at ${row.location}`);
+}
+function directoryMutation(verb, mutation, context) {
+  const writable = writableSkillRoots(mutation.harness, mutation.scope, mutation.homes, mutation.cwd);
+  if (!writable.length) unsupported(`\`${mutation.harness}\` has no ${mutation.scope} skills root Volter Harness may write; its inventory names none`);
+  if (verb === 'install') {
+    const source = requireSource(mutation);
+    if (!directory(actual(source, context.cwd))) invalid(`\`${source}\` is not a directory: \`${mutation.harness}\`'s skills door is its loader's own root, so the source must be the skill PACKAGE — a directory holding SKILL.md`);
+    const declared = declaredSkillName(source, context.cwd);
+    if (declared == null) invalid(`\`${source}\` holds no SKILL.md, so it is not a skill package the harness's loader would read`);
+    const name = validateName(nativeTrim(mutation.name ?? '') || declared), root = writable[0], destination = childPath(root, name);
+    if (exists(actual(destination, context.cwd))) invalid(`\`${name}\` is already installed at ${display(destination)}; remove it first`);
+    try { mkdirSync(actual(root, context.cwd), { recursive: true }); }
+    catch (error) { failed(`${mutation.harness}'s ${mutation.scope} skills root ${display(root)} could not be created: ${error.message}`); }
+    contained(destination, [root], context);
+    const ran = `cp -R ${skillShellQuote(source)} ${skillShellQuote(display(destination))}`;
+    try { copyPackage(source, destination, context); }
+    catch (error) { try { rmSync(actual(destination, context.cwd), { recursive: true }); } catch { /* retain the primary copy refusal */ } throw error; }
+    const skill = rows(mutation, context).find(row => same(row.location, destination));
+    if (!skill) failed(`\`${ran}\` succeeded but ${mutation.harness}'s loader does not report a skill at ${display(destination)}`);
+    return { harness: mutation.harness, verb, ran, name: skill.name, skill };
+  }
+  const name = validateName(requireName(mutation)), matches = rows(mutation, context).filter(row => row.name === name && row.scope === mutation.scope);
+  if (!matches.length) invalid(`\`${mutation.harness}\` has no ${mutation.scope} skill \`${name}\``);
+  if (matches.length !== 1) invalid(`\`${mutation.harness}\` reports ${matches.length} skills named \`${name}\` in its ${mutation.scope} roots (${matches.map(row => row.location).join(', ')}); supercode refuses to guess which one to delete`);
+  const row = matches[0], recognized = [...writable, ...skillRoots(mutation.harness, mutation.homes, mutation.cwd, context.cwd).filter(([scope]) => scope === mutation.scope).map(([, root]) => root)];
+  contained(row.location, recognized, context);
+  if (!file(actual(childPath(row.location, 'SKILL.md'), context.cwd))) invalid(`${row.location} holds no SKILL.md; supercode removes skill PACKAGES, never a directory it cannot identify as one`);
+  const ran = `rm -r ${skillShellQuote(row.location)}`;
+  try { rmSync(actual(row.location, context.cwd), { recursive: true }); }
+  catch (error) { failed(`\`${ran}\` failed: ${error.message}`); }
+  refusePresent(mutation, name, ran, context);
+  return { harness: mutation.harness, verb, ran, name, removed: true };
+}
+function harnessProgram(harness, context) {
+  const overridden = nativeTrim(context.env[harness === 'hermes' ? 'SUPERCODE_HERMES_BIN' : 'SUPERCODE_OPENCLAW_BIN'] ?? '');
+  if (overridden) return overridden;
+  const program = supportRegistryReport(context).harnesses.find(row => row.id === harness)?.runtime?.default_launch?.program;
+  if (!program) failed(`the registry has no launch for \`${harness}\`, so its CLI cannot be located`);
+  return program.replace(/-acp$/, '');
+}
+function commandFor(verb, mutation, context) {
+  if (mutation.harness === 'hermes' && mutation.scope !== 'user') unsupported('hermes keeps skills in one root per HERMES_HOME (`<HERMES_HOME>/skills`, and a profile IS a HERMES_HOME); it has no project-scoped skills root, so supercode refuses rather than inventing one');
+  if (mutation.harness === 'openclaw' && verb === 'remove') unsupported('openclaw 2026.7.1-2 publishes no `skills remove` verb (`openclaw skills` has search|install|update|verify|curator|workshop|list|info|check). supercode refuses rather than deleting files out of the harness\'s managed directory behind its back');
+  const program = harnessProgram(mutation.harness, context), args = ['skills'], env = { ...context.env }, name = nativeTrim(mutation.name ?? '');
+  if (mutation.harness === 'hermes') {
+    env.HERMES_HOME = display(mutation.homes.hermes);
+    if (verb === 'install') {
+      const source = requireSource(mutation);
+      if (directory(actual(source, context.cwd))) unsupported(`\`hermes skills install\` takes a registry identifier (\`owner/repo/skills/x\`) or a direct HTTP(S) URL to a SKILL.md — its pinned help enumerates no local-directory form, so \`${source}\` cannot be handed to it. Serve the package's SKILL.md over HTTP, or install it into a harness whose door is the directory`);
+      args.push('install', '--yes'); if (name) args.push('--name', name); args.push(source);
+    } else args.push('uninstall', requireName(mutation), '--yes');
+  } else {
+    env.OPENCLAW_STATE_DIR = display(mutation.homes.openclaw); env.OPENCLAW_CONFIG_PATH = display(childPath(mutation.homes.openclaw, 'openclaw.json'));
+    args.push('install', requireSource(mutation)); if (mutation.scope === 'user') args.push('--global'); if (name) args.push('--as', name);
+  }
+  return { program, args, env, ran: [program, ...args].map(skillShellQuote).join(' ') };
+}
+async function runCommand(command, context) {
+  if (context.signal?.aborted) failed('skill client closed before the harness command started');
+  const output = await new Promise((resolve, reject) => {
+    let child; const stdout = [], stderr = []; let force;
+    try { child = spawn(command.program, command.args, { cwd: context.cwd, env: command.env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); }
+    catch (error) { reject(error); return; }
+    const abort = () => { child.kill('SIGTERM'); force = setTimeout(() => child.kill('SIGKILL'), 500); };
+    child.stdout.on('data', data => stdout.push(data)); child.stderr.on('data', data => stderr.push(data));
+    child.once('error', reject);
+    child.once('close', (code, signal) => { clearTimeout(force); context.signal?.removeEventListener('abort', abort); resolve({ code, signal, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }); });
+    context.signal?.addEventListener('abort', abort, { once: true }); if (context.signal?.aborted) abort();
+  }).catch(error => failed(`\`${command.ran}\` could not be executed: ${error.message}`));
+  if (output.code !== 0) {
+    const detail = nativeTrim(output.stderr) || nativeTrim(output.stdout) || 'the harness printed nothing';
+    failed(`\`${command.ran}\` failed (${output.signal ? `signal: ${output.signal}` : process.platform === 'win32' ? `exit code: ${output.code}` : `exit status: ${output.code}`}): ${detail}`);
+  }
+}
+async function cliMutation(verb, mutation, context) {
+  const command = commandFor(verb, mutation, context), before = verb === 'install' ? names(mutation, context) : null, removing = verb === 'remove' ? requireName(mutation) : null;
+  await runCommand(command, context);
+  if (verb === 'remove') {
+    refusePresent(mutation, removing, command.ran, context);
+    return { harness: mutation.harness, verb, ran: command.ran, name: removing, removed: true };
+  }
+  const after = names(mutation, context), fresh = [...after].filter(name => !before.has(name)).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b))), requested = nativeTrim(mutation.name ?? '');
+  const name = fresh.length === 1 ? fresh[0] : requested && after.has(requested) ? requested : null;
+  if (name == null) failed(`\`${command.ran}\` exited 0 but ${mutation.harness}'s skills root gained ${fresh.length} skill(s), so the installed skill cannot be identified — pass \`name\` to say which one it should be`);
+  const skill = findName(mutation, name, context);
+  if (!skill) failed(`\`${command.ran}\` exited 0 but ${mutation.harness}'s skills roots hold no \`${name}\` afterwards`);
+  return { harness: mutation.harness, verb, ran: command.ran, name, skill };
+}
+export async function mutateInstalledSkill(verb, params, { env = process.env, cwd = process.cwd(), signal } = {}) {
+  const context = { env, cwd, signal }, mutation = mutationParams(params, context);
+  if (!SKILL_HARNESSES.includes(mutation.harness)) unsupported(`\`${mutation.harness}\` has no skills root Volter Harness reads; \`skills.${verb}\` is supported for: ${SKILL_HARNESSES.join(', ')}`);
+  if (!['user', 'project'].includes(mutation.scope)) invalid(`\`${mutation.scope}\` is a root the harness owns, not one a client may write; use user or project`);
+  if (verb !== 'install' && verb !== 'remove') invalid(`unknown skill mutation: ${verb}`);
+  return ['hermes', 'openclaw'].includes(mutation.harness) ? cliMutation(verb, mutation, context) : directoryMutation(verb, mutation, context);
+}

package/skills-list.mjs

@@ -0,0 +1,237 @@
+// Read-only skill packages. Controlled installation shares these exact loader
+// roots and frontmatter rules; runtime skill loading keeps its native owner.
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { userInfo } from 'node:os';
+import { parseSkillToml } from './skill-toml.mjs';
+import { childPath, directoryEntries, textName } from './session-spend-files.mjs';
+import { nativeTrim, truncateScalars } from './text.mjs';
+
+export const SKILL_HARNESSES = Object.freeze(['claude-code', 'codex', 'opencode', 'pi', 'hermes', 'openclaw']);
+const scopes = ['managed', 'user', 'project', 'plugin', 'bundled'];
+const skipped = new Set(['node_modules', 'target', '.git', 'scripts', 'references']);
+const whitespace = /[\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/u;
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const asciiLower = value => value.replace(/[A-Z]/g, char => char.toLowerCase());
+const join = (...parts) => parts.reduce((root, part) => childPath(root, part), Buffer.alloc(0));
+const selected = (path, cwd) => !path.length || isAbsolute(path.toString()) || process.platform === 'win32' && /^[A-Za-z]:/.test(path.toString()) ? path : childPath(cwd, path);
+const file = (path, cwd) => { try { return statSync(selected(path, cwd)).isFile(); } catch { return false; } };
+const exists = (path, cwd) => { try { statSync(selected(path, cwd)); return true; } catch { return false; } };
+const read = (path, cwd) => { try { return decoder.decode(readFileSync(selected(path, cwd))); } catch { return null; } };
+const unquote = value => nativeTrim(nativeTrim(value).replace(/^["']+|["']+$/g, ''));
+
+// PathBuf comparisons normalize separators and interior '.' components, but
+// keep '..' lexical. Filesystem reads retain the selected spelling throughout.
+function components(path) {
+  let source = Buffer.from(path), prefix = Buffer.alloc(0), rooted = false;
+  if (process.platform === 'win32') {
+    const text = source.toString('utf8');
+    const match = /^(?:\\\\[?.]\\(?:UNC\\[^\\]+\\[^\\]+|[A-Za-z]:|[^\\]+)|\\\\[^\\/]+[\\/][^\\/]+|[A-Za-z]:)/i.exec(text);
+    if (match) {
+      prefix = Buffer.from(match[0].replaceAll('/', '\\')); source = source.subarray(prefix.length);
+      // Windows PathBuf compares ordinary drive prefixes case-insensitively.
+      // Keep the filesystem/location spelling; normalize only the comparison.
+      if (prefix.length === 2 && prefix[1] === 58 && prefix[0] >= 97 && prefix[0] <= 122) prefix[0] -= 32;
+    }
+  }
+  const separator = byte => byte === 47 || process.platform === 'win32' && byte === 92;
+  rooted = source.length > 0 && separator(source[0]);
+  const parts = [], out = prefix.length ? [[0, prefix]] : [];
+  if (rooted) out.push([1, Buffer.alloc(0)]);
+  let begin = 0;
+  for (let at = 0; at <= source.length; at++) if (at === source.length || separator(source[at])) {
+    const part = source.subarray(begin, at); begin = at + 1;
+    if (part.length) parts.push(part);
+  }
+  for (let at = 0; at < parts.length; at++) {
+    const part = parts[at];
+    if (part.equals(Buffer.from('.'))) { if (!at && !rooted) out.push([2, Buffer.alloc(0)]); }
+    else out.push([part.equals(Buffer.from('..')) ? 3 : 4, part]);
+  }
+  return out;
+}
+const pathKey = path => JSON.stringify(components(path).map(([kind, text]) => [kind, text.toString('hex')]));
+function pathCompare(a, b) {
+  const left = components(a), right = components(b);
+  for (let at = 0; at < Math.min(left.length, right.length); at++) {
+    const order = left[at][0] - right[at][0] || Buffer.compare(left[at][1], right[at][1]);
+    if (order) return order;
+  }
+  return left.length - right.length;
+}
+const compareText = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+function directory(root, cwd) { try { return statSync(selected(root, cwd)).isDirectory(); } catch { return false; } }
+function directories(root, cwd) {
+  return [...directoryEntries(selected(root, cwd))].map(entry => childPath(root, entry.name)).filter(path => directory(path, cwd)).sort(pathCompare);
+}
+function parent(path) {
+  const parts = components(path); if (!parts.length || parts.at(-1)[0] <= 1) return null;
+  // Remove the last component, retaining the spelling of all preceding ones.
+  let text = path.toString('utf8'); const prefix = parts[0][0] === 0 ? parts[0][1].length : 0;
+  const slash = process.platform === 'win32' ? /[\\/]/ : /\//;
+  const minimum = prefix + (parts.some(([kind]) => kind === 1) ? 1 : 0);
+  const trimSeparators = () => { while (text.length > minimum && slash.test(text.at(-1))) text = text.slice(0, -1); };
+  trimSeparators();
+  for (;;) {
+    let start = text.length; while (start > prefix && !slash.test(text[start - 1])) start--;
+    if (text.slice(start) !== '.' || start === prefix) { text = text.slice(0, start); trimSeparators(); break; }
+    text = text.slice(0, start); trimSeparators();
+  }
+  return Buffer.from(text);
+}
+function projectRoots(cwd, markers, readerCwd) {
+  const roots = [], seen = new Set(); let ancestor = Buffer.from(cwd);
+  for (let count = 0; ancestor != null && count < 32; count++, ancestor = parent(ancestor)) {
+    for (const marker of markers) {
+      const root = join(ancestor, ...marker), key = pathKey(root);
+      if (directory(root, readerCwd) && !seen.has(key)) { seen.add(key); roots.push(root); }
+    }
+    if (exists(join(ancestor, '.git'), readerCwd)) break;
+  }
+  return roots;
+}
+export function skillHomes(env) {
+  let home; try { home = env.HOME || process.platform === 'win32' && env.USERPROFILE || userInfo().homedir || '.'; } catch { home = '.'; }
+  return {
+    claude_code: env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), codex: env.CODEX_HOME ?? join(home, '.codex'),
+    opencode: env.OPENCODE_CONFIG_DIR ?? join(env.XDG_CONFIG_HOME ?? join(home, '.config'), 'opencode'),
+    pi: env.PI_CODING_AGENT_DIR ?? join(home, '.pi', 'agent'), hermes: env.HERMES_HOME ?? join(home, '.hermes'),
+    openclaw: env.OPENCLAW_STATE_DIR ?? (env.OPENCLAW_HOME != null ? join(env.OPENCLAW_HOME, '.openclaw') : join(home, '.openclaw')),
+    agents: join(home, '.agents'),
+  };
+}
+function struct(params, keys, name) {
+  if (Array.isArray(params)) { if (params.length > keys.length) invalid(`${name} has too many fields`); return Object.fromEntries(params.map((value, at) => [keys[at], value])); }
+  if (params == null || typeof params !== 'object') invalid(`${name} must be a struct`);
+  return params;
+}
+function queryParams(params, context) {
+  const query = struct(params, ['harness', 'scope', 'cwd', 'homes'], 'skills params');
+  for (const key of ['harness', 'scope', 'cwd']) if (query[key] != null && typeof query[key] !== 'string') invalid(`${key} must be a string`);
+  if (query.scope != null && !scopes.includes(query.scope)) invalid(`unknown skill scope: ${query.scope}`);
+  const homes = skillHomes(context.env);
+  if (Object.hasOwn(query, 'homes')) {
+    const supplied = struct(query.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string') invalid(`homes.${key} must be a string`);
+      homes[key] = supplied[key];
+    }
+  }
+  if (query.harness != null && !SKILL_HARNESSES.includes(query.harness)) throw Object.assign(new Error(`\`${query.harness}\` has no skills root Volter Harness reads`), { rpcCode: -32020 });
+  return { ...query, homes, cwd: query.cwd ?? context.cwd };
+}
+export function skillRoots(harness, homes, cwd, readerCwd = cwd) {
+  const out = [], add = (scope, path) => out.push([scope, path]), project = markers => projectRoots(cwd, markers, readerCwd).forEach(path => add('project', path));
+  if (harness === 'claude-code') {
+    add('managed', process.platform === 'darwin' ? '/Library/Application Support/ClaudeCode/skills' : '/etc/claude-code/skills'); add('user', join(homes.claude_code, 'skills'));
+    for (const market of directories(join(homes.claude_code, 'plugins', 'cache'), readerCwd)) for (const plugin of directories(market, readerCwd)) for (const version of directories(plugin, readerCwd)) add('plugin', join(version, 'skills'));
+    project([['.claude', 'skills']]);
+  } else if (harness === 'codex') {
+    add('managed', '/etc/codex/skills'); add('bundled', join(homes.codex, 'skills', '.system')); add('user', join(homes.agents, 'skills')); add('user', join(homes.codex, 'skills')); project([['.agents', 'skills']]);
+  } else if (harness === 'opencode') {
+    add('user', join(homes.opencode, 'skill')); add('user', join(homes.opencode, 'skills')); project([['.opencode', 'skill'], ['.opencode', 'skills']]);
+  } else if (harness === 'pi') {
+    add('user', join(homes.pi, 'skills')); add('user', join(homes.agents, 'skills')); project([['.pi', 'skills'], ['.agents', 'skills']]);
+  } else if (harness === 'hermes') {
+    add('user', join(homes.hermes, 'skills')); for (const profile of directories(join(homes.hermes, 'profiles'), readerCwd)) add('user', join(profile, 'skills'));
+  } else if (harness === 'openclaw') {
+    add('managed', join(homes.openclaw, 'skills')); add('plugin', join(homes.openclaw, 'plugin-skills')); add('user', join(homes.agents, 'skills'));
+    add('project', join(homes.openclaw, 'workspace', 'skills')); add('project', join(homes.openclaw, 'workspace', '.agents', 'skills'));
+  }
+  return out.filter(([, root]) => directory(root, readerCwd));
+}
+function frontmatter(manifest, cwd) {
+  const source = read(manifest, cwd), out = new Map(); if (source == null) return out;
+  const lines = truncateScalars(source, 8192).split('\n').map(line => line.endsWith('\r') ? line.slice(0, -1) : line);
+  if (nativeTrim(lines.shift() ?? '') !== '---') return out;
+  let pending;
+  for (const line of lines) {
+    const trimmed = line.replace(new RegExp(`${whitespace.source}$`, 'u'), ''), item = nativeTrim(trimmed);
+    if (item === '---' || item === '...') break;
+    if (!trimmed || item.startsWith('#')) continue;
+    if (whitespace.test(trimmed[0])) {
+      if (pending && item.startsWith('- ')) { const value = unquote(item.slice(2)); if (value) out.set(pending, out.has(pending) && out.get(pending) ? `${out.get(pending)}, ${value}` : value); }
+      continue;
+    }
+    pending = undefined; const colon = trimmed.indexOf(':'); if (colon < 0) continue;
+    const key = asciiLower(nativeTrim(trimmed.slice(0, colon))), value = unquote(trimmed.slice(colon + 1));
+    if (!key) continue;
+    if (!value) pending = key;
+    else if (!out.has(key)) out.set(key, value);
+  }
+  return out;
+}
+const boolean = value => ['true', 'yes', 'on'].includes(asciiLower(unquote(value))) ? true : ['false', 'no', 'off'].includes(asciiLower(unquote(value))) ? false : null;
+function collect(harness, scope, root, depth, out, cwd) {
+  if (out.length >= 512) return;
+  for (const directory of directories(root, cwd)) {
+    if (out.length >= 512) return;
+    const name = textName(components(directory).at(-1)?.[1] ?? Buffer.alloc(0));
+    if (name == null || name.startsWith('.') || skipped.has(name)) continue;
+    const manifest = join(directory, 'SKILL.md');
+    if (file(manifest, cwd)) {
+      const front = frontmatter(manifest, cwd), row = { name: nativeTrim(front.get('name') ?? '') || name, harness, scope, location: textName(directory), enabled: null };
+      if (front.has('description')) row.description = nativeTrim(front.get('description')).split(whitespace).join(' ');
+      const version = nativeTrim(front.get('version') ?? ''); if (version) row.version = version;
+      if (front.has('enabled')) row.enabled = boolean(front.get('enabled'));
+      else if (front.has('disable-model-invocation')) { const disabled = boolean(front.get('disable-model-invocation')); if (disabled != null) row.enabled = !disabled; }
+      if (row.location == null) throw new Error('skill location is not valid UTF-8'); out.push(row); continue;
+    }
+    const before = out.length; if (depth + 1 < 3) collect(harness, scope, directory, depth + 1, out, cwd);
+    if (before === out.length) { const location = textName(directory); if (location == null) throw new Error('skill location is not valid UTF-8'); out.push({ name, harness, scope, location, enabled: null }); }
+  }
+}
+function codexEnablement(homes, rows, cwd) {
+  const source = read(join(homes.codex, 'config.toml'), cwd); if (source == null) return;
+  let skills; try { skills = parseSkillToml(source).skills; } catch { return; }
+  for (const row of rows) {
+    if (row.harness !== 'codex') continue;
+    if (row.scope === 'bundled' && typeof skills?.bundled?.enabled === 'boolean') row.enabled = skills.bundled.enabled;
+    for (const entry of Array.isArray(skills?.config) ? skills.config : []) {
+      if (typeof entry?.enabled !== 'boolean') continue;
+      if (typeof entry.name === 'string' && entry.name === row.name || typeof entry.path === 'string' && pathKey(entry.path) === pathKey(row.location)) row.enabled = entry.enabled;
+    }
+  }
+}
+export function listInstalledSkills(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const query = queryParams(params, { env, cwd }), rows = [], seen = new Set();
+  for (const harness of SKILL_HARNESSES) {
+    if (query.harness != null && query.harness !== harness) continue;
+    for (const [scope, root] of skillRoots(harness, query.homes, query.cwd, cwd)) {
+      if (query.scope != null && query.scope !== scope) continue;
+      const found = []; collect(harness, scope, root, 0, found, cwd);
+      for (const row of found) { const key = `${harness}\0${pathKey(row.location)}`; if (!seen.has(key)) { seen.add(key); rows.push(row); } }
+    }
+  }
+  codexEnablement(query.homes, rows, cwd);
+  return rows.sort((a, b) => compareText(a.harness, b.harness) || scopes.indexOf(a.scope) - scopes.indexOf(b.scope) || compareText(a.name, b.name) || pathCompare(a.location, b.location));
+}
+
+// Internal mutation helpers use the reader's PathBuf comparison and manifest
+// rules. Existing runtime roots remain independent of the writable root table.
+export { parent as skillPathParent, pathKey as skillPathKey };
+export function skillPathName(path) {
+  const last = components(Buffer.from(path)).at(-1);
+  return last?.[0] === 4 ? last[1] : null;
+}
+export function writableSkillRoots(harness, scope, homes, cwd) {
+  const project = markers => markers.map(marker => join(cwd, ...marker));
+  if (scope === 'user') {
+    if (harness === 'claude-code') return [join(homes.claude_code, 'skills')];
+    if (harness === 'codex') return [join(homes.agents, 'skills'), join(homes.codex, 'skills')];
+    if (harness === 'opencode') return [join(homes.opencode, 'skill'), join(homes.opencode, 'skills')];
+    if (harness === 'pi') return [join(homes.pi, 'skills'), join(homes.agents, 'skills')];
+  } else if (scope === 'project') {
+    if (harness === 'claude-code') return project([['.claude', 'skills']]);
+    if (harness === 'codex') return project([['.agents', 'skills']]);
+    if (harness === 'opencode') return project([['.opencode', 'skill'], ['.opencode', 'skills']]);
+    if (harness === 'pi') return project([['.pi', 'skills'], ['.agents', 'skills']]);
+  }
+  return [];
+}
+export function declaredSkillName(path, cwd) {
+  const manifest = join(path, 'SKILL.md');
+  if (!file(manifest, cwd)) return null;
+  return nativeTrim(frontmatter(manifest, cwd).get('name') ?? '') || textName(components(Buffer.from(path)).at(-1)?.[1] ?? Buffer.alloc(0)) || null;
+}

package/source-files.mjs

@@ -16,8 +16,18 @@ export async function optionalFile(path, work, metrics) {
   catch (error) { if (missing(error)) return { path, missing: true, result: null }; throw error; }
 }
 
-export function readSourceJson(path, metrics) {
-  return optionalFile(path, async (reader) => parseJsonLine(await reader.read(0, reader.size), { strictUtf8: true }), metrics);
+const sourceJsonReads = new WeakSet();
+
+/** Only a result from this process can reuse its parsed native-number facts.
+ * Opening and verifying the current file still checks identity and readability. */
+export async function readSourceJson(path, metrics, previous) {
+  const source = await optionalFile(path, async (reader) => {
+    if (previous?.path === path && sourceJsonReads.has(previous) && sameFingerprint(previous.fingerprint, reader.fingerprint))
+      return previous.result;
+    return parseJsonLine(await reader.read(0, reader.size), { strictUtf8: true });
+  }, metrics);
+  sourceJsonReads.add(source);
+  return source;
 }
 
 /** A compound descriptor includes every auxiliary identity, including an