@rahul05ranjan/dhruv-cli 1.4.6 → 1.5.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,104 @@
+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');
+  });
+
+  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');
+  });
+});

package/__tests__/core.test.ts

@@ -185,6 +185,30 @@ 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');
+
+      expect(detectProjectType()).toBe('unknown');
+
+      mockExistsSync.mockRestore();
+      mockReadFileSync.mockRestore();
+    });
   });
 
   describe('System Message Templates', () => {
@@ -287,6 +311,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 +365,68 @@ describe('Dhruv CLI Core Systems', () => {
       const { printError } = await import('../src/utils/ux');
       expect(jest.mocked(printError).mock.calls.length).toBeGreaterThan(0);
     });
+
+    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', () => {

package/__tests__/diagnostics.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { saveConfig } from '../src/config/config';
+import { status } from '../src/commands/status';
+import { health } from '../src/commands/health';
+import { metrics } from '../src/commands/metrics';
+import { getOllamaStatus, listModels } from '../src/core/ai';
+import { metricsCollector } from '../src/core/metrics';
+
+jest.mock('chalk', () => {
+  const identity = (value: unknown) => String(value);
+  const makeChalk = (): unknown => new Proxy(identity, {
+    get: (_target, property: string | symbol) => property === 'level' ? 0 : makeChalk(),
+    apply: (_target, _thisArg, args: unknown[]) => String(args[0]),
+  });
+  const chalk = makeChalk() as Record<string, unknown>;
+  return { __esModule: true, default: chalk, ...chalk };
+});
+
+jest.mock('../src/utils/ux', () => ({
+  printError: jest.fn(),
+  printSuccess: jest.fn(),
+  printWarning: jest.fn(),
+  printInfo: jest.fn(),
+  createSpinner: jest.fn(),
+  themed: jest.fn((value: string) => value),
+  highlightCode: jest.fn((value: string) => value),
+  createProgressBar: jest.fn(),
+}));
+
+jest.mock('../src/core/ai', () => ({
+  listModels: jest.fn(),
+  getOllamaStatus: jest.fn(),
+}));
+
+jest.mock('../src/core/logger', () => ({
+  logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+  logInfo: jest.fn(),
+  logError: jest.fn(),
+}));
+
+describe('diagnostic commands', () => {
+  it('emits structured status output in JSON mode', async () => {
+    jest.mocked(listModels).mockResolvedValue(['test-model']);
+    jest.mocked(getOllamaStatus).mockResolvedValue({ endpoint: 'http://127.0.0.1:11434', version: '0.12.3' });
+    saveConfig({ model: 'test-model', responseFormat: 'json' });
+    const output: string[] = [];
+    const write = jest.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+      output.push(String(chunk));
+      return true;
+    });
+
+    try {
+      await status();
+      expect(JSON.parse(output.join(''))).toMatchObject({
+        ok: true,
+        command: 'status',
+        model: 'test-model',
+        availableModels: ['test-model'],
+        endpoint: 'http://127.0.0.1:11434',
+        version: '0.12.3',
+      });
+    } finally {
+      write.mockRestore();
+      saveConfig({ responseFormat: 'text' });
+    }
+  });
+
+  it('emits structured health output in JSON mode', async () => {
+    jest.mocked(listModels).mockResolvedValue(['test-model']);
+    saveConfig({ model: 'test-model', responseFormat: 'json' });
+    const output: string[] = [];
+    const write = jest.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+      output.push(String(chunk));
+      return true;
+    });
+
+    const memory = jest.spyOn(process, 'memoryUsage').mockReturnValue({
+      rss: 40 * 1024 * 1024,
+      heapTotal: 30 * 1024 * 1024,
+      heapUsed: 20 * 1024 * 1024,
+      external: 1024 * 1024,
+      arrayBuffers: 0,
+    });
+
+    try {
+      await health();
+      const result = JSON.parse(output.join('')) as Record<string, unknown>;
+      expect(result).toMatchObject({ ok: true, command: 'health' });
+      expect(result).toHaveProperty('results');
+      expect(result).toHaveProperty('summary');
+    } finally {
+      memory.mockRestore();
+      write.mockRestore();
+      saveConfig({ responseFormat: 'text' });
+    }
+  });
+
+  it('retains a local command summary across collector reads', () => {
+    metricsCollector.resetPersistent();
+    metricsCollector.recordCommand('explain', 1250, true);
+
+    expect(metricsCollector.getSummary()).toMatchObject({
+      commands: {
+        explain: {
+          runs: 1,
+          successes: 1,
+          failures: 0,
+          durationMs: 1250,
+        },
+      },
+    });
+
+    metricsCollector.resetPersistent();
+  });
+
+  it('retains model and cache activity in the local summary', () => {
+    metricsCollector.resetPersistent();
+    metricsCollector.recordAIRequest('test-model', 'explain', 250, true);
+    metricsCollector.recordCacheHit('ai-response');
+    metricsCollector.recordCacheMiss('ai-response');
+
+    expect(metricsCollector.getSummary()).toMatchObject({
+      models: {
+        'test-model': { requests: 1, successes: 1, failures: 0, durationMs: 250 },
+      },
+      cache: { hits: 1, misses: 1 },
+    });
+
+    metricsCollector.resetPersistent();
+  });
+
+  it('emits persisted metrics in JSON mode', async () => {
+    metricsCollector.resetPersistent();
+    metricsCollector.recordCommand('status', 50, true);
+    saveConfig({ responseFormat: 'json' });
+    const output: string[] = [];
+    const write = jest.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+      output.push(String(chunk));
+      return true;
+    });
+
+    try {
+      await metrics();
+      expect(JSON.parse(output.join(''))).toMatchObject({
+        ok: true,
+        command: 'metrics',
+        summary: { commands: { status: { runs: 1 } } },
+      });
+    } finally {
+      write.mockRestore();
+      saveConfig({ responseFormat: 'text' });
+      metricsCollector.resetPersistent();
+    }
+  });
+});