genrex 0.1.0 → 0.2.1

package/README.md

@@ -11,95 +11,200 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version" />
+  <a href="https://www.npmjs.com/package/genrex"><img src="https://img.shields.io/npm/v/genrex?style=flat-square&color=cb3837" alt="npm version" /></a>
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" />
+  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="Node version" />
 </p>
 
 > **Forge production-ready projects from configurable blueprints.**
 
-`genrex` is a modern, lightweight project scaffolding CLI engine. Rather than copying generic boilerplates, it generates strongly-typed, coherent software projects with Biome, Vitest, CI/CD, and Docker support tailored to your stack.
+`genrex` is a modern, lightweight CLI scaffolding engine. Rather than copying bare-bones or obsolete boilerplates, it generates strictly-typed, coherent software projects equipped with modern standards: **Biome**, **Vitest**, native ESM, **GitHub Actions CI**, and multi-stage **Dockerfiles**.
 
 ---
 
-## Tech Stack & Ecosystem
+## ⚡ Installation & Execution
 
-- **Language & Runtime:** TypeScript (Strict, Native ESM), Node.js (>=20)
-- **Code Quality & Testing:** Biome (Format/Lint), Vitest
-- **API Framework:** Fastify + `tsx` hot-reload
-- **DevOps & Containers:** Multi-stage Docker, GitHub Actions CI
-- **Package Managers:** `pnpm`, `npm`, `yarn`, `bun`
+You have two ways to run `genrex`:
 
----
-
-## Quick Start
+### 1. One-Time Run (Recommended — No Install Needed)
 
-Run directly with `npx`:
+Run the latest version instantly using `npx`:
 
 ```bash
-npx genrex create my-api --blueprint node-api
+npx genrex create
 ```
 
-Preview what will be generated without writing to disk:
+Or target a specific name directly:
 
 ```bash
-npx genrex create my-cli --dry-run
+npx genrex create my-app
 ```
 
 ---
 
-## Blueprints
+### 2. Global Installation
 
-| Blueprint | ID | Description |
-|---|---|---|
-| **TypeScript CLI** | `ts-cli` | Standalone CLI binary, ESM, Biome formatting, Vitest |
-| **Node.js API** | `node-api` | Fastify REST API, hot-reload (`tsx`), healthchecks |
-| **TypeScript Library** | `ts-lib` | Publishable library with dual ESM exports and `.d.ts` declaration maps |
+If you frequently scaffold new projects, install `genrex` globally:
+
+```bash
+# Using npm
+npm install -g genrex
+
+# Using pnpm
+pnpm add -g genrex
+
+# Using yarn
+yarn global add genrex
+
+# Using bun
+bun add -g genrex
+```
 
-View all blueprints anytime:
+Once installed, use the `genrex` command anywhere:
 
 ```bash
-genrex list
-genrex info ts-cli
+genrex create
 ```
 
 ---
 
-## Commands & Usage
+## 🎯 Interactive Wizard Mode
 
-### 1. Create a Project
+Running `genrex create` without options launches an interactive step-by-step setup wizard:
 
