@ridit/lens 0.3.0 → 0.3.2

package/src/prompts/system.ts

@@ -26,85 +26,64 @@ They are stripped before display — the user will not see the raw tags.
 ### memory-delete — delete a memory by its ID (shown in brackets like [abc123])
 <memory-delete>abc123</memory-delete>
 
-Use memory-add when:
-- The user explicitly asks you to remember something ("remember that...", "don't forget...")
-- You learn something project-specific that would be useful in future sessions
-  (e.g. preferred patterns, architecture decisions, known gotchas, user preferences)
-
-Use memory-delete when:
-- The user asks you to forget something
-- A memory is outdated or wrong and you are replacing it with a new one
-
-You may emit multiple memory operations in a single response alongside normal content.
+Use memory-add when the user asks you to remember something, or when you learn something project-specific that would be useful in future sessions.
+Use memory-delete when the user asks you to forget something or a memory is outdated.
 
 ## RULES
 
-1. When you need to use a tool, output ONLY the XML tag — nothing before or after it in that response
-2. ONE tool per response — emit the tag, then stop completely
-3. After the user approves and you get the result, continue your analysis in the next response
-4. NEVER print a URL, command, filename, or JSON blob as plain text when you should be using a tool
-5. NEVER say "I'll fetch" / "run this command" / "here's the write-file" — just emit the tag
-6. NEVER use shell to run git clone — always use the clone tag instead
-7. NEVER use shell to list files or folders (no ls, dir, find, git ls-files, tree) — ALWAYS use read-folder instead
-8. NEVER use shell to read a file (no cat, type, Get-Content) — ALWAYS use read-file instead
-9. NEVER use shell grep, findstr, or Select-String to search file contents — ALWAYS use grep instead
-10. shell is ONLY for running code, installing packages, building, testing — not for filesystem inspection
-11. write-file content field must be the COMPLETE file content, never empty or placeholder
-12. After a write-file succeeds, do NOT repeat it — trust the result and move on
-13. After a write-file succeeds, tell the user it is done immediately — do NOT auto-read the file back to verify
-13a. NEVER read a file you just wrote — the write output confirms success. Reading back is a wasted tool call and will confuse you.
-14. NEVER apologize and redo a tool call you already made — if write-file or shell ran and returned a result, it worked, do not run it again
-15. NEVER say "I made a mistake" and repeat the same tool — one attempt is enough, trust the output
-16. NEVER second-guess yourself mid-response — commit to your answer
-17. If a read-folder or read-file returns "not found", accept it and move on — do NOT retry the same path
-18. If you have already retrieved a result for a path in this conversation, do NOT request it again — use the result you already have
-19. Every shell command runs from the repo root — \`cd\` has NO persistent effect. NEVER use \`cd\` alone. Use full paths or combine with && e.g. \`cd list && bun run index.ts\`
-20. write-file paths are relative to the repo root — if creating files in a subfolder write the full relative path e.g. \`list/src/index.tsx\` NOT \`src/index.tsx\`
-21. When scaffolding a new project in a subfolder, ALL write-file paths must start with that subfolder name e.g. \`list/package.json\`, \`list/src/index.tsx\`
-22. When scaffolding a multi-file project, after each write-file succeeds, immediately proceed to writing the NEXT file — NEVER rewrite a file you already wrote in this session. Each file is written ONCE and ONLY ONCE.
-23. For JSX/TSX files always use \`.tsx\` extension and include \`/** @jsxImportSource react */\` or ensure tsconfig has jsx set — bun needs this to parse JSX
-24. When explaining how to use a tool in text, use [tag] bracket notation or a fenced code block — NEVER emit a real XML tool tag as part of an explanation or example
-25. NEVER read files, list folders, or run tools that were not asked for in the current user message
-26. NEVER use markdown formatting in plain text responses — no **bold**, no *italics*, no # headings, no bullet points with -, *, or +, no numbered lists, no backtick inline code. Write in plain prose. Only use fenced \`\`\` code blocks when showing actual code.
-27. When the user asks you to CREATE a new file (e.g. "write a README", "create a config", "add a license", "this codebase doesn't have X"), write it IMMEDIATELY — do NOT read first, even if a stub exists.
-28. When a tool result is returned, your response must be directly based on that result — never invent or hallucinate content unrelated to the tool output.
-29. When scaffolding multiple files, emit ONE write-file tag per response — wait for each result before emitting the next. Never chain multiple write-file tags in a single response when file content is complex (more than 20 lines).
-
-## SCAFFOLDING — CHAINING WRITE-FILE CALLS
-
-When creating multiple files (e.g. scaffolding a project or creating 10 files), emit ALL of them
-in a single response by chaining the tags back-to-back with no text between them:
+1. ONE tool per response — emit the XML tag, then stop. Never chain tools in one response except when scaffolding (see below).
+2. NEVER call a tool more than once for the same path in a session. If write-file or shell returned a result, it succeeded. Move on immediately.
+3. NEVER write the same file twice in one session. One write per file, period. If you already wrote it, it is done.
+4. shell is ONLY for running code, installing packages, building, and testing. NEVER use shell to inspect the filesystem or read files — use read-file, read-folder, or grep instead.
+5. write-file content must be the COMPLETE file content, never a placeholder or partial.
+6. NEVER read a file you just wrote. The write output confirms success.
+7. NEVER apologize and redo a tool call — one attempt is enough, trust the output.
+8. NEVER use shell to run git clone — use the clone tag instead.
+9. When the user asks you to CREATE a new file, write it immediately — do NOT read first.
+10. When the user asks you to MODIFY or FIX an existing file, read it first, then write the complete updated version ONCE.
+11. When fixing multiple files, use read-files to read ALL of them first, then write each one ONCE sequentially — never rewrite a file already written this session.
+12. If a read-folder or read-file returns not found, accept it and move on — do NOT retry the same path.
+13. Every shell command runs from the repo root — cd has no persistent effect. Use full paths or combine with && e.g. cd myapp && bun run index.ts
+14. write-file paths are relative to the repo root — use full relative paths e.g. myapp/src/index.tsx not src/index.tsx
+15. When explaining how to use a tool in text, use [tag] bracket notation — NEVER emit a real XML tool tag as part of an explanation.
+16. NEVER use markdown formatting in plain text responses — no bold, no headings, no bullet points. Only use fenced code blocks when showing actual code.
+17. When scaffolding multiple files, emit ONE write-file tag per response and wait for the result before writing the next file.
+
+## ADDON FORMAT
+
+All addons use defineTool from @ridit/lens-sdk. The ONLY correct format is:
+
+\`\`\`js
+const { defineTool } = require("@ridit/lens-sdk");
+const { execSync } = require("child_process");
+
+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 path
+    // use execSync from child_process for shell commands, NOT ctx.tools.shell
+    return { kind: "text", value: "result" };
+  },
+});
+\`\`\`
+
+NEVER use module.exports, registerTool, ctx.tools.shell, or any other format. See addons/run-tests.js for a full working example.
+
+## SCAFFOLDING
+
+When creating multiple files, emit ONE write-file per response and wait for each result:
 
 <write-file>
-{"path": "test/file1.txt", "content": "File 1 content"}
+{"path": "myapp/package.json", "content": "..."}
 </write-file>
-<write-file>
-{"path": "test/file2.txt", "content": "File 2 content"}
-</write-file>
-<write-file>
-{"path": "test/file3.txt", "content": "File 3 content"}
-</write-file>
-
-The system processes each tag sequentially and automatically continues to the next one.
-Do NOT wait for a user message between files — emit all tags at once.
-
-## WHEN TO READ BEFORE WRITING
-
-Only read a file before writing if ALL of these are true:
-- The file already exists AND has content you need to preserve
-- The user explicitly asked you to modify, edit, or update it (not create it)
-- You do not already have the file content in this conversation
 
-Never read before writing when:
-- The user asked you to create, write, or add a new file
-- The file is empty, missing, or a stub
-- You already read it earlier in this conversation
-
-When modifying an existing file:
-1. Use read-file on the exact file first
-2. Preserve ALL existing content — do not remove anything that was not part of the request
-3. Your write-file must contain EVERYTHING the original had, PLUS your additions
-4. NEVER produce a file shorter than the original unless explicitly asked to delete things
+Wait for result, then emit the next file. Never chain write-file tags when content is complex.
 
 ## CODEBASE
 
@@ -115,57 +94,57 @@ ${memorySummary}`;
 
 const BUILTIN_TOOLS_SECTION = `## TOOLS
 
-You have exactly thirteen tools. To use a tool you MUST wrap it in the exact XML tags shown below — no other format will work.
+You have exactly fourteen tools. Use ONLY the XML tags shown below.
 
 ### 1. fetch — load a URL
 <fetch>https://example.com</fetch>
 
-### 2. shell — run a terminal command
+### 2. shell — run a terminal command (NOT for filesystem inspection)
 <shell>node -v</shell>
 
-### 3. read-file — read a file from the repo
+### 3. read-file — read a single file from the repo
 <read-file>src/foo.ts</read-file>
 
-### 4. read-folder — list contents of a folder (files + subfolders, one level deep)
+### 4. read-files — read multiple files at once
+<read-files>
+["src/foo.ts", "src/bar.ts"]
+</read-files>
+
+### 5. read-folder — list contents of a folder (one level deep)
 <read-folder>src/components</read-folder>
 
-### 5. grep — search for a pattern across files in the repo (cross-platform, no shell needed)
+### 6. grep — search for a pattern across files
 <grep>
 {"pattern": "ChatRunner", "glob": "src/**/*.tsx"}
 </grep>
 
-### 6. write-file — create or overwrite a file
+### 7. write-file — create or overwrite a file (COMPLETE content only)
 <write-file>
 {"path": "data/output.csv", "content": "col1,col2\\nval1,val2"}
 </write-file>
 
-### 7. delete-file — permanently delete a single file
+### 8. delete-file — permanently delete a single file
 <delete-file>src/old-component.tsx</delete-file>
 
-### 8. delete-folder — permanently delete a folder and all its contents
+### 9. delete-folder — permanently delete a folder and all its contents
 <delete-folder>src/legacy</delete-folder>
 
-### 9. open-url — open a URL in the user's default browser
+### 10. open-url — open a URL in the user's default browser
 <open-url>https://github.com/owner/repo</open-url>
 
-### 10. generate-pdf — generate a PDF file from markdown-style content
+### 11. generate-pdf — generate a PDF from markdown-style content
 <generate-pdf>
-{"path": "output/report.pdf", "content": "# Title\\n\\nSome body text.\\n\\n## Section\\n\\nMore content."}
+{"path": "output/report.pdf", "content": "# Title\\n\\nBody text."}
 </generate-pdf>
 
-### 11. search — search the internet for anything you are unsure about
-<search>how to use React useEffect cleanup function</search>
+### 12. search — search the internet
+<search>how to use React useEffect cleanup</search>
 
-### 12. clone — clone a GitHub repo so you can explore and discuss it
+### 13. clone — clone a GitHub repo
 <clone>https://github.com/owner/repo</clone>
 
-### 13. changes — propose code edits (shown as a diff for user approval)
+### 14. changes — propose code edits shown as a diff for user approval
 <changes>
 {"summary": "what changed and why", "patches": [{"path": "src/foo.ts", "content": "COMPLETE file content", "isNew": false}]}
 </changes>
-
-### 14. read-files — read multiple files from the repo at once
-<read-files>
-["src/foo.ts", "src/bar.ts"]
-</read-files>
 `;

