@netpilot/skills 0.3.2

package/scripts/doctor.mjs

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { validateRepository } from "./validate.mjs";
+
+function commandVersion(command) {
+  const result = spawnSync(`${command} --version`, {
+    encoding: "utf8",
+    shell: true,
+    windowsHide: true,
+    timeout: 10_000,
+  });
+  if (result.error || result.status !== 0) {
+    return { available: false, detail: result.error?.message ?? result.stderr?.trim() ?? "命令不可用" };
+  }
+  return { available: true, detail: (result.stdout || result.stderr).trim().split(/\r?\n/u)[0] };
+}
+
+export function isSupportedNodeMajor(nodeMajor) {
+  return Number.isInteger(nodeMajor) && nodeMajor >= 22;
+}
+
+export async function runDoctor(rootDir) {
+  const checks = [];
+  const nodeMajor = Number.parseInt(process.versions.node.split(".")[0], 10);
+  checks.push({
+    name: "Node.js >= 22",
+    ok: isSupportedNodeMajor(nodeMajor),
+    required: true,
+    detail: process.version,
+  });
+
+  const git = commandVersion("git");
+  checks.push({ name: "Git", ok: git.available, required: true, detail: git.detail });
+
+  const codex = commandVersion("codex");
+  checks.push({ name: "Codex CLI", ok: codex.available, required: false, detail: codex.detail });
+
+  const claude = commandVersion("claude");
+  checks.push({ name: "Claude Code", ok: claude.available, required: false, detail: claude.detail });
+  checks.push({
+    name: "至少一个 AI 宿主",
+    ok: codex.available || claude.available,
+    required: true,
+    detail: codex.available || claude.available ? "可用" : "Codex CLI 与 Claude Code 均不可用",
+  });
+
+  const validation = await validateRepository(rootDir);
+  checks.push({
+    name: "仓库结构",
+    ok: validation.ok,
+    required: true,
+    detail: validation.ok
+      ? `${validation.skillCount} 个 skills，${validation.agentCount} 个 Codex agents`
+      : `${validation.errors.length} 个问题`,
+  });
+
+  return {
+    ok: checks.every((check) => !check.required || check.ok),
+    checks,
+    validation,
+  };
+}
+
+async function main() {
+  const rootDir = fileURLToPath(new URL("..", import.meta.url));
+  const result = await runDoctor(rootDir);
+  for (const check of result.checks) {
+    const status = check.ok ? "OK" : check.required ? "ERROR" : "WARN";
+    console.log(`[${status}] ${check.name}: ${check.detail}`);
+  }
+  if (!result.ok) {
+    for (const error of result.validation.errors) console.error(`- ${error}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/scripts/public-hygiene.mjs

@@ -0,0 +1,232 @@
+import { execFile } from "node:child_process";
+import { lstat, readFile, readdir, readlink } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+const execFileAsync = promisify(execFile);
+const EXCLUDED_DIRECTORIES = new Set([".git", "node_modules"]);
+
+const RULES = [
+  {
+    id: "windows-absolute-path",
+    message: "使用了固定的 Windows 绝对路径",
+    pattern: /(?<![A-Za-z0-9])[A-Za-z]:[\\/][^\s"'<>|\r\n]*/gu,
+  },
+  {
+    id: "windows-unc-path",
+    message: "使用了固定的 Windows UNC 路径",
+    pattern: /(?<![:\\/])(?:\\\\|\/\/)[A-Za-z0-9._-]+[\\/][A-Za-z0-9.$_-]+(?:[\\/][^\s"'<>|]*)?/gu,
+  },
+  {
+    id: "personal-home-path",
+    message: "使用了具体用户的 Unix home 路径",
+    pattern: /(?<![A-Za-z0-9])(?:\/(?:Users|home)\/[A-Za-z0-9._-]+(?:\/[^\s"'<>]*)?|\/root(?:\/[^\s"'<>]*|(?=$|[\s"'<>])))/gu,
+  },
+  {
+    id: "legacy-project-name",
+    message: "包含不应进入公开资产的旧项目标识",
+    pattern: /\bai[-_ ]?playbook\b/giu,
+  },
+  {
+    id: "legacy-package-name",
+    message: "包含已经停用的 npm 包标识",
+    pattern: /@netpilot-z\/skills\b/giu,
+  },
+  {
+    id: "default-branch-git-spec",
+    message: "GitHub 安装规格不应硬编码默认分支",
+    pattern: /(?:\bgithub:|\b(?:git\+)?https?:\/\/github\.com\/|\bgit(?:\+ssh)?:\/\/(?:git@)?github\.com\/|\bgit@github\.com:)[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+#(?:master|main)\b/giu,
+  },
+];
+
+function lineNumberAt(content, index) {
+  let line = 1;
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    if (content.charCodeAt(cursor) === 10) line += 1;
+  }
+  return line;
+}
+
+export function findPublicHygieneViolations(content, filePath = "<content>") {
+  const violations = [];
+  for (const rule of RULES) {
+    rule.pattern.lastIndex = 0;
+    for (const match of content.matchAll(rule.pattern)) {
+      violations.push({
+        filePath,
+        line: lineNumberAt(content, match.index),
+        ruleId: rule.id,
+        message: rule.message,
+        value: match[0],
+      });
+    }
+  }
+  return violations.sort(
+    (left, right) =>
+      left.filePath.localeCompare(right.filePath) ||
+      left.line - right.line ||
+      left.ruleId.localeCompare(right.ruleId),
+  );
+}
+
+async function collectTextFiles(targetPath, files) {
+  let metadata;
+  try {
+    metadata = await lstat(targetPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+
+  if (metadata.isSymbolicLink() || metadata.isFile()) {
+    files.add(path.resolve(targetPath));
+    return;
+  }
+  if (!metadata.isDirectory()) return;
+
+  const entries = await readdir(targetPath, { withFileTypes: true });
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (entry.isDirectory() && EXCLUDED_DIRECTORIES.has(entry.name)) continue;
+    await collectTextFiles(path.join(targetPath, entry.name), files);
+  }
+}
+
+async function collectGitFiles(repositoryRoot, files) {
+  let repositoryPrefix;
+  try {
+    ({ stdout: repositoryPrefix } = await execFileAsync(
+      "git",
+      ["-C", repositoryRoot, "rev-parse", "--show-prefix"],
+      { encoding: "utf8", windowsHide: true },
+    ));
+  } catch {
+    return false;
+  }
+  if (repositoryPrefix.trim() !== "") {
+    return false;
+  }
+
+  const [{ stdout }, { stdout: staged }] = await Promise.all([
+    execFileAsync(
+      "git",
+      ["-C", repositoryRoot, "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+      { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, windowsHide: true },
+    ),
+    execFileAsync(
+      "git",
+      ["-C", repositoryRoot, "ls-files", "--cached", "--stage", "-z"],
+      { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, windowsHide: true },
+    ),
+  ]);
+  const gitlinks = new Set(
+    staged
+      .split("\0")
+      .flatMap((entry) => {
+        const separator = entry.indexOf("\t");
+        return entry.startsWith("160000 ") && separator >= 0
+          ? [entry.slice(separator + 1).replaceAll("\\", "/")]
+          : [];
+      }),
+  );
+  for (const relativePath of stdout.split("\0").filter(Boolean)) {
+    const gitPath = relativePath.replaceAll("\\", "/");
+    if ([...gitlinks].some((gitlink) => gitPath === gitlink || gitPath.startsWith(`${gitlink}/`))) {
+      continue;
+    }
+    const targetPath = path.resolve(repositoryRoot, relativePath);
+    const portableRelative = path.relative(repositoryRoot, targetPath);
+    if (
+      portableRelative === "" ||
+      path.isAbsolute(portableRelative) ||
+      portableRelative === ".." ||
+      portableRelative.startsWith(`..${path.sep}`)
+    ) {
+      throw new Error(`Git 文件路径越界：${relativePath}`);
+    }
+    let metadata;
+    try {
+      metadata = await lstat(targetPath);
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    if (metadata.isSymbolicLink() || metadata.isFile()) files.add(targetPath);
+  }
+  return true;
+}
+
+function decodeUtf16(buffer, littleEndian, offset = 0) {
+  const body = Buffer.from(buffer.subarray(offset));
+  if (body.length % 2 !== 0) return null;
+  if (!littleEndian) body.swap16();
+  return body.toString("utf16le");
+}
+
+function decodePublicText(buffer) {
+  if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+    return decodeUtf16(buffer, true, 2);
+  }
+  if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+    return decodeUtf16(buffer, false, 2);
+  }
+  if (buffer.includes(0)) {
+    const sampleLength = Math.min(buffer.length - (buffer.length % 2), 1024);
+    let evenNulls = 0;
+    let oddNulls = 0;
+    for (let index = 0; index < sampleLength; index += 2) {
+      if (buffer[index] === 0) evenNulls += 1;
+      if (buffer[index + 1] === 0) oddNulls += 1;
+    }
+    const pairs = sampleLength / 2;
+    if (pairs > 0 && oddNulls / pairs >= 0.3 && evenNulls / pairs <= 0.05) {
+      return decodeUtf16(buffer, true);
+    }
+    if (pairs > 0 && evenNulls / pairs >= 0.3 && oddNulls / pairs <= 0.05) {
+      return decodeUtf16(buffer, false);
+    }
+    return null;
+  }
+  try {
+    return UTF8_DECODER.decode(buffer);
+  } catch {
+    return null;
+  }
+}
+
+export async function scanPublicPackage(repositoryRoot) {
+  const files = new Set();
+  if (!(await collectGitFiles(repositoryRoot, files))) {
+    await collectTextFiles(repositoryRoot, files);
+  }
+
+  const violations = [];
+  for (const filePath of [...files].sort()) {
+    const relativePath = path.relative(repositoryRoot, filePath).replaceAll("\\", "/");
+    const metadata = await lstat(filePath);
+    const content = metadata.isSymbolicLink()
+      ? await readlink(filePath)
+      : decodePublicText(await readFile(filePath));
+    if (content === null) continue;
+    violations.push(...findPublicHygieneViolations(content, relativePath));
+  }
+  return violations;
+}
+
+const modulePath = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(modulePath)) {
+  const repositoryRoot = path.dirname(path.dirname(modulePath));
+  const violations = await scanPublicPackage(repositoryRoot);
+  if (violations.length > 0) {
+    process.stderr.write(`公网卫生校验失败：发现 ${violations.length} 个问题。\n`);
+    for (const violation of violations) {
+      process.stderr.write(
+        `- ${violation.filePath}:${violation.line} [${violation.ruleId}] ${violation.message}：${violation.value}\n`,
+      );
+    }
+    process.exitCode = 1;
+  } else {
+    process.stdout.write("OK: 公开发布文件不含本机路径、旧项目标识或默认分支硬编码。\n");
+  }
+}