readmeg 1.0.0

package/README.md

@@ -0,0 +1,217 @@
+<a name="readme-top"></a>
+
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![MIT License][license-shield]][license-url]
+[![LinkedIn][linkedin-shield]][linkedin-url]
+
+<br />
+<div align="center">
+  <a href="https://github.com/your_username/readmeg">
+    <img src="https://images.unsplash.com/photo-1618401471353-b98aedd07871?q=80&w=120&auto=format&fit=crop" alt="Logo" width="80" height="80">
+  </a>
+
+  <h3 align="center">readmeg</h3>
+
+  <p align="center">
+    An AI-powered CLI tool to instantly generate beautiful, comprehensive, and professional README.md files for your repositories.
+    <br />
+    <a href="https://github.com/your_username/readmeg"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/your_username/readmeg">View Demo</a>
+    ·
+    <a href="https://github.com/your_username/readmeg/issues">Report Bug</a>
+    ·
+    <a href="https://github.com/your_username/readmeg/issues">Request Feature</a>
+  </p>
+</div>
+
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#built-with">Built With</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#roadmap">Roadmap</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+    <li><a href="#acknowledgments">Acknowledgments</a></li>
+  </ol>
+</details>
+
+## About The Project
+
+[![readmeg Screen Shot][product-screenshot]](https://github.com/your_username/readmeg)
+
+Writing a high-quality README is often the most tedious part of finishing a project. `readmeg` is an interactive Command Line Interface (CLI) tool designed to automate this process. By leveraging Google's advanced Gemini generative AI models, `readmeg` analyzes your project structure, prompts you for key details, and outputs a perfectly formatted, professional `README.md` file in seconds.
+
+Here's why you should use `readmeg`:
+* **Save Time**: Stop writing boilerplate markdown sections from scratch.
+* **Interactive Prompts**: Simple, step-by-step terminal questions guide you through defining your project's scope.
+* **AI-Powered**: Generates intelligent descriptions, installation steps, and usage guides based on your actual project configuration.
+* **Standardized Layouts**: Outputs clean markdown following industry-standard templates.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+### Built With
+
+This project is built using modern Node.js and TypeScript, leveraging powerful CLI and AI libraries:
+
+* [![Node.js][Node.js]][Node-url]
+* [![TypeScript][TypeScript]][TypeScript-url]
+* [![Google Gemini][Gemini]][Gemini-url]
+* [![Commander.js][Commander]][Commander-url]
+* [![Inquirer.js][Inquirer]][Inquirer-url]
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Getting Started
+
+To get a local copy up and running, follow these simple steps.
+
+### Prerequisites
+
+Ensure you have Node.js installed (version 18.0.0 or higher is recommended).
+
+* npm
+  ```sh
+  npm install npm@latest -g
+  ```
+
+### Installation
+
+1. Get a free Gemini API Key from [Google AI Studio](https://aistudio.google.com/).
+2. Clone the repository:
+   ```sh
+   git clone https://github.com/your_username/readmeg.git
+   ```
+3. Install NPM packages:
+   ```sh
+   npm install
+   ```
+4. Create a `.env` file in the root directory and add your Gemini API key:
+   ```env
+   GEMINI_API_KEY=your_actual_api_key_here
+   ```
+5. Build the TypeScript files (if modifying source files):
+   ```sh
+   npm run build
+   ```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Usage
+
+You can run `readmeg` directly using Node.js. The CLI will guide you through an interactive prompt session to gather information about your repository before generating the markdown file.
+
+### Running the CLI
+
+To start the interactive generation process:
+```sh
+node ./bin/readmeg.js
+```
+
+To view available CLI commands and options:
+```sh
+npm start
+```
+
+### Example Interactive Flow
+
+1. **Project Name**: Enter the name of your project (defaults to your directory name).
+2. **Description**: Provide a brief summary of what your application does.
+3. **Technologies**: Select or enter the main frameworks and languages used.
+4. **License**: Choose your project's license (e.g., MIT, Apache 2.0, GPL v3).
+5. **Output**: The tool will call the Gemini API and write a polished `README.md` directly to your root directory.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Roadmap
+
+- [ ] Add support for automatic codebase parsing (reading `package.json`, `requirements.txt`, etc.)
+- [ ] Provide multiple pre-designed README templates (Minimal, Detailed, API-focused)
+- [ ] Add support for alternative LLM providers (OpenAI, Anthropic)
+- [ ] Implement a dry-run mode to preview markdown in the terminal before writing to disk
+
+See the [open issues](https://github.com/your_username/readmeg/issues) for a full list of proposed features and known issues.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Contributing
+
+Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
+Don't forget to give the project a star! Thanks again!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Contact
+
+Your Name - [@your_twitter](https://twitter.com/your_twitter) - email@example.com
+
+Project Link: [https://github.com/your_username/readmeg](https://github.com/your_username/readmeg)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Acknowledgments
+
+* [Google Gen AI SDK](https://github.com/google/generative-ai-js)
+* [Commander.js](https://github.com/tj/commander.js/)
+* [Inquirer.js](https://github.com/SBoudrias/Inquirer.js/)
+* [Shields.io](https://shields.io)
+* [Best-README-Template](https://github.com/othneildrew/Best-README-Template)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+[contributors-shield]: https://img.shields.io/github/contributors/your_username/readmeg.svg?style=for-the-badge
+[contributors-url]: https://github.com/your_username/readmeg/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/your_username/readmeg.svg?style=for-the-badge
+[forks-url]: https://github.com/your_username/readmeg/network/members
+[stars-shield]: https://img.shields.io/github/stars/your_username/readmeg.svg?style=for-the-badge
+[stars-url]: https://github.com/your_username/readmeg/stargazers
+[issues-shield]: https://img.shields.io/github/issues/your_username/readmeg.svg?style=for-the-badge
+[issues-url]: https://github.com/your_username/readmeg/issues
+[license-shield]: https://img.shields.io/github/license/your_username/readmeg.svg?style=for-the-badge
+[license-url]: https://github.com/your_username/readmeg/blob/master/LICENSE.txt
+[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
+[linkedin-url]: https://linkedin.com/in/your_username
+[product-screenshot]: https://images.unsplash.com/photo-1618401471353-b98aedd07871?q=80&w=600&auto=format&fit=crop
+
+[Node.js]: https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white
+[Node-url]: https://nodejs.org/
+[TypeScript]: https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white
+[TypeScript-url]: https://www.typescriptlang.org/
+[Gemini]: https://img.shields.io/badge/Google%20Gemini-8E75C2?style=for-the-badge&logo=googlegemini&logoColor=white
+[Gemini-url]: https://deepmind.google/technologies/gemini/
+[Commander]: https://img.shields.io/badge/Commander.js-black?style=for-the-badge&logo=commander
+[Commander-url]: https://github.com/tj/commander.js/
+[Inquirer]: https://img.shields.io/badge/Inquirer.js-red?style=for-the-badge&logo=npm
+[Inquirer-url]: https://github.com/SBoudrias/Inquirer.js/

package/bin/readmeg.js

@@ -0,0 +1,679 @@
+#!/usr/bin/env node
+
+/**
+ * ReadMe-Gen CLI
+ * Zero-config terminal execution tool powered by Gemini with interactive menus.
+ */
+
+import fs from "fs";
+import path from "path";
+import { Command } from "commander";
+import inquirer from "inquirer";
+import { GoogleGenAI } from "@google/genai";
+import dotenv from "dotenv";
+
+// Load local .env configurations if present
+dotenv.config();
+
+const program = new Command();
+
+program
+  .name("readmeg")
+  .description("Automatically generate comprehensive production-grade README.md files for your local directory repositories using Gemini.")
+  .version("1.0.0")
+  .option("-k, --api-key <key>", "Provide your Gemini API key manually")
+  .option("-o, --output <file>", "Define custom output file path", "README.md")
+  .option("-n, --non-interactive", "Run directly without interactive menu loop", false)
+  .parse(process.argv);
+
+const options = program.opts();
+
+const IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  "__pycache__",
+  ".venv",
+  "venv",
+  "env",
+  ".aistudio",
+  "assets",
+  ".next",
+  ".svelte-kit",
+  ".nuxt",
+  ".cache",
+  "tmp",
+  ".DS_Store"
+]);
+
+const MANIFEST_NAMES = new Set([
+  "package.json",
+  "requirements.txt",
+  "go.mod",
+  "Cargo.toml",
+  "docker-compose.yml",
+  "pyproject.toml",
+  "Gemfile",
+  "pom.xml",
+  "build.gradle",
+  "composer.json",
+  "setup.py"
+]);
+
+const SNIPPET_NAMES = new Set([
+  "server.ts",
+  "main.py",
+  "main.go",
+  "main.rs",
+  "App.tsx",
+  "main.tsx",
+  "index.html",
+  "index.js",
+  "index.ts",
+  "App.js"
+]);
+
+// 1. Traverse directory to form visual path layout
+function buildTreeString(currentPath, prefix = "") {
+  try {
+    const stats = fs.statSync(currentPath);
+    if (!stats.isDirectory()) return "";
+
+    const items = fs.readdirSync(currentPath)
+      .filter((item) => !IGNORED_DIRS.has(item) && !item.startsWith("."))
+      .sort((a, b) => {
+        const aPath = path.join(currentPath, a);
+        const bPath = path.join(currentPath, b);
+        let aIsDir = false, bIsDir = false;
+        try {
+          aIsDir = fs.statSync(aPath).isDirectory();
+          bIsDir = fs.statSync(bPath).isDirectory();
+        } catch (_) {}
+        if (aIsDir && !bIsDir) return -1;
+        if (!aIsDir && bIsDir) return 1;
+        return a.localeCompare(b);
+      });
+
+    let tree = "";
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      const itemPath = path.join(currentPath, item);
+      const isLast = i === items.length - 1;
+      const connector = isLast ? "└── " : "├── ";
+
+      let isDir = false;
+      try {
+        isDir = fs.statSync(itemPath).isDirectory();
+      } catch (_) {}
+
+      tree += `${prefix}${connector}${item}${isDir ? "/" : ""}\n`;
+
+      if (isDir) {
+        const nextPrefix = prefix + (isLast ? "    " : "│   ");
+        tree += buildTreeString(itemPath, nextPrefix);
+      }
+    }
+    return tree;
+  } catch (err) {
+    console.warn(`\x1b[33m[Warning] Failed to generate tree for directory '${currentPath}': ${err.message}\x1b[0m`);
+    return "";
+  }
+}
+
+// 2. Traverses and reads file information
+function scanDirectoryFiles(currentPath, relativePath, result) {
+  try {
+    const items = fs.readdirSync(currentPath);
+    for (const item of items) {
+      if (IGNORED_DIRS.has(item) || item.startsWith(".")) continue;
+
+      const itemPath = path.join(currentPath, item);
+      const itemRelPath = relativePath ? path.join(relativePath, item) : item;
+      const stats = fs.statSync(itemPath);
+
+      if (stats.isDirectory()) {
+        scanDirectoryFiles(itemPath, itemRelPath, result);
+      } else if (stats.isFile()) {
+        const ext = path.extname(item).toLowerCase();
+        
+        if (ext === ".ts" || ext === ".tsx") result.languages.add("TypeScript");
+        else if (ext === ".js" || ext === ".jsx") result.languages.add("JavaScript");
+        else if (ext === ".py") result.languages.add("Python");
+        else if (ext === ".go") result.languages.add("Go");
+        else if (ext === ".rs") result.languages.add("Rust");
+
+        if (MANIFEST_NAMES.has(item)) {
+          const content = fs.readFileSync(itemPath, "utf-8").substring(0, 10000);
+          result.manifests.push({ relativePath: itemRelPath, name: item, content });
+        } else if (SNIPPET_NAMES.has(item) && stats.size < 12000) {
+          const content = fs.readFileSync(itemPath, "utf-8");
+          result.snippets.push({ relativePath: itemRelPath, name: item, content });
+        } else if (ext === ".md" && item.toLowerCase() !== "readme.md" && stats.size < 15000) {
+          const content = fs.readFileSync(itemPath, "utf-8");
+          result.markdowns.push({ relativePath: itemRelPath, name: item, content });
+        }
+      }
+    }
+  } catch (err) {
+    console.error(`\x1b[31m[Error] Failed to read directory '${currentPath}': ${err.message}\x1b[0m`);
+  }
+}
+
+const showBanner = () => {
+  console.log(`\x1b[36m
+  _____                 _ __  __               
+ |  __ \\               | |  \\/  |              
+ | |__) |___  __ _  __| | |\\/| |/ _ \\/ _\` |    
+ |  _  // _ \\/ _\` |/ _\` | |  | |  __/ (_| |    
+ | | \\ \\  __/ (_| | (_| | |  | | \\___|\\__, |    
+ |_|  \\_\\___|\\__,_|\\__,_|_|  |_|      |___/     
+\x1b[0m`);
+  console.log(` \x1b[45m\x1b[37m ReadMeg — Interactive CLI v1.0.0 \x1b[0m Powered by Google Gemini AI\n`);
+};
+
+async function main() {
+  if (options.nonInteractive) {
+    // Standard direct execution if specified --non-interactive
+    await runDirectScanAndGen();
+    return;
+  }
+
+  showBanner();
+
+  // 1. Core API KEY Resolution
+  let apiKey = options.apiKey || process.env.GEMINI_API_KEY;
+  if (!apiKey || !apiKey.trim()) {
+    console.log("\x1b[33mGemini API Key is not configured yet or is empty.\x1b[0m");
+    const keyAnswer = await inquirer.prompt([
+      {
+        type: "password",
+        name: "key",
+        message: "Please enter your Google Gemini API Key:",
+        mask: "*"
+      }
+    ]);
+    apiKey = keyAnswer.key;
+
+    if (!apiKey || !apiKey.trim()) {
+      console.error("\x1b[31mERROR: GEMINI_API_KEY is required to generate README files.\x1b[0m");
+      process.exit(1);
+    }
+  }
+  apiKey = apiKey.trim();
+
+  // 2. Active directory scanner
+  console.log("\n\x1b[36mScanning repository layers...\x1b[0m");
+  const activeCwd = process.cwd();
+  const treeBody = buildTreeString(activeCwd);
+  const scanResult = {
+    manifests: [],
+    snippets: [],
+    markdowns: [],
+    languages: new Set()
+  };
+
+  scanDirectoryFiles(activeCwd, "", scanResult);
+
+  let projectType = "Unknown Project Core";
+  if (scanResult.manifests.some(m => m.name === "package.json")) projectType = "Node.js (JavaScript/TypeScript)";
+  else if (scanResult.manifests.some(m => m.name === "requirements.txt" || m.name === "pyproject.toml")) projectType = "Python";
+  else if (scanResult.manifests.some(m => m.name === "go.mod")) projectType = "Go (Golang)";
+  else if (scanResult.manifests.some(m => m.name === "Cargo.toml")) projectType = "Rust";
+
+  console.log(`\x1b[32mSuccessfully mapped codebase structure as:\x1b[0m ${projectType}`);
+  console.log(`Tree Depth loaded. Captured manifests: ${scanResult.manifests.map(m => m.name).join(", ") || "None"}\n`);
+
+  // CLI Selection Loop states
+  let selectedManifestPaths = scanResult.manifests.map(m => m.relativePath);
+  let selectedSnippetPaths = scanResult.snippets.map(s => s.relativePath);
+  let selectedMarkdownPaths = scanResult.markdowns.map(md => md.relativePath);
+  let addGuidelines = [];
+  let customInstructions = "";
+  let chosenModel = "gemini-3.5-flash";
+  let generatedContent = "";
+
+  // Interactive Menu Loop
+  while (true) {
+    const listChoices = [
+      { name: "View scanned File Tree diagram", value: "view_tree" },
+      { name: "Select configuration manifest files to analyze", value: "select_manifests" },
+      { name: "Select code snippet guides to inspect", value: "select_snippets" },
+      { name: "Select reference markdown files to inspect", value: "select_markdowns" },
+      { name: "Select supplementary layout headings", value: "select_headings" },
+      { name: "Enter custom text highlight instructions", value: "custom_notes" },
+      { name: "GENERATE README DOCUMENT RIGHT NOW", value: "trigger_gen" },
+      { name: "Exit ReadMeg", value: "exit_cli" }
+    ];
+
+    const promptMenu = await inquirer.prompt([
+      {
+        type: "select",
+        name: "action",
+        message: "ReadMeg Main Menu — Choose a configuration command:",
+        choices: listChoices,
+        loop: false
+      }
+    ]);
+
+    const activeChoice = promptMenu.action;
+
+    if (activeChoice === "exit_cli") {
+      console.log("Thanks for using ReadMeg. Keep coding!");
+      process.exit(0);
+    }
+
+    if (activeChoice === "view_tree") {
+      console.log("\n\x1b[36m--- Repository Tree Diagram ---\x1b[0m");
+      console.log(treeBody || "(Directory is empty)");
+      console.log("\x1b[36m-------------------------------\x1b[0m\n");
+      continue;
+    }
+
+    if (activeChoice === "select_manifests") {
+      if (scanResult.manifests.length === 0) {
+        console.log("\x1b[33mWarning: No manifest files (package.json, requirements.txt, setup.py, Cargo.toml etc) found to check.\x1b[0m\n");
+        continue;
+      }
+      const manifestAsk = await inquirer.prompt([
+        {
+          type: "checkbox",
+          name: "paths",
+          message: "Check config files to feed into Gemini parameters:",
+          choices: scanResult.manifests.map(m => ({ name: m.relativePath, value: m.relativePath, checked: selectedManifestPaths.includes(m.relativePath) })),
+          loop: false
+        }
+      ]);
+      selectedManifestPaths = manifestAsk.paths;
+      console.log(`\x1b[32m✔ Manifest files updated. Total: ${selectedManifestPaths.length}\x1b[0m\n`);
+      continue;
+    }
+
+    if (activeChoice === "select_snippets") {
+      if (scanResult.snippets.length === 0) {
+        console.log("\x1b[33mWarning: No target snippet sources found. Copy key files to analyze.\x1b[0m\n");
+        continue;
+      }
+      const snippetAsk = await inquirer.prompt([
+        {
+          type: "checkbox",
+          name: "paths",
+          message: "Check code files to inject for code syntax style scanning:",
+          choices: scanResult.snippets.map(s => ({ name: s.relativePath, value: s.relativePath, checked: selectedSnippetPaths.includes(s.relativePath) })),
+          loop: false
+        }
+      ]);
+      selectedSnippetPaths = snippetAsk.paths;
+      console.log(`\x1b[32m✔ Key code snippets updated. Total: ${selectedSnippetPaths.length}\x1b[0m\n`);
+      continue;
+    }
+
+    if (activeChoice === "select_markdowns") {
+      if (scanResult.markdowns.length === 0) {
+        console.log("\x1b[33mWarning: No reference markdown files (.md) found to check. Add some customized docs first!\x1b[0m\n");
+        continue;
+      }
+      const markdownAsk = await inquirer.prompt([
+        {
+          type: "checkbox",
+          name: "paths",
+          message: "Check markdown documents to inject as key architectural sources:",
+          choices: scanResult.markdowns.map(md => ({ name: md.relativePath, value: md.relativePath, checked: selectedMarkdownPaths.includes(md.relativePath) })),
+          loop: false
+        }
+      ]);
+      selectedMarkdownPaths = markdownAsk.paths;
+      console.log(`\x1b[32m✔ Reference markdown files updated. Total: ${selectedMarkdownPaths.length}\x1b[0m\n`);
+      continue;
+    }
+
+    if (activeChoice === "select_headings") {
+      const headingAsk = await inquirer.prompt([
+        {
+          type: "checkbox",
+          name: "sections",
+          message: "Verify additional custom layout sections to mandate:",
+          choices: [
+            { name: "Contribution Guidelines", checked: addGuidelines.includes("Contribution Guidelines") },
+            { name: "Docker & Kubernetes Deployment Guidelines", checked: addGuidelines.includes("Docker & Kubernetes Deployment Guidelines") },
+            { name: "Architecture Layout Details", checked: addGuidelines.includes("Architecture Layout Details") },
+            { name: "Security Warnings", checked: addGuidelines.includes("Security Warnings") },
+            { name: "Testing suite & Benchmarks", checked: addGuidelines.includes("Testing suite & Benchmarks") }
+          ],
+          loop: false
+        }
+      ]);
+      addGuidelines = headingAsk.sections;
+      console.log(`\x1b[32m✔ Supplementary headings updated. Total: ${addGuidelines.length}\x1b[0m\n`);
+      continue;
+    }
+
+    if (activeChoice === "custom_notes") {
+      const customsAsk = await inquirer.prompt([
+        {
+          type: "input",
+          name: "notes",
+          message: "Input details or focal directions for this layout:",
+          default: customInstructions
+        }
+      ]);
+      customInstructions = customsAsk.notes;
+      console.log("\x1b[32m✔ Focal guidelines registered.\x1b[0m\n");
+      continue;
+    }
+
+    if (activeChoice === "trigger_gen") {
+      console.log("\n\x1b[36mCalling Google Gemini API models to analyze repo architectures...\x1b[0m");
+
+      try {
+        const ai = new GoogleGenAI({
+          apiKey,
+          httpOptions: {
+            headers: {
+              'User-Agent': 'aistudio-build',
+            }
+          }
+        });
+
+        const filteredManifests = scanResult.manifests.filter(m => selectedManifestPaths.includes(m.relativePath));
+        const filteredSnippets = scanResult.snippets.filter(s => selectedSnippetPaths.includes(s.relativePath));
+        const filteredMarkdowns = scanResult.markdowns.filter(md => selectedMarkdownPaths.includes(md.relativePath));
+
+        let manifestsBlock = "";
+        filteredManifests.forEach(m => {
+          manifestsBlock += `\n--- Manifest File: ${m.relativePath} ---\n\`\`\`\n${m.content}\n\`\`\`\n`;
+        });
+
+        let snippetsBlock = "";
+        filteredSnippets.forEach(s => {
+          snippetsBlock += `\n--- Code Snippet: ${s.relativePath} ---\n\`\`\`\n${s.content}\n\`\`\`\n`;
+        });
+
+        let markdownsBlock = "";
+        filteredMarkdowns.forEach(md => {
+          markdownsBlock += `\n--- Reference Markdown File: ${md.relativePath} ---\n\`\`\`markdown\n${md.content}\n\`\`\`\n`;
+        });
+
+        const systemInstruction = `Role: You are an expert technical writer and principal software architect.
+Task: Your job is to generate a comprehensive, highly polished, professional README.md file based only on the provided directory structure, project configuration files, and references, formatted EXACTLY using the Best-README-Template by @othneildrew.
+
+Visual Layout / Structure Requirements (Derived from othneildrew/Best-README-Template):
+The document MUST strictly follow this exact outline and formatting sequence:
+
+1. Top Anchors & Shields:
+- Add a top anchor: \`<a name="readme-top"></a>\` at the absolute beginning of the file.
+- Centered shields/badges using raw Markdown with stylish links: Contributors, Forks, Stargazers, Issues, License, LinkedIn. Specify reference URL identifiers at the absolute bottom of the file (e.g. \`[contributors-shield]: ...\`).
+- Put badges cleanly on top.
+
+2. Project Logo & Headers (Centered):
+- Leave space for logo using \`<br />\` and then a centered div block containing:
+  - An image tag targeting a generic logo placeholder (or repository logo) with dimensions 80x80. Use "https://images.unsplash.com/photo-1618401471353-b98aedd07871?q=80&w=120&auto=format&fit=crop" as a source placeholder if no logo is found.
+  - A centered \`<h3 align="center">Project Title</h3>\`
+  - A short, descriptive project subtitle.
+  - Links to Explore the Docs, View Demo, Report Bug, Request Feature centering on appropriate URLs.
+
+3. Interactive Detail-TOC (Table of Contents):
+- Add a table of contents enclosed in a Collapsible Details panel (\`<details><summary>Table of Contents</summary>...\` using list elements with anchors pointing to respective sections: About The Project, Getting Started (Prerequisites, Installation), Usage, Roadmap, Contributing, License, Contact, Acknowledgments).
+
+4. About the Project:
+- Place a section title \`## About The Project\` with a paragraph detailing what issues the library solves and why.
+- Provide a placeholder screenshot element (\`[![Product Name Screen Shot][product-screenshot]](https://example.com)\`).
+- Add a \`### Built With\` subsection with raw shields list linking to core framework technologies identified in the manifests or languages (e.g. Next.js, React, Python, Go, Rust, etc., with shields like \`* [![React][React.js]][React-url]\`).
+- Add \`<p align="right">(<a href="#readme-top">back to top</a>)</p>\` at the end of this and ALL subsequent major sections.
+
+5. Getting Started:
+- Place \`## Getting Started\` heading.
+- Include \`### Prerequisites\` listing key runtime versions or engines with raw commands (e.g., npm or pip).
+- Include \`### Installation\` with custom sequential steps: Clone repository, Install dependencies/packages using correct package manager commands, Setup key constants/configs.
+
+6. Usage:
+- Place \`## Usage\` heading with direct code instructions, visual scripts invocation, and explanation.
+
+7. Roadmap:
+- Place \`## Roadmap\` heading highlighting future planning milestones or upcoming revisions. Use standard markdown task lists (e.g., \`- [ ] Feature 1\`).
+
+8. Contributing:
+- Place \`## Contributing\` heading detailing the exact five-step guidelines for forks, branching, commits, and pull request initiation.
+
+9. License:
+- Place \`## License\` heading highlighting the standard licensing info (e.g. MIT License).
+
+10. Contact:
+- Place \`## Contact\` heading listing author/maintainer contact points, project links, or email tags.
+
+11. Acknowledgments:
+- Place \`## Acknowledgments\` heading listing standard resources (e.g., Shields.io, select libraries, or other credits).
+
+12. Bottom Link References:
+- At the absolute bottom of the document, define ALL referenced links and shield assets used at the top and Built With section dynamically to keep the rest of the text bodies pristine (e.g., \`[contributors-shield]: ...\`).
+
+${addGuidelines.length > 0 ? `Include these extra specific layout headings inside the layout: ${addGuidelines.map(sec => `- ${sec}`).join("\n")}` : ""}
+
+Do not write markdown block fences inside the generated readme itself unless wrapping code examples. Do not add any conversational meta-talk. Output the raw Best-README-Template markdown directly.`;
+
+        const prompt = `Generate a README.md file based on the following codebase analysis:
+
+Project Structure:
+${treeBody}
+
+${manifestsBlock}
+
+${snippetsBlock}
+
+${markdownsBlock}
+
+${customInstructions ? `Custom User directives:\n${customInstructions}\n` : ""}
+
+Generate the complete, polished Markdown output directly without any extra conversation.`;
+
+        const response = await ai.models.generateContent({
+          model: chosenModel,
+          contents: prompt,
+          config: {
+            systemInstruction,
+            temperature: 0.2
+          }
+        });
+
+        generatedContent = response.text || "";
+        if (!generatedContent.trim()) {
+          throw new Error("Empty response received. The Gemini API returned no text output. This may indicate a content safety block or translation filter restriction.");
+        }
+        console.log("\n\x1b[32mSuccess: Complete README.md script synthesized successfully!\x1b[0m\n");
+
+        // Open custom post-generation menu to prevent orthodox layout issues
+        let backToMain = false;
+        while (!backToMain) {
+          const postChoices = [
+            { name: "Preview generated Markdown code", value: "preview_output" },
+            { name: "Save output documentation to root README.md", value: "save_disk" },
+            { name: "Return to Main Menu", value: "return_main" },
+            { name: "Exit ReadMeg", value: "exit_cli" }
+          ];
+
+          const postMenu = await inquirer.prompt([
+            {
+              type: "select",
+              name: "action",
+              message: "Document Actions Menu — Choose action for compiled guide:",
+              choices: postChoices,
+              loop: false
+            }
+          ]);
+
+          const postAction = postMenu.action;
+
+          if (postAction === "exit_cli") {
+            console.log("Thanks for using ReadMeg. Keep coding!");
+            process.exit(0);
+          }
+
+          if (postAction === "return_main") {
+            backToMain = true;
+            break;
+          }
+
+          if (postAction === "preview_output") {
+            console.log("\n\x1b[35m=== Generated Markdown Output Preview ===\x1b[0m\n");
+            console.log(generatedContent || "(No content compiled yet)");
+            console.log("\n\x1b[35m==========================================\x1b[0m\n");
+            continue;
+          }
+
+          if (postAction === "save_disk") {
+            const activeOutput = options.output || "README.md";
+            const targetFilePath = path.resolve(activeCwd, activeOutput);
+            let fileExists = false;
+            try {
+              fileExists = fs.existsSync(targetFilePath);
+            } catch (err) {
+              console.error(`\x1b[31m[Error] Failed to verify existence of ${activeOutput}: ${err.message}\x1b[0m\n`);
+              continue;
+            }
+
+            if (fileExists) {
+              console.log(`\n\x1b[33mWarning: File already exists at workspace path: ${path.basename(targetFilePath)}\x1b[0m`);
+              const confirmSave = await inquirer.prompt([
+                {
+                  type: "select",
+                  name: "overwriteAction",
+                  message: "Verify overwrite protection settings:",
+                  choices: [
+                    { name: "Overwrite file fully (Wipe and replace)", value: "overwrite" },
+                    { name: "Append documentation content at bottom", value: "append" },
+                    { name: "Cancel operation", value: "cancel" }
+                  ]
+                }
+              ]);
+
+              const saveAction = confirmSave.overwriteAction;
+              if (saveAction === "cancel") {
+                console.log("File modification canceled.\n");
+                continue;
+              }
+
+              if (saveAction === "append") {
+                try {
+                  const originalText = fs.readFileSync(targetFilePath, "utf-8");
+                  fs.writeFileSync(targetFilePath, originalText + "\n\n" + generatedContent, "utf-8");
+                  console.log(`\x1b[32mSuccess: Document successfully appended to ${activeOutput}!\x1b[0m\n`);
+                } catch (writeErr) {
+                  console.error(`\x1b[31m[Error] Failed to read or append to ${activeOutput}: ${writeErr.message}\x1b[0m\n`);
+                }
+                continue;
+              }
+            }
+
+            try {
+              fs.writeFileSync(targetFilePath, generatedContent, "utf-8");
+              console.log(`\x1b[32mSuccess: Output written successfully to root ${activeOutput} path!\x1b[0m\n`);
+            } catch (writeErr) {
+              console.error(`\x1b[31m[Error] Failed to write file to ${activeOutput}: ${writeErr.message}\x1b[0m\n`);
+            }
+          }
+        }
+
+      } catch (err) {
+        console.error(`\n\x1b[31m✖ Gemini API Generation Failed:\x1b[0m`);
+        console.error(`\x1b[33mReason:\x1b[0m ${err.message}`);
+        if (err.status === 400 || err.message?.toLowerCase().includes("api key") || err.message?.toLowerCase().includes("apikey")) {
+          console.error(`\x1b[35mTip:\x1b[0m Please verify that your Gemini API Key is active, valid, and has correct permissions.`);
+        } else if (err.message?.toLowerCase().includes("model")) {
+          console.error(`\x1b[35mTip:\x1b[0m The chosen model '${chosenModel}' might be unavailable or invalid.`);
+        } else if (err.message?.toLowerCase().includes("fetch") || err.message?.toLowerCase().includes("enotfound") || err.message?.toLowerCase().includes("network")) {
+          console.error(`\x1b[35mTip:\x1b[0m Network connectivity issue detected. Please check your internet connection.`);
+        }
+        console.log("");
+      }
+      continue;
+    }
+  }
+}
+
+/**
+ * Direct non-interactive execution logic
+ */
+async function runDirectScanAndGen() {
+  console.log("Running zero-config non-interactive codebase scans...");
+  const activeCwd = process.cwd();
+  
+  let treeBody = "";
+  try {
+    treeBody = buildTreeString(activeCwd);
+  } catch (err) {
+    console.error(`\x1b[31mERROR: Directory tree scanning failed completely: ${err.message}\x1b[0m`);
+    process.exit(1);
+  }
+
+  const scanResult = {
+    manifests: [],
+    snippets: [],
+    languages: new Set()
+  };
+
+  try {
+    scanDirectoryFiles(activeCwd, "", scanResult);
+  } catch (err) {
+    console.error(`\x1b[31mERROR: Detailed file scanning failed: ${err.message}\x1b[0m`);
+    process.exit(1);
+  }
+
+  const apiKey = options.apiKey || process.env.GEMINI_API_KEY;
+  if (!apiKey || !apiKey.trim()) {
+    console.error("\x1b[31mERROR: Gemini API key is missing. Run with --api-key=KEY or set the GEMINI_API_KEY environment variable.\x1b[0m");
+    process.exit(1);
+  }
+
+  try {
+    const ai = new GoogleGenAI({
+      apiKey: apiKey.trim(),
+      httpOptions: {
+        headers: {
+          'User-Agent': 'aistudio-build',
+        }
+      }
+    });
+
+    let manifestsBlock = "";
+    scanResult.manifests.forEach(m => {
+      manifestsBlock += `\n--- file: ${m.relativePath} ---\n\`\`\`\n${m.content}\n\`\`\`\n`;
+    });
+
+    const prompt = `Generate a README.md file based on the following codebase layout tree:
+
+Project Structure:
+${treeBody}
+
+${manifestsBlock}
+
+Generate the complete, polished Markdown output directly without any extra conversation.`;
+
+    const response = await ai.models.generateContent({
+      model: "gemini-3.5-flash",
+      contents: prompt,
+      config: {
+        systemInstruction: "You are an expert technical writer. Write a comprehensive, polished production-ready README.md file directly.",
+        temperature: 0.2
+      }
+    });
+
+    const markdownOutput = response.text || "";
+    if (!markdownOutput.trim()) {
+      throw new Error("Empty response received. The Gemini API returned no text output. This may indicate a content safety block or translation filter restriction.");
+    }
+
+    const targetFile = path.resolve(activeCwd, options.output);
+    fs.writeFileSync(targetFile, markdownOutput, "utf-8");
+    console.log(`Success: Direct Generation saved cleanly to: ${options.output}`);
+  } catch (error) {
+    console.error(`\n\x1b[31m✖ Direct Generative Error:\x1b[0m ${error.message}`);
+    if (error.status === 400 || error.message?.toLowerCase().includes("api key") || error.message?.toLowerCase().includes("apikey")) {
+      console.error(`\x1b[35mTip:\x1b[0m Please verify that your Gemini API Key is active, valid, and has correct permissions.`);
+    } else if (error.message?.toLowerCase().includes("fetch") || error.message?.toLowerCase().includes("enotfound") || error.message?.toLowerCase().includes("network")) {
+      console.error(`\x1b[35mTip:\x1b[0m Network connectivity issue detected. Please check your internet connection.`);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "readmeg",
+  "version": "1.0.0",
+  "description": "Zero-config terminal tool powered by Gemini that automatically generates comprehensive, production-grade README files for local repositories.",
+  "type": "module",
+  "bin": {
+    "readmeg": "./bin/readmeg.js"
+  },
+  "files": [
+    "bin/readmeg.js"
+  ],
+  "scripts": {
+    "build": "echo 'Build successful'",
+    "start": "node ./bin/readmeg.js --help",
+    "lint": "echo 'No lint needed'"
+  },
+  "dependencies": {
+    "@google/genai": "^2.4.0",
+    "commander": "^15.0.0",
+    "dotenv": "^17.2.3",
+    "inquirer": "^14.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0"
+  },
+  "keywords": [
+    "readme",
+    "generator",
+    "gemini",
+    "cli",
+    "ai",
+    "documentation"
+  ],
+  "author": "",
+  "license": "MIT"
+}