-```bash
-genrex create <project-name> [options]
+```text
+genrex — Project Blueprint Engine
+
+? Project name: my-fastify-api
+
+? Choose a blueprint:
+  1) TypeScript CLI         (ts-cli)
+  2) Node.js API            (node-api)
+  3) TypeScript Library     (ts-lib)
+Select [1-3] (1): 2
+
+? Package manager:
+  1) pnpm
+  2) npm
+  3) yarn
+  4) bun
+Select [1-4] (1): 1
+
+? Initialize Git? (Y/n): y
+? Add GitHub Actions CI? (y/N): y
+? Add Docker? (y/N): y
+
+✓ Project scaffolded in /path/to/my-fastify-api
+Installing dependencies using pnpm...
+✓ Dependencies installed
+Initializing Git repository...
+✓ Git repository initialized
+
+Done. Next steps:
+  cd my-fastify-api
+  pnpm run dev
+  pnpm test
 ```
 
-**Options:**
+---
+
+## 📖 Complete Command Reference
+
+| Command | Description |
+|---|---|
+| `genrex create [name]` | Scaffold a new project (interactive wizard by default) |
+| `genrex list` | Show all available blueprints and descriptions |
+| `genrex info <id>` | Inspect detailed metadata & capabilities of a blueprint |
+| `genrex doctor` | Audit local development environment tools and versions |
+| `genrex -v, --version` | Output current CLI version |
+| `genrex -h, --help` | Display command usage and option flags |
+
+---
+
+### 1. `genrex create [name] [options]`
+
+Scaffold a project. You can skip interactive prompts entirely using flags (ideal for CI/automation scripts).
+
+#### Command Flags:
 
 | Flag | Description | Default |
 |---|---|---|
-| `--blueprint <id>` | Blueprint template (`ts-cli`, `node-api`, `ts-lib`) | `ts-cli` |
+| `-i, --interactive` | Force interactive wizard even if name is supplied | `false` |
+| `--blueprint <id>` | Target blueprint: `ts-cli`, `node-api`, or `ts-lib` | `ts-cli` |
 | `--package-manager <pm>` | `npm`, `pnpm`, `yarn`, or `bun` | `pnpm` |
 | `--git` | Initialize empty Git repository | `false` |
-| `--github-actions` | Generate GitHub Actions CI test/lint workflow | `false` |
-| `--docker` | Generate optimized multi-stage Dockerfile | `false` |
-| `--dry-run` | Preview file tree and dependencies without writing files | `false` |
-| `--skip-install` | Scaffold files without running package installation | `false` |
+| `--github-actions` | Generate `.github/workflows/ci.yml` CI workflow | `false` |
+| `--docker` | Generate multi-stage `Dockerfile` and `.dockerignore` | `false` |
+| `--dry-run` | Preview files and packages without writing to disk | `false` |
+| `--skip-install` | Scaffold files without executing package manager install | `false` |
 
-**Full-fledged Example:**
+#### Non-Interactive Examples:
 
 ```bash
-genrex create billing-service \
-  --blueprint node-api \
-  --package-manager pnpm \
-  --git \
-  --github-actions \
-  --docker
+# Preview what would be created without writing any files
+genrex create my-tool --blueprint ts-cli --dry-run
+
+# Node.js API with pnpm, Git, and GitHub Actions
+genrex create backend-service --blueprint node-api --package-manager pnpm --git --github-actions
+
+# Lightweight library without waiting for dependency installation
+genrex create math-utils --blueprint ts-lib --skip-install
+
+# Full-stack microservice with Docker containerization
+genrex create auth-service --blueprint node-api --docker --github-actions --git
 ```
 
 ---
 
-### 2. Environment Doctor
+### 2. `genrex list`
 
-Diagnose your environment tools in one command:
+List all built-in blueprint architectures:
+
+```bash
+genrex list
+```
+
+```text
+Available blueprints:
+
+  ts-cli       TypeScript CLI (TypeScript)
+               Production-ready TypeScript CLI tool.
+
+  node-api     Node.js API (TypeScript)
+               Node.js REST API with routing and healthchecks.
+
+  ts-lib       TypeScript Library (TypeScript)
+               Publishable TypeScript library blueprint.
+```
+
+---
+
+### 3. `genrex info <blueprint-id>`
+
+Inspect capabilities and metadata of any blueprint:
+
+```bash
+genrex info node-api
+```
+
+```text
+Node.js API (node-api)
+Version:      1.0.0
+Language:     TypeScript
+Description:  Node.js REST API with routing and healthchecks.
+Capabilities:
+  - testing
+  - formatting
+  - git
+  - github-actions
+  - docker
+```
+
+---
+
+### 4. `genrex doctor`
+
+Audit your machine's environment and ensure required developer tools are installed:
 
 ```bash
 genrex doctor
@@ -122,27 +227,86 @@ Environment is ready.
 
 ---
 
-## Design Principles
+## 🏗️ Available Blueprints & Project Structures
 
