@schalkneethling/miyagi-core 4.3.0 → 4.4.0

package/README.md

@@ -22,7 +22,52 @@ _miyagi_ is a component development tool for JavaScript templating engines.
 
 ## Requirements
 
-- NodeJS `20.11.0` or higher
+- NodeJS `24` or higher
+
+## Quick start
+
+Twig example:
+
+```bash
+pnpm add -D @schalkneethling/miyagi-core twing
+```
+
+Create `.miyagi.mjs`:
+
+```js
+import { createSynchronousEnvironment, createSynchronousFilesystemLoader } from "twing";
+import fs from "node:fs";
+
+const twing = createSynchronousEnvironment(createSynchronousFilesystemLoader(fs));
+
+export default {
+  components: {
+    folder: "src/components",
+  },
+  docs: {
+    folder: "docs",
+  },
+  engine: {
+    async render({ name, context, cb }) {
+      try {
+        return cb(null, await twing.render(name, context));
+      } catch (err) {
+        return cb(err.toString());
+      }
+    },
+  },
+};
+```
+
+Then start miyagi:
+
+```bash
+pnpm exec miyagi start
+```
+
+Open `http://localhost:5000`.
+
+If you use a different template engine, swap the `engine.render` implementation for that engine.
 
 ## Demos
 
