contentrain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contentrain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# `contentrain`
+
+CLI for Contentrain.
+
+`contentrain` is the local operations surface for a Contentrain project:
+
+- initialize `.contentrain/` in an existing repo
+- inspect project health and validation state
+- generate the typed `#contentrain` SDK client
+- review pending `contentrain/*` branches
+- run the local review UI
+- expose the MCP server over stdio for IDE agents
+
+This package is the human-facing companion to:
+
+- [`@contentrain/mcp`](https://github.com/contentrain/contentrain-ai/tree/main/packages/mcp) for deterministic content operations
+- [`@contentrain/query`](https://github.com/contentrain/contentrain-ai/tree/main/packages/sdk/js) for generated runtime queries
+- [`@contentrain/rules`](https://github.com/contentrain/contentrain-ai/tree/main/packages/rules) and [`@contentrain/skills`](https://github.com/contentrain/contentrain-ai/tree/main/packages/skills) for agent guidance
+
+## 🚀 Install
+
+Use `npx`:
+
+```bash
+npx contentrain init
+```
+
+Or install globally:
+
+```bash
+pnpm add -g contentrain
+contentrain status
+```
+
+Requirements:
+
+- Node.js 22+
+- Git available in `PATH`
+
+## 🧰 Commands
+
+| Command | Purpose |
+| --- | --- |
+| `contentrain init` | Initialize `.contentrain/`, git workflow, templates, and IDE rules |
+| `contentrain status` | Show project overview, models, branch pressure, and validation summary |
+| `contentrain doctor` | Check setup health, SDK freshness, orphan content, and branch limits |
+| `contentrain validate` | Validate content against schemas, optionally create review-branch fixes |
+| `contentrain generate` | Generate `.contentrain/client/` and `#contentrain` package imports |
+| `contentrain diff` | Review and merge or reject pending `contentrain/*` branches |
+| `contentrain serve` | Start the local review UI or the MCP stdio server |
+
+## 🔄 Typical Flow
+
+Initialize a project:
+
+```bash
+contentrain init
+```
+
+Check project state:
+
+```bash
+contentrain status
+contentrain doctor
+```
+
+Generate the typed SDK client:
+
+```bash
+contentrain generate
+```
+
+Validate content and create review-branch fixes when possible:
+
+```bash
+contentrain validate
+contentrain validate --fix
+```
+
+Review pending changes:
+
+```bash
+contentrain diff
+```
+
+Open the local UI:
+
+```bash
+contentrain serve
+```
+
+## 🖥 `serve` Modes
+
+`contentrain serve` has two roles.
+
+Start the local review UI:
+
+```bash
+contentrain serve
+contentrain serve --port 3333 --host localhost
+```
+
+This serves:
+
+- REST endpoints for status, content, validation, branches, and normalize data
+- a WebSocket stream for live updates
+- the embedded Vue `serve-ui` app bundled with the CLI
+
+Start the MCP server for IDE integration:
+
+```bash
+contentrain serve --stdio
+```
+
+Use stdio mode when connecting Claude Code, Cursor, Windsurf, or another MCP client to the local project.
+
+## 📦 `generate` and `#contentrain`
+
+`contentrain generate` writes a typed client to `.contentrain/client/` and injects `#contentrain` imports into your `package.json`.
+
+After generation:
+
+```ts
+import { query, singleton, dictionary, document } from '#contentrain'
+```
+
+Run with watch mode during local model/content work:
+
+```bash
+contentrain generate --watch
+```
+
+## 👀 Review Workflow
+
+Most write operations create `contentrain/*` branches in review mode.
+
+Use:
+
+```bash
+contentrain status
+contentrain diff
+```
+
+to understand:
+
+- how many active review branches exist
+- whether branch health is blocking new writes
+- what changed before merging or deleting a branch
+
+## 🤖 IDE Rules
+
+`contentrain init` installs project-level AI rules automatically:
+
+- `CLAUDE.md` for Claude Code or generic fallback
+- `.cursorrules` for Cursor
+- `.windsurfrules` for Windsurf
+
+If the target file already exists, Contentrain appends its rules instead of overwriting unrelated content where possible.
+
+## 🛠 Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter contentrain test -- --run
+pnpm --filter contentrain exec tsc --noEmit
+pnpm --filter contentrain build
+```

package/dist/context-An3xrvcP.mjs

@@ -0,0 +1,50 @@
+import { readConfig, readVocabulary } from "@contentrain/mcp/core/config";
+import { join, resolve } from "node:path";
+import { readContext } from "@contentrain/mcp/core/context";
+import { listModels } from "@contentrain/mcp/core/model-manager";
+import { contentrainDir, pathExists } from "@contentrain/mcp/util/fs";
+//#region src/utils/context.ts
+async function resolveProjectRoot(argRoot) {
+	return resolve(argRoot ?? process.env["CONTENTRAIN_PROJECT_ROOT"] ?? process.cwd());
+}
+async function loadProjectContext(projectRoot) {
+	const crDir = contentrainDir(projectRoot);
+	if (!await pathExists(join(crDir, "config.json"))) return {
+		projectRoot,
+		crDir,
+		initialized: false,
+		config: null,
+		context: null,
+		models: [],
+		vocabulary: null
+	};
+	const config = await readConfig(projectRoot);
+	if (!config) return {
+		projectRoot,
+		crDir,
+		initialized: false,
+		config: null,
+		context: null,
+		models: [],
+		vocabulary: null
+	};
+	const [context, models, vocabulary] = await Promise.all([
+		readContext(projectRoot),
+		listModels(projectRoot),
+		readVocabulary(projectRoot)
+	]);
+	return {
+		projectRoot,
+		crDir,
+		initialized: true,
+		config,
+		context,
+		models,
+		vocabulary
+	};
+}
+function requireInitialized(ctx) {
+	if (!ctx.initialized || !ctx.config) throw new Error("Project not initialized. Run `contentrain init` first.");
+}
+//#endregion
+export { requireInitialized as n, resolveProjectRoot as r, loadProjectContext as t };

package/dist/diff-otz0kGqT.mjs

@@ -0,0 +1,116 @@
+import { r as resolveProjectRoot } from "./context-An3xrvcP.mjs";
+import { i as pc } from "./ui-B5mXontH.mjs";
+import { defineCommand } from "citty";
+import { confirm, intro, isCancel, log, outro, select } from "@clack/prompts";
+import { simpleGit } from "simple-git";
+import { readConfig } from "@contentrain/mcp/core/config";
+//#region src/commands/diff.ts
+var diff_default = defineCommand({
+	meta: {
+		name: "diff",
+		description: "Review pending contentrain branches"
+	},
+	args: { root: {
+		type: "string",
+		description: "Project root path",
+		required: false
+	} },
+	async run({ args }) {
+		const projectRoot = await resolveProjectRoot(args.root);
+		const git = simpleGit(projectRoot);
+		intro(pc.bold("contentrain diff"));
+		const branches = await git.branch(["--list", "contentrain/*"]);
+		if (branches.all.length === 0) {
+			log.message("No pending contentrain branches.");
+			outro("");
+			return;
+		}
+		log.info(pc.bold(`Pending branches (${branches.all.length})`));
+		const config = await readConfig(projectRoot);
+		const baseBranch = process.env["CONTENTRAIN_BRANCH"] ?? config?.repository?.default_branch ?? ((await git.raw(["branch", "--show-current"])).trim() || "main");
+		const branchInfos = [];
+		for (const branch of branches.all) try {
+			const diffStat = await git.diffSummary([`${baseBranch}...${branch}`]);
+			branchInfos.push({
+				name: branch,
+				summary: `${diffStat.changed} file(s), +${diffStat.insertions}/-${diffStat.deletions}`,
+				files: diffStat.changed
+			});
+		} catch {
+			branchInfos.push({
+				name: branch,
+				summary: "Could not diff",
+				files: 0
+			});
+		}
+		for (const info of branchInfos) log.message(`  ${pc.yellow("●")} ${pc.bold(info.name)}  ${pc.dim(info.summary)}`);
+		const reviewChoice = await select({
+			message: "Select a branch to review",
+			options: [...branchInfos.map((b) => ({
+				value: b.name,
+				label: `${b.name} (${b.summary})`
+			})), {
+				value: "__skip",
+				label: "Done — exit"
+			}]
+		});
+		if (isCancel(reviewChoice) || reviewChoice === "__skip") {
+			outro("");
+			return;
+		}
+		const selectedBranch = reviewChoice;
+		try {
+			const diff = await git.diff([`${baseBranch}...${selectedBranch}`, "--stat"]);
+			log.info(pc.bold(`\nDiff: ${selectedBranch}`));
+			log.message(diff);
+			const fullDiff = await git.diff([`${baseBranch}...${selectedBranch}`]);
+			if (fullDiff.length < 5e3) log.message(fullDiff);
+			else log.message(pc.dim(`(${Math.round(fullDiff.length / 1024)}KB diff — too large to display inline)`));
+		} catch (error) {
+			log.error(`Could not show diff: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const action = await select({
+			message: "Action",
+			options: [
+				{
+					value: "merge",
+					label: `Merge into ${baseBranch}`
+				},
+				{
+					value: "delete",
+					label: "Delete branch (reject changes)"
+				},
+				{
+					value: "skip",
+					label: "Leave for later"
+				}
+			]
+		});
+		if (isCancel(action) || action === "skip") {
+			outro("");
+			return;
+		}
+		if (action === "merge") {
+			const confirmMerge = await confirm({ message: `Merge ${selectedBranch} into ${baseBranch}?` });
+			if (!isCancel(confirmMerge) && confirmMerge) try {
+				await git.checkout(baseBranch);
+				await git.merge([selectedBranch, "--no-edit"]);
+				await git.deleteLocalBranch(selectedBranch, true);
+				log.success(`Merged and deleted ${selectedBranch}`);
+			} catch (error) {
+				log.error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		} else if (action === "delete") {
+			const confirmDelete = await confirm({ message: `Delete ${selectedBranch}? This cannot be undone.` });
+			if (!isCancel(confirmDelete) && confirmDelete) try {
+				await git.deleteLocalBranch(selectedBranch, true);
+				log.success(`Deleted ${selectedBranch}`);
+			} catch (error) {
+				log.error(`Delete failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		outro("");
+	}
+});
+//#endregion
+export { diff_default as default };

package/dist/doctor-DyKjAIKH.mjs

@@ -0,0 +1,187 @@
+import { r as resolveProjectRoot } from "./context-An3xrvcP.mjs";
+import { i as pc, o as statusIcon } from "./ui-B5mXontH.mjs";
+import { defineCommand } from "citty";
+import { intro, log, outro, spinner } from "@clack/prompts";
+import { simpleGit } from "simple-git";
+import { readConfig } from "@contentrain/mcp/core/config";
+import { join } from "node:path";
+import { listModels, readModel } from "@contentrain/mcp/core/model-manager";
+import { contentrainDir, pathExists, readDir } from "@contentrain/mcp/util/fs";
+import { stat } from "node:fs/promises";
+import { resolveContentDir } from "@contentrain/mcp/core/content-manager";
+//#region src/commands/doctor.ts
+var doctor_default = defineCommand({
+	meta: {
+		name: "doctor",
+		description: "Check project health and environment"
+	},
+	args: { root: {
+		type: "string",
+		description: "Project root path",
+		required: false
+	} },
+	async run({ args }) {
+		const projectRoot = await resolveProjectRoot(args.root);
+		intro(pc.bold("contentrain doctor"));
+		const s = spinner();
+		s.start("Running health checks...");
+		const checks = [];
+		try {
+			const version = await simpleGit(projectRoot).version();
+			checks.push({
+				name: "Git",
+				pass: true,
+				detail: `v${version.major}.${version.minor}.${version.patch}`
+			});
+		} catch {
+			checks.push({
+				name: "Git",
+				pass: false,
+				detail: "Not installed or not in PATH"
+			});
+		}
+		const hasGit = await pathExists(join(projectRoot, ".git"));
+		checks.push({
+			name: "Git repository",
+			pass: hasGit,
+			detail: hasGit ? projectRoot : "No .git directory found"
+		});
+		const nodeVersion = process.versions.node;
+		const [major] = nodeVersion.split(".").map(Number);
+		checks.push({
+			name: "Node.js",
+			pass: (major ?? 0) >= 22,
+			detail: `v${nodeVersion}${(major ?? 0) < 22 ? " (requires ≥22)" : ""}`
+		});
+		const crDir = contentrainDir(projectRoot);
+		const hasCrDir = await pathExists(crDir);
+		const hasConfig = await pathExists(join(crDir, "config.json"));
+		const hasModels = await pathExists(join(crDir, "models"));
+		const hasContent = await pathExists(join(crDir, "content"));
+		checks.push({
+			name: ".contentrain/ structure",
+			pass: hasCrDir && hasConfig && hasModels && hasContent,
+			detail: !hasCrDir ? "Not initialized — run `contentrain init`" : [
+				hasConfig ? null : "missing config.json",
+				hasModels ? null : "missing models/",
+				hasContent ? null : "missing content/"
+			].filter(Boolean).join(", ") || "OK"
+		});
+		if (hasConfig) {
+			const config = await readConfig(projectRoot);
+			checks.push({
+				name: "Config",
+				pass: config !== null,
+				detail: config ? `stack: ${config.stack}, locales: ${config.locales.supported.join(", ")}` : "Failed to parse config.json"
+			});
+		}
+		if (hasCrDir) try {
+			const models = await listModels(projectRoot);
+			let allParseable = true;
+			for (const m of models) if (!await readModel(projectRoot, m.id)) allParseable = false;
+			checks.push({
+				name: "Models",
+				pass: allParseable,
+				detail: `${models.length} model(s)${allParseable ? ", all valid" : ", some failed to parse"}`
+			});
+		} catch {
+			checks.push({
+				name: "Models",
+				pass: false,
+				detail: "Failed to read models"
+			});
+		}
+		if (hasCrDir) {
+			const orphans = await findOrphanContent(projectRoot);
+			checks.push({
+				name: "Orphan content",
+				pass: orphans.length === 0,
+				detail: orphans.length === 0 ? "None" : `Found: ${orphans.join(", ")}`
+			});
+		}
+		if (hasGit) try {
+			const staleCount = (await simpleGit(projectRoot).branch(["--list", "contentrain/*"])).all.length;
+			checks.push({
+				name: "Pending branches",
+				pass: staleCount < 50,
+				detail: staleCount === 0 ? "None" : staleCount >= 80 ? `${staleCount} branches (BLOCKED — limit: 80)` : staleCount >= 50 ? `${staleCount} branches (WARNING — limit: 50)` : `${staleCount} contentrain branch(es)`
+			});
+		} catch {
+			checks.push({
+				name: "Pending branches",
+				pass: true,
+				detail: "Could not check"
+			});
+		}
+		const clientDir = join(crDir, "client");
+		const modelsDir = join(crDir, "models");
+		if (await pathExists(clientDir) && await pathExists(modelsDir)) try {
+			const clientStat = await stat(clientDir);
+			const modelsStat = await stat(modelsDir);
+			const fresh = clientStat.mtimeMs >= modelsStat.mtimeMs;
+			checks.push({
+				name: "SDK client",
+				pass: fresh,
+				detail: fresh ? "Up to date" : "Stale — run `contentrain generate`"
+			});
+		} catch {
+			checks.push({
+				name: "SDK client",
+				pass: true,
+				detail: "Could not check"
+			});
+		}
+		s.stop("Health checks complete");
+		const passed = checks.filter((c) => c.pass).length;
+		const failed = checks.filter((c) => !c.pass).length;
+		for (const check of checks) log.message(`${statusIcon(check.pass)} ${pc.bold(check.name)}: ${check.detail}`);
+		if (failed === 0) outro(pc.green(`All ${passed} checks passed!`));
+		else outro(pc.yellow(`${passed} passed, ${failed} failed`));
+	}
+});
+async function findOrphanContent(projectRoot) {
+	const crDir = contentrainDir(projectRoot);
+	const models = await listModels(projectRoot);
+	const orphans = [];
+	const knownContentDirs = /* @__PURE__ */ new Set();
+	for (const m of models) {
+		const full = await readModel(projectRoot, m.id);
+		const modelForPath = full ? {
+			...full,
+			content_path: full.content_path ?? m.content_path
+		} : {
+			id: m.id,
+			name: m.id,
+			kind: m.kind,
+			domain: m.domain,
+			i18n: m.i18n,
+			fields: {},
+			content_path: m.content_path
+		};
+		knownContentDirs.add(resolveContentDir(projectRoot, modelForPath));
+	}
+	const contentDir = join(crDir, "content");
+	if (await pathExists(contentDir)) {
+		const domains = await readDir(contentDir);
+		for (const domain of domains) {
+			const domainDir = join(contentDir, domain);
+			const entries = await readDir(domainDir);
+			for (const entry of entries) {
+				if (entry === ".gitkeep") continue;
+				const entryDir = join(domainDir, entry);
+				if (!knownContentDirs.has(entryDir)) orphans.push(`${domain}/${entry}`);
+			}
+		}
+	}
+	for (const dir of knownContentDirs) {
+		if (dir.startsWith(contentDir)) continue;
+		if (!await pathExists(dir)) {
+			orphans.push(`(missing custom path) ${dir}`);
+			continue;
+		}
+		await readDir(dir);
+	}
+	return orphans;
+}
+//#endregion
+export { doctor_default as default };

package/dist/generate-DDEDRLdy.mjs

@@ -0,0 +1,76 @@
+import { n as requireInitialized, r as resolveProjectRoot, t as loadProjectContext } from "./context-An3xrvcP.mjs";
+import { i as pc } from "./ui-B5mXontH.mjs";
+import { defineCommand } from "citty";
+import { intro, log, outro, spinner } from "@clack/prompts";
+import { join } from "node:path";
+import { contentrainDir } from "@contentrain/mcp/util/fs";
+import { watch } from "node:fs";
+//#region src/utils/watch.ts
+const watchPath = watch;
+//#endregion
+//#region src/commands/generate.ts
+var generate_default = defineCommand({
+	meta: {
+		name: "generate",
+		description: "Generate typed SDK client from models"
+	},
+	args: {
+		root: {
+			type: "string",
+			description: "Project root path",
+			required: false
+		},
+		watch: {
+			type: "boolean",
+			description: "Watch for changes and regenerate",
+			required: false
+		}
+	},
+	async run({ args }) {
+		const projectRoot = await resolveProjectRoot(args.root);
+		requireInitialized(await loadProjectContext(projectRoot));
+		intro(pc.bold("contentrain generate"));
+		const s = spinner();
+		s.start("Generating SDK client...");
+		try {
+			const { generate } = await import("@contentrain/query/generate");
+			const result = await generate({ projectRoot });
+			s.stop("SDK client generated");
+			log.success(`Output: ${pc.cyan(".contentrain/client/")}`);
+			log.message(`  Files:  ${result.generatedFiles.length}`);
+			log.message(`  Types:  ${result.typesCount}`);
+			log.message(`  Data:   ${result.dataModulesCount} modules`);
+			if (result.packageJsonUpdated) log.info(`${pc.cyan("#contentrain")} imports added to package.json`);
+			if (args.watch) {
+				log.info("Watching for changes... (Ctrl+C to stop)");
+				const crDir = contentrainDir(projectRoot);
+				const dirsToWatch = [
+					join(crDir, "models"),
+					join(crDir, "content"),
+					join(crDir, "config.json")
+				];
+				let debounce = null;
+				for (const dir of dirsToWatch) watchPath(dir, { recursive: true }, () => {
+					if (debounce) clearTimeout(debounce);
+					debounce = setTimeout(async () => {
+						log.info("Changes detected, regenerating...");
+						try {
+							const r = await generate({ projectRoot });
+							log.success(`Regenerated: ${r.generatedFiles.length} files`);
+						} catch (err) {
+							log.error(`Regeneration failed: ${err instanceof Error ? err.message : String(err)}`);
+						}
+					}, 500);
+				});
+				await new Promise(() => {});
+			}
+		} catch (error) {
+			s.stop("Generation failed");
+			log.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		}
+		outro("");
+	}
+});
+//#endregion
+export { generate_default as default };

package/dist/index.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from "citty";
+//#region src/index.ts
+runMain(defineCommand({
+	meta: {
+		name: "contentrain",
+		version: "0.1.0",
+		description: "Contentrain CLI — AI content governance infrastructure"
+	},
+	subCommands: {
+		init: () => import("./init-D5L_7bKE.mjs").then((m) => m.default),
+		status: () => import("./status-kF5miVty.mjs").then((m) => m.default),
+		doctor: () => import("./doctor-DyKjAIKH.mjs").then((m) => m.default),
+		validate: () => import("./validate-DnVamp3p.mjs").then((m) => m.default),
+		serve: () => import("./serve-CaCZMeHF.mjs").then((m) => m.default),
+		generate: () => import("./generate-DDEDRLdy.mjs").then((m) => m.default),
+		diff: () => import("./diff-otz0kGqT.mjs").then((m) => m.default)
+	}
+}));
+//#endregion
+export {};