-- **Zero Unnecessary Bloat:** Fast execution with near-zero runtime dependencies.
-- **Fail Safely:** Refuses to overwrite non-empty directories; pre-validates all input and tools before modifying the disk.
-- **Modern Standards:** Native ESM, strict TypeScript, Biome linter/formatter, and Vitest by default.
-- **Cross-Platform:** Works seamlessly on Windows, macOS, and Linux.
+### 1. TypeScript CLI (`ts-cli`)
+Tailored for building standalone developer tools and CLI applications.
+```text
+my-cli/
+├── src/
+│   └── index.ts          # Executable binary entry point with shebang
+├── tests/
+│   └── index.test.ts     # Vitest unit test suite
+├── .gitignore
+├── biome.json            # High-performance linter & formatter
+├── package.json          # Configured with "bin" field and ESM
+├── tsconfig.json         # Strict NodeNext configuration
+└── README.md
+```
+
+### 2. Node.js API (`node-api`)
+Production-ready REST API built with Fastify.
+```text
+my-api/
+├── src/
+│   └── server.ts         # Fastify server with /health route
+├── tests/
+│   └── server.test.ts    # Vitest route testing
+├── .gitignore
+├── biome.json
+├── package.json          # Development with "tsx watch" hot-reload
+├── tsconfig.json
+└── README.md
+```
+
+### 3. TypeScript Library (`ts-lib`)
+Ready for distribution on npm with dual type declarations.
+```text
+my-lib/
+├── src/
+│   └── index.ts          # Library exports
+├── tests/
+│   └── index.test.ts     # Vitest test suite
+├── .gitignore
+├── .npmignore            # Keeps source and tests out of npm tarball
+├── biome.json
+├── package.json          # "exports", "main", "types", "prepublishOnly"
+├── tsconfig.json         # Generates declaration maps (.d.ts)
+└── README.md
+```
 
 ---
 
-## Development
+## 🛡️ Safety & Core Philosophy
+
+- **Zero Accidental Overwriting:** Refuses to generate files inside non-empty folders.
+- **Shell Injection Safe:** Child processes use direct executable arguments (`shell: false`) rather than concatenated shell strings.
+- **Fail Fast:** Project names, blueprint availability, and Git binary presence are validated before modifying the filesystem.
+- **Zero Heavy Runtime Dependencies:** Blazing fast execution using native Node.js APIs (`node:readline/promises`, `node:child_process`, `node:fs`).
+
+---
+
+## 💻 Development & Contributing
+
+Want to add new blueprints or improve the CLI?
 
 ```bash
+# Clone the repository
 git clone https://github.com/waeterr/genrex.git
 cd genrex
+
+# Install dev dependencies
 npm install
+
+# Run automated tests (native Node test runner + TypeScript strip)
 npm test
+
+# Build TypeScript to dist/
 npm run build
 ```
 
 ---
 
