ftreeview 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ftree contributors
+
+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,235 @@
+# ftree
+
+A lightweight, interactive CLI file explorer with live monitoring and git awareness.
+
+**Open source**: MIT licensed (see [LICENSE](LICENSE)). Contributions welcome.
+
+## Features
+
+- **Interactive Tree Navigation** - Browse directories with vim-style keybindings
+- **Live File Watching** - Automatically updates when files change
+- **Git Status Integration** - See modified, added, and untracked files at a glance
+- **Added/Modified Indicators** - File and folder lines show quick A/M change icons (folder status is inherited from changed children)
+- **Colored File Types** - Syntax-highlighted file extensions (JS, TS, Python, Go, Rust, etc.)
+- **Smart Icons** - Nerd Font devicons (optional) with emoji fallback; ASCII mode supported
+- **Keyboard Navigation** - Full keyboard control with arrow keys or vim bindings
+- **Handles Large Directories** - Efficient traversal with viewport scrolling
+- **Terminal Resize Support** - Adapts to terminal window size changes
+- **Clean Exit** - Graceful shutdown with proper terminal state restoration
+
+## Installation
+
+### Global Install (Recommended)
+
+```bash
+npm install -g ftreeview
+```
+
+Then run from anywhere:
+
+```bash
+ftree
+```
+
+### npx (No Install Required)
+
+```bash
+npx ftree
+```
+
+### Local Development
+
+```bash
+git clone https://github.com/chaitanyame/watchout.git
+cd watchout
+npm install
+npm run build
+node dist/cli.js
+```
+
+## Usage
+
+```bash
+ftree [path] [options]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `[path]` | Path to directory to explore (default: current directory) |
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-h, --help` | Print help message |
+| `-v, --version` | Print version information |
+| `--no-git` | Disable git integration |
+| `--no-icons` | Use ASCII icons (disable emoji/nerd icons) |
+| `--icon-set <emoji\|nerd\|ascii>` | Choose icon set (default: emoji). You can also set `FTREE_ICON_SET`. |
+| `--theme <vscode>` | UI theme (default: vscode). You can also set `FTREE_THEME`. |
+| `--no-watch` | Disable file watching for static view |
+
+### Examples
+
+```bash
+# Explore current directory
+ftree
+
+# Explore specific directory
+ftree ~/projects
+
+# Explore with git disabled
+ftree --no-git
+
+ # Explore without icons (ASCII mode)
+ ftree --no-icons
+
+ # Use Nerd Font icons (requires Nerd Font)
+ ftree --icon-set nerd
+
+ # WSL / network drive troubleshooting (force polling watcher)
+ FTREE_USE_POLLING=1 ftree
+
+ # Static view (no live watching)
+ ftree --no-watch
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---------|-------------|
+| `FTREE_ICON_SET` | Default icon set (`emoji`, `nerd`, `ascii`) |
+| `FTREE_THEME` | Theme name (currently `vscode`) |
+| `FTREE_USE_POLLING` | Force chokidar polling watcher (`1`/`true` to enable, `0`/`false` to disable) |
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑` / `k` | Move cursor up |
+| `↓` / `j` | Move cursor down |
+| `→` / `l` / `Enter` | Expand directory or enter |
+| `←` / `h` | Collapse directory or jump to parent |
+| `Space` | Toggle expand/collapse |
+| `g` | Jump to first item |
+| `G` | Jump to last item |
+| `r` | Refresh tree |
+| `q` / `Ctrl+C` | Quit |
+
+## Screenshots
+
+### Main View
+
+```
+ftree v0.1.0 │ ./projects/myapp │ 42 files, 12 dirs │ Watching... │ Git: clean
+q:quit ↑↓:nav ←→:expand/collapse r:refresh ?:help
+
+📁 src
+  📁 components
+    📜 App.jsx
+    📜 Header.jsx
+  📁 hooks
+    📜 useAuth.js
+  📁 utils
+    📜 helpers.js
+📄 package.json
+📄 README.md
+```
+
+### Git Status View
+
+```
+ftree v0.1.0 │ ./projects/myapp │ 42 files, 12 dirs │ Watching... │ Git: 2M 1A
+q:quit ↑↓:nav ←→:expand/collapse r:refresh ?:help
+
+📁 src
+  📁 components
+    📜 App.jsx [M]    ← Modified file
+    📜 Header.jsx
+  📁 hooks
+    📜 useAuth.js [A] ← Newly added file
+  📄 package.json [M] ← Modified file
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/ftree.git
+cd ftree
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run from project root
+node dist/cli.js /path/to/explore
+
+# Link globally for testing
+npm link
+ftree
+```
+
+### Project Structure
+
+```
+ftree/
+├── src/
+│   ├── cli.js           # CLI entry point
+│   ├── App.jsx          # Root React component
+│   ├── components/
+│   │   ├── TreeView.jsx # Main tree renderer
+│   │   ├── TreeLine.jsx # Individual line renderer
+│   │   └── StatusBar.jsx# Status bar component
+│   ├── hooks/
+│   │   ├── useTree.js   # Tree building and management
+│   │   ├── useNavigation.js # Keyboard navigation
+│   │   ├── useGitStatus.js  # Git status polling
+│   │   ├── useWatcher.js     # File system watcher
+│   │   └── useIgnore.js     # Gitignore filtering
+│   └── lib/
+│       ├── icons.js     # Icon and color mappings
+│       ├── constants.js # Configuration constants
+│       └── connectors.js# Tree line connectors
+├── package.json
+└── README.md
+```
+
+## Tech Stack
+
+- **Node.js** (>=18.0.0) - Runtime environment
+- **React** - UI component framework
+- **Ink** - React for CLIs
+- **chokidar** - File system watcher
+- **chalk** - Terminal colors
+- **ignore** - Gitignore pattern matching
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome!
+
+- Bug reports / feature requests: open an issue at https://github.com/chaitanyame/watchout/issues
+- Pull requests: keep changes focused, include a clear description, and run `npm run build` before submitting.
+
+## Security
+
+If you believe you’ve found a security issue, please open a GitHub issue with the `security` label (or contact the maintainers privately if you prefer).
+
+## Author
+
+Created with passion for better CLI tools.