@lakindu_perera/toren 1.0.2 → 1.0.4

package/README.md

@@ -1,164 +1,247 @@
-# Toren — Codebase Intelligence CLI
+# 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 powerful **codebase intelligence CLI** and **project analysis** tool designed to help developers understand unfamiliar repositories instantly. By running this lightweight **scanner**, you gain immediate insight into the architecture of any software project. It performs robust **framework detection**, identifies critical application start files through **entry point analysis**, and generates a clear **project structure visualization**—all without requiring you to read a single line of code.
+**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 are onboarding to a new team, auditing a complex repository, or looking for a fast **monorepo analyzer**, 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
 
-Toren is built to deliver comprehensive repository insights efficiently:
-
-- **Codebase Scanning**: Recursively walks any project in milliseconds to gather deep architectural insights.
-- **Framework Detection**: Instantly identifies the underlying technologies powering the application.
-- **Entry Point Analysis**: Automatically pinpoints where execution begins (e.g., `index.js`, `main.ts`, `App.tsx`, `Application.java`).
-- **Project Structure Visualization**: Generates a beautiful, hierarchical directory tree right in your terminal.
-- **Monorepo Support**: Gracefully handles complex, multi-package repositories without failing.
-- **Zero Dependencies**: A pure Node.js CLI tool with zero external runtime packages.
-- **Machine-Readable Output**: Full JSON support for seamless integration with other developer tools and AI agents.
+- **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 the **Toren CLI tool** globally via npm to use it across all your local projects:
+Install Toren globally via npm to make the **repository inspection CLI** available anywhere on your machine:
 
 ```bash
 npm install -g @lakindu_perera/toren
 ```
 
-Alternatively, you can run it instantly without global installation:
-
-```bash
-npx @lakindu_perera/toren
-```
-
 **Requirements:** Node.js 18.0.0 or higher.
 
 ---
 
-## Usage Examples
-
-Navigate to your target project folder or point Toren directly to a repository.
-
-Scan the current directory for an instant summary:
-
-```bash
-toren .
-```
+## CLI Usage
 
-Scan and output the analysis in JSON format (ideal for toolchain integrations):
+Toren is designed to be simple and intuitive. Point it at any directory to generate an immediate intelligence report.
 
 ```bash
-toren . --format json
-```
+# Scan a specific path
+toren /path/to/project
 
-Run a deep analysis on the codebase:
+# Scan the current directory
+toren .
 
-```bash
-toren . --analyze
+# Export results in different formats
+toren --format json
+toren --format markdown
+toren --format html
+
+# Save output to a file
+toren --format markdown > PROJECT_REPORT.md
+toren --format html > report.html
+toren --format json > scan.json
+
+# Focused Output Modes (Mutually Exclusive)
+toren --project-type
+toren --frameworks
+toren --entry-points
+toren --structure
+
+# Lifecycle & Help Commands
+toren --help
+toren --version
+toren --doctor
+toren --uninstall
 ```
 
-*Note: You can also point Toren to any absolute or relative path, e.g., `toren ../my-project`.*
+### All Flags
+
+| Flag | Description |
+|------|-------------|
+| `[path]` | Directory to scan. Defaults to the current directory (`.`). |
+| `--project-type` | Show detected project type only. |
+| `--frameworks` | Show detected frameworks only. |
+| `--entry-points` | Show detected entry points only. |
+| `--structure` | Show repository structure only. |
+| `--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.
+> **Note:** Focused output flags (`--project-type`, `--frameworks`, `--entry-points`, `--structure`) are mutually exclusive.
 
 ---
 
-## Supported Frameworks
+## Output Examples
 
-Toren is equipped with highly accurate **framework detection** for modern development stacks. It automatically detects:
+### Focused Output Example
+Sometimes you only need a specific piece of intelligence for use in a script or a quick lookup. Use the focused output flags to bypass the full report:
 
-- **Next.js**
-- **React**
-- **Node.js** (including Express, Fastify, Koa, and TypeScript variants)
-- **Spring Boot** (Java)
-- **Python** (including Pipenv and pyproject.toml setups)
-- **Go**
-- **Rust**
-- **Vue.js**
-- **Angular**
-- **Svelte**
-- **PHP**
-- **Ruby**
-- **Elixir**
+```bash
+$ toren --project-type
+Project Type: Node.js / JavaScript
 
-If a specific marker is not found, Toren intelligently falls back to structural heuristics to identify generic entry points, ensuring you always get meaningful project analysis.
+$ toren --frameworks
+Frameworks:
+- React
 
