@ridit/lens 0.3.7 → 0.3.9

package/CLAUDE.md

@@ -1,50 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Lens is an AI-powered CLI tool for natural language interaction with codebases. It uses React 19 + Ink 6 for terminal UI rendering, Commander.js for CLI parsing, and supports multiple LLM providers (Anthropic, OpenAI, Gemini, Ollama, custom OpenAI-compatible endpoints).
-
-Published as `@ridit/lens` on npm. User config lives in `~/.lens/` (config.json, memory.json, addons/).
-
-## Build Commands
-
-```bash
-bun run build          # Build to dist/index.mjs (adds Node shebang post-build)
-bun install            # Install dependencies
-```
-
-There are no lint or test scripts configured. TypeScript strict mode serves as the primary static analysis tool.
-
-## Architecture
-
-**CLI entry** (`src/index.tsx`): Registers 8 commands via Commander.js, loads built-in tools and user addons, then renders Ink React components.
-
-**Commands** (`src/commands/`): Each command (chat, commit, review, repo, task, timeline, provider, run) is a React component rendered by Ink.
-
-**Components** (`src/components/`): Reusable Ink UI components organized by feature (chat/, provider/, repo/, task/, timeline/, watch/). Chat is the most complex — `ChatRunner.tsx` handles tool execution, permission prompts, and the main interaction loop.
-
-**Tools** (`src/tools/`): Capability implementations (file ops, shell, web fetch, PDF, git, charts, images). Registered at startup via the tool registry.
-
-**Tool Registry** (`src/utils/tools/registry.ts`): Central registry implementing `@ridit/lens-sdk` interface. Supports intent-based filtering — readonly intents never see write/shell/delete tools. Tools are tagged with `TOOL_TAGS.read`, `write`, `delete`, `shell`, `net`.
-
-**Intent Classifier** (`src/utils/intentClassifier.ts`): Regex-based classification of user messages into readonly/mutating/any scopes. Controls which tools appear in the LLM system prompt.
-
-**LLM Abstraction** (`src/utils/ai.ts`): `callModel()` provides a unified interface across all 5 provider types.
-
-**Response Parsing** (`src/utils/chat.ts`): Parses LLM responses for tool calls (XML tags or fenced code blocks), file patches, and clone operations.
-
-**Types** (`src/types/`): Discriminated unions are used throughout — every multi-step UI flow uses `type` + `stage` fields (e.g., `ChatStage`, `ReviewStage`) for exhaustive pattern matching.
-
-**Memory** (`src/utils/memory.ts`): File-based persistence with session-only entries (in-memory, 200 max) and persistent entries (~/.lens/memory.json, global + repo-scoped).
-
-**Addons** (`src/utils/addons/loadAddons.ts`): Plugin system loading tools from `~/.lens/addons/` using `defineTool()` from `@ridit/lens-sdk`.
-
-## Key Patterns
-
-- **Discriminated union state machines**: All commands use `{ type, stage }` unions for multi-step flows. Add new stages by extending the union and handling them exhaustively.
-- **Provider-agnostic LLM calls**: All provider differences are encapsulated in `callModel()` — never call provider SDKs directly from commands/components.
-- **Intent-scoped tool visibility**: The intent classifier determines which tools the LLM can see. Readonly queries hide mutating tools for safety.
-- **Conventional commits**: The project uses conventional commit format (e.g., `feat(chat):`, `chore:`, `fix:`).
-- **Bun as package manager and bundler**: Use `bun` for all dependency and build operations, not npm/yarn.

package/LENS.md

