dsh-skill-hub 0.2.6 → 0.3.1

package/lib/index.js

@@ -1,11 +1,11 @@
 import { createRequire } from "node:module";
-import { settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "schemastery";
 import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { dump, load } from "js-yaml";
 import { isSkillName } from "@deepseek-ai/dsh-skill";
+import { randomUUID } from "node:crypto";
 //#region src/protocol.ts
 /**
 * Shared API contract for dsh-skill-hub: the route paths and payload shapes
@@ -31,11 +31,16 @@ const SKILL_HUB_API = {
 	marketSync: "/api/skill-hub/market/source/sync",
 	repo: "/api/skill-hub/repo",
 	repoImport: "/api/skill-hub/repo/import",
+	repoImportProgress: "/api/skill-hub/repo/import/progress",
+	repoImportCancel: "/api/skill-hub/repo/import/cancel",
 	update: "/api/skill-hub/update",
 	groups: "/api/skill-hub/groups",
 	tag: "/api/skill-hub/tag",
 	tagDelete: "/api/skill-hub/tag/delete",
 	tagMembers: "/api/skill-hub/tag/members",
+	tagReorder: "/api/skill-hub/tag/reorder",
+	collectionReorder: "/api/skill-hub/collections/reorder",
+	sourceGroupReorder: "/api/skill-hub/source-groups/reorder",
 	sources: "/api/skill-hub/sources",
 	sourceCheck: "/api/skill-hub/sources/check",
 	sourceSync: "/api/skill-hub/sources/sync",
@@ -172,7 +177,9 @@ function migrateStore(parsed) {
 		...sources !== void 0 ? { sources } : {},
 		...marketSources !== void 0 ? { marketSources } : {},
 		...trash !== void 0 ? { trash } : {},
-		...record.skillStats !== void 0 ? { skillStats: record.skillStats } : {}
+		...record.skillStats !== void 0 ? { skillStats: record.skillStats } : {},
+		...Array.isArray(record.collectionOrder) ? { collectionOrder: record.collectionOrder } : {},
+		...Array.isArray(record.sourceGroupOrder) ? { sourceGroupOrder: record.sourceGroupOrder } : {}
 	};
 }
 /** Sidecar state owner. */
@@ -185,6 +192,8 @@ var SkillHubStore = class {
 	marketSources = [];
 	trashByName = /* @__PURE__ */ new Map();
 	skillStats = void 0;
+	collectionOrder = [];
+	sourceGroupOrder = [];
 	loaded = false;
 	/** Serializes persist runs: concurrent mutators must not let an earlier
 	*  snapshot overwrite a later one (rename is atomic, ordering is not). */
@@ -226,10 +235,11 @@ var SkillHubStore = class {
 					const source = entry;
 					if (source !== null && typeof source === "object" && typeof source.repo === "string" && source.repo !== "" && Array.isArray(source.skills)) {
 						const manifest = source.manifest;
+						const rawRoot = typeof source.root === "string" && source.root !== "" && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(source.root) ? source.root : "skills";
 						this.sourcesByRepo.set(source.repo, {
 							repo: source.repo,
 							...typeof source.ref === "string" && source.ref !== "" ? { ref: source.ref } : {},
-							root: source.root === "design-templates" ? "design-templates" : "skills",
+							root: rawRoot,
 							commitSha: typeof source.commitSha === "string" ? source.commitSha : "",
 							skills: source.skills.filter((n) => typeof n === "string"),
 							...manifest !== null && typeof manifest === "object" && !Array.isArray(manifest) ? { manifest: Object.fromEntries(Object.entries(manifest).filter(([, size]) => typeof size === "number")) } : {}
@@ -254,7 +264,7 @@ var SkillHubStore = class {
 							path: item.path,
 							movedAt: typeof item.movedAt === "number" ? item.movedAt : 0,
 							...typeof item.sourcePath === "string" && item.sourcePath !== "" ? { sourcePath: item.sourcePath } : {},
-							...origin !== null && typeof origin === "object" && typeof origin.repo === "string" && origin.repo !== "" && (origin.root === "skills" || origin.root === "design-templates") ? { origin: {
+							...origin !== null && typeof origin === "object" && typeof origin.repo === "string" && origin.repo !== "" && typeof origin.root === "string" && origin.root !== "" && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(origin.root) ? { origin: {
 								repo: origin.repo,
 								root: origin.root,
 								...typeof origin.ref === "string" && origin.ref !== "" ? { ref: origin.ref } : {},
@@ -286,6 +296,10 @@ var SkillHubStore = class {
 						lastFullReconcile: savedStats.lastFullReconcile
 					};
 				}
+				const rawColOrder = migrated.collectionOrder;
+				if (Array.isArray(rawColOrder)) this.collectionOrder = rawColOrder.filter((n) => typeof n === "string" && n !== "");
+				const rawSrcOrder = migrated.sourceGroupOrder;
+				if (Array.isArray(rawSrcOrder)) this.sourceGroupOrder = rawSrcOrder.filter((n) => typeof n === "string" && n !== "");
 			}
 		} catch (error) {
 			if (error.code !== "ENOENT") console.warn("[dsh-skill-hub] sidecar state unreadable, starting empty:", error instanceof Error ? error.message : error);
@@ -432,6 +446,50 @@ var SkillHubStore = class {
 		}
 		if (changed) await this.persist();
 	}
+	/** Reorder tag groups by orderedIds (drag-and-drop). */
+	async reorderTags(orderedIds) {
+		await this.ensureLoaded();
+		const currentIds = [...this.tagsById.keys()];
+		if (orderedIds.length !== currentIds.length) throw new StoreError("validation", "orderedIds length mismatch");
+		const seen = /* @__PURE__ */ new Set();
+		for (const id of orderedIds) {
+			if (typeof id !== "string" || id === "") throw new StoreError("validation", "invalid tag id");
+			if (seen.has(id)) throw new StoreError("validation", "duplicate tag id: " + id);
+			if (!this.tagsById.has(id)) throw new StoreError("not-found", "tag not found: " + id);
+			seen.add(id);
+		}
+		const newMap = /* @__PURE__ */ new Map();
+		for (const id of orderedIds) newMap.set(id, this.tagsById.get(id));
+		this.tagsById = newMap;
+		await this.persist();
+		return [...this.tagsById.values()];
+	}
+	/** Collection order for 来源分组拖拽 */
+	async getCollectionOrder() {
+		await this.ensureLoaded();
+		return [...this.collectionOrder];
+	}
+	/** Reorder collections by orderedNames (drag-and-drop). */
+	async reorderCollections(orderedNames) {
+		await this.ensureLoaded();
+		const uniq = [...new Set(orderedNames.filter((n) => typeof n === "string" && n !== ""))];
+		this.collectionOrder = uniq;
+		await this.persist();
+		return [...this.collectionOrder];
+	}
+	/** Source top-level group order for 来源分组（project / col:xxx / personal） */
+	async getSourceGroupOrder() {
+		await this.ensureLoaded();
+		return [...this.sourceGroupOrder];
+	}
+	/** Reorder source top-level groups by orderedKeys */
+	async reorderSourceGroups(orderedKeys) {
+		await this.ensureLoaded();
+		const uniq = [...new Set(orderedKeys.filter((k) => typeof k === "string" && k !== ""))];
+		this.sourceGroupOrder = uniq;
+		await this.persist();
+		return [...this.sourceGroupOrder];
+	}
 	/** All source records, sorted by repo. */
 	async listSources() {
 		await this.ensureLoaded();
@@ -659,7 +717,9 @@ var SkillHubStore = class {
 				...this.sourcesByRepo.size > 0 ? { sources: [...this.sourcesByRepo.values()] } : {},
 				...this.marketSources.length > 0 ? { marketSources: [...this.marketSources] } : {},
 				...this.trashByName.size > 0 ? { trash: [...this.trashByName.values()] } : {},
-				...this.skillStats !== void 0 ? { skillStats: this.skillStats } : {}
+				...this.skillStats !== void 0 ? { skillStats: this.skillStats } : {},
+				...this.collectionOrder.length > 0 ? { collectionOrder: [...this.collectionOrder] } : {},
+				...this.sourceGroupOrder.length > 0 ? { sourceGroupOrder: [...this.sourceGroupOrder] } : {}
 			};
 			const tmp = this.file + ".tmp";
 			await mkdir(dirname(this.file), { recursive: true });
@@ -698,10 +758,22 @@ function rootPath(root, home = dshHome()) {
 }
 /** Root of an absolute skill file path, or undefined when not user-owned. */
 function rootOfPath(path, home = dshHome()) {
-	const normalized = join(path);
+	const normalized = resolve(path);
 	for (const root of WRITABLE_ROOTS) {
-		const base = rootPath(root, home);
-		if (normalized.startsWith(base + "/") || normalized === base) return root;
+		const base = resolve(rootPath(root, home));
+		if (process.platform === "win32") {
+			const n = normalized.toLowerCase();
+			const b = base.toLowerCase();
+			if (n === b) return root;
+			if (n.startsWith(b + "/") || n.startsWith(b + "\\") || n.startsWith(b + sep)) return root;
+			const rel = relative(base, normalized);
+			if (rel !== "" && !rel.startsWith("../") && !rel.startsWith("..\\") && !rel.startsWith(".." + sep) && rel !== ".." && !isAbsolute(rel)) return root;
+		} else {
+			if (normalized === base) return root;
+			if (normalized.startsWith(base + sep) || normalized.startsWith(base + "/") || normalized.startsWith(base + "\\")) return root;
+			const rel = relative(base, normalized);
+			if (rel !== "" && !rel.startsWith(".." + sep) && !rel.startsWith("../") && !rel.startsWith("..\\") && rel !== ".." && !isAbsolute(rel)) return root;
+		}
 	}
 }
 /**
@@ -1102,10 +1174,12 @@ var SkillHubProvider = class {
 * GitHub repository skill discovery/import helpers.
 *
 * Kept dependency-free and mostly pure so the root/origin rules are easy to
-* test. The two supported roots mirror the repositories we care about:
-* `skills/**` (standard skill bundles) and `design-templates/**` (template
-* skill bundles in nexu-io/open-design).
+* test. Roots are auto-derived: any top-level directory that contains a
+* `**\/SKILL.md` (e.g. `skills/**`, `design-templates/**`, `templates/**`,
+* `workflows/**`) is treated as a skill root. No hard-coded allowlist.
 */
+/** Top-level directory pattern for a skill root: visible, non-dot, safe chars. First char must be alphanum. */
+const ROOT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 /** Fetch failure carrying a useful HTTP status for the route layer. */
 var RepoFetchError = class extends Error {
 	status;
@@ -1234,16 +1308,19 @@ function collectRepoSkillFiles(tree, dir) {
 function originForRoot(repo, rootsPresent, root) {
 	return rootsPresent.size > 1 ? `${repo}/${root}` : repo;
 }
-/** Discover importable skills from a repo tree. Invalid names are ignored. */
+/** Discover importable skills from a repo tree. Invalid names are ignored. Roots are auto-derived from the top-level directory of each SKILL.md. */
 function discoverRepoEntries(tree, repo, existingNames = /* @__PURE__ */ new Set()) {
 	const candidates = [];
 	const rootsPresent = /* @__PURE__ */ new Set();
 	for (const item of tree) {
 		if (item.type !== "blob") continue;
-		const match = /^(skills|design-templates)\/(.+)\/SKILL\.md$/.exec(item.path);
-		if (match === null) continue;
-		const root = match[1];
+		const slash = item.path.indexOf("/");
+		if (slash === -1) continue;
+		if (!item.path.endsWith("/SKILL.md")) continue;
+		const root = item.path.slice(0, slash);
+		if (!ROOT_RE.test(root)) continue;
 		const dir = item.path.slice(0, -9);
+		if (dir === root || dir.length <= root.length + 1) continue;
 		const name = dir.slice(dir.lastIndexOf("/") + 1);
 		if (!isSkillName(name)) continue;
 		rootsPresent.add(root);
@@ -1282,30 +1359,44 @@ async function mapConcurrent(items, limit, worker) {
 	await Promise.all(runners);
 	return results;
 }
+/** Whether an error is an abort (AbortError / signal). */
+function isAbortError(error) {
+	return error instanceof Error && (error.name === "AbortError" || error.message.includes("aborted") || error.message.includes("Abort"));
+}
 /**
 * Download one GitHub file as a buffer. Tries raw.githubusercontent.com
 * first (no API quota); on any failure falls back to the api.github.com
 * contents endpoint with the raw media type (rate-limited, but reachable
 * from networks that block the raw host).
 */
-async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch) {
+async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch, signal) {
+	if (signal?.aborted) throw new DOMException("aborted", "AbortError");
 	const encodedPath = path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 	const rawUrl = `https://raw.githubusercontent.com/${repo}/${encodeURIComponent(ref)}/${encodedPath}`;
 	let firstError = null;
 	let response = null;
 	try {
-		response = await fetchImpl(rawUrl, { headers: githubAuthHeaders() });
+		response = await fetchImpl(rawUrl, {
+			headers: githubAuthHeaders(),
+			...signal !== void 0 ? { signal } : {}
+		});
 	} catch (error) {
+		if (isAbortError(error)) throw error;
 		firstError = error instanceof Error ? error.message : String(error);
 	}
 	if (response === null || !response.ok) {
+		if (signal?.aborted) throw new DOMException("aborted", "AbortError");
 		const apiUrl = `https://api.github.com/repos/${repo}/contents/${encodedPath}`;
 		try {
-			response = await fetchImpl(apiUrl, { headers: {
-				accept: "application/vnd.github.raw",
-				...githubAuthHeaders()
-			} });
+			response = await fetchImpl(apiUrl, {
+				headers: {
+					accept: "application/vnd.github.raw",
+					...githubAuthHeaders()
+				},
+				...signal !== void 0 ? { signal } : {}
+			});
 		} catch (error) {
+			if (isAbortError(error)) throw error;
 			throw new RepoFetchError("download failed: " + (firstError ?? (error instanceof Error ? error.message : String(error))));
 		}
 	}
@@ -1313,6 +1404,7 @@ async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch) {
 	try {
 		return Buffer.from(await response.arrayBuffer());
 	} catch (error) {
+		if (isAbortError(error)) throw error;
 		throw new RepoFetchError("download read failed: " + (error instanceof Error ? error.message : String(error)));
 	}
 }
@@ -1321,19 +1413,24 @@ async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch) {
 * then atomically rename it into place. The target root is created when missing.
 * Callers pass a target root and a skill entry plus its collected files.
 */
-async function downloadRepoSkill(repo, ref, entry, files, targetRoot, fetchImpl = fetch) {
+async function downloadRepoSkill(repo, ref, entry, files, targetRoot, fetchImpl = fetch, signal, onProgress) {
+	if (signal?.aborted) throw new DOMException("aborted", "AbortError");
 	const targetDir = join(targetRoot, entry.name);
 	await mkdir(targetRoot, { recursive: true });
 	const tempDir = await mkdtemp(join(targetRoot, "." + entry.name + ".import-"));
+	let renamed = false;
 	try {
 		await mapConcurrent(files, 6, async (file) => {
+			if (signal?.aborted) throw new DOMException("aborted", "AbortError");
 			const relative = file.path.slice(entry.dir.length + 1);
 			if (relative === "" || relative.includes("..")) throw new RepoFetchError("unsafe repo path: " + file.path);
 			const target = join(tempDir, relative);
-			const buffer = await downloadGitHubFile(repo, ref, file.path, fetchImpl);
+			const buffer = await downloadGitHubFile(repo, ref, file.path, fetchImpl, signal);
 			await mkdir(dirname(target), { recursive: true });
 			await writeFile(target, buffer);
+			onProgress?.(buffer.length, relative);
 		});
+		if (signal?.aborted) throw new DOMException("aborted", "AbortError");
 		let text;
 		try {
 			text = await readFile(join(tempDir, "SKILL.md"), "utf8");
@@ -1344,25 +1441,62 @@ async function downloadRepoSkill(repo, ref, entry, files, targetRoot, fetchImpl
 		if ("error" in parsed) throw new RepoFetchError("downloaded skill rejected: " + parsed.error, 422);
 		if (parsed.value.name !== entry.name) throw new RepoFetchError("downloaded skill declares name \"" + parsed.value.name + "\", expected \"" + entry.name + "\"", 422);
 		await rename(tempDir, targetDir);
+		renamed = true;
 		return {
 			targetDir,
 			skillPath: join(targetDir, "SKILL.md")
 		};
 	} catch (error) {
-		await rm(tempDir, {
-			recursive: true,
-			force: true
-		}).catch(async () => {
-			await new Promise((resolve) => setTimeout(resolve, 60));
+		throw error;
+	} finally {
+		if (!renamed) try {
 			await rm(tempDir, {
 				recursive: true,
 				force: true
-			}).catch(() => {});
-		});
-		throw error;
+			});
+		} catch (firstError) {
+			await new Promise((resolve) => setTimeout(resolve, 60));
+			try {
+				await rm(tempDir, {
+					recursive: true,
+					force: true
+				});
+			} catch (secondError) {
+				console.warn(`[skill-hub] cleanup tempDir failed ${tempDir}:`, secondError instanceof Error ? secondError.message : String(secondError), "first:", firstError instanceof Error ? firstError.message : String(firstError));
+			}
+		}
 	}
 }
 /**
+* 启动时扫描并清理残留的 `.*.import-*` 临时目录（Issue #3 第4点）。
+* 越积越多的点前缀目录不会显示为 skill，但会占空间，尽早回收。
+*/
+async function cleanupLeftoverImportDirs(targetRoot) {
+	const { readdir, rm: rm2 } = await import("node:fs/promises");
+	let names;
+	try {
+		names = await readdir(targetRoot);
+	} catch {
+		return 0;
+	}
+	let cleaned = 0;
+	for (const name of names) {
+		if (!/^\..*\.import-/.test(name)) continue;
+		const full = join(targetRoot, name);
+		try {
+			await rm2(full, {
+				recursive: true,
+				force: true
+			});
+			cleaned += 1;
+		} catch (error) {
+			console.warn(`[skill-hub] startup cleanup failed ${full}:`, error instanceof Error ? error.message : String(error));
+		}
+	}
+	if (cleaned > 0) console.warn(`[skill-hub] startup cleaned ${cleaned} leftover import temp dir(s) in ${targetRoot}`);
+	return cleaned;
+}
+/**
 * The latest non-prerelease release tag of a repo, or undefined when the
 * repo has no releases (GitHub's /releases/latest skips prereleases/drafts).
 */
@@ -1827,21 +1961,34 @@ async function resolveWritableSkill(deps, name, cwd) {
 }
 /** 系统集合组 + 用户 tag + origin 映射（groups 路由的数据源）。 */
 async function buildGroups(deps) {
-	const [tags, origins] = await Promise.all([deps.store.listTags(), deps.store.listOrigins()]);
+	const [tags, origins, collectionOrder, sourceGroupOrder] = await Promise.all([
+		deps.store.listTags(),
+		deps.store.listOrigins(),
+		deps.store.getCollectionOrder(),
+		deps.store.getSourceGroupOrder()
+	]);
 	const byCollection = /* @__PURE__ */ new Map();
 	for (const [skillName, origin] of Object.entries(origins)) {
 		const list = byCollection.get(origin);
 		if (list === void 0) byCollection.set(origin, [skillName]);
 		else list.push(skillName);
 	}
+	const orderIndex = new Map(collectionOrder.map((name, i) => [name, i]));
 	return {
 		ok: true,
 		tags,
 		collections: [...byCollection.entries()].map(([name, skillNames]) => ({
 			name,
 			skillNames: [...skillNames].sort((a, b) => a.localeCompare(b))
-		})).sort((a, b) => a.name.localeCompare(b.name)),
-		origins
+		})).sort((a, b) => {
+			const ai = orderIndex.has(a.name) ? orderIndex.get(a.name) : Infinity;
+			const bi = orderIndex.has(b.name) ? orderIndex.get(b.name) : Infinity;
+			if (ai !== bi) return ai - bi;
+			return a.name.localeCompare(b.name);
+		}),
+		origins,
+		...sourceGroupOrder.length > 0 ? { sourceGroupOrder } : {},
+		...collectionOrder.length > 0 ? { collectionOrder } : {}
 	};
 }
 /** 目录中存在的技能名集合（tag 成员校验用）：启用目录 ∪ 已禁用名单，避免成员因禁用而丢失。 */
@@ -1986,6 +2133,18 @@ function toDetail(skill) {
 const lastSourceCheck = /* @__PURE__ */ new Map();
 /** Last successful market update check per repo (same throttle). */
 const lastMarketCheck = /* @__PURE__ */ new Map();
+const importJobs = /* @__PURE__ */ new Map();
+const IMPORT_JOB_TTL_MS = 5 * 6e4;
+const IMPORT_JOB_MAX = 100;
+function gcImportJobs() {
+	if (importJobs.size > 500) importJobs.clear();
+	const now = Date.now();
+	for (const [id, job] of importJobs) if (job.status !== "running" && now - job.createdAt > IMPORT_JOB_TTL_MS) importJobs.delete(id);
+	if (importJobs.size > IMPORT_JOB_MAX) {
+		const sorted = [...importJobs.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+		for (let i = 0; i < sorted.length - IMPORT_JOB_MAX; i++) importJobs.delete(sorted[i][0]);
+	}
+}
 /** Replace one skill directory with a fresh download; restores the old dir on failure. */
 async function replaceSkillDir(targetDir, download) {
 	const backup = join(dirname(targetDir), "." + basename(targetDir) + ".sync-bak-" + Date.now());
@@ -2103,13 +2262,27 @@ function makeRoutes(deps) {
 					return;
 				}
 				const resolved = await resolveWritableSkill(deps, name, typeof request.cwd === "string" ? request.cwd : void 0);
+				let trashResult = null;
 				if (!resolved.ok) {
-					writeError(res, resolved.status, resolved.error);
-					return;
+					const disabled = await deps.store.getDisabled(name);
+					if (disabled !== void 0) {
+						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
+						};
+					} else {
+						writeError(res, resolved.status, resolved.error);
+						return;
+					}
 				}
 				const tracked = await deps.store.getSourceForSkill(name);
 				const tagIds = (await deps.store.listTags()).filter((tag) => tag.skillNames.includes(name)).map((tag) => tag.id);
-				const { path, source } = await trashSkill(resolved.path);
+				const { path, source } = trashResult ?? await trashSkill(resolved.path);
 				await deps.store.addTrash({
 					name,
 					path,
@@ -2600,11 +2773,16 @@ function makeRoutes(deps) {
 				const entries = discoverRepoEntries(tree, repo, await knownSkillNames(deps));
 				const byPath = new Map(entries.map((entry) => [entry.path, entry]));
 				const selected = paths.map((path) => byPath.get(path)).filter((entry) => entry !== void 0);
+				if (selected.length === 0) {
+					writeError(res, 400, "no matching skills for selected paths");
+					return;
+				}
 				if (selected.length > 500) {
 					writeError(res, 400, "select at most 500 skills per import");
 					return;
 				}
-				if (selected.reduce((sum, entry) => sum + entry.totalBytes, 0) > 200 * 1024 * 1024) {
+				const totalBytes = selected.reduce((sum, entry) => sum + entry.totalBytes, 0);
+				if (totalBytes > 200 * 1024 * 1024) {
 					writeError(res, 400, "selected skills exceed the 200MB import limit");
 					return;
 				}
@@ -2612,51 +2790,164 @@ function makeRoutes(deps) {
 				try {
 					commitSha = (await getLatestCommit(repo, resolvedRef)).commitSha;
 				} catch {}
-				const imported = [];
-				const skipped = [];
-				const failed = [];
-				const targetRoot = rootPath("user-dsh", homeOf(deps));
-				await mkdir(targetRoot, { recursive: true });
-				const defaultTag = await deps.store.getDefaultTag();
-				for (const entry of selected) {
-					if (entry.existing) {
-						skipped.push({
-							name: entry.name,
-							reason: "exists"
-						});
-						continue;
-					}
-					if (await pathExists(join(targetRoot, entry.name))) {
-						skipped.push({
-							name: entry.name,
-							reason: "exists"
-						});
-						continue;
+				const jobId = "imp_" + randomUUID().slice(0, 8);
+				const controller = new AbortController();
+				const now = Date.now();
+				const job = {
+					jobId,
+					repo,
+					ref: resolvedRef,
+					total: selected.length,
+					done: 0,
+					totalBytes,
+					downloadedBytes: 0,
+					startTime: now,
+					imported: [],
+					skipped: [],
+					failed: [],
+					status: "running",
+					controller,
+					createdAt: now
+				};
+				gcImportJobs();
+				importJobs.set(jobId, job);
+				cleanupLeftoverImportDirs(rootPath("user-dsh", homeOf(deps))).catch(() => {});
+				(async () => {
+					const targetRoot = rootPath("user-dsh", homeOf(deps));
+					await mkdir(targetRoot, { recursive: true });
+					const defaultTag = await deps.store.getDefaultTag();
+					let needInvalidate = false;
+					for (const entry of selected) {
+						if (controller.signal.aborted) break;
+						job.current = entry.name;
+						job.currentFile = entry.dir + "/SKILL.md";
+						if (entry.existing) {
+							job.skipped.push({
+								name: entry.name,
+								reason: "exists"
+							});
+							job.downloadedBytes += entry.totalBytes;
+							job.done += 1;
+							continue;
+						}
+						if (await pathExists(join(targetRoot, entry.name))) {
+							job.skipped.push({
+								name: entry.name,
+								reason: "exists"
+							});
+							job.downloadedBytes += entry.totalBytes;
+							job.done += 1;
+							continue;
+						}
+						if (controller.signal.aborted) break;
+						const files = collectRepoSkillFiles(tree, entry.dir);
+						try {
+							const result = await downloadRepoSkill(repo, resolvedRef, entry, files, targetRoot, fetch, controller.signal, (bytes, file) => {
+								job.downloadedBytes += bytes;
+								job.currentFile = entry.dir + "/" + file;
+							});
+							await deps.store.addSourceSkill(repo, entry.root, commitSha, resolvedRef, entry.name);
+							await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir);
+							if (defaultTag !== void 0) await deps.store.addSkillToTag(defaultTag.id, entry.name);
+							job.imported.push({
+								name: entry.name,
+								origin: entry.origin,
+								path: result.skillPath
+							});
+							needInvalidate = true;
+						} catch (error) {
+							if (isAbortError(error) || controller.signal.aborted) break;
+							job.failed.push({
+								name: entry.name,
+								error: error instanceof Error ? error.message : String(error)
+							});
+						} finally {
+							job.done += 1;
+						}
 					}
-					const files = collectRepoSkillFiles(tree, entry.dir);
-					try {
-						const result = await downloadRepoSkill(repo, resolvedRef, entry, files, targetRoot);
-						await deps.store.addSourceSkill(repo, entry.root, commitSha, resolvedRef, entry.name);
-						await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir);
-						if (defaultTag !== void 0) await deps.store.addSkillToTag(defaultTag.id, entry.name);
-						imported.push({
-							name: entry.name,
-							origin: entry.origin,
-							path: result.skillPath
-						});
-					} catch (error) {
-						failed.push({
-							name: entry.name,
-							error: error instanceof Error ? error.message : String(error)
-						});
+					if (controller.signal.aborted) {
+						job.status = "cancelled";
+						job.current = void 0;
+						job.currentFile = void 0;
+					} else {
+						job.status = "done";
+						job.current = void 0;
+						job.currentFile = void 0;
+						job.downloadedBytes = job.totalBytes;
 					}
+					if (needInvalidate) deps.invalidate?.();
+				})().catch((error) => {
+					job.status = "error";
+					job.error = error instanceof Error ? error.message : String(error);
+					job.current = void 0;
+					job.currentFile = void 0;
+				});
+				writeJson(res, 200, {
+					ok: true,
+					jobId,
+					total: selected.length,
+					totalBytes
+				});
+			}
+		}),
+		route({
+			path: SKILL_HUB_API.repoImportProgress,
+			methods: ["GET"],
+			handler: async ({ res, url }) => {
+				const jobId = queryParam(url, "jobId") ?? "";
+				if (jobId === "") {
+					writeError(res, 400, "jobId is required");
+					return;
 				}
-				deps.invalidate?.();
+				const job = importJobs.get(jobId);
+				if (job === void 0) {
+					writeError(res, 404, "import job not found: " + jobId);
+					return;
+				}
+				const elapsedSec = Math.max(.5, (Date.now() - job.startTime) / 1e3);
+				const bytesPerSecond = job.status === "running" ? Math.round(job.downloadedBytes / elapsedSec) : void 0;
 				writeJson(res, 200, {
 					ok: true,
-					imported,
-					skipped,
-					failed
+					jobId: job.jobId,
+					status: job.status,
+					total: job.total,
+					done: job.done,
+					...job.current !== void 0 ? { current: job.current } : {},
+					...job.currentFile !== void 0 ? { currentFile: job.currentFile } : {},
+					totalBytes: job.totalBytes,
+					downloadedBytes: job.downloadedBytes,
+					...bytesPerSecond !== void 0 ? { bytesPerSecond } : {},
+					imported: [...job.imported],
+					skipped: [...job.skipped],
+					failed: [...job.failed],
+					...job.error !== void 0 ? { error: job.error } : {}
+				});
+			}
+		}),
+		route({
+			path: SKILL_HUB_API.repoImportCancel,
+			methods: ["POST"],
+			jsonBody: true,
+			handler: async ({ res, body }) => {
+				const request = body;
+				const jobId = typeof request.jobId === "string" ? request.jobId : "";
+				if (jobId === "") {
+					writeError(res, 400, "jobId is required");
+					return;
+				}
+				const job = importJobs.get(jobId);
+				if (job === void 0) {
+					writeError(res, 404, "import job not found: " + jobId);
+					return;
+				}
+				if (job.status === "running") {
+					job.controller.abort();
+					job.status = "cancelled";
+				}
+				writeJson(res, 200, {
+					ok: true,
+					jobId: job.jobId,
+					status: job.status
 				});
 			}
 		}),
@@ -2739,14 +3030,64 @@ function makeRoutes(deps) {
 				});
 			}
 		}),
+		route({
+			path: SKILL_HUB_API.tagReorder,
+			methods: ["POST"],
+			jsonBody: true,
+			handler: async ({ res, body }) => {
+				const request = body;
+				const orderedIds = Array.isArray(request.orderedIds) ? request.orderedIds.filter((id) => typeof id === "string" && id !== "") : [];
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						tags: await deps.store.reorderTags(orderedIds)
+					});
+				} catch (error) {
+					if (error instanceof StoreError) {
+						writeError(res, error.kind === "validation" ? 400 : error.kind === "not-found" ? 404 : 409, error.message);
+						return;
+					}
+					throw error;
+				}
+			}
+		}),
+		route({
+			path: SKILL_HUB_API.collectionReorder,
+			methods: ["POST"],
+			jsonBody: true,
+			handler: async ({ res, body }) => {
+				const request = body;
+				const orderedNames = Array.isArray(request.orderedNames) ? request.orderedNames.filter((n) => typeof n === "string" && n !== "") : [];
+				const order = await deps.store.reorderCollections(orderedNames);
+				writeJson(res, 200, {
+					ok: true,
+					collections: (await buildGroups(deps)).collections,
+					order
+				});
+			}
+		}),
+		route({
+			path: SKILL_HUB_API.sourceGroupReorder,
+			methods: ["POST"],
+			jsonBody: true,
+			handler: async ({ res, body }) => {
+				const request = body;
+				const orderedKeys = Array.isArray(request.orderedKeys) ? request.orderedKeys.filter((k) => typeof k === "string" && k !== "") : [];
+				writeJson(res, 200, {
+					ok: true,
+					order: await deps.store.reorderSourceGroups(orderedKeys)
+				});
+			}
+		}),
 		route({
 			path: SKILL_HUB_API.sources,
 			methods: ["GET"],
 			handler: async ({ res }) => {
-				const [sources, origins, trash] = await Promise.all([
+				const [sources, origins, trash, collectionOrder] = await Promise.all([
 					deps.store.listSources(),
 					deps.store.listOrigins(),
-					deps.store.listTrash()
+					deps.store.listTrash(),
+					deps.store.getCollectionOrder()
 				]);
 				const byCollection = /* @__PURE__ */ new Map();
 				for (const [skillName, origin] of Object.entries(origins)) {
@@ -2754,6 +3095,7 @@ function makeRoutes(deps) {
 					if (list === void 0) byCollection.set(origin, [skillName]);
 					else list.push(skillName);
 				}
+				const orderIndex = new Map(collectionOrder.map((name, i) => [name, i]));
 				writeJson(res, 200, {
 					ok: true,
 					sources,
@@ -2761,7 +3103,12 @@ function makeRoutes(deps) {
 					collections: [...byCollection.entries()].map(([name, skillNames]) => ({
 						name,
 						skillNames: [...skillNames].sort((a, b) => a.localeCompare(b))
-					})).sort((a, b) => a.name.localeCompare(b.name)),
+					})).sort((a, b) => {
+						const ai = orderIndex.has(a.name) ? orderIndex.get(a.name) : Infinity;
+						const bi = orderIndex.has(b.name) ? orderIndex.get(b.name) : Infinity;
+						if (ai !== bi) return ai - bi;
+						return a.name.localeCompare(b.name);
+					}),
 					trash
 				});
 			}
@@ -3273,7 +3620,7 @@ const Config = z.object({
 * page edit this namespace through the official settings transport, and the
 * plugin consumes the same resolved value — one source of truth.
 */
-const CONFIG_NAMESPACE = settingsNamespace("dsh-skill-hub");
+const CONFIG_NAMESPACE = "dsh-skill-hub";
 /** Schema of the hub's settings namespace: the card's fields (booleans + optional dot colors). */
 const HubSettingsSchema = z.object({
 	enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled),
@@ -3306,7 +3653,7 @@ function apply(ctx, config) {
 	let providerControl;
 	let stats;
 	const saved = () => {
-		return ctx.settings.describe().find((entry) => entry.ns === CONFIG_NAMESPACE)?.user ?? {};
+		return ctx.settings.describe().find((entry) => entry.ns === "dsh-skill-hub")?.user ?? {};
 	};
 	const updateConfig = async (patch) => {
 		const user = { ...saved() };
@@ -3362,6 +3709,16 @@ function apply(ctx, config) {
 	ctx.effect(() => settingsScope.watch(() => {
 		sync();
 	}), "dsh-skill-hub: settings config watch");
+	(async () => {
+		const home = dshHome();
+		const agentsHome = process.env.DSH_AGENTS_HOME ?? join(homedir(), ".agents");
+		for (const root of [join(home, "skills"), join(agentsHome, "skills")]) try {
+			const c = await cleanupLeftoverImportDirs(root);
+			if (c > 0) ctx.logger.info(`[dsh-skill-hub] startup cleaned ${c} leftover import temp dir(s) in ${root}`);
+		} catch (error) {
+			ctx.logger.warn("[dsh-skill-hub] startup cleanup failed", error);
+		}
+	})();
 	(async () => {
 		const legacy = await store.getConfig();
 		if (Object.keys(legacy).length > 0 && Object.keys(saved()).length === 0) try {