js-to-cli 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Million Software, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/build-cli-Bl-vRrRB.mjs

@@ -0,0 +1,422 @@
+import { Command } from "commander";
+import { basename, extname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/utils/camel-to-kebab.ts
+const camelToKebab = (input) => input.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").toLowerCase();
+//#endregion
+//#region src/load-module.ts
+const SUPPORTED_EXTENSIONS = new Set([
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".mts",
+	".cts"
+]);
+const RESERVED_COMMAND_NAMES = new Set(["help", "version"]);
+const isCallableValue = (value) => typeof value === "function";
+const isClassConstructor = (value) => /^\s*class\b/.test(Function.prototype.toString.call(value));
+const loadModule = async (modulePath) => {
+	const absolutePath = resolve(process.cwd(), modulePath);
+	const extension = extname(absolutePath).toLowerCase();
+	if (!SUPPORTED_EXTENSIONS.has(extension)) throw new Error(`unsupported module extension: "${extension}"`);
+	const importedNamespace = await import(pathToFileURL(absolutePath).href);
+	const functionExports = [];
+	for (const [exportName, exportedValue] of Object.entries(importedNamespace)) {
+		if (exportName === "__esModule") continue;
+		if (!isCallableValue(exportedValue)) continue;
+		if (isClassConstructor(exportedValue)) continue;
+		const commandName = exportName === "default" ? "default" : camelToKebab(exportName);
+		if (RESERVED_COMMAND_NAMES.has(commandName)) {
+			process.stderr.write(`js-to-cli: skipping export "${exportName}" — collides with reserved command name\n`);
+			continue;
+		}
+		functionExports.push({
+			exportName,
+			commandName,
+			fn: exportedValue
+		});
+	}
+	if (functionExports.length === 0) throw new Error(`no exported functions found in ${modulePath}`);
+	return {
+		modulePath,
+		absolutePath,
+		namespace: importedNamespace,
+		functionExports
+	};
+};
+//#endregion
+//#region src/utils/split-top-level.ts
+const splitTopLevel = (source, separator) => {
+	const segments = [];
+	let depth = 0;
+	let stringQuote = null;
+	let segmentStart = 0;
+	for (let index = 0; index < source.length; index++) {
+		const character = source[index];
+		if (stringQuote !== null) {
+			if (character === "\\") {
+				index++;
+				continue;
+			}
+			if (character === stringQuote) stringQuote = null;
+			continue;
+		}
+		if (character === "\"" || character === "'" || character === "`") {
+			stringQuote = character;
+			continue;
+		}
+		if (character === "(" || character === "[" || character === "{") {
+			depth++;
+			continue;
+		}
+		if (character === ")" || character === "]" || character === "}") {
+			depth--;
+			continue;
+		}
+		if (depth === 0 && source.startsWith(separator, index)) {
+			segments.push(source.slice(segmentStart, index));
+			segmentStart = index + separator.length;
+			index += separator.length - 1;
+		}
+	}
+	segments.push(source.slice(segmentStart));
+	return segments;
+};
+//#endregion
+//#region src/utils/strip-comments.ts
+const stripComments = (source) => {
+	let output = "";
+	let stringQuote = null;
+	let index = 0;
+	while (index < source.length) {
+		const character = source[index];
+		if (stringQuote !== null) {
+			output += character;
+			if (character === "\\" && index + 1 < source.length) {
+				output += source[index + 1];
+				index += 2;
+				continue;
+			}
+			if (character === stringQuote) stringQuote = null;
+			index++;
+			continue;
+		}
+		if (character === "\"" || character === "'" || character === "`") {
+			stringQuote = character;
+			output += character;
+			index++;
+			continue;
+		}
+		if (character === "/" && source[index + 1] === "/") {
+			const newlineIndex = source.indexOf("\n", index + 2);
+			if (newlineIndex === -1) index = source.length;
+			else index = newlineIndex;
+			continue;
+		}
+		if (character === "/" && source[index + 1] === "*") {
+			const closingIndex = source.indexOf("*/", index + 2);
+			if (closingIndex === -1) index = source.length;
+			else index = closingIndex + 2;
+			continue;
+		}
+		output += character;
+		index++;
+	}
+	return output;
+};
+//#endregion
+//#region src/parse-function.ts
+const IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/;
+const findMatchingClose = (source, openIndex) => {
+	const openChar = source[openIndex];
+	const closeChar = openChar === "(" ? ")" : openChar === "{" ? "}" : "]";
+	let depth = 0;
+	let stringQuote = null;
+	for (let index = openIndex; index < source.length; index++) {
+		const character = source[index];
+		if (stringQuote !== null) {
+			if (character === "\\") {
+				index++;
+				continue;
+			}
+			if (character === stringQuote) stringQuote = null;
+			continue;
+		}
+		if (character === "\"" || character === "'" || character === "`") {
+			stringQuote = character;
+			continue;
+		}
+		if (character === openChar) depth++;
+		else if (character === closeChar) {
+			depth--;
+			if (depth === 0) return index;
+		}
+	}
+	return -1;
+};
+const findTopLevelDefaultEquals = (source) => {
+	let depth = 0;
+	let stringQuote = null;
+	for (let index = 0; index < source.length; index++) {
+		const character = source[index];
+		if (stringQuote !== null) {
+			if (character === "\\") {
+				index++;
+				continue;
+			}
+			if (character === stringQuote) stringQuote = null;
+			continue;
+		}
+		if (character === "\"" || character === "'" || character === "`") {
+			stringQuote = character;
+			continue;
+		}
+		if (character === "(" || character === "[" || character === "{") {
+			depth++;
+			continue;
+		}
+		if (character === ")" || character === "]" || character === "}") {
+			depth--;
+			continue;
+		}
+		if (depth === 0 && character === "=") {
+			const nextCharacter = source[index + 1];
+			const previousCharacter = source[index - 1];
+			if (nextCharacter === "=" || nextCharacter === ">") continue;
+			if (previousCharacter === "=" || previousCharacter === "<" || previousCharacter === ">" || previousCharacter === "!") continue;
+			return index;
+		}
+	}
+	return -1;
+};
+const splitNameAndDefault = (source) => {
+	const equalsIndex = findTopLevelDefaultEquals(source);
+	if (equalsIndex === -1) return {
+		beforeEquals: source.trim(),
+		defaultLiteral: null
+	};
+	return {
+		beforeEquals: source.slice(0, equalsIndex).trim(),
+		defaultLiteral: source.slice(equalsIndex + 1).trim()
+	};
+};
+const parseOptionFields = (innerSource) => {
+	const fields = [];
+	for (const rawSlice of splitTopLevel(innerSource, ",")) {
+		const slice = rawSlice.trim();
+		if (slice === "") continue;
+		const { beforeEquals, defaultLiteral } = splitNameAndDefault(slice);
+		let propertyName = beforeEquals;
+		const colonIndex = beforeEquals.indexOf(":");
+		if (colonIndex !== -1) propertyName = beforeEquals.slice(0, colonIndex).trim();
+		if (!IDENTIFIER_PATTERN.test(propertyName)) throw new Error(`unsupported destructured option field: "${slice}"`);
+		fields.push({
+			name: propertyName,
+			hasDefault: defaultLiteral !== null,
+			defaultLiteral
+		});
+	}
+	return fields;
+};
+const parseParameter = (rawSlice, exportedName) => {
+	const slice = rawSlice.trim();
+	if (slice.startsWith("...")) {
+		const restName = slice.slice(3).trim();
+		if (!IDENTIFIER_PATTERN.test(restName)) throw new Error(`unsupported rest parameter "${slice}" in "${exportedName}"`);
+		return {
+			name: restName,
+			kind: "rest",
+			hasDefault: false,
+			defaultLiteral: null,
+			optionFields: null
+		};
+	}
+	if (slice.startsWith("{")) {
+		const closingBraceIndex = findMatchingClose(slice, 0);
+		if (closingBraceIndex === -1) throw new Error(`could not parse destructured options parameter in "${exportedName}"`);
+		const innerSource = slice.slice(1, closingBraceIndex);
+		const afterBrace = slice.slice(closingBraceIndex + 1).trim();
+		const hasDefault = afterBrace.startsWith("=");
+		return {
+			name: "options",
+			kind: "options",
+			hasDefault,
+			defaultLiteral: hasDefault ? afterBrace.slice(1).trim() : null,
+			optionFields: parseOptionFields(innerSource)
+		};
+	}
+	if (slice.startsWith("[")) throw new Error(`unsupported parameter pattern "${slice}" in "${exportedName}" (array destructuring not supported)`);
+	const { beforeEquals, defaultLiteral } = splitNameAndDefault(slice);
+	if (!IDENTIFIER_PATTERN.test(beforeEquals)) throw new Error(`unsupported parameter pattern "${slice}" in "${exportedName}"`);
+	return {
+		name: beforeEquals,
+		kind: "primitive",
+		hasDefault: defaultLiteral !== null,
+		defaultLiteral,
+		optionFields: null
+	};
+};
+const extractParameterListSource = (source) => {
+	let cursor = 0;
+	while (cursor < source.length && /\s/.test(source[cursor])) cursor++;
+	if (source.startsWith("function", cursor)) {
+		cursor += 8;
+		while (cursor < source.length && source[cursor] !== "(") cursor++;
+	}
+	while (cursor < source.length && /\s/.test(source[cursor])) cursor++;
+	if (source[cursor] !== "(") {
+		const arrowIndex = source.indexOf("=>", cursor);
+		if (arrowIndex === -1) throw new Error(`could not parse function source: ${source}`);
+		return source.slice(cursor, arrowIndex).trim();
+	}
+	const closingIndex = findMatchingClose(source, cursor);
+	if (closingIndex === -1) throw new Error(`could not find matching paren in function source: ${source}`);
+	return source.slice(cursor + 1, closingIndex);
+};
+const parseFunctionSignature = (fn, exportedName) => {
+	const strippedSource = stripComments(fn.toString()).trim();
+	const isAsync = /^async\b/.test(strippedSource);
+	const parameterListSource = extractParameterListSource(isAsync ? strippedSource.slice(5).trimStart() : strippedSource);
+	if (parameterListSource.trim() === "") return {
+		name: exportedName,
+		isAsync,
+		parameters: []
+	};
+	const parameters = splitTopLevel(parameterListSource, ",").map((slice) => slice.trim()).filter((slice) => slice !== "").map((slice) => parseParameter(slice, exportedName));
+	for (let index = 0; index < parameters.length; index++) {
+		const parameter = parameters[index];
+		const isLast = index === parameters.length - 1;
+		if ((parameter.kind === "options" || parameter.kind === "rest") && !isLast) throw new Error(`${parameter.kind} parameter "${parameter.name}" must be last in "${exportedName}"`);
+	}
+	return {
+		name: exportedName,
+		isAsync,
+		parameters
+	};
+};
+//#endregion
+//#region src/utils/format-result.ts
+const formatResult = (value) => {
+	if (value === void 0) return null;
+	if (value === null) return "null";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	return JSON.stringify(value, null, 2);
+};
+//#endregion
+//#region src/utils/infer-option-type.ts
+const NUMBER_LITERAL_PATTERN = /^-?\d+(?:\.\d+)?$/;
+const inferOptionType = (defaultLiteral) => {
+	if (defaultLiteral === null) return { commanderType: "required-string" };
+	const trimmedLiteral = defaultLiteral.trim();
+	if (trimmedLiteral === "false") return { commanderType: "boolean" };
+	if (trimmedLiteral === "true") return { commanderType: "negated-boolean" };
+	if (NUMBER_LITERAL_PATTERN.test(trimmedLiteral)) return {
+		commanderType: "number",
+		defaultValue: parseFloat(trimmedLiteral)
+	};
+	if (trimmedLiteral.startsWith("[")) return { commanderType: "array" };
+	const firstCharacter = trimmedLiteral[0];
+	if (firstCharacter === "\"" || firstCharacter === "'" || firstCharacter === "`") return {
+		commanderType: "string",
+		defaultValue: trimmedLiteral[trimmedLiteral.length - 1] === firstCharacter ? trimmedLiteral.slice(1, -1) : trimmedLiteral.slice(1)
+	};
+	return {
+		commanderType: "string",
+		defaultValue: void 0
+	};
+};
+//#endregion
+//#region src/build-cli.ts
+const collectArrayValue = (value, previous) => [...previous, value];
+const applyOptionField = (subcommand, field) => {
+	const kebabName = camelToKebab(field.name);
+	const inferred = inferOptionType(field.defaultLiteral);
+	switch (inferred.commanderType) {
+		case "boolean":
+			subcommand.option(`--${kebabName}`, "");
+			return;
+		case "negated-boolean":
+			subcommand.option(`--no-${kebabName}`, "");
+			return;
+		case "number":
+			subcommand.option(`--${kebabName} <number>`, "", parseFloat, inferred.defaultValue);
+			return;
+		case "array":
+			subcommand.option(`--${kebabName} <value>`, "", collectArrayValue, []);
+			return;
+		case "required-string":
+			subcommand.requiredOption(`--${kebabName} <value>`, "");
+			return;
+		case "string":
+			if (inferred.defaultValue !== void 0) {
+				subcommand.option(`--${kebabName} <value>`, "", inferred.defaultValue);
+				return;
+			}
+			subcommand.option(`--${kebabName} <value>`, "");
+			return;
+	}
+};
+const applyParameter = (subcommand, parameter) => {
+	if (parameter.kind === "primitive") {
+		const argumentSpec = parameter.hasDefault ? `[${camelToKebab(parameter.name)}]` : `<${camelToKebab(parameter.name)}>`;
+		subcommand.argument(argumentSpec);
+		return;
+	}
+	if (parameter.kind === "rest") {
+		subcommand.argument(`[${camelToKebab(parameter.name)}...]`);
+		return;
+	}
+	for (const field of parameter.optionFields ?? []) applyOptionField(subcommand, field);
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null;
+const assembleCallArgs = (signature, commanderArgs) => {
+	const positionalParameters = signature.parameters.filter((parameter) => parameter.kind === "primitive" || parameter.kind === "rest");
+	const positionalValues = commanderArgs.slice(0, positionalParameters.length);
+	const optionsSlot = commanderArgs[positionalParameters.length];
+	const rawOptions = isPlainObject(optionsSlot) ? optionsSlot : {};
+	const callArgs = [];
+	let positionalCursor = 0;
+	for (const parameter of signature.parameters) {
+		if (parameter.kind === "primitive") {
+			callArgs.push(positionalValues[positionalCursor]);
+			positionalCursor++;
+			continue;
+		}
+		if (parameter.kind === "rest") {
+			const restValue = positionalValues[positionalCursor];
+			positionalCursor++;
+			if (Array.isArray(restValue)) callArgs.push(...restValue);
+			else if (restValue !== void 0) callArgs.push(restValue);
+			continue;
+		}
+		const optionsObject = {};
+		for (const field of parameter.optionFields ?? []) if (field.name in rawOptions) optionsObject[field.name] = rawOptions[field.name];
+		callArgs.push(optionsObject);
+	}
+	return callArgs;
+};
+const buildActionHandler = (fn, signature) => async (...commanderArgs) => {
+	try {
+		const formatted = formatResult(await fn(...assembleCallArgs(signature, commanderArgs)));
+		if (formatted !== null) process.stdout.write(formatted + "\n");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		process.stderr.write(message + "\n");
+		process.exit(1);
+	}
+};
+const convertJsToCli = async (modulePath, options = {}) => {
+	const loaded = await loadModule(modulePath);
+	const program = new Command().name(options.programName ?? basename(loaded.absolutePath)).description(`CLI generated from ${loaded.modulePath}`);
+	for (const functionExport of loaded.functionExports) {
+		const signature = parseFunctionSignature(functionExport.fn, functionExport.exportName);
+		const subcommand = program.command(functionExport.commandName);
+		for (const parameter of signature.parameters) applyParameter(subcommand, parameter);
+		subcommand.action(buildActionHandler(functionExport.fn, signature));
+	}
+	return program;
+};
+//#endregion
+export { loadModule as i, inferOptionType as n, parseFunctionSignature as r, convertJsToCli as t };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { t as convertJsToCli } from "./build-cli-Bl-vRrRB.mjs";
+//#region src/cli.ts
+const HELP_TEXT = "Usage: js-to-cli <module-path> <subcommand> [args...]\n\nLoads the given JS/TS module and exposes its exported functions as subcommands.\nEach function becomes a subcommand. Primitive parameters become positional args;\na trailing destructured options object becomes --flags.\n";
+const main = async () => {
+	const argv = process.argv.slice(2);
+	if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+		process.stdout.write(HELP_TEXT);
+		process.exit(0);
+	}
+	const modulePath = argv[0];
+	const remainingArgv = argv.slice(1);
+	try {
+		await (await convertJsToCli(modulePath)).parseAsync(remainingArgv, { from: "user" });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		process.stderr.write(`js-to-cli: ${message}\n`);
+		process.exit(1);
+	}
+};
+main();
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+
+//#region src/build-cli.d.ts
+interface BuildCliOptions {
+  programName?: string;
+}
+declare const convertJsToCli: (modulePath: string, options?: BuildCliOptions) => Promise<Command>;
+//#endregion
+//#region src/load-module.d.ts
+interface LoadedFunctionExport {
+  exportName: string;
+  commandName: string;
+  fn: (...args: unknown[]) => unknown;
+}
+interface LoadedModule {
+  modulePath: string;
+  absolutePath: string;
+  namespace: Record<string, unknown>;
+  functionExports: LoadedFunctionExport[];
+}
+declare const loadModule: (modulePath: string) => Promise<LoadedModule>;
+//#endregion
+//#region src/parse-function.d.ts
+interface ParsedOptionField {
+  name: string;
+  hasDefault: boolean;
+  defaultLiteral: string | null;
+}
+interface ParsedParameter {
+  name: string;
+  kind: "primitive" | "options" | "rest";
+  hasDefault: boolean;
+  defaultLiteral: string | null;
+  optionFields: ParsedOptionField[] | null;
+}
+interface ParsedFunctionSignature {
+  name: string;
+  isAsync: boolean;
+  parameters: ParsedParameter[];
+}
+declare const parseFunctionSignature: (fn: Function, exportedName: string) => ParsedFunctionSignature;
+//#endregion
+//#region src/utils/infer-option-type.d.ts
+interface BooleanOption {
+  commanderType: "boolean";
+}
+interface NegatedBooleanOption {
+  commanderType: "negated-boolean";
+}
+interface NumberOption {
+  commanderType: "number";
+  defaultValue: number;
+}
+interface ArrayOption {
+  commanderType: "array";
+}
+interface StringOption {
+  commanderType: "string";
+  defaultValue: string | undefined;
+}
+interface RequiredStringOption {
+  commanderType: "required-string";
+}
+type InferredOptionType = BooleanOption | NegatedBooleanOption | NumberOption | ArrayOption | StringOption | RequiredStringOption;
+declare const inferOptionType: (defaultLiteral: string | null) => InferredOptionType;
+//#endregion
+export { type BuildCliOptions, type LoadedFunctionExport, type LoadedModule, type ParsedFunctionSignature, type ParsedOptionField, type ParsedParameter, convertJsToCli, inferOptionType, loadModule, parseFunctionSignature };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { i as loadModule, n as inferOptionType, r as parseFunctionSignature, t as convertJsToCli } from "./build-cli-Bl-vRrRB.mjs";
+export { convertJsToCli, inferOptionType, loadModule, parseFunctionSignature };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "js-to-cli",
+  "version": "0.0.2",
+  "description": "Turn any Node.js module into a Commander CLI. Inverse of cli-to-js.",
+  "keywords": [
+    "cli",
+    "commander",
+    "module",
+    "node",
+    "runtime",
+    "wrapper"
+  ],
+  "homepage": "https://github.com/aidenybai/cli-to-js",
+  "bugs": {
+    "url": "https://github.com/aidenybai/cli-to-js/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Aiden Bai",
+    "email": "aiden@million.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidenybai/cli-to-js.git"
+  },
+  "bin": {
+    "js-to-cli": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test run",
+    "typecheck": "tsc --noEmit"
+  }
+}