@theholocron/cli 1.0.0

package/src/utils/env/README.md

@@ -0,0 +1,52 @@
+# Environment Variables
+
+A wrapper around [`dotenv`](https://github.com/motdotla/dotenv) that provides a configuration file for storing environment variables.
+
+The configuration will pull from a `.env` file within the repository and place all of that data onto the `process.env` for instant access.
+
+## Usage
+
+```javascript
+import { env } from "@/utils";
+
+// grab every value within the configuration file
+const [readErr, readData] = env.read();
+
+// grab a specific variable
+const [readAllErr, readAllData] = env.read("SOME_ENV_VAR");
+
+// set a specific variable
+const [writeErr, writeData] = env.write({ mockKey: "mockValue" });
+```
+
+### When to use `env` methods or `process.env`
+
+#### Use `process.env` for accessing environment variables
+
+The point of `dotenv` is to allow you to put environment variables within a file in order to have them show up on `process.env`.  So if you need access to any environment variable, rather than running it on the command-line, you can add it to the `.env` and it will be present.
+
+#### Use `env.read()` for interfacing with the configuration file
+
+Whenever you want the application to read the configuration file or values on it, then use `env.read()`. Common use cases would be to read the configuration before changing it, or reading the values to use it for setting something else such as a file name.
+
+#### Use `env.write()` for writing to or updating the configuration file
+
+Whenever you want the application to change the configuration file or values on it, then use `env.write()`.  This will set permanent changes to the configuration file.
+
+## API
+
+### `.read(key?: string)`
+
+Returns the value of the key specified or the entire environment variables object if no key is present.
+
+#### key
+
+Type: `string`
+
+### `.write(obj: Record<string, string>)`
+
+Returns `true` if writing to the environment variables file was successful, or `false` if there was an error.
+
+#### obj
+
+Type: `Record<string, string>`

package/src/utils/env/env.example.ts

@@ -0,0 +1,21 @@
+import { env } from "@/utils";
+
+const [err, data] = env.read();
+
+if (err) {
+	console.error(err);
+	process.exit(1);
+}
+
+console.log("Complete env");
+console.log(data);
+
+const [singleErr, singleData] = env.read("VERBOSE");
+
+if (singleErr) {
+	console.error(singleErr);
+	process.exit(1);
+}
+
+console.log("Single key env");
+console.log(singleData);

package/src/utils/env/env.ts

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import dotenv from "dotenv";
+
+const ENV_CONF = `${process.cwd()}/.env`;
+
+/**
+ * Reads environment variables from the .env file.
+ */
+type ReadEnvReturn<T> = [Error | null, T];
+
+const readEnv = <T = Record<string, string>>(key?: string): ReadEnvReturn<T> => {
+	try {
+		const result = dotenv.config();
+
+		if (result.error) {
+			return [result.error, {} as T];
+		}
+
+		const parsedData = result.parsed || {};
+
+		if (key && parsedData.hasOwnProperty(key)) {
+			return [null, parsedData[key] as T];
+		}
+
+		return [null, parsedData as T];
+	} catch (error) {
+		return [error as Error, {} as T];
+	}
+};
+
+/**
+ * Writes environment variables to the .env file.
+ */
+const writeEnv = (obj: Record<string, string>): [Error | null, boolean] => {
+	try {
+		const [_, conf] = readEnv();
+
+		const newConf = {
+			...conf,
+			...obj,
+		};
+
+		const content = Object.entries(newConf)
+			.map(([key, value]) => `${key}=${value}`)
+			.join("\n");
+
+		fs.writeFileSync(ENV_CONF, content, { flag: "w+" });
+		return [null, true];
+	} catch (err) {
+		return [err as Error, false];
+	}
+};
+
+export const env = {
+	read: readEnv,
+	write: writeEnv,
+};

package/src/utils/env/index.ts

@@ -0,0 +1 @@
+export * from "./env";

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export * from "./$";
+export * from "./config";
+export * from "./env";
+export * from "./log";
+export * from "./node";

package/src/utils/log/README.md

@@ -0,0 +1,117 @@
+# Log
+
+A logger with different levels and formatting options.
+
+This provides functions for logging messages with different log levels (error, info, success, warning). Each log level has its own formatting for better readability.
+
+## Usage
+
+```javascript
+import { log } from "@/utils";
+
+const FN = "func";
+const options = { debug: true };
+
+console.log(log.style.bold("this message is bold"));
+
+log.data(FN, "key", { test: "value"}, options);
+log.error(FN, "This is an error message", options);
+log.info(FN, "This is an info message", options);
+log.process(FN, "this is a processing message", options);
+log.success(FN, "This is a success message", options);
+log.warning(FN, "This is a warning message", options);
+```
+
+## API
+
+All functions take `CLIOptions` as the last argument, which allow you to pass in an object with `debug` as a boolean to allow you to print to the console and `sound` as a boolean to allow sound as feedback.
+
+### `.data(prefix: string, key: string, message: any, options: CLIOptions)`
+
+Logs data with a function prefix.
+
+#### prefix
+
+The function name to be identified in the logs.
+
+Type: `string`
+
+#### key
+
+A name for the data.
+
+Type: `string`
+
+#### message
+
+Type: `any`
+
+### `.error(prefix: string, message: string)`
+
+Logs an error message with a function prefix.
+
+#### prefix
+
+The function name to be identified in the logs.
+
+Type: `string`
+
+#### message
+
+Type: `string`
+
+### `.info(prefix: string, message: string)`
+
+Logs an info message with a function prefix.
+
+#### prefix
+
+The function name to be identified in the logs.
+
+Type: `string`
+
+#### message
+
+Type: `string`
+
+### `.process(prefix: string, message: string)`
+
+Logs a message for a running process with a function prefix.
+
+#### prefix
+
+The function name to be identified in the logs.
+
+Type: `string`
+
+#### message
+
+Type: `string`
+
+### `.success(prefix: string, message: string)`
+
+Logs a success message with a function prefix.
+
+#### prefix
+
+The function name to be identified in the logs.
+
+Type: `string`
+
+#### message
+
+Type: `string`
+
+### `.warning(prefix: string, message: string)`
+
+Logs a warning message with a function prefix.
+
+#### prefix
+
+The function name to be identified in the logs.
+
+Type: `string`
+
+#### message
+
+Type: `string`

package/src/utils/log/index.ts

@@ -0,0 +1,2 @@
+export * from "./log";
+export { type LogLevel } from "./logger";

package/src/utils/log/log.example.ts

@@ -0,0 +1,13 @@
+import { log } from "@/utils";
+
+const FN = "func";
+const options = { debug: true };
+
+console.log(log.style.bold("this message is bold"));
+
+log.data(FN, "key", { test: "value" }, options);
+log.error(FN, "This is an error message", options);
+log.info(FN, "This is an info message", options);
+log.process(FN, "this is a processing message", options);
+log.success(FN, "This is a success message", options);
+log.warning(FN, "This is a warning message", options);

package/src/utils/log/log.ts

@@ -0,0 +1,58 @@
+import chalk from "chalk";
+import { type CLIOptions } from "@/cli";
+import { logger } from "./logger";
+import { sound } from "./sound";
+
+type LoggerFunction = (prefix: string, message: string, options?: CLIOptions) => void;
+
+const bold = (str: string) => chalk.magenta.bold(str);
+
+const data = (prefix: string, key: string, message: any, options: CLIOptions) => {
+	options?.debug && console.log(chalk.cyan(`[${prefix}]:`), chalk.bgWhiteBright(`${key}:`), message);
+};
+
+const error: LoggerFunction = (prefix, message, options) => {
+	logger.error(`[${prefix}] error: ${message}`);
+
+	console.log(chalk.red.bold(message));
+	options?.sound && sound.error();
+};
+
+const info: LoggerFunction = (prefix, message, options) => {
+	logger.info(`[${prefix}] info: ${message}`);
+
+	options?.debug && console.log(chalk.cyan(`[${prefix}]:`), message);
+};
+
+const processing: LoggerFunction = (prefix, message, options) => {
+	logger.info(`[${prefix}] processing: ${message}`);
+
+	options?.debug && console.log(chalk.magenta(`[${prefix}]:`), message);
+};
+
+const success: LoggerFunction = (prefix, message, options) => {
+	logger.info(`[${prefix}] success: ${message}`);
+
+	console.log(chalk.green.bold(message));
+	options?.sound && sound.success();
+};
+
+const warning: LoggerFunction = (prefix, message, options) => {
+	logger.warn(`[${prefix}] warning: ${message}`);
+
+	console.log(chalk.yellow.bold(message));
+	options?.sound && sound.warning();
+};
+
+export const log = {
+	bold,
+	data,
+	error,
+	info,
+	process: processing,
+	success,
+	style: {
+		bold,
+	},
+	warning,
+};

package/src/utils/log/logger.ts

@@ -0,0 +1,28 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import winston from "winston";
+import { config } from "@/utils";
+
+const LOGS = config.get("preferences.logs");
+
+if (!fs.existsSync(LOGS)) {
+	fs.mkdirSync(LOGS, { recursive: true });
+}
+
+export type LogLevel = "error" | "warn" | "info" | "verbose" | "debug" | "all";
+
+export const logger = winston.createLogger({
+	level: "info" as LogLevel,
+	format: winston.format.combine(
+		winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+		winston.format.printf(({ timestamp, level, message }) => `${timestamp} ${level}: ${message}`)
+	),
+	transports: [
+		new winston.transports.File({ filename: path.join(LOGS, "error.log"), level: "error" as LogLevel }),
+		new winston.transports.File({ filename: path.join(LOGS, "warn.log"), level: "warn" as LogLevel }),
+		new winston.transports.File({ filename: path.join(LOGS, "info.log"), level: "info" as LogLevel }),
+		new winston.transports.File({ filename: path.join(LOGS, "verbose.log"), level: "verbose" as LogLevel }),
+		new winston.transports.File({ filename: path.join(LOGS, "debug.log"), level: "debug" as LogLevel }),
+		new winston.transports.File({ filename: path.join(LOGS, "log") }), // General log file
+	],
+});

package/src/utils/log/sound.ts

@@ -0,0 +1,35 @@
+import play from "play-sound";
+
+const player = play();
+
+async function playSound(soundPath: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		player.play(soundPath, (err: Error | null) => {
+			if (err) {
+				reject(err);
+			} else {
+				resolve();
+			}
+		});
+	});
+}
+
+type FeedbackFunction = () => Promise<void>;
+
+const error: FeedbackFunction = async () => {
+	await playSound("./media/error.mp3");
+};
+
+const success: FeedbackFunction = async () => {
+	await playSound("./media/success.mp3");
+};
+
+const warning: FeedbackFunction = async () => {
+	await playSound("./media/warning.mp3");
+};
+
+export const sound = {
+	error,
+	success,
+	warning,
+};

