smartreadme 1.0.0

package/README.md

@@ -0,0 +1,270 @@
+# Readme Gen
+
+> A zero-dependency CLI tool and Node.js library that scans your project and generates a professional, publish-ready `README.md` — written in TypeScript.
+
+[![npm version](https://badge.fury.io/js/smartreadme.svg)](https://www.npmjs.com/package/smartreadme)
+[![npm downloads](https://img.shields.io/npm/dm/smartreadme.svg)](https://www.npmjs.com/package/smartreadme)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)
+
+---
+
+## 📋 About
+
+**smartreadme** scans your `package.json`, detects your tech stack, reads your scripts, checks for Docker and CI configs, and safely masks any `.env` variables — then outputs a polished, structured `README.md` in seconds.
+
+- **Zero dependencies** at runtime — nothing to install beyond the tool itself.
+- **Safe `.env` handling** — real secret values are never written to your README; they are replaced with clearly labelled example placeholders.
+- **Auto backup** — if a `README.md` already exists it is renamed to `README.backup.<timestamp>.md` before writing.
+- **Works as a CLI or a programmatic API** — import `scan`, `generate`, and `run` directly in your own scripts.
+
+---
+
+## ✨ Features
+
+- ✅ Detects 30+ frameworks and libraries (React, Vue, Next.js, Express, Prisma, tRPC, Hono…)
+- ✅ Generates npm badges, license badge, and per-tech-stack shield badges automatically
+- ✅ Masks `.env` / `.env.example` values with safe, contextual placeholders
+- ✅ Produces a scripts table from `package.json`
+- ✅ Adds Docker usage section when `Dockerfile` / `docker-compose.yml` is detected
+- ✅ Adds API Reference section for backend/library project types
+- ✅ Backs up any existing README before overwriting
+- ✅ Fully typed — ships with `.d.ts` declaration files
+- 🚧 Plugin system for custom section builders — coming soon
+
+---
+
+## 🛠️ Tech Stack
+
+- **TypeScript** — strict mode, full declaration output
+- **Node.js** — CommonJS, no runtime dependencies
+- **ts-node** — for running tests directly without a build step
+
+---
+
+## 📦 Prerequisites
+
+- [Node.js](https://nodejs.org/) v18 or higher
+- [npm](https://www.npmjs.com/) v9 or higher
+
+---
+
+## 🚀 Getting Started
+
+### Install globally (CLI usage)
+
+```bash
+npm install -g smartreadme
+```
+
+### Install locally (programmatic API)
+
+```bash
+npm install --save-dev readme-gen
+```
+
+### Clone and develop
+
+```bash
+git clone https://github.com/yourusername/readme-gen.git
+cd readme-gen
+
+# Install dev dependencies
+npm install
+
+# Build TypeScript → dist/
+npm run build
+
+# Run the CLI from dist
+npm start
+```
+
+---
+
+## 💻 Usage
+
+### CLI
+
+Run inside any Node.js project directory:
+
+```bash
+smartreadme
+```
+
+This scans the current directory, generates `README.md`, and backs up any existing file.
+
+#### CLI Options
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--help` | `-h` | Show help message |
+| `--version` | `-v` | Print version number |
+| `--output <file>` | `-o` | Output filename (default: `README.md`) |
+| `--overwrite` | `-f` | Overwrite existing README without backup |
+| `--preview` | `-p` | Print README to terminal, no file written |
+| `--dir <path>` | | Target directory (default: current directory) |
+
+#### Examples
+
+```bash
+# Generate README in current directory
+readme-gen
+
+# Preview without writing
+readme-gen --preview
+
+# Write to a custom file name
+readme-gen --output DOCS.md
+
+# Target a different project folder
+readme-gen --dir ./my-other-project
+
+# Overwrite without backup
+readme-gen --overwrite
+```
+
+### Programmatic API
+
+```typescript
+import { scan, generate, run } from 'readme-gen';
+
+// Scan + generate in one step (writes README.md to disk)
+const result = run('/path/to/project');
+console.log(result.outPath);   // absolute path to the written file
+console.log(result.markdown);  // the raw markdown string
+
+// Or do it in two steps
+const data = scan('/path/to/project');
+const markdown = generate(data);
+console.log(markdown);
+
+// Access individual helpers
+import { scanEnvFile, generateExampleValue, detectStack } from 'readme-gen';
+
+const env = scanEnvFile('/path/to/project');
+// { found: true, content: 'DB_URL=mongodb://localhost:27017/your_db\n...', sourceFile: '.env' }
+
+const placeholder = generateExampleValue('DATABASE_URL');
+// 'mongodb://localhost:27017/your_db'
+```
+
+---
+
+## 🔐 Environment Variable Masking
+
+`readme-gen` scans `.env.example`, `.env.sample`, or `.env` (in that order of preference). Real values are **never** written to the README — instead, each key is matched against a set of patterns and replaced with a descriptive placeholder:
+
+| Key pattern | Example output |
+|-------------|----------------|
+| `*PASSWORD*`, `*SECRET*`, `*PASS*` | `your_secret_here` |
+| `*API_KEY*`, `*PRIVATE_KEY*` | `your_api_key_here` |
+| `*TOKEN*` | `your_token_here` |
+| `*DATABASE_URL*`, `*MONGO*` | `mongodb://localhost:27017/your_db` |
+| `*REDIS_URL*` | `redis://localhost:6379` |
+| `*POSTGRES*` | `postgresql://user:password@localhost:5432/your_db` |
+| `PORT` | `3000` |
+| `NODE_ENV` | `development` |
+
+> ⚠️ Even if you accidentally paste a `.env` with real secrets, they will not appear in the output README.
+
+---
+
+## 📜 Available Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `npm run build` | `tsc --project tsconfig.json` | Compile TypeScript to `dist/` |
+| `npm run dev` | `tsc --project tsconfig.json --watch` | Watch mode compilation |
+| `npm start` | `node dist/bin/cli.js` | Run the compiled CLI |
+| `npm test` | `ts-node --project tsconfig.json test/test.ts` | Run the test suite |
+| `npm run typecheck` | `tsc --noEmit` | Type-check without emitting files |
+
+---
+
+## 📁 Project Structure
+
+```
+readme-gen/
+├── src/
+│   ├── types.ts       # All TypeScript interfaces and type definitions
+│   ├── scanner.ts     # Project scanner (package.json, stack, env, configs)
+│   ├── generator.ts   # Markdown section builders
+│   └── index.ts       # Public API (scan, generate, run) + re-exports
+├── bin/
+│   └── cli.ts         # CLI entry point — argument parsing and file I/O
+├── demo/
+│   └── index.html     # Interactive browser demo — open and try it locally
+├── test/
+│   └── test.ts        # Test suite (20 assertions, zero test framework deps)
+├── dist/              # Compiled output (generated by `npm run build`)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## 🌐 Demo
+
+Open `demo/index.html` directly in your browser — no server needed. Fill in your project details, select your stack, paste a `.env`, and click **Generate README** to see a live preview with masked env values. You can download the result as `README.md`.
+
+---
+
+## 📡 API Reference
+
+### `scan(projectRoot?: string): ProjectData`
+
+Scans the given directory (default: `process.cwd()`) and returns a `ProjectData` object.
+
+### `generate(data: ProjectData): string`
+
+Takes `ProjectData` and returns a complete README markdown string.
+
+### `run(projectRoot?: string, options?: RunOptions): RunResult`
+
+Combines `scan` + `generate` + file write in one call. Backs up any existing README.
+
+```typescript
+interface RunOptions {
+  output?: string;    // default: 'README.md'
+  overwrite?: boolean; // default: false
+}
+
+interface RunResult {
+  outPath: string;
+  data: ProjectData;
+  markdown: string;
+}
+```
+
+### `generateExampleValue(key: string): string`
+
+Returns a safe placeholder value for the given env variable key name.
+
+### `scanEnvFile(projectRoot: string): EnvInfo`
+
+Reads `.env.example` / `.env.sample` / `.env` and returns masked content.
+
+### `detectStack(pkg: PackageJson | null): string[]`
+
+Returns an array of detected framework/library names from `package.json` deps.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m "feat: add amazing feature"`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+Please make sure to run `npm run typecheck` and `npm test` before submitting.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

package/dist/bin/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":""}

package/dist/bin/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var _a, _b, _c, _d;
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const scanner_1 = require("../src/scanner");
+const generator_1 = require("../src/generator");
+// ── Arg parsing ───────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+function getFlag(name) {
+    var _a;
+    const idx = args.indexOf(name);
+    if (idx !== -1 && idx + 1 < args.length)
+        return (_a = args[idx + 1]) !== null && _a !== void 0 ? _a : null;
+    return null;
+}
+function hasFlag(...names) {
+    return names.some((n) => args.includes(n));
+}
+const flags = {
+    help: hasFlag("--help", "-h"),
+    version: hasFlag("--version", "-v"),
+    output: (_b = (_a = getFlag("--output")) !== null && _a !== void 0 ? _a : getFlag("-o")) !== null && _b !== void 0 ? _b : "README.md",
+    overwrite: hasFlag("--overwrite", "-f"),
+    preview: hasFlag("--preview", "-p"),
+    dir: (_c = getFlag("--dir")) !== null && _c !== void 0 ? _c : process.cwd(),
+};
+// ── Help ──────────────────────────────────────────────────────────────────────
+if (flags.help) {
+    console.log(`
+  ┌─────────────────────────────────────────┐
+  │        smartreadme  📄                   │
+  │   Generate professional README files    │
+  └─────────────────────────────────────────┘
+
+  Usage:
+    smartreadme [options]
+
+  Options:
+    -h, --help          Show this help message
+    -v, --version       Show version number
+    -o, --output FILE   Output file name (default: README.md)
+    -f, --overwrite     Overwrite existing README without backup
+    -p, --preview       Print README to terminal, no file written
+    --dir PATH          Target project directory (default: cwd)
+
+  Examples:
+    smartreadme
+    smartreadme --output DOCS.md
+    smartreadme --dir ./my-project --overwrite
+    smartreadme --preview
+`);
+    process.exit(0);
+}
+// ── Version ───────────────────────────────────────────────────────────────────
+if (flags.version) {
+    // Walk up from dist/bin/ to find package.json
+    const pkgPath = path_1.default.join(__dirname, "..", "package.json");
+    try {
+        const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, "utf-8"));
+        console.log(`smartreadme v${pkg.version}`);
+    }
+    catch {
+        console.error("❌ Could not read version from package.json");
+        process.exit(1);
+    }
+    process.exit(0);
+}
+// ── Main ──────────────────────────────────────────────────────────────────────
+console.log("\n  📡 smartreadme — Scanning your project...\n");
+const projectRoot = path_1.default.resolve(flags.dir);
+if (!fs_1.default.existsSync(projectRoot)) {
+    console.error(`  ❌ Directory not found: ${projectRoot}`);
+    process.exit(1);
+}
+const data = (0, scanner_1.scanProject)(projectRoot);
+console.log(`  ✅ Project : ${data.name} (${data.projectType})`);
+if (data.stack.length > 0) {
+    console.log(`  ✅ Stack   : ${data.stack.join(", ")}`);
+}
+if (data.envInfo.found) {
+    console.log(`  ✅ Env file: ${(_d = data.envInfo.sourceFile) !== null && _d !== void 0 ? _d : ".env"} (values replaced with examples)`);
+}
+if (data.configs.docker) {
+    console.log("  ✅ Docker config detected");
+}
+console.log("");
+const markdown = (0, generator_1.generateReadme)(data);
+// Preview mode — just print, no file write
+if (flags.preview) {
+    console.log("─".repeat(60));
+    console.log(markdown);
+    console.log("─".repeat(60));
+    console.log("\n  ℹ️  Preview mode — no file written.\n");
+    process.exit(0);
+}
+const outPath = path_1.default.join(projectRoot, flags.output);
+if (fs_1.default.existsSync(outPath) && !flags.overwrite) {
+    const backup = outPath.replace(/\.md$/i, `.backup.${Date.now()}.md`);
+    try {
+        fs_1.default.renameSync(outPath, backup);
+        console.log(`  📦 Existing README backed up to: ${path_1.default.basename(backup)}`);
+    }
+    catch (err) {
+        console.error(`  ❌ Failed to backup existing README: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+try {
+    fs_1.default.writeFileSync(outPath, markdown, "utf-8");
+}
+catch (err) {
+    console.error(`  ❌ Failed to write README: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+}
+console.log(`  ✨ README generated successfully → ${flags.output}`);
+console.log("  📝 Don't forget to fill in the placeholder sections!\n");
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/generator.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectData } from "./types";
+/**
+ * Generates a professional README.md from scanned project data.
+ */
+export declare function generateReadme(data: ProjectData): string;
+//# sourceMappingURL=generator.d.ts.map

package/dist/src/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AAExD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAmBxD"}