@docker-doctor/cli 0.3.0 → 0.3.2

package/README.md

@@ -28,32 +28,37 @@ Works with any project that uses Docker.
 npx @docker-doctor/cli@latest
 ```
 
-### 2. Browse rules
+### 2. Install for agents
+
+Once you have an audit, install the skill so your coding agent learns the `/docker-doctor` triage workflow and can fix the issues for you:
 
 ```bash
-npx @docker-doctor/cli@latest rules list
-npx @docker-doctor/cli@latest rules explain docker-doctor/no-root-user
+npx @docker-doctor/cli@latest install
 ```
 
-### 3. Run in CI
+Works with Claude Code, Cursor, Codex, OpenCode, and many more. After an interactive scan finds issues, Docker Doctor also offers to hand them straight to an agent detected on your machine.
 
-Docker Doctor walks you through setting up a GitHub Actions workflow after your first scan:
+[Rules reference →](https://docker-doctor.vercel.app/docs/reference/rules)
 
-```bash
-npx @docker-doctor/cli@latest
-```
+### 3. Run in CI
+
+The GitHub Action (`PunGrumpy/docker-doctor`) scans every pull request and posts a sticky summary comment — advisory by default, with an opt-in gate. See the [GitHub Actions guide](https://docker-doctor.vercel.app/docs/guides/github-actions) for setup, inputs, and gating.
 
 ### 4. Configure
 
-```js
+```ts
 // docker-doctor.config.ts
+import type { DockerDoctorConfig } from "@docker-doctor/cli";
+
 export default {
   rules: {
     "docker-doctor/no-root-user": "error",
   },
-};
+} satisfies DockerDoctorConfig;
 ```
 
