nvwa-skill-cli 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# nvwa-skill-cli
+
+一个可发布到 npm 的最小 CLI。既支持把 zip 解压到指定目录，也支持从 8188 下载后委托 `skills` 做真正的 agent 安装。
+
+## 功能
+
+- 支持 `install <zip-url-or-file>`
+- 支持 `install-skillhub <skillId> [version] --base-url <8188>`
+- 自动下载 zip
+- 自动解压
+- 自动查找 `SKILL.md`
+- 默认优先使用 `SKILL.md` 中的 `name` 作为安装目录名
+- `install-skillhub` 会调用 `skills add`，把 skill 真正安装到 Codex/其他 agent 的 skills 目录
+
+## 本地调试
+
+在当前目录执行：
+
+```bash
+npm install
+node bin/cli.js --help
+node bin/cli.js install ./demo-skill.zip --target ./skills
+node bin/cli.js install-skillhub 2062784556544692224 --base-url http://localhost:8188 -g
+node bin/cli.js install-skillhub 2062784556544692224 1.0.0 --base-url http://localhost:8188 --agent codex -y
+```
+
+也可以用 `npx` 调试本地包：
+
+```bash
+npx . --help
+npx . install ./demo-skill.zip --target ./skills
+npx . install-skillhub 2062784556544692224 --base-url http://localhost:8188 -g
+npx . install-skillhub 2062784556544692224 1.0.0 --base-url http://localhost:8188 --agent codex -y
+```
+
+## 命令
+
+```bash
+npx nvwa-skill-cli install <zip-url-or-file> [options]
+npx nvwa-skill-cli install-skillhub <skillId> [version] [options]
+```
+
+### 参数
+
+- `install` 命令参数
+- `--target <dir>`：安装根目录，默认 `./installed-skills`
+- `--name <dirName>`：覆盖安装目录名
+- `--force`：目标目录已存在时覆盖
+- `install-skillhub` 命令参数
+- `--base-url <url>`：`install-skillhub` 使用的 8188 地址，默认 `http://localhost:8188`
+- `--agent <agent>`：要安装到的 agent，默认 `codex`
+- `-g, --global`：安装到全局目录；对于 Codex 即 `~/.codex/skills`
+- `--copy`：调用 `skills add` 时使用复制模式，不走 symlink
+- `-y, --yes`：跳过 `skills` 的交互确认
+- `version`：可选；不传时默认下载技能当前版本
+
+### 示例
+
+```bash
+npx nvwa-skill-cli install https://example.com/demo-skill.zip
+npx nvwa-skill-cli install ./demo-skill.zip --target ./skills
+npx nvwa-skill-cli install https://example.com/demo-skill.zip --name self-improvement
+npx nvwa-skill-cli install-skillhub 2062784556544692224 --base-url http://localhost:8188 -g
+npx nvwa-skill-cli install-skillhub 2062784556544692224 1.0.0 --base-url http://localhost:8188 --agent codex -y
+
+## 安装结果
+
+- `install`：只是解压到指定目录，方便检查 zip 内容
+- `install-skillhub`：下载后调用 `skills add <临时目录>`，会真正安装到 agent 的 skills 目录
+- 对 Codex 而言：
+- 项目级安装默认落到 `./.agents/skills`
+- 全局安装 `-g` 落到 `~/.codex/skills`
+```
+
+## 发布到 npm
+
+1. 修改 `package.json` 中的 `name`，确认 npm 上未被占用
+2. 按需要调整 `version`
+3. 登录 npm：
+
+```bash
+npm login
+```
+
+4. 发布：
+
+```bash
+npm publish
+```
+
+如果后续需要 scoped package，可以改成：
+
+```json
+{
+  "name": "@your-scope/nvwa-skill-cli"
+}
+```
+
+然后发布：
+
+```bash
+npm publish --access public
+```

package/bin/cli.js

