specleaf 1.1.2 → 1.2.0

package/lib/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import $RefParser, { getJsonSchemaRefParserDefaultOptions } from "@apidevtools/json-schema-ref-parser";
 import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
 // src/lib/openapi.ts
 var pointerEscape = (value) => value.replace(/~/g, "~0").replace(/\//g, "~1");
 // build/references.ts
@@ -309,8 +310,132 @@ async function generate(input, destination) {
 		if (temporary) await rm(temporary, { force: true });
 	}
 }
+// build/skills.ts
+var skillAgents = [
+	"codex",
+	"claude",
+	"opencode"
+];
+var skillHelp = `用法：specleaf install skill [选项]
+
+安装随包提供的 specleaf skill，默认面向 Codex、Claude Code 和 OpenCode。
+默认安装到调用目录；--global 安装到用户目录。安装过程无需联网。
+Codex 与 OpenCode 共用 .agents/skills/specleaf，Claude Code 使用 .claude/skills/specleaf。
+
+选项：
+  --agent <名称>     选择 codex、claude、opencode 或 all；可重复或用逗号分隔
+  -g, --global      安装到用户目录，供所有项目使用
+  --force           替换内容不同的 skill 文件，保留其他文件
+  -h, --help        显示帮助
+`;
+function parseSkillArguments(args) {
+	const options = {
+		agents: [],
+		global: false,
+		force: false
+	};
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index];
+		if (argument === "--help" || argument === "-h") return {
+			...options,
+			help: true
+		};
+		if (argument === "--global" || argument === "-g") options.global = true;
+		else if (argument === "--force") options.force = true;
+		else if (argument === "--agent" || argument.startsWith("--agent=")) {
+			const value = argument === "--agent" ? args[++index] : argument.slice(8);
+			if (!value || value.startsWith("-")) throw new Error("--agent 缺少工具名称。");
+			for (const name of value.split(",").map((name) => name.trim())) if (name === "all") options.agents.push(...skillAgents);
+			else if (skillAgents.includes(name)) options.agents.push(name);
+			else throw new Error(`未知工具：${name || "（空）"}。支持 codex、claude、opencode 或 all。`);
+		} else throw new Error(`未知 skill 安装参数：${argument}`);
+	}
+	options.agents = options.agents.length ? [...new Set(options.agents)] : [...skillAgents];
+	return options;
+}
+var skillDirectories = {
+	codex: ".agents",
+	claude: ".claude",
+	opencode: ".agents"
+};
+var statIfPresent = (path) => lstat(path).catch((error) => {
+	if (error.code !== "ENOENT") throw error;
+});
+async function readSkillFiles(directory, prefix = "") {
+	const files = /* @__PURE__ */ new Map();
+	const entries = await readdir(join(directory, prefix), { withFileTypes: true });
+	for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+		const path = join(prefix, entry.name);
+		if (entry.isDirectory()) for (const [name, content] of await readSkillFiles(directory, path)) files.set(name, content);
+		else if (entry.isFile()) files.set(path, await readFile(join(directory, path)));
+		else throw new Error(`skill 资源必须为普通文件或目录：${join(directory, path)}`);
+	}
+	return files;
+}
+async function checkDirectories(base, relative) {
+	let path = base;
+	for (const part of relative.split(sep)) {
+		if (!part || part === ".") continue;
+		path = join(path, part);
+		const existing = await statIfPresent(path);
+		if (existing && (!existing.isDirectory() || existing.isSymbolicLink())) throw new Error(`skill 安装目录不能是符号链接或非目录：${path}`);
+	}
+}
+async function installSkill(options, context) {
+	const files = await readSkillFiles(fileURLToPath(new URL("../skills/specleaf/", import.meta.url)));
+	const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+	files.set("specleaf.json", Buffer.from(`${JSON.stringify({ version }, null, 2)}\n`));
+	const base = resolve(options.global ? context.homeDirectory ?? homedir() : context.cwd);
+	const targets = /* @__PURE__ */ new Map();
+	for (const agent of options.agents) {
+		const relative = join(skillDirectories[agent], "skills", "specleaf");
+		targets.set(relative, [...targets.get(relative) ?? [], agent]);
+	}
+	const plans = [];
+	for (const [relative, agents] of targets) {
+		await checkDirectories(base, relative);
+		const directory = join(base, relative);
+		const changes = [];
+		let hasFiles = false;
+		for (const [name, content] of files) {
+			await checkDirectories(base, join(relative, dirname(name)));
+			const path = join(directory, name);
+			const existing = await statIfPresent(path);
+			if (existing) {
+				if (!existing.isFile() || existing.isSymbolicLink()) throw new Error(`skill 文件不能是符号链接或非普通文件：${path}`);
+				hasFiles = true;
+				if ((await readFile(path)).equals(content)) continue;
+				if (!options.force) throw new Error(`已有 skill 文件内容不同：${path}\n使用 --force 替换 skill 文件；其他文件会保留。`);
+			}
+			changes.push({
+				path,
+				content
+			});
+		}
+		plans.push({
+			result: {
+				agents,
+				directory,
+				status: changes.length ? hasFiles ? "updated" : "installed" : "unchanged"
+			},
+			changes
+		});
+	}
+	for (const { changes } of plans) for (const { path, content } of changes) {
+		await mkdir(dirname(path), { recursive: true });
+		const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+		try {
+			await writeFile(temporary, content, { flag: "wx" });
+			await rename(temporary, path);
+		} finally {
+			await rm(temporary, { force: true });
+		}
+	}
+	return plans.map(({ result }) => result);
+}
 // build/cli.ts
 var help = `用法：specleaf <input> [-o <output.html>]
+      specleaf install skill [--agent <名称>] [--global] [--force]
 
 把本地 OpenAPI 3.0 / 3.1 YAML / JSON 文件或模块目录转为单个离线 HTML。
 目录递归发现 openapi.yaml、openapi.yml、openapi.json，各模块独立浏览。
@@ -320,6 +445,8 @@ var help = `用法：specleaf <input> [-o <output.html>]
   -o, --output <文件>  指定输出文件
   -h, --help           显示帮助
   -v, --version        显示版本
