dsh-skill-hub 0.3.19 → 0.3.20

package/lib/index.js

@@ -83,29 +83,30 @@ const HUB_CONFIG_DEFAULTS = {
 	statsScanMinutes: 5
 };
 /**
-* Resolve the effective hub config: saved sidecar overrides win over the
-* cordis composition entry (the web card owns runtime config), missing
-* booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
-* (saved first, then base) only when set. Numeric stats knobs are clamped to
-* their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
+* Fill a raw settings value into the effective hub config: schema defaults for
+* anything missing, and the numeric stats knobs clamped to sane ranges
+* (window ≥ 0, scan interval ≥ 1 minute).
+*
+* There is deliberately no "saved sidecar layer" parameter. Until dsh 0.1.7 the
+* hub kept its own runtime overrides in the sidecar and merged them here; the
+* settings namespace is now the only user layer (`updateConfig` writes through
+* `ctx.settings.mutate`), so a merge against a sidecar layer could never
+* observe anything but `{}` — see the git history of `resolveHubConfig`.
 */
-function resolveHubConfig(saved, base = {}) {
-	const dotModelColor = saved.dotModelColor !== void 0 ? saved.dotModelColor : base.dotModelColor;
-	const dotUserColor = saved.dotUserColor !== void 0 ? saved.dotUserColor : base.dotUserColor;
-	const githubToken = saved.githubToken !== void 0 ? saved.githubToken : base.githubToken;
-	const windowDays = clampNumber(saved.statsWindowDays ?? base.statsWindowDays, 0) ?? HUB_CONFIG_DEFAULTS.statsWindowDays;
-	const scanMinutes = clampNumber(saved.statsScanMinutes ?? base.statsScanMinutes, 1) ?? HUB_CONFIG_DEFAULTS.statsScanMinutes;
+function resolveHubConfig(base = {}) {
+	const windowDays = clampNumber(base.statsWindowDays, 0) ?? HUB_CONFIG_DEFAULTS.statsWindowDays;
+	const scanMinutes = clampNumber(base.statsScanMinutes, 1) ?? HUB_CONFIG_DEFAULTS.statsScanMinutes;
 	return {
-		enabled: saved.enabled ?? base.enabled ?? HUB_CONFIG_DEFAULTS.enabled,
-		announceToAgent: saved.announceToAgent ?? base.announceToAgent ?? HUB_CONFIG_DEFAULTS.announceToAgent,
-		showUseCount: saved.showUseCount ?? base.showUseCount ?? HUB_CONFIG_DEFAULTS.showUseCount,
-		showUseTime: saved.showUseTime ?? base.showUseTime ?? HUB_CONFIG_DEFAULTS.showUseTime,
-		showGroupSummary: saved.showGroupSummary ?? base.showGroupSummary ?? HUB_CONFIG_DEFAULTS.showGroupSummary,
+		enabled: base.enabled ?? HUB_CONFIG_DEFAULTS.enabled,
+		announceToAgent: base.announceToAgent ?? HUB_CONFIG_DEFAULTS.announceToAgent,
+		showUseCount: base.showUseCount ?? HUB_CONFIG_DEFAULTS.showUseCount,
+		showUseTime: base.showUseTime ?? HUB_CONFIG_DEFAULTS.showUseTime,
+		showGroupSummary: base.showGroupSummary ?? HUB_CONFIG_DEFAULTS.showGroupSummary,
 		statsWindowDays: windowDays,
 		statsScanMinutes: scanMinutes,
-		...dotModelColor !== void 0 ? { dotModelColor } : {},
-		...dotUserColor !== void 0 ? { dotUserColor } : {},
-		...githubToken !== void 0 ? { githubToken } : {}
+		...base.dotModelColor !== void 0 ? { dotModelColor: base.dotModelColor } : {},
+		...base.dotUserColor !== void 0 ? { dotUserColor: base.dotUserColor } : {},
+		...base.githubToken !== void 0 ? { githubToken: base.githubToken } : {}
 	};
 }
 /** Clamp a numeric override into a valid value; undefined/invalid stays undefined. */
@@ -1373,6 +1374,26 @@ function rootOfPath(path, home = dshHome()) {
 	}
 }
 //#endregion
