copilot-liku-cli 0.0.1

package/CONTRIBUTING.md

@@ -0,0 +1,225 @@
+# Contributing to Copilot-Liku CLI
+
+Thank you for your interest in contributing to Copilot-Liku CLI! This guide will help you get started with local development.
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** v22 or higher
+- **npm** v10 or higher
+- **Git**
+- (On Windows) **PowerShell** v6 or higher
+
+### Initial Setup
+
+1. **Fork and clone the repository:**
+```bash
+git clone https://github.com/YOUR-USERNAME/copilot-Liku-cli.git
+cd copilot-Liku-cli
+```
+
+2. **Install dependencies:**
+```bash
+npm install
+```
+
+3. **Link for global usage (recommended for testing):**
+```bash
+npm link
+```
+
+This creates a symlink from your global `node_modules` to your local development directory. Any changes you make will be immediately reflected when you run the `liku` command.
+
+4. **Verify the setup:**
+```bash
+liku --version
+liku --help
+```
+
+### Development Workflow
+
+#### Testing Your Changes
+
+After making changes to the CLI code:
+
+1. **Test the CLI commands:**
+```bash
+liku --help           # Test help output
+liku start            # Test starting the app
+liku click "Button"   # Test automation commands
+```
+
+2. **Run existing tests:**
+```bash
+npm test              # Run test suite
+npm run test:ui       # Run UI automation tests
+```
+
+3. **Manual testing:**
+```bash
+# Start the application
+liku start
+
+# Test specific commands
+liku screenshot
+liku window "VS Code"
+```
+
+#### Unlinking When Done
+
+If you need to unlink your development version:
+```bash
+npm unlink -g copilot-liku-cli
+```
+
+Or to install the published version:
+```bash
+npm unlink -g copilot-liku-cli
+npm install -g copilot-liku-cli
+```
+
+### Project Structure
+
+```
+copilot-Liku-cli/
+├── src/
+│   ├── cli/              # CLI implementation
+│   │   ├── liku.js       # Main CLI entry point
+│   │   ├── commands/     # Command implementations
+│   │   └── util/         # CLI utilities
+│   ├── main/             # Electron main process
+│   ├── renderer/         # Electron renderer process
+│   └── shared/           # Shared utilities
+├── scripts/              # Build and test scripts
+├── docs/                 # Additional documentation
+└── package.json          # Package configuration with bin entry
+```
+
+### Making Changes
+
+#### Adding a New CLI Command
+
+1. Create a new command file in `src/cli/commands/`:
+```javascript
+// src/cli/commands/mycommand.js
+async function run(args, options) {
+  // Command implementation
+  console.log('Running my command with args:', args);
+  return { success: true };
+}
+
+module.exports = { run };
+```
+
+2. Register the command in `src/cli/liku.js`:
+```javascript
+const COMMANDS = {
+  // ... existing commands
+  mycommand: { 
+    desc: 'Description of my command', 
+    file: 'mycommand',
+    args: '[optional-arg]' 
+  },
+};
+```
+
+3. Test your command:
+```bash
+liku mycommand --help
+```
+
+#### Modifying the CLI Parser
+
+The main CLI logic is in `src/cli/liku.js`. Key functions:
+- `parseArgs()` - Parses command-line arguments
+- `executeCommand()` - Loads and runs command modules
+- `showHelp()` - Displays help text
+
+### Code Style
+
+- Follow existing code conventions
+- Use meaningful variable names
+- Add comments for complex logic
+- Keep functions focused and small
+
+### Testing Guidelines
+
+1. **Test your changes locally** before submitting a PR
+2. **Ensure existing tests pass**: `npm test`
+3. **Add tests for new features** when applicable
+4. **Test cross-platform** if possible (Windows, macOS, Linux)
+
+### Submitting Changes
+
+1. **Create a feature branch:**
+```bash
+git checkout -b feature/my-feature
+```
+
+2. **Make your changes and commit:**
+```bash
+git add .
+git commit -m "Add feature: description"
+```
+
+3. **Push to your fork:**
+```bash
+git push origin feature/my-feature
+```
+
+4. **Open a Pull Request** on GitHub with:
+   - Clear description of changes
+   - Reasoning for the changes
+   - Any testing performed
+   - Screenshots if UI changes
+
+### Troubleshooting
+
+#### `liku` command not found after `npm link`
+
+Make sure npm's global bin directory is in your PATH:
+```bash
+npm bin -g
+```
+
+Add the output directory to your PATH if needed.
+
+#### Changes not reflected when running `liku`
+
+1. Verify you're linked to the local version:
+```bash
+which liku          # Unix/Mac
+where liku          # Windows
+```
+
+2. Re-link if needed:
+```bash
+npm unlink -g copilot-liku-cli
+npm link
+```
+
+#### Permission errors with `npm link`
+
+On some systems, you may need to configure npm to use a user-local prefix:
+```bash
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+```
+
+Then add `~/.npm-global/bin` to your PATH.
+
+### Additional Resources
+
+- [npm link documentation](https://docs.npmjs.com/cli/v10/commands/npm-link)
+- [npm bin configuration](https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables)
+- [Project Architecture](ARCHITECTURE.md)
+- [Testing Guide](TESTING.md)
+
+### Getting Help
+
+- Check existing [GitHub Issues](https://github.com/TayDa64/copilot-Liku-cli/issues)
+- Join discussions in the repository
+- Review documentation files in the repo
+
+Thank you for contributing! 🎉

package/ELECTRON_README.md

@@ -0,0 +1,121 @@
+# Electron Headless Agent + Ultra-Thin Overlay
+
+This is an implementation of an Electron-based application with a headless agent architecture and ultra-thin overlay interface.
+
+## Architecture
+
+The application consists of three main components:
+
+### 1. Main Process (`src/main/index.js`)
+- Manages overlay window (transparent, full-screen, always-on-top)
+- Manages chat window (small, edge-docked)
+- Handles system tray icon and context menu
+- Registers global hotkeys:
+  - `Ctrl+Alt+Space` (or `Cmd+Alt+Space` on macOS): Toggle chat window
+  - `Ctrl+Shift+O` (or `Cmd+Shift+O` on macOS): Toggle overlay window
+- Manages IPC communication between windows
+
+### 2. Overlay Window (`src/renderer/overlay/`)
+- Full-screen, transparent, always-on-top window
+- Click-through by default (passive mode)
+- Displays a coarse grid of dots (100px spacing)
+- In selection mode, dots become interactive
+- Minimal footprint with vanilla JavaScript
+
+### 3. Chat Window (`src/renderer/chat/`)
+- Small window positioned at bottom-right by default
+- Contains:
+  - Chat history display
+  - Mode controls (Passive/Selection)
+  - Input field for commands
+- Hidden by default, shown via hotkey or tray icon
+
+## Installation
+
+```bash
+npm install
+```
+
+## Running the Application
+
+```bash
+npm start
+```
+
+## Usage
+
+1. **Launch the application** - The overlay starts in passive mode (click-through)
+2. **Open chat window** - Click tray icon or press `Ctrl+Alt+Space`
+3. **Enable selection mode** - Click "Selection" button in chat window
+4. **Select dots** - Click any dot on the overlay to select it
+5. **Return to passive mode** - Automatically switches back after selection, or click "Passive" button
+
+## Modes
+
+### Passive Mode
+- Overlay is completely click-through
+- Users can interact with applications normally
+- Overlay is invisible to mouse events
+
+### Selection Mode
+- Overlay captures mouse events
+- Dots become interactive
+- Click dots to select screen positions
+- Automatically returns to passive mode after selection
+
+## Platform-Specific Behavior
+
+### macOS
+- Uses `screen-saver` window level to float above fullscreen apps
+- Hides from Dock
+- Tray icon appears in menu bar
+
+### Windows
+- Uses standard `alwaysOnTop` behavior
+- Tray icon appears in system tray
+- Works with most windowed applications
+
+## Architecture Benefits
+
+1. **Minimal footprint**: Single overlay renderer with vanilla JS, no heavy frameworks
+2. **Non-intrusive**: Overlay is transparent and sparse; chat is at screen edge
+3. **Performance**: Click-through mode prevents unnecessary event processing
+4. **Extensibility**: IPC message system ready for agent integration
+5. **Cross-platform**: Works on macOS and Windows with appropriate adaptations
+
+## Future Enhancements
+
+- Agent integration (LLM-based reasoning)
+- Screen capture and analysis
+- Fine grid mode for precise targeting
+- Highlight layers for suggested targets
+- Persistent window positioning
+- Custom tray icon
+- Task list implementation
+- Settings panel
+
+## Development
+
+The application follows Electron best practices:
+- Context isolation enabled
+- Node integration disabled in renderers
+- Preload scripts for secure IPC
+- Minimal renderer dependencies
+- Single persistent windows (no repeated creation/destruction)
+
+## File Structure
+
+```
+src/
+├── main/
+│   └── index.js           # Main process
+├── renderer/
+│   ├── overlay/
+│   │   ├── index.html     # Overlay UI
+│   │   └── preload.js     # Overlay IPC bridge
+│   └── chat/
+│       ├── index.html     # Chat UI
+│       └── preload.js     # Chat IPC bridge
+└── assets/
+    └── tray-icon.png      # System tray icon (placeholder)
+```

package/INSTALLATION.md

@@ -0,0 +1,350 @@
+# Installation Guide
+
+This guide covers multiple installation methods for the Copilot-Liku CLI across different platforms.
+
+## Table of Contents
+
+- [Quick Install (npm)](#quick-install-npm)
+- [Platform-Specific Installation](#platform-specific-installation)
+  - [macOS](#macos)
+  - [Windows](#windows)
+  - [Linux](#linux)
+- [Local Development](#local-development)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Install (npm)
+
+The fastest way to install Liku is via npm:
+
+```bash
+npm install -g copilot-liku-cli
+```
+
+Verify installation:
+```bash
+liku --version
+liku --help
+```
+
+Start using Liku:
+```bash
+liku start
+```
+
+---
+
+## Platform-Specific Installation
+
+### macOS
+
+#### Option 1: npm (Recommended)
+
+```bash
+npm install -g copilot-liku-cli
+```
+
+#### Option 2: Homebrew (Coming Soon)
+
+Once we set up a Homebrew tap, you'll be able to install via:
+```bash
+brew tap TayDa64/liku
+brew install liku
+```
+
+**Benefits of Homebrew:**
+- Automatic updates via `brew upgrade`
+- Better integration with macOS
+- Easy uninstallation
+
+#### Verify Installation
+
+```bash
+liku --version
+```
+
+### Windows
+
+#### Option 1: npm (Recommended)
+
+Open PowerShell or Command Prompt:
+```powershell
+npm install -g copilot-liku-cli
+```
+
+#### Option 2: Scoop (Coming Soon)
+
+Once we set up a Scoop manifest, you'll be able to install via:
+```powershell
+scoop bucket add liku https://github.com/TayDa64/scoop-liku
+scoop install liku
+```
+
+#### Option 3: Chocolatey (Coming Soon)
+
+```powershell
+choco install copilot-liku-cli
+```
+
+**Benefits of Scoop/Chocolatey:**
+- Automatic updates
+- System-wide installation
+- Easy uninstallation
+
+#### Verify Installation
+
+```powershell
+liku --version
+```
+
+### Linux
+
+#### Option 1: npm (Recommended)
+
+```bash
+npm install -g copilot-liku-cli
+```
+
+#### Option 2: Distribution Packages (Future)
+
+We plan to provide `.deb` and `.rpm` packages for easy installation on Debian/Ubuntu and Red Hat/Fedora systems.
+
+**Ubuntu/Debian (Coming Soon):**
+```bash
+wget https://github.com/TayDa64/copilot-Liku-cli/releases/latest/download/liku.deb
+sudo dpkg -i liku.deb
+```
+
+**Red Hat/Fedora (Coming Soon):**
+```bash
+wget https://github.com/TayDa64/copilot-Liku-cli/releases/latest/download/liku.rpm
+sudo rpm -i liku.rpm
+```
+
+#### Verify Installation
+
+```bash
+liku --version
+```
+
+---
+
+## Local Development
+
+For contributors and developers who want to work on the Liku CLI source code:
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/TayDa64/copilot-Liku-cli.git
+cd copilot-Liku-cli
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install
+```
+
+### 3. Link for Global Usage
+
+```bash
+npm link
+```
+
+This creates a symbolic link from your global `node_modules` to your local development directory. Any changes you make will be immediately available when you run `liku`.
+
+### 4. Verify Setup
+
+```bash
+liku --version
+liku --help
+```
+
+For more details on contributing, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Troubleshooting
+
+### Command Not Found
+
+If you see `liku: command not found` after installation:
+
+#### Check npm global path
+
+```bash
+npm bin -g
+```
+
+#### Add npm global bin to PATH
+
+**macOS/Linux:**
+Add this to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`:
+```bash
+export PATH="$(npm bin -g):$PATH"
+```
+
+**Windows PowerShell:**
+Add to your PowerShell profile:
+```powershell
+$env:PATH += ";$(npm bin -g)"
+```
+
+Or permanently via System Properties → Environment Variables.
+
+### Permission Errors (npm global install)
+
+#### Option 1: Use a Node version manager (Recommended)
+
+Install Node via [nvm](https://github.com/nvm-sh/nvm) (Unix/Mac) or [nvm-windows](https://github.com/coreybutler/nvm-windows):
+
+```bash
+# Unix/Mac
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 22
+nvm use 22
+```
+
+#### Option 2: Configure npm to use a user directory
+
+```bash
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+```
+
+Then add `~/.npm-global/bin` to your PATH.
+
+#### Option 3: Use sudo (Not Recommended)
+
+```bash
+sudo npm install -g copilot-liku-cli
+```
+
+**Note:** Using sudo can cause permission issues later. We recommend Option 1 or 2.
+
+### Package Version Issues
+
+#### Update to Latest Version
+
+```bash
+npm update -g copilot-liku-cli
+```
+
+#### Force Reinstall
+
+```bash
+npm uninstall -g copilot-liku-cli
+npm install -g copilot-liku-cli
+```
+
+### Multiple Node Versions
+
+If you have multiple Node versions installed, ensure you're using the correct one:
+
+```bash
+node --version    # Should be v22 or higher
+which node        # Shows which Node is in use
+```
+
+### Windows-Specific Issues
+
+#### PowerShell Execution Policy
+
+If you see execution policy errors:
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+#### Path Length Limitations
+
+Windows has path length limitations. If you encounter errors, try:
+1. Enable long path support (Windows 10 1607+)
+2. Install in a shorter path
+
+### Verifying Installation
+
+Run these commands to verify everything is working:
+
+```bash
+# Check version
+liku --version
+
+# Show help
+liku --help
+
+# Test a simple command
+liku screenshot --help
+```
+
+---
+
+## Updating Liku
+
+### npm Installation
+
+```bash
+npm update -g copilot-liku-cli
+```
+
+### Homebrew (macOS)
+
+```bash
+brew upgrade liku
+```
+
+### Scoop (Windows)
+
+```powershell
+scoop update liku
+```
+
+### Local Development
+
+```bash
+cd copilot-Liku-cli
+git pull origin main
+npm install
+```
+
+---
+
+## Uninstalling
+
+### npm
+
+```bash
+npm uninstall -g copilot-liku-cli
+```
+
+### Homebrew
+
+```bash
+brew uninstall liku
+```
+
+### Scoop
+
+```powershell
+scoop uninstall liku
+```
+
+### Local Development Link
+
+```bash
+npm unlink -g copilot-liku-cli
+```
+
+---
+
+## Next Steps
+
+After installation:
+
+1. **Start the application:** `liku start`
+2. **Read the Quick Start:** [QUICKSTART.md](QUICKSTART.md)
+3. **Explore commands:** `liku --help`
+4. **Read the full guide:** [README.md](README.md)
+
+For issues or questions, please visit our [GitHub Issues](https://github.com/TayDa64/copilot-Liku-cli/issues).

package/LICENSE.md

@@ -0,0 +1 @@
+ Copyright (c) GitHub 2025. All rights reserved. Use is subject to GitHub's [Pre-release License Terms](https://docs.github.com/en/site-policy/github-terms/github-pre-release-license-terms)