mirror of
https://github.com/affaan-m/ECC.git
synced 2026-11-17 05:22:17 +00:00
319 lines
17 KiB
JavaScript
319 lines
17 KiB
JavaScript
'use strict';
|
|
|
|
// Neighbor skills: skills the host has installed from somewhere other than ECC.
|
|
// ECC never loads their bodies as context or interprets their instructions.
|
|
// Discovery reads bounded files to extract frontmatter. Their names and
|
|
// descriptions are matched against the task so the ones that also fit can be
|
|
// listed as companions next to ECC's own selection, which they never change.
|
|
// The host can then use ECC's skill and the user's other skills together. The
|
|
// list is an explicit, digest-bound input: resolution never scans the machine,
|
|
// so the same input gives the same result everywhere. Discovery is a separate,
|
|
// read-only step that writes a snapshot.
|
|
const fs = require('node:fs');
|
|
const os = require('node:os');
|
|
const path = require('node:path');
|
|
const yaml = require('js-yaml');
|
|
const { scoreExternal, tokenize } = require('./context-retrieval');
|
|
const { DEFAULT_REPO_ROOT, digestObject } = require('./context-profile-support');
|
|
|
|
const SCHEMA = 'ecc.context-neighbors.v1';
|
|
// The envelope `ecc profile <command> --json` prints around a successful result.
|
|
const OPERATION_SCHEMA = 'ecc.profile-operation.v1';
|
|
const MAX_NEIGHBORS = 1024;
|
|
const MAX_NAME_BYTES = 128;
|
|
const MAX_SOURCE_BYTES = 256;
|
|
const MAX_DESCRIPTION_BYTES = 4096;
|
|
// Discovery keeps the routing-relevant start of long descriptions.
|
|
const DISCOVERED_DESCRIPTION_CHARS = 1024;
|
|
const MAX_SNAPSHOT_BYTES = 4 * 1024 * 1024;
|
|
const MAX_SKILL_FILE_BYTES = 256 * 1024;
|
|
const MAX_FRONTMATTER_CHARS = 16 * 1024;
|
|
const MAX_JSON_BYTES = 1024 * 1024;
|
|
const NEIGHBOR_KEYS = new Set(['source', 'name', 'description']);
|
|
const SNAPSHOT_KEYS = new Set(['schemaVersion', 'target', 'neighbors', 'neighborsDigest', 'excludedEccCopies',
|
|
'excludedEccPlugins', 'skipped']);
|
|
const TARGETS = ['claude', 'codex'];
|
|
// C0/C1 controls (tab and line breaks are collapsed instead) and invisible format characters
|
|
// (zero-width, bidi, tag characters) are rejected: this text is shown to models.
|
|
// eslint-disable-next-line no-control-regex
|
|
const CONTROL = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]|\p{Cf}/u;
|
|
|
|
function boundedString(value, label, maxBytes, index) {
|
|
if (typeof value !== 'string' || !value.trim() || Buffer.byteLength(value) > maxBytes || CONTROL.test(value)) {
|
|
throw new Error(`Neighbor ${index} ${label} must be a non-empty string of at most ${maxBytes} bytes`);
|
|
}
|
|
return value.trim().replace(/\s+/g, ' ');
|
|
}
|
|
|
|
function compareNeighbors(left, right) {
|
|
for (const key of ['source', 'name', 'description']) {
|
|
if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1;
|
|
}
|
|
return 0;
|
|
}
|
|
|
|
/** Validate a neighbor list (an array, or an ecc.context-neighbors.v1 snapshot)
|
|
* and return it canonically ordered and deduplicated with its digest. */
|
|
function normalizeNeighbors(value) {
|
|
const snapshot = value && typeof value === 'object' && !Array.isArray(value) ? value : null;
|
|
if (snapshot && (snapshot.schemaVersion !== SCHEMA || !Array.isArray(snapshot.neighbors)
|
|
|| Object.keys(snapshot).some(key => !SNAPSHOT_KEYS.has(key)))) {
|
|
throw new Error(`Neighbor skills must be an array or an ${SCHEMA} snapshot`);
|
|
}
|
|
const list = Array.isArray(value) ? value : snapshot ? snapshot.neighbors : null;
|
|
if (!list) throw new Error(`Neighbor skills must be an array or an ${SCHEMA} snapshot`);
|
|
if (list.length > MAX_NEIGHBORS) throw new Error(`Neighbor skills must list at most ${MAX_NEIGHBORS} entries`);
|
|
const normalized = list.map((item, index) => {
|
|
if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error(`Neighbor ${index} must be an object`);
|
|
for (const key of Object.keys(item)) if (!NEIGHBOR_KEYS.has(key)) throw new Error(`Unknown neighbor field: ${key}`);
|
|
return { source: item.source === undefined ? 'unspecified' : boundedString(item.source, 'source', MAX_SOURCE_BYTES, index),
|
|
name: boundedString(item.name, 'name', MAX_NAME_BYTES, index),
|
|
description: boundedString(item.description, 'description', MAX_DESCRIPTION_BYTES, index) };
|
|
}).sort(compareNeighbors);
|
|
const neighbors = normalized.filter((item, index) => !index || compareNeighbors(item, normalized[index - 1]) !== 0);
|
|
const neighborsDigest = digestObject(neighbors);
|
|
if (snapshot && snapshot.neighborsDigest !== undefined && snapshot.neighborsDigest !== neighborsDigest) {
|
|
throw new Error('Neighbor snapshot digest does not match its neighbors');
|
|
}
|
|
return { neighbors, neighborsDigest };
|
|
}
|
|
|
|
// Provider skill directories may legitimately be symlinks. Resolve that
|
|
// mapping once, then bind type/size checks and all reads to one open file.
|
|
// A raced FIFO must not block opening, and a newly substituted final symlink
|
|
// must not be followed where the platform supports O_NOFOLLOW.
|
|
function readBoundedBytes(file, maxBytes) {
|
|
const canonical = fs.realpathSync(file);
|
|
const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0);
|
|
const writeFlags = fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_APPEND
|
|
| fs.constants.O_WRONLY | fs.constants.O_RDWR;
|
|
if (flags & writeFlags) throw new Error('Neighbor files require a non-creating, read-only descriptor');
|
|
// Mode does not change existing files. Keep an explicit least-privilege
|
|
// fallback as well as the non-creating flag contract above.
|
|
const fd = fs.openSync(canonical, flags, 0o400);
|
|
try {
|
|
const before = fs.fstatSync(fd, { bigint: true });
|
|
if (!before.isFile() || before.size > BigInt(maxBytes)) {
|
|
throw new Error(`Neighbor file must be a regular file of at most ${maxBytes} bytes`);
|
|
}
|
|
const bytes = Buffer.alloc(Number(before.size) + 1);
|
|
let length = 0;
|
|
while (length < bytes.length) {
|
|
const count = fs.readSync(fd, bytes, length, Math.min(64 * 1024, bytes.length - length), null);
|
|
if (count === 0) break;
|
|
length += count;
|
|
}
|
|
const after = fs.fstatSync(fd, { bigint: true });
|
|
const sameFile = stat => stat.isFile() && stat.dev === before.dev && stat.ino === before.ino
|
|
&& stat.size === before.size && stat.mtimeNs === before.mtimeNs && stat.ctimeNs === before.ctimeNs;
|
|
if (length > maxBytes || BigInt(length) !== before.size || !sameFile(after)
|
|
|| fs.realpathSync(file) !== canonical || !sameFile(fs.statSync(canonical, { bigint: true }))) {
|
|
throw new Error('Neighbor file changed while reading');
|
|
}
|
|
return bytes.subarray(0, length);
|
|
} finally {
|
|
fs.closeSync(fd);
|
|
}
|
|
}
|
|
|
|
/** Read and validate a neighbor snapshot file written by discovery or by hand. */
|
|
function readNeighborSnapshot(file) {
|
|
const absolute = path.resolve(file);
|
|
const bytes = readBoundedBytes(absolute, MAX_SNAPSHOT_BYTES);
|
|
const text = bytes.toString('utf8');
|
|
if (!Buffer.from(text).equals(bytes) || text.includes('\0')) throw new Error('Neighbor snapshot must be UTF-8 JSON without NUL');
|
|
let value;
|
|
try { value = JSON.parse(text); } catch { throw new Error('Neighbor snapshot must be valid JSON'); }
|
|
// `ecc profile neighbors --json` wraps the snapshot in the CLI's operation
|
|
// envelope; saving that output and passing it back must work as-is.
|
|
if (value && value.schemaVersion === OPERATION_SCHEMA && value.status === 'success' && value.neighbors
|
|
&& typeof value.neighbors === 'object' && value.neighbors.schemaVersion === SCHEMA) value = value.neighbors;
|
|
return { schemaVersion: SCHEMA, ...normalizeNeighbors(value) };
|
|
}
|
|
|
|
function slug(name) {
|
|
return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'skill';
|
|
}
|
|
|
|
const COMPANION_LIMITATION = 'Companion skills are installed non-ECC skills matched by name and description only, '
|
|
+ "scored with ECC's word statistics: a word no ECC skill uses weighs more, so a companion can be listed on vocabulary "
|
|
+ 'alone. ECC does not load, read or vouch for them; the host decides whether to use them.';
|
|
|
|
/** A validated, non-empty neighbor set, or null. No list and an empty list are
|
|
* both null, so the resolver result is unchanged without neighbors. */
|
|
function companionInput(neighbors) {
|
|
if (neighbors === null || neighbors === undefined) return null;
|
|
const set = normalizeNeighbors(neighbors);
|
|
return set.neighbors.length ? set : null;
|
|
}
|
|
|
|
// One skill per name and description: copies installed from several sources
|
|
// collapse into the first source in canonical order; the rest are alsoIn.
|
|
function distinctSkills(neighbors) {
|
|
const bySkill = new Map();
|
|
for (const item of neighbors) {
|
|
const key = `${item.name}\n${item.description}`;
|
|
if (bySkill.has(key)) bySkill.get(key).alsoIn.push(item.source);
|
|
else bySkill.set(key, { ...item, alsoIn: [] });
|
|
}
|
|
return [...bySkill.values()];
|
|
}
|
|
|
|
/** Installed neighbors that also match the query, strongest first, to list
|
|
* beside ECC's own selection. Each neighbor is scored with the ECC index's own
|
|
* statistics, shaped like an ECC entry whose id slug is its name. It is listed
|
|
* when it clears the caller's evidence bar and a matched term is in its name.
|
|
* A companion is marked sameTopicAs ECC's top candidate when one of its
|
|
* matched terms is an anchor term (name or trigger) of that candidate. */
|
|
// A companion clears the score and term bar and either shares a word with the
|
|
// prompt in its name (anchored), or is the single best-scoring neighbor and
|
|
// leads the next one by the auto-admission margin. Specialized skills often
|
|
// have names a prompt never uses; the margin keeps that route to one clear
|
|
// winner instead of every neighbor with matching description words.
|
|
function rankCompanions(index, query, neighbors, { minBm25, minTerms, minAnchorTerms, margin, limit, top = null }) {
|
|
if (!index || !neighbors || !neighbors.length) return [];
|
|
const topAnchors = new Set(top && Array.isArray(top.anchorTerms) ? top.anchorTerms : []);
|
|
const entries = distinctSkills(neighbors).map(skill => ({ id: `skill:${slug(skill.name)}`, name: skill.name,
|
|
description: skill.description, skill, nameTerms: new Set(tokenize(skill.name)) }));
|
|
const scored = scoreExternal(index, query, entries);
|
|
const onBar = candidate => candidate.bm25 >= minBm25 && candidate.matchedTerms.length >= minTerms;
|
|
const anchored = candidate => candidate.matchedTerms.filter(term => candidate.entry.nameTerms.has(term)).length >= minAnchorTerms;
|
|
const clearLead = (candidate, position) => position === 0 && (!scored[1] || candidate.bm25 >= margin * scored[1].bm25);
|
|
return scored
|
|
.filter((candidate, position) => onBar(candidate) && (anchored(candidate) || clearLead(candidate, position)))
|
|
.slice(0, limit)
|
|
.map(({ entry, bm25, matchedTerms }) => ({ name: entry.skill.name, source: entry.skill.source,
|
|
...(entry.skill.alsoIn.length ? { alsoIn: entry.skill.alsoIn } : {}),
|
|
description: entry.skill.description, bm25, matchedTerms,
|
|
...(top && matchedTerms.some(term => topAnchors.has(term)) ? { sameTopicAs: top.id } : {}) }));
|
|
}
|
|
|
|
function readBoundedJson(file) {
|
|
try {
|
|
return JSON.parse(readBoundedBytes(file, MAX_JSON_BYTES).toString('utf8'));
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function frontmatter(file) {
|
|
const text = readBoundedBytes(file, MAX_SKILL_FILE_BYTES).toString('utf8');
|
|
const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
|
|
// Only name and description are needed; a frontmatter block this large is
|
|
// not a skill header, so it is skipped before YAML parsing.
|
|
if (!match || match[1].length > MAX_FRONTMATTER_CHARS) return null;
|
|
const value = yaml.load(match[1], { schema: yaml.CORE_SCHEMA });
|
|
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
|
|
}
|
|
|
|
function skillDirectories(root) {
|
|
try {
|
|
return fs.readdirSync(path.join(root, 'skills'), { withFileTypes: true })
|
|
.filter(entry => (entry.isDirectory() || entry.isSymbolicLink()) && !entry.name.startsWith('.'))
|
|
.map(entry => path.join(root, 'skills', entry.name))
|
|
.sort();
|
|
} catch {
|
|
return [];
|
|
}
|
|
}
|
|
|
|
function claudeSkillRoots(configDir, eccPluginName) {
|
|
const roots = [{ source: 'claude:user', root: configDir }];
|
|
let excludedEccPlugins = 0;
|
|
const installed = readBoundedJson(path.join(configDir, 'plugins', 'installed_plugins.json'));
|
|
const settings = readBoundedJson(path.join(configDir, 'settings.json'));
|
|
const enabled = settings && typeof settings.enabledPlugins === 'object' && settings.enabledPlugins ? settings.enabledPlugins : {};
|
|
const plugins = installed && typeof installed.plugins === 'object' && installed.plugins ? installed.plugins : {};
|
|
for (const key of Object.keys(plugins).sort()) {
|
|
if (enabled[key] !== true || !Array.isArray(plugins[key])) continue;
|
|
const record = plugins[key].find(item => item && (item.scope === undefined || item.scope === 'user')
|
|
&& typeof item.installPath === 'string' && path.isAbsolute(item.installPath));
|
|
if (!record) continue;
|
|
const manifest = readBoundedJson(path.join(record.installPath, '.claude-plugin', 'plugin.json'));
|
|
if (eccPluginName && manifest && manifest.name === eccPluginName) {
|
|
excludedEccPlugins += 1;
|
|
continue;
|
|
}
|
|
const source = `claude:plugin:${key}`;
|
|
// A plugin key that cannot be a valid source label is skipped, not fatal.
|
|
if (Buffer.byteLength(source) > MAX_SOURCE_BYTES || CONTROL.test(source)) continue;
|
|
roots.push({ source, root: record.installPath });
|
|
}
|
|
return { roots, excludedEccPlugins };
|
|
}
|
|
|
|
const comparable = text => String(text || '').trim().replace(/\s+/g, ' ');
|
|
|
|
// One skill directory: a neighbor summary, an installed ECC copy, a skipped
|
|
// (unreadable or incomplete) skill, or no SKILL.md at all.
|
|
function readSkillSummary(directory, eccCopies) {
|
|
const file = path.join(directory, 'SKILL.md');
|
|
let meta;
|
|
try { meta = frontmatter(file); } catch (error) {
|
|
if (error.code === 'ENOENT') return { kind: 'missing' };
|
|
meta = null;
|
|
}
|
|
const name = meta && typeof meta.name === 'string' && meta.name.trim() ? meta.name.trim() : path.basename(directory);
|
|
const description = meta && typeof meta.description === 'string' ? comparable(meta.description) : '';
|
|
if (!description || Buffer.byteLength(name) > MAX_NAME_BYTES || CONTROL.test(name) || CONTROL.test(description)) {
|
|
return { kind: 'skipped' };
|
|
}
|
|
if (eccCopies.has(`${comparable(name)}\n${description}`)) return { kind: 'ecc' };
|
|
return { kind: 'neighbor', skill: { name, description: description.slice(0, DISCOVERED_DESCRIPTION_CHARS) } };
|
|
}
|
|
|
|
// Skill roots to read for one target, in source order.
|
|
function discoveryRoots({ target, env, home, projectDir, eccPluginName }) {
|
|
if (target !== 'claude') {
|
|
return { roots: [{ source: 'codex:user', root: env.CODEX_HOME || path.join(home, '.codex') }], excludedEccPlugins: 0 };
|
|
}
|
|
const configDir = env.CLAUDE_CONFIG_DIR || path.join(home, '.claude');
|
|
const discovery = claudeSkillRoots(configDir, eccPluginName);
|
|
const projectRoot = projectDir && path.join(projectDir, '.claude');
|
|
// Run from the home directory, the project folder is the user folder: read it once.
|
|
if (projectRoot && path.resolve(projectRoot) !== path.resolve(configDir)) {
|
|
return { ...discovery, roots: [...discovery.roots, { source: 'claude:project', root: projectRoot }] };
|
|
}
|
|
return discovery;
|
|
}
|
|
|
|
/** Read-only discovery of the skills a provider home exposes besides ECC.
|
|
* Claude: user skills, skills of enabled user-scope plugins, and, with
|
|
* projectDir, the project's own `.claude/skills` (where teams keep skills
|
|
* specific to their codebase). Codex: the Codex home's skills. ECC's own
|
|
* plugin and installed copies of ECC skills (same name and description as the
|
|
* registry) are excluded. */
|
|
function discoverNeighborSkills({ repoRoot = DEFAULT_REPO_ROOT, target = 'codex', env = process.env,
|
|
home = os.homedir(), projectDir = null } = {}) {
|
|
if (!TARGETS.includes(target)) throw new Error(`Unsupported neighbor target: ${target}`);
|
|
if (projectDir !== null && (target !== 'claude' || typeof projectDir !== 'string' || !path.isAbsolute(projectDir))) {
|
|
throw new Error('A project directory must be an absolute path and applies to the claude target only');
|
|
}
|
|
const { loadContextRegistry } = require('./context-pack-registry');
|
|
const registry = loadContextRegistry({ repoRoot });
|
|
const eccCopies = new Set(registry.entries.map(entry => `${comparable(entry.name)}\n${comparable(entry.description)}`));
|
|
const eccPlugin = readBoundedJson(path.join(repoRoot, '.claude-plugin', 'plugin.json'));
|
|
const discovery = discoveryRoots({ target, env, home, projectDir, eccPluginName: eccPlugin && eccPlugin.name });
|
|
const neighbors = [];
|
|
const counts = { missing: 0, skipped: 0, ecc: 0 };
|
|
for (const { source, root } of discovery.roots) {
|
|
for (const directory of skillDirectories(root)) {
|
|
const found = readSkillSummary(directory, eccCopies);
|
|
if (found.kind !== 'neighbor') {
|
|
counts[found.kind] += 1;
|
|
continue;
|
|
}
|
|
neighbors.push({ source, ...found.skill });
|
|
if (neighbors.length > MAX_NEIGHBORS) throw new Error(`Discovered more than ${MAX_NEIGHBORS} neighbor skills`);
|
|
}
|
|
}
|
|
const excludedEccCopies = counts.ecc;
|
|
const skipped = counts.skipped;
|
|
const normalized = normalizeNeighbors(neighbors);
|
|
return { schemaVersion: SCHEMA, target, neighbors: normalized.neighbors, neighborsDigest: normalized.neighborsDigest,
|
|
excludedEccCopies, excludedEccPlugins: discovery.excludedEccPlugins, skipped };
|
|
}
|
|
|
|
module.exports = { COMPANION_LIMITATION, SCHEMA, companionInput, discoverNeighborSkills, normalizeNeighbors, rankCompanions,
|
|
readNeighborSnapshot };
|