rulesync 16.2.0 → 16.3.0

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as ErrorCodes, $t as RULESYNC_SKILLS_RELATIVE_DIR_PATH, A as RulesyncMcp, At as RULESYNC_AIIGNORE_RELATIVE_FILE_PATH, B as stringifyFrontmatter, Bt as RULESYNC_IGNORE_RELATIVE_FILE_PATH, C as RulesyncSubagent, Ct as writeFileContent, D as RulesyncRule, Dt as ToolTargetSchema, E as RulesyncSkillFrontmatterSchema, Et as PACKAGING_TOOL_TARGETS, F as parseJsonc, Ft as RULESYNC_CURATED_RULES_RELATIVE_DIR_PATH, G as ConfigFileSchema, Gt as RULESYNC_MCP_SCHEMA_URL, H as SHARED_USER_MANAGED_CONFIG_PATHS, Ht as RULESYNC_MCP_FILE_NAME, I as RulesyncCommand, It as RULESYNC_CURATED_SKILLS_RELATIVE_DIR_PATH, J as ConsoleLogger, Jt as RULESYNC_PERMISSIONS_LEGACY_FILE_NAME, K as SourceEntrySchema, Kt as RULESYNC_NPM_SOURCES_LOCK_RELATIVE_FILE_PATH, L as RulesyncCommandFrontmatterSchema, Lt as RULESYNC_HOOKS_FILE_NAME, M as RulesyncHooks, Mt as RULESYNC_COMMANDS_RELATIVE_DIR_PATH, N as getRulesyncSourceCandidates, Nt as RULESYNC_CONFIG_RELATIVE_FILE_PATH, O as RulesyncRuleFrontmatterSchema, Ot as MAX_FILE_SIZE, P as resolveRulesyncSourceWritePath, Pt as RULESYNC_CONFIG_SCHEMA_URL, Q as CLIError, Qt as RULESYNC_RULES_RELATIVE_DIR_PATH, R as RulesyncCheck, Rt as RULESYNC_HOOKS_LEGACY_FILE_NAME, S as getLocalSkillDirNames, St as toPosixPath, T as RulesyncSkill, Tt as ALL_TOOL_TARGETS_WITH_WILDCARD, U as SKILL_FILE_NAME$1, Ut as RULESYNC_MCP_LEGACY_FILE_NAME, V as loadYaml, Vt as RULESYNC_LOCAL_CONFIG_RELATIVE_FILE_PATH, W as ConfigResolver, Wt as RULESYNC_MCP_RELATIVE_FILE_PATH, X as fallbackLogger, Xt as RULESYNC_PERMISSIONS_SCHEMA_URL, Y as JsonLogger, Yt as RULESYNC_PERMISSIONS_RELATIVE_FILE_PATH, Z as warnOnConflictingFlags, Zt as RULESYNC_RELATIVE_DIR_PATH, _ as CLAUDECODE_SETTINGS_LOCAL_FILE_NAME, _t as removeFile, a as convertFromTool, at as directoryExists, b as CODEXCLI_BASH_RULES_FILE_NAME, bt as resolvePath, c as SubagentsProcessor, ct as findFilesByGlobs, d as IgnoreProcessor, dt as isSymlink, en as RULESYNC_SOURCES_LOCK_RELATIVE_FILE_PATH, et as assertDirectoryIfExists, f as HooksProcessor, ft as listDirectoryFiles, g as CLAUDECODE_MEMORIES_DIR_NAME, gt as removeDirectoryStrict, h as CLAUDECODE_LOCAL_RULE_FILE_NAME, ht as removeDirectory, i as getProcessorRegistryEntry, in as formatError, it as createTempDirectory, j as RulesyncIgnore, jt as RULESYNC_CHECKS_RELATIVE_DIR_PATH, k as RulesyncPermissions, kt as RULESYNC_AIIGNORE_FILE_NAME, l as SkillsProcessor, lt as getFileSize, m as CLAUDECODE_DIR, mt as readFileContentOrNull, n as checkRulesyncDirExists, nn as ALL_FEATURES, nt as assertWritablePathInsideRoot, o as isPackagingToolTarget, ot as ensureDir, p as CommandsProcessor, pt as readFileContent, q as findControlCharacter, qt as RULESYNC_PERMISSIONS_FILE_NAME, r as generate, rn as ALL_FEATURES_WITH_WILDCARD, rt as checkPathTraversal, s as RulesProcessor, st as fileExists, t as importFromTool, tn as RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, tt as assertTreeContainsNoSymlinks, u as McpProcessor, ut as getHomeDirectory, v as CLAUDECODE_SKILLS_DIR_PATH, vt as removeFileStrict, w as RulesyncSubagentFrontmatterSchema, wt as ALL_TOOL_TARGETS, x as CODEXCLI_DIR, xt as runWithDirectoryRollback, y as ChecksProcessor, yt as removeTempDirectory, z as RulesyncCheckFrontmatterSchema, zt as RULESYNC_HOOKS_RELATIVE_FILE_PATH } from "../import-CArKOPG_.js";
+import { $ as warnOnConflictingFlags, $t as RULESYNC_RELATIVE_DIR_PATH, A as RulesyncMcp, At as MAX_FILE_SIZE, B as stringifyFrontmatter, Bt as RULESYNC_HOOKS_LEGACY_FILE_NAME, C as RulesyncSubagent, Ct as runWithDirectoryRollback, D as RulesyncRule, Dt as ALL_TOOL_TARGETS_WITH_WILDCARD, E as RulesyncSkillFrontmatterSchema, Et as ALL_TOOL_TARGETS, F as parseJsonc, Ft as RULESYNC_CONFIG_RELATIVE_FILE_PATH, G as CONFLICTING_TARGET_PAIRS, Gt as RULESYNC_MCP_LEGACY_FILE_NAME, H as SHARED_USER_MANAGED_CONFIG_PATHS, Ht as RULESYNC_IGNORE_RELATIVE_FILE_PATH, I as RulesyncCommand, It as RULESYNC_CONFIG_SCHEMA_URL, J as SourceEntrySchema, Jt as RULESYNC_NPM_SOURCES_LOCK_RELATIVE_FILE_PATH, K as ConfigFileSchema, Kt as RULESYNC_MCP_RELATIVE_FILE_PATH, L as RulesyncCommandFrontmatterSchema, Lt as RULESYNC_CURATED_RULES_RELATIVE_DIR_PATH, M as RulesyncHooks, Mt as RULESYNC_AIIGNORE_RELATIVE_FILE_PATH, N as getRulesyncSourceCandidates, Nt as RULESYNC_CHECKS_RELATIVE_DIR_PATH, O as RulesyncRuleFrontmatterSchema, Ot as PACKAGING_TOOL_TARGETS, P as resolveRulesyncSourceWritePath, Pt as RULESYNC_COMMANDS_RELATIVE_DIR_PATH, Q as fallbackLogger, Qt as RULESYNC_PERMISSIONS_SCHEMA_URL, R as RulesyncCheck, Rt as RULESYNC_CURATED_SKILLS_RELATIVE_DIR_PATH, S as getLocalSkillDirNames, St as resolvePath, T as RulesyncSkill, Tt as writeFileContent, U as SKILL_FILE_NAME$1, Ut as RULESYNC_LOCAL_CONFIG_RELATIVE_FILE_PATH, V as loadYaml, Vt as RULESYNC_HOOKS_RELATIVE_FILE_PATH, W as ConfigResolver, Wt as RULESYNC_MCP_FILE_NAME, X as ConsoleLogger, Xt as RULESYNC_PERMISSIONS_LEGACY_FILE_NAME, Y as findControlCharacter, Yt as RULESYNC_PERMISSIONS_FILE_NAME, Z as JsonLogger, Zt as RULESYNC_PERMISSIONS_RELATIVE_FILE_PATH, _ as CLAUDECODE_SETTINGS_LOCAL_FILE_NAME, _t as removeDirectory, a as convertFromTool, an as ALL_FEATURES_WITH_WILDCARD, at as checkPathTraversal, b as CODEXCLI_BASH_RULES_FILE_NAME, bt as removeFileStrict, c as SubagentsProcessor, ct as ensureDir, d as IgnoreProcessor, dt as getFileSize, en as RULESYNC_RULES_RELATIVE_DIR_PATH, et as CLIError, f as HooksProcessor, ft as getHomeDirectory, g as CLAUDECODE_MEMORIES_DIR_NAME, gt as readFileContentOrNull, h as CLAUDECODE_LOCAL_RULE_FILE_NAME, ht as readFileContent, i as getProcessorRegistryEntry, in as ALL_FEATURES, it as assertWritablePathInsideRoot, j as RulesyncIgnore, jt as RULESYNC_AIIGNORE_FILE_NAME, k as RulesyncPermissions, kt as ToolTargetSchema, l as SkillsProcessor, lt as fileExists, m as CLAUDECODE_DIR, mt as listDirectoryFiles, n as checkRulesyncDirExists, nn as RULESYNC_SOURCES_LOCK_RELATIVE_FILE_PATH, nt as assertDirectoryIfExists, o as isPackagingToolTarget, on as DEPRECATED_FEATURE_REPLACEMENTS, ot as createTempDirectory, p as CommandsProcessor, pt as isSymlink, q as GITIGNORE_DESTINATION_KEY, qt as RULESYNC_MCP_SCHEMA_URL, r as generate, rn as RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH, rt as assertTreeContainsNoSymlinks, s as RulesProcessor, sn as formatError, st as directoryExists, t as importFromTool, tn as RULESYNC_SKILLS_RELATIVE_DIR_PATH, tt as ErrorCodes, u as McpProcessor, ut as findFilesByGlobs, v as CLAUDECODE_SKILLS_DIR_PATH, vt as removeDirectoryStrict, w as RulesyncSubagentFrontmatterSchema, wt as toPosixPath, x as CODEXCLI_DIR, xt as removeTempDirectory, y as ChecksProcessor, yt as removeFile, z as RulesyncCheckFrontmatterSchema, zt as RULESYNC_HOOKS_FILE_NAME } from "../import-Bj5HxY9p.js";
 import { Command } from "commander";
 import { nonnegative, optional, refine, z } from "zod/mini";
 import { cp, mkdtemp, realpath, rm } from "node:fs/promises";
