@axplusb/kepler 0.0.1 → 1.0.1

package/src/telemetry/index.mjs

@@ -0,0 +1,96 @@
+/**
+ * Telemetry Stub — basic telemetry interface (no actual reporting).
+ *
+ * Logs events to debug output when CLAUDE_CODE_DEBUG is set.
+ * Designed to be a drop-in interface for the full telemetry system.
+ */
+
+const events = [];
+let enabled = true;
+
+/**
+ * Track a telemetry event.
+ * @param {string} event - event name
+ * @param {object} [properties] - event properties
+ */
+export function track(event, properties = {}) {
+    if (!enabled) return;
+    if (process.env.CLAUDE_CODE_DISABLE_TELEMETRY === '1') return;
+
+    const entry = {
+        event,
+        properties,
+        timestamp: Date.now(),
+    };
+
+    events.push(entry);
+
+    // Keep max 1000 events in memory
+    if (events.length > 1000) {
+        events.splice(0, events.length - 1000);
+    }
+
+    if (process.env.CLAUDE_CODE_DEBUG) {
+        console.error(`[telemetry] ${event}`, JSON.stringify(properties).slice(0, 200));
+    }
+}
+
+/**
+ * Track a timing event.
+ * @param {string} event - event name
+ * @param {number} durationMs - duration in milliseconds
+ * @param {object} [properties] - additional properties
+ */
+export function trackTiming(event, durationMs, properties = {}) {
+    track(event, { ...properties, durationMs });
+}
+
+/**
+ * Track an error.
+ * @param {string} event - error context
+ * @param {Error} error - the error
+ */
+export function trackError(event, error) {
+    track(`error.${event}`, {
+        message: error.message,
+        stack: error.stack?.split('\n').slice(0, 3).join('\n'),
+    });
+}
+
+/**
+ * Get collected events (for debugging).
+ * @returns {Array}
+ */
+export function getEvents() {
+    return [...events];
+}
+
+/**
+ * Clear collected events.
+ */
+export function clear() {
+    events.length = 0;
+}
+
+/**
+ * Enable or disable telemetry.
+ * @param {boolean} value
+ */
+export function setEnabled(value) {
+    enabled = value;
+}
+
+/**
+ * Get telemetry stats.
+ */
+export function getStats() {
+    const counts = {};
+    for (const e of events) {
+        counts[e.event] = (counts[e.event] || 0) + 1;
+    }
+    return {
+        totalEvents: events.length,
+        enabled,
+        eventCounts: counts,
+    };
+}

package/src/terminal/agents.mjs

