@axplusb/kepler 0.0.1 → 1.0.1

package/src/core/local-store.mjs

@@ -0,0 +1,325 @@
+/**
+ * Local Store Reader — scans ~/.kepler/ JSONL files for historical stats.
+ *
+ * Provides read helpers for CLI commands (/stats, /history, /tokens, /tools, /sessions).
+ * All data comes from local JSONL files — no cloud dependency.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as readline from 'node:readline';
+
+const KEPLER_DIR = process.env.KEPLER_HOME || path.join(os.homedir(), '.kepler');
+const PROJECTS_DIR = path.join(KEPLER_DIR, 'projects');
+
+function normalizeBlock(block) {
+  if (!block || typeof block !== 'object') {
+    return { type: 'unknown', value: String(block ?? '') };
+  }
+  if (block.type === 'text') {
+    return { type: 'text', text: block.text || '' };
+  }
+  if (block.type === 'tool_use') {
+    return {
+      type: 'tool_use',
+      id: block.id || null,
+      name: block.name || 'unknown',
+      input: block.input || {},
+    };
+  }
+  if (block.type === 'tool_result') {
+    return {
+      type: 'tool_result',
+      tool_use_id: block.tool_use_id || null,
+      content: typeof block.content === 'string' ? block.content : JSON.stringify(block.content || ''),
+      is_error: !!block.is_error,
+    };
+  }
+  return { ...block };
+}
+
+function normalizeMessageContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map(normalizeBlock);
+  if (content == null) return '';
+  try {
+    return JSON.stringify(content);
+  } catch {
+    return String(content);
+  }
+}
+
+/**
+ * List all session JSONL files across all projects.
+ * Returns [{slug, sessionId, filePath, mtime}] sorted by mtime desc.
+ */
+function listSessionFiles() {
+  const results = [];
+  try {
+    const slugs = fs.readdirSync(PROJECTS_DIR);
+    for (const slug of slugs) {
+      const slugDir = path.join(PROJECTS_DIR, slug);
+      if (!fs.statSync(slugDir).isDirectory()) continue;
+      const files = fs.readdirSync(slugDir).filter(f => f.endsWith('.jsonl'));
+      for (const file of files) {
+        const filePath = path.join(slugDir, file);
+        const stat = fs.statSync(filePath);
+        results.push({
+          slug,
+          sessionId: file.replace('.jsonl', ''),
+          filePath,
+          mtime: stat.mtimeMs,
+        });
+      }
+    }
+  } catch { /* projects dir may not exist yet */ }
+  results.sort((a, b) => b.mtime - a.mtime);
+  return results;
+}
+
+function findSessionFile(sessionId) {
+  return listSessionFiles().find((entry) => entry.sessionId === sessionId) || null;
+}
+
+/**
+ * Parse a session JSONL file and extract metadata.
+ * Reads line-by-line (streaming) to handle large files.
+ */
+async function parseSessionMeta(filePath) {
+  const meta = {
+    sessionId: null,
+    project: null,
+    firstPrompt: null,
+    userMessages: 0,
+    assistantMessages: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+    toolCalls: [],   // [{name, count}]
+    models: [],      // [model strings]
+    startTime: null,
+    endTime: null,
+    gitBranch: null,
+  };
+
+  const toolCounts = {};
+  const modelSet = new Set();
+
+  try {
+    const fileStream = fs.createReadStream(filePath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+      let obj;
+      try { obj = JSON.parse(line); } catch { continue; }
+
+      if (obj.sessionId && !meta.sessionId) meta.sessionId = obj.sessionId;
+      if (obj.cwd && !meta.project) meta.project = obj.cwd;
+      if (obj.gitBranch && !meta.gitBranch) meta.gitBranch = obj.gitBranch;
+
+      const ts = obj.timestamp;
+      if (ts) {
+        if (!meta.startTime || ts < meta.startTime) meta.startTime = ts;
+        if (!meta.endTime || ts > meta.endTime) meta.endTime = ts;
+      }
+
+      if (obj.type === 'user') {
+        meta.userMessages++;
+        // Capture first user prompt (string content only)
+        if (!meta.firstPrompt) {
+          const content = obj.message?.content;
+          if (typeof content === 'string' && content.length > 0) {
+            meta.firstPrompt = content.slice(0, 100);
+          }
+        }
+      }
+
+      if (obj.type === 'assistant') {
+        meta.assistantMessages++;
+        const usage = obj.message?.usage;
+        if (usage) {
+          meta.inputTokens += usage.input_tokens || 0;
+          meta.outputTokens += usage.output_tokens || 0;
+          meta.cacheReadTokens += usage.cache_read_input_tokens || 0;
+          meta.cacheCreationTokens += usage.cache_creation_input_tokens || 0;
+        }
+        const model = obj.message?.model;
+        if (model) modelSet.add(model);
+
+        // Count tool_use blocks
+        const content = obj.message?.content;
+        if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.type === 'tool_use' && block.name) {
+              toolCounts[block.name] = (toolCounts[block.name] || 0) + 1;
+            }
+          }
+        }
+      }
+    }
+  } catch { /* file read error — return partial meta */ }
+
+  meta.toolCalls = Object.entries(toolCounts)
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count);
+  meta.models = [...modelSet];
+
+  return meta;
+}
+
+/**
+ * Get recent sessions with metadata.
+ * @param {number} n — max sessions to return
+ */
+export async function getRecentSessions(n = 10) {
+  const files = listSessionFiles().slice(0, n);
+  const sessions = [];
+  for (const f of files) {
+    const meta = await parseSessionMeta(f.filePath);
+    sessions.push({
+      ...meta,
+      slug: f.slug,
+      mtime: f.mtime,
+    });
+  }
+  return sessions;
+}
+
+/**
+ * Return normalized entries for a single session transcript.
+ * @param {string} sessionId
+ */
+export async function getSessionDetail(sessionId) {
+  const file = findSessionFile(sessionId);
+  if (!file) return null;
+
+  const entries = [];
+  const fileStream = fs.createReadStream(file.filePath, { encoding: 'utf-8' });
+  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const message = obj.message || {};
+    entries.push({
+      type: obj.type || null,
+      timestamp: obj.timestamp || null,
+      cwd: obj.cwd || null,
+      role: message.role || null,
+      model: message.model || null,
+      usage: message.usage || null,
+      content: normalizeMessageContent(message.content),
+      uuid: obj.uuid || null,
+      parentUuid: obj.parentUuid || null,
+    });
+  }
+
+  const meta = await parseSessionMeta(file.filePath);
+  return {
+    sessionId: file.sessionId,
+    slug: file.slug,
+    filePath: file.filePath,
+    mtime: file.mtime,
+    meta,
+    entries,
+  };
+}
+
+/**
+ * Aggregate stats across sessions within a date range.
+ * @param {number} days — look back this many days (0 = all time)
+ */
+export async function getSessionStats(days = 30) {
+  const files = listSessionFiles();
+  const cutoff = days > 0 ? Date.now() - (days * 86400000) : 0;
+  const filtered = files.filter(f => f.mtime >= cutoff);
+
+  const stats = {
+    totalSessions: filtered.length,
+    totalUserMessages: 0,
+    totalAssistantMessages: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheReadTokens: 0,
+    totalToolCalls: 0,
+    toolBreakdown: {},
+    modelBreakdown: {},
+  };
+
+  for (const f of filtered) {
+    const meta = await parseSessionMeta(f.filePath);
+    stats.totalUserMessages += meta.userMessages;
+    stats.totalAssistantMessages += meta.assistantMessages;
+    stats.totalInputTokens += meta.inputTokens;
+    stats.totalOutputTokens += meta.outputTokens;
+    stats.totalCacheReadTokens += meta.cacheReadTokens;
+
+    for (const tc of meta.toolCalls) {
+      stats.toolBreakdown[tc.name] = (stats.toolBreakdown[tc.name] || 0) + tc.count;
+      stats.totalToolCalls += tc.count;
+    }
+    for (const model of meta.models) {
+      stats.modelBreakdown[model] = (stats.modelBreakdown[model] || 0) + 1;
+    }
+  }
+
+  return stats;
+}
+
+/**
+ * Get tool breakdown ranked by usage.
+ * @param {number} days — look back period
+ */
+export async function getToolBreakdown(days = 30) {
+  const stats = await getSessionStats(days);
+  return Object.entries(stats.toolBreakdown)
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Get model breakdown with session counts.
+ * @param {number} days — look back period
+ */
+export async function getModelBreakdown(days = 30) {
+  const stats = await getSessionStats(days);
+  return Object.entries(stats.modelBreakdown)
+    .map(([model, sessions]) => ({ model, sessions }))
+    .sort((a, b) => b.sessions - a.sessions);
+}
+
+/**
+ * Read history.jsonl entries.
+ * @param {number} n — max entries to return (most recent first)
+ */
+export function getHistory(n = 50) {
+  const historyPath = path.join(KEPLER_DIR, 'history.jsonl');
+  try {
+    const content = fs.readFileSync(historyPath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try { entries.push(JSON.parse(line)); } catch { /* skip bad lines */ }
+    }
+    return entries.slice(-n).reverse();
+  } catch {
+    return [];
+  }
+}
+
+export function getStorePaths() {
+  return {
+    keplerDir: KEPLER_DIR,
+    projectsDir: PROJECTS_DIR,
+    historyPath: path.join(KEPLER_DIR, 'history.jsonl'),
+  };
+}

package/src/core/mode-selector.mjs

@@ -0,0 +1,51 @@
+/**
+ * Mode Selector
+ *
+ * remote (default): All requests go to Tarang backend.
+ *   Backend handles orchestration, model selection, tool routing.
+ *   User's provider and models configured via web Settings page.
+ *
+ * local: For local LLMs (Ollama, LM Studio, etc.)
+ *   Direct API call, no backend. Only when user explicitly opts in.
+ */
+
+let _probeCache = { available: null, timestamp: 0 };
+const PROBE_CACHE_TTL = 60_000; // 60s
+
+export async function selectMode(instruction, options, config) {
+    // Explicit --local flag: user wants local LLM
+    if (options.local) return 'local';
+
+    // Everything else goes to the backend
+    return 'remote';
+}
+
+export async function probeBackend(url) {
+    if (!url) return false;
+    const now = Date.now();
+    if (_probeCache.available !== null && (now - _probeCache.timestamp) < PROBE_CACHE_TTL) {
+        return _probeCache.available;
+    }
+    try {
+        const resp = await fetch(`${url}/health`, { signal: AbortSignal.timeout(2000) });
+        _probeCache = { available: resp.ok, timestamp: now };
+        return resp.ok;
+    } catch {
+        _probeCache = { available: false, timestamp: now };
+        return false;
+    }
+}
+
+export function classifyTask(instruction) {
+    if (!instruction) return 'simple';
+    const isSimple = SIMPLE_PATTERNS.some(p => p.test(instruction));
+    const isComplex = COMPLEX_PATTERNS.some(p => p.test(instruction));
+    if (isComplex && !isSimple) return 'complex';
+    if (isSimple && !isComplex) return 'simple';
+    return 'medium'; // ambiguous → default to remote when available
+}
+
+/** Reset probe cache (for testing). */
+export function resetProbeCache() {
+    _probeCache = { available: null, timestamp: 0 };
+}

package/src/core/output-filter.mjs

@@ -0,0 +1,177 @@
+/**
+ * Output Filter — Smart shell output filtering + auto-lint.
+ * Ported from tarang-cli (Python) ws/executor.py with enhanced patterns.
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { execSync } from 'node:child_process';
+
+// ── Command Classification ──────────────────────────────────
+
+const COMMAND_PROFILES = {
+    install: {
+        patterns: [/pip install/i, /npm install/i, /yarn add/i, /pnpm add/i, /cargo add/i, /go get/i, /brew install/i, /apt install/i],
+        successLimit: 500,
+        failureLimit: 2000,
+        noisePatterns: [
+            /^Collecting \S+/,
+            /^Downloading \S+/,
+            /^Installing collected/,
+            /^Successfully installed/,
+            /^━+/,                          // Progress bars
+            /^\s*\d+%\s*\|/,              // Percentage bars
+            /^Using cached/,
+            /^Requirement already satisfied/,
+            /^added \d+ packages?/,
+            /^up to date/,
+            /^npm WARN/,
+            /^npm notice/,
+            /^\s*$/,                        // Empty lines
+        ],
+        keepPatterns: [/error/i, /failed/i, /WARN(?:ING)?/i, /not found/i, /permission denied/i],
+    },
+    test: {
+        patterns: [/pytest/i, /npm test/i, /cargo test/i, /go test/i, /jest/i, /vitest/i, /mocha/i],
+        successLimit: 2000,
+        failureLimit: 8000,
+        noisePatterns: [
+            /^\.+$/,                        // Lines of dots (pytest progress)
+            /^PASSED/,
+            /^\s*✓/,                        // Checkmarks
+            /^\s*$/,
+        ],
+        keepPatterns: [/FAILED/i, /FAIL/i, /Error/i, /AssertionError/i, /Expected/i, /Actual/i, /✗/, /✘/],
+    },
+    build: {
+        patterns: [/npm run build/i, /cargo build/i, /go build/i, /tsc/i, /webpack/i, /vite build/i, /make\b/i, /next build/i],
+        successLimit: 1000,
+        failureLimit: 6000,
+        noisePatterns: [
+            /^Compiling \S+/,
+            /^Finished \S+ target/,
+            /^\s*$/,
+        ],
+        keepPatterns: [/error/i, /warning/i],
+    },
+    run: {
+        patterns: [/python\s/i, /node\s/i, /go run/i, /cargo run/i, /npm start/i, /npm run dev/i],
+        successLimit: 4000,
+        failureLimit: 8000,
+        noisePatterns: [],
+        keepPatterns: [],
+    },
+    default: {
+        patterns: [],
+        successLimit: 3000,
+        failureLimit: 6000,
+        noisePatterns: [/^\s*$/],
+        keepPatterns: [],
+    },
+};
+
+/** Detect shell command type for smart filtering. */
+export function detectCommandType(command) {
+    if (!command) return 'default';
+    for (const [type, profile] of Object.entries(COMMAND_PROFILES)) {
+        if (type === 'default') continue;
+        if (profile.patterns.some(p => p.test(command))) return type;
+    }
+    return 'default';
+}
+
+// ── Output Filtering ────────────────────────────────────────
+
+/**
+ * Filter shell output based on command type.
+ * Reduces noise from install/build while preserving errors and useful output.
+ *
+ * @param {string} output - Raw shell output
+ * @param {string} command - The command that was run
+ * @param {boolean} success - Whether the command succeeded
+ * @returns {{ output: string, commandType: string, truncated: boolean, originalLines: number, filteredLines: number }}
+ */
+export function filterOutput(output, command, success = true) {
+    if (!output) return { output: '', commandType: 'default', truncated: false, originalLines: 0, filteredLines: 0 };
+
+    const type = detectCommandType(command);
+    const profile = COMMAND_PROFILES[type];
+    const limit = success ? profile.successLimit : profile.failureLimit;
+    const lines = output.split('\n');
+    const originalLines = lines.length;
+
+    let filteredLines = [];
+
+    for (const line of lines) {
+        // Always keep lines matching keep patterns (errors, failures)
+        const shouldKeep = profile.keepPatterns.length > 0 &&
+            profile.keepPatterns.some(p => p.test(line));
+
+        // Filter out noise patterns
+        const isNoise = !shouldKeep && profile.noisePatterns.length > 0 &&
+            profile.noisePatterns.some(p => p.test(line));
+
+        if (shouldKeep || !isNoise) {
+            filteredLines.push(line);
+        }
+    }
+
+    let filteredOutput = filteredLines.join('\n');
+    let truncated = false;
+
+    // Truncate to limit
+    if (filteredOutput.length > limit) {
+        filteredOutput = filteredOutput.slice(0, limit);
+        const lastNewline = filteredOutput.lastIndexOf('\n');
+        if (lastNewline > 0) {
+            filteredOutput = filteredOutput.slice(0, lastNewline);
+        }
+        filteredOutput += '\n... (truncated)';
+        truncated = true;
+    }
+
+    return {
+        output: filteredOutput,
+        commandType: type,
+        truncated,
+        originalLines,
+        filteredLines: filteredLines.length,
+    };
+}
+
+// ── Auto-Lint ───────────────────────────────────────────────
+
+/** Auto-lint a file after write/edit. Returns lint output or null. */
+export function autoLint(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) return null;
+    const ext = path.extname(filePath);
+    let cmd;
+
+    try {
+        switch (ext) {
+            case '.py':
+                cmd = `python3 -m py_compile "${filePath}" 2>&1`;
+                break;
+            case '.js': case '.mjs': case '.cjs':
+                cmd = `node --check "${filePath}" 2>&1`;
+                break;
+            case '.ts': case '.tsx':
+                if (fs.existsSync('node_modules/.bin/tsc'))
+                    cmd = `npx tsc --noEmit --pretty "${filePath}" 2>&1`;
+                break;
+            case '.go':
+                cmd = `go vet "${filePath}" 2>&1`;
+                break;
+            case '.rs':
+                cmd = `rustfmt --check "${filePath}" 2>&1`;
+                break;
+        }
+
+        if (!cmd) return null;
+        const output = execSync(cmd, { stdio: 'pipe', timeout: 15_000, encoding: 'utf-8' });
+        return output.trim() || null;
+    } catch (err) {
+        const output = (err.stderr || err.stdout || '').toString().trim();
+        return output || null;
+    }
+}

