@dsh-gis/dsh-opengis-skill 0.1.0 → 0.1.2

package/lib/catalog.js

@@ -0,0 +1,238 @@
+/**
+ * Shared skill-catalog helpers for the runtime provider and the source-repo
+ * scripts. The functions are pure Node built-ins: no DeepSeek Harness imports
+ * and no third-party dependencies.
+ *
+ * @module @dsh-gis/dsh-opengis-skill/catalog
+ */
+
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseSkillFile } from "./skill-file.js";
+
+/** The instruction file name inside one skill directory. */
+export const SKILL_FILE = "SKILL.md";
+
+/** One inline code-span delimiter used by the generated markdown table. */
+const TICK = "`";
+
+/** README marker pair around the generated skill count line. */
+const COUNT_START = "<!-- skills:count:start -->";
+const COUNT_END = "<!-- skills:count:end -->";
+
+/** README marker pair around the generated skill table. */
+const TABLE_START = "<!-- skills:start -->";
+const TABLE_END = "<!-- skills:end -->";
+
+/**
+ * Read one skill directory.
+ *
+ * @param directory - absolute skill directory.
+ * @param expectedName - directory name the frontmatter name must match, when known.
+ * @returns the validated entry, or undefined when the directory has no SKILL.md.
+ * @throws when SKILL.md is malformed or declares a different name.
+ */
+export function readSkillEntry(directory, expectedName) {
+	const path = join(directory, SKILL_FILE);
+	if (statSync(path, { throwIfNoEntry: false })?.isFile() !== true) return undefined;
+	const parsed = parseSkillFile(readFileSync(path, "utf8"), path);
+	if (expectedName !== undefined && parsed.name !== expectedName) {
+		throw new Error(path + ' declares "' + parsed.name + '" but its directory is "' + expectedName + '"');
+	}
+	return { name: parsed.name, description: parsed.description, directory, path };
+}
+
+/**
+ * Read every skill directory under one asset root, sorted by name.
+ *
+ * Directories without SKILL.md are skipped so a stray directory cannot break
+ * the runtime; the validation script reports those separately.
+ *
+ * @param assetRoot - absolute directory holding one subdirectory per skill.
+ * @returns the validated skills sorted by name.
+ * @throws when the root is missing, two skills share a name, or no skill exists.
+ */
+export function readSkillCatalog(assetRoot) {
+	if (statSync(assetRoot, { throwIfNoEntry: false })?.isDirectory() !== true) {
+		throw new Error("skill asset directory not found: " + assetRoot);
+	}
+	const skills = [];
+	const seen = new Set();
+	for (const entry of readdirSync(assetRoot, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const skill = readSkillEntry(join(assetRoot, entry.name), entry.name);
+		if (skill === undefined) continue;
+		if (seen.has(skill.name)) throw new Error('duplicate skill name "' + skill.name + '" under ' + assetRoot);
+		seen.add(skill.name);
+		skills.push(skill);
+	}
+	if (skills.length === 0) throw new Error("no skills found under " + assetRoot);
+	return skills.sort((left, right) => compareCodePoints(left.name, right.name));
+}
+
+/**
+ * Render the directory resource base with forward slashes for the model.
+ *
+ * @param directory - absolute skill directory, using the host separator.
+ * @returns the resource base value the skill registry expects.
+ */
+export function resourceBaseOf(directory) {
+	return { kind: "directory", path: directory.replaceAll("\\", "/") };
+}
+
+/**
+ * Render the generated README skill-count section.
+ *
+ * @param skills - the catalog entries.
+ * @returns the complete marked section, markers included.
+ */
+export function renderSkillCount(skills) {
+	return [
+		COUNT_START,
+		"共 **" + skills.length + "** 个技能，描述取自上游 frontmatter。",
+		COUNT_END
+	].join("\n");
+}
+
+/**
+ * Render the generated README skill table.
+ *
+ * @param skills - the catalog entries carrying name and description.
+ * @returns the complete marked table section, markers included.
+ */
+export function renderSkillTable(skills) {
+	const rows = skills.map((skill) => {
+		const cell = "| " + TICK + skill.name + TICK + " | " + skill.description.replaceAll("|", "\\|") + " |";
+		return cell;
+	});
+	return [
+		TABLE_START,
+		"| Skill | Description (upstream frontmatter) |",
+		"| --- | --- |",
+		...rows,
+		TABLE_END
+	].join("\n");
+}
+
+/**
+ * Read the generated README sections including their markers.
+ *
+ * @param markdown - the complete README text.
+ * @returns the exact current count and table sections.
+ * @throws when a marker is missing or duplicated.
+ */
+export function readGeneratedSections(markdown) {
+	return {
+		count: extractSection(markdown, COUNT_START, COUNT_END),
+		table: extractSection(markdown, TABLE_START, TABLE_END)
+	};
+}
+
+/**
+ * Regenerate both README sections in place.
+ *
+ * @param markdown - the complete README text.
+ * @param skills - the catalog entries to render.
+ * @returns the README text with both generated sections replaced.
+ * @throws when a marker is missing or duplicated.
+ */
+export function replaceGeneratedSections(markdown, skills) {
+	const current = readGeneratedSections(markdown);
+	const replacements = [
+		[current.table, renderSkillTable(skills)],
+		[current.count, renderSkillCount(skills)]
+	];
+	let next = markdown;
+	for (const [from, to] of replacements) {
+		const index = next.indexOf(from);
+		if (index === -1) throw new Error("cannot regenerate README: generated section not found");
+		next = next.slice(0, index) + to + next.slice(index + from.length);
+	}
+	return next;
+}
+
+/**
+ * List every regular file under one directory as POSIX-style relative paths.
+ *
+ * @param root - the directory to walk.
+ * @returns sorted relative paths using "/" on every platform.
+ * @throws when the root is missing, a symbolic link is present, or an entry is neither a file nor a directory.
+ */
+export function listFiles(root) {
+	const resolvedRoot = resolve(root);
+	const output = [];
+	const stack = [""];
+	while (stack.length > 0) {
+		const prefix = stack.pop();
+		const directory = prefix === "" ? resolvedRoot : join(resolvedRoot, prefix);
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			const relativePath = prefix === "" ? entry.name : prefix + "/" + entry.name;
+			if (entry.isDirectory()) {
+				stack.push(relativePath);
+				continue;
+			}
+			if (entry.isSymbolicLink()) throw new Error("refusing to follow symbolic link: " + join(directory, entry.name));
+			if (!entry.isFile()) throw new Error("unsupported file type: " + join(directory, entry.name));
+			output.push(relativePath);
+		}
+	}
+	return output.sort(compareCodePoints);
+}
+
+/**
+ * Hash one file with SHA-256.
+ *
+ * @param path - the file to read.
+ * @returns the lowercase hexadecimal digest.
+ */
+export function hashFile(path) {
+	return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/**
+ * Hash every regular file under one directory.
+ *
+ * @param root - the directory to walk.
+ * @returns a map from POSIX-style relative path to lowercase SHA-256 digest.
+ */
+export function hashFiles(root) {
+	const digests = {};
+	for (const relativePath of listFiles(root)) digests[relativePath] = hashFile(join(root, relativePath));
+	return digests;
+}
+
+/**
+ * Normalize one vendored file to the upstream git blob form.
+ *
+ * A file carrying a NUL byte is treated as binary and copied unchanged; every
+ * other file has its CRLF line endings collapsed to LF. An upstream checkout on
+ * Windows can carry CRLF through core.autocrlf while the upstream git blob is
+ * LF, so normalizing keeps the vendored bytes equal to the blob independent of
+ * the platform.
+ *
+ * @param buffer - the raw file bytes.
+ * @returns the bytes to write or compare.
+ */
+export function canonicalVendoredBytes(buffer) {
+	if (buffer.includes(0)) return buffer;
+	return Buffer.from(buffer.toString("utf8").replaceAll("\r\n", "\n"), "utf8");
+}
+
+/** Extract one marked section and reject missing or duplicated markers. */
+function extractSection(markdown, start, end) {
+	const first = markdown.indexOf(start);
+	if (first === -1) throw new Error('missing generated README marker "' + start + '"');
+	if (markdown.indexOf(start, first + start.length) !== -1) throw new Error('duplicate generated README marker "' + start + '"');
+	const last = markdown.indexOf(end, first + start.length);
+	if (last === -1) throw new Error('missing generated README marker "' + end + '"');
+	if (markdown.indexOf(end, last + end.length) !== -1) throw new Error('duplicate generated README marker "' + end + '"');
+	return markdown.slice(first, last + end.length);
+}
+
+/** Compare two strings by Unicode code point, independent of the locale. */
+function compareCodePoints(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}

package/lib/index.d.ts

@@ -1,18 +1,59 @@
 /** Stable Loader identity. */
 export declare const name: "opengis-skill";
 
-/** Services that must exist before `apply` runs. */
+/** Services that must exist before "apply" runs. */
 export declare const inject: readonly ["skills"];
 
+/** Invocation controls shared by the model-facing and user-facing surfaces. */
+export interface OpenGisInvocation {
+	modelInvocable: boolean;
+	userInvocable: boolean;
+}
+
+/** Directory resource base handed to the model with a loaded skill. */
+export interface OpenGisResourceBase {
+	kind: "directory";
+	path: string;
+}
+
+/** One skill summary returned by the provider catalog. */
+export interface OpenGisSkillCandidate {
+	name: string;
+	description: string;
+	invocation: OpenGisInvocation;
+	source: string;
+	provider: string;
+	rank: number;
+	locator: string;
+	path: string;
+	resourceBase: OpenGisResourceBase;
+}
+
+/** One loaded skill body returned by the provider. */
+export interface OpenGisSkillDefinition {
+	name: string;
+	description: string;
+	invocation: OpenGisInvocation;
+	source: string;
+	provider: string;
+	resourceBase: OpenGisResourceBase;
+	path: string;
+	content: string;
+}
+
+/** The borrowed provider object the skill registry holds. */
+export interface OpenGisSkillProvider {
+	name: string;
+	list(options?: { signal?: AbortSignal }): Promise<readonly OpenGisSkillCandidate[]>;
+	get(candidate: OpenGisSkillCandidate, options?: { signal?: AbortSignal }): Promise<OpenGisSkillDefinition>;
+}
+
 /** Cordis context surface used by this plugin. */
 export interface OpenGisSkillHost {
-	/** Own a registration so plugin unload removes it. */
-	effect(callback: () => unknown, label?: string): unknown;
-	/** The skill registry this provider registers on. */
 	skills: {
-		registerProvider(create: (control: { signal: AbortSignal; invalidate(): void }) => unknown): unknown;
+		registerProvider(create: (control: { signal: AbortSignal; invalidate(): void }) => OpenGisSkillProvider): unknown;
 	};
 }
 
-/** Register the bundled OpenGIS skill provider on `ctx.skills`. */
+/** Register the bundled OpenGIS skill provider on "ctx.skills". */
 export declare function apply(ctx: OpenGisSkillHost): void;

package/lib/index.js

@@ -1,22 +1,21 @@
 /**
  * Bundled OpenGIS skill provider for DeepSeek Harness.
  *
- * The package ships the 32 GIS skills of the opengis-skills repository under
- * `assets/<skill>/SKILL.md` and registers one skill provider on `ctx.skills`.
+ * The package ships the "gis/" skills of the opengis-skills repository under
+ * "assets/<skill>/SKILL.md" and registers one skill provider on "ctx.skills".
  * Discovery reads only the frontmatter; the instruction body and the
- * `reference/*.md` files are read on demand, and each candidate carries the
+ * "reference/*.md" files are read on demand, and each candidate carries the
  * skill directory as its resource base so relative references resolve.
  *
  * @module @dsh-gis/dsh-opengis-skill
  */
 
-import { readFileSync, readdirSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { readSkillCatalog, resourceBaseOf } from "./catalog.js";
 import { parseSkillFile } from "./skill-file.js";
 
-/** Provider name registered on `ctx.skills` (the runtime name "runtime" is reserved). */
+/** Provider name registered on "ctx.skills" (the runtime name "runtime" is reserved). */
 const PROVIDER_NAME = "opengis";
 
 /** Source label carried by every candidate and definition. */
@@ -25,59 +24,43 @@ const SOURCE = "opengis";
 /** Standard rank for packaged skill providers and bundled roots (BUNDLED_SKILL_RANK). */
 const RANK = 600;
 
-/** The instruction file name inside one skill directory. */
-const SKILL_FILE = "SKILL.md";
-
 /** Absolute asset root, resolved from this module inside the installed package. */
 const ASSET_ROOT = fileURLToPath(new URL("../assets/", import.meta.url));
 
 /** Stable Loader identity. */
 const name = "opengis-skill";
 
-/** The skill registry must exist before `apply` runs. */
+/** The skill registry must exist before "apply" runs. */
 const inject = ["skills"];
 
+/** The invocation policy every bundled skill uses: model and user may load it. */
+const INVOCATION = { modelInvocable: true, userInvocable: true };
+
 /**
- * Read every `assets/<name>/SKILL.md` bundle and validate it.
+ * Read and validate the packaged skill catalog, annotating asset failures with
+ * the plugin name so a broken installation is diagnosable from the host log.
  *
- * @param assetRoot - absolute directory holding one subdirectory per skill.
- * @returns the validated skills sorted by name.
- * @throws when two skills share a name or a directory disagrees with its frontmatter.
+ * @returns the validated catalog sorted by name.
+ * @throws when the packaged assets are missing or malformed.
  */
-function readAssetSkills(assetRoot) {
-	const skills = [];
-	const seen = new Set();
-	for (const entry of readdirSync(assetRoot, { withFileTypes: true })) {
-		if (!entry.isDirectory()) continue;
-		const directory = join(assetRoot, entry.name);
-		const path = join(directory, SKILL_FILE);
-		if (statSync(path, { throwIfNoEntry: false })?.isFile() !== true) continue;
-		const parsed = parseSkillFile(readFileSync(path, "utf8"), path);
-		if (parsed.name !== entry.name) {
-			throw new Error(`opengis-skill: ${path} declares "${parsed.name}" but its directory is "${entry.name}"`);
-		}
-		if (seen.has(parsed.name)) throw new Error(`opengis-skill: duplicate skill name "${parsed.name}"`);
-		seen.add(parsed.name);
-		skills.push({ name: parsed.name, description: parsed.description, directory, path });
+function loadSkills() {
+	try {
+		return readSkillCatalog(ASSET_ROOT);
+	} catch (cause) {
+		throw new Error("opengis-skill: cannot load skill assets from " + ASSET_ROOT + ": " + cause.message, { cause });
 	}
-	return skills.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
-}
-
-/** Render the directory resource base with forward slashes for the model. */
-function resourceBaseOf(directory) {
-	return { kind: "directory", path: directory.split(sep).join("/") };
 }
 
-/** The invocation policy every bundled skill uses: model and user may load it. */
-const INVOCATION = { modelInvocable: true, userInvocable: true };
-
 /**
- * Register the bundled OpenGIS skill provider on `ctx.skills`.
+ * Register the bundled OpenGIS skill provider on "ctx.skills".
+ *
+ * The returned disposer of "registerProvider" is owned by the calling fiber,
+ * so plugin unload removes the provider without an extra "ctx.effect" wrapper.
  *
  * @param ctx - Cordis context carrying the skill registry.
  */
 function apply(ctx) {
-	const skills = readAssetSkills(ASSET_ROOT);
+	const skills = loadSkills();
 	const byName = new Map(skills.map((skill) => [skill.name, skill]));
 	const candidates = skills.map((skill) => ({
 		name: skill.name,
@@ -95,11 +78,16 @@ function apply(ctx) {
 		list: () => Promise.resolve(candidates),
 		async get(candidate, options) {
 			const skill = byName.get(candidate.name);
-			if (skill === undefined) throw new Error(`opengis-skill: unknown skill "${candidate.name}"`);
+			if (skill === undefined) throw new Error('opengis-skill: unknown skill "' + candidate.name + '"');
 			const raw = await readFile(skill.path, { encoding: "utf8", signal: options?.signal });
-			const parsed = parseSkillFile(raw, skill.path);
+			let parsed;
+			try {
+				parsed = parseSkillFile(raw, skill.path);
+			} catch (cause) {
+				throw new Error("opengis-skill: " + cause.message, { cause });
+			}
 			if (parsed.name !== candidate.name) {
-				throw new Error(`opengis-skill: ${skill.path} now declares "${parsed.name}"`);
+				throw new Error("opengis-skill: " + skill.path + ' now declares "' + parsed.name + '" but was listed as "' + candidate.name + '"');
 			}
 			return {
 				name: parsed.name,
@@ -113,7 +101,7 @@ function apply(ctx) {
 			};
 		}
 	};
-	ctx.effect(() => ctx.skills.registerProvider(() => provider), "opengis-skill: skill provider");
+	ctx.skills.registerProvider(() => provider);
 }
 
 export { apply, inject, name };

package/lib/markdown-links.d.ts

@@ -0,0 +1,11 @@
+/** Extract every relative file link target from one markdown document. */
+export declare function relativeMarkdownLinks(markdown: string): string[];
+
+/** Resolve one relative markdown link against its containing file. */
+export declare function resolveMarkdownLink(fromFile: string, link: string): { path: string; fragment: string };
+
+/** Report whether one resolved path stays inside a directory. */
+export declare function isInsideDirectory(root: string, candidate: string): boolean;
+
+/** Collect every problem with the relative links in one markdown document. */
+export declare function findMarkdownLinkProblems(fromFile: string, markdown: string, root: string): string[];

package/lib/markdown-links.js

@@ -0,0 +1,103 @@
+/**
+ * Markdown link helpers shared by the validation script and the tests.
+ *
+ * Only relative file links are inspected: scheme links, fragment-only links,
+ * and absolute URLs are ignored. Resolution is lexical, so a link must stay
+ * inside the directory the caller allows.
+ *
+ * @module @dsh-gis/dsh-opengis-skill/markdown-links
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+
+/** One inline markdown link target, as written. */
+const LINK = /\]\(([^)]+)\)/gu;
+
+/** A link with a URI scheme or a fragment-only target is not a file link. */
+const NON_FILE_LINK = /^(?:[a-z][a-z0-9+.-]*:|#)/iu;
+
+/**
+ * Extract every relative file link target from one markdown document.
+ *
+ * @param markdown - the complete markdown text.
+ * @returns the targets still carrying their optional fragment or query text.
+ */
+export function relativeMarkdownLinks(markdown) {
+	const links = [];
+	for (const match of markdown.matchAll(LINK)) {
+		const target = match[1].trim();
+		if (target.length === 0 || NON_FILE_LINK.test(target)) continue;
+		links.push(target);
+	}
+	return links;
+}
+
+/**
+ * Resolve one relative markdown link against its containing file.
+ *
+ * @param fromFile - the markdown file that contains the link.
+ * @param link - a relative link target, optionally with a "#fragment".
+ * @returns the absolute target path and the fragment without its "#".
+ * @throws when the target contains invalid percent-encoding.
+ */
+export function resolveMarkdownLink(fromFile, link) {
+	const hash = link.indexOf("#");
+	const pathPart = hash === -1 ? link : link.slice(0, hash);
+	const fragment = hash === -1 ? "" : link.slice(hash + 1);
+	if (pathPart.length === 0) return { path: fromFile, fragment };
+	let decoded;
+	try {
+		decoded = decodeURIComponent(pathPart);
+	} catch (cause) {
+		throw new Error('invalid URL encoding in link "' + link + '"', { cause });
+	}
+	if (decoded.length === 0) return { path: fromFile, fragment };
+	return { path: resolve(dirname(fromFile), decoded), fragment };
+}
+
+/**
+ * Report whether one resolved path stays inside a directory.
+ *
+ * @param root - the allowed directory.
+ * @param candidate - the resolved path to test.
+ * @returns whether the candidate equals or is below the root.
+ */
+export function isInsideDirectory(root, candidate) {
+	const rootKey = pathKey(root);
+	const candidateKey = pathKey(candidate);
+	return candidateKey === rootKey || candidateKey.startsWith(rootKey + sep);
+}
+
+/**
+ * Collect every problem with the relative links in one markdown document.
+ *
+ * @param fromFile - the markdown file that contains the links; also used in messages.
+ * @param markdown - the complete markdown text.
+ * @param root - the directory every link must stay inside.
+ * @returns human-readable problems, empty when every link is valid.
+ */
+export function findMarkdownLinkProblems(fromFile, markdown, root) {
+	const problems = [];
+	for (const link of relativeMarkdownLinks(markdown)) {
+		let resolved;
+		try {
+			resolved = resolveMarkdownLink(fromFile, link);
+		} catch (cause) {
+			problems.push(fromFile + ": " + cause.message);
+			continue;
+		}
+		if (!isInsideDirectory(root, resolved.path)) {
+			problems.push(fromFile + ": link escapes " + root + ": " + link);
+			continue;
+		}
+		if (!existsSync(resolved.path)) problems.push(fromFile + ": broken link " + link);
+	}
+	return problems;
+}
+
+/** Normalize one path for comparison, folding case on Windows. */
+function pathKey(value) {
+	const normalized = resolve(value);
+	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}