@eya46/dsh-plugin-info 0.0.2

package/lib/index.js

@@ -0,0 +1,543 @@
+import { createRequire } from "node:module";
+import z from "@deepseek-ai/schemastery";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/http.ts
+/** Write a JSON response. */
+function sendJson(res, status, payload) {
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(payload));
+}
+/** Parse the request URL against a dummy origin so query strings work. */
+function requestUrl(req) {
+	return new URL(req.url ?? "/", "http://127.0.0.1");
+}
+//#endregion
+//#region src/semver.ts
+/** Strip a leading `v` and build metadata. */
+function normalizeVersion(input) {
+	const trimmed = input.trim();
+	const withoutBuild = trimmed.split("+")[0] ?? trimmed;
+	return withoutBuild.startsWith("v") || withoutBuild.startsWith("V") ? withoutBuild.slice(1) : withoutBuild;
+}
+/** Parse `1.2.3`, `1.2.3-rc.1`, or `v1.2.3`. Returns undefined when not numeric. */
+function parseVersion(input) {
+	const normalized = normalizeVersion(input);
+	const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(normalized);
+	if (match === null) return void 0;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) return void 0;
+	return {
+		major,
+		minor,
+		patch,
+		prerelease: match[4] === void 0 || match[4].length === 0 ? [] : match[4].split(".")
+	};
+}
+function compareIdentifier(left, right) {
+	const leftNum = /^\d+$/.test(left) ? Number(left) : void 0;
+	const rightNum = /^\d+$/.test(right) ? Number(right) : void 0;
+	if (leftNum !== void 0 && rightNum !== void 0) return leftNum - rightNum;
+	if (leftNum !== void 0) return -1;
+	if (rightNum !== void 0) return 1;
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Compare two parsed versions. Negative when `left` is older. */
+function compareParsed(left, right) {
+	if (left.major !== right.major) return left.major - right.major;
+	if (left.minor !== right.minor) return left.minor - right.minor;
+	if (left.patch !== right.patch) return left.patch - right.patch;
+	if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+	if (left.prerelease.length === 0) return 1;
+	if (right.prerelease.length === 0) return -1;
+	const count = Math.max(left.prerelease.length, right.prerelease.length);
+	for (let index = 0; index < count; index += 1) {
+		const leftPart = left.prerelease[index];
+		const rightPart = right.prerelease[index];
+		if (leftPart === void 0) return -1;
+		if (rightPart === void 0) return 1;
+		const delta = compareIdentifier(leftPart, rightPart);
+		if (delta !== 0) return delta;
+	}
+	return 0;
+}
+/** True when `latest` is a newer published version than `installed`. */
+function hasNewerVersion(installed, latest) {
+	if (installed === void 0 || latest === void 0) return false;
+	if (normalizeVersion(installed) === normalizeVersion(latest)) return false;
+	const parsedInstalled = parseVersion(installed);
+	const parsedLatest = parseVersion(latest);
+	if (parsedInstalled === void 0 || parsedLatest === void 0) return normalizeVersion(installed) !== normalizeVersion(latest);
+	return compareParsed(parsedLatest, parsedInstalled) > 0;
+}
+//#endregion
+//#region src/profile.ts
+/** Classify a profile dependency spec. */
+function classifySpec(spec) {
+	const trimmed = spec.trim();
+	if (trimmed.startsWith("file:")) return "file";
+	if (trimmed.startsWith("link:")) return "link";
+	if (trimmed.startsWith("git+") || trimmed.startsWith("github:") || trimmed.startsWith("git://") || trimmed.startsWith("ssh://") || /\.git(?:#|$)/.test(trimmed)) return "git";
+	if (trimmed.startsWith(".") || trimmed.startsWith("/") || /^[A-Za-z]:[\\/]/.test(trimmed)) return "file";
+	if (trimmed.startsWith("http://") || trimmed.startsWith("https://") || trimmed.startsWith("workspace:")) return "other";
+	return "registry";
+}
+/** User-added plugins are the profile's own `dependencies`, not in-box bundles. */
+function listUserPlugins(manifest) {
+	const dependencies = manifest.dependencies ?? {};
+	return Object.entries(dependencies).filter(([name, spec]) => name.trim().length > 0 && spec.trim().length > 0).map(([name, spec]) => ({
+		name,
+		spec,
+		source: classifySpec(spec)
+	})).sort((left, right) => left.name.localeCompare(right.name));
+}
+/** Read a profile package.json. */
+function readProfileManifest(dir) {
+	const text = readFileSync(join(dir, "package.json"), "utf8");
+	const parsed = JSON.parse(text);
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("profile package.json is not an object");
+	return parsed;
+}
+/** Resolve one installed package.json from the profile directory. */
+function readInstalledPackage(profileDir, name) {
+	const direct = join(profileDir, "node_modules", ...name.split("/"), "package.json");
+	const path = existsSync(direct) ? direct : resolveViaRequire(profileDir, name);
+	if (path === void 0) return void 0;
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+	const record = parsed;
+	return {
+		name: typeof record.name === "string" ? record.name : name,
+		...typeof record.version === "string" && record.version.length > 0 ? { version: record.version } : {},
+		...typeof record.description === "string" && record.description.length > 0 ? { description: record.description } : {},
+		...typeof record.homepage === "string" && record.homepage.length > 0 ? { homepage: record.homepage } : {},
+		...record.repository === void 0 ? {} : { repository: record.repository }
+	};
+}
+function resolveViaRequire(profileDir, name) {
+	try {
+		return createRequire(join(profileDir, "package.json")).resolve(`${name}/package.json`);
+	} catch {
+		return;
+	}
+}
+/** Turn a package `repository` field into a browsable https URL. */
+function repositoryUrlOf(repository) {
+	if (repository === void 0) return void 0;
+	const raw = typeof repository === "string" ? repository : repository.url;
+	if (raw === void 0 || raw.trim().length === 0) return void 0;
+	const github = parseGithubRepo(raw);
+	if (github !== void 0) return `https://github.com/${github.owner}/${github.repo}`;
+	if (raw.startsWith("http://") || raw.startsWith("https://")) return raw.replace(/\.git$/, "");
+	return raw;
+}
+/** owner/repo extracted from common GitHub repository spellings. */
+function parseGithubRepo(input) {
+	const trimmed = input.trim();
+	for (const pattern of [
+		/^github:([^/]+)\/([^#]+)/i,
+		/^(?:git\+)?https?:\/\/github\.com\/([^/]+)\/([^/#]+)/i,
+		/^(?:git\+)?ssh:\/\/git@github\.com\/([^/]+)\/([^/#]+)/i,
+		/^git@github\.com:([^/]+)\/([^/#]+)/i
+	]) {
+		const match = pattern.exec(trimmed);
+		if (match === null) continue;
+		const owner = match[1];
+		const repo = match[2]?.replace(/\.git$/i, "");
+		if (owner === void 0 || repo === void 0 || owner.length === 0 || repo.length === 0) continue;
+		return {
+			owner,
+			repo
+		};
+	}
+}
+//#endregion
+//#region src/registry.ts
+/** Join a registry origin with a package name, encoding the scoped slash. */
+function packumentUrl(registryUrl, name) {
+	return `${registryUrl.replace(/\/+$/, "")}/${name.startsWith("@") ? name.replace("/", "%2f") : name}`;
+}
+/** Latest dist-tag, when the packument has one. */
+function latestVersionOf(packument) {
+	const latest = packument["dist-tags"]?.latest;
+	return typeof latest === "string" && latest.length > 0 ? latest : void 0;
+}
+/** Most recently published versions, newest first. */
+function recentVersions(packument, installedVersion, limit) {
+	const versions = Object.keys(packument.versions ?? {});
+	const time = packument.time ?? {};
+	versions.sort((left, right) => timestampOf(time[right]) - timestampOf(time[left]));
+	const latest = latestVersionOf(packument);
+	const installed = installedVersion === void 0 ? void 0 : installedVersion;
+	return versions.slice(0, Math.max(0, limit)).map((version) => ({
+		version,
+		...typeof time[version] === "string" ? { publishedAt: time[version] } : {},
+		latest: latest === version,
+		installed: installed === version
+	}));
+}
+/** The published version immediately older than `version` by publish time. */
+function previousPublishedVersion(packument, version) {
+	const versions = Object.keys(packument.versions ?? {});
+	const time = packument.time ?? {};
+	versions.sort((left, right) => timestampOf(time[right]) - timestampOf(time[left]));
+	const index = versions.indexOf(version);
+	if (index < 0) return void 0;
+	return versions[index + 1];
+}
+function timestampOf(value) {
+	if (value === void 0) return 0;
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? 0 : parsed;
+}
+/** Clamp the versions query to a sane positive integer. */
+function resolveVersionLimit(raw, fallback) {
+	const value = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : fallback;
+	if (!Number.isFinite(value)) return fallback;
+	return Math.min(50, Math.max(1, Math.trunc(value)));
+}
+//#endregion
+//#region src/service.ts
+/** Query surface used by the HTTP API and tests. */
+var PluginInfoService = class {
+	config;
+	fetchJson;
+	now;
+	packuments = /* @__PURE__ */ new Map();
+	notes = /* @__PURE__ */ new Map();
+	constructor(config, fetchJson, now = () => Date.now()) {
+		this.config = config;
+		this.fetchJson = fetchJson;
+		this.now = now;
+	}
+	/** List user-added plugins for one profile directory. */
+	async listPlugins(profileDir) {
+		const manifest = readProfileManifest(profileDir);
+		const listed = listUserPlugins(manifest).filter((item) => isAllowedScope(item.name, this.config.allowScopes));
+		const plugins = await Promise.all(listed.map(async (item) => this.describePlugin(profileDir, item.name, item.spec)));
+		return {
+			profile: manifest.name ?? profileDir,
+			plugins
+		};
+	}
+	/** Recent published versions for one user-added plugin. */
+	async listVersions(profileDir, name, limit) {
+		const plugin = findUserPlugin(profileDir, name, this.config.allowScopes);
+		const installed = readInstalledPackage(profileDir, name);
+		if (plugin.source !== "registry") {
+			const installedVersion = installed?.version;
+			return {
+				name,
+				...installedVersion === void 0 ? {} : { installedVersion },
+				versions: installedVersion === void 0 ? [] : [{
+					version: installedVersion,
+					latest: false,
+					installed: true
+				}]
+			};
+		}
+		const packument = await this.loadPackument(name);
+		const installedVersion = installed?.version;
+		const latestVersion = latestVersionOf(packument);
+		return {
+			name,
+			...installedVersion === void 0 ? {} : { installedVersion },
+			...latestVersion === void 0 ? {} : { latestVersion },
+			versions: recentVersions(packument, installedVersion, limit)
+		};
+	}
+	/** Update notes for one published version. */
+	async versionNotes(profileDir, name, version) {
+		findUserPlugin(profileDir, name, this.config.allowScopes);
+		const cacheKey = `${name}@${version}`;
+		const cached = this.notes.get(cacheKey);
+		if (cached !== void 0 && cached.expiresAt > this.now()) return cached.value;
+		const notes = await this.loadNotes(profileDir, name, version);
+		this.notes.set(cacheKey, {
+			value: notes,
+			expiresAt: this.now() + this.config.cacheTtlMs
+		});
+		return notes;
+	}
+	async describePlugin(profileDir, name, spec) {
+		const source = classifySpec(spec);
+		const installed = readInstalledPackage(profileDir, name);
+		const installedRepository = repositoryUrlOf(installed?.repository);
+		const summary = {
+			name,
+			spec,
+			source,
+			hasUpdate: false,
+			...installed?.description === void 0 ? {} : { description: installed.description },
+			...installed?.version === void 0 ? {} : { installedVersion: installed.version },
+			...installed?.homepage === void 0 ? {} : { homepage: installed.homepage },
+			...installedRepository === void 0 ? {} : { repository: installedRepository }
+		};
+		if (source !== "registry") return summary;
+		try {
+			const packument = await this.loadPackument(name);
+			const latestVersion = latestVersionOf(packument);
+			const homepage = summary.homepage ?? packument.homepage;
+			const repository = summary.repository ?? repositoryUrlOf(packument.repository);
+			return {
+				...summary,
+				...packument.description === void 0 || summary.description !== void 0 ? {} : { description: packument.description },
+				...latestVersion === void 0 ? {} : { latestVersion },
+				hasUpdate: hasNewerVersion(summary.installedVersion, latestVersion),
+				...homepage === void 0 ? {} : { homepage },
+				...repository === void 0 ? {} : { repository }
+			};
+		} catch (error) {
+			return {
+				...summary,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async loadPackument(name) {
+		const cached = this.packuments.get(name);
+		if (cached !== void 0 && cached.expiresAt > this.now()) return cached.value;
+		const payload = await this.fetchJson(packumentUrl(this.config.registryUrl, name), this.config.timeoutMs, { accept: "application/json" });
+		if (payload === null || typeof payload !== "object" || Array.isArray(payload)) throw new Error(`registry returned a non-object packument for ${name}`);
+		const packument = payload;
+		this.packuments.set(name, {
+			value: packument,
+			expiresAt: this.now() + this.config.cacheTtlMs
+		});
+		return packument;
+	}
+	async loadNotes(profileDir, name, version) {
+		const installed = readInstalledPackage(profileDir, name);
+		let packument;
+		try {
+			packument = await this.loadPackument(name);
+		} catch {
+			packument = void 0;
+		}
+		const repository = repositoryUrlOf(installed?.repository) ?? repositoryUrlOf(packument?.repository);
+		const github = repository === void 0 ? void 0 : parseGithubRepo(repository);
+		const publishedAt = packument?.time?.[version];
+		const base = {
+			name,
+			version,
+			source: "none",
+			...publishedAt === void 0 ? {} : { publishedAt }
+		};
+		if (github === void 0) return base;
+		const release = await this.fetchGithubRelease(github.owner, github.repo, version);
+		if (release !== void 0) return {
+			...base,
+			source: "github-release",
+			...release.title === void 0 ? {} : { title: release.title },
+			...release.body === void 0 ? {} : { body: release.body },
+			...release.url === void 0 ? {} : { url: release.url },
+			...release.publishedAt === void 0 ? {} : { publishedAt: release.publishedAt }
+		};
+		const previous = packument === void 0 ? void 0 : previousPublishedVersion(packument, version);
+		if (previous === void 0) return base;
+		const compare = await this.fetchGithubCompare(github.owner, github.repo, previous, version);
+		if (compare === void 0) return base;
+		return {
+			...base,
+			source: "github-compare",
+			url: compare.url,
+			commits: compare.commits
+		};
+	}
+	async fetchGithubRelease(owner, repo, version) {
+		const tags = unique([version, `v${version}`]);
+		for (const tag of tags) try {
+			const payload = await this.fetchJson(`https://api.github.com/repos/${owner}/${repo}/releases/tags/${encodeURIComponent(tag)}`, this.config.timeoutMs, githubHeaders());
+			if (payload === null || typeof payload !== "object" || Array.isArray(payload)) continue;
+			const record = payload;
+			if (record.message === "Not Found") continue;
+			const title = typeof record.name === "string" && record.name.length > 0 ? record.name : void 0;
+			const body = typeof record.body === "string" && record.body.trim().length > 0 ? record.body : void 0;
+			const url = typeof record.html_url === "string" ? record.html_url : void 0;
+			const publishedAt = typeof record.published_at === "string" ? record.published_at : void 0;
+			return {
+				...title === void 0 ? {} : { title },
+				...body === void 0 ? {} : { body },
+				...url === void 0 ? {} : { url },
+				...publishedAt === void 0 ? {} : { publishedAt }
+			};
+		} catch {
+			continue;
+		}
+	}
+	async fetchGithubCompare(owner, repo, previous, version) {
+		const bases = unique([previous, `v${previous}`]);
+		const heads = unique([version, `v${version}`]);
+		for (const base of bases) for (const head of heads) try {
+			const payload = await this.fetchJson(`https://api.github.com/repos/${owner}/${repo}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`, this.config.timeoutMs, githubHeaders());
+			if (payload === null || typeof payload !== "object" || Array.isArray(payload)) continue;
+			const record = payload;
+			if (!Array.isArray(record.commits)) continue;
+			const commits = [];
+			for (const item of record.commits) {
+				if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+				const commitRecord = item;
+				const sha = typeof commitRecord.sha === "string" ? commitRecord.sha.slice(0, 7) : void 0;
+				const nested = commitRecord.commit;
+				const message = nested !== null && typeof nested === "object" && !Array.isArray(nested) && typeof nested.message === "string" ? String(nested.message).split("\n")[0] : void 0;
+				if (sha === void 0 || message === void 0 || message.length === 0) continue;
+				const url = typeof commitRecord.html_url === "string" ? commitRecord.html_url : void 0;
+				commits.push({
+					sha,
+					message,
+					...url === void 0 ? {} : { url }
+				});
+			}
+			if (commits.length === 0) continue;
+			return {
+				url: typeof record.html_url === "string" ? record.html_url : `https://github.com/${owner}/${repo}/compare/${base}...${head}`,
+				commits: commits.slice(-20).reverse()
+			};
+		} catch {
+			continue;
+		}
+	}
+};
+function findUserPlugin(profileDir, name, allowScopes) {
+	const match = listUserPlugins(readProfileManifest(profileDir)).find((item) => item.name === name);
+	if (match === void 0) throw new Error(`"${name}" is not a user-added plugin in this profile`);
+	if (allowScopes !== void 0 && !isAllowedScope(match.name, allowScopes)) throw new Error(`"${name}" is filtered out by allowScopes`);
+	return match;
+}
+function unique(values) {
+	return [...new Set(values.filter((value) => value.length > 0))];
+}
+/** True when `name` matches one of the configured scope prefixes (empty list = allow all). */
+function isAllowedScope(name, allowScopes) {
+	if (allowScopes === void 0 || allowScopes.length === 0) return true;
+	const lower = name.toLowerCase();
+	return allowScopes.some((prefix) => lower.startsWith(prefix.toLowerCase()));
+}
+function githubHeaders() {
+	const headers = {
+		accept: "application/vnd.github+json",
+		"user-agent": "@eya46/dsh-plugin-info"
+	};
+	const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+	if (token !== void 0 && token.length > 0) headers.authorization = `Bearer ${token}`;
+	return headers;
+}
+/** Resolve the current profile directory from the Loader base URL. */
+function profileDirFromBaseUrl(baseUrl) {
+	if (baseUrl === void 0 || baseUrl.length === 0) throw new Error("ctx.baseUrl is unset — cannot locate the current profile");
+	return fileURLToPath(new URL(".", baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`));
+}
+/** Default JSON fetch used by the live plugin. */
+async function fetchJson(url, timeoutMs, headers = {}) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`request timed out after ${timeoutMs}ms`)), timeoutMs);
+	try {
+		const response = await fetch(url, {
+			headers,
+			signal: controller.signal
+		});
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			throw new Error(`HTTP ${response.status} ${response.statusText}${text.length > 0 ? `: ${text.slice(0, 200)}` : ""}`);
+		}
+		return await response.json();
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+//#region src/index.ts
+/** Cordis plugin name used by Loader diagnostics. */
+const name = "dsh-plugin-info";
+/** Default version window shown by the settings page. */
+const DEFAULT_VERSION_LIMIT = 10;
+/** Runtime schema for {@link Config}. */
+const Config = z.object({
+	registryUrl: z.string().default("https://registry.npmjs.org"),
+	defaultVersionLimit: z.number().step(1).min(1).max(50).default(10),
+	timeoutMs: z.number().step(1).min(1e3).default(15e3),
+	cacheTtlMs: z.number().step(1).min(0).default(3e5),
+	allowScopes: z.array(z.string()).default(["@eya46/"])
+});
+/**
+* Register the plugin-info HTTP API when a web server is present.
+* @param ctx - Cordis context; `webServer` is optional so headless boots stay inert.
+* @param config - registry and cache knobs.
+*/
+function apply(ctx, config) {
+	const service = new PluginInfoService(config, fetchJson);
+	ctx.inject(["webServer"], (sctx) => {
+		sctx.effect(() => {
+			const disposers = [
+				sctx.webServer.register({
+					kind: "exact",
+					path: "/plugin-info/api/plugins",
+					handler: async (_req, res) => {
+						try {
+							sendJson(res, 200, await service.listPlugins(profileDirFromBaseUrl(sctx.baseUrl)));
+						} catch (error) {
+							sendError(res, error);
+						}
+					}
+				}),
+				sctx.webServer.register({
+					kind: "exact",
+					path: "/plugin-info/api/versions",
+					handler: async (req, res) => {
+						try {
+							const url = requestUrl(req);
+							const name = url.searchParams.get("name") ?? "";
+							if (name.length === 0) {
+								sendJson(res, 400, {
+									ok: false,
+									reason: "name is required"
+								});
+								return;
+							}
+							const limit = resolveVersionLimit(url.searchParams.get("limit"), config.defaultVersionLimit);
+							sendJson(res, 200, await service.listVersions(profileDirFromBaseUrl(sctx.baseUrl), name, limit));
+						} catch (error) {
+							sendError(res, error);
+						}
+					}
+				}),
+				sctx.webServer.register({
+					kind: "exact",
+					path: "/plugin-info/api/notes",
+					handler: async (req, res) => {
+						try {
+							const url = requestUrl(req);
+							const name = url.searchParams.get("name") ?? "";
+							const version = url.searchParams.get("version") ?? "";
+							if (name.length === 0 || version.length === 0) {
+								sendJson(res, 400, {
+									ok: false,
+									reason: "name and version are required"
+								});
+								return;
+							}
+							sendJson(res, 200, await service.versionNotes(profileDirFromBaseUrl(sctx.baseUrl), name, version));
+						} catch (error) {
+							sendError(res, error);
+						}
+					}
+				})
+			];
+			return () => {
+				for (const dispose of disposers) dispose();
+			};
+		}, "dsh-plugin-info.web-api");
+	});
+}
+function sendError(res, error) {
+	sendJson(res, 500, {
+		ok: false,
+		reason: "error",
+		message: error instanceof Error ? error.message : String(error)
+	});
+}
+//#endregion
+export { Config, DEFAULT_VERSION_LIMIT, PluginInfoService, apply, classifySpec, fetchJson, hasNewerVersion, latestVersionOf, listUserPlugins, name, packumentUrl, parseGithubRepo, parseVersion, profileDirFromBaseUrl, recentVersions, repositoryUrlOf, resolveVersionLimit };

package/lib/types/client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @eya46/dsh-plugin-info — browser half.
+ *
+ * A settings page listing plugins the current profile added, with update
+ * marks and a per-plugin version drawer (default 10) that can open notes.
+ *
+ * @module @eya46/dsh-plugin-info/client
+ */
+interface ModuleLoader {
+    load(handoff: {
+        id: string;
+        factory: (require: (spec: string) => unknown) => Record<string, unknown>;
+    }): void;
+}
+interface DshWindow {
+    __ModuleLoader__?: ModuleLoader;
+}
+interface MinimalReact {
+    createElement(type: unknown, props: Record<string, unknown> | null, ...children: unknown[]): unknown;
+    useState<T>(initial: T | (() => T)): [T, (next: T | ((prev: T) => T)) => void];
+    useEffect(effect: () => void | (() => void), deps?: unknown[]): void;
+    useCallback<T>(fn: T, deps: unknown[]): T;
+}
+interface SlotsService {
+    inject(key: string, register: () => void): void;
+    register(options: Record<string, unknown>, component: unknown): void;
+}
+interface ClientContext {
+    slots: SlotsService;
+    /** Cordis fiber-lifetime effect: runs now, disposes on fiber unload. */
+    effect(callback: () => (() => void) | void, label?: string): () => void;
+}
+interface PluginRow {
+    name: string;
+    description?: string;
+    spec: string;
+    source: string;
+    installedVersion?: string;
+    latestVersion?: string;
+    hasUpdate: boolean;
+    homepage?: string;
+    repository?: string;
+    error?: string;
+}
+interface VersionRow {
+    version: string;
+    publishedAt?: string;
+    latest: boolean;
+    installed: boolean;
+}
+interface VersionNotes {
+    name: string;
+    version: string;
+    source: 'github-release' | 'github-compare' | 'none';
+    publishedAt?: string;
+    title?: string;
+    body?: string;
+    url?: string;
+    commits?: Array<{
+        sha: string;
+        message: string;
+        url?: string;
+    }>;
+}

package/lib/types/http.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Read a JSON request body (1 MB cap). */
+export declare function readJsonBody(req: IncomingMessage): Promise<unknown>;
+/** Write a JSON response. */
+export declare function sendJson(res: ServerResponse, status: number, payload: unknown): void;
+/** Parse the request URL against a dummy origin so query strings work. */
+export declare function requestUrl(req: IncomingMessage): URL;
+//# sourceMappingURL=http.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@eya46/dsh-plugin-info` lists plugins the current profile added, marks
+ * available registry updates, and exposes recent version notes.
+ * @module @eya46/dsh-plugin-info
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { PluginConfig } from './types.ts';
+export { classifySpec, listUserPlugins, parseGithubRepo, repositoryUrlOf } from './profile.ts';
+export { hasNewerVersion, parseVersion } from './semver.ts';
+export { latestVersionOf, packumentUrl, recentVersions, resolveVersionLimit } from './registry.ts';
+export { fetchJson, PluginInfoService, profileDirFromBaseUrl } from './service.ts';
+export type { InstalledPackage, Packument, PluginConfig, PluginSource, PluginSummary, PluginVersionRow, ProfileManifest, VersionNotes, } from './types.ts';
+/** Cordis plugin name used by Loader diagnostics. */
+export declare const name = "dsh-plugin-info";
+/** Default version window shown by the settings page. */
+export declare const DEFAULT_VERSION_LIMIT = 10;
+/** Cordis plugin configuration. */
+export interface Config extends PluginConfig {
+}
+/** Runtime schema for {@link Config}. */
+export declare const Config: z<Config>;
+/**
+ * Register the plugin-info HTTP API when a web server is present.
+ * @param ctx - Cordis context; `webServer` is optional so headless boots stay inert.
+ * @param config - registry and cache knobs.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/profile.d.ts

@@ -0,0 +1,21 @@
+import type { InstalledPackage, PluginSource, ProfileManifest } from './types.ts';
+/** Classify a profile dependency spec. */
+export declare function classifySpec(spec: string): PluginSource;
+/** User-added plugins are the profile's own `dependencies`, not in-box bundles. */
+export declare function listUserPlugins(manifest: ProfileManifest): Array<{
+    name: string;
+    spec: string;
+    source: PluginSource;
+}>;
+/** Read a profile package.json. */
+export declare function readProfileManifest(dir: string): ProfileManifest;
+/** Resolve one installed package.json from the profile directory. */
+export declare function readInstalledPackage(profileDir: string, name: string): InstalledPackage | undefined;
+/** Turn a package `repository` field into a browsable https URL. */
+export declare function repositoryUrlOf(repository: InstalledPackage['repository']): string | undefined;
+/** owner/repo extracted from common GitHub repository spellings. */
+export declare function parseGithubRepo(input: string): {
+    owner: string;
+    repo: string;
+} | undefined;
+//# sourceMappingURL=profile.d.ts.map

package/lib/types/registry.d.ts

@@ -0,0 +1,12 @@
+import type { Packument, PluginVersionRow } from './types.ts';
+/** Join a registry origin with a package name, encoding the scoped slash. */
+export declare function packumentUrl(registryUrl: string, name: string): string;
+/** Latest dist-tag, when the packument has one. */
+export declare function latestVersionOf(packument: Packument): string | undefined;
+/** Most recently published versions, newest first. */
+export declare function recentVersions(packument: Packument, installedVersion: string | undefined, limit: number): PluginVersionRow[];
+/** The published version immediately older than `version` by publish time. */
+export declare function previousPublishedVersion(packument: Packument, version: string): string | undefined;
+/** Clamp the versions query to a sane positive integer. */
+export declare function resolveVersionLimit(raw: unknown, fallback: number): number;
+//# sourceMappingURL=registry.d.ts.map