@lakindu_perera/toren 1.0.5 → 1.0.7

package/README.md

@@ -77,10 +77,10 @@ toren --doctor
 toren --uninstall
 ```
 
-### All Flags
+### CLI Reference
 
-| Flag | Description |
-|------|-------------|
+| Command / Flag | Description |
+|----------------|-------------|
 | `[path]` | Directory to scan. Defaults to the current directory (`.`). |
 | `--project-type` | Show detected project type only. |
 | `--frameworks` | Show detected frameworks only. |
@@ -90,9 +90,9 @@ toren --uninstall
 | `--scripts` | Show available package scripts 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. |
+| `--max-files <n>` | Override the default 50,000-file scan limit. |
+| `--help`, `-h` | Show usage and help message. |
+| `--version`, `-v` | Print the installed version number. |
 | `--doctor` | Diagnose the global installation health. |
 | `--uninstall` | Safely remove Toren from the global npm environment. |
 
@@ -101,57 +101,30 @@ toren --uninstall
 
 ---
 
-## Output Examples
+## Screenshots & Output Examples
 
-### 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:
-
-```bash
-$ toren --project-type
-Project Type: Node.js / JavaScript
-
-$ toren --frameworks
-Frameworks:
-- React
+### Console Output Example
+The default `console` format renders a beautiful summary directly in your terminal:
 
-$ toren --entry-points
-Entry Points:
-- src/main.tsx
+```text
+Toren v1.0.6  —  Codebase Onboarding Intelligence
 
-$ toren --configs
-Configuration Files
-───────────────────
+Project Summary
+───────────────
 
-✓ package.json
-✓ vite.config.ts
+Path:          ./my-react-app
+Project type:  React
+Total files:   32
+Total folders: 6
 
-$ toren --scripts
-Available Scripts
+Entry Points
+────────────
 
-start      node bin/toren.js
-test       node --test
-```
+src/main.tsx
 
-### Console Output Example
-The default `console` format renders a beautiful summary directly in your terminal:
+Folder Structure  (first 20 files)
+──────────────────────────────────
 
-```text
-  Toren v1.0.4  —  Codebase Onboarding Intelligence
-
- Project Summary
-────────────────────────────────────────────────────────────────────────────────
-  Path:          ./my-react-app
-  Project type:  React
-  Total files:   32
-  Total folders: 6
-  Scan duration: 4 ms
-
- Entry Points
-────────────────────────────────────────────────────────────────────────────────
-  →  src/main.tsx
-
- Folder Structure  (first 20 files)
-────────────────────────────────────────────────────────────────────────────────
 my-react-app/
 ├── public/
 │   └── vite.svg
@@ -165,10 +138,46 @@ my-react-app/
 ├── index.html
 ├── package.json
 └── vite.config.ts
-  … and 21 more file(s) not shown
+… and 21 more file(s) not shown
 
-────────────────────────────────────────────────────────────────────────────────
-  Scan complete.
+Scan completed in 4 ms
+```
+
+### Focused Output Examples
+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:
+
+```bash
+$ toren --project-type
+Project Type
+────────────
+
+Node.js / JavaScript
+
+$ toren --frameworks
+Frameworks
+──────────
+
+React
+
+$ toren --entry-points
+Entry Points
+────────────
+
+src/main.tsx
+
+$ toren --configs
+Configuration Files
+───────────────────
+
+package.json
+vite.config.ts
+
+$ toren --scripts
+Package Scripts
+───────────────
+
+start  vite
+test   vitest
 ```
 
 ### JSON Output Example
@@ -207,6 +216,17 @@ Generate machine-readable output for scripts, toolchains, or AI context windows
 
 ---
 
+## Release Notes
+
+### v1.0.6 - CLI Experience Update
+- **Redesigned CLI Output**: Completely revamped the console layout to use minimal typography, bold section titles, and dynamic divider lines matching the title width.
+- **Improved Error Handling**: Transformed raw exceptions into user-friendly error messages outlining the issue and potential fixes, ensuring consistent exit codes.
+- **Enhanced Focused Modes**: Focused output flags (`--configs`, `--entry-points`, `--structure`, etc.) now strictly mirror the design tokens of the full console renderer, providing identical spacing and layouts.
+- **Streamlined Help & Version**: The `--help` interface was fully redesigned for faster reading, and `-v` / `--version` flags were added to output the exact binary version directly from `package.json`.
+- **Accurate Timing Metrics**: Scan duration logic was improved to utilize native timing APIs, precisely measuring execution and printing results natively as "Scan completed in X ms" without clogging the project summary.
+
+---
+
 ## Architecture
 
 Toren's internal architecture emphasizes modular design, separation of concerns, and a strict **zero dependency** philosophy.

package/bin/toren.js

@@ -38,43 +38,56 @@ const DEFAULT_FORMAT = 'console';
 const SUPPORTED_FORMATS = Object.keys(renderers);
 
 // ---------------------------------------------------------------------------
