@loghead/core 0.1.0

package/README.md

@@ -0,0 +1,201 @@
+# Loggerhead
+
+Loggerhead is a smart log aggregation tool and MCP server. It collects logs from various sources like your Terminal, Docker containers, or Browser, stores them in a database, and makes them searchable for AI assistants (like Claude, Cursor, or Windsurf).
+
+Think of it as a "long-term memory" for your development logs that your AI coding agent can read.
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+1.  **Local Ollama**: [Download here](https://ollama.com/download).
+    - Ensure it is running (`ollama serve`) and accessible at `http://localhost:11434`.
+    - Pull the embedding model: `ollama pull qwen3-embedding:0.6b` (or similar).
+2.  **The Loggerhead Executable**: You can download the latest release or build it yourself (see below).
+
+_(Note: [Deno](https://docs.deno.com/runtime/fundamentals/installation/) is only required if you want to build the project from source.)_
+
+## Setup Guide
+
+Follow these steps to get Loggerhead running on your machine.
+
+### 1. Install the Tool
+
+Download the `loggerhead` binary from the releases page and move it to a directory in your PATH (e.g., `/usr/local/bin`).
+
+**Verify installation:**
+
+```bash
+loggerhead --help
+```
+
+### 2. Initialize the Database
+
+Run this command to set up the database tables (SQLite):
+
+```bash
+loggerhead init
+```
+
+## How to Use
+
+### 1. Start the MCP Server
+
+This is the bridge that allows your AI editor to talk to Loggerhead.
+
+```bash
+loggerhead start
+```
+
+You will see instructions on how to connect your specific AI tool (Claude, Cursor, VS Code, Windsurf) in the output.
+
+**Example for Claude Desktop Config:**
+
+```json
+"loggerhead": {
+  "command": "loggerhead",
+  "args": ["stdio"]
+}
+```
+
+### 2. Create a Project
+
+Organize your logs into projects.
+
+```bash
+loggerhead projects add "My Awesome App"
+```
+
+### 3. Add a Log Stream
+
+A "stream" is a specific source of logs (e.g., your terminal output, or a specific Docker container). You need the Project ID from the previous step (use `loggerhead projects list` to see it).
+
+**Example: Creating a stream for Docker logs**
+
+```bash
+loggerhead streams add docker --project <PROJECT_ID> --name "Backend API" --container my-api-container
+```
+
+**Example: Creating a generic terminal stream**
+
+```bash
+loggerhead streams add terminal --project <PROJECT_ID> --name "Build Logs"
+```
+
+### 4. Ingest Logs
+
+Now, feed logs into the stream you created. You need the Stream ID (use `loggerhead streams list --project <PROJECT_ID>` to find it).
+
+**From Standard Input (Manual):**
+You can pipe any command's output into Loggerhead:
+
+```bash
+echo "Something happened" | loggerhead ingest --stream <STREAM_ID>
+```
+
+Or run a script and capture its output:
+
+```bash
+deno run my_script.ts | loggerhead ingest --stream <STREAM_ID>
+```
+
+### 5. Query Logs (The AI Part)
+
+Your AI assistant can now "call" tools to search these logs. It can ask things like:
+
+- "Show me the recent errors in the Backend API stream."
+- "Find logs related to 'database connection failure'."
+
+You can also check logs manually:
+
+```bash
+loggerhead log list --stream <STREAM_ID>
+```
+
+## Building from Source
+
+If you want to build the `loggerhead` executable yourself (e.g., to contribute or modify it):
+
+1.  Install **Deno** (see Prerequisites).
+2.  Compile the tool into a single executable file in the `build` directory:
+
+```bash
+mkdir -p build
+deno compile --allow-net --allow-read --allow-env --allow-run --allow-write --output build/loggerhead src/main.ts
+```
+
+3.  This will generate the `loggerhead` binary in your `build/` directory. You can add it to your PATH (see Setup Guide) or move it manually:
+
+```bash
+sudo mv build/loggerhead /usr/local/bin/
+```
+
+## Architecture Overview
+
+- **Language:** TypeScript (Deno)
+- **Database:** SQLite with `sqlite-vec` via `@sqliteai/sqlite-wasm` for storing log embeddings.
+- **AI:** Local Ollama running `qwen3-embedding` to understand the semantic meaning of logs.
+- **Protocol:** Model Context Protocol (MCP) for integration with AI agents.
+
+## Sample Apps
+
+We provide sample applications in the `sample_apps` directory to help you test Loggerhead's capabilities.
+
+### 1. CLI Calculator
+
+A simple script that generates random logs and simulates a crash.
+
+**How to test:**
+
+1. Create a project and a stream:
+   ```bash
+   loggerhead projects add "Calculator App"
+   # Copy Project ID
+   loggerhead streams add terminal --project <PROJECT_ID> --name "CLI Output"
+   # Copy Stream ID
+   ```
+2. Run the calculator and pipe logs to Loggerhead:
+   ```bash
+   deno run sample_apps/cli_calculator/main.ts | loggerhead ingest --stream <STREAM_ID>
+   ```
+3. Ask your AI Agent: "Why did the calculator app crash?"
+
+### 2. Docker App
+
+A Python worker process running in Docker that logs tasks and simulates occasional warnings.
+
+**How to test:**
+
+1. Create a stream for Docker:
+   ```bash
+   # Use existing Project ID
+   loggerhead streams add docker --project <PROJECT_ID> --name "Worker Node" --container worker-app
+   # Note the container name "worker-app" matches the --name in docker run below
+   # Copy Stream ID
+   ```
+2. Build and run the container:
+   ```bash
+   cd sample_apps/docker_app
+   docker build -t docker-app .
+   docker run --name worker-app -d docker-app
+   ```
+3. Attach Loggerhead to the container logs:
+   ```bash
+   loggerhead attach --stream <STREAM_ID> --container worker-app
+   ```
+4. Ask your AI Agent: "What tasks is the worker processing?" or "Are there any performance warnings?"
+
+### 3. Browser App
+
+A simple HTML/JS Calculator that logs actions to the browser console. This is designed to be used with a Browser Extension (coming soon) or manual copy-paste testing.
+
+**How to test:**
+
+1. Open `sample_apps/browser_app/index.html` in your browser.
+2. Open Developer Tools (Console).
+3. Perform some calculations (try dividing by zero!).
+4. (Manual) Copy the console logs and save them to a file `logs.txt`.
+5. Ingest the file:
+   ```bash
+   cat logs.txt | loggerhead ingest --stream <STREAM_ID>
+   ```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@loghead/core",
+  "version": "0.1.0",
+  "description": "Smart log aggregation tool and MCP server",
+  "bin": {
+    "loghead": "./bin/loghead"
+  },
+  "files": [
+    "bin"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "scripts": {
+    "postinstall": "echo 'Note: This package contains a prebuilt binary for macOS ARM64.'"
+  },
+  "author": "Onvo AI",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onvo-ai/loggerhead.git"
+  },
+  "bugs": {
+    "url": "https://github.com/onvo-ai/loggerhead/issues"
+  }
+}