@theholocron/cli 1.0.0

package/src/utils/$/README.md

@@ -0,0 +1,87 @@
+# $
+
+Interact with the file system or run commands.
+
+## Usage
+
+```javascript
+import { $ } from "@/utils";
+
+async function main() {
+	const hasBrew = await $.command("brew");
+	if (hasBrew) {
+		const [err, data] = await $("brew install test");
+
+		if (err) {
+			console.error("Error:", err);
+			process.exit(1);
+		}
+
+		console.log(data);
+	}
+}
+
+main();
+```
+
+## API
+
+### `$(command: string)`
+
+Run a shell command. Returns a Promise that will resolve to either an error or the standard output.
+
+#### command
+
+The shell command to run.
+
+Type: `string`
+
+### `.command(command: string)`
+
+Checks whether a bash command exists. Returns a promise resolving to true if the command is installed, false otherwise.
+
+#### command
+
+The shell command to check.
+
+Type: `string`
+
+### `.directory(path: string, maxDepth: number)`
+
+Returns a Promise that will resolve to a tuple with either an error, or an object with `files` and the `path`.
+
+#### path
+
+The path to the file.
+
+Type: `string`
+
+#### maxDepth
+
+The maximum levels of directories to look through.
+
+Type: `number`
+Default: `Infinity`
+
+### `.file(path: string, content: string | Buffer, overwrite: boolean)`
+
+Returns a Promise that will resolve to a tuple with either an error, or an object with `content` and the `path`.
+
+#### path
+
+The path to the file.
+
+Type: `string`
+
+#### content
+
+The contents of the file to write or append.
+
+Type: `string | Buffer`
+
+#### overwrite
+
+Whether to append to the file or overwrite them completely.
+
+Type: `boolean`
+Default: `false`

package/src/utils/$/command.test.ts

@@ -0,0 +1,48 @@
+import { command, isInstalled } from "./command";
+
+describe("command", () => {
+	test("execute command and return stdout", async () => {
+		const cmd = "echo Hello, world!";
+
+		const result = await command(cmd);
+
+		expect(result).toEqual([null, "Hello, world!\n", expect.any(Number)]);
+	});
+
+	describe("errors", () => {
+		test("return error if command fails", async () => {
+			const result = await command("{}");
+
+			expect(result[0]).toBeDefined();
+			expect(result[1]).toBeNull();
+			expect(result[2]).toEqual(expect.any(Number));
+		});
+
+		test("return 'Unknown error' if error is not an instance of Error", async () => {
+			const unexpectedError = "This is not an Error object";
+
+			const result = await command("valid-command-that-will-throw-an-error", { unexpectedError });
+
+			expect(result[1]).toBeNull();
+			expect(result[2]).toEqual(expect.any(Number));
+		});
+	});
+});
+
+describe("isInstalled", () => {
+	test("return true if command is installed", async () => {
+		const cmd = "ls"; // Assuming 'ls' command is installed on your system
+
+		const result = await isInstalled(cmd);
+
+		expect(result).toBe(true);
+	});
+
+	test("return false if command is not installed", async () => {
+		const cmd = "nonexistent-command";
+
+		const result = await isInstalled(cmd);
+
+		expect(result).toBe(false);
+	});
+});

package/src/utils/$/command.ts

@@ -0,0 +1,21 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { type Return } from "@/types";
+
+const asyncExec = promisify(exec);
+
+export async function command(cmd: string, options: object = {}): Promise<Return<string>> {
+	const start = performance.now();
+
+	try {
+		const { stdout } = await asyncExec(cmd, options);
+		return [null, stdout, performance.now() - start];
+	} catch (error) {
+		return [error as Error, null, performance.now() - start];
+	}
+}
+
+export async function isInstalled(cmd: string, options: object = {}): Promise<boolean> {
+	const [err] = await command(`command -v ${cmd}`, options);
+	return !err;
+}

package/src/utils/$/directory.ts