-// Help
+// Helpers
 // ---------------------------------------------------------------------------
 
+function printError(title, message, detailLabel, detailValue) {
+  console.error(`\x1b[31m✖ ${title}\x1b[0m\n`);
+  console.error(`${message}\n`);
+  if (detailLabel && detailValue) {
+    console.error(`${detailLabel}:\n`);
+    console.error(`${detailValue}\n`);
+  }
+}
+
 function printHelp() {
-  const formatList = SUPPORTED_FORMATS.map(f => `      ${f}`).join('\n');
+  const formatList = SUPPORTED_FORMATS.map(f => {
+    const suffix = f === DEFAULT_FORMAT ? '  (default)' : '';
+    return `  --format ${f.padEnd(10)}${suffix}`;
+  }).join('\n');
+
   console.log(`
-\x1b[1mUsage:\x1b[0m
+\x1b[1mToren\x1b[0m v${pkg.version}
+Fast Repository Discovery CLI
+
+\x1b[1mUSAGE\x1b[0m
   toren [path] [options]
 
-\x1b[1mOptions:\x1b[0m
+\x1b[1mCOMMANDS\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
   --configs           Show detected project configuration files
   --scripts           Show available package scripts 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
+  --help              Show this help message
+  --version           Show version number
 
-\x1b[1mOutput Formats:\x1b[0m
+\x1b[1mOUTPUT FORMATS\x1b[0m
 ${formatList}
 
-    console is the default.
-
-\x1b[1mExamples:\x1b[0m
+\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 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
+  toren . --configs                    Show project configuration files
+  toren . --frameworks                 Show detected frameworks
 `);
 }
 
@@ -110,7 +123,7 @@ function parseArgs() {
   }
 
   if (args.includes('--version') || args.includes('-V') || args.includes('-v')) {
-    console.log(pkg.version);
+    console.log(`Toren ${pkg.version}`);
     return { action: 'exit', code: 0 };
   }
 
@@ -135,13 +148,12 @@ function parseArgs() {
     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('');
+      printError(
+        'Missing value',
+        'The --format flag requires a valid output format.',
+        'Supported formats',
+        SUPPORTED_FORMATS.join(', ')
+      );
       return { action: 'exit', code: 1 };
     }
     format = nextToken;
