@rahul05ranjan/dhruv-cli 1.4.6 → 1.6.0

package/README.md

@@ -1,61 +1,166 @@
-# Dhruv CLI
-
-[📦 View on npm](https://www.npmjs.com/package/@rahul05ranjan/dhruv-cli)
-[📖 View Documentation on GitHub Pages](https://rahul05ranjan.github.io/dhruv-cli/)
-
-AI-powered CLI assistant for developers using Ollama.
-
-## 🚀 Features
-- Smart command suggestions: `suggest`, `explain`, `fix`
-- Project context detection (Node, React, Python, etc.)
-- Code review: `review <fileOrDir>`
-- Code optimization: `optimize <file>`
-- Security analysis: `security-check [fileOrDir]`
-- Test/code generation: `generate <type> <target>`
-- Interactive setup: `init`
-- Streaming AI responses in terminal
-- Syntax highlighting for code output
-- Progress bars for long operations
-- Plugin system: drop ESM modules in `plugins/`
-- Autocomplete: `completion [shell]`
-- Offline-first with local Ollama models
-- Beautiful, modern CLI UX
-
-## 🛠️ Installation
+<p align="center">
+  <a href="https://github.com/rahul05ranjan/dhruv-cli">
+    <strong>⚡ Dhruv CLI</strong>
+  </a>
+</p>
+
+<p align="center">
+  A local-first AI command center for your terminal.
+</p>
+
+<p align="center">
+  Ask better questions. Understand unfamiliar code. Ship with confidence.
+</p>
+
+<p align="center">
+  <a href="https://rahul05ranjan.github.io/dhruv-cli/">Website</a>
+  ·
+  <a href="https://www.npmjs.com/package/@rahul05ranjan/dhruv-cli">npm</a>
+  ·
+  <a href="https://github.com/rahul05ranjan/dhruv-cli/issues">Issues</a>
+  ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/rahul05ranjan/dhruv-cli/actions/workflows/deploy.yml"><img src="https://github.com/rahul05ranjan/dhruv-cli/actions/workflows/deploy.yml/badge.svg" alt="Deployment status"></a>
+  <a href="https://www.npmjs.com/package/@rahul05ranjan/dhruv-cli"><img src="https://img.shields.io/npm/v/%40rahul05ranjan%2Fdhruv-cli?style=flat-square&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@rahul05ranjan/dhruv-cli"><img src="https://img.shields.io/npm/dm/%40rahul05ranjan%2Fdhruv-cli?style=flat-square&label=downloads" alt="npm downloads"></a>
+  <img src="https://img.shields.io/github/license/rahul05ranjan/dhruv-cli?style=flat-square" alt="MIT license">
+</p>
+
+<p align="center">
+  <img src="docs/dhruv-cli-preview.svg" alt="Dhruv CLI terminal preview" width="760">
+</p>
+
+## Why Dhruv?
+
+Dhruv brings a focused AI toolkit into the terminal, powered by local Ollama models. It keeps your workflow close to the codebase, works without a hosted AI account, and turns everyday developer questions into fast, actionable output.
+
+<table>
+  <tr>
+    <td width="33%"><strong>✦ Think with you</strong><br>Explain concepts, suggest approaches, and turn errors into clear next steps.</td>
+    <td width="33%"><strong>◈ Inspect deeply</strong><br>Review code, optimize files, and scan projects for common security risks.</td>
+    <td width="33%"><strong>⌁ Fit your flow</strong><br>Use an interactive menu, shell completion, JSON output, or your own plugins.</td>
+  </tr>
+</table>
+
+## Start in 60 seconds
+
+### 1. Install Dhruv
+
 ```bash
 npm install -g @rahul05ranjan/dhruv-cli
 ```
 
-Or visit the npm page: https://www.npmjs.com/package/@rahul05ranjan/dhruv-cli
+### 2. Start a local model
+
+Install [Ollama](https://ollama.com/), then run:
+
+```bash
+ollama serve
+ollama pull gemma3:270m
+```
+
+### 3. Configure once, then go
+
+```bash
+dhruv init
+dhruv suggest "how should I structure this Node.js service?"
+```
+
+Dhruv requires Node.js 18 or newer. The default model is `gemma3:270m`; choose any model available in your Ollama installation during setup.
+
+## A command surface built for shipping
+
+| Command | What it does |
+| --- | --- |
+| `dhruv suggest <query>` | Generate practical suggestions for a development task |
+| `dhruv explain <query>` | Explain a concept, command, or unfamiliar error |
+| `dhruv fix <query>` | Analyze a coding issue and propose a fix |
+| `dhruv review <file-or-dir>` | Review up to ten code files for quality and maintainability; add `--diff` for uncommitted changes |
+| `dhruv optimize <file>` | Find actionable improvements for source or configuration files |
+| `dhruv security-check [file-or-dir]` | Run a redacted local security analysis; add `--strict` for CI failure on high-confidence findings |
+| `dhruv generate <type> <target>` | Preview generated tests by default; use `--apply`, `--output`, or `--overwrite` to write safely |
+| `dhruv status` | Check Ollama connectivity and configured models |
+| `dhruv health` | Show a concise health summary; use `--details` for diagnostics |
+| `dhruv metrics` | Inspect local usage and performance metrics; use `--raw` or `--reset` explicitly |
+| `dhruv project-type` | Detect the current project type |
+| `dhruv menu` | Open the interactive command palette |
+| `dhruv completion [shell]` | Generate Bash, Zsh, or Fish completion |
+
+### Common workflows
 
-## 📝 Usage Examples
 ```bash
-dhruv suggest "deploy react app to vercel"
+# Understand and plan
 dhruv explain "git rebase vs merge"
-dhruv fix "cors error in express"
+dhruv suggest "deploy a React app to Vercel"
+
+# Improve an existing project
 dhruv review src/
+dhruv review --diff .
 dhruv optimize package.json
 dhruv security-check src/
-dhruv generate tests src/utils/helpers.js
-dhruv init
-dhruv completion bash > dhruv-complete.sh # Enable tab completion
+dhruv security-check src/ --strict
+
+# Generate and automate
+dhruv generate tests src/utils/helpers.js       # preview only
+dhruv generate tests src/utils/helpers.js --apply
+dhruv completion zsh > ~/.zsh/completions/_dhruv
+```
+
+## Configuration that stays out of your way
+
+Run `dhruv init` to set the Ollama model, response format, verbosity, terminal theme, and whether settings are project-local or user-global. Local configuration is stored in `.dhruv-config.json`; global settings live under your user config directory.
+
+For one-off runs, use global flags:
+
+```bash
+dhruv suggest "summarize this migration" --model llama3.2 --json
+dhruv review src/ --verbose
+dhruv explain "what changed?" --timeout 60000
 ```
 
-## 🧩 Plugins
-Add new commands by dropping ESM modules in the `plugins/` directory. Example:
+## Extend it with plugins
+
+Drop an ESM module into your project's `plugins/` directory. Dhruv loads `.js` plugins before parsing the command line, so you can add commands without changing the core CLI.
+
 ```js
 // plugins/hello.js
 export default (program) => {
-  program.command('hello-plugin').action(() => console.log('Hello from plugin!'));
+  program
+    .command('hello-plugin')
+    .description('Say hello from a project plugin')
+    .action(() => console.log('Hello from Dhruv!'));
 };
 ```
 
-## 📦 Configuration
-- Run `dhruv init` to set model, response format, and verbosity.
-- Project type auto-detected for context-aware suggestions.
+Then run:
+
+```bash
+dhruv hello-plugin
+```
+
+## Documentation & project guides
 
-## 🖥️ Advanced UX
-- Streaming output, syntax highlighting, progress bars, colored errors, and interactive menus.
+| Resource | Link |
+| --- | --- |
+| Product site | [rahul05ranjan.github.io/dhruv-cli](https://rahul05ranjan.github.io/dhruv-cli/) |
+| API reference | [Generated TypeDoc](https://rahul05ranjan.github.io/dhruv-cli/api/) |
+| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Security policy | [SECURITY.md](SECURITY.md) |
+| Publishing notes | [docs/publishing-fix.md](docs/publishing-fix.md) |
+
+## Development
+
+```bash
+npm install
+npm run type-check
+npm test
+npm run lint
+npm run build
+```
 
 ## License
-MIT
+
+MIT © [Rahul Ranjan](https://github.com/rahul05ranjan)

package/__tests__/cli-contract.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from '@jest/globals';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve } from 'node:path';
+
+const execFileAsync = promisify(execFile);
+const repoRoot = resolve(__dirname, '..');
+// Package/relative specifiers so Windows does not pass `D:\...` into the ESM loader.
+const sourceEntry = './src/index.ts';
+const loaderEntry = 'ts-node/esm';
+
+describe('CLI output contract', () => {
+  it('keeps shell completion stdout free of startup telemetry', async () => {
+    const result = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'completion', 'bash'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+      },
+    );
+
+    expect(result.stdout).toMatch(/^#!\/bin\/bash/);
+    expect(result.stdout).not.toContain('Dhruv CLI starting');
+    expect(result.stdout).not.toContain('\u001b[');
+  });
+
+  it('includes diagnostic commands and shared options in completion scripts', async () => {
+    const result = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'completion', 'bash'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+      },
+    );
+
+    expect(result.stdout).toContain('status');
+    expect(result.stdout).toContain('--json');
+    expect(result.stdout).toContain('tests documentation docs component');
+  });
+
+  it('generates valid zsh and fish completion scripts with subcommands', async () => {
+    const zshResult = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'completion', 'zsh'],
+      { cwd: repoRoot, env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' } },
+    );
+    expect(zshResult.stdout).toContain('#compdef dhruv');
+    expect(zshResult.stdout).toContain('generate');
+    expect(zshResult.stdout).not.toContain('\u001b[');
+
+    const fishResult = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'completion', 'fish'],
+      { cwd: repoRoot, env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' } },
+    );
+    expect(fishResult.stdout).toContain('complete -c dhruv');
+    expect(fishResult.stdout).toContain('__fish_seen_subcommand_from generate');
+    expect(fishResult.stdout).not.toContain('\u001b[');
+  });
+
+  it('rejects unsupported completion shells', async () => {
+    await expect(execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'completion', 'powershell'],
+      { cwd: repoRoot, env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' } },
+    )).rejects.toMatchObject({ code: 2 });
+  });
+
+  it('documents strict security checks in command help', async () => {
+    const result = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'security-check', '--help'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+      },
+    );
+
+    expect(result.stdout).toContain('--strict');
+  });
+
+  it('documents safe generation controls in command help', async () => {
+    const result = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'generate', '--help'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+      },
+    );
+
+    expect(result.stdout).toContain('--apply');
+    expect(result.stdout).toContain('--output');
+    expect(result.stdout).toContain('--overwrite');
+  });
+
+  it('documents explicit metrics export and reset controls', async () => {
+    const result = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'metrics', '--help'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+      },
+    );
+
+    expect(result.stdout).toContain('--raw');
+    expect(result.stdout).toContain('--reset');
+  });
+
+  it('documents detailed health diagnostics as an explicit option', async () => {
+    const result = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'health', '--help'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+      },
+    );
+
+    expect(result.stdout).toContain('--details');
+  });
+
+  it('outputs exactly one valid JSON document on stdout with no ANSI or extra text', async () => {
+    const result = await execFileAsync(
+      process.execPath,
+      ['--loader', loaderEntry, sourceEntry, 'metrics', '--json'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+      },
+    );
+
+    expect(result.stdout).not.toContain('\u001b[');
+    const parsed = JSON.parse(result.stdout.trim()) as Record<string, unknown>;
+    expect(parsed).toMatchObject({
+      ok: true,
+      command: 'metrics',
+    });
+  });
+
+  it('outputs valid JSON for health command with expected top-level schema', async () => {
+    let stdout = '';
+    try {
+      const result = await execFileAsync(
+        process.execPath,
+        ['--loader', loaderEntry, sourceEntry, 'health', '--json'],
+        {
+          cwd: repoRoot,
+          env: { ...process.env, DHRUV_METRICS_ENABLED: 'false' },
+        },
+      );
+      stdout = result.stdout;
+    } catch (err: unknown) {
+      const execError = err as { stdout?: string; code?: number };
+      if (typeof execError?.stdout === 'string' && execError.stdout.trim().length > 0) {
+        stdout = execError.stdout;
+      } else {
+        throw err;
+      }
+    }
+
+    expect(stdout).not.toContain('\u001b[');
+    const parsed = JSON.parse(stdout.trim()) as Record<string, unknown>;
+    expect(parsed).toHaveProperty('ok');
+    expect(parsed.command).toBe('health');
+  });
+});

