rulesync 16.1.0 → 16.3.0

package/dist/cli/index.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_import = require("../import-eG7fZPXI.cjs");
+const require_import = require("../import-DD-GRmB9.cjs");
 let commander = require("commander");
 let zod_mini = require("zod/mini");
 let node_fs_promises = require("node:fs/promises");
@@ -18,9 +18,9 @@ let node_util = require("node:util");
 let _octokit_request_error = require("@octokit/request-error");
 let _octokit_rest = require("@octokit/rest");
 let node_zlib = require("node:zlib");
-let fastmcp = require("fastmcp");
 let node_fs = require("node:fs");
 node_fs = require_import.__toESM(node_fs, 1);
+let fastmcp = require("fastmcp");
 let node_stream = require("node:stream");
 let node_stream_promises = require("node:stream/promises");
 //#region src/utils/parse-comma-separated-list.ts
@@ -3861,6 +3861,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 = [require_import.GITIGNORE_DESTINATION_KEY];
+const KNOWN_CONFIG_KEYS = Object.keys(require_import.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 (require_import.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: require_import.ALL_TOOL_TARGETS
+		}) ?? `Valid targets: ${require_import.ALL_TOOL_TARGETS.join(", ")}.`
+	};
+}
+function checkFeatureName({ name, file, context }) {
+	const replacement = require_import.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 (require_import.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: require_import.ALL_FEATURES
+		}) ?? `Valid features: ${require_import.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 require_import.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": "${require_import.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 "${require_import.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 = require_import.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 = (0, jsonc_parser.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: ${(0, jsonc_parser.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 = (0, jsonc_parser.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 require_import.directoryExists((0, node_path.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 = require_import.resolvePath(options.config ?? "rulesync.jsonc", cwd);
+	const localConfigPath = (0, node_path.join)((0, node_path.dirname)(validatedConfigPath), require_import.RULESYNC_LOCAL_CONFIG_RELATIVE_FILE_PATH);
+	const toDisplayPath = (absolutePath) => {
+		const relativePath = (0, node_path.relative)(cwd, absolutePath);
+		return relativePath === "" || relativePath.startsWith("..") ? absolutePath : relativePath;
+	};
+	const diagnostics = [];
+	if (!await require_import.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 require_import.fileExists(filePath)) continue;
+		const content = await require_import.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 require_import.CLIError(`Doctor found problems: ${summary}.`, require_import.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)
@@ -4376,6 +4934,216 @@ async function fetchCommand(logger, options) {
 		throw error;
 	}
 }
+/**
+* Coalesces file-system change notifications into debounced, non-overlapping
+* runs.
+*
+* Guarantees:
+* - At most one `run` is in flight at any time.
+* - Every notified path is reported to exactly one `run` as a trigger.
+* - Notifications that arrive while a run is in flight schedule exactly one
+*   follow-up run after it finishes, so a change is never lost and never
+*   causes a run per event.
+*/
+var WatchScheduler = class {
+	run;
+	onError;
+	debounceMs;
+	pending = /* @__PURE__ */ new Set();
+	timer;
+	running;
+	closed = false;
+	constructor({ run, onError, debounceMs = 300 }) {
+		this.run = run;
+		this.onError = onError;
+		this.debounceMs = debounceMs;
+	}
+	notify({ path }) {
+		if (this.closed) return;
+		this.pending.add(path);
+		this.schedule();
+	}
+	/**
+	* Stops accepting notifications and waits for an in-flight run to settle.
+	* Pending (not yet started) changes are dropped.
+	*/
+	async close() {
+		this.closed = true;
+		this.clearTimer();
+		this.pending.clear();
+		await this.running;
+	}
+	clearTimer() {
+		if (this.timer !== void 0) {
+			clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+	}
+	schedule() {
+		this.clearTimer();
+		this.timer = setTimeout(() => {
+			this.timer = void 0;
+			this.flush();
+		}, this.debounceMs);
+	}
+	async flush() {
+		if (this.closed || this.running !== void 0 || this.pending.size === 0) return;
+		const triggers = [...this.pending];
+		this.pending.clear();
+		const running = (async () => {
+			try {
+				await this.run({ triggers });
+			} catch (error) {
+				this.onError({
+					error,
+					triggers
+				});
+			}
+		})();
+		this.running = running;
+		await running;
+		this.running = void 0;
+		if (!this.closed && this.pending.size > 0) this.schedule();
+	}
+};
+/**
+* Watches one directory, re-attaching the underlying `fs.watch` if the
+* directory is deleted and later recreated.
+*
+* Without this, a `git checkout` to a branch without `.rulesync/` (or any
+* tool that replaces the directory rather than its contents) would silently
+* kill the watcher: the deleted inode emits no further events and no error,
+* so watch mode would keep running while never regenerating again.
+*
+* The first attach is not guarded — a missing directory at startup is a real
+* configuration error and must surface to the caller.
+*/
+function watchTargetWithRearm({ target, onChange, onError, rearmIntervalMs }) {
+	let watcher;
+	let rearmTimer;
+	let closed = false;
+	const attach = () => {
+		const created = (0, node_fs.watch)(target.directory, {
+			recursive: target.recursive,
+			persistent: true
+		}, (_eventType, filename) => {
+			if (filename === null || filename === void 0) {
+				onChange({ path: target.directory });
+				verifyStillWatching();
+				return;
+			}
+			const relativePath = filename.toString();
+			if (target.include && !target.include(relativePath)) {
+				verifyStillWatching();
+				return;
+			}
+			onChange({ path: (0, node_path.join)(target.directory, relativePath) });
+			verifyStillWatching();
+		});
+		created.on("error", (error) => {
+			onError({
+				error,
+				directory: target.directory
+			});
+			verifyStillWatching();
+		});
+		watcher = created;
+	};
+	const scheduleRearm = () => {
+		if (closed || rearmTimer !== void 0) return;
+		rearmTimer = setInterval(() => {
+			if (closed || !(0, node_fs.existsSync)(target.directory)) return;
+			clearInterval(rearmTimer);
+			rearmTimer = void 0;
+			try {
+				attach();
+			} catch (error) {
+				onError({
+					error,
+					directory: target.directory
+				});
+				scheduleRearm();
+				return;
+			}
+			onChange({ path: target.directory });
+		}, rearmIntervalMs);
+	};
+	const verifyStillWatching = () => {
+		if (closed || watcher === void 0 || (0, node_fs.existsSync)(target.directory)) return;
+		watcher.close();
+		watcher = void 0;
+		scheduleRearm();
+	};
+	attach();
+	return { close: () => {
+		closed = true;
+		if (rearmTimer !== void 0) {
+			clearInterval(rearmTimer);
+			rearmTimer = void 0;
+		}
+		watcher?.close();
+		watcher = void 0;
+	} };
+}
+/**
+* Starts one watcher per target and forwards matching events to `onChange` as
+* absolute paths. If any target fails to attach, the watchers started so far
+* are closed before the error propagates, so no descriptor is leaked.
+*/
+function watchTargets({ targets, onChange, onError, rearmIntervalMs = 500 }) {
+	const handles = [];
+	const closeAll = () => {
+		for (const handle of handles) handle.close();
+	};
+	try {
+		for (const target of targets) handles.push(watchTargetWithRearm({
+			target,
+			onChange,
+			onError,
+			rearmIntervalMs
+		}));
+	} catch (error) {
+		closeAll();
+		throw error;
+	}
+	return { close: closeAll };
+}
+/**
+* Builds the set of directories watch mode observes: the `.rulesync/` source
+* tree (recursively) and, filtered down to the configuration files themselves,
+* the directory holding `rulesync.jsonc`.
+*
+* Only input paths are watched. Generated output lives outside `.rulesync/`, so
+* a regeneration cannot re-trigger the watcher.
+*/
+function buildWatchTargets({ inputRoot, configFilePath }) {
+	const configFilePaths = buildConfigFilePaths({ configFilePath });
+	return [{
+		directory: (0, node_path.join)(inputRoot, require_import.RULESYNC_RELATIVE_DIR_PATH),
+		recursive: true
+	}, {
+		directory: (0, node_path.dirname)(configFilePath),
+		recursive: false,
+		include: (relativePath) => configFilePaths.has((0, node_path.join)((0, node_path.dirname)(configFilePath), relativePath))
+	}];
+}
+/**
+* The absolute paths of the configuration files watch mode observes: the base
+* configuration file and the `rulesync.local.jsonc` sitting next to it, which
+* is exactly what `ConfigResolver` loads.
+*/
+function buildConfigFilePaths({ configFilePath }) {
+	return /* @__PURE__ */ new Set([configFilePath, (0, node_path.join)((0, node_path.dirname)(configFilePath), require_import.RULESYNC_LOCAL_CONFIG_RELATIVE_FILE_PATH)]);
+}
+/**
+* Renders trigger paths relative to `baseDir` for logging, truncating long
+* bursts so a `git checkout` does not flood the terminal.
+*/
+function formatTriggerPaths({ triggers, baseDir, max = 5 }) {
+	const displayed = triggers.slice(0, max).map((trigger) => (0, node_path.relative)(baseDir, trigger) || trigger);
+	const remaining = triggers.length - displayed.length;
+	return remaining > 0 ? `${displayed.join(", ")} (+${remaining} more)` : displayed.join(", ");
+}
 //#endregion
 //#region src/cli/commands/generate.ts
 /**
@@ -4465,7 +5233,20 @@ function buildSummaryParts(result) {
 	return parts;
 }
 async function generateCommand(logger, options) {
-	const config = await require_import.ConfigResolver.resolve(options, { logger });
+	if (options.watch) {
+		await generateWatchCommand(logger, options);
+		return;
+	}
+	await generateOnce(logger, options);
+}
+/**
+* Runs one generation. `resolvedConfig` lets a caller that already resolved
+* the configuration (watch mode's startup validation) reuse it instead of
+* paying for a second resolution — and, more importantly, instead of emitting
+* the resolver's warnings twice.
+*/
+async function generateOnce(logger, options, { resolvedConfig } = {}) {
+	const config = resolvedConfig ?? await require_import.ConfigResolver.resolve(options, { logger });
 	const check = config.getCheck();
 	const isPreview = config.isPreviewMode();
 	const modePrefix = isPreview ? "[DRY RUN]" : "";
@@ -4560,6 +5341,76 @@ async function generateCommand(logger, options) {
 	if (isPreview) logger.info(`${modePrefix} Would write ${totalGenerated} file(s) total (${parts.join(" + ")})`);
 	else logger.success(`🎉 All done! Written ${totalGenerated} file(s) total (${parts.join(" + ")})`);
 }
+/**
+* Rejects flag combinations that contradict a long-running watch: `--check`
+* and `--dry-run` are one-shot verification modes (the former is meant to exit
+* non-zero), and `--json` buffers a single result document until the command
+* returns, which never happens while watching.
+*/
+function assertWatchModeCompatible({ isCheck, isDryRun, isJsonMode }) {
+	const conflicts = [
+		isCheck ? "--check" : void 0,
+		isDryRun ? "--dry-run" : void 0,
+		isJsonMode ? "--json" : void 0
+	].filter((flag) => flag !== void 0);
+	if (conflicts.length > 0) throw new require_import.CLIError(`--watch cannot be combined with ${conflicts.join(", ")}.`, require_import.ErrorCodes.VALIDATION_FAILED);
+}
+async function generateWatchCommand(logger, options) {
+	const config = await require_import.ConfigResolver.resolve(options, { logger });
+	assertWatchModeCompatible({
+		isCheck: config.getCheck(),
+		isDryRun: config.getDryRun(),
+		isJsonMode: logger.jsonMode
+	});
+	const inputRoot = config.getInputRoot();
+	const configFilePath = config.getConfigFilePath();
+	const configFilePaths = buildConfigFilePaths({ configFilePath });
+	await generateOnce(logger, options, { resolvedConfig: config });
+	const targets = buildWatchTargets({
+		inputRoot,
+		configFilePath
+	});
+	const scheduler = new WatchScheduler({
+		run: async ({ triggers }) => {
+			logger.info(`\nChange detected: ${formatTriggerPaths({
+				triggers,
+				baseDir: inputRoot
+			})}`);
+			if (triggers.some((trigger) => configFilePaths.has(trigger))) logger.warn("Configuration file changed. The set of watched paths is fixed at startup — restart 'rulesync generate --watch' if you changed 'inputRoot' or the configuration file location.");
+			await generateOnce(logger, options);
+		},
+		onError: ({ error }) => {
+			logger.error(`Generation failed: ${require_import.formatError(error)}`);
+			logger.info("Still watching for changes...");
+		}
+	});
+	const handle = watchTargets({
+		targets,
+		onChange: ({ path }) => {
+			scheduler.notify({ path });
+		},
+		onError: ({ error, directory }) => {
+			logger.error(`Watch error on ${directory}: ${require_import.formatError(error)}`);
+		}
+	});
+	logger.info(`\nWatching for changes in:\n${targets.map((target) => `    ${target.directory}`).join("\n")}`);
+	logger.info("Press Ctrl+C to stop.");
+	await new Promise((resolveShutdown) => {
+		const shutdown = () => {
+			process.off("SIGINT", shutdown);
+			process.off("SIGTERM", shutdown);
+			handle.close();
+			scheduler.close().catch((error) => {
+				logger.error(`Failed to stop the watcher cleanly: ${require_import.formatError(error)}`);
+			}).finally(() => {
+				logger.info("\nStopped watching.");
+				resolveShutdown();
+			});
+		};
+		process.once("SIGINT", shutdown);
+		process.once("SIGTERM", shutdown);
+	});
+}
 //#endregion
 //#region src/cli/commands/gitignore-derive.ts
 const TARGETS_NOT_DERIVED = /* @__PURE__ */ new Set([
@@ -9004,7 +9855,7 @@ function wrapCommand$1({ name, errorCode, handler, getVersion, loggerFactory = c
 }
 //#endregion
 //#region src/cli/program.ts
-const getVersion = () => "16.1.0";
+const getVersion = () => "16.3.0";
 const FEATURES_HELP = `${require_import.ALL_FEATURES.join(",")}; ignore is deprecated, use permissions`;
 function wrapCommand(name, errorCode, handler) {
 	return wrapCommand$1({
@@ -9073,9 +9924,12 @@ function createProgram() {
 			silent: options.silent
 		});
 	}));
-	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)").action(wrapCommand("generate", "GENERATION_FAILED", async (logger, options) => {
+	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);
 	}));