folder-tree-print 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# folder-tree-print
+
+A zero-dependency CLI tool that prints your folder structure as a beautiful, colorized tree. Great for LLM context, README docs, and sharing project layouts.
+
+## What it does
+
+Running `folder-tree-print` in any directory prints a tree view of its contents:
+
+```
+my-project/
+├── src/
+│   ├── components/
+│   │   ├── Header.tsx
+│   │   └── Footer.tsx
+│   ├── utils/
+│   │   └── helpers.ts
+│   └── index.ts
+├── package.json
+├── tsconfig.json
+└── README.md
+
+3 directories, 6 files
+```
+
+It automatically colorizes output (directories in blue, symlinks in cyan, executables in green), sorts directories before files, and skips common noise like `node_modules` and `.git`.
+
+## Install
+
+```bash
+npm install -g folder-tree-print
+```
+
+Or run directly with npx:
+
+```bash
+npx folder-tree-print
+```
+
+## Usage
+
+```bash
+# Current directory
+folder-tree
+
+# Specific folder
+folder-tree-print ./src
+
+# Limit depth
+folder-tree-print -L 3
+
+# Include hidden files, ignore specific folders
+folder-tree-print -a -I logs -I tmp
+
+# Directories only
+folder-tree-print --dirs-only
+
+# JSON output (great for piping)
+folder-tree-print --json > structure.json
+
+# Flat list
+folder-tree-print --flat
+
+# ASCII mode for legacy terminals
+folder-tree-print --ascii
+
+# Combine flags
+folder-tree-print ./src -L 2 -d --no-color
+```
+
+## Configuration
+
+The script includes a `CONFIG` object at the top of the file that you can edit before running. Here's the full reference:
+
+### Display Format
+
+| Option          | Default    | Description                                                                      |
+| --------------- | ---------- | -------------------------------------------------------------------------------- |
+| `displayFormat` | `"tree"`   | `"tree"` for box-drawing tree, `"flat"` for flat paths, `"json"` for JSON output |
+| `treeStyle`     | `"unicode"`| `"unicode"` for `├── └──`, `"ascii"` for `+-- \`--` (legacy terminal fallback)   |
+
+### Sorting
+
+| Option      | Default        | Description                                                                      |
+| ----------- | -------------- | -------------------------------------------------------------------------------- |
+| `sortOrder` | `"dirs-first"` | `"dirs-first"` groups dirs above files, `"alpha"` pure alphabetical, `"none"` filesystem order |
+
+### Filtering
+
+| Option              | Default | Description                                                      |
+| ------------------- | ------- | ---------------------------------------------------------------- |
+| `showHidden`        | `false` | Show hidden files and directories (dotfiles)                     |
+| `dirsOnly`          | `false` | Show only directories, hide all files                            |
+| `maxDepth`          | `0`     | Maximum depth to traverse (`0` = no limit)                       |
+| `extraSkipDirs`     | `[]`    | Additional directories to skip (merged with built-in list)       |
+| `extraSkipFiles`    | `[]`    | Additional files to skip (merged with built-in list)             |
+| `onlyExtensions`    | `[]`    | Only show files matching these extensions (empty = all)          |
+| `excludeExtensions` | `[]`    | Hide files matching these extensions                             |
+
+### Colors
+
+| Option     | Default | Description                                                          |
+| ---------- | ------- | -------------------------------------------------------------------- |
+| `colorize` | `true`  | Enable colored output (blue dirs, cyan symlinks, green executables)   |
+
+### Output
+
+| Option        | Default | Description                                          |
+| ------------- | ------- | ---------------------------------------------------- |
+| `showSummary` | `true`  | Show summary line at the end ("X directories, Y files") |
+
+### Example Configurations
+
+**Only show TypeScript and JavaScript files:**
+
+```js
+onlyExtensions: ["ts", "tsx", "js", "jsx"],
+```
+
+**Use ASCII tree characters for CI logs:**
+
+```js
+treeStyle: "ascii",
+colorize: false,
+```
+
+**Shallow overview with no files:**
+
+```js
+dirsOnly: true,
+maxDepth: 2,
+```
+
+## CLI Options
+
+| Flag           | Short | Description                                  |
+| -------------- | ----- | -------------------------------------------- |
+| `--help`       | `-h`  | Show help message                            |
+| `--all`        | `-a`  | Include hidden files (dotfiles)              |
+| `--dirs-only`  | `-d`  | Show only directories                        |
+| `--depth <n>`  | `-L`  | Limit tree depth                             |
+| `--ignore <s>` | `-I`  | Ignore matching names (repeatable)           |
+| `--no-color`   |       | Disable colored output                       |
+| `--no-summary` |       | Hide the summary line                        |
+| `--flat`       |       | Flat list instead of tree                    |
+| `--json`       |       | Output as JSON                               |
+| `--ascii`      |       | Use ASCII characters instead of Unicode      |
+
+## Behavior
+
+- **Color-coded** — directories (blue), symlinks (cyan with → target), executables (green).
+- **Smart defaults** — auto-skips `node_modules`, `.git`, `.next`, `dist`, `build`, `vendor`, `__pycache__`, `.idea`, `.vscode`, and more.
+- **Sorted output** — directories listed before files, alphabetical within each group.
+- **Symlink-aware** — displays symlink targets with `→` arrows.
+- **Plural-correct summary** — "1 directory, 1 file" vs "3 directories, 12 files".
+- **Configurable** — edit the `CONFIG` object for persistent preferences, or use CLI flags for one-off runs.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+// ============================================================================
+// CONFIGURATION - Edit this object to alter script behavior before running
+// ============================================================================
+const CONFIG = {
+  // --- Display Format ---
+  // "tree"  → classic tree with box-drawing characters (├── └── │)
+  // "flat"  → flat list of relative paths
+  // "json"  → JSON object output
+  displayFormat: "tree",
+
+  // --- Tree Characters ---
+  // "unicode" → ├── └── │ (works in most modern terminals)
+  // "ascii"   → +-- `-- |  (safe fallback for legacy terminals)
+  treeStyle: "unicode",
+
+  // --- Sorting ---
+  // "dirs-first" → directories listed before files, alphabetical within each
+  // "alpha"      → pure alphabetical, no grouping
+  // "none"       → filesystem order (as returned by readdir)
+  sortOrder: "dirs-first",
+
+  // --- Filtering ---
+  // Show hidden files and directories (dotfiles)
+  showHidden: false,
+
+  // Show only directories, hide all files
+  dirsOnly: false,
+
+  // Maximum depth to traverse (0 = no limit)
+  maxDepth: 0,
+
+  // Extra directories to skip (merged with built-in SKIP_DIRS)
+  extraSkipDirs: [],
+
+  // Extra files to skip (merged with built-in SKIP_FILES)
+  extraSkipFiles: [],
+
+  // Only show files matching these extensions (empty = show all)
+  // e.g. ["js", "ts", "tsx"] — directories are always shown
+  onlyExtensions: [],
+
+  // Hide files matching these extensions
+  excludeExtensions: [],
+
+  // --- Colors ---
+  // Enable colored output (directory names in blue, symlinks in cyan, etc.)
+  colorize: true,
+
+  // --- Output ---
+  // Show summary line at the end ("X directories, Y files")
+  showSummary: true,
+};
+
+// ============================================================================
+// TREE CHARACTER SETS
+// ============================================================================
+const TREE_CHARS = {
+  unicode: {
+    TEE: "├── ",
+    LAST: "└── ",
+    PIPE: "│   ",
+    SPACE: "    ",
+  },
+  ascii: {
+    TEE: "+-- ",
+    LAST: "`-- ",
+    PIPE: "|   ",
+    SPACE: "    ",
+  },
+};
+
+// ============================================================================
+// DEFAULT SKIP LISTS
+// ============================================================================
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", ".next", ".nuxt", "dist", "build",
+  ".cache", ".turbo", "vendor", "__pycache__", ".pytest_cache",
+  ".venv", "venv", ".idea", ".vscode", "coverage", ".nyc_output",
+  ".parcel-cache",
+  ...CONFIG.extraSkipDirs,
+]);
+
+const SKIP_FILES = new Set([
+  ".DS_Store", "Thumbs.db",
+  ...CONFIG.extraSkipFiles,
+]);
+
+// ============================================================================
+// COLOR DEFINITIONS
+// ============================================================================
+function getColors(enabled) {
+  if (!enabled) {
+    return { reset: "", bold: "", dim: "", dir: "", file: "", sym: "", exec: "" };
+  }
+  return {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    dir: "\x1b[1;34m",   // bold blue
+    file: "\x1b[0m",     // default
+    sym: "\x1b[1;36m",   // bold cyan
+    exec: "\x1b[1;32m",  // bold green
+  };
+}
+
+// ============================================================================
+// CLI ARGUMENT PARSING
+// ============================================================================
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    help: false,
+    all: false,
+    dirsOnly: false,
+    noColor: false,
+    flat: false,
+    json: false,
+    ascii: false,
+    noSummary: false,
+  };
+  const ignore = [];
+  let depth = 0;
+  let targetDir = null;
+
+  const consumed = new Set();
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--help" || arg === "-h") { flags.help = true; consumed.add(i); }
+    else if (arg === "--all" || arg === "-a") { flags.all = true; consumed.add(i); }
+    else if (arg === "--dirs-only" || arg === "-d") { flags.dirsOnly = true; consumed.add(i); }
+    else if (arg === "--no-color") { flags.noColor = true; consumed.add(i); }
+    else if (arg === "--flat") { flags.flat = true; consumed.add(i); }
+    else if (arg === "--json") { flags.json = true; consumed.add(i); }
+    else if (arg === "--ascii") { flags.ascii = true; consumed.add(i); }
+    else if (arg === "--no-summary") { flags.noSummary = true; consumed.add(i); }
+    else if (arg === "--depth" || arg === "-L") {
+      consumed.add(i);
+      if (i + 1 < args.length) {
+        depth = parseInt(args[i + 1], 10);
+        consumed.add(i + 1);
+        i++;
+      }
+    }
+    else if (arg === "--ignore" || arg === "-I") {
+      consumed.add(i);
+      if (i + 1 < args.length) {
+        ignore.push(args[i + 1]);
+        consumed.add(i + 1);
+        i++;
+      }
+    }
+  }
+
+  // First non-consumed, non-flag argument is the target directory
+  for (let i = 0; i < args.length; i++) {
+    if (!consumed.has(i) && !args[i].startsWith("-")) {
+      targetDir = args[i];
+      break;
+    }
+  }
+
+  return { flags, ignore, depth, targetDir: targetDir || "." };
+}
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function shouldIgnore(name, ignoreSet) {
+  if (!CONFIG.showHidden && name.startsWith(".")) return true;
+  return ignoreSet.has(name);
+}
+
+function shouldShowFile(name) {
+  if (CONFIG.dirsOnly) return false;
+
+  const ext = path.extname(name).slice(1).toLowerCase();
+
+  if (CONFIG.onlyExtensions.length > 0 && !CONFIG.onlyExtensions.includes(ext)) {
+    return false;
+  }
+  if (CONFIG.excludeExtensions.includes(ext)) {
+    return false;
+  }
+
+  return true;
+}
+
+function getEntries(dirPath, ignoreSet) {
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    return entries
+      .filter((e) => !shouldIgnore(e.name, ignoreSet))
+      .filter((e) => e.isDirectory() || e.isSymbolicLink() || shouldShowFile(e.name))
+      .sort((a, b) => {
+        if (CONFIG.sortOrder === "none") return 0;
+        if (CONFIG.sortOrder === "dirs-first") {
+          if (a.isDirectory() && !b.isDirectory()) return -1;
+          if (!a.isDirectory() && b.isDirectory()) return 1;
+        }
+        return a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+      });
+  } catch {
+    return [];
+  }
+}
+
+function formatEntryName(entry, fullPath, colors) {
+  const name = entry.name;
+
+  if (entry.isSymbolicLink()) {
+    try {
+      const target = fs.readlinkSync(fullPath);
+      return `${colors.sym}${name}${colors.reset} ${colors.dim}→ ${target}${colors.reset}`;
+    } catch {
+      return `${colors.sym}${name}${colors.reset}`;
+    }
+  }
+
+  if (entry.isDirectory()) {
+    return `${colors.dir}${name}/${colors.reset}`;
+  }
+
+  // Check if executable
+  try {
+    fs.accessSync(fullPath, fs.constants.X_OK);
+    const suffix = process.platform !== "win32" ? "*" : "";
+    return `${colors.exec}${name}${suffix}${colors.reset}`;
+  } catch {
+    return `${colors.file}${name}${colors.reset}`;
+  }
+}
+
+// ============================================================================
+// DISPLAY: TREE FORMAT
+// ============================================================================
+
+function printTree(dirPath, prefix, depth, ignoreSet, colors, chars, stats) {
+  if (CONFIG.maxDepth > 0 && depth >= CONFIG.maxDepth) return;
+
+  const entries = getEntries(dirPath, ignoreSet);
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const isLast = i === entries.length - 1;
+    const connector = isLast ? chars.LAST : chars.TEE;
+    const fullPath = path.join(dirPath, entry.name);
+    const display = formatEntryName(entry, fullPath, colors);
+
+    console.log(`${colors.dim}${prefix}${connector}${colors.reset}${display}`);
+
+    if (entry.isDirectory()) {
+      stats.dirs++;
+      const newPrefix = prefix + (isLast ? chars.SPACE : chars.PIPE);
+      printTree(fullPath, newPrefix, depth + 1, ignoreSet, colors, chars, stats);
+    } else {
+      stats.files++;
+    }
+  }
+}
+
+// ============================================================================
+// DISPLAY: FLAT FORMAT
+// ============================================================================
+
+function printFlat(dirPath, relativePath, depth, ignoreSet, colors, stats) {
+  if (CONFIG.maxDepth > 0 && depth >= CONFIG.maxDepth) return;
+
+  const entries = getEntries(dirPath, ignoreSet);
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    const relPath = path.join(relativePath, entry.name);
+
+    if (entry.isDirectory()) {
+      stats.dirs++;
+      console.log(`${colors.dir}${relPath}/${colors.reset}`);
+      printFlat(fullPath, relPath, depth + 1, ignoreSet, colors, stats);
+    } else {
+      stats.files++;
+      console.log(`${colors.file}${relPath}${colors.reset}`);
+    }
+  }
+}
+
+// ============================================================================
+// DISPLAY: JSON FORMAT
+// ============================================================================
+
+function buildJson(dirPath, depth, ignoreSet, stats) {
+  if (CONFIG.maxDepth > 0 && depth >= CONFIG.maxDepth) return [];
+
+  const entries = getEntries(dirPath, ignoreSet);
+
+  return entries.map((entry) => {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      stats.dirs++;
+      return {
+        name: entry.name,
+        type: "directory",
+        children: buildJson(fullPath, depth + 1, ignoreSet, stats),
+      };
+    }
+
+    stats.files++;
+    try {
+      const fileStat = fs.statSync(fullPath);
+      return { name: entry.name, type: "file", size: fileStat.size };
+    } catch {
+      return { name: entry.name, type: "file" };
+    }
+  });
+}
+
+// ============================================================================
+// HELP TEXT
+// ============================================================================
+
+function printHelp() {
+  console.log(`
+  📂 folder-tree-print — Print folder structure in a beautiful tree format
+
+  Usage:
+    folder-tree-print [path] [options]
+
+  Options:
+    -h, --help        Show this help message
+    -a, --all         Include hidden files/folders (dotfiles)
+    -d, --dirs-only   Show only directories
+    -L, --depth <n>   Limit depth of tree (e.g. -L 2)
+    -I, --ignore <s>  Ignore files/folders matching name (repeatable)
+        --no-color    Disable colored output
+        --no-summary  Hide the summary line
+        --flat        Print flat list instead of tree
+        --json        Output as JSON
+        --ascii       Use ASCII characters instead of Unicode
+
+  Examples:
+    folder-tree-print
+    folder-tree-print ./src -L 3
+    folder-tree-print -a -I node_modules -I .git
+    folder-tree-print --dirs-only --depth 2
+    folder-tree-print --json > structure.json
+`);
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+const { flags, ignore, depth, targetDir } = parseArgs(process.argv);
+
+// --- Apply CLI flags to CONFIG ---
+if (flags.help) { printHelp(); process.exit(0); }
+if (flags.all) CONFIG.showHidden = true;
+if (flags.dirsOnly) CONFIG.dirsOnly = true;
+if (flags.noColor) CONFIG.colorize = false;
+if (flags.noSummary) CONFIG.showSummary = false;
+if (flags.ascii) CONFIG.treeStyle = "ascii";
+if (flags.flat) CONFIG.displayFormat = "flat";
+if (flags.json) CONFIG.displayFormat = "json";
+if (depth > 0) CONFIG.maxDepth = depth;
+
+// --- Build ignore set ---
+const ignoreSet = new Set([...SKIP_DIRS, ...SKIP_FILES, ...ignore]);
+
+// --- Resolve target directory ---
+const resolvedPath = path.resolve(targetDir);
+
+if (!fs.existsSync(resolvedPath)) {
+  console.error(`\x1b[31mError: "${targetDir}" does not exist.\x1b[0m`);
+  process.exit(1);
+}
+
+if (!fs.statSync(resolvedPath).isDirectory()) {
+  console.error(`\x1b[31mError: "${targetDir}" is not a directory.\x1b[0m`);
+  process.exit(1);
+}
+
+// --- Setup ---
+const colors = getColors(CONFIG.colorize);
+const chars = TREE_CHARS[CONFIG.treeStyle];
+const rootName = path.basename(resolvedPath) || resolvedPath;
+const stats = { dirs: 0, files: 0 };
+
+// --- Run ---
+if (CONFIG.displayFormat === "json") {
+  const tree = {
+    name: rootName,
+    type: "directory",
+    children: buildJson(resolvedPath, 0, ignoreSet, stats),
+  };
+  console.log(JSON.stringify(tree, null, 2));
+} else if (CONFIG.displayFormat === "flat") {
+  console.log(`\n${colors.bold}${colors.dir}${rootName}/${colors.reset}`);
+  printFlat(resolvedPath, "", 0, ignoreSet, colors, stats);
+} else {
+  console.log(`\n${colors.bold}${colors.dir}${rootName}/${colors.reset}`);
+  printTree(resolvedPath, "", 0, ignoreSet, colors, chars, stats);
+}
+
+// --- Summary ---
+if (CONFIG.showSummary && CONFIG.displayFormat !== "json") {
+  console.log(
+    `\n${colors.dim}${stats.dirs} director${stats.dirs === 1 ? "y" : "ies"}, ${stats.files} file${stats.files === 1 ? "" : "s"}${colors.reset}\n`
+  );
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "folder-tree-print",
+  "version": "1.0.0",
+  "description": "Print a beautiful tree view of any folder structure. Great for LLM context, docs, and sharing project layouts.",
+  "main": "index.js",
+  "bin": {
+    "folder-tree-print": "index.js"
+  },
+  "keywords": [
+    "tree",
+    "folder",
+    "directory",
+    "structure",
+    "cli",
+    "llm",
+    "project-structure",
+    "code-context"
+  ],
+  "author": "Rayan Mansoor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rayan-Mansoor/Folder-Tree-Print.git"
+  }
+}