@@ -1,48 +0,0 @@
-# Lens
-> Generated: 2026-03-24T15:21:42.840Z
-
-## Overview
-Lens is an AI-powered CLI tool built with React and Ink that enables natural language interaction with codebases. It provides chat-based exploration, code modification, repository analysis, timeline viewing, and smart commit generation. The tool connects to multiple LLM providers (Anthropic, OpenAI, Gemini, Ollama) and gives AI access to filesystem operations, shell commands, and web tools through a plugin system.
-
-## Architecture
-The architecture follows a command-based structure with Ink components for terminal UI rendering. Each CLI command (chat, commit, review, task, timeline) has a corresponding React component in src/commands/ that handles the specific workflow. The system uses discriminated union types for state management across multi-step processes. Tool execution is managed through a centralized registry system that supports plugins via @ridit/lens-sdk.
-
-## Tooling & Conventions
-- **packageManager**: bun
-- **language**: TypeScript
-- **runtime**: Node.js
-- **bundler**: bun build
-- **framework**: Ink + React
-- **testRunner**: jest (configured but not actively used)
-- **linter**: TypeScript compiler with strict settings
-
-## Important Folders
-- src/commands: Contains CLI command entry points (chat.tsx, commit.tsx, review.tsx, task.tsx, timeline.tsx) that render Ink components
-- src/components: Houses reusable UI components organized by feature (chat/, repo/, timeline/, task/) with associated hooks
-- src/utils: Core utilities including AI integration (ai.ts), configuration management (config.ts), git operations (git.ts), and tool registry (tools/)
-- src/tools: Filesystem, shell, web, and PDF tools that the AI can call through the tool registry system
-
-## Key Files
-- src/index.tsx: Main CLI entry point that sets up Commander.js with all command handlers and loads built-in tools
-- src/utils/tools/registry.ts: Central tool registry implementing the @ridit/lens-sdk interface for tool management and system prompt generation
-- src/utils/ai.ts: Provider-agnostic AI integration with support for Anthropic, OpenAI, Ollama, and custom providers through unified interfaces
-- src/types/chat.ts: Core type definitions for chat messages, tool calls, and state management using discriminated unions
-- src/components/chat/ChatRunner.tsx: Main chat interface component handling tool execution, permission prompts, and clone operations
-
-## Patterns & Idioms
-- Discriminated union state machines (type + stage fields) for multi-step UI flows in every command component (ChatStage, AnalysisStage, etc)
-- Centralized tool registry pattern with plugin system support through @ridit/lens-sdk interface
-- Provider abstraction layer that supports multiple LLM backends with consistent interfaces
-- File-based memory system that persists chat history and context across sessions per repository
-- Ink component composition with hooks for input handling and state management
-
-## Suggestions
-- In src/utils/ai.ts, callModel has no retry logic — adding exponential backoff would improve reliability for ollama which can be slow to start
-- The tool registry in src/utils/tools/registry.ts lacks validation for tool name conflicts during registration
-- src/utils/git.ts uses simple execSync for git operations which could benefit from proper error handling and timeout management
-- The discriminated union types in src/types/chat.ts could use branded types for better type safety
-- The build process in package.json uses a postbuild script to add node shebang which could be replaced with bun's native --target=binary option
-
-<!--lens-json
-{"overview":"Lens is an AI-powered CLI tool built with React and Ink that enables natural language interaction with codebases. It provides chat-based exploration, code modification, repository analysis, timeline viewing, and smart commit generation. The tool connects to multiple LLM providers (Anthropic, OpenAI, Gemini, Ollama) and gives AI access to filesystem operations, shell commands, and web tools through a plugin system.","importantFolders":["src/commands: Contains CLI command entry points (chat.tsx, commit.tsx, review.tsx, task.tsx, timeline.tsx) that render Ink components","src/components: Houses reusable UI components organized by feature (chat/, repo/, timeline/, task/) with associated hooks","src/utils: Core utilities including AI integration (ai.ts), configuration management (config.ts), git operations (git.ts), and tool registry (tools/)","src/tools: Filesystem, shell, web, and PDF tools that the AI can call through the tool registry system"],"tooling":{"packageManager":"bun","language":"TypeScript","runtime":"Node.js","bundler":"bun build","framework":"Ink + React","testRunner":"jest (configured but not actively used)","linter":"TypeScript compiler with strict settings"},"keyFiles":["src/index.tsx: Main CLI entry point that sets up Commander.js with all command handlers and loads built-in tools","src/utils/tools/registry.ts: Central tool registry implementing the @ridit/lens-sdk interface for tool management and system prompt generation","src/utils/ai.ts: Provider-agnostic AI integration with support for Anthropic, OpenAI, Ollama, and custom providers through unified interfaces","src/types/chat.ts: Core type definitions for chat messages, tool calls, and state management using discriminated unions","src/components/chat/ChatRunner.tsx: Main chat interface component handling tool execution, permission prompts, and clone operations"],"patterns":["Discriminated union state machines (type + stage fields) for multi-step UI flows in every command component (ChatStage, AnalysisStage, etc)","Centralized tool registry pattern with plugin system support through @ridit/lens-sdk interface","Provider abstraction layer that supports multiple LLM backends with consistent interfaces","File-based memory system that persists chat history and context across sessions per repository","Ink component composition with hooks for input handling and state management"],"architecture":"The architecture follows a command-based structure with Ink components for terminal UI rendering. Each CLI command (chat, commit, review, task, timeline) has a corresponding React component in src/commands/ that handles the specific workflow. The system uses discriminated union types for state management across multi-step processes. Tool execution is managed through a centralized registry system that supports plugins via @ridit/lens-sdk.","suggestions":["In src/utils/ai.ts, callModel has no retry logic — adding exponential backoff would improve reliability for ollama which can be slow to start","The tool registry in src/utils/tools/registry.ts lacks validation for tool name conflicts during registration","src/utils/git.ts uses simple execSync for git operations which could benefit from proper error handling and timeout management","The discriminated union types in src/types/chat.ts could use branded types for better type safety","The build process in package.json uses a postbuild script to add node shebang which could be replaced with bun's native --target=binary option"],"generatedAt":"2026-03-24T15:21:42.840Z","lastUpdated":"2026-03-24T15:21:42.840Z"}
-lens-json-->

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Ridit
-
-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