package/src/utils/addons/loadAddons.ts

@@ -1,6 +1,7 @@
 import path from "path";
 import os from "os";
 import { existsSync, readdirSync } from "fs";
+import { pathToFileURL } from "url";
 
 const ADDONS_DIR = path.join(os.homedir(), ".lens", "addons");
 
@@ -18,9 +19,10 @@ export async function loadAddons(): Promise<void> {
     if (!file) return;
 
     const fullPath = path.join(ADDONS_DIR, file);
+    const fileUrl = pathToFileURL(fullPath).href;
     const isLast = i === files.length - 1;
     try {
-      await import(fullPath);
+      await import(fileUrl);
       console.log(`[addons] loaded: ${file}${isLast ? "\n" : ""}`);
     } catch (err) {
       console.error(

package/src/utils/tools/builtins.ts

@@ -17,6 +17,8 @@ import {
   convertImageTool,
 } from "../../tools";
 
+const cleanBody = (body: string) => body.trim().replace(/\\/g, "/");
+
 export const fetchTool: Tool<string> = {
   name: "fetch",
   description: "load a URL",
@@ -61,7 +63,7 @@ export const readFileTool: Tool<string> = {
   permissionLabel: "read",
   systemPromptEntry: (i) =>
     `### ${i}. read-file — read a file from the repo\n<read-file>src/foo.ts</read-file>`,
-  parseInput: (body) => body || null,
+  parseInput: (body) => cleanBody(body) || null,
   summariseInput: (p) => p,
   execute: (filePath, ctx) => ({
     kind: "text",
@@ -76,7 +78,7 @@ export const readFolderTool: Tool<string> = {
   permissionLabel: "folder",
   systemPromptEntry: (i) =>
     `### ${i}. read-folder — list contents of a folder (files + subfolders, one level deep)\n<read-folder>src/components</read-folder>`,
-  parseInput: (body) => body || null,
+  parseInput: (body) => cleanBody(body) || null,
   summariseInput: (p) => p,
   execute: (folderPath, ctx) => ({
     kind: "text",
@@ -98,7 +100,10 @@ export const grepTool: Tool<GrepInput> = {
     `### ${i}. grep — search for a pattern across files in the repo (cross-platform, no shell needed)\n<grep>\n{"pattern": "ChatRunner", "glob": "src/**/*.tsx"}\n</grep>`,
   parseInput: (body) => {
     try {
-      const parsed = JSON.parse(body) as { pattern: string; glob?: string };
+      const parsed = JSON.parse(cleanBody(body)) as {
+        pattern: string;
+        glob?: string;
+      };
       return { pattern: parsed.pattern, glob: parsed.glob ?? "**/*" };
     } catch {
       return { pattern: body, glob: "**/*" };
@@ -127,7 +132,7 @@ export const writeFileTool: Tool<WriteFileInput> = {
     try {
       const parsed = JSON.parse(body) as { path: string; content: string };
       if (!parsed.path) return null;
-      return parsed;
+      return { ...parsed, path: parsed.path.replace(/\\/g, "/") };
     } catch {
       return null;
     }
@@ -146,7 +151,7 @@ export const deleteFileTool: Tool<string> = {
   permissionLabel: "delete",
   systemPromptEntry: (i) =>
     `### ${i}. delete-file — permanently delete a single file\n<delete-file>src/old-component.tsx</delete-file>`,
-  parseInput: (body) => body || null,
+  parseInput: (body) => cleanBody(body) || null,
   summariseInput: (p) => p,
   execute: (filePath, ctx) => ({
     kind: "text",
@@ -161,7 +166,7 @@ export const deleteFolderTool: Tool<string> = {
   permissionLabel: "delete folder",
   systemPromptEntry: (i) =>
     `### ${i}. delete-folder — permanently delete a folder and all its contents\n<delete-folder>src/legacy</delete-folder>`,
-  parseInput: (body) => body || null,
+  parseInput: (body) => cleanBody(body) || null,
   summariseInput: (p) => p,
   execute: (folderPath, ctx) => ({
     kind: "text",
@@ -195,7 +200,7 @@ export const generatePdfTool: Tool<GeneratePdfInput> = {
     `### ${i}. generate-pdf — generate a PDF file from markdown-style content\n<generate-pdf>\n{"path": "output/report.pdf", "content": "# Title\\n\\nSome body text."}\n</generate-pdf>`,
   parseInput: (body) => {
     try {
-      const parsed = JSON.parse(body) as {
+      const parsed = JSON.parse(cleanBody(body)) as {
         path?: string;
         filePath?: string;
         content?: string;
@@ -266,7 +271,7 @@ export const changesTool: Tool<ChangesInput> = {
     `### ${i}. changes — propose code edits (shown as a diff for user approval)\n<changes>\n{"summary": "what changed and why", "patches": [{"path": "src/foo.ts", "content": "COMPLETE file content", "isNew": false}]}\n</changes>`,
   parseInput: (body) => {
     try {
-      return JSON.parse(body) as ChangesInput;
+      return JSON.parse(cleanBody(body)) as ChangesInput;
     } catch {
       return null;
     }
@@ -291,7 +296,7 @@ export const readFilesTool: Tool<ReadFilesInput> = {
     `### ${i}. read-files — read multiple files from the repo at once\n<read-files>\n["src/foo.ts", "src/bar.ts"]\n</read-files>`,
   parseInput: (body) => {
     try {
-      const parsed = JSON.parse(body) as string[];
+      const parsed = JSON.parse(cleanBody(body)) as string[];
       if (!Array.isArray(parsed) || parsed.length === 0) return null;
       return { paths: parsed };
     } catch {

package/LENS.md

@@ -1,32 +0,0 @@
-# Lens Analysis
-> Generated: 2026-03-21T11:15:38.543Z
-
-## Overview
-Lens is a CLI tool built with React components rendered in the terminal via Ink, designed to help developers understand, navigate, and interact with codebases using AI-powered analysis. The tool provides repository analysis, AI-powered insights, interactive chat, code review, timeline exploration, and task automation capabilities. Key components include ChatRunner for interactive conversations, RepoAnalysis for repository examination, and various command handlers like ReviewCommand and TaskCommand. The project uses Bun as a build tool and runtime, with Commander.js for CLI structure and TypeScript throughout for type safety.
-
-## Important Folders
-- src/components: Contains core UI components like ChatRunner (handles interactive chat), RepoAnalysis (analyzes repositories), DiffViewer (shows code differences), and ProviderPicker (selects AI providers). These components use Ink for terminal rendering and provide the main user interface.
-- src/commands: Implements all CLI commands including repo (analyze remote repositories), review (local codebase analysis), task (apply natural language changes), chat (interactive conversation), timeline (commit history exploration), and commit (smart commit message generation).
-- src/utils: Contains utility functions for AI integration (ai.ts), chat processing (chat.ts), configuration management (config.ts), file operations (files.ts), git operations (git.ts), memory management (memory.ts), and thinking animations (thinking.tsx).
-- src/tools: Provides various tool implementations including files (file operations), shell (command execution), web (URL fetching), pdf (PDF generation), and git (version control operations). These tools are used throughout the chat functionality.
-
-## Missing Configs
-- ESLint configuration: The project uses TypeScript but lacks an ESLint config file (.eslintrc.js or eslint.config.js) for code quality enforcement
-- Testing setup: No test framework configuration (Jest/Vitest) or test files found, which is important for a developer tool of this complexity
-- GitHub Actions CI/CD: Missing workflow files for automated testing and deployment, which would help maintain quality for a CLI tool
-
-## Security Issues
-- In src/utils/chat.ts: The parseResponse function uses regex-based XML parsing which could be vulnerable to injection attacks if malformed responses are processed
-- In src/utils/repo.ts: The cloneRepo function uses exec() with user-provided URLs without proper sanitization, potentially allowing command injection
-- In multiple files: API keys and sensitive information are handled without encryption in config files stored in ~/.lens directory
-
-## Suggestions
-- In src/utils/chat.ts: Replace regex-based XML parsing with a proper XML parser library to prevent injection vulnerabilities and improve reliability
-- In src/utils/repo.ts: Use execFile with proper argument sanitization instead of exec() for git operations to prevent command injection attacks
-- In src/utils/config.ts: Implement encryption for storing API keys in the config file rather than plaintext storage
-- In src/components/chat/ChatRunner.tsx: Add pagination or virtualization for long chat histories to improve performance with many messages
-- In package.json: Add linting and testing scripts to establish better code quality practices for the project
-
-<!--lens-json
-{"overview":"Lens is a CLI tool built with React components rendered in the terminal via Ink, designed to help developers understand, navigate, and interact with codebases using AI-powered analysis. The tool provides repository analysis, AI-powered insights, interactive chat, code review, timeline exploration, and task automation capabilities. Key components include ChatRunner for interactive conversations, RepoAnalysis for repository examination, and various command handlers like ReviewCommand and TaskCommand. The project uses Bun as a build tool and runtime, with Commander.js for CLI structure and TypeScript throughout for type safety.","importantFolders":["src/components: Contains core UI components like ChatRunner (handles interactive chat), RepoAnalysis (analyzes repositories), DiffViewer (shows code differences), and ProviderPicker (selects AI providers). These components use Ink for terminal rendering and provide the main user interface.","src/commands: Implements all CLI commands including repo (analyze remote repositories), review (local codebase analysis), task (apply natural language changes), chat (interactive conversation), timeline (commit history exploration), and commit (smart commit message generation).","src/utils: Contains utility functions for AI integration (ai.ts), chat processing (chat.ts), configuration management (config.ts), file operations (files.ts), git operations (git.ts), memory management (memory.ts), and thinking animations (thinking.tsx).","src/tools: Provides various tool implementations including files (file operations), shell (command execution), web (URL fetching), pdf (PDF generation), and git (version control operations). These tools are used throughout the chat functionality."],"missingConfigs":["ESLint configuration: The project uses TypeScript but lacks an ESLint config file (.eslintrc.js or eslint.config.js) for code quality enforcement","Testing setup: No test framework configuration (Jest/Vitest) or test files found, which is important for a developer tool of this complexity","GitHub Actions CI/CD: Missing workflow files for automated testing and deployment, which would help maintain quality for a CLI tool"],"securityIssues":["In src/utils/chat.ts: The parseResponse function uses regex-based XML parsing which could be vulnerable to injection attacks if malformed responses are processed","In src/utils/repo.ts: The cloneRepo function uses exec() with user-provided URLs without proper sanitization, potentially allowing command injection","In multiple files: API keys and sensitive information are handled without encryption in config files stored in ~/.lens directory"],"suggestions":["In src/utils/chat.ts: Replace regex-based XML parsing with a proper XML parser library to prevent injection vulnerabilities and improve reliability","In src/utils/repo.ts: Use execFile with proper argument sanitization instead of exec() for git operations to prevent command injection attacks","In src/utils/config.ts: Implement encryption for storing API keys in the config file rather than plaintext storage","In src/components/chat/ChatRunner.tsx: Add pagination or virtualization for long chat histories to improve performance with many messages","In package.json: Add linting and testing scripts to establish better code quality practices for the project"],"generatedAt":"2026-03-21T11:15:38.543Z"}
-lens-json-->