quick-sh 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 YoungChou
+
+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,226 @@
+# Quick Shell
+
+[![npm version](https://badge.fury.io/js/@youngchou%2Fquick-sh.svg)](https://badge.fury.io/js/@youngchou%2Fquick-sh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A local script management tool for quick execution of JavaScript and Shell scripts with advanced alias support.
+
+[中文文档](./README-zh.md) | English
+
+## Features
+
+- 🚀 **Quick Execution**: Run local scripts with simple `q script-name` command
+- 📁 **Multiple Formats**: Support JavaScript (.js), Shell scripts (.sh), and directories
+- 🔗 **Advanced Aliases**: Configure custom aliases with relative paths, absolute paths, and system commands
+- 📝 **Parameter Forwarding**: Pass arguments transparently to your scripts
+- 🎯 **Smart Priority**: Alias config > Script files > System commands
+- ⚡ **Global Access**: Install once, use anywhere
+- 🧪 **Comprehensive Testing**: 16 automated test cases ensure reliability
+
+## Installation
+
+```bash
+npm install -g @youngchou/quick-sh
+```
+
+After installation, you can use the `q` command globally.
+
+## Quick Start
+
+### 1. Set Script Directory
+
+```bash
+# Set your script directory
+q -path /path/to/your/scripts
+
+# Check current status
+q -list
+```
+
+### 2. Run Scripts
+
+```bash
+# Run a JavaScript file
+q myscript
+
+# Run a shell script
+q deploy.sh
+
+# Run with parameters
+q backup --target /data --compress
+
+# Execute directory (looks for index.js or index.sh)
+q myproject
+```
+
+### 3. Configure Aliases
+
+Create or edit `config.json` in your script directory:
+
+```json
+{
+  "aliases": {
+    "deploy": {
+      "bin": "./deploy/index.js"
+    },
+    "backup": {
+      "bin": "/usr/local/bin/backup.sh"
+    },
+    "start": {
+      "bin": "npm start"
+    }
+  }
+}
+```
+
+## Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `q -path <dir>` | Set script directory | `q -path ~/scripts` |
+| `q -list` | Show current status and available scripts | `q -list` |
+| `q -help` | Display help information | `q -help` |
+| `q <script>` | Execute script or alias | `q deploy` |
+
+## Alias Configuration
+
+### Supported Alias Types
+
+1. **Relative Path**: Relative to script directory
+   ```json
+   {
+     "aliases": {
+       "deploy": {"bin": "./deploy/index.js"}
+     }
+   }
+   ```
+
+2. **Absolute Path**: Full system path
+   ```json
+   {
+     "aliases": {
+       "backup": {"bin": "/usr/local/bin/backup.sh"}
+     }
+   }
+   ```
+
+3. **System Command**: Execute system commands
+   ```json
+   {
+     "aliases": {
+       "list": {"bin": "ls -la"},
+       "findnode": {"bin": "which node"}
+     }
+   }
+   ```
+
+### Execution Priority
+
+1. **Alias Configuration** (highest priority)
+2. **Script Files** (medium priority)
+3. **System Commands** (lowest priority)
+
+## Parameter Forwarding
+
+All parameters are transparently forwarded to target scripts:
+
+```bash
+# These parameters will be passed to the script
+q deploy --env production --verbose
+q backup /data/important --compress
+```
+
+In your script, access parameters normally:
+- **JavaScript**: `process.argv`
+- **Shell**: `$1`, `$2`, etc.
+
+## Examples
+
+### Directory Structure
+```
+~/scripts/
+├── config.json
+├── deploy.js
+├── backup.sh
+└── utils/
+    └── index.js
+```
+
+### config.json
+```json
+{
+  "aliases": {
+    "deploy": {"bin": "./deploy.js"},
+    "util": {"bin": "./utils"},
+    "backup": {"bin": "./backup.sh"},
+    "start": {"bin": "npm start"}
+  }
+}
+```
+
+### Usage
+```bash
+# Execute via alias
+q deploy --env prod
+
+# Execute shell script
+q backup.sh /data
+
+# Execute directory (looks for utils/index.js)
+q utils --help
+
+# System command via alias
+q start
+```
+
+## Development
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Manual testing with example scripts
+npm run test:manual
+```
+
+### Project Structure
+
+```
+quick-sh/
+├── bin/           # CLI entry point
+├── lib/           # Core modules
+│   ├── config.js      # Configuration management
+│   ├── executor.js    # Script execution
+│   ├── help.js        # Help text
+│   ├── script-manager.js  # Main logic
+│   └── utils.js       # Utilities
+├── test/          # Test suite
+└── examples/      # Example scripts
+```
+
+## Requirements
+
+- Node.js >= 14.0.0
+- npm or yarn
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+- **YoungChou** - *Initial work*
+
+## Support
+
+If you encounter any issues or have questions, please [open an issue](https://github.com/YoungChou/quick-sh/issues) on GitHub. 

package/bin/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { setPath } = require('../lib/config');
+const { executeScript, showStatus } = require('../lib/script-manager');
+const { showHelp } = require('../lib/help');
+
+// 自定义命令处理 - 在 commander.js 解析之前拦截
+const args = process.argv.slice(2);
+
+if (args.length > 0) {
+  const firstArg = args[0];
+  
+  // 处理内置命令
+  if (firstArg === '-path' && args.length >= 2) {
+    setPath(args[1]);
+    return;
+  }
+  
+  if (firstArg === '-list' || firstArg === '-l') {
+    showStatus();
+    return;
+  }
+  
+  if (firstArg === '-help' || firstArg === '-h') {
+    showHelp();
+    return;
+  }
+}
+
+// 设置命令行程序
+program
+  .name('q')
+  .description('Quick Shell - Local script management tool')
+  .version('1.0.0');
+
+// 默认命令：执行脚本
+program
+  .argument('[script]', 'Script name to execute')
+  .argument('[args...]', 'Arguments to pass to the script')
+  .action(async (script, args) => {
+    if (!script) {
+      await showStatus();
+      return;
+    }
+    await executeScript(script, args || []);
+  });
+
+program.parse(); 

package/lib/config.js

@@ -0,0 +1,71 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+// 配置文件路径
+const CONFIG_DIR = path.join(os.homedir(), '.quick-sh');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+// 确保配置目录存在
+async function ensureConfigDir() {
+  await fs.ensureDir(CONFIG_DIR);
+}
+
+// 读取全局配置
+async function readConfig() {
+  try {
+    await ensureConfigDir();
+    if (await fs.pathExists(CONFIG_FILE)) {
+      return await fs.readJson(CONFIG_FILE);
+    }
+    return {};
+  } catch (error) {
+    return {};
+  }
+}
+
+// 写入全局配置
+async function writeConfig(config) {
+  try {
+    await ensureConfigDir();
+    await fs.writeJson(CONFIG_FILE, config, { spaces: 2 });
+  } catch (error) {
+    console.error('Error writing config:', error.message);
+  }
+}
+
+// 读取脚本目录中的alias配置
+async function readAliasConfig(scriptPath) {
+  try {
+    const aliasConfigPath = path.join(scriptPath, 'config.json');
+    if (await fs.pathExists(aliasConfigPath)) {
+      return await fs.readJson(aliasConfigPath);
+    }
+    return {};
+  } catch (error) {
+    return {};
+  }
+}
+
+// 设置脚本路径
+async function setPath(scriptPath) {
+  const absolutePath = path.resolve(scriptPath);
+  
+  if (!await fs.pathExists(absolutePath)) {
+    console.error(`Path does not exist: ${absolutePath}`);
+    process.exit(1);
+  }
+  
+  const config = await readConfig();
+  config.scriptPath = absolutePath;
+  await writeConfig(config);
+  
+  console.log(`Script path set to: ${absolutePath}`);
+}
+
+module.exports = {
+  readConfig,
+  writeConfig,
+  readAliasConfig,
+  setPath
+}; 

package/lib/executor.js

@@ -0,0 +1,98 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { spawn } = require('child_process');
+
+// 执行文件
+async function executeFile(filePath, args = []) {
+  const ext = path.extname(filePath);
+  const fileName = path.basename(filePath);
+  
+  console.log(`Executing: ${fileName}${args.length > 0 ? ' with args: ' + args.join(' ') : ''}`);
+  
+  try {
+    if (ext === '.js' || ext === '.mjs') {
+      // 使用spawn来保持交互性
+      const child = spawn('node', [filePath, ...args], {
+        stdio: 'inherit',
+        cwd: path.dirname(filePath)
+      });
+      
+      child.on('close', (code) => {
+        process.exit(code);
+      });
+      
+    } else if (ext === '.sh') {
+      // 确保shell脚本有执行权限
+      try {
+        await fs.chmod(filePath, 0o755);
+      } catch (error) {
+        // 忽略权限设置错误
+      }
+      
+      const child = spawn('sh', [filePath, ...args], {
+        stdio: 'inherit',
+        cwd: path.dirname(filePath)
+      });
+      
+      child.on('close', (code) => {
+        process.exit(code);
+      });
+      
+    } else {
+      console.error(`Unsupported file type: ${ext}`);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`Error executing script: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// 从目录执行脚本
+async function executeFromDirectory(dirPath, args = []) {
+  const possibleFiles = [
+    path.join(dirPath, 'index.js'),
+    path.join(dirPath, 'index.sh'),
+    path.join(dirPath, 'index.mjs')
+  ];
+  
+  let targetFile = null;
+  for (const file of possibleFiles) {
+    if (await fs.pathExists(file)) {
+      targetFile = file;
+      break;
+    }
+  }
+  
+  if (!targetFile) {
+    console.error(`No index.js, index.sh, or index.mjs found in directory: ${dirPath}`);
+    process.exit(1);
+  }
+  
+  await executeFile(targetFile, args);
+}
+
+// 执行系统命令
+async function executeSystemCommand(command, args = []) {
+  console.log(`Executing system command: ${command}${args.length > 0 ? ' with args: ' + args.join(' ') : ''}`);
+  
+  const child = spawn(command, args, {
+    stdio: 'inherit',
+    cwd: process.cwd()
+  });
+  
+  child.on('close', (code) => {
+    process.exit(code);
+  });
+  
+  child.on('error', (error) => {
+    console.error(`Error executing system command: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  executeFile,
+  executeFromDirectory,
+  executeSystemCommand
+}; 

package/lib/help.js

@@ -0,0 +1,62 @@
+// 显示帮助信息
+function showHelp() {
+  console.log(`
+🚀 Quick Shell - Local Script Management Tool
+
+DESCRIPTION:
+  Quick Shell (q) is a command-line tool that helps you manage and execute
+  local scripts quickly. It supports JavaScript (.js, .mjs), Shell (.sh) 
+  scripts, and directory-based scripts.
+
+USAGE:
+  q [command] [options]
+  q <script> [args...]
+
+COMMANDS:
+  -path <directory>   Set the script directory path
+  -list, -l          Show current configuration and available scripts
+  -help, -h          Show this help message
+  --version, -V      Show version number
+
+SCRIPT EXECUTION:
+  q <script>          Execute a script by name
+  q <script> [args]   Execute a script with arguments
+
+EXAMPLES:
+  # Setup
+  q -path /path/to/scripts      Set script directory
+  q -list                       View current configuration
+  
+  # Execute scripts
+  q hello                       Run hello.js or hello.sh
+  q backup /src /dest           Run backup script with arguments
+  q deploy production --verbose Run deploy script with multiple args
+  q my-folder                   Run index.js/index.sh from my-folder/
+
+SUPPORTED FILE TYPES:
+  .js, .mjs    JavaScript files (executed with node)
+  .sh          Shell scripts (executed with sh)
+  directories  Looks for index.js, index.sh, or index.mjs
+
+ALIAS CONFIGURATION:
+  Create a config.json file in your script directory to define aliases:
+  
+  {
+    "chat": {"bin": "./chat/src/main.js"},  // Relative path
+    "python3": "/usr/bin/python3",          // Absolute path  
+    "w": "which"                            // System command
+  }
+  
+  Execution priority: Alias config > Script files > System commands
+
+CONFIGURATION:
+  Global config: ~/.quick-sh/config.json
+  Alias config: <script-path>/config.json
+  
+For more information, visit: https://github.com/your-repo/quick-sh
+`);
+}
+
+module.exports = {
+  showHelp
+}; 

package/lib/script-manager.js

@@ -0,0 +1,153 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { readConfig, readAliasConfig } = require('./config');
+const { executeFile, executeFromDirectory, executeSystemCommand } = require('./executor');
+const { checkSystemCommand } = require('./utils');
+
+// 执行脚本（核心逻辑，包含alias处理和优先级）
+async function executeScript(scriptName, args = []) {
+  const config = await readConfig();
+  
+  if (!config.scriptPath) {
+    console.error('No script path configured. Use "q -path <directory>" to set one.');
+    process.exit(1);
+  }
+  
+  // 优先级1: 检查alias配置
+  const aliasConfig = await readAliasConfig(config.scriptPath);
+  if (aliasConfig[scriptName]) {
+    const aliasValue = aliasConfig[scriptName];
+    
+    if (typeof aliasValue === 'string') {
+      // 字符串值：可能是绝对路径或系统命令
+      if (path.isAbsolute(aliasValue)) {
+        // 绝对路径
+        if (await fs.pathExists(aliasValue)) {
+          console.log(`Executing alias (absolute path): ${aliasValue}`);
+          await executeFile(aliasValue, args);
+          return;
+        } else {
+          console.error(`Alias target not found: ${aliasValue}`);
+          process.exit(1);
+        }
+      } else {
+        // 系统命令
+        if (await checkSystemCommand(aliasValue)) {
+          await executeSystemCommand(aliasValue, args);
+          return;
+        } else {
+          console.error(`System command not found: ${aliasValue}`);
+          process.exit(1);
+        }
+      }
+    } else if (aliasValue && typeof aliasValue === 'object' && aliasValue.bin) {
+      // 对象值：相对路径配置
+      const relativePath = aliasValue.bin;
+      const fullPath = path.resolve(config.scriptPath, relativePath);
+      
+      if (await fs.pathExists(fullPath)) {
+        console.log(`Executing alias (relative path): ${relativePath}`);
+        await executeFile(fullPath, args);
+        return;
+      } else {
+        console.error(`Alias target not found: ${fullPath}`);
+        process.exit(1);
+      }
+    } else {
+      console.error(`Invalid alias configuration for: ${scriptName}`);
+      process.exit(1);
+    }
+  }
+  
+  // 优先级2: 检查path中的文件（原有逻辑）
+  const scriptPath = path.join(config.scriptPath, scriptName);
+  
+  // 检查是否是文件夹
+  if (await fs.pathExists(scriptPath) && (await fs.stat(scriptPath)).isDirectory()) {
+    await executeFromDirectory(scriptPath, args);
+    return;
+  }
+  
+  // 检查不同的文件扩展名
+  const possibleFiles = [
+    scriptPath,
+    `${scriptPath}.js`,
+    `${scriptPath}.sh`,
+    `${scriptPath}.mjs`
+  ];
+  
+  let targetFile = null;
+  for (const file of possibleFiles) {
+    if (await fs.pathExists(file)) {
+      targetFile = file;
+      break;
+    }
+  }
+  
+  if (targetFile) {
+    await executeFile(targetFile, args);
+    return;
+  }
+  
+  // 优先级3: 检查系统可执行命令
+  if (await checkSystemCommand(scriptName)) {
+    await executeSystemCommand(scriptName, args);
+    return;
+  }
+  
+  console.error(`Command not found: ${scriptName}`);
+  console.error(`Looked in:`);
+  console.error(`  - Alias config: ${path.join(config.scriptPath, 'config.json')}`);
+  console.error(`  - Script directory: ${config.scriptPath}`);
+  console.error(`  - System PATH`);
+  process.exit(1);
+}
+
+// 显示当前配置和可用脚本
+async function showStatus() {
+  const config = await readConfig();
+  
+  if (config.scriptPath) {
+    console.log(`Current script path: ${config.scriptPath}`);
+    
+    // 列出可用的脚本
+    try {
+      const files = await fs.readdir(config.scriptPath);
+      const scripts = [];
+      
+      for (const file of files) {
+        const filePath = path.join(config.scriptPath, file);
+        const stat = await fs.stat(filePath);
+        
+        if (stat.isDirectory()) {
+          // 检查目录是否包含index文件
+          const indexFiles = ['index.js', 'index.sh', 'index.mjs'];
+          for (const indexFile of indexFiles) {
+            if (await fs.pathExists(path.join(filePath, indexFile))) {
+              scripts.push(`${file}/ (${indexFile})`);
+              break;
+            }
+          }
+        } else if (file.endsWith('.js') || file.endsWith('.sh') || file.endsWith('.mjs')) {
+          scripts.push(file);
+        }
+      }
+      
+      if (scripts.length > 0) {
+        console.log('\nAvailable scripts:');
+        scripts.forEach(script => console.log(`  - ${script}`));
+      } else {
+        console.log('\nNo executable scripts found.');
+      }
+    } catch (error) {
+      console.error('Error reading script directory:', error.message);
+    }
+  } else {
+    console.log('No script path configured. Use "q -path <directory>" to set one.');
+  }
+}
+
+module.exports = {
+  executeScript,
+  showStatus
+}; 

package/lib/utils.js

@@ -0,0 +1,18 @@
+const { execSync } = require('child_process');
+
+// 检查系统命令是否存在
+async function checkSystemCommand(command) {
+  try {
+    const isWindows = process.platform === 'win32';
+    const whichCommand = isWindows ? 'where' : 'which';
+    
+    execSync(`${whichCommand} ${command}`, { stdio: 'ignore' });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+module.exports = {
+  checkSystemCommand
+}; 

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "quick-sh",
+  "version": "1.0.0",
+  "description": "A local script management tool for quick execution of JavaScript and Shell scripts with alias support",
+  "main": "lib/script-manager.js",
+  "bin": {
+    "q": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/test.js",
+    "test:manual": "echo \"Run manual tests with: q test-args, q test-args.sh, q test-dir\"",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "shell",
+    "script",
+    "cli",
+    "automation",
+    "local-scripts",
+    "alias",
+    "command-line",
+    "script-manager",
+    "javascript",
+    "bash",
+    "quick-execution"
+  ],
+  "author": "YoungChou <your-email@example.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YoungChou/quick-sh.git"
+  },
+  "homepage": "https://github.com/YoungChou/quick-sh#readme",
+  "bugs": {
+    "url": "https://github.com/YoungChou/quick-sh/issues"
+  },
+  "dependencies": {
+    "commander": "^9.0.0",
+    "fs-extra": "^11.0.0"
+  },
+  "devDependencies": {},
+  "preferGlobal": true,
+  "directories": {
+    "example": "examples",
+    "lib": "lib",
+    "test": "test"
+  }
+}