@getbourdon/participants 0.5.5 → 0.6.0

package/dist/skills.js

@@ -0,0 +1,999 @@
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * Skill readers: advertise the local skills an agent can see in its L5
+ * manifest (plan 005, discovery side). Port of `participants/_skills.py`.
+ *
+ * A participant that knows where its agent keeps skills (a folder per skill
+ * holding a `SKILL.md` with `name` / `description` front matter) lists them as
+ * `SkillRef` rows: name, description and a content hash. Nothing is shared or
+ * promoted here; the body never enters the manifest.
+ *
+ * Two kinds of skill directory:
+ *  - **The agent's own** (`~/.claude/skills`, `$CODEX_HOME/skills`,
+ *    `~/.cursor/skills` and their project forms).
+ *  - **The cross-agent store**, `~/.agents/skills` (and `<project>/.agents/skills`):
+ *    a vendor-neutral directory no single agent owns. The cross-agent skills
+ *    installer CLI keeps its installs there and records each one in
+ *    `~/.agents/.skill-lock.json`; people also write skills there by hand. Refs
+ *    from it carry `store: cross_agent`. Every skill-reading participant reads
+ *    it with its own directories; a reader of several manifests collapses the
+ *    copies (`collectAdvertisedSkills` in @getbourdon/federation).
+ *
+ * One skill, one ref per manifest: when an agent's own folder holds a skill
+ * that is also in the cross-agent store, the agent-folder ref is kept and
+ * records the store copy in `also_in` (`via: copy` for a copy with the same
+ * `content_sha256`, `via: link` for a link into the store); the store's own ref
+ * is then left out. A link counts only when it resolves to a direct child
+ * folder of the store at the same scope, and the skill is then read through
+ * the store's own path, never through the link. Any other link is skipped.
+ *
+ * Provenance (user-level store only): a skill with an entry in the installer
+ * lock carries `origin: {kind: installed, ...}`; one without carries
+ * `origin: {kind: authored}`. Nothing else is read from the lock, and a
+ * missing, linked, oversized or malformed lock never fails a scan.
+ *
+ * Scope: one skill at a time. By default a participant lists only the skills
+ * the person approved one by one with `bourdon skills share` (stored locally
+ * in `<library>/.skill-shares.json`, see skill-shares.ts), and only while the
+ * folder still hashes to the approved content; no other skill folder is read.
+ * `BOURDON_SKILLS_ADVERTISE` set to an on value lists every skill; an off
+ * value or an unrecognised one lists none, shared or not. A caller that builds
+ * a participant with explicit `skillSources` lists every skill in them
+ * ({@link skillsListingMode}). The directories: user-level skill directories,
+ * and a project's directories
+ * only when the project is named in `BOURDON_SKILL_PROJECTS` (absolute paths
+ * separated by the platform's path delimiter). Disallowed files are skipped
+ * and flagged, never fatal; no link is followed; no absolute path reaches the
+ * manifest (`path_hint` starts at a symbolic root); refs are emitted as
+ * `team`.
+ */
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, normalize } from "node:path";
+import { Visibility, makeSkillRef, } from "@getbourdon/l5";
+import { containsSecret } from "@getbourdon/redaction";
+import { SkillContentError, codePointLength, codePointSlice, compareUtf8, isPathLinkOrReparse, pyStrip, scanLocalSkill, } from "./skill-index.js";
+import { loadShares, shareAppliesTo } from "./skill-shares.js";
+/** Opt-in list of project roots whose skill directories may be indexed. */
+export const SKILL_PROJECTS_ENV = "BOURDON_SKILL_PROJECTS";
+/**
+ * The listing switch for every participant. Skill descriptions are free text
+ * and can name private projects, clients or infrastructure, so by default
+ * (unset or empty) only the skills approved one by one are listed. `1` /
+ * `true` / `yes` / `on` list every skill; `0` / `false` / `no` / `off` list
+ * none, approved or not, and so does any other value (fail closed): a typo
+ * never lists anything.
+ */
+export const SKILLS_ADVERTISE_ENV = "BOURDON_SKILLS_ADVERTISE";
+/**
+ * Turns named participants off in every mode: agent ids separated by commas
+ * (or whitespace), e.g. `codex,cursor`. Matching ignores case.
+ */
+export const SKILLS_NO_ADVERTISE_ENV = "BOURDON_SKILLS_NO_ADVERTISE";
+/** {@link skillsListingMode} results. */
+export const LIST_ALL = "all";
+export const LIST_APPROVED = "approved";
+export const LIST_OFF = "off";
+const ADVERTISE_ON = new Set(["1", "true", "yes", "on"]);
+const ADVERTISE_OFF = new Set(["0", "false", "no", "off"]);
+// A run of str.split() whitespace.
+// eslint-disable-next-line no-control-regex
+const PY_WHITESPACE_RUN = /[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/;
+/** Every advertised ref carries this visibility. */
+export const SKILL_REF_VISIBILITY = Visibility.TEAM;
+/** The L5 schema bounds (`skills.maxItems` and the `SkillRef` fields). */
+export const MAX_SKILL_REFS = 512;
+export const MAX_SKIPPED_FILES = 32;
+export const MAX_PATH_HINT_CHARS = 255;
+export const MAX_PROJECT_NAME_CHARS = 128;
+export const MAX_ORIGIN_SOURCE_CHARS = 255;
+export const MAX_ORIGIN_URL_CHARS = 512;
+export const MAX_ORIGIN_SOURCE_TYPE_CHARS = 32;
+/** An installer lock larger than this is not read (origin is then omitted). */
+export const MAX_LOCK_BYTES = 4 * 1024 * 1024;
+export const SCOPE_USER = "user";
+export const SCOPE_PROJECT = "project";
+/** Whose directory a skill folder sits in; `agent` is the default and never written. */
+export const STORE_AGENT = "agent";
+export const STORE_CROSS_AGENT = "cross_agent";
+export const VIA_COPY = "copy";
+export const VIA_LINK = "link";
+export const ORIGIN_INSTALLED = "installed";
+export const ORIGIN_AUTHORED = "authored";
+/** The cross-agent installer's lock file, beside the user-level store. */
+export const CROSS_AGENT_LOCK_NAME = ".skill-lock.json";
+// Kept in step with $defs/SkillRef.origin in the L5 schema.
+const ORIGIN_SOURCE_RE = /^[A-Za-z0-9][A-Za-z0-9._~/:+-]*$/;
+const ORIGIN_SOURCE_TYPE_RE = /^[a-z0-9][a-z0-9_-]*$/;
+const ORIGIN_URL_RE = /^https?:\/\/[^\s/?#@]+(\/[^\s?#]*)?$/;
+function warn(message) {
+    console.warn(`[bourdon.participants] ${message}`);
+}
+/** The home directory user-level skill directories are found under. */
+export function userHome() {
+    return homedir();
+}
+// -- sources ------------------------------------------------------------------
+function expandUser(path) {
+    if (path === "~")
+        return userHome();
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(userHome(), path.slice(2));
+    return path;
+}
+function isAbsoluteProjectPath(path) {
+    if (process.platform === "win32") {
+        // A Windows path is absolute only with a drive and a root, or as UNC.
+        return /^[A-Za-z]:[\\/]/.test(path) || /^[\\/]{2}[^\\/]/.test(path);
+    }
+    return isAbsolute(path);
+}
+function pathKey(path) {
+    const normalized = normalize(path);
+    const trimmed = normalized.replace(/[\\/]+$/, "");
+    return trimmed === "" || /^[A-Za-z]:$/.test(trimmed) ? normalized : trimmed;
+}
+/**
+ * Project roots opted in through {@link SKILL_PROJECTS_ENV}, in order. Only
+ * absolute paths count: a relative entry is ignored (and logged) rather than
+ * resolved against whatever directory the export happens to run in.
+ */
+export function skillProjects() {
+    const raw = process.env[SKILL_PROJECTS_ENV] ?? "";
+    const projects = [];
+    const seen = new Set();
+    for (const entry of raw.split(delimiter)) {
+        const text = pyStrip(entry);
+        if (!text)
+            continue;
+        const path = expandUser(text);
+        if (!isAbsoluteProjectPath(path)) {
+            warn(`${SKILL_PROJECTS_ENV}: ignoring relative entry (use an absolute path)`);
+            continue;
+        }
+        const key = pathKey(path);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        projects.push(key);
+    }
+    return projects;
+}
+function projectName(project) {
+    const name = basename(pathKey(project)) || "project";
+    return codePointSlice(name, MAX_PROJECT_NAME_CHARS);
+}
+function projectSources(projects, relative, store = STORE_AGENT) {
+    const chosen = projects === undefined ? skillProjects() : [...projects];
+    return chosen.map((project) => ({
+        root: join(project, ...relative.split("/")),
+        scope: SCOPE_PROJECT,
+        label: relative,
+        project: projectName(project),
+        store,
+        lockFile: null,
+    }));
+}
+function homeOverride(...names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value)
+            return [expandUser(value), `$${name}`];
+    }
+    return null;
+}
+/**
+ * Claude Code: `<config dir>/skills` and, on opt-in, `<project>/.claude/skills`.
+ * The config directory is `CLAUDE_CONFIG_DIR` (Claude Code's own override),
+ * else `CLAUDE_HOME`, else `~/.claude`.
+ */
+export function claudeCodeSkillSources(options = {}) {
+    const override = homeOverride("CLAUDE_CONFIG_DIR", "CLAUDE_HOME");
+    let user;
+    if (override !== null) {
+        const [configDir, label] = override;
+        user = { root: join(configDir, "skills"), scope: SCOPE_USER, label: `${label}/skills` };
+    }
+    else {
+        const base = options.home ?? userHome();
+        user = { root: join(base, ".claude", "skills"), scope: SCOPE_USER, label: "~/.claude/skills" };
+    }
+    return [user, ...projectSources(options.projects, ".claude/skills")];
+}
+/**
+ * Codex: `$CODEX_HOME/skills`. `codexHome` is an explicit Codex home, if one
+ * was given; otherwise `CODEX_HOME`, else `~/.codex`. Codex keeps its bundled
+ * skills in a hidden `.system` folder there, which is not indexed. The mirror
+ * has no Codex participant yet; this is the source a Codex reader would use.
+ */
+export function codexSkillSources(options = {}) {
+    if (options.codexHome != null) {
+        return [
+            { root: join(options.codexHome, "skills"), scope: SCOPE_USER, label: "$CODEX_HOME/skills" },
+        ];
+    }
+    const override = homeOverride("CODEX_HOME");
+    if (override !== null) {
+        const [root, label] = override;
+        return [{ root: join(root, "skills"), scope: SCOPE_USER, label: `${label}/skills` }];
+    }
+    const base = options.home ?? userHome();
+    return [{ root: join(base, ".codex", "skills"), scope: SCOPE_USER, label: "~/.codex/skills" }];
+}
+/**
+ * Cursor: `~/.cursor/skills` and, on opt-in, `<project>/.cursor/skills`.
+ * `CURSOR_HOME` overrides `~/.cursor`. `~/.cursor/skills-cursor` holds
+ * Cursor's own built-in skills and is not indexed.
+ */
+export function cursorSkillSources(options = {}) {
+    const override = homeOverride("CURSOR_HOME");
+    let user;
+    if (override !== null) {
+        const [root, label] = override;
+        user = { root: join(root, "skills"), scope: SCOPE_USER, label: `${label}/skills` };
+    }
+    else {
+        const base = options.home ?? userHome();
+        user = { root: join(base, ".cursor", "skills"), scope: SCOPE_USER, label: "~/.cursor/skills" };
+    }
+    return [user, ...projectSources(options.projects, ".cursor/skills")];
+}
+/**
+ * The vendor-neutral store: `~/.agents/skills` and, on opt-in,
+ * `<project>/.agents/skills`. The user-level store comes with the installer
+ * lock for provenance; no lock is read for a project store.
+ */
+export function crossAgentSkillSources(options = {}) {
+    const base = options.home ?? userHome();
+    const agentsDir = join(base, ".agents");
+    const user = {
+        root: join(agentsDir, "skills"),
+        scope: SCOPE_USER,
+        label: "~/.agents/skills",
+        store: STORE_CROSS_AGENT,
+        lockFile: join(agentsDir, CROSS_AGENT_LOCK_NAME),
+    };
+    return [user, ...projectSources(options.projects, ".agents/skills", STORE_CROSS_AGENT)];
+}
+function isDict(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/**
+ * The `skills` table of the installer lock, keyed by skill name. An empty map
+ * when there is no lock (every store skill is then `authored`); `null` when a
+ * lock exists but cannot be trusted or parsed (a link, not a regular file, too
+ * large, not JSON, or without a `skills` mapping), in which case origin is left
+ * off rather than guessed.
+ */
+export function readInstallLock(path) {
+    let info;
+    try {
+        info = lstatSync(path);
+    }
+    catch (err) {
+        return err.code === "ENOENT" ? new Map() : null;
+    }
+    let data;
+    try {
+        if (isPathLinkOrReparse(path, info) || !info.isFile())
+            return null;
+        if (info.size > MAX_LOCK_BYTES)
+            return null;
+        data = JSON.parse(STRICT_UTF8.decode(readFileSync(path)));
+    }
+    catch {
+        return null;
+    }
+    if (!isDict(data))
+        return null;
+    const skills = data.skills;
+    if (!isDict(skills))
+        return null;
+    const table = new Map();
+    for (const [name, entry] of Object.entries(skills)) {
+        if (isDict(entry))
+            table.set(name, entry);
+    }
+    return table;
+}
+function cleanSource(value) {
+    if (typeof value !== "string")
+        return null;
+    const text = pyStrip(value);
+    if (!text || codePointLength(text) > MAX_ORIGIN_SOURCE_CHARS)
+        return null;
+    if (!ORIGIN_SOURCE_RE.test(text) || containsSecret(text))
+        return null;
+    return text;
+}
+function cleanSourceType(value) {
+    if (typeof value !== "string")
+        return null;
+    const text = pyStrip(value);
+    if (!text || codePointLength(text) > MAX_ORIGIN_SOURCE_TYPE_CHARS)
+        return null;
+    return ORIGIN_SOURCE_TYPE_RE.test(text) ? text : null;
+}
+// urllib.parse.urlsplit: leading C0 control/space stripped, tab/CR/LF removed.
+// eslint-disable-next-line no-control-regex
+const URL_LEADING_JUNK_RE = /^[\x00-\x20]+/;
+const URL_UNSAFE_RE = /[\t\r\n]/g;
+const URL_SCHEME_RE = /^([A-Za-z][A-Za-z0-9+.-]*):/;
+/** The scheme, netloc and path of `value` as Python's `urlsplit` reads them, or null on its ValueError. */
+function urlSplit(value) {
+    let url = value.replace(URL_LEADING_JUNK_RE, "").replace(URL_UNSAFE_RE, "");
+    let scheme = "";
+    const schemeMatch = URL_SCHEME_RE.exec(url);
+    if (schemeMatch) {
+        scheme = (schemeMatch[1] ?? "").toLowerCase();
+        url = url.slice(schemeMatch[0].length);
+    }
+    let netloc = "";
+    if (url.startsWith("//")) {
+        const rest = url.slice(2);
+        const delim = rest.search(/[/?#]/);
+        netloc = delim === -1 ? rest : rest.slice(0, delim);
+        url = delim === -1 ? "" : rest.slice(delim);
+        if (netloc.includes("[") !== netloc.includes("]"))
+            return null;
+    }
+    const hash = url.indexOf("#");
+    if (hash !== -1)
+        url = url.slice(0, hash);
+    const query = url.indexOf("?");
+    if (query !== -1)
+        url = url.slice(0, query);
+    return { scheme, netloc, path: url };
+}
+function urlHostname(netloc) {
+    const hostinfo = netloc.slice(netloc.lastIndexOf("@") + 1);
+    let host;
+    if (hostinfo.startsWith("[")) {
+        const close = hostinfo.indexOf("]");
+        host = close === -1 ? "" : hostinfo.slice(1, close);
+    }
+    else {
+        const colon = hostinfo.indexOf(":");
+        host = colon === -1 ? hostinfo : hostinfo.slice(0, colon);
+    }
+    return host ? host.toLowerCase() : null;
+}
+/** An http(s) URL without credentials; query string and fragment dropped. */
+function cleanSourceUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    const parts = urlSplit(pyStrip(value));
+    if (parts === null)
+        return null;
+    if ((parts.scheme !== "http" && parts.scheme !== "https") || !urlHostname(parts.netloc)) {
+        return null;
+    }
+    // Credentials in the URL: drop it rather than try to repair it.
+    if (parts.netloc.includes("@"))
+        return null;
+    const url = `${parts.scheme}://${parts.netloc}${parts.path}`;
+    if (codePointLength(url) > MAX_ORIGIN_URL_CHARS || !ORIGIN_URL_RE.test(url))
+        return null;
+    return containsSecret(url) ? null : url;
+}
+// datetime.fromisoformat (3.11+): extended or basic date, any one-character
+// separator, then HH[:MM[:SS[.f+]]] or the basic forms, then an optional offset.
+const ISO_DATE_RE = /^(\d{4})-?(\d{2})-?(\d{2})/;
+const ISO_TIME_RE = /^(\d{2})(?::?(\d{2})(?::?(\d{2})(?:[.,](\d+))?)?)?/;
+const ISO_OFFSET_RE = /^([+-])(\d{2})(?::?(\d{2})(?::?(\d{2})(?:\.(\d+))?)?)?$/;
+function daysInMonth(year, month) {
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
+}
+function pad(value, width) {
+    return String(value).padStart(width, "0");
+}
+function cleanTimestamp(value) {
+    if (typeof value !== "string" || codePointLength(value) > 64)
+        return null;
+    let text = pyStrip(value);
+    if (text.endsWith("Z") || text.endsWith("z"))
+        text = `${text.slice(0, -1)}+00:00`;
+    const date = ISO_DATE_RE.exec(text);
+    if (!date)
+        return null;
+    const extendedDate = date[0].includes("-");
+    if (extendedDate && date[0].length !== 10)
+        return null;
+    if (!extendedDate && date[0].length !== 8)
+        return null;
+    const [year, month, day] = [Number(date[1]), Number(date[2]), Number(date[3])];
+    if (year < 1 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
+        return null;
+    }
+    let rest = text.slice(date[0].length);
+    let [hour, minute, second] = [0, 0, 0];
+    let offsetSeconds = 0;
+    if (rest.length > 0) {
+        const separator = Array.from(rest)[0] ?? "";
+        rest = rest.slice(separator.length);
+        const time = ISO_TIME_RE.exec(rest);
+        if (!time)
+            return null;
+        hour = Number(time[1]);
+        minute = time[2] === undefined ? 0 : Number(time[2]);
+        second = time[3] === undefined ? 0 : Number(time[3]);
+        if (hour > 23 || minute > 59 || second > 59)
+            return null;
+        rest = rest.slice(time[0].length);
+        if (rest.length > 0) {
+            const offset = ISO_OFFSET_RE.exec(rest);
+            if (!offset)
+                return null;
+            const oh = Number(offset[2]);
+            const om = offset[3] === undefined ? 0 : Number(offset[3]);
+            const os = offset[4] === undefined ? 0 : Number(offset[4]);
+            if (oh > 23 || om > 59 || os > 59)
+                return null;
+            offsetSeconds = (offset[1] === "-" ? -1 : 1) * (oh * 3600 + om * 60 + os);
+        }
+    }
+    const moment = new Date(0);
+    moment.setUTCFullYear(year, month - 1, day);
+    moment.setUTCHours(hour, minute, second, 0);
+    const utc = new Date(moment.getTime() - offsetSeconds * 1000);
+    const utcYear = utc.getUTCFullYear();
+    if (utcYear < 1 || utcYear > 9999)
+        return null;
+    return (`${pad(utcYear, 4)}-${pad(utc.getUTCMonth() + 1, 2)}-${pad(utc.getUTCDate(), 2)}` +
+        `T${pad(utc.getUTCHours(), 2)}:${pad(utc.getUTCMinutes(), 2)}:${pad(utc.getUTCSeconds(), 2)}Z`);
+}
+/**
+ * `installed` with the lock entry's sanitised source fields, else `authored`.
+ * Reads only `source`, `sourceType`, `sourceUrl` and `updatedAt`; a field
+ * that is missing, of the wrong type or fails its check is left out.
+ */
+export function originFromLockEntry(entry) {
+    if (entry == null)
+        return { kind: ORIGIN_AUTHORED };
+    return {
+        kind: ORIGIN_INSTALLED,
+        source: cleanSource(entry.source),
+        source_type: cleanSourceType(entry.sourceType),
+        source_url: cleanSourceUrl(entry.sourceUrl),
+        updated_at: cleanTimestamp(entry.updatedAt),
+    };
+}
+function sourceStore(source) {
+    return source.store ?? STORE_AGENT;
+}
+function skip(report, source, hint, reason) {
+    report.skipped.push({
+        pathHint: hint,
+        scope: source.scope,
+        reason,
+        project: source.project ?? null,
+    });
+}
+function listSource(source, report) {
+    const root = source.root;
+    let info;
+    try {
+        info = lstatSync(root);
+    }
+    catch {
+        return null; // no such directory: the agent simply has no skills here
+    }
+    if (isPathLinkOrReparse(root, info)) {
+        skip(report, source, source.label, "skills directory is a link; links are not followed");
+        return null;
+    }
+    if (!info.isDirectory())
+        return null;
+    try {
+        return readdirSync(root, { withFileTypes: true }).sort((a, b) => compareUtf8(a.name, b.name));
+    }
+    catch {
+        skip(report, source, source.label, "skills directory cannot be listed");
+        return null;
+    }
+}
+function makeRef(source, hint, folder, report) {
+    if (codePointLength(hint) > MAX_PATH_HINT_CHARS) {
+        skip(report, source, codePointSlice(hint, MAX_PATH_HINT_CHARS), "path is too long");
+        return null;
+    }
+    let scan;
+    try {
+        scan = scanLocalSkill(folder);
+    }
+    catch (err) {
+        if (err instanceof SkillContentError) {
+            skip(report, source, hint, err.problems.join("; "));
+        }
+        else {
+            skip(report, source, hint, "skill folder cannot be read");
+        }
+        return null;
+    }
+    return makeSkillRef({
+        name: scan.frontMatter.name,
+        description: scan.frontMatter.description,
+        content_sha256: scan.contentSha256,
+        scope: source.scope,
+        path_hint: hint,
+        project: source.project ?? null,
+        skipped_files: scan.skipped.slice(0, MAX_SKIPPED_FILES).map((item) => ({
+            path: codePointSlice(item.path, MAX_PATH_HINT_CHARS),
+            reason: item.reason,
+        })),
+        visibility: SKILL_REF_VISIBILITY,
+        store: sourceStore(source) === STORE_CROSS_AGENT ? STORE_CROSS_AGENT : null,
+    });
+}
+function realPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function normCase(path) {
+    const normalized = normalize(path);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+/**
+ * The store folder a linked agent skill folder resolves to, if any. Only the
+ * link's target path is resolved; nothing behind it is read. It counts only
+ * when it is a direct child of the store root and that child is itself a real
+ * folder, so the skill is then read through the store's own path.
+ */
+function storeMember(link, store) {
+    if (store === null || store.realRoot === null)
+        return null;
+    const target = realPath(link);
+    if (target === null)
+        return null;
+    const name = basename(target);
+    if (!name || normCase(dirname(target)) !== normCase(store.realRoot))
+        return null;
+    const member = join(store.source.root, name);
+    let info;
+    try {
+        info = lstatSync(member);
+    }
+    catch {
+        return null;
+    }
+    if (isPathLinkOrReparse(member, info) || !info.isDirectory())
+        return null;
+    return name;
+}
+function scanStore(source, report, wanted = null) {
+    const store = { source, realRoot: null, byFolder: new Map(), byHash: new Map() };
+    const found = [];
+    const children = listSource(source, report);
+    if (children === null)
+        return [store, found];
+    store.realRoot = realPath(source.root);
+    const lock = source.lockFile ? readInstallLock(source.lockFile) : null;
+    for (const entry of children) {
+        if (entry.name.startsWith("."))
+            continue; // tool-managed (a .git checkout), not a skill
+        if (wanted !== null && !wanted.has(entry.name))
+            continue; // not asked for: not read
+        const hint = `${source.label}/${entry.name}`;
+        const path = join(source.root, entry.name);
+        try {
+            if (isPathLinkOrReparse(path)) {
+                skip(report, source, hint, "skill folder is a link; links are not followed");
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+        }
+        catch {
+            skip(report, source, hint, "skill folder cannot be read");
+            continue;
+        }
+        const ref = makeRef(source, hint, path, report);
+        if (ref === null)
+            continue;
+        if (lock !== null) {
+            const lockEntry = lock.get(entry.name) ?? lock.get(ref.name);
+            ref.origin = originFromLockEntry(lockEntry);
+        }
+        const item = { source, folder: entry.name, ref, represents: null, represented: false };
+        found.push(item);
+        store.byFolder.set(entry.name, item);
+        if (!store.byHash.has(ref.content_sha256))
+            store.byHash.set(ref.content_sha256, item);
+    }
+    return [store, found];
+}
+function scanAgentDir(source, report, store, include = null) {
+    const found = [];
+    const children = listSource(source, report);
+    if (children === null)
+        return found;
+    for (const entry of children) {
+        if (entry.name.startsWith("."))
+            continue; // agent-managed (bundled) skills, not the user's
+        if (include !== null && !include(source, entry.name))
+            continue; // not asked for: not read
+        const hint = `${source.label}/${entry.name}`;
+        const path = join(source.root, entry.name);
+        let isLink;
+        try {
+            isLink = isPathLinkOrReparse(path);
+            if (!isLink && !entry.isDirectory())
+                continue; // a loose file beside the skill folders
+        }
+        catch {
+            skip(report, source, hint, "skill folder cannot be read");
+            continue;
+        }
+        if (isLink) {
+            const member = storeMember(path, store);
+            if (store === null || member === null) {
+                skip(report, source, hint, "skill folder is a link; links are not followed");
+                continue;
+            }
+            const shared = store.byFolder.get(member);
+            if (shared === undefined) {
+                skip(report, source, hint, "skill folder links to a cross-agent skill that is not advertised");
+                continue;
+            }
+            if (codePointLength(hint) > MAX_PATH_HINT_CHARS) {
+                skip(report, source, codePointSlice(hint, MAX_PATH_HINT_CHARS), "path is too long");
+                continue;
+            }
+            const linked = makeSkillRef({
+                ...shared.ref,
+                scope: source.scope,
+                project: source.project ?? null,
+                path_hint: hint,
+                store: null,
+                also_in: { path_hint: shared.ref.path_hint, via: VIA_LINK },
+            });
+            found.push({ source, folder: entry.name, ref: linked, represents: shared, represented: false });
+            continue;
+        }
+        const ref = makeRef(source, hint, path, report);
+        if (ref === null)
+            continue;
+        const copy = store !== null ? (store.byHash.get(ref.content_sha256) ?? null) : null;
+        let advertised = ref;
+        if (copy !== null) {
+            advertised = makeSkillRef({
+                ...ref,
+                also_in: { path_hint: copy.ref.path_hint, via: VIA_COPY },
+                origin: copy.ref.origin ?? null,
+            });
+        }
+        found.push({ source, folder: entry.name, ref: advertised, represents: copy, represented: false });
+    }
+    return found;
+}
+function childNames(root) {
+    try {
+        return readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Store folders that an included agent folder links to. Only link targets are
+ * resolved (no skill file is read), so a link the caller asked for is still
+ * read through the store's own folder.
+ */
+function linkedStoreMembers(storeSource, agentSources, include) {
+    const members = new Set();
+    const realRoot = realPath(storeSource.root);
+    if (realRoot === null)
+        return members;
+    for (const source of agentSources) {
+        if (source.scope !== storeSource.scope ||
+            (source.project ?? null) !== (storeSource.project ?? null)) {
+            continue;
+        }
+        for (const name of childNames(source.root)) {
+            if (name.startsWith(".") || !include(source, name))
+                continue;
+            const path = join(source.root, name);
+            let target;
+            try {
+                if (!isPathLinkOrReparse(path))
+                    continue;
+                target = realPath(path);
+            }
+            catch {
+                continue;
+            }
+            if (target === null)
+                continue;
+            const member = basename(target);
+            if (member && normCase(dirname(target)) === normCase(realRoot))
+                members.add(member);
+        }
+    }
+    return members;
+}
+/**
+ * Index every source; one ref per skill, first occurrence of a name wins per
+ * store and scope. Cross-agent stores are scanned first so the agent's own
+ * folders can be matched against them (`also_in`). Refs come back with the
+ * agent's own folders first, in source order, then the cross-agent store
+ * skills that no advertised agent folder already represents.
+ */
+export function scanSkillSources(sources, options = {}) {
+    const include = options.include ?? null;
+    const ordered = [...sources];
+    const report = { refs: [], skipped: [] };
+    const stores = new Map();
+    const perSource = new Map();
+    const storeKey = (source) => JSON.stringify([source.scope, source.project ?? null]);
+    const agentSources = ordered.filter((source) => sourceStore(source) !== STORE_CROSS_AGENT);
+    ordered.forEach((source, index) => {
+        if (sourceStore(source) !== STORE_CROSS_AGENT)
+            return;
+        const key = storeKey(source);
+        if (stores.has(key))
+            return; // one store per scope; a repeat would only duplicate it
+        let wanted = null;
+        if (include !== null) {
+            wanted = linkedStoreMembers(source, agentSources, include);
+            for (const name of childNames(source.root)) {
+                if (include(source, name))
+                    wanted.add(name);
+            }
+        }
+        const [store, found] = scanStore(source, report, wanted);
+        stores.set(key, store);
+        perSource.set(index, found);
+    });
+    ordered.forEach((source, index) => {
+        if (sourceStore(source) === STORE_CROSS_AGENT)
+            return;
+        perSource.set(index, scanAgentDir(source, report, stores.get(storeKey(source)) ?? null, include));
+    });
+    const seen = new Map();
+    const indexed = ordered.map((source, index) => [index, source]);
+    const agentFirst = [
+        ...indexed.filter(([, source]) => sourceStore(source) !== STORE_CROSS_AGENT),
+        ...indexed.filter(([, source]) => sourceStore(source) === STORE_CROSS_AGENT),
+    ];
+    for (const [index, source] of agentFirst) {
+        for (const item of perSource.get(index) ?? []) {
+            if (item.represented)
+                continue;
+            const ref = item.ref;
+            const nameKey = JSON.stringify([
+                ref.store ?? STORE_AGENT,
+                ref.scope,
+                ref.project ?? null,
+                ref.name,
+            ]);
+            const advertisedAt = seen.get(nameKey);
+            if (advertisedAt !== undefined) {
+                skip(report, source, ref.path_hint, `duplicate skill name '${ref.name}' (advertised: ${advertisedAt})`);
+                continue;
+            }
+            if (report.refs.length >= MAX_SKILL_REFS) {
+                skip(report, source, ref.path_hint, `more than ${MAX_SKILL_REFS} skills`);
+                continue;
+            }
+            seen.set(nameKey, ref.path_hint);
+            report.refs.push(ref);
+            if (item.represents !== null)
+                item.represents.represented = true;
+        }
+    }
+    return report;
+}
+function perAgentOff(agentId) {
+    const quiet = process.env[SKILLS_NO_ADVERTISE_ENV] ?? "";
+    const names = new Set(pyStrip(quiet.replaceAll(",", " "))
+        .split(PY_WHITESPACE_RUN)
+        .map((item) => pyStrip(item).toLowerCase())
+        .filter((item) => item !== ""));
+    return names.has(pyStrip(agentId).toLowerCase());
+}
+/**
+ * Which skills the participant `agentId` may list in its manifest.
+ *
+ *  - {@link LIST_APPROVED}: {@link SKILLS_ADVERTISE_ENV} unset or empty: only
+ *    the skills approved one by one (`bourdon skills share`) whose folder still
+ *    hashes to the approved content.
+ *  - {@link LIST_ALL}: an on value; or, while the variable is unset, a
+ *    participant built with explicit `skillSources` (the caller chose what to
+ *    index).
+ *  - {@link LIST_OFF}: an off value, or any unrecognised one (fail closed):
+ *    nothing is listed, approved or not.
+ *
+ * {@link SKILLS_NO_ADVERTISE_ENV} turns named participants off in every mode.
+ */
+export function skillsListingMode(agentId, options = {}) {
+    const raw = process.env[SKILLS_ADVERTISE_ENV];
+    const value = pyStrip(raw ?? "").toLowerCase();
+    let mode;
+    if (ADVERTISE_ON.has(value)) {
+        mode = LIST_ALL;
+    }
+    else if (value === "") {
+        mode = options.explicitSources ? LIST_ALL : LIST_APPROVED;
+    }
+    else {
+        if (!ADVERTISE_OFF.has(value)) {
+            warn(`${SKILLS_ADVERTISE_ENV}=${JSON.stringify(raw)} is not a recognised on/off value; ` +
+                "not listing skills");
+        }
+        return LIST_OFF;
+    }
+    return perAgentOff(agentId) ? LIST_OFF : mode;
+}
+/**
+ * Whether the participant `agentId` lists every skill it can see: true only
+ * in {@link LIST_ALL} mode ({@link skillsListingMode}). In the default mode a
+ * participant lists only the skills shared one by one.
+ */
+export function skillsAdvertisingEnabled(agentId, options = {}) {
+    return skillsListingMode(agentId, options) === LIST_ALL;
+}
+/**
+ * Approved-only mode: the participant's skills that hold a current approval.
+ * Reads only the approved folders (and a store folder an approved link points
+ * at); with nothing approved, nothing is read.
+ */
+function sharedRefs(participant, agentId) {
+    const shares = loadShares().filter((share) => shareAppliesTo(share, agentId));
+    if (shares.length === 0)
+        return [];
+    const approved = new Set(shares.map((s) => JSON.stringify([s.scope, s.project, s.pathHint, s.contentSha256])));
+    const hints = new Set(shares.map((s) => JSON.stringify([s.scope, s.project, s.pathHint])));
+    let refs;
+    if (typeof participant.skillSources === "function") {
+        const include = (source, name) => hints.has(JSON.stringify([source.scope, source.project ?? null, `${source.label}/${name}`]));
+        refs = scanSkillSources(participant.skillSources(), { include }).refs;
+    }
+    else {
+        // A reader without skill sources: its own scan, approved refs kept.
+        refs = [...participant.exportSkills()];
+    }
+    return refs.filter((ref) => approved.has(JSON.stringify([ref.scope, ref.project ?? null, ref.path_hint, ref.content_sha256])));
+}
+/**
+ * The refs `participant`'s manifest carries, for `exportL5`.
+ *
+ * Follows {@link skillsListingMode}: nothing, and no skill directory read,
+ * when off; by default only the skills with a current approval, reading only
+ * their folders; every skill the reader sees when listing all. A participant
+ * built with explicit `skillSources` lists all unless turned off. A failure
+ * here never fails an export: skills are an addition to the manifest, not a
+ * reason to lose its memory rows. Private refs are dropped, as private
+ * entities are.
+ */
+export function advertisedSkills(participant) {
+    const agentId = String(participant.agentId ?? "");
+    const explicitSources = participant.hasExplicitSkillSources?.() === true;
+    const mode = skillsListingMode(agentId, { explicitSources });
+    if (mode === LIST_OFF)
+        return [];
+    let refs;
+    try {
+        refs = mode === LIST_APPROVED ? sharedRefs(participant, agentId) : [...participant.exportSkills()];
+    }
+    catch (err) {
+        warn(`skill readers: ${agentId} skipped skill export: ${String(err)}`);
+        return [];
+    }
+    return refs.filter((ref) => ref.visibility !== Visibility.PRIVATE);
+}
+// -- proposal side: back from an advertised ref to its folder -----------------
+/**
+ * The default skill directories of a built-in skill-reading participant.
+ *
+ * The same directories the participant's own export reads (its user-level
+ * directory honouring its home override, the opted-in projects, and the
+ * cross-agent store). `null` for an agent with no skill reader here, so a skill
+ * it advertises can be listed but not proposed from this machine.
+ */
+export function skillSourcesForAgent(agentId) {
+    const builders = {
+        "claude-code": () => claudeCodeSkillSources(),
+        codex: () => codexSkillSources(),
+        cursor: () => cursorSkillSources(),
+    };
+    const build = Object.hasOwn(builders, agentId) ? builders[agentId] : undefined;
+    if (build === undefined)
+        return null;
+    return [...build(), ...crossAgentSkillSources()];
+}
+function folderForHint(sources, pathHint, scope, project) {
+    for (const source of sources) {
+        if (source.scope !== scope || (source.project ?? null) !== (project ?? null))
+            continue;
+        const prefix = `${source.label}/`;
+        if (!pathHint.startsWith(prefix))
+            continue;
+        const folder = pathHint.slice(prefix.length);
+        if (!folder ||
+            folder === "." ||
+            folder === ".." ||
+            folder.includes("/") ||
+            folder.includes("\\")) {
+            return null;
+        }
+        return join(source.root, folder);
+    }
+    return null;
+}
+/**
+ * The folder an advertised ref was scanned from, found through `sources` only.
+ *
+ * `ref` is a SkillRef as it sits in a manifest. Its `path_hint` is matched
+ * against each source's symbolic label (same scope and project), so the result
+ * is always one direct child of a directory the reader indexes; a path from
+ * anywhere else cannot be produced. A ref that is a link into the cross-agent
+ * store resolves to the store's own folder, as the reader read it. `null` when
+ * nothing matches.
+ */
+export function resolveAdvertisedFolder(sources, ref) {
+    const hint = ref.path_hint;
+    if (typeof hint !== "string")
+        return null;
+    const scope = ref.scope;
+    const project = ref.project;
+    const alsoIn = ref.also_in;
+    const isCrossAgent = (s) => s.store === STORE_CROSS_AGENT;
+    if (isDict(alsoIn) && alsoIn.via === VIA_LINK) {
+        const storeHint = alsoIn.path_hint;
+        if (typeof storeHint !== "string")
+            return null;
+        return folderForHint(sources.filter(isCrossAgent), storeHint, scope, project);
+    }
+    const chosen = ref.store === STORE_CROSS_AGENT
+        ? sources.filter(isCrossAgent)
+        : sources.filter((s) => !isCrossAgent(s));
+    return folderForHint(chosen, hint, scope, project);
+}
+// -- the local share commands: what this machine's readers can see -------------
+/** The built-in skill readers, in listing order. */
+export const SKILL_READERS = ["claude-code", "codex", "cursor"];
+/**
+ * Every skill folder the built-in readers see on this machine (each one is
+ * read). The same directories the readers' exports use: user-level, opted-in
+ * projects and the cross-agent store. One row per folder; a store folder seen
+ * by several readers is one row naming them all. `agent` keeps the folders
+ * that one reader sees.
+ */
+export function localSkills(agent = null) {
+    const rows = new Map();
+    for (const reader of SKILL_READERS) {
+        if (agent !== null && reader !== agent)
+            continue;
+        const sources = skillSourcesForAgent(reader) ?? [];
+        for (const ref of scanSkillSources(sources).refs) {
+            const owner = ref.store === STORE_CROSS_AGENT ? null : reader;
+            const store = ref.store || STORE_AGENT;
+            const key = JSON.stringify([owner, store, ref.scope, ref.project ?? null, ref.path_hint]);
+            const row = rows.get(key);
+            if (row !== undefined) {
+                if (!row.agents.includes(reader))
+                    row.agents.push(reader);
+                continue;
+            }
+            const alsoIn = ref.also_in
+                ? { path_hint: ref.also_in.path_hint, via: ref.also_in.via }
+                : null;
+            const folder = resolveAdvertisedFolder(sources, {
+                path_hint: ref.path_hint,
+                scope: ref.scope,
+                project: ref.project ?? null,
+                store: ref.store ?? null,
+                also_in: alsoIn,
+            });
+            if (folder !== null)
+                rows.set(key, { ref, agent: owner, agents: [reader], folder, store });
+        }
+    }
+    return [...rows.values()];
+}