dsh-skill-importer 0.1.2 → 0.2.1

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,13 +58,36 @@ 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;
-/**
- * Fetch a URL's content for import. Markdown/plain responses pass through
- * verbatim; HTML is roughly extracted to text (the import UI recommends
- * `.md` sources).
- * @param url - the source URL.
- * @returns the text to write as the skill body.
- */
+/** 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[];
+/** Whether an address is unsafe for a host-side URL import. */
+export declare function isPrivateAddress(address: string): boolean;
+type ResolveHost = (hostname: string) => Promise<readonly {
+    readonly address: string;
+}[]>;
+/** Parse and resolve one URL before the host is allowed to request it. */
+export declare function assertSafeImportUrl(input: string, resolver?: ResolveHost): Promise<URL>;
 export declare function fetchUrlContent(url: string): Promise<string>;
 /**
  * Resolve one import request into a written file path. Shared by the file
@@ -74,10 +102,12 @@ export declare function readJsonBody(req: IncomingMessage, limit?: number): Prom
  * Origin fence: the routes are served on the harness's loopback-only web
  * server, so only the browser page itself (or a local curl) reaches them.
  * A cross-origin page (any other website) is refused. Requests without an
- * Origin header (curl, same-origin GET) pass.
+ * Origin header is rejected: all state-changing browser requests include it,
+ * while accepting an absent header would let non-browser clients bypass the fence.
  */
 export declare function originAllowed(req: IncomingMessage): boolean;
 /** Send one JSON response. */
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-importer",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Web UI plugin for DeepSeek Harness: import skills from local Markdown files or URLs into the skill roots the harness discovers automatically",
   "type": "module",
   "main": "lib/index.js",
@@ -36,10 +36,15 @@
     "lib/index.js",
     "lib/client.js",
     "lib/types/**/*.d.ts",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "src/frontmatter.ts",
+    "src/server.ts",
+    "src/types.ts",
+    "tests/**/*.mjs"
   ],
   "scripts": {
     "build": "rm -rf lib && tsc -p tsconfig.json && tsdown",
+    "test:batch": "node --experimental-strip-types tests/batch-import.test.mjs",
     "watch": "tsdown --watch"
   },
   "license": "MIT",

package/src/frontmatter.ts

@@ -0,0 +1,112 @@
+/**
+ * Skill Markdown frontmatter parsing and validation (pure, browser-safe).
+ *
+ * Mirrors the subset of `dsh-skill-filesystem`'s frontmatter contract the
+ * import UI needs for preview and pre-flight validation. The authoritative
+ * parse remains the host provider's; this parser only previews and catches
+ * obvious mistakes before the import instruction is sent.
+ */
+
+/** Frontmatter fields the import UI understands. */
+export interface SkillFrontmatter {
+  /** Kebab-case skill name (required for a valid skill). */
+  name?: string
+  /** One-line routing description (required for a valid skill). */
+  description?: string
+  /** Optional routing guidance. */
+  whenToUse?: string
+  /** `disable-model-invocation: true` keeps the skill out of model catalogs. */
+  disableModelInvocation?: boolean
+  /** `user-invocable: false` keeps the skill out of the `/` menu. */
+  userInvocable?: boolean
+}
+
+/** Parsed Markdown file: frontmatter plus the body after it. */
+export interface ParsedSkillFile {
+  /** Parsed frontmatter values (empty when the file has no frontmatter block). */
+  readonly frontmatter: SkillFrontmatter
+  /** Markdown body after the closing `---` (empty when absent). */
+  readonly body: string
+}
+
+/** Kebab-case name rule shared with `dsh-skill` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). */
+const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/** True when the name satisfies the harness skill-name rule. */
+export function isValidSkillName(name: string): boolean {
+  return KEBAB_CASE.test(name)
+}
+
+const BOOLEAN_TRUE = new Set(['true', 'yes', 'on', '1'])
+const BOOLEAN_FALSE = new Set(['false', 'no', 'off', '0'])
+
+/** Parse one frontmatter scalar: quoted strings, booleans, or plain text. */
+function parseScalar(raw: string): string | boolean | undefined {
+  const value = raw.trim()
+  if (value.length === 0) return undefined
+  const lower = value.toLowerCase()
+  if (BOOLEAN_TRUE.has(lower)) return true
+  if (BOOLEAN_FALSE.has(lower)) return false
+  if (
+    (value.startsWith('"') && value.endsWith('"') && value.length >= 2)
+    || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
+  ) {
+    return value.slice(1, -1)
+  }
+  return value
+}
+
+/**
+ * Parse a skill Markdown file's frontmatter block.
+ * @param text - full file text.
+ * @returns parsed frontmatter and body; a file without a leading `---` block
+ *   yields an empty frontmatter with the whole text as body.
+ */
+export function parseSkillFile(text: string): ParsedSkillFile {
+  const frontmatter: SkillFrontmatter = {}
+  // Normalize platform line endings before locating and parsing the YAML
+  // fence. This accepts Windows CRLF and legacy CR files while keeping the
+  // canonical output produced by normalizeSkillText consistently LF-based.
+  const normalized = text.replace(/\r\n?/g, '\n')
+  if (!normalized.startsWith('---\n')) return { frontmatter, body: text }
+  const end = normalized.indexOf('\n---', 4)
+  if (end < 0) return { frontmatter, body: text }
+  const block = normalized.slice(4, end)
+  const body = normalized.slice(end + 4).replace(/^\n/, '')
+  for (const line of block.split('\n')) {
+    const colon = line.indexOf(':')
+    if (colon <= 0) continue
+    const key = line.slice(0, colon).trim()
+    const value = parseScalar(line.slice(colon + 1))
+    if (value === undefined) continue
+    switch (key) {
+      case 'name':
+        if (typeof value === 'string') frontmatter.name = value
+        break
+      case 'description':
+        if (typeof value === 'string') frontmatter.description = value
+        break
+      case 'whenToUse':
+        if (typeof value === 'string') frontmatter.whenToUse = value
+        break
+      case 'disable-model-invocation':
+        if (typeof value === 'boolean') frontmatter.disableModelInvocation = value
+        break
+      case 'user-invocable':
+        if (typeof value === 'boolean') frontmatter.userInvocable = value
+        break
+      default:
+        break
+    }
+  }
+  return { frontmatter, body }
+}
+
+/** Why a parsed file cannot be imported as a skill (or undefined when it can). */
+export function validateSkillFile(text: string): string | undefined {
+  const { frontmatter } = parseSkillFile(text)
+  if (frontmatter.name === undefined || frontmatter.name.length === 0) return 'frontmatter 缺少 name 字段'
+  if (!isValidSkillName(frontmatter.name)) return 'name 必须是 kebab-case（小写字母、数字、短横线）'
+  if (frontmatter.description === undefined || frontmatter.description.length === 0) return 'frontmatter 缺少 description 字段'
+  return undefined
+}