+
+运行 specleaf install skill --help 查看 Codex、Claude Code、OpenCode 的 skill 安装用法。
 `;
 function parseArguments(args) {
 	let input;
@@ -357,15 +484,30 @@ function parseArguments(args) {
 	};
 }
 try {
-	const args = parseArguments(process.argv.slice(2));
-	if (args.help) process.stdout.write(help);
-	else if (args.version) {
-		const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
-		process.stdout.write(`${version}\n`);
+	const argv = process.argv.slice(2);
+	const cwd = fileURLToPath(import.meta.url) === resolve(projectRoot, "build/cli.ts") && process.env.npm_lifecycle_event === "generate" ? process.env.INIT_CWD || process.cwd() : process.cwd();
+	if (argv[0] === "install" && argv[1] === "skill") {
+		const options = parseSkillArguments(argv.slice(2));
+		if (options.help) process.stdout.write(skillHelp);
+		else {
+			const labels = {
+				installed: "已安装",
+				updated: "已更新",
+				unchanged: "已是相同内容，跳过"
+			};
+			for (const result of await installSkill(options, { cwd })) process.stdout.write(`${labels[result.status]} specleaf skill（${result.agents.join("、")}）：${result.directory}\n`);
+			process.stdout.write("可在对应工具的下一轮会话中使用 specleaf skill；若未显示，请重新打开会话。\n");
+		}
 	} else {
-		const cwd = fileURLToPath(import.meta.url) === resolve(projectRoot, "build/cli.ts") && process.env.npm_lifecycle_event === "generate" ? process.env.INIT_CWD || process.cwd() : process.cwd();
-		const output = await generate(contractEntry(cwd, args.input), resolve(cwd, args.output));
-		process.stdout.write(`已生成离线 HTML：${output}\n`);
+		const args = parseArguments(argv);
+		if (args.help) process.stdout.write(help);
+		else if (args.version) {
+			const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+			process.stdout.write(`${version}\n`);
+		} else {
+			const output = await generate(contractEntry(cwd, args.input), resolve(cwd, args.output));
+			process.stdout.write(`已生成离线 HTML：${output}\n`);
+		}
 	}
 } catch (error) {
 	process.stderr.write(`错误：${error.message}\n运行 specleaf --help 查看用法。\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specleaf",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "将本地 OpenAPI 3.0 / 3.1 YAML / JSON 文件或模块目录转为按模块分组、离线阅读的单文件 HTML 文档。",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
   "files": [
     "lib/cli.js",
     "lib/assets/",
+    "skills/specleaf/",
     "README.md",
     "LICENSE"
   ],

