dsh-skill-importer 0.1.0

package/lib/types/frontmatter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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;
+}
+/** True when the name satisfies the harness skill-name rule. */
+export declare function isValidSkillName(name: string): boolean;
+/**
+ * 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 declare function parseSkillFile(text: string): ParsedSkillFile;
+/** Why a parsed file cannot be imported as a skill (or undefined when it can). */
+export declare function validateSkillFile(text: string): string | undefined;

package/lib/types/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Host (Node) half of the dsh-skill-importer plugin.
+ *
+ * Registers four `/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):
+ *
+ * - GET  /skill-importer/health     — liveness probe
+ * - GET  /skill-importer/list       — installed skills across all roots
+ * - 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
+ *
+ * The host process owns the filesystem (no agent sandbox, no approval), so
+ * an import lands the file immediately; the skill-filesystem provider's
+ * watcher then discovers it and hot-refreshes the catalog. No session, no
+ * model, no agent involved in imports.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Route paths this plugin owns (exact matches; the client fetches the same literals). */
+export declare const ROUTES: {
+    readonly health: "/skill-importer/health";
+    readonly list: "/skill-importer/list";
+    readonly import: "/skill-importer/import";
+    readonly importUrl: "/skill-importer/import-url";
+    readonly delete: "/skill-importer/delete";
+};
+/** Required services: the harness web server's route registry and the workspace registry. */
+export declare const inject: string[];
+/**
+ * Host plugin body: register the importer routes.
+ * @param ctx - host plugin context (provides `ctx.webServer`).
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/server.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Host-side skill importer logic: direct filesystem writes, skill-root
+ * scanning, and URL fetching. Pure Node — no Cordis imports — so the route
+ * handlers stay unit-testable and the plugin body is only wiring.
+ *
+ * This is the "direct write" path: the host process owns the filesystem
+ * (no agent sandbox, no approval), so an import lands the file immediately
+ * 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';
+/** 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;
+/** The harness home (`$DSH_HOME`, defaulting to `~/.dsh`). */
+export declare function dshHomeDir(): string;
+/** Absolute skill root for one target under one workspace. */
+export declare function skillRoot(target: ImportTarget, workspacePath: string): string;
+/**
+ * Rebuild a skill file's frontmatter in the canonical, strictly-YAML-valid
+ * form the harness's provider parses. Unknown keys are dropped (the harness
+ * only consumes name/description/whenToUse and the two invocation flags);
+ * the body is preserved verbatim (trimmed).
+ */
+export declare function normalizeSkillText(text: string): string;
+/**
+ * Write one skill file atomically: `<root>/<name>/SKILL.md`, created via a
+ * same-directory temp file plus rename so a crash never leaves a torn file.
+ * The content's frontmatter is normalized first so the harness's strict YAML
+ * discovery always finds the skill.
+ * @param name - kebab-case skill name (validated).
+ * @param target - which skill root to write into.
+ * @param content - full Markdown text (frontmatter included).
+ * @param workspacePath - canonical workspace path; required for project targets.
+ * @returns the absolute path of the written file.
+ */
+export declare function writeSkillFile(name: string, target: ImportTarget, content: string, workspacePath?: string): string;
+/**
+ * List every installed skill across every registered workspace's project
+ * roots plus the user root. No rank deduplication: the management surface
+ * shows every location's copy (the framework's own catalog still applies
+ * rank at discovery time). Display order groups by source, then name.
+ * @param workspacePaths - canonical paths of the registered workspaces.
+ */
+export declare function listSkills(workspacePaths: readonly string[]): SkillListEntry[];
+/**
+ * Delete one installed skill (its whole bundle directory `<root>/<name>/`,
+ * or the flat `<root>/<name>.md`), scoped to the skill roots only.
+ * @param name - kebab-case skill name (validated).
+ * @param source - which root the copy lives in.
+ * @param workspacePath - canonical workspace path; required for project sources.
+ * @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.
+ */
+export declare function fetchUrlContent(url: string): Promise<string>;
+/**
+ * Resolve one import request into a written file path. Shared by the file
+ * and URL routes; URL imports fetch first, then reuse the same write path.
+ * @param request - validated import body.
+ * @returns the absolute path of the written SKILL.md.
+ */
+export declare function resolveImport(request: ImportRequest | ImportUrlRequest): Promise<string>;
+/** Read and parse a JSON request body within a byte cap. */
+export declare function readJsonBody(req: IncomingMessage, limit?: number): Promise<unknown>;
+/**
+ * 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.
+ */
+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;

package/lib/types/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared wire types between the host half (HTTP routes) and the client half
+ * (fetch calls). Pure types — no runtime code, no node imports — so the
+ * browser bundle can reference them safely.
+ */
+/** Where the imported skill file should land. */
+export type ImportTarget = 'user' | 'project-agents' | 'project-dsh';
+/** One installed skill row served by `/skill-importer/list`. */
+export interface SkillListEntry {
+    /** Kebab-case skill name (frontmatter `name`). */
+    readonly name: string;
+    /** One-line routing description (frontmatter `description`). */
+    readonly description: string;
+    /** Optional routing guidance (frontmatter `whenToUse`). */
+    readonly whenToUse?: string;
+    /** False marks a user-only skill (`disable-model-invocation`). */
+    readonly modelInvocable: boolean;
+    /** False marks a model-only skill (`user-invocable: false`). */
+    readonly userInvocable: boolean;
+    /** Winning discovery root ('project-dsh' | 'project-agents' | 'user'). */
+    readonly source: ImportTarget;
+}
+/** File-import request body. */
+export interface ImportRequest {
+    readonly name: string;
+    readonly target: ImportTarget;
+    /** Full Markdown skill file text (frontmatter included). */
+    readonly content: string;
+    /** Canonical workspace path for project targets (host-validated against the registry). */
+    readonly workspacePath?: string;
+}
+/** Delete-request body. */
+export interface DeleteRequest {
+    readonly name: string;
+    /** Which root the copy lives in ('user' | 'project-agents' | 'project-dsh'). */
+    readonly source: ImportTarget;
+    /** Canonical workspace path for project sources (host-validated). */
+    readonly workspacePath?: string;
+}
+/** URL-import request body. */
+export interface ImportUrlRequest {
+    readonly name: string;
+    readonly target: ImportTarget;
+    /** Source URL the host fetches (`.md` preferred; HTML is roughly extracted). */
+    readonly url: string;
+    /** Canonical workspace path for project targets (host-validated against the registry). */
+    readonly workspacePath?: string;
+}
+/** `/skill-importer/list` response. */
+export interface SkillListResponse {
+    readonly ok: true;
+    readonly skills: readonly SkillListEntry[];
+}
+/** Success response of an import. */
+export interface ImportResponse {
+    readonly ok: true;
+    /** Absolute path of the written SKILL.md. */
+    readonly path: string;
+}
+/** Error response of any route. */
+export interface ErrorResponse {
+    readonly ok: false;
+    readonly error: string;
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "dsh-skill-importer",
+  "version": "0.1.0",
+  "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",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.json && tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-commands": "^0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@types/react": "^18.3.0",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@types/node": "^24.0.0",
+    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-commands": "^0.1.0-rc.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saitamahang/dsh-skill-importer.git"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "skill",
+    "agent",
+    "plugin"
+  ]
+}