@theholocron/cli 1.0.0

package/README.md

@@ -0,0 +1,17 @@
+# Holocron
+
+The command-line client designed to support [The Holocron](http://docs.theholocron.dev).
+
+## Installation
+
+```bash
+npm install --global @theholocron/cli
+```
+
+## Usage
+
+<!-- fill out the usage with examples -->
+
+## Documentation
+
+Check out [The Holocron Archive](https://docs.theholocron.dev/projects/holocron/) for more information.

package/commitlint.config.js

@@ -0,0 +1,9 @@
+/**
+ * @see https://commitlint.js.org/reference/configuration.html
+ * @type {import("@commitlint/types").UserConfig}
+ */
+const config = {
+	extends: ["@theholocron"],
+};
+
+export default config;

package/eslint.config.js

@@ -0,0 +1,9 @@
+import theHolocron from "@theholocron/eslint-config";
+
+/**
+ * @see https://eslint.org/docs/latest/use/configure/
+ * @type {import("eslint").Linter.Config}
+ */
+const config = [...theHolocron];
+
+export default config;

package/media/README.md

@@ -0,0 +1,11 @@
+# Media
+
+The following is a storage place for all of the media used within `holocron`.
+
+## What's Available
+
+### MP3s
+
+-   error.mp3 - used for when a command errs, and the `--sound` flag is enabled
+-   warning.mp3 - used for when a command has a warning, and the `--sound` flag is enabled
+-   success.mp3 - used for when a command is successful, and the `--sound` flag is enabled

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@theholocron/cli",
+  "version": "1.0.0",
+  "description": "The command-line client designed to support The Holocron.",
+  "homepage": "https://github.com/theholocron/holocron#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git"
+  },
+  "license": "GPL-3.0",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "src/cli.ts",
+  "bin": {
+    "holocron": "./src/cli.ts"
+  },
+  "man": "./man/holocron.1",
+  "scripts": {
+    "lint": "docker run -e LOG_LEVEL=DEBUG -e RUN_LOCAL=true -v .:/tmp/lint --rm ghcr.io/super-linter/super-linter:latest",
+    "postbuild": "marked-man README.md > man/holocron.1",
+    "start": "tsx ./src/cli.ts"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.1",
+    "@theholocron/utils-string": "^0.1.0",
+    "chalk": "^5.3.0",
+    "conf": "^13.0.1",
+    "default-browser": "^5.2.1",
+    "dotenv": "^16.4.5",
+    "inquirer-autocomplete-standalone": "^0.8.1",
+    "open": "^10.1.0",
+    "open-editor": "^4.1.1",
+    "ora": "^8.1.0",
+    "play-sound": "^1.1.6",
+    "update-notifier": "^7.3.1",
+    "winston": "^3.15.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@theholocron/commitlint-config": "^3.4.4",
+    "@theholocron/eslint-config": "^3.4.4",
+    "@theholocron/jest-config": "^3.4.4",
+    "@theholocron/lint-staged-config": "^3.4.4",
+    "@theholocron/prettier-config": "^3.4.4",
+    "@theholocron/storybook-config": "^3.4.4",
+    "@theholocron/stylelint-config": "^3.4.4",
+    "@theholocron/tsconfig": "^3.4.4",
+    "@tsconfig/node-lts": "^20.1.3",
+    "@types/conf": "^2.1.0",
+    "@types/inquirer": "^9.0.7",
+    "@types/play-sound": "^1.1.2",
+    "@types/update-notifier": "^6.0.8",
+    "@types/winston": "^2.4.4",
+    "@types/yargs": "^17.0.33",
+    "alexjs": "^1.0.0",
+    "marked-man": "^2.1.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  },
+  "packageManager": "npm@9.5.0",
+  "engines": {
+    "node": ">=23",
+    "npm": ">=10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "releases": "https://github.com/theholocron/holocron/releases",
+  "wiki": "https://github.com/theholocron/holocron/wiki"
+}

package/prettier.config.js

@@ -0,0 +1,11 @@
+import theholocron from "@theholocron/prettier-config";
+
+/**
+ * @see https://prettier.io/docs/en/configuration
+ * @type {import("prettier").Config}
+ */
+const config = {
+	...theholocron,
+};
+
+export default config;

package/src/cli.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env npx tsx
+
+import * as str from "@theholocron/utils-string";
+import updateNotifier from "update-notifier";
+import { hideBin } from "yargs/helpers";
+import yargs from "yargs/yargs";
+import { __cmddir } from "@/const";
+import pkg from "@/package";
+import * as utils from "@/utils";
+
+const [, env] = utils.env.read();
+
+export interface CLIOptions {
+	d?: boolean;
+	debug?: boolean;
+	s?: boolean;
+	sound?: boolean;
+	verbose?: boolean;
+	// spinner: Ora;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+yargs(hideBin(process.argv))
+	.usage("Usage: $0 <command> [options]")
+	.commandDir(__cmddir("./commands"), {
+		extensions: ["ts"],
+	})
+	.demandCommand()
+	.env("HOLOCRON")
+	.completion()
+	.recommendCommands()
+	.options({
+		d: {
+			alias: ["debug"],
+			default: utils.config.get("preferences.debug") || str.toBoolean(env?.HOLOCRON_DEBUG) || false,
+			describe: "Turn on debugging mode",
+			type: "boolean",
+			global: true,
+			hidden: true,
+		},
+		s: {
+			alias: ["sound"],
+			default: utils.config.get("preferences.sound") || str.toBoolean(env?.HOLOCRON_SOUND) || false,
+			describe: "Turn on sound effects",
+			type: "boolean",
+			global: true,
+			hidden: true,
+		},
+		verbose: {
+			default: str.toBoolean(env?.HOLOCRON_VERBOSE) || false,
+			describe: "Turn on logging",
+			type: "boolean",
+			global: true,
+		},
+	})
+	.alias({
+		h: "help",
+		v: "version",
+	})
+	.strict()
+	.help("h")
+	.version()
+	.epilogue(`© 2024-${new Date().getFullYear()} The Holocron, Inc. All rights reserved.`).argv as CLIOptions;
+
+updateNotifier({ pkg }).notify();

package/src/commands/README.md

@@ -0,0 +1,13 @@
+# Commands
+
+A direct interaction with the command-line via `yargs`.
+
+## What's Available
+
+-   bootstrap - bootstrap a repository by swapping out template variables
+-   conf - interact with the configuration file
+-   log - print out the log file
+
+## Rules
+
+-   There should be error logging and success logging; process/warning if it make sense; data for sure

package/src/commands/bootstrap.ts

@@ -0,0 +1,102 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as str from "@theholocron/utils-string";
+import { type CommandBuilder } from "yargs";
+import { type CLIOptions } from "@/cli";
+import { HOME } from "@/const";
+import { findReplace } from "@/tasks";
+import { prompt } from "@/ui";
+import { getDirectoryByLevel, log, node } from "@/utils";
+
+function getRepoName(pathname) {
+	const gitconfig = path.join(pathname, ".git", "config");
+
+	try {
+		const content = fs.readFileSync(gitconfig, "utf-8");
+		const match = content.match(/url = .*\/(.*)\.git/); // Regex to capture repo name
+		return match ? match[1] : null;
+	} catch (error) {
+		console.error("Error reading .git/config:", error);
+		return null;
+	}
+}
+
+interface BootstrapOpts extends CLIOptions {
+	description?: string;
+	name?: string;
+}
+
+interface BootstrapPositional extends CLIOptions {
+	filepath?: string;
+}
+
+export const builder: CommandBuilder<BootstrapOpts, BootstrapPositional> = (yargs) =>
+	yargs
+		.options({
+			description: {
+				describe: "The description for the project",
+				nargs: 1,
+				requiresArg: true,
+				type: "string",
+			},
+			name: {
+				describe: "The name of the project",
+				nargs: 1,
+				requiresArg: true,
+				type: "string",
+			},
+		})
+		.positional("filepath", {
+			describe: "The path to where the project is stored",
+			type: "string",
+		});
+export const command: string = "bootstrap [filepath] [name] [description]";
+export const desc: string = "Bootstrap a template";
+export async function handler(options: CLIOptions): Promise<void> {
+	const FN = "bootstrap";
+	log.data(FN, "arguments", options, options);
+
+	// search the home directory for projects
+	// @TODO set this to check a configurable directory and default to HOME
+	const projectPath = await prompt.search(options?.filepath, HOME, options);
+	// from the project i need to determine if its has a package.json
+	// and what type of template it is based on the name on the package.json
+	// e.g. { name: "@theholocron/cli-template" }
+	const [, pkg] = await node.pkg(projectPath);
+	// template type, if any
+	const type = getDirectoryByLevel(pkg.name, -1) ?? "react-template";
+
+	const name =
+		options?.name ??
+		(await prompt.input("The name. What are we calling this thing?", true, {
+			default: getRepoName(projectPath),
+			transformer: str.toKebabCase,
+		}));
+
+	const description =
+		options?.description ??
+		(await prompt.input("A brief description. What does it do?", true, {
+			transformer: str.toSentenceCase,
+		}));
+
+	const readme = `${projectPath}/README.md`;
+	const pkgJson = `${projectPath}/package.json`;
+
+	await findReplace([readme, `${projectPath}/tsconfig.json`], type, str.toTitleCase(name));
+	await findReplace(
+		[`${projectPath}/src/utils/config/config.ts`, pkgJson, `${projectPath}/vite.config.ts`],
+		type,
+		str.toKebabCase(name)
+	);
+	await findReplace([readme, pkgJson], "<description>", str.toSentenceCase(description));
+
+	if (type === "cli-template") {
+		await findReplace(
+			[`${projectPath}/src/cli.ts`, `${projectPath}/.env`],
+			"CLI_TEMPLATE",
+			str.toConstantCase(name)
+		);
+	}
+
+	process.exit(0);
+}

package/src/commands/conf/README.md

@@ -0,0 +1,45 @@
+# Configuration File
+
+An action to interact with the configuration file.
+
+## How Do I Use This?
+
+Run the `--help` or `-h` command to find out how to use the command.
+
+```sh
+Usage: tsx ./src/cli.ts conf <command> [options]
+
+Commands:
+	tsx ./src/cli.ts conf add <key> <value> [options]
+	tsx ./src/cli.ts conf edit [options]
+	tsx ./src/cli.ts conf view [key] [options]
+
+Examples:
+	tsx ./src/cli.ts conf add 
+	tsx ./src/cli.ts conf edit
+	tsx ./src/cli.ts conf view
+	tsx ./src/cli.ts conf view domains
+```
+
+All [global options](/README.md#options) are supported as well.
+
+## API
+
+### Return
+
+If command is valid, it will exit with a `0` code and the file path. Otherwise, it will exit with `1` code and an error message.
+
+### `add`
+
+Adds a key-value pair to the configuration and returns the updated configuration.
+
+### `edit`
+
+Opens the configuration file in the default editor for editing.
+
+### `view`
+
+Retrieves and prints the configuration settings based on provided keys or all configurations if no keys are specified.
+
+* `options:CLIOptions` - The options containing configuration details and the keys to be retrieved.
+* @returns {Record<string, any> | Record<string, any>[]} - The requested configuration settings.

package/src/commands/conf/add.ts

@@ -0,0 +1,49 @@
+import type { CommandBuilder } from "yargs";
+import { CLIOptions } from "@/cli";
+import { config, log } from "@/utils";
+
+interface AddConfOpts extends CLIOptions {
+	name: string;
+	value: any;
+}
+
+export const builder: CommandBuilder<AddConfOpts, AddConfOpts> = (yargs) =>
+	yargs
+		.positional("name", {
+			demandOption: true,
+			describe: "A key to store as within the configuration file",
+			type: "string",
+		})
+		.positional("value", {
+			demandOption: true,
+			describe: "The value to store within the configuration file",
+			type: "string",
+		});
+export const command: string = "add <name> <value>";
+export const desc: string = "Add to the configuration";
+export function handler(options: AddConfOpts): void {
+	const FN = "conf add";
+	log.data(FN, "arguments", options, options);
+
+	const { name, value } = options;
+	const conf = config.get(name);
+
+	if (Array.isArray(conf)) {
+		config.set(name, Array.from(new Set([...conf, value])));
+		const obj = config.get(name);
+		log.success(FN, obj);
+		return obj;
+	}
+
+	if (Object.prototype.toString.call(conf) === "[object Object]") {
+		config.set(name, { ...conf, ...value });
+		const obj = config.get(name);
+		log.success(FN, obj);
+		return obj;
+	}
+
+	config.set(name, value);
+	const obj = config.get(name);
+	log.success(FN, obj);
+	return obj;
+}

package/src/commands/conf/edit.ts

@@ -0,0 +1,12 @@
+import { type CLIOptions } from "@/cli";
+import { open } from "@/ui";
+import { config, log } from "@/utils";
+
+export const command: string = "edit";
+export const desc: string = "Edit the configuration";
+export async function handler(options: CLIOptions): Promise<void> {
+	const FN = "conf edit";
+	log.data(FN, "arguments", options, options);
+
+	await open.editor(config.path, undefined, true);
+}

package/src/commands/conf/view.ts

@@ -0,0 +1,40 @@
+import type { CommandBuilder } from "yargs";
+import { CLIOptions } from "@/cli";
+import { config, log, str } from "@/utils";
+
+interface ViewConfOpts extends CLIOptions {
+	name?: string[];
+}
+
+export const builder: CommandBuilder<ViewConfOpts, ViewConfOpts> = (yargs) =>
+	yargs.positional("name", {
+		coerce: str.toArray,
+		describe: "Any key within the configuration file",
+		type: "string",
+	});
+export const command: string = "view [name..]";
+export const desc: string = "View the configuration";
+export function handler(options: ViewConfOpts): Record<string, any> | Record<string, any>[] {
+	const FN = "conf.view";
+	log.data(FN, "arguments", options, options);
+
+	const { name } = options;
+
+	if (name && name.length > 0) {
+		const items = name.reduce(
+			(acc, item) => {
+				acc[item] = config.get(item);
+				return acc;
+			},
+			{} as Record<string, any>
+		);
+
+		console.log(items);
+		return items;
+	}
+
+	const allConfig = config.get();
+	const obj = { ...allConfig };
+	console.log(obj);
+	return obj;
+}

package/src/commands/conf.ts

@@ -0,0 +1,10 @@
+import { type CommandBuilder } from "yargs";
+
+interface ConfArgs {
+	command: string;
+}
+
+export const builder: CommandBuilder<ConfArgs, ConfArgs> = (yargs) =>
+	yargs.commandDir("conf", { extensions: ["js", "ts"] });
+export const command: string = "conf <command>";
+export const desc: string = "Interact with the configuration";

package/src/commands/log.ts

@@ -0,0 +1,91 @@
+import fs from "fs";
+import readline from "readline";
+import chalk from "chalk";
+import type { CommandBuilder } from "yargs";
+import { type CLIOptions } from "@/cli";
+import { config, type LogLevel } from "@/utils";
+
+export interface LogOpts extends CLIOptions {
+	level?: LogLevel;
+	maxLines?: number;
+}
+
+export const levels: Record<LogLevel, string> = {
+	all: "log",
+	error: "error.log",
+	warn: "warn.log",
+	info: "info.log",
+	verbose: "verbose.log",
+	debug: "debug.log",
+};
+
+export const builder: CommandBuilder<LogOpts, LogOpts> = (yargs) =>
+	yargs.options({
+		l: {
+			alias: ["level", "log-level"],
+			choices: Object.keys(levels) as LogLevel[],
+			default: "all",
+			demandOption: true,
+			describe: "The log level to show",
+		},
+		o: {
+			alias: ["output", "max-lines"],
+			default: 20,
+			describe: "Maximum number of lines to show, from the end of the file",
+			type: "number",
+		},
+	});
+export const command: string = "log";
+export const desc: string = "Print out the logs";
+
+/**
+ * Reads and displays the last `maxLines` lines from a log file with enhanced formatting.
+ *
+ * @param {string} [level='all'] - The log level to read (e.g., 'all', 'error'). Defaults to 'all'.
+ * @param {number} [maxLines] - The number of lines to display from the end of the log file. If not provided, displays the entire file.
+ */
+export async function handler(options: LogOpts): Promise<void> {
+	const { level, maxLines } = options;
+	const logFilePath = `${config.get("preferences.logs")}/${levels[level || "all"] || levels.all}`;
+	const fileStream = fs.createReadStream(logFilePath);
+	const rl = readline.createInterface({
+		input: fileStream,
+		crlfDelay: Infinity,
+	});
+
+	const lines: { number: number; content: string }[] = [];
+	let lineNumber = 0;
+
+	rl.on("line", (line: string) => {
+		lineNumber++;
+		lines.push({ number: lineNumber, content: line });
+		if (maxLines !== undefined && lines.length > maxLines) {
+			lines.shift();
+		}
+	});
+
+	await new Promise<void>((resolve) => rl.on("close", resolve));
+
+	// Define chalk styles
+	const timestampStyle = chalk.yellow;
+	const levelStyle = chalk.bold.red;
+	const messageStyle = chalk.white;
+	const bracketStyle = chalk.magenta;
+
+	lines.forEach(({ number, content }) => {
+		const match = content.match(/(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) (\w+): (.+)/);
+		if (match) {
+			let [, timestamp, level, message] = match;
+
+			// Apply magenta style to bracketed content
+			message = message.replace(/\[([^\]]+)\]/g, (match, p1) => `${bracketStyle(`[${p1}]`)}`);
+			console.log(
+				`${chalk.gray(number)}: ${timestampStyle(`[${timestamp}]`)} ${levelStyle(level)}: ${messageStyle(message)}`
+			);
+		} else {
+			// Apply magenta style to bracketed content in lines that don't match the main pattern
+			content = content.replace(/\[([^\]]+)\]/g, (match, p1) => `${bracketStyle(`[${p1}]`)}`);
+			console.log(`${chalk.gray(number)}: ${content}`); // If the line doesn't match the expected format, print it as is with line number
+		}
+	});
+}

package/src/const.ts

@@ -0,0 +1,19 @@
+import os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const __filename = fileURLToPath(import.meta.url);
+export const __dirname = path.dirname(__filename);
+export const __cmddir = (dir: string) => path.resolve(__dirname, dir);
+export const HOME = os.homedir();
+export const OS = process.platform;
+export const SYSTEM_IGNORED_FOLDERS = [
+	"Applications",
+	"Library",
+	"Movies",
+	"Music",
+	"Pictures",
+	"Public",
+	"Users",
+] as const;
+export type IgnoredFolders = (typeof SYSTEM_IGNORED_FOLDERS)[number];

package/src/tasks/README.md

@@ -0,0 +1,33 @@
+# Tasks
+
+A set of functions designed to be strung together to create actions. An API of sorts, to power the command-line client.
+
+## What's Available
+
+-   [find](./find/README.md) - find things
+-   [replace](./replace/README.md) - replace things
+
+## Rules
+
+A set of rules for how I decide when to create a task, as opposed to creating an action.
+
+### A single responsibility
+
+It should only have a single responsibility. It shouldn't interact with the user in any sort of decision tree (no interaction with `inquirer`). Testing this through the provided examples should allow for a few inputs with some expected outputs. For example:
+
+-   I clone a project; I get a clone somewhere
+-   I search a folder; I get the location of that folder
+-   I search a project; I get the location of that project
+-   I create a directory; I get a directory somewhere
+
+In the case of actions, these are where I may ask it do several things while having it interact with the user. This also means that the return type is typically consistent; meaning it will be an array of consistent types, etc. If you have forks in your code that change the type from say a string to a number you might need to split them up into separate tasks.
+
+### Return type
+
+It should return in the form of <code>[null | Error, null | data, null | duration]</code>. Tasks returns data; actions return process error codes or voids or logs.
+
+### Other rules
+
+-   Tasks are designed to be used to compose an action; this means the output of one task will be input for another
+-   Tasks are atomic; as close to bare metal Node processes as possible
+-   Most of the arguments in the function should be required unless where sensible defaults make sense

package/src/tasks/find/README.md

@@ -0,0 +1,49 @@
+# Find a Folder
+
+Find a folder recursively.
+
+## Usage
+
+```javascript
+import { findFolder } from "@/tasks";
+
+async function main() {
+	const [, , folder] = process.argv;
+
+	try {
+		const [err, data] = await findFolder(folder);
+
+		if (err) {
+			console.error(err);
+			process.exit(1);
+		}
+
+		console.log("Folders Found:\n");
+		console.table(data);
+	} catch (error) {
+		console.error("An error occurred:", error);
+		process.exit(1);
+	}
+}
+
+main();
+```
+
+## API
+
+### `findFolder(folder: string, location?: string)`
+
+Returns an array of file paths that were found.
+
+#### folder
+
+The folder with which to search.
+
+Type: `string`
+
+#### location
+
+The directory path to where to search for the folder.
+
+Type: `string`
+Default: `os.homedir()`