-## License
+## 📄 License
 
 MIT © [waeterr](https://github.com/waeterr)

package/dist/src/create.js

@@ -6,21 +6,39 @@ import { buildNodeApiFiles } from "./generators/node-api.js";
 import { buildTsLibFiles } from "./generators/ts-lib.js";
 import { checkGit, initGit } from "./git.js";
 import { installDependencies } from "./pm.js";
-export function createProject(name, options) {
-    if (!name) {
+import { promptWizard } from "./prompt.js";
+export async function createProject(name, options) {
+    let targetName = name;
+    let targetBlueprint = options.blueprint ?? "ts-cli";
+    let targetPm = options.packageManager ?? "pnpm";
+    let targetGit = options.git;
+    let targetCi = options.githubActions;
+    let targetDocker = options.docker;
+    const shouldPrompt = Boolean(process.stdin.isTTY) &&
+        (!targetName || options.interactive || (!options.blueprint && !options.dryRun));
+    if (shouldPrompt) {
+        const answers = await promptWizard(targetName);
+        targetName = answers.name;
+        targetBlueprint = answers.blueprint;
+        targetPm = answers.packageManager;
+        targetGit = answers.git;
+        targetCi = answers.githubActions;
+        targetDocker = answers.docker;
+    }
+    if (!targetName) {
         fail("Project name is required. Example: genrex create my-project");
         return;
     }
     const config = {
-        name: basename(name),
-        destination: resolve(name),
-        blueprint: options.blueprint ?? "ts-cli",
-        packageManager: options.packageManager ?? "pnpm",
+        name: basename(targetName),
+        destination: resolve(targetName),
+        blueprint: targetBlueprint,
+        packageManager: targetPm,
         testing: "vitest",
         formatter: "biome",
-        git: options.git,
-        githubActions: options.githubActions,
-        docker: options.docker,
+        git: targetGit,
+        githubActions: targetCi,
+        docker: targetDocker,
     };
     const errors = validateConfig(config);
     const blueprint = getBlueprint(config.blueprint);
@@ -57,16 +75,16 @@ export function createProject(name, options) {
         console.log(`Blueprint:       ${blueprint.name}`);
         console.log(`Destination:     ${config.destination}`);
         console.log(`Package manager: ${config.packageManager}`);
-        console.log(`Git:             ${options.git ? "yes" : "no"}`);
-        console.log(`GitHub Actions:  ${options.githubActions ? "yes" : "no"}`);
-        console.log(`Docker:          ${options.docker ? "yes" : "no"}`);
+        console.log(`Git:             ${config.git ? "yes" : "no"}`);
+        console.log(`GitHub Actions:  ${config.githubActions ? "yes" : "no"}`);
+        console.log(`Docker:          ${config.docker ? "yes" : "no"}`);
         console.log("\nWould create:");
         for (const f of files) {
             console.log(`  - ${f.path}`);
         }
         console.log("\nWould install:");
         console.log("  devDependencies: typescript, vitest, @biomejs/biome, @types/node");
-        if (options.git) {
+        if (config.git) {
             console.log("\nWould execute:");
             console.log("  git init");
         }
@@ -84,13 +102,13 @@ export function createProject(name, options) {
             installDependencies(config.packageManager, config.destination);
             console.log("✓ Dependencies installed");
         }
-        if (options.git) {
+        if (config.git) {
             console.log("Initializing Git repository...");
             initGit(config.destination);
             console.log("✓ Git repository initialized");
         }
         console.log("\nDone. Next steps:");
-        console.log(`  cd ${name}`);
+        console.log(`  cd ${targetName}`);
         if (options.skipInstall) {
             console.log(`  ${config.packageManager} install`);
         }

package/dist/src/index.js

@@ -5,7 +5,7 @@ import { blueprints, getBlueprint } from "./blueprints.js";
 const [command, ...args] = process.argv.slice(2);
 switch (command) {
     case "create":
-        runCreate(args);
+        await runCreate(args);
         break;
     case "list":
         listBlueprints();
@@ -23,24 +23,27 @@ switch (command) {
         break;
     case "--version":
     case "-v":
-        console.log("0.1.0");
+        console.log("0.2.1");
         break;
     default:
         console.error(`Unknown command: ${command}`);
         console.error("Run 'genrex --help' for usage.");
         process.exitCode = 1;
 }
-function runCreate(args) {
-    const [name, ...flags] = args;
+async function runCreate(args) {
+    const [firstArg, ...flags] = args;
+    let name = firstArg?.startsWith("-") ? undefined : firstArg;
+    const allFlags = firstArg?.startsWith("-") ? [firstArg, ...flags] : flags;
     const options = {
         dryRun: false,
         skipInstall: false,
         git: false,
         githubActions: false,
         docker: false,
+        interactive: false,
     };
-    for (let index = 0; index < flags.length; index += 1) {
-        const flag = flags[index];
+    for (let index = 0; index < allFlags.length; index += 1) {
+        const flag = allFlags[index];
         if (flag === "--dry-run") {
             options.dryRun = true;
         }
@@ -56,11 +59,14 @@ function runCreate(args) {
         else if (flag === "--docker") {
             options.docker = true;
         }
+        else if (flag === "-i" || flag === "--interactive") {
+            options.interactive = true;
+        }
         else if (flag === "--blueprint") {
-            options.blueprint = flags[++index];
+            options.blueprint = allFlags[++index];
         }
         else if (flag === "--package-manager") {
-            const packageManager = flags[++index];
+            const packageManager = allFlags[++index];
             if (!["npm", "pnpm", "yarn", "bun"].includes(packageManager)) {
                 console.error(`Error: Unsupported package manager '${packageManager}'.`);
                 process.exitCode = 1;
@@ -74,7 +80,7 @@ function runCreate(args) {
             return;
         }
     }
-    createProject(name, options);
+    await createProject(name, options);
 }
 function listBlueprints() {
     console.log("Available blueprints:\n");
@@ -111,19 +117,20 @@ Usage:
   genrex <command> [options]
 
 Commands:
+  create [name]                     Create a project (interactive wizard by default)
   list                              List available blueprints
   info <name>                       Show blueprint details
-  create <name> --dry-run           Preview project generation
   doctor                            Check local environment
 
 Create options:
-  --blueprint <id>                  Blueprint ID (default: ts-cli)
+  -i, --interactive                 Launch interactive prompt wizard
+  --blueprint <id>                  Blueprint ID (ts-cli, node-api, ts-lib)
   --package-manager <manager>       npm, pnpm, yarn, or bun (default: pnpm)
-  --dry-run                         Preview without filesystem changes
-  --skip-install                    Do not install dependencies
   --git                             Initialize a Git repository
   --github-actions                  Generate GitHub Actions CI workflow
   --docker                          Generate Dockerfile & .dockerignore
+  --dry-run                         Preview without filesystem changes
+  --skip-install                    Do not install dependencies
 
 Options:
   -h, --help                        Show help

package/dist/src/pm.js

@@ -5,6 +5,6 @@ export function installDependencies(pm, cwd) {
     execFileSync(cmd, ["install"], {
         cwd,
         stdio: "inherit",
-        shell: false,
+        shell: isWindows,
     });
 }

package/dist/src/prompt.js

@@ -0,0 +1,55 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { blueprints } from "./blueprints.js";
+export async function promptWizard(initialName) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        console.log("\ngenrex — Project Blueprint Engine\n");
+        let name = initialName;
+        if (name) {
+            console.log(`? Project name: ${name}`);
+        }
+        else {
+            while (!name || name.trim() === "") {
+                const answer = await rl.question("? Project name: ");
+                name = answer.trim();
+                if (!name) {
+                    console.log("  Project name cannot be empty.");
+                }
+            }
+        }
+        console.log("\n? Choose a blueprint:");
+        blueprints.forEach((b, i) => {
+            console.log(`  ${i + 1}) ${b.name.padEnd(22)} (${b.id})`);
+        });
+        const bpChoice = await rl.question(`Select [1-${blueprints.length}] (1): `);
+        const bpIndex = Number.parseInt(bpChoice.trim() || "1", 10) - 1;
+        const blueprint = (blueprints[bpIndex] ?? blueprints[0]).id;
+        const pms = ["pnpm", "npm", "yarn", "bun"];
+        console.log("\n? Package manager:");
+        pms.forEach((pm, i) => {
+            console.log(`  ${i + 1}) ${pm}`);
+        });
+        const pmChoice = await rl.question(`Select [1-${pms.length}] (1): `);
+        const pmIndex = Number.parseInt(pmChoice.trim() || "1", 10) - 1;
+        const packageManager = pms[pmIndex] ?? "pnpm";
+        const gitAns = await rl.question("\n? Initialize Git? (Y/n): ");
+        const git = gitAns.trim().toLowerCase() !== "n";
+        const ciAns = await rl.question("? Add GitHub Actions CI? (y/N): ");
+        const githubActions = ciAns.trim().toLowerCase() === "y";
+        const dockerAns = await rl.question("? Add Docker? (y/N): ");
+        const docker = dockerAns.trim().toLowerCase() === "y";
+        console.log();
+        return {
+            name,
+            blueprint,
+            packageManager,
+            git,
+            githubActions,
+            docker,
+        };
+    }
+    finally {
+        rl.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genrex",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Forge production-ready TypeScript projects from blueprints",
   "license": "MIT",
   "type": "module",
@@ -38,5 +38,8 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "dependencies": {
+    "genrex": "^0.1.0"
   }
 }