package/__tests__/core.test.ts

@@ -7,7 +7,7 @@ import {
 } from '../src/core/ai';
 import { loadConfig, saveConfig } from '../src/config/config';
 import { createSpinner } from '../src/utils/ux';
-import { detectProjectType } from '../src/utils/projectType';
+import { detectProjectType, detectProjectDetails } from '../src/utils/projectType';
 import { getSystemMessage } from '../src/core/prompts';
 import { runCommand } from '../src/core/command-runner';
 import fs from 'fs';
@@ -185,6 +185,75 @@ describe('Dhruv CLI Core Systems', () => {
 
       mockExistsSync.mockRestore();
     });
+
+    it('should detect a TypeScript Node project', () => {
+      const mockExistsSync = jest.spyOn(fs, 'existsSync');
+      mockExistsSync.mockImplementation((filePath: fs.PathLike) => path.basename(filePath.toString()) === 'package.json');
+      const mockReadFileSync = jest.spyOn(fs, 'readFileSync');
+      mockReadFileSync.mockReturnValue(JSON.stringify({ devDependencies: { typescript: '^5.0.0' } }));
+
+      expect(detectProjectType()).toBe('node-typescript');
+
+      mockExistsSync.mockRestore();
+      mockReadFileSync.mockRestore();
+    });
+
+    it('should return unknown instead of throwing for malformed package metadata', () => {
+      const mockExistsSync = jest.spyOn(fs, 'existsSync');
+      mockExistsSync.mockImplementation((filePath: fs.PathLike) => path.basename(filePath.toString()) === 'package.json');
+      const mockReadFileSync = jest.spyOn(fs, 'readFileSync');
+      mockReadFileSync.mockReturnValue('{ malformed');
+
+      const details = detectProjectDetails();
+      expect(details.type).toBe('unknown');
+      expect(details.diagnostic).toContain('Malformed package.json');
+      expect(detectProjectType()).toBe('unknown');
+
+      mockExistsSync.mockRestore();
+      mockReadFileSync.mockRestore();
+    });
+
+    it('should detect Python project with FastAPI framework', () => {
+      const mockExistsSync = jest.spyOn(fs, 'existsSync');
+      mockExistsSync.mockImplementation((filePath: fs.PathLike) => path.basename(filePath.toString()) === 'requirements.txt');
+      const mockReadFileSync = jest.spyOn(fs, 'readFileSync');
+      mockReadFileSync.mockReturnValue('fastapi>=0.100.0\nuvicorn>=0.20.0');
+
+      expect(detectProjectType()).toBe('python-fastapi');
+
+      mockExistsSync.mockRestore();
+      mockReadFileSync.mockRestore();
+    });
+
+    it('should detect Go project from go.mod', () => {
+      const mockExistsSync = jest.spyOn(fs, 'existsSync');
+      mockExistsSync.mockImplementation((filePath: fs.PathLike) => path.basename(filePath.toString()) === 'go.mod');
+
+      expect(detectProjectType()).toBe('go');
+
+      mockExistsSync.mockRestore();
+    });
+
+    it('should detect Rust project from Cargo.toml', () => {
+      const mockExistsSync = jest.spyOn(fs, 'existsSync');
+      mockExistsSync.mockImplementation((filePath: fs.PathLike) => path.basename(filePath.toString()) === 'Cargo.toml');
+
+      expect(detectProjectType()).toBe('rust');
+
+      mockExistsSync.mockRestore();
+    });
+
+    it('should detect Java Spring Boot project', () => {
+      const mockExistsSync = jest.spyOn(fs, 'existsSync');
+      mockExistsSync.mockImplementation((filePath: fs.PathLike) => path.basename(filePath.toString()) === 'pom.xml');
+      const mockReadFileSync = jest.spyOn(fs, 'readFileSync');
+      mockReadFileSync.mockReturnValue('<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId></dependency>');
+
+      expect(detectProjectType()).toBe('java-spring-boot');
+
+      mockExistsSync.mockRestore();
+      mockReadFileSync.mockRestore();
+    });
   });
 
   describe('System Message Templates', () => {
@@ -287,6 +356,41 @@ describe('Dhruv CLI Core Systems', () => {
       expect(completed).toBe('the answer');
     });
 
+    it('shows the AI response to the user', async () => {
+      const output: string[] = [];
+      const write = jest.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+        output.push(String(chunk));
+        return true;
+      });
+
+      await runCommand(makeSpec());
+
+      expect(output.join('')).toContain('the answer');
+      write.mockRestore();
+    });
+
+    it('emits one structured result in JSON mode', async () => {
+      saveConfig({ responseFormat: 'json' });
+      const output: string[] = [];
+      const write = jest.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+        output.push(String(chunk));
+        return true;
+      });
+
+      try {
+        await runCommand(makeSpec());
+        const result = JSON.parse(output.join('')) as Record<string, unknown>;
+        expect(result).toMatchObject({
+          ok: true,
+          command: 'explain',
+          response: 'the answer',
+        });
+      } finally {
+        write.mockRestore();
+        saveConfig({ responseFormat: 'text' });
+      }
+    });
+
     it('short-circuits on validation failure before the AI call', async () => {
       const computationsBefore = client.computations;
       await runCommand(makeSpec({ input: { query: '<script>alert(1)</script>' } }));
@@ -306,6 +410,94 @@ describe('Dhruv CLI Core Systems', () => {
       const { printError } = await import('../src/utils/ux');
       expect(jest.mocked(printError).mock.calls.length).toBeGreaterThan(0);
     });
+
+    it('maps an untyped ECONNREFUSED error to the ollama-serve hint', async () => {
+      setAIClient({
+        ask: async () => { throw new Error('connect ECONNREFUSED 127.0.0.1:11434'); },
+        listModels: async () => [],
+      });
+      const consoleSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+      await runCommand(makeSpec());
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('ollama serve'));
+      consoleSpy.mockRestore();
+    });
+
+    it('displays completed response when streaming is unavailable', async () => {
+      setAIClient({
+        ask: async () => 'static completed response',
+        listModels: async () => [],
+      });
+      const output: string[] = [];
+      const writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+        output.push(String(chunk));
+        return true;
+      });
+      await runCommand(makeSpec());
+      expect(output.join('')).toContain('static completed response');
+      writeSpy.mockRestore();
+    });
+
+    it('marks the process unsuccessful when an AI command fails', async () => {
+      const originalExitCode = process.exitCode;
+      process.exitCode = undefined;
+      client.failures.set('happy', { kind: 'connection', cause: 'ECONNREFUSED' });
+
+      try {
+        await runCommand(makeSpec());
+        expect(process.exitCode).toBe(1);
+      } finally {
+        process.exitCode = originalExitCode;
+      }
+    });
+
+    it('treats an empty AI response as a failed command', async () => {
+      setAIClient(new InMemoryAIClient(new Map([['happy', '']])));
+      process.exitCode = undefined;
+
+      try {
+        await runCommand(makeSpec());
+        expect(process.exitCode).toBe(1);
+      } finally {
+        process.exitCode = undefined;
+      }
+    });
+
+    it('times out a long-running AI request with a failing exit code', async () => {
+      saveConfig({ timeoutMs: 5 });
+      setAIClient({
+        ask: () => new Promise<string>(() => {}),
+        listModels: async () => [],
+      });
+      process.exitCode = undefined;
+
+      try {
+        await runCommand(makeSpec());
+        expect(process.exitCode).toBe(1);
+      } finally {
+        saveConfig({ timeoutMs: 45000 });
+        process.exitCode = undefined;
+      }
+    });
+
+    it('cancels an in-flight request on Ctrl-C', async () => {
+      saveConfig({ timeoutMs: 1000 });
+      setAIClient({
+        ask: () => new Promise<string>(() => {}),
+        listModels: async () => [],
+      });
+      process.exitCode = undefined;
+
+      try {
+        const running = runCommand(makeSpec());
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        process.emit('SIGINT');
+        await running;
+        expect(process.exitCode).toBe(130);
+      } finally {
+        saveConfig({ timeoutMs: 45000 });
+        process.exitCode = undefined;
+      }
+    });
   });
 
   describe('UX Utilities', () => {