feat: add core logic

Author: Silent-Watcher

.env

@@ -1,2 +1 @@
 GROQ_API_KEY=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
-HTTPS_PROXY=http://127.0.0.1:7890

package-lock.json

@@ -52,8 +52,10 @@
         "typescript": "^5.9.2"
     },
     "dependencies": {
+        "enquirer": "^2.4.1",
         "groq-sdk": "^0.32.0",
         "https-proxy-agent": "^7.0.6",
+        "keytar": "^7.9.0",
         "ora": "^8.2.0",
         "sade": "^1.8.1"
     },

package.json

@@ -0,0 +1,119 @@
+import Groq from "groq-sdk";
+import Enquirer from "enquirer";
+import keytar from "keytar";
+import { prompt as aiPrompt } from "./prompt";
+import ora from "ora";
+import { ACCOUNT_NAME, SERVICE_NAME } from "../utils/constants";
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+function isValidUrl(input: string) {
+	try {
+		new URL(input);
+		return true;
+	} catch (error) {
+		return false;
+	}
+}
+
+async function getApiKey() {
+	try {
+		const { prompt } = Enquirer;
+		// 1. Check env
+		if (process.env.GROQ_API_KEY) {
+			return process.env.GROQ_API_KEY;
+		}
+
+		// 2. Check keytar
+		const savedKey = await keytar.getPassword(SERVICE_NAME, ACCOUNT_NAME);
+		if (savedKey) {
+			return savedKey;
+		}
+
+		// 3. Prompt user
+		const { apiKey: newKey } = await prompt({
+			type: "password",
+			name: "apiKey",
+			message: "Enter your Groq API key:",
+			validate: (
+				value: string,
+			) => (value.trim() === "" ? "API key cannot be empty" : true),
+			initial: "",
+			result: (value: string) => value.trim(),
+			stdin: process.stdin,
+			stdout: process.stdout,
+		}) as { apiKey: string };
+
+		await keytar.setPassword(SERVICE_NAME, ACCOUNT_NAME, newKey);
+		console.log("\n✅ API key saved securely!");
+		return newKey;
+	} catch (error) {
+		console.error(error);
+		process.exit(1);
+	}
+}
+
+async function getHttpProxyAgent(): Promise<
+	HttpsProxyAgent<string> | undefined
+> {
+	const envProxy = process.env.HTTPS_PROXY || process.env.https_proxy;
+
+	if (envProxy) {
+		console.log("Using proxy from environment variables");
+		return new HttpsProxyAgent(envProxy);
+	}
+
+	const { setProxy } = await Enquirer.prompt<{ setProxy: boolean }>({
+		type: "confirm",
+		name: "setProxy",
+		message: "Do you want to set a proxy?",
+		initial: false,
+	});
+
+	if (!setProxy) return undefined;
+
+	const { proxyAddr } = await Enquirer.prompt<{ proxyAddr: string }>({
+		type: "input",
+		name: "proxyAddr",
+		message: "Enter proxy address (e.g., http://user:pass@localhost:7890):",
+		validate: (value) => isValidUrl(value) || "Invalid URL format",
+	});
+
+	return new HttpsProxyAgent(proxyAddr);
+}
+
+// Main function
+export async function explain(regex: string) {
+	try {
+		const apiKey = await getApiKey();
+		console.log("apiKey: ", apiKey);
+		const httpAgent = await getHttpProxyAgent();
+
+		const groq = new Groq({ apiKey, ...(httpAgent ? { httpAgent } : {}) });
+
+		const spinner = ora("loading ....").start();
+		const completion = await groq.chat.completions.create({
+			model: "openai/gpt-oss-20b",
+			messages: [
+				{ role: "system", content: "You are a regex explainer." },
+				{ role: "user", content: aiPrompt(regex) },
+			],
+		});
+
+		spinner.stop().clear();
+
+		console.log("\n📖 Explanation:\n");
+		if (
+			completion.choices && completion.choices[0] &&
+			completion.choices[0].message
+		) {
+			console.log(completion.choices[0].message.content);
+		} else {
+			console.error(
+				"Error: Completion result is undefined or malformed.",
+			);
+		}
+	} catch (error) {
+		console.error(error);
+		process.exit(1);
+	}
+}

src/ai/explain.ts

@@ -0,0 +1,24 @@
+export const prompt = (regex: string): string => (`
+**Role:** You are RegExpert, a world-class expert in regular expressions. Your sole purpose is to analyze, explain, and provide insights on regex patterns provided by the user.
+
+**Context:** The user will provide you with a regular expression pattern. Your task is to generate a comprehensive, easy-to-understand explanation.
+
+**Instructions:**
+1.  **Break Down the Pattern:** Deconstruct the regex into its core components.
+2.  **Explain Each Part:** For each significant component (anchors, character classes, quantifiers, groups, lookarounds, flags, etc.), provide a plain-English description of what it does.
+3.  **Overall Purpose:** Synthesize the components to describe the overall purpose of the regex in one or two sentences.
+4.  **Example Matches (Optional):** If possible and clear, provide 1-2 short examples of text that would match and 1 that would not.
+5.  **Tone:** Be professional, clear, and pedagogical. Avoid unnecessary jargon, but don't oversimplify for complex patterns. Assume the user has basic programming knowledge but might be new to regex.
+
+**Output Format Requirements:**
+*   **Do not use markdown** (e.g., no \`, **bold**, or headings). This output will be displayed in a terminal.
+*   Use clear spacing and colons for structure.
+*   Keep the explanation concise but thorough.
+
+**Safety & Ethics:**
+- If the pattern is empty, overly complex to the point of being potentially harmful (e.g., ReDoS vectors), or not a regex, politely decline to analyze it and explain why.
+- Do not generate or explain regex patterns for obviously malicious purposes (e.g., matching credit card numbers for extraction).
+
+**Input from user:**
+${regex}
+`);

src/ai/prompt.ts

@@ -0,0 +1,9 @@
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+export function createHttpsProxyAgent(): HttpsProxyAgent<string> | undefined {
+	const proxy = process.env?.HTTPS_PROXY as string; // replace with your proxy
+	if (proxy) {
+		return new HttpsProxyAgent(proxy);
+	}
+	return undefined;
+}

src/utils/agent.ts

@@ -0,0 +1,2 @@
+export const SERVICE_NAME = "regexplain";
+export const ACCOUNT_NAME = "user"; // could later be email/username if multi-user

src/utils/constants.ts

@@ -1,5 +1,6 @@
 import sade from "sade";
 import { description, version } from "../../package.json";
+import { explain } from "../ai/explain";
 
 export function runProgram() {
 	const program = sade("regexplain <regex>");
@@ -8,5 +9,9 @@ export function runProgram() {
 		.version(version)
 		.describe(description)
 		.action((regex: string) => {
+			explain(regex).catch((error) => {
+				console.error("Error:", error.message);
+				process.exit(1);
+			});
 		}).parse(process.argv);
 }