----
+$ toren --entry-points
+Entry Points:
+- src/main.tsx
+```
 
-## Example Output
+### Console Output Example
+The default `console` format renders a beautiful summary directly in your terminal:
 
-```
-  Toren v1.0.1  —  Codebase Onboarding Intelligence
+```text
+  Toren v1.0.4  —  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 Example
+Generate machine-readable output for scripts, toolchains, or AI context windows by running `toren --format json`:
+
+```json
+{
+  "project": {
+    "path": "./my-react-app",
+    "type": "React",
+    "framework": "React"
+  },
+  "summary": {
+    "totalFiles": 32,
+    "totalFolders": 6,
+    "scanDurationMs": 4
+  },
+  "entryPoints": [
+    "src/main.tsx"
+  ],
+  "structure": [
+    {
+      "type": "folder",
+      "name": "src",
+      "children": [
+        { "type": "file", "name": "App.tsx" },
+        { "type": "file", "name": "main.tsx" }
+      ]
+    },
+    { "type": "file", "name": "package.json" }
+  ]
+}
+```
+
+*Note: You can also generate rich, GitHub-flavored Markdown (`--format markdown`) or self-contained HTML reports (`--format html`) for documentation purposes!*
+
+---
+
+## Architecture
+
+Toren's internal architecture emphasizes modular design, separation of concerns, and a strict **zero dependency** philosophy.
+
+- **`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.
+
+---
+
+## Why Toren Exists
+
+Modern software development moves fast, but **onboarding into large codebases is slow**.
+
+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.
+
+**Toren solves the "first 5 minutes of any repo" problem.**
+
+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.
+
+---
+
+## Roadmap (Future Improvements)
+
+- `.torenignore` configuration file support
+- Dependency graph analysis and visualization
+- Plugin system for custom renderer injection
+- AI-generated natural language project summaries
+
 ---
 
 ## Contributing
 
-Contributions to improve this **repository analyzer** and **developer tool** are welcome!
+Contributions to improve this codebase analyzer CLI are always welcome!
 
-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.
+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
 
-Please ensure any additions maintain the zero-dependency architecture. 
+*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 during your codebase analysis, please consider starring the repository — it helps other developers discover this 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
  * ──────────────────────────
@@ -23,6 +25,7 @@
 import { createRequire } from 'node:module';
 import { scan }          from '../src/scanner/scan.js';
 import renderers         from '../src/renderers/index.js';
+import { getFocusedModeInfo, renderFocusedMode, FOCUSED_FLAGS } from '../src/focused-output.js';
 import { runDoctor, runUninstall } from '../src/lifecycle.js';
 
 const require = createRequire(import.meta.url);
