@lakindu_perera/toren 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lakindu Perera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,354 @@
+# Toren
+
+> Understand any codebase in seconds.
+
+[![npm version](https://img.shields.io/npm/v/toren.svg)](https://www.npmjs.com/package/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)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-success.svg)](package.json)
+
+---
+
+## 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
+
+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.
+
+---
+
+## 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
+
+---
+
+## Installation
+
+Install globally with npm:
+
+```bash
+npm install -g toren
+```
+
+Or run without installing:
+
+```bash
+npx toren
+```
+
+**Requirements:** Node.js 18.0.0 or higher.
+
+---
+
+## Quick Start
+
+Scan the current directory:
+
+```bash
+toren
+```
+
+Scan a specific path:
+
+```bash
+toren .
+toren ../my-project
+toren /path/to/any/repo
+```
+
+Output results as JSON:
+
+```bash
+toren --json
+```
+
+Check your global installation:
+
+```bash
+toren --doctor
+```
+
+---
+
+## Example Output
+
+```
+  Toren v1.0.0  —  Codebase Onboarding Intelligence
+
+🔍  Project Summary
+────────────────────────────────────────────────────────────────────────────────
+  Path:          ./my-app
+  Project type:  Next.js
+  Total files:   48
+  Total folders: 11
+  Scan duration: 3 ms
+
+🚪  Entry Points
+────────────────────────────────────────────────────────────────────────────────
+  →  src/app/page.tsx
+  →  src/app/layout.tsx
+
+📁  Folder Structure  (first 20 files)
+────────────────────────────────────────────────────────────────────────────────
+my-app/
+├── public/
+│   └── favicon.ico
+├── src/
+│   ├── app/
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── components/
+│   │   ├── Header.tsx
+│   │   └── Footer.tsx
+│   └── lib/
+│       └── utils.ts
+├── .eslintrc.json
+├── next.config.js
+├── package.json
+└── tsconfig.json
+  … and 28 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
+{
+  "project": {
+    "path": "./my-app",
+    "type": "Next.js",
+    "framework": "Next.js"
+  },
+  "summary": {
+    "totalFiles": 48,
+    "totalFolders": 11,
+    "scanDurationMs": 3
+  },
+  "entryPoints": [
+    "src/app/page.tsx",
+    "src/app/layout.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": "package.json" },
+    { "type": "file", "name": "next.config.js" }
+  ]
+}
+```
+
+---
+
+## 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.
+
+---
+
+## 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        |
+
+---
+
+## Project Structure
+
+```
+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
+```
+
+---
+
+## 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.).
+
+The result is an in-memory tree of `DirNode` and `FileNode` objects, along with a flat list of all relative file paths.
+
+### 2. Framework Detection
+
+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.).
+
+### 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.
+
+---
+
+## Architecture
+
+```
+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 md`)
+- [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
+
+---
+
+## 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
+
+For bugs or feature requests, please [open an issue](https://github.com/your-username/toren/issues). Try to include a clear description and, for bugs, the output of `toren --doctor`.
+
+**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
+
+---
+
+## License
+
+[MIT](LICENSE) — free to use, modify, and distribute.
+
+---
+
+*If Toren saves you time, consider starring the repository — it helps others discover the project.* ⭐

package/bin/toren.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Toren CLI — Entry Point
+ *
+ * Usage:
+ *   toren [path]              Scan <path> (defaults to current directory)
+ *   toren --format <type>     Select output format (default: console)
+ *   toren --json              Legacy alias for --format json
+ *   toren --version           Print version
+ *   toren --help              Print usage
+ *   toren --doctor            Check global installation health
+ *   toren --uninstall         Safely remove global installation
+ *
+ * Adding a new output format
+ * ──────────────────────────
+ *   1. Create src/renderers/<format>-renderer.js
+ *      and export: render(result, options?) => void
+ *   2. Register it in src/renderers/index.js
+ *
+ *   No changes to this file are required.
+ */
+
+import { createRequire } from 'node:module';
+import { scan }          from '../src/scanner/scan.js';
+import renderers         from '../src/renderers/index.js';
+import { runDoctor, runUninstall } from '../src/lifecycle.js';
+
+const require = createRequire(import.meta.url);
+const pkg     = require('../package.json');
+
+/** Format used when no --format flag is supplied. */
+const DEFAULT_FORMAT = 'console';
+
+/** Derived from the registry — always in sync with available renderers. */
+const SUPPORTED_FORMATS = Object.keys(renderers);
+
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+
+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
+
+\x1b[1mOutput Formats:\x1b[0m
+${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
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} ParsedArgs
+ * @property {'exit'|'wait'|'scan'} action
+ * @property {string}  [target]  - Resolved path to scan
+ * @property {string}  [format]  - Renderer format name
+ */
+
+/**
+ * Parse process.argv into a structured options object.
+ *
+ * Returns { action: 'exit' } when the process should exit immediately.
+ * Returns { action: 'wait' } when an async interactive command is running.
+ * Returns { action: 'scan', target, format } for normal scan operations.
+ *
+ * @returns {ParsedArgs}
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+
+  // ── Informational flags ─────────────────────────────────────────────────
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return { action: 'exit' };
+  }
+
+  if (args.includes('--version') || args.includes('-v') || args.includes('--v')) {
+    console.log(pkg.version);
+    return { action: 'exit' };
+  }
+
+  // ── Lifecycle commands ──────────────────────────────────────────────────
+  if (args.includes('--doctor')) {
+    runDoctor(pkg.version);
+    return { action: 'exit' };
+  }
+
+  if (args.includes('--uninstall')) {
+    runUninstall();
+    return { action: 'wait' };
+  }
+
+  // ── Output format ───────────────────────────────────────────────────────
+  // --json is a legacy alias for --format json, kept for backwards
+  // compatibility. It will be removed in a future major version.
+  let format = DEFAULT_FORMAT;
+
+  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;
+  } else if (args.includes('--json')) {
+    format = 'json';
+  }
+
+  // ── 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) {
+    consumedValues.add(args[formatIdx + 1]);
+  }
+
+  // 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));
+  
+  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: 'scan', target, format };
+}
+
+// ---------------------------------------------------------------------------
+// Format validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that `format` has a registered renderer.
+ * Prints a descriptive error message and exits with code 1 if not found.
+ *
+ * @param {string} format
+ */
+function assertValidFormat(format) {
+  if (renderers[format]) return;
+
+  const list = SUPPORTED_FORMATS.map(f => `  • ${f}`).join('\n');
+  console.error('');
+  console.error(`\x1b[31m  Unknown output format: ${format}\x1b[0m`);
+  console.error('');
+  console.error('  Supported formats:');
+  console.error('');
+  console.error(list);
+  console.error('');
+  console.error('  Run \x1b[36mtoren --help\x1b[0m for usage.');
+  console.error('');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+(function main() {
+  const parsed = parseArgs();
+  if (parsed.action === 'exit') process.exit(0);
+  if (parsed.action === 'wait') return;
+
+  // Validate before scanning — fail fast on bad format names.
+  assertValidFormat(parsed.format);
+
+  const render = renderers[parsed.format];
+
+  try {
+    const result = scan(parsed.target);
+    render(result, { cwd: process.cwd() });
+  } catch (err) {
+    // Render errors in the requested format where possible.
+    if (parsed.format === 'json') {
+      console.error(JSON.stringify({ error: err.message }, null, 2));
+    } else {
+      console.error('');
+      console.error(`\x1b[31m  ❌  Error: ${err.message}\x1b[0m`);
+      console.error('');
+    }
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@lakindu_perera/toren",
+  "version": "1.0.0",
+  "description": "A CLI that analyzes software codebases and generates onboarding insights.",
+  "type": "module",
+  "bin": {
+    "toren": "./bin/toren.js"
+  },
+  "preferGlobal": true,
+  "main": "bin/toren.js",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "node bin/toren.js",
+    "lint": "node --check bin/toren.js src/scanner/scan.js"
+  },
+  "keywords": [
+    "cli",
+    "codebase",
+    "onboarding",
+    "developer-tool",
+    "scanner"
+  ],
+  "author": "Lakindu Perera",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lakindudev/toren.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lakindudev/toren/issues"
+  },
+  "homepage": "https://github.com/lakindudev/toren#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}