quackstack 1.0.23 → 1.0.25

package/README.md

@@ -4,23 +4,21 @@
 
 QuackStack is an interactive CLI tool that indexes your codebase using local AI embeddings and lets you ask questions about it conversationally. Perfect for understanding unfamiliar code, onboarding to new projects, or giving your AI coding assistant persistent context.
 
-## 🎯 Quack in Action!
-Check out the QuackStack Live demo [here](https://courageous-spaniel.clueso.site/share/4f5e6395-8ad8-4d18-8e81-f736a6581a25)!
-## ✨ Features
+[Live Demo](https://courageous-spaniel.clueso.site/share/4f5e6395-8ad8-4d18-8e81-f736a6581a25) | [Documentation](https://quackstack.siddharththakkar.xyz/docs) | [Frontend](https://github.com/woustachemax/quack-web)
 
-* 🚀 **Zero-config** - Just run `quack` in any project directory
-* 🧠 **Smart code parsing** - Automatically extracts functions and classes
-* 💬 **Interactive REPL** - Ask questions conversationally, stays open until Ctrl+C
-* 🔒 **100% Local embeddings** - No API calls for vector generation, your code stays private
-* 🤖 **AI-powered answers** - Uses OpenAI, Claude, Gemini, DeepSeek, or Mistral for conversational responses
-* 🎯 **Universal AI tool support** - Auto-generate context for Cursor, Windsurf, Cline, Continue, and Aider
-* 📦 **Local database** - Your code stays on your infrastructure
-* 🌍 **Multi-language** - Supports JS/TS, Python, Go, Rust, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, and more
+## Features
 
+* **Zero-config** - Just run `quack` in any project directory
+* **Smart code parsing** - Automatically extracts functions and classes
+* **Interactive REPL** - Ask questions conversationally, stays open until Ctrl+C
+* **100% Local embeddings** - No API calls for vector generation, your code stays private
+* **AI-powered answers** - Uses OpenAI, Claude, Gemini, DeepSeek, Grok, or Mistral for conversational responses
+* **Git history integration** - Track authorship, commit history, and code ownership
+* **Universal AI tool support** - Auto-generate context for Cursor, Windsurf, Cline, Continue, and Aider
+* **Local database** - Your code stays on your infrastructure
+* **Multi-language** - Supports JS/TS, Python, Go, Rust, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, and more
 
-## 💻 Frontend
-Check out the Frontend Repo [here](https://github.com/woustachemax/quack-web)
-## 📦 Installation
+## Installation
 
 ### Global Install (Recommended)
 
@@ -39,7 +37,7 @@ pnpm install
 pnpm build
 ```
 
-## ⚙️ Setup
+## Setup
 
 ### 1. Create `.env` in your project root
 
@@ -50,7 +48,7 @@ QUACKSTACK_DATABASE_URL=postgresql://user:pass@host:port/dbname
 # REQUIRED: Choose ONE AI provider for conversational answers
 # (Embeddings are computed locally - no API calls!)
 
-# Option 1: OpenAI (RECOMMENDED)
+# Option 1: OpenAI
 QUACKSTACK_OPENAI_KEY=sk-...
 
 # Option 2: Anthropic Claude
@@ -59,10 +57,13 @@ QUACKSTACK_ANTHROPIC_KEY=sk-ant-...
 # Option 3: Google Gemini (has free tier!)
 QUACKSTACK_GEMINI_KEY=AIza...
 
-# Option 4: DeepSeek (cheapest option)
+# Option 4: xAI Grok
+QUACKSTACK_GROK_KEY=xai-...
+
+# Option 5: DeepSeek (cheapest option)
 QUACKSTACK_DEEPSEEK_KEY=sk-...
 
-# Option 5: Mistral AI
+# Option 6: Mistral AI
 QUACKSTACK_MISTRAL_KEY=...
 ```
 
@@ -73,14 +74,13 @@ npx prisma generate
 npx prisma db push
 ```
 
-## 🚀 Usage
+## Usage
 
 ### Interactive Mode (Default)
 
 ```bash
 quack
-
-# Answer appears with context
+# Ask questions about your codebase
 # Press Ctrl+C to exit
 ```
 
@@ -95,8 +95,31 @@ quack --context
 # - Cline (.clinerules)
 # - Continue (.continue/context.md)
 # - Aider (.aider.conf.yml)
+```
+
+### Generate AGENTS.md Configuration
+
+```bash
+quack --agent
+
+# Creates agent.md with codebase context
+# for AI agent frameworks
+```
+
+### Generate README
+
+```bash
+quack --readme
+
+# Auto-generates README.md from your codebase
+```
+
+### Generate Documentation
 
-# Your AI coding assistants automatically read these files!
+```bash
+quack --docs
+
+# Creates CODEBASE.md with architecture overview
 ```
 
 ### Watch Mode (Auto-update Context)
@@ -105,8 +128,21 @@ quack --context
 quack --watch
 
 # Watches for file changes
-# Auto-regenerates all context files
-# Keep running in background during development
+# Auto-regenerates context files
+```
+
+### Git History Commands
+
+```bash
+# View contributor statistics
+quack authors
+
+# View recently modified files
+quack recent
+quack recent --days 30
+
+# View repository information
+quack git-info
 ```
 
 ### Force Reindex
@@ -117,17 +153,27 @@ quack --reindex
 # Clears old index and re-scans entire codebase
 ```
 
-## 📖 Example Session
+### List Available AI Models
+
+```bash
+quack --list-models
+
+# Shows all configured providers and available models
+```
+
+## Example Session
 
 ```bash
 $ quack
-Welcome to QuackStack! 🐥
-🔍 Indexing your codebase (this may take a moment)...
-✅ Indexing complete!
+Welcome to QuackStack!
+
+Using: OpenAI - gpt-4o
+Press Ctrl+C to exit
 
-💡 Tip: Press Ctrl+C to exit
+Indexing your codebase...
+Indexing complete
 
-🐥 Quack! How can I help? > how does the search function work?
+quack > how does the search function work?
 
 The search function uses local embeddings to convert your query into a vector,
 compares it against stored code embeddings using cosine similarity, ranks results,
@@ -135,141 +181,153 @@ and feeds the top matches to the AI for a conversational answer.
 
 Implementation is in src/commands/search.ts
 
-💡 Want more details? (y/n) > y
+Want more details? (y/n) > n
 
-📚 Relevant Code:
+quack > who wrote the authentication system?
 
-[1] src/commands/search.ts (relevance: 87.3%)
-export async function search(query: string, projectName: string) {
-  const snippets = await client.codeSnippet.findMany({
-    where: { projectName },
-  });
-  // ... cosine similarity ranking ...
-}
-
-🐥 Quack! How can I help? > where are embeddings generated?
-
-Embeddings are generated locally using the local-embeddings module.
-No API calls are made for vector generation, keeping your code private.
-
-💡 Want more details? (y/n) > n
+The authentication system was primarily written by Siddharth Thakkar, with the
+main implementation in app/api/auth/[...nextauth]/options.ts (last modified 187 days ago).
 
-🐥 Quack! How can I help? > ^C
-👋 Happy coding!
+quack > ^C
+Happy coding!
 ```
 
-## 🛠️ How It Works
+## How It Works
 
 1. **Scanning** - Finds all code files (ignoring `node_modules`, `.git`, etc.)
-2. **Parsing** - Uses AST parsing to extract functions/classes from JS/TS
+2. **Parsing** - Uses AST parsing to extract functions/classes
 3. **Chunking** - Breaks code into logical chunks
-4. **Local Embedding** - Generates vector embeddings **locally** (no API calls!)
-5. **Storage** - Saves to your PostgreSQL/Neon database
-6. **Search** - Semantic search using cosine similarity + AI-powered conversational answers
-
-## 🎯 Use Cases
-
-- **Context switching** - Quickly understand projects you haven't touched in months
-- **Onboarding** - New team members can ask questions instead of reading docs
-- **Code archaeology** - Find implementations without grepping
-- **AI coding assistants** - Give Cursor/Windsurf/Cline/Continue/Aider persistent codebase context
-- **Documentation** - Auto-generate explanations of how things work
-- **Privacy-focused** - All embeddings generated locally, no code sent to embedding APIs
+4. **Local Embedding** - Generates vector embeddings locally (no API calls)
+5. **Git Enrichment** - Extracts commit history, authorship, and ownership data
+6. **Storage** - Saves to your PostgreSQL database
+7. **Search** - Semantic search using cosine similarity + AI-powered conversational answers
 
-## 📋 Commands Reference
+## Commands Reference
 
 | Command | Description |
 |---------|-------------|
-| `quack` | Start interactive REPL (auto-indexes first time) |
-| `quack --context` | Generate context files for ALL AI coding tools |
+| `quack` | Start interactive REPL |
+| `quack --context` | Generate context files for all AI coding tools |
+| `quack --agent` | Generate AGENTS.md configuration |
+| `quack --readme` | Generate README.md from codebase |
+| `quack --docs` | Generate CODEBASE.md documentation |
 | `quack --watch` | Watch mode - auto-update context on file changes |
 | `quack --reindex` | Force reindex the entire codebase |
-| `quack --cursor` | [DEPRECATED] Use `--context` instead |
+| `quack --list-models` | Show available AI providers and models |
+| `quack authors` | View contributor statistics |
+| `quack recent [--days N]` | View recently modified files |
+| `quack git-info` | View repository information |
 
-## 🔑 Supported AI Providers
+## Supported AI Providers
 
 | Provider | Used For | Cost | Privacy | Setup |
 |----------|----------|------|---------|-------|
-| **Local** | Embeddings | FREE | 🔒 100% Private | Built-in |
+| **Local** | Embeddings | FREE | 100% Private | Built-in |
 | OpenAI | Chat answers | $$ | Query only | [Get key](https://platform.openai.com/api-keys) |
 | Anthropic | Chat answers | $$$ | Query only | [Get key](https://console.anthropic.com/) |
 | Gemini | Chat answers | FREE | Query only | [Get key](https://aistudio.google.com/app/apikey) |
+| xAI Grok | Chat answers | $$ | Query only | [Get key](https://x.ai/) |
 | DeepSeek | Chat answers | $ | Query only | [Get key](https://platform.deepseek.com/) |
 | Mistral | Chat answers | $$ | Query only | [Get key](https://console.mistral.ai/) |
 
-**Privacy Note:** QuackStack generates embeddings **locally** on your machine. Only your natural language queries and retrieved code context are sent to the AI provider for generating conversational answers. Your entire codebase is never sent to any API.
+**Privacy Note:** QuackStack generates embeddings locally on your machine. Only your natural language queries and retrieved code context are sent to the AI provider for generating conversational answers. Your entire codebase is never sent to any API.
 
-## 🗄️ Database Schema
+## Database Schema
 
 ```prisma
 model codeSnippet {
-  id           Int      @id @default(autoincrement())
-  content      String
-  embedding    Json     // Stored as JSON array of numbers
-  filePath     String
-  projectName  String
-  language     String?
-  functionName String?
-  lineStart    Int?
-  lineEnd      Int?
-  createdAt    DateTime @default(now())
-  updatedAt    DateTime @updatedAt
+  id                 Int       @id @default(autoincrement())
+  content            String
+  embedding          Json
+  filePath           String
+  projectName        String
+  language           String?
+  functionName       String?
+  lineStart          Int?
+  lineEnd            Int?
+  
+  lastCommitHash     String?
+  lastCommitAuthor   String?
+  lastCommitEmail    String?
+  lastCommitDate     DateTime?
+  lastCommitMessage  String?
+  totalCommits       Int?       @default(0)
+  primaryAuthor      String?
+  primaryAuthorEmail String?
+  fileOwnerCommits   Int?       @default(0)
+  
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
   @@index([projectName])
+  @@index([lastCommitDate])
+  @@index([primaryAuthor])
 }
-```
 
-Each project is isolated by `projectName` (uses current directory name).
+model gitAuthor {
+  id             Int       @id @default(autoincrement())
+  projectName    String
+  author         String
+  email          String
+  totalCommits   Int       @default(0)
+  linesAdded     Int       @default(0)
+  linesRemoved   Int       @default(0)
+  recentActivity DateTime?
+  filesOwned     String[]
+  
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([projectName, email])
+  @@index([projectName])
+  @@index([recentActivity])
+}
+```
 
-## 🌍 Supported Languages
+## Supported Languages
 
 JavaScript, TypeScript, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, R, Vue, Svelte
 
-## 🎓 Development
+## Use Cases
+
+- **Context switching** - Quickly understand projects you haven't touched in months
+- **Onboarding** - New team members can ask questions instead of reading docs
+- **Code archaeology** - Find implementations without grepping
+- **Code ownership** - Identify who wrote and maintains specific parts of the codebase
+- **AI coding assistants** - Give Cursor/Windsurf/Cline/Continue/Aider persistent codebase context
+- **Documentation** - Auto-generate explanations of how things work
+- **Privacy-focused** - All embeddings generated locally, no code sent to embedding APIs
+
+## Development
 
 ```bash
 git clone https://github.com/woustachemax/quackstack.git
 cd quackstack
 pnpm install
-
 pnpm build
 
 # Run locally
 node dist/cli.cjs
-node dist/cli.cjs --context
-node dist/cli.cjs --watch
 ```
 
-## 🗺️ Roadmap
-
-- [x] Local embeddings (no API calls!)
-- [x] Support for all major AI coding assistants
-- [ ] VS Code extension
-- [ ] Official Cursor plugin
-- [ ] Export Q&A sessions as markdown docs
-- [ ] Add filtering by file type, date range, author
-- [ ] Support for code diffs and change tracking
-- [ ] Team collaboration features
-- [ ] Self-hosted web UI
-
-## 🤝 Contributing
+## Contributing
 
 Contributions welcome! Feel free to:
 - Report bugs via [GitHub Issues](https://github.com/woustachemax/quackstack/issues)
 - Submit feature requests
 - Open pull requests
 
-## 📄 License
+## License
 
 MIT
 
-## 💡 Pro Tips
+## Pro Tips
 
 **Privacy First**: Embeddings are generated locally - your code never leaves your machine during indexing.
 
 **Gemini Free Tier**: Start with Google Gemini for chat responses - it's free and works great for most use cases.
 
-**Universal Context**: Run `quack --context` once to generate context files for ALL major AI coding tools at once.
+**Universal Context**: Run `quack --context` once to generate context files for all major AI coding tools at once.
 
 **Background Watcher**: Run `quack --watch &` in the background to keep context always fresh across all your AI tools.
 
@@ -277,4 +335,6 @@ MIT
 
 **Large Codebases**: First index might take a few minutes. After that, only changed files are re-indexed.
 
-**No Vendor Lock-in**: Unlike other tools, QuackStack works with Cursor, Windsurf, Cline, Continue, and Aider - choose your favorite!
+**Git Integration**: QuackStack automatically enriches your codebase with git history - no setup required. Track authorship, view recent changes, and understand code ownership.
+
+**No Vendor Lock-in**: Unlike other tools, QuackStack works with Cursor, Windsurf, Cline, Continue, and Aider - choose your favorite!

package/dist/cli.cjs

@@ -12,6 +12,8 @@ const context_generator_js_1 = require("./lib/context-generator.js");
 const readme_js_1 = require("./commands/readme.js");
 const agents_js_1 = require("./commands/agents.js");
 const ai_provider_js_1 = require("./lib/ai-provider.js");
+const database_js_1 = require("./lib/database.js");
+const git_history_js_1 = require("./lib/git-history.js");
 const path_1 = __importDefault(require("path"));
 const program = new commander_1.Command();
 const PROJECT_NAME = path_1.default.basename(process.cwd());
@@ -85,4 +87,84 @@ program
     }
     await (0, repl_js_1.startREPL)(options.reindex, options.provider, options.model);
 });
+program
+    .command("authors")
+    .description("Show contributor statistics for this project")
+    .action(async () => {
+    if (!git_history_js_1.gitHistory.isRepository()) {
+        console.log(chalk_1.default.red("❌ Not a git repository"));
+        process.exit(1);
+    }
+    console.log(chalk_1.default.cyan("\n📊 Contributor Statistics\n"));
+    const authors = await (0, database_js_1.getProjectAuthors)(PROJECT_NAME);
+    if (authors.length === 0) {
+        console.log(chalk_1.default.yellow("No contributor data found. Run 'quack --reindex' first."));
+        process.exit(0);
+    }
+    authors.forEach((author, i) => {
+        console.log(chalk_1.default.green(`${i + 1}. ${author.author}`) + chalk_1.default.gray(` (${author.email})`));
+        console.log(chalk_1.default.white(`   ${author.totalCommits} commits | +${author.linesAdded}/-${author.linesRemoved} lines`));
+        if (author.recentActivity) {
+            const daysAgo = Math.floor((Date.now() - author.recentActivity.getTime()) / (1000 * 60 * 60 * 24));
+            console.log(chalk_1.default.gray(`   Last active ${daysAgo} days ago`));
+        }
+        if (author.filesOwned.length > 0) {
+            console.log(chalk_1.default.gray(`   Owns ${author.filesOwned.length} files`));
+        }
+        console.log();
+    });
+    console.log(chalk_1.default.cyan(`Total: ${authors.length} contributors\n`));
+});
+program
+    .command("recent")
+    .description("Show recently modified files")
+    .option("-d, --days <number>", "Number of days to look back", "7")
+    .action(async (options) => {
+    if (!git_history_js_1.gitHistory.isRepository()) {
+        console.log(chalk_1.default.red("❌ Not a git repository"));
+        process.exit(1);
+    }
+    const days = parseInt(options.days);
+    console.log(chalk_1.default.cyan(`\n📝 Files modified in last ${days} days\n`));
+    const files = await (0, database_js_1.getRecentlyModifiedFiles)(PROJECT_NAME, days);
+    if (files.length === 0) {
+        console.log(chalk_1.default.yellow(`No files modified in last ${days} days (or run 'quack --reindex')`));
+        process.exit(0);
+    }
+    files.forEach((file, i) => {
+        const daysAgo = Math.floor((Date.now() - file.lastCommitDate.getTime()) / (1000 * 60 * 60 * 24));
+        console.log(chalk_1.default.green(`${i + 1}. ${file.filePath}`));
+        console.log(chalk_1.default.gray(`   Modified by ${file.lastCommitAuthor} ${daysAgo} days ago`));
+        if (file.lastCommitMessage) {
+            console.log(chalk_1.default.white(`   "${file.lastCommitMessage.substring(0, 60)}${file.lastCommitMessage.length > 60 ? '...' : ''}"`));
+        }
+        console.log();
+    });
+    console.log(chalk_1.default.cyan(`Total: ${files.length} files\n`));
+});
+program
+    .command("git-info")
+    .description("Show git repository information")
+    .action(() => {
+    if (!git_history_js_1.gitHistory.isRepository()) {
+        console.log(chalk_1.default.red("❌ Not a git repository"));
+        process.exit(1);
+    }
+    console.log(chalk_1.default.cyan("\n🔍 Git Repository Info\n"));
+    const branch = git_history_js_1.gitHistory.getCurrentBranch();
+    if (branch) {
+        console.log(chalk_1.default.white(`Current Branch: `) + chalk_1.default.green(branch));
+    }
+    const repoRoot = git_history_js_1.gitHistory.getRepositoryRoot();
+    console.log(chalk_1.default.white(`Repository Root: `) + chalk_1.default.gray(repoRoot));
+    console.log(chalk_1.default.cyan("\n📈 Recent Commits:\n"));
+    const commits = git_history_js_1.gitHistory.getRecentCommits(10);
+    commits.slice(0, 5).forEach((commit, i) => {
+        const date = new Date(commit.date).toLocaleDateString();
+        console.log(chalk_1.default.green(`${i + 1}. ${commit.author}`) + chalk_1.default.gray(` (${date})`));
+        console.log(chalk_1.default.white(`   ${commit.message.substring(0, 70)}${commit.message.length > 70 ? '...' : ''}`));
+        console.log(chalk_1.default.gray(`   ${commit.filesChanged.length} files changed`));
+        console.log();
+    });
+});
 program.parse();

package/dist/commands/ingest.js

@@ -2,14 +2,20 @@ import fs from "fs";
 import path from "path";
 import { scanDir } from "../lib/scanner.js";
 import { chunkCode } from "../lib/chunker.js";
-import { saveToDB } from "../lib/database.js";
+import { saveToDB, saveAuthorToDB } from "../lib/database.js";
 import { localEmbeddings } from "../lib/local-embeddings.js";
-export async function ingest(rootDir, projectName, silent = false) {
+import { gitHistory, initGitHistory } from "../lib/git-history.js";
+export async function ingest(rootDir, projectName, silent = false, includeGitHistory = true) {
+    initGitHistory(rootDir);
     if (!silent)
         console.log("Starting ingestion...");
     const files = await scanDir(rootDir);
     if (!silent)
         console.log(`Found ${files.length} files to process`);
+    const isGitRepo = gitHistory.isRepository();
+    if (isGitRepo && includeGitHistory && !silent) {
+        console.log(`Git repository detected - enriching with history data`);
+    }
     const allChunks = [];
     for (const filePath of files) {
         try {
@@ -31,10 +37,38 @@ export async function ingest(rootDir, projectName, silent = false) {
         console.log(`Saving to database...`);
     const BATCH_SIZE = 50;
     let processedCount = 0;
+    const fileGitData = new Map();
+    if (isGitRepo && includeGitHistory) {
+        for (const { filePath } of allChunks) {
+            if (!fileGitData.has(filePath)) {
+                const history = gitHistory.getFileHistory(filePath, 100);
+                fileGitData.set(filePath, history);
+            }
+        }
+    }
     for (let i = 0; i < allChunks.length; i += BATCH_SIZE) {
         const batch = allChunks.slice(i, i + BATCH_SIZE);
         await Promise.all(batch.map(async ({ content, filePath, chunk }) => {
             const embedding = localEmbeddings.getVector(content);
+            let gitMetadata = {};
+            if (isGitRepo && includeGitHistory) {
+                const history = fileGitData.get(filePath);
+                if (history && history.commits.length > 0) {
+                    const lastCommit = history.commits[0];
+                    const primaryAuthor = history.primaryAuthors[0];
+                    gitMetadata = {
+                        lastCommitHash: lastCommit.hash,
+                        lastCommitAuthor: lastCommit.author,
+                        lastCommitEmail: lastCommit.email,
+                        lastCommitDate: lastCommit.date,
+                        lastCommitMessage: lastCommit.message,
+                        totalCommits: history.totalCommits,
+                        primaryAuthor: primaryAuthor?.author,
+                        primaryAuthorEmail: primaryAuthor?.email,
+                        fileOwnerCommits: primaryAuthor?.commitCount,
+                    };
+                }
+            }
             await saveToDB({
                 content,
                 embedding,
@@ -44,6 +78,7 @@ export async function ingest(rootDir, projectName, silent = false) {
                 functionName: chunk.functionName,
                 lineStart: chunk.lineStart,
                 lineEnd: chunk.lineEnd,
+                ...gitMetadata,
             });
         }));
         processedCount += batch.length;
@@ -51,6 +86,35 @@ export async function ingest(rootDir, projectName, silent = false) {
             console.log(`Saved ${processedCount}/${allChunks.length} chunks...`);
         }
     }
-    if (!silent)
+    if (isGitRepo && includeGitHistory && !silent) {
+        console.log("📈 Computing author statistics...");
+        const authorStats = gitHistory.getAuthorStats();
+        console.log(`Found ${authorStats.length} authors`);
+        for (const stats of authorStats) {
+            const ownedFiles = [];
+            fileGitData.forEach((history, filePath) => {
+                if (history?.primaryAuthors[0]?.email === stats.email) {
+                    ownedFiles.push(path.relative(gitHistory.getRepositoryRoot(), filePath));
+                }
+            });
+            await saveAuthorToDB({
+                projectName,
+                author: stats.author,
+                email: stats.email,
+                totalCommits: stats.totalCommits,
+                linesAdded: stats.linesAdded,
+                linesRemoved: stats.linesRemoved,
+                recentActivity: stats.recentActivity,
+                filesOwned: ownedFiles,
+            });
+        }
+        if (!silent)
+            console.log(`✅ Stored stats for ${authorStats.length} contributors`);
+    }
+    if (!silent) {
         console.log(`Done! Processed ${processedCount} chunks from ${files.length} files.`);
+        if (isGitRepo && includeGitHistory) {
+            console.log(`Git history enrichment complete`);
+        }
+    }
 }