@contentrain/mcp 0.1.1 → 0.3.0

package/dist/index.mjs

@@ -904,6 +904,87 @@ var GitSyncManager = class {
 		}
 	}
 	/**
+	* Run a staging transaction: worktree → execute → commit → push to staging branch → cleanup.
+	* Changes are pushed to a separate branch instead of the target branch.
+	*/
+	async stagingTransaction(fn, message, stagingBranch) {
+		const ctx = await this.createWorktree();
+		try {
+			const result = await fn(ctx.path);
+			const commitHash = await this.commit(ctx, message);
+			if (commitHash) {
+				const git = simpleGit(ctx.path);
+				try {
+					await git.push(this.config.remote, `${ctx.branch}:${stagingBranch}`);
+				} catch (err) {
+					throw new GitSyncError(`Failed to push to staging branch "${stagingBranch}"`, {
+						branch: stagingBranch,
+						originalError: String(err)
+					});
+				}
+			}
+			return {
+				result,
+				hasChanges: !!commitHash
+			};
+		} finally {
+			await this.cleanup(ctx);
+		}
+	}
+	/**
+	* Merge a remote staging branch into the target branch.
+	* Tries fast-forward first, falls back to merge commit.
+	*/
+	async mergeStagingToTarget(stagingBranch) {
+		const git = simpleGit(this.config.repoPath);
+		const remote = this.config.remote;
+		await git.fetch(remote, stagingBranch);
+		try {
+			await git.raw([
+				"rev-parse",
+				"--verify",
+				`${remote}/${stagingBranch}`
+			]);
+		} catch {
+			throw new GitSyncError(`Staging branch "${stagingBranch}" not found on remote "${remote}"`, { branch: stagingBranch });
+		}
+		await git.fetch(remote, this.config.branch);
+		const ctx = await this.createWorktree();
+		try {
+			const wtGit = simpleGit(ctx.path);
+			try {
+				await wtGit.merge([`${remote}/${stagingBranch}`, "--ff-only"]);
+			} catch {
+				await wtGit.merge([
+					`${remote}/${stagingBranch}`,
+					"-m",
+					`${this.config.commitPrefix} apply doctor fix from ${stagingBranch}`
+				]);
+			}
+			await this.pushWithRetry(ctx);
+			try {
+				await git.push(remote, `:${stagingBranch}`);
+			} catch {}
+			return (await wtGit.log({ maxCount: 1 })).latest?.hash || "";
+		} finally {
+			await this.cleanup(ctx);
+		}
+	}
+	/**
+	* Delete a remote staging branch without merging.
+	*/
+	async deleteStagingBranch(stagingBranch) {
+		const git = simpleGit(this.config.repoPath);
+		try {
+			await git.push(this.config.remote, `:${stagingBranch}`);
+		} catch (err) {
+			throw new GitSyncError(`Failed to delete staging branch "${stagingBranch}"`, {
+				branch: stagingBranch,
+				originalError: String(err)
+			});
+		}
+	}
+	/**
 	* Resolve push conflicts via structural JSON merge.
 	*/
 	async resolveAndRetry(ctx) {
@@ -987,6 +1068,31 @@ var ContentrainWriter = class {
 		}, options?.message || "content update");
 	}
 	/**
+	* Execute operations and push to a staging branch instead of the target branch.
+	* Returns the result and whether any changes were pushed.
+	*/
+	async stagingTransaction(fn, options) {
+		if (this.config.dryRun) return {
+			result: await this.dryRunTransaction(fn),
+			hasChanges: false
+		};
+		return this.gitSync.stagingTransaction(async (worktreePath) => {
+			return fn(this.createManagers(worktreePath));
+		}, options.message, options.stagingBranch);
+	}
+	/**
+	* Merge a staging branch into the target branch.
+	*/
+	async applyStagingBranch(stagingBranch) {
+		return this.gitSync.mergeStagingToTarget(stagingBranch);
+	}
+	/**
+	* Delete a staging branch without merging.
+	*/
+	async discardStagingBranch(stagingBranch) {
+		return this.gitSync.deleteStagingBranch(stagingBranch);
+	}
+	/**
 	* Dry-run: copy contentrain dir to temp, run operations there, then discard.
 	* The original repository is never modified.
 	*/