@@ -0,0 +1,531 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const fsp = require("fs/promises");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+const { pipeline } = require("stream/promises");
+const AdmZip = require("adm-zip");
+
+const HELP_TEXT = `
+Usage:
+  nvwa-skill install <zip-url-or-file> [options]
+  nvwa-skill install-skillhub <skillId> [version] [options]
+  nvwa-skill help
+
+Commands:
+  install                 Download or read a zip, extract it, verify SKILL.md, and install it
+  install-skillhub        Download a skill package from 8188 anonymous endpoints and install it
+  help                    Show help
+
+Options:
+  --target <dir>          Installation root directory (default: ./installed-skills)
+  --name <dirName>        Override installed directory name
+  --base-url <url>        8188 base URL for install-skillhub (default: http://localhost:8188)
+  --agent <agent>         Target agent for install-skillhub (default: codex)
+  -g, --global            Install to global agent directory
+  --copy                  Copy files instead of symlinking when using skills
+  -y, --yes               Skip skills confirmation prompts
+  --force                 Overwrite existing target directory
+  -h, --help              Show help
+
+Examples:
+  npx nvwa-skill-cli install https://example.com/demo-skill.zip
+  npx nvwa-skill-cli install ./demo-skill.zip --target ./skills
+  npx nvwa-skill-cli install https://example.com/demo-skill.zip --name self-improvement
+  npx nvwa-skill-cli install-skillhub 2062784556544692224 --base-url http://localhost:8188 -g
+  npx nvwa-skill-cli install-skillhub 2062784556544692224 1.0.0 --base-url http://localhost:8188 --agent codex -y
+`.trim();
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "help" || command === "-h" || command === "--help") {
+    console.log(HELP_TEXT);
+    return;
+  }
+
+  if (command !== "install" && command !== "install-skillhub") {
+    fail(`Unknown command: ${command}`);
+  }
+
+  if (command === "install") {
+    const parsed = parseInstallArgs(args.slice(1));
+    if (!parsed.source) {
+      fail("Missing zip URL or local zip path.");
+    }
+    await installFromSource(parsed);
+    return;
+  }
+
+  const skillHubParsed = parseInstallSkillHubArgs(args.slice(1));
+  await installFromSkillHub(skillHubParsed);
+}
+
+async function installFromSource(parsed) {
+  const targetRoot = path.resolve(parsed.target || path.join(process.cwd(), "installed-skills"));
+  const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "nvwa-skill-"));
+
+  try {
+    const zipPath = await resolveZipSource(parsed.source, tempRoot);
+    const extractDir = path.join(tempRoot, "extract");
+    await extractZip(zipPath, extractDir);
+
+    const skillRoots = await findSkillRoots(extractDir);
+    if (skillRoots.length === 0) {
+      fail("No SKILL.md found in extracted package.");
+    }
+    if (skillRoots.length > 1) {
+      fail(`Multiple SKILL.md roots found: ${skillRoots.join(", ")}`);
+    }
+
+    const skillRoot = skillRoots[0];
+    const detectedSkillName = await detectSkillName(skillRoot);
+    const installName = parsed.name || detectedSkillName || path.basename(skillRoot);
+    const installDir = path.join(targetRoot, installName);
+
+    await ensureInstallTarget(installDir, parsed.force);
+    await fsp.mkdir(targetRoot, { recursive: true });
+    await copyDirectory(skillRoot, installDir);
+
+    const result = {
+      source: parsed.source,
+      skillRoot,
+      installDir,
+      installedName: installName
+    };
+
+    console.log("Skill installed successfully.");
+    console.log(JSON.stringify(result, null, 2));
+  } finally {
+    await safeRemove(tempRoot);
+  }
+}
+
+function parseInstallArgs(args) {
+  const result = {
+    source: "",
+    target: "",
+    name: "",
+    force: false
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) {
+      continue;
+    }
+    if (!result.source && !arg.startsWith("-")) {
+      result.source = arg;
+      continue;
+    }
+    if (arg === "--target") {
+      result.target = requireNextValue(args, index, "--target");
+      index += 1;
+      continue;
+    }
+    if (arg === "--name") {
+      result.name = requireNextValue(args, index, "--name");
+      index += 1;
+      continue;
+    }
+    if (arg === "--force") {
+      result.force = true;
+      continue;
+    }
+    if (arg === "-h" || arg === "--help") {
+      console.log(HELP_TEXT);
+      process.exit(0);
+    }
+    fail(`Unknown option: ${arg}`);
+  }
+
+  return result;
+}
+
+function parseInstallSkillHubArgs(args) {
+  const result = {
+    skillId: "",
+    version: "",
+    baseUrl: "http://localhost:8188",
+    agent: "codex",
+    global: false,
+    copy: false,
+    yes: false
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) {
+      continue;
+    }
+    if (!result.skillId && !arg.startsWith("-")) {
+      result.skillId = arg;
+      continue;
+    }
+    if (!result.version && !arg.startsWith("-")) {
+      result.version = arg;
+      continue;
+    }
+    if (arg === "--agent") {
+      result.agent = requireNextValue(args, index, "--agent");
+      index += 1;
+      continue;
+    }
+    if (arg === "--base-url") {
+      result.baseUrl = requireNextValue(args, index, "--base-url");
+      index += 1;
+      continue;
+    }
+    if (arg === "-g" || arg === "--global") {
+      result.global = true;
+      continue;
+    }
+    if (arg === "--copy") {
+      result.copy = true;
+      continue;
+    }
+    if (arg === "-y" || arg === "--yes") {
+      result.yes = true;
+      continue;
+    }
+    if (arg === "-h" || arg === "--help") {
+      console.log(HELP_TEXT);
+      process.exit(0);
+    }
+    fail(`Unknown option: ${arg}`);
+  }
+
+  if (!result.skillId) {
+    fail("Missing skillId for install-skillhub.");
+  }
+  return result;
+}
+
+function requireNextValue(args, index, optionName) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("-")) {
+    fail(`Missing value for ${optionName}`);
+  }
+  return value;
+}
+
+async function resolveZipSource(source, tempRoot) {
+  if (isHttpUrl(source)) {
+    const zipPath = path.join(tempRoot, "download.zip");
+    await downloadFile(source, zipPath, 0);
+    return zipPath;
+  }
+
+  const localPath = path.resolve(source);
+  const stat = await fsp.stat(localPath).catch(() => null);
+  if (!stat || !stat.isFile()) {
+    fail(`Local zip file not found: ${localPath}`);
+  }
+  return localPath;
+}
+
+async function installFromSkillHub(parsed) {
+  const normalizedBaseUrl = trimTrailingSlash(parsed.baseUrl);
+  const basicDetailUrl = `${normalizedBaseUrl}/api/v1/skill/basic?skillId=${encodeURIComponent(parsed.skillId)}`;
+  const downloadUrl = parsed.version
+    ? `${normalizedBaseUrl}/api/v1/skill/version/download?skillId=${encodeURIComponent(parsed.skillId)}&version=${encodeURIComponent(parsed.version)}`
+    : `${normalizedBaseUrl}/api/v1/skill/download?skillId=${encodeURIComponent(parsed.skillId)}`;
+  const basicDetail = await getJson(basicDetailUrl);
+  const detailData = basicDetail && basicDetail.data ? basicDetail.data : null;
+  if (!detailData || !detailData.name) {
+    fail(`Failed to resolve skill basic detail from ${basicDetailUrl}`);
+  }
+
+  const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "nvwa-skillhub-"));
+  try {
+    const zipPath = await resolveZipSource(downloadUrl, tempRoot);
+    const extractDir = path.join(tempRoot, "extract");
+    await extractZip(zipPath, extractDir);
+
+    const skillRoots = await findSkillRoots(extractDir);
+    if (skillRoots.length === 0) {
+      fail("No SKILL.md found in extracted package.");
+    }
+    if (skillRoots.length > 1) {
+      fail(`Multiple SKILL.md roots found: ${skillRoots.join(", ")}`);
+    }
+
+    const skillRoot = skillRoots[0];
+    const detectedSkillName = await detectSkillName(skillRoot);
+    const installName = sanitizeDirectoryName(String(detectedSkillName || detailData.name || path.basename(skillRoot)));
+    const installResult = await runSkillsAdd(skillRoot, {
+      agent: parsed.agent,
+      global: parsed.global,
+      copy: parsed.copy,
+      yes: parsed.yes
+    });
+    const codexSyncDir = await syncCodexGlobalSkillIfNeeded(installName, parsed);
+
+    console.log("Skill installed via skills successfully.");
+    console.log(JSON.stringify({
+      source: downloadUrl,
+      skillId: parsed.skillId,
+      version: parsed.version || String(detailData.version || ""),
+      installedName: installName,
+      agent: parsed.agent,
+      global: parsed.global,
+      mode: parsed.copy ? "copy" : "symlink",
+      skillsCommand: installResult.command,
+      codexInstallDir: codexSyncDir
+    }, null, 2));
+  } finally {
+    await safeRemove(tempRoot);
+  }
+}
+
+async function runSkillsAdd(skillRoot, options) {
+  const skillsPackageJson = require.resolve("skills/package.json");
+  const skillsCliPath = path.join(path.dirname(skillsPackageJson), "bin", "cli.mjs");
+  const commandArgs = [skillsCliPath, "add", skillRoot, "--agent", options.agent];
+  if (options.global) {
+    commandArgs.push("--global");
+  }
+  if (options.copy) {
+    commandArgs.push("--copy");
+  }
+  if (options.yes) {
+    commandArgs.push("--yes");
+  }
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, commandArgs, {
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`skills add exited with code ${code}`));
+    });
+  });
+
+  return {
+    command: [process.execPath, ...commandArgs].join(" ")
+  };
+}
+
+async function syncCodexGlobalSkillIfNeeded(skillName, options) {
+  if (options.agent !== "codex" || !options.global) {
+    return "";
+  }
+
+  const homeDir = os.homedir();
+  const codexHome = process.env.CODEX_HOME && process.env.CODEX_HOME.trim()
+    ? process.env.CODEX_HOME.trim()
+    : path.join(homeDir, ".codex");
+  const canonicalSkillDir = path.join(homeDir, ".agents", "skills", skillName);
+  const codexSkillsDir = path.join(codexHome, "skills");
+  const codexSkillDir = path.join(codexSkillsDir, skillName);
+  const canonicalStat = await fsp.stat(canonicalSkillDir).catch(() => null);
+  if (!canonicalStat || !canonicalStat.isDirectory()) {
+    return "";
+  }
+
+  await fsp.mkdir(codexSkillsDir, { recursive: true });
+  await safeRemove(codexSkillDir);
+  await copyDirectory(canonicalSkillDir, codexSkillDir);
+  return codexSkillDir;
+}
+
+function isHttpUrl(value) {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+
+function trimTrailingSlash(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+async function downloadFile(url, destination, redirectCount) {
+  if (redirectCount > 5) {
+    fail(`Too many redirects while downloading: ${url}`);
+  }
+
+  const client = url.startsWith("https://") ? https : http;
+  const response = await new Promise((resolve, reject) => {
+    client.get(url, (res) => resolve(res)).on("error", reject);
+  });
+
+  if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+    response.resume();
+    const redirectUrl = new URL(response.headers.location, url).toString();
+    await downloadFile(redirectUrl, destination, redirectCount + 1);
+    return;
+  }
+
+  if (response.statusCode !== 200) {
+    response.resume();
+    fail(`Download failed with status ${response.statusCode}: ${url}`);
+  }
+
+  await pipeline(response, fs.createWriteStream(destination));
+}
+
+async function getJson(url) {
+  const body = await getText(url, 0);
+  try {
+    return JSON.parse(body);
+  } catch (error) {
+    fail(`Invalid JSON response from ${url}: ${error.message}`);
+  }
+}
+
+async function getText(url, redirectCount) {
+  if (redirectCount > 5) {
+    fail(`Too many redirects while requesting: ${url}`);
+  }
+  const client = url.startsWith("https://") ? https : http;
+  const response = await new Promise((resolve, reject) => {
+    client.get(url, (res) => resolve(res)).on("error", reject);
+  });
+
+  if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+    const redirectUrl = new URL(response.headers.location, url).toString();
+    response.resume();
+    return getText(redirectUrl, redirectCount + 1);
+  }
+  if (response.statusCode !== 200) {
+    const errorBody = await readResponseBody(response);
+    fail(`Request failed with status ${response.statusCode}: ${url}${errorBody ? `, body=${errorBody}` : ""}`);
+  }
+  return readResponseBody(response);
+}
+
+async function readResponseBody(response) {
+  let content = "";
+  for await (const chunk of response) {
+    content += chunk.toString("utf8");
+  }
+  return content;
+}
+
+async function extractZip(zipPath, extractDir) {
+  await fsp.mkdir(extractDir, { recursive: true });
+  const zip = new AdmZip(zipPath);
+  zip.extractAllTo(extractDir, true);
+}
+
+async function findSkillRoots(rootDir) {
+  const results = [];
+  await walk(rootDir, async (entryPath, dirent) => {
+    if (dirent.isFile() && dirent.name === "SKILL.md") {
+      results.push(path.dirname(entryPath));
+    }
+  });
+  return results;
+}
+
+async function walk(rootDir, visitor) {
+  const entries = await fsp.readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(rootDir, entry.name);
+    await visitor(fullPath, entry);
+    if (entry.isDirectory()) {
+      await walk(fullPath, visitor);
+    }
+  }
+}
+
+async function detectSkillName(skillRoot) {
+  const skillFilePath = path.join(skillRoot, "SKILL.md");
+  const exists = await fsp.stat(skillFilePath).catch(() => null);
+  if (!exists || !exists.isFile()) {
+    return "";
+  }
+  const content = await fsp.readFile(skillFilePath, "utf8");
+  return parseSkillName(content);
+}
+
+function parseSkillName(content) {
+  if (!content || !content.startsWith("---")) {
+    return "";
+  }
+  const lines = content.split(/\r?\n/);
+  let frontMatterEnded = false;
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() === "---") {
+      frontMatterEnded = true;
+      break;
+    }
+    const match = line.match(/^name\s*:\s*(.+)\s*$/);
+    if (match) {
+      return sanitizeDirectoryName(stripWrappingQuotes(match[1].trim()));
+    }
+  }
+  if (!frontMatterEnded) {
+    return "";
+  }
+  return "";
+}
+
+function stripWrappingQuotes(value) {
+  if (!value) {
+    return "";
+  }
+  if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1).trim();
+  }
+  return value;
+}
+
+function sanitizeDirectoryName(value) {
+  if (!value) {
+    return "";
+  }
+  return value
+    .replace(/[<>:"/\\|?*\u0000-\u001F]/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+async function ensureInstallTarget(installDir, force) {
+  const exists = await fsp.stat(installDir).catch(() => null);
+  if (!exists) {
+    return;
+  }
+  if (!force) {
+    fail(`Target directory already exists: ${installDir}. Use --force to overwrite.`);
+  }
+  await safeRemove(installDir);
+}
+
+async function copyDirectory(sourceDir, targetDir) {
+  await fsp.mkdir(targetDir, { recursive: true });
+  const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      await fsp.copyFile(sourcePath, targetPath);
+    }
+  }
+}
+
+async function safeRemove(targetPath) {
+  await fsp.rm(targetPath, { recursive: true, force: true }).catch(() => undefined);
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main().catch((error) => {
+  const message = error && error.message ? error.message : String(error);
+  fail(message);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "nvwa-skill-cli",
+  "version": "0.1.0",
+  "description": "CLI for installing skill packages from zip URLs or local zip files.",
+  "bin": {
+    "nvwa-skill": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "skill",
+    "cli",
+    "zip",
+    "installer"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "skills": "^1.5.10"
+  }
+}