@@ -1,93 +0,0 @@
-# Lens
-
-Lens is an AI-powered CLI tool that lets you explore, understand, and modify any codebase through natural language. Built with React and Ink for a rich terminal UI, Lens connects to multiple LLM providers and gives the AI direct access to your filesystem, shell, and the web.
-
-## Features
-
-- **Chat with your codebase** — ask questions, request changes, scaffold new files
-- **Multi-provider support** — Anthropic, OpenAI, Gemini, Ollama, or any OpenAI-compatible API
-- **Tool system** — AI can read/write files, run shell commands, fetch URLs, search the web, clone repos, generate PDFs, and more
-- **Plugin registry** — extend Lens with custom tools via `@ridit/lens-sdk`
-- **Diff preview** — proposed code changes are shown as a diff before applying
-- **Auto-approve mode** — `/auto` skips confirmation for safe read/search tools
-- **Force-all mode** — `/auto --force-all` approves everything including shell and writes
-- **Persistent memory** — Lens remembers project-specific context across sessions
-- **Chat history** — save, load, rename, and delete chat sessions per repo
-- **Smart commits** — generate conventional commit messages from staged changes
-- **Timeline** — browse and explore commit history
-- **Repo analysis** — deep codebase review from a remote URL or local path
-
-## Installation
-
-```bash
-# using bun
-bun add @ridit/lens -g
-
-# using npm
-npm install -g @ridit/lens
-```
-
-## CLI Commands
-
-```
-lens chat                               chat with your codebase
-lens chat -p /path/to/repo              chat in a specific repo
-
-lens review                             AI review of the current directory
-lens review /path/to/repo               AI review of a specific repo
-
-lens repo <url>                         analyze a remote GitHub repository
-
-lens task <text>                        apply a natural language change to the codebase
-lens task <text> -p /path               apply change to a specific repo
-
-lens commit                             generate a smart commit message from staged changes
-lens commit [files...]                  stage specific files and generate a commit message
-lens commit --auto                      stage all changes and commit without confirmation
-lens commit --confirm                   show preview before committing when using --auto
-lens commit --preview                   show the generated message without committing
-lens commit  --push                     push to remote after committing
-
-lens timeline                           explore commit history
-lens timeline -p /path                  explore history of a specific repo
-
-lens run                                Run your dev server. Lens detects and fixes errors automatically
-
-lens provider                           configure AI providers
-```
-
-## Chat Commands
-
-Once inside a `lens chat / vibe` session, use slash commands:
-
-```
-/timeline              browse commit history
-/review                AI review of the current codebase
-/auto                  toggle auto-approve for safe tools (read, search, fetch)
-/auto --force-all      auto-approve ALL tools including shell and writes ⚠️
-/chat list             list saved chat sessions for this repo
-/chat load <name>      load a saved chat session
-/chat rename <name>    rename the current session
-/chat delete <name>    delete a saved session
-/memory list           list stored memories for this repo
-/memory add <text>     add a memory
-/memory delete <id>    delete a memory by ID
-/memory clear          clear all memories for this repo
-/clear history         wipe session memory for this repo
-```
-
-## Supported Providers
-
-- **Anthropic** — Claude models
-- **OpenAI** — GPT models
-- **Gemini** — Google Gemini models
-- **Ollama** — local models (free, fully offline)
-- **Custom** — any OpenAI-compatible API endpoint
-
-## Extending Lens
-
-Custom tools can be built and registered using `[@ridit/lens-sdk](https://www.npmjs.com/package/@ridit/lens-sdk)`.
-
-## License
-
-MIT

package/addons/README.md

