You are an expert AI assistant tasked with building a single-page Progressive Web Application (PWA) that re-imagines common command-line interface (CLI) tools with a modern, AI-enhanced, and developer-friendly user experience. The application should serve as a local or web-based utility for developers, providing smarter, more intuitive alternatives to traditional CLI commands.
PROJECT OVERVIEW:
The core problem this application addresses is the often clunky, unintuitive, or overly aggressive 'feature creep' seen in some traditional CLI tools, as highlighted by the Hacker News post 'Good software knows when to stop'. Users face situations where familiar tools are unexpectedly altered or deprecated, sometimes with AI-driven 'improvements' that disrupt workflows. Our application, tentatively named 'Klasik Komutlar: Modern Arayüz' (Classic Commands: Modern Interface), aims to provide a superior developer experience by offering familiar functionalities with enhanced intelligence, better UX, and predictable behavior. The value proposition is increased developer productivity, reduced friction, and a more enjoyable command-line interaction, bridging the gap between the power of the terminal and modern UI/UX principles.
TECH STACK:
- Frontend Framework: React (using Vite for fast development setup)
- Styling: Tailwind CSS for rapid, utility-first styling
- State Management: Zustand for efficient global state management
- Routing: React Router DOM (if multiple views become necessary, but aim for single-page initially)
- Icons: React Icons library (e.g., for file type indicators, status icons)
- Local Storage: Utilizing browser's Local Storage API for persisting settings, command history, and user preferences.
- WebAssembly (Optional for MVP, consider for future): For potential performance-critical tasks or running actual CLI binaries in a sandboxed environment.
CORE FEATURES (MVP):
1. **Enhanced `ls` Replacement ('als'):**
* **User Flow:** Upon opening the app or accessing this feature, the user sees a visually rich representation of the current directory's contents. Instead of plain text, files and directories are listed with distinct icons representing their type (folder, file, executable, image, etc.). File sizes are human-readable (e.g., 1.5KB, 2MB, 3GB). Timestamps are clear and concise. Metadata like permissions or ownership might be available on hover or click.
* **Functionality:** Mimics `ls -la` but with significant visual improvements. Supports sorting by name, size, date. Allows navigation into directories by clicking on them.
2. **Contextual Command Suggestions ('suggest'):**
* **User Flow:** As the user types a command or navigates directories, a suggestion panel appears. It predicts the user's intent based on the current directory, recent commands, and common development workflows. For example, if in a Node.js project, it might suggest `npm install` or `npm run dev`. If a Git repository is detected, it might suggest `git status`, `git add .`, etc.
* **Functionality:** This is the AI-powered component. It uses a combination of heuristics (current path, file types) and potentially a lightweight local model or API call (for MVP, focus on heuristics) to predict the most likely next command.
3. **Smart Directory Navigation ('nav'):**
* **User Flow:** Similar to `cd`, but smarter. Typing parts of a directory name or a known project path triggers suggestions. Users can type `nav proje` and see suggestions like `/home/user/projects/my-awesome-project`. Pressing Enter or clicking a suggestion navigates directly.
* **Functionality:** Autocompletes directory paths, remembers frequently visited directories, and allows fuzzy searching within the directory structure.
4. **Command History & Favorites ('history'):**
* **User Flow:** A dedicated section or a hotkey (e.g., Ctrl+R) allows users to search through their command history. Users can mark commands as 'favorites' for quick access from a separate list or dropdown.
* **Functionality:** Stores command history locally. Provides search and filtering capabilities. Allows users to re-run, edit, or add commands to favorites.
UI/UX DESIGN:
- **Layout:** A clean, modern, single-page application layout. A primary content area displays the directory listing or command output. A persistent sidebar could house command history, favorites, and settings. A command input bar is prominently placed at the bottom or top.
- **Color Palette:** Primarily dark mode theme suitable for developers. Use of accent colors (e.g., blues, greens, purples) for highlighting, links, and interactive elements. Avoid jarring color combinations. Ensure good contrast for readability.
- **Typography:** Use a clean, legible monospaced font for command input and output (e.g., 'Fira Code', 'JetBrains Mono'). Use a sans-serif font for UI elements (e.g., 'Inter', 'Roboto'). Font sizes should be adjustable.
- **Responsiveness:** The application must be responsive. On smaller screens, the sidebar might collapse into a hamburger menu. The directory listing should adapt to the available width, possibly using a compact view.
- **Interactivity:** Clear visual feedback for interactive elements (buttons, links, input fields). Loading states should be clearly indicated.
COMPONENT BREAKDOWN:
- **`App.jsx`:** Main application component. Sets up layout, routing (if any), and global context/state providers.
* Props: None
* Responsibilities: Root component, layout management.
- **`CommandBar.jsx`:** The primary input field for typing commands and suggestions.
* Props: `onCommandSubmit` (function), `suggestions` (array)
* Responsibilities: Captures user input, displays suggestions, triggers command execution.
- **`DirectoryListing.jsx`:** Displays the contents of a directory.
* Props: `items` (array of file/directory objects), `onNavigate` (function), `isLoading` (boolean)
* Responsibilities: Renders file items, handles navigation clicks, displays loading state.
- **`FileItem.jsx`:** Represents a single file or directory in the listing.
* Props: `item` (object - {name, type, size, modifiedDate}), `onClick` (function)
* Responsibilities: Displays file details visually, handles click events for navigation or actions.
- **`HistoryPanel.jsx`:** Displays the command history and favorites.
* Props: `history` (array), `favorites` (array), `onRunCommand` (function), `onToggleFavorite` (function)
* Responsibilities: Lists commands, allows searching/filtering, enables re-running and favoriting.
- **`SuggestionsPanel.jsx`:** Displays contextual command suggestions.
* Props: `suggestions` (array of strings/objects), `onSelectSuggestion` (function)
* Responsibilities: Shows predicted commands based on context.
DATA MODEL:
- **`AppState` (Zustand Store):**
* `currentPath`: string (e.g., '/home/user')
* `directoryContents`: Array<{id, name, type, size, modifiedDate, permissions}> (e.g., type: 'file', 'directory', 'symlink')
* `commandHistory`: Array<{id, command, timestamp}>
* `favorites`: Array<{id, command}>
* `settings`: { theme: 'dark' | 'light', fontSize: number }
* `isLoading`: boolean
* `error`: string | null
- **Mock Data Format (`directoryContents` item):**
```json
{
"id": "1a2b3c",
"name": "src",
"type": "directory",
"size": null, // Directories might not have a direct size in this view
"modifiedDate": "2023-10-27T10:00:00Z",
"permissions": "drwxr-xr-x"
}
```
- **Mock Data Format (`commandHistory` item):**
```json
{
"id": "cmd_1",
"command": "npm install prettier --save-dev",
"timestamp": "2023-10-27T09:30:00Z"
}
```
ANIMATIONS & INTERACTIONS:
- **Directory Transitions:** Smooth fade-in/fade-out or slide animation when navigating between directories.
- **Command Input:** Subtle typing indicator or underline animation. Suggestions panel should appear/disappear gracefully.
- **Loading States:** Use spinners or shimmering placeholder elements within `DirectoryListing` while data is being fetched.
- **Hover Effects:** Slight background color change or subtle scale-up on `FileItem` and buttons.
- **Micro-interactions:** Visual feedback when adding a command to favorites.
EDGE CASES:
- **Empty Directory:** Display a clear message like "This directory is empty."
- **Error Handling:** Gracefully handle API errors (if applicable) or file system access errors. Display user-friendly error messages.
- **Permissions:** Indicate if access to a directory or file is denied.
- **Large Directories:** Implement virtualization or pagination for directory listings to maintain performance.
- **Input Validation:** Basic validation for commands entered, providing hints if a command is unrecognized or malformed.
- **Accessibility (a11y):** Ensure proper ARIA attributes, keyboard navigation support (tabbing, Enter key for actions), sufficient color contrast, and focus management.
SAMPLE DATA (for initial load and testing):
```json
// Example directoryContents for root '/'
[
{
"id": "dir_home",
"name": "home",
"type": "directory",
"size": null,
"modifiedDate": "2023-10-26T15:00:00Z",
"permissions": "drwxr-xr-x"
},
{
"id": "dir_etc",
"name": "etc",
"type": "directory",
"size": null,
"modifiedDate": "2023-10-25T08:00:00Z",
"permissions": "drwxr-xr-x"
},
{
"id": "file_readme",
"name": "README.md",
"type": "file",
"size": 1200,
"modifiedDate": "2023-10-27T11:00:00Z",
"permissions": "-rw-r--r--"
},
{
"id": "file_config",
"name": "app.config",
"type": "file",
"size": 512,
"modifiedDate": "2023-10-27T09:00:00Z",
"permissions": "-rw-rw-r--"
}
]
// Example commandHistory
[
{
"id": "cmd_101",
"command": "ls -la",
"timestamp": "2023-10-27T11:05:00Z"
},
{
"id": "cmd_102",
"command": "cd projects",
"timestamp": "2023-10-27T11:06:00Z"
},
{
"id": "cmd_103",
"command": "git status",
"timestamp": "2023-10-27T11:07:00Z"
}
]
// Example Favorites
[
{
"id": "fav_1",
"command": "npm run dev"
},
{
"id": "fav_2",
"command": "docker-compose up -d"
}
]
```
DEPLOYMENT NOTES:
- **Build Tool:** Vite is recommended for its speed and ease of configuration.
- **Environment Variables:** Use `.env` files for managing API keys (if any), application name, and other configuration settings. Ensure sensitive variables are not committed to version control.
- **Performance Optimizations:** Implement code splitting if the application grows. Optimize image loading. Use `React.memo` or `useMemo`/`useCallback` where necessary to prevent unnecessary re-renders, especially in list components.
- **PWA Configuration:** Include a `manifest.json` file and a service worker for offline capabilities and installability on desktops and mobile devices.
- **Build Command:** `vite build`. The output should be static assets suitable for hosting on platforms like Netlify, Vercel, or GitHub Pages.