dependfix 0.1.0 → 0.3.2

package/dist/runner.mjs

@@ -0,0 +1,792 @@
+import { createRequire } from "node:module";
+import { AppError, isValidRepoIdentifier, toAppError } from "@dependfix/core";
+import { defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage } from "citty";
+import { ALERT_SOURCES, DependfixApp, RUNTIME_MODES, SEVERITY_THRESHOLDS, formatHistory, queryRepoHistory, resolveRuntimeConfig } from "@dependfix/engine";
+import { homedir } from "node:os";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+
+//#region src/cli/index.ts
+const argsDef = {
+	mode: {
+		type: "positional",
+		description: "运行模式：report-only, fix, fix-and-pr, cleanup-branches",
+		required: false,
+		default: "report-only"
+	},
+	repo: {
+		type: "string",
+		description: "目标仓库 (owner/repo)，逗号分隔多个",
+		alias: [
+			"r",
+			"repository",
+			"repositories"
+		]
+	},
+	"repos-file": {
+		type: "string",
+		description: "从文件读取仓库列表（每行一个 owner/repo）"
+	},
+	owner: {
+		type: "string",
+		description: "owner / org 自动发现（逗号分隔多个或多次传入），与 --repo 合并去重（显式优先）"
+	},
+	"repo-topics": {
+		type: "string",
+		description: "发现结果 topic 白名单（逗号分隔，AND 语义；仅影响 --owner 发现结果）"
+	},
+	"repo-include": {
+		type: "string",
+		description: "仓库白名单 glob（逗号分隔多个或多次传入，如 owner/*、owner/pkg-*；仅作用于发现结果）"
+	},
+	"repo-exclude": {
+		type: "string",
+		description: "仓库黑名单 glob（逗号分隔多个或多次传入；显式列表与发现结果均受约束，与 include 冲突时胜出）"
+	},
+	"repo-topics-exclude": {
+		type: "string",
+		description: "发现结果 topic 黑名单（逗号分隔，排除含任一指定 topic 的仓库）"
+	},
+	"severity-threshold": {
+		type: "string",
+		description: "严重级别阈值：critical, high, medium, all",
+		default: "high"
+	},
+	"dry-run": {
+		type: "boolean",
+		description: "试运行模式，不实际写入文件",
+		negativeDescription: "关闭试运行模式"
+	},
+	"create-pr": {
+		type: "boolean",
+		description: "创建 Pull Request",
+		negativeDescription: "不创建 Pull Request"
+	},
+	commit: {
+		type: "boolean",
+		description: "修复完成后在本地当前分支直接提交（不推送、不创建 PR）",
+		negativeDescription: "不自动提交（默认）"
+	},
+	"cleanup-branches": {
+		type: "boolean",
+		description: "（fix-and-pr 模式）结束后列出已合并的 dependfix 分支到报告，不自动删除",
+		negativeDescription: "不执行分支清理检查"
+	},
+	"cleanup-branches-auto": {
+		type: "boolean",
+		description: "（fix-and-pr 模式）结束后自动删除已合并/已关闭的 dependfix 分支（非交互，不删有 open PR 的分支）",
+		negativeDescription: "不自动删除分支"
+	},
+	"github-token": {
+		type: "string",
+		description: "GitHub Personal Access Token"
+	},
+	"alerts-token": {
+		type: "string",
+		description: "Dependabot alerts 专用 token（可选，最小权限 PAT，仅 Dependabot alerts: read；缺省回退 --github-token。GITHUB_TOKEN 无法读取 Dependabot alerts）"
+	},
+	"alerts-source": {
+		type: "string",
+		description: "告警数据源：github-dependabot（默认，GitHub Dependabot alerts API）或 pnpm-audit（本地无 token 回退，扫描当前工作区 lockfile；repository 优先 --repo → git remote → local 兜底）"
+	},
+	"code-scanning": {
+		type: "boolean",
+		description: "同时拉取 Code Scanning alerts（与 Dependabot 并行，默认关闭；需要 token 具备 security-events: read，GITHUB_TOKEN 默认具备）",
+		negativeDescription: "不拉取 Code Scanning alerts（默认）"
+	},
+	"allow-major-upgrade": {
+		type: "boolean",
+		description: "跨线告警（推荐版本跨大版本，当前线内无修复版本）显式授权自动升级：仅根 package.json 直接依赖（workspace 成员独占声明维持人工）且 lockfile 单版本的告警自动跨线升级，升级后复核脆弱实例、强制完整验证（install+lint+build），失败自动回滚；间接依赖 / 多版本共存跨线告警维持人工处理。仅 CLI 可用，Action 不支持",
+		negativeDescription: "不自动升级跨线告警（默认，维持人工处理）"
+	},
+	"max-alerts-per-repository": {
+		type: "string",
+		description: "每个仓库最多处理的告警数",
+		default: "20"
+	},
+	"max-concurrency": {
+		type: "string",
+		description: "多仓库并发窗口（1-16，默认 1 保守串行；>1 可能触发 GitHub 限流）",
+		default: "1"
+	},
+	"max-retries": {
+		type: "string",
+		description: "GitHub API 限流重试次数（0-10，默认 3；429/rate limit 指数退避重试）",
+		default: "3"
+	},
+	"max-backoff-ms": {
+		type: "string",
+		description: "限流退避单次等待上限毫秒（100-120000，默认 30000；Retry-After / reset / 指数退避均受此约束）",
+		default: "30000"
+	},
+	history: {
+		type: "string",
+		description: "查询仓库历史运行摘要（读 dependfix-reports/index.json，倒序时间；不执行扫描）"
+	},
+	"upgrade-groups": {
+		type: "string",
+		description: "用户显式分组（覆盖自动分组），格式 \"name1:pkg1,pkg2;name2:pkg3\""
+	},
+	"toolchain-pnpm-version": {
+		type: "string",
+		description: "lockfile 修复用的 pnpm 版本（工具链固定；缺省从 package.json packageManager 解析；PIN_TOOLCHAIN 策略用 corepack pnpm@<version> 执行）"
+	},
+	commands: {
+		type: "string",
+		description: "自定义验证命令（逗号分隔），覆盖默认的 install/lint/build"
+	},
+	verbose: {
+		type: "boolean",
+		description: "输出详细日志"
+	},
+	ai: {
+		type: "boolean",
+		description: "开启 AI breaking change 研判（默认关闭；需配置 AI API Key。触发范围见 --ai-trigger；dry-run 不触发、不产生费用）",
+		negativeDescription: "关闭 AI 研判（默认）"
+	},
+	"ai-provider": {
+		type: "string",
+		description: "AI 提供商：openai-compatible（默认，DeepSeek 等指定 --ai-base-url 兼容）或 anthropic"
+	},
+	"ai-model": {
+		type: "string",
+		description: "AI 模型名（默认 deepseek-v4-flash）"
+	},
+	"ai-base-url": {
+		type: "string",
+		description: "OpenAI 兼容端点基地址（默认 https://api.deepseek.com，与默认模型 deepseek-v4-flash 配套；使用 OpenAI 官方模型时指定 https://api.openai.com/v1 + --ai-model）"
+	},
+	"ai-api-url": {
+		type: "string",
+		description: "Anthropic 兼容端点（仅 --ai-provider anthropic 生效；默认 https://api.anthropic.com/v1/messages，自托管/网关可显式指定）"
+	},
+	"ai-api-key": {
+		type: "string",
+		description: "AI API Key（优先 DEPENDFIX_AI_API_KEY env；注意命令行参数会出现在进程列表/shell history，敏感环境请用 env）"
+	},
+	"ai-trigger": {
+		type: "string",
+		description: "AI 研判触发范围：failure（升级验证失败）/ major（major 升级）/ both（默认）"
+	}
+};
+function isRuntimeMode(value) {
+	return RUNTIME_MODES.includes(value);
+}
+function isSeverityThreshold(value) {
+	return SEVERITY_THRESHOLDS.includes(value);
+}
+function isAlertSource(value) {
+	return ALERT_SOURCES.includes(value);
+}
+function appendRepositories(target, value) {
+	for (const repository of value.split(",")) {
+		const trimmed = repository.trim();
+		if (!trimmed) continue;
+		if (!isValidRepoIdentifier(trimmed)) throw new AppError("ARGUMENT_PARSE_ERROR", `Invalid repository identifier: "${trimmed}". Expected format: owner/repo`);
+		target.push(trimmed);
+	}
+}
+function parseCommandsFlag(value) {
+	return value.split(",").map((cmd) => cmd.trim()).filter(Boolean);
+}
+/**
+* 严格整数字面量解析（修复：拒绝 `2.5` 被 parseInt 静默截断为 2）。
+* 仅接受 `^\d+$`；范围语义由调用方在 expected 描述中声明（config 校验兜底）。
+*/
+function parseIntegerFlag(value, flagName, expected) {
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) throw new AppError("ARGUMENT_PARSE_ERROR", `Invalid ${flagName} value: "${value}". ${expected}`);
+	return Number.parseInt(trimmed, 10);
+}
+/**
+* 归一化可重复 flag 值（citty/mri 对重复传入返回数组，单次传入返回字符串）：
+* 按逗号拆分 + 去空白 + 去空项。`--owner a,b --owner c` → ['a', 'b', 'c']。
+*/
+function normalizeFlagList(value) {
+	if (value === void 0) return [];
+	return (Array.isArray(value) ? value : [value]).flatMap((v) => v.split(",")).map((s) => s.trim()).filter(Boolean);
+}
+function parsedArgsToCliOverrides(parsed) {
+	const overrides = {};
+	const rawMode = parsed.mode;
+	if (isRuntimeMode(rawMode)) overrides.mode = rawMode;
+	const repoValue = parsed.repo;
+	if (repoValue) {
+		const repos = [];
+		appendRepositories(repos, repoValue);
+		if (repos.length > 0) overrides.repositories = repos;
+	}
+	const reposFile = parsed["repos-file"];
+	if (reposFile) overrides.reposFilePath = reposFile;
+	const ownerValue = normalizeFlagList(parsed.owner);
+	if (ownerValue.length > 0) overrides.owner = ownerValue;
+	const repoTopicsValue = normalizeFlagList(parsed["repo-topics"]);
+	if (repoTopicsValue.length > 0) overrides.repoTopics = repoTopicsValue;
+	const repoIncludeValue = normalizeFlagList(parsed["repo-include"]);
+	if (repoIncludeValue.length > 0) overrides.repoInclude = repoIncludeValue;
+	const repoExcludeValue = normalizeFlagList(parsed["repo-exclude"]);
+	if (repoExcludeValue.length > 0) overrides.repoExclude = repoExcludeValue;
+	const repoTopicsExcludeValue = normalizeFlagList(parsed["repo-topics-exclude"]);
+	if (repoTopicsExcludeValue.length > 0) overrides.repoTopicsExclude = repoTopicsExcludeValue;
+	const severityThreshold = parsed["severity-threshold"];
+	if (isSeverityThreshold(severityThreshold)) overrides.severityThreshold = severityThreshold;
+	if (parsed["dry-run"] !== void 0) overrides.dryRun = parsed["dry-run"];
+	if (parsed["create-pr"] !== void 0) overrides.createPullRequest = parsed["create-pr"];
+	if (parsed.commit !== void 0) overrides.commit = parsed.commit;
+	if (parsed["cleanup-branches"] !== void 0) overrides.cleanupBranches = parsed["cleanup-branches"];
+	if (parsed["cleanup-branches-auto"] !== void 0) overrides.cleanupBranchesAuto = parsed["cleanup-branches-auto"];
+	const githubToken = parsed["github-token"];
+	if (githubToken) overrides.githubToken = githubToken;
+	const alertsToken = parsed["alerts-token"];
+	if (alertsToken) overrides.alertsToken = alertsToken;
+	const alertsSource = parsed["alerts-source"];
+	if (alertsSource) {
+		if (!isAlertSource(alertsSource)) throw new AppError("ARGUMENT_PARSE_ERROR", `Invalid --alerts-source value: "${alertsSource}". Expected one of: ${ALERT_SOURCES.join(", ")}.`);
+		overrides.alertSource = alertsSource;
+	}
+	if (parsed["code-scanning"] !== void 0) overrides.codeScanningEnabled = parsed["code-scanning"];
+	if (parsed["allow-major-upgrade"] !== void 0) overrides.allowMajorUpgrade = parsed["allow-major-upgrade"];
+	const maxAlerts = parsed["max-alerts-per-repository"];
+	if (maxAlerts) overrides.maxAlertsPerRepository = parseIntegerFlag(maxAlerts, "--max-alerts-per-repository", "Expected a positive integer.");
+	const maxConcurrency = parsed["max-concurrency"];
+	if (maxConcurrency) overrides.maxConcurrency = parseIntegerFlag(maxConcurrency, "--max-concurrency", "Expected an integer between 1 and 16.");
+	const maxRetries = parsed["max-retries"];
+	if (maxRetries) overrides.maxRetries = parseIntegerFlag(maxRetries, "--max-retries", "Expected an integer between 0 and 10.");
+	const maxBackoffMs = parsed["max-backoff-ms"];
+	if (maxBackoffMs) overrides.maxBackoffMs = parseIntegerFlag(maxBackoffMs, "--max-backoff-ms", "Expected an integer between 100 and 120000.");
+	const history = parsed.history;
+	if (history) overrides.history = history;
+	if (parsed.verbose !== void 0) overrides.verbose = parsed.verbose;
+	const commandsValue = parsed.commands;
+	if (commandsValue) overrides.commands = parseCommandsFlag(commandsValue);
+	const upgradeGroups = parsed["upgrade-groups"];
+	if (upgradeGroups) overrides.upgradeGroups = parseUpgradeGroupsFlag(upgradeGroups);
+	const toolchainPnpmVersion = parsed["toolchain-pnpm-version"];
+	if (toolchainPnpmVersion) overrides.toolchainPnpmVersion = toolchainPnpmVersion;
+	if (parsed.ai !== void 0) overrides.aiEnabled = parsed.ai;
+	const aiProvider = parsed["ai-provider"];
+	if (aiProvider) {
+		if (aiProvider !== "openai-compatible" && aiProvider !== "anthropic") throw new AppError("ARGUMENT_PARSE_ERROR", `Invalid --ai-provider value: "${aiProvider}". Expected "openai-compatible" or "anthropic".`);
+		overrides.aiProvider = aiProvider;
+	}
+	const aiModel = parsed["ai-model"];
+	if (aiModel) overrides.aiModel = aiModel;
+	const aiBaseUrl = parsed["ai-base-url"];
+	if (aiBaseUrl) overrides.aiBaseUrl = aiBaseUrl;
+	const aiApiUrl = parsed["ai-api-url"];
+	if (aiApiUrl) overrides.aiApiUrl = aiApiUrl;
+	const aiApiKey = parsed["ai-api-key"];
+	if (aiApiKey) overrides.aiApiKey = aiApiKey;
+	const aiTrigger = parsed["ai-trigger"];
+	if (aiTrigger) {
+		if (aiTrigger !== "failure" && aiTrigger !== "major" && aiTrigger !== "both") throw new AppError("ARGUMENT_PARSE_ERROR", `Invalid --ai-trigger value: "${aiTrigger}". Expected "failure", "major" or "both".`);
+		overrides.aiTrigger = aiTrigger;
+	}
+	return overrides;
+}
+/**
+* 解析 `--upgrade-groups "name1:pkg1,pkg2;name2:pkg3"`。
+* 与 config 的 normalizeUpgradeGroups 保持一致（CLI 与 env 同格式）：
+* 空 entry 忽略；非空但缺冒号/组名或包列表为空 → 抛 ARGUMENT_PARSE_ERROR；
+* 原型链风险键名（__proto__ / constructor / prototype）忽略。
+*/
+function parseUpgradeGroupsFlag(value) {
+	const result = {};
+	for (const entry of value.split(";")) {
+		if (!entry.trim()) continue;
+		const idx = entry.indexOf(":");
+		if (idx <= 0) throw new AppError("ARGUMENT_PARSE_ERROR", `Invalid --upgrade-groups entry: "${entry}". Expected format: "name:pkg1,pkg2"`);
+		const name = entry.slice(0, idx).trim();
+		const pkgs = entry.slice(idx + 1).split(",").map((p) => p.trim()).filter(Boolean);
+		if (name === "__proto__" || name === "constructor" || name === "prototype") continue;
+		if (!name || pkgs.length === 0) throw new AppError("ARGUMENT_PARSE_ERROR", `Invalid --upgrade-groups entry: "${entry}". Expected format: "name:pkg1,pkg2"`);
+		result[name] = pkgs;
+	}
+	return result;
+}
+function parseCliArgs(rawArgs) {
+	const configOverrides = parsedArgsToCliOverrides(parseArgs(rawArgs, argsDef));
+	return {
+		mode: configOverrides.mode,
+		configOverrides,
+		rawArgs: [...rawArgs]
+	};
+}
+
+//#endregion
+//#region src/app/pipeline.ts
+function createPipeline(deps = {}) {
+	const env = deps.env ?? process.env;
+	const logger = deps.logger ?? console;
+	const resolveConfig = deps.resolveConfig ?? ((opts) => resolveRuntimeConfig(opts));
+	const exit = deps.exit ?? ((code) => {
+		process.exitCode = code;
+	});
+	return {
+		parse(rawArgs) {
+			const invocation = parseCliArgs(rawArgs);
+			return {
+				ok: true,
+				invocation,
+				config: resolveConfig({
+					env,
+					cliOverrides: invocation.configOverrides
+				})
+			};
+		},
+		async run(rawArgs) {
+			const invocation = parseCliArgs(rawArgs);
+			if (invocation.configOverrides.history) {
+				const entries = queryRepoHistory(invocation.configOverrides.history);
+				logger.info(formatHistory(entries, invocation.configOverrides.history));
+				return 0;
+			}
+			const config = resolveConfig({
+				env,
+				cliOverrides: invocation.configOverrides
+			});
+			const { exitCode } = await new DependfixApp({
+				config,
+				verbose: invocation.configOverrides.verbose,
+				commands: invocation.configOverrides.commands
+			}).run();
+			exit(exitCode);
+			return exitCode;
+		}
+	};
+}
+
+//#endregion
+//#region src/skills/agents.ts
+const AGENTS = [
+	{
+		id: "claude-code",
+		displayName: "Claude Code",
+		projectSkillDir: (root) => join(root, ".claude", "skills"),
+		globalSkillDir: (home) => join(home, ".claude", "skills"),
+		detectInstalled: (home) => existsSync(join(home, ".claude"))
+	},
+	{
+		id: "opencode",
+		displayName: "OpenCode",
+		projectSkillDir: (root) => join(root, ".agents", "skills"),
+		globalSkillDir: (home) => join(home, ".config", "opencode", "skills"),
+		detectInstalled: (home) => existsSync(join(home, ".config", "opencode"))
+	},
+	{
+		id: "cursor",
+		displayName: "Cursor",
+		projectSkillDir: (root) => join(root, ".cursor", "skills"),
+		globalSkillDir: (home) => join(home, ".cursor", "skills"),
+		detectInstalled: (home) => existsSync(join(home, ".cursor"))
+	},
+	{
+		id: "copilot",
+		displayName: "GitHub Copilot",
+		projectSkillDir: () => void 0,
+		globalSkillDir: (home) => join(home, ".copilot", "skills"),
+		detectInstalled: (home) => existsSync(join(home, ".copilot"))
+	}
+];
+
+//#endregion
+//#region src/skills/source.ts
+const PRODUCT_SKILL_NAME = "dependfix-remediator";
+/**
+* 解析产品 skill 内容目录（含 SKILL.md 的目录）。
+* 找不到包或内容目录时抛错（install / doctor 的必要前置）。
+*/
+function resolveProductSkillSourceDir() {
+	const pkgJsonPath = createRequire(import.meta.url).resolve("@dependfix/skills/package.json");
+	return join(dirname(pkgJsonPath), PRODUCT_SKILL_NAME);
+}
+
+//#endregion
+//#region src/skills/installer.ts
+/** 收集目录内文件相对路径 -> sha256（递归） */
+function collectFileHashes(dir) {
+	const result = /* @__PURE__ */ new Map();
+	if (!existsSync(dir)) return result;
+	const walk = (current, relPrefix) => {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const full = join(current, entry.name);
+			const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) walk(full, rel);
+			else if (entry.isFile()) result.set(rel, hashFile(full));
+		}
+	};
+	walk(dir, "");
+	return result;
+}
+function hashFile(filePath) {
+	return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+/** 两个目录内容是否完全一致（文件集合 + 内容 hash） */
+function isContentSame(dirA, dirB) {
+	const mapA = collectFileHashes(dirA);
+	const mapB = collectFileHashes(dirB);
+	if (mapA.size !== mapB.size) return false;
+	for (const [rel, hash] of mapA) if (mapB.get(rel) !== hash) return false;
+	return true;
+}
+/** 复制目录（镜像语义：先清空目标内同名子目录再复制） */
+function mirrorCopy(sourceDir, targetSkillDir) {
+	rmSync(targetSkillDir, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(targetSkillDir, { recursive: true });
+	for (const entry of readdirSync(sourceDir)) {
+		const src = join(sourceDir, entry);
+		const dst = join(targetSkillDir, entry);
+		if (statSync(src).isDirectory()) cpSync(src, dst, { recursive: true });
+		else cpSync(src, dst);
+	}
+}
+/**
+* 安装产品 skill 到单个 agent skills 目录。
+* 返回 InstallResult；失败时 status='failed' 且 detail 含错误信息（不抛错，便于批量收尾）。
+*/
+async function installSkillToDir(options) {
+	const { sourceDir, targetDir, force, dryRun, confirmOverwrite } = options;
+	const skillTarget = join(targetDir, PRODUCT_SKILL_NAME);
+	if (!existsSync(sourceDir)) return {
+		status: "failed",
+		targetDir,
+		detail: `权威源不存在: ${sourceDir}`
+	};
+	if (dryRun) try {
+		return existsSync(skillTarget) && isContentSame(sourceDir, skillTarget) ? {
+			status: "up-to-date",
+			targetDir,
+			detail: "[dry-run] 已一致"
+		} : {
+			status: "installed",
+			targetDir,
+			detail: "[dry-run] 将安装"
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			targetDir,
+			detail: errorMessage(error)
+		};
+	}
+	if (!existsSync(skillTarget)) try {
+		mirrorCopy(sourceDir, skillTarget);
+		return {
+			status: "installed",
+			targetDir
+		};
+	} catch (error) {
+		cleanupPartial(skillTarget);
+		return {
+			status: "failed",
+			targetDir,
+			detail: errorMessage(error)
+		};
+	}
+	let same;
+	try {
+		same = isContentSame(sourceDir, skillTarget);
+	} catch (error) {
+		return {
+			status: "failed",
+			targetDir,
+			detail: errorMessage(error)
+		};
+	}
+	if (same) return {
+		status: "up-to-date",
+		targetDir
+	};
+	if (!(force ?? (confirmOverwrite ? await confirmOverwrite(skillTarget) : false))) return {
+		status: "skipped-conflict",
+		targetDir,
+		detail: "目标存在内容不一致的同名 skill，已跳过（使用 --force 或交互确认覆盖）"
+	};
+	try {
+		mirrorCopy(sourceDir, skillTarget);
+		return {
+			status: "installed",
+			targetDir,
+			detail: "已覆盖旧版本"
+		};
+	} catch (error) {
+		cleanupPartial(skillTarget);
+		return {
+			status: "failed",
+			targetDir,
+			detail: errorMessage(error)
+		};
+	}
+}
+/** mirrorCopy 失败后清理半写目录（避免下次安装误判为内容不一致需 force） */
+function cleanupPartial(skillTarget) {
+	try {
+		rmSync(skillTarget, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+
+//#endregion
+//#region src/skills/doctor.ts
+function runDoctor(options) {
+	const { homeDir, projectRoot = process.cwd() } = options;
+	const findings = [];
+	for (const agent of AGENTS) {
+		if (!agent.detectInstalled(homeDir)) continue;
+		const globalDir = agent.globalSkillDir(homeDir);
+		if (!existsSync(globalDir)) findings.push({
+			level: "warn",
+			message: `${agent.displayName} 已检测到，但全局 skills 目录缺失（${globalDir}）——可能官方目录约定已变更，或尚未初始化`
+		});
+		const projectDir = agent.projectSkillDir(projectRoot);
+		if (projectDir && !existsSync(projectDir)) findings.push({
+			level: "ok",
+			message: `${agent.displayName} 项目级 skills 目录不存在（${projectDir}）——非问题，按需创建`
+		});
+	}
+	const sourceDir = options.productSourceDir ?? safeResolveSourceDir();
+	if (sourceDir) for (const agent of AGENTS) {
+		if (!agent.detectInstalled(homeDir)) continue;
+		const installedDir = join(agent.globalSkillDir(homeDir), PRODUCT_SKILL_NAME);
+		if (!existsSync(installedDir)) {
+			findings.push({
+				level: "ok",
+				message: `${agent.displayName}: ${PRODUCT_SKILL_NAME} 未安装（运行 dependfix skills install）`
+			});
+			continue;
+		}
+		if (isContentSame(sourceDir, installedDir)) findings.push({
+			level: "ok",
+			message: `${agent.displayName}: ${PRODUCT_SKILL_NAME} 已安装且与当前版本一致`
+		});
+		else findings.push({
+			level: "warn",
+			message: `${agent.displayName}: ${PRODUCT_SKILL_NAME} 已安装但内容与当前版本不一致（建议重新 install）`
+		});
+	}
+	const internalSkillsRoot = join(projectRoot, ".github", "skills");
+	if (existsSync(internalSkillsRoot)) {
+		const missing = [];
+		for (const entry of readdirSync(internalSkillsRoot, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			const skillFile = join(internalSkillsRoot, entry.name, "SKILL.md");
+			if (!existsSync(skillFile)) {
+				missing.push(`${entry.name}（缺 SKILL.md）`);
+				continue;
+			}
+			const content = readFileSync(skillFile, "utf8");
+			if (!/metadata:\s*\r?\n\s*internal:\s*true/.test(content)) missing.push(entry.name);
+		}
+		if (missing.length > 0) findings.push({
+			level: "error",
+			message: `内部 skill internal 标记缺失（生态可见泄漏风险）: ${missing.join(", ")}`
+		});
+		else findings.push({
+			level: "ok",
+			message: `内部 skill internal 标记完整性检查通过（.github/skills）`
+		});
+	}
+	return findings;
+}
+/** 解析产品 skill 源目录；失败返回 undefined（如 CLI 运行在无 @dependfix/skills 的调试环境） */
+function safeResolveSourceDir() {
+	try {
+		return resolveProductSkillSourceDir();
+	} catch {
+		return;
+	}
+}
+
+//#endregion
+//#region src/skills/index.ts
+async function runInstall(args) {
+	const home = homedir();
+	const projectRoot = process.cwd();
+	let sourceDir;
+	try {
+		sourceDir = resolveProductSkillSourceDir();
+	} catch (error) {
+		console.error(`无法定位产品 skill 内容（@dependfix/skills 未安装？）: ${error instanceof Error ? error.message : String(error)}`);
+		process.exitCode = 1;
+		return;
+	}
+	const detected = AGENTS.filter((agent) => agent.detectInstalled(home));
+	if (detected.length === 0) {
+		console.info("未检测到已安装的 agent 工具（Claude Code / OpenCode / Cursor / Copilot）。");
+		console.info("主通道安装（推荐）: npx skills add dependfix/dependfix -s dependfix-remediator -g");
+		return;
+	}
+	console.info(`检测到 ${detected.length} 个 agent 工具，目标模式: ${args.project ? "项目级" : "全局"}\n`);
+	const results = [];
+	for (const agent of detected) {
+		const agentDir = args.project ? agent.projectSkillDir(projectRoot) : agent.globalSkillDir(home);
+		if (!agentDir) {
+			console.info(`- ${agent.displayName}: 不支持 ${args.project ? "项目级" : ""}安装，跳过`);
+			continue;
+		}
+		const result = await installSkillToDir({
+			sourceDir,
+			targetDir: agentDir,
+			force: args.force,
+			dryRun: args["dry-run"],
+			confirmOverwrite: (existingDir) => confirmOverwritePrompt(agent.displayName, existingDir)
+		});
+		results.push({
+			agent: agent.displayName,
+			result
+		});
+	}
+	console.info("\n安装清单:");
+	const installIcons = {
+		installed: "✓",
+		"up-to-date": "=",
+		"skipped-conflict": "!",
+		failed: "✗"
+	};
+	for (const { agent, result } of results) {
+		const icon = installIcons[result.status];
+		console.info(`  ${icon} ${agent}: ${result.status}${result.detail ? ` — ${result.detail}` : ""}`);
+	}
+	if (results.filter((r) => r.result.status === "failed").length > 0) process.exitCode = 1;
+}
+/** 交互式覆盖确认；非 TTY 返回 false（不静默覆盖） */
+async function confirmOverwritePrompt(agentName, existingDir) {
+	if (!process.stdin.isTTY) {
+		console.warn(`  ${agentName}: 目标已存在内容不一致的 dependfix-remediator，非交互环境跳过（使用 --force 覆盖）`);
+		return false;
+	}
+	const readline = (await import("node:readline")).createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return new Promise((resolve) => {
+		readline.question(`  覆盖 ${existingDir} 中的旧版本？[y/N] `, (answer) => {
+			readline.close();
+			resolve(answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes");
+		});
+	});
+}
+async function runDoctorCli() {
+	const findings = runDoctor({
+		homeDir: homedir(),
+		projectRoot: process.cwd()
+	});
+	const doctorIcons = {
+		ok: "✓",
+		warn: "!",
+		error: "✗"
+	};
+	let warnCount = 0;
+	let errorCount = 0;
+	for (const finding of findings) {
+		const icon = doctorIcons[finding.level];
+		console.info(`  ${icon} [${finding.level}] ${finding.message}`);
+		if (finding.level === "warn") warnCount++;
+		else if (finding.level === "error") errorCount++;
+	}
+	console.info(`\ndoctor 完成: ${findings.length} 项检查，${warnCount} warning, ${errorCount} error`);
+	if (errorCount > 0) process.exitCode = 1;
+}
+const skillsCommand = defineCommand({
+	meta: {
+		name: "skills",
+		description: "产品 skill 管理（npx skills 生态的离线兜底安装器）"
+	},
+	subCommands: {
+		install: defineCommand({
+			meta: {
+				name: "install",
+				description: "检测本机已装 agent 工具并安装 dependfix-remediator 产品 skill"
+			},
+			args: {
+				project: {
+					type: "boolean",
+					description: "安装到当前项目目录（默认用户全局）",
+					negativeDescription: "安装到用户全局（默认）"
+				},
+				force: {
+					type: "boolean",
+					description: "覆盖已存在的内容不一致同名 skill（跳过确认）",
+					negativeDescription: "内容不一致时需确认（默认）"
+				},
+				"dry-run": {
+					type: "boolean",
+					description: "只输出将要执行的操作，不写文件",
+					negativeDescription: "实际执行安装"
+				}
+			},
+			async run({ args }) {
+				await runInstall(args);
+			}
+		}),
+		doctor: defineCommand({
+			meta: {
+				name: "doctor",
+				description: "检查 agent 目录约定、产品 skill 安装状态与内部 skill internal 标记完整性"
+			},
+			async run() {
+				await runDoctorCli();
+			}
+		})
+	},
+	async run({ cmd, rawArgs }) {
+		const sub = rawArgs[0];
+		if (sub === "install" || sub === "doctor") return;
+		console.info(await renderUsage(cmd));
+	}
+});
+
+//#endregion
+//#region src/cli/runner.ts
+/** 默认 CLI 日志（console）；platform 场景经 createPipeline 注入自定义 logger */
+const cliLogger = console;
+function runCli(rawArgs) {
+	return createPipeline({ logger: cliLogger }).parse(rawArgs);
+}
+async function runApp(rawArgs) {
+	return createPipeline({ logger: cliLogger }).run(rawArgs);
+}
+const dependfixCommand = defineCommand({
+	meta: {
+		name: "dependfix",
+		version: "0.1.0",
+		description: "自动化处理 Dependabot / Code Scanning 安全告警的修复工具"
+	},
+	args: argsDef,
+	async run({ rawArgs }) {
+		if (rawArgs[0] === "skills") {
+			await runCommand(skillsCommand, { rawArgs: rawArgs.slice(1) });
+			return;
+		}
+		let exitCode = 1;
+		try {
+			exitCode = await runApp(rawArgs);
+		} catch (error) {
+			const appError = toAppError(error, "CLI_EXECUTION_FAILED");
+			console.error(`Error: ${appError.message}`);
+			exitCode = 1;
+		}
+		process.exitCode = exitCode;
+	}
+});
+async function runDependfixMain(rawArgs = process.argv.slice(2)) {
+	if (rawArgs[0] === "skills" && (rawArgs.includes("--help") || rawArgs.includes("-h"))) {
+		console.info(await renderUsage(skillsCommand));
+		process.exitCode = 0;
+		return;
+	}
+	await runMain(dependfixCommand, { showUsage });
+}
+
+//#endregion
+export { argsDef as a, createPipeline as i, runCli as n, parseCliArgs as o, runDependfixMain as r, dependfixCommand as t };
+//# sourceMappingURL=runner.mjs.map