+//#region src/concurrency.ts
+/**
+* 并发工具：有界并发的 map。原先 repo.ts 与 stats.ts 各有一份实现，
+* 这里统一为一份（采用 stats 版本的 limit 夹取，调用点 limit≥1 行为不变）。
+*/
+/** Run an async worker over items with a bounded concurrency, preserving index order. */
+async function mapConcurrent(items, limit, worker) {
+	const results = new Array(items.length);
+	let cursor = 0;
+	const runners = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
+		while (cursor < items.length) {
+			const index = cursor;
+			cursor += 1;
+			results[index] = await worker(items[index], index);
+		}
+	});
+	await Promise.all(runners);
+	return results;
+}
+//#endregion
 //#region src/skillfs/scan.ts
 /**
 * Scan one skills root for discovery files: directory bundles (SKILL.md)
@@ -1475,7 +1496,7 @@ async function readSkillInterface(directory) {
 	const hexColor = (value) => {
 		if (typeof value !== "string") return void 0;
 		const trimmed = value.trim();
-		return /^#[0-9a-fA-F]{6}$/.test(trimmed) ? trimmed : void 0;
+		return HEX_COLOR_RE.test(trimmed) ? trimmed : void 0;
 	};
 	const iconPath = (value) => {
 		if (typeof value !== "string" || value.trim() === "") return void 0;
@@ -1515,37 +1536,38 @@ async function findProjectRoot(cwd) {
 	return resolve(cwd);
 }
 /**
-* Scan one writable root for files the provider ignores, so the GUI can
-* show why a skill never appears — a
-* missing frontmatter must be visible, not silent). .disabled files belong
-* to the hub and are skipped.
+* Scan one writable root for files the provider ignores, so the GUI can show
+* why a skill never appears — a missing frontmatter, a name that disagrees
+* with the discovery path, and the like must be visible, not silent. Files the
+* hub itself disabled (`.disabled`) are skipped: they are a toggle state, not
+* a defect.
 */
 async function scanDiagnostics(root, home = dshHome()) {
-	const diagnostics = [];
-	for (const entry of await listSkillEntries(root, home)) {
+	return (await mapConcurrent(await listSkillEntries(root, home), 8, async (entry) => {
+		const found = [];
 		let text;
 		try {
 			text = await readFile(entry.path, "utf8");
 		} catch (error) {
-			if (error.code !== "ENOENT") diagnostics.push({
+			if (error.code !== "ENOENT") found.push({
 				path: entry.path,
 				root,
 				reason: "unreadable: " + errorText(error)
 			});
-			continue;
+			return found;
 		}
 		const parsed = parseFrontmatter(text);
 		if ("error" in parsed) {
 			const fixable = repairFrontmatterFileText(text) !== null;
-			diagnostics.push({
+			found.push({
 				path: entry.path,
 				root,
 				reason: parsed.error,
 				...fixable ? { fixable: true } : {}
 			});
-			continue;
+			return found;
 		}
-		if (repairFrontmatterFileText(text) !== null) diagnostics.push({
+		if (repairFrontmatterFileText(text) !== null) found.push({
 			path: entry.path,
 			root,
 			reason: "frontmatter contains unquoted colon/bracket (auto-repaired in memory; click Fix to persist)",
@@ -1553,18 +1575,18 @@ async function scanDiagnostics(root, home = dshHome()) {
 		});
 		const { value } = parsed;
 		const pathName = entry.kind === "directory" ? basename(entry.directory) : basename(entry.path, ".md");
-		if (value.name !== pathName) diagnostics.push({
+		if (value.name !== pathName) found.push({
 			path: entry.path,
 			root,
 			reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)`
 		});
-		if (value.description.length < 10) diagnostics.push({
+		if (value.description.length < 10) found.push({
 			path: entry.path,
 			root,
 			reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill`
 		});
-	}
-	return diagnostics;
+		return found;
+	})).flat();
 }
 //#endregion
 //#region src/skillfs.ts
@@ -1624,14 +1646,18 @@ async function enableSkill(disabledPath) {
 	return original;
 }
 /**
-* Move a skill (directory bundle or flat .md file) into the root's trash.
-* The skill stays recoverable: the source is renamed into
-* <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
-* SKILL.md path and moved as a whole directory.
+* Move one already-resolved skill (a bundle directory or a flat .md file) into
+* its root's trash as `<root>/.trash/<name>-<timestamp>`.
+*
+* The layout is the restore contract, not an implementation detail:
+* `restoreSkill` renames the entry back and only proves the parent is `.trash`,
+* and `clearTrash` deletes in place. Every producer of a trash entry must go
+* through here — skill delete, the hub-disabled whole-group delete, and repo
+* import's placeholder replacement all move skills for the same recovery flow.
+*
 * @returns the trashed path plus the original path that was moved.
 */
-async function trashSkill(sourcePath) {
-	const source = basename(sourcePath) === "SKILL.md" ? dirname(sourcePath) : sourcePath;
+async function moveIntoTrash(source) {
 	const trashDir = join(dirname(source), ".trash");
 	await mkdir(trashDir, { recursive: true });
 	const target = join(trashDir, basename(source) + "-" + Date.now());
@@ -1641,6 +1667,16 @@ async function trashSkill(sourcePath) {
 		source
 	};
 }
+/**
+* Move a skill (directory bundle or flat .md file) into the root's trash.
+* The skill stays recoverable: the source is renamed into
+* <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
+* SKILL.md path and moved as a whole directory.
+* @returns the trashed path plus the original path that was moved.
+*/
+async function trashSkill(sourcePath) {
+	return moveIntoTrash(basename(sourcePath) === "SKILL.md" ? dirname(sourcePath) : sourcePath);
+}
 /** Restore a trashed skill (directory or flat file) to its original location. */
 async function restoreSkill(entry, home = dshHome()) {
 	if (basename(dirname(entry.path)) !== ".trash") throw new TypeError("not a trashed skill path: " + entry.path);
@@ -1663,14 +1699,29 @@ function skillFileKind(path) {
 	if (basename(path) === "SKILL.md") return "directory";
 	if (path.endsWith(".md")) return "flat";
 }
-/** Repair one file on disk when its frontmatter is auto-fixable. Returns the new text. */
+/**
+* Repair one file on disk when its frontmatter is auto-fixable. Returns the new text.
+*
+* The write is atomic (sibling temp file + rename), matching the sidecar's
+* persist path: this rewrites a real skill file in place, and a crash midway
+* through a plain write would leave a truncated SKILL.md — exactly the failure
+* the store layer already guards against. The `.tmp` sibling is never picked
+* up by discovery (only `SKILL.md` and `*.md` are scanned).
+*/
 async function fixDiagnosticFile(path, home = dshHome()) {
 	if (rootOfPath(path, home) === void 0) throw new TypeError("not a hub writable skill path: " + path);
 	const repairedText = repairFrontmatterFileText(await readFile(path, "utf8"));
 	if (repairedText === null) throw new TypeError("diagnostic is not auto-fixable: " + path);
 	const parsed = parseFrontmatter(repairedText);
 	if ("error" in parsed) throw new TypeError("repaired frontmatter still invalid: " + parsed.error);
-	await writeFile(path, repairedText, "utf8");
+	const tmp = path + ".tmp";
+	await writeFile(tmp, repairedText, "utf8");
+	try {
+		await rename(tmp, path);
+	} catch (error) {
+		await rm(tmp, { force: true }).catch(() => {});
+		throw error;
+	}
 	return path;
 }
 //#endregion
@@ -1913,15 +1964,27 @@ function etagCacheSet(url, etag, json) {
 	});
 }
 /**
+* When the response shows an exhausted GitHub rate limit, the instant it
+* resets; otherwise undefined. Shared by the repo fetch layer and the plugin's
+* own update check so both agree on what counts as a rate-limit rejection
+* (403/429 + `x-ratelimit-remaining: 0` + a parseable `x-ratelimit-reset`)
+* instead of each re-deriving it from the headers.
+*/
+function rateLimitResetAt(response) {
+	if (response.status !== 403 && response.status !== 429) return void 0;
+	if (response.headers.get("x-ratelimit-remaining") !== "0") return void 0;
+	const reset = response.headers.get("x-ratelimit-reset");
+	if (reset === null) return void 0;
+	const at = /* @__PURE__ */ new Date(Number(reset) * 1e3);
+	return Number.isNaN(at.getTime()) ? void 0 : at;
+}
+/**
 * Build a RepoFetchError; when the response shows an exhausted rate limit,
 * report the reset time instead of a bare HTTP status.
 */
 function fetchError(context, response, fallbackStatus = 502) {
-	const remaining = response.headers.get("x-ratelimit-remaining");
-	const reset = response.headers.get("x-ratelimit-reset");
-	if (response.status === 403 || response.status === 429) {
-		if (remaining === "0" && reset !== null) return new RepoFetchError("github rate limit reached (anonymous quota exhausted); retry after " + (/* @__PURE__ */ new Date(Number(reset) * 1e3)).toLocaleTimeString() + " or set GITHUB_TOKEN", 403);
-	}
+	const resetAt = rateLimitResetAt(response);
+	if (resetAt !== void 0) return new RepoFetchError("github rate limit reached (anonymous quota exhausted); retry after " + resetAt.toLocaleTimeString() + " or set GITHUB_TOKEN", 403);
 	return new RepoFetchError(context + " (HTTP " + response.status + ")", response.status === 404 ? 404 : fallbackStatus);
 }
 /** 是否限流/中断类错误（调用方可直接透出，不再包装）。 */
@@ -1951,10 +2014,9 @@ async function fetchJson(url, fetchImpl, context, headers = apiHeaders()) {
 	}
 }
 /**
-* Load repo metadata and the recursive git tree at the given ref. The meta
-* request always resolves the default branch (used when ref is absent); the
-* tree is fetched at `ref ?? default_branch` so an explicit branch/tag scans
-* the exact same content a later download would fetch.
+* Load one JSON document from the GitHub API, reusing an ETag when the URL was
+* fetched before. `fetchImpl`/`context` exist so callers can stub the transport
+* and shape the error text; the payload is whatever the endpoint returned.
 */
 async function fetchJsonCached(url, fetchImpl, context) {
 	const cached = etagCache.get(url);
@@ -2081,26 +2143,6 @@ async function loadRepoTreeAt(repo, treeSha, fetchImpl = fetch) {
 	return Array.isArray(record.tree) ? record.tree : [];
 }
 //#endregion
-//#region src/concurrency.ts
-/**
-* 并发工具：有界并发的 map。原先 repo.ts 与 stats.ts 各有一份实现，
-* 这里统一为一份（采用 stats 版本的 limit 夹取，调用点 limit≥1 行为不变）。
-*/
-/** Run an async worker over items with a bounded concurrency, preserving index order. */
-async function mapConcurrent(items, limit, worker) {
-	const results = new Array(items.length);
-	let cursor = 0;
-	const runners = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
-		while (cursor < items.length) {
-			const index = cursor;
-			cursor += 1;
-			results[index] = await worker(items[index], index);
-		}
-	});
-	await Promise.all(runners);
-	return results;
-}
-//#endregion
 //#region src/repo/install.ts
 /**
 * 技能目录下载与落地：单文件下载（raw 优先、contents 兜底）、整目录
@@ -2352,9 +2394,14 @@ function isWritableSource(source) {
 }
 /** The resolved hub config a route sees (the shared resolver fills defaults). */
 function configOf(deps) {
-	return resolveHubConfig({}, deps.config?.() ?? {});
+	return resolveHubConfig(deps.config?.() ?? {});
 }
-/** The raw saved config layer a route reports (empty when the owner omits it). */
+/**
+* The raw saved config layer as persisted in the sidecar, reported for display
+* only. Since dsh 0.1.7 the settings namespace is the one user layer, so this
+* is legacy data: nothing writes it any more and the effective config above
+* never merges it.
+*/
 function savedOf(deps) {
 	return deps.saved?.() ?? {};
 }
@@ -2502,9 +2549,8 @@ async function checkLatestRelease(repo = UPDATE_REPO, fetchImpl = fetch) {
 	}
 	if (response.status === 404) return failure("no release published yet");
 	if (!response.ok) {
-		const remaining = response.headers.get("x-ratelimit-remaining");
-		const reset = response.headers.get("x-ratelimit-reset");
-		if ((response.status === 403 || response.status === 429) && remaining === "0" && reset !== null) return failure("github rate limit reached; retry after " + (/* @__PURE__ */ new Date(Number(reset) * 1e3)).toLocaleTimeString() + " or set GITHUB_TOKEN");
+		const resetAt = rateLimitResetAt(response);
+		if (resetAt !== void 0) return failure("github rate limit reached; retry after " + resetAt.toLocaleTimeString() + " or set GITHUB_TOKEN");
 		return failure("GitHub HTTP " + response.status);
 	}
 	let payload;
@@ -2692,7 +2738,8 @@ async function buildCatalog(deps, cwd) {
 		if (iface !== void 0) applyInterface(row, iface);
 		return row;
 	});
-	const diagnostics = [...await scanDiagnostics("user-dsh", home), ...await scanDiagnostics("user-agents", home)];
+	const [userDshDiagnostics, userAgentsDiagnostics] = await Promise.all([scanDiagnostics("user-dsh", home), scanDiagnostics("user-agents", home)]);
+	const diagnostics = [...userDshDiagnostics, ...userAgentsDiagnostics];
 	return {
 		ok: true,
 		pluginVersion: CURRENT_VERSION,
@@ -2881,15 +2928,7 @@ function catalogRoutes(deps) {
 							writeError(res, 409, "disabled skill path is outside the hub writable roots");
 							return;
 						}
-						const sourceToTrash = disabled.path.endsWith("SKILL.md.disabled") ? dirname(disabled.path) : disabled.path;
-						const trashDir = join(dirname(sourceToTrash), ".trash");
-						await mkdir(trashDir, { recursive: true });
-						const target = join(trashDir, basename(sourceToTrash) + "-" + Date.now());
-						await rename(sourceToTrash, target);
-						trashResult = {
-							path: target,
-							source: sourceToTrash
-						};
+						trashResult = await moveIntoTrash(disabled.path.endsWith("SKILL.md.disabled") ? dirname(disabled.path) : disabled.path);
 					} else {
 						writeError(res, resolved.status, resolved.error);
 						return;
@@ -3303,6 +3342,7 @@ function marketRoutes(deps) {
 			}
 			try {
 				const latestTag = await getLatestReleaseTag(source.repo);
+				lastMarketCheck.set(source.repo, now);
 				if (source.ref === void 0) {
 					results.push({
 						...base,
@@ -3313,7 +3353,6 @@ function marketRoutes(deps) {
 					continue;
 				}
 				const latest = await getLatestCommit(source.repo, source.ref);
-				lastMarketCheck.set(source.repo, now);
 				const commitMoved = source.commitSha !== void 0 && latest.commitSha !== source.commitSha;
 				const newRelease = latestTag !== void 0 && latestTag !== source.ref;
 				results.push({
@@ -3358,9 +3397,11 @@ function marketRoutes(deps) {
 					return;
 				}
 				const ref = parsed.ref;
+				const slug = repoSlug(parsed);
 				writeJson(res, 200, {
 					ok: true,
-					repos: await deps.store.addMarketSource(repoSlug(parsed), ref)
+					repo: slug,
+					repos: await deps.store.addMarketSource(slug, ref)
 				});
 			}
 		},
@@ -3554,10 +3595,7 @@ async function clearDisabledPlaceholder(deps, targetRoot, name) {
 	const sourceToTrash = record.path.endsWith("SKILL.md.disabled") ? dirname(record.path) : record.path;
 	if (sourceToTrash !== dir) return false;
 	if (await pathExists(join(dir, "SKILL.md"))) return false;
-	const trashDir = join(targetRoot, ".trash");
-	await mkdir(trashDir, { recursive: true });
-	const target = join(trashDir, name + "-" + Date.now());
-	await rename(sourceToTrash, target);
+	const { path: target } = await moveIntoTrash(sourceToTrash);
 	await deps.store.addTrash({
 		name,
 		path: target,
@@ -4776,7 +4814,7 @@ function apply(ctx, config) {
 		}
 		return out;
 	};
-	const current = () => resolveHubConfig({}, readConfig());
+	const current = () => resolveHubConfig(readConfig());
 	/** The Settings service, when this deployment mounts it. Absent ⇒ no user layer to read or write. */
 	const settingsOf = () => ctx.get("settings");
 	const store = new SkillHubStore();

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

@@ -2,7 +2,7 @@
  * Browser-side API client for the /api/skill-hub route family. The only
  * data access path the panel uses — plain fetch, same origin.
  */
-import { type CatalogResponse, type ConfigResponse, type CreateRequest, type CreateResponse, type DiagnosticFixResponse, type GroupsResponse, type MarketCheckResponse, type MarketSourcesResponse, type MarketSourceVersionsResponse, type MarketStatsResponse, type MarketSyncResponse, type RepoDiscoverResponse, type RepoImportCancelResponse, type RepoImportProgressResponse, type RepoImportResponse, type SkillDetail, type SkillDeleteResponse, type SkillTag, type SourceCheckResponse, type SourceDeleteResponse, type SourceRestoreResponse, type SourceTrashClearResponse, type SourcesResponse, type SourceSyncResponse, type StatsResponse, type TagSaveRequest, type ToggleBatchResponse, type UpdateCheckResponse } from '../protocol.ts';
+import { type CatalogResponse, type ConfigResponse, type CreateRequest, type CreateResponse, type DiagnosticFixResponse, type GroupsResponse, type MarketCheckResponse, type MarketSourceAddResponse, type MarketSourcesResponse, type MarketSourceVersionsResponse, type MarketStatsResponse, type MarketSyncResponse, type RepoDiscoverResponse, type RepoImportCancelResponse, type RepoImportProgressResponse, type RepoImportResponse, type SkillDetail, type SkillDeleteResponse, type SkillTag, type SourceCheckResponse, type SourceDeleteResponse, type SourceRestoreResponse, type SourceTrashClearResponse, type SourcesResponse, type SourceSyncResponse, type StatsResponse, type TagSaveRequest, type ToggleBatchResponse, type UpdateCheckResponse } from '../protocol.ts';
 /** Error carrying the route's JSON error message. */
 export declare class SkillHubApiError extends Error {
     constructor(message: string);
@@ -31,8 +31,8 @@ export declare class SkillHubApi {
     toggleBatch(names: string[], enabled: boolean): Promise<ToggleBatchResponse>;
     /** The user's added market sources. */
     market(): Promise<MarketSourcesResponse>;
-    /** Add a market source repo; resolves with the fresh list. */
-    addMarketSource(repo: string): Promise<MarketSourcesResponse>;
+    /** Add a market source repo; resolves with the fresh list plus the resolved slug. */
+    addMarketSource(repo: string): Promise<MarketSourceAddResponse>;
     /** Remove a market source repo; resolves with the fresh list. */
     removeMarketSource(repo: string): Promise<MarketSourcesResponse>;
     /** Stars + downloads per market source (hourly server-side cache; refresh=1 refetches stale entries). */

package/lib/types/protocol/config.d.ts

@@ -83,13 +83,17 @@ export declare const HUB_CONFIG_DEFAULTS: {
     readonly statsScanMinutes: 5;
 };
 /**
- * Resolve the effective hub config: saved sidecar overrides win over the
- * cordis composition entry (the web card owns runtime config), missing
- * booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
- * (saved first, then base) only when set. Numeric stats knobs are clamped to
- * their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
+ * Fill a raw settings value into the effective hub config: schema defaults for
+ * anything missing, and the numeric stats knobs clamped to sane ranges
+ * (window ≥ 0, scan interval ≥ 1 minute).
+ *
+ * There is deliberately no "saved sidecar layer" parameter. Until dsh 0.1.7 the
+ * hub kept its own runtime overrides in the sidecar and merged them here; the
+ * settings namespace is now the only user layer (`updateConfig` writes through
+ * `ctx.settings.mutate`), so a merge against a sidecar layer could never
+ * observe anything but `{}` — see the git history of `resolveHubConfig`.
  */
-export declare function resolveHubConfig(saved: Partial<HubConfig>, base?: Partial<HubConfig>): HubConfig;
+export declare function resolveHubConfig(base?: Partial<HubConfig>): HubConfig;
 /**
  * Drop the GitHub token from a config-shaped object. Returns a copy, so the
  * caller's own config layer keeps the token. Shared by the config route's GET
@@ -112,7 +116,13 @@ export interface ConfigResponse {
     /** True when a GitHub token is in effect (saved override or the base/env layer). */
     githubTokenSet: boolean;
 }
-/** POST /api/skill-hub/config — a partial patch; omitted fields keep their values. */
+/**
+ * POST /api/skill-hub/config — a partial patch; omitted fields keep their values.
+ *
+ * Only the fields the handler actually parses belong here: the stats knobs are
+ * owned by the settings namespace (`statsWindowDays` / `statsScanMinutes` are
+ * still part of {@link HubSettingsValue}), not by this route.
+ */
 export interface ConfigRequest {
     /** Set the field; null clears the saved override so it re-inherits the default. */
     enabled?: boolean | null;
@@ -128,10 +138,6 @@ export interface ConfigRequest {
     dotModelColor?: string | null;
     /** Set the dot color; null clears the saved override so it re-inherits the default. */
     dotUserColor?: string | null;
-    /** 统计滚动窗口天数（0 = 全部历史）；null 清除覆盖回默认。 */
-    statsWindowDays?: number | null;
-    /** 自动统计扫描间隔（分钟）；null 清除覆盖回默认。 */
-    statsScanMinutes?: number | null;
     /** Set the GitHub token; null/empty clears it back to anonymous. */
     githubToken?: string | null;
 }

package/lib/types/protocol/market.d.ts

@@ -23,6 +23,17 @@ export interface MarketSourceResponse {
     ok: true;
     repos: MarketSourceRecord[];
 }
+/**
+ * POST /api/skill-hub/market/source — same list, plus the slug the host
+ * resolved from the input. Clients must scan *this* slug rather than assume
+ * the acted-on source sits at some position in `repos`: re-adding a repo the
+ * user already tracks only updates its `ref` in place and never reorders the
+ * list.
+ */
+export interface MarketSourceAddResponse extends MarketSourceResponse {
+    /** Normalized `owner/repo` the host recorded for the submitted input. */
+    repo: string;
+}
 /** POST /api/skill-hub/market/source/ref — pin a market source to an explicit ref. */
 export interface MarketSourceRefRequest {
     repo: string;

package/lib/types/protocol.d.ts

@@ -12,7 +12,7 @@ export type { WritableRoot, HubInvocation, CatalogSkill, DisabledSkill, Diagnost
 export type { SkillStat, StatsResponse, SkillStatsCheckpoint } from './protocol/stats.ts';
 export type { ErrorResponse, HubConfig, HubSettingsValue, RedactedHubConfig, ConfigResponse, ConfigRequest } from './protocol/config.ts';
 export { HUB_CONFIG_DEFAULTS, HUB_ENTRY_ID, HEX_COLOR_RE, GITHUB_TOKEN_RE, resolveHubConfig, redactGithubToken } from './protocol/config.ts';
-export type { MarketSourceRecord, MarketSourcesResponse, MarketSourceRequest, MarketSourceResponse, MarketSourceRefRequest, MarketSourceVersionsResponse, MarketStatsSnapshot, MarketStatsResponse, MarketCheckResponse, MarketSyncResponse, } from './protocol/market.ts';
+export type { MarketSourceRecord, MarketSourcesResponse, MarketSourceRequest, MarketSourceAddResponse, MarketSourceResponse, MarketSourceRefRequest, MarketSourceVersionsResponse, MarketStatsSnapshot, MarketStatsResponse, MarketCheckResponse, MarketSyncResponse, } from './protocol/market.ts';
 export type { RepoSkillEntry, RepoRoot, RepoDiscoverResponse, RepoImportRequest, RepoImportResponse, RepoImportProgressResponse, RepoImportCancelRequest, RepoImportCancelResponse, UpdateCheckResponse, } from './protocol/repo.ts';
 export type { SkillTag, CollectionGroup, GroupsResponse, TagSaveRequest, TagSaveResponse, TagDeleteRequest, TagDeleteResponse, TagMembersRequest, TagMembersResponse, TagReorderRequest, TagReorderResponse, CollectionReorderRequest, CollectionReorderResponse, SourceGroupReorderRequest, SourceGroupReorderResponse, } from './protocol/groups.ts';
 export type { SourceRecord, TrashEntry, SourcesResponse, SourceCheckRequest, SourceCheckResult, SourceCheckResponse, SourceSyncRequest, SourceSyncResponse, SourceDeleteRequest, SourceDeleteResponse, SourceRestoreRequest, SourceRestoreResponse, SourceTrashClearResponse, } from './protocol/sources.ts';

package/lib/types/repo/github-client.d.ts

@@ -30,6 +30,14 @@ export declare function githubAuthHeaders(): Record<string, string>;
 export declare const NO_COMPRESSION: Record<string, string>;
 /** JSON API 默认请求头（含鉴权）。 */
 export declare function apiHeaders(): Record<string, string>;
+/**
+ * When the response shows an exhausted GitHub rate limit, the instant it
+ * resets; otherwise undefined. Shared by the repo fetch layer and the plugin's
+ * own update check so both agree on what counts as a rate-limit rejection
+ * (403/429 + `x-ratelimit-remaining: 0` + a parseable `x-ratelimit-reset`)
+ * instead of each re-deriving it from the headers.
+ */
+export declare function rateLimitResetAt(response: Response): Date | undefined;
 /**
  * Build a RepoFetchError; when the response shows an exhausted rate limit,
  * report the reset time instead of a bare HTTP status.
@@ -46,10 +54,9 @@ export declare function fetchJson(url: string, fetchImpl: typeof fetch, context:
     response: Response;
 }>;
 /**
- * Load repo metadata and the recursive git tree at the given ref. The meta
- * request always resolves the default branch (used when ref is absent); the
- * tree is fetched at `ref ?? default_branch` so an explicit branch/tag scans
- * the exact same content a later download would fetch.
+ * Load one JSON document from the GitHub API, reusing an ETag when the URL was
+ * fetched before. `fetchImpl`/`context` exist so callers can stub the transport
+ * and shape the error text; the payload is whatever the endpoint returned.
  */
 export declare function fetchJsonCached(url: string, fetchImpl: typeof fetch, context: string): Promise<{
     json: unknown;

package/lib/types/repo.d.ts

@@ -12,7 +12,7 @@
  * The implementation now lives under `./repo/` (types, discovery, api,
  * install) and this module is a barrel that re-exports it.
  */
-export { NO_COMPRESSION, RepoFetchError, apiHeaders, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, setGithubToken } from './repo/github-client.ts';
+export { NO_COMPRESSION, RepoFetchError, apiHeaders, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, rateLimitResetAt, setGithubToken } from './repo/github-client.ts';
 export type { RepoRef, RepoTreeItem, RepoFile } from './repo/types.ts';
 export { REPO_ROOT, isRepoRoot, repoSlug, normalizeRepoInput, collectRepoSkillFiles, originForRoot, discoverRepoEntries, skillManifest, skillDirOf, skillFileAt, skillPathIn, relativeToSkillDir, diffRemoteSkills, repoSkillEntry, } from './repo/discovery.ts';
 export { loadRepoTree, getLatestReleaseTag, getRepoStats, listRepoReleases, listRepoBranches, getLatestCommit, loadRepoTreeAt, } from './repo/api.ts';

package/lib/types/routes/deps.d.ts

@@ -37,7 +37,12 @@ export interface SkillHubRouteDeps {
 }
 /** The resolved hub config a route sees (the shared resolver fills defaults). */
 export declare function configOf(deps: SkillHubRouteDeps): HubConfig;
-/** The raw saved config layer a route reports (empty when the owner omits it). */
+/**
+ * The raw saved config layer as persisted in the sidecar, reported for display
+ * only. Since dsh 0.1.7 the settings namespace is the one user layer, so this
+ * is legacy data: nothing writes it any more and the effective config above
+ * never merges it.
+ */
 export declare function savedOf(deps: SkillHubRouteDeps): Partial<HubConfig>;
 /** Refuse business routes while the master switch is off (the config route stays up). */
 export declare function disabledGate(deps: SkillHubRouteDeps, res: ServerResponse): boolean;

package/lib/types/skillfs/scan.d.ts

@@ -1,4 +1,4 @@
-import type { DiagnosticEntry, WritableRoot } from '../protocol.ts';
+import { type DiagnosticEntry, type WritableRoot } from '../protocol.ts';
 /** One discoverable skill file in a scanned root. */
 export interface SkillEntry {
     /** Absolute path of the discovery file (SKILL.md or the flat .md). */
@@ -39,9 +39,10 @@ export declare function readSkillInterface(directory: string): Promise<SkillInte
  */
 export declare function findProjectRoot(cwd: string): Promise<string>;
 /**
- * Scan one writable root for files the provider ignores, so the GUI can
- * show why a skill never appears — a
- * missing frontmatter must be visible, not silent). .disabled files belong
- * to the hub and are skipped.
+ * Scan one writable root for files the provider ignores, so the GUI can show
+ * why a skill never appears — a missing frontmatter, a name that disagrees
+ * with the discovery path, and the like must be visible, not silent. Files the
+ * hub itself disabled (`.disabled`) are skipped: they are a toggle state, not
+ * a defect.
  */
 export declare function scanDiagnostics(root: WritableRoot, home?: string): Promise<DiagnosticEntry[]>;

package/lib/types/skillfs.d.ts

@@ -29,6 +29,22 @@ export declare function createSkill(root: WritableRoot, name: string, descriptio
 export declare function disableSkill(path: string): Promise<string>;
 /** Re-enable a previously disabled file (reverse of disableSkill). */
 export declare function enableSkill(disabledPath: string): Promise<string>;
+/**
+ * Move one already-resolved skill (a bundle directory or a flat .md file) into
+ * its root's trash as `<root>/.trash/<name>-<timestamp>`.
+ *
+ * The layout is the restore contract, not an implementation detail:
+ * `restoreSkill` renames the entry back and only proves the parent is `.trash`,
+ * and `clearTrash` deletes in place. Every producer of a trash entry must go
+ * through here — skill delete, the hub-disabled whole-group delete, and repo
+ * import's placeholder replacement all move skills for the same recovery flow.
+ *
+ * @returns the trashed path plus the original path that was moved.
+ */
+export declare function moveIntoTrash(source: string): Promise<{
+    path: string;
+    source: string;
+}>;
 /**
  * Move a skill (directory bundle or flat .md file) into the root's trash.
  * The skill stays recoverable: the source is renamed into
@@ -44,5 +60,13 @@ export declare function trashSkill(sourcePath: string): Promise<{
 export declare function restoreSkill(entry: TrashEntry, home?: string): Promise<string>;
 /** Permanently delete one trashed skill (directory or flat file). */
 export declare function clearTrash(entry: TrashEntry, home?: string): Promise<string>;
-/** Repair one file on disk when its frontmatter is auto-fixable. Returns the new text. */
+/**
+ * Repair one file on disk when its frontmatter is auto-fixable. Returns the new text.
+ *
+ * The write is atomic (sibling temp file + rename), matching the sidecar's
+ * persist path: this rewrites a real skill file in place, and a crash midway
+ * through a plain write would leave a truncated SKILL.md — exactly the failure
+ * the store layer already guards against. The `.tmp` sibling is never picked
+ * up by discovery (only `SKILL.md` and `*.md` are scanned).
+ */
 export declare function fixDiagnosticFile(path: string, home?: string): Promise<string>;