feat(core): implement Deno Tree file generator with complete API 🌳

- Add complete documentation with examples and API reference
- Add Tree class with clear(), generate(), init(), remove(), set() methods
- Implement file metadata collection and tree formatting
- Implement singleton pattern for global tree instance
- Include performance optimizations with ignoreDirs, maxDepth, maxFiles
- Support directory ignoring and hidden file filtering

Author: NeaByteLab

.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.5.4
+
+      - name: Run lint and check
+        run: deno lint src/ && deno check src/
+
+      - name: Publish package
+        run: deno publish

.gitignore

@@ -0,0 +1,11 @@
+# Deno
+.deno/
+deno.lock
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NeaByteLab
+
+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.

README.md

@@ -0,0 +1,279 @@
+# Deno Tree [![Deno](https://img.shields.io/badge/Deno-2.5.4-blue)](https://deno.land) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A file tree generator for Deno. Generate beautiful directory trees instantly from a single scan.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Tree Options](#tree-options)
+  - [Performance Settings](#performance-settings)
+- [Basic Usage](#basic-usage)
+  - [Simple Tree Generation](#simple-tree-generation)
+  - [Multiple Tree Generation](#multiple-tree-generation)
+  - [Promise Chain Style](#promise-chain-style)
+  - [File Management](#file-management)
+  - [Project Switching](#project-switching)
+- [API Reference](#api-reference)
+  - [Main API](#main-api)
+  - [Configuration Options](#configuration-options)
+  - [File Metadata](#file-metadata)
+- [Troubleshooting](#troubleshooting)
+  - [Common Issues](#common-issues)
+  - [Debug Mode](#debug-mode)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```bash
+deno install @neabyte/deno-tree
+```
+
+## Quick Start
+
+```ts
+import tree from '@neabyte/deno-tree'
+
+// Initialize with a directory
+await tree.init('/path/to/directory', {
+  ignoreDirs: ['node_modules', '.git', 'dist'],
+  maxFiles: 1000,
+  showHidden: false,
+  maxDepth: 3
+})
+
+// Generate tree for the entire directory
+const result = await tree.generate('/path/to/directory')
+console.log(result)
+```
+
+**Example Output:**
+
+```
+.
+├── src/
+│   ├── components/
+│   │   ├── Button.tsx
+│   │   └── Modal.tsx
+│   ├── utils/
+│   │   └── helpers.ts
+│   └── index.ts
+├── tests/
+│   └── components.test.ts
+├── deno.json
+└── README.md
+```
+
+## Configuration
+
+### Tree Options
+
+```ts
+interface TreeOptions {
+  ignoreDirs?: string[] // Directories to ignore (default: [])
+  maxFiles?: number // Maximum files to process (default: unlimited)
+  showHidden?: boolean // Show hidden files/directories (default: false)
+  maxDepth?: number // Maximum directory depth (default: unlimited)
+}
+```
+
+### Performance Settings
+
+```ts
+// For large directories - limit files and depth
+{
+  maxFiles: 5000,
+  maxDepth: 4,
+  ignoreDirs: ['node_modules', '.git', 'dist', 'build', 'coverage']
+}
+
+// For quick overview - shallow scan
+{
+  maxFiles: 100,
+  maxDepth: 2,
+  showHidden: false
+}
+
+// For complete scan - no limits
+{
+  showHidden: true
+  // No maxFiles or maxDepth limits
+}
+```
+
+## Basic Usage
+
+### Simple Tree Generation
+
+```ts
+import tree from '@neabyte/deno-tree'
+
+// Basic tree generation
+await tree.init('/path/to/project')
+const result = await tree.generate('/path/to/project')
+console.log(result)
+```
+
+### Multiple Tree Generation
+
+```ts
+import tree from '@neabyte/deno-tree'
+
+// Scan parent directory once
+await tree.init('/workspace', {
+  ignoreDirs: ['node_modules', '.git', 'dist'],
+  maxFiles: 2000,
+  showHidden: false,
+  maxDepth: 2
+})
+
+// Generate trees for multiple projects
+const projectA = await tree.generate('/workspace/project-a')
+const projectB = await tree.generate('/workspace/project-b')
+const projectC = await tree.generate('/workspace/project-c')
+
+console.log('Project A Tree:', projectA)
+console.log('Project B Tree:', projectB)
+console.log('Project C Tree:', projectC)
+```
+
+### Promise Chain Style
+
+```ts
+import tree from '@neabyte/deno-tree'
+
+tree
+  .init('/path/to/project', {
+    ignoreDirs: ['node_modules', '.git'],
+    maxFiles: 500,
+    showHidden: false,
+    maxDepth: 2
+  })
+  .then(async () => {
+    const result = await tree.generate('/path/to/project')
+    console.log(result)
+  })
+  .catch((error) => {
+    console.error(error)
+  })
+```
+
+### File Management
+
+```ts
+import tree from '@neabyte/deno-tree'
+
+// Add individual files to the tree
+await tree.set('/path/to/file.txt')
+await tree.set('/path/to/another-file.js')
+
+// Remove files when they're deleted
+await tree.remove('/path/to/deleted-file.txt')
+await tree.remove('/path/to/deleted-directory')
+
+// Clear all files and reset state
+tree.clear()
+
+// Generate tree with updated metadata
+const result = await tree.generate('/path/to/directory')
+console.log(result)
+```
+
+### Project Switching
+
+```ts
+import tree from '@neabyte/deno-tree'
+
+// Work with multiple projects
+await tree.init('/workspace/project-a', { maxFiles: 1000 })
+const treeA = await tree.generate('/workspace/project-a')
+console.log('Project A:', treeA)
+
+// Clear and switch to different project
+tree.clear()
+await tree.init('/workspace/project-b', { maxFiles: 2000 })
+const treeB = await tree.generate('/workspace/project-b')
+console.log('Project B:', treeB)
+```
+
+## API Reference
+
+### Main API
+
+| Method       | Description                            | Parameters                            | Returns           |
+| ------------ | -------------------------------------- | ------------------------------------- | ----------------- |
+| `clear()`    | Clear all stored file metadata         | None                                  | `void`            |
+| `generate()` | Generate formatted tree string         | `rootPath: string`                    | `Promise<string>` |
+| `init()`     | Scan directory and store file metadata | `path: string, options?: TreeOptions` | `Promise<void>`   |
+| `remove()`   | Remove file/directory from tree        | `path: string`                        | `Promise<void>`   |
+| `set()`      | Add single file to tree metadata       | `path: string`                        | `Promise<void>`   |
+
+### Configuration Options
+
+| Property     | Type     | Required | Description                   | Example                    |
+| ------------ | -------- | -------- | ----------------------------- | -------------------------- |
+| `ignoreDirs` | string[] | ❌       | Directories to ignore         | `['node_modules', '.git']` |
+| `maxFiles`   | number   | ❌       | Maximum files to process      | `1000`                     |
+| `showHidden` | boolean  | ❌       | Show hidden files/directories | `false`                    |
+| `maxDepth`   | number   | ❌       | Maximum directory depth       | `3`                        |
+
+### File Metadata
+
+```ts
+interface FileMetadata {
+  name: string // File name
+  path: string // Full file path
+  type: 'file' | 'directory' // File type
+  parent?: string // Parent directory path
+  size?: number // File size in bytes
+  modified?: Date // Last modified date
+  extension?: string // File extension
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Empty Tree Output**
+
+- Verify the path exists and is accessible
+- Check if `maxFiles` limit was reached before scanning the target directory
+- Ensure `maxDepth` allows reaching the target directory
+
+**Memory Issues**
+
+- Reduce `maxFiles` limit for large directories
+- Use `maxDepth` to limit scanning depth
+- Add more directories to `ignoreDirs`
+
+**Slow Performance**
+
+- Increase `maxFiles` limit if hitting the cap too early
+- Reduce `maxDepth` for shallow scans
+- Add common build directories to `ignoreDirs`
+
+### Debug Mode
+
+```ts
+import tree from '@neabyte/deno-tree'
+
+// Debug file storage
+await tree.init('/path/to/project', { maxFiles: 100 })
+console.log('Files stored:', tree.files.size)
+
+// Debug specific path generation
+const result = await tree.generate('/path/to/project/src')
+console.log('Generated tree length:', result.length)
+console.log('Tree output:', result)
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a [Pull Request](https://github.com/NeaByteLab/Deno-Tree/pulls).
+
+## License
+
+This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.