@@ -1,55 +0,0 @@
-# Sample addons for Lens
-
-## These addons are generated by lens.
-
-Paste them inside ~/.lens/addons or C:/Users/UserName/.lens/addons
-
-## Addon Format
-
-Addons use `defineTool` from `@ridit/lens-sdk`:
-
-```js
-const { defineTool } = require("@ridit/lens-sdk");
-
-defineTool({
-  name: "tool-name",
-  description: "what it does",
-  safe: false,
-  permissionLabel: "label shown to user",
-  systemPromptEntry: () => `<tool-name>{}</tool-name> — description`,
-  parseInput: (body) => JSON.parse(body.trim() || "{}"),
-  summariseInput: (input) => "summary",
-  execute: async (input, ctx) => {
-    // ctx.repoPath is the current repo
-    return { kind: "text", value: "result" };
-  },
-});
-```
-
-## Available Addons
-
-### clean-cache
-Clears node_modules and bun install cache
-```xml
-<clean-cache>{}</clean-cache>
-```
-
-### generate-readme
-Creates a README.md file for the project
-```xml
-<generate-readme>{}</generate-readme>
-```
-
-### git-stats
-Shows git contributor commit counts
-```xml
-<git-stats></git-stats>
-```
-
-### run-tests
-Runs test suite or specific test files
-```xml
-<run-tests>{}</run-tests> — full suite
-<run-tests>{"file": "src/utils.test.js"}</run-tests> — specific file
-<run-tests>{"command": "node script.js"}</run-tests> — custom command
-```

package/addons/clean-cache.js

@@ -1,48 +0,0 @@
-const { defineTool } = require("@ridit/lens-sdk");
-const { execSync } = require("child_process");
-
-const isWindows = process.platform === "win32";
-
-defineTool({
-  name: "clean-cache",
-  description: "Clean node_modules and bun install cache",
-  safe: false,
-  permissionLabel: "Clean cache and node_modules",
-
-  systemPromptEntry: () =>
-    `<clean-cache>{}</clean-cache> — clean node_modules and bun cache`,
-
-  parseInput: (body) => {
-    const trimmed = body.trim();
-    if (!trimmed || trimmed === "{}") return {};
-    return JSON.parse(trimmed);
-  },
-
-  summariseInput: () => "clean cache",
-
-  execute: async (input, ctx) => {
-    const repoPath = ctx.repoPath;
-
-    try {
-      // Remove node_modules
-      if (isWindows) {
-        execSync("rmdir /s /q node_modules", { cwd: repoPath, stdio: "pipe" });
-      } else {
-        execSync("rm -rf node_modules", { cwd: repoPath, stdio: "pipe" });
-      }
-
-      // Clean bun cache
-      execSync("bun clean", { cwd: repoPath, stdio: "pipe" });
-
-      return {
-        kind: "text",
-        value: "Cache cleaned successfully! node_modules removed and bun cache cleared.",
-      };
-    } catch (err) {
-      return {
-        kind: "error",
-        value: `Failed to clean cache: ${err.message}`,
-      };
-    }
-  },
-});

package/addons/generate-readme.js

@@ -1,67 +0,0 @@
-const { defineTool } = require("@ridit/lens-sdk");
-const fs = require("fs");
-
-const readmeTemplate = `# {name}
-
-{description}
-
-## Getting Started
-
-\`\`\`bash
-bun install
-bun run dev
-\`\`\`
-
-## Features
-
-- Feature one
-- Feature two
-
-## Contributing
-
-Pull requests welcome.`;
-
-defineTool({
-  name: "generate-readme",
-  description: "Generate a README.md file for the project",
-  safe: true,
-  permissionLabel: "Generate README",
-
-  systemPromptEntry: () =>
-    `<generate-readme>{}</generate-readme> — generate a README.md`,
-
-  parseInput: (body) => {
-    const trimmed = body.trim();
-    if (!trimmed || trimmed === "{}") return {};
-    return JSON.parse(trimmed);
-  },
-
-  summariseInput: () => "generate README",
-
-  execute: async (input, ctx) => {
-    const repoPath = ctx.repoPath;
-    const pkgPath = `${repoPath}/package.json`;
-    
-    let name = "Project";
-    let description = "A brief description.";
-    
-    if (fs.existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-        name = pkg.name || name;
-        description = pkg.description || description;
-      } catch {}
-    }
-    
-    const content = readmeTemplate
-      .replace("{name}", name)
-      .replace("{description}", description);
-    
-    fs.writeFileSync(`${repoPath}/README.md`, content);
-    
-    return {
-      kind: "text",
-      value: "README.md generated successfully!"
-    };
-  }
-});

package/addons/git-stats.js