package/skills/specleaf/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: specleaf
+description: 将本地 OpenAPI 契约生成为 SpecLeaf 单文件离线 HTML 文档。用于生成、更新、汇总 API 文档，或诊断 SpecLeaf 生成失败。
+---
+
+# SpecLeaf
+
+将现有 OpenAPI 3.0 / 3.1 YAML / JSON 文件或模块目录转换为可离线阅读的 HTML。沿用项目现有契约，生成时保持入口及引用文件只读。
+
+## 选择输入和输出
+
+- 优先使用用户指定路径，其次检查项目已有文档命令和约定，再在相关目录中寻找入口。区分包含 `openapi`、`info`、`paths` 的契约与被引用的模型片段。存在多个无明确关系的候选时，澄清生成范围。
+- 单个契约使用文件输入；汇总多个模块使用其公共目录。目录模式递归识别准确命名的 `openapi.yaml`、`openapi.yml`、`openapi.json`，同一目录只能有一个入口。跳过隐藏目录、`node_modules`、`dist`、`build`、`coverage` 及目录符号链接。
+- 各模块保留独立版本、服务地址、鉴权和引用作用域；无需手动合并契约或重命名同名模型。
+- 输出遵循用户路径或项目约定；没有约定时可用 `./openapi.html`，显式传入 `-o`。已有文件时确认它是本任务要更新的产物，避免覆盖无关文件。
+
+## 调用 CLI
+
+需要 Node.js 22.19.0+。优先复用项目已有文档命令或已安装的 `specleaf`：
+
+```bash
+specleaf "./docs/apis" -o "./docs/api.html"
+```
+
+输入、输出相对调用目录解析；`$ref` 相对包含它的文件解析。不要切换到 skill 目录执行生成。
+
+若只有项目内安装的 CLI，可通过 `npm exec --offline -- specleaf` 调用。若 CLI 不可用，读取本 skill 同目录安装记录 `specleaf.json` 的 `version`，用该版本执行 `npx --yes specleaf@版本 输入 -o 输出`，替换其中的版本和路径。没有安装记录时，先核实可用版本。获取 npm 包可能需要联网，应遵循当前环境的网络权限；包与依赖齐备后，本地生成无需联网。
+
+## 处理失败
+
+- 缺失引用：根据报错的来源文件和 JSON Pointer 检查相对路径、目标文件和目标字段。
+- 重复入口：报告具体目录及候选入口，不擅自删除或重命名契约。
+- 无模块入口：检查范围和入口命名，避免将模型目录作为模块集合。
+- 远程入口、远程 `$ref`、Swagger 2.0 不受支持；说明限制和所需的本地 OpenAPI 3.0 / 3.1 输入。
+- 输出与入口或引用文件冲突时更换输出路径。修复契约内容应属于用户请求的范围，不能为生成成功编造接口、字段或示例。
+
+## 验收与交付
+
+确认命令退出码为零、输出 HTML 存在且非空。需要浏览器验收且环境具备条件时，检查标题、搜索和接口导航；只在实际验证后报告这些结果。
+
+交付 HTML 文件链接、输入范围、使用版本和可复现命令。产物包含脚本、样式和契约，可以单独复制并在浏览器离线打开。页面仅供阅读，不执行接口请求。生成成功表示完成解析与渲染，不代表完整的 OpenAPI / JSON Schema 语义校验。

package/skills/specleaf/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SpecLeaf"
+  short_description: "Generate offline HTML from local OpenAPI contracts"
+  default_prompt: "Use $specleaf to generate an offline HTML document from this project’s OpenAPI contracts."