@axplusb/kepler 0.0.1 → 1.0.0

package/src/core/safety.mjs

@@ -0,0 +1,200 @@
+/**
+ * Safety Guardrails — prevent destructive tool execution.
+ *
+ * Protects against:
+ * - Deleting/overwriting source code directories
+ * - rm -rf on critical paths
+ * - Writing outside allowed boundaries
+ * - Dangerous shell commands (fork bombs, disk wipes, etc.)
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+// ── Protected Paths ──────────────────────────────────────────
+
+/** Files/dirs that should NEVER be deleted or overwritten wholesale. */
+const PROTECTED_NAMES = new Set([
+  '.git',
+  '.env',
+  '.env.local',
+  '.env.production',
+  'node_modules',
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'Cargo.lock',
+  'go.sum',
+]);
+
+/** Directory names that indicate a source root — never delete the dir itself. */
+const SOURCE_DIRS = new Set([
+  'src',
+  'lib',
+  'app',
+  'pages',
+  'components',
+  'packages',
+  'dist',
+  'build',
+  'test',
+  'tests',
+  '__tests__',
+  'spec',
+]);
+
+/** Shell patterns that are always blocked. */
+const DANGEROUS_SHELL_PATTERNS = [
+  /rm\s+(-\w*[rR]\w*\s+)*(\/|~|\$HOME|\.\.|\.\/\.\.)/,  // rm -rf / or ~ or ..
+  /rm\s+(-\w*[rR]\w*\s+)*\.\s*$/,                         // rm -rf .
+  /rm\s+(-\w*[rR]\w*\s+)*\*\s*$/,                         // rm -rf *
+  /:\(\)\s*\{\s*:\|\s*:\s*&\s*\}\s*;/,                     // fork bomb
+  /mkfs\./,                                                 // format filesystem
+  /dd\s+.*of=\/dev\//,                                      // disk wipe
+  />\s*\/dev\/sd/,                                          // overwrite disk
+  /chmod\s+(-\w+\s+)*777\s+\//,                            // chmod 777 /
+  /curl.*\|\s*(ba)?sh/,                                     // pipe curl to shell
+  /wget.*\|\s*(ba)?sh/,                                     // pipe wget to shell
+  /eval\s*\$\(/,                                            // eval command substitution
+  /\bfind\s+\/\s/,                                          // find / (scans entire filesystem)
+  /\bfind\s+\/\s*$/,                                        // find / at end
+  /\bls\s+(-\w+\s+)*\/\s*$/,                               // ls / (root listing)
+];
+
+/** Commands that need extra scrutiny — require approval even if auto-approved. */
+const HIGH_RISK_COMMANDS = [
+  /\brm\s/,                    // ALL rm commands require explicit approval
+  /\bunlink\s/,                // unlink
+  /\brmdir\s/,                 // rmdir
+  /git\s+push\s+--force/,
+  /git\s+reset\s+--hard/,
+  /git\s+clean\s+-[fd]/,
+  /drop\s+table/i,
+  /drop\s+database/i,
+  /truncate\s+table/i,
+];
+
+// ── Validation Functions ─────────────────────────────────────
+
+/**
+ * Check if a path is protected (should not be deleted/overwritten entirely).
+ * @param {string} filePath - Absolute path
+ * @param {string} cwd - Current working directory
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+export function validatePath(filePath, cwd = process.cwd()) {
+  if (!filePath) return { safe: false, reason: 'Empty path' };
+
+  const resolved = path.resolve(cwd, filePath);
+  const basename = path.basename(resolved);
+  const relative = path.relative(cwd, resolved);
+
+  // Block anything outside CWD parent
+  const cwdParent = path.dirname(cwd);
+  if (!resolved.startsWith(cwdParent)) {
+    return { safe: false, reason: `Path outside workspace: ${filePath}` };
+  }
+
+  // Block protected file names at any level
+  if (PROTECTED_NAMES.has(basename) && !resolved.includes('node_modules/')) {
+    return { safe: false, reason: `Protected path: ${basename}` };
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Check if a delete operation is safe.
+ * Stricter than validatePath — also blocks source directories.
+ * @param {string} filePath - Path to delete
+ * @param {string} cwd - Current working directory
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+export function validateDelete(filePath, cwd = process.cwd()) {
+  const pathCheck = validatePath(filePath, cwd);
+  if (!pathCheck.safe) return pathCheck;
+
+  const resolved = path.resolve(cwd, filePath);
+  const basename = path.basename(resolved);
+
+  // Never delete source root directories
+  if (SOURCE_DIRS.has(basename)) {
+    try {
+      const stat = fs.statSync(resolved);
+      if (stat.isDirectory()) {
+        return { safe: false, reason: `Cannot delete source directory: ${basename}/` };
+      }
+    } catch { /* file doesn't exist, safe to proceed */ }
+  }
+
+  // Never delete CWD itself
+  if (resolved === cwd || resolved === path.dirname(cwd)) {
+    return { safe: false, reason: 'Cannot delete working directory' };
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Check if a shell command is safe to execute.
+ * @param {string} command
+ * @returns {{ safe: boolean, reason?: string, highRisk?: boolean }}
+ */
+export function validateShellCommand(command) {
+  if (!command) return { safe: false, reason: 'Empty command' };
+
+  // Always block dangerous patterns
+  for (const pattern of DANGEROUS_SHELL_PATTERNS) {
+    if (pattern.test(command)) {
+      return { safe: false, reason: `Blocked dangerous command: ${command.slice(0, 60)}` };
+    }
+  }
+
+  // Flag high-risk commands (still allowed, but should force approval)
+  for (const pattern of HIGH_RISK_COMMANDS) {
+    if (pattern.test(command)) {
+      return { safe: true, highRisk: true, reason: `High-risk command: ${command.slice(0, 60)}` };
+    }
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Check if a write operation targets a sensible path.
+ * @param {string} filePath
+ * @param {string} content
+ * @param {string} cwd
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+export function validateWrite(filePath, content, cwd = process.cwd()) {
+  const pathCheck = validatePath(filePath, cwd);
+  if (!pathCheck.safe) return pathCheck;
+
+  const resolved = path.resolve(cwd, filePath);
+
+  // Don't allow overwriting .git internals
+  if (resolved.includes('/.git/')) {
+    return { safe: false, reason: 'Cannot write to .git directory' };
+  }
+
+  // Warn if writing a very large file (> 1MB)
+  if (content && content.length > 1_000_000) {
+    return { safe: true, reason: `Large file write: ${(content.length / 1024).toFixed(0)}KB` };
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Get a human-readable summary of safety rules.
+ */
+export function getSafetyRules() {
+  return {
+    protectedNames: [...PROTECTED_NAMES],
+    sourceDirs: [...SOURCE_DIRS],
+    blockedPatterns: DANGEROUS_SHELL_PATTERNS.length,
+    highRiskPatterns: HIGH_RISK_COMMANDS.length,
+  };
+}

package/src/core/scheduler.mjs

@@ -0,0 +1,173 @@
+/**
+ * Scheduler — cron-based task scheduling.
+ *
+ * Stores scheduled tasks in ~/.claude/scheduled_tasks.json.
+ * Tasks have a cron expression, prompt, and optional environment.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+
+export class Scheduler {
+    /**
+     * @param {string} [tasksFile] - path to scheduled tasks JSON
+     */
+    constructor(tasksFile) {
+        this.tasksFile = tasksFile ||
+            path.join(os.homedir(), '.claude', 'scheduled_tasks.json');
+        this.timers = new Map();
+    }
+
+    /**
+     * Create a new scheduled task.
+     * @param {string} cron - cron expression or interval shorthand (e.g., "5m", "1h")
+     * @param {string} prompt - prompt to execute
+     * @param {object} [options]
+     * @param {string} [options.name] - human-readable name
+     * @param {string} [options.model] - model to use
+     * @param {boolean} [options.enabled] - whether task is enabled (default: true)
+     * @returns {object} created task
+     */
+    async create(cron, prompt, options = {}) {
+        const tasks = this._loadTasks();
+        const task = {
+            id: `task_${crypto.randomBytes(4).toString('hex')}`,
+            name: options.name || `Task ${tasks.length + 1}`,
+            cron,
+            prompt,
+            model: options.model || null,
+            enabled: options.enabled !== false,
+            createdAt: new Date().toISOString(),
+            lastRun: null,
+            runCount: 0,
+            intervalMs: parseCronInterval(cron),
+        };
+
+        tasks.push(task);
+        this._saveTasks(tasks);
+        return task;
+    }
+
+    /**
+     * Delete a scheduled task by ID.
+     * @param {string} taskId
+     * @returns {boolean} true if deleted
+     */
+    async delete(taskId) {
+        const tasks = this._loadTasks();
+        const idx = tasks.findIndex(t => t.id === taskId);
+        if (idx === -1) return false;
+
+        tasks.splice(idx, 1);
+        this._saveTasks(tasks);
+
+        // Clear timer if running
+        if (this.timers.has(taskId)) {
+            clearInterval(this.timers.get(taskId));
+            this.timers.delete(taskId);
+        }
+
+        return true;
+    }
+
+    /**
+     * List all scheduled tasks.
+     * @returns {Array<object>}
+     */
+    async list() {
+        return this._loadTasks();
+    }
+
+    /**
+     * Check and return tasks that are due to run.
+     * @returns {Array<object>} tasks that are due
+     */
+    async runDue() {
+        const tasks = this._loadTasks();
+        const due = [];
+        const now = Date.now();
+
+        for (const task of tasks) {
+            if (!task.enabled) continue;
+            if (!task.intervalMs) continue;
+
+            const lastRun = task.lastRun ? new Date(task.lastRun).getTime() : 0;
+            if (now - lastRun >= task.intervalMs) {
+                task.lastRun = new Date().toISOString();
+                task.runCount = (task.runCount || 0) + 1;
+                due.push(task);
+            }
+        }
+
+        if (due.length > 0) {
+            this._saveTasks(tasks);
+        }
+
+        return due;
+    }
+
+    /**
+     * Enable or disable a task.
+     * @param {string} taskId
+     * @param {boolean} enabled
+     * @returns {boolean}
+     */
+    async setEnabled(taskId, enabled) {
+        const tasks = this._loadTasks();
+        const task = tasks.find(t => t.id === taskId);
+        if (!task) return false;
+
+        task.enabled = enabled;
+        this._saveTasks(tasks);
+        return true;
+    }
+
+    /**
+     * Load tasks from disk.
+     * @returns {Array<object>}
+     */
+    _loadTasks() {
+        try {
+            const raw = fs.readFileSync(this.tasksFile, 'utf-8');
+            return JSON.parse(raw);
+        } catch {
+            return [];
+        }
+    }
+
+    /**
+     * Save tasks to disk.
+     * @param {Array<object>} tasks
+     */
+    _saveTasks(tasks) {
+        try {
+            const dir = path.dirname(this.tasksFile);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(this.tasksFile, JSON.stringify(tasks, null, 2));
+        } catch {
+            // Best effort
+        }
+    }
+}
+
+/**
+ * Parse a cron expression or interval shorthand into milliseconds.
+ * @param {string} cron
+ * @returns {number}
+ */
+export function parseCronInterval(cron) {
+    const match = cron.match(/^(\d+)(s|m|h|d)$/);
+    if (match) {
+        const value = parseInt(match[1], 10);
+        const units = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+        return value * (units[match[2]] || 60000);
+    }
+
+    const num = parseInt(cron, 10);
+    if (!isNaN(num)) return num * 60000;
+
+    // Full cron expression — default to 5 minutes
+    return 300000;
+}

package/src/core/session-manager.mjs

@@ -0,0 +1,317 @@
+/**
+ * Session Manager — persist session state, history, and conversation messages.
+ *
+ * All data lives under ~/.orca/:
+ *   ~/.orca/
+ *     projects/{hash}/
+ *       state.json              — current session metadata
+ *       sessions/               — session metadata archive
+ *     conversations/
+ *       {sessionId}.jsonl       — conversation messages (JSONL)
+ *         Line 1: {"type":"header","instruction":"...","project":"..."}
+ *         Line 2+: {"role":"user","content":"...","timestamp":"..."}
+ *
+ * Zero per-project files. /resume works from anywhere.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+    projectDir as getProjectDir,
+    statePath as getStatePath,
+    sessionsDir as getSessionsDir,
+    conversationsDir as getConversationsDir,
+    conversationPath as getConversationPath,
+} from './paths.mjs';
+
+const MAX_SESSIONS = 100;
+
+export class SessionManager {
+    constructor(projectPath = process.cwd()) {
+        this.projectPath = projectPath;
+        this.projectOrcaDir = getProjectDir(projectPath);
+        this.statePath = getStatePath(projectPath);
+        this.sessionsDir = getSessionsDir(projectPath);
+        this.conversationsDir = getConversationsDir();
+        this.currentState = null;
+    }
+
+    _ensureDirs() {
+        fs.mkdirSync(this.projectOrcaDir, { recursive: true });
+        fs.mkdirSync(this.sessionsDir, { recursive: true });
+        fs.mkdirSync(this.conversationsDir, { recursive: true });
+    }
+
+    /** Start tracking a new session. */
+    start(instruction) {
+        this._ensureDirs();
+        this.currentState = {
+            instruction,
+            started_at: new Date().toISOString(),
+            status: 'running',
+            task_id: null,
+            job_id: null,
+            session_id: null,
+            tool_count: 0,
+            turn_count: 0,
+            events: [],
+        };
+        this._writeState();
+    }
+
+    /** Update state from session_info event. */
+    setSessionInfo(data) {
+        if (!this.currentState) return;
+        this.currentState.task_id = data.task_id || this.currentState.task_id;
+        this.currentState.job_id = data.job_id || this.currentState.job_id;
+        this.currentState.session_id = data.session_id || this.currentState.session_id;
+        this._writeState();
+    }
+
+    /** Record a tool call. */
+    recordToolCall(toolName) {
+        if (!this.currentState) return;
+        this.currentState.tool_count++;
+    }
+
+    /** Mark session as complete. */
+    complete(summary) {
+        if (!this.currentState) return;
+        this.currentState.status = 'completed';
+        this.currentState.completed_at = new Date().toISOString();
+        this.currentState.summary = summary;
+        const duration = (Date.now() - new Date(this.currentState.started_at).getTime()) / 1000;
+        this.currentState.duration_s = Math.round(duration * 10) / 10;
+        this._writeState();
+        this._saveToHistory();
+    }
+
+    /** Mark session as failed. */
+    fail(errorMessage) {
+        if (!this.currentState) return;
+        this.currentState.status = 'failed';
+        this.currentState.error = errorMessage;
+        this.currentState.completed_at = new Date().toISOString();
+        this._writeState();
+        this._saveToHistory();
+    }
+
+    /** Mark session as cancelled. */
+    cancel() {
+        if (!this.currentState) return;
+        this.currentState.status = 'cancelled';
+        this.currentState.completed_at = new Date().toISOString();
+        this._writeState();
+        this._saveToHistory();
+    }
+
+    /** Mark session as paused. */
+    pause() {
+        if (!this.currentState) return;
+        this.currentState.status = 'paused';
+        this._writeState();
+    }
+
+    /** Load saved state for resume. */
+    loadState() {
+        try {
+            if (fs.existsSync(this.statePath)) {
+                return JSON.parse(fs.readFileSync(this.statePath, 'utf-8'));
+            }
+        } catch { /* corrupt file */ }
+        return null;
+    }
+
+    /** List recent sessions. */
+    listSessions(limit = 20) {
+        if (!fs.existsSync(this.sessionsDir)) return [];
+        return fs.readdirSync(this.sessionsDir)
+            .filter(f => f.endsWith('.json'))
+            .sort()
+            .reverse()
+            .slice(0, limit)
+            .map(file => {
+                try {
+                    const data = JSON.parse(fs.readFileSync(path.join(this.sessionsDir, file), 'utf-8'));
+                    return { file, ...data };
+                } catch {
+                    return { file, status: 'unreadable' };
+                }
+            });
+    }
+
+    // ── Conversation Persistence ──
+
+    /**
+     * Get the JSONL file path for a session's conversation.
+     * @param {string} [sessionId] - defaults to current session
+     */
+    _conversationPath(sessionId) {
+        const id = sessionId || this.currentState?.session_id || this.currentState?.task_id || 'unknown';
+        return getConversationPath(id);
+    }
+
+    /**
+     * Append a message to the conversation JSONL file.
+     * On first write, prepends a header line with session metadata.
+     * @param {string} role - 'user' or 'assistant'
+     * @param {string} content - message content
+     * @param {object} [meta] - optional metadata (tokens, cost, tools)
+     */
+    saveMessage(role, content, meta = {}) {
+        if (!this.currentState) return;
+        this._ensureDirs();
+
+        const convPath = this._conversationPath();
+
+        // Write header line on first message (so listResumable can read metadata)
+        if (!fs.existsSync(convPath)) {
+            const header = {
+                type: 'header',
+                instruction: this.currentState.instruction || '',
+                project: this.projectPath,
+                project_name: path.basename(this.projectPath),
+                started_at: this.currentState.started_at || new Date().toISOString(),
+                session_id: this.currentState.session_id || '',
+            };
+            fs.appendFileSync(convPath, JSON.stringify(header) + '\n');
+        }
+
+        const entry = {
+            role,
+            content,
+            timestamp: new Date().toISOString(),
+            turn: this.currentState.turn_count || 0,
+            ...meta,
+        };
+
+        fs.appendFileSync(convPath, JSON.stringify(entry) + '\n');
+    }
+
+    /**
+     * Read the header line from a conversation JSONL file.
+     * @param {string} filePath
+     * @returns {object|null}
+     */
+    _readHeader(filePath) {
+        try {
+            const first = fs.readFileSync(filePath, 'utf-8').split('\n')[0];
+            if (!first) return null;
+            const parsed = JSON.parse(first);
+            return parsed.type === 'header' ? parsed : null;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Load all messages from a session's conversation file (skips header).
+     * @param {string} sessionId - session to load
+     * @returns {{ role: string, content: string }[]}
+     */
+    loadMessages(sessionId) {
+        const filePath = this._conversationPath(sessionId);
+        if (!fs.existsSync(filePath)) return [];
+
+        const lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+        return lines
+            .map(line => {
+                try { return JSON.parse(line); } catch { return null; }
+            })
+            .filter(entry => entry && entry.role) // skip header (type=header, no role)
+            .map(entry => ({ role: entry.role, content: entry.content }));
+    }
+
+    /**
+     * Get the most recent session that has a conversation file.
+     * @returns {{ sessionId: string, instruction: string, startedAt: string }|null}
+     */
+    getLastSession() {
+        if (!fs.existsSync(this.conversationsDir)) return null;
+
+        // Sort by file modification time (most recent first)
+        const files = fs.readdirSync(this.conversationsDir)
+            .filter(f => f.endsWith('.jsonl'))
+            .map(f => ({
+                name: f,
+                mtime: fs.statSync(path.join(this.conversationsDir, f)).mtimeMs,
+            }))
+            .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length === 0) return null;
+
+        const file = files[0].name;
+        const sessionId = file.replace('.jsonl', '');
+        const header = this._readHeader(path.join(this.conversationsDir, file));
+
+        return {
+            sessionId,
+            instruction: header?.instruction || '',
+            startedAt: header?.started_at || '',
+            project: header?.project_name || '',
+        };
+    }
+
+    /**
+     * List sessions that have conversation history (resumable).
+     * Reads metadata from JSONL header line — no cross-referencing needed.
+     * @param {number} [limit=10]
+     * @returns {Array<{ sessionId, instruction, startedAt, project, messageCount }>}
+     */
+    listResumable(limit = 10) {
+        if (!fs.existsSync(this.conversationsDir)) return [];
+
+        // Sort by modification time (most recent first)
+        const files = fs.readdirSync(this.conversationsDir)
+            .filter(f => f.endsWith('.jsonl'))
+            .map(f => ({
+                name: f,
+                mtime: fs.statSync(path.join(this.conversationsDir, f)).mtimeMs,
+            }))
+            .sort((a, b) => b.mtime - a.mtime)
+            .slice(0, limit);
+
+        return files.map(({ name }) => {
+            const sessionId = name.replace('.jsonl', '');
+            const convPath = path.join(this.conversationsDir, name);
+            const lines = fs.readFileSync(convPath, 'utf-8').split('\n').filter(Boolean);
+            const header = this._readHeader(convPath);
+
+            // Message count = total lines minus header
+            const messageCount = header ? lines.length - 1 : lines.length;
+
+            return {
+                sessionId,
+                instruction: header?.instruction || '(no instruction)',
+                startedAt: header?.started_at || '',
+                project: header?.project_name || '',
+                messageCount,
+            };
+        });
+    }
+
+    _writeState() {
+        this._ensureDirs();
+        fs.writeFileSync(this.statePath, JSON.stringify(this.currentState, null, 2));
+    }
+
+    _saveToHistory() {
+        this._ensureDirs();
+        const filename = this.currentState.started_at.replace(/[:.]/g, '-') + '.json';
+        fs.writeFileSync(
+            path.join(this.sessionsDir, filename),
+            JSON.stringify(this.currentState, null, 2)
+        );
+        this._pruneHistory();
+    }
+
+    _pruneHistory() {
+        const files = fs.readdirSync(this.sessionsDir)
+            .filter(f => f.endsWith('.json'))
+            .sort();
+        while (files.length > MAX_SESSIONS) {
+            const oldest = files.shift();
+            try { fs.unlinkSync(path.join(this.sessionsDir, oldest)); } catch {}
+        }
+    }
+}