@soda-gql/cli 0.8.0 → 0.9.0

package/dist/index.cjs

@@ -26,17 +26,115 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+let neverthrow = require("neverthrow");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let __soda_gql_builder = require("@soda-gql/builder");
 let __soda_gql_config = require("@soda-gql/config");
 let __soda_gql_codegen = require("@soda-gql/codegen");
-let neverthrow = require("neverthrow");
 let zod = require("zod");
+let node_fs = require("node:fs");
 let fast_glob = require("fast-glob");
 fast_glob = __toESM(fast_glob);
-let node_fs = require("node:fs");
 
+//#region packages/cli/src/errors.ts
+/**
+* Error constructor helpers for concise error creation.
+* Each function returns a specific error type for better type inference.
+*/
+const cliErrors = {
+	argsInvalid: (command, message) => ({
+		category: "cli",
+		code: "CLI_ARGS_INVALID",
+		message,
+		command
+	}),
+	unknownCommand: (command) => ({
+		category: "cli",
+		code: "CLI_UNKNOWN_COMMAND",
+		message: `Unknown command: ${command}`,
+		command
+	}),
+	unknownSubcommand: (parent, subcommand) => ({
+		category: "cli",
+		code: "CLI_UNKNOWN_SUBCOMMAND",
+		message: `Unknown subcommand: ${subcommand}`,
+		parent,
+		subcommand
+	}),
+	fileExists: (filePath, message) => ({
+		category: "cli",
+		code: "CLI_FILE_EXISTS",
+		message: message ?? `File already exists: ${filePath}. Use --force to overwrite.`,
+		filePath
+	}),
+	fileNotFound: (filePath, message) => ({
+		category: "cli",
+		code: "CLI_FILE_NOT_FOUND",
+		message: message ?? `File not found: ${filePath}`,
+		filePath
+	}),
+	writeFailed: (filePath, message, cause) => ({
+		category: "cli",
+		code: "CLI_WRITE_FAILED",
+		message: message ?? `Failed to write file: ${filePath}`,
+		filePath,
+		cause
+	}),
+	readFailed: (filePath, message, cause) => ({
+		category: "cli",
+		code: "CLI_READ_FAILED",
+		message: message ?? `Failed to read file: ${filePath}`,
+		filePath,
+		cause
+	}),
+	noPatterns: (message) => ({
+		category: "cli",
+		code: "CLI_NO_PATTERNS",
+		message: message ?? "No patterns provided and config not found. Usage: soda-gql format [patterns...] [--check]"
+	}),
+	formatterNotInstalled: (message) => ({
+		category: "cli",
+		code: "CLI_FORMATTER_NOT_INSTALLED",
+		message: message ?? "@soda-gql/formatter is not installed. Run: bun add @soda-gql/formatter"
+	}),
+	parseError: (message, filePath) => ({
+		category: "cli",
+		code: "CLI_PARSE_ERROR",
+		message,
+		filePath
+	}),
+	formatError: (message, filePath) => ({
+		category: "cli",
+		code: "CLI_FORMAT_ERROR",
+		message,
+		filePath
+	}),
+	unexpected: (message, cause) => ({
+		category: "cli",
+		code: "CLI_UNEXPECTED",
+		message,
+		cause
+	}),
+	fromCodegen: (error) => ({
+		category: "codegen",
+		error
+	}),
+	fromBuilder: (error) => ({
+		category: "builder",
+		error
+	}),
+	fromArtifact: (error) => ({
+		category: "artifact",
+		error
+	}),
+	fromConfig: (error) => ({
+		category: "config",
+		error
+	})
+};
+
+//#endregion
 //#region packages/cli/src/commands/artifact/build.ts
 const BUILD_HELP = `Usage: soda-gql artifact build [options]
 
@@ -78,33 +176,29 @@ const parseBuildArgs = (argv) => {
 	}
 	return args;
 };
+const formatSuccess$3 = (data) => {
+	const { artifact, outputPath, dryRun } = data;
+	const fragmentCount = Object.values(artifact.elements).filter((e) => e.type === "fragment").length;
+	const operationCount = Object.values(artifact.elements).filter((e) => e.type === "operation").length;
+	const lines = [];
+	if (dryRun) lines.push(`Validation passed: ${fragmentCount} fragments, ${operationCount} operations`);
+	else lines.push(`Build complete: ${fragmentCount} fragments, ${operationCount} operations`);
+	if (artifact.meta?.version) lines.push(`  Version: ${artifact.meta.version}`);
+	if (outputPath && !dryRun) lines.push(`Artifact written to: ${outputPath}`);
+	return lines.join("\n");
+};
 /**
 * Build command - builds and validates soda-gql artifacts.
 */
 const buildCommand = async (argv) => {
 	const args = parseBuildArgs(argv);
-	if (args.help) {
-		process.stdout.write(BUILD_HELP);
-		return 0;
-	}
+	if (args.help) return (0, neverthrow.ok)({ message: BUILD_HELP });
 	const configResult = (0, __soda_gql_config.loadConfig)(args.configPath);
-	if (configResult.isErr()) {
-		const error = configResult.error;
-		process.stderr.write(`Error: Failed to load config\n`);
-		process.stderr.write(`  at ${error.filePath}\n`);
-		process.stderr.write(`  ${error.message}\n`);
-		return 1;
-	}
+	if (configResult.isErr()) return (0, neverthrow.err)(cliErrors.fromConfig(configResult.error));
 	const config = configResult.value;
 	const buildResult = await (0, __soda_gql_builder.createBuilderService)({ config }).buildAsync();
-	if (buildResult.isErr()) {
-		const formattedError = (0, __soda_gql_builder.formatBuilderErrorForCLI)(buildResult.error);
-		process.stderr.write(`${formattedError}\n`);
-		return 1;
-	}
+	if (buildResult.isErr()) return (0, neverthrow.err)(cliErrors.fromBuilder(buildResult.error));
 	const artifact = buildResult.value;
-	const fragmentCount = Object.values(artifact.elements).filter((e) => e.type === "fragment").length;
-	const operationCount = Object.values(artifact.elements).filter((e) => e.type === "operation").length;
 	const meta = args.version ? {
 		version: args.version,
 		createdAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -114,17 +208,33 @@ const buildCommand = async (argv) => {
 		...artifact
 	};
 	if (args.dryRun) {
-		process.stdout.write(`Validation passed: ${fragmentCount} fragments, ${operationCount} operations\n`);
-		if (args.version) process.stdout.write(`  Version: ${args.version}\n`);
-	} else {
-		const outputPath = (0, node_path.resolve)(process.cwd(), args.outputPath);
-		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(outputPath), { recursive: true });
+		const data$1 = {
+			artifact: artifactWithMeta,
+			dryRun: true
+		};
+		return (0, neverthrow.ok)({
+			message: formatSuccess$3(data$1),
+			data: data$1
+		});
+	}
+	const outputPath = (0, node_path.resolve)(process.cwd(), args.outputPath);
+	const outputDir = (0, node_path.dirname)(outputPath);
+	try {
+		await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
 		await (0, node_fs_promises.writeFile)(outputPath, JSON.stringify(artifactWithMeta, null, 2));
-		process.stdout.write(`Build complete: ${fragmentCount} fragments, ${operationCount} operations\n`);
-		if (args.version) process.stdout.write(`  Version: ${args.version}\n`);
-		process.stdout.write(`Artifact written to: ${outputPath}\n`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return (0, neverthrow.err)(cliErrors.writeFailed(outputPath, `Failed to write artifact: ${message}`, error));
 	}
-	return 0;
+	const data = {
+		artifact: artifactWithMeta,
+		outputPath,
+		dryRun: false
+	};
+	return (0, neverthrow.ok)({
+		message: formatSuccess$3(data),
+		data
+	});
 };
 
 //#endregion
@@ -155,36 +265,27 @@ const parseValidateArgs = (argv) => {
 	else if (!arg.startsWith("-")) args.artifactPath = arg;
 	return args;
 };
+const formatSuccess$2 = (artifact) => {
+	const lines = [`Artifact valid: ${Object.values(artifact.elements).filter((e) => e.type === "fragment").length} fragments, ${Object.values(artifact.elements).filter((e) => e.type === "operation").length} operations`];
+	if (artifact.meta) {
+		lines.push(`  Version: ${artifact.meta.version}`);
+		lines.push(`  Created: ${artifact.meta.createdAt}`);
+	} else lines.push(`  (No metadata - legacy artifact format)`);
+	return lines.join("\n");
+};
 /**
 * Validate command - validates a pre-built artifact file.
 */
 const validateCommand = async (argv) => {
 	const args = parseValidateArgs(argv);
-	if (args.help) {
-		process.stdout.write(VALIDATE_HELP);
-		return 0;
-	}
-	if (!args.artifactPath) {
-		process.stderr.write("Error: Missing artifact path argument\n\n");
-		process.stdout.write(VALIDATE_HELP);
-		return 1;
-	}
+	if (args.help) return (0, neverthrow.ok)({ message: VALIDATE_HELP });
+	if (!args.artifactPath) return (0, neverthrow.err)(cliErrors.argsInvalid("artifact validate", "Missing artifact path argument"));
 	const result = await (0, __soda_gql_builder.loadArtifact)((0, node_path.resolve)(process.cwd(), args.artifactPath));
-	if (result.isErr()) {
-		const error = result.error;
-		process.stderr.write(`Validation failed: ${error.message}\n`);
-		if (error.filePath) process.stderr.write(`  File: ${error.filePath}\n`);
-		return 1;
-	}
-	const artifact = result.value;
-	const fragmentCount = Object.values(artifact.elements).filter((e) => e.type === "fragment").length;
-	const operationCount = Object.values(artifact.elements).filter((e) => e.type === "operation").length;
-	process.stdout.write(`Artifact valid: ${fragmentCount} fragments, ${operationCount} operations\n`);
-	if (artifact.meta) {
-		process.stdout.write(`  Version: ${artifact.meta.version}\n`);
-		process.stdout.write(`  Created: ${artifact.meta.createdAt}\n`);
-	} else process.stdout.write(`  (No metadata - legacy artifact format)\n`);
-	return 0;
+	if (result.isErr()) return (0, neverthrow.err)(cliErrors.fromArtifact(result.error));
+	return (0, neverthrow.ok)({
+		message: formatSuccess$2(result.value),
+		data: result.value
+	});
 };
 
 //#endregion
@@ -204,15 +305,10 @@ Run 'soda-gql artifact <subcommand> --help' for more information.
 */
 const artifactCommand = async (argv) => {
 	const [subcommand, ...rest] = argv;
-	if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-		process.stdout.write(ARTIFACT_HELP);
-		return 0;
-	}
+	if (!subcommand || subcommand === "--help" || subcommand === "-h") return (0, neverthrow.ok)({ message: ARTIFACT_HELP });
 	if (subcommand === "build") return buildCommand(rest);
 	if (subcommand === "validate") return validateCommand(rest);
-	process.stderr.write(`Unknown subcommand: ${subcommand}\n`);
-	process.stderr.write(`Run 'soda-gql artifact --help' for available subcommands.\n`);
-	return 1;
+	return (0, neverthrow.err)(cliErrors.unknownSubcommand("artifact", subcommand));
 };
 
 //#endregion
@@ -262,28 +358,16 @@ const parseArgs = (args, schema) => {
 //#region packages/cli/src/commands/codegen.ts
 const parseCodegenArgs = (argv) => {
 	const parsed = parseArgs([...argv], CodegenArgsSchema);
-	if (!parsed.isOk()) return (0, neverthrow.err)({
-		code: "EMIT_FAILED",
-		message: parsed.error,
-		outPath: ""
-	});
+	if (!parsed.isOk()) return (0, neverthrow.err)(cliErrors.argsInvalid("codegen", parsed.error));
 	const args = parsed.value;
 	if (args["emit-inject-template"]) return (0, neverthrow.ok)({
 		kind: "emitInjectTemplate",
 		outPath: args["emit-inject-template"]
 	});
 	const configResult = (0, __soda_gql_config.loadConfig)(args.config);
-	if (configResult.isErr()) return (0, neverthrow.err)({
-		code: "EMIT_FAILED",
-		message: `Failed to load config: ${configResult.error.message}`,
-		outPath: ""
-	});
+	if (configResult.isErr()) return (0, neverthrow.err)(cliErrors.fromConfig(configResult.error));
 	const config = configResult.value;
-	if (!config.schemas || Object.keys(config.schemas).length === 0) return (0, neverthrow.err)({
-		code: "EMIT_FAILED",
-		message: "schemas configuration is required in soda-gql.config.ts",
-		outPath: ""
-	});
+	if (!config.schemas || Object.keys(config.schemas).length === 0) return (0, neverthrow.err)(cliErrors.argsInvalid("codegen", "schemas configuration is required in soda-gql.config.ts"));
 	const schemas = {};
 	for (const [name, schemaConfig] of Object.entries(config.schemas)) schemas[name] = {
 		schema: schemaConfig.schema,
@@ -305,20 +389,6 @@ const formatSuccess$1 = (success) => {
 const formatTemplateSuccess = (outPath) => {
 	return `Created inject template → ${outPath}`;
 };
-const errorHints = {
-	SCHEMA_NOT_FOUND: "Verify the schema path in soda-gql.config.ts",
-	SCHEMA_INVALID: "Check your GraphQL schema for syntax errors",
-	INJECT_MODULE_NOT_FOUND: "Run: soda-gql codegen --emit-inject-template <path>",
-	INJECT_MODULE_REQUIRED: "Add inject configuration to your schema in soda-gql.config.ts",
-	INJECT_TEMPLATE_EXISTS: "Delete the existing file to regenerate, or use a different path",
-	EMIT_FAILED: "Check write permissions and that the output directory exists"
-};
-const formatCodegenError = (error) => {
-	const message = "message" in error ? error.message : "Unknown error";
-	const hint = errorHints[error.code];
-	const hintLine = hint ? `\n  Hint: ${hint}` : "";
-	return `${error.code}: ${message}${hintLine}`;
-};
 const CODEGEN_HELP = `Usage: soda-gql codegen [options]
 
 Generate graphql-system runtime module from GraphQL schema.