@@ -0,0 +1,177 @@
+/**
+ * Built-in Agents — specialized agent modes invoked via slash commands.
+ *
+ * Each agent wraps the same backend SSE flow but with a specialized
+ * system prompt prefix that focuses the AI on a specific task type.
+ *
+ * Agents:
+ * - explore: Code explorer — traces execution paths, maps architecture
+ * - review:  Code reviewer — finds bugs, security issues, quality problems
+ * - architect: Feature architect — designs implementations, file plans
+ */
+
+import { c, spinner, inPlace, hr } from './ansi.mjs';
+import { TarangStreamClient } from '../core/stream-client.mjs';
+import { resolveBackendUrl } from '../core/backend-url.mjs';
+
+// ── Agent Definitions ────────────────────────────────────────
+
+export const BUILTIN_AGENTS = [
+  {
+    command: 'explore',
+    name: 'Code Explorer',
+    description: 'Deeply analyze codebase features and architecture',
+    detail: 'Traces execution paths, maps layers, documents dependencies',
+    icon: '🔭',
+    systemPrompt: `You are a Code Explorer agent. Your job is to deeply analyze the codebase to answer the user's question.
+
+Your approach:
+1. Start by understanding what the user wants to know
+2. Search for relevant files using search_code and list_files
+3. Read the key files to trace the execution path
+4. Map the architecture layers (entry points → business logic → data layer)
+5. Document dependencies between components
+6. Provide a clear, structured answer with file references
+
+Rules:
+- ONLY use read-only tools: read_file, search_code, list_files, search_files, get_file_info
+- NEVER modify any files
+- NEVER run shell commands that modify state
+- Include file paths and line numbers in your references
+- Structure your response with clear sections: Overview, Key Files, Execution Flow, Dependencies
+- Be thorough but concise — focus on what matters for the user's question`,
+    readOnly: true,
+  },
+  {
+    command: 'review',
+    name: 'Code Reviewer',
+    description: 'Review code for bugs, security issues, and quality',
+    detail: 'Scans for OWASP top 10, logic errors, code smells',
+    icon: '🔍',
+    systemPrompt: `You are a Code Review agent. Your job is to review code for issues.
+
+Your approach:
+1. Read the files or directories the user specifies
+2. Check for:
+   - Security vulnerabilities (OWASP top 10: injection, XSS, auth bypass, etc.)
+   - Logic errors and edge cases
+   - Error handling gaps
+   - Performance issues (N+1 queries, memory leaks, blocking operations)
+   - Code quality (naming, complexity, duplication)
+3. Rate each finding by severity: CRITICAL / HIGH / MEDIUM / LOW
+4. Provide specific fix suggestions with code
+
+Rules:
+- ONLY use read-only tools: read_file, search_code, list_files, search_files
+- NEVER modify any files
+- Focus on HIGH and CRITICAL issues first
+- Include file:line references
+- Structure: Summary → Critical Issues → Other Findings → Recommendations
+- Be specific — "line 42 has SQL injection via string interpolation" not "check for SQL injection"`,
+    readOnly: true,
+  },
+  {
+    command: 'architect',
+    name: 'Feature Architect',
+    description: 'Design feature implementations with file plans',
+    detail: 'Analyzes patterns, designs components, maps data flows',
+    icon: '📐',
+    systemPrompt: `You are a Feature Architect agent. Your job is to design how a feature should be implemented.
+
+Your approach:
+1. Understand the feature requirements from the user
+2. Analyze existing codebase patterns and conventions:
+   - File organization and naming
+   - Import patterns and module structure
+   - Error handling patterns
+   - Testing patterns
+3. Design the implementation:
+   - List all files to create/modify
+   - Component/module design with interfaces
+   - Data flow (request → processing → response)
+   - Database schema changes if needed
+4. Provide implementation order (what to build first)
+
+Rules:
+- ONLY use read-only tools: read_file, search_code, list_files, search_files
+- NEVER modify any files — you DESIGN, you don't implement
+- Follow existing project conventions
+- Structure: Requirements → Architecture → File Plan → Implementation Order → Risks
+- Include code sketches for key interfaces
+- Call out edge cases and potential pitfalls`,
+    readOnly: true,
+  },
+];
+
+// ── Agent Runner ─────────────────────────────────────────────
+
+/**
+ * Run a built-in agent with the given instruction.
+ * @param {string} agentName - e.g. 'explore', 'review', 'architect'
+ * @param {string} instruction - User's instruction
+ * @param {Object} ctx - { auth, toolExecutor, approval }
+ * @param {Object} session - Session state
+ * @param {Function} renderEvent - Event renderer function
+ */
+export async function runAgent(agentName, instruction, ctx, session, renderEvent) {
+  const agent = BUILTIN_AGENTS.find(a => a.command === agentName);
+  if (!agent) {
+    process.stderr.write(`  ${c.red('Unknown agent: ' + agentName)}\n`);
+    return;
+  }
+
+  const creds = ctx.auth.loadCredentials();
+  if (!creds.token) {
+    process.stderr.write(`  ${c.red('Not logged in. Run /login first.')}\n`);
+    return;
+  }
+
+  // Header
+  process.stderr.write(`\n  ${agent.icon} ${c.bold(c.brand(agent.name))}\n`);
+  process.stderr.write(`  ${c.gray('─'.repeat(40))}\n`);
+  process.stderr.write(`  ${c.gray(instruction)}\n\n`);
+
+  // Prepend agent system prompt to instruction
+  const fullInstruction = `${agent.systemPrompt}\n\n---\n\nUser request: ${instruction}`;
+
+  // For read-only agents, use a restricted approval manager
+  const { ApprovalManager } = await import('../core/approval.mjs');
+  const agentApproval = agent.readOnly
+    ? new ApprovalManager({ planMode: true })  // planMode blocks all writes
+    : ctx.approval;
+
+  const client = new TarangStreamClient({
+    baseUrl: creds.backendUrl,
+    token: creds.token,
+    toolExecutor: ctx.toolExecutor,
+    approvalManager: agentApproval,
+  });
+
+  session.turns++;
+  session.toolCalls = 0;
+  let assistantContent = '';
+
+  try {
+    for await (const event of client.execute(fullInstruction, { cwd: process.cwd() })) {
+      renderEvent(event);
+
+      if (event.type === 'content' || event.type === 'content_partial') {
+        const text = event.data?.text || '';
+        if (text) assistantContent = text;
+      }
+    }
+  } catch (err) {
+    inPlace('');
+    process.stderr.write(`  ${c.red('Agent error: ' + err.message)}\n`);
+  }
+
+  // Save to conversation history
+  if (assistantContent) {
+    session.history.push(
+      { role: 'user', content: `[${agent.name}] ${instruction}` },
+      { role: 'assistant', content: assistantContent }
+    );
+  }
+
+  process.stderr.write('\n');
+}

