@crewx/cron 0.1.2 → 0.1.4

package/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: cron
+description: Cron Scheduler skill for CrewX - Schedule and execute crewx/shell commands automatically using cron expressions.
+version: 1.1.0
+---
+
+# Cron Scheduler Skill
+
+> **Phase**: 1 (MVP)
+
+Schedule and execute CrewX commands automatically using cron expressions.
+
+## Overview
+
+The Cron Scheduler skill allows you to schedule `crewx q` (query), `crewx x` (execute), or raw shell commands to run automatically at specified intervals. It runs as a background daemon that checks schedules every minute and executes matching commands.
+
+The daemon is managed by **PM2** (Process Manager 2), providing robust process management with automatic restarts, log management, and cross-platform compatibility.
+
+## Quick Start
+
+```bash
+# Navigate to skill directory
+cd skills/cron
+
+# Install dependencies (includes PM2)
+npm install
+
+# Add a schedule (daily at 9:00 AM)
+node cron.js add "0 9 * * *" "@crewx_claude_dev Daily code review"
+
+# Start the daemon (uses PM2)
+node cron.js start
+
+# Check status
+node cron.js status
+```
+
+## Prerequisites
+
+This skill requires **PM2** (Process Manager 2) for daemon management. PM2 is included in the package dependencies and will be installed automatically when you run `npm install`.
+
+If you need to install PM2 globally:
+```bash
+npm install -g pm2
+```
+
+## Commands
+
+### Schedule Management
+
+| Command | Description |
+|---------|-------------|
+| `add <cron> <command>` | Add a new schedule |
+| `list` | List all schedules |
+| `update <id>` | Update a schedule |
+| `remove <id>` | Remove a schedule |
+| `enable <id>` | Enable a schedule |
+| `disable <id>` | Disable a schedule |
+| `info <id>` | Show schedule details |
+| `run <id>` | Run a schedule immediately (testing) |
+
+### Daemon Management
+
+| Command | Description |
+|---------|-------------|
+| `start` | Start the cron daemon |
+| `stop` | Stop the cron daemon |
+| `status` | Check daemon status |
+
+## Usage Examples
+
+### Basic Scheduling
+
+```bash
+# Daily code review at 9:00 AM
+node cron.js add "0 9 * * *" "@crewx_claude_dev Daily code review" --name "Daily Review"
+
+# Weekly report every Friday at 5:00 PM
+node cron.js add "0 17 * * 5" "@crewx_gemini_dev Generate weekly report" --name "Weekly Report"
+
+# Every hour on weekdays
+node cron.js add "0 * * * 1-5" "@claude Check for new issues"
+
+# Run a shell command
+node cron.js add "*/5 * * * *" "echo hello >> /tmp/cron.log" --mode command --name "Hello Log"
+```
+
+### Options
+
+```bash
+node cron.js add "0 9 * * *" "@agent command" \
+  --name "My Schedule"        # Human-readable name
+  --mode query                # "query", "execute", or "command" (default: execute)
+  --timezone "Asia/Seoul"     # IANA timezone
+  --dir "/path/to/project"    # Working directory
+  --timeout 300000            # Timeout in ms (default: 600000 = 10min)
+  --allow-concurrent          # Allow overlapping executions
+```
+
+### Managing Schedules
+
+```bash
+# List all schedules
+node cron.js list
+
+# Show schedule details
+node cron.js info abc123
+
+# Update a schedule (no need to remove and add again!)
+node cron.js update abc123 --cron="0 10 * * *"     # Change cron expression
+node cron.js update abc123 --command="@agent new"  # Change command
+node cron.js update abc123 --name="New Name"       # Change name
+node cron.js update abc123 --cron="30 8 * * *" --name="Morning Task"  # Multiple changes
+
+# Disable/enable a schedule
+node cron.js disable abc123
+node cron.js enable abc123
+
+# Remove a schedule
+node cron.js remove abc123
+
+# Test run a schedule immediately
+node cron.js run abc123
+```
+
+### Update Options
+
+```bash
+node cron.js update <id> \
+  --cron "0 9 * * *"           # New cron expression
+  --command "@agent task"      # New command
+  --name "New Name"            # New name
+  --mode query                 # "query", "execute", or "command"
+  --timezone "Asia/Seoul"      # IANA timezone
+  --dir "/path/to/project"     # Working directory
+  --timeout 300000             # Timeout in ms
+  --allow-concurrent           # Allow overlapping executions
+  --no-allow-concurrent        # Disallow overlapping executions
+```
+
+### Daemon Control
+
+```bash
+# Start daemon in background (via PM2)
+node cron.js start
+
+# Check if daemon is running
+node cron.js status
+
+# Stop daemon (via PM2)
+node cron.js stop
+```
+
+The daemon is managed by **PM2**, which provides:
+- Automatic restarts on crashes
+- Log management
+- Process monitoring
+- Cross-platform compatibility
+
+### Auto-Start Behavior
+
+User commands like `add`, `list`, `run`, `enable`, `disable`, `update`, and `info` will automatically start the daemon if it is not running:
+
+```
+⚡ cron 데몬이 꺼져 있어서 자동 시작합니다...
+```
+
+You can also use PM2 commands directly:
+```bash
+# View PM2 process list
+pm2 list
+
+# View daemon logs
+pm2 logs cron-daemon
+
+# Monitor daemon
+pm2 monit
+
+# Restart daemon
+pm2 restart cron-daemon
+```
+
+## Cron Expression Format
+
+Standard 5-field cron format: `minute hour day month weekday`
+
+```
+ ┌───────────── minute (0 - 59)
+ │ ┌───────────── hour (0 - 23)
+ │ │ ┌───────────── day of month (1 - 31)
+ │ │ │ ┌───────────── month (1 - 12)
+ │ │ │ │ ┌───────────── day of week (0 - 6, Sunday = 0)
+ │ │ │ │ │
+ * * * * *
+```
+
+### Special Characters
+
+| Character | Description | Example |
+|-----------|-------------|---------|
+| `*` | Any value | `* * * * *` (every minute) |
+| `*/n` | Every n | `*/5 * * * *` (every 5 minutes) |
+| `a-b` | Range | `0 9-17 * * *` (9 AM to 5 PM) |
+| `a,b,c` | List | `0 9,12,18 * * *` (9 AM, 12 PM, 6 PM) |
+
+### Common Patterns
+
+| Expression | Description |
+|------------|-------------|
+| `0 9 * * *` | Every day at 9:00 AM |
+| `0 9 * * 1-5` | Weekdays at 9:00 AM |
+| `0 */2 * * *` | Every 2 hours |
+| `*/30 * * * *` | Every 30 minutes |
+| `0 0 * * 0` | Every Sunday at midnight |
+| `0 0 1 * *` | First day of every month |
+
+## File Structure
+
+```
+skills/cron/
+├── cron.js              # Main CLI + daemon
+├── ecosystem.config.js  # PM2 configuration
+├── package.json         # Dependencies
+├── SKILL.md             # This documentation
+├── .cron-data.json      # Schedule data (auto-created)
+└── .daemon.log          # Daemon log file (auto-created)
+```
+
+## Timezone Support
+
+Specify timezone using IANA format:
+
+```bash
+# Schedule for Asia/Seoul timezone
+node cron.js add "0 9 * * *" "@agent task" --timezone "Asia/Seoul"
+
+# Schedule for US Pacific time
+node cron.js add "0 9 * * *" "@agent task" --timezone "America/Los_Angeles"
+```
+
+If no timezone is specified, local system time is used.
+
+## Concurrent Execution Prevention
+
+By default, a schedule will not start a new execution if the previous one is still running. This prevents overlap when commands take longer than expected.
+
+To allow concurrent executions:
+
+```bash
+node cron.js add "* * * * *" "@agent task" --allow-concurrent
+```
+
+## Cross-Platform Compatibility
+
+This skill supports Windows, macOS, and Linux:
+
+- **Windows**: Uses `windowsHide: true` to prevent console popups, `taskkill` for process termination
+- **Unix/macOS**: Uses standard SIGTERM signals
+
+## Troubleshooting
+
+### Daemon won't start
+
+```bash
+# Check if already running
+node cron.js status
+
+# Or check PM2 directly
+pm2 list
+
+# If stale process exists, stop first
+node cron.js stop
+node cron.js start
+```
+
+### Check daemon logs
+
+```bash
+# View daemon logs via PM2
+pm2 logs cron-daemon
+
+# Or view log file directly
+tail -f skills/cron/.daemon.log
+
+# View PM2 process info
+pm2 show cron-daemon
+```
+
+### Schedule not executing
+
+1. Check if daemon is running: `node cron.js status` or `pm2 list`
+2. Verify schedule is enabled: `node cron.js info <id>`
+3. Check cron expression is correct
+4. Test manually: `node cron.js run <id>`
+5. Check daemon logs: `pm2 logs cron-daemon`
+
+### PM2 not found
+
+If you get "pm2 command not found", ensure PM2 is installed:
+```bash
+npm install  # Installs PM2 locally in node_modules
+# Or install globally
+npm install -g pm2
+```
+
+## Security Note
+
+Do not include sensitive information directly in commands. Use environment variables instead:
+
+```bash
+# Bad - API key exposed in schedule
+node cron.js add "0 9 * * *" "@agent API_KEY=secret task"
+
+# Good - Use environment variables
+export API_KEY=secret
+node cron.js add "0 9 * * *" "@agent task using env"
+```
+
+## API Reference
+
+### Schedule Object
+
+```typescript
+interface Schedule {
+  id: string;                    // 6-character unique ID
+  cron: string;                  // Cron expression (5 fields)
+  command: string;               // CrewX command to execute
+  mode: "query" | "execute" | "command"; // Execution mode
+  enabled: boolean;              // Whether schedule is active
+  name?: string;                 // Human-readable name
+  working_directory?: string;    // Execution directory
+  timezone?: string;             // IANA timezone
+  timeout_ms?: number;           // Timeout (default: 600000)
+  allow_concurrent?: boolean;    // Allow overlapping runs
+  created_at: string;            // ISO 8601 timestamp
+  updated_at: string;            // ISO 8601 timestamp
+  last_run?: string;             // Last execution time
+  next_run?: string;             // Next scheduled time
+  run_count?: number;            // Total execution count
+}
+```
+
+## Future Enhancements (Phase 2+)
+
+- Execution history with detailed logs
+- Integration with CrewX TracingService
+- Web UI for schedule management
+- Notification on failure
+- Retry logic for failed executions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/cron",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Cron Scheduler for CrewX - Schedule and execute crewx commands automatically",
   "type": "commonjs",
   "main": "dist/src/engine.js",
@@ -12,7 +12,7 @@
     }
   },
   "bin": { "cron": "./dist/cli.js" },
-  "files": ["dist"],
+  "files": ["dist", "SKILL.md"],
   "scripts": {
     "build": "tsc",
     "dev": "ts-node cli.ts",
@@ -20,7 +20,9 @@
   },
   "keywords": ["crewx", "cron", "scheduler", "automation"],
   "license": "MIT",
-  "dependencies": {},
+  "dependencies": {
+    "@crewx/shared": "0.0.3"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "ts-node": "^10.9.0",