ftreeview 0.1.1

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "ftreeview",
+  "version": "0.1.1",
+  "description": "Terminal file explorer with git awareness and live updates",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "ftree": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "node build.js",
+    "dev": "node build.js --run",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cli",
+    "file",
+    "explorer",
+    "tree",
+    "terminal",
+    "tui",
+    "watcher",
+    "git"
+  ],
+  "author": "ftree contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chaitanyame/watchout.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chaitanyame/watchout/issues"
+  },
+  "homepage": "https://github.com/chaitanyame/watchout#readme",
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "chokidar": "^4.0.3",
+    "ignore": "^6.0.2",
+    "ink": "^5.0.1",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.3"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  }
+}

package/src/App.jsx

@@ -0,0 +1,243 @@
+/**
+ * App Component - Root Component for ftree
+ *
+ * Orchestrates between:
+ * - useTree: Manages the file tree data structure
+ * - useNavigation: Handles keyboard navigation and cursor state
+ * - TreeView: Renders the visible portion of the tree
+ * - StatusBar: Shows helpful information (T9)
+ * - useGitStatus: Provides git status integration
+ * - useWatcher: Monitors file system changes
+ *
+ * This component uses React hooks to manage state and coordinates
+ * between the data flow, navigation state, and rendering.
+ */
+import React, { useEffect, useCallback, useMemo, useState, useRef } from 'react';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { Box } from 'ink';
+import TreeView from './components/TreeView.jsx';
+import StatusBar, { calculateCounts, calculateGitStatus } from './components/StatusBar.jsx';
+import { useTree, applyGitStatus, applyChangeIndicators } from './hooks/useTree.js';
+import { useNavigation } from './hooks/useNavigation.js';
+import { useGitStatus } from './hooks/useGitStatus.js';
+import { useWatcher } from './hooks/useWatcher.js';
+import { useChangedFiles } from './hooks/useChangedFiles.js';
+import { mapWatcherEventToChangeStatus } from './lib/changeStatus.js';
+import { getTheme, resolveIconSet, resolveThemeName } from './lib/theme.js';
+
+/**
+ * Clean exit handler - ensures proper terminal state on exit
+ * Prints a newline to avoid leaving cursor on status line
+ */
+function setupCleanExit() {
+  const onExit = () => {
+    // Print newline for clean exit
+    process.stdout.write('\n');
+  };
+
+  // Handle normal exit
+  process.on('exit', onExit);
+
+  // Handle SIGINT (Ctrl+C)
+  process.on('SIGINT', () => {
+    onExit();
+    process.exit(0);
+  });
+
+  // Return cleanup function
+  return () => {
+    process.off('exit', onExit);
+    process.off('SIGINT');
+  };
+}
+
+/**
+ * App Component Props
+ * @property {string} rootPath - Root directory path to explore
+ * @property {object} options - Configuration options from CLI
+ */
+export default function App({ rootPath, options = {}, version }) {
+  const rootAbsPath = resolve(rootPath);
+  const iconSet = resolveIconSet({ cliIconSet: options.iconSet, noIcons: options.noIcons });
+  const theme = getTheme(resolveThemeName({ cliTheme: options.theme }));
+
+  // Track selected path to preserve cursor position across rebuilds
+  const [selectedPath, setSelectedPath] = useState(null);
+
+  // Setup clean exit handler - ensures proper terminal state on exit
+  useEffect(() => setupCleanExit(), []);
+
+  // Get tree data and rebuild function
+  const { tree, flatList, refreshFlatList, rebuildTree } = useTree(rootPath, options);
+
+  // Get git status (enabled unless --no-git flag is set)
+  const { statusMap, isGitRepo, refresh: refreshGit } = useGitStatus(
+    rootPath,
+    !options.noGit
+  );
+
+  // Get navigation state (cursor, viewport)
+  const { cursor, viewportStart, setCursor } = useNavigation(
+    flatList,
+    rebuildTree,
+    refreshFlatList
+  );
+  const cursorRef = useRef(cursor);
+  cursorRef.current = cursor;
+
+  // Track recently changed files for visual highlighting
+  const { changedFiles, markChanged } = useChangedFiles();
+
+  // Apply git/change indicators during render (memoized) to avoid effect-driven update loops.
+  useMemo(() => {
+    if (!tree) {
+      return;
+    }
+
+    const gitStatuses = isGitRepo ? statusMap : new Map();
+    applyGitStatus(tree, gitStatuses);
+    applyChangeIndicators(tree, gitStatuses, changedFiles);
+  }, [statusMap, tree, isGitRepo, changedFiles]);
+
+  // Terminal size state (for resize handling)
+  const [termSize, setTermSize] = useState({
+    width: process.stdout.columns,
+    height: process.stdout.rows,
+  });
+
+  // Listen for terminal resize events
+  useEffect(() => {
+    const handleResize = () => {
+      setTermSize({
+        width: process.stdout.columns,
+        height: process.stdout.rows,
+      });
+    };
+
+    // Listen for resize events
+    process.stdout.on('resize', handleResize);
+
+    // Cleanup listener on unmount
+    return () => {
+      process.stdout.off('resize', handleResize);
+    };
+  }, []);
+
+  // Update selected path when cursor changes
+  useEffect(() => {
+    if (flatList.length > 0 && cursor >= 0 && cursor < flatList.length) {
+      const currentNode = flatList[cursor];
+      if (currentNode) {
+        setSelectedPath((prev) => (prev === currentNode.path ? prev : currentNode.path));
+      }
+    }
+  }, [cursor, flatList]);
+
+  // Restore cursor position after rebuild
+  useEffect(() => {
+    if (!selectedPath || flatList.length === 0) {
+      return;
+    }
+
+    const newIndex = flatList.findIndex((node) => node.path === selectedPath);
+    if (newIndex === -1) {
+      setCursor((prev) => Math.min(prev, flatList.length - 1));
+      return;
+    }
+
+    if (newIndex !== cursorRef.current) {
+      setCursor(newIndex);
+    }
+  }, [flatList, selectedPath, setCursor]);
+
+  // Convert watcher path to tree-relative path format
+  const toTreeRelativePath = useCallback((watchPath) => {
+    if (!watchPath) {
+      return '';
+    }
+
+    const absolutePath = isAbsolute(watchPath)
+      ? watchPath
+      : resolve(rootAbsPath, watchPath);
+    const relativePath = relative(rootAbsPath, absolutePath);
+
+    if (!relativePath || relativePath.startsWith('..')) {
+      return '';
+    }
+
+    return relativePath.split(sep).join('/');
+  }, [rootAbsPath]);
+
+  // File watcher - rebuilds tree and refreshes git status on file changes
+  // Enabled unless --no-watch flag is set
+  const handleTreeChange = useCallback((eventsOrEvent, watchPath) => {
+    const batch = Array.isArray(eventsOrEvent)
+      ? eventsOrEvent
+      : [{ event: eventsOrEvent, path: watchPath }];
+
+    for (const item of batch) {
+      if (!item) continue;
+      const changeStatus = mapWatcherEventToChangeStatus(item.event);
+      const relativePath = toTreeRelativePath(item.path);
+
+      if (changeStatus && relativePath) {
+        markChanged(relativePath, changeStatus);
+      }
+    }
+
+    rebuildTree(true);
+    if (isGitRepo) {
+      refreshGit();
+    }
+  }, [rebuildTree, isGitRepo, refreshGit, markChanged, toTreeRelativePath]);
+
+  const { isWatching } = useWatcher(rootPath, handleTreeChange, {
+    noWatch: options.noWatch,
+  });
+
+  // Calculate viewport dimensions
+  // Reserve space: 1 line for status bar (2 if help enabled)
+  const helpEnabled = options.help !== false; // Show help by default
+  const statusBarHeight = helpEnabled ? 2 : 1;
+  const viewportHeight = termSize.height - statusBarHeight;
+  const termWidth = termSize.width;
+
+  // Calculate file and directory counts
+  const { fileCount, dirCount } = calculateCounts(flatList);
+
+  // Calculate git status summary
+  const { summary: gitSummary } = calculateGitStatus(statusMap);
+
+  return (
+    <Box flexDirection="column" height="100%">
+      {/* Main tree view area */}
+      <Box flexGrow={1}>
+        <TreeView
+          flatList={flatList}
+          cursor={cursor}
+          viewportStart={viewportStart}
+          viewportHeight={viewportHeight}
+          termWidth={termWidth}
+          iconSet={iconSet}
+          theme={theme}
+        />
+      </Box>
+
+      {/* StatusBar */}
+      <StatusBar
+        version={version}
+        rootPath={rootPath}
+        fileCount={fileCount}
+        dirCount={dirCount}
+        isWatching={isWatching}
+        gitEnabled={!options.noGit}
+        isGitRepo={isGitRepo}
+        gitSummary={gitSummary}
+        showHelp={helpEnabled}
+        termWidth={termWidth}
+        iconSet={iconSet}
+        theme={theme}
+      />
+    </Box>
+  );
+}