package/src/utils/node/README.md

@@ -0,0 +1,23 @@
+# Node
+
+Interact with node packages.
+
+## Usage
+
+```javascript
+import { node } from "@/utils";
+
+const name = node.pkg("~/code/foo");
+```
+
+## API
+
+### `.pkg(dirPath: string)`
+
+Grabs the data from the package in parsed JSON.
+
+#### dirPath
+
+The pathway to the `package.json`.
+
+Type: `string`

package/src/utils/node/index.ts

@@ -0,0 +1,5 @@
+import { getPackage } from "./package";
+
+export const node = {
+	pkg: getPackage,
+};

package/src/utils/node/package.ts

@@ -0,0 +1,12 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+export async function getPackage(dirPath: string): Promise<string | null> {
+	try {
+		const pkg = await fs.readFile(path.join(dirPath, "package.json"), "utf-8");
+
+		return [null, JSON.parse(pkg)];
+	} catch (error) {
+		return [error];
+	}
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "display": "Holocron CLI",
+  "extends": "@tsconfig/node-lts/tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "outDir": "./dist",
+    "paths": {
+      "@/media": ["./media/*"],
+      "@/package": ["./package.json"],
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["./node_modules"]
+}

package/yamllint.config.yml

@@ -0,0 +1,20 @@
+---
+
+extends: default
+
+rules:
+  comments:
+    min-spaces-from-content: 1
+    require-starting-space: true
+
+  comments-indentation: {}
+
+  document-start:
+    ignore: |
+      .github/*.yml
+
+  indentation:
+    spaces: consistent
+    indent-sequences: consistent
+
+  line-length: disable