dsh-skill-compat-plus 0.0.0-stage → 0.1.0

package/lib/index.js

@@ -0,0 +1,761 @@
+// src/config.ts
+var CONFIG_KEYS = [
+  "providerName",
+  "sources",
+  "extraDirs",
+  "watch",
+  "watchUsePolling",
+  "watchStabilityThresholdMs",
+  "watchPollIntervalMs",
+  "watchMaxProjects",
+  "slugifyNames",
+  "synthesizeDescription"
+];
+var SOURCE_KEYS = ["enabled", "project", "root", "rank"];
+var SOURCE_IDS = ["claude", "codex", "zcode"];
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function booleanField(source, key) {
+  const value = source[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "boolean") throw new Error(`config field "${key}" must be a boolean, got ${typeof value}`);
+  return value;
+}
+function positiveNumberField(source, key) {
+  const value = source[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`config field "${key}" must be a positive finite number`);
+  }
+  return value;
+}
+function stringField(source, key) {
+  const value = source[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`config field "${key}" must be a non-empty string`);
+  }
+  return value;
+}
+function resolveSourceOption(id, option) {
+  const settings = { enabled: true, project: true };
+  if (option === void 0 || typeof option === "boolean") {
+    settings.enabled = option !== false;
+    return settings;
+  }
+  if (!isPlainObject(option)) {
+    throw new Error(`config sources.${id} must be a boolean or an object`);
+  }
+  for (const key of Object.keys(option)) {
+    if (!SOURCE_KEYS.includes(key)) {
+      throw new Error(`unknown config sources.${id} key "${key}" (expected ${SOURCE_KEYS.join(", ")})`);
+    }
+  }
+  const enabled = booleanField(option, "enabled");
+  const project = booleanField(option, "project");
+  const root = stringField(option, "root");
+  const rank = option.rank;
+  if (rank !== void 0 && (typeof rank !== "number" || !Number.isFinite(rank))) {
+    throw new Error("config sources rank must be a finite number");
+  }
+  return {
+    enabled: enabled ?? true,
+    project: project ?? true,
+    root,
+    rank
+  };
+}
+function resolveExtraDirs(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) throw new Error("config extraDirs must be an array");
+  const dirs = [];
+  for (const raw of value) {
+    if (!isPlainObject(raw)) throw new Error("config extraDirs entries must be objects like { path, label?, rank? }");
+    for (const key of Object.keys(raw)) {
+      if (!["path", "label", "rank"].includes(key)) {
+        throw new Error(`unknown config extraDirs entry key "${key}" (expected path, label, rank)`);
+      }
+    }
+    const path = stringField(raw, "path");
+    if (path === void 0) throw new Error('config extraDirs entry requires a non-empty "path"');
+    const label = stringField(raw, "label") ?? "custom";
+    const rank = raw.rank;
+    if (rank !== void 0 && (typeof rank !== "number" || !Number.isFinite(rank))) {
+      throw new Error("config extraDirs entry rank must be a finite number");
+    }
+    dirs.push({ path, label, rank: rank ?? 300 });
+  }
+  return dirs;
+}
+function resolveConfig(input) {
+  if (input !== void 0 && !isPlainObject(input)) {
+    throw new Error("plugin config must be an object");
+  }
+  const source = input ?? {};
+  for (const key of Object.keys(source)) {
+    if (!CONFIG_KEYS.includes(key)) {
+      throw new Error(`unknown plugin config key "${key}" (expected ${CONFIG_KEYS.join(", ")})`);
+    }
+  }
+  const providerName = stringField(source, "providerName") ?? "skill-compat-plus";
+  if (providerName === "runtime") {
+    throw new Error('config providerName "runtime" is reserved by the dsh skill registry');
+  }
+  const rawSources = source.sources;
+  if (rawSources !== void 0 && !isPlainObject(rawSources)) {
+    throw new Error("config sources must be an object with keys claude, codex, zcode");
+  }
+  for (const key of Object.keys(rawSources ?? {})) {
+    if (!SOURCE_IDS.includes(key)) {
+      throw new Error(`unknown config sources key "${key}" (expected ${SOURCE_IDS.join(", ")})`);
+    }
+  }
+  const sources = {
+    claude: resolveSourceOption("claude", rawSources?.claude),
+    codex: resolveSourceOption("codex", rawSources?.codex),
+    zcode: resolveSourceOption("zcode", rawSources?.zcode)
+  };
+  const watch2 = booleanField(source, "watch") ?? true;
+  const watchUsePolling = booleanField(source, "watchUsePolling") ?? false;
+  const watchStabilityThresholdMs = positiveNumberField(source, "watchStabilityThresholdMs") ?? 200;
+  const watchPollIntervalMs = positiveNumberField(source, "watchPollIntervalMs") ?? 100;
+  const watchMaxProjects = positiveNumberField(source, "watchMaxProjects") ?? 128;
+  const slugifyNames = booleanField(source, "slugifyNames") ?? true;
+  const synthesizeDescription2 = booleanField(source, "synthesizeDescription") ?? true;
+  const extraDirs = resolveExtraDirs(source.extraDirs);
+  const anySourceEnabled = sources.claude.enabled || sources.codex.enabled || sources.zcode.enabled || extraDirs.length > 0;
+  return Object.freeze({
+    providerName,
+    sources,
+    extraDirs: Object.freeze(extraDirs),
+    watch: watch2,
+    watchUsePolling,
+    watchStabilityThresholdMs,
+    watchPollIntervalMs,
+    watchMaxProjects,
+    slugifyNames,
+    synthesizeDescription: synthesizeDescription2,
+    anySourceEnabled
+  });
+}
+
+// src/provider.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { basename as basename2 } from "node:path";
+
+// src/frontmatter.ts
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+var SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isSkillName(name2) {
+  return SKILL_NAME.test(name2);
+}
+function splitFrontmatter(raw) {
+  const firstLineEnd = raw.indexOf("\n");
+  if (firstLineEnd < 0) return void 0;
+  const firstLine = raw.slice(0, firstLineEnd).replace(/\r$/, "");
+  if (firstLine !== "---") return void 0;
+  const start = firstLineEnd + 1;
+  let lineStart = start;
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf("\n", lineStart);
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+    const line = raw.slice(lineStart, lineEnd).replace(/\r$/, "");
+    if (line === "---") {
+      const yamlText = raw.slice(start, lineStart);
+      let parsed;
+      try {
+        parsed = parseYaml(yamlText);
+      } catch {
+        return void 0;
+      }
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+      return { data: parsed, body: raw.slice(nextNewline < 0 ? raw.length : nextNewline + 1) };
+    }
+    if (nextNewline < 0) return void 0;
+    lineStart = nextNewline + 1;
+  }
+  return void 0;
+}
+var LEGACY_INVOCATION_KEYS = ["disableModelInvocation", "modelInvocable", "userInvocable"];
+function lenientBoolean(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (value === 1) return true;
+    if (value === 0) return false;
+    return void 0;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "yes", "on", "1"].includes(normalized)) return true;
+    if (["false", "no", "off", "0"].includes(normalized)) return false;
+  }
+  return void 0;
+}
+function slugifySkillName(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function firstMeaningfulText(text) {
+  for (const line of text.split(/\r?\n/)) {
+    const stripped = line.replace(/^\s*#+\s*/, "").trim();
+    if (stripped.length > 0) return stripped;
+  }
+  return "";
+}
+function synthesizeDescription(body) {
+  const text = firstMeaningfulText(body);
+  if (text.length <= 200) return text;
+  const slice = text.slice(0, 200);
+  const lastSpace = slice.lastIndexOf(" ");
+  return (lastSpace >= 160 ? slice.slice(0, lastSpace) : slice) + "\u2026";
+}
+function stringField2(data, key) {
+  const value = data[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function mapForeignSkill(input) {
+  const { parsed, filePath } = input;
+  const data = parsed.data;
+  for (const key of LEGACY_INVOCATION_KEYS) {
+    if (key in data) {
+      return {
+        ok: false,
+        reason: `frontmatter field "${key}" is unsupported; use "disable-model-invocation"`
+      };
+    }
+  }
+  const rawName = stringField2(data, "name") ?? input.entryName;
+  let name2 = rawName;
+  if (!isSkillName(name2)) {
+    if (!input.slugify) {
+      return { ok: false, reason: `invalid skill name "${rawName}" and slugifyNames is disabled` };
+    }
+    const slug = slugifySkillName(rawName);
+    if (!isSkillName(slug)) {
+      return { ok: false, reason: `invalid skill name "${rawName}" cannot be converted to a dsh kebab-case name` };
+    }
+    name2 = slug;
+  }
+  let description = stringField2(data, "description");
+  if (description === void 0) {
+    if (!input.synthesize) {
+      return { ok: false, reason: "frontmatter requires a description and synthesizeDescription is disabled" };
+    }
+    description = synthesizeDescription(parsed.body);
+    if (description.length === 0) {
+      return { ok: false, reason: "frontmatter requires a description and the body is empty" };
+    }
+  }
+  const whenToUse = stringField2(data, "whenToUse") ?? stringField2(data, "when_to_use");
+  const disableModelInvocation = lenientBoolean(data["disable-model-invocation"]);
+  if (data["disable-model-invocation"] !== void 0 && disableModelInvocation === void 0) {
+    return { ok: false, reason: 'frontmatter field "disable-model-invocation" must be a boolean' };
+  }
+  const userInvocableRaw = data["user-invocable"];
+  let userInvocable = true;
+  if (userInvocableRaw !== void 0) {
+    const parsed2 = lenientBoolean(userInvocableRaw);
+    if (parsed2 === void 0) {
+      return { ok: false, reason: 'frontmatter field "user-invocable" must be a boolean' };
+    }
+    userInvocable = parsed2;
+  }
+  const modelInvocable = disableModelInvocation !== true && input.allowImplicitInvocation !== false;
+  return {
+    ok: true,
+    skill: {
+      name: name2,
+      description,
+      whenToUse,
+      invocation: { modelInvocable, userInvocable },
+      // 原始 frontmatter 全量保真：allowed-tools/model/hooks 等字段在 dsh
+      // 没有对应物，保留在 metadata 里可追溯，不做静默丢弃。
+      metadata: Object.freeze({ ...data }),
+      path: filePath,
+      directory: input.directory,
+      content: parsed.body.trim()
+    }
+  };
+}
+async function readCodexOpenAiPolicy(directory) {
+  let raw;
+  try {
+    raw = await readFile(join(directory, "agents", "openai.yaml"), { encoding: "utf8" });
+  } catch {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = parseYaml(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const policy = parsed["policy"];
+  if (typeof policy !== "object" || policy === null) return void 0;
+  return lenientBoolean(policy["allow_implicit_invocation"]);
+}
+
+// src/roots.ts
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join as join2, resolve } from "node:path";
+var DEFAULT_RANKS = {
+  claudeProject: 210,
+  zcodeProject: 220,
+  extra: 300,
+  claudeUser: 450,
+  codexUser: 460,
+  zcodeUser: 470
+};
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findProjectRoot(cwd) {
+  let current = resolve(cwd);
+  for (; ; ) {
+    if (await pathExists(join2(current, ".git"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return resolve(cwd);
+    current = parent;
+  }
+}
+async function resolveRoots(config, cwd) {
+  const roots = [];
+  const home = homedir();
+  if (cwd !== void 0) {
+    const projectRoot = await findProjectRoot(cwd);
+    if (config.sources.claude.enabled && config.sources.claude.project) {
+      roots.push({
+        path: join2(projectRoot, ".claude", "skills"),
+        source: "claude-code",
+        rank: DEFAULT_RANKS.claudeProject,
+        kind: "project"
+      });
+    }
+    if (config.sources.zcode.enabled && config.sources.zcode.project) {
+      roots.push({
+        path: join2(projectRoot, ".zcode", "skills"),
+        source: "zcode",
+        rank: DEFAULT_RANKS.zcodeProject,
+        kind: "project"
+      });
+    }
+  }
+  for (const dir of config.extraDirs) {
+    roots.push({ path: resolve(dir.path), source: dir.label, rank: dir.rank, kind: "extra" });
+  }
+  const claude = config.sources.claude;
+  if (claude.enabled) {
+    roots.push({
+      path: resolve(claude.root ?? join2(home, ".claude", "skills")),
+      source: "claude-code",
+      rank: claude.rank ?? DEFAULT_RANKS.claudeUser,
+      kind: "user"
+    });
+  }
+  const codex = config.sources.codex;
+  if (codex.enabled) {
+    roots.push({
+      path: resolve(codex.root ?? join2(home, ".codex", "skills")),
+      source: "codex",
+      rank: codex.rank ?? DEFAULT_RANKS.codexUser,
+      kind: "user"
+    });
+  }
+  const zcode = config.sources.zcode;
+  if (zcode.enabled) {
+    roots.push({
+      path: resolve(zcode.root ?? join2(home, ".zcode", "skills")),
+      source: "zcode",
+      rank: zcode.rank ?? DEFAULT_RANKS.zcodeUser,
+      kind: "user"
+    });
+  }
+  roots.sort((left, right) => left.rank - right.rank || left.path.localeCompare(right.path));
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const root of roots) {
+    if (seen.has(root.path)) continue;
+    seen.add(root.path);
+    unique.push(root);
+  }
+  return unique;
+}
+
+// src/scan.ts
+import { readdir, readFile as readFile2 } from "node:fs/promises";
+import { basename, join as join3 } from "node:path";
+var CLAUDE_RESERVED_ENTRY = /^(synced|anthropic-skills)/;
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function readSkillText(path) {
+  try {
+    return await readFile2(path, { encoding: "utf8" });
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function scanRoot(root, options) {
+  let dirents;
+  try {
+    dirents = await readdir(root.path, { withFileTypes: true });
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { root, skills: [], absent: true, issues: [] };
+    }
+    return { root, skills: [], absent: false, issues: [`${root.source}(${root.path}): failed to list directory: ${errorMessage(error)}`] };
+  }
+  const entries = [...dirents].sort((left, right) => left.name.localeCompare(right.name));
+  const skills = [];
+  const issues = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (root.source === "claude-code" && CLAUDE_RESERVED_ENTRY.test(entry.name)) continue;
+    const isDirectory = entry.isDirectory();
+    const isFlatSkill = entry.isFile() && entry.name.endsWith(".md");
+    if (!isDirectory && !isFlatSkill) continue;
+    const entryPath = isDirectory ? join3(root.path, entry.name, "SKILL.md") : join3(root.path, entry.name);
+    const entryName = isDirectory ? entry.name : entry.name.slice(0, -3);
+    const directory = isDirectory ? join3(root.path, entry.name) : root.path;
+    let raw;
+    try {
+      raw = await readSkillText(entryPath);
+    } catch (error) {
+      issues.push(`${root.source}(${root.path}): failed to read ${entryPath}: ${errorMessage(error)}`);
+      continue;
+    }
+    if (raw === void 0) continue;
+    const parsed = splitFrontmatter(raw);
+    if (parsed === void 0) {
+      issues.push(`${entryPath} ignored: invalid or missing YAML frontmatter`);
+      continue;
+    }
+    const allowImplicit = isDirectory ? await readCodexOpenAiPolicy(directory) : void 0;
+    const mapped = mapForeignSkill({
+      filePath: entryPath,
+      directory,
+      entryName,
+      parsed,
+      slugify: options.slugify,
+      synthesize: options.synthesize,
+      allowImplicitInvocation: allowImplicit
+    });
+    if (!mapped.ok) {
+      issues.push(`${entryPath} ignored: ${mapped.reason}`);
+      continue;
+    }
+    const previous = seen.get(mapped.skill.name);
+    if (previous !== void 0) {
+      issues.push(
+        `${entryPath} ignored: duplicate skill name "${mapped.skill.name}" (already provided by ${previous})`
+      );
+      continue;
+    }
+    seen.set(mapped.skill.name, entryPath);
+    skills.push(mapped.skill);
+  }
+  return { root, skills, absent: false, issues };
+}
+function entryNameFor(directory, path) {
+  return basename(path) === "SKILL.md" ? basename(directory) : basename(path).replace(/\.md$/, "");
+}
+
+// src/watch.ts
+import { stat } from "node:fs/promises";
+import { watchFile, unwatchFile } from "node:fs";
+import * as chokidar from "chokidar";
+var PRESENCE_POLL_MS = 2500;
+var DEBOUNCE_MS = 150;
+var CompatWatchController = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  states = /* @__PURE__ */ new Map();
+  debounceTimer;
+  disposed = false;
+  /** 注册要监视的根（幂等；list() 每轮把解析出的 roots 传进来）。 */
+  observe(entries) {
+    if (this.disposed) return;
+    for (const entry of entries) {
+      if (this.states.has(entry.path)) continue;
+      const state = { kind: entry.kind, chokidarWatcher: void 0, present: false };
+      this.states.set(entry.path, state);
+      watchFile(entry.path, { interval: PRESENCE_POLL_MS, persistent: false }, () => {
+        void this.refresh(entry.path, state);
+      });
+      void this.refresh(entry.path, state);
+    }
+    this.evictProjectOverflow();
+  }
+  /** 项目根数量超限时逐出最旧的项目根（Map 保持插入序）。 */
+  evictProjectOverflow() {
+    let projectCount = 0;
+    for (const state of this.states.values()) {
+      if (state.kind === "project") projectCount += 1;
+    }
+    for (const [path, state] of this.states) {
+      if (projectCount <= this.options.maxProjects) break;
+      if (state.kind !== "project") continue;
+      this.closeChokidar(state);
+      unwatchFile(path);
+      this.states.delete(path);
+      projectCount -= 1;
+      this.options.logger.warn(`skill-compat-plus: project watch limit (${this.options.maxProjects}) reached, dropped watch for ${path}`);
+    }
+  }
+  /** 存在性判定以 stat() 为准；watchFile 只充当变化信号。 */
+  async refresh(path, state) {
+    if (this.disposed) return;
+    let info;
+    try {
+      info = await stat(path);
+    } catch {
+      info = void 0;
+    }
+    const exists = info !== void 0 && info.isDirectory();
+    if (exists === state.present) return;
+    state.present = exists;
+    if (exists) {
+      this.openChokidar(path, state);
+    } else {
+      this.closeChokidar(state);
+    }
+    this.queueInvalidate();
+  }
+  openChokidar(path, state) {
+    if (state.chokidarWatcher !== void 0) return;
+    try {
+      const watcher = chokidar.watch(path, {
+        persistent: true,
+        ignoreInitial: true,
+        depth: 1,
+        atomic: true,
+        usePolling: this.options.usePolling,
+        interval: this.options.pollIntervalMs,
+        awaitWriteFinish: {
+          stabilityThreshold: this.options.stabilityThresholdMs,
+          pollInterval: this.options.pollIntervalMs
+        }
+      });
+      watcher.on("all", () => this.queueInvalidate());
+      watcher.on("error", (error) => {
+        this.options.logger.warn(
+          `skill-compat-plus: watcher error for ${path}: ${error instanceof Error ? error.message : String(error)}`
+        );
+        this.closeChokidar(state);
+      });
+      state.chokidarWatcher = watcher;
+    } catch (error) {
+      this.options.logger.warn(
+        `skill-compat-plus: failed to watch ${path}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  closeChokidar(state) {
+    const watcher = state.chokidarWatcher;
+    state.chokidarWatcher = void 0;
+    if (watcher !== void 0) void watcher.close().catch(() => {
+    });
+  }
+  queueInvalidate() {
+    if (this.disposed || this.debounceTimer !== void 0) return;
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = void 0;
+      this.options.invalidate();
+    }, DEBOUNCE_MS);
+    this.debounceTimer.unref?.();
+  }
+  async dispose() {
+    this.disposed = true;
+    if (this.debounceTimer !== void 0) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = void 0;
+    }
+    for (const [path, state] of this.states) {
+      this.closeChokidar(state);
+      unwatchFile(path);
+      this.states.delete(path);
+    }
+  }
+};
+
+// src/provider.ts
+function errorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var CompatSkillProvider = class {
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger;
+    this.name = config.providerName;
+  }
+  config;
+  logger;
+  name;
+  control;
+  watcher;
+  lastIssueSignature = "";
+  disposed = false;
+  /** 由 registerProvider 工厂调用；只能成功一次。 */
+  attach(control) {
+    if (this.control !== void 0) return;
+    this.control = control;
+    if (this.config.watch) {
+      this.watcher = new CompatWatchController({
+        invalidate: () => {
+          if (!this.disposed) this.control?.invalidate();
+        },
+        logger: this.logger,
+        usePolling: this.config.watchUsePolling,
+        stabilityThresholdMs: this.config.watchStabilityThresholdMs,
+        pollIntervalMs: this.config.watchPollIntervalMs,
+        maxProjects: this.config.watchMaxProjects
+      });
+    }
+  }
+  async list(options) {
+    options.signal?.throwIfAborted();
+    if (this.disposed) return [];
+    const roots = await resolveRoots(this.config, options.cwd);
+    const results = await Promise.all(
+      roots.map(async (root) => {
+        try {
+          const result = await scanRoot(root, {
+            slugify: this.config.slugifyNames,
+            synthesize: this.config.synthesizeDescription
+          });
+          return { root, skills: [...result.skills], issues: [...result.issues] };
+        } catch (error) {
+          return { root, skills: [], issues: [`${root.source}(${root.path}): scan failed: ${errorMessage2(error)}`] };
+        }
+      })
+    );
+    const candidates = [];
+    const issues = [];
+    for (const result of results) {
+      for (const issue of result.issues) {
+        issues.push(`${result.root.source}(${result.root.path}): ${issue}`);
+      }
+      for (const skill of result.skills) {
+        candidates.push(this.toCandidate(skill, result.root));
+      }
+    }
+    const signature = issues.join("\n");
+    if (signature !== this.lastIssueSignature) {
+      for (const issue of issues) this.logger.warn(issue);
+      this.lastIssueSignature = signature;
+    }
+    this.watcher?.observe(roots.map((root) => ({ path: root.path, kind: root.kind })));
+    return candidates;
+  }
+  async get(candidate, options) {
+    options.signal?.throwIfAborted();
+    if (this.disposed) return void 0;
+    const locator = candidate.locator;
+    if (typeof locator?.path !== "string" || typeof locator?.directory !== "string") return void 0;
+    let raw;
+    try {
+      raw = await readFile3(locator.path, { encoding: "utf8", signal: options.signal });
+    } catch (error) {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    }
+    const parsed = splitFrontmatter(raw);
+    if (parsed === void 0) return void 0;
+    const allowImplicit = basename2(locator.path) === "SKILL.md" ? await readCodexOpenAiPolicy(locator.directory) : void 0;
+    const mapped = mapForeignSkill({
+      filePath: locator.path,
+      directory: locator.directory,
+      entryName: entryNameFor(locator.directory, locator.path),
+      parsed,
+      slugify: this.config.slugifyNames,
+      synthesize: this.config.synthesizeDescription,
+      allowImplicitInvocation: allowImplicit
+    });
+    if (!mapped.ok || mapped.skill.name !== candidate.name) return void 0;
+    const skill = mapped.skill;
+    return {
+      name: skill.name,
+      description: skill.description,
+      whenToUse: skill.whenToUse,
+      invocation: skill.invocation,
+      source: candidate.source,
+      provider: this.name,
+      resourceBase: { kind: "directory", path: skill.directory },
+      path: skill.path,
+      metadata: skill.metadata,
+      content: skill.content
+    };
+  }
+  toCandidate(skill, root) {
+    return {
+      name: skill.name,
+      description: skill.description,
+      whenToUse: skill.whenToUse,
+      invocation: skill.invocation,
+      source: root.source,
+      provider: this.name,
+      resourceBase: { kind: "directory", path: skill.directory },
+      path: skill.path,
+      metadata: skill.metadata,
+      rank: root.rank,
+      locator: { path: skill.path, directory: skill.directory }
+    };
+  }
+  async dispose() {
+    this.disposed = true;
+    await this.watcher?.dispose();
+  }
+};
+
+// src/index.ts
+var name = "skill-compat-plus";
+var inject = ["skills"];
+function apply(ctx, config) {
+  let resolved;
+  try {
+    resolved = resolveConfig(config);
+  } catch (error) {
+    ctx.logger.warn(`skill-compat-plus disabled: invalid config: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  if (!resolved.anySourceEnabled) {
+    ctx.logger.warn("skill-compat-plus disabled: every source is turned off and extraDirs is empty");
+    return;
+  }
+  const provider = new CompatSkillProvider(resolved, ctx.logger);
+  try {
+    ctx.skills.registerProvider((control) => {
+      provider.attach(control);
+      return provider;
+    });
+  } catch (error) {
+    ctx.logger.warn(
+      `skill-compat-plus not registered: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return;
+  }
+  ctx.effect(function* () {
+    yield async () => {
+      await provider.dispose();
+    };
+  }, "skill-compat-plus watch lifecycle");
+}
+export {
+  apply,
+  inject,
+  name
+};