@@ -153,7 +165,7 @@ function parseArgs() {
   const focusedInfo = getFocusedModeInfo(args);
   
   if (focusedInfo.error) {
-    console.error(focusedInfo.message);
+    printError(focusedInfo.title, focusedInfo.message, focusedInfo.detailLabel, focusedInfo.detailValue);
     return { action: 'exit', code: 1 };
   }
 
@@ -176,17 +188,22 @@ function parseArgs() {
   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('');
+      printError(
+        'Missing value',
+        'The --max-files flag requires a numeric value.',
+        'Example',
+        'toren --max-files 100000'
+      );
       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('');
+      printError(
+        'Invalid value',
+        'The --max-files flag must be a positive integer.',
+        'Provided value',
+        rawVal
+      );
       return { action: 'exit', code: 1 };
     }
     consumedValues.add(rawVal);
@@ -213,8 +230,12 @@ function parseArgs() {
   );
 
   if (unknownFlag) {
-    console.error(`\x1b[31m  Unknown flag: ${unknownFlag}\x1b[0m`);
-    console.error(`  Run \x1b[36mtoren --help\x1b[0m for usage.\n`);
+    printError(
+      'Unknown option',
+      'An unrecognized flag was provided.',
+      'Flag',
+      unknownFlag
+    );
     return { action: 'exit', code: 1 };
   }
 
@@ -234,16 +255,12 @@ function parseArgs() {
 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('');
+  printError(
+    'Unsupported output format',
+    'The requested output format is not supported.',
+    'Format',
+    format
+  );
   process.exit(1);
 }
 
@@ -280,9 +297,11 @@ function assertValidFormat(format) {
     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('');
+      if (err.title) {
+        printError(err.title, err.message, err.detailLabel, err.detailValue);
+      } else {
+        printError('Scan failed', err.message);
+      }
     }
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakindu_perera/toren",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "A powerful codebase scanner CLI tool for project analysis, framework detection, and understanding repository structure instantly.",
   "type": "module",
   "bin": {

package/src/focused-output.js

@@ -1,9 +1,33 @@
 /**
- * @fileoverview Focused output modes handling for Toren CLI.
+ * @fileoverview Toren — Focused Output Mode Handler
+ *
+ * Handles the six focused output flags:
+ *   --project-type  --frameworks  --entry-points
+ *   --structure     --configs     --scripts
+ *
+ * Design contract:
+ *  - Each flag renders exactly one section to stdout using the console visual
+ *    style (ANSI colours, section header + divider).
+ *  - Empty-state messages are canonical strings declared in EMPTY below.
+ *    They must end with a period and stay in sync with console-renderer.js.
+ *  - No business logic. All data comes from the ScanResult passed in.
+ *  - Stateless: renderFocusedMode() may be called multiple times safely.
  */
 
 import { renderStructure } from './renderers/console-renderer.js';
 
+// ---------------------------------------------------------------------------
+// Canonical empty-state messages
+// Keep these in sync with the equivalent strings in console-renderer.js.
+// ---------------------------------------------------------------------------
+
+const EMPTY = {
+  frameworks:  'No frameworks detected.',
+  entryPoints: 'No entry points detected.',
+  configs:     'No configuration files detected.',
+  scripts:     'No package scripts detected.',
+};
+
 export const FOCUSED_FLAGS = [
   '--project-type',
   '--frameworks',
@@ -25,8 +49,10 @@ export function getFocusedModeInfo(args) {
   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'
+      title: 'Conflicting options',
+      message: 'Focused output flags are mutually exclusive.',
+      detailLabel: 'Provided flags',
+      detailValue: activeFlags.join(', ')
     };
   }
 
@@ -36,6 +62,37 @@ export function getFocusedModeInfo(args) {
   };
 }
 
+/**
+ * Print a bold-white section title followed by a dim matched-length divider
+ * and a blank line — same visual pattern as console-renderer.js's section().
+ *
+ * @param {string} title
+ */
+function printSectionHeader(title) {
+  console.log(`\x1b[1m\x1b[97m${title}\x1b[0m`);
+  console.log(`\x1b[2m${'─'.repeat(title.length)}\x1b[0m`);
+  console.log('');
+}
+
+/**
+ * Print a focused section: header, then items or an empty-state message.
+ *
+ * @param {string}   title    - Section heading
+ * @param {string[]} items    - Pre-formatted lines to print
+ * @param {string}   emptyMsg - Canonical empty-state message (ends with '.')
+ */
+function section(title, items, emptyMsg) {
+  printSectionHeader(title);
+
+  if (!items || items.length === 0) {
+    console.log(`\x1b[2m${emptyMsg}\x1b[0m`);
+  } else {
+    for (const item of items) {
+      console.log(item);
+    }
+  }
+}
+
 /**
  * Renders the scan result based on the active focused mode.
  * 
@@ -44,53 +101,46 @@ export function getFocusedModeInfo(args) {
  */
 export function renderFocusedMode(mode, result) {
   switch (mode) {
-    case '--project-type':
-      console.log(`Project Type: ${result.projectType}`);
+    case '--project-type': {
+      // projectType is always a string; 'Unknown' when undetected.
+      section('Project Type', [result.projectType], 'Unknown');
       break;
-      
-    case '--frameworks':
-      if (!result.projectType || result.projectType === 'Unknown') {
-        console.log('Frameworks: None detected');
-      } else {
-        console.log('Frameworks:');
-        console.log(`- ${result.projectType}`);
-      }
+    }
+
+    case '--frameworks': {
+      const frameworks = (!result.projectType || result.projectType === 'Unknown')
+        ? []
+        : [result.projectType];
+      section('Frameworks', frameworks, EMPTY.frameworks);
       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}`));
-      }
+    }
+
+    case '--entry-points': {
+      section('Entry Points', result.entryPoints || [], EMPTY.entryPoints);
       break;
-      
-    case '--structure':
+    }
+
+    case '--structure': {
       renderStructure(result);
       break;
-      
-    case '--configs':
-      console.log('Configuration Files');
-      console.log('───────────────────\n');
-      if (!result.configs || result.configs.length === 0) {
-        console.log('No configuration files detected.');
-      } else {
-        result.configs.forEach(c => console.log(`✓ ${c}`));
-      }
+    }
+
+    case '--configs': {
+      section('Configuration Files', result.configs || [], EMPTY.configs);
       break;
+    }
 
-    case '--scripts':
-      console.log('Available Scripts\n');
-      if (!result.scripts || result.scripts.length === 0) {
-        console.log('No scripts found');
-      } else {
+    case '--scripts': {
+      const scriptsList = [];
+      if (result.scripts && result.scripts.length > 0) {
         const maxNameLen = Math.max(...result.scripts.map(s => s.name.length));
-        result.scripts.forEach(s => {
-          const paddedName = s.name.padEnd(maxNameLen + 6, ' ');
-          console.log(`${paddedName}${s.command}`);
-        });
+        for (const s of result.scripts) {
+          const paddedName = s.name.padEnd(maxNameLen, ' ');
+          scriptsList.push(`\x1b[97m${paddedName}\x1b[0m  \x1b[2m${s.command}\x1b[0m`);
+        }
       }
+      section('Package Scripts', scriptsList, EMPTY.scripts);
       break;
+    }
   }
 }