craftclose 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaunchDay Studio Inc
+
+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,176 @@
+# CraftClose
+
+[![npm version](https://img.shields.io/npm/v/craftclose)](https://www.npmjs.com/package/craftclose)
+[![CI](https://github.com/LaunchDay-Studio-Inc/craftclose/actions/workflows/ci.yml/badge.svg)](https://github.com/LaunchDay-Studio-Inc/craftclose/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**AI-powered Minecraft server monitoring** — crash detection, auto-restart, and smart alerts.
+
+Open-source [OpenClaw](https://openclaw.dev) skill for monitoring Minecraft servers via SSH, RCON, or Pterodactyl panel. Includes AI-powered crash analysis via Google Gemini (BYOK).
+
+## Features
+
+- **Multi-server monitoring** — SSH, RCON, Pterodactyl, or any combination
+- **Crash detection** — 22 built-in patterns for OOM, plugin errors, watchdog timeouts, etc.
+- **Auto-restart** — Automatically restart crashed servers with circuit breaker protection
+- **Smart alerts** — Telegram and Discord notifications with severity levels
+- **AI crash analysis** — Feed crash logs to Google Gemini for root cause + fix suggestions (BYOK)
+- **AI config optimization** — Get specific recommendations for `server.properties`, `spigot.yml`, etc.
+- **AI plugin conflict detection** — Scan your plugins folder for known incompatibilities
+- **TPS & player history** — SQLite-backed tracking with trend analysis
+- **Pterodactyl integration** — Full panel support: console, logs, file manager, resource stats
+- **Security sandbox** — Path jail, RCON command filter, input sanitization, audit logging
+
+## Quick Start
+
+```bash
+# Install
+npm install -g craftclose
+
+# Configure
+cp craftclose.example.yml craftclose.yml
+# Edit craftclose.yml with your server details
+
+# Test connectivity
+craftclose test
+
+# Start monitoring
+craftclose monitor
+```
+
+## Configuration
+
+Copy `craftclose.example.yml` and configure your servers:
+
+### SSH + RCON (self-hosted)
+
+```yaml
+servers:
+  - name: "survival"
+    host: "192.168.1.100"
+    type: "paper"
+    ssh:
+      user: "ubuntu"
+      key: "~/.ssh/id_ed25519"
+    rcon:
+      port: 25575
+      password: "your-rcon-password"
+    restart_command: "systemctl restart minecraft"
+```
+
+### Pterodactyl (panel-hosted)
+
+```yaml
+servers:
+  - name: "creative"
+    host: "play.example.com"
+    type: "paper"
+    pterodactyl:
+      panel_url: "https://panel.yourhost.com"
+      api_key: "ptlc_xxxxxxxxxxxx"
+      server_id: "a1b2c3d4"
+```
+
+### Alerts
+
+```yaml
+alerts:
+  telegram:
+    bot_token: "123456:ABC-DEF..."
+    chat_id: "-1001234567890"
+  discord:
+    webhook_url: "https://discord.com/api/webhooks/..."
+```
+
+### AI (BYOK — Bring Your Own Key)
+
+```yaml
+ai:
+  gemini_key: "your-gemini-api-key"
+  model: "gemini-2.5-flash"
+  max_calls_per_hour: 10
+```
+
+Get a free API key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey).
+
+## Commands
+
+```
+craftclose status                     Check all servers
+craftclose monitor                    Start continuous monitoring
+craftclose test                       Test connectivity
+craftclose history <server>           Show TPS/player history
+craftclose analyze <logfile>          AI crash analysis
+craftclose optimize <configdir>       AI config optimization
+craftclose conflicts <plugindir>      AI plugin conflict detection
+craftclose ptero-test                 Test Pterodactyl connections
+craftclose ptero-console <srv> <cmd>  Send console command
+craftclose ptero-logs <srv>           Read server logs
+craftclose ptero-files <srv> [dir]    List server files
+```
+
+## Security Model
+
+CraftClose includes a security sandbox that protects your servers:
+
+| Layer | Protection |
+|-------|------------|
+| **Path Jail** | File access restricted to server directory — no `../` traversal |
+| **RCON Filter** | Dangerous commands (`stop`, `op`, `ban`, `reload`) blocked by default |
+| **Input Sanitizer** | Shell/RCON injection characters stripped from all inputs |
+| **Audit Log** | All security-relevant actions logged to `craftclose-audit.jsonl` |
+| **Action Allowlist** | Only approved config files can be read/written |
+
+Configure in `craftclose.yml`:
+
+```yaml
+security:
+  confirm_destructive: true
+  max_log_lines: 500
+  blocked_rcon_commands:
+    - timings
+    - spark
+```
+
+## Architecture
+
+```
+src/
+├── craft-close-skill.ts    # Main orchestrator
+├── ai-analyzer.ts          # BYOK Gemini AI (direct API)
+├── config.ts               # YAML config loader
+├── history.ts              # SQLite TPS/player tracking
+├── types.ts                # TypeScript interfaces
+├── connectors/
+│   ├── ssh.ts              # SSH health checks + log reading
+│   ├── rcon.ts             # RCON TPS/players/commands
+│   ├── pterodactyl.ts      # Panel API integration
+│   └── parsers.ts          # TPS/player response parsers
+├── alerts/
+│   ├── telegram.ts         # Telegram Bot API
+│   └── discord.ts          # Discord webhooks
+├── patterns/
+│   └── index.ts            # 22 crash pattern matchers
+└── security/
+    ├── path-jail.ts        # File access control
+    ├── rcon-filter.ts      # RCON command filter
+    ├── input-sanitizer.ts  # Input cleaning
+    ├── audit-log.ts        # Action audit trail
+    └── action-allowlist.ts # Config file allowlist
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/SKILL.md

@@ -0,0 +1,139 @@
+# CraftClose
+
+AI-powered Minecraft server monitoring — crash detection, auto-restart, and smart alerts.
+
+## Setup
+
+1. Copy `craftclose.example.yml` to `craftclose.yml`
+2. Configure your server(s):
+   - **SSH + RCON** — for self-hosted/VPS servers
+   - **Pterodactyl** — for panel-hosted servers (no SSH needed)
+   - **Hybrid** — Pterodactyl for resources + RCON for TPS/players
+3. (Optional) Add alert channels: Telegram bot token or Discord webhook
+4. (Optional) Add Google Gemini API key for AI crash analysis
+5. Run `craftclose test` to verify connectivity
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `craftclose status` | Check all servers once and print health |
+| `craftclose monitor` | Start continuous monitoring |
+| `craftclose test` | Test connectivity to all servers |
+| `craftclose history <server>` | Show TPS/player history for a server |
+| `craftclose analyze <logfile>` | AI crash log analysis (requires Gemini key) |
+| `craftclose optimize <configdir>` | AI config optimization |
+| `craftclose conflicts <plugindir>` | AI plugin conflict detection from jar filenames |
+| `craftclose ptero-test` | Test Pterodactyl API connections |
+| `craftclose ptero-console <server> <cmd>` | Send console command via Pterodactyl panel |
+| `craftclose ptero-logs <server>` | Read server logs via Pterodactyl panel |
+| `craftclose ptero-files <server> [dir]` | List server files via Pterodactyl panel |
+| `craftclose --help` | Show help and all available commands |
+| `craftclose --version` | Print version number |
+
+## Configuration
+
+### Server Config (required)
+
+Each server needs at least one connector (SSH, RCON, or Pterodactyl):
+
+```yaml
+servers:
+  - name: "my-server"
+    host: "192.168.1.100"
+    port: 25565
+    type: "paper"
+    ssh:
+      user: "ubuntu"
+      key: "~/.ssh/id_ed25519"
+    rcon:
+      port: 25575
+      password: "rcon-pass"
+    pterodactyl:
+      panel_url: "https://panel.yourhost.com"
+      api_key: "ptlc_xxxx"
+      server_id: "a1b2c3d4"
+    restart_command: "systemctl restart minecraft"
+    log_path: "/opt/minecraft/logs/latest.log"
+```
+
+### Alert Config (optional)
+
+```yaml
+alerts:
+  telegram:
+    bot_token: "123456:ABC-DEF..."
+    chat_id: "-1001234567890"
+  discord:
+    webhook_url: "https://discord.com/api/webhooks/..."
+```
+
+### AI Config (optional — BYOK)
+
+```yaml
+ai:
+  gemini_key: "your-gemini-api-key"      # From https://aistudio.google.com/apikey
+  model: "gemini-2.5-flash"             # gemini-2.5-flash, gemini-2.5-pro, gemini-3.1-flash, gemini-3.1-pro
+  max_calls_per_hour: 10                # Rate limit (default: 10)
+```
+
+### Monitoring Config
+
+```yaml
+monitoring:
+  interval: 60
+  auto_restart: true
+  max_restarts: 3
+  track_tps: true
+  track_players: true
+```
+
+### Security Config
+
+```yaml
+security:
+  confirm_destructive: true         # Require confirmation for restart/stop (default: true)
+  max_log_lines: 500                # Max log lines per request (default: 500)
+  max_backup_size_gb: 10            # Max backup size in GB (default: 10)
+  allowed_config_files:             # Override default config file allowlist
+    - server.properties
+    - bukkit.yml
+    - spigot.yml
+  blocked_rcon_commands:            # Extra blocked RCON commands
+    - timings
+```
+
+## Security Model
+
+CraftClose includes a security sandbox to prevent accidental damage:
+
+- **Path Jail** — File access restricted to server directory. No `../` traversal.
+- **RCON Filter** — Dangerous commands (`stop`, `op`, `ban`, `reload`, etc.) are blocked by default.
+- **Input Sanitizer** — All user-provided strings are cleaned before use in shell/RCON commands.
+- **Audit Log** — All security-relevant actions are logged to `craftclose-audit.jsonl`.
+- **Action Allowlist** — Only approved config files can be read/written. Destructive actions require confirmation.
+
+## AI Features
+
+### Crash Analysis
+
+```bash
+craftclose analyze /path/to/crash-2024-01-15-1.txt
+```
+
+### Config Optimization
+
+```bash
+craftclose optimize /opt/minecraft/
+```
+
+### Plugin Conflict Detection
+
+```bash
+craftclose conflicts /opt/minecraft/plugins/
+```
+
+## Requirements
+
+- Node.js 20+
+- At least one connector per server (SSH, RCON, or Pterodactyl)

package/craftclose.example.yml

@@ -0,0 +1,84 @@
+# CraftClose Configuration
+# Copy this to craftclose.yml and fill in your server details.
+
+servers:
+  # Option 1: SSH + RCON (traditional setup)
+  - name: "my-server"
+    host: "192.168.1.100"
+    port: 25565
+    type: "paper"
+    
+    ssh:
+      user: "ubuntu"
+      # Use key-based auth (recommended):
+      key: "~/.ssh/id_ed25519"
+      # Or password auth:
+      # password: "your-password"
+    
+    rcon:
+      port: 25575
+      password: "your-rcon-password"
+    
+    # Command to restart the server (via SSH)
+    restart_command: "docker restart my-minecraft-server"
+    
+    # Path to server log (auto-detected if not specified)
+    # log_path: "/home/minecraft/server/logs/latest.log"
+
+  # Option 2: Pterodactyl Panel (easiest setup — no SSH needed!)
+  - name: "hosted-server"
+    host: "play.example.com"        # Server IP (for ping checks)
+    type: "paper"
+    pterodactyl:
+      panel_url: "https://panel.yourhost.com"
+      api_key: "ptlc_xxxxxxxxxxxx"   # Client API key from Panel → Account → API Credentials
+      server_id: "a1b2c3d4"          # From your server URL: panel.yourhost.com/server/a1b2c3d4
+
+  # Option 3: Pterodactyl + RCON (panel for resources, RCON for TPS/players)
+  - name: "hybrid-server"
+    host: "play.example.com"
+    type: "paper"
+    pterodactyl:
+      panel_url: "https://panel.yourhost.com"
+      api_key: "ptlc_xxxxxxxxxxxx"
+      server_id: "a1b2c3d4"
+    rcon:
+      port: 25575
+      password: "rcon-pass"
+
+# Alert channels (optional)
+alerts:
+  telegram:
+    bot_token: "123456:ABC-DEF..."
+    chat_id: "-1001234567890"
+  discord:
+    webhook_url: "https://discord.com/api/webhooks/..."
+
+# Monitoring settings
+monitoring:
+  interval: 60         # Check every 60 seconds
+  auto_restart: true   # Restart crashed servers automatically
+  max_restarts: 3      # Max restarts per 10-minute window (circuit breaker)
+  track_tps: true      # Store TPS history
+  track_players: true  # Store player count history
+
+# AI Analysis (optional — requires Google Gemini API key)
+# Get a key at https://aistudio.google.com/apikey
+ai:
+  gemini_key: "your-gemini-api-key-here"
+  # model: "gemini-2.5-flash"     # Options: gemini-2.5-flash (fast/cheap), gemini-2.5-pro (deep), gemini-3.1-flash (latest fast), gemini-3.1-pro (latest deep)
+  # max_calls_per_hour: 10        # Rate limit (default: 10)
+
+# Security settings (all optional — safe defaults apply)
+security:
+  confirm_destructive: true        # Require confirmation for restart/stop
+  max_log_lines: 500               # Max log lines to read per request
+  max_backup_size_gb: 10           # Max backup size in GB
+  # allowed_config_files:          # Override default config file allowlist
+  #   - server.properties
+  #   - bukkit.yml
+  #   - spigot.yml
+  #   - paper-global.yml
+  # blocked_rcon_commands:          # Add extra blocked RCON commands
+  #   - timings
+  #   - spark

package/dist/ai-analyzer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * CraftClose — BYOK AI Crash Analyzer
+ *
+ * Uses the user's own Gemini API key for crash log analysis.
+ * No backend, no paid tier — direct Gemini API calls.
+ * AI analysis is always best-effort: returns null on failure, never blocks monitoring.
+ */
+import type { AiAnalysis } from "./types.js";
+export interface AIAnalyzerOptions {
+    geminiKey: string;
+    /** Use flash (fast/cheap) or pro (deep) model */
+    model?: "gemini-2.5-flash" | "gemini-2.5-pro" | "gemini-3.1-flash" | "gemini-3.1-pro";
+    /** Max Gemini calls per hour (default: 10) */
+    maxCallsPerHour?: number;
+    /** Cache TTL in ms (default: 24 hours) */
+    cacheTtlMs?: number;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+export interface CrashAnalysisRequest {
+    log: string;
+    context: {
+        version?: string;
+        plugins?: string[];
+        ram_mb?: number;
+        player_count?: number;
+        server_type?: string;
+    };
+}
+export interface ConfigOptimizeRequest {
+    configs: Record<string, string>;
+    ram_mb: number;
+    player_target: number;
+    server_type: string;
+}
+export interface ConfigRecommendation {
+    file: string;
+    setting: string;
+    current_value: string;
+    recommended_value: string;
+    reason: string;
+    risk: "safe" | "low" | "medium";
+}
+export interface PluginConflictRequest {
+    plugins: Array<{
+        name: string;
+        version: string;
+    }>;
+    crash_log?: string;
+}
+export interface PluginConflict {
+    plugins: string[];
+    type: "known" | "suspected";
+    description: string;
+    resolution: string;
+}
+export declare class AIAnalyzer {
+    private readonly apiKey;
+    private readonly model;
+    private readonly maxCallsPerHour;
+    private readonly cacheTtlMs;
+    private readonly timeout;
+    private readonly crashCache;
+    private readonly callTimestamps;
+    constructor(options: AIAnalyzerOptions);
+    /**
+     * Analyze a crash log. Returns null if rate-limited, cached, or on error.
+     */
+    analyzeCrash(request: CrashAnalysisRequest): Promise<AiAnalysis | null>;
+    /**
+     * Optimize server configs. Returns null on failure.
+     */
+    optimizeConfig(request: ConfigOptimizeRequest): Promise<ConfigRecommendation[] | null>;
+    /**
+     * Detect plugin conflicts. Returns null on failure.
+     */
+    detectConflicts(request: PluginConflictRequest): Promise<PluginConflict[] | null>;
+    /** Hash the first 2000 chars of a log for cache lookup. */
+    private hashLog;
+    /** Check cache for a previous analysis result. */
+    private getCached;
+    /** Sliding-window rate limiter. Returns false if limit exceeded. */
+    private checkRateLimit;
+    /** Call Gemini generateContent API. */
+    private callGemini;
+    /** Parse JSON from model response, with retry on parse failure. */
+    private parseJsonResponse;
+    private validateJson;
+    /** Build crash analysis prompt with few-shot examples and guardrails. */
+    private buildCrashAnalysisPrompt;
+    /** Build config optimization prompt. */
+    private buildConfigOptimizePrompt;
+    /** Build plugin conflict detection prompt. */
+    private buildConflictDetectionPrompt;
+}
+//# sourceMappingURL=ai-analyzer.d.ts.map

package/dist/ai-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-analyzer.d.ts","sourceRoot":"","sources":["../src/ai-analyzer.ts"],"names":[],"mappings":"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"}