@dmall-inc/skills-cli 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @dmall-inc/skills-cli
+
+基于平台技能引用 URL 安装技能到本地。
+
+## 安装
+
+```bash
+npm i -g @dmall-inc/skills-cli
+```
+
+或临时执行：
+
+```bash
+npx @dmall-inc/skills-cli add https://<host>/skills/@owner/<name> --token <wat_xxx>
+```
+
+## 用法
+
+```bash
+skills-cli add <url> [--token <wat_xxx>] [--target-dir <dir>] [--force] [--version <v>]
+```
+
+- `url` 必须是：`https://<host>/skills/@owner/<name>`
+- token 优先级：`--token` > `DMALL_SKILLS_TOKEN`
+- 未传 `--target-dir` 时，默认安装到：
+  - `$CODEX_SKILLS_DIR/<owner>--<name>`（若设置）
+  - 否则 `~/.codex/skills/<owner>--<name>`
+
+## 安装流程
+
+1. 解析 URL 得到 `owner + name`
+2. 调用 `GET /api/open/skills/resolve`
+3. 调用 `GET /api/open/skills/{id}/download`
+4. 解压并安装到本地目录
+5. 校验目标目录内存在 `SKILL.md`
+
+## 常见问题
+
+- 报错 `Missing token`
+  - 传 `--token` 或设置 `DMALL_SKILLS_TOKEN`
+- 报错 `HTTP 401/403`
+  - token 无效、无权限，或技能对当前 workspace 不可见
+- 报错 `Invalid install URL path`
+  - URL 不是 `/skills/@owner/<name>` 结构
+- 报错 ``unzip` command not found`
+  - 先在本机安装 `unzip`

