@kidd-cli/cli 0.1.0

package/dist/commands/doctor.mjs

@@ -0,0 +1,680 @@
+import { command } from "@kidd-cli/core";
+import { dirname, join, relative } from "node:path";
+import { readManifest } from "@kidd-cli/utils/manifest";
+import { loadConfig } from "@kidd-cli/config/loader";
+import { z } from "zod";
+import pc from "picocolors";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { attemptAsync, err, ok } from "@kidd-cli/utils/fp";
+import { jsonParse, jsonStringify } from "@kidd-cli/utils/json";
+
+//#region src/lib/checks.ts
+/**
+* Default entry point for the CLI source.
+*/
+const DEFAULT_ENTRY = "./src/index.ts";
+/**
+* Default directory for CLI commands.
+*/
+const DEFAULT_COMMANDS = "./commands";
+/**
+* Create a CheckContext from the gathered project data.
+*
+* @param params - The context parameters.
+* @returns A frozen CheckContext.
+*/
+function createCheckContext(params) {
+	return {
+		configError: params.configError,
+		configResult: params.configResult,
+		cwd: params.cwd,
+		manifest: params.manifest,
+		rawPackageJson: params.rawPackageJson
+	};
+}
+/**
+* Create a CheckResult with the given status.
+*
+* @private
+* @param params - The check result parameters.
+* @returns A CheckResult.
+*/
+function checkResult(params) {
+	return {
+		hint: params.hint ?? null,
+		message: params.message,
+		name: params.name,
+		status: params.status
+	};
+}
+/**
+* Create a FixResult.
+*
+* @private
+* @param params - The fix result parameters.
+* @returns A FixResult.
+*/
+function fixResult(params) {
+	return {
+		fixed: params.fixed,
+		message: params.message,
+		name: params.name
+	};
+}
+/**
+* Check whether a kidd config file exists.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass or fail.
+*/
+async function checkKiddConfig(context) {
+	if (context.configResult && context.configResult.configFile) return checkResult({
+		message: `Config file found at ./${relative(context.cwd, context.configResult.configFile)}`,
+		name: "kidd.config",
+		status: "pass"
+	});
+	return checkResult({
+		hint: "Run \"kidd init\" to scaffold a config file",
+		message: "No config file found",
+		name: "kidd.config",
+		status: "fail"
+	});
+}
+/**
+* Check whether the loaded config schema is valid.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass, warn, or fail.
+*/
+async function checkConfigSchema(context) {
+	if (context.configResult) return checkResult({
+		message: "Config is valid",
+		name: "config schema",
+		status: "pass"
+	});
+	if (context.configError) return checkResult({
+		hint: "Check your kidd.config.ts for syntax or schema errors",
+		message: `Config validation failed: ${context.configError.message}`,
+		name: "config schema",
+		status: "fail"
+	});
+	return checkResult({
+		message: "No config file, using defaults",
+		name: "config schema",
+		status: "warn"
+	});
+}
+/**
+* Check whether package.json exists in the project.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass or fail.
+*/
+async function checkPackageJson(context) {
+	if (context.rawPackageJson) return checkResult({
+		message: "Found",
+		name: "package.json",
+		status: "pass"
+	});
+	return checkResult({
+		hint: "Run \"pnpm init\" to create a package.json",
+		message: "Not found",
+		name: "package.json",
+		status: "fail"
+	});
+}
+/**
+* Check whether the package.json has a version field.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass or warn.
+*/
+async function checkPackageVersion(context) {
+	if (context.manifest && context.manifest.version) return checkResult({
+		message: context.manifest.version,
+		name: "package version",
+		status: "pass"
+	});
+	return checkResult({
+		hint: "Add a \"version\" field to package.json",
+		message: "No version field",
+		name: "package version",
+		status: "warn"
+	});
+}
+/**
+* Check whether the package.json declares ESM via `"type": "module"`.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass or fail.
+*/
+async function checkModuleType(context) {
+	if (context.rawPackageJson && context.rawPackageJson.type === "module") return checkResult({
+		message: "ESM (\"type\": \"module\")",
+		name: "module type",
+		status: "pass"
+	});
+	return checkResult({
+		hint: "Add \"type\": \"module\" to package.json (fixable with --fix)",
+		message: "Missing or wrong \"type\" field (expected \"module\")",
+		name: "module type",
+		status: "fail"
+	});
+}
+/**
+* Check whether kidd is listed as a dependency or devDependency.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass or fail.
+*/
+async function checkKiddDependency(context) {
+	if (!context.rawPackageJson) return checkResult({
+		hint: "Run \"pnpm init\" to create a package.json first",
+		message: "No package.json found",
+		name: "@kidd-cli/core dependency",
+		status: "fail"
+	});
+	const deps = context.rawPackageJson.dependencies ?? {};
+	const devDeps = context.rawPackageJson.devDependencies ?? {};
+	if ("@kidd-cli/core" in deps) return checkResult({
+		message: "Found in dependencies",
+		name: "@kidd-cli/core dependency",
+		status: "pass"
+	});
+	if ("@kidd-cli/core" in devDeps) return checkResult({
+		message: "Found in devDependencies",
+		name: "@kidd-cli/core dependency",
+		status: "pass"
+	});
+	return checkResult({
+		hint: "Run \"pnpm add kidd\" or use --fix to add it (fixable with --fix)",
+		message: "Not found in dependencies or devDependencies",
+		name: "@kidd-cli/core dependency",
+		status: "fail"
+	});
+}
+/**
+* Check whether the CLI entry point file exists on disk.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass, warn, or fail.
+*/
+async function checkEntryPoint(context) {
+	const config = extractConfig(context.configResult);
+	const entryPath = resolveEntryPath(config);
+	if (await fileExists(join(context.cwd, entryPath))) return checkResult({
+		message: `Found: ${entryPath}`,
+		name: "entry point",
+		status: "pass"
+	});
+	if (!config) return checkResult({
+		hint: "Create the entry file or update \"entry\" in kidd.config.ts (fixable with --fix)",
+		message: `No config, default not found: ${entryPath}`,
+		name: "entry point",
+		status: "warn"
+	});
+	return checkResult({
+		hint: "Create the entry file or update \"entry\" in kidd.config.ts (fixable with --fix)",
+		message: `Not found: ${entryPath}`,
+		name: "entry point",
+		status: "fail"
+	});
+}
+/**
+* Check whether the commands directory exists on disk.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass, warn, or fail.
+*/
+async function checkCommandsDirectory(context) {
+	const config = extractConfig(context.configResult);
+	const commandsPath = resolveCommandsPath(config);
+	if (await fileExists(join(context.cwd, commandsPath))) return checkResult({
+		message: `Found: ${commandsPath}`,
+		name: "commands directory",
+		status: "pass"
+	});
+	if (!config) return checkResult({
+		hint: "Create the directory or update \"commands\" in kidd.config.ts (fixable with --fix)",
+		message: `No config, default not found: ${commandsPath}`,
+		name: "commands directory",
+		status: "warn"
+	});
+	return checkResult({
+		hint: "Create the directory or update \"commands\" in kidd.config.ts (fixable with --fix)",
+		message: `Not found: ${commandsPath}`,
+		name: "commands directory",
+		status: "fail"
+	});
+}
+/**
+* Check whether a tsconfig.json exists in the project root.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A CheckResult indicating pass or warn.
+*/
+async function checkTsconfig(context) {
+	if (await fileExists(join(context.cwd, "tsconfig.json"))) return checkResult({
+		message: "Found",
+		name: "tsconfig.json",
+		status: "pass"
+	});
+	return checkResult({
+		hint: "Run \"tsc --init\" to create a tsconfig.json",
+		message: "Not found (recommended)",
+		name: "tsconfig.json",
+		status: "warn"
+	});
+}
+/**
+* Fix the module type by adding "type": "module" to package.json.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A FixResult indicating whether the fix was applied.
+*/
+async function fixModuleType(context) {
+	const [updateError] = await updatePackageJson(context.cwd, (pkg) => ({
+		...pkg,
+		type: "module"
+	}));
+	if (updateError) return fixResult({
+		fixed: false,
+		message: updateError.message,
+		name: "module type"
+	});
+	return fixResult({
+		fixed: true,
+		message: "Added \"type\": \"module\" to package.json",
+		name: "module type"
+	});
+}
+/**
+* Fix the kidd dependency by adding it to package.json dependencies.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A FixResult indicating whether the fix was applied.
+*/
+async function fixKiddDependency(context) {
+	const [updateError] = await updatePackageJson(context.cwd, (pkg) => {
+		const deps = pkg.dependencies;
+		return {
+			...pkg,
+			dependencies: {
+				...deps,
+				"@kidd-cli/core": "latest"
+			}
+		};
+	});
+	if (updateError) return fixResult({
+		fixed: false,
+		message: updateError.message,
+		name: "@kidd-cli/core dependency"
+	});
+	return fixResult({
+		fixed: true,
+		message: "Added \"@kidd-cli/core\": \"latest\" to dependencies",
+		name: "@kidd-cli/core dependency"
+	});
+}
+/**
+* Fix the entry point by creating the entry file with a minimal scaffold.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A FixResult indicating whether the fix was applied.
+*/
+async function fixEntryPoint(context) {
+	const entryPath = resolveEntryPath(extractConfig(context.configResult));
+	const absolutePath = join(context.cwd, entryPath);
+	const [mkdirError] = await attemptAsync(() => mkdir(dirname(absolutePath), { recursive: true }));
+	if (mkdirError) return fixResult({
+		fixed: false,
+		message: `Failed to create directory: ${mkdirError.message}`,
+		name: "entry point"
+	});
+	const content = `import { create } from '@kidd-cli/core'\n`;
+	const [writeError] = await attemptAsync(() => writeFile(absolutePath, content, "utf8"));
+	if (writeError) return fixResult({
+		fixed: false,
+		message: `Failed to create file: ${writeError.message}`,
+		name: "entry point"
+	});
+	return fixResult({
+		fixed: true,
+		message: `Created ${entryPath}`,
+		name: "entry point"
+	});
+}
+/**
+* Fix the commands directory by creating it.
+*
+* @private
+* @param context - The diagnostic check context.
+* @returns A FixResult indicating whether the fix was applied.
+*/
+async function fixCommandsDirectory(context) {
+	const commandsPath = resolveCommandsPath(extractConfig(context.configResult));
+	const absolutePath = join(context.cwd, commandsPath);
+	const [mkdirError] = await attemptAsync(() => mkdir(absolutePath, { recursive: true }));
+	if (mkdirError) return fixResult({
+		fixed: false,
+		message: `Failed to create directory: ${mkdirError.message}`,
+		name: "commands directory"
+	});
+	return fixResult({
+		fixed: true,
+		message: `Created ${commandsPath}`,
+		name: "commands directory"
+	});
+}
+/**
+* All diagnostic checks to run in order.
+*/
+const CHECKS = [
+	{
+		name: "kidd.config",
+		run: checkKiddConfig
+	},
+	{
+		name: "config schema",
+		run: checkConfigSchema
+	},
+	{
+		name: "package.json",
+		run: checkPackageJson
+	},
+	{
+		name: "package version",
+		run: checkPackageVersion
+	},
+	{
+		fix: fixModuleType,
+		name: "module type",
+		run: checkModuleType
+	},
+	{
+		fix: fixKiddDependency,
+		name: "@kidd-cli/core dependency",
+		run: checkKiddDependency
+	},
+	{
+		fix: fixEntryPoint,
+		name: "entry point",
+		run: checkEntryPoint
+	},
+	{
+		fix: fixCommandsDirectory,
+		name: "commands directory",
+		run: checkCommandsDirectory
+	},
+	{
+		name: "tsconfig.json",
+		run: checkTsconfig
+	}
+];
+/**
+* Read and parse the raw package.json from a directory.
+*
+* Only extracts the fields needed by diagnostic checks that Manifest does not expose.
+*
+* @param cwd - The directory to read from.
+* @returns A Result tuple with the raw package.json data or an error message.
+*/
+async function readRawPackageJson(cwd) {
+	const filePath = join(cwd, "package.json");
+	const [readError, content] = await attemptAsync(() => readFile(filePath, "utf8"));
+	if (readError) return err(`Failed to read package.json: ${readError.message}`);
+	const [parseError, data] = jsonParse(content);
+	if (parseError) return [parseError, null];
+	return ok(data);
+}
+/**
+* Check whether a path exists on disk.
+*
+* @private
+* @param filePath - The path to check.
+* @returns True when the path is accessible, false otherwise.
+*/
+async function fileExists(filePath) {
+	const [accessError] = await attemptAsync(() => access(filePath));
+	return accessError === null;
+}
+/**
+* Extract a KiddConfig from a load result, returning null when absent.
+*
+* @private
+* @param result - The config load result, or null.
+* @returns The config object or null.
+*/
+function extractConfig(result) {
+	if (result) return result.config;
+	return null;
+}
+/**
+* Resolve the entry path from config, falling back to the default.
+*
+* @private
+* @param config - The loaded config or null.
+* @returns The entry path string.
+*/
+function resolveEntryPath(config) {
+	if (config && config.entry) return config.entry;
+	return DEFAULT_ENTRY;
+}
+/**
+* Resolve the commands directory path from config, falling back to the default.
+*
+* @private
+* @param config - The loaded config or null.
+* @returns The commands directory path string.
+*/
+function resolveCommandsPath(config) {
+	if (config && config.commands) return config.commands;
+	return DEFAULT_COMMANDS;
+}
+/**
+* Read, transform, and write back a package.json file.
+*
+* @private
+* @param cwd - The directory containing the package.json.
+* @param transform - A pure function that returns the updated package data.
+* @returns A Result tuple indicating success or failure.
+*/
+async function updatePackageJson(cwd, transform) {
+	const filePath = join(cwd, "package.json");
+	const [readError, content] = await attemptAsync(() => readFile(filePath, "utf8"));
+	if (readError) return err(`Failed to read package.json: ${readError.message}`);
+	const [parseError, data] = jsonParse(content);
+	if (parseError) return [parseError, null];
+	const [stringifyError, json] = jsonStringify(transform(data), { pretty: true });
+	if (stringifyError) return [stringifyError, null];
+	const [writeError] = await attemptAsync(() => writeFile(filePath, `${json}\n`, "utf8"));
+	if (writeError) return err(`Failed to write package.json: ${writeError.message}`);
+	return ok();
+}
+
+//#endregion
+//#region src/commands/doctor.ts
+/**
+* Diagnose common kidd project issues.
+*
+* Validates config, checks package.json setup, verifies entry points exist,
+* and catches anything that could cause build or runtime failures.
+*/
+const doctorCommand = command({
+	args: z.object({ fix: z.boolean().describe("Auto-fix issues where possible").optional() }),
+	description: "Diagnose common kidd project issues",
+	handler: async (ctx) => {
+		const cwd = process.cwd();
+		const shouldFix = ctx.args.fix === true;
+		const [configError, configResult] = await loadConfig({ cwd });
+		const [, manifest] = await readManifest(cwd);
+		const [, rawPackageJson] = await readRawPackageJson(cwd);
+		const context = createCheckContext({
+			configError,
+			configResult,
+			cwd,
+			manifest,
+			rawPackageJson
+		});
+		ctx.spinner.start("Running diagnostics...");
+		const initialResults = await Promise.all(CHECKS.map((check) => check.run(context)));
+		const fixResults = await resolveFixResults(shouldFix, initialResults, context);
+		const fixed = fixResults.filter((r) => r.fixed).length;
+		const results = await resolveResults({
+			cwd,
+			fixed,
+			initialResults,
+			shouldFix
+		});
+		ctx.spinner.stop("Diagnostics complete");
+		displayResults(ctx, results, fixResults);
+		const passed = results.filter((r) => r.status === "pass").length;
+		const warnings = results.filter((r) => r.status === "warn").length;
+		const failed = results.filter((r) => r.status === "fail").length;
+		const summary = formatSummary({
+			failed,
+			fixed,
+			passed,
+			total: results.length,
+			warnings
+		});
+		ctx.output.raw(summary);
+		if (failed > 0) ctx.fail(`${failed} ${pluralizeCheck(failed)} failed`);
+	}
+});
+/**
+* Resolve fix results based on whether --fix is enabled.
+*
+* @private
+* @param shouldFix - Whether the --fix flag was set.
+* @param results - The initial check results.
+* @param context - The diagnostic check context.
+* @returns Fix results when --fix is enabled, empty array otherwise.
+*/
+async function resolveFixResults(shouldFix, results, context) {
+	if (!shouldFix) return [];
+	return applyFixes(results, context);
+}
+/**
+* Resolve the final check results, re-running after fixes when needed.
+*
+* Rebuilds the context from disk so that fixes to package.json are reflected.
+*
+* @private
+* @param params - The resolution parameters.
+* @returns Updated check results if fixes were applied, otherwise the initial results.
+*/
+async function resolveResults(params) {
+	if (!params.shouldFix || params.fixed === 0) return params.initialResults;
+	const [configError, configResult] = await loadConfig({ cwd: params.cwd });
+	const [, manifest] = await readManifest(params.cwd);
+	const [, rawPackageJson] = await readRawPackageJson(params.cwd);
+	const freshContext = createCheckContext({
+		configError,
+		configResult,
+		cwd: params.cwd,
+		manifest,
+		rawPackageJson
+	});
+	return Promise.all(CHECKS.map((check) => check.run(freshContext)));
+}
+/**
+* Apply fixes for all non-passing checks that have a fix function.
+*
+* @private
+* @param results - The initial check results.
+* @param context - The diagnostic check context.
+* @returns An array of FixResults for checks that were attempted.
+*/
+async function applyFixes(results, context) {
+	const fixable = CHECKS.filter((check) => {
+		if (!check.fix) return false;
+		const result = results.find((r) => r.name === check.name);
+		return result !== void 0 && result.status !== "pass";
+	}).flatMap((check) => {
+		if (check.fix) return [check.fix];
+		return [];
+	});
+	return Promise.all(fixable.map((fix) => fix(context)));
+}
+/**
+* Display check results with hints and fix indicators.
+*
+* @private
+* @param ctx - The command context.
+* @param results - The check results to display.
+* @param fixResults - The fix results (empty when --fix was not used).
+*/
+function displayResults(ctx, results, fixResults) {
+	results.map((result) => formatResultLine(ctx, result, fixResults));
+}
+/**
+* Format and display a single check result line with optional hint.
+*
+* @private
+* @param ctx - The command context.
+* @param result - The check result to display.
+* @param fixResults - The fix results to check for applied fixes.
+*/
+function formatResultLine(ctx, result, fixResults) {
+	const appliedFix = fixResults.find((f) => f.name === result.name && f.fixed);
+	if (appliedFix) {
+		ctx.output.raw(`  ${formatDisplayStatus("fix")}  ${result.name} - ${appliedFix.message}\n`);
+		return;
+	}
+	ctx.output.raw(`  ${formatDisplayStatus(result.status)}  ${result.name} - ${result.message}\n`);
+	if (result.hint && result.status !== "pass") ctx.output.raw(`        ${pc.dim(`→ ${result.hint}`)}\n`);
+}
+/**
+* Format a display status with color.
+*
+* Accepts both CheckStatus values and the 'fix' display status.
+*
+* @private
+* @param status - The status to format.
+* @returns A colored string representation of the status.
+*/
+function formatDisplayStatus(status) {
+	if (status === "pass") return pc.green("pass");
+	if (status === "warn") return pc.yellow("warn");
+	if (status === "fix") return pc.blue("fix ");
+	return pc.red("fail");
+}
+/**
+* Format the summary line with counts.
+*
+* @private
+* @param params - The count parameters.
+* @returns A formatted summary string.
+*/
+function formatSummary(params) {
+	const base = `\n${params.total} checks, ${params.passed} passed, ${params.warnings} warnings, ${params.failed} failed`;
+	if (params.fixed > 0) return `${base}, ${params.fixed} fixed\n`;
+	return `${base}\n`;
+}
+/**
+* Pluralize the word "check" based on count.
+*
+* @private
+* @param count - The number of checks.
+* @returns "check" or "checks".
+*/
+function pluralizeCheck(count) {
+	if (count === 1) return "check";
+	return "checks";
+}
+
+//#endregion
+export { doctorCommand as default };

package/dist/commands/init.d.mts

@@ -0,0 +1,6 @@
+import { Command } from "@kidd-cli/core";
+
+//#region src/commands/init.d.ts
+declare const _default: Command;
+//#endregion
+export { _default as default };