@@ -333,58 +403,521 @@ Examples:
   soda-gql codegen --emit-inject-template ./src/graphql/scalars.ts
 `;
 const codegenCommand = async (argv) => {
-	if (argv.includes("--help") || argv.includes("-h")) {
-		process.stdout.write(CODEGEN_HELP);
-		return 0;
+	if (argv.includes("--help") || argv.includes("-h")) return (0, neverthrow.ok)({ message: CODEGEN_HELP });
+	const parsed = parseCodegenArgs(argv);
+	if (parsed.isErr()) return (0, neverthrow.err)(parsed.error);
+	const command = parsed.value;
+	if (command.kind === "emitInjectTemplate") {
+		const outPath = (0, node_path.resolve)(command.outPath);
+		const result$1 = (0, __soda_gql_codegen.writeInjectTemplate)(outPath);
+		if (result$1.isErr()) return (0, neverthrow.err)(cliErrors.fromCodegen(result$1.error));
+		return (0, neverthrow.ok)({ message: formatTemplateSuccess(outPath) });
 	}
+	const resolvedSchemas = {};
+	for (const [name, schemaConfig] of Object.entries(command.schemas)) resolvedSchemas[name] = {
+		schema: (0, node_path.resolve)(schemaConfig.schema),
+		inject: {
+			scalars: (0, node_path.resolve)(schemaConfig.inject.scalars),
+			...schemaConfig.inject.adapter ? { adapter: (0, node_path.resolve)(schemaConfig.inject.adapter) } : {}
+		},
+		defaultInputDepth: schemaConfig.defaultInputDepth,
+		inputDepthOverrides: schemaConfig.inputDepthOverrides
+	};
+	const result = await (0, __soda_gql_codegen.runCodegen)({
+		schemas: resolvedSchemas,
+		outPath: (0, node_path.resolve)(command.outPath),
+		format: "human",
+		importExtension: command.importExtension
+	});
+	if (result.isErr()) return (0, neverthrow.err)(cliErrors.fromCodegen(result.error));
+	return (0, neverthrow.ok)({
+		message: formatSuccess$1(result.value),
+		data: result.value
+	});
+};
+
+//#endregion
+//#region packages/cli/src/commands/doctor/checks/codegen-freshness.ts
+/**
+* Codegen freshness check.
+* @module
+*/
+/**
+* Check if generated code is newer than schema files.
+*/
+const checkCodegenFreshness = () => {
+	const configPath = (0, __soda_gql_config.findConfigFile)();
+	if (!configPath) return {
+		name: "Codegen Freshness",
+		status: "skip",
+		message: "No soda-gql.config.ts found",
+		data: { schemas: [] }
+	};
+	const configResult = (0, __soda_gql_config.loadConfig)(configPath);
+	if (configResult.isErr()) return {
+		name: "Codegen Freshness",
+		status: "skip",
+		message: "Could not load config",
+		data: { schemas: [] }
+	};
+	const config = configResult.value;
+	const generatedPath = (0, node_path.join)(config.outdir, "index.ts");
+	if (!(0, node_fs.existsSync)(generatedPath)) return {
+		name: "Codegen Freshness",
+		status: "warn",
+		message: "Generated code not found - run codegen",
+		data: { schemas: [] },
+		fix: "Run: soda-gql codegen"
+	};
+	const generatedMtime = (0, node_fs.statSync)(generatedPath).mtimeMs;
+	const schemaResults = [];
+	let hasStale = false;
+	for (const [name, schemaConfig] of Object.entries(config.schemas)) {
+		if (!(0, node_fs.existsSync)(schemaConfig.schema)) continue;
+		const schemaMtime = (0, node_fs.statSync)(schemaConfig.schema).mtimeMs;
+		const isStale = schemaMtime > generatedMtime;
+		if (isStale) hasStale = true;
+		schemaResults.push({
+			name,
+			schemaPath: schemaConfig.schema,
+			generatedPath,
+			schemaMtime,
+			generatedMtime,
+			isStale
+		});
+	}
+	if (hasStale) return {
+		name: "Codegen Freshness",
+		status: "warn",
+		message: `Schema modified after codegen: ${schemaResults.filter((s) => s.isStale).map((s) => s.name).join(", ")}`,
+		data: { schemas: schemaResults },
+		fix: "Run: soda-gql codegen"
+	};
+	return {
+		name: "Codegen Freshness",
+		status: "pass",
+		message: "Generated code is up to date",
+		data: { schemas: schemaResults }
+	};
+};
+
+//#endregion
+//#region packages/cli/src/commands/doctor/checks/config-validation.ts
+/**
+* Config validation check.
+* @module
+*/
+/**
+* Check that config file is valid and referenced files exist.
+*/
+const checkConfigValidation = () => {
+	const configPath = (0, __soda_gql_config.findConfigFile)();
+	if (!configPath) return {
+		name: "Config Validation",
+		status: "skip",
+		message: "No soda-gql.config.ts found",
+		data: {
+			configPath: null,
+			missingFiles: []
+		}
+	};
+	const configResult = (0, __soda_gql_config.loadConfig)(configPath);
+	if (configResult.isErr()) return {
+		name: "Config Validation",
+		status: "fail",
+		message: `Config error: ${configResult.error.message}`,
+		data: {
+			configPath,
+			missingFiles: []
+		},
+		fix: "Check your soda-gql.config.ts for syntax errors"
+	};
+	const config = configResult.value;
+	const missingFiles = [];
+	for (const [name, schemaConfig] of Object.entries(config.schemas)) {
+		if (!(0, node_fs.existsSync)(schemaConfig.schema)) missingFiles.push(`Schema '${name}': ${schemaConfig.schema}`);
+		if (!(0, node_fs.existsSync)(schemaConfig.inject.scalars)) missingFiles.push(`Scalars '${name}': ${schemaConfig.inject.scalars}`);
+		if (schemaConfig.inject.adapter && !(0, node_fs.existsSync)(schemaConfig.inject.adapter)) missingFiles.push(`Adapter '${name}': ${schemaConfig.inject.adapter}`);
+	}
+	if (missingFiles.length > 0) return {
+		name: "Config Validation",
+		status: "fail",
+		message: `${missingFiles.length} referenced file(s) not found`,
+		data: {
+			configPath,
+			missingFiles
+		},
+		fix: "Create the missing files or update paths in config"
+	};
+	return {
+		name: "Config Validation",
+		status: "pass",
+		message: "Config loaded successfully",
+		data: {
+			configPath,
+			missingFiles: []
+		}
+	};
+};
+
+//#endregion
+//#region packages/cli/src/commands/doctor/discovery.ts
+/**
+* Package discovery utilities for doctor command.
+* @module
+*/
+const SODA_GQL_SCOPE = "@soda-gql";
+/**
+* Find the nearest node_modules directory.
+*/
+const findNodeModules = (startDir = process.cwd()) => {
+	let currentDir = startDir;
+	while (currentDir !== (0, node_path.dirname)(currentDir)) {
+		const nodeModulesPath = (0, node_path.join)(currentDir, "node_modules");
+		if ((0, node_fs.existsSync)(nodeModulesPath) && (0, node_fs.statSync)(nodeModulesPath).isDirectory()) return nodeModulesPath;
+		currentDir = (0, node_path.dirname)(currentDir);
+	}
+	return null;
+};
+/**
+* Read package.json from a directory.
+*/
+const readPackageJson = (dir) => {
+	const packageJsonPath = (0, node_path.join)(dir, "package.json");
 	try {
-		const parsed = parseCodegenArgs(argv);
-		if (parsed.isErr()) {
-			process.stderr.write(`${formatCodegenError(parsed.error)}\n`);
-			return 1;
+		const content = (0, node_fs.readFileSync)(packageJsonPath, "utf-8");
+		const pkg = JSON.parse(content);
+		if (!pkg.name || !pkg.version) return (0, neverthrow.err)(`Invalid package.json at ${packageJsonPath}`);
+		return (0, neverthrow.ok)({
+			name: pkg.name,
+			version: pkg.version
+		});
+	} catch {
+		return (0, neverthrow.err)(`Failed to read package.json at ${packageJsonPath}`);
+	}
+};
+/**
+* Discover @soda-gql packages at a specific node_modules path.
+*/
+const discoverAtPath = (nodeModulesPath) => {
+	const scopePath = (0, node_path.join)(nodeModulesPath, SODA_GQL_SCOPE);
+	if (!(0, node_fs.existsSync)(scopePath)) return [];
+	const packages = [];
+	try {
+		const entries = (0, node_fs.readdirSync)(scopePath, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const packageDir = (0, node_path.join)(scopePath, entry.name);
+			const result = readPackageJson(packageDir);
+			if (result.isOk()) packages.push({
+				name: result.value.name,
+				version: result.value.version,
+				path: packageDir
+			});
+		}
+	} catch {}
+	return packages;
+};
+/**
+* Discover all @soda-gql packages including nested node_modules.
+* Uses breadth-first search to avoid deep recursion.
+*/
+const discoverAllSodaGqlPackages = (startDir = process.cwd()) => {
+	const rootNodeModules = findNodeModules(startDir);
+	if (!rootNodeModules) return (0, neverthrow.err)("No node_modules directory found");
+	const allPackages = [];
+	const visitedPaths = /* @__PURE__ */ new Set();
+	const queue = [rootNodeModules];
+	while (queue.length > 0) {
+		const nodeModulesPath = queue.shift();
+		if (!nodeModulesPath) continue;
+		let realPath;
+		try {
+			realPath = (0, node_path.resolve)(nodeModulesPath);
+		} catch {
+			continue;
+		}
+		if (visitedPaths.has(realPath)) continue;
+		visitedPaths.add(realPath);
+		const packages = discoverAtPath(nodeModulesPath);
+		allPackages.push(...packages);
+		try {
+			const entries = (0, node_fs.readdirSync)(nodeModulesPath, { withFileTypes: true });
+			for (const entry of entries) {
+				if (!entry.isDirectory()) continue;
+				if (entry.name.startsWith("@")) {
+					const scopeDir = (0, node_path.join)(nodeModulesPath, entry.name);
+					try {
+						const scopeEntries = (0, node_fs.readdirSync)(scopeDir, { withFileTypes: true });
+						for (const scopeEntry of scopeEntries) {
+							if (!scopeEntry.isDirectory()) continue;
+							const nestedNodeModules = (0, node_path.join)(scopeDir, scopeEntry.name, "node_modules");
+							if ((0, node_fs.existsSync)(nestedNodeModules)) queue.push(nestedNodeModules);
+						}
+					} catch {}
+				} else {
+					const nestedNodeModules = (0, node_path.join)(nodeModulesPath, entry.name, "node_modules");
+					if ((0, node_fs.existsSync)(nestedNodeModules)) queue.push(nestedNodeModules);
+				}
+			}
+		} catch {}
+	}
+	return (0, neverthrow.ok)(allPackages);
+};
+/**
+* Get the soda-gql CLI version.
+*/
+const getCliVersion = () => {
+	try {
+		const content = (0, node_fs.readFileSync)((0, node_path.join)(__dirname, "..", "..", "..", "package.json"), "utf-8");
+		return JSON.parse(content).version ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+};
+/**
+* Get TypeScript version from node_modules.
+*/
+const getTypescriptVersion = (startDir = process.cwd()) => {
+	const nodeModulesPath = findNodeModules(startDir);
+	if (!nodeModulesPath) return null;
+	const tsPackageJson = (0, node_path.join)(nodeModulesPath, "typescript", "package.json");
+	try {
+		const content = (0, node_fs.readFileSync)(tsPackageJson, "utf-8");
+		return JSON.parse(content).version ?? null;
+	} catch {
+		return null;
+	}
+};
+
+//#endregion
+//#region packages/cli/src/commands/doctor/checks/duplicate-packages.ts
+/**
+* Duplicate packages check.
+* @module
+*/
+/**
+* Check for duplicate @soda-gql packages installed at different paths.
+*/
+const checkDuplicatePackages = () => {
+	const packagesResult = discoverAllSodaGqlPackages();
+	if (packagesResult.isErr()) return {
+		name: "Duplicate Packages",
+		status: "skip",
+		message: packagesResult.error,
+		data: { duplicates: [] }
+	};
+	const packages = packagesResult.value;
+	const byName = /* @__PURE__ */ new Map();
+	for (const pkg of packages) {
+		const existing = byName.get(pkg.name) ?? [];
+		existing.push(pkg);
+		byName.set(pkg.name, existing);
+	}
+	const duplicates = [];
+	for (const [name, instances] of byName) if (instances.length > 1) duplicates.push({
+		name,
+		instances: instances.map((i) => ({
+			path: i.path,
+			version: i.version
+		}))
+	});
+	if (duplicates.length === 0) return {
+		name: "Duplicate Packages",
+		status: "pass",
+		message: "No duplicate packages detected",
+		data: { duplicates: [] }
+	};
+	return {
+		name: "Duplicate Packages",
+		status: "warn",
+		message: `Duplicate packages found: ${duplicates.map((d) => d.name).join(", ")}`,
+		data: { duplicates },
+		fix: "Run: rm -rf node_modules && bun install"
+	};
+};
+
+//#endregion
+//#region packages/cli/src/commands/doctor/checks/version-consistency.ts
+/**
+* Version consistency check.
+* @module
+*/
+/**
+* Check that all @soda-gql packages have consistent versions.
+*/
+const checkVersionConsistency = () => {
+	const packagesResult = discoverAllSodaGqlPackages();
+	if (packagesResult.isErr()) return {
+		name: "Version Consistency",
+		status: "skip",
+		message: packagesResult.error,
+		data: {
+			packages: [],
+			expectedVersion: null
+		}
+	};
+	const packages = packagesResult.value;
+	if (packages.length === 0) return {
+		name: "Version Consistency",
+		status: "skip",
+		message: "No @soda-gql packages found",
+		data: {
+			packages: [],
+			expectedVersion: null
+		}
+	};
+	const byName = /* @__PURE__ */ new Map();
+	for (const pkg of packages) {
+		const existing = byName.get(pkg.name) ?? [];
+		existing.push(pkg);
+		byName.set(pkg.name, existing);
+	}
+	const uniquePackages = Array.from(byName.values()).map((instances) => instances[0]).filter((pkg) => pkg !== void 0);
+	const versionCounts = /* @__PURE__ */ new Map();
+	for (const pkg of uniquePackages) versionCounts.set(pkg.version, (versionCounts.get(pkg.version) ?? 0) + 1);
+	let expectedVersion = uniquePackages[0]?.version ?? null;
+	let maxCount = 0;
+	for (const [version, count] of versionCounts) if (count > maxCount) {
+		maxCount = count;
+		expectedVersion = version;
+	}
+	const packageResults = uniquePackages.map((pkg) => ({
+		name: pkg.name,
+		version: pkg.version,
+		path: pkg.path,
+		isMismatch: pkg.version !== expectedVersion
+	}));
+	const mismatches = packageResults.filter((p) => p.isMismatch);
+	if (mismatches.length === 0) return {
+		name: "Version Consistency",
+		status: "pass",
+		message: `All ${uniquePackages.length} packages at version ${expectedVersion}`,
+		data: {
+			packages: packageResults,
+			expectedVersion
+		}
+	};
+	return {
+		name: "Version Consistency",
+		status: "fail",
+		message: `Version mismatch: ${mismatches.map((p) => p.name).join(", ")}`,
+		data: {
+			packages: packageResults,
+			expectedVersion
+		},
+		fix: `Run: bun update ${mismatches.map((p) => p.name).join(" ")}`
+	};
+};
+
+//#endregion
+//#region packages/cli/src/commands/doctor/output.ts
+const STATUS_SYMBOLS = {
+	pass: "✓",
+	warn: "!",
+	fail: "✗",
+	skip: "-"
+};
+/**
+* Type guard to check if data is an object (not null/primitive).
+*/
+const isObject = (data) => {
+	return typeof data === "object" && data !== null;
+};
+/**
+* Format a single check result for human output.
+*/
+const formatCheckResult = (result) => {
+	const lines = [];
+	const symbol = STATUS_SYMBOLS[result.status];
+	lines.push(`${symbol} ${result.message}`);
+	if (result.status === "fail" || result.status === "warn") {
+		const data = result.data;
+		if (isObject(data) && "packages" in data && "expectedVersion" in data) {
+			const versionData = data;
+			const mismatched = versionData.packages.filter((p) => p.isMismatch);
+			for (const pkg of mismatched) lines.push(`  ${pkg.name}: ${pkg.version}  <- mismatch`);
+			if (versionData.expectedVersion && mismatched.length > 0) lines.push(`  Expected: ${versionData.expectedVersion}`);
 		}
-		const command = parsed.value;
-		if (command.kind === "emitInjectTemplate") {
-			const outPath = (0, node_path.resolve)(command.outPath);
-			const result$1 = (0, __soda_gql_codegen.writeInjectTemplate)(outPath);
-			if (result$1.isErr()) {
-				process.stderr.write(`${formatCodegenError(result$1.error)}\n`);
-				return 1;
+		if (isObject(data) && "duplicates" in data) {
+			const dupData = data;
+			for (const dup of dupData.duplicates) {
+				lines.push(`  ${dup.name}:`);
+				for (const instance of dup.instances) lines.push(`    ${instance.version} at ${instance.path}`);
 			}
-			process.stdout.write(`${formatTemplateSuccess(outPath)}\n`);
-			return 0;
 		}
-		const resolvedSchemas = {};
-		for (const [name, schemaConfig] of Object.entries(command.schemas)) resolvedSchemas[name] = {
-			schema: (0, node_path.resolve)(schemaConfig.schema),
-			inject: {
-				scalars: (0, node_path.resolve)(schemaConfig.inject.scalars),
-				...schemaConfig.inject.adapter ? { adapter: (0, node_path.resolve)(schemaConfig.inject.adapter) } : {}
-			},
-			defaultInputDepth: schemaConfig.defaultInputDepth,
-			inputDepthOverrides: schemaConfig.inputDepthOverrides
-		};
-		const result = await (0, __soda_gql_codegen.runCodegen)({
-			schemas: resolvedSchemas,
-			outPath: (0, node_path.resolve)(command.outPath),
-			format: "human",
-			importExtension: command.importExtension
-		});
-		if (result.isErr()) {
-			process.stderr.write(`${formatCodegenError(result.error)}\n`);
-			return 1;
+		if (result.fix) {
+			lines.push("");
+			lines.push(`  Fix: ${result.fix}`);
 		}
-		process.stdout.write(`${formatSuccess$1(result.value)}\n`);
-		return 0;
-	} catch (error) {
-		const unexpectedError = {
-			code: "EMIT_FAILED",
-			message: error instanceof Error ? error.message : String(error),
-			outPath: ""
-		};
-		process.stderr.write(`${formatCodegenError(unexpectedError)}\n`);
-		return 1;
 	}
+	return lines;
+};
+/**
+* Format the complete doctor result for human output.
+*/
+const formatDoctorResult = (result) => {
+	const lines = [];
+	lines.push(`soda-gql doctor v${result.version}`);
+	lines.push("");
+	for (const check of result.checks) {
+		lines.push(...formatCheckResult(check));
+		lines.push("");
+	}
+	const passed = result.checks.filter((c) => c.status === "pass").length;
+	if (result.issueCount === 0 && result.warningCount === 0) lines.push(`Summary: All ${passed} checks passed`);
+	else {
+		const parts = [];
+		if (result.issueCount > 0) parts.push(`${result.issueCount} issue${result.issueCount > 1 ? "s" : ""}`);
+		if (result.warningCount > 0) parts.push(`${result.warningCount} warning${result.warningCount > 1 ? "s" : ""}`);
+		lines.push(`Summary: ${parts.join(", ")} found`);
+	}
+	return lines.join("\n");
+};
+
+//#endregion
+//#region packages/cli/src/commands/doctor/index.ts
+/**
+* Doctor command entry point.
+* @module
+*/
+const DOCTOR_HELP = `Usage: soda-gql doctor
+
+Run diagnostic checks on your soda-gql installation.
+
+Checks performed:
+  - Version consistency across @soda-gql packages
+  - Duplicate package detection
+  - Config file validation
+  - Codegen freshness (schema vs generated code)
+
+Options:
+  --help, -h    Show this help message
+`;
+const doctorCommand = (argv) => {
+	if (argv.includes("--help") || argv.includes("-h")) return (0, neverthrow.ok)({ message: DOCTOR_HELP });
+	const version = getCliVersion();
+	const tsVersion = getTypescriptVersion();
+	const checks = [];
+	if (tsVersion) checks.push({
+		name: "TypeScript Version",
+		status: "pass",
+		message: `TypeScript version: ${tsVersion}`
+	});
+	checks.push(checkVersionConsistency());
+	checks.push(checkDuplicatePackages());
+	checks.push(checkConfigValidation());
+	checks.push(checkCodegenFreshness());
+	const result = {
+		version,
+		checks,
+		issueCount: checks.filter((c) => c.status === "fail").length,
+		warningCount: checks.filter((c) => c.status === "warn").length
+	};
+	return (0, neverthrow.ok)({
+		message: formatDoctorResult(result),
+		data: result
+	});
 };
 
 //#endregion
@@ -396,22 +929,19 @@ const loadFormatter = async () => {
 		return null;
 	}
 };
-const formatFormatError = (error) => {
-	return `${error.code}: ${error.message}`;
-};
-const formatResult = (result) => {
-	if (result.mode === "check") {
-		if (result.unformatted.length > 0) {
-			const files = result.unformatted.map((f) => `  ${f}`).join("\n");
-			return `${result.unformatted.length} file(s) need formatting:\n${files}`;
+const formatResultMessage = (data) => {
+	if (data.mode === "check") {
+		if (data.unformatted.length > 0) {
+			const files = data.unformatted.map((f) => `  ${f}`).join("\n");
+			return `${data.unformatted.length} file(s) need formatting:\n${files}`;
 		}
-		return `All ${result.total} file(s) are properly formatted`;
+		return `All ${data.total} file(s) are properly formatted`;
 	}
 	const parts = [];
-	if (result.modified > 0) parts.push(`${result.modified} formatted`);
-	if (result.unchanged > 0) parts.push(`${result.unchanged} unchanged`);
-	if (result.errors > 0) parts.push(`${result.errors} errors`);
-	return `${result.total} file(s) checked: ${parts.join(", ")}`;
+	if (data.modified > 0) parts.push(`${data.modified} formatted`);
+	if (data.unchanged > 0) parts.push(`${data.unchanged} unchanged`);
+	if (data.errors > 0) parts.push(`${data.errors} errors`);
+	return `${data.total} file(s) checked: ${parts.join(", ")}`;
 };
 const isGlobPattern = (pattern) => {
 	return /[*?[\]{}]/.test(pattern);
@@ -449,19 +979,9 @@ Examples:
   soda-gql format --check             # Check mode with config
 `;
 const formatCommand = async (argv) => {
-	if (argv.includes("--help") || argv.includes("-h")) {
-		process.stdout.write(FORMAT_HELP);
-		return 0;
-	}
+	if (argv.includes("--help") || argv.includes("-h")) return (0, neverthrow.ok)({ message: FORMAT_HELP });
 	const parsed = parseArgs([...argv], FormatArgsSchema);
-	if (!parsed.isOk()) {
-		const error = {
-			code: "PARSE_ERROR",
-			message: parsed.error
-		};
-		process.stderr.write(`${formatFormatError(error)}\n`);
-		return 1;
-	}
+	if (!parsed.isOk()) return (0, neverthrow.err)(cliErrors.argsInvalid("format", parsed.error));
 	const args = parsed.value;
 	const isCheckMode = args.check === true;
 	const explicitPatterns = args._ ?? [];
@@ -470,36 +990,27 @@ const formatCommand = async (argv) => {
 	if (explicitPatterns.length > 0) targetPatterns = explicitPatterns;
 	else {
 		const configResult = (0, __soda_gql_config.loadConfig)(args.config);
-		if (configResult.isErr()) {
-			process.stderr.write(`${formatFormatError({
-				code: "NO_PATTERNS",
-				message: "No patterns provided and config not found. Usage: soda-gql format [patterns...] [--check]"
-			})}\n`);
-			return 1;
-		}
+		if (configResult.isErr()) return (0, neverthrow.err)(cliErrors.noPatterns());
 		targetPatterns = configResult.value.include;
 		excludePatterns = configResult.value.exclude;
 	}
 	const formatter = await loadFormatter();
-	if (!formatter) {
-		process.stderr.write(`${formatFormatError({
-			code: "FORMATTER_NOT_INSTALLED",
-			message: "@soda-gql/formatter is not installed. Run: npm install @soda-gql/formatter"
-		})}\n`);
-		return 1;
-	}
+	if (!formatter) return (0, neverthrow.err)(cliErrors.formatterNotInstalled());
 	const files = await expandGlobPatterns(targetPatterns, excludePatterns);
 	if (files.length === 0) {
-		const result$1 = {
+		const data$1 = {
 			mode: isCheckMode ? "check" : "format",
 			total: 0,
 			modified: 0,
 			unchanged: 0,
 			errors: 0,
-			unformatted: []
+			unformatted: [],
+			hasFormattingIssues: false
 		};
-		process.stdout.write(`${formatResult(result$1)}\n`);
-		return 0;
+		return (0, neverthrow.ok)({
+			message: formatResultMessage(data$1),
+			data: data$1
+		});
 	}
 	let modified = 0;
 	let unchanged = 0;
@@ -508,44 +1019,46 @@ const formatCommand = async (argv) => {
 	for (const filePath of files) {
 		const sourceCode = await (0, node_fs_promises.readFile)(filePath, "utf-8");
 		if (isCheckMode) {
-			const result$1 = formatter.needsFormat({
+			const result = formatter.needsFormat({
 				sourceCode,
 				filePath
 			});
-			if (result$1.isErr()) {
+			if (result.isErr()) {
 				errors++;
 				continue;
 			}
-			if (result$1.value) {
+			if (result.value) {
 				unformatted.push(filePath);
 				modified++;
 			} else unchanged++;
 		} else {
-			const result$1 = formatter.format({
+			const result = formatter.format({
 				sourceCode,
 				filePath
 			});
-			if (result$1.isErr()) {
+			if (result.isErr()) {
 				errors++;
 				continue;
 			}
-			if (result$1.value.modified) {
-				await (0, node_fs_promises.writeFile)(filePath, result$1.value.sourceCode, "utf-8");
+			if (result.value.modified) {
+				await (0, node_fs_promises.writeFile)(filePath, result.value.sourceCode, "utf-8");
 				modified++;
 			} else unchanged++;
 		}
 	}
-	const result = {
+	const data = {
 		mode: isCheckMode ? "check" : "format",
 		total: files.length,
 		modified,
 		unchanged,
 		errors,
-		unformatted
+		unformatted,
+		hasFormattingIssues: isCheckMode && unformatted.length > 0 || errors > 0
 	};
-	process.stdout.write(`${formatResult(result)}\n`);
-	if (isCheckMode && unformatted.length > 0) return 1;
-	return errors > 0 ? 1 : 0;
+	return (0, neverthrow.ok)({
+		message: formatResultMessage(data),
+		data
+	});
 };
 
 //#endregion
@@ -619,11 +1132,7 @@ Generated files:
 `;
 const checkFilesExist = (files, force) => {
 	if (force) return (0, neverthrow.ok)(void 0);
-	for (const file of files) if ((0, node_fs.existsSync)(file.path)) return (0, neverthrow.err)({
-		code: "FILE_EXISTS",
-		message: `File already exists: ${file.path}. Use --force to overwrite.`,
-		filePath: file.path
-	});
+	for (const file of files) if ((0, node_fs.existsSync)(file.path)) return (0, neverthrow.err)(cliErrors.fileExists(file.path));
 	return (0, neverthrow.ok)(void 0);
 };
 const writeFiles = (files) => {
@@ -634,11 +1143,7 @@ const writeFiles = (files) => {
 		createdPaths.push(file.path);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
-		return (0, neverthrow.err)({
-			code: "WRITE_FAILED",
-			message: `Failed to write ${file.description}: ${message}`,
-			filePath: file.path
-		});
+		return (0, neverthrow.err)(cliErrors.writeFailed(file.path, `Failed to write ${file.description}: ${message}`, error));
 	}
 	return (0, neverthrow.ok)({ filesCreated: createdPaths });
 };
@@ -655,23 +1160,10 @@ const formatSuccess = (result) => {
 	lines.push("  3. Import gql from ./graphql-system");
 	return lines.join("\n");
 };
-const formatInitError = (error) => {
-	return `${error.code}: ${error.message}`;
-};
 const initCommand = async (argv) => {
-	if (argv.includes("--help") || argv.includes("-h")) {
-		process.stdout.write(INIT_HELP);
-		return 0;
-	}
+	if (argv.includes("--help") || argv.includes("-h")) return (0, neverthrow.ok)({ message: INIT_HELP });
 	const parsed = parseArgs([...argv], InitArgsSchema);
-	if (!parsed.isOk()) {
-		const error = {
-			code: "PARSE_ERROR",
-			message: parsed.error
-		};
-		process.stderr.write(`${formatInitError(error)}\n`);
-		return 1;
-	}
+	if (!parsed.isOk()) return (0, neverthrow.err)(cliErrors.argsInvalid("init", parsed.error));
 	const force = parsed.value.force === true;
 	const cwd = process.cwd();
 	const files = [
@@ -697,54 +1189,192 @@ const initCommand = async (argv) => {
 		}
 	];
 	const existsCheck = checkFilesExist(files, force);
-	if (existsCheck.isErr()) {
-		process.stderr.write(`${formatInitError(existsCheck.error)}\n`);
-		return 1;
-	}
+	if (existsCheck.isErr()) return (0, neverthrow.err)(existsCheck.error);
 	const writeResult = writeFiles(files);
-	if (writeResult.isErr()) {
-		process.stderr.write(`${formatInitError(writeResult.error)}\n`);
-		return 1;
-	}
-	process.stdout.write(`${formatSuccess(writeResult.value)}\n`);
-	return 0;
+	if (writeResult.isErr()) return (0, neverthrow.err)(writeResult.error);
+	return (0, neverthrow.ok)({
+		message: formatSuccess(writeResult.value),
+		data: writeResult.value
+	});
 };
 
 //#endregion
 //#region packages/cli/src/utils/format.ts
-const formatError = (error, format = "human") => {
-	if (format === "json") return JSON.stringify({ error }, null, 2);
-	return error instanceof Error ? error.message : String(error);
+/**
+* CLI-specific error hints to help users fix issues.
+*/
+const cliErrorHints = {
+	CLI_ARGS_INVALID: "Check command usage with --help",
+	CLI_UNKNOWN_COMMAND: "Run 'soda-gql --help' for available commands",
+	CLI_UNKNOWN_SUBCOMMAND: "Run the parent command with --help for available subcommands",
+	CLI_FILE_EXISTS: "Use --force flag to overwrite existing files",
+	CLI_FILE_NOT_FOUND: "Verify the file path exists",
+	CLI_WRITE_FAILED: "Check write permissions and disk space",
+	CLI_READ_FAILED: "Check file permissions and verify the file is not locked",
+	CLI_NO_PATTERNS: "Provide file patterns or create soda-gql.config.ts",
+	CLI_FORMATTER_NOT_INSTALLED: "Install with: bun add @soda-gql/formatter",
+	CLI_PARSE_ERROR: "Check the file for syntax errors",
+	CLI_FORMAT_ERROR: "Verify the file contains valid soda-gql code",
+	CLI_UNEXPECTED: "This is an unexpected error. Please report at https://github.com/soda-gql/soda-gql/issues"
+};
+/**
+* Codegen-specific error hints.
+*/
+const codegenErrorHints = {
+	SCHEMA_NOT_FOUND: "Verify the schema path in soda-gql.config.ts",
+	SCHEMA_INVALID: "Check your GraphQL schema for syntax errors",
+	INJECT_MODULE_NOT_FOUND: "Run: soda-gql codegen --emit-inject-template <path>",
+	INJECT_MODULE_REQUIRED: "Add inject configuration to your schema in soda-gql.config.ts",
+	INJECT_TEMPLATE_EXISTS: "Delete the existing file to regenerate, or use a different path",
+	EMIT_FAILED: "Check write permissions and that the output directory exists",
+	INJECT_TEMPLATE_FAILED: "Check write permissions for the output path"
+};
+/**
+* Config-specific error hints.
+*/
+const configErrorHints = {
+	CONFIG_NOT_FOUND: "Create a soda-gql.config.ts file in your project root",
+	CONFIG_LOAD_FAILED: "Check your configuration file for syntax errors",
+	CONFIG_VALIDATION_FAILED: "Verify your configuration matches the expected schema",
+	CONFIG_INVALID_PATH: "Verify the path in your configuration exists"
+};
+/**
+* Artifact-specific error hints.
+*/
+const artifactErrorHints = {
+	ARTIFACT_NOT_FOUND: "Verify the artifact file path exists",
+	ARTIFACT_PARSE_ERROR: "Check that the artifact file is valid JSON",
+	ARTIFACT_VALIDATION_ERROR: "Verify the artifact was built with a compatible version of soda-gql"
+};
+/**
+* Get hint for any error type.
+*/
+const getErrorHint = (error) => {
+	if (error.category === "cli") return cliErrorHints[error.code];
+	if (error.category === "codegen") return codegenErrorHints[error.error.code];
+	if (error.category === "config") return configErrorHints[error.error.code];
+	if (error.category === "artifact") return artifactErrorHints[error.error.code];
+};
+/**
+* Format CliError to human-readable string with hints.
+*/
+const formatCliErrorHuman = (error) => {
+	if (error.category === "builder") return (0, __soda_gql_builder.formatBuilderErrorForCLI)(error.error);
+	const lines = [];
+	if (error.category === "codegen") {
+		const codegenError = error.error;
+		lines.push(`Error [${codegenError.code}]: ${codegenError.message}`);
+		if ("schemaPath" in codegenError) lines.push(`  Schema: ${codegenError.schemaPath}`);
+		if ("outPath" in codegenError && codegenError.outPath) lines.push(`  Output: ${codegenError.outPath}`);
+		if ("injectPath" in codegenError) lines.push(`  Inject: ${codegenError.injectPath}`);
+	} else if (error.category === "config") {
+		const configError = error.error;
+		lines.push(`Error [${configError.code}]: ${configError.message}`);
+		if (configError.filePath) lines.push(`  Config: ${configError.filePath}`);
+	} else if (error.category === "artifact") {
+		const artifactError = error.error;
+		lines.push(`Error [${artifactError.code}]: ${artifactError.message}`);
+		if (artifactError.filePath) lines.push(`  Artifact: ${artifactError.filePath}`);
+	} else {
+		lines.push(`Error [${error.code}]: ${error.message}`);
+		if ("filePath" in error && error.filePath) lines.push(`  File: ${error.filePath}`);
+		if ("command" in error && error.code !== "CLI_UNKNOWN_COMMAND") lines.push(`  Command: ${error.command}`);
+		if ("parent" in error) lines.push(`  Parent: ${error.parent}`);
+	}
+	const hint = getErrorHint(error);
+	if (hint) {
+		lines.push("");
+		lines.push(`  Hint: ${hint}`);
+	}
+	return lines.join("\n");
+};
+/**
+* Format CliError to JSON string.
+*/
+const formatCliErrorJson = (error) => {
+	if (error.category === "cli") {
+		const { category: _category, ...rest } = error;
+		return JSON.stringify({ error: rest }, null, 2);
+	}
+	return JSON.stringify({ error: error.error }, null, 2);
+};
+/**
+* Format CliError with output format preference.
+*/
+const formatCliError = (error, format = "human") => {
+	return format === "json" ? formatCliErrorJson(error) : formatCliErrorHuman(error);
 };
 
 //#endregion
 //#region packages/cli/src/index.ts
+const MAIN_HELP = `Usage: soda-gql <command> [options]
+
+Commands:
+  init       Initialize a new soda-gql project
+  codegen    Generate graphql-system runtime module
+  format     Format soda-gql field selections
+  artifact   Manage soda-gql artifacts
+  doctor     Run diagnostic checks
+
+Run 'soda-gql <command> --help' for more information on a specific command.
+`;
+/**
+* Parse output format from argv.
+* Returns "json" if --format=json or --json flag is present, otherwise "human".
+*/
+const getOutputFormat = (argv) => {
+	for (const arg of argv) {
+		if (arg === "--format=json" || arg === "--json") return "json";
+		if (arg === "--format=human") return "human";
+	}
+	return "human";
+};
 const dispatch = async (argv) => {
 	const [command, ...rest] = argv;
-	if (!command || command === "--help" || command === "-h") {
-		process.stdout.write(`Usage: soda-gql <command> [options]\n`);
-		process.stdout.write(`\nCommands:\n`);
-		process.stdout.write(`  init       Initialize a new soda-gql project\n`);
-		process.stdout.write(`  codegen    Generate graphql-system runtime module\n`);
-		process.stdout.write(`  format     Format soda-gql field selections\n`);
-		process.stdout.write(`  artifact   Manage soda-gql artifacts\n`);
-		return 0;
-	}
+	if (!command || command === "--help" || command === "-h") return (0, neverthrow.ok)({ message: MAIN_HELP });
 	if (command === "init") return initCommand(rest);
 	if (command === "codegen") return codegenCommand(rest);
-	if (command === "format") return formatCommand(rest);
+	if (command === "format") {
+		const result = await formatCommand(rest);
+		if (result.isOk()) {
+			const exitCode = result.value.data?.hasFormattingIssues ? 1 : 0;
+			return (0, neverthrow.ok)({
+				...result.value,
+				exitCode
+			});
+		}
+		return (0, neverthrow.err)(result.error);
+	}
 	if (command === "artifact") return artifactCommand(rest);
-	process.stderr.write(`Unknown command: ${command}\n`);
-	return 1;
-};
-dispatch(process.argv.slice(2)).then((exitCode) => {
-	process.exitCode = exitCode;
-}).catch((error) => {
-	const unexpectedError = {
-		code: "UNEXPECTED_ERROR",
-		message: error instanceof Error ? error.message : String(error)
-	};
-	process.stderr.write(`${formatError(unexpectedError, "json")}\n`);
+	if (command === "doctor") {
+		const result = doctorCommand(rest);
+		if (result.isOk()) {
+			const exitCode = result.value.data?.issueCount ? 1 : 0;
+			return (0, neverthrow.ok)({
+				...result.value,
+				exitCode
+			});
+		}
+		return result;
+	}
+	return (0, neverthrow.err)(cliErrors.unknownCommand(command));
+};
+const main = async () => {
+	const argv = process.argv.slice(2);
+	const format = getOutputFormat(argv);
+	const result = await dispatch(argv);
+	if (result.isOk()) {
+		process.stdout.write(`${result.value.message}\n`);
+		process.exitCode = result.value.exitCode ?? 0;
+	} else {
+		process.stderr.write(`${formatCliError(result.error, format)}\n`);
+		process.exitCode = 1;
+	}
+};
+main().catch((error) => {
+	const unexpectedError = cliErrors.unexpected(error instanceof Error ? error.message : String(error), error);
+	const format = getOutputFormat(process.argv.slice(2));
+	process.stderr.write(`${formatCliError(unexpectedError, format)}\n`);
 	process.exitCode = 1;
 });