@tailor-platform/erp-kit 0.2.0 → 0.2.2

package/dist/cli.mjs

@@ -0,0 +1,1613 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { arg, defineCommand, runMain } from "politty";
+import { z } from "zod";
+import chalk from "chalk";
+import fs, { existsSync, readFileSync, readdirSync } from "node:fs";
+import path, { basename, dirname, join, relative, resolve } from "node:path";
+import { execFile, execSync } from "node:child_process";
+import fg from "fast-glob";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toString } from "mdast-util-to-string";
+import { createServer, request } from "node:http";
+import { createServer as createServer$1 } from "node:net";
+import { readFile, readdir, stat } from "node:fs/promises";
+//#region src/util.ts
+const PACKAGE_ROOT = path.resolve(import.meta.dirname, "..");
+function readErpKitVersion() {
+	return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf-8")).version;
+}
+//#endregion
+//#region src/commands/lib/distribute.ts
+const SKILLS_SRC = path.join(PACKAGE_ROOT, "skills");
+const WORKFLOWS_SRC = path.join(PACKAGE_ROOT, "templates", "workflows");
+const CONFIG_SRC = path.join(PACKAGE_ROOT, "templates", "config");
+function copyDirectoryRecursive(srcDir, destDir) {
+	let copied = 0;
+	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+		const srcPath = path.join(srcDir, entry.name);
+		const destPath = path.join(destDir, entry.name);
+		if (entry.isDirectory()) copied += copyDirectoryRecursive(srcPath, destPath);
+		else {
+			fs.mkdirSync(destDir, { recursive: true });
+			fs.copyFileSync(srcPath, destPath);
+			copied++;
+		}
+	}
+	return copied;
+}
+function discoverFrameworkSkills() {
+	if (!fs.existsSync(SKILLS_SRC)) return [];
+	return fs.readdirSync(SKILLS_SRC, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith("erp-kit-")).map((entry) => entry.name);
+}
+function copySkills(cwd) {
+	const skillsDest = path.join(cwd, ".agents", "skills");
+	let removed = 0;
+	if (fs.existsSync(skillsDest)) {
+		for (const entry of fs.readdirSync(skillsDest)) if (entry.startsWith("erp-kit-")) {
+			fs.rmSync(path.join(skillsDest, entry), {
+				recursive: true,
+				force: true
+			});
+			removed++;
+		}
+	}
+	let copied = 0;
+	for (const skill of discoverFrameworkSkills()) {
+		const srcSkillDir = path.join(SKILLS_SRC, skill);
+		if (!fs.existsSync(srcSkillDir)) continue;
+		const destDir = path.join(skillsDest, skill);
+		copied += copyDirectoryRecursive(srcSkillDir, destDir);
+	}
+	return {
+		copied,
+		removed
+	};
+}
+function copyWorkflows(cwd) {
+	const workflowsDest = path.join(cwd, ".github", "workflows");
+	if (!fs.existsSync(WORKFLOWS_SRC)) return {
+		copied: 0,
+		removed: 0
+	};
+	const workflowFiles = fs.readdirSync(WORKFLOWS_SRC).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+	let copied = 0;
+	for (const file of workflowFiles) {
+		fs.mkdirSync(workflowsDest, { recursive: true });
+		fs.copyFileSync(path.join(WORKFLOWS_SRC, file), path.join(workflowsDest, file));
+		copied++;
+	}
+	return {
+		copied,
+		removed: 0
+	};
+}
+function copyConfigs(cwd) {
+	if (!fs.existsSync(CONFIG_SRC)) return {
+		copied: 0,
+		removed: 0
+	};
+	let copied = 0;
+	for (const entry of fs.readdirSync(CONFIG_SRC)) {
+		const destPath = path.join(cwd, entry);
+		fs.copyFileSync(path.join(CONFIG_SRC, entry), destPath);
+		copied++;
+	}
+	return {
+		copied,
+		removed: 0
+	};
+}
+function setupSymlink(cwd) {
+	const skillsDest = path.join(cwd, ".agents", "skills");
+	const claudeSkills = path.join(cwd, ".claude", "skills");
+	const relTarget = path.relative(path.dirname(claudeSkills), skillsDest);
+	let exists = false;
+	try {
+		fs.lstatSync(claudeSkills);
+		exists = true;
+	} catch {}
+	if (exists) {
+		if (fs.lstatSync(claudeSkills).isSymbolicLink()) {
+			if (fs.readlinkSync(claudeSkills) === relTarget) return "already_linked";
+			fs.unlinkSync(claudeSkills);
+			fs.symlinkSync(relTarget, claudeSkills);
+			return "linked";
+		}
+		return "skipped_directory";
+	}
+	fs.mkdirSync(path.dirname(claudeSkills), { recursive: true });
+	fs.symlinkSync(relTarget, claudeSkills);
+	return "linked";
+}
+function isAlreadyInitialized(cwd) {
+	const skillsDest = path.join(cwd, ".agents", "skills");
+	if (!fs.existsSync(skillsDest)) return false;
+	return fs.readdirSync(skillsDest).some((entry) => entry.startsWith("erp-kit-"));
+}
+//#endregion
+//#region src/commands/init.ts
+function runInit(cwd) {
+	console.log(chalk.bold("erp-kit init\n"));
+	if (isAlreadyInitialized(cwd)) {
+		console.log(chalk.yellow("Already initialized. Use `erp-kit update` to refresh framework resources."));
+		return 1;
+	}
+	const skills = copySkills(cwd);
+	console.log(chalk.green(`  Copied ${skills.copied} skill files to .agents/skills/`));
+	const symlink = setupSymlink(cwd);
+	if (symlink === "linked") console.log(chalk.green("  .claude/skills -> .agents/skills/ (linked)"));
+	else if (symlink === "skipped_directory") console.log(chalk.yellow("  Skipped .claude/skills (directory exists, not a symlink)"));
+	const workflows = copyWorkflows(cwd);
+	if (workflows.copied > 0) console.log(chalk.green(`  Copied ${workflows.copied} workflow(s) to .github/workflows/`));
+	const configs = copyConfigs(cwd);
+	if (configs.copied > 0) console.log(chalk.green(`  Copied ${configs.copied} config file(s)`));
+	console.log(chalk.bold.green("\nDone! Run `erp-kit check` to validate your docs."));
+	return 0;
+}
+//#endregion
+//#region src/commands/update.ts
+const VALID_RESOURCES = ["skills", "workflows"];
+function runUpdate(cwd, resources) {
+	console.log(chalk.bold("erp-kit update\n"));
+	const selected = resources.length === 0 ? new Set(VALID_RESOURCES) : new Set(resources.filter((r) => VALID_RESOURCES.includes(r)));
+	if (selected.size === 0) {
+		console.error(chalk.red(`Invalid resource. Valid: ${VALID_RESOURCES.join(", ")}`));
+		return 1;
+	}
+	if (selected.has("skills")) {
+		const result = copySkills(cwd);
+		if (result.removed > 0) console.log(chalk.green(`  Removed ${result.removed} stale erp-kit-* skills`));
+		console.log(chalk.green(`  Copied ${result.copied} skill files to .agents/skills/`));
+	}
+	if (selected.has("workflows")) {
+		const result = copyWorkflows(cwd);
+		if (result.copied > 0) console.log(chalk.green(`  Copied ${result.copied} workflow(s) to .github/workflows/`));
+	}
+	console.log(chalk.bold.green("\nDone!"));
+	return 0;
+}
+//#endregion
+//#region src/commands/license.ts
+const licenseGroups = {
+	reciprocal: [
+		"APSL-1.0",
+		"APSL-1.1",
+		"APSL-1.2",
+		"APSL-2.0",
+		"CDDL-1.0",
+		"CDDL-1.1",
+		"CPL-1.0",
+		"EPL-1.0",
+		"EPL-2.0",
+		"FreeImage",
+		"IPL-1.0",
+		"MPL-1.0",
+		"MPL-1.1",
+		"MPL-2.0",
+		"Ruby"
+	],
+	notice: [
+		"AFL-1.1",
+		"AFL-1.2",
+		"AFL-2.0",
+		"AFL-2.1",
+		"AFL-3.0",
+		"Apache-1.0",
+		"Apache-1.1",
+		"Apache-2.0",
+		"Artistic-1.0-cl8",
+		"Artistic-1.0-Perl",
+		"Artistic-1.0",
+		"Artistic-2.0",
+		"BSL-1.0",
+		"BSD-2-Clause-FreeBSD",
+		"BSD-2-Clause-NetBSD",
+		"BSD-2-Clause",
+		"BSD-3-Clause-Attribution",
+		"BSD-3-Clause-Clear",
+		"BSD-3-Clause-LBNL",
+		"BSD-3-Clause",
+		"BSD-4-Clause",
+		"BSD-4-Clause-UC",
+		"BSD-Protection",
+		"CC-BY-1.0",
+		"CC-BY-2.0",
+		"CC-BY-2.5",
+		"CC-BY-3.0",
+		"CC-BY-4.0",
+		"FTL",
+		"ISC",
+		"ImageMagick",
+		"Libpng",
+		"Lil-1.0",
+		"Linux-OpenIB",
+		"LPL-1.02",
+		"LPL-1.0",
+		"MS-PL",
+		"MIT",
+		"NCSA",
+		"OpenSSL",
+		"PHP-3.01",
+		"PHP-3.0",
+		"PIL",
+		"Python-2.0",
+		"Python-2.0-complete",
+		"PostgreSQL",
+		"SGI-B-1.0",
+		"SGI-B-1.1",
+		"SGI-B-2.0",
+		"Unicode-DFS-2015",
+		"Unicode-DFS-2016",
+		"Unicode-TOU",
+		"UPL-1.0",
+		"W3C-19980720",
+		"W3C-20150513",
+		"W3C",
+		"X11",
+		"Xnet",
+		"Zend-2.0",
+		"zlib-acknowledgement",
+		"Zlib",
+		"ZPL-1.1",
+		"ZPL-2.0",
+		"ZPL-2.1"
+	],
+	unencumbered: [
+		"CC0-1.0",
+		"Unlicense",
+		"0BSD"
+	]
+};
+function buildAllowSet(config) {
+	const set = /* @__PURE__ */ new Set();
+	for (const group of config.groups) for (const license of licenseGroups[group]) set.add(license);
+	if (config.allow) for (const license of config.allow) set.add(license);
+	if (config.deny) for (const license of config.deny) set.delete(license);
+	return set;
+}
+function isLicenseAllowed(licenseString, allowSet) {
+	if (/\s+(?:OR|AND)\s+/i.test(licenseString)) return licenseString.replace(/[()]/g, "").trim().split(/\s+(?:OR|AND)\s+/i).map((l) => l.trim()).filter((l) => l.length > 0).every((l) => allowSet.has(l));
+	return allowSet.has(licenseString);
+}
+function runLicenseList() {
+	for (const [group, licenses] of Object.entries(licenseGroups)) {
+		console.log(`${group} (${licenses.length} licenses):`);
+		for (const license of licenses) console.log(`  ${license}`);
+		console.log();
+	}
+	return 0;
+}
+function runLicenseCheck(configPath) {
+	const raw = fs.readFileSync(configPath, "utf-8");
+	const config = JSON.parse(raw);
+	const validGroups = Object.keys(licenseGroups);
+	for (const group of config.groups) if (!validGroups.includes(group)) {
+		console.error(`Unknown license group: "${group}". Valid groups: ${validGroups.join(", ")}`);
+		return 2;
+	}
+	const allowSet = buildAllowSet(config);
+	console.log("Checking licenses...\n");
+	execSync("pnpm licenses list", { stdio: "inherit" });
+	const output = execSync("pnpm licenses list --json");
+	const licensesJson = JSON.parse(output.toString());
+	const violations = [];
+	for (const [license, packages] of Object.entries(licensesJson)) if (!isLicenseAllowed(license, allowSet)) for (const pkg of packages) violations.push({
+		package: pkg.name,
+		license
+	});
+	if (violations.length === 0) {
+		console.log("All licenses are allowed.");
+		return 0;
+	}
+	console.error("Found dependencies with disallowed licenses:\n");
+	for (const violation of violations) {
+		console.error(`  - ${violation.package}`);
+		console.error(`    License: ${violation.license}\n`);
+	}
+	return 1;
+}
+//#endregion
+//#region src/mdschema.ts
+const require = createRequire(import.meta.url);
+function getMdschemaBin() {
+	const pkgPath = require.resolve("@jackchuka/mdschema/package.json");
+	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+	const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.mdschema;
+	if (!bin) throw new Error("Could not resolve mdschema binary from package.json bin field");
+	return path.join(path.dirname(pkgPath), bin);
+}
+function runMdschema(args, cwd) {
+	return new Promise((resolve) => {
+		execFile(getMdschemaBin(), args, {
+			encoding: "utf-8",
+			cwd,
+			timeout: 3e4
+		}, (error, stdout, stderr) => {
+			if (error) {
+				const execError = error;
+				resolve({
+					exitCode: execError.code === "ENOENT" ? 127 : execError.status ?? 1,
+					stdout: stdout ?? "",
+					stderr: stderr ?? ""
+				});
+			} else resolve({
+				exitCode: 0,
+				stdout: stdout ?? "",
+				stderr: stderr ?? ""
+			});
+		});
+	});
+}
+//#endregion
+//#region src/schemas.ts
+const SCHEMAS_ROOT = path.join(PACKAGE_ROOT, "schemas");
+const MODULE_SCHEMAS = {
+	module: path.join(SCHEMAS_ROOT, "module", "module.yml"),
+	command: path.join(SCHEMAS_ROOT, "module", "command.yml"),
+	model: path.join(SCHEMAS_ROOT, "module", "model.yml"),
+	feature: path.join(SCHEMAS_ROOT, "module", "feature.yml"),
+	query: path.join(SCHEMAS_ROOT, "module", "query.yml")
+};
+const APP_COMPOSE_SCHEMAS = {
+	app: path.join(SCHEMAS_ROOT, "app-compose", "requirements.yml"),
+	actors: path.join(SCHEMAS_ROOT, "app-compose", "actors.yml"),
+	"business-flow": path.join(SCHEMAS_ROOT, "app-compose", "business-flow.yml"),
+	story: path.join(SCHEMAS_ROOT, "app-compose", "story.yml"),
+	screen: path.join(SCHEMAS_ROOT, "app-compose", "screen.yml"),
+	resolver: path.join(SCHEMAS_ROOT, "app-compose", "resolver.yml")
+};
+const ALL_SCHEMAS = {
+	...MODULE_SCHEMAS,
+	...APP_COMPOSE_SCHEMAS
+};
+//#endregion
+//#region src/commands/check.ts
+function buildCheckTargets(config) {
+	const targets = [];
+	if (config.modulesRoot) {
+		const m = config.modulesRoot;
+		targets.push({
+			glob: `${m}/[a-zA-Z]*/docs/features/*.md`,
+			schemaKey: "feature"
+		}, {
+			glob: `${m}/[a-zA-Z]*/docs/commands/*.md`,
+			schemaKey: "command"
+		}, {
+			glob: `${m}/[a-zA-Z]*/docs/models/*.md`,
+			schemaKey: "model"
+		}, {
+			glob: `${m}/[a-zA-Z]*/docs/queries/*.md`,
+			schemaKey: "query"
+		}, {
+			glob: `${m}/[a-zA-Z]*/README.md`,
+			schemaKey: "module"
+		});
+	}
+	if (config.appRoot) {
+		const a = config.appRoot;
+		targets.push({
+			glob: `${a}/[a-zA-Z]*/README.md`,
+			schemaKey: "app"
+		}, {
+			glob: `${a}/[a-zA-Z]*/docs/actors/*.md`,
+			schemaKey: "actors"
+		}, {
+			glob: `${a}/[a-zA-Z]*/docs/business-flow/*/README.md`,
+			schemaKey: "business-flow"
+		}, {
+			glob: `${a}/[a-zA-Z]*/docs/business-flow/*/story/*.md`,
+			schemaKey: "story"
+		}, {
+			glob: `${a}/[a-zA-Z]*/docs/screen/*.md`,
+			schemaKey: "screen"
+		}, {
+			glob: `${a}/[a-zA-Z]*/docs/resolver/*.md`,
+			schemaKey: "resolver"
+		});
+	}
+	return targets;
+}
+async function runCheck(config, cwd) {
+	const targets = buildCheckTargets(config);
+	const results = await Promise.all(targets.map(async (target) => {
+		const schemaPath = ALL_SCHEMAS[target.schemaKey];
+		if (!schemaPath) {
+			console.error(`Unknown schema key: ${target.schemaKey}`);
+			return 2;
+		}
+		const { exitCode, stdout, stderr } = await runMdschema([
+			"check",
+			target.glob,
+			"--schema",
+			schemaPath
+		], cwd);
+		if (stdout.trim()) console.log(stdout);
+		if (stderr.trim()) console.error(stderr);
+		return exitCode;
+	}));
+	if (results.includes(2)) return 2;
+	return results.some((code) => code !== 0) ? 1 : 0;
+}
+//#endregion
+//#region src/commands/parse-doc-test-cases.ts
+function isHeading$1(node) {
+	return node.type === "heading";
+}
+function isList$1(node) {
+	return node.type === "list";
+}
+/**
+* Parse test case descriptions from the `## Test Cases` section of a Markdown doc.
+* Uses mdast to traverse the AST instead of string matching.
+*/
+function parseTestCasesFromDoc(markdown) {
+	const tree = fromMarkdown(markdown);
+	const cases = [];
+	let collecting = false;
+	for (const node of tree.children) {
+		if (isHeading$1(node)) {
+			if (collecting) break;
+			if (node.depth === 2 && toString(node) === "Test Cases") {
+				collecting = true;
+				continue;
+			}
+		}
+		if (collecting && isList$1(node)) for (const item of node.children) {
+			const text = toString(item).trim();
+			if (text) cases.push(text);
+		}
+	}
+	return cases;
+}
+/**
+* Parse `it("...")` descriptions from a test file using regex.
+* Test files are not Markdown, so regex is appropriate here.
+*/
+function parseItDescriptionsFromTest(content) {
+	const descriptions = [];
+	const regex = /\bit\(\s*["'`]([^"'`]+)["'`]/g;
+	let match;
+	while ((match = regex.exec(content)) !== null) descriptions.push(match[1]);
+	return descriptions;
+}
+//#endregion
+//#region src/commands/sync-check.ts
+function moduleCategories(root) {
+	return [
+		{
+			name: "command",
+			sourcePattern: `${root}/*/command/*.ts`,
+			docPattern: `${root}/*/docs/commands/*.md`,
+			exclusions: [/\.test\.ts$/, /\.generated\.ts$/]
+		},
+		{
+			name: "model",
+			sourcePattern: `${root}/*/db/*.ts`,
+			docPattern: `${root}/*/docs/models/*.md`,
+			exclusions: [/\.test\.ts$/, /^index\.ts$/]
+		},
+		{
+			name: "query",
+			sourcePattern: `${root}/*/query/*.ts`,
+			docPattern: `${root}/*/docs/queries/*.md`,
+			exclusions: [/\.test\.ts$/]
+		}
+	];
+}
+function appComposeCategories(root) {
+	return [{
+		name: "resolver",
+		sourcePattern: `${root}/*/backend/src/modules/**/resolvers/*.ts`,
+		docPattern: `${root}/*/docs/resolver/*.md`,
+		exclusions: [/\.test\.ts$/, /^index\.ts$/]
+	}];
+}
+function shouldExclude(fileName, exclusions) {
+	return exclusions.some((pattern) => pattern.test(fileName));
+}
+async function runSyncCheck(config, cwd) {
+	const errors = [];
+	let totalSources = 0;
+	let totalDocs = 0;
+	const allCategories = [];
+	if (config.modulesRoot) allCategories.push(...moduleCategories(config.modulesRoot));
+	if (config.appRoot) allCategories.push(...appComposeCategories(config.appRoot));
+	for (const category of allCategories) {
+		const sources = await fg(category.sourcePattern, { cwd });
+		const docs = await fg(category.docPattern, { cwd });
+		const sourceBasenames = /* @__PURE__ */ new Map();
+		const docBasenames = /* @__PURE__ */ new Map();
+		for (const sourcePath of sources) {
+			if (shouldExclude(path.basename(sourcePath), category.exclusions)) continue;
+			let basename = path.basename(sourcePath, path.extname(sourcePath));
+			if (basename.endsWith(".generated")) basename = basename.slice(0, -10);
+			sourceBasenames.set(basename.toLowerCase(), sourcePath);
+		}
+		for (const docPath of docs) {
+			const basename = path.basename(docPath, path.extname(docPath));
+			docBasenames.set(basename.toLowerCase(), docPath);
+		}
+		for (const [basename, sourcePath] of sourceBasenames) if (!docBasenames.has(basename)) errors.push({
+			type: "missing-doc",
+			category: category.name,
+			sourcePath,
+			expectedBasename: basename
+		});
+		for (const [basename, docPath] of docBasenames) if (!sourceBasenames.has(basename)) errors.push({
+			type: "orphaned-doc",
+			category: category.name,
+			docPath,
+			expectedBasename: basename
+		});
+		totalSources += sourceBasenames.size;
+		totalDocs += docBasenames.size;
+	}
+	if (config.modulesRoot) {
+		const testCaseErrors = await runTestCaseSyncCheck(config.modulesRoot, cwd);
+		errors.push(...testCaseErrors);
+	}
+	return {
+		exitCode: errors.length > 0 ? 1 : 0,
+		errors,
+		summary: {
+			categoriesChecked: allCategories.length,
+			totalSources,
+			totalDocs
+		}
+	};
+}
+function testCaseCategories(root) {
+	return [{
+		name: "command-test-case",
+		docPattern: `${root}/*/docs/commands/*.md`,
+		testDir: "command"
+	}, {
+		name: "query-test-case",
+		docPattern: `${root}/*/docs/queries/*.md`,
+		testDir: "query"
+	}];
+}
+function toCamelCase(pascalCase) {
+	return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
+}
+async function runTestCaseSyncCheck(root, cwd) {
+	const errors = [];
+	const categories = testCaseCategories(root);
+	for (const category of categories) {
+		const docPaths = await fg(category.docPattern, { cwd });
+		for (const docPath of docPaths) {
+			const docFullPath = path.join(cwd, docPath);
+			const docTestCases = parseTestCasesFromDoc(fs.readFileSync(docFullPath, "utf-8"));
+			if (docTestCases.length === 0) continue;
+			const docBasename = path.basename(docPath, ".md");
+			const docsIndex = docPath.indexOf("/docs/");
+			if (docsIndex === -1) continue;
+			const modulePath = docPath.substring(0, docsIndex);
+			const testFileName = `${toCamelCase(docBasename)}.test.ts`;
+			const testPath = path.join(modulePath, category.testDir, testFileName);
+			const testFullPath = path.join(cwd, testPath);
+			if (!fs.existsSync(testFullPath)) continue;
+			const itDescriptions = parseItDescriptionsFromTest(fs.readFileSync(testFullPath, "utf-8"));
+			const docSet = new Set(docTestCases);
+			const testSet = new Set(itDescriptions);
+			for (const docCase of docSet) if (!testSet.has(docCase)) errors.push({
+				type: "missing-test-case",
+				category: category.name,
+				docPath,
+				sourcePath: testPath,
+				expectedBasename: docCase
+			});
+			for (const testCase of testSet) if (!docSet.has(testCase)) errors.push({
+				type: "extra-test-case",
+				category: category.name,
+				docPath,
+				sourcePath: testPath,
+				expectedBasename: testCase
+			});
+		}
+	}
+	return errors;
+}
+function formatSyncCheckReport(result) {
+	const lines = [];
+	lines.push(chalk.bold("docs-sync-check: Checking source-documentation correspondence...\n"));
+	if (result.errors.length > 0) {
+		lines.push(chalk.red.bold("Errors:\n"));
+		const byCategory = /* @__PURE__ */ new Map();
+		for (const error of result.errors) {
+			const existing = byCategory.get(error.category) ?? [];
+			existing.push(error);
+			byCategory.set(error.category, existing);
+		}
+		for (const [category, categoryErrors] of byCategory) {
+			lines.push(chalk.cyan(`  Category: ${category}\n`));
+			for (const error of categoryErrors) {
+				if (error.type === "missing-doc") {
+					lines.push(`  ${chalk.red(error.sourcePath)}`);
+					lines.push(`    ${chalk.yellow("Missing documentation for:")} ${error.expectedBasename}`);
+				} else if (error.type === "orphaned-doc") {
+					lines.push(`  ${chalk.red(error.docPath)}`);
+					lines.push(`    ${chalk.yellow("Orphaned documentation:")} no source file for ${error.expectedBasename}`);
+				} else if (error.type === "missing-test-case") {
+					lines.push(`  ${chalk.red(error.sourcePath)}`);
+					lines.push(`    ${chalk.yellow("Missing test case:")} "${error.expectedBasename}" is in doc but not in test`);
+				} else if (error.type === "extra-test-case") {
+					lines.push(`  ${chalk.red(error.sourcePath)}`);
+					lines.push(`    ${chalk.yellow("Extra test case:")} "${error.expectedBasename}" is in test but not in doc`);
+				}
+				lines.push("");
+			}
+		}
+	} else lines.push(chalk.green("All source files have corresponding documentation.\n"));
+	lines.push(chalk.bold("Summary:"));
+	lines.push(`  Categories checked: ${result.summary.categoriesChecked}`);
+	lines.push(`  Source files: ${result.summary.totalSources}, Doc files: ${result.summary.totalDocs}`);
+	if (result.errors.length > 0) {
+		lines.push(chalk.red(`  Errors: ${result.errors.length}`));
+		lines.push("");
+		lines.push(chalk.red.bold(`docs-sync-check failed with ${result.errors.length} error(s).`));
+	} else {
+		lines.push(chalk.green("  Errors: 0"));
+		lines.push("");
+		lines.push(chalk.green.bold("docs-sync-check passed."));
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/scaffold.ts
+const MODULE_TYPES = [
+	"module",
+	"feature",
+	"command",
+	"model",
+	"query"
+];
+const APP_TYPES = [
+	"app",
+	"actors",
+	"business-flow",
+	"story",
+	"screen",
+	"resolver"
+];
+[...MODULE_TYPES, ...APP_TYPES];
+const MODULE_DIR_MAP = {
+	feature: "docs/features",
+	command: "docs/commands",
+	model: "docs/models",
+	query: "docs/queries"
+};
+const APP_DIR_MAP = {
+	actors: "docs/actors",
+	"business-flow": "docs/business-flow",
+	screen: "docs/screen",
+	resolver: "docs/resolver"
+};
+function resolveScaffoldPath(type, parentName, name, root) {
+	if (type === "module" || type === "app") return path.join(root, parentName, "README.md");
+	if (!name) throw new Error(`Name is required for scaffold type "${type}"`);
+	if (type === "business-flow") return path.join(root, parentName, "docs/business-flow", name, "README.md");
+	if (type === "story") {
+		const parts = name.split("/");
+		if (parts.length !== 2) throw new Error(`Story name must be "<flow>/<story>" (e.g., "onboarding/admin--create-user")`);
+		return path.join(root, parentName, "docs/business-flow", parts[0], "story", `${parts[1]}.md`);
+	}
+	if (MODULE_DIR_MAP[type]) return path.join(root, parentName, MODULE_DIR_MAP[type], `${name}.md`);
+	if (APP_DIR_MAP[type]) return path.join(root, parentName, APP_DIR_MAP[type], `${name}.md`);
+	throw new Error(`Unknown scaffold type: ${type}`);
+}
+async function runScaffold(type, parentName, name, root, cwd) {
+	const outputPath = resolveScaffoldPath(type, parentName, name, root);
+	const absoluteOutput = path.resolve(cwd, outputPath);
+	if (fs.existsSync(absoluteOutput)) {
+		console.error(`File already exists: ${outputPath}`);
+		return 1;
+	}
+	const schemaPath = ALL_SCHEMAS[type];
+	if (!schemaPath) {
+		console.error(`No schema found for type: ${type}`);
+		return 2;
+	}
+	try {
+		fs.mkdirSync(path.dirname(absoluteOutput), { recursive: true });
+	} catch (err) {
+		console.error(`Failed to create directory: ${err instanceof Error ? err.message : String(err)}`);
+		return 1;
+	}
+	const { exitCode, stdout, stderr } = await runMdschema([
+		"generate",
+		"--schema",
+		schemaPath,
+		"--output",
+		absoluteOutput
+	], cwd);
+	if (stdout.trim()) console.log(stdout);
+	if (stderr.trim()) console.error(stderr);
+	if (exitCode !== 0) return exitCode;
+	if (type === "module") scaffoldModuleSrc(path.dirname(absoluteOutput), parentName);
+	if (type === "app") scaffoldAppSrc(path.dirname(absoluteOutput), parentName);
+	return exitCode;
+}
+function copyTemplateDir(srcDir, destDir, replacements, placeholderFiles) {
+	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+		const srcPath = path.join(srcDir, entry.name);
+		const destName = entry.name === "__dot__gitignore" ? ".gitignore" : entry.name;
+		const destPath = path.join(destDir, destName);
+		if (entry.isDirectory()) {
+			fs.mkdirSync(destPath, { recursive: true });
+			copyTemplateDir(srcPath, destPath, replacements, placeholderFiles);
+		} else {
+			fs.mkdirSync(path.dirname(destPath), { recursive: true });
+			if (placeholderFiles.has(entry.name)) {
+				let content = fs.readFileSync(srcPath, "utf-8");
+				for (const [from, to] of Object.entries(replacements)) content = content.replaceAll(from, to);
+				fs.writeFileSync(destPath, content);
+			} else fs.copyFileSync(srcPath, destPath);
+		}
+	}
+}
+function scaffoldModuleSrc(moduleDir, moduleName) {
+	copyTemplateDir(path.join(PACKAGE_ROOT, "templates", "scaffold", "module"), moduleDir, { "template-module": moduleName }, new Set(["permissions.ts", "tailor.config.ts"]));
+}
+function scaffoldAppSrc(appDir, appName) {
+	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "app");
+	const erpKitVersion = readErpKitVersion();
+	copyTemplateDir(templateDir, appDir, {
+		"template-app-frontend": `${appName}-frontend`,
+		"template-app-backend": appName,
+		"template-app": appName,
+		"\"workspace:*\"": `"${erpKitVersion}"`
+	}, new Set([
+		"package.json",
+		"tailor.config.ts",
+		"index.html"
+	]));
+}
+//#endregion
+//#region src/commands/module/list.ts
+const MODULES_DIR = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS = new Set(["shared", "testing"]);
+function countFiles(dir, pattern, exclusions) {
+	if (!existsSync(dir)) return 0;
+	return readdirSync(dir).filter((f) => pattern.test(f) && !exclusions.some((p) => p.test(f))).length;
+}
+function listModules() {
+	if (!existsSync(MODULES_DIR)) return [];
+	return readdirSync(MODULES_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && !EXCLUDED_DIRS.has(d.name)).map((d) => {
+		const modDir = join(MODULES_DIR, d.name);
+		return {
+			name: d.name,
+			commands: countFiles(join(modDir, "command"), /\.ts$/, [/\.test\.ts$/]),
+			models: countFiles(join(modDir, "db"), /\.ts$/, [/\.test\.ts$/, /^index\.ts$/]),
+			features: countFiles(join(modDir, "docs", "features"), /\.md$/, [])
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name));
+}
+function formatModuleList(modules) {
+	if (modules.length === 0) return "No modules found.";
+	const lines = [];
+	lines.push(chalk.bold("Modules:\n"));
+	const nameWidth = Math.max(...modules.map((m) => m.name.length), 4);
+	for (const mod of modules) {
+		const counts = [
+			`${mod.commands} commands`,
+			`${mod.models} models`,
+			`${mod.features} features`
+		].join(", ");
+		lines.push(`  ${mod.name.padEnd(nameWidth)}  ${counts}`);
+	}
+	lines.push("");
+	lines.push(`${modules.length} modules`);
+	return lines.join("\n");
+}
+function runModuleList() {
+	const modules = listModules();
+	console.log(formatModuleList(modules));
+	return 0;
+}
+//#endregion
+//#region src/generator/parse-command-doc.ts
+function parseCommandDoc(fileName, markdown) {
+	const commandName = fileName.charAt(0).toLowerCase() + fileName.slice(1);
+	const tree = fromMarkdown(markdown);
+	return {
+		commandName,
+		errors: parseErrorScenarios(tree),
+		externalDependencies: parseExternalDependencies(tree)
+	};
+}
+function errorCodeToClassName(code) {
+	return code.toLowerCase().split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("") + "Error";
+}
+function isHeading(node) {
+	return node.type === "heading";
+}
+function isList(node) {
+	return node.type === "list";
+}
+function getNodesUnderHeading(tree, headingText) {
+	const nodes = [];
+	let collecting = false;
+	for (const node of tree.children) {
+		if (isHeading(node)) {
+			if (collecting) break;
+			if (node.depth === 2 && toString(node) === headingText) {
+				collecting = true;
+				continue;
+			}
+		}
+		if (collecting) nodes.push(node);
+	}
+	return nodes;
+}
+const ERROR_PATTERN = /^([A-Z_]+):\s*(.+)$/;
+function parseErrorScenarios(tree) {
+	const nodes = getNodesUnderHeading(tree, "Error Scenarios");
+	const errors = [];
+	for (const node of nodes) {
+		if (!isList(node)) continue;
+		for (const item of node.children) {
+			const text = toString(item);
+			const match = ERROR_PATTERN.exec(text);
+			if (match) errors.push({
+				code: match[1],
+				description: match[2].trim()
+			});
+		}
+	}
+	return errors;
+}
+const DEPENDENCY_PATTERN = /^([^:]+)::(.+)$/;
+function parseExternalDependencies(tree) {
+	const nodes = getNodesUnderHeading(tree, "External Dependencies");
+	const deps = [];
+	for (const node of nodes) {
+		if (!isList(node)) continue;
+		for (const item of node.children) {
+			const firstChild = item.children[0];
+			if (firstChild?.type !== "paragraph") continue;
+			for (const inline of firstChild.children) if (inline.type === "link" || inline.type === "linkReference") {
+				const linkText = toString(inline);
+				const match = DEPENDENCY_PATTERN.exec(linkText);
+				if (match) deps.push({
+					module: match[1],
+					entity: match[2]
+				});
+			}
+		}
+	}
+	return deps;
+}
+//#endregion
+//#region src/generator/generate-code.ts
+function moduleNameToPrefix(moduleName) {
+	return moduleName.toUpperCase().replace(/-/g, "_");
+}
+function generateErrors(moduleName, docs) {
+	const seen = /* @__PURE__ */ new Set();
+	const lines = [];
+	const prefix = moduleNameToPrefix(moduleName);
+	for (const doc of docs) for (const error of doc.errors) {
+		if (seen.has(error.code)) continue;
+		seen.add(error.code);
+		const className = errorCodeToClassName(error.code);
+		const prefixedCode = `${prefix}_${error.code}`;
+		lines.push(`export const ${className} = createDomainError(`);
+		lines.push(`  "${className}", "${prefixedCode}",`);
+		const escapedDesc = error.description.replace(/`/g, "'");
+		lines.push(`  (identifier: string) => \`${escapedDesc}: \${identifier}\`,`);
+		lines.push(`);`);
+		lines.push(``);
+	}
+	if (lines.length === 0) return "";
+	return `// @generated — do not edit
+import { createDomainError } from "../../../shared";
+
+${lines.join("\n")}`;
+}
+function generateCommandStub(doc) {
+	const inputType = `${doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1)}Input`;
+	return `import { ok, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+
+export interface ${inputType} {
+  // TODO: define input fields
+}
+
+export async function run(db: Transaction, input: ${inputType}, ctx: CommandContext) {
+  // TODO: implement
+  return ok({});
+}
+`;
+}
+function generateTestStub(doc) {
+	const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
+	return `import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { run, ${pascal}Input } from "./${doc.commandName}";
+
+describe("${doc.commandName} - test scenario", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["TODO:${doc.commandName}"],
+  };
+
+  it("should be implemented", async () => {
+    const { db } = createMockDb<Transaction>();
+    const result = await run(db, {} as ${pascal}Input, ctx);
+    expect(result.ok).toBe(true);
+  });
+});
+`;
+}
+function generateCommandShell(doc) {
+	return [
+		`// @generated — do not edit`,
+		`import { defineCommand } from "../../../shared";`,
+		`import { permissions } from "../lib/permissions.generated";`,
+		`import { run } from "./${doc.commandName}";`,
+		``,
+		`export const ${doc.commandName} = defineCommand(permissions.${doc.commandName}, run);`,
+		``
+	].join("\n");
+}
+function generateQueryShell(doc) {
+	return [
+		`// @generated — do not edit`,
+		`import { defineQuery } from "../../../shared";`,
+		`import { run } from "./${doc.commandName}";`,
+		``,
+		`export const ${doc.commandName} = defineQuery(run);`,
+		``
+	].join("\n");
+}
+function generateQueryStub(doc) {
+	const inputType = `${doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1)}Input`;
+	return `import type { ReadonlyDB } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface ${inputType} {
+  // TODO: define input fields
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ${inputType}) {
+  // TODO: implement
+  return {};
+}
+`;
+}
+function generateQueryTestStub(doc) {
+	const inputType = `${doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1)}Input`;
+	return `import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { run, type ${inputType} } from "./${doc.commandName}";
+
+describe("${doc.commandName}", () => {
+  it("should be implemented", async () => {
+    const { db } = createMockDb<DB>();
+    const result = await run(db, {} as ${inputType});
+    expect(result).toBeDefined();
+  });
+});
+`;
+}
+function generatePermissions(moduleName, commandNames) {
+	return `// @generated — do not edit
+import { definePermissions } from "../../../shared";
+
+export const { permissions, own, all } = definePermissions("${moduleName}", [
+${[...commandNames].sort().map((name) => `  "${name}",`).join("\n")}
+] as const);
+`;
+}
+function runGenerateCode(modulePath, moduleName) {
+	const docsDir = path.join(modulePath, "docs", "commands");
+	const libDir = path.join(modulePath, "lib");
+	const commandDir = path.join(modulePath, "command");
+	if (!fs.existsSync(docsDir)) {
+		console.error(`No docs/commands/ directory found at ${docsDir}`);
+		return 1;
+	}
+	const mdFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md"));
+	if (mdFiles.length === 0) {
+		console.error(`No command docs found in ${docsDir}`);
+		return 1;
+	}
+	const parsedDocs = [];
+	for (const file of mdFiles) {
+		const content = fs.readFileSync(path.join(docsDir, file), "utf-8");
+		const name = path.basename(file, ".md");
+		parsedDocs.push(parseCommandDoc(name, content));
+	}
+	const queryDocsDir = path.join(modulePath, "docs", "queries");
+	const allDocsForErrors = [...parsedDocs];
+	if (fs.existsSync(queryDocsDir)) {
+		const queryFiles = fs.readdirSync(queryDocsDir).filter((f) => f.endsWith(".md"));
+		for (const file of queryFiles) {
+			const content = fs.readFileSync(path.join(queryDocsDir, file), "utf-8");
+			const name = path.basename(file, ".md");
+			allDocsForErrors.push(parseCommandDoc(name, content));
+		}
+	}
+	let generated = 0;
+	const errorsContent = generateErrors(moduleName, allDocsForErrors);
+	if (errorsContent) {
+		fs.mkdirSync(libDir, { recursive: true });
+		const errorsFile = path.join(libDir, "errors.generated.ts");
+		fs.writeFileSync(errorsFile, errorsContent);
+		console.log(`  wrote ${path.relative(modulePath, errorsFile)}`);
+		generated++;
+	}
+	const permissionsContent = generatePermissions(moduleName, parsedDocs.map((d) => d.commandName));
+	const permissionsFile = path.join(libDir, "permissions.generated.ts");
+	fs.writeFileSync(permissionsFile, permissionsContent);
+	console.log(`  wrote ${path.relative(modulePath, permissionsFile)}`);
+	generated++;
+	fs.mkdirSync(commandDir, { recursive: true });
+	for (const doc of parsedDocs) {
+		const implFile = path.join(commandDir, `${doc.commandName}.ts`);
+		const shellContent = generateCommandShell(doc);
+		const shellFile = path.join(commandDir, `${doc.commandName}.generated.ts`);
+		fs.writeFileSync(shellFile, shellContent);
+		console.log(`  wrote ${path.relative(modulePath, shellFile)}`);
+		generated++;
+		if (!fs.existsSync(implFile)) {
+			fs.writeFileSync(implFile, generateCommandStub(doc));
+			console.log(`  scaffolded ${path.relative(modulePath, implFile)}`);
+		}
+		const testFile = path.join(commandDir, `${doc.commandName}.test.ts`);
+		if (!fs.existsSync(testFile)) {
+			fs.writeFileSync(testFile, generateTestStub(doc));
+			console.log(`  scaffolded ${path.relative(modulePath, testFile)}`);
+		}
+	}
+	if (fs.existsSync(queryDocsDir)) {
+		const queryFiles = fs.readdirSync(queryDocsDir).filter((f) => f.endsWith(".md"));
+		if (queryFiles.length > 0) {
+			const queryDir = path.join(modulePath, "query");
+			fs.mkdirSync(queryDir, { recursive: true });
+			for (const file of queryFiles) {
+				const content = fs.readFileSync(path.join(queryDocsDir, file), "utf-8");
+				const doc = parseCommandDoc(path.basename(file, ".md"), content);
+				const shellFile = path.join(queryDir, `${doc.commandName}.generated.ts`);
+				fs.writeFileSync(shellFile, generateQueryShell(doc));
+				console.log(`  wrote ${path.relative(modulePath, shellFile)}`);
+				generated++;
+				const implFile = path.join(queryDir, `${doc.commandName}.ts`);
+				if (!fs.existsSync(implFile)) {
+					fs.writeFileSync(implFile, generateQueryStub(doc));
+					console.log(`  scaffolded ${path.relative(modulePath, implFile)}`);
+				}
+				const testFile = path.join(queryDir, `${doc.commandName}.test.ts`);
+				if (!fs.existsSync(testFile)) {
+					fs.writeFileSync(testFile, generateQueryTestStub(doc));
+					console.log(`  scaffolded ${path.relative(modulePath, testFile)}`);
+				}
+			}
+		}
+	}
+	console.log(`Generated ${generated} file(s) for ${moduleName}`);
+	return 0;
+}
+//#endregion
+//#region src/commands/module/generate.ts
+const cwd$3 = process.cwd();
+const generateCommand = defineCommand({
+	name: "generate",
+	description: "Generate code from model definitions and docs",
+	subCommands: { code: defineCommand({
+		name: "code",
+		description: "Generate errors, permissions, command shells, and query shells from docs",
+		args: z.object({
+			root: arg(z.string(), {
+				alias: "r",
+				description: "Path to modules directory"
+			}),
+			module: arg(z.string(), {
+				positional: true,
+				description: "Module name (e.g., primitives, item-management)"
+			})
+		}),
+		run: (args) => {
+			const modulePath = path.resolve(cwd$3, args.root, args.module);
+			console.log(`Generating code for ${args.module}...`);
+			const exitCode = runGenerateCode(modulePath, args.module);
+			process.exit(exitCode);
+		}
+	}) }
+});
+//#endregion
+//#region src/commands/module/index.ts
+const cwd$2 = process.cwd();
+const rootArgs$1 = z.object({ root: arg(z.string(), {
+	alias: "r",
+	description: "Path to modules directory"
+}) });
+const listCommand = defineCommand({
+	name: "list",
+	description: "List available modules",
+	run: () => {
+		const exitCode = runModuleList();
+		process.exit(exitCode);
+	}
+});
+const checkCommand$1 = defineCommand({
+	name: "check",
+	description: "Validate module docs against schemas",
+	args: rootArgs$1,
+	run: async (args) => {
+		const exitCode = await runCheck({ modulesRoot: args.root }, cwd$2);
+		process.exit(exitCode);
+	}
+});
+const syncCheckCommand$1 = defineCommand({
+	name: "sync-check",
+	description: "Validate source <-> doc correspondence",
+	args: rootArgs$1,
+	run: async (args) => {
+		const result = await runSyncCheck({ modulesRoot: args.root }, cwd$2);
+		console.log(formatSyncCheckReport(result));
+		process.exit(result.exitCode);
+	}
+});
+const scaffoldCommand$1 = defineCommand({
+	name: "scaffold",
+	description: "Generate module doc from schema template",
+	args: rootArgs$1.extend({
+		type: arg(z.enum(MODULE_TYPES), {
+			positional: true,
+			description: `Scaffold type (${MODULE_TYPES.join(", ")})`
+		}),
+		parent: arg(z.string(), {
+			positional: true,
+			description: "Module name"
+		}),
+		name: arg(z.string().optional(), {
+			positional: true,
+			description: "Item name (required for feature, command, model)"
+		})
+	}),
+	run: async (args) => {
+		const exitCode = await runScaffold(args.type, args.parent, args.name, args.root, cwd$2);
+		process.exit(exitCode);
+	}
+});
+const moduleCommand = defineCommand({
+	name: "module",
+	description: "Module management",
+	subCommands: {
+		list: listCommand,
+		check: checkCommand$1,
+		"sync-check": syncCheckCommand$1,
+		scaffold: scaffoldCommand$1,
+		generate: generateCommand
+	}
+});
+//#endregion
+//#region src/commands/app/index.ts
+const cwd$1 = process.cwd();
+const rootArgs = z.object({ root: arg(z.string(), {
+	alias: "r",
+	description: "Path to app-compose directory"
+}) });
+const checkCommand = defineCommand({
+	name: "check",
+	description: "Validate app docs against schemas",
+	args: rootArgs,
+	run: async (args) => {
+		const exitCode = await runCheck({ appRoot: args.root }, cwd$1);
+		process.exit(exitCode);
+	}
+});
+const syncCheckCommand = defineCommand({
+	name: "sync-check",
+	description: "Validate source <-> doc correspondence",
+	args: rootArgs,
+	run: async (args) => {
+		const result = await runSyncCheck({ appRoot: args.root }, cwd$1);
+		console.log(formatSyncCheckReport(result));
+		process.exit(result.exitCode);
+	}
+});
+const scaffoldCommand = defineCommand({
+	name: "scaffold",
+	description: "Generate app doc from schema template",
+	args: rootArgs.extend({
+		type: arg(z.enum(APP_TYPES), {
+			positional: true,
+			description: `Scaffold type (${APP_TYPES.join(", ")})`
+		}),
+		parent: arg(z.string(), {
+			positional: true,
+			description: "App name"
+		}),
+		name: arg(z.string().optional(), {
+			positional: true,
+			description: "Item name (required for most types)"
+		})
+	}),
+	run: async (args) => {
+		const exitCode = await runScaffold(args.type, args.parent, args.name, args.root, cwd$1);
+		process.exit(exitCode);
+	}
+});
+const appCommand = defineCommand({
+	name: "app",
+	description: "App-compose management",
+	subCommands: {
+		check: checkCommand,
+		"sync-check": syncCheckCommand,
+		scaffold: scaffoldCommand
+	}
+});
+//#endregion
+//#region src/mockServer.ts
+/**
+* Start a Mockoon mock server from a mock.json file.
+* Returns a handle with the server URL and a stop function.
+*/
+async function createMockServer(mockJsonPath, port) {
+	const { MockoonServer, createLoggerInstance, listenServerEvents } = await import("@mockoon/commons-server");
+	const resolvedPath = resolve(mockJsonPath);
+	const environment = JSON.parse(readFileSync(resolvedPath, "utf-8"));
+	if (port !== void 0) environment.port = port;
+	const actualPort = environment.port;
+	const logger = createLoggerInstance(null);
+	const server = new MockoonServer(environment, {
+		environmentDirectory: dirname(resolvedPath),
+		enableAdminApi: false,
+		disableTls: true,
+		enableRandomLatency: false,
+		maxTransactionLogs: 100,
+		envVarsPrefix: "MOCKOON_"
+	});
+	listenServerEvents(server, environment, logger, false);
+	await new Promise((resolve, reject) => {
+		server.on("started", resolve);
+		server.on("error", (errorCode, originalError) => {
+			reject(originalError ?? /* @__PURE__ */ new Error(`Mockoon error: ${errorCode}`));
+		});
+		server.start();
+	});
+	return {
+		url: `http://127.0.0.1:${actualPort}`,
+		port: actualPort,
+		stop: () => new Promise((resolve) => {
+			server.on("stopped", resolve);
+			server.stop();
+		})
+	};
+}
+//#endregion
+//#region src/commands/mock/start.ts
+function readdirSafe(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+	} catch {
+		return [];
+	}
+}
+function discoverMocks(mocksDir, filters) {
+	const mocks = [];
+	for (const provider of readdirSafe(mocksDir)) {
+		const providerDir = join(mocksDir, provider);
+		for (const scenario of readdirSafe(providerDir)) {
+			const mockPath = join(providerDir, scenario, "mock.json");
+			if (!existsSync(mockPath)) continue;
+			mocks.push({
+				provider,
+				scenario,
+				mockPath
+			});
+		}
+	}
+	if (filters.length === 0) return mocks;
+	return mocks.filter(({ provider, scenario }) => filters.some((f) => f === provider || f === `${provider}/${scenario}`));
+}
+function findFreePort() {
+	return new Promise((resolve, reject) => {
+		const srv = createServer$1();
+		srv.listen(0, "127.0.0.1", () => {
+			const addr = srv.address();
+			const port = typeof addr === "object" && addr ? addr.port : 0;
+			srv.close(() => resolve(port));
+		});
+		srv.on("error", reject);
+	});
+}
+async function startMock(mock) {
+	const port = await findFreePort();
+	return {
+		server: await createMockServer(mock.mockPath, port),
+		route: `/${mock.provider}/${mock.scenario}`,
+		provider: mock.provider,
+		scenario: mock.scenario
+	};
+}
+function createProxy(routeTable) {
+	return createServer((req, res) => {
+		const match = req.url?.match(/^\/([^/?]+)\/([^/?]+)(\/[^?]*)?(\?.*)?$/);
+		if (!match) {
+			res.writeHead(404, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "Not found. Use /{provider}/{scenario}/..." }));
+			return;
+		}
+		const [, provider, scenario] = match;
+		const key = `/${provider}/${scenario}`;
+		const target = routeTable.get(key);
+		if (!target) {
+			res.writeHead(404, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({
+				error: `Unknown route: ${key}`,
+				available: [...routeTable.keys()]
+			}));
+			return;
+		}
+		const downstream = (req.url ?? "/").slice(key.length) || "/";
+		const proxyReq = request({
+			hostname: "127.0.0.1",
+			port: target.server.port,
+			path: downstream,
+			method: req.method,
+			headers: {
+				...req.headers,
+				host: `127.0.0.1:${target.server.port}`
+			}
+		}, (proxyRes) => {
+			res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+			proxyRes.pipe(res);
+		});
+		proxyReq.on("error", (err) => {
+			if (!res.headersSent) res.writeHead(502, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({
+				error: "Bad gateway",
+				detail: err.message
+			}));
+		});
+		req.pipe(proxyReq);
+	});
+}
+async function runMockStart(mocksRoot, filters, port) {
+	const mocksDir = resolve(mocksRoot);
+	const mocks = discoverMocks(mocksDir, filters);
+	if (mocks.length === 0) {
+		console.error("No matching mocks found.");
+		if (filters.length > 0) {
+			console.error(`Filters: ${filters.join(", ")}`);
+			console.error(`Available mocks are under: ${relative(process.cwd(), mocksDir)}/`);
+		}
+		return 1;
+	}
+	console.log(`Starting ${mocks.length} mock(s)...\n`);
+	const running = [];
+	for (const mock of mocks) {
+		const info = await startMock(mock);
+		running.push(info);
+	}
+	const routeTable = /* @__PURE__ */ new Map();
+	for (const r of running) routeTable.set(r.route, r);
+	console.log("Route table:");
+	console.log("─".repeat(50));
+	for (const [route, { server }] of routeTable) console.log(`  ${route}  \u2192  127.0.0.1:${server.port}`);
+	console.log("─".repeat(50));
+	const proxy = createProxy(routeTable);
+	proxy.listen(port, () => {
+		console.log(`\nReverse proxy listening on http://localhost:${port}`);
+		console.log("Press Ctrl+C to stop all mocks.\n");
+	});
+	function shutdown() {
+		console.log("\nShutting down...");
+		proxy.close();
+		for (const { server } of running) server.stop();
+		process.exit(0);
+	}
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+	return new Promise(() => void 0);
+}
+//#endregion
+//#region src/commands/mock/validate.ts
+function pass(msg) {
+	console.log(chalk.green(`\u2713 ${msg}`));
+}
+function fail(ctx, msg) {
+	console.log(chalk.red(`\u2717 ${msg}`));
+	ctx.failures++;
+}
+async function subdirs(dir) {
+	const entries = await readdir(dir);
+	const dirs = [];
+	for (const entry of entries) if ((await stat(join(dir, entry))).isDirectory()) dirs.push(entry);
+	return dirs.sort();
+}
+function checkStructure(ctx, entries, label) {
+	if (entries.includes("README.md")) pass(`${label}: has README.md`);
+	else fail(ctx, `${label}: missing README.md`);
+	if (entries.includes("mock.json")) {
+		pass(`${label}: has mock.json`);
+		return true;
+	}
+	fail(ctx, `${label}: missing mock.json`);
+	return false;
+}
+async function checkSchema(ctx, data, label) {
+	const result = (await import("@mockoon/commons")).EnvironmentSchemaNoFix.validate(data, { abortEarly: false });
+	if (!result.error) pass(`${label}: valid Mockoon schema`);
+	else for (const detail of result.error.details) fail(ctx, `${label}: schema — ${detail.message}`);
+}
+function checkResponseQuality(ctx, data, label) {
+	const routes = data.routes ?? [];
+	for (const route of routes) for (const resp of route.responses ?? []) {
+		const respLabel = `${label} \u2192 ${route.uuid}/${resp.uuid}`;
+		if ((resp.headers ?? []).some((h) => h.key.toLowerCase() === "content-type")) pass(`${respLabel}: has Content-Type`);
+		else fail(ctx, `${respLabel}: missing Content-Type header`);
+		if (resp.label && resp.label.trim().length > 0) pass(`${respLabel}: has label "${resp.label}"`);
+		else fail(ctx, `${respLabel}: missing or empty label`);
+	}
+}
+function checkDatabucketRefs(ctx, data, label) {
+	const bucketIds = new Set((data.data ?? []).map((d) => d.id));
+	for (const route of data.routes ?? []) for (const resp of route.responses ?? []) if (resp.bodyType === "DATABUCKET") {
+		const respLabel = `${label} \u2192 ${route.uuid}/${resp.uuid}`;
+		if (resp.databucketID && bucketIds.has(resp.databucketID)) pass(`${respLabel}: databucket "${resp.databucketID}" exists`);
+		else fail(ctx, `${respLabel}: databucketID "${resp.databucketID}" not found in data array`);
+	}
+}
+async function discoverAllScenarios(mocksDir) {
+	const scenarios = [];
+	const providers = await subdirs(mocksDir);
+	for (const provider of providers) {
+		const providerDir = join(mocksDir, provider);
+		for (const scenario of await subdirs(providerDir)) scenarios.push(`${provider}/${scenario}`);
+	}
+	return scenarios;
+}
+function resolveScenarioDir(arg) {
+	const abs = resolve(arg);
+	if (basename(abs) === "mock.json") return dirname(abs);
+	return abs;
+}
+async function validateScenario(ctx, scenarioDir, mocksDir) {
+	const label = relative(mocksDir, scenarioDir);
+	console.log(chalk.bold(`\n\u2500\u2500 ${label} \u2500\u2500`));
+	let entries;
+	try {
+		entries = await readdir(scenarioDir);
+	} catch {
+		fail(ctx, `${label}: directory not found`);
+		return;
+	}
+	if (!checkStructure(ctx, entries, label)) return;
+	const mockPath = join(scenarioDir, "mock.json");
+	let data;
+	try {
+		data = JSON.parse(await readFile(mockPath, "utf-8"));
+	} catch (err) {
+		fail(ctx, `${label}: invalid JSON \u2014 ${err instanceof Error ? err.message : String(err)}`);
+		return;
+	}
+	await checkSchema(ctx, data, label);
+	checkResponseQuality(ctx, data, label);
+	checkDatabucketRefs(ctx, data, label);
+}
+async function runMockValidate(mocksRoot, paths) {
+	const ctx = { failures: 0 };
+	const mocksDir = resolve(mocksRoot);
+	const targets = paths.length > 0 ? paths.map(resolveScenarioDir) : (await discoverAllScenarios(mocksDir)).map((s) => join(mocksDir, s));
+	if (targets.length === 0) {
+		fail(ctx, "No scenarios found under mocks/");
+		return 1;
+	}
+	console.log(chalk.bold("\nValidating mock configs...\n"));
+	for (const target of targets) await validateScenario(ctx, target, mocksDir);
+	console.log(chalk.bold("\n── summary ──"));
+	if (ctx.failures === 0) console.log(chalk.green("✓ All checks passed"));
+	else console.log(chalk.red(`\u2717 ${ctx.failures} check(s) failed`));
+	return ctx.failures === 0 ? 0 : 1;
+}
+const mockCommand = defineCommand({
+	name: "mock",
+	description: "Mock API server management",
+	subCommands: {
+		start: defineCommand({
+			name: "start",
+			description: "Start mock API servers with reverse proxy",
+			args: z.object({
+				mocksRoot: arg(z.string().default("./mocks"), { description: "Path to mocks directory" }),
+				port: arg(z.coerce.number().default(3e3), {
+					alias: "p",
+					description: "Reverse proxy port"
+				}),
+				filter: arg(z.array(z.string()).default([]), {
+					positional: true,
+					description: "Filter by provider or provider/scenario"
+				})
+			}),
+			run: async (args) => {
+				const exitCode = await runMockStart(args.mocksRoot, args.filter, args.port);
+				process.exit(exitCode);
+			}
+		}),
+		validate: defineCommand({
+			name: "validate",
+			description: "Validate mock scenario configs",
+			args: z.object({
+				mocksRoot: arg(z.string().default("./mocks"), { description: "Path to mocks directory" }),
+				paths: arg(z.array(z.string()).default([]), {
+					positional: true,
+					description: "Specific scenario paths to validate"
+				})
+			}),
+			run: async (args) => {
+				const exitCode = await runMockValidate(args.mocksRoot, args.paths);
+				process.exit(exitCode);
+			}
+		})
+	}
+});
+//#endregion
+//#region src/commands/index.ts
+const cwd = process.cwd();
+//#endregion
+//#region src/cli.ts
+runMain(defineCommand({
+	name: "erp-kit",
+	description: "ERP module framework CLI",
+	subCommands: {
+		module: moduleCommand,
+		app: appCommand,
+		mock: mockCommand,
+		init: defineCommand({
+			name: "init",
+			description: "First-time setup for a consumer repo",
+			run: () => {
+				const exitCode = runInit(cwd);
+				process.exit(exitCode);
+			}
+		}),
+		update: defineCommand({
+			name: "update",
+			description: "Refresh framework-managed resources (skills, workflows)",
+			args: z.object({ resources: arg(z.array(z.string()).default([]), {
+				positional: true,
+				description: "Resources to update (skills, workflows). Defaults to all."
+			}) }),
+			run: (args) => {
+				const exitCode = runUpdate(cwd, args.resources);
+				process.exit(exitCode);
+			}
+		}),
+		license: defineCommand({
+			name: "license",
+			description: "License management",
+			subCommands: {
+				check: defineCommand({
+					name: "check",
+					description: "Check dependency licenses against allowlist",
+					args: z.object({ config: arg(z.string(), {
+						alias: "c",
+						description: "Path to license config JSON file"
+					}) }),
+					run: (args) => {
+						const exitCode = runLicenseCheck(args.config);
+						process.exit(exitCode);
+					}
+				}),
+				list: defineCommand({
+					name: "list",
+					description: "List available license groups",
+					run: () => {
+						const exitCode = runLicenseList();
+						process.exit(exitCode);
+					}
+				})
+			}
+		})
+	}
+}));
+//#endregion
+export {};