@cdo-ai/cli 0.1.0

package/lib/skills.mjs

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { extractSkillZip } from "./zip.mjs";
+
+const SKILL_NAME = "cdo-sys-local";
+const HOST_ROOTS = Object.freeze({ codex: [".codex", "skills"], claude: [".claude", "skills"] });
+const MAX_ARCHIVE_BYTES = 20 * 1024 * 1024;
+const MANAGED_METADATA_FILE = ".cdo-managed.json";
+
+export function targetForAgent(agent, environment = process.env) {
+  if (!(agent in HOST_ROOTS)) throw new Error("--agent 必须是 codex 或 claude");
+  const home = environment.CDO_TEST_HOME || homedir();
+  return join(home, ...HOST_ROOTS[agent], SKILL_NAME);
+}
+
+async function installedContentSha256(target) {
+  const files = [];
+  async function collect(directory, prefix = "") {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => Buffer.compare(Buffer.from(left.name), Buffer.from(right.name)));
+    for (const entry of entries) {
+      if (!prefix && entry.name === MANAGED_METADATA_FILE) continue;
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const absolute = join(directory, entry.name);
+      if (entry.isDirectory()) await collect(absolute, relative);
+      else if (entry.isFile()) files.push({ relative, absolute });
+      else throw new Error(`系统 Skill 安装包含不受支持的文件类型：${relative}`);
+    }
+  }
+  await collect(target);
+  const digest = createHash("sha256");
+  for (const file of files) {
+    const content = await readFile(file.absolute);
+    digest.update(`${Buffer.byteLength(file.relative)}:`);
+    digest.update(file.relative);
+    digest.update(`:${content.byteLength}:`);
+    digest.update(content);
+  }
+  return digest.digest("hex");
+}
+
+async function inspectInstalledIntegrity(target, current) {
+  try {
+    const entrypoint = await lstat(join(target, "SKILL.md"));
+    if (!entrypoint.isFile()) return { status: "missing_entrypoint" };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { status: "missing_entrypoint" };
+    throw error;
+  }
+  if (!/^[a-f0-9]{64}$/i.test(current?.content_sha256 || "")) return { status: "unrecorded" };
+  try {
+    const actual = await installedContentSha256(target);
+    return actual === current.content_sha256.toLowerCase()
+      ? { status: "verified", actual }
+      : { status: "mismatch", actual };
+  } catch {
+    return { status: "mismatch" };
+  }
+}
+
+async function assertInstalledIntegrity(target, current) {
+  const integrity = await inspectInstalledIntegrity(target, current);
+  if (integrity.status === "missing_entrypoint") {
+    throw new Error(`系统 Skill 安装已损坏，请人工卸载后重装：${target}`);
+  }
+  if (integrity.status === "unrecorded") {
+    throw new Error(`系统 Skill 安装完整性记录缺失，请人工卸载后重装：${target}`);
+  }
+  if (integrity.status !== "verified") {
+    throw new Error(`系统 Skill 本地内容已改动，请人工卸载后重装：${target}`);
+  }
+}
+
+function sourceBinding(current, requestedEnvironment, requestedApiBaseUrl) {
+  return {
+    sourceEnvironment: requestedEnvironment || current?.source_environment || current?.environment || "prod",
+    sourceApiBaseUrl: requestedApiBaseUrl || current?.source_api_base_url || current?.api_base_url || null,
+  };
+}
+
+export async function inspectSystemSkill({
+  agent,
+  sourceEnvironment = null,
+  sourceApiBaseUrl = null,
+  environmentName = null,
+  apiBaseUrl = null,
+  environment = process.env,
+  fetchImplementation = fetch,
+}) {
+  const target = targetForAgent(agent, environment);
+  const current = await managedMetadata(target);
+  const source = sourceBinding(current, sourceEnvironment || environmentName, sourceApiBaseUrl || apiBaseUrl);
+  let latest = null;
+  let latestError = null;
+  try {
+    if (!source.sourceApiBaseUrl) throw new Error("系统 Skill 发布来源地址不可用");
+    const response = await fetchImplementation(new URL(`/public/skills/${SKILL_NAME}/latest.json`, source.sourceApiBaseUrl), {
+      headers: { Accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(10_000),
+    });
+    const body = await response.json().catch(() => null);
+    if (response.ok && body?.data?.name === SKILL_NAME) latest = body.data;
+    else latestError = body?.error?.message || `读取系统 Skill 元数据失败 (${response.status})`;
+  } catch (error) { latestError = error?.code || error?.name || "request_failed"; }
+  if (!current) return {
+    status: "not_installed", installed_version: null, latest_version: latest?.version || null,
+    latest_checked: Boolean(latest), latest_error: latestError, target,
+    source_environment: source.sourceEnvironment, source_api_base_url: source.sourceApiBaseUrl,
+  };
+  const integrity = await inspectInstalledIntegrity(target, current);
+  return {
+    status: current.agent !== agent ? "wrong_host_binding"
+      : integrity.status === "missing_entrypoint" ? "damaged"
+        : integrity.status === "mismatch" ? "locally_modified"
+          : integrity.status === "unrecorded" ? "integrity_unverified"
+      : !latest ? "installed_unverified"
+        : current.sha256 !== latest.sha256 ? "update_available" : "installed_current",
+    integrity_status: integrity.status,
+    installed_version: current.version || null,
+    latest_version: latest?.version || null,
+    latest_checked: Boolean(latest),
+    latest_error: latestError,
+    target,
+    source_environment: source.sourceEnvironment,
+    source_api_base_url: source.sourceApiBaseUrl,
+  };
+}
+
+async function pathExists(path) {
+  try { await stat(path); return true; } catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+}
+
+async function managedMetadata(target) {
+  try { return JSON.parse(await readFile(join(target, MANAGED_METADATA_FILE), "utf8")); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw new Error(`系统 Skill 安装记录损坏：${error.message}`); }
+}
+
+async function writeManagedMetadataAtomic(target, value) {
+  const path = join(target, MANAGED_METADATA_FILE);
+  const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  try { await rename(temporary, path); }
+  catch (error) { await rm(temporary, { force: true }); throw error; }
+}
+
+async function readBoundedResponse(response, maxBytes) {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    throw new Error("系统 Skill 下载包大小超限");
+  }
+  if (!response.body) return Buffer.alloc(0);
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) {
+        await reader.cancel("archive size limit exceeded");
+        throw new Error("系统 Skill 下载包大小超限");
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks, size);
+}
+
+async function fetchRelease(apiBaseUrl, fetchImplementation) {
+  const response = await fetchImplementation(new URL(`/public/skills/${SKILL_NAME}/latest.json`, apiBaseUrl), {
+    headers: { Accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(20_000),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body?.data) throw new Error(body?.error?.message || `读取系统 Skill 元数据失败 (${response.status})`);
+  const metadata = body.data;
+  if (metadata.name !== SKILL_NAME || !metadata.version || !/^[a-f0-9]{64}$/i.test(metadata.sha256 || "")) {
+    throw new Error("系统 Skill 元数据无效");
+  }
+  const download = new URL(metadata.download_url);
+  if ((download.protocol !== "https:" && download.protocol !== "http:") || download.username || download.password) {
+    throw new Error("系统 Skill 下载 URL 无效");
+  }
+  if (download.origin !== new URL(apiBaseUrl).origin) throw new Error("系统 Skill 下载 URL 必须与当前 CDO 环境同源");
+  const archiveResponse = await fetchImplementation(download, { redirect: "error", signal: AbortSignal.timeout(30_000) });
+  if (!archiveResponse.ok) throw new Error(`下载系统 Skill 失败 (${archiveResponse.status})`);
+  const archive = await readBoundedResponse(archiveResponse, MAX_ARCHIVE_BYTES);
+  const sha256 = createHash("sha256").update(archive).digest("hex");
+  if (sha256 !== metadata.sha256.toLowerCase()) throw new Error("系统 Skill 下载摘要与发布元数据不符");
+  return { metadata, archive };
+}
+
+export async function installOrUpdateSkill({
+  action,
+  agent,
+  sourceEnvironment = null,
+  sourceApiBaseUrl = null,
+  environmentName = null,
+  apiBaseUrl = null,
+  environment = process.env,
+  fetchImplementation = fetch,
+}) {
+  if (!['install', 'update'].includes(action)) throw new Error("系统 Skill 操作无效");
+  const target = targetForAgent(agent, environment);
+  const existing = await pathExists(target);
+  const current = existing ? await managedMetadata(target) : null;
+  if (existing && !current) throw new Error(`目标已存在且不由 CDO CLI 管理，请人工卸载后重装：${target}`);
+  if (action === "install" && existing) throw new Error(`系统 Skill 已安装，请使用 update：${target}`);
+  if (action === "update" && !existing) throw new Error(`系统 Skill 尚未安装，请使用 install：${target}`);
+  if (current && current.agent !== agent) throw new Error("现有系统 Skill 属于其他宿主，请人工卸载后重装");
+  if (current) await assertInstalledIntegrity(target, current);
+  const source = sourceBinding(current, sourceEnvironment || environmentName, sourceApiBaseUrl || apiBaseUrl);
+  if (!source.sourceApiBaseUrl) throw new Error("系统 Skill 发布来源地址不可用；初装请显式提供 --source-env");
+
+  let release;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try { release = await fetchRelease(source.sourceApiBaseUrl, fetchImplementation); break; }
+    catch (error) {
+      if (attempt === 1 || !String(error.message).includes("摘要")) throw error;
+    }
+  }
+  const { metadata, archive } = release;
+  if (current) await assertInstalledIntegrity(target, current);
+  if (current?.sha256 === metadata.sha256 && current?.source_checksum === metadata.source_checksum) {
+    if (current.schema_version !== 2 || current.source_environment !== source.sourceEnvironment
+        || current.source_api_base_url !== source.sourceApiBaseUrl || "environment" in current || "api_base_url" in current) {
+      await writeManagedMetadataAtomic(target, {
+        ...current,
+        schema_version: 2,
+        source_environment: source.sourceEnvironment,
+        source_api_base_url: source.sourceApiBaseUrl,
+        environment: undefined,
+        api_base_url: undefined,
+      });
+    }
+    return { status: "unchanged", target, version: current.version, source_checksum: current.source_checksum };
+  }
+
+  await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const temporaryRoot = await mkdtemp(join(dirname(target), ".cdo-skill-stage-"));
+  const staged = join(temporaryRoot, SKILL_NAME);
+  const backup = `${target}.backup-${process.pid}-${Date.now()}`;
+  try {
+    await extractSkillZip(archive, staged, SKILL_NAME);
+    const contentSha256 = await installedContentSha256(staged);
+    await writeFile(join(staged, MANAGED_METADATA_FILE), `${JSON.stringify({
+      schema_version: 2, name: SKILL_NAME, version: metadata.version,
+      sha256: metadata.sha256, source_checksum: metadata.source_checksum || null,
+      content_sha256: contentSha256,
+      agent, source_environment: source.sourceEnvironment, source_api_base_url: source.sourceApiBaseUrl,
+      installed_at: new Date().toISOString(),
+    }, null, 2)}\n`, { mode: 0o600 });
+    if (current) await assertInstalledIntegrity(target, current);
+    if (existing) await rename(target, backup);
+    try { await rename(staged, target); }
+    catch (error) { if (existing) await rename(backup, target); throw error; }
+    if (existing) await rm(backup, { recursive: true, force: true });
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+  return {
+    status: existing ? "updated" : "installed", target, version: metadata.version,
+    source_checksum: metadata.source_checksum || null,
+    source_environment: source.sourceEnvironment,
+  };
+}

package/lib/version.mjs

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+export const VERSION = require("../package.json").version;

package/lib/zip.mjs

@@ -0,0 +1,134 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+
+function containsRange(start, length, limit) {
+  return Number.isSafeInteger(start) && Number.isSafeInteger(length)
+    && start >= 0 && length >= 0 && start <= limit && length <= limit - start;
+}
+
+function invalidArchive(message = "系统 Skill 包目录超限或损坏") {
+  throw new Error(message);
+}
+
+export function readZipEntries(buffer, { maxEntries = 500, maxBytes = 50 * 1024 * 1024 } = {}) {
+  const bytes = Buffer.from(buffer);
+  let eocd = -1;
+  for (let index = bytes.length - 22; index >= Math.max(0, bytes.length - 65557); index -= 1) {
+    if (bytes.readUInt32LE(index) === EOCD
+      && index + 22 + bytes.readUInt16LE(index + 20) === bytes.length) {
+      eocd = index;
+      break;
+    }
+  }
+  if (eocd < 0) throw new Error("系统 Skill 包不是有效 ZIP");
+  const diskNumber = bytes.readUInt16LE(eocd + 4);
+  const centralDisk = bytes.readUInt16LE(eocd + 6);
+  const entriesOnDisk = bytes.readUInt16LE(eocd + 8);
+  const entryCount = bytes.readUInt16LE(eocd + 10);
+  const centralSize = bytes.readUInt32LE(eocd + 12);
+  const centralOffset = bytes.readUInt32LE(eocd + 16);
+  if (diskNumber !== 0 || centralDisk !== 0 || entriesOnDisk !== entryCount
+    || entryCount === 0xffff || centralSize === 0xffffffff || centralOffset === 0xffffffff
+    || entryCount > maxEntries || !containsRange(centralOffset, centralSize, eocd)
+    || centralOffset + centralSize !== eocd) invalidArchive();
+  const entries = [];
+  const seen = new Set();
+  let totalBytes = 0;
+  let offset = centralOffset;
+  const centralEnd = centralOffset + centralSize;
+  for (let index = 0; index < entryCount; index += 1) {
+    if (!containsRange(offset, 46, centralEnd)) invalidArchive("系统 Skill 包中央目录损坏");
+    if (bytes.readUInt32LE(offset) !== CENTRAL) throw new Error("系统 Skill 包中央目录损坏");
+    const flags = bytes.readUInt16LE(offset + 8);
+    const method = bytes.readUInt16LE(offset + 10);
+    const crc32 = bytes.readUInt32LE(offset + 16);
+    const compressedSize = bytes.readUInt32LE(offset + 20);
+    const uncompressedSize = bytes.readUInt32LE(offset + 24);
+    const nameLength = bytes.readUInt16LE(offset + 28);
+    const extraLength = bytes.readUInt16LE(offset + 30);
+    const commentLength = bytes.readUInt16LE(offset + 32);
+    const externalAttributes = bytes.readUInt32LE(offset + 38);
+    const localOffset = bytes.readUInt32LE(offset + 42);
+    const centralEntryLength = 46 + nameLength + extraLength + commentLength;
+    if (!containsRange(offset, centralEntryLength, centralEnd)) invalidArchive("系统 Skill 包中央目录损坏");
+    const centralName = bytes.subarray(offset + 46, offset + 46 + nameLength);
+    const name = centralName.toString("utf8").replaceAll("\\", "/");
+    offset += centralEntryLength;
+    if ((flags & 0x0009) !== 0 || ![0, 8].includes(method)) throw new Error(`系统 Skill 包含不支持的 ZIP 条目：${name}`);
+    if (!name || name.startsWith("/") || name.includes("\0") || name.split("/").some((part) => part === "..")) {
+      throw new Error(`系统 Skill 包路径越界：${name}`);
+    }
+    const normalized = name.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (!normalized || seen.has(normalized)) throw new Error(`系统 Skill 包路径重复：${name}`);
+    seen.add(normalized);
+    const unixMode = externalAttributes >>> 16;
+    if ((unixMode & 0o170000) === 0o120000) throw new Error(`系统 Skill 包不得包含符号链接：${name}`);
+    totalBytes += uncompressedSize;
+    if (totalBytes > maxBytes) throw new Error("系统 Skill 包解压后大小超限");
+    if (!containsRange(localOffset, 30, centralOffset)) throw new Error(`系统 Skill 包本地目录损坏：${name}`);
+    if (bytes.readUInt32LE(localOffset) !== LOCAL) throw new Error(`系统 Skill 包本地目录损坏：${name}`);
+    const localFlags = bytes.readUInt16LE(localOffset + 6);
+    const localMethod = bytes.readUInt16LE(localOffset + 8);
+    const localCrc32 = bytes.readUInt32LE(localOffset + 14);
+    const localCompressedSize = bytes.readUInt32LE(localOffset + 18);
+    const localUncompressedSize = bytes.readUInt32LE(localOffset + 22);
+    const localNameLength = bytes.readUInt16LE(localOffset + 26);
+    const localExtraLength = bytes.readUInt16LE(localOffset + 28);
+    const dataOffset = localOffset + 30 + localNameLength + localExtraLength;
+    if (!containsRange(localOffset, 30 + localNameLength + localExtraLength, centralOffset)
+      || !containsRange(dataOffset, compressedSize, centralOffset)) {
+      throw new Error(`系统 Skill 包条目数据越界：${name}`);
+    }
+    const localName = bytes.subarray(localOffset + 30, localOffset + 30 + localNameLength);
+    if (!localName.equals(centralName) || localFlags !== flags || localMethod !== method
+      || localCrc32 !== crc32 || localCompressedSize !== compressedSize
+      || localUncompressedSize !== uncompressedSize) {
+      throw new Error(`系统 Skill 包本地目录与中央目录不一致：${name}`);
+    }
+    const compressed = bytes.subarray(dataOffset, dataOffset + compressedSize);
+    let data;
+    try {
+      data = method === 0
+        ? Buffer.from(compressed)
+        : inflateRawSync(compressed, { maxOutputLength: Math.max(1, uncompressedSize + 1) });
+    } catch {
+      throw new Error(`系统 Skill 包条目压缩数据损坏：${name}`);
+    }
+    if (data.length !== uncompressedSize) throw new Error(`系统 Skill 包条目大小不符：${name}`);
+    entries.push({ name: normalized, directory: name.endsWith("/"), data });
+  }
+  if (offset !== centralEnd) invalidArchive("系统 Skill 包中央目录损坏");
+  return entries;
+}
+
+export async function extractSkillZip(buffer, targetDirectory, skillName) {
+  const entries = readZipEntries(buffer);
+  const prefix = `${skillName}/`;
+  const rootLayout = entries.some((entry) => entry.name === "SKILL.md" && !entry.directory);
+  const prefixedLayout = entries.some((entry) => entry.name === `${skillName}/SKILL.md` && !entry.directory);
+  if (rootLayout === prefixedLayout) throw new Error("系统 Skill 包必须且只能包含一个根 SKILL.md");
+  const selected = rootLayout ? entries : entries.filter((entry) => entry.name === skillName || entry.name.startsWith(prefix));
+  if (!rootLayout) {
+    const unexpected = entries.find((entry) => entry.name !== skillName && !entry.name.startsWith(prefix));
+    if (unexpected) throw new Error(`系统 Skill 包含目标目录外条目：${unexpected.name}`);
+    const rootEntry = selected.find((entry) => entry.name === skillName);
+    if (rootEntry && !rootEntry.directory) throw new Error(`系统 Skill 包根目录不是目录：${skillName}`);
+  }
+  for (const entry of selected) {
+    const relative = rootLayout ? entry.name : (entry.name === skillName ? "" : entry.name.slice(prefix.length));
+    if (!relative) continue;
+    const output = resolve(targetDirectory, relative);
+    const root = resolve(targetDirectory);
+    if (output !== root && !output.startsWith(`${root}${sep}`)) throw new Error(`系统 Skill 包路径越界：${entry.name}`);
+    if (entry.directory) await mkdir(output, { recursive: true, mode: 0o700 });
+    else {
+      await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+      await writeFile(output, entry.data, { mode: 0o600 });
+    }
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@cdo-ai/cli",
+  "version": "0.1.0",
+  "description": "CDO local command line for user Key, REST, Git and system Skill setup",
+  "type": "module",
+  "bin": {
+    "cdo": "bin/cdo.mjs"
+  },
+  "exports": {
+    "./context": "./lib/config.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "dependencies": {
+    "yaml": "2.9.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,30 @@
+import { readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+
+export async function removeBlockedPowerShellShim({
+  platform = process.platform,
+  prefix = process.env.npm_config_prefix,
+} = {}) {
+  if (platform !== "win32" || !prefix) return false;
+  const shim = join(prefix, "cdo.ps1");
+  let contents;
+  try {
+    contents = await readFile(shim, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+  const generatedForThisPackage = contents.includes("@cdo-ai/cli")
+    && contents.includes("cdo.mjs");
+  if (!generatedForThisPackage) return false;
+  await unlink(shim);
+  process.stdout.write("cdo: removed the generated PowerShell shim; bare cdo will use cdo.cmd.\n");
+  return true;
+}
+
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await removeBlockedPowerShellShim();
+}