+Prefer YAML? `docker-doctor.config.yaml` works too, with editor autocomplete via `# yaml-language-server: $schema=https://docker-doctor.vercel.app/schema.json`. A `defineConfig` helper is also exported for projects with `@docker-doctor/cli` installed — see the [configuration docs](https://docker-doctor.vercel.app/docs/reference/configuration).
+
 ## How the score works
 
 Every scan produces a 0-100 health score alongside a label (`Excellent 🏆`, `Good ✅`, `Needs Work ⚠️`, `Critical 🚨`).

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_src = require('./src-TEhFWhpk.cjs');
+const require_src = require('./src-Dz3RukyR.cjs');
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_src.__toESM(node_fs_promises, 1);
 let node_path = require("node:path");
@@ -9,11 +9,15 @@ node_os = require_src.__toESM(node_os, 1);
 let node_readline = require("node:readline");
 node_readline = require_src.__toESM(node_readline, 1);
 let node_timers_promises = require("node:timers/promises");
+let agent_install = require("agent-install");
 let node_process = require("node:process");
 node_process = require_src.__toESM(node_process, 1);
 let node_tty = require("node:tty");
 node_tty = require_src.__toESM(node_tty, 1);
 let commander = require("commander");
+let node_child_process = require("node:child_process");
+let node_fs = require("node:fs");
+node_fs = require_src.__toESM(node_fs, 1);
 
 //#region ../../node_modules/.bun/chalk@5.6.2/node_modules/chalk/source/vendor/ansi-styles/index.js
 const ANSI_BACKGROUND_OFFSET = 10;
@@ -420,6 +424,234 @@ Object.defineProperties(createChalk.prototype, styles);
 const chalk = createChalk();
 const chalkStderr = createChalk({ level: stderrColor ? stderrColor.level : 0 });
 
+//#endregion
+//#region src/agents/clipboard.ts
+const getClipboardCommands = () => {
+	if (process.platform === "darwin") return [{
+		args: [],
+		command: "pbcopy"
+	}];
+	if (process.platform === "win32") return [{
+		args: [],
+		command: "clip"
+	}];
+	return [
+		{
+			args: [],
+			command: "wl-copy"
+		},
+		{
+			args: ["-selection", "clipboard"],
+			command: "xclip"
+		},
+		{
+			args: ["--clipboard", "--input"],
+			command: "xsel"
+		}
+	];
+};
+const tryCopy = ({ command, args }, text) => new Promise((resolve) => {
+	const child = (0, node_child_process.spawn)(command, args, { stdio: [
+		"pipe",
+		"ignore",
+		"ignore"
+	] });
+	child.once("error", () => {
+		resolve(false);
+	});
+	child.once("exit", (code) => {
+		resolve(code === 0);
+	});
+	child.stdin.end(text);
+});
+const tryCommands = async (commands, text) => {
+	const [first, ...rest] = commands;
+	if (!first) return false;
+	if (await tryCopy(first, text)) return true;
+	return tryCommands(rest, text);
+};
+const copyToClipboard = (text) => tryCommands(getClipboardCommands(), text);
+
+//#endregion
+//#region src/agents/diagnostics-dir.ts
+const DIAGNOSTICS_DIR_NAME = ".docker-doctor";
+const UNSAFE_FILE_CHARS = /[^a-z0-9-]+/giu;
+const ruleFileName = (rule) => {
+	return `${(rule.split("/").at(-1) ?? rule).replace(UNSAFE_FILE_CHARS, "-")}.txt`;
+};
+const groupDiagnosticsByRule = (diagnostics) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const diagnostic of diagnostics) {
+		const group = groups.get(diagnostic.rule);
+		if (group) group.push(diagnostic);
+		else groups.set(diagnostic.rule, [diagnostic]);
+	}
+	return groups;
+};
+const writeDiagnosticsDirectory = async (diagnostics, report, rootDir) => {
+	const dir = node_path.default.join(rootDir, DIAGNOSTICS_DIR_NAME);
+	await node_fs_promises.default.rm(dir, {
+		force: true,
+		recursive: true
+	});
+	await node_fs_promises.default.mkdir(dir, { recursive: true });
+	await node_fs_promises.default.writeFile(node_path.default.join(dir, "diagnostics.json"), JSON.stringify(report, null, 2), "utf-8");
+	const writes = [];
+	for (const [rule, ruleDiagnostics] of groupDiagnosticsByRule(diagnostics)) {
+		const [first] = ruleDiagnostics;
+		const lines = [
+			`${rule} (${first.severity})`,
+			first.message,
+			`Fix: ${first.help}`,
+			"",
+			...ruleDiagnostics.map((d) => `${d.file}${d.line === void 0 ? "" : `:${d.line}`}`),
+			""
+		];
+		writes.push(node_fs_promises.default.writeFile(node_path.default.join(dir, ruleFileName(rule)), lines.join("\n"), "utf-8"));
+	}
+	await Promise.all(writes);
+};
+const ensureGitignoreEntry = async (rootDir) => {
+	const gitignorePath = node_path.default.join(rootDir, ".gitignore");
+	let existing = null;
+	try {
+		existing = await node_fs_promises.default.readFile(gitignorePath, "utf-8");
+	} catch {
+		existing = null;
+	}
+	if (existing !== null) {
+		if (existing.split(/\r?\n/u).some((line) => [
+			".docker-doctor",
+			`${".docker-doctor"}/`,
+			`/${".docker-doctor"}`,
+			`/${".docker-doctor"}/`
+		].includes(line.trim()))) return;
+		const separator = existing.endsWith("\n") || existing === "" ? "" : "\n";
+		await node_fs_promises.default.writeFile(gitignorePath, `${existing}${separator}${DIAGNOSTICS_DIR_NAME}/\n`, "utf-8");
+		return;
+	}
+	try {
+		await node_fs_promises.default.access(node_path.default.join(rootDir, ".git"));
+	} catch {
+		return;
+	}
+	await node_fs_promises.default.writeFile(gitignorePath, `${DIAGNOSTICS_DIR_NAME}/\n`, "utf-8");
+};
+
+//#endregion
+//#region src/agents/handoff-payload.ts
+const MAX_FILES_PER_RULE = 5;
+const SEVERITY_RANK = {
+	error: 0,
+	info: 2,
+	warning: 1
+};
+const SEVERITY_LABEL = {
+	error: "ERROR",
+	info: "INFO",
+	warning: "WARN"
+};
+const buildHandoffPayload = (input) => {
+	const groups = [...groupDiagnosticsByRule(input.diagnostics).entries()].toSorted(([, a], [, b]) => {
+		const rankDelta = SEVERITY_RANK[a[0].severity] - SEVERITY_RANK[b[0].severity];
+		return rankDelta === 0 ? b.length - a.length : rankDelta;
+	});
+	const issueWord = groups.length === 1 ? "issue" : "issues";
+	const lines = [`Fix the ${groups.length} Docker Doctor ${issueWord} in ${input.projectName}.`, ""];
+	for (const [index, [rule, ruleDiagnostics]] of groups.entries()) {
+		const [first] = ruleDiagnostics;
+		const category = require_src.findRule(rule)?.category ?? "General";
+		const countBadge = ruleDiagnostics.length > 1 ? ` (×${ruleDiagnostics.length})` : "";
+		lines.push(`${index + 1}. ${SEVERITY_LABEL[first.severity]} ${category}: ${first.message} [${rule}]${countBadge}`, `   Fix: ${first.help}`);
+		const files = [...new Set(ruleDiagnostics.map((d) => d.file))];
+		for (const file of files.slice(0, MAX_FILES_PER_RULE)) {
+			const firstSite = ruleDiagnostics.find((d) => d.file === file && d.line !== void 0);
+			lines.push(`   - ${file}${firstSite ? `:${firstSite.line}` : ""}`);
+		}
+		const remaining = files.length - MAX_FILES_PER_RULE;
+		if (remaining > 0) lines.push(`   - +${remaining} more files`);
+	}
+	lines.push("", `Full report (diagnostics.json + a .txt per rule): ${DIAGNOSTICS_DIR_NAME}/`, "", "Read each file and fix the root cause — don't suppress or silence the rule.", "When you're done, re-run `npx @docker-doctor/cli@latest .` and confirm the score improved and no errors remain.");
+	return lines.join("\n");
+};
+
+//#endregion
+//#region src/agents/is-command-available.ts
+const WINDOWS_EXTENSIONS = [
+	".exe",
+	".cmd",
+	".bat"
+];
+const isCommandAvailable = (command) => {
+	const pathValue = process.env.PATH ?? "";
+	const extensions = process.platform === "win32" ? WINDOWS_EXTENSIONS : [""];
+	for (const dir of pathValue.split(node_path.default.delimiter)) {
+		if (dir === "") continue;
+		for (const extension of extensions) try {
+			node_fs.default.accessSync(node_path.default.join(dir, command + extension), node_fs.default.constants.X_OK);
+			return true;
+		} catch {}
+	}
+	return false;
+};
+
+//#endregion
+//#region src/agents/launchable-agents.ts
+const LAUNCHABLE_AGENT_IDS = [
+	"claude-code",
+	"codex",
+	"cursor"
+];
+const AGENT_BINARIES = {
+	"claude-code": "claude",
+	codex: "codex",
+	cursor: "cursor-agent"
+};
+const AGENT_AUTO_FLAGS = {
+	"claude-code": ["--dangerously-skip-permissions"],
+	codex: ["--yolo"],
+	cursor: ["--force"]
+};
+const detectLaunchableAgents = () => {
+	if (process.platform === "win32") return [];
+	return LAUNCHABLE_AGENT_IDS.filter((agentId) => isCommandAvailable(AGENT_BINARIES[agentId]));
+};
+
+//#endregion
+//#region src/agents/launch-agent.ts
+const launchAgent = (agentId, prompt) => new Promise((resolve) => {
+	const child = (0, node_child_process.spawn)(AGENT_BINARIES[agentId], [...AGENT_AUTO_FLAGS[agentId], prompt], { stdio: "inherit" });
+	child.once("error", () => {
+		resolve(false);
+	});
+	child.once("exit", () => {
+		resolve(true);
+	});
+});
+
+//#endregion
+//#region src/agents/skill-install.ts
+const moduleDir = __dirname;
+const getSkillSourceDirectory = () => {
+	const candidates = [node_path.default.resolve(moduleDir, "../skill/docker-doctor"), node_path.default.resolve(moduleDir, "../../../../skills/docker-doctor")];
+	for (const candidate of candidates) if (node_fs.default.existsSync(node_path.default.join(candidate, agent_install.SKILL_MANIFEST_FILE))) return candidate;
+	return null;
+};
+const installSkillForAgents = async (agents, projectRoot) => {
+	const source = getSkillSourceDirectory();
+	if (!source) return null;
+	try {
+		return await (0, agent_install.installSkillsFromSource)({
+			agents,
+			cwd: projectRoot,
+			mode: "copy",
+			source
+		});
+	} catch {
+		return null;
+	}
+};
+
 //#endregion
 //#region src/formatters/terminal.ts
 const printCodeFrame = (content, line, severityColor) => {
@@ -696,37 +928,131 @@ const askSelect = (question, options, defaultIndex = 0) => {
 		process.stdin.on("keypress", handleKeypress);
 	});
 };
