dsh-codex-port 0.2.0 → 0.2.1

package/README.en.md

@@ -1,5 +1,7 @@
 [中文](README.md)
 
+![npm](https://img.shields.io/npm/v/dsh-codex-port) ![downloads](https://img.shields.io/npm/dm/dsh-codex-port) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-codex-port) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-codex-port?style=social)
+
 # dsh-codex-port
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
@@ -10,7 +12,7 @@ Move the whole **official Codex plugin family** into DSH: scan `~/.codex` unpack
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified against `@deepseek-ai/dsh@0.1.2-alpha.2` on 2026-08-31. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 
@@ -68,16 +70,19 @@ Ported skills are immediately usable from the DSH skills directory; the agent tr
 - **Frontmatter conversion**: Codex `name/description/metadata` → DSH `name/description/compatibility/allowed-tools`, multi-line descriptions preserved
 - **Codex-only files stripped**: `agents/*.yaml` and friends stay behind
 - **Name sanitization**: invalid characters become underscores; `..` traversal rejected outright
+- **Host loadability checks**: before replacement, the converted name must follow DSH's lowercase kebab-case grammar, exactly match its target directory, and have a nonempty description. Names with uppercase letters, underscores, dots, or a different sanitized directory name cannot replace an existing skill.
 - **Idempotent**: same-name skills are skipped by default; `overwrite=true` to replace
+- **Recoverable replacement**: copying, conversion, and read-back validation finish inside a unique `.dsh-port-<skill>-*` directory under the target root before the old skill moves to `previous/` and the new skill takes its place. Copy/conversion failures leave the old skill untouched. A failed switch attempts rollback; if rollback also fails, both copies remain and the error includes their recovery location. Content created by another writer is never deleted.
+- **Backups and path checks**: successful replacements retain `previous/` and `recovery.json`, using additional disk space; archive them manually when recovery is no longer needed. No `SKILL.md` sits at the transaction directory's top level, so current DSH one-level skill discovery does not register backups. Overlapping source/target paths, target symlinks/junctions, paths outside the target root, and Windows device names are rejected. Multiple renames are not one atomic Windows transaction; after process or system interruption, inspect `recovery.json` to restore the appropriate directory.
 - **Safe**: pure filesystem operations, zero runtime dependencies (yaml parsing only)
 
 ## Development
 
 ```bash
 pnpm install
-pnpm test       # build + 33 tests
+pnpm test       # build + offline tests; fixtures stay under workspace .harness-validation/codex-port-tests
 ```
 
 ## License
 
-MIT
+MIT

package/README.md

@@ -15,7 +15,7 @@
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+在 `@deepseek-ai/dsh@0.1.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -89,14 +89,17 @@ codex_port { targetDir: ~/.claude/skills }
 - **frontmatter 转换**：Codex 的 `name/description/metadata` → DSH 的 `name/description/compatibility/allowed-tools`，多行描述完整保留
 - **剔除 codex 专属文件**：`agents/*.yaml` 等子代理描述不带走
 - **名称清洗**：非法字符替换为下划线，`..` 路径穿越直接拒绝
+- **宿主可加载性校验**：覆盖前要求转换后的技能名符合 DSH 的小写短横线命名规则、与目标目录同名，且描述为非空字符串；大写、下划线、点号或清洗后不同名的技能不会替换旧版。
 - **幂等**：同名技能默认跳过，`overwrite=true` 才覆盖
+- **覆盖失败可恢复**：先在目标根内的唯一 `.dsh-port-<技能名>-*` 目录中复制、转换并回读校验；成功后才把旧技能移到事务目录的 `previous/`，再切换新技能。复制或转换失败不会改动旧技能，切换失败会尝试恢复旧技能；恢复失败时保留两份资料，并在失败原因中给出恢复路径。不会删除已存在的其他写入。
+- **备份与目录边界**：成功覆盖也保留 `previous/` 及 `recovery.json`，会额外占用磁盘空间；确认不需要恢复后可自行归档。事务目录顶层不含 `SKILL.md`，不会被当前 DSH 的单层技能发现重复注册。拒绝源/目标重叠、目标符号链接或目录联接、路径越界及 Windows 设备名称。多次目录重命名不构成 Windows 上全程原子的事务；进程或系统中断后可按 `recovery.json` 检查和恢复。
 - **安全**：纯文件系统操作，零运行时依赖（仅 yaml 解析）
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm test       # 构建 + 33 个测试
+pnpm test       # 构建 + 离线测试；fixture 只写入工作区 .harness-validation/codex-port-tests
 ```
 
 ## License

package/lib/port.d.ts

@@ -8,6 +8,7 @@ export interface PortResult {
     files: number;
 }
 /**
- * 移植单个技能到目标目录。
+ * Port one skill without deleting its previous installation. Each rename is a
+ * filesystem operation; the complete replacement is not atomic on Windows.
  */
 export declare function portSkill(skill: CodexSkillSource, plugin: CodexPluginInfo, targetDir: string, overwrite: boolean): PortResult;

package/lib/port.js

@@ -1,59 +1,198 @@
 /**
- * 移植执行：目录拷贝（剔除 agents 等 codex 专属文件）+ SKILL.md 转换 + 幂等跳过。
- *
+ * Stage and validate skill copies before replacing an installation; retain backups for recovery.
  * @module dsh-codex-port/port
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { convertSkillFile, sanitizeSkillName } from './frontmatter.js';
-/** codex 专属目录，移植时剔除。 */
+import fs from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { convertSkillFile, parseSkillFile, sanitizeSkillName } from './frontmatter.js';
 const EXCLUDED_DIRS = new Set(['agents']);
-/** 递归拷贝，跳过排除目录；返回拷贝文件数。 */
-function copyTree(source, target) {
-    mkdirSync(target, { recursive: true });
+// Matches Harness skill.isSkillName; keep the public filename sanitizer unchanged.
+const DSH_SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isWithin(root, path) {
+    const child = relative(root, path);
+    return child !== '' && child !== '..' && !child.startsWith('..' + sep) && !isAbsolute(child);
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Anchor every move to the resolved target root, rejecting symlinks and changed parents. */
+class InstallRoot {
+    path;
+    constructor(targetDir) {
+        if (targetDir.trim() === '')
+            throw new Error('目标技能目录不能为空');
+        const requested = resolve(targetDir);
+        if (dirname(requested) === requested)
+            throw new Error('不能把文件系统根目录作为技能目录');
+        const existing = fs.lstatSync(requested, { throwIfNoEntry: false });
+        if (existing?.isSymbolicLink())
+            throw new Error('目标技能根目录不能是符号链接或目录联接');
+        // Resolve absent target roots through their existing ancestor without creating
+        // anything yet: overlap with the source must fail before filesystem writes.
+        let ancestor = requested;
+        while (fs.lstatSync(ancestor, { throwIfNoEntry: false }) === undefined)
+            ancestor = dirname(ancestor);
+        this.path = resolve(fs.realpathSync(ancestor), relative(ancestor, requested));
+    }
+    check(path) {
+        const absolute = resolve(path);
+        if (!isWithin(this.path, absolute))
+            throw new Error('安装路径越出目标技能根目录：' + absolute);
+        const root = fs.lstatSync(this.path);
+        if (!root.isDirectory() || root.isSymbolicLink() || fs.realpathSync(this.path) !== this.path) {
+            throw new Error('目标技能根目录在安装期间发生变化');
+        }
+        const parent = fs.realpathSync(dirname(absolute));
+        if (parent !== this.path && !isWithin(this.path, parent))
+            throw new Error('安装路径的父目录越界：' + absolute);
+        if (parent !== dirname(absolute))
+            throw new Error('安装路径的父目录包含符号链接或目录联接：' + absolute);
+        const entry = fs.lstatSync(absolute, { throwIfNoEntry: false });
+        if (entry?.isSymbolicLink())
+            throw new Error('安装路径不能是符号链接或目录联接：' + absolute);
+        if (entry !== undefined && !isWithin(this.path, fs.realpathSync(absolute))) {
+            throw new Error('安装路径解析后越界：' + absolute);
+        }
+        return absolute;
+    }
+    move(source, target) {
+        const from = this.check(source);
+        const to = this.check(target);
+        if (!fs.lstatSync(from).isDirectory())
+            throw new Error('只能切换技能目录：' + from);
+        if (fs.lstatSync(to, { throwIfNoEntry: false }) !== undefined)
+            throw new Error('切换目标已存在，保留现场：' + to);
+        fs.renameSync(from, to);
+    }
+}
+/** Copy only regular files/directories; the destination is a new private staging tree. */
+function copyTree(source, target, sourceRoot, root) {
+    if (source !== sourceRoot && !isWithin(sourceRoot, fs.realpathSync(source)))
+        throw new Error('技能源目录越界');
+    if (fs.lstatSync(source).isSymbolicLink())
+        throw new Error('技能源目录不能是符号链接');
+    fs.mkdirSync(root.check(target));
     let count = 0;
-    for (const entry of readdirSync(source, { withFileTypes: true })) {
-        if (entry.isSymbolicLink())
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+        const from = join(source, entry.name);
+        const to = root.check(join(target, entry.name));
+        const stat = fs.lstatSync(from);
+        if (stat.isSymbolicLink())
             continue;
-        if (entry.isDirectory() && EXCLUDED_DIRS.has(entry.name))
+        if (stat.isDirectory() && EXCLUDED_DIRS.has(entry.name))
             continue;
-        const from = join(source, entry.name);
-        const to = join(target, entry.name);
-        if (entry.isDirectory()) {
-            count += copyTree(from, to);
-        }
-        else {
-            writeFileSync(to, readFileSync(from));
+        if (!isWithin(sourceRoot, fs.realpathSync(from)))
+            throw new Error('技能源文件解析后越界：' + from);
+        if (stat.isDirectory())
+            count += copyTree(from, to, sourceRoot, root);
+        else if (stat.isFile()) {
+            fs.copyFileSync(from, to, fs.constants.COPYFILE_EXCL);
             count += 1;
         }
+        else
+            throw new Error('技能目录含非普通文件：' + from);
     }
     return count;
 }
 /**
- * 移植单个技能到目标目录。
+ * Port one skill without deleting its previous installation. Each rename is a
+ * filesystem operation; the complete replacement is not atomic on Windows.
  */
 export function portSkill(skill, plugin, targetDir, overwrite) {
     const safeName = sanitizeSkillName(skill.skillName !== '' ? skill.skillName : skill.skillDirName);
-    if (safeName === null) {
+    if (safeName === null || safeName.endsWith('.') || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(safeName)) {
         return { skill: skill.skillDirName, plugin: plugin.name, status: 'failed', reason: '技能名清洗后为空或不合法，已跳过（可能是纯中文或含危险字符的名称）', files: 0 };
     }
-    const target = join(targetDir, safeName);
-    if (existsSync(target) && !overwrite) {
-        return { skill: safeName, plugin: plugin.name, status: 'skipped', reason: '目标技能已存在（overwrite=false），跳过以免覆盖', files: 0 };
-    }
+    let root;
+    let target = '';
+    let transaction = '';
+    let incoming = '';
+    let previous = '';
+    let backedUp = false;
+    let installed = false;
+    const record = (phase, error) => {
+        if (root === undefined || transaction === '')
+            return;
+        const file = root.check(join(transaction, 'recovery.json'));
+        fs.writeFileSync(file, JSON.stringify({ version: 1, skill: safeName, target, incoming, previous, phase, ...(error === undefined ? {} : { error }) }, null, 2) + '\n', 'utf8');
+    };
     try {
-        if (existsSync(target))
-            rmSync(target, { recursive: true, force: true });
-        let files = copyTree(skill.sourceDir, target);
-        // 重写 SKILL.md 的 frontmatter
-        const skillFile = join(target, 'SKILL.md');
-        const original = readFileSync(skillFile, 'utf8');
-        const converted = convertSkillFile(original, { pluginName: plugin.name, homepage: plugin.homepage, license: plugin.license }, safeName);
-        writeFileSync(skillFile, converted, 'utf8');
-        files = Math.max(files, 1);
-        return { skill: safeName, plugin: plugin.name, status: 'ported', reason: '', files };
+        root = new InstallRoot(targetDir);
+        target = join(root.path, safeName);
+        if (fs.lstatSync(root.path, { throwIfNoEntry: false }) !== undefined)
+            root.check(target);
+        const existing = fs.lstatSync(target, { throwIfNoEntry: false });
+        if (existing !== undefined && !overwrite) {
+            return { skill: safeName, plugin: plugin.name, status: 'skipped', reason: '目标技能已存在（overwrite=false），跳过以免覆盖', files: 0 };
+        }
+        if (existing !== undefined && !existing.isDirectory())
+            throw new Error('目标技能不是目录，拒绝覆盖：' + target);
+        const sourceEntry = fs.lstatSync(skill.sourceDir);
+        if (!sourceEntry.isDirectory() || sourceEntry.isSymbolicLink())
+            throw new Error('技能源必须是普通目录');
+        const source = fs.realpathSync(skill.sourceDir);
+        if (source === root.path || isWithin(source, root.path) || source === target || isWithin(target, source)) {
+            throw new Error('技能源与安装目标重叠，拒绝递归复制或移动源目录');
+        }
+        fs.mkdirSync(root.path, { recursive: true });
+        root.check(target);
+        transaction = fs.mkdtempSync(root.check(join(root.path, '.dsh-port-' + safeName + '-')));
+        incoming = root.check(join(transaction, 'incoming'));
+        previous = root.check(join(transaction, 'previous'));
+        record('preparing');
+        const files = copyTree(source, incoming, source, root);
+        const skillFile = root.check(join(incoming, 'SKILL.md'));
+        const converted = convertSkillFile(fs.readFileSync(skillFile, 'utf8'), {
+            pluginName: plugin.name, homepage: plugin.homepage, license: plugin.license,
+        }, safeName);
+        fs.writeFileSync(skillFile, converted, 'utf8');
+        // Validate the bytes that were actually written, before moving the old skill.
+        const parsed = parseSkillFile(fs.readFileSync(skillFile, 'utf8'));
+        if (!parsed.hasFrontmatter || typeof parsed.frontmatter.name !== 'string'
+            || !DSH_SKILL_NAME.test(parsed.frontmatter.name) || parsed.frontmatter.name !== safeName
+            || typeof parsed.frontmatter.description !== 'string' || parsed.frontmatter.description.length === 0) {
+            throw new Error('转换后的 SKILL.md 未通过 DSH 技能名称、目录一致性或非空描述校验');
+        }
+        record('prepared');
+        if (existing !== undefined) {
+            root.move(target, previous);
+            backedUp = true;
+            record('previous-backed-up');
+        }
+        root.move(incoming, target);
+        installed = true;
+        let reason = '';
+        try {
+            record('installed');
+        }
+        catch (error) {
+            reason = '技能已安装，但恢复记录更新失败：' + errorText(error) + '；恢复目录：' + transaction;
+        }
+        return { skill: safeName, plugin: plugin.name, status: 'ported', reason, files: Math.max(files, 1) };
     }
     catch (error) {
-        return { skill: safeName, plugin: plugin.name, status: 'failed', reason: error instanceof Error ? error.message : String(error), files: 0 };
+        let reason = errorText(error);
+        let phase = 'failed-before-switch';
+        if (backedUp && !installed) {
+            try {
+                root.move(previous, target);
+                phase = 'rolled-back';
+                reason += '；已恢复原技能';
+            }
+            catch (rollbackError) {
+                phase = 'rollback-failed';
+                reason += '；自动恢复失败：' + errorText(rollbackError) + '；原技能备份：' + previous;
+            }
+        }
+        if (transaction !== '') {
+            try {
+                record(phase, reason);
+            }
+            catch (recordError) {
+                reason += '；恢复记录写入失败：' + errorText(recordError);
+            }
+            reason += '；恢复资料保留在：' + transaction;
+        }
+        return { skill: safeName, plugin: plugin.name, status: 'failed', reason, files: 0 };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-codex-port",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "DSH 技能移植工具插件：把 ~/.codex 里的 Codex 官方插件（170+ 个）一键移植为 DSH 技能（codex_list / codex_port / codex_status），frontmatter 自动转换、名称清洗、幂等跳过。",
   "type": "module",
   "main": "lib/index.js",