package/src/terminal/analytics.mjs

@@ -0,0 +1,292 @@
+import * as http from 'node:http';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+import {
+  getRecentSessions,
+  getSessionStats,
+  getToolBreakdown,
+  getModelBreakdown,
+  getHistory,
+  getSessionDetail,
+  getStorePaths,
+} from '../core/local-store.mjs';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
+
+function parseNumber(value, fallback) {
+  const num = Number.parseInt(value, 10);
+  return Number.isFinite(num) && num >= 0 ? num : fallback;
+}
+
+function readOption(args, name, fallback = null) {
+  const idx = args.indexOf(name);
+  if (idx === -1 || idx === args.length - 1) return fallback;
+  return args[idx + 1];
+}
+
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+function basename(projectPath) {
+  return projectPath ? path.basename(projectPath) : 'unknown';
+}
+
+function formatNumber(num) {
+  return new Intl.NumberFormat('en-US').format(num || 0);
+}
+
+function formatWhen(value) {
+  if (!value) return 'n/a';
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? 'n/a' : date.toLocaleString();
+}
+
+function formatDuration(startTime, endTime) {
+  if (!startTime || !endTime) return 'n/a';
+  const ms = new Date(endTime).getTime() - new Date(startTime).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return 'n/a';
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.round(ms / 100) / 10;
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rem = Math.round((seconds % 60) * 10) / 10;
+  return `${minutes}m ${rem}s`;
+}
+
+function truncate(text, max = 80) {
+  if (!text) return '';
+  return text.length > max ? `${text.slice(0, max - 3)}...` : text;
+}
+
+function relativeDaysLabel(days) {
+  return days === 0 ? 'all time' : `last ${days} days`;
+}
+
+function extractPrompt(entry) {
+  return truncate(entry?.display || '', 120);
+}
+
+export function formatSessionsReport(sessions, limit) {
+  if (!sessions.length) {
+    return 'No local sessions found in ~/.kepler/projects.\n';
+  }
+
+  const lines = [];
+  lines.push(`KEPLER SESSIONS  ${sessions.length} shown`);
+  lines.push(`Recent local transcripts from ~/.kepler/projects  (limit ${limit})`);
+  lines.push('');
+
+  for (const session of sessions) {
+    const model = session.models[0] || 'backend default';
+    const totalTokens = (session.inputTokens || 0) + (session.outputTokens || 0);
+    lines.push(`${formatWhen(session.endTime || session.startTime)}  ${basename(session.project)}`);
+    lines.push(`  session  ${session.sessionId}`);
+    lines.push(`  prompt   ${truncate(session.firstPrompt || '(no prompt captured)', 96)}`);
+    lines.push(`  usage    ${formatNumber(totalTokens)} tok  ${formatNumber(session.toolCalls.reduce((sum, tool) => sum + tool.count, 0))} tools  ${session.userMessages} user / ${session.assistantMessages} assistant`);
+    lines.push(`  model    ${model}${session.gitBranch ? `  git:${session.gitBranch}` : ''}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+export function formatStatsReport(stats, tools, models, days, paths) {
+  const lines = [];
+  lines.push(`KEPLER STATS  ${relativeDaysLabel(days)}`);
+  lines.push(`Store: ${paths.keplerDir}`);
+  lines.push('');
+  lines.push(`Sessions        ${formatNumber(stats.totalSessions)}`);
+  lines.push(`Messages        ${formatNumber(stats.totalUserMessages + stats.totalAssistantMessages)}  (${formatNumber(stats.totalUserMessages)} user, ${formatNumber(stats.totalAssistantMessages)} assistant)`);
+  lines.push(`Tokens          ${formatNumber(stats.totalInputTokens + stats.totalOutputTokens)}  (${formatNumber(stats.totalInputTokens)} in, ${formatNumber(stats.totalOutputTokens)} out)`);
+  lines.push(`Cache Read      ${formatNumber(stats.totalCacheReadTokens)}`);
+  lines.push(`Tool Calls      ${formatNumber(stats.totalToolCalls)}`);
+  lines.push('');
+
+  lines.push('Top Tools');
+  if (tools.length === 0) {
+    lines.push('  none');
+  } else {
+    for (const tool of tools.slice(0, 8)) {
+      lines.push(`  ${tool.name.padEnd(18)} ${formatNumber(tool.count)}`);
+    }
+  }
+  lines.push('');
+
+  lines.push('Models');
+  if (models.length === 0) {
+    lines.push('  none');
+  } else {
+    for (const model of models.slice(0, 8)) {
+      lines.push(`  ${truncate(model.model, 42).padEnd(42)} ${formatNumber(model.sessions)} sessions`);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+export function formatHistoryReport(entries, limit) {
+  if (!entries.length) {
+    return 'No local prompt history found in ~/.kepler/history.jsonl.\n';
+  }
+
+  const lines = [];
+  lines.push(`KEPLER HISTORY  ${entries.length} shown`);
+  lines.push(`Recent prompts from ~/.kepler/history.jsonl  (limit ${limit})`);
+  lines.push('');
+
+  for (const entry of entries) {
+    lines.push(`${formatWhen(entry.timestamp)}  ${basename(entry.project)}`);
+    lines.push(`  ${extractPrompt(entry)}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function json(res, status, payload) {
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+  });
+  res.end(JSON.stringify(payload));
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function openBrowser(url) {
+  try {
+    let child;
+    if (process.platform === 'darwin') {
+      child = spawn('open', [url], { stdio: 'ignore', detached: true });
+    } else if (process.platform === 'win32') {
+      child = spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true });
+    } else {
+      child = spawn('xdg-open', [url], { stdio: 'ignore', detached: true });
+    }
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runSessionsCommand(args = []) {
+  const limit = parseNumber(readOption(args, '--limit', '20'), 20);
+  const sessions = getRecentSessions(limit);
+  process.stdout.write(formatSessionsReport(sessions, limit));
+}
+
+export async function runStatsCommand(args = []) {
+  const days = parseNumber(readOption(args, '--days', '30'), 30);
+  const stats = getSessionStats(days);
+  const tools = getToolBreakdown(days);
+  const models = getModelBreakdown(days);
+  const paths = getStorePaths();
+  process.stdout.write(formatStatsReport(stats, tools, models, days, paths));
+}
+
+export async function runHistoryCommand(args = []) {
+  const limit = parseNumber(readOption(args, '--limit', '50'), 50);
+  const history = getHistory(limit);
+  process.stdout.write(formatHistoryReport(history, limit));
+}
+
+// Dashboard removed — now using Kepler Pulse (pulse/cli.js)
+
+export async function _runDashboardCommand_REMOVED() { /* see pulse/cli.js */ }
+
+export async function _OLD_runDashboardCommand(args = []) {
+  const requestedPort = parseNumber(readOption(args, '--port', '4318'), 4318);
+  const host = readOption(args, '--host', '127.0.0.1') || '127.0.0.1';
+  const shouldOpen = !hasFlag(args, '--no-open');
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url || '/', `http://${req.headers.host || `${host}:${requestedPort}`}`);
+
+      if (url.pathname === '/') {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(dashboardHtml());
+        return;
+      }
+
+      if (url.pathname === '/api/overview') {
+        const days = parseNumber(url.searchParams.get('days') || '30', 30);
+        const limit = parseNumber(url.searchParams.get('limit') || '18', 18);
+        const historyLimit = parseNumber(url.searchParams.get('history_limit') || '40', 40);
+        const [stats, tools, models, sessions] = await Promise.all([
+          getSessionStats(days),
+          getToolBreakdown(days),
+          getModelBreakdown(days),
+          getRecentSessions(limit),
+        ]);
+        json(res, 200, {
+          stats,
+          tools,
+          models,
+          sessions,
+          history: getHistory(historyLimit),
+          paths: getStorePaths(),
+        });
+        return;
+      }
+
+      if (url.pathname === '/api/session') {
+        const sessionId = url.searchParams.get('session_id') || '';
+        if (!sessionId) {
+          json(res, 400, { error: 'session_id is required' });
+          return;
+        }
+        const detail = await getSessionDetail(sessionId);
+        if (!detail) {
+          json(res, 404, { error: 'Session not found' });
+          return;
+        }
+        json(res, 200, detail);
+        return;
+      }
+
+      json(res, 404, { error: 'Not found' });
+    } catch (err) {
+      json(res, 500, { error: err.message || 'Internal error' });
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(requestedPort, host, resolve);
+  });
+
+  const address = server.address();
+  const actualPort = typeof address === 'object' && address ? address.port : requestedPort;
+  const url = `http://${host}:${actualPort}`;
+
+  process.stderr.write(`\x1b[36mKepler dashboard\x1b[0m ${url}\n`);
+  process.stderr.write(`\x1b[2mReading local analytics from ${getStorePaths().keplerDir}\x1b[0m\n`);
+  process.stderr.write(`\x1b[2mPress Ctrl+C to stop the dashboard server.\x1b[0m\n`);
+
+  if (shouldOpen) {
+    const opened = openBrowser(url);
+    if (!opened) {
+      process.stderr.write(`\x1b[33mUnable to open a browser automatically. Open ${url} manually.\x1b[0m\n`);
+    }
+  }
+
+  const shutdown = () => {
+    server.close(() => process.exit(0));
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}