@standardbeagle/lci 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Standard Beagle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# LCI - Lightning Code Index
+
+Lightning-fast code indexing and search for AI assistants.
+
+[![CI](https://github.com/standardbeagle/lci/actions/workflows/ci.yml/badge.svg)](https://github.com/standardbeagle/lci/actions/workflows/ci.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/standardbeagle/lci)](https://goreportcard.com/report/github.com/standardbeagle/lci)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Sub-millisecond search**: Trigram-based indexing with <5ms search guarantee
+- **Multi-language support**: Go, TypeScript, JavaScript, Python, Rust, C#, PHP, and more
+- **MCP integration**: Model Context Protocol server for AI assistant integration
+- **Semantic search**: Natural language queries with intelligent matching
+- **Call graph analysis**: Track function calls, references, and dependencies
+- **Semantic annotations**: `@lci:` vocabulary for marking up code with metadata
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g @standardbeagle/lci
+```
+
+### pip
+
+```bash
+pip install lightning-code-index
+```
+
+### Homebrew (coming soon)
+
+```bash
+brew install standardbeagle/tap/lci
+```
+
+### From Source
+
+```bash
+go install github.com/standardbeagle/lci/cmd/lci@latest
+```
+
+### From Releases
+
+Download pre-built binaries from [GitHub Releases](https://github.com/standardbeagle/lci/releases).
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Index and search in current directory
+lci search "handleRequest"
+
+# Find symbol definitions
+lci def UserService
+
+# Find all references to a symbol
+lci refs CreateUser
+
+# Display function call hierarchy
+lci tree main
+
+# Fast grep-style search
+lci grep "TODO|FIXME"
+
+# List files that would be indexed
+lci list
+```
+
+### MCP Server
+
+Start the MCP server for AI assistant integration:
+
+```bash
+lci mcp
+```
+
+#### Claude Code Integration
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "lci": {
+    "command": "lci",
+    "args": ["mcp"],
+    "env": {}
+  }
+}
+```
+
+## Configuration
+
+Create `.lci.kdl` in your project root:
+
+```kdl
+project {
+    name "my-project"
+    root "."
+}
+
+index {
+    include "**/*.go" "**/*.ts" "**/*.py"
+    exclude "**/node_modules/**" "**/vendor/**"
+}
+
+search {
+    max-results 100
+    context-lines 3
+}
+```
+
+## MCP Tools
+
+When running as an MCP server, LCI exposes these tools:
+
+| Tool | Description |
+|------|-------------|
+| `search` | Semantic code search with fuzzy matching |
+| `get_context` | Get detailed context for a code symbol |
+| `find_files` | Fast file path search with glob patterns |
+| `code_insight` | Codebase intelligence and analysis |
+| `context` | Save/load code context manifests |
+| `semantic_annotations` | Query @lci: semantic labels |
+| `side_effects` | Analyze function purity and side effects |
+
+## Semantic Annotations
+
+Mark up your code with `@lci:` annotations for enhanced AI understanding:
+
+```go
+// @lci:risk[high] @lci:public-api
+// @lci:requires[env:DATABASE_URL]
+func HandleUserLogin(w http.ResponseWriter, r *http.Request) {
+    // ...
+}
+
+// @lci:purpose[Validate user credentials against database]
+// @lci:must[Return error for invalid credentials]
+func ValidateCredentials(username, password string) error {
+    // ...
+}
+```
+
+### Annotation Categories
+
+- **Risk & Safety**: `@lci:risk[low|medium|high|critical]`, `@lci:safe-zone`, `@lci:stability`
+- **Dependencies**: `@lci:requires[env:VAR]`, `@lci:requires[db:table]`, `@lci:requires[service:name]`
+- **Conventions**: `@lci:convention[pattern]`, `@lci:idiom[name]`, `@lci:template[name]`
+- **Contracts**: `@lci:must[behavior]`, `@lci:must-not[behavior]`, `@lci:invariant[condition]`
+- **Purpose**: `@lci:purpose[description]`, `@lci:domain[area]`, `@lci:owner[team]`
+
+## Architecture
+
+```
+lci/
+├── cmd/lci/          # CLI entry point
+├── internal/
+│   ├── core/         # Trigram index, symbol store, reference tracker
+│   ├── parser/       # Tree-sitter based multi-language parsing
+│   ├── search/       # Search engine and scoring
+│   ├── indexing/     # Master index and pipeline
+│   ├── mcp/          # MCP server and tools
+│   └── analysis/     # Code analysis and metrics
+└── pkg/              # Public API
+```
+
+## Performance
+
+LCI is designed for speed:
+
+- **Indexing**: <5s for typical projects (<10k files)
+- **Search**: <5ms for most queries
+- **Memory**: <100MB for typical web projects
+- **Startup**: Near-instant with persistent index
+
+## Development
+
+```bash
+# Run tests
+go test ./...
+
+# Build
+go build ./cmd/lci
+
+# Run with race detector
+go test -race ./...
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please read the contributing guidelines before submitting PRs.

package/bin/lci.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+function getBinaryPath() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  let binaryName;
+
+  if (platform === "darwin") {
+    if (arch === "x64") {
+      binaryName = "lci_darwin_amd64";
+    } else if (arch === "arm64") {
+      binaryName = "lci_darwin_arm64";
+    }
+  } else if (platform === "linux") {
+    if (arch === "x64") {
+      binaryName = "lci_linux_amd64";
+    } else if (arch === "arm64") {
+      binaryName = "lci_linux_arm64";
+    }
+  } else if (platform === "win32") {
+    if (arch === "x64") {
+      binaryName = "lci_windows_amd64.exe";
+    }
+  }
+
+  if (!binaryName) {
+    console.error(`Unsupported platform: ${platform} ${arch}`);
+    console.error("Supported platforms: darwin (x64, arm64), linux (x64, arm64), win32 (x64)");
+    process.exit(1);
+  }
+
+  const binaryPath = path.join(__dirname, "..", "binaries", binaryName);
+
+  if (!fs.existsSync(binaryPath)) {
+    console.error(`Binary not found: ${binaryPath}`);
+    console.error("This may be a development installation.");
+    console.error("Please install from npm: npm install -g @standardbeagle/lci");
+    process.exit(1);
+  }
+
+  return binaryPath;
+}
+
+function main() {
+  const binaryPath = getBinaryPath();
+  const args = process.argv.slice(2);
+
+  try {
+    execFileSync(binaryPath, args, {
+      stdio: "inherit",
+      env: process.env,
+    });
+  } catch (error) {
+    if (error.status !== undefined) {
+      process.exit(error.status);
+    }
+    console.error(`Failed to execute binary: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@standardbeagle/lci",
+  "version": "0.1.0",
+  "description": "Lightning Code Index - Sub-millisecond semantic code search and analysis",
+  "keywords": [
+    "code-search",
+    "semantic-search",
+    "code-analysis",
+    "mcp",
+    "indexing",
+    "cli"
+  ],
+  "homepage": "https://github.com/standardbeagle/lci",
+  "bugs": {
+    "url": "https://github.com/standardbeagle/lci/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/standardbeagle/lci.git"
+  },
+  "license": "MIT",
+  "author": "Standard Beagle",
+  "bin": {
+    "lci": "bin/lci.js"
+  },
+  "files": [
+    "bin/",
+    "binaries/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}