dsh-skills-manager 0.1.0

package/lib/index.js

@@ -0,0 +1,700 @@
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { tmpdir } from "node:os";
+import { promisify } from "node:util";
+import Schema from "@deepseek-ai/schemastery";
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import { FileSystemSkillProvider } from "@deepseek-ai/dsh-skill-filesystem";
+import { parse } from "yaml";
+
+//#region lib/types/state.js
+const EMPTY_STATE = {
+	version: 1,
+	skills: {},
+	globalEnabled: [],
+	projectEnabled: {}
+};
+function normalizeState(value) {
+	if (!isRecord$1(value) || value.version !== 1 || !isRecord$1(value.skills) || !Array.isArray(value.globalEnabled) || !isRecord$1(value.projectEnabled)) throw new Error("skill-manager state.json has an unsupported shape");
+	const skills = {};
+	for (const [name$1, entry] of Object.entries(value.skills)) {
+		if (!isRecord$1(entry) || entry.name !== name$1 || typeof entry.description !== "string" || entry.layout !== "directory" && entry.layout !== "file" || typeof entry.installedAt !== "string") throw new Error(`skill-manager state.json has an invalid skill entry: ${name$1}`);
+		skills[name$1] = {
+			name: name$1,
+			description: entry.description,
+			layout: entry.layout,
+			installedAt: entry.installedAt,
+			...typeof entry.updatedAt === "string" ? { updatedAt: entry.updatedAt } : {},
+			...entry.sourceType === "local" || entry.sourceType === "git" ? { sourceType: entry.sourceType } : {},
+			...typeof entry.sourcePath === "string" && isAbsolute(entry.sourcePath) ? { sourcePath: entry.sourcePath } : {},
+			...typeof entry.sourceUrl === "string" ? { sourceUrl: entry.sourceUrl } : {},
+			...typeof entry.sourceSubpath === "string" ? { sourceSubpath: entry.sourceSubpath } : {},
+			...typeof entry.contentHash === "string" ? { contentHash: entry.contentHash } : {}
+		};
+	}
+	return {
+		version: 1,
+		skills,
+		globalEnabled: cleanNames(value.globalEnabled, skills),
+		projectEnabled: cleanProjects(value.projectEnabled, skills)
+	};
+}
+function setEnabled(state, name$1, scope, projectRoot, enabled) {
+	if (!(name$1 in state.skills)) throw new Error(`skill is not installed: ${name$1}`);
+	if (scope === "project" && !projectRoot) throw new Error("projectRoot is required for project scope");
+	if (scope === "global") return {
+		...state,
+		globalEnabled: updateNames(state.globalEnabled, name$1, enabled)
+	};
+	const next = updateNames(state.projectEnabled[projectRoot] ?? [], name$1, enabled);
+	const projectEnabled = { ...state.projectEnabled };
+	if (next.length === 0) delete projectEnabled[projectRoot];
+	else projectEnabled[projectRoot] = next;
+	return {
+		...state,
+		projectEnabled
+	};
+}
+function removeSkill(state, name$1) {
+	if (!(name$1 in state.skills)) throw new Error(`skill is not installed: ${name$1}`);
+	const skills = { ...state.skills };
+	delete skills[name$1];
+	return {
+		version: 1,
+		skills,
+		globalEnabled: state.globalEnabled.filter((item) => item !== name$1),
+		projectEnabled: Object.fromEntries(Object.entries(state.projectEnabled).map(([root, names]) => [root, names.filter((item) => item !== name$1)]).filter(([, names]) => names.length > 0))
+	};
+}
+function isPathWithin(root, target) {
+	if (!isAbsolute(root) || !isAbsolute(target)) return false;
+	const child = relative(root, target);
+	return child === "" || child !== ".." && !child.startsWith(`..${sep}`);
+}
+function isEnabledFor(state, name$1, cwd) {
+	if (state.globalEnabled.includes(name$1)) return true;
+	if (!cwd) return false;
+	return Object.entries(state.projectEnabled).some(([root, names]) => names.includes(name$1) && isPathWithin(root, cwd));
+}
+function updateNames(names, name$1, enabled) {
+	const next = new Set(names);
+	if (enabled) next.add(name$1);
+	else next.delete(name$1);
+	return [...next].sort();
+}
+function cleanNames(value, skills) {
+	return [...new Set(value.filter((item) => typeof item === "string" && item in skills))].sort();
+}
+function cleanProjects(value, skills) {
+	const result = {};
+	for (const [root, names] of Object.entries(value)) {
+		if (!isAbsolute(root) || !Array.isArray(names)) continue;
+		const clean = cleanNames(names, skills);
+		if (clean.length > 0) result[root] = clean;
+	}
+	return result;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+//#endregion
+//#region lib/types/index.js
+const name = "dsh-skills-manager";
+const inject = ["skills", "connection"];
+const execFileAsync = promisify(execFile);
+const Config = Schema.object({ storageDir: Schema.string().default("") });
+var SkillManager = class {
+	ctx;
+	root;
+	library;
+	stateFile;
+	state = EMPTY_STATE;
+	loaded;
+	writeQueue = Promise.resolve();
+	updateChecks = /* @__PURE__ */ new Map();
+	providerControl;
+	filesystemProvider;
+	constructor(ctx, config) {
+		this.ctx = ctx;
+		const storageDir = config.storageDir?.trim();
+		this.root = storageDir ? resolve(storageDir) : join(resolveDshHome(), "skill-manager");
+		this.library = join(this.root, "library");
+		this.stateFile = join(this.root, "state.json");
+		this.loaded = this.load();
+	}
+	provider(control) {
+		this.providerControl = control;
+		this.filesystemProvider = new FileSystemSkillProvider(this.ctx, control, {
+			providerName: "skill-manager-library",
+			includeDefaultRoots: false,
+			customSkillDirs: [this.library],
+			watch: true
+		});
+		return {
+			name: "skill-manager",
+			list: async (options) => {
+				await this.loaded;
+				const discovered = await this.filesystemProvider.list(options);
+				return (Array.isArray(discovered) ? discovered : discovered.candidates).filter((candidate) => isEnabledFor(this.state, candidate.name, options.cwd)).map((candidate) => this.managedCandidate(candidate));
+			},
+			get: async (candidate, options) => {
+				await this.loaded;
+				const locator = candidate.locator;
+				return this.filesystemProvider.get(locator.candidate, options);
+			}
+		};
+	}
+	async catalog(projectRoot) {
+		await this.loaded;
+		return {
+			entries: Object.values(this.state.skills).sort((a, b) => a.name.localeCompare(b.name)).map((skill) => {
+				const check = this.updateChecks.get(skill.name);
+				return {
+					...skill,
+					globalEnabled: this.state.globalEnabled.includes(skill.name),
+					projectEnabled: projectRoot !== void 0 && (this.state.projectEnabled[projectRoot] ?? []).includes(skill.name),
+					effectiveEnabled: isEnabledFor(this.state, skill.name, projectRoot),
+					updateSupported: Boolean(skill.sourcePath || skill.sourceUrl),
+					updateAvailable: check?.available ?? false,
+					...check?.error ? { updateError: check.error } : {}
+				};
+			}),
+			...projectRoot ? { projectRoot } : {}
+		};
+	}
+	async install(sourcePath, projectRoot) {
+		const sources = await discoverSources(sourcePath);
+		return this.installSources(sources, (source) => ({
+			sourceType: "local",
+			sourcePath: source.path
+		}), projectRoot);
+	}
+	async installRemote(input, projectRoot) {
+		const sourceUrl = normalizeGitSource(input);
+		const checkout = await cloneGitRepository(sourceUrl);
+		try {
+			const sources = await discoverRepositorySources(checkout);
+			return await this.installSources(sources, (source) => ({
+				sourceType: "git",
+				sourceUrl,
+				sourceSubpath: relative(checkout, source.path).split(sep).join("/")
+			}), projectRoot);
+		} finally {
+			await rm(checkout, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	async installSources(sources, originFor, projectRoot) {
+		await this.loaded;
+		const duplicate = sources.find((source) => source.name in this.state.skills);
+		if (duplicate) throw new Error(`skill is already installed: ${duplicate.name}`);
+		await mkdir(this.library, { recursive: true });
+		const installed = {};
+		const staged = [];
+		const previousState = this.state;
+		try {
+			for (const source of sources) {
+				const target = join(this.library, source.layout === "file" ? `${source.name}.md` : source.name);
+				if (await pathExists(target)) throw new Error(`skill target already exists: ${target}`);
+				const temp = `${target}.tmp-${randomUUID()}`;
+				await cp(source.path, temp, {
+					recursive: source.layout === "directory",
+					errorOnExist: true,
+					force: false,
+					verbatimSymlinks: true
+				});
+				staged.push({
+					temp,
+					target,
+					layout: source.layout,
+					committed: false
+				});
+				const now = (/* @__PURE__ */ new Date()).toISOString();
+				installed[source.name] = {
+					name: source.name,
+					description: source.description,
+					layout: source.layout,
+					installedAt: now,
+					updatedAt: now,
+					...originFor(source),
+					contentHash: await hashSkillSource(temp)
+				};
+			}
+			for (const item of staged) {
+				await rename(item.temp, item.target);
+				item.committed = true;
+			}
+			this.state = {
+				...this.state,
+				skills: {
+					...this.state.skills,
+					...installed
+				}
+			};
+			await this.persist();
+			for (const skillName of Object.keys(installed)) this.updateChecks.set(skillName, { available: false });
+			this.providerControl?.invalidate();
+			return this.catalog(projectRoot);
+		} catch (error) {
+			this.state = previousState;
+			await Promise.all(staged.flatMap((item) => [rm(item.temp, {
+				recursive: item.layout === "directory",
+				force: true
+			}), ...item.committed ? [rm(item.target, {
+				recursive: item.layout === "directory",
+				force: true
+			})] : []]));
+			throw error;
+		}
+	}
+	async checkUpdates(projectRoot) {
+		await this.loaded;
+		const checkouts = [];
+		const checkoutCache = /* @__PURE__ */ new Map();
+		const checkoutFor = (sourceUrl) => {
+			let checkout = checkoutCache.get(sourceUrl);
+			if (!checkout) {
+				checkout = cloneGitRepository(sourceUrl).then((path) => {
+					checkouts.push(path);
+					return path;
+				});
+				checkoutCache.set(sourceUrl, checkout);
+			}
+			return checkout;
+		};
+		try {
+			for (const skill of Object.values(this.state.skills)) {
+				if (!skill.contentHash || !skill.sourcePath && !skill.sourceUrl) {
+					this.updateChecks.delete(skill.name);
+					continue;
+				}
+				try {
+					const source = await resolveTrackedSource(skill, checkoutFor);
+					this.updateChecks.set(skill.name, { available: await hashSkillSource(source.path) !== skill.contentHash });
+				} catch (error) {
+					this.updateChecks.set(skill.name, {
+						available: false,
+						error: messageOf(error)
+					});
+				}
+			}
+			return this.catalog(projectRoot);
+		} finally {
+			await Promise.all(checkouts.map((path) => rm(path, {
+				recursive: true,
+				force: true
+			})));
+		}
+	}
+	async update(name$1, sourcePath, projectRoot) {
+		await this.loaded;
+		const current = this.state.skills[name$1];
+		if (!current) throw new Error(`skill is not installed: ${name$1}`);
+		const resolvedSource = sourcePath ? {
+			source: await findUpdateSource(name$1, sourcePath),
+			origin: {
+				sourceType: "local",
+				sourcePath: resolve(sourcePath)
+			}
+		} : await prepareTrackedUpdate(current);
+		try {
+			return await this.replaceSkill(name$1, current, resolvedSource.source, resolvedSource.origin, projectRoot);
+		} finally {
+			await resolvedSource.cleanup?.();
+		}
+	}
+	async replaceSkill(name$1, current, source, origin, projectRoot) {
+		const currentTarget = join(this.library, current.layout === "file" ? `${name$1}.md` : name$1);
+		const nextTarget = join(this.library, source.layout === "file" ? `${name$1}.md` : name$1);
+		if (currentTarget !== nextTarget && await pathExists(nextTarget)) throw new Error(`cannot change skill layout because the target already exists: ${nextTarget}`);
+		const suffix = randomUUID();
+		const temp = `${nextTarget}.tmp-${suffix}`;
+		const backup = `${currentTarget}.bak-${suffix}`;
+		const previousState = this.state;
+		let currentMoved = false;
+		let nextMoved = false;
+		try {
+			await cp(source.path, temp, {
+				recursive: source.layout === "directory",
+				errorOnExist: true,
+				force: false,
+				verbatimSymlinks: true
+			});
+			const contentHash = await hashSkillSource(temp);
+			await rename(currentTarget, backup);
+			currentMoved = true;
+			await rename(temp, nextTarget);
+			nextMoved = true;
+			this.state = {
+				...this.state,
+				skills: {
+					...this.state.skills,
+					[name$1]: {
+						...current,
+						description: source.description,
+						layout: source.layout,
+						sourceType: origin.sourceType,
+						sourcePath: origin.sourcePath,
+						sourceUrl: origin.sourceUrl,
+						sourceSubpath: origin.sourceSubpath,
+						contentHash,
+						updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+					}
+				}
+			};
+			await this.persist();
+			await rm(backup, {
+				recursive: current.layout === "directory",
+				force: true
+			}).catch(() => void 0);
+			this.updateChecks.set(name$1, { available: false });
+			this.providerControl?.invalidate();
+			return this.catalog(projectRoot);
+		} catch (error) {
+			this.state = previousState;
+			if (nextMoved) await rm(nextTarget, {
+				recursive: source.layout === "directory",
+				force: true
+			});
+			if (currentMoved) await rename(backup, currentTarget);
+			await rm(temp, {
+				recursive: source.layout === "directory",
+				force: true
+			});
+			throw error;
+		}
+	}
+	async setEnabled(name$1, scope, projectRoot, enabled) {
+		await this.loaded;
+		this.state = setEnabled(this.state, name$1, scope, projectRoot, enabled);
+		await this.persist();
+		this.providerControl?.invalidate();
+		return this.catalog(projectRoot);
+	}
+	async remove(name$1, projectRoot) {
+		await this.loaded;
+		const skill = this.state.skills[name$1];
+		if (!skill) throw new Error(`skill is not installed: ${name$1}`);
+		await rm(join(this.library, skill.layout === "file" ? `${name$1}.md` : name$1), {
+			recursive: skill.layout === "directory",
+			force: true
+		});
+		this.state = removeSkill(this.state, name$1);
+		await this.persist();
+		this.updateChecks.delete(name$1);
+		this.providerControl?.invalidate();
+		return this.catalog(projectRoot);
+	}
+	async load() {
+		await mkdir(this.library, { recursive: true });
+		try {
+			this.state = normalizeState(JSON.parse(await readFile(this.stateFile, "utf8")));
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") {
+				this.state = EMPTY_STATE;
+				await this.persist();
+				return;
+			}
+			throw error;
+		}
+	}
+	async persist() {
+		const operation = this.writeQueue.then(async () => {
+			await mkdir(this.root, { recursive: true });
+			const temp = `${this.stateFile}.tmp-${randomUUID()}`;
+			await writeFile(temp, `${JSON.stringify(this.state, null, 2)}\n`, "utf8");
+			await rename(temp, this.stateFile);
+		});
+		this.writeQueue = operation.catch(() => void 0);
+		await operation;
+	}
+	managedCandidate(candidate) {
+		return {
+			...candidate,
+			provider: "skill-manager",
+			source: "skill-manager",
+			rank: 50,
+			locator: { candidate }
+		};
+	}
+};
+function apply(ctx, config) {
+	if (config.storageDir?.trim() && !isAbsolute(config.storageDir)) throw new Error("storageDir must resolve to an absolute path");
+	const manager = new SkillManager(ctx, config);
+	ctx.skills.registerProvider((control) => manager.provider(control));
+	const host = ctx;
+	ctx.effect(() => host.connection.rpc.handle("/skill-manager", async (endpoint, payload) => handleRpc(manager, endpoint, payload), { authority: "loopback" }), "dsh-skill-manager: rpc");
+}
+async function handleRpc(manager, endpoint, payload) {
+	const args = isRecord(payload) ? payload : {};
+	switch (endpoint) {
+		case "list": return {
+			ok: true,
+			value: await manager.catalog(asOptionalString(args.projectRoot))
+		};
+		case "install": return {
+			ok: true,
+			value: await manager.install(requiredString(args.path, "path"), asOptionalString(args.projectRoot))
+		};
+		case "install-remote": return {
+			ok: true,
+			value: await manager.installRemote(requiredString(args.repository, "repository"), asOptionalString(args.projectRoot))
+		};
+		case "check-updates": return {
+			ok: true,
+			value: await manager.checkUpdates(asOptionalString(args.projectRoot))
+		};
+		case "update": return {
+			ok: true,
+			value: await manager.update(requiredString(args.name, "name"), asOptionalString(args.path), asOptionalString(args.projectRoot))
+		};
+		case "set-enabled": return {
+			ok: true,
+			value: await manager.setEnabled(requiredString(args.name, "name"), requiredScope(args.scope), asOptionalString(args.projectRoot), requiredBoolean(args.enabled, "enabled"))
+		};
+		case "remove": return {
+			ok: true,
+			value: await manager.remove(requiredString(args.name, "name"), asOptionalString(args.projectRoot))
+		};
+		default: throw new Error(`unknown skill-manager endpoint: ${endpoint}`);
+	}
+}
+async function discoverSources(inputPath) {
+	const path = resolve(inputPath.trim());
+	const info = await stat(path);
+	if (info.isFile()) {
+		if (extname(path).toLowerCase() !== ".md") throw new Error("a skill file must use the .md extension");
+		return [await readSkillSource(path, "file")];
+	}
+	if (!info.isDirectory()) throw new Error("skill source must be a directory or Markdown file");
+	if (await isFile(join(path, "SKILL.md"))) return [await readSkillSource(join(path, "SKILL.md"), "directory", path)];
+	const entries = await readdir(path, { withFileTypes: true });
+	const sources = [];
+	for (const entry of entries) {
+		const child = join(path, entry.name);
+		if (entry.isDirectory() && await isFile(join(child, "SKILL.md"))) sources.push(await readSkillSource(join(child, "SKILL.md"), "directory", child));
+		else if (entry.isFile() && extname(entry.name).toLowerCase() === ".md") sources.push(await readSkillSource(child, "file"));
+	}
+	if (sources.length === 0) throw new Error("no SKILL.md or Markdown skill file was found in the selected folder");
+	return sources;
+}
+async function discoverRepositorySources(root) {
+	if (await isFile(join(root, "SKILL.md"))) return [await readSkillSource(join(root, "SKILL.md"), "directory", root)];
+	const searchRoots = [
+		root,
+		join(root, "skills"),
+		join(root, ".agents", "skills")
+	];
+	const sources = /* @__PURE__ */ new Map();
+	for (const searchRoot of searchRoots) {
+		let entries;
+		try {
+			entries = await readdir(searchRoot, { withFileTypes: true });
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") continue;
+			throw error;
+		}
+		for (const entry of entries) {
+			const child = join(searchRoot, entry.name);
+			if (entry.isDirectory() && await isFile(join(child, "SKILL.md"))) {
+				const source = await readSkillSource(join(child, "SKILL.md"), "directory", child);
+				sources.set(source.name, source);
+			} else if (entry.isFile() && extname(entry.name).toLowerCase() === ".md" && entry.name.toLowerCase() !== "readme.md") try {
+				const source = await readSkillSource(child, "file");
+				sources.set(source.name, source);
+			} catch (error) {
+				if ((await readFile(child, "utf8")).startsWith("---")) throw error;
+			}
+		}
+	}
+	if (sources.size === 0) throw new Error("the repository does not contain a root skill or skills/* entries");
+	return [...sources.values()];
+}
+function normalizeGitSource(input) {
+	const value = input.trim();
+	if (!value || value.startsWith("-") || /[\r\n\0]/.test(value)) throw new Error("repository must be a valid Git URL or owner/repo");
+	if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value)) return `https://github.com/${value}.git`;
+	if (/^[A-Za-z0-9_.-]+@[A-Za-z0-9_.-]+:[^\s]+$/.test(value)) return value;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error("repository must be a GitHub owner/repo, HTTPS URL, SSH URL, or file URL");
+	}
+	if (![
+		"https:",
+		"http:",
+		"ssh:",
+		"git:",
+		"file:"
+	].includes(url.protocol)) throw new Error(`unsupported Git protocol: ${url.protocol}`);
+	if (url.password || (url.protocol === "https:" || url.protocol === "http:") && url.username) throw new Error("do not embed credentials in the repository URL; use a Git credential helper or SSH");
+	if (url.hostname === "github.com" && /\/tree\//.test(url.pathname)) throw new Error("use the repository root URL, not a GitHub /tree/ URL");
+	return value;
+}
+async function cloneGitRepository(sourceUrl) {
+	const checkout = await mkdtemp(join(tmpdir(), "dsh-skill-manager-git-"));
+	try {
+		await execFileAsync("git", [
+			"clone",
+			"--depth",
+			"1",
+			"--",
+			sourceUrl,
+			checkout
+		], {
+			timeout: 12e4,
+			maxBuffer: 1024 * 1024
+		});
+		return checkout;
+	} catch {
+		await rm(checkout, {
+			recursive: true,
+			force: true
+		});
+		throw new Error("failed to clone Git repository; check the URL and local Git credentials");
+	}
+}
+async function resolveTrackedSource(skill, checkoutFor) {
+	if (skill.sourceUrl) {
+		if (typeof skill.sourceSubpath !== "string") throw new Error("the repository skill path is missing; import it again");
+		const checkout = await checkoutFor(skill.sourceUrl);
+		return findUpdateSource(skill.name, resolveRepositorySubpath(checkout, skill.sourceSubpath));
+	}
+	return findUpdateSource(skill.name, skill.sourcePath);
+}
+async function prepareTrackedUpdate(skill) {
+	if (!skill.sourceUrl) return {
+		source: await findUpdateSource(skill.name, skill.sourcePath),
+		origin: {
+			sourceType: "local",
+			sourcePath: skill.sourcePath
+		}
+	};
+	const checkout = await cloneGitRepository(skill.sourceUrl);
+	try {
+		return {
+			source: await resolveTrackedSource(skill, async () => checkout),
+			origin: {
+				sourceType: "git",
+				sourceUrl: skill.sourceUrl,
+				sourceSubpath: skill.sourceSubpath
+			},
+			cleanup: () => rm(checkout, {
+				recursive: true,
+				force: true
+			})
+		};
+	} catch (error) {
+		await rm(checkout, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+function resolveRepositorySubpath(root, subpath) {
+	const target = resolve(root, subpath);
+	const child = relative(root, target);
+	if (child === ".." || child.startsWith(`..${sep}`) || isAbsolute(child)) throw new Error("repository skill path escapes the checkout");
+	return target;
+}
+async function findUpdateSource(name$1, sourcePath) {
+	if (!sourcePath) throw new Error("the original source is unknown; select the skill source folder to update it");
+	const source = (await discoverSources(sourcePath)).find((candidate) => candidate.name === name$1);
+	if (!source) throw new Error(`the selected source does not contain skill: ${name$1}`);
+	return source;
+}
+async function hashSkillSource(root) {
+	const hash = createHash("sha256");
+	const visit = async (path) => {
+		const info = await lstat(path);
+		const name$1 = relative(root, path).split(sep).join("/");
+		if (info.isSymbolicLink()) {
+			const target = await readlink(path);
+			const child = relative(root, resolve(dirname(path), target));
+			if (isAbsolute(target) || child === ".." || child.startsWith(`..${sep}`) || isAbsolute(child)) throw new Error(`skill symlink escapes its source root: ${path}`);
+			hash.update(`link\0${name$1}\0${target}\0`);
+			return;
+		}
+		if (info.isFile()) {
+			hash.update(`file\0${name$1}\0`);
+			hash.update(await readFile(path));
+			hash.update("\0");
+			return;
+		}
+		if (!info.isDirectory()) throw new Error(`unsupported skill entry: ${path}`);
+		hash.update(`directory\0${name$1}\0`);
+		const entries = await readdir(path);
+		entries.sort();
+		for (const entry of entries) await visit(join(path, entry));
+	};
+	await visit(root);
+	return hash.digest("hex");
+}
+async function pathExists(path) {
+	try {
+		await lstat(path);
+		return true;
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+async function readSkillSource(markdownPath, layout, directoryPath = markdownPath) {
+	return {
+		path: layout === "directory" ? directoryPath : markdownPath,
+		layout,
+		...await parseSkillFrontmatter(markdownPath)
+	};
+}
+async function parseSkillFrontmatter(path) {
+	const text = await readFile(path, "utf8");
+	const match = /^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/.exec(text);
+	if (!match) throw new Error(`missing YAML frontmatter: ${path}`);
+	const metadata = parse(match[1]);
+	if (!isRecord(metadata) || typeof metadata.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(metadata.name) || typeof metadata.description !== "string" || !metadata.description.trim()) throw new Error(`invalid skill frontmatter: ${path}`);
+	return {
+		name: metadata.name,
+		description: metadata.description.trim()
+	};
+}
+async function isFile(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+function requiredString(value, field) {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${field} must be a non-empty string`);
+	return value.trim();
+}
+function asOptionalString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function requiredBoolean(value, field) {
+	if (typeof value !== "boolean") throw new Error(`${field} must be boolean`);
+	return value;
+}
+function requiredScope(value) {
+	if (value !== "global" && value !== "project") throw new Error("scope must be global or project");
+	return value;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function messageOf(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+function isNodeError(value) {
+	return value instanceof Error && "code" in value;
+}
+
+//#endregion
+export { Config, SkillManager, apply, inject, name };

package/lib/types/client/index.d.ts

@@ -0,0 +1,3 @@
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+export declare const inject: string[];
+export declare function apply(ctx: ClientContext): void;