@lakindu_perera/toren 1.0.1 → 1.0.3

package/README.md

@@ -1,354 +1,220 @@
-# Toren
+# Toren — Codebase Analyzer CLI
 
-> Understand any codebase in seconds.
+> The fastest way to understand any project structure. A zero-dependency codebase scanner CLI for modern developers.
 
 [![npm version](https://img.shields.io/npm/v/@lakindu_perera/toren.svg)](https://www.npmjs.com/package/@lakindu_perera/toren)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-success.svg)](package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 ---
 
 ## What is Toren?
 
-**Toren** is a lightweight, zero-dependency CLI tool that scans a software project and gives you an instant, structured overview — without reading a single line of code.
-
-Drop it into any unfamiliar repository and immediately see:
-
-- What technology stack the project uses
-- Where the application starts (entry points)
-- How many files and folders exist
-- A visual preview of the directory structure
+**Toren** is a fast, lightweight **codebase analyzer CLI** and **project scanner tool** designed to generate instant onboarding intelligence reports. By recursively scanning any local directory, Toren detects the underlying project framework, identifies critical entry points, and visualizes the folder structure—all in milliseconds.
 
-Whether you've just cloned an open-source project, joined a new team, or are reviewing a client's codebase, Toren cuts through the noise and gets you oriented fast.
+Built with zero external dependencies, this **Node.js repository explorer** is the ultimate **developer onboarding tool** to help you conquer the "first 5 minutes" of navigating an unfamiliar repository.
 
 ---
 
 ## Features
 
-- **Fast scanning** — recursively walks a project in milliseconds
-- **Zero external dependencies** — pure Node.js stdlib only
-- **Framework detection** — identifies React, Next.js, Vue, Angular, Go, Rust, Python, and more
-- **Entry point detection** — pinpoints `index.js`, `main.ts`, `App.tsx`, `Application.java`, and other common entry files
-- **File tree preview** — visual directory structure, up to 4 levels deep
-- **Beautiful terminal output** — ANSI-styled, readable at a glance
-- **JSON output** — machine-readable format for scripting and tooling integration
-- **Smart ignore rules** — skips `node_modules`, `.git`, `dist`, `build`, `.venv`, and more
-- **Extensible renderer architecture** — add new output formats without touching core logic
+- **Recursive Project Scanning**: Fast directory traversal using native Node.js APIs.
+- **Framework Detection**: Instantly identifies Node.js, React, Next.js, Vue, Nuxt, Angular, Svelte, Python, Go, Rust, Spring Boot, Ruby, PHP, Elixir and more.
+- **Entry Point Detection**: Automatically pinpoints where execution begins (e.g., `index.js`, `main.ts`, `App.tsx`, `main.go`).
+- **Project Structure Visualizer**: Generates clean, hierarchical file trees.
+- **Multiple Output Formats**: Choose between `console` (default), `json`, `markdown`, or `html` reports.
+- **Zero Dependencies**: A pure Node.js CLI tool with no external runtime packages. Lightning fast install, infinitely secure.
+- **CLI Lifecycle Tools**: Native diagnostic and uninstallation tools (`--doctor`, `--uninstall`).
 
 ---
 
 ## Installation
 
-Install globally with npm:
+Install Toren globally via npm to make the **repository inspection CLI** available anywhere on your machine:
 
 ```bash
 npm install -g @lakindu_perera/toren
 ```
 
-Or run without installing:
-
-```bash
-npx @lakindu_perera/toren
-```
-
 **Requirements:** Node.js 18.0.0 or higher.
 
 ---
 
-## Quick Start
+## CLI Usage
 
-Scan the current directory:
+Toren is designed to be simple and intuitive. Point it at any directory to generate an immediate intelligence report.
 
 ```bash
-toren
-```
+# Scan a specific path
+toren /path/to/project
 
-Scan a specific path:
-
-```bash
+# Scan the current directory
 toren .
-toren ../my-project
-toren /path/to/any/repo
-```
-
-Output results as JSON:
 
-```bash
-toren --json
-```
+# Export results in different formats
+toren --format json
+toren --format markdown
+toren --format html
 
-Check your global installation:
+# Save output to a file
+toren --format markdown > PROJECT_REPORT.md
+toren --format html > report.html
+toren --format json > scan.json
 
-```bash
+# Lifecycle & Help Commands
+toren --help
+toren --version
 toren --doctor
+toren --uninstall
 ```
 
+### All Flags
+
+| Flag | Description |
+|------|-------------|
+| `[path]` | Directory to scan. Defaults to the current directory (`.`). |
+| `--format <type>` | Output format: `console` (default), `json`, `markdown`, `html`. |
+| `--include-hidden` | Include hidden files and dot-directories in the scan. |
+| `--max-files <N>` | Override the default 50,000-file scan limit. |
+| `--help` / `-h` | Show usage information. |
+| `--version` / `-V` | Print the installed version number. |
+| `--doctor` | Diagnose the global installation health. |
+| `--uninstall` | Safely remove Toren from the global npm environment. |
+
+> **Note:** `--format md` is not a valid alias. Use `--format markdown` in full.
+
 ---
 
-## Example Output
+## Output Examples
 
-```
-  Toren v1.0.0  —  Codebase Onboarding Intelligence
+### Console Output Example
+The default `console` format renders a beautiful summary directly in your terminal:
+
+```text
+  Toren v1.0.3  —  Codebase Onboarding Intelligence
 
 🔍  Project Summary
 ────────────────────────────────────────────────────────────────────────────────
-  Path:          ./my-app
-  Project type:  Next.js
-  Total files:   48
-  Total folders: 11
-  Scan duration: 3 ms
+  Path:          ./my-react-app
+  Project type:  React
+  Total files:   32
+  Total folders: 6
+  Scan duration: 4 ms
 
 🚪  Entry Points
 ────────────────────────────────────────────────────────────────────────────────
-  →  src/app/page.tsx
-  →  src/app/layout.tsx
+  →  src/main.tsx
 
 📁  Folder Structure  (first 20 files)
 ────────────────────────────────────────────────────────────────────────────────
-my-app/
+my-react-app/
 ├── public/
-│   └── favicon.ico
+│   └── vite.svg
 ├── src/
-│   ├── app/
-│   │   ├── layout.tsx
-│   │   └── page.tsx
-│   ├── components/
-│   │   ├── Header.tsx
-│   │   └── Footer.tsx
-│   └── lib/
-│       └── utils.ts
-├── .eslintrc.json
-├── next.config.js
+│   ├── assets/
+│   │   └── react.svg
+│   ├── App.css
+│   ├── App.tsx
+│   ├── index.css
+│   └── main.tsx
+├── index.html
 ├── package.json
-└── tsconfig.json
-  … and 28 more file(s) not shown
+└── vite.config.ts
+  … and 21 more file(s) not shown
 
 ────────────────────────────────────────────────────────────────────────────────
   ✅  Scan complete.
 ```
 
----
-
-## JSON Output
-
-Use `toren --json` to get a machine-readable result suitable for piping into other tools:
+### JSON Output Example
+Generate machine-readable output for scripts, toolchains, or AI context windows by running `toren --format json`:
 
 ```json
 {
   "project": {
-    "path": "./my-app",
-    "type": "Next.js",
-    "framework": "Next.js"
+    "path": "./my-react-app",
+    "type": "React",
+    "framework": "React"
   },
   "summary": {
-    "totalFiles": 48,
-    "totalFolders": 11,
-    "scanDurationMs": 3
+    "totalFiles": 32,
+    "totalFolders": 6,
+    "scanDurationMs": 4
   },
   "entryPoints": [
-    "src/app/page.tsx",
-    "src/app/layout.tsx"
+    "src/main.tsx"
   ],
   "structure": [
     {
       "type": "folder",
       "name": "src",
       "children": [
-        {
-          "type": "folder",
-          "name": "app",
-          "children": [
-            { "type": "file", "name": "layout.tsx" },
-            { "type": "file", "name": "page.tsx" }
-          ]
-        }
+        { "type": "file", "name": "App.tsx" },
+        { "type": "file", "name": "main.tsx" }
       ]
     },
-    { "type": "file", "name": "package.json" },
-    { "type": "file", "name": "next.config.js" }
+    { "type": "file", "name": "package.json" }
   ]
 }
 ```
 
----
-
-## Supported Project Types
-
-Toren detects the following project types automatically:
-
-| Marker File                          | Detected Type              |
-|--------------------------------------|----------------------------|
-| `package.json`                       | Node.js / JavaScript       |
-| `package.json` + `next` dep          | Next.js                    |
-| `package.json` + `react` dep         | React                      |
-| `package.json` + `vue` dep           | Vue.js                     |
-| `package.json` + `@angular/core` dep | Angular                    |
-| `package.json` + `svelte` dep        | Svelte                     |
-| `package.json` + `express` dep       | Node.js / Express          |
-| `package.json` + `fastify` dep       | Node.js / Fastify          |
-| `package.json` + `koa` dep           | Node.js / Koa              |
-| `package.json` + `typescript` dep    | Node.js / TypeScript       |
-| `requirements.txt`                   | Python                     |
-| `Pipfile`                            | Python (Pipenv)            |
-| `pyproject.toml`                     | Python (pyproject)         |
-| `go.mod`                             | Go                         |
-| `Cargo.toml`                         | Rust                       |
-| `pom.xml`                            | Java / Spring Boot         |
-| `build.gradle`                       | Java / Gradle              |
-| `composer.json`                      | PHP / Composer             |
-| `Gemfile`                            | Ruby                       |
-| `mix.exs`                            | Elixir                     |
-
-If no marker is found, Toren reports `Unknown` without failing.
+*Note: You can also generate rich, GitHub-flavored Markdown (`--format markdown`) or self-contained HTML reports (`--format html`) for documentation purposes!*
 
 ---
 
-## CLI Reference
-
-| Command              | Description                                      |
-|----------------------|--------------------------------------------------|
-| `toren`              | Scan the current directory                       |
-| `toren [path]`       | Scan a specific directory or file path           |
-| `toren --json`       | Output scan results as formatted JSON            |
-| `toren --version`    | Print the installed version number               |
-| `toren --help`       | Show usage information                           |
-| `toren --doctor`     | Diagnose the global installation health          |
-| `toren --uninstall`  | Guided removal of the global installation        |
-
----
+## Architecture
 
-## Project Structure
+Toren's internal architecture emphasizes modular design, separation of concerns, and a strict **zero dependency** philosophy.
 
-```
-toren/
-├── bin/
-│   └── toren.js          # CLI entry point — argument parsing and orchestration
-├── src/
-│   ├── lifecycle.js      # --doctor and --uninstall command implementations
-│   ├── scanner/
-│   │   └── scan.js       # Core scanning engine — file walker, type detection, entry point detection
-│   └── renderers/
-│       ├── console-renderer.js   # ANSI-styled terminal output
-│       ├── json-renderer.js      # Machine-readable JSON output
-│       └── tree-renderer.js      # Standalone flat-file tree formatter (utility)
-└── package.json
-```
+- **`bin/toren.js`** — The CLI entry point. Handles argument parsing, option validation, and orchestrates the scanning and rendering phases.
+- **`src/scanner/scan.js`** — The core scanning engine. Safely traverses the file system, executes framework detection heuristics, and extracts entry points.
+- **`src/renderers/`** — The output formatting system. A highly decoupled registry of formatters (`console`, `json`, `html`, `markdown`). Each renderer consumes the raw scan data and formats it independently.
+- **`src/lifecycle.js`** — Dedicated install/uninstall diagnostic tools (`--doctor`, `--uninstall`) to ensure the global CLI binary remains healthy.
 
 ---
 
-## How It Works
-
-### 1. Scanner
-
-`src/scanner/scan.js` is the core engine. It takes a target path and recursively walks the file system using Node's `fs.readdirSync`, collecting every file and directory while skipping entries in the ignore list (`node_modules`, `.git`, `dist`, `build`, etc.).
+## Why Toren Exists
 
-The result is an in-memory tree of `DirNode` and `FileNode` objects, along with a flat list of all relative file paths.
+Modern software development moves fast, but **onboarding into large codebases is slow**.
 
-### 2. Framework Detection
+When developers join a new team, review a complex pull request, or audit an open-source project, they waste valuable time manually clicking through folders and reading `package.json` files just to understand the basic structure.
 
-After walking the directory, the scanner checks for known marker files at the project root (e.g. `package.json`, `go.mod`, `Cargo.toml`). For `package.json`, it reads the file and inspects `dependencies`, `devDependencies`, and `peerDependencies` to determine the specific framework (React, Next.js, Vue, Angular, etc.).
+**Toren solves the "first 5 minutes of any repo" problem.**
 
-### 3. Entry Point Detection
-
-During the walk, each filename is checked against a known set of entry points: `index.js`, `index.ts`, `main.py`, `App.tsx`, `Application.java`, `page.tsx`, `layout.tsx`, etc. All matches are collected and surfaced in the output.
-
-### 4. Renderer
-
-The scan result — a plain JavaScript object — is passed to a renderer. Renderers are completely decoupled from the scanner; they only read data and produce output.
-
-### 5. Output
-
-The CLI selects the appropriate renderer based on flags (`--json` → JSON renderer; default → console renderer). Errors are caught and formatted consistently in both modes.
+As a dedicated **developer onboarding tool**, Toren automates the initial discovery phase. In a single command, it tells you exactly what the project is, where the code starts executing, and how the folders are structured. By eliminating the manual guesswork of repository inspection, Toren drastically improves developer productivity.
 
 ---
 
-## Architecture
+## Roadmap (Future Improvements)
 
-```
-CLI (bin/toren.js)
-        │
-        ▼
-  Argument Parser
-        │
-        ▼
-   Scanner (scan.js)
-        │
-        ├── Directory Walker
-        ├── Ignore Filter
-        ├── Framework Detector
-        └── Entry Point Detector
-        │
-        ▼
-   ScanResult (plain object)
-        │
-        ├──────────────────┐
-        ▼                  ▼
-Console Renderer      JSON Renderer
-(ANSI terminal)    (stdout / pipe)
-```
-
-Adding a new output format is as simple as creating a new file in `src/renderers/` and importing it in `bin/toren.js`.
-
----
-
-## Why Toren?
-
-When you encounter a new codebase, the usual approach is to start opening files, guessing at folder names, and reading `package.json` manually. This works — but it's slow and inconsistent.
-
-Toren automates that first pass. In one command, you get a structured summary of what the project is, where it starts, and what's inside. This is especially useful when:
-
-- **Onboarding to a new job** — quickly orient yourself before your first meeting
-- **Reviewing a pull request or open-source repo** — understand the scope at a glance
-- **Auditing a legacy codebase** — know what you're dealing with before diving in
-- **Building tooling** — use `--json` to feed project metadata into scripts or AI tools
-
----
-
-## Roadmap
-
-- [x] Console renderer
-- [x] JSON renderer
-- [x] Framework detection (11+ project types)
-- [x] Entry point detection
-- [x] `--doctor` install health check
-- [x] `--uninstall` guided removal
-- [x] Markdown renderer (`--format markdown`)
-- [x] HTML renderer (`--format html`)
-- [ ] YAML output
-- [ ] `.torenignore` configuration file
-- [ ] Plugin / custom renderer system
-- [ ] Dependency graph analysis
-- [ ] AI-generated project summary
-- [ ] Project health score
-- [ ] Architecture visualisation layer
+- `.torenignore` configuration file support
+- Dependency graph analysis and visualization
+- Plugin system for custom renderer injection
+- AI-generated natural language project summaries
 
 ---
 
 ## Contributing
 
-Contributions are welcome and appreciated.
-
-1. **Fork** this repository
-2. **Create** a feature branch: `git checkout -b feature/my-feature`
-3. **Commit** your changes: `git commit -m "feat: add my feature"`
-4. **Push** to your branch: `git push origin feature/my-feature`
-5. **Open** a pull request
+Contributions to improve this codebase analyzer CLI are always welcome!
 
-For bugs or feature requests, please [open an issue](https://github.com/lakindudev/toren/issues). Try to include a clear description and, for bugs, the output of `toren --doctor`.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-**Code style notes:**
-- Zero external runtime dependencies — keep it that way
-- No TypeScript compilation step — plain ES modules only
-- Keep scanner and renderers strictly decoupled
-- Document public functions with JSDoc
+*Please ensure all new features maintain the strict zero-dependency architecture rule.*
 
 ---
 
-## License
+## 📄 License
 
-[MIT](LICENSE) — free to use, modify, and distribute.
+Distributed under the MIT License. See `LICENSE` for more information.
 
 ---
 
-*If Toren saves you time, consider starring the repository — it helps others discover the project.* ⭐
+## 👨‍💻 Author
+
+Built with by **[Lakindu Perera](https://github.com/lakindudev)**.

package/bin/toren.js

@@ -10,6 +10,8 @@
  *   toren --help              Print usage
  *   toren --doctor            Check global installation health
  *   toren --uninstall         Safely remove global installation
+ *   toren --include-hidden    Include hidden files (dot-files) in scan
+ *   toren --max-files <N>     Override the max file scan limit
  *
  * Adding a new output format
  * ──────────────────────────
@@ -42,12 +44,14 @@ function printHelp() {
   const formatList = SUPPORTED_FORMATS.map(f => `      ${f}`).join('\n');
   console.log(`
 \x1b[1mUsage:\x1b[0m
-  toren [path]              Scan a directory (defaults to current directory)
-  toren --format <type>     Select output format (default: console)
-  toren --help              Show this help message
-  toren --version           Show version number
-  toren --doctor            Check global installation health
-  toren --uninstall         Safely remove global installation
+  toren [path]                Scan a directory (defaults to current directory)
+  toren --format <type>       Select output format (default: console)
+  toren --include-hidden      Include hidden dot-files in the scan
+  toren --max-files <N>       Set max file scan limit (default: 50000)
+  toren --help                Show this help message
+  toren --version             Show version number
+  toren --doctor              Check global installation health
+  toren --uninstall           Safely remove global installation
 
 \x1b[1mOutput Formats:\x1b[0m
 ${formatList}
@@ -55,10 +59,13 @@ ${formatList}
     console is the default.
 
 \x1b[1mExamples:\x1b[0m
-  toren .                   Scan the current directory
-  toren ./my-project        Scan a specific project folder
-  toren --format json       Output results as JSON
-  toren --format json .     Scan a path and output as JSON
+  toren .                              Scan the current directory
+  toren ./my-project                   Scan a specific project folder
+  toren --format json .                Output results as JSON
+  toren --format markdown . > out.md   Save a Markdown report to a file
+  toren --format html . > out.html     Save an HTML report to a file
+  toren --include-hidden .             Include hidden dot-files in scan
+  toren --max-files 100000 .           Override the 50k file scan limit
 `);
 }
 
@@ -69,8 +76,10 @@ ${formatList}
 /**
  * @typedef {Object} ParsedArgs
  * @property {'exit'|'wait'|'scan'} action
- * @property {string}  [target]  - Resolved path to scan
- * @property {string}  [format]  - Renderer format name
+ * @property {string}  [target]        - Resolved path to scan
+ * @property {string}  [format]        - Renderer format name
+ * @property {boolean} [includeHidden] - Whether to include hidden files
+ * @property {number}  [maxFiles]      - Max files to scan
  */
 
 /**
@@ -88,18 +97,18 @@ function parseArgs() {
   // ── Informational flags ─────────────────────────────────────────────────
   if (args.includes('--help') || args.includes('-h')) {
     printHelp();
-    return { action: 'exit' };
+    return { action: 'exit', code: 0 };
   }
 
-  if (args.includes('--version') || args.includes('-v') || args.includes('--v')) {
+  if (args.includes('--version') || args.includes('-V') || args.includes('-v')) {
     console.log(pkg.version);
-    return { action: 'exit' };
+    return { action: 'exit', code: 0 };
   }
 
   // ── Lifecycle commands ──────────────────────────────────────────────────
   if (args.includes('--doctor')) {
     runDoctor(pkg.version);
-    return { action: 'exit' };
+    return { action: 'exit', code: 0 };
   }
 
   if (args.includes('--uninstall')) {
@@ -114,36 +123,82 @@ function parseArgs() {
 
   const formatIdx = args.indexOf('--format');
   if (formatIdx !== -1) {
-    // Accept the token immediately following --format.
-    // If the user omits the value (e.g. toren --format) default is used.
-    format = args[formatIdx + 1] ?? DEFAULT_FORMAT;
+    const nextToken = args[formatIdx + 1];
+    // If the next token is missing or starts with '-', the user omitted the value.
+    if (nextToken === undefined || nextToken.startsWith('-')) {
+      console.error('');
+      console.error('\x1b[31m  --format requires a value.\x1b[0m');
+      console.error('');
+      console.error(`  Supported formats: ${SUPPORTED_FORMATS.join(', ')}`);
+      console.error('');
+      console.error('  Run \x1b[36mtoren --help\x1b[0m for usage.');
+      console.error('');
+      return { action: 'exit', code: 1 };
+    }
+    format = nextToken;
   } else if (args.includes('--json')) {
     format = 'json';
   }
 
+  // ── Hidden files ────────────────────────────────────────────────────────
+  const includeHidden = args.includes('--include-hidden');
+
   // ── Target path ─────────────────────────────────────────────────────────
   // Build the set of tokens that are consumed as values by named flags so
   // we don't accidentally treat them as the positional path argument.
-  // Currently only --format consumes a value token.
   const consumedValues = new Set();
-  if (formatIdx !== -1 && args[formatIdx + 1] !== undefined) {
+  if (formatIdx !== -1 && args[formatIdx + 1] !== undefined && !args[formatIdx + 1].startsWith('-')) {
     consumedValues.add(args[formatIdx + 1]);
   }
 
+  // ── Max files ───────────────────────────────────────────────────────────
+  let maxFiles = undefined;
+  const maxFilesIdx = args.indexOf('--max-files');
+  if (maxFilesIdx !== -1) {
+    const rawVal = args[maxFilesIdx + 1];
+    if (rawVal === undefined || rawVal.startsWith('-')) {
+      console.error('');
+      console.error('\x1b[31m  --max-files requires a numeric value.\x1b[0m');
+      console.error('  Example: toren --max-files 100000');
+      console.error('');
+      return { action: 'exit', code: 1 };
+    }
+    maxFiles = parseInt(rawVal, 10);
+    if (isNaN(maxFiles) || maxFiles < 1) {
+      console.error('');
+      console.error(`\x1b[31m  --max-files must be a positive integer, got: ${rawVal}\x1b[0m`);
+      console.error('');
+      return { action: 'exit', code: 1 };
+    }
+    consumedValues.add(rawVal);
+  }
+
   // First non-flag, non-consumed token is the target path; default to cwd.
   const target = args.find(a => !a.startsWith('-') && !consumedValues.has(a)) ?? '.';
 
   // ── Unknown flag check ──────────────────────────────────────────────────
-  const knownFlags = new Set(['--help', '-h', '--version', '-v', '--v', '--doctor', '--uninstall', '--format', '--json']);
-  const unknownFlag = args.find(a => a.startsWith('-') && !knownFlags.has(a) && !consumedValues.has(a));
-  
+  const knownFlags = new Set([
+    '--help', '-h',
+    '--version', '-V', '-v',
+    '--doctor',
+    '--uninstall',
+    '--format',
+    '--json',
+    '--include-hidden',
+    '--max-files',
+  ]);
+
+  const unknownFlag = args.find(
+    a => a.startsWith('-') && !knownFlags.has(a) && !consumedValues.has(a),
+  );
+
   if (unknownFlag) {
     console.error(`\x1b[31m  Unknown flag: ${unknownFlag}\x1b[0m`);
     console.error(`  Run \x1b[36mtoren --help\x1b[0m for usage.\n`);
-    return { action: 'exit' };
+    return { action: 'exit', code: 1 };
   }
 
-  return { action: 'scan', target, format };
+  return { action: 'scan', target, format, includeHidden, maxFiles };
 }
 
 // ---------------------------------------------------------------------------
@@ -178,7 +233,10 @@ function assertValidFormat(format) {
 
 (function main() {
   const parsed = parseArgs();
-  if (parsed.action === 'exit') process.exit(0);
+
+  if (parsed.action === 'exit') {
+    process.exit(parsed.code ?? 0);
+  }
   if (parsed.action === 'wait') return;
 
   // Validate before scanning — fail fast on bad format names.
@@ -187,7 +245,10 @@ function assertValidFormat(format) {
   const render = renderers[parsed.format];
 
   try {
-    const result = scan(parsed.target);
+    const result = scan(parsed.target, {
+      includeHidden: parsed.includeHidden,
+      maxFiles:      parsed.maxFiles,
+    });
     render(result, { cwd: process.cwd() });
   } catch (err) {
     // Render errors in the requested format where possible.

package/package.json

@@ -1,32 +1,36 @@
 {
   "name": "@lakindu_perera/toren",
-  "version": "1.0.1",
-  "description": "A CLI that analyzes software codebases and generates onboarding insights.",
+  "version": "1.0.3",
+  "description": "A powerful codebase scanner CLI tool for project analysis, framework detection, and understanding repository structure instantly.",
   "type": "module",
   "bin": {
-    "toren": "./bin/toren.js"
+    "toren": "bin/toren.js"
   },
-  "preferGlobal": true,
-  "main": "bin/toren.js",
   "files": [
     "bin",
-    "src"
+    "src",
+    "LICENSE",
+    "README.md"
   ],
   "scripts": {
     "start": "node bin/toren.js",
-    "lint": "node --check bin/toren.js src/scanner/scan.js"
+    "lint": "node --check bin/toren.js src/scanner/scan.js src/lifecycle.js src/renderers/index.js src/renderers/console-renderer.js src/renderers/json-renderer.js src/renderers/markdown-renderer.js src/renderers/html-renderer.js"
   },
   "keywords": [
-    "cli",
-    "codebase",
-    "onboarding",
-    "developer-tool",
-    "scanner"
+    "cli tool",
+    "codebase scanner",
+    "repository analyzer",
+    "project structure viewer",
+    "framework detection",
+    "monorepo analyzer",
+    "node cli tool",
+    "developer tool",
+    "onboarding"
   ],
   "author": "Lakindu Perera",
   "repository": {
     "type": "git",
-    "url": "https://github.com/lakindudev/toren.git"
+    "url": "git+https://github.com/lakindudev/toren.git"
   },
   "bugs": {
     "url": "https://github.com/lakindudev/toren/issues"

package/src/renderers/console-renderer.js

@@ -98,10 +98,10 @@ function row(label, value, ...valueCodes) {
  * @param {import('../scanner/scan.js').DirNode | import('../scanner/scan.js').FileNode} node
  * @param {string}            prefix   - Accumulated indentation
  * @param {boolean}           isLast   - Whether this is the last sibling
- * @param {{ count: number }} counter  - Shared mutable file counter
+ * @param {{ count: number, maxReached: boolean }} counter  - Shared mutable file counter
  */
 function renderTree(node, prefix, isLast, counter, depth = 0, maxDepth = 4) {
-  if (counter.count >= PREVIEW_LIMIT) return;
+  if (counter.maxReached) return;
   if (depth >= maxDepth) return;
 
   const connector = isLast ? '└── ' : '├── ';
@@ -117,8 +117,16 @@ function renderTree(node, prefix, isLast, counter, depth = 0, maxDepth = 4) {
     }
 
     for (let i = 0; i < children.length; i++) {
-      if (counter.count >= PREVIEW_LIMIT) break;
-      renderTree(children[i], prefix + extension, i === children.length - 1, counter, depth + 1, maxDepth);
+      if (counter.count >= PREVIEW_LIMIT) {
+        console.log(`${prefix}${extension}└── ${paint('...', C.dim)}`);
+        counter.maxReached = true;
+        break;
+      }
+      // Check if this child will be the last one we render due to limits
+      let willBeLast = i === children.length - 1;
+      
+      renderTree(children[i], prefix + extension, willBeLast, counter, depth + 1, maxDepth);
+      if (counter.maxReached) break;
     }
   } else {
     console.log(`${prefix}${connector}${paint(node.name, C.white)}`);
@@ -198,11 +206,15 @@ export function render(result, options = {}) {
 
   console.log(paint(`${tree.name || '.'}/`, C.bold, C.blue));
 
-  const counter  = { count: 0 };
+  const counter  = { count: 0, maxReached: false };
   const children = tree.children ?? [];
   for (let i = 0; i < children.length; i++) {
-    if (counter.count >= PREVIEW_LIMIT) break;
+    if (counter.count >= PREVIEW_LIMIT) {
+      console.log(`└── ${paint('...', C.dim)}`);
+      break;
+    }
     renderTree(children[i], '', i === children.length - 1, counter);
+    if (counter.maxReached) break;
   }
 
   if (flatFiles.length > PREVIEW_LIMIT) {

package/src/scanner/scan.js

@@ -8,7 +8,8 @@
  *  - Detect the project type from marker files
  *  - Identify known entry-point files
  *
- * This module is intentionally free of side-effects (no console.log).
+ * This module is intentionally free of side-effects (no console.log),
+ * except for warnings about unreadable directories.
  * All output concerns live in bin/toren.js.
  *
  * Designed to scale into:
@@ -44,6 +45,10 @@ const IGNORED_DIRS = new Set([
   'venv',
   '.idea',
   '.vscode',
+  '.svelte-kit',
+  '.turbo',
+  '.parcel-cache',
+  '.DS_Store'
 ]);
 
 /**
@@ -65,24 +70,6 @@ const PROJECT_TYPE_MARKERS = [
   { marker: 'mix.exs',            label: 'Elixir'                  },
 ];
 
-const ENTRY_POINT_EXACT = new Set([
-  'index.js', 'index.ts', 'index.jsx', 'index.tsx',
-  'main.js', 'main.ts', 'main.jsx', 'main.tsx', 'main.py',
-  'app.js', 'app.ts', 'app.jsx', 'app.tsx', 'App.js', 'App.ts', 'App.jsx', 'App.tsx',
-  'server.js', 'server.ts', 'server.jsx', 'server.tsx',
-  'Application.java', 'Main.java',
-  'page.js', 'page.ts', 'page.jsx', 'page.tsx',
-  'layout.js', 'layout.ts', 'layout.jsx', 'layout.tsx',
-  '_app.js', '_app.ts', '_app.jsx', '_app.tsx',
-  '_document.js', '_document.ts', '_document.jsx', '_document.tsx'
-]);
-
-function isEntryPoint(filename) {
-  if (ENTRY_POINT_EXACT.has(filename)) return true;
-  if (filename.endsWith('Application.java')) return true;
-  return false;
-}
-
 // ---------------------------------------------------------------------------
 // Types (JSDoc — no TypeScript dependency required)
 // ---------------------------------------------------------------------------
@@ -92,7 +79,7 @@ function isEntryPoint(filename) {
  * @property {'file'} type
  * @property {string} name      - Basename of the file
  * @property {string} fullPath  - Absolute path
- * @property {string} relPath   - Path relative to the scanned root
+ * @property {string} relPath   - Path relative to the scanned root (POSIX style)
  */
 
 /**
@@ -100,7 +87,7 @@ function isEntryPoint(filename) {
  * @property {'directory'} type
  * @property {string} name      - Basename of the directory
  * @property {string} fullPath  - Absolute path
- * @property {string} relPath   - Path relative to the scanned root
+ * @property {string} relPath   - Path relative to the scanned root (POSIX style)
  * @property {Array<FileNode|DirNode>} children
  */
 
@@ -119,31 +106,41 @@ function isEntryPoint(filename) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Normalize a path to use POSIX separators ('/').
+ */
+function toPosix(p) {
+  return p.replace(/\\/g, '/');
+}
+
 /**
  * Determine whether a directory entry should be skipped.
  *
  * @param {string} name - Basename of the entry
  * @param {fs.Dirent} dirent
+ * @param {boolean} includeHidden
  * @returns {boolean}
  */
-function shouldIgnore(name, dirent) {
-  if (name.startsWith('.') && dirent.isDirectory()) return true;
+function shouldIgnore(name, dirent, includeHidden) {
+  if (!includeHidden && name.startsWith('.')) return true;
   return IGNORED_DIRS.has(name);
 }
 
 /**
  * Recursively walk `dirPath`, building a DirNode tree.
- * Also populates `flatFiles` and `entryPoints` arrays by reference.
+ * Also populates `flatFiles` array by reference.
  *
  * @param {string} dirPath      - Absolute path of the current directory
  * @param {string} rootPath     - Absolute path of the scan root (for relative paths)
- * @param {Array<string>} flatFiles    - Accumulator for all relative file paths
- * @param {Array<string>} entryPoints  - Accumulator for entry-point relative paths
+ * @param {Array<string>} flatFiles - Accumulator for all relative file paths
+ * @param {boolean} includeHidden - Whether to include hidden files
+ * @param {number} maxFiles - Maximum number of files to scan before aborting
  * @returns {DirNode}
  */
-function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
+function walkDirectory(dirPath, rootPath, flatFiles, includeHidden, maxFiles) {
   const name    = path.basename(dirPath);
-  const relPath = path.relative(rootPath, dirPath) || '.';
+  let rawRelPath = path.relative(rootPath, dirPath) || '.';
+  const relPath = toPosix(rawRelPath);
 
   /** @type {DirNode} */
   const node = {
@@ -159,6 +156,8 @@ function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
     entries = fs.readdirSync(dirPath, { withFileTypes: true });
   } catch {
     // Permission-denied or unreadable directory — skip silently.
+    // Write to stderr so stdout remains clean for piped/redirected output.
+    process.stderr.write(`[toren] warning: skipping unreadable directory: ${dirPath}\n`);
     return node;
   }
 
@@ -171,15 +170,21 @@ function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
   });
 
   for (const dirent of entries) {
-    if (shouldIgnore(dirent.name, dirent)) continue;
+    if (shouldIgnore(dirent.name, dirent, includeHidden)) continue;
 
     const childPath = path.join(dirPath, dirent.name);
 
+    // Explicitly skip symbolic links to prevent infinite loops and unsafe traversals
+    if (dirent.isSymbolicLink()) continue;
+
     if (dirent.isDirectory()) {
-      const childNode = walkDirectory(childPath, rootPath, flatFiles, entryPoints);
+      const childNode = walkDirectory(childPath, rootPath, flatFiles, includeHidden, maxFiles);
       node.children.push(childNode);
     } else if (dirent.isFile()) {
-      const relFilePath = path.relative(rootPath, childPath);
+      if (flatFiles.length >= maxFiles) {
+        throw new Error(`Max file scan limit exceeded (${maxFiles} files). Use --max-files <number> to increase the limit.`);
+      }
+      const relFilePath = toPosix(path.relative(rootPath, childPath));
 
       /** @type {FileNode} */
       const fileNode = {
@@ -191,10 +196,6 @@ function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
 
       node.children.push(fileNode);
       flatFiles.push(relFilePath);
-
-      if (isEntryPoint(dirent.name)) {
-        entryPoints.push(relFilePath);
-      }
     }
   }
 
@@ -240,21 +241,177 @@ function refineNodeProjectType(pkgPath) {
       ...pkg.peerDependencies,
     };
 
-    if (deps['next'])         return 'Next.js';
-    if (deps['react'])        return 'React';
-    if (deps['vue'])          return 'Vue.js';
+    if (deps['next'])          return 'Next.js';
+    if (deps['nuxt'] || deps['nuxt3']) return 'Nuxt.js';
+    if (deps['react'])         return 'React';
+    if (deps['vue'])           return 'Vue.js';
     if (deps['@angular/core']) return 'Angular';
-    if (deps['svelte'])       return 'Svelte';
-    if (deps['express'])      return 'Node.js / Express';
-    if (deps['fastify'])      return 'Node.js / Fastify';
-    if (deps['koa'])          return 'Node.js / Koa';
-    if (deps['typescript'])   return 'Node.js / TypeScript';
+    if (deps['svelte'])        return 'Svelte';
+    if (deps['express'])       return 'Node.js / Express';
+    if (deps['fastify'])       return 'Node.js / Fastify';
+    if (deps['koa'])           return 'Node.js / Koa';
+    if (deps['typescript'])    return 'Node.js / TypeScript';
   } catch {
     // Malformed package.json — fall through.
   }
   return 'Node.js / JavaScript';
 }
 
+// ---------------------------------------------------------------------------
+// Entry Point Heuristics
+// ---------------------------------------------------------------------------
+
+const FALSE_POSITIVES = [
+  '/internal/', '/renderer/', '/renderers/', '/dist/', '/build/', '/generated/', '/node_modules/'
+];
+
+function isFalsePositive(relPath) {
+  const normalized = '/' + relPath + '/'; // relPath is already POSIX
+  if (FALSE_POSITIVES.some(fp => normalized.includes(fp))) return true;
+  if (relPath.includes('.test.') || relPath.includes('.spec.')) return true;
+  // Exclude config files usually not entry points
+  if (relPath.endsWith('.config.js') || relPath.endsWith('.config.ts')) return true;
+  return false;
+}
+
+function findEntryPoints(projectType, flatFiles, rootPath) {
+  let entries = [];
+  const validFiles = flatFiles.filter(f => !isFalsePositive(f));
+  const validSet = new Set(validFiles);
+  
+  if (projectType === 'Node.js / JavaScript' || projectType.startsWith('Node.js')) {
+    try {
+      const pkgPath = path.join(rootPath, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        if (pkg.bin) {
+          if (typeof pkg.bin === 'string') entries.push(pkg.bin);
+          else Object.values(pkg.bin).forEach(b => entries.push(b));
+        }
+        if (pkg.main) entries.push(pkg.main);
+      }
+    } catch {}
+    
+    // Normalize and filter package.json entries to ensure they exist
+    entries = entries.map(e => toPosix(e).replace(/^\.\//, '')).filter(e => validSet.has(e));
+    
+    if (entries.length === 0) {
+      const fallbacks = ['src/index.ts', 'src/index.js', 'lib/index.js', 'index.js'];
+      for (const f of fallbacks) {
+        if (validSet.has(f)) { entries.push(f); break; }
+      }
+    }
+  } else if (
+    projectType === 'React'   || projectType === 'Next.js' ||
+    projectType === 'Nuxt.js' || projectType === 'Vue.js'  ||
+    projectType === 'Angular' || projectType === 'Svelte'
+  ) {
+    const priorities = [
+      'src/main.tsx', 'src/main.jsx', 'src/main.ts', 'src/main.js',
+      'pages/_app.tsx', 'pages/_app.js',
+      'app/layout.tsx', 'app/layout.js',
+      'src/App.tsx', 'src/App.jsx',
+      'index.html',
+    ];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+  } else if (projectType.includes('Java')) {
+    const applicationJava = validFiles.filter(f => f.endsWith('Application.java'));
+    if (applicationJava.length > 0) {
+      entries.push(...applicationJava);
+    } else {
+      for (const f of validFiles) {
+        if (f.endsWith('.java')) {
+          try {
+            const content = fs.readFileSync(path.join(rootPath, f), 'utf8');
+            if (content.includes('public static void main')) {
+              entries.push(f);
+              break;
+            }
+          } catch {}
+        }
+      }
+    }
+  } else if (projectType.includes('Python')) {
+    const priorities = ['main.py', 'app.py', '__main__.py', 'manage.py', 'run.py'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+    if (entries.length === 0) {
+      for (const f of validFiles) {
+        if (f.endsWith('.py')) {
+          try {
+            const content = fs.readFileSync(path.join(rootPath, f), 'utf8');
+            if (content.includes('if __name__ == "__main__":') || content.includes("if __name__ == '__main__':")) {
+              entries.push(f);
+              break;
+            }
+          } catch {}
+        }
+      }
+    }
+  } else if (projectType === 'Go') {
+    const priorities = ['main.go', 'cmd/main.go', 'cmd/api/main.go'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+  } else if (projectType === 'Rust') {
+    const priorities = ['src/main.rs', 'src/lib.rs'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+  } else if (projectType === 'Ruby') {
+    const priorities = ['app.rb', 'main.rb', 'config.ru', 'Rakefile'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+  } else if (projectType === 'PHP / Composer') {
+    const priorities = ['index.php', 'public/index.php', 'src/index.php', 'artisan'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+  } else if (projectType === 'Elixir') {
+    const priorities = ['lib/mix/tasks/run.ex', 'mix.exs'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+  }
+  
+  if (entries.length === 0) {
+    // Fallbacks for Unknown or unrecognised projects.
+    // First try well-known index file patterns.
+    for (const f of validFiles) {
+      if (/^(src\/)?index\.[a-z]+$/.test(f)) {
+        entries.push(f);
+        break;
+      }
+    }
+    // If still empty, pick the file with the highest import/export density.
+    if (entries.length === 0) {
+      let best = null;
+      let maxScore = -1;
+      for (const f of validFiles) {
+        if (f.match(/\.(js|ts|jsx|tsx|py|java|go|rs|rb|php)$/)) {
+          try {
+            const content = fs.readFileSync(path.join(rootPath, f), 'utf8');
+            const score = (content.match(/import /g) || []).length +
+                          (content.match(/export /g) || []).length +
+                          (content.match(/require\(/g) || []).length;
+            if (score > maxScore) {
+              maxScore = score;
+              best = f;
+            }
+          } catch {}
+        }
+      }
+      if (best) entries.push(best);
+    }
+  }
+  
+  return Array.from(new Set(entries));
+}
+
 // ---------------------------------------------------------------------------
 // Tree helpers
 // ---------------------------------------------------------------------------
@@ -279,8 +436,10 @@ function countFolders(node) {
 // Public API
 // ---------------------------------------------------------------------------
 
-export function scan(targetPath) {
+export function scan(targetPath, options = {}) {
   const rootPath = path.resolve(targetPath);
+  const includeHidden = !!options.includeHidden;
+  const maxFiles = options.maxFiles || 50000; // Default cap of 50k files for huge repos
 
   // Validate target
   let stat;
@@ -293,7 +452,7 @@ export function scan(targetPath) {
   /** @type {Array<string>} */
   const flatFiles   = [];
   /** @type {Array<string>} */
-  const entryPoints = [];
+  let entryPoints = [];
 
   const startTime   = performance.now();
   let tree;
@@ -301,12 +460,13 @@ export function scan(targetPath) {
   let totalFolders = 0;
 
   if (stat.isDirectory()) {
-    tree = walkDirectory(rootPath, rootPath, flatFiles, entryPoints);
+    tree = walkDirectory(rootPath, rootPath, flatFiles, includeHidden, maxFiles);
     projectType = detectProjectType(rootPath);
     // Count all directory nodes in the tree (excluding root itself).
     totalFolders = countFolders(tree) - 1;
+    entryPoints = findEntryPoints(projectType, flatFiles, rootPath);
   } else if (stat.isFile()) {
-    const relFilePath = path.basename(rootPath);
+    const relFilePath = toPosix(path.basename(rootPath));
     tree = {
       type: 'directory',
       name: path.basename(path.dirname(rootPath)),
@@ -320,9 +480,7 @@ export function scan(targetPath) {
       }]
     };
     flatFiles.push(relFilePath);
-    if (isEntryPoint(relFilePath)) {
-      entryPoints.push(relFilePath);
-    }
+    entryPoints = [relFilePath]; // A single file is its own entry point
   } else {
     throw new Error(`Path is neither a file nor a directory: ${rootPath}`);
   }

package/src/renderers/tree-renderer.js

@@ -1,67 +0,0 @@
-/**
- * @fileoverview Toren — Tree Renderer
- * 
- * Formats a flat array of file paths into a clean CLI tree view.
- */
-
-/**
- * Converts a flat file list into a hierarchical tree structure and renders it.
- *
- * @param {Array<string>} flatFiles - Array of relative file paths
- * @returns {{ output: string, totalFilesShown: number }}
- */
-export function renderTree(flatFiles) {
-  const root = { type: 'directory', children: {} };
-
-  // 1. Build the tree structure
-  for (const p of flatFiles) {
-    const parts = p.split(/[/\\]/).filter(Boolean);
-    
-    let current = root;
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-      const isFile = i === parts.length - 1;
-      
-      if (!current.children[part]) {
-        current.children[part] = isFile 
-          ? { type: 'file', name: part }
-          : { type: 'directory', name: part, children: {} };
-      }
-      current = current.children[part];
-    }
-  }
-
-  const state = { output: [], filesCount: 0 };
-  
-  // 2. Traverse and format the tree (depth limit 4)
-  function traverse(node, depth) {
-    if (depth >= 4) return;
-    
-    const children = Object.values(node.children || {}).sort((a, b) => {
-      // Directories first, then files
-      if (a.type !== b.type) {
-        return a.type === 'directory' ? -1 : 1;
-      }
-      // Alphabetical sort
-      return a.name.localeCompare(b.name);
-    });
-    
-    for (const child of children) {
-      const indent = '  '.repeat(depth);
-      if (child.type === 'directory') {
-        state.output.push(`${indent}📁 ${child.name}`);
-        traverse(child, depth + 1);
-      } else {
-        state.output.push(`${indent}└── ${child.name}`);
-        state.filesCount++;
-      }
-    }
-  }
-  
-  traverse(root, 0);
-  
-  return {
-    output: state.output.join('\n'),
-    totalFilesShown: state.filesCount
-  };
-}