package/bin/skills-cli.js

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 20_000;
+
+function printHelp() {
+  console.log(`@dmall-inc/skills-cli\n\nUsage:\n  skills-cli add <https://<host>/skills/@owner/name> [--token <wat_xxx>] [--target-dir <dir>] [--force] [--version <v>] [--timeout-ms <ms>] [--verbose]\n\nToken priority:\n  1) --token\n  2) DMALL_SKILLS_TOKEN\n\nTimeout priority:\n  1) --timeout-ms\n  2) DMALL_SKILLS_TIMEOUT_MS\n  3) default 20000ms\n\nExamples:\n  skills-cli add https://example.com/skills/@team/report-generator --token wat_xxx\n  DMALL_SKILLS_TOKEN=wat_xxx skills-cli add https://example.com/skills/@team/report-generator\n  skills-cli add https://example.com/skills/@team/report-generator --verbose --timeout-ms 30000\n`);
+}
+
+function fail(message, code = 1) {
+  console.error(`[skills-cli] ${message}`);
+  process.exit(code);
+}
+
+function parseNonEmptyOptionValue(rest, i, optionName) {
+  const value = rest[i + 1];
+  if (value == null || String(value).trim() === '' || String(value).startsWith('--')) {
+    fail(`Option ${optionName} requires a value.`);
+  }
+  return String(value);
+}
+
+function parsePositiveInteger(raw, optionName) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0 || Math.floor(n) !== n) {
+    fail(`Option ${optionName} must be a positive integer.`);
+  }
+  return n;
+}
+
+function parseArgs(argv) {
+  const [, , command, ...rest] = argv;
+  if (!command || command === '-h' || command === '--help') {
+    return { command: 'help' };
+  }
+  if (command !== 'add') {
+    fail(`Unsupported command: ${command}`);
+  }
+  const options = {
+    token: undefined,
+    targetDir: undefined,
+    force: false,
+    version: undefined,
+    timeoutMs: undefined,
+    verbose: false,
+  };
+  const positional = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const item = rest[i];
+    if (item === '--token') {
+      options.token = parseNonEmptyOptionValue(rest, i, '--token');
+      i += 1;
+      continue;
+    }
+    if (item === '--target-dir') {
+      options.targetDir = parseNonEmptyOptionValue(rest, i, '--target-dir');
+      i += 1;
+      continue;
+    }
+    if (item === '--version') {
+      options.version = parseNonEmptyOptionValue(rest, i, '--version');
+      i += 1;
+      continue;
+    }
+    if (item === '--timeout-ms') {
+      const raw = parseNonEmptyOptionValue(rest, i, '--timeout-ms');
+      options.timeoutMs = parsePositiveInteger(raw, '--timeout-ms');
+      i += 1;
+      continue;
+    }
+    if (item === '--force') {
+      options.force = true;
+      continue;
+    }
+    if (item === '--verbose') {
+      options.verbose = true;
+      continue;
+    }
+    if (item.startsWith('--')) {
+      fail(`Unknown option: ${item}`);
+    }
+    positional.push(item);
+  }
+  if (positional.length !== 1) {
+    fail('`add` requires exactly one URL argument.');
+  }
+  return { command, url: positional[0], options };
+}
+
+function parseInstallUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    fail('Invalid URL. Expected format: https://<host>/skills/@owner/<name>');
+  }
+  if (url.protocol !== 'https:') {
+    fail('Only https:// URLs are supported.');
+  }
+  const match = url.pathname.match(/^\/skills\/@([a-zA-Z0-9._-]+)\/([a-z0-9](?:[a-z0-9-]{1,62}[a-z0-9])?)\/?$/);
+  if (!match) {
+    fail('Invalid install URL path. Expected: /skills/@owner/<name>');
+  }
+  return {
+    hostOrigin: `${url.protocol}//${url.host}`,
+    owner: match[1],
+    name: match[2],
+  };
+}
+
+function resolveToken(optionsToken) {
+  const t = (optionsToken || process.env.DMALL_SKILLS_TOKEN || '').trim();
+  if (!t) {
+    fail('Missing token. Pass --token or set DMALL_SKILLS_TOKEN.');
+  }
+  return t;
+}
+
+function resolveTimeoutMs(optionsTimeoutMs) {
+  if (Number.isFinite(optionsTimeoutMs)) {
+    return optionsTimeoutMs;
+  }
+  const envTimeoutRaw = (process.env.DMALL_SKILLS_TIMEOUT_MS || '').trim();
+  if (!envTimeoutRaw) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  return parsePositiveInteger(envTimeoutRaw, 'DMALL_SKILLS_TIMEOUT_MS');
+}
+
+function debugLog(enabled, message) {
+  if (enabled) {
+    console.log(`[skills-cli][debug] ${message}`);
+  }
+}
+
+function buildHttpFailureMessage(prefix, status, bodyPreview) {
+  const hints = [];
+  if (status === 401 || status === 403) {
+    hints.push('token 无效、过期，或对当前 workspace 无权限');
+  }
+  if (status === 404) {
+    hints.push('owner/name 不存在，或技能对当前 token 不可见');
+  }
+  const hintText = hints.length > 0 ? `；可能原因：${hints.join('；')}` : '';
+  return `${prefix}: HTTP ${status}${hintText}${bodyPreview ? `；response=${bodyPreview}` : ''}`;
+}
+
+function normalizeTextPreview(text, maxLen = 500) {
+  if (!text) return '';
+  const oneLine = String(text).replace(/\s+/g, ' ').trim();
+  if (oneLine.length <= maxLen) return oneLine;
+  return `${oneLine.slice(0, maxLen)}... (truncated, total=${oneLine.length})`;
+}
+
+function extractErrorMessageFromEnvelope(text) {
+  if (!text) return null;
+  try {
+    const json = JSON.parse(text);
+    const msg = typeof json?.message === 'string' ? json.message.trim() : '';
+    const errCode = typeof json?.errorCode === 'string' ? json.errorCode.trim() : '';
+    if (!msg && !errCode) return null;
+    return `${msg || '请求失败'}${errCode ? ` (${errCode})` : ''}`;
+  } catch {
+    return null;
+  }
+}
+
+async function requestWithTimeout(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (error) {
+    if (error && error.name === 'AbortError') {
+      throw new Error(`Request timeout after ${timeoutMs}ms: ${url}`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function requestJson(url, token, timeoutMs, verbose) {
+  debugLog(verbose, `GET ${url}`);
+  const response = await requestWithTimeout(
+    url,
+    {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+      },
+    },
+    timeoutMs
+  );
+  const text = await response.text();
+  if (!response.ok) {
+    const envelopeError = extractErrorMessageFromEnvelope(text);
+    if (envelopeError) {
+      throw new Error(`${envelopeError} (HTTP ${response.status})`);
+    }
+    throw new Error(buildHttpFailureMessage('Request failed', response.status, normalizeTextPreview(text)));
+  }
+
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(`Invalid JSON response: ${normalizeTextPreview(text, 300)}`);
+  }
+
+  const code = Number(json?.code);
+  if (!Number.isFinite(code) || code !== 200) {
+    const msg = typeof json?.message === 'string' ? json.message : 'Request failed';
+    const errCode = json?.errorCode ? ` (${json.errorCode})` : '';
+    throw new Error(`${msg}${errCode}`);
+  }
+  return json.data;
+}
+
+function isLikelyZip(buffer) {
+  return (
+    buffer &&
+    buffer.length >= 4 &&
+    buffer[0] === 0x50 &&
+    buffer[1] === 0x4b &&
+    (buffer[2] === 0x03 || buffer[2] === 0x05 || buffer[2] === 0x07) &&
+    (buffer[3] === 0x04 || buffer[3] === 0x06 || buffer[3] === 0x08)
+  );
+}
+
+async function downloadZip(url, token, timeoutMs, verbose) {
+  debugLog(verbose, `GET ${url}`);
+  const response = await requestWithTimeout(
+    url,
+    {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/zip',
+      },
+    },
+    timeoutMs
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    const envelopeError = extractErrorMessageFromEnvelope(text);
+    if (envelopeError) {
+      throw new Error(`Download failed: ${envelopeError} (HTTP ${response.status})`);
+    }
+    throw new Error(buildHttpFailureMessage('Download failed', response.status, normalizeTextPreview(text)));
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  if (!isLikelyZip(buffer)) {
+    throw new Error('Download failed: response is not a valid zip payload.');
+  }
+  return buffer;
+}
+
+async function unzipToDir(zipPath, destDir) {
+  await fsp.mkdir(destDir, { recursive: true });
+  try {
+    await execFileAsync('unzip', ['-q', zipPath, '-d', destDir]);
+  } catch (error) {
+    if (error && /ENOENT/.test(String(error))) {
+      throw new Error('`unzip` command not found. Please install unzip and retry.');
+    }
+    const stderr = error && error.stderr ? String(error.stderr) : String(error);
+    throw new Error(`Unzip failed: ${normalizeTextPreview(stderr)}`);
+  }
+}
+
+async function findSkillMdFiles(rootDir) {
+  const found = [];
+  async function walk(current) {
+    const entries = await fsp.readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile() && entry.name === 'SKILL.md') {
+        found.push(full);
+      }
+    }
+  }
+  await walk(rootDir);
+  return found;
+}
+
+function chooseSkillRoot(extractDir, skillMdFiles) {
+  if (skillMdFiles.length === 0) {
+    throw new Error('Extracted package does not contain SKILL.md');
+  }
+  const directRootSkillMd = skillMdFiles.find((file) => path.dirname(file) === extractDir);
+  const selected = directRootSkillMd || [...skillMdFiles].sort((a, b) => a.length - b.length)[0];
+  return { root: path.dirname(selected), skillMd: selected };
+}
+
+async function copyDirAtomically(src, dest, force) {
+  const exists = fs.existsSync(dest);
+  if (exists && !force) {
+    throw new Error(`Target already exists: ${dest}. Use --force to overwrite.`);
+  }
+
+  const parentDir = path.dirname(dest);
+  await fsp.mkdir(parentDir, { recursive: true });
+
+  const stagingDir = path.join(parentDir, `.${path.basename(dest)}.tmp-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`);
+  await fsp.cp(src, stagingDir, { recursive: true });
+
+  try {
+    if (exists && force) {
+      await fsp.rm(dest, { recursive: true, force: true });
+    }
+    await fsp.rename(stagingDir, dest);
+  } catch (error) {
+    await fsp.rm(stagingDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function resolveTargetDir(owner, name, explicitDir) {
+  if (explicitDir && explicitDir.trim()) {
+    return path.resolve(explicitDir.trim());
+  }
+  const codexHome = process.env.CODEX_HOME
+    ? path.resolve(process.env.CODEX_HOME)
+    : path.join(os.homedir(), '.codex');
+  const skillsDir = process.env.CODEX_SKILLS_DIR
+    ? path.resolve(process.env.CODEX_SKILLS_DIR)
+    : path.join(codexHome, 'skills');
+  return path.join(skillsDir, `${owner}--${name}`);
+}
+
+async function addCommand(rawUrl, options) {
+  const parsed = parseInstallUrl(rawUrl);
+  const token = resolveToken(options.token);
+  const timeoutMs = resolveTimeoutMs(options.timeoutMs);
+
+  const resolveUrl = new URL('/api/open/skills/resolve', parsed.hostOrigin);
+  resolveUrl.searchParams.set('owner', parsed.owner);
+  resolveUrl.searchParams.set('name', parsed.name);
+
+  console.log(`[skills-cli] Resolving ${parsed.owner}/${parsed.name} ...`);
+  const resolved = await requestJson(resolveUrl.toString(), token, timeoutMs, options.verbose);
+  const skillId = String(resolved?.id || '').trim();
+  if (!skillId) {
+    throw new Error('Resolve response missing skill id');
+  }
+
+  const resolvedOwner = String(resolved?.owner || '').trim();
+  const resolvedName = String(resolved?.name || '').trim();
+  if ((resolvedOwner && resolvedOwner !== parsed.owner) || (resolvedName && resolvedName !== parsed.name)) {
+    debugLog(options.verbose, `Resolve canonical ref: owner=${resolvedOwner || parsed.owner}, name=${resolvedName || parsed.name}`);
+  }
+
+  const downloadUrl = new URL(`/api/open/skills/${encodeURIComponent(skillId)}/download`, parsed.hostOrigin);
+  if (options.version && options.version.trim()) {
+    downloadUrl.searchParams.set('version', options.version.trim());
+  }
+
+  console.log(`[skills-cli] Downloading skill ${skillId} ...`);
+  const zipBuffer = await downloadZip(downloadUrl.toString(), token, timeoutMs, options.verbose);
+
+  const tempDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'skills-cli-'));
+  const zipPath = path.join(tempDir, 'skill.zip');
+  const extractDir = path.join(tempDir, 'extract');
+
+  try {
+    await fsp.writeFile(zipPath, zipBuffer);
+    await unzipToDir(zipPath, extractDir);
+
+    const skillMdFiles = await findSkillMdFiles(extractDir);
+    const selected = chooseSkillRoot(extractDir, skillMdFiles);
+    const targetDir = resolveTargetDir(parsed.owner, parsed.name, options.targetDir);
+
+    console.log(`[skills-cli] Installing to ${targetDir} ...`);
+    await copyDirAtomically(selected.root, targetDir, options.force);
+
+    const installedSkillMd = path.join(targetDir, path.relative(selected.root, selected.skillMd));
+    if (!fs.existsSync(installedSkillMd)) {
+      throw new Error(`Installed package validation failed: SKILL.md not found in ${targetDir}`);
+    }
+
+    console.log('[skills-cli] Install success.');
+    console.log(`[skills-cli] Path: ${targetDir}`);
+    if (resolved?.publishedVersion) {
+      console.log(`[skills-cli] Published version: ${resolved.publishedVersion}`);
+    }
+  } finally {
+    await fsp.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  if (typeof fetch !== 'function') {
+    fail('Global fetch is unavailable. Please use Node.js >= 18.');
+  }
+
+  const parsed = parseArgs(process.argv);
+  if (parsed.command === 'help') {
+    printHelp();
+    return;
+  }
+  if (parsed.command === 'add') {
+    await addCommand(parsed.url, parsed.options);
+    return;
+  }
+  fail(`Unsupported command: ${parsed.command}`);
+}
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@dmall-inc/skills-cli",
+  "version": "0.1.0",
+  "description": "Install Dmall platform skills from @owner/name URL",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "skills-cli": "bin/skills-cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lint": "node --check bin/skills-cli.js",
+    "start": "node bin/skills-cli.js"
+  }
+}