@@ -3860,6 +3860,564 @@ async function convertCommand(logger, options) {
 	else logger.success(summary);
 }
 //#endregion
+//#region src/cli/commands/doctor.ts
+/** Per-feature object form also accepts a gitignore destination override. */
+const PER_FEATURE_EXTRA_KEYS = [GITIGNORE_DESTINATION_KEY];
+const KNOWN_CONFIG_KEYS = Object.keys(ConfigFileSchema.shape);
+/**
+* Classic dynamic-programming Levenshtein distance; inputs are short config
+* keys and tool names, so the O(a.b) cost is negligible.
+*/
+function levenshteinDistance({ a, b }) {
+	const rows = a.length + 1;
+	const cols = b.length + 1;
+	let previous = Array.from({ length: cols }, (_, i) => i);
+	for (let i = 1; i < rows; i++) {
+		const current = [i, ...Array.from({ length: cols - 1 }, () => 0)];
+		for (let j = 1; j < cols; j++) {
+			const substitutionCost = a[i - 1] === b[j - 1] ? 0 : 1;
+			current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, (previous[j - 1] ?? 0) + substitutionCost);
+		}
+		previous = current;
+	}
+	return previous[cols - 1] ?? 0;
+}
+/**
+* Returns the closest candidate to `input`, or undefined when nothing is close
+* enough to be a plausible typo. The threshold scales with input length so
+* short keys don't produce far-fetched suggestions.
+*/
+function suggestNearest({ input, candidates }) {
+	const maxDistance = Math.max(2, Math.floor(input.length / 3));
+	let best;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const candidate of candidates) {
+		const distance = levenshteinDistance({
+			a: input.toLowerCase(),
+			b: candidate.toLowerCase()
+		});
+		if (distance < bestDistance) {
+			bestDistance = distance;
+			best = candidate;
+		}
+	}
+	return bestDistance <= maxDistance ? best : void 0;
+}
+function didYouMean({ input, candidates }) {
+	const suggestion = suggestNearest({
+		input,
+		candidates
+	});
+	return suggestion === void 0 ? void 0 : `Did you mean '${suggestion}'?`;
+}
+/** Converts a character offset into a 1-based line/column pair. */
+function offsetToPosition({ content, offset }) {
+	let line = 1;
+	let lineStart = 0;
+	const end = Math.min(offset, content.length);
+	for (let i = 0; i < end; i++) if (content[i] === "\n") {
+		line++;
+		lineStart = i + 1;
+	}
+	return {
+		line,
+		column: end - lineStart + 1
+	};
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function checkTargetName({ name, file, context }) {
+	if (ALL_TOOL_TARGETS.includes(name)) return void 0;
+	return {
+		severity: "error",
+		code: "config/unknown-target",
+		file,
+		message: `Unknown tool target '${name}' in ${context}.`,
+		hint: didYouMean({
+			input: name,
+			candidates: ALL_TOOL_TARGETS
+		}) ?? `Valid targets: ${ALL_TOOL_TARGETS.join(", ")}.`
+	};
+}
+function checkFeatureName({ name, file, context }) {
+	const replacement = DEPRECATED_FEATURE_REPLACEMENTS[name];
+	if (replacement !== void 0) return {
+		severity: "warning",
+		code: "config/deprecated-feature",
+		file,
+		message: `Feature '${name}' in ${context} is deprecated.`,
+		hint: `Use the '${replacement}' feature instead.`
+	};
+	if (ALL_FEATURES.includes(name)) return void 0;
+	return {
+		severity: "error",
+		code: "config/unknown-feature",
+		file,
+		message: `Unknown feature '${name}' in ${context}.`,
+		hint: didYouMean({
+			input: name,
+			candidates: ALL_FEATURES
+		}) ?? `Valid features: ${ALL_FEATURES.join(", ")}.`
+	};
+}
+function checkTargetsValue({ targets, file }) {
+	const diagnostics = [];
+	if (Array.isArray(targets)) {
+		for (const entry of targets) {
+			if (typeof entry !== "string") {
+				diagnostics.push({
+					severity: "error",
+					code: "config/invalid-value",
+					file,
+					message: `'targets' entries must be strings, found ${JSON.stringify(entry)}.`
+				});
+				continue;
+			}
+			if (entry === "*") continue;
+			const diagnostic = checkTargetName({
+				name: entry,
+				file,
+				context: "'targets'"
+			});
+			if (diagnostic) diagnostics.push(diagnostic);
+		}
+		return diagnostics;
+	}
+	if (isPlainObject(targets)) {
+		for (const [key, value] of Object.entries(targets)) {
+			if (key === "*") {
+				diagnostics.push({
+					severity: "error",
+					code: "config/invalid-value",
+					file,
+					message: "Wildcard '*' is not supported as a key in the object form of 'targets'; per-target options cannot be attached to a wildcard.",
+					hint: "Use the array form `\"targets\": [\"*\"]` instead."
+				});
+				continue;
+			}
+			const diagnostic = checkTargetName({
+				name: key,
+				file,
+				context: "the 'targets' object"
+			});
+			if (diagnostic) {
+				diagnostics.push(diagnostic);
+				continue;
+			}
+			diagnostics.push(...checkPerTargetFeaturesValue({
+				target: key,
+				value,
+				file
+			}));
+		}
+		return diagnostics;
+	}
+	if (targets !== void 0) diagnostics.push({
+		severity: "error",
+		code: "config/invalid-value",
+		file,
+		message: `'targets' must be an array of tool names or a per-target object, found ${JSON.stringify(targets)}.`
+	});
+	return diagnostics;
+}
+function checkPerTargetFeaturesValue({ target, value, file }) {
+	const diagnostics = [];
+	if (Array.isArray(value)) {
+		for (const entry of value) {
+			if (typeof entry !== "string") {
+				diagnostics.push({
+					severity: "error",
+					code: "config/invalid-value",
+					file,
+					message: `Features for target '${target}' must be strings, found ${JSON.stringify(entry)}.`
+				});
+				continue;
+			}
+			if (entry === "*") continue;
+			const diagnostic = checkFeatureName({
+				name: entry,
+				file,
+				context: `'targets.${target}'`
+			});
+			if (diagnostic) diagnostics.push(diagnostic);
+		}
+		return diagnostics;
+	}
+	if (isPlainObject(value)) {
+		for (const key of Object.keys(value)) {
+			if (key === "*" || PER_FEATURE_EXTRA_KEYS.includes(key)) continue;
+			const diagnostic = checkFeatureName({
+				name: key,
+				file,
+				context: `'targets.${target}'`
+			});
+			if (diagnostic) diagnostics.push(diagnostic);
+		}
+		return diagnostics;
+	}
+	diagnostics.push({
+		severity: "error",
+		code: "config/invalid-value",
+		file,
+		message: `Value for target '${target}' must be a feature array or a per-feature object, found ${JSON.stringify(value)}.`
+	});
+	return diagnostics;
+}
+function checkFeaturesValue({ features, file }) {
+	const diagnostics = [];
+	if (features === void 0) return diagnostics;
+	if (!Array.isArray(features)) {
+		diagnostics.push({
+			severity: "error",
+			code: "config/invalid-value",
+			file,
+			message: `'features' must be an array of feature names, found ${JSON.stringify(features)}.`,
+			hint: "To configure features per target, use the object form of 'targets' instead."
+		});
+		return diagnostics;
+	}
+	for (const entry of features) {
+		if (typeof entry !== "string") {
+			diagnostics.push({
+				severity: "error",
+				code: "config/invalid-value",
+				file,
+				message: `'features' entries must be strings, found ${JSON.stringify(entry)}.`
+			});
+			continue;
+		}
+		if (entry === "*") continue;
+		const diagnostic = checkFeatureName({
+			name: entry,
+			file,
+			context: "'features'"
+		});
+		if (diagnostic) diagnostics.push(diagnostic);
+	}
+	return diagnostics;
+}
+function checkConflictingTargets({ targets, file }) {
+	const has = (target) => {
+		if (Array.isArray(targets)) return targets.includes(target);
+		if (isPlainObject(targets)) return Object.prototype.hasOwnProperty.call(targets, target);
+		return false;
+	};
+	const diagnostics = [];
+	for (const [target1, target2] of CONFLICTING_TARGET_PAIRS) if (has(target1) && has(target2)) diagnostics.push({
+		severity: "error",
+		code: "config/conflicting-targets",
+		file,
+		message: `Targets '${target1}' and '${target2}' cannot be used together.`,
+		hint: "Remove one of the two from 'targets'."
+	});
+	return diagnostics;
+}
+function checkSchemaProperty({ config, file }) {
+	const schema = config.$schema;
+	if (schema === void 0) return [{
+		severity: "info",
+		code: "config/missing-schema",
+		file,
+		message: "No '$schema' property; editors cannot offer completion and validation.",
+		hint: `Add "$schema": "${RULESYNC_CONFIG_SCHEMA_URL}".`
+	}];
+	if (typeof schema === "string" && schema !== "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json") return [{
+		severity: "warning",
+		code: "config/outdated-schema",
+		file,
+		message: `'$schema' does not point at the current rulesync config schema.`,
+		hint: `Update it to "${RULESYNC_CONFIG_SCHEMA_URL}".`
+	}];
+	return [];
+}
+function checkUnknownTopLevelKeys({ config, file }) {
+	const diagnostics = [];
+	for (const key of Object.keys(config)) {
+		if (KNOWN_CONFIG_KEYS.includes(key)) continue;
+		diagnostics.push({
+			severity: "error",
+			code: "config/unknown-key",
+			file,
+			message: `Unknown key '${key}'. It is silently ignored by 'rulesync generate'.`,
+			hint: didYouMean({
+				input: key,
+				candidates: KNOWN_CONFIG_KEYS
+			}) ?? `Known keys: ${KNOWN_CONFIG_KEYS.join(", ")}.`
+		});
+	}
+	return diagnostics;
+}
+function checkTargetsFeaturesExclusivity({ config, file }) {
+	if (!isPlainObject(config.targets) || config.features === void 0) return [];
+	return [{
+		severity: "error",
+		code: "config/targets-features-conflict",
+		file,
+		message: "When 'targets' is in object form, 'features' must be omitted.",
+		hint: "Declare per-target features inside the 'targets' object instead."
+	}];
+}
+function checkTokenEnvVars({ config, file, env }) {
+	if (!Array.isArray(config.sources)) return [];
+	const diagnostics = [];
+	for (const source of config.sources) {
+		if (!isPlainObject(source)) continue;
+		const tokenEnv = source.tokenEnv;
+		if (typeof tokenEnv !== "string" || tokenEnv.length === 0) continue;
+		if (env[tokenEnv] === void 0 || env[tokenEnv] === "") diagnostics.push({
+			severity: "warning",
+			code: "config/token-env-not-set",
+			file,
+			message: `Source '${String(source.source ?? "<unnamed>")}' references environment variable '${tokenEnv}', which is not set.`,
+			hint: `Export ${tokenEnv} before running commands that fetch from this source.`
+		});
+	}
+	return diagnostics;
+}
+/**
+* Structural validation via the same Zod schema `ConfigResolver` uses.
+* `targets` / `features` issues are skipped because the dedicated checks above
+* already reported them with better messages and suggestions.
+*/
+function checkAgainstConfigFileSchema({ config, file }) {
+	const result = ConfigFileSchema.safeParse(config);
+	if (result.success) return [];
+	const diagnostics = [];
+	for (const issue of result.error.issues) {
+		const topLevelKey = issue.path[0];
+		if (topLevelKey === "targets" || topLevelKey === "features") continue;
+		const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+		diagnostics.push({
+			severity: "error",
+			code: "config/invalid-value",
+			file,
+			message: `Invalid value at '${path}': ${issue.message}`
+		});
+	}
+	return diagnostics;
+}
+/**
+* Runs every per-file check against one configuration file's raw content.
+* Pure with respect to the filesystem so each check is unit-testable; only the
+* `tokenEnv` check consults the provided environment map.
+*/
+function collectConfigFileDiagnostics({ file, content, env = process.env }) {
+	if (content.trim() === "") return [{
+		severity: "warning",
+		code: "config/empty-file",
+		file,
+		message: "Configuration file is empty; rulesync will run with built-in defaults."
+	}];
+	const parseErrors = [];
+	const parsed = parse(content, parseErrors, { allowTrailingComma: true });
+	if (parseErrors.length > 0) return parseErrors.map((parseError) => {
+		const { line, column } = offsetToPosition({
+			content,
+			offset: parseError.offset
+		});
+		return {
+			severity: "error",
+			code: "config/parse-error",
+			file,
+			message: `JSONC parse error: ${printParseErrorCode(parseError.error)}.`,
+			line,
+			column
+		};
+	});
+	if (!isPlainObject(parsed)) return [{
+		severity: "error",
+		code: "config/not-an-object",
+		file,
+		message: `Configuration file must contain a JSON object, found ${JSON.stringify(parsed)}.`
+	}];
+	return [
+		...checkUnknownTopLevelKeys({
+			config: parsed,
+			file
+		}),
+		...checkSchemaProperty({
+			config: parsed,
+			file
+		}),
+		...checkTargetsValue({
+			targets: parsed.targets,
+			file
+		}),
+		...checkFeaturesValue({
+			features: parsed.features,
+			file
+		}),
+		...checkTargetsFeaturesExclusivity({
+			config: parsed,
+			file
+		}),
+		...checkConflictingTargets({
+			targets: parsed.targets,
+			file
+		}),
+		...checkTokenEnvVars({
+			config: parsed,
+			file,
+			env
+		}),
+		...checkAgainstConfigFileSchema({
+			config: parsed,
+			file
+		})
+	];
+}
+/**
+* A base file and a local file can each be valid in isolation yet merge into
+* the invalid `{ targets: object, features: array }` state — the same
+* cross-file rule `ConfigResolver` enforces at generate time.
+*/
+function collectMergedConfigDiagnostics({ baseConfig, localConfig, baseFile, localFile }) {
+	if (baseConfig === void 0 || localConfig === void 0) return [];
+	const mergedTargets = localConfig.targets ?? baseConfig.targets;
+	const mergedFeatures = localConfig.features ?? baseConfig.features;
+	if (!isPlainObject(mergedTargets) || mergedFeatures === void 0) return [];
+	if (isPlainObject(baseConfig.targets) && baseConfig.features !== void 0 || isPlainObject(localConfig.targets) && localConfig.features !== void 0) return [];
+	return [{
+		severity: "error",
+		code: "config/targets-features-conflict",
+		file: localFile,
+		message: `Merging '${baseFile}' with '${localFile}' combines object-form 'targets' with 'features', which is invalid.`,
+		hint: "Remove the conflicting field from one of the two files."
+	}];
+}
+function severityRank(severity) {
+	return severity === "error" ? 0 : severity === "warning" ? 1 : 2;
+}
+/**
+* Strips control characters (including ANSI escape sequences) so key names and
+* values copied out of an untrusted config file cannot inject terminal escape
+* codes into the diagnostic output.
+*/
+function stripControlCharacters(text) {
+	return text.replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, "");
+}
+function formatDiagnostic(diagnostic) {
+	const position = diagnostic.line !== void 0 ? `:${diagnostic.line}${diagnostic.column !== void 0 ? `:${diagnostic.column}` : ""}` : "";
+	const label = diagnostic.severity === "error" ? "✖" : diagnostic.severity === "warning" ? "⚠" : "ℹ";
+	const hint = diagnostic.hint === void 0 ? "" : `\n    ↳ ${stripControlCharacters(diagnostic.hint)}`;
+	return `${label} ${stripControlCharacters(diagnostic.file)}${position} [${diagnostic.code}] ${stripControlCharacters(diagnostic.message)}${hint}`;
+}
+/**
+* Re-parses an already-read config file's content for the cross-file checks.
+* Returns undefined when the content is unparseable or not an object — the
+* per-file checks have already reported those states.
+*/
+function parseConfigObjectForMerge(content) {
+	if (content === void 0) return void 0;
+	const errors = [];
+	const parsed = parse(content, errors, { allowTrailingComma: true });
+	if (errors.length > 0 || !isPlainObject(parsed)) return void 0;
+	return parsed;
+}
+/**
+* Path sanity: an `inputRoot` that does not exist means every command will
+* fail (or silently read nothing); local config wins, mirroring the merge
+* order in `ConfigResolver`.
+*/
+async function checkInputRootExists({ baseConfig, localConfig, baseFile, localFile }) {
+	const mergedInputRoot = localConfig?.inputRoot ?? baseConfig?.inputRoot;
+	if (typeof mergedInputRoot !== "string" || mergedInputRoot.length === 0) return [];
+	if (await directoryExists(resolve(mergedInputRoot))) return [];
+	return [{
+		severity: "error",
+		code: "config/input-root-not-found",
+		file: localConfig?.inputRoot !== void 0 ? localFile : baseFile,
+		message: `'inputRoot' points at '${mergedInputRoot}', which is not an existing directory.`,
+		hint: "Create the directory or fix the 'inputRoot' path."
+	}];
+}
+function reportDiagnostics({ logger, diagnostics }) {
+	if (logger.jsonMode) return;
+	for (const diagnostic of diagnostics) {
+		const formatted = formatDiagnostic(diagnostic);
+		if (diagnostic.severity === "error") logger.error(formatted);
+		else if (diagnostic.severity === "warning") logger.warn(formatted);
+		else logger.info(formatted);
+	}
+}
+/**
+* `rulesync doctor` — read-only diagnostics for the configuration files.
+* Never writes; exits non-zero when errors (or, with --strict, warnings) are
+* found.
+*/
+async function doctorCommand(logger, options) {
+	const cwd = process.cwd();
+	const validatedConfigPath = resolvePath(options.config ?? "rulesync.jsonc", cwd);
+	const localConfigPath = join(dirname(validatedConfigPath), RULESYNC_LOCAL_CONFIG_RELATIVE_FILE_PATH);
+	const toDisplayPath = (absolutePath) => {
+		const relativePath = relative(cwd, absolutePath);
+		return relativePath === "" || relativePath.startsWith("..") ? absolutePath : relativePath;
+	};
+	const diagnostics = [];
+	if (!await fileExists(validatedConfigPath)) diagnostics.push({
+		severity: "info",
+		code: "config/no-config-file",
+		file: toDisplayPath(validatedConfigPath),
+		message: "No configuration file found; rulesync will run with built-in defaults.",
+		hint: "Run 'rulesync init' to scaffold one."
+	});
+	const fileContents = /* @__PURE__ */ new Map();
+	for (const filePath of [validatedConfigPath, localConfigPath]) {
+		if (!await fileExists(filePath)) continue;
+		const content = await readFileContent(filePath);
+		fileContents.set(filePath, content);
+		diagnostics.push(...collectConfigFileDiagnostics({
+			file: toDisplayPath(filePath),
+			content
+		}));
+	}
+	const baseConfig = parseConfigObjectForMerge(fileContents.get(validatedConfigPath));
+	const localConfig = parseConfigObjectForMerge(fileContents.get(localConfigPath));
+	diagnostics.push(...collectMergedConfigDiagnostics({
+		baseConfig,
+		localConfig,
+		baseFile: toDisplayPath(validatedConfigPath),
+		localFile: toDisplayPath(localConfigPath)
+	}));
+	diagnostics.push(...await checkInputRootExists({
+		baseConfig,
+		localConfig,
+		baseFile: toDisplayPath(validatedConfigPath),
+		localFile: toDisplayPath(localConfigPath)
+	}));
+	diagnostics.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+	const errorCount = diagnostics.filter((d) => d.severity === "error").length;
+	const warningCount = diagnostics.filter((d) => d.severity === "warning").length;
+	const infoCount = diagnostics.filter((d) => d.severity === "info").length;
+	reportDiagnostics({
+		logger,
+		diagnostics
+	});
+	if (logger.jsonMode) {
+		logger.captureData("diagnostics", diagnostics);
+		logger.captureData("summary", {
+			errors: errorCount,
+			warnings: warningCount,
+			infos: infoCount
+		});
+	}
+	const summary = `${errorCount} error(s), ${warningCount} warning(s), ${infoCount} info(s)`;
+	if (errorCount > 0 || options.strict === true && warningCount > 0) throw new CLIError(`Doctor found problems: ${summary}.`, ErrorCodes.DOCTOR_FAILED, 1, {
+		diagnostics,
+		summary: {
+			errors: errorCount,
+			warnings: warningCount,
+			infos: infoCount
+		}
+	});
+	if (warningCount > 0) {
+		logger.warn(`Doctor finished with ${summary}.`);
+		return;
+	}
+	logger.success(`✓ No problems found (${summary}).`);
+}
+//#endregion
 //#region src/lib/fetch.ts
 /**
 * Feature to path mapping for filtering (rulesync format)
@@ -9296,7 +9854,7 @@ function wrapCommand$1({ name, errorCode, handler, getVersion, loggerFactory = c
 }
 //#endregion
 //#region src/cli/program.ts
-const getVersion = () => "16.2.0";
+const getVersion = () => "16.3.0";
 const FEATURES_HELP = `${ALL_FEATURES.join(",")}; ignore is deprecated, use permissions`;
 function wrapCommand(name, errorCode, handler) {
 	return wrapCommand$1({
@@ -9368,6 +9926,9 @@ function createProgram() {
 	program.command("generate").description("Generate configuration files for AI tools").option("-t, --targets <tools>", "Comma-separated list of tools to generate for (e.g., 'copilot,cursor,cline' or '*' for all)", parseCommaSeparatedList).option("-f, --features <features>", `Comma-separated list of features to generate (${FEATURES_HELP}) or '*' for all`, parseCommaSeparatedList).option("--delete", "Delete all existing files in output directories before generating").option("-o, --output-roots <paths>", "Output root directories to generate files into (comma-separated for multiple paths)", parseCommaSeparatedList).option("-V, --verbose", "Verbose output").option("-s, --silent", "Suppress all output").option("-c, --config <path>", "Path to configuration file").option("-g, --global", "Generate for global(user scope) configuration files").option("--simulate-commands", "Generate simulated commands. This feature is only available for copilot, cursor and codexcli.").option("--simulate-subagents", "Generate simulated subagents. This feature is only available for copilot and codexcli.").option("--simulate-skills", "Generate simulated skills. This feature is only available for copilot, cursor and codexcli.").option("--input-root <path>", "Path to the directory containing .rulesync/ (parent of .rulesync/)").option("--dry-run", "Dry run: show changes without writing files").option("--check", "Check if files are up to date (exits with code 1 if changes needed)").option("-w, --watch", "Keep running and regenerate whenever rulesync source files change (cannot be combined with --check, --dry-run or --json)").action(wrapCommand("generate", "GENERATION_FAILED", async (logger, options) => {
 		await generateCommand(logger, options);
 	}));
+	program.command("doctor").description("Diagnose the rulesync configuration for common problems (read-only, never writes files)").option("-c, --config <path>", "Path to configuration file").option("--strict", "Treat warnings as errors (exit with code 1)").option("-V, --verbose", "Verbose output").option("-s, --silent", "Suppress all output").action(wrapCommand("doctor", "DOCTOR_FAILED", async (logger, options) => {
+		await doctorCommand(logger, options);
+	}));
 	program.command("update").description("Update rulesync to the latest version").option("--check", "Check for updates without installing").option("--force", "Force update even if already at latest version").option("--token <token>", "GitHub token for API access").option("-V, --verbose", "Verbose output").option("-s, --silent", "Suppress all output").action(wrapCommand("update", "UPDATE_FAILED", async (logger, options) => {
 		await updateCommand(logger, version, options);
 	}));