package/src/core/paths.mjs

@@ -0,0 +1,101 @@
+/**
+ * Kepler Paths — centralized path resolution for all Kepler data.
+ *
+ * Everything lives under ~/.kepler/:
+ *   ~/.kepler/
+ *     config.json              — auth credentials + settings
+ *     history.jsonl            — prompt history
+ *     hooks.json               — global hooks
+ *     conversations/           — conversation JSONL files
+ *     projects/
+ *       {hash}/                — per-project data (hash of project path)
+ *         index/               — BM25 search index
+ *         checkpoints/         — file undo checkpoints
+ *         state.json           — current session state
+ *         sessions/            — session metadata archive
+ *         hooks.json           — project-specific hooks
+ *     projects.json            — slug → project path mapping
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+
+const KEPLER_HOME = process.env.KEPLER_HOME || process.env.ORCA_HOME || path.join(os.homedir(), '.kepler');
+
+/**
+ * Hash a project path to a short directory name.
+ * Uses first 16 chars of SHA-256 (same as Claude Code).
+ */
+export function projectHash(projectDir) {
+    // Resolve symlinks (macOS: /tmp → /private/tmp) so the hash is stable
+    let resolved = projectDir;
+    try {
+        resolved = fs.realpathSync(projectDir);
+    } catch {
+        // realpathSync fails if path doesn't exist yet — use as-is
+    }
+    return crypto.createHash('sha256')
+        .update(resolved)
+        .digest('hex')
+        .slice(0, 16);
+}
+
+/** Root ~/.kepler/ directory. */
+export function keplerHome() {
+    return KEPLER_HOME;
+}
+
+/** @deprecated Use keplerHome() */
+export const orcaHome = keplerHome;
+
+/** ~/.kepler/projects/{hash}/ for a given project path. */
+export function projectDir(projectPath) {
+    return path.join(KEPLER_HOME, 'projects', projectHash(projectPath));
+}
+
+/** ~/.kepler/projects/{hash}/index/ — BM25 search index. */
+export function indexDir(projectPath) {
+    return path.join(projectDir(projectPath), 'index');
+}
+
+/** ~/.kepler/projects/{hash}/checkpoints/ — file undo. */
+export function checkpointsDir(projectPath) {
+    return path.join(projectDir(projectPath), 'checkpoints');
+}
+
+/** ~/.kepler/projects/{hash}/state.json — current session. */
+export function statePath(projectPath) {
+    return path.join(projectDir(projectPath), 'state.json');
+}
+
+/** ~/.kepler/projects/{hash}/sessions/ — session archive. */
+export function sessionsDir(projectPath) {
+    return path.join(projectDir(projectPath), 'sessions');
+}
+
+/** ~/.kepler/projects/{hash}/hooks.json — project hooks. */
+export function projectHooksPath(projectPath) {
+    return path.join(projectDir(projectPath), 'hooks.json');
+}
+
+/** ~/.kepler/conversations/ — central conversation storage. */
+export function conversationsDir() {
+    return path.join(KEPLER_HOME, 'conversations');
+}
+
+/** ~/.kepler/conversations/{sessionId}.jsonl */
+export function conversationPath(sessionId) {
+    return path.join(conversationsDir(), `${sessionId}.jsonl`);
+}
+
+/** ~/.kepler/hooks.json — global hooks. */
+export function globalHooksPath() {
+    return path.join(KEPLER_HOME, 'hooks.json');
+}
+
+/** ~/.kepler/history.jsonl — prompt history. */
+export function historyPath() {
+    return path.join(KEPLER_HOME, 'history.jsonl');
+}