@rahul05ranjan/dhruv-cli 1.3.0 → 1.5.0

package/.github/workflows/security.yml

@@ -0,0 +1,201 @@
+name: Security Monitoring
+
+on:
+  schedule:
+    - cron: '0 6 * * 1' # Every Monday at 6 AM UTC
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  secret-scan:
+    name: Secret Scanning
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run TruffleHog
+        uses: trufflesecurity/trufflehog@main
+        with:
+          path: ./
+          # Use the action's event-aware range (push, PR, or full history).
+          extra_args: --debug --only-verified
+
+  license-check:
+    name: License Compliance
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    timeout-minutes: 10
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.8.1'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Check licenses
+        run: |
+          npx license-checker --summary --onlyAllow 'MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC;0BSD;Unlicense' || echo "License check completed with warnings"
+        continue-on-error: true
+
+  supply-chain:
+    name: Supply Chain Security
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    timeout-minutes: 15
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.8.1'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Run OSV Scanner
+        uses: google/osv-scanner-action/osv-scanner-action@v2.6.0
+        continue-on-error: true
+        with:
+          scan-args: |-
+            --recursive
+            ./
+
+      - name: Run Snyk Security Scan
+        uses: snyk/actions/node@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          args: --severity-threshold=high
+        continue-on-error: true
+
+  sbom-generation:
+    name: Generate SBOM
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    timeout-minutes: 10
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.8.1'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Generate SBOM
+        run: |
+          npx --yes @cyclonedx/cyclonedx-npm --output-file sbom.json
+          npx --yes @cyclonedx/cyclonedx-npm --output-file sbom.xml --output-format XML
+
+      - name: Upload SBOM
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom-files
+          path: |
+            sbom.json
+            sbom.xml
+          retention-days: 90
+
+  security-scorecard:
+    name: OSSF Scorecard
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+      id-token: write
+    # Scorecard only supports analysis from the repository's default branch.
+    if: github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@v2.4.4
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload SARIF results
+        if: always() && hashFiles('results.sarif') != ''
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+
+  container-scan:
+    name: Container and Dependency Scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@v2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@v4
+
+      # Scorecard publishing only permits approved actions in its own job.
+      - name: Container and dependency scan
+        uses: anchore/scan-action@v7.4.2
+        id: scan
+        with:
+          path: "."
+          fail-build: false
+          output-format: sarif
+
+      - name: Upload Anchore scan SARIF file
+        if: always() && steps.scan.outputs.sarif != ''
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: ${{ steps.scan.outputs.sarif }}

package/.releaserc.json

@@ -0,0 +1,50 @@
+{
+  "branches": [
+    "main",
+    {
+      "name": "improvement",
+      "prerelease": "beta"
+    },
+    {
+      "name": "development",
+      "prerelease": "alpha"
+    }
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    "@semantic-release/npm",
+    [
+      "@semantic-release/github",
+      {
+        "assets": [
+          {
+            "path": "dist/**",
+            "label": "Distribution files"
+          },
+          {
+            "path": "docs/**",
+            "label": "Documentation"
+          }
+        ]
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "CHANGELOG.md",
+          "package.json",
+          "package-lock.json"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ]
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues (rahul05ranjan/dhruv-cli), via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default five-role vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [1.4.0](https://github.com/rahul05ranjan/dhruv-cli/compare/v1.4.6...v1.4.0) (2026-09-18)
+
+
+### Bug Fixes
+
+* change moduleResolution from Node to Bundler in tsconfig ([b8339bb](https://github.com/rahul05ranjan/dhruv-cli/commit/b8339bb89781490d5678f43052b606138f375d21))
+* drop unused menu loop flag ([51eeec6](https://github.com/rahul05ranjan/dhruv-cli/commit/51eeec6a607299120ce3e1f15af9f9dc62396ce7))
+* stabilize health and CLI contract tests on CI ([3b3e650](https://github.com/rahul05ranjan/dhruv-cli/commit/3b3e6503591c8c33d36f1887e94358dafe6163ce))
+
+
+### Features
+
+* improve cli experience across commands ([ce41913](https://github.com/rahul05ranjan/dhruv-cli/commit/ce4191350ca3d1c5f49b371508e66de9421f6d20))
 # Changelog
 
 ## [1.1.1](https://github.com/rahul05ranjan/dhruv-cli/compare/v1.1.0...v1.1.1) (2025-06-29)

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');
+  });
+});