package/src/cli.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * ftree CLI entry point
+ * Terminal file explorer with git awareness and live updates
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { statSync, readdirSync } from 'node:fs';
+import { render } from 'ink';
+import React from 'react';
+
+import App from './App.jsx';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Get version from package.json
+const pkgPath = resolve(__dirname, '../package.json');
+const { version } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+/**
+ * Print help message
+ */
+function printHelp() {
+  console.log(`
+ftree - Terminal file explorer with git awareness and live updates
+
+USAGE:
+  ftree [path]
+
+ARGUMENTS:
+  [path]        Path to directory to explore (default: current directory)
+
+OPTIONS:
+  -h, --help    Print this help message
+  -v, --version Print version information
+      --no-git  Disable git integration
+      --no-icons Use ASCII icons (disable emoji/nerd icons)
+      --no-watch Disable file watching
+      --icon-set <emoji|nerd|ascii>  Icon set (default: emoji). You can also set FTREE_ICON_SET.
+      --theme <vscode>  UI theme (default: vscode). You can also set FTREE_THEME.
+
+EXAMPLES:
+  ftree                    # Explore current directory
+  ftree ~/projects         # Explore specific directory
+  ftree /path/to/project   # Explore project path
+
+EXIT CODES:
+  0 - Success
+  1 - Invalid path or error
+`);
+}
+
+/**
+ * Print version information
+ */
+function printVersion() {
+  console.log(`ftree v${version}`);
+}
+
+/**
+ * Validate a directory path
+ * @param {string} path - Path to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validatePath(path) {
+  const resolvedPath = resolve(path);
+
+  // Check if path exists
+  if (!existsSync(resolvedPath)) {
+    return {
+      valid: false,
+      error: `Error: Path does not exist: ${resolvedPath}`,
+    };
+  }
+
+  // Check if it's a directory
+  try {
+    const stats = statSync(resolvedPath);
+    if (!stats.isDirectory()) {
+      return {
+        valid: false,
+        error: `Error: Path is not a directory: ${resolvedPath}`,
+      };
+    }
+  } catch (err) {
+    return {
+      valid: false,
+      error: `Error: Cannot access path: ${resolvedPath} (${err.message})`,
+    };
+  }
+
+  // Check if directory is readable
+  try {
+    readdirSync(resolvedPath);
+  } catch (err) {
+    return {
+      valid: false,
+      error: `Error: Cannot read directory: ${resolvedPath} (${err.message})`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Parse command line arguments
+ * @returns {{path?: string, help: boolean, version: boolean, options: object}}
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {
+    help: false,
+    version: false,
+    options: {
+      noIcons: false,
+      noGit: false,
+      noWatch: false,
+      help: true, // show help line by default
+      iconSet: undefined,
+      theme: undefined,
+    },
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      result.help = true;
+      continue;
+    }
+    if (arg === '-v' || arg === '--version') {
+      result.version = true;
+      continue;
+    }
+
+    if (arg === '--no-git') {
+      result.options.noGit = true;
+      continue;
+    }
+    if (arg === '--no-icons') {
+      result.options.noIcons = true;
+      continue;
+    }
+    if (arg === '--no-watch') {
+      result.options.noWatch = true;
+      continue;
+    }
+    if (arg === '--no-help') {
+      result.options.help = false;
+      continue;
+    }
+
+    if (arg === '--icon-set' || arg.startsWith('--icon-set=')) {
+      const value = arg.includes('=')
+        ? arg.split('=')[1]
+        : args[++i];
+      if (!value) {
+        console.error('Error: --icon-set requires a value (emoji|nerd|ascii)');
+        process.exit(1);
+      }
+      result.options.iconSet = value;
+      continue;
+    }
+
+    if (arg === '--theme' || arg.startsWith('--theme=')) {
+      const value = arg.includes('=')
+        ? arg.split('=')[1]
+        : args[++i];
+      if (!value) {
+        console.error('Error: --theme requires a value');
+        process.exit(1);
+      }
+      result.options.theme = value;
+      continue;
+    }
+
+    if (!arg.startsWith('-')) {
+      // Positional argument (path)
+      result.path = arg;
+      continue;
+    }
+
+    console.error(`Error: Unknown option: ${arg}`);
+    console.error('Use --help for usage information');
+    process.exit(1);
+  }
+
+  return result;
+}
+
+/**
+ * Main CLI entry point
+ */
+function main() {
+  const { path, help, version, options } = parseArgs();
+
+  // Handle help flag
+  if (help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Handle version flag
+  if (version) {
+    printVersion();
+    process.exit(0);
+  }
+
+  // Determine target path (default to current directory)
+  const targetPath = path || '.';
+
+  // Validate path
+  const validation = validatePath(targetPath);
+  if (!validation.valid) {
+    console.error(validation.error);
+    process.exit(1);
+  }
+
+  // Render the Ink app
+  const resolvedPath = resolve(targetPath);
+  render(React.createElement(App, { rootPath: resolvedPath, options, version: `v${version}` }));
+}
+
+// Run CLI
+main();