@@ -1,29 +0,0 @@
-const { defineTool } = require("@ridit/lens-sdk");
-const { execSync } = require("child_process");
-
-defineTool({
-  name: "git-stats",
-  description: "Show git contributor stats",
-  safe: true,
-  permissionLabel: "View git stats",
-  systemPromptEntry: () => "<git-stats>{}</git-stats> — show contributor commit counts",
-  parseInput: (body) => JSON.parse(body.trim() || "{}"),
-  summariseInput: () => "git contributor stats",
-  execute: async (input, ctx) => {
-    try {
-      const output = execSync("git shortlog -sn --all", {
-        cwd: ctx.repoPath,
-        stdio: "pipe",
-      }).toString();
-      return {
-        kind: "text",
-        value: output || "No commits found",
-      };
-    } catch (err) {
-      return {
-        kind: "error",
-        value: `Failed to get git stats: ${err.message}`,
-      };
-    }
-  },
-});

package/addons/run-tests.js

@@ -1,127 +0,0 @@
-const { defineTool } = require("@ridit/lens-sdk");
-const { execSync } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-
-defineTool({
-  name: "run-tests",
-  description:
-    "Runs Node.js tests — whole suite or a specific file, auto-detected",
-  safe: false,
-  permissionLabel: "Run tests in the repo",
-
-  systemPromptEntry: () =>
-    `<run-tests>{}</run-tests> — run the full test suite\n` +
-    `<run-tests>{"file": "src/utils.test.js"}</run-tests> — run a specific test file\n` +
-    `<run-tests>{"command": "node script.js"}</run-tests> — run any custom Node.js command`,
-
-  parseInput: (body) => {
-    const trimmed = body.trim();
-    if (!trimmed || trimmed === "{}") return {};
-    return JSON.parse(trimmed);
-  },
-
-  summariseInput: (input) => {
-    if (input.file) return `test file: ${input.file}`;
-    if (input.command) return `command: ${input.command}`;
-    return "full test suite";
-  },
-
-  execute: async (input, ctx) => {
-    const repoPath = ctx.repoPath;
-
-    // Helper: run a shell command and capture output
-    const run = (cmd) => {
-      try {
-        const output = execSync(cmd, {
-          cwd: repoPath,
-          timeout: 60_000,
-          stdio: "pipe",
-        }).toString();
-        return { ok: true, output };
-      } catch (err) {
-        const output = [err.stdout?.toString(), err.stderr?.toString()]
-          .filter(Boolean)
-          .join("\n");
-        return { ok: false, output: output || err.message };
-      }
-    };
-
-    // --- Custom command ---
-    if (input.command) {
-      const result = run(input.command);
-      return {
-        kind: result.ok ? "text" : "error",
-        value: result.output || "(no output)",
-      };
-    }
-
-    // --- Detect test runner from package.json ---
-    const pkgPath = path.join(repoPath, "package.json");
-    let pkg = {};
-    if (fs.existsSync(pkgPath)) {
-      try {
-        pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-      } catch {}
-    }
-
-    const hasScript = (name) => !!pkg.scripts?.[name];
-    const hasDep = (name) =>
-      !!(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
-
-    const detectRunner = () => {
-      if (hasScript("test")) return "npm test";
-      if (hasDep("jest")) return "npx jest";
-      if (hasDep("vitest")) return "npx vitest run";
-      if (hasDep("mocha")) return "npx mocha";
-      if (hasDep("tap")) return "npx tap";
-      return null;
-    };
-
-    // --- Specific file ---
-    if (input.file) {
-      const filePath = path.resolve(repoPath, input.file);
-
-      if (!fs.existsSync(filePath)) {
-        return { kind: "error", value: `File not found: ${input.file}` };
-      }
-
-      let cmd;
-      if (
-        hasDep("jest") ||
-        (hasScript("test") && pkg.scripts.test?.includes("jest"))
-      ) {
-        cmd = `npx jest ${input.file} --no-coverage`;
-      } else if (hasDep("vitest")) {
-        cmd = `npx vitest run ${input.file}`;
-      } else if (hasDep("mocha")) {
-        cmd = `npx mocha ${input.file}`;
-      } else {
-        // Fallback: just run it with Node
-        cmd = `node ${input.file}`;
-      }
-
-      const result = run(cmd);
-      return {
-        kind: result.ok ? "text" : "error",
-        value: result.output || "(no output)",
-      };
-    }
-
-    // --- Full test suite ---
-    const suiteCmd = detectRunner();
-    if (!suiteCmd) {
-      return {
-        kind: "error",
-        value:
-          "Could not detect a test runner. No 'test' script in package.json and no known test framework (jest, vitest, mocha, tap) found in dependencies.",
-      };
-    }
-
-    const result = run(suiteCmd);
-    return {
-      kind: result.ok ? "text" : "error",
-      value: result.output || "(no output)",
-    };
-  },
-});