dsh-skill-importer 0.1.2 → 0.2.0

package/lib/index.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, extname, isAbsolute, join, relative } from "node:path";
 //#region src/frontmatter.ts
 /** Kebab-case name rule shared with `dsh-skill` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). */
 const KEBAB_CASE$1 = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -91,6 +92,9 @@ function parseSkillFile(text) {
 const MAX_CONTENT_BYTES = 262144;
 /** Cap for one request body read (JSON overhead above the content cap). */
 const MAX_BODY_BYTES = 1048576;
+const MAX_BATCH_FILES_PER_SKILL = 2e3;
+const MAX_BATCH_SKILL_BYTES = 10485760;
+const BATCH_SCAN_TTL_MS = 6e5;
 const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** The harness home (`$DSH_HOME`, defaulting to `~/.dsh`). */
 function dshHomeDir() {
@@ -101,21 +105,15 @@ function skillRoot(target, workspacePath) {
 	switch (target) {
 		case "user": return join(dshHomeDir(), "skills");
 		case "project-agents": return join(workspacePath, ".agents", "skills");
-		case "project-dsh": return join(workspacePath, ".dsh", "skills");
 	}
 }
 /** Discovery rank per root (lower wins), mirroring dsh-skill-filesystem. */
 const ROOT_RANK = {
-	"project-dsh": 100,
 	"project-agents": 200,
 	user: 400
 };
 /** Scan order: project roots first so project skills win duplicate names. */
-const SCAN_ORDER = [
-	"project-dsh",
-	"project-agents",
-	"user"
-];
+const SCAN_ORDER = ["project-agents", "user"];
 /**
 * Quote one frontmatter string value when plain YAML would mis-parse it:
 * a value containing `: ` (or any colon), leading/trailing whitespace, a
@@ -240,6 +238,239 @@ function deleteSkillFile(name, source, workspacePath) {
 	}
 	return false;
 }
+/** Hash names and bytes while refusing symlinks and oversized skill bundles. */
+function sourceStats(sourcePath, kind) {
+	const hash = createHash("sha256");
+	let fileCount = 0;
+	let bytes = 0;
+	const visit = (path, relativePath) => {
+		const stat = lstatSync(path);
+		if (stat.isSymbolicLink()) throw new Error("技能目录不能包含符号链接");
+		if (stat.isDirectory()) {
+			for (const entry of readdirSync(path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) visit(join(path, entry.name), relativePath.length === 0 ? entry.name : join(relativePath, entry.name));
+			return;
+		}
+		if (!stat.isFile()) throw new Error("技能目录包含不支持的文件类型");
+		fileCount += 1;
+		bytes += stat.size;
+		if (fileCount > 2e3) throw new Error(`技能文件数量超过 ${MAX_BATCH_FILES_PER_SKILL}`);
+		if (bytes > 10485760) throw new Error(`技能目录超过 ${MAX_BATCH_SKILL_BYTES / 1024 / 1024} MB`);
+		hash.update(relativePath);
+		hash.update("\0");
+		hash.update(readFileSync(path));
+		hash.update("\0");
+	};
+	visit(sourcePath, kind === "file" ? basename(sourcePath) : "");
+	return {
+		fingerprint: hash.digest("hex"),
+		fileCount,
+		bytes
+	};
+}
+function destinationExists(name, target, workspacePath) {
+	const root = skillRoot(target, workspacePath ?? "");
+	return existsSync(join(root, name)) || existsSync(join(root, `${name}.md`));
+}
+/** Resolve immediate child skill directories and flat Markdown skills. */
+function batchSources(root) {
+	const ownSkill = join(root, "SKILL.md");
+	if (existsSync(ownSkill)) return [{
+		path: root,
+		kind: "directory",
+		label: basename(root)
+	}];
+	const sources = [];
+	for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		const path = join(root, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory() && existsSync(join(path, "SKILL.md"))) sources.push({
+			path,
+			kind: "directory",
+			label: entry.name
+		});
+		else if (entry.isFile() && [".md", ".markdown"].includes(extname(entry.name).toLowerCase())) sources.push({
+			path,
+			kind: "file",
+			label: basename(entry.name, extname(entry.name))
+		});
+	}
+	return sources;
+}
+/** Validate a selected skills root without writing anything. */
+function scanBatch(request) {
+	if (!isAbsolute(request.sourcePath)) throw new Error("批量导入目录必须是绝对路径");
+	if (!existsSync(request.sourcePath) || !statSync(request.sourcePath).isDirectory()) throw new Error("批量导入目录不存在或不可读");
+	if (request.target !== "user" && request.workspacePath === void 0) throw new Error("项目目标需要 workspacePath（当前工作区路径）");
+	const sources = batchSources(request.sourcePath);
+	if (sources.length === 0) throw new Error("所选目录中没有找到可导入的技能");
+	if (sources.length > 200) throw new Error(`一次最多扫描 200 个技能`);
+	const entries = [];
+	const candidates = /* @__PURE__ */ new Map();
+	const nameRows = /* @__PURE__ */ new Map();
+	for (const [index, source] of sources.entries()) {
+		const id = String(index + 1);
+		const relativePath = relative(request.sourcePath, source.path) || ".";
+		try {
+			const skillFile = source.kind === "directory" ? join(source.path, "SKILL.md") : source.path;
+			const text = readFileSync(skillFile, "utf8");
+			if (Buffer.byteLength(text, "utf8") > 262144) throw new Error(`SKILL.md 超过 ${MAX_CONTENT_BYTES / 1024} KB`);
+			const { frontmatter } = parseSkillFile(text);
+			if (frontmatter.name === void 0) throw new Error("frontmatter 缺少 name 字段");
+			if (!isValidSkillName(frontmatter.name)) throw new Error("name 必须是 kebab-case（小写字母、数字、短横线）");
+			if (frontmatter.description === void 0 || frontmatter.description.trim().length === 0) throw new Error("frontmatter 缺少 description 字段");
+			normalizeSkillText(text);
+			const stats = sourceStats(source.path, source.kind);
+			const warnings = source.label === frontmatter.name ? void 0 : [`目录或文件名“${source.label}”与技能名“${frontmatter.name}”不一致`];
+			entries.push({
+				id,
+				name: frontmatter.name,
+				description: frontmatter.description,
+				relativePath,
+				status: "ready",
+				conflict: destinationExists(frontmatter.name, request.target, request.workspacePath),
+				...warnings === void 0 ? {} : { warnings }
+			});
+			candidates.set(id, {
+				id,
+				name: frontmatter.name,
+				description: frontmatter.description,
+				sourcePath: source.path,
+				sourceKind: source.kind,
+				fingerprint: stats.fingerprint
+			});
+			const at = entries.length - 1;
+			nameRows.set(frontmatter.name, [...nameRows.get(frontmatter.name) ?? [], at]);
+		} catch (error) {
+			entries.push({
+				id,
+				name: source.label,
+				relativePath,
+				status: "error",
+				error: error instanceof Error ? error.message : String(error),
+				conflict: false
+			});
+		}
+	}
+	for (const [name, indexes] of nameRows) {
+		if (indexes.length < 2) continue;
+		for (const index of indexes) {
+			const entry = entries[index];
+			if (entry === void 0) continue;
+			entries[index] = {
+				...entry,
+				status: "error",
+				conflict: false,
+				error: `批次内存在重复技能名：${name}`
+			};
+			candidates.delete(entry.id);
+		}
+	}
+	return {
+		scanId: randomUUID(),
+		sourcePath: request.sourcePath,
+		target: request.target,
+		...request.workspacePath === void 0 ? {} : { workspacePath: request.workspacePath },
+		expiresAt: Date.now() + BATCH_SCAN_TTL_MS,
+		entries,
+		candidates
+	};
+}
+/** Copy one validated candidate into a same-root staging directory, then atomically swap it in. */
+function installBatchCandidate(candidate, session, replace) {
+	if (sourceStats(candidate.sourcePath, candidate.sourceKind).fingerprint !== candidate.fingerprint) throw new Error("源技能在确认期间发生变化，请重新扫描");
+	const root = skillRoot(session.target, session.workspacePath ?? "");
+	mkdirSync(root, { recursive: true });
+	const finalDirectory = join(root, candidate.name);
+	const conflicts = [finalDirectory, join(root, `${candidate.name}.md`)].filter(existsSync);
+	if (conflicts.length > 0 && !replace) throw new Error("目标中已存在同名技能");
+	const staging = join(root, `.${candidate.name}.import-${randomUUID()}`);
+	const backups = [];
+	try {
+		if (candidate.sourceKind === "directory") {
+			cpSync(candidate.sourcePath, staging, {
+				recursive: true,
+				errorOnExist: true,
+				dereference: false
+			});
+			const skillFile = join(staging, "SKILL.md");
+			writeFileSync(skillFile, normalizeSkillText(readFileSync(skillFile, "utf8")), "utf8");
+		} else {
+			mkdirSync(staging, { recursive: false });
+			writeFileSync(join(staging, "SKILL.md"), normalizeSkillText(readFileSync(candidate.sourcePath, "utf8")), "utf8");
+		}
+		for (const original of conflicts) {
+			const backup = join(root, `.${basename(original)}.backup-${randomUUID()}`);
+			renameSync(original, backup);
+			backups.push({
+				original,
+				backup
+			});
+		}
+		renameSync(staging, finalDirectory);
+		for (const { backup } of backups) rmSync(backup, {
+			recursive: true,
+			force: true
+		});
+		return conflicts.length > 0 ? "replaced" : "imported";
+	} catch (error) {
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+		if (existsSync(finalDirectory) && backups.length > 0) rmSync(finalDirectory, {
+			recursive: true,
+			force: true
+		});
+		for (const { original, backup } of backups.reverse()) if (existsSync(backup)) renameSync(backup, original);
+		throw error;
+	}
+}
+/** Commit a valid, unexpired scan once; invalid rows are returned as errors and never written. */
+function commitBatch(session, replaceNames) {
+	if (Date.now() > session.expiresAt) throw new Error("批量扫描结果已过期，请重新扫描");
+	const results = [];
+	for (const entry of session.entries) {
+		if (entry.status === "error") {
+			results.push({
+				name: entry.name,
+				status: "error",
+				message: entry.error
+			});
+			continue;
+		}
+		const candidate = session.candidates.get(entry.id);
+		if (candidate === void 0) {
+			results.push({
+				name: entry.name,
+				status: "error",
+				message: "扫描记录不完整，请重新扫描"
+			});
+			continue;
+		}
+		const conflict = destinationExists(entry.name, session.target, session.workspacePath);
+		if (conflict && !replaceNames.has(entry.name)) {
+			results.push({
+				name: entry.name,
+				status: "skipped",
+				message: "目标中已存在同名技能，未选择替换"
+			});
+			continue;
+		}
+		try {
+			results.push({
+				name: entry.name,
+				status: installBatchCandidate(candidate, session, conflict && replaceNames.has(entry.name))
+			});
+		} catch (error) {
+			results.push({
+				name: entry.name,
+				status: "error",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	return results;
+}
 /** Strip HTML down to a plain-Markdown-ish text body (best effort). */
 function extractHtmlText(html) {
 	const withoutBlocks = html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<!--[\s\S]*?-->/g, "");
@@ -338,7 +569,9 @@ const ROUTES = {
 	list: "/skill-importer/list",
 	import: "/skill-importer/import",
 	importUrl: "/skill-importer/import-url",
-	delete: "/skill-importer/delete"
+	delete: "/skill-importer/delete",
+	batchScan: "/skill-importer/batch/scan",
+	batchCommit: "/skill-importer/batch/commit"
 };
 /** Required services: the harness web server's route registry and the workspace registry. */
 const inject = ["webServer", "workspaceRegistry"];
@@ -354,6 +587,11 @@ const handle = (fn) => (req, res) => {
 */
 function apply(ctx) {
 	const projectPaths = () => ctx.workspaceRegistry.list().map((workspace) => workspace.path);
+	const batchScans = /* @__PURE__ */ new Map();
+	const pruneBatchScans = () => {
+		const now = Date.now();
+		for (const [id, session] of batchScans) if (session.expiresAt <= now) batchScans.delete(id);
+	};
 	const routes = [
 		{
 			kind: "exact",
@@ -379,7 +617,7 @@ function apply(ctx) {
 					return;
 				}
 				const body = await readJsonBody(req);
-				if (typeof body.name !== "string" || typeof body.content !== "string" || body.target !== "user" && body.target !== "project-agents" && body.target !== "project-dsh") {
+				if (typeof body.name !== "string" || typeof body.content !== "string" || body.target !== "user" && body.target !== "project-agents") {
 					sendError(res, 400, "请求缺少 name / content / target 字段");
 					return;
 				}
@@ -404,7 +642,7 @@ function apply(ctx) {
 					return;
 				}
 				const body = await readJsonBody(req);
-				if (typeof body.name !== "string" || typeof body.url !== "string" || body.target !== "user" && body.target !== "project-agents" && body.target !== "project-dsh") {
+				if (typeof body.name !== "string" || typeof body.url !== "string" || body.target !== "user" && body.target !== "project-agents") {
 					sendError(res, 400, "请求缺少 name / url / target 字段");
 					return;
 				}
@@ -429,7 +667,7 @@ function apply(ctx) {
 					return;
 				}
 				const body = await readJsonBody(req);
-				if (typeof body.name !== "string" || body.source !== "user" && body.source !== "project-agents" && body.source !== "project-dsh") {
+				if (typeof body.name !== "string" || body.source !== "user" && body.source !== "project-agents") {
 					sendError(res, 400, "请求缺少 name / source 字段");
 					return;
 				}
@@ -439,6 +677,62 @@ function apply(ctx) {
 					removed: deleteSkillFile(body.name, body.source, workspacePath)
 				});
 			})
+		},
+		{
+			kind: "exact",
+			path: ROUTES.batchScan,
+			handler: handle(async (req, res) => {
+				if (!originAllowed(req)) {
+					sendError(res, 403, "origin 不被允许");
+					return;
+				}
+				const body = await readJsonBody(req);
+				if (typeof body.sourcePath !== "string" || body.target !== "user" && body.target !== "project-agents") {
+					sendError(res, 400, "请求缺少 sourcePath / target 字段");
+					return;
+				}
+				const workspacePath = requireWorkspace(body.target, body.workspacePath);
+				pruneBatchScans();
+				const session = scanBatch({
+					sourcePath: body.sourcePath,
+					target: body.target,
+					workspacePath
+				});
+				batchScans.set(session.scanId, session);
+				sendJson(res, 200, {
+					ok: true,
+					scanId: session.scanId,
+					sourcePath: session.sourcePath,
+					entries: session.entries
+				});
+			})
+		},
+		{
+			kind: "exact",
+			path: ROUTES.batchCommit,
+			handler: handle(async (req, res) => {
+				if (!originAllowed(req)) {
+					sendError(res, 403, "origin 不被允许");
+					return;
+				}
+				const body = await readJsonBody(req);
+				if (typeof body.scanId !== "string" || !Array.isArray(body.replace) || !body.replace.every((name) => typeof name === "string")) {
+					sendError(res, 400, "请求缺少 scanId / replace 字段");
+					return;
+				}
+				pruneBatchScans();
+				const session = batchScans.get(body.scanId);
+				if (session === void 0) {
+					sendError(res, 410, "批量扫描结果不存在或已过期，请重新扫描");
+					return;
+				}
+				batchScans.delete(body.scanId);
+				const allowedNames = new Set(session.entries.filter((entry) => entry.status === "ready" && entry.conflict).map((entry) => entry.name));
+				sendJson(res, 200, {
+					ok: true,
+					results: commitBatch(session, new Set(body.replace.filter((name) => allowedNames.has(name))))
+				});
+			})
 		}
 	];
 	/**

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

@@ -3,7 +3,7 @@ import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SkillImporterProps } from './SkillImporterSection.tsx';
 import type { SkillsPickerProps } from './SkillsPicker.tsx';
 import { type SkillImporterKey } from './locales.ts';
-import type { DeleteRequest, ImportRequest, ImportUrlRequest, SkillListResponse } from '../types.ts';
+import type { BatchCommitRequest, BatchCommitResponse, BatchScanRequest, BatchScanResponse, DeleteRequest, ImportRequest, ImportUrlRequest, SkillListResponse } from '../types.ts';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         /** The skill importer section's copy. */
@@ -27,6 +27,12 @@ export interface SkillImporterInjected {
         importUrl: (request: ImportUrlRequest) => Promise<string>;
         /** Delete one installed skill copy via the host route. */
         deleteSkill: (request: DeleteRequest) => Promise<boolean>;
+        /** Open dsh's native host directory chooser. */
+        pickDirectory: () => Promise<string | null>;
+        /** Validate one local skills root without writing. */
+        scanBatch: (request: BatchScanRequest) => Promise<BatchScanResponse>;
+        /** Commit one preflight once, replacing only explicitly confirmed names. */
+        commitBatch: (request: BatchCommitRequest) => Promise<BatchCommitResponse>;
     };
 }
 /** Required services (cordis fiber inject). */

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

@@ -20,9 +20,6 @@ export declare const zh: {
     installedTitle: string;
     refresh: string;
     installedEmpty: string;
-    sourceAgents: string;
-    sourceDsh: string;
-    sourceUser: string;
     delete: string;
     deleteConfirm: string;
     deleteFailed: string;
@@ -31,9 +28,18 @@ export declare const zh: {
     userOnly: string;
     modelOnly: string;
     importTitle: string;
+    importDescription: string;
     fileTab: string;
     urlTab: string;
+    batchTab: string;
+    fileEntryDescription: string;
+    urlEntryDescription: string;
+    batchEntryDescription: string;
     chooseFile: string;
+    filePickerHint: string;
+    replaceFile: string;
+    browse: string;
+    change: string;
     fileHelp: string;
     previewTitle: string;
     previewName: string;
@@ -48,10 +54,28 @@ export declare const zh: {
     urlLabel: string;
     urlNameLabel: string;
     urlNameHelp: string;
+    batchChooseDirectory: string;
+    batchDirectoryHint: string;
+    batchDirectorySelected: string;
+    batchPickFailed: string;
+    batchScan: string;
+    batchWorking: string;
+    batchCommit: string;
+    batchScanFailed: string;
+    batchImportFailed: string;
+    batchPreflight: string;
+    batchConflict: string;
+    batchReplace: string;
+    batchConfirm: string;
+    batchResultTitle: string;
+    batchResultSummary: string;
+    batchStatusImported: string;
+    batchStatusReplaced: string;
+    batchStatusSkipped: string;
+    batchStatusError: string;
     targetLabel: string;
     targetUser: string;
     targetProjectAgents: string;
-    targetProjectDsh: string;
     targetProjectNoWorkspace: string;
     noWorkspace: string;
     import: string;
@@ -75,9 +99,6 @@ export declare const en: {
     installedTitle: string;
     refresh: string;
     installedEmpty: string;
-    sourceAgents: string;
-    sourceDsh: string;
-    sourceUser: string;
     delete: string;
     deleteConfirm: string;
     deleteFailed: string;
@@ -86,9 +107,18 @@ export declare const en: {
     userOnly: string;
     modelOnly: string;
     importTitle: string;
+    importDescription: string;
     fileTab: string;
     urlTab: string;
+    batchTab: string;
+    fileEntryDescription: string;
+    urlEntryDescription: string;
+    batchEntryDescription: string;
     chooseFile: string;
+    filePickerHint: string;
+    replaceFile: string;
+    browse: string;
+    change: string;
     fileHelp: string;
     previewTitle: string;
     previewName: string;
@@ -103,10 +133,28 @@ export declare const en: {
     urlLabel: string;
     urlNameLabel: string;
     urlNameHelp: string;
+    batchChooseDirectory: string;
+    batchDirectoryHint: string;
+    batchDirectorySelected: string;
+    batchPickFailed: string;
+    batchScan: string;
+    batchWorking: string;
+    batchCommit: string;
+    batchScanFailed: string;
+    batchImportFailed: string;
+    batchPreflight: string;
+    batchConflict: string;
+    batchReplace: string;
+    batchConfirm: string;
+    batchResultTitle: string;
+    batchResultSummary: string;
+    batchStatusImported: string;
+    batchStatusReplaced: string;
+    batchStatusSkipped: string;
+    batchStatusError: string;
     targetLabel: string;
     targetUser: string;
     targetProjectAgents: string;
-    targetProjectDsh: string;
     targetProjectNoWorkspace: string;
     noWorkspace: string;
     import: string;

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Host (Node) half of the dsh-skill-importer plugin.
  *
- * Registers four `/skill-importer/*` HTTP routes on the harness's own web
+ * Registers the `/skill-importer/*` HTTP routes on the harness's own web
  * server (`ctx.webServer` — the official plugin route registry, served on
  * the same origin as the Web UI):
  *
@@ -10,6 +10,8 @@
  * - POST /skill-importer/import     — write one skill file from its text
  * - POST /skill-importer/import-url — fetch a URL and write the skill file
  * - POST /skill-importer/delete     — remove one installed skill copy
+ * - POST /skill-importer/batch/scan — validate a local skills directory without writing
+ * - POST /skill-importer/batch/commit — commit one short-lived preflight once
  *
  * The host process owns the filesystem (no agent sandbox, no approval), so
  * an import lands the file immediately; the skill-filesystem provider's
@@ -24,6 +26,8 @@ export declare const ROUTES: {
     readonly import: "/skill-importer/import";
     readonly importUrl: "/skill-importer/import-url";
     readonly delete: "/skill-importer/delete";
+    readonly batchScan: "/skill-importer/batch/scan";
+    readonly batchCommit: "/skill-importer/batch/commit";
 };
 /** Required services: the harness web server's route registry and the workspace registry. */
 export declare const inject: string[];

package/lib/types/server.d.ts

@@ -8,11 +8,16 @@
  * and the skill-filesystem watcher discovers it in place.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { ImportRequest, ImportTarget, ImportUrlRequest, SkillListEntry } from './types.ts';
+import type { BatchCommitEntry, BatchScanEntry, BatchScanRequest, ImportRequest, ImportTarget, ImportUrlRequest, SkillListEntry } from './types.ts';
 /** Hard cap for one imported skill body (matches the client preview limit). */
 export declare const MAX_CONTENT_BYTES: number;
 /** Cap for one request body read (JSON overhead above the content cap). */
 export declare const MAX_BODY_BYTES: number;
+/** Batch safety bounds: resources are copied, but one selection stays finite. */
+export declare const MAX_BATCH_SKILLS = 200;
+export declare const MAX_BATCH_FILES_PER_SKILL = 2000;
+export declare const MAX_BATCH_SKILL_BYTES: number;
+export declare const BATCH_SCAN_TTL_MS: number;
 /** The harness home (`$DSH_HOME`, defaulting to `~/.dsh`). */
 export declare function dshHomeDir(): string;
 /** Absolute skill root for one target under one workspace. */
@@ -53,6 +58,29 @@ export declare function listSkills(workspacePaths: readonly string[]): SkillList
  * @returns true when something was removed, false when nothing matched.
  */
 export declare function deleteSkillFile(name: string, source: ImportTarget, workspacePath?: string): boolean;
+/** Host-only source candidate retained between scan and the one-time commit. */
+interface BatchCandidate {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly sourcePath: string;
+    readonly sourceKind: 'directory' | 'file';
+    readonly fingerprint: string;
+}
+/** One short-lived preflight. The HTTP layer owns the map and single-use lifecycle. */
+export interface BatchScanSession {
+    readonly scanId: string;
+    readonly sourcePath: string;
+    readonly target: ImportTarget;
+    readonly workspacePath?: string;
+    readonly expiresAt: number;
+    readonly entries: readonly BatchScanEntry[];
+    readonly candidates: ReadonlyMap<string, BatchCandidate>;
+}
+/** Validate a selected skills root without writing anything. */
+export declare function scanBatch(request: BatchScanRequest): BatchScanSession;
+/** Commit a valid, unexpired scan once; invalid rows are returned as errors and never written. */
+export declare function commitBatch(session: BatchScanSession, replaceNames: ReadonlySet<string>): BatchCommitEntry[];
 /**
  * Fetch a URL's content for import. Markdown/plain responses pass through
  * verbatim; HTML is roughly extracted to text (the import UI recommends
@@ -81,3 +109,4 @@ export declare function originAllowed(req: IncomingMessage): boolean;
 export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
 /** Send a JSON error response with the given status. */
 export declare function sendError(res: ServerResponse, status: number, error: string): void;
+export {};

package/lib/types/types.d.ts

@@ -4,7 +4,7 @@
  * browser bundle can reference them safely.
  */
 /** Where the imported skill file should land. */
-export type ImportTarget = 'user' | 'project-agents' | 'project-dsh';
+export type ImportTarget = 'user' | 'project-agents';
 /** One installed skill row served by `/skill-importer/list`. */
 export interface SkillListEntry {
     /** Kebab-case skill name (frontmatter `name`). */
@@ -17,7 +17,7 @@ export interface SkillListEntry {
     readonly modelInvocable: boolean;
     /** False marks a model-only skill (`user-invocable: false`). */
     readonly userInvocable: boolean;
-    /** Winning discovery root ('project-dsh' | 'project-agents' | 'user'). */
+    /** Skill root (`'project-agents'` or `'user'`). */
     readonly source: ImportTarget;
 }
 /** File-import request body. */
@@ -32,7 +32,7 @@ export interface ImportRequest {
 /** Delete-request body. */
 export interface DeleteRequest {
     readonly name: string;
-    /** Which root the copy lives in ('user' | 'project-agents' | 'project-dsh'). */
+    /** Which root the copy lives in (`'project-agents'` or `'user'`). */
     readonly source: ImportTarget;
     /** Canonical workspace path for project sources (host-validated). */
     readonly workspacePath?: string;
@@ -46,6 +46,51 @@ export interface ImportUrlRequest {
     /** Canonical workspace path for project targets (host-validated against the registry). */
     readonly workspacePath?: string;
 }
+/** Read-only preflight request for one local skills directory. */
+export interface BatchScanRequest {
+    readonly sourcePath: string;
+    readonly target: ImportTarget;
+    readonly workspacePath?: string;
+}
+/** One source entry reported by batch preflight. */
+export interface BatchScanEntry {
+    /** Stable row id within this one scan. */
+    readonly id: string;
+    /** Frontmatter name when readable, otherwise a best-effort source label. */
+    readonly name: string;
+    readonly description?: string;
+    /** Path relative to the selected source directory. */
+    readonly relativePath: string;
+    /** Error rows can never be selected for commit. */
+    readonly status: 'ready' | 'error';
+    readonly error?: string;
+    readonly warnings?: readonly string[];
+    /** The selected destination already contains this skill name. */
+    readonly conflict: boolean;
+}
+/** Successful batch scan; the id is single-use and expires after ten minutes. */
+export interface BatchScanResponse {
+    readonly ok: true;
+    readonly scanId: string;
+    readonly sourcePath: string;
+    readonly entries: readonly BatchScanEntry[];
+}
+/** Commit a preflight, explicitly naming every destination conflict to replace. */
+export interface BatchCommitRequest {
+    readonly scanId: string;
+    readonly replace: readonly string[];
+}
+/** Final outcome of one preflight row. */
+export interface BatchCommitEntry {
+    readonly name: string;
+    readonly status: 'imported' | 'replaced' | 'skipped' | 'error';
+    readonly message?: string;
+}
+/** One-time batch commit result. */
+export interface BatchCommitResponse {
+    readonly ok: true;
+    readonly results: readonly BatchCommitEntry[];
+}
 /** `/skill-importer/list` response. */
 export interface SkillListResponse {
     readonly ok: true;