@@ -0,0 +1,108 @@
+import { promises as fs, Dirent } from "node:fs";
+import * as path from "node:path";
+import { HOME } from "@/const";
+import { type Return } from "@/types";
+import { expandTilde, isHidden, isIgnored } from "./utils";
+
+export function getDirectoryByLevel(filepath: string, size: number = -3): string {
+	// Normalize the file path and split it into parts
+	const parts = path.normalize(filepath).split(path.sep);
+
+	// Remove the home directory path if present
+	if (filepath.startsWith(HOME)) {
+		parts.splice(0, HOME.split(path.sep).length);
+	}
+
+	// Slice the last 3 directories, but if the third directory from the end is not the home directory, keep all three
+	const lastDirs = parts.slice(size);
+
+	// If three parts are kept, only return last two if the third last was home directory
+	return lastDirs.join(path.sep);
+}
+
+export async function isDirectory(pathname: string, options: object = {}): Promise<boolean> {
+	const resolvedPath = expandTilde(pathname);
+
+	try {
+		const stat = await fs.stat(resolvedPath, options);
+		return stat.isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+export async function readDirectory(
+	pathname: string,
+	maxDepth: number = Infinity,
+	currentDepth: number = 0,
+	options: object = {}
+): Promise<string[]> {
+	const resolvedPath = expandTilde(pathname);
+	const files: string[] = [];
+
+	try {
+		const dirents: Dirent[] = await fs.readdir(resolvedPath, { withFileTypes: true, ...options });
+
+		for (const dirent of dirents) {
+			const fullPath = `${resolvedPath}/${dirent.name}`;
+			if (dirent.isDirectory()) {
+				if (!isHidden(dirent.name) && !isIgnored(dirent.name) && currentDepth < maxDepth) {
+					files.push(...(await readDirectory(fullPath, maxDepth, currentDepth + 1)));
+				}
+			} else {
+				files.push(fullPath);
+			}
+		}
+
+		return files;
+	} catch {
+		return [];
+	}
+}
+
+export async function writeDirectory(pathname: string, options: object = {}): Promise<Return<string>> {
+	const resolvedPath = expandTilde(pathname);
+
+	if (await isDirectory(resolvedPath)) {
+		return [null, resolvedPath, 0];
+	}
+
+	try {
+		await fs.mkdir(resolvedPath, { recursive: true, ...options });
+		return [null, resolvedPath, 0];
+	} catch (error) {
+		return [error as Error, null, 0];
+	}
+}
+
+export interface Directory {
+	files: string[];
+	path: string;
+}
+
+export async function directory(pathname: string, maxDepth: number = Infinity): Promise<Return<Directory>> {
+	// if its a directory, return the resolved path and files
+	if (await isDirectory(pathname)) {
+		const files = await readDirectory(pathname, maxDepth);
+		return [
+			null,
+			{
+				files,
+				path: expandTilde(pathname),
+			},
+			0,
+		];
+	}
+
+	// if it doesn't exist, attempt to create it and return resolved path
+	// if it's a file or something other than a directory, it will throw an error
+	const [writeErr] = await writeDirectory(pathname);
+	return [
+		writeErr,
+		{
+			files: [],
+			path: expandTilde(pathname),
+		},
+		0,
+	];
+}

package/src/utils/$/file.ts

@@ -0,0 +1,98 @@
+import { promises as fs } from "node:fs";
+import * as str from "@theholocron/utils-string";
+import { type Return } from "@/types";
+import { expandTilde } from "./utils";
+
+const encoding = "utf-8";
+
+export async function isFile(pathname: string, options: object = {}): Promise<boolean> {
+	const resolvedPath = expandTilde(pathname);
+
+	try {
+		const stat = await fs.stat(resolvedPath, options);
+		return stat.isFile();
+	} catch {
+		return false;
+	}
+}
+
+export interface File {
+	path: string;
+	content: string;
+}
+
+export async function readFile(pathname: string | string[], options: object = {}): Promise<File[]> {
+	const files = str.toArray(pathname);
+	const results: File[] = [];
+
+	for (const file of files) {
+		const resolvedPath = expandTilde(file);
+
+		try {
+			const content = await fs.readFile(resolvedPath, { encoding, ...options });
+			results.push({
+				content,
+				path: resolvedPath,
+			});
+		} catch {
+			results.push({
+				content: "",
+				path: resolvedPath,
+			});
+		}
+	}
+
+	return results;
+}
+
+export async function writeFile(
+	pathname: string,
+	content?: string | Buffer,
+	overwrite: boolean = false,
+	options: object = {}
+): Promise<Return<File>> {
+	const resolvedPath = expandTilde(pathname);
+
+	if (!content) {
+		const [data] = await readFile(resolvedPath);
+		return [null, data, 0];
+	}
+
+	try {
+		if (overwrite) {
+			await fs.writeFile(resolvedPath, content, { encoding, ...options });
+		} else {
+			await fs.appendFile(resolvedPath, content, { encoding, ...options });
+		}
+
+		const [data] = await readFile(resolvedPath);
+		return [null, data, 0];
+	} catch (error) {
+		return [error as Error, null, 0];
+	}
+}
+
+// only handles single files
+export async function file(
+	pathname: string,
+	content?: string | Buffer,
+	overwrite: boolean = false
+): Promise<Return<File>> {
+	// if its a file and there's no content, return the resolved path and contents
+	if ((await isFile(pathname)) && !content) {
+		const [contents] = await readFile(pathname);
+		return [null, contents, 0];
+	}
+
+	// if it doesn't exist, attempt to create it and return resolved path
+	// if it's a file or something other than a directory, it will throw an error
+	const [writeErr, write] = await writeFile(pathname, content, overwrite);
+	return [
+		writeErr,
+		{
+			content: write?.content ?? "",
+			path: write?.path ?? "",
+		},
+		0,
+	];
+}

package/src/utils/$/index.example.ts

@@ -0,0 +1,37 @@
+import { $ } from "./index";
+
+async function main() {
+	const isFile = await $.file("./README.md");
+	const isNotAFile = await $.file("./");
+	const isResolvedFile = await $.file("~/Downloads/chevron-down.tsx");
+	console.log({
+		isFile,
+		isNotAFile,
+		isResolvedFile,
+	});
+
+	const isDirectory = await $.directory("./");
+	const isNotADirectory = await $.directory("./README.md");
+	const isResolvedDirectory = await $.directory("~/Downloads");
+	const isCreatedDirectory = await $.directory("./test");
+	console.log({
+		isDirectory,
+		isNotADirectory,
+		isResolvedDirectory,
+		isCreatedDirectory,
+	});
+
+	const [err, output, time] = await $("ls .");
+	if (err) {
+		console.error("Error executing command:", err);
+	} else {
+		console.log("Command output:", output);
+		console.log("Execution time:", time, "ms");
+	}
+
+	// Checking if a command is installed
+	const isBrewInstalled = await $.command("brew");
+	console.log("Is brew installed?", isBrewInstalled);
+}
+
+main();

package/src/utils/$/index.ts

@@ -0,0 +1,22 @@
+import { type Return } from "@/types";
+import { command, isInstalled } from "./command";
+import { directory } from "./directory";
+import { file } from "./file";
+import { path } from "./path";
+import { remove } from "./remove";
+import { spwn } from "./spawn";
+
+export { type Directory } from "./directory";
+export { type File } from "./file";
+export { getDirectoryByLevel } from "./directory";
+
+export async function $(cmd: string, options: object = {}): Promise<Return<string>> {
+	return await command(cmd, options);
+}
+
+$.command = isInstalled;
+$.directory = directory;
+$.file = file;
+$.path = path;
+$.remove = remove;
+$.spawn = spwn;

package/src/utils/$/path.ts

@@ -0,0 +1,13 @@
+import { promises as fs } from "node:fs";
+import { expandTilde } from "./utils";
+
+export async function path(pathname: string): Promise<boolean> {
+	const resolvedPath = expandTilde(pathname);
+
+	try {
+		await fs.access(resolvedPath);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/utils/$/remove.ts

@@ -0,0 +1,47 @@
+import { promises as fs } from "node:fs";
+import { type Return } from "@/types";
+import { isDirectory } from "./directory";
+import { isFile } from "./file";
+import { expandTilde } from "./utils";
+
+export async function removeFile(pathname: string, options: object = {}): Promise<boolean> {
+	const resolvedPath = expandTilde(pathname);
+
+	try {
+		await fs.rm(resolvedPath, options);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function removeDirectory(pathname: string, options: object = {}): Promise<boolean> {
+	const resolvedPath = expandTilde(pathname);
+
+	try {
+		await fs.rmdir(resolvedPath, options);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function remove(pathname: string, options: object = {}): Promise<Return<boolean>> {
+	const resolvedPath = expandTilde(pathname);
+
+	try {
+		if (await isDirectory(resolvedPath)) {
+			await fs.rmdir(resolvedPath, { recursive: true, ...options });
+			return [null, true, 0];
+		}
+
+		if (await isFile(resolvedPath)) {
+			await fs.rm(resolvedPath, options);
+			return [null, true, 0];
+		}
+
+		return [new Error(`Path does not exist: ${resolvedPath}`), null, 0];
+	} catch (error) {
+		return [error as Error, false, 0];
+	}
+}

package/src/utils/$/spawn.ts

@@ -0,0 +1,26 @@
+import { spawn } from "node:child_process";
+import { type Return } from "@/types";
+
+const asyncSpawn = (cmd: string, args: string[], options: object = {}): Promise<void> =>
+	new Promise((resolve, reject) => {
+		const process = spawn(cmd, args, options);
+
+		process.on("close", (code) => {
+			if (code !== 0) {
+				reject(new Error(`process exited with code ${code}`));
+			} else {
+				resolve();
+			}
+		});
+	});
+
+export async function spwn(cmd: string, args: string[], options: object = {}): Promise<Return<boolean>> {
+	const start = performance.now();
+
+	try {
+		await asyncSpawn(cmd, args, options);
+		return [null, true, performance.now() - start];
+	} catch (error) {
+		return [error as Error, false, performance.now() - start];
+	}
+}

package/src/utils/$/utils.ts

@@ -0,0 +1,21 @@
+import { HOME, SYSTEM_IGNORED_FOLDERS, type IgnoredFolders } from "@/const";
+import { config } from "../config";
+
+/**
+ * Expands the tilde (~) in a path to the user's home directory.
+ */
+export function expandTilde(pathname: string): string {
+	const tilde = "~";
+
+	if (pathname.startsWith(tilde)) {
+		return pathname.replace(tilde, HOME);
+	}
+
+	return pathname;
+}
+
+export const isHidden = (pathname: string): boolean => pathname.startsWith(".");
+
+export const isIgnored = (pathname: string): boolean =>
+	SYSTEM_IGNORED_FOLDERS.includes(pathname as IgnoredFolders) ||
+	config.get("preferences.ignoredFolders").includes(pathname);

package/src/utils/README.md

@@ -0,0 +1,15 @@
+# Utilities
+
+A set of functions designed to be littered everywhere.
+
+## What's Available
+
+-   [$](./$/README.md) - run a bash command in Node
+-   [config](./config/README.md) - read and write to a configuration file
+-   [env](./env/README.md) - read and write to a `.env` for use with Environment variables
+-   [log](./log/README.md) - a logger
+-   [node](./node/README.md) - interact with node packages
+
+## Rules
+
+-   There should be no logging; all Utilities should rely on what is returned, no thrown errors, only returns

package/src/utils/config/README.md

@@ -0,0 +1,41 @@
+# Configuration
+
+A wrapper around [`conf`](https://github.com/sindresorhus/conf) that provides a configuration file for storing environment variables.
+
+The configuration will pull from a `config.json` file within the operating systems [preferred configuration locations](https://github.com/sindresorhus/env-paths?tab=readme-ov-file#pathsdata).
+
+## Usage
+
+```javascript
+import { config } from "@/utils";
+
+const debugMode = "preferences.debug";
+
+// get an item
+const isDebugMode = config.get(debugMode);
+
+// set an item
+config.write(debugMode, true);
+```
+## API
+
+The API is a wrapper, so look at the [docs](https://github.com/sindresorhus/conf) for a detailed list of functions.  The following is the ones that are most commonly used.
+
+### `.get(key, defaultValue?)`
+
+Get an item or `defaultValue` if the item does not exist.
+
+### `.set(key, value)`
+
+Set an item.
+
+The value must be JSON serializable. Trying to set the type `undefined`, `function`, or `symbol` will result in a `TypeError`.
+
+### `.set(object)`
+
+Set multiple items at once.
+
+### `.edit()`
+
+Open the configuration file in your preferred `$EDITOR`;
+

package/src/utils/config/config.ts

@@ -0,0 +1,26 @@
+import Conf, { type Schema } from "conf";
+import pkg from "@/package";
+
+import { preferences, type PreferencesSchema } from "./preferences.conf";
+
+interface ConfigSchema {
+	name: string;
+	preferences: PreferencesSchema;
+}
+
+const schema: Schema<ConfigSchema> = {
+	name: {
+		default: "holocron",
+		type: "string",
+	},
+	preferences: {
+		type: "object",
+		properties: preferences,
+	},
+};
+
+export const config = new Conf({
+	projectName: pkg.name,
+	projectVersion: pkg.version,
+	schema,
+});

package/src/utils/config/index.ts

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

package/src/utils/config/preferences.conf.ts

@@ -0,0 +1,45 @@
+import * as path from "node:path";
+import { HOME, OS } from "@/const";
+
+export interface PreferencesSchema {
+	debug: boolean;
+	destination: string;
+	ignoredFolders: string[];
+	notifications: boolean;
+	sound: boolean;
+}
+
+export const preferences = {
+	debug: {
+		type: "boolean",
+		default: false,
+	},
+	destination: {
+		type: "string",
+		default: `${OS}/Desktop`,
+	},
+	ignoredFolders: {
+		type: "array",
+		items: {
+			type: "string",
+		},
+		uniqueItems: true,
+		default: [".DS_Store", "holocron", "coverage", "dist", "node_modules"],
+	},
+	logs: {
+		type: "string",
+		default:
+			process.env.LOG_DIR ||
+			(OS === "win32"
+				? path.join(process.env.LOCALAPPDATA || path.join(HOME, "AppData", "Local"), "Holocron", "logs")
+				: path.join(HOME, ".holocron", "logs")),
+	},
+	notifications: {
+		type: "boolean",
+		default: false,
+	},
+	sound: {
+		type: "boolean",
+		default: false,
+	},
+};