@@ -38,6 +83,8 @@ _miyagi_ is a component development tool for JavaScript templating engines.
 
 [https://docs.miyagi.dev](https://docs.miyagi.dev)
 
+CLI quickstart: [https://docs.miyagi.dev/cli-commands/starting-miyagi/](https://docs.miyagi.dev/cli-commands/starting-miyagi/)
+
 ## Sponsor
 
 <a href="https://factorial.io"><img src="https://logo.factorial.io/color.png" width="40" height="56" alt="Factorial"></a>

package/bin/miyagi.js

@@ -1,2 +1,10 @@
 #!/usr/bin/env node
-import "../index.js";
+import runCli from "../index.js";
+
+const result = await runCli();
+
+if (result?.shouldExit) {
+	process.exit(result.code ?? 0);
+}
+
+process.exitCode = result?.code ?? 0;

package/index.js

@@ -1,3 +1,3 @@
-import Miyagi from "./lib/index.js";
+import { runCli } from "./lib/cli/run.js";
 
-export default await Miyagi();
+export default runCli;

package/lib/cli/component.js

@@ -2,18 +2,24 @@ import generateComponent from "../generator/component.js";
 import log from "../logger.js";
 import appConfig from "../default-config.js";
 import { t } from "../i18n/index.js";
+import { EXIT_CODES } from "../errors.js";
 
 /**
  * @param {object} cliParams
- * @returns {Promise<void>}
+ * @returns {Promise<object>}
  */
 export default async function createComponentViaCli(cliParams) {
-	const commands = cliParams._.slice(1);
+	const commands = [cliParams.component].filter(Boolean);
 
 	if (commands.length === 0) {
-		log("error", t("generator.noComponentNameDefined"));
-
-		return;
+		const message = t("generator.noComponentNameDefined");
+		log("error", message);
+		return {
+			success: false,
+			code: EXIT_CODES.CLI_USAGE_ERROR,
+			shouldExit: true,
+			message,
+		};
 	}
 
 	const [component] = commands;
@@ -25,8 +31,20 @@ export default async function createComponentViaCli(cliParams) {
 	try {
 		const result = await generateComponent({ component, fileTypes });
 		log("success", result);
+		return {
+			success: true,
+			code: EXIT_CODES.SUCCESS,
+			shouldExit: true,
+			message: result,
+		};
 	} catch (message) {
 		log("error", message);
+		return {
+			success: false,
+			code: EXIT_CODES.GENERAL_ERROR,
+			shouldExit: true,
+			message: String(message),
+		};
 	}
 }
 

package/lib/cli/doctor.js

@@ -0,0 +1,153 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import log from "../logger.js";
+import { EXIT_CODES } from "../errors.js";
+import pkgJson from "../../package.json" with { type: "json" };
+
+const CONFIG_FILES = [".miyagi.js", ".miyagi.mjs"];
+
+/**
+ * @returns {Promise<object>}
+ */
+export default async function doctor() {
+	let success = true;
+
+	if (checkNodeVersion()) {
+		log("success", `Node.js ${process.versions.node} satisfies ${pkgJson.engines.node}.`);
+	} else {
+		success = false;
+		log(
+			"error",
+			`Node.js ${process.versions.node} does not satisfy ${pkgJson.engines.node}.`,
+		);
+	}
+
+	const configResult = await loadUserConfig();
+
+	if (!configResult.userFileName) {
+		success = false;
+		log(
+			"error",
+			"No miyagi config found. Create .miyagi.js or .miyagi.mjs in your project root.",
+		);
+		return {
+			success,
+			code: EXIT_CODES.CONFIG_ERROR,
+			shouldExit: true,
+		};
+	}
+
+	if (configResult.error) {
+		success = false;
+		log(
+			"error",
+			`Could not parse ${configResult.userFileName}. Check its syntax and exports.`,
+		);
+		log("error", configResult.error.message, configResult.error);
+		return {
+			success,
+			code: EXIT_CODES.CONFIG_ERROR,
+			shouldExit: true,
+		};
+	}
+
+	log("success", `Loaded config from ${configResult.userFileName}.`);
+
+	const config = configResult.config || {};
+
+	if (typeof config.engine?.render === "function") {
+		log("success", "engine.render is defined.");
+	} else {
+		success = false;
+		log("error", "engine.render is missing.");
+	}
+
+	if (config.components?.folder || config.docs?.folder) {
+		log("success", "At least one source folder is configured.");
+	} else {
+		success = false;
+		log(
+			"error",
+			"Set at least one of components.folder or docs.folder in your miyagi config.",
+		);
+	}
+
+	if (config.components?.folder) {
+		if (await pathExists(config.components.folder)) {
+			log("success", `components.folder exists: ${config.components.folder}`);
+		} else {
+			success = false;
+			log("error", `components.folder does not exist: ${config.components.folder}`);
+		}
+	}
+
+	if (config.docs?.folder) {
+		if (await pathExists(config.docs.folder)) {
+			log("success", `docs.folder exists: ${config.docs.folder}`);
+		} else {
+			success = false;
+			log("error", `docs.folder does not exist: ${config.docs.folder}`);
+		}
+	}
+
+	log(success ? "success" : "error", success ? "Doctor checks passed." : "Doctor found issues.");
+
+	return {
+		success,
+		code: success ? EXIT_CODES.SUCCESS : EXIT_CODES.CONFIG_ERROR,
+		shouldExit: true,
+	};
+}
+
+/**
+ * @returns {boolean}
+ */
+function checkNodeVersion() {
+	const minimumMajor = Number(pkgJson.engines.node.match(/\d+/)?.[0] || 0);
+	const currentMajor = Number(process.versions.node.split(".")[0]);
+	return currentMajor >= minimumMajor;
+}
+
+/**
+ * @param {string} relativePath
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(relativePath) {
+	try {
+		await stat(path.resolve(process.cwd(), relativePath));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * @returns {Promise<object>}
+ */
+async function loadUserConfig() {
+	for (const fileName of CONFIG_FILES) {
+		const fullPath = path.resolve(process.cwd(), fileName);
+
+		if (!(await pathExists(fileName))) {
+			continue;
+		}
+
+		try {
+			const module = await import(`${fullPath}?time=${Date.now()}`);
+			return {
+				userFileName: fileName,
+				config: module.default || {},
+			};
+		} catch (error) {
+			return {
+				userFileName: fileName,
+				error: /** @type {Error} */ (error),
+			};
+		}
+	}
+
+	return {
+		userFileName: null,
+		config: null,
+	};
+}

package/lib/cli/drupal-assets.js

@@ -4,6 +4,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import yaml from "js-yaml";
 import log from "../logger.js";
+import { EXIT_CODES } from "../errors.js";
 import { loadAssetsConfig } from "../drupal/load-assets-config.js";
 import {
 	parseLibrariesYaml,
@@ -18,27 +19,47 @@ import {
 
 /**
  * @param {object} args - CLI arguments from yargs
+ * @returns {Promise<object>}
  */
 export default async function drupalAssets(args) {
 	let config;
 	try {
 		config = await loadAssetsConfig(args);
 	} catch (err) {
-		log("error", /** @type {Error} */ (err).message);
-		process.exit(1);
+		const message = /** @type {Error} */ (err).message;
+		log("error", message);
+		return {
+			success: false,
+			code: EXIT_CODES.CONFIG_ERROR,
+			shouldExit: true,
+			message,
+		};
 	}
 
 	if (!config.libraries) {
-		log("error", "No libraries file specified. Use --libraries or configure it in .miyagi-assets.js.");
-		process.exit(1);
+		const message =
+			"No libraries file specified. Use --libraries or configure it in .miyagi-assets.js.";
+		log("error", message);
+		return {
+			success: false,
+			code: EXIT_CODES.CLI_USAGE_ERROR,
+			shouldExit: true,
+			message,
+		};
 	}
 
 	let yamlContent;
 	try {
 		yamlContent = await readFile(config.libraries, "utf8");
 	} catch {
-		log("error", `Could not read libraries file: ${config.libraries}`);
-		process.exit(1);
+		const message = `Could not read libraries file: ${config.libraries}`;
+		log("error", message);
+		return {
+			success: false,
+			code: EXIT_CODES.CONFIG_ERROR,
+			shouldExit: true,
+			message,
+		};
 	}
 
 	const librariesMap = parseLibrariesYaml(yamlContent);
@@ -89,8 +110,24 @@ export default async function drupalAssets(args) {
 	}
 
 	if (!config.dryRun) {
-		log("success", `Done. Updated ${updatedCount} component(s).`);
+		const message = `Done. Updated ${updatedCount} component(s).`;
+		log("success", message);
+		return {
+			success: true,
+			code: EXIT_CODES.SUCCESS,
+			shouldExit: true,
+			message,
+			updatedCount,
+		};
 	}
+
+	return {
+		success: true,
+		code: EXIT_CODES.SUCCESS,
+		shouldExit: true,
+		message: "Dry run completed.",
+		updatedCount,
+	};
 }
 
 /**

package/lib/cli/index.js

@@ -1,7 +1,9 @@
 import lintImport from "./lint.js";
 import componentImport from "./component.js";
 import drupalAssetsImport from "./drupal-assets.js";
+import doctorImport from "./doctor.js";
 
 export const lint = lintImport;
 export const component = componentImport;
 export const drupalAssets = drupalAssetsImport;
+export const doctor = doctorImport;

package/lib/cli/lint.js

@@ -10,14 +10,16 @@ import {
 	validateSchemas,
 } from "../validator/schemas.js";
 import { t } from "../i18n/index.js";
+import { EXIT_CODES } from "../errors.js";
 
 /**
  * @param {object} args
+ * @returns {Promise<object>}
  */
 export default async function lint(args) {
 	process.env.NODE_ENV = "development";
 
-	const componentArg = args._.slice(1)[0];
+	const componentArg = args.component;
 	const config = await getConfig(args);
 	process.env.MIYAGI_LOG_CONTEXT = "lint";
 	process.env.MIYAGI_LOG_LEVEL = config.lint?.logLevel || "error";
@@ -36,26 +38,63 @@ export default async function lint(args) {
 
 			if (schemaValidation.errors.length > 0) {
 				reportSchemaErrors(schemaValidation.errors);
-				process.exit(1);
+				return {
+					success: false,
+					code: EXIT_CODES.VALIDATION_ERROR,
+					shouldExit: true,
+				};
 			}
 
 			log("success", "All schemas valid.");
 
-			await validateComponentMockData({
+			return await validateComponentMockData({
 				component,
 				validSchemas: schemaValidation.validSchemas,
 			});
 		} else {
-			log("error", `The component ${componentArg} does not seem to exist.`);
-			process.exit(1);
+			const message = `The component ${componentArg} does not seem to exist.`;
+			log("error", message);
+			return {
+				success: false,
+				code: EXIT_CODES.CLI_USAGE_ERROR,
+				shouldExit: true,
+				message,
+			};
 		}
 	} else {
-		await validateAllMockData();
+		return await validateAllMockData();
 	}
 }
 
+/**
+ * @param {object} options
+ * @param {boolean} options.success
+ * @param {boolean} options.shouldExit
+ * @param {boolean} [options.valid]
+ * @param {string} [options.type]
+ * @returns {object}
+ */
+function createLintResult({ success, shouldExit, valid, type }) {
+	const result = {
+		success,
+		code: success ? EXIT_CODES.SUCCESS : EXIT_CODES.VALIDATION_ERROR,
+		shouldExit,
+	};
+
+	if (valid !== undefined) {
+		result.valid = valid;
+	}
+
+	if (type) {
+		result.type = type;
+	}
+
+	return result;
+}
+
 /**
  * @param {boolean} exitProcess
+ * @returns {Promise<object>}
  */
 async function validateAllMockData(exitProcess = true) {
 	log("info", t("linter.all.start"));
@@ -86,9 +125,17 @@ async function validateAllMockData(exitProcess = true) {
 					),
 		);
 		if (exitProcess) {
-			process.exit(1);
+			return {
+				success: false,
+				code: EXIT_CODES.VALIDATION_ERROR,
+				shouldExit: true,
+			};
 		}
-		return;
+		return {
+			success: false,
+			code: EXIT_CODES.VALIDATION_ERROR,
+			shouldExit: false,
+		};
 	}
 
 	const results = await Promise.all(
@@ -134,15 +181,16 @@ async function validateAllMockData(exitProcess = true) {
 
 	if (mockInvalidResults.length === 0 && schemaValidation.errors.length === 0) {
 		log("success", t("linter.all.valid"));
-		if (exitProcess) {
-			process.exit(0);
-		}
-		return;
+		return createLintResult({
+			success: true,
+			shouldExit: exitProcess,
+		});
 	}
 
-	if (exitProcess) {
-		process.exit(1);
-	}
+	return createLintResult({
+		success: false,
+		shouldExit: exitProcess,
+	});
 }
 
 /**
@@ -188,23 +236,19 @@ async function validateComponentMockData({
 			log("success", t("linter.component.valid"));
 		}
 
-		if (exitProcess) {
-			process.exit(0);
-		}
-
-		return {
+		return createLintResult({
 			valid: true,
-		};
-	}
-
-	if (exitProcess) {
-		process.exit(1);
+			success: true,
+			shouldExit: exitProcess,
+		});
 	}
 
-	return {
+	return createLintResult({
 		valid: false,
+		success: false,
+		shouldExit: exitProcess,
 		type: results[0].type,
-	};
+	});
 }
 
 /**