@@ -42,12 +45,20 @@ 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] [options]
+
+\x1b[1mOptions:\x1b[0m
+  --project-type      Show detected project type only
+  --frameworks        Show detected frameworks only
+  --entry-points      Show detected entry points only
+  --structure         Show repository structure only
+  --format <type>     Output as console, json, markdown, or html
+  --include-hidden    Include hidden files and folders
+  --max-files <n>     Set scan file limit
+  --help              Show this help message
+  --version           Show version number
+  --doctor            Run CLI diagnostics
+  --uninstall         Remove Toren global installation
 
 \x1b[1mOutput Formats:\x1b[0m
 ${formatList}
@@ -55,10 +66,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,9 +83,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
  */
 
 /**
@@ -89,18 +104,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')) {
@@ -115,40 +130,93 @@ 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';
   }
 
+  // ── Focused Output Flags ────────────────────────────────────────────────
+  const focusedInfo = getFocusedModeInfo(args);
+  
+  if (focusedInfo.error) {
+    console.error(focusedInfo.message);
+    return { action: 'exit', code: 1 };
+  }
+
+  const focusedMode = focusedInfo.mode;
+
   // ── 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', '--include-hidden']);
-  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',
+    ...FOCUSED_FLAGS,
+    '--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, includeHidden };
+  return { action: 'scan', target, format, includeHidden, maxFiles, focusedMode };
 }
 
 // ---------------------------------------------------------------------------
@@ -183,7 +251,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.
@@ -192,8 +263,16 @@ function assertValidFormat(format) {
   const render = renderers[parsed.format];
 
   try {
-    const result = scan(parsed.target, { includeHidden: parsed.includeHidden });
-    render(result, { cwd: process.cwd() });
+    const result = scan(parsed.target, {
+      includeHidden: parsed.includeHidden,
+      maxFiles:      parsed.maxFiles,
+    });
+    
+    if (parsed.focusedMode) {
+      renderFocusedMode(parsed.focusedMode, result);
+    } else {
+      render(result, { cwd: process.cwd() });
+    }
   } catch (err) {
     // Render errors in the requested format where possible.
     if (parsed.format === 'json') {

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@lakindu_perera/toren",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A powerful codebase scanner CLI tool for project analysis, framework detection, and understanding repository structure instantly.",
   "type": "module",
   "bin": {
     "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 tool",
@@ -25,7 +25,6 @@
     "monorepo analyzer",
     "node cli tool",
     "developer tool",
-    "typescript cli",
     "onboarding"
   ],
   "author": "Lakindu Perera",

package/src/focused-output.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Focused output modes handling for Toren CLI.
+ */
+
+import { renderStructure } from './renderers/console-renderer.js';
+
+export const FOCUSED_FLAGS = [
+  '--project-type',
+  '--frameworks',
+  '--entry-points',
+  '--structure'
+];
+
+/**
+ * Validates focused flags in the provided arguments.
+ * 
+ * @param {string[]} args Process arguments
+ * @returns {{ error: boolean, message?: string, mode?: string|null }}
+ */
+export function getFocusedModeInfo(args) {
+  const activeFlags = FOCUSED_FLAGS.filter(flag => args.includes(flag));
+  
+  if (activeFlags.length > 1) {
+    return {
+      error: true,
+      message: '\x1b[31mError: focused output flags are mutually exclusive. Please use only one of:\x1b[0m\n' + 
+               FOCUSED_FLAGS.map(f => `  ${f}`).join('\n') + '\n'
+    };
+  }
+
+  return {
+    error: false,
+    mode: activeFlags[0] || null
+  };
+}
+
+/**
+ * Renders the scan result based on the active focused mode.
+ * 
+ * @param {string} mode Active focused mode flag
+ * @param {import('./scanner/scan.js').ScanResult} result 
+ */
+export function renderFocusedMode(mode, result) {
+  switch (mode) {
+    case '--project-type':
+      console.log(`Project Type: ${result.projectType}`);
+      break;
+      
+    case '--frameworks':
+      if (!result.projectType || result.projectType === 'Unknown') {
+        console.log('Frameworks: None detected');
+      } else {
+        console.log('Frameworks:');
+        console.log(`- ${result.projectType}`);
+      }
+      break;
+      
+    case '--entry-points':
+      if (!result.entryPoints || result.entryPoints.length === 0) {
+        console.log('Entry Points: None detected');
+      } else {
+        console.log('Entry Points:');
+        result.entryPoints.forEach(ep => console.log(`- ${ep}`));
+      }
+      break;
+      
+    case '--structure':
+      renderStructure(result);
+      break;
+  }
+}

package/src/renderers/console-renderer.js

@@ -99,8 +99,11 @@ function row(label, value, ...valueCodes) {
  * @param {string}            prefix   - Accumulated indentation
  * @param {boolean}           isLast   - Whether this is the last sibling
  * @param {{ count: number, maxReached: boolean }} counter  - Shared mutable file counter
+ * @param {number}            limit    - Max files to render
+ * @param {number}            depth    - Current depth
+ * @param {number}            maxDepth - Max recursion depth
  */
-function renderTree(node, prefix, isLast, counter, depth = 0, maxDepth = 4) {
+function renderTree(node, prefix, isLast, counter, limit = PREVIEW_LIMIT, depth = 0, maxDepth = 4) {
   if (counter.maxReached) return;
   if (depth >= maxDepth) return;
 
@@ -117,7 +120,7 @@ function renderTree(node, prefix, isLast, counter, depth = 0, maxDepth = 4) {
     }
 
     for (let i = 0; i < children.length; i++) {
-      if (counter.count >= PREVIEW_LIMIT) {
+      if (counter.count >= limit) {
         console.log(`${prefix}${extension}└── ${paint('...', C.dim)}`);
         counter.maxReached = true;
         break;
@@ -125,7 +128,7 @@ function renderTree(node, prefix, isLast, counter, depth = 0, maxDepth = 4) {
       // 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);
+      renderTree(children[i], prefix + extension, willBeLast, counter, limit, depth + 1, maxDepth);
       if (counter.maxReached) break;
     }
   } else {
@@ -228,3 +231,28 @@ export function render(result, options = {}) {
   console.log(paint('  ✅  Scan complete.', C.green));
   console.log('');
 }
+
+/**
+ * Render only the project structure for the --structure flag.
+ * 
+ * @param {import('../scanner/scan.js').ScanResult} result
+ */
+export function renderStructure(result) {
+  const { tree, flatFiles } = result;
+
+  console.log(paint('Project Structure:', C.bold, C.white));
+  console.log(paint(`${tree.name || '.'}/`, C.bold, C.blue));
+
+  const counter  = { count: 0, maxReached: false };
+  const children = tree.children ?? [];
+  const limit = flatFiles.length; // No preview limit for focused --structure
+
+  for (let i = 0; i < children.length; i++) {
+    if (counter.count >= limit) {
+      console.log(`└── ${paint('...', C.dim)}`);
+      break;
+    }
+    renderTree(children[i], '', i === children.length - 1, counter, limit, 0, Infinity);
+    if (counter.maxReached) break;
+  }
+}

package/src/scanner/scan.js

@@ -45,6 +45,10 @@ const IGNORED_DIRS = new Set([
   'venv',
   '.idea',
   '.vscode',
+  '.svelte-kit',
+  '.turbo',
+  '.parcel-cache',
+  '.DS_Store'
 ]);
 
 /**
@@ -130,9 +134,10 @@ function shouldIgnore(name, dirent, includeHidden) {
  * @param {string} rootPath     - Absolute path of the scan root (for 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, includeHidden) {
+function walkDirectory(dirPath, rootPath, flatFiles, includeHidden, maxFiles) {
   const name    = path.basename(dirPath);
   let rawRelPath = path.relative(rootPath, dirPath) || '.';
   const relPath = toPosix(rawRelPath);
@@ -149,9 +154,10 @@ function walkDirectory(dirPath, rootPath, flatFiles, includeHidden) {
   let entries;
   try {
     entries = fs.readdirSync(dirPath, { withFileTypes: true });
-  } catch (err) {
-    // Permission-denied or unreadable directory — skip and log warnings instead of failing.
-    console.warn(`[warn] Skipping ${dirPath} (permission denied)`);
+  } 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;
   }
 
@@ -168,10 +174,16 @@ function walkDirectory(dirPath, rootPath, flatFiles, includeHidden) {
 
     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, includeHidden);
+      const childNode = walkDirectory(childPath, rootPath, flatFiles, includeHidden, maxFiles);
       node.children.push(childNode);
     } else if (dirent.isFile()) {
+      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} */
@@ -229,15 +241,16 @@ 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.
   }
@@ -288,8 +301,18 @@ function findEntryPoints(projectType, flatFiles, rootPath) {
         if (validSet.has(f)) { entries.push(f); break; }
       }
     }
-  } else if (projectType === 'React' || projectType === 'Next.js' || projectType === 'Vue.js' || projectType === 'Angular' || projectType === 'Svelte') {
-    const priorities = ['src/main.tsx', 'src/main.jsx', 'pages/_app.tsx', 'app/layout.tsx', 'src/App.tsx', 'index.html'];
+  } 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; }
     }
@@ -311,7 +334,7 @@ function findEntryPoints(projectType, flatFiles, rootPath) {
       }
     }
   } else if (projectType.includes('Python')) {
-    const priorities = ['main.py', 'app.py', '__main__.py'];
+    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; }
     }
@@ -328,25 +351,52 @@ function findEntryPoints(projectType, flatFiles, rootPath) {
         }
       }
     }
+  } 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 missed projects
-    let best = null;
-    let maxScore = -1;
+    // 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|rb|php)$/)) {
+        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 + 
+            const score = (content.match(/import /g) || []).length +
+                          (content.match(/export /g) || []).length +
                           (content.match(/require\(/g) || []).length;
             if (score > maxScore) {
               maxScore = score;
@@ -389,6 +439,7 @@ function countFolders(node) {
 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;
@@ -409,7 +460,7 @@ export function scan(targetPath, options = {}) {
   let totalFolders = 0;
 
   if (stat.isDirectory()) {
-    tree = walkDirectory(rootPath, rootPath, flatFiles, includeHidden);
+    tree = walkDirectory(rootPath, rootPath, flatFiles, includeHidden, maxFiles);
     projectType = detectProjectType(rootPath);
     // Count all directory nodes in the tree (excluding root itself).
     totalFolders = countFolders(tree) - 1;

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
-  };
-}