{"_id":"@c3-lefv-1/lsh","name":"@c3-lefv-1/lsh","dist-tags":{"latest":"0.3.0"},"versions":{"0.3.0":{"name":"@c3-lefv-1/lsh","version":"0.3.0","description":"A powerful, extensible shell with advanced job management, database persistence, and modern CLI features","main":"dist/app.js","bin":{"lsh":"dist/cli.js"},"repository":{"type":"git","url":"git+https://github.com/lefv/lsh.git"},"homepage":"https://github.com/lefv/lsh#readme","bugs":{"url":"https://github.com/lefv/lsh/issues"},"scripts":{"build":"tsc","compile-ts":"tsc -b","compile-nexe":"node build.js","build-bin":"npm run clean; npm run compile-ts; npm run compile-nexe","start":"node dist/app.js","start:pipeline":"npm run compile-ts && node dist/pipeline/pipeline-service.js","watch":"tsc --watch","test":"node --experimental-vm-modules ./node_modules/.bin/jest","test:coverage":"node --experimental-vm-modules ./node_modules/.bin/jest --coverage","test:integration":"npm run test -- --testMatch=\"**/*.integration.test.(js|ts)\"","clean":"rm -rf ./build; rm -rf ./bin; rm -rf ./dist","electron":"npm run compile-ts && electron src/electron/main.cjs","electron-dev":"NODE_ENV=development npm run electron","dashboard":"npm run electron","app":"npm run electron","lint":"eslint src --ext .js,.ts,.tsx","lint:fix":"eslint src --ext .js,.ts,.tsx --fix","typecheck":"tsc --noEmit","audit:security":"npm audit --audit-level moderate"},"keywords":["cli","shell","terminal","job-manager","cron","daemon","zsh","bash","posix","database-persistence","task-scheduler","command-line","automation","devops","cicd"],"engines":{"node":">=18.0.0","npm":">=8.0.0"},"type":"module","author":{"name":"Luis Fernandez de la Vara","email":"luis@lefv.io"},"license":"MIT","dependencies":{"@deck.gl/core":"^8.9.33","@inkjs/ui":"^1.0.0","@octokit/rest":"^20.1.0","@supabase/supabase-js":"^2.57.4","@types/ink":"^2.0.3","@types/ioredis":"^4.28.10","@types/socket.io":"^3.0.1","@xstate/react":"^4.1.0","async":"^3.2.5","async-lock":"^1.4.0","axios":"^1.5.1","bcrypt":"^5.1.1","chalk":"^5.3.0","cheerio":"^1.0.0-rc.12","chokidar":"^3.6.0","commander":"^10.0.1","cors":"^2.8.5","csv":"^6.3.5","dotenv":"^16.4.5","express":"^5.1.0","fprint":"^2.0.1","glob":"^10.3.12","gradstop":"^2.2.3","helmet":"^8.1.0","highlightjs":"^9.16.2","http-proxy-middleware":"^3.0.5","ink":"^4.4.1","ink-text-input":"^5.0.1","inquirer":"^9.2.12","ioredis":"^5.8.0","jest":"^29.7.0","jsonwebtoken":"^9.0.2","lodash":"^4.17.21","mocha":"^10.3.0","ncc":"^0.3.6","nexe":"^4.0.0-rc.2","node-cron":"^3.0.3","node-fetch":"^3.3.2","nodemon":"^3.0.1","ora":"^8.0.1","path":"^0.12.7","pg":"^8.16.3","react":"^18.2.0","repl":"^0.1.3","sendgrid":"^5.2.3","socket.io":"^4.8.1","uuid":"^10.0.0","xstate":"^5.9.1","zapier-platform-core":"15.4.1","zx":"^7.2.3"},"devDependencies":{"@babel/preset-env":"^7.23.2","@babel/preset-react":"^7.24.1","@types/async-lock":"^1.4.2","@types/jest":"^30.0.0","@types/node":"^20.12.7","@types/react":"^18.2.73","@types/request":"^2.48.12","@types/supertest":"^6.0.3","@typescript-eslint/eslint-plugin":"^8.44.1","@typescript-eslint/parser":"^8.44.1","babel-jest":"^29.7.0","electron":"^38.1.2","eslint":"^9.36.0","eslint-plugin-react":"^7.37.5","eslint-plugin-react-hooks":"^5.2.0","supertest":"^7.1.4","ts-jest":"^29.4.4","typescript":"^5.4.5"},"_id":"@c3-lefv-1/lsh@0.3.0","gitHead":"66f8c082c28fb14a2c20a0820a099d4ea0dda3e6","_nodeVersion":"24.6.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-z6+cwALKQh5Zs9t3Ye3amTZDMfKHidOnYEW409TlXhfU1LNUl6/lUZdSNb02NDIPrUVEOZ+m3UO+uPM5KHusbw==","shasum":"373326cdd879a7d78266d303c68bd8567412bacb","tarball":"https://registry.npmjs.org/@c3-lefv-1/lsh/-/lsh-0.3.0.tgz","fileCount":69,"unpackedSize":820046,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAXAdujb428kWCio7plePA4pZY4lKi0iPHrgu8IeIVsYAiEAu9+E1LNZokuad5dqIty2017gqVkTTMcXsshn0okEFNY="}]},"_npmUser":{"name":"c3-lefv-1","email":"luis@lefv.io"},"directories":{},"maintainers":[{"name":"c3-lefv-1","email":"luis@lefv.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/lsh_0.3.0_1759319597354_0.29966821452985837"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-01T11:53:17.288Z","0.3.0":"2025-10-01T11:53:17.574Z","modified":"2025-10-01T11:53:17.857Z"},"maintainers":[{"name":"c3-lefv-1","email":"luis@lefv.io"}],"description":"A powerful, extensible shell with advanced job management, database persistence, and modern CLI features","homepage":"https://github.com/lefv/lsh#readme","keywords":["cli","shell","terminal","job-manager","cron","daemon","zsh","bash","posix","database-persistence","task-scheduler","command-line","automation","devops","cicd"],"repository":{"type":"git","url":"git+https://github.com/lefv/lsh.git"},"author":{"name":"Luis Fernandez de la Vara","email":"luis@lefv.io"},"bugs":{"url":"https://github.com/lefv/lsh/issues"},"license":"MIT","readme":"# LSH - Enhanced Shell with Job Management\n\n`lsh` is an extensible CLI shell with advanced job management, CI/CD integration, and persistent daemon for reliable job execution. Built with TypeScript, it provides POSIX-compatible shell features with modern enhancements for automation and pipeline orchestration.\n\n## Features\n\n### Core Shell Features\n- **POSIX Shell Compatibility** - Standard shell syntax and builtins\n- **ZSH-Compatible Features** - Extended globbing, parameter expansion, associative arrays\n- **Interactive Terminal UI** - Built with React/Ink for rich terminal experiences\n- **Command History** - Persistent history with search and replay\n- **Tab Completion** - Intelligent completion system\n\n### Job Management\n- **Persistent Job Daemon** - Background daemon for reliable job execution\n- **Cron-Style Scheduling** - Schedule jobs with cron expressions\n- **Job Control** - Start, stop, monitor, and manage background jobs\n- **Job Registry** - Centralized job tracking and persistence\n\n### CI/CD Integration\n- **Webhook Receiver** - GitHub, GitLab, and Jenkins webhook support\n- **Pipeline Orchestration** - Workflow engine for complex pipelines\n- **Build Analytics** - Track build metrics and performance\n- **Cache Management** - Intelligent caching for faster builds\n\n### Security\n- **Command Validation** - Prevents command injection attacks\n- **Environment Variable Validation** - Validates configuration at startup\n- **Webhook Signature Verification** - HMAC verification for webhooks\n- **Secure Defaults** - Fail-safe configuration in production\n\n### API & Integration\n- **RESTful API** - HTTP API for job control and monitoring\n- **JWT Authentication** - Secure API access with token-based auth\n- **ML Pipeline Support** - Integration with machine learning workflows\n- **Database Persistence** - PostgreSQL/Supabase for data storage\n\n## Installation\n\n### Prerequisites\n- Node.js 18.0.0 or higher\n- npm 8.0.0 or higher\n- PostgreSQL (optional, for persistence features)\n- Redis (optional, for caching)\n\n### Quick Start\n\n**Install from npm (Recommended):**\n\n```bash\nnpm install -g lsh\n```\n\n**Or use the install script:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/lefv/lsh/main/scripts/install.sh | bash\n```\n\n**Verify installation:**\n\n```bash\nlsh --version\nlsh --help\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/lefv/lsh.git\ncd lsh\n\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Link globally (optional)\nnpm link\n\n# Run\nlsh\n```\n\n## Quick Start\n\n### Interactive Shell\n\n```bash\n# Start interactive shell\nlsh\n\n# Execute commands\nlsh> ls -la\nlsh> echo \"Hello, LSH!\"\nlsh> cd /tmp && pwd\n```\n\n### Daemon Mode\n\n```bash\n# Start the persistent daemon\nlsh daemon start\n\n# Check daemon status\nlsh daemon status\n\n# Stop the daemon\nlsh daemon stop\n```\n\n### Job Management\n\n```bash\n# Add a scheduled job (runs every day at midnight)\nlsh cron add --name \"daily-backup\" --schedule \"0 0 * * *\" --command \"backup.sh\"\n\n# List all jobs\nlsh cron list\n\n# Trigger a job manually\nlsh cron trigger daily-backup\n\n# Remove a job\nlsh cron remove daily-backup\n```\n\n### API Server\n\n```bash\n# Start API server\nlsh api start --port 3030\n\n# With authentication\nLSH_API_KEY=your_secret_key lsh api start\n```\n\n## Configuration\n\n### Environment Variables\n\nCopy `.env.example` to `.env` and configure:\n\n```bash\n# Core Configuration\nNODE_ENV=development                    # Environment mode\nLSH_API_ENABLED=true                    # Enable API server\nLSH_API_PORT=3030                       # API server port\n\n# Security (REQUIRED in production)\nLSH_API_KEY=<generate-32-char-key>      # API authentication key\nLSH_JWT_SECRET=<generate-32-char-secret> # JWT signing secret\nLSH_ALLOW_DANGEROUS_COMMANDS=false      # Allow risky commands (use with caution)\n\n# Webhooks\nLSH_ENABLE_WEBHOOKS=true                # Enable webhook receiver\nWEBHOOK_PORT=3033                       # Webhook receiver port\nGITHUB_WEBHOOK_SECRET=<your-secret>     # GitHub webhook secret\nGITLAB_WEBHOOK_SECRET=<your-secret>     # GitLab webhook secret\nJENKINS_WEBHOOK_SECRET=<your-secret>    # Jenkins webhook secret\n\n# Database (Optional)\nDATABASE_URL=postgresql://localhost:5432/cicd\nSUPABASE_URL=https://your-project.supabase.co\nSUPABASE_ANON_KEY=<your-anon-key>\n\n# Caching (Optional)\nREDIS_URL=redis://localhost:6379\n\n# Monitoring\nMONITORING_API_PORT=3031                # Monitoring API port\n```\n\n### Security Best Practices\n\n**🔒 Production Deployment:**\n\n1. **Always set secrets** - API keys and JWT secrets are mandatory in production\n2. **Generate strong keys** - Use `openssl rand -hex 32` for secrets\n3. **Enable webhook verification** - Set webhook secrets when using webhooks\n4. **Review dangerous commands** - Keep `LSH_ALLOW_DANGEROUS_COMMANDS=false`\n5. **Use environment variables** - Never commit `.env` to version control\n\n**Environment Validation:**\n\nLSH validates environment variables at startup and fails fast in production if:\n- Required secrets are missing or too short\n- Invalid URL formats\n- Dangerous commands enabled in production\n\n## Development\n\n### Building\n\n```bash\n# Build TypeScript\nnpm run build\n\n# Watch mode for development\nnpm run watch\n\n# Type checking only\nnpm run typecheck\n```\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run integration tests\nnpm run test:integration\n\n# Lint code\nnpm run lint\n\n# Auto-fix lint issues\nnpm run lint:fix\n```\n\n**Current Test Coverage:** ~1.5% (baseline established, actively improving)\n\n**Well-tested modules:**\n- `command-validator.ts` - 100% coverage\n- `env-validator.ts` - 74% coverage\n\n### Electron App\n\n```bash\n# Run as desktop application\nnpm run electron\n\n# Development mode\nnpm run electron-dev\n\n# Access dashboards\nnpm run dashboard\n```\n\n## Architecture\n\n### Core Components\n\n- **`src/lib/shell-executor.ts`** - Main shell command executor\n- **`src/lib/job-manager.ts`** - Job lifecycle management\n- **`src/daemon/lshd.ts`** - Persistent background daemon\n- **`src/daemon/api-server.ts`** - RESTful API server\n- **`src/cicd/webhook-receiver.ts`** - CI/CD webhook integration\n\n### Data Flow\n\n```\nUser Command → Parser → AST → Executor → Output\n                                ↓\n                          Job Manager\n                                ↓\n                          Daemon (persistent)\n                                ↓\n                          Database/Redis\n```\n\n### Security Architecture\n\n```\nAPI Request → JWT Validation → Command Validation → Execution\nWebhook → HMAC Verification → Event Processing → Job Trigger\nDaemon Startup → Env Validation → Fail Fast if Invalid\n```\n\n## API Reference\n\n### Authentication\n\n```bash\n# Include API key in header\ncurl -H \"X-API-Key: your_api_key\" http://localhost:3030/api/status\n```\n\n### Endpoints\n\n**Job Management:**\n- `GET /api/jobs` - List all jobs\n- `POST /api/jobs` - Create a new job\n- `GET /api/jobs/:id` - Get job details\n- `POST /api/jobs/:id/trigger` - Trigger job execution\n- `DELETE /api/jobs/:id` - Remove a job\n\n**Daemon Control:**\n- `GET /api/status` - Daemon status\n- `GET /api/metrics` - System metrics\n\n**Webhooks:**\n- `POST /webhooks/github` - GitHub webhook endpoint\n- `POST /webhooks/gitlab` - GitLab webhook endpoint\n- `POST /webhooks/jenkins` - Jenkins webhook endpoint\n\n## Troubleshooting\n\n### Common Issues\n\n**Daemon won't start:**\n```bash\n# Check if already running\nps aux | grep lshd\n\n# Check PID file\ncat /tmp/lsh-job-daemon-$USER.pid\n\n# Remove stale PID file\nrm /tmp/lsh-job-daemon-$USER.pid\n```\n\n**Tests failing:**\n```bash\n# Clear Jest cache\nnpm test -- --clearCache\n\n# Check Node version\nnode --version  # Should be 18+\n```\n\n**Environment validation errors:**\n```bash\n# Check your .env file matches .env.example\ncp .env.example .env\n# Edit .env with your values\n\n# Generate secrets\nopenssl rand -hex 32\n```\n\n**Lint errors:**\n```bash\n# Auto-fix what's possible\nnpm run lint:fix\n\n# Check specific file\nnpx eslint src/your-file.ts\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. **Fork the repository**\n2. **Create a feature branch** - `git checkout -b feature/your-feature`\n3. **Make your changes**\n4. **Add tests** - Ensure tests pass with `npm test`\n5. **Lint your code** - Run `npm run lint:fix`\n6. **Commit your changes** - Follow conventional commit format\n7. **Push to your fork** - `git push origin feature/your-feature`\n8. **Create a Pull Request**\n\n### Code Style\n\n- Use TypeScript with proper types (avoid `any`)\n- Prefix unused variables with `_` (e.g., `_unusedVar`)\n- Add tests for new features\n- Follow existing code structure\n- Update documentation for user-facing changes\n\n### Running in Development\n\n```bash\n# Terminal 1: Watch TypeScript compilation\nnpm run watch\n\n# Terminal 2: Run tests in watch mode\nnpm test -- --watch\n\n# Terminal 3: Run the shell\nnode dist/cli.js\n```\n\n## License\n\nISC\n\n## Project Status\n\n**Active Development** - This project is under active development. Features and APIs may change.\n\n**Current Focus:**\n- Improving test coverage (target: 70%)\n- Reducing lint errors\n- Adding comprehensive documentation\n- Refactoring large modules\n\n## Credits\n\n- [awesome-micro-npm](https://github.com/parro-it/awesome-micro-npm-packages)\n\n## Support\n\nFor issues, questions, or contributions:\n- **Issues**: https://github.com/gwicho38/lsh/issues\n- **Discussions**: https://github.com/gwicho38/lsh/discussions\n","readmeFilename":"README.md","_rev":"1-08f8e60c28623d11aa35831c02a3c7a4"}