stakeout-cli 0.1.0

package/LICENSE

@@ -0,0 +1,131 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Casey (https://github.com/yourusername)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,152 @@
+# Stakeout
+
+Surveillance ops for your codebase. AI-powered change tracking that turns your git history into readable summaries.
+
+**Stop reading diffs. Start understanding changes.**
+
+## What It Does
+
+Every time you commit (or manually record), Stakeout:
+1. Captures the diff
+2. Sends it to an AI (local Ollama or OpenAI)
+3. Generates a human-readable summary focused on *why* and *impact*
+4. Stores it in a searchable database
+
+Later you can:
+- Browse your dev history as readable summaries
+- Search through past changes
+- Chat with AI about your codebase evolution
+- Generate digests ("what happened this week?")
+- Tag, favorite, and annotate entries
+
+## Install
+
+```bash
+npm install -g stakeout
+# or
+npx stakeout
+```
+
+## Quick Start
+
+```bash
+# Initialize in your repo
+stakeout init
+
+# Record current changes
+stakeout record
+
+# View recent summaries
+stakeout log
+
+# See what you did this week
+stakeout log --since "1 week"
+```
+
+## Commands
+
+| Command | What It Does |
+|---------|--------------|
+| `stakeout init` | Initialize for a repo, optionally install git hook |
+| `stakeout record` | Record and summarize current changes |
+| `stakeout log` | View recorded summaries |
+| `stakeout search <query>` | Search through summaries |
+| `stakeout chat` | Chat with AI about your codebase history |
+| `stakeout digest` | Generate high-level digest of recent activity |
+| `stakeout stats` | Show statistics and analytics |
+| `stakeout watch` | Watch for changes and auto-record |
+| `stakeout hook` | Install git post-commit hook for auto-recording |
+| `stakeout dashboard` | Open web UI |
+| `stakeout tui` | Open terminal UI |
+
+## AI Configuration
+
+Stakeout uses **Ollama by default** (free, local, private).
+
+```bash
+# Check current config
+stakeout config --show
+
+# Use Ollama (default)
+stakeout config --provider ollama
+stakeout config --ollama-model llama3.1
+
+# Or use OpenAI
+stakeout config --provider openai
+stakeout config --openai-key sk-...
+stakeout config --openai-model gpt-4o-mini
+```
+
+## Auto-Recording
+
+Set it and forget it:
+
+```bash
+# Install git hook (records on every commit)
+stakeout hook
+
+# Or watch mode (records on file changes)
+stakeout watch
+```
+
+## Organization
+
+```bash
+# Tag entries
+stakeout tag 42 --add "feature,auth"
+
+# Mark as favorite
+stakeout note 42 --favorite
+
+# Add notes
+stakeout note 42 --note "This fixed the login bug"
+
+# Mark breaking changes
+stakeout note 42 --breaking
+
+# Filter by tag
+stakeout log --tag feature
+
+# Show only favorites
+stakeout log --favorites
+```
+
+## Export
+
+```bash
+# Export to markdown
+stakeout export --format markdown --since "1 month" -o changelog.md
+
+# Export to JSON
+stakeout export --format json -o history.json
+```
+
+## Multi-Repo
+
+```bash
+# Add repos to track
+stakeout repo --add /path/to/project
+
+# List tracked repos
+stakeout repo --list
+```
+
+## Storage
+
+Everything stored locally in `~/.stakeout/`:
+- `stakeout.db` — SQLite database
+- `config.json` — settings
+
+Your code never leaves your machine (unless you choose OpenAI).
+
+## Why?
+
+Because "what did I do last week?" shouldn't require archaeology.
+
+Because commit messages are often "fix" or "wip" or nothing at all.
+
+Because AI can read your diffs and tell you what actually changed.
+
+---
+
+*Built for devs who want their git history to make sense.*

package/dist/commands/chat.d.ts

@@ -0,0 +1,5 @@
+interface ChatOptions {
+    clear?: boolean;
+}
+export declare function chat(options: ChatOptions): Promise<void>;
+export {};

package/dist/commands/chat.js

@@ -0,0 +1,162 @@
+import chalk from 'chalk';
+import * as readline from 'readline';
+import { getEntries, getDb, addChatMessage, getChatHistory, clearChatHistory } from '../lib/database.js';
+import { loadConfig } from '../lib/config.js';
+import { Ollama } from 'ollama';
+import OpenAI from 'openai';
+const SYSTEM_PROMPT = `You are STAKEOUT AI, an intelligent assistant that helps developers understand their codebase history and changes.
+
+You have access to a database of recorded code changes, each with:
+- A timestamp
+- An AI-generated summary of what changed
+- The directories and files affected
+- Optional commit hash and message
+- Tags, notes, and whether it's marked as breaking
+
+Your job is to:
+1. Answer questions about what changed and when
+2. Identify patterns in development activity
+3. Help find specific changes or features
+4. Provide insights about the codebase evolution
+
+Be concise but helpful. Use the context provided to give accurate answers.
+If you don't have enough information, say so.`;
+export async function chat(options) {
+    if (options.clear) {
+        clearChatHistory();
+        console.log(chalk.green('Chat history cleared.'));
+        return;
+    }
+    console.log(chalk.bold.green('\n🔍 STAKEOUT AI Chat\n'));
+    console.log(chalk.dim('Ask questions about your codebase history.'));
+    console.log(chalk.dim('Type "exit" to quit, "clear" to reset history.\n'));
+    console.log(chalk.dim('─'.repeat(50)));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const prompt = () => {
+        rl.question(chalk.cyan('\nYou: '), async (input) => {
+            const trimmed = input.trim();
+            if (!trimmed) {
+                prompt();
+                return;
+            }
+            if (trimmed.toLowerCase() === 'exit') {
+                console.log(chalk.dim('\nGoodbye!'));
+                rl.close();
+                return;
+            }
+            if (trimmed.toLowerCase() === 'clear') {
+                clearChatHistory();
+                console.log(chalk.yellow('Chat history cleared.'));
+                prompt();
+                return;
+            }
+            try {
+                // Get context from database
+                const context = await gatherContext(trimmed);
+                // Get chat history
+                const history = getChatHistory(10);
+                // Add user message to history
+                addChatMessage('user', trimmed);
+                // Generate response
+                console.log(chalk.dim('\nThinking...'));
+                const response = await generateResponse(trimmed, context, history);
+                // Add assistant response to history
+                addChatMessage('assistant', response);
+                console.log(chalk.green('\nSTAKEOUT: ') + response);
+            }
+            catch (error) {
+                console.error(chalk.red('\nError: ' + error.message));
+            }
+            prompt();
+        });
+    };
+    prompt();
+}
+async function gatherContext(query) {
+    const db = getDb();
+    // Get recent entries
+    const recentEntries = getEntries({ limit: 20 });
+    // Get stats
+    const total = db.prepare('SELECT COUNT(*) as count FROM entries').get().count;
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    const todayCount = db.prepare('SELECT COUNT(*) as count FROM entries WHERE timestamp >= ?').get(today.toISOString()).count;
+    const weekAgo = new Date();
+    weekAgo.setDate(weekAgo.getDate() - 7);
+    const weekCount = db.prepare('SELECT COUNT(*) as count FROM entries WHERE timestamp >= ?').get(weekAgo.toISOString()).count;
+    // Search for relevant entries based on query keywords
+    const keywords = query.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+    let relevantEntries = [];
+    if (keywords.length > 0) {
+        const searchPattern = keywords.map(k => `%${k}%`);
+        const conditions = keywords.map(() => '(summary LIKE ? OR directories LIKE ? OR files_changed LIKE ?)').join(' OR ');
+        const params = searchPattern.flatMap(p => [p, p, p]);
+        relevantEntries = db.prepare(`
+      SELECT * FROM entries
+      WHERE ${conditions}
+      ORDER BY timestamp DESC
+      LIMIT 10
+    `).all(...params);
+    }
+    // Build context string
+    let context = `DATABASE STATS:\n`;
+    context += `- Total entries: ${total}\n`;
+    context += `- Today: ${todayCount}\n`;
+    context += `- This week: ${weekCount}\n\n`;
+    if (relevantEntries.length > 0) {
+        context += `RELEVANT ENTRIES (matching query keywords):\n`;
+        for (const entry of relevantEntries) {
+            const dirs = JSON.parse(entry.directories);
+            context += `\n[#${entry.id} - ${new Date(entry.timestamp).toLocaleDateString()}]\n`;
+            context += `Summary: ${entry.summary}\n`;
+            context += `Directories: ${dirs.join(', ')}\n`;
+            if (entry.commit_hash)
+                context += `Commit: ${entry.commit_hash.slice(0, 7)}\n`;
+            if (entry.tags && entry.tags !== '[]')
+                context += `Tags: ${entry.tags}\n`;
+            if (entry.is_breaking)
+                context += `⚠️ BREAKING CHANGE\n`;
+        }
+    }
+    context += `\nRECENT ENTRIES:\n`;
+    for (const entry of recentEntries.slice(0, 5)) {
+        context += `\n[#${entry.id} - ${new Date(entry.timestamp).toLocaleDateString()}]\n`;
+        context += `Summary: ${entry.summary}\n`;
+        context += `Directories: ${entry.directories.join(', ')}\n`;
+    }
+    return context;
+}
+async function generateResponse(query, context, history) {
+    const config = loadConfig();
+    const messages = [
+        { role: 'system', content: SYSTEM_PROMPT },
+        { role: 'system', content: `CONTEXT:\n${context}` },
+        ...history.map(h => ({ role: h.role, content: h.content })),
+        { role: 'user', content: query }
+    ];
+    if (config.llm_provider === 'ollama') {
+        const ollama = new Ollama({ host: config.ollama_host });
+        const response = await ollama.chat({
+            model: config.ollama_model,
+            messages,
+            options: { temperature: 0.7 }
+        });
+        return response.message.content.trim();
+    }
+    else {
+        if (!config.openai_api_key) {
+            throw new Error('OpenAI API key not configured');
+        }
+        const openai = new OpenAI({ apiKey: config.openai_api_key });
+        const response = await openai.chat.completions.create({
+            model: config.openai_model,
+            messages,
+            temperature: 0.7,
+            max_tokens: 1000
+        });
+        return response.choices[0]?.message?.content?.trim() ?? 'Unable to generate response';
+    }
+}

package/dist/commands/clear.d.ts

@@ -0,0 +1,7 @@
+interface ClearOptions {
+    before?: string;
+    all?: boolean;
+    yes?: boolean;
+}
+export declare function clear(options: ClearOptions): Promise<void>;
+export {};

package/dist/commands/clear.js

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+import { getDb } from '../lib/database.js';
+import * as readline from 'readline';
+export async function clear(options) {
+    const db = getDb();
+    let count;
+    let description;
+    if (options.all) {
+        const result = db.prepare('SELECT COUNT(*) as count FROM entries').get();
+        count = result.count;
+        description = 'ALL entries';
+    }
+    else if (options.before) {
+        const before = parseBefore(options.before);
+        const result = db.prepare('SELECT COUNT(*) as count FROM entries WHERE timestamp < ?').get(before);
+        count = result.count;
+        description = `entries before ${new Date(before).toLocaleDateString()}`;
+    }
+    else {
+        console.log(chalk.yellow('Please specify --all or --before <time>'));
+        console.log(chalk.dim('Examples:'));
+        console.log(chalk.dim('  stakeout clear --before "30 days"'));
+        console.log(chalk.dim('  stakeout clear --before "2024-01-01"'));
+        console.log(chalk.dim('  stakeout clear --all'));
+        return;
+    }
+    if (count === 0) {
+        console.log(chalk.yellow('No entries to delete.'));
+        return;
+    }
+    console.log(chalk.yellow(`\nThis will delete ${count} ${description}.`));
+    if (!options.yes) {
+        const confirmed = await confirm('Are you sure? (y/N) ');
+        if (!confirmed) {
+            console.log(chalk.dim('Cancelled.'));
+            return;
+        }
+    }
+    if (options.all) {
+        db.prepare('DELETE FROM entries').run();
+    }
+    else if (options.before) {
+        const before = parseBefore(options.before);
+        db.prepare('DELETE FROM entries WHERE timestamp < ?').run(before);
+    }
+    console.log(chalk.green(`✓ Deleted ${count} entries.`));
+}
+function parseBefore(before) {
+    // Try relative time first
+    const match = before.match(/^(\d+)\s*(day|days|week|weeks|month|months)$/i);
+    if (match) {
+        const now = new Date();
+        const amount = parseInt(match[1], 10);
+        const unit = match[2].toLowerCase();
+        switch (unit) {
+            case 'day':
+            case 'days':
+                now.setDate(now.getDate() - amount);
+                break;
+            case 'week':
+            case 'weeks':
+                now.setDate(now.getDate() - (amount * 7));
+                break;
+            case 'month':
+            case 'months':
+                now.setMonth(now.getMonth() - amount);
+                break;
+        }
+        return now.toISOString();
+    }
+    // Try parsing as date
+    const parsed = new Date(before);
+    if (!isNaN(parsed.getTime())) {
+        return parsed.toISOString();
+    }
+    throw new Error(`Invalid date format: ${before}`);
+}
+function confirm(prompt) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    return new Promise(resolve => {
+        rl.question(prompt, answer => {
+            rl.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,10 @@
+interface ConfigOptions {
+    provider?: string;
+    ollamaModel?: string;
+    ollamaHost?: string;
+    openaiKey?: string;
+    openaiModel?: string;
+    show?: boolean;
+}
+export declare function config(options: ConfigOptions): Promise<void>;
+export {};

package/dist/commands/config.js

@@ -0,0 +1,64 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig, getConfigPath } from '../lib/config.js';
+export async function config(options) {
+    const currentConfig = loadConfig();
+    // If --show or no options, display current config
+    if (options.show || Object.keys(options).length === 0) {
+        console.log(chalk.bold('\n⚙️  STAKEOUT CONFIG\n'));
+        console.log(chalk.dim(`Location: ${getConfigPath()}\n`));
+        console.log(chalk.cyan('LLM Provider:'), currentConfig.llm_provider);
+        console.log('');
+        console.log(chalk.dim('Ollama:'));
+        console.log(`  Model: ${currentConfig.ollama_model}`);
+        console.log(`  Host:  ${currentConfig.ollama_host}`);
+        console.log('');
+        console.log(chalk.dim('OpenAI:'));
+        console.log(`  Model:   ${currentConfig.openai_model}`);
+        console.log(`  API Key: ${currentConfig.openai_api_key ? '****' + currentConfig.openai_api_key.slice(-4) : chalk.yellow('not set')}`);
+        console.log('');
+        console.log(chalk.dim('Ignore patterns:'));
+        currentConfig.ignore_patterns.slice(0, 5).forEach(p => {
+            console.log(`  - ${p}`);
+        });
+        if (currentConfig.ignore_patterns.length > 5) {
+            console.log(chalk.dim(`  ... and ${currentConfig.ignore_patterns.length - 5} more`));
+        }
+        console.log('');
+        return;
+    }
+    // Update config based on options
+    let updated = false;
+    if (options.provider) {
+        if (options.provider !== 'ollama' && options.provider !== 'openai') {
+            console.error(chalk.red('Provider must be "ollama" or "openai"'));
+            process.exit(1);
+        }
+        currentConfig.llm_provider = options.provider;
+        updated = true;
+        console.log(chalk.green(`✓ Provider set to: ${options.provider}`));
+    }
+    if (options.ollamaModel) {
+        currentConfig.ollama_model = options.ollamaModel;
+        updated = true;
+        console.log(chalk.green(`✓ Ollama model set to: ${options.ollamaModel}`));
+    }
+    if (options.ollamaHost) {
+        currentConfig.ollama_host = options.ollamaHost;
+        updated = true;
+        console.log(chalk.green(`✓ Ollama host set to: ${options.ollamaHost}`));
+    }
+    if (options.openaiKey) {
+        currentConfig.openai_api_key = options.openaiKey;
+        updated = true;
+        console.log(chalk.green(`✓ OpenAI API key set`));
+    }
+    if (options.openaiModel) {
+        currentConfig.openai_model = options.openaiModel;
+        updated = true;
+        console.log(chalk.green(`✓ OpenAI model set to: ${options.openaiModel}`));
+    }
+    if (updated) {
+        saveConfig(currentConfig);
+        console.log(chalk.dim('\nConfig saved.'));
+    }
+}

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,5 @@
+interface DashboardOptions {
+    port?: string;
+}
+export declare function dashboard(options: DashboardOptions): Promise<void>;
+export {};

package/dist/commands/dashboard.js

@@ -0,0 +1,9 @@
+import chalk from 'chalk';
+import { createServer } from '../web/server.js';
+export async function dashboard(options) {
+    const port = options.port ? parseInt(options.port, 10) : 3333;
+    console.log(chalk.dim('Starting STAKEOUT Command Center...'));
+    createServer(port);
+    console.log(chalk.green(`Dashboard: http://localhost:${port}`));
+    console.log(chalk.dim('\nPress Ctrl+C to stop'));
+}

package/dist/commands/digest.d.ts

@@ -0,0 +1,6 @@
+interface DigestOptions {
+    since?: string;
+    path?: string;
+}
+export declare function digest(options: DigestOptions): Promise<void>;
+export {};