@@ -1007,6 +1113,8 @@ var ContentrainWriter = class {
 	createManagers(repoPath) {
 		const basePath = join(repoPath, this.contentrainDir);
 		return {
+			basePath,
+			repoPath,
 			model: new ModelManager(basePath),
 			content: new ContentManager(basePath, repoPath),
 			asset: new AssetManager(basePath, repoPath, this.config),
@@ -1442,16 +1550,587 @@ function registerAssetTools(server, writer) {
 	});
 }
 //#endregion
+//#region src/core/doctor.ts
+var Doctor = class {
+	issues = [];
+	fixed = 0;
+	totalEntries = 0;
+	scannedEntries = 0;
+	idRemap = /* @__PURE__ */ new Map();
+	contentFiles = [];
+	fieldsByModel = /* @__PURE__ */ new Map();
+	constructor(basePath, repoPath) {
+		this.basePath = basePath;
+		this.repoPath = repoPath;
+	}
+	async diagnose(options = {}) {
+		this.issues = [];
+		this.fixed = 0;
+		this.totalEntries = 0;
+		this.scannedEntries = 0;
+		this.idRemap = /* @__PURE__ */ new Map();
+		this.contentFiles = [];
+		this.fieldsByModel = /* @__PURE__ */ new Map();
+		const fix = options.fix ?? false;
+		const models = await this.checkMetadata();
+		if (!models) return this.buildResult(0);
+		const targetModels = options.modelId ? models.filter((m) => m.modelId === options.modelId) : models;
+		if (options.modelId && targetModels.length === 0) {
+			this.addIssue("error", "structure", `Model "${options.modelId}" not found in metadata.json`);
+			return this.buildResult(models.length);
+		}
+		await this.checkFieldFiles(models, targetModels);
+		const assets = await this.loadAssets();
+		await this.loadAllContentFiles(fix ? models : targetModels);
+		for (const model of models) try {
+			const fields = await readJsonFile(join(this.basePath, "models", `${model.modelId}.json`));
+			this.fieldsByModel.set(model.modelId, fields);
+		} catch {}
+		for (const cf of this.contentFiles) if (targetModels.some((m) => m.modelId === cf.modelId)) this.scannedEntries += cf.entries.length;
+		for (const model of targetModels) {
+			this.checkModelStructure(model);
+			this.checkModelContent(model, assets, fix);
+			if (model.type === "MD" || model.type === "MDX") {
+				const modelFiles = this.contentFiles.filter((f) => f.modelId === model.modelId);
+				await this.checkMarkdownSync(model, modelFiles);
+			}
+		}
+		if (!options.modelId) await this.checkOrphanDirectories(models);
+		if (fix && this.idRemap.size > 0) this.propagateIdChanges();
+		if (fix) await this.writeDirtyFiles();
+		return this.buildResult(targetModels.length);
+	}
+	async loadAllContentFiles(models) {
+		for (const model of models) {
+			const contentDir = join(this.basePath, model.modelId);
+			const fileNames = await listJsonFiles(contentDir);
+			for (const fileName of fileNames) {
+				const filePath = join(contentDir, `${fileName}.json`);
+				let entries;
+				try {
+					const raw = await readFile(filePath, "utf-8");
+					entries = JSON.parse(raw);
+					if (!Array.isArray(entries)) {
+						this.addIssue("error", "structure", "Content file is not an array", model.modelId, void 0, void 0, `${model.modelId}/${fileName}.json`);
+						continue;
+					}
+				} catch {
+					this.addIssue("error", "structure", "Invalid JSON in content file", model.modelId, void 0, void 0, `${model.modelId}/${fileName}.json`);
+					continue;
+				}
+				this.totalEntries += entries.length;
+				this.contentFiles.push({
+					modelId: model.modelId,
+					fileName,
+					filePath,
+					entries,
+					dirty: false
+				});
+			}
+		}
+	}
+	async checkMetadata() {
+		const metadataPath = join(this.basePath, "models", "metadata.json");
+		try {
+			const raw = await readFile(metadataPath, "utf-8");
+			try {
+				const models = JSON.parse(raw);
+				if (!Array.isArray(models)) {
+					this.addIssue("error", "structure", "metadata.json is not an array", void 0, void 0, void 0, "models/metadata.json");
+					return null;
+				}
+				const seen = /* @__PURE__ */ new Map();
+				for (const m of models) {
+					const count = (seen.get(m.modelId) ?? 0) + 1;
+					seen.set(m.modelId, count);
+				}
+				for (const [modelId, count] of seen) if (count > 1) this.addIssue("error", "structure", `Duplicate modelId "${modelId}" in metadata.json (${count} times)`, modelId, void 0, void 0, "models/metadata.json");
+				return models;
+			} catch {
+				this.addIssue("error", "structure", "metadata.json contains invalid JSON", void 0, void 0, void 0, "models/metadata.json");
+				return null;
+			}
+		} catch {
+			this.addIssue("error", "structure", "metadata.json not found — is this a Contentrain project?", void 0, void 0, void 0, "models/metadata.json");
+			return null;
+		}
+	}
+	async checkFieldFiles(allModels, targetModels) {
+		for (const model of targetModels) if (!await fileExists(join(this.basePath, "models", `${model.modelId}.json`))) this.addIssue("error", "structure", `Field definition file missing for model "${model.modelId}"`, model.modelId, void 0, void 0, `models/${model.modelId}.json`);
+		const metaIds = new Set(allModels.map((m) => m.modelId));
+		const fieldFiles = await listJsonFiles(join(this.basePath, "models"));
+		for (const file of fieldFiles) {
+			if (file === "metadata") continue;
+			if (!metaIds.has(file)) this.addIssue("warning", "structure", `Field definition file "${file}.json" has no matching model in metadata.json`, file, void 0, void 0, `models/${file}.json`);
+		}
+	}
+	async checkOrphanDirectories(models) {
+		const modelIds = new Set(models.map((m) => m.modelId));
+		const { readdir, stat } = await import("node:fs/promises");
+		try {
+			const entries = await readdir(this.basePath);
+			for (const entry of entries) {
+				if (entry === "models" || entry === "assets.json" || entry === "static" || entry.startsWith(".")) continue;
+				if ((await stat(join(this.basePath, entry))).isDirectory() && !modelIds.has(entry)) this.addIssue("warning", "structure", `Content directory "${entry}/" has no matching model in metadata.json`, entry);
+			}
+		} catch {}
+	}
+	checkModelStructure(model) {
+		const fields = this.fieldsByModel.get(model.modelId);
+		if (!fields) return;
+		for (const sysId of [
+			"createdAt",
+			"updatedAt",
+			"ID",
+			"status"
+		]) if (!fields.some((f) => f.fieldId === sysId && f.system)) this.addIssue("error", "schema", `Missing system field "${sysId}" in field definitions`, model.modelId, void 0, void 0, `models/${model.modelId}.json`);
+		if (model.type === "MD" || model.type === "MDX") {
+			if (!fields.some((f) => f.fieldId === "slug")) this.addIssue("error", "schema", "MD/MDX model missing required \"slug\" field", model.modelId, void 0, void 0, `models/${model.modelId}.json`);
+			if (!fields.some((f) => f.fieldId === "content")) this.addIssue("warning", "schema", "MD/MDX model missing \"content\" field definition", model.modelId, void 0, void 0, `models/${model.modelId}.json`);
+		}
+	}
+	checkModelContent(model, assets, fix) {
+		const fields = this.fieldsByModel.get(model.modelId);
+		if (!fields) return;
+		const modelFiles = this.contentFiles.filter((f) => f.modelId === model.modelId);
+		if (modelFiles.length === 0 && !model.localization) {
+			this.addIssue("warning", "structure", `No content files found for model "${model.modelId}"`, model.modelId);
+			return;
+		}
+		for (const cf of modelFiles) {
+			const fileIdSet = /* @__PURE__ */ new Map();
+			for (const entry of cf.entries) {
+				const count = (fileIdSet.get(entry.ID) ?? 0) + 1;
+				fileIdSet.set(entry.ID, count);
+			}
+			for (const [id, count] of fileIdSet) if (count > 1) {
+				this.addIssue("error", "id", `Duplicate ID "${id}" appears ${count} times in same file`, model.modelId, id, void 0, `${model.modelId}/${cf.fileName}.json`, fix ? "Will regenerate duplicate IDs and update relations" : void 0);
+				if (fix) this.fixDuplicateIds(cf, id);
+			}
+			for (const entry of cf.entries) this.checkEntry(model, fields, entry, assets, `${model.modelId}/${cf.fileName}.json`, fix, cf);
+			this.checkUniqueConstraints(model, fields, cf.entries, `${model.modelId}/${cf.fileName}.json`);
+		}
+		if (model.localization && modelFiles.length > 1) this.checkLocaleIdConsistency(model, modelFiles);
+	}
+	checkEntry(model, fields, entry, assets, file, fix, cf) {
+		const entryId = entry.ID;
+		if (!entryId || typeof entryId !== "string") {
+			this.addIssue("error", "id", "Entry missing ID field", model.modelId, void 0, "ID", file);
+			return;
+		}
+		if (!isValidId(entryId)) {
+			const existingNewId = this.idRemap.get(entryId);
+			const newId = fix ? existingNewId || generateId() : void 0;
+			this.addIssue("error", "id", `Invalid ID format "${entryId}" — must be 12-char lowercase hex`, model.modelId, entryId, "ID", file, fix ? `Regenerated to "${newId}" and updating all relations` : void 0);
+			if (fix && newId) {
+				this.idRemap.set(entryId, newId);
+				entry.ID = newId;
+				cf.dirty = true;
+				if (!existingNewId) this.fixed++;
+			}
+		}
+		if (!entry.createdAt) {
+			this.addIssue("error", "schema", "Missing createdAt", model.modelId, entryId, "createdAt", file, fix ? "Will set to current timestamp" : void 0);
+			if (fix) {
+				entry.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+				cf.dirty = true;
+				this.fixed++;
+			}
+		}
+		if (!entry.updatedAt) {
+			this.addIssue("error", "schema", "Missing updatedAt", model.modelId, entryId, "updatedAt", file, fix ? "Will set to current timestamp" : void 0);
+			if (fix) {
+				entry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+				cf.dirty = true;
+				this.fixed++;
+			}
+		}
+		if (!entry.status) {
+			this.addIssue("error", "schema", "Missing status", model.modelId, entryId, "status", file, fix ? "Will set to \"draft\"" : void 0);
+			if (fix) {
+				entry.status = "draft";
+				cf.dirty = true;
+				this.fixed++;
+			}
+		} else if (![
+			"draft",
+			"publish",
+			"changed"
+		].includes(entry.status)) {
+			this.addIssue("error", "schema", `Invalid status "${entry.status}" — must be draft, publish, or changed`, model.modelId, entryId, "status", file, fix ? "Will set to \"draft\"" : void 0);
+			if (fix) {
+				entry.status = "draft";
+				cf.dirty = true;
+				this.fixed++;
+			}
+		}
+		if (entry.createdAt && isNaN(Date.parse(entry.createdAt))) this.addIssue("error", "schema", `Invalid createdAt date format "${entry.createdAt}"`, model.modelId, entryId, "createdAt", file);
+		if (entry.updatedAt && isNaN(Date.parse(entry.updatedAt))) this.addIssue("error", "schema", `Invalid updatedAt date format "${entry.updatedAt}"`, model.modelId, entryId, "updatedAt", file);
+		const nonSystemFields = fields.filter((f) => !f.system);
+		for (const field of nonSystemFields) {
+			const value = entry[field.fieldId];
+			if (field.validations?.["required-field"]?.value) {
+				if (value === void 0 || value === null || value === "") {
+					if (field.fieldId === "content" && (model.type === "MD" || model.type === "MDX")) continue;
+					this.addIssue("error", "schema", `Required field "${field.fieldId}" is empty`, model.modelId, entryId, field.fieldId, file);
+					continue;
+				}
+			}
+			if (value === void 0 || value === null) continue;
+			const typeError = validateFieldValue(value, getExpectedType(field.componentId, field.fieldType), field.fieldId);
+			if (typeError) {
+				this.addIssue("error", "schema", `Type mismatch: ${typeError}`, model.modelId, entryId, field.fieldId, file);
+				continue;
+			}
+			if (field.componentId === "integer") {
+				const intError = validateInteger(value, field.fieldId);
+				if (intError) this.addIssue("error", "schema", intError, model.modelId, entryId, field.fieldId, file);
+			}
+			if (field.componentId === "one-to-one" && typeof value === "string") this.checkRelation(model.modelId, entryId, field, value, file);
+			if (field.componentId === "one-to-many" && Array.isArray(value)) for (const refId of value) if (typeof refId === "string") this.checkRelation(model.modelId, entryId, field, refId, file);
+			else this.addIssue("error", "relation", "one-to-many array contains non-string value", model.modelId, entryId, field.fieldId, file);
+			if ((field.componentId === "one-to-one" || field.componentId === "one-to-many") && !field.options?.reference?.form?.reference?.value) this.addIssue("warning", "relation", `Relation field "${field.fieldId}" missing options.reference.form.reference.value`, model.modelId, void 0, field.fieldId, `models/${model.modelId}.json`);
+			if (field.componentId === "media" && typeof value === "string" && value !== "") {
+				if (!assets.some((a) => a.path === value)) this.addIssue("error", "asset", `Media path "${value}" not found in assets.json`, model.modelId, entryId, field.fieldId, file);
+			}
+		}
+	}
+	checkRelation(modelId, entryId, field, refId, file) {
+		const refModelId = field.options?.reference?.form?.reference?.value;
+		if (!refModelId) return;
+		if (!isValidId(refId)) {
+			this.addIssue("error", "relation", `Relation references invalid ID "${refId}"`, modelId, entryId, field.fieldId, file);
+			return;
+		}
+		if (!this.contentFiles.filter((f) => f.modelId === refModelId).some((rf) => rf.entries.some((e) => e.ID === refId))) this.addIssue("error", "relation", `Referenced entry "${refId}" not found in model "${refModelId}"`, modelId, entryId, field.fieldId, file);
+	}
+	checkUniqueConstraints(model, fields, entries, file) {
+		const uniqueFields = fields.filter((f) => f.validations?.["unique-field"]?.value && !f.system);
+		for (const field of uniqueFields) {
+			const seen = /* @__PURE__ */ new Map();
+			for (const entry of entries) {
+				const value = entry[field.fieldId];
+				if (value === void 0 || value === null || value === "") continue;
+				const key = typeof value === "object" ? JSON.stringify(value) : value;
+				const existing = seen.get(key);
+				if (existing) this.addIssue("error", "schema", `Unique constraint violated: "${field.fieldId}" value "${value}" duplicated between entries ${existing} and ${entry.ID}`, model.modelId, entry.ID, field.fieldId, file);
+				else seen.set(key, entry.ID);
+			}
+		}
+	}
+	checkLocaleIdConsistency(model, modelFiles) {
+		if (modelFiles.length < 2) return;
+		const referenceFile = modelFiles[0];
+		const referenceIds = new Set(referenceFile.entries.map((e) => e.ID));
+		for (let i = 1; i < modelFiles.length; i++) {
+			const otherFile = modelFiles[i];
+			const otherIds = new Set(otherFile.entries.map((e) => e.ID));
+			for (const id of referenceIds) if (!otherIds.has(id)) this.addIssue("error", "id", `Entry "${id}" exists in ${referenceFile.fileName}.json but missing in ${otherFile.fileName}.json`, model.modelId, id, void 0, `${model.modelId}/${otherFile.fileName}.json`);
+			for (const id of otherIds) if (!referenceIds.has(id)) this.addIssue("error", "id", `Entry "${id}" exists in ${otherFile.fileName}.json but missing in ${referenceFile.fileName}.json`, model.modelId, id, void 0, `${model.modelId}/${referenceFile.fileName}.json`);
+		}
+	}
+	async checkMarkdownSync(model, modelFiles) {
+		for (const cf of modelFiles) {
+			const locale = model.localization && cf.fileName !== model.modelId ? cf.fileName : void 0;
+			for (const entry of cf.entries) {
+				if (!("slug" in entry) || !entry.slug) {
+					this.addIssue("error", "sync", "MD/MDX entry missing \"slug\" field", model.modelId, entry.ID, "slug", `${model.modelId}/${cf.fileName}.json`);
+					continue;
+				}
+				const mdEntry = entry;
+				const ext = model.type === "MDX" ? ".mdx" : ".md";
+				const baseMdPath = mdEntry.path || model.path || "";
+				const mdPath = locale ? join(this.repoPath, baseMdPath, locale, `${mdEntry.slug}${ext}`) : join(this.repoPath, baseMdPath, `${mdEntry.slug}${ext}`);
+				if (!await fileExists(mdPath)) this.addIssue("error", "sync", `Markdown file missing for entry "${mdEntry.slug}"`, model.modelId, entry.ID, void 0, mdPath.replace(this.repoPath + "/", ""));
+				if ("content" in entry && entry.content && typeof entry.content === "string" && entry.content.length > 0) this.addIssue("warning", "sync", "MD/MDX JSON index should not contain \"content\" body — body belongs in markdown file", model.modelId, entry.ID, "content", `${model.modelId}/${cf.fileName}.json`);
+			}
+		}
+	}
+	async loadAssets() {
+		try {
+			return await readJsonFile(join(this.basePath, "assets.json"));
+		} catch {
+			this.addIssue("warning", "structure", "assets.json not found or invalid");
+			return [];
+		}
+	}
+	/**
+	* After all ID fixes are collected in idRemap, propagate changes
+	* to ALL relation fields across ALL loaded content files.
+	*
+	* This is the critical two-way binding: when entry A's ID changes,
+	* every relation field in every model that points to A must be updated.
+	*/
+	propagateIdChanges() {
+		if (this.idRemap.size === 0) return;
+		for (const cf of this.contentFiles) {
+			const fields = this.fieldsByModel.get(cf.modelId);
+			if (!fields) continue;
+			const relationFields = fields.filter((f) => f.componentId === "one-to-one" || f.componentId === "one-to-many");
+			if (relationFields.length === 0) continue;
+			for (const entry of cf.entries) for (const field of relationFields) {
+				const value = entry[field.fieldId];
+				if (value === void 0 || value === null) continue;
+				if (field.componentId === "one-to-one" && typeof value === "string") {
+					const newId = this.idRemap.get(value);
+					if (newId) {
+						this.addIssue("warning", "relation", `Updated relation "${field.fieldId}": "${value}" → "${newId}"`, cf.modelId, entry.ID, field.fieldId, `${cf.modelId}/${cf.fileName}.json`, "Propagated ID change to relation");
+						entry[field.fieldId] = newId;
+						cf.dirty = true;
+						this.fixed++;
+					}
+				}
+				if (field.componentId === "one-to-many" && Array.isArray(value)) {
+					let changed = false;
+					const updated = value.map((refId) => {
+						const newId = this.idRemap.get(refId);
+						if (newId) {
+							changed = true;
+							return newId;
+						}
+						return refId;
+					});
+					if (changed) {
+						this.addIssue("warning", "relation", `Updated one-to-many relation "${field.fieldId}": propagated ${this.idRemap.size} ID change(s)`, cf.modelId, entry.ID, field.fieldId, `${cf.modelId}/${cf.fileName}.json`, "Propagated ID changes to relation array");
+						entry[field.fieldId] = updated;
+						cf.dirty = true;
+						this.fixed++;
+					}
+				}
+			}
+		}
+	}
+	fixDuplicateIds(cf, duplicateId) {
+		let first = true;
+		for (const entry of cf.entries) if (entry.ID === duplicateId) {
+			if (first) {
+				first = false;
+				continue;
+			}
+			const newId = generateId();
+			this.idRemap.set(`${duplicateId}:dup:${newId}`, newId);
+			entry.ID = newId;
+			cf.dirty = true;
+			this.fixed++;
+		}
+	}
+	async writeDirtyFiles() {
+		for (const cf of this.contentFiles) if (cf.dirty) await writeJsonFile(cf.filePath, cf.entries);
+	}
+	addIssue(severity, category, message, modelId, entryId, field, file, fix) {
+		this.issues.push({
+			severity,
+			category,
+			modelId,
+			entryId,
+			field,
+			file,
+			message,
+			fix
+		});
+	}
+	buildResult(modelCount) {
+		const unfixedErrors = this.issues.filter((i) => i.severity === "error" && !i.fix).length;
+		return {
+			summary: {
+				total: this.issues.length,
+				errors: unfixedErrors,
+				warnings: this.issues.filter((i) => i.severity === "warning").length,
+				fixed: this.fixed,
+				models: modelCount,
+				entries: this.scannedEntries
+			},
+			issues: this.issues
+		};
+	}
+};
+//#endregion
+//#region src/tools/doctor.ts
+function registerDoctorTools(server, writer, config) {
+	const targetBranch = config.branch || "contentrain";
+	const stagingPrefix = `${targetBranch}--doctor-fix/`;
+	function isStagingBranch(branch) {
+		return branch.startsWith(stagingPrefix);
+	}
+	server.registerTool("contentrain_doctor", {
+		description: [
+			"Run a full diagnostic scan on all Contentrain models, content, and assets.",
+			"Detects: duplicate/invalid IDs, type mismatches, broken relations, missing assets,",
+			"locale ID inconsistencies, orphan directories, MD/MDX sync issues, unique constraint",
+			"violations, missing system fields, and invalid JSON files.",
+			"Use fix=true to auto-repair fixable issues — changes are pushed to a staging branch",
+			"for review. Use contentrain_doctor_apply to merge the staging branch into the target.",
+			"Use modelId to scope the scan to a single model."
+		].join(" "),
+		annotations: { readOnlyHint: false },
+		inputSchema: {
+			fix: z.boolean().optional().default(false).describe("Auto-fix repairable issues (duplicate IDs, missing timestamps, invalid status). Pushes to a staging branch for review."),
+			modelId: z.string().optional().describe("Scope scan to a specific model ID. Omit to scan all models.")
+		}
+	}, async ({ fix, modelId }) => {
+		try {
+			if (fix) {
+				const stagingBranch = `${stagingPrefix}${Date.now()}`;
+				const { result, hasChanges } = await writer.stagingTransaction(async (tx) => {
+					return new Doctor(tx.basePath, tx.repoPath).diagnose({
+						fix: true,
+						modelId
+					});
+				}, {
+					message: `doctor fix${modelId ? ` ${modelId}` : ""}`,
+					stagingBranch
+				});
+				return { content: [{
+					type: "text",
+					text: formatResult(result, hasChanges ? stagingBranch : void 0)
+				}] };
+			}
+			const contentrainDir = config.contentrainDir || "contentrain";
+			return { content: [{
+				type: "text",
+				text: formatResult(await new Doctor(join(config.repoPath, contentrainDir), config.repoPath).diagnose({
+					fix: false,
+					modelId
+				}))
+			}] };
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${err}`
+				}],
+				isError: true
+			};
+		}
+	});
+	server.registerTool("contentrain_doctor_apply", {
+		description: [
+			"Apply a staged doctor fix by merging the staging branch into the target branch.",
+			"Use the stagingBranch value returned by contentrain_doctor fix=true.",
+			"Attempts fast-forward merge first, falls back to merge commit.",
+			"Deletes the staging branch after successful merge."
+		].join(" "),
+		annotations: { readOnlyHint: false },
+		inputSchema: { branch: z.string().describe(`The staging branch name returned by contentrain_doctor fix=true (e.g., "${stagingPrefix}1234567890")`) }
+	}, async ({ branch }) => {
+		try {
+			if (!isStagingBranch(branch)) return {
+				content: [{
+					type: "text",
+					text: `Error: branch must start with "${stagingPrefix}" — only doctor staging branches for the "${targetBranch}" target can be applied.`
+				}],
+				isError: true
+			};
+			return { content: [{
+				type: "text",
+				text: `✅ Doctor fix applied to "${targetBranch}".\nCommit: ${await writer.applyStagingBranch(branch)}\nStaging branch "${branch}" has been deleted.`
+			}] };
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${err}`
+				}],
+				isError: true
+			};
+		}
+	});
+	server.registerTool("contentrain_doctor_discard", {
+		description: "Discard a staged doctor fix by deleting the staging branch without merging.",
+		annotations: { readOnlyHint: false },
+		inputSchema: { branch: z.string().describe(`The staging branch name to discard (e.g., "${stagingPrefix}1234567890")`) }
+	}, async ({ branch }) => {
+		try {
+			if (!isStagingBranch(branch)) return {
+				content: [{
+					type: "text",
+					text: `Error: branch must start with "${stagingPrefix}" — only doctor staging branches can be discarded.`
+				}],
+				isError: true
+			};
+			await writer.discardStagingBranch(branch);
+			return { content: [{
+				type: "text",
+				text: `Staging branch "${branch}" has been deleted.`
+			}] };
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${err}`
+				}],
+				isError: true
+			};
+		}
+	});
+}
+function formatResult(result, stagingBranch) {
+	const { summary, issues } = result;
+	const lines = [];
+	if (summary.errors === 0 && summary.warnings === 0 && summary.fixed === 0) lines.push("✅ No issues found!");
+	else if (summary.errors === 0 && summary.fixed > 0) lines.push("✅ All fixable issues have been repaired.");
+	else if (summary.errors === 0) lines.push("⚠️ No errors, but some warnings found.");
+	else lines.push("❌ Issues detected.");
+	lines.push("");
+	lines.push(`Models scanned: ${summary.models}`);
+	lines.push(`Entries scanned: ${summary.entries}`);
+	lines.push(`Errors: ${summary.errors}`);
+	lines.push(`Warnings: ${summary.warnings}`);
+	if (summary.fixed > 0) lines.push(`Fixed: ${summary.fixed}`);
+	if (stagingBranch) {
+		lines.push("");
+		lines.push(`📦 Staging branch: ${stagingBranch}`);
+		lines.push("→ Review the changes, then run contentrain_doctor_apply to merge into the target branch.");
+		lines.push("→ Or run contentrain_doctor_discard to discard without applying.");
+	}
+	if (issues.length > 0) {
+		lines.push("");
+		const grouped = /* @__PURE__ */ new Map();
+		for (const issue of issues) {
+			const key = issue.category;
+			const arr = grouped.get(key) ?? [];
+			arr.push(issue);
+			grouped.set(key, arr);
+		}
+		const categoryLabels = {
+			structure: "📁 Structure",
+			id: "🔑 IDs",
+			schema: "📋 Schema",
+			relation: "🔗 Relations",
+			asset: "🖼️ Assets",
+			sync: "📝 MD/MDX Sync"
+		};
+		for (const [category, categoryIssues] of grouped) {
+			lines.push(`\n### ${categoryLabels[category] || category}`);
+			for (const issue of categoryIssues) {
+				const icon = issue.fix ? "✅" : issue.severity === "error" ? "❌" : "⚠️";
+				const location = [
+					issue.modelId,
+					issue.entryId,
+					issue.field
+				].filter(Boolean).join(" → ");
+				const filePart = issue.file ? ` (${issue.file})` : "";
+				const fixPart = issue.fix ? ` [FIX: ${issue.fix}]` : "";
+				lines.push(`  ${icon} ${location ? `[${location}]` : ""}${filePart} ${issue.message}${fixPart}`);
+			}
+		}
+	}
+	lines.push("\n---\n");
+	lines.push(JSON.stringify(result, null, 2));
+	return lines.join("\n");
+}
+//#endregion
 //#region src/server.ts
 function createServer(config) {
 	const server = new McpServer({
 		name: "contentrain",
-		version: "0.1.0"
+		version: "0.1.1"
 	});
 	const writer = new ContentrainWriter(config);
 	registerModelTools(server, writer);
 	registerContentTools(server, writer);
 	registerAssetTools(server, writer);
+	registerDoctorTools(server, writer, config);
 	return server;
 }
 //#endregion
@@ -1483,6 +2162,6 @@ main().catch((err) => {
 	process.exit(1);
 });
 //#endregion
-export { ContentrainWriter, createServer };
+export { ContentrainWriter, Doctor, createServer };
 
 //# sourceMappingURL=index.mjs.map