-const runInteractiveWizard = async () => {
+const askMultiSelect = (question, options) => {
+	if (!process.stdin.isTTY) return Promise.resolve(options.flatMap((option, i) => option.selected ? [i] : []));
+	return new Promise((resolve) => {
+		let index = 0;
+		const selected = options.map((option) => option.selected);
+		const lineCount = options.length + 2;
+		node_readline.default.emitKeypressEvents(process.stdin);
+		process.stdin.setRawMode(true);
+		process.stdin.resume();
+		process.stdout.write("\x1B[?25l");
+		const render = (firstTime = false) => {
+			if (!firstTime) process.stdout.write(`\u001B[${lineCount}A\r`);
+			process.stdout.write(`\r\u001B[K  ${chalk.green("✔")} ${chalk.bold(question)}\n`);
+			let i = 0;
+			for (const option of options) {
+				const isCursor = i === index;
+				const cursor = isCursor ? chalk.cyan("❯ ") : "  ";
+				const box = selected[i] ? chalk.cyan("[x]") : chalk.dim("[ ]");
+				let text = chalk.dim(option.label);
+				if (isCursor) text = chalk.cyan.bold(option.label);
+				else if (selected[i]) text = option.label;
+				process.stdout.write(`\r\u001B[K${cursor}${box} ${text}\n`);
+				i += 1;
+			}
+			process.stdout.write(`\r\u001B[K  ${chalk.dim("space to toggle · enter to confirm")}\n`);
+		};
+		render(true);
+		const handleKeypress = (str, key) => {
+			const cleanup = () => {
+				process.stdin.removeListener("keypress", handleKeypress);
+				if (process.stdin.isTTY) process.stdin.setRawMode(false);
+				process.stdin.pause();
+				process.stdout.write("\x1B[?25h");
+			};
+			if (key.name === "up" || key.name === "k") {
+				index = (index - 1 + options.length) % options.length;
+				render();
+			} else if (key.name === "down" || key.name === "j") {
+				index = (index + 1) % options.length;
+				render();
+			} else if (key.name === "space" || str === " ") {
+				selected[index] = !selected[index];
+				render();
+			} else if (key.name === "return" || key.name === "enter" || str === "\r" || str === "\n") {
+				cleanup();
+				const chosen = options.flatMap((option, i) => selected[i] ? [option.label] : []);
+				process.stdout.write(`\u001B[${lineCount}A\r\u001B[K`);
+				process.stdout.write(`  ${chalk.green("✔")} ${chalk.bold(question)} › ${chosen.length > 0 ? chalk.cyan(chosen.join(", ")) : chalk.dim("none")}\n`);
+				for (let i = 0; i < lineCount - 1; i += 1) process.stdout.write("\r\x1B[K\n");
+				process.stdout.write(`\u001B[${lineCount - 1}A`);
+				resolve(options.flatMap((_, i) => selected[i] ? [i] : []));
+			} else if (key.ctrl && key.name === "c") {
+				cleanup();
+				process.stdout.write("\n");
+				process.exit(130);
+			}
+		};
+		process.stdin.on("keypress", handleKeypress);
+	});
+};
+const printAgentPrompt = (payload) => {
+	console.log(`\n${chalk.dim("──── Agent prompt ────")}`);
+	console.log(payload);
+	console.log(chalk.dim("──────────────────────"));
+};
+const agentDisplayName = (agent) => agent === "universal" ? "Universal" : (0, agent_install.getSkillAgentConfig)(agent).displayName;
+const runAgentHandoff = async (context) => {
+	const launchable = detectLaunchableAgents();
+	const options = [
+		...launchable.map((agentId) => agentDisplayName(agentId)),
+		"Copy prompt to clipboard",
+		"Skip"
+	];
+	const skipIndex = options.length - 1;
+	const clipboardIndex = options.length - 2;
+	const choice = await askSelect("What would you like to do next?", options);
+	if (choice === skipIndex) return;
+	await writeDiagnosticsDirectory(context.diagnostics, context.report, context.rootDir);
+	await ensureGitignoreEntry(context.rootDir);
+	const payload = buildHandoffPayload({
+		diagnostics: context.diagnostics,
+		projectName: node_path.default.basename(context.rootDir)
+	});
+	if (choice === clipboardIndex) {
+		if (await copyToClipboard(payload)) console.log(`\n  ${chalk.green("✔")} Prompt copied — paste it into any agent or chat.`);
+		else printAgentPrompt(payload);
+		return;
+	}
+	const agentId = launchable[choice];
+	const installResult = await installSkillForAgents([agentId], context.rootDir);
+	if (installResult && installResult.installed.length > 0) console.log(`\n  ${chalk.green("✔")} Installed the docker-doctor skill for ${agentDisplayName(agentId)}`);
+	console.log(`\n  Handing off to ${agentDisplayName(agentId)}...\n`);
+	if (!await launchAgent(agentId, payload)) {
+		console.log(`  ${chalk.yellow("⚠")} Couldn't launch ${AGENT_BINARIES[agentId]}. Here's the prompt instead:`);
+		printAgentPrompt(payload);
+	}
+};
+const runInteractiveWizard = async (context) => {
 	try {
 		if (await askConfirm("Add Docker Doctor to GitHub Actions?")) {
 			const workflowDir = node_path.default.resolve(".github/workflows");
 			await node_fs_promises.default.mkdir(workflowDir, { recursive: true });
 			const workflowPath = node_path.default.join(workflowDir, "docker-doctor.yml");
-			await node_fs_promises.default.writeFile(workflowPath, `name: Docker Doctor Scan
+			const [actionMajor] = require_src.package_default.version.split(".");
+			const workflowYaml = `name: Docker Doctor
 on:
-  push:
-    branches: [ main, master ]
   pull_request:
-    branches: [ main, master ]
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
 jobs:
   docker-doctor:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-      - name: Install dependencies
-        run: bun install
-      - name: Run docker-doctor
-        run: bunx docker-doctor .
-`, "utf-8");
+      - uses: actions/checkout@v5
+      - uses: PunGrumpy/docker-doctor@v${actionMajor}
+`;
+			await node_fs_promises.default.writeFile(workflowPath, workflowYaml, "utf-8");
 			console.log(`\n  ${chalk.green("✨")} Created ${chalk.cyan(".github/workflows/docker-doctor.yml")}!`);
-			console.log(`    Scan every pull request to prevent new Docker issues while you fix the backlog.`);
-		}
-		if (await askSelect("What would you like to do next?", ["View rules list", "Skip"]) === 0) {
-			console.log(`\n  ${chalk.bold("Available Rules:")}`);
-			for (const r of require_src.allRules) console.log(`    - ${chalk.cyan(r.key)}: ${r.message} (${chalk.dim(r.category)})`);
+			console.log(`    Every pull request gets a scan and a sticky summary comment — advisory by default.`);
+			console.log(`    Inputs and gating: ${chalk.cyan("https://docker-doctor.vercel.app/docs/guides/github-actions")}`);
 		}
+		if (context.diagnostics.length === 0) return;
+		await runAgentHandoff(context);
 	} catch {}
 };
 const runRulesEngine = async (rootDir, project, rulesConfig, projectFilesList, fileContents, options, setStatus) => {
@@ -859,7 +1185,11 @@ program.argument("[dir]", "directory to scan", ".").option("-v, --verbose", "sho
 			}
 			await formatTerminal(filteredDiagnostics, score, label, project, options.verbose, fileContents);
 			const hasErrors = filteredDiagnostics.some((d) => d.severity === "error");
-			if (process.stdout.isTTY && process.stdin.isTTY) await runInteractiveWizard();
+			if (process.stdout.isTTY && process.stdin.isTTY) await runInteractiveWizard({
+				diagnostics: filteredDiagnostics,
+				report: require_src.toJsonReport(filteredDiagnostics, score, label, project),
+				rootDir
+			});
 			process.exitCode = hasErrors ? 1 : 0;
 		} finally {
 			if (spinnerInterval !== null) {
@@ -873,6 +1203,55 @@ program.argument("[dir]", "directory to scan", ".").option("-v, --verbose", "sho
 		process.exit(1);
 	}
 });
+const CURATED_INSTALL_AGENTS = [
+	"claude-code",
+	"codex",
+	"cursor",
+	"opencode"
+];
+const resolveInstallAgents = async (requested) => {
+	if (requested && requested.length > 0) {
+		const invalid = requested.filter((agent) => !(0, agent_install.isSkillAgentType)(agent));
+		if (invalid.length > 0) {
+			console.error(`Unknown agent id(s): ${invalid.join(", ")}`);
+			console.error(`Valid ids: ${(0, agent_install.getSkillAgentTypes)().filter((agent) => agent !== "universal").join(", ")}`);
+			return null;
+		}
+		return requested.filter((agent) => (0, agent_install.isSkillAgentType)(agent));
+	}
+	if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+		console.error("Non-interactive run: pass --agent <id...> (e.g. --agent claude-code cursor).");
+		return null;
+	}
+	const detected = (await (0, agent_install.detectInstalledSkillAgents)()).filter((agent) => agent !== "universal");
+	const choices = [.../* @__PURE__ */ new Set([...detected, ...CURATED_INSTALL_AGENTS])];
+	const detectedSet = new Set(detected);
+	return (await askMultiSelect("Which coding agents should get the docker-doctor skill?", choices.map((agent) => ({
+		label: agentDisplayName(agent),
+		selected: detectedSet.has(agent)
+	})))).map((i) => choices[i]);
+};
+program.command("install").description("install the Docker Doctor agent skill for your coding agents").option("-a, --agent <agents...>", "agent id(s) to install for (e.g. claude-code codex cursor)").action(async (options) => {
+	if (!getSkillSourceDirectory()) {
+		console.error("Bundled skill not found — this looks like a broken installation.");
+		process.exit(1);
+	}
+	const agents = await resolveInstallAgents(options.agent);
+	if (agents === null) process.exit(1);
+	if (agents.length === 0) {
+		console.log("Nothing selected — skipped.");
+		return;
+	}
+	const result = await installSkillForAgents(agents, process.cwd());
+	if (!result) {
+		console.error("Failed to install the skill.");
+		process.exit(1);
+	}
+	for (const installed of result.installed) console.log(`  ${chalk.green("✔")} ${agentDisplayName(installed.agent)} → ${installed.path}`);
+	for (const failed of result.failed) console.log(`  ${chalk.red("✖")} ${agentDisplayName(failed.agent)}: ${failed.error}`);
+	if (result.installed.length > 0) console.log(`\n  The agent can now run ${chalk.cyan("/docker-doctor")} to scan and triage this project.`);
+	process.exitCode = result.failed.length > 0 ? 1 : 0;
+});
 const rules = program.command("rules").description("manage and list configuration rules");
 rules.command("list").description("list all available rules").action(() => {
 	console.log("\nAvailable Rules:");