devvami 1.3.0 → 1.4.1

package/src/services/nvd.js

@@ -0,0 +1,245 @@
+import { loadConfig } from './config.js'
+import { DvmiError } from '../utils/errors.js'
+
+/** @import { CveSearchResult, CveDetail } from '../types.js' */
+
+const NVD_BASE_URL = 'https://services.nvd.nist.gov/rest/json/cves/2.0'
+
+/** NVD attribution required in all interactive output. */
+export const NVD_ATTRIBUTION =
+  'This product uses data from the NVD API but is not endorsed or certified by the NVD.'
+
+/**
+ * Normalize a raw NVD severity string to the 4-tier canonical form.
+ * @param {string|undefined} raw
+ * @returns {'Critical'|'High'|'Medium'|'Low'|'Unknown'}
+ */
+export function normalizeSeverity(raw) {
+  if (!raw) return 'Unknown'
+  const s = raw.toUpperCase()
+  if (s === 'CRITICAL') return 'Critical'
+  if (s === 'HIGH') return 'High'
+  if (s === 'MEDIUM') return 'Medium'
+  if (s === 'LOW') return 'Low'
+  return 'Unknown'
+}
+
+/**
+ * Extract the best available CVSS metrics from a CVE record.
+ * Priority: cvssMetricV31 > cvssMetricV40 > cvssMetricV2
+ * @param {Record<string, unknown>} metrics
+ * @returns {{ score: number|null, severity: string, vector: string|null }}
+ */
+function extractCvss(metrics) {
+  const sources = [
+    (metrics?.cvssMetricV31 ?? []),
+    (metrics?.cvssMetricV40 ?? []),
+    (metrics?.cvssMetricV2 ?? []),
+  ]
+
+  for (const list of sources) {
+    if (Array.isArray(list) && list.length > 0) {
+      const data = /** @type {any} */ (list[0]).cvssData
+      if (data) {
+        return {
+          score: data.baseScore ?? null,
+          severity: normalizeSeverity(data.baseSeverity),
+          vector: data.vectorString ?? null,
+        }
+      }
+    }
+  }
+
+  return { score: null, severity: 'Unknown', vector: null }
+}
+
+/**
+ * Get the English description from the NVD descriptions array.
+ * @param {Array<{lang: string, value: string}>} descriptions
+ * @returns {string}
+ */
+function getEnDescription(descriptions) {
+  if (!Array.isArray(descriptions)) return ''
+  const en = descriptions.find((d) => d.lang === 'en')
+  return en?.value ?? ''
+}
+
+/**
+ * Build query parameters for NVD API request.
+ * @param {Record<string, string|number|undefined>} params
+ * @returns {URLSearchParams}
+ */
+function buildParams(params) {
+  const sp = new URLSearchParams()
+  for (const [key, val] of Object.entries(params)) {
+    if (val !== undefined && val !== null && val !== '') {
+      sp.set(key, String(val))
+    }
+  }
+  return sp
+}
+
+/**
+ * Make an authenticated fetch to the NVD API.
+ * @param {URLSearchParams} params
+ * @param {string|undefined} apiKey
+ * @returns {Promise<unknown>}
+ */
+async function nvdFetch(params, apiKey) {
+  const url = `${NVD_BASE_URL}?${params.toString()}`
+  /** @type {Record<string, string>} */
+  const headers = { Accept: 'application/json' }
+  if (apiKey) headers['apiKey'] = apiKey
+
+  const res = await fetch(url, { headers })
+  if (!res.ok) {
+    throw new DvmiError(
+      `NVD API returned HTTP ${res.status}`,
+      'Check your network connection or try again later.',
+    )
+  }
+  return res.json()
+}
+
+/**
+ * Parse a raw NVD vulnerability object into a CveSearchResult.
+ * @param {any} raw
+ * @returns {CveSearchResult}
+ */
+function parseCveSearchResult(raw) {
+  const cve = raw.cve
+  const { score, severity } = extractCvss(cve.metrics ?? {})
+  return {
+    id: cve.id,
+    description: getEnDescription(cve.descriptions),
+    severity,
+    score,
+    publishedDate: cve.published,
+    lastModified: cve.lastModified,
+    firstReference: (cve.references ?? [])[0]?.url ?? null,
+  }
+}
+
+/**
+ * Parse a raw NVD vulnerability object into a CveDetail.
+ * @param {any} raw
+ * @returns {CveDetail}
+ */
+function parseCveDetail(raw) {
+  const cve = raw.cve
+  const { score, severity, vector } = extractCvss(cve.metrics ?? {})
+
+  // Weaknesses: flatten all CWE descriptions
+  const weaknesses = (cve.weaknesses ?? []).flatMap((w) =>
+    (w.description ?? []).map((d) => ({
+      id: d.value,
+      description: d.value,
+    })),
+  )
+
+  // Affected products: parse CPE data from configurations
+  const affectedProducts = (cve.configurations ?? []).flatMap((cfg) =>
+    (cfg.nodes ?? []).flatMap((node) =>
+      (node.cpeMatch ?? [])
+        .filter((m) => m.vulnerable)
+        .map((m) => {
+          // cpe:2.3:a:vendor:product:version:...
+          const parts = (m.criteria ?? '').split(':')
+          const vendor = parts[3] ?? 'unknown'
+          const product = parts[4] ?? 'unknown'
+          const versionStart = m.versionStartIncluding ?? m.versionStartExcluding ?? ''
+          const versionEnd = m.versionEndExcluding ?? m.versionEndIncluding ?? ''
+          const versions = versionStart && versionEnd
+            ? `${versionStart} to ${versionEnd}`
+            : versionStart || versionEnd || (parts[5] ?? '*')
+          return { vendor, product, versions }
+        }),
+    ),
+  )
+
+  // References
+  const references = (cve.references ?? []).map((r) => ({
+    url: r.url ?? '',
+    source: r.source ?? '',
+    tags: Array.isArray(r.tags) ? r.tags : [],
+  }))
+
+  return {
+    id: cve.id,
+    description: getEnDescription(cve.descriptions),
+    severity,
+    score,
+    cvssVector: vector,
+    publishedDate: cve.published,
+    lastModified: cve.lastModified,
+    status: cve.vulnStatus ?? '',
+    weaknesses,
+    affectedProducts,
+    references,
+  }
+}
+
+/**
+ * Search CVEs by keyword within a date window.
+ * @param {Object} options
+ * @param {string} [options.keyword] - Search keyword (optional — omit to return all recent CVEs)
+ * @param {number} [options.days=14] - Look-back window in days
+ * @param {string} [options.severity] - Optional minimum severity filter (low|medium|high|critical)
+ * @param {number} [options.limit=20] - Maximum results to return
+ * @returns {Promise<{ results: CveSearchResult[], totalResults: number }>}
+ */
+export async function searchCves({ keyword, days = 14, severity, limit = 20 }) {
+  const config = await loadConfig()
+  const apiKey = config.nvd?.apiKey
+
+  const now = new Date()
+  const past = new Date(now.getTime() - days * 24 * 60 * 60 * 1000)
+
+  // NVD requires ISO-8601 with time component, no trailing Z
+  const pubStartDate = past.toISOString().replace('Z', '')
+  const pubEndDate = now.toISOString().replace('Z', '')
+
+  const trimmedKeyword = keyword?.trim()
+
+  const params = buildParams({
+    ...(trimmedKeyword ? { keywordSearch: trimmedKeyword } : {}),
+    pubStartDate,
+    pubEndDate,
+    resultsPerPage: limit,
+    ...(severity ? { cvssV3Severity: severity.toUpperCase() } : {}),
+  })
+
+  const data = /** @type {any} */ (await nvdFetch(params, apiKey))
+
+  const results = (data.vulnerabilities ?? []).map(parseCveSearchResult)
+  return { results, totalResults: data.totalResults ?? results.length }
+}
+
+/**
+ * Fetch full details for a single CVE by ID.
+ * @param {string} cveId - CVE identifier (e.g. "CVE-2021-44228")
+ * @returns {Promise<CveDetail>}
+ */
+export async function getCveDetail(cveId) {
+  if (!cveId || !/^CVE-\d{4}-\d{4,}$/i.test(cveId)) {
+    throw new DvmiError(
+      `Invalid CVE ID: ${cveId}`,
+      'CVE IDs must match the format CVE-YYYY-NNNNN (e.g. CVE-2021-44228)',
+    )
+  }
+
+  const config = await loadConfig()
+  const apiKey = config.nvd?.apiKey
+
+  const params = buildParams({ cveId: cveId.toUpperCase() })
+  const data = /** @type {any} */ (await nvdFetch(params, apiKey))
+
+  if (!data.vulnerabilities || data.vulnerabilities.length === 0) {
+    throw new DvmiError(
+      `CVE not found: ${cveId}`,
+      'Verify the CVE ID is correct and exists in the NVD database.',
+    )
+  }
+
+  return parseCveDetail(data.vulnerabilities[0])
+}

package/src/types.js

@@ -14,6 +14,70 @@
  * @property {string} [latestVersion] - Latest known CLI version
  * @property {'opencode'|'copilot'} [aiTool] - Preferred AI tool for running prompts
  * @property {string} [promptsDir] - Local directory for downloaded prompts (default: .prompts)
+ * @property {DotfilesConfig} [dotfiles] - Chezmoi dotfiles configuration
+ */
+
+/**
+ * @typedef {Object} DotfilesConfig
+ * @property {boolean} enabled - Whether chezmoi dotfiles management is active
+ * @property {string} [repo] - Remote dotfiles repository URL
+ * @property {string[]} [customSensitivePatterns] - User-added sensitive path patterns
+ */
+
+/**
+ * @typedef {Object} DotfileEntry
+ * @property {string} path - Target file path (e.g. "/home/user/.zshrc")
+ * @property {string} sourcePath - Source path in chezmoi state
+ * @property {boolean} encrypted - Whether the file is stored with encryption
+ * @property {'file'|'dir'|'symlink'} type - Entry type
+ */
+
+/**
+ * @typedef {Object} DotfileRecommendation
+ * @property {string} path - File path to recommend (e.g. "~/.zshrc")
+ * @property {'shell'|'git'|'editor'|'package'|'security'} category - Display grouping
+ * @property {Platform[]} platforms - Platforms this file applies to
+ * @property {boolean} autoEncrypt - Whether to encrypt by default
+ * @property {string} description - Human-readable description
+ */
+
+/**
+ * @typedef {Object} DotfilesSetupResult
+ * @property {Platform} platform - Detected platform
+ * @property {boolean} chezmoiInstalled - Whether chezmoi was found
+ * @property {boolean} encryptionConfigured - Whether age encryption is set up
+ * @property {string|null} sourceDir - Chezmoi source directory path
+ * @property {string|null} publicKey - Age public key
+ * @property {'success'|'skipped'|'failed'} status - Overall setup outcome
+ * @property {string} [message] - Human-readable outcome message
+ */
+
+/**
+ * @typedef {Object} DotfilesStatusResult
+ * @property {Platform} platform - Detected platform
+ * @property {boolean} enabled - Whether dotfiles management is active
+ * @property {boolean} chezmoiInstalled - Whether chezmoi binary exists
+ * @property {boolean} encryptionConfigured - Whether age encryption is set up
+ * @property {string|null} repo - Remote dotfiles repo URL
+ * @property {string|null} sourceDir - Chezmoi source directory
+ * @property {DotfileEntry[]} files - All managed files
+ * @property {{ total: number, encrypted: number, plaintext: number }} summary - File counts
+ */
+
+/**
+ * @typedef {Object} DotfilesAddResult
+ * @property {{ path: string, encrypted: boolean }[]} added - Successfully added files
+ * @property {{ path: string, reason: string }[]} skipped - Skipped files
+ * @property {{ path: string, reason: string }[]} rejected - Rejected files
+ */
+
+/**
+ * @typedef {Object} DotfilesSyncResult
+ * @property {'push'|'pull'|'init-remote'|'skipped'} action - Sync action performed
+ * @property {string|null} repo - Remote repository URL
+ * @property {'success'|'skipped'|'failed'} status - Outcome
+ * @property {string} [message] - Human-readable outcome
+ * @property {string[]} [conflicts] - Conflicting file paths
  */
 
 /**
@@ -294,11 +358,15 @@
  */
 
 /**
- * @typedef {Object} SearchMatch
- * @property {string} file - File path (e.g. "docs/deploy.md")
- * @property {number} line - Line number (1-based)
- * @property {string} context - Line text containing the match
- * @property {number} occurrences - Total number of occurrences in the file
+ * @typedef {Object} CveSearchResult
+ * Represents a single CVE returned from a search query. Used by `dvmi vuln search`.
+ * @property {string} id
+ * @property {string} description
+ * @property {'Critical'|'High'|'Medium'|'Low'|'Unknown'} severity
+ * @property {number|null} score
+ * @property {string} publishedDate
+ * @property {string} lastModified
+ * @property {string|null} firstReference - First reference URL from the CVE record, or null
  */
 
 /**

package/src/utils/errors.js

@@ -28,6 +28,8 @@ export class ValidationError extends DvmiError {
    constructor(message, hint) {
      super(message, hint, 2)
      this.name = 'ValidationError'
+     // oclif reads this.oclif.exit to determine the process exit code
+     this.oclif = { exit: 2 }
    }
  }
 

package/src/utils/tui/modal.js

@@ -0,0 +1,224 @@
+import chalk from 'chalk'
+import { NVD_ATTRIBUTION } from '../../services/nvd.js'
+
+// ──────────────────────────────────────────────────────────────────────────────
+// ANSI escape sequences (re-declared locally — avoids cross-module coupling)
+// ──────────────────────────────────────────────────────────────────────────────
+
+const ANSI_CLEAR = '\x1b[2J'
+const ANSI_HOME = '\x1b[H'
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Clamp a value between min and max (inclusive).
+ * @param {number} val
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function clamp(val, min, max) {
+  return Math.min(Math.max(val, min), max)
+}
+
+/**
+ * Center a string within a fixed width, padding with spaces on both sides.
+ * @param {string} text - Plain text (no ANSI codes)
+ * @param {number} width
+ * @returns {string}
+ */
+function centerText(text, width) {
+  if (text.length >= width) return text.slice(0, width)
+  const totalPad = width - text.length
+  const left = Math.floor(totalPad / 2)
+  const right = totalPad - left
+  return ' '.repeat(left) + text + ' '.repeat(right)
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// T006: buildModalScreen
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build the full modal overlay screen string from the current interactive state.
+ * Renders the modal content lines with a border, scroll indicators, and footer hints.
+ * Prepends ANSI clear + home to replace the previous frame.
+ * @param {import('./navigable-table.js').InteractiveTableState} state
+ * @returns {string}
+ */
+export function buildModalScreen(state) {
+  const { modalContent, modalScrollOffset, termRows, termCols, firstRefUrl } = state
+
+  const lines = []
+
+  // Modal inner width: leave 4 chars for left/right borders + padding
+  const innerWidth = Math.max(20, termCols - 4)
+
+  // ── Title bar ──────────────────────────────────────────────────────────────
+  const titleText = 'CVE Detail'
+  lines.push(chalk.bold.cyan('╔' + '═'.repeat(innerWidth + 2) + '╗'))
+  lines.push(chalk.bold.cyan('║ ') + chalk.bold(centerText(titleText, innerWidth)) + chalk.bold.cyan(' ║'))
+  lines.push(chalk.bold.cyan('╠' + '═'.repeat(innerWidth + 2) + '╣'))
+
+  const BORDER_LINES = 3 // title bar: top + title + divider
+  const FOOTER_LINES = 4 // empty + attribution + hints + bottom border
+  const contentViewport = Math.max(1, termRows - BORDER_LINES - FOOTER_LINES)
+
+  const content = modalContent ?? []
+  const maxOffset = Math.max(0, content.length - contentViewport)
+  const safeOffset = clamp(modalScrollOffset, 0, maxOffset)
+
+  // ── Content lines ──────────────────────────────────────────────────────────
+  const visibleLines = content.slice(safeOffset, safeOffset + contentViewport)
+  for (const line of visibleLines) {
+    // Truncate to inner width to avoid terminal wrapping
+    const truncated = line.length > innerWidth ? line.slice(0, innerWidth - 1) + '…' : line
+    lines.push(chalk.bold.cyan('║ ') + truncated.padEnd(innerWidth) + chalk.bold.cyan(' ║'))
+  }
+  // Pad to fill the content viewport
+  for (let i = visibleLines.length; i < contentViewport; i++) {
+    lines.push(chalk.bold.cyan('║ ') + ' '.repeat(innerWidth) + chalk.bold.cyan(' ║'))
+  }
+
+  // ── Footer ─────────────────────────────────────────────────────────────────
+  lines.push(chalk.bold.cyan('╠' + '═'.repeat(innerWidth + 2) + '╣'))
+  lines.push(chalk.bold.cyan('║ ') + chalk.dim(NVD_ATTRIBUTION).slice(0, innerWidth).padEnd(innerWidth) + chalk.bold.cyan(' ║'))
+
+  const scrollHint = content.length > contentViewport ? '  ↑↓/PgUp/PgDn scroll' : ''
+  const openHint = firstRefUrl ? '  o open ref' : ''
+  const hintLine = `  ↑↓ scroll   Esc back to table   q exit${openHint}${scrollHint}`
+  const truncHint = hintLine.length > innerWidth ? hintLine.slice(0, innerWidth - 1) + '…' : hintLine
+  lines.push(chalk.bold.cyan('║ ') + chalk.dim(truncHint).padEnd(innerWidth) + chalk.bold.cyan(' ║'))
+  lines.push(chalk.bold.cyan('╚' + '═'.repeat(innerWidth + 2) + '╝'))
+
+  return ANSI_CLEAR + ANSI_HOME + lines.join('\n')
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// T007: buildLoadingScreen
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build a "loading detail" screen to display while a CVE detail fetch is in flight.
+ * @param {string} cveId - The CVE identifier being fetched
+ * @param {number} termRows - Current terminal height
+ * @param {number} termCols - Current terminal width
+ * @returns {string}
+ */
+export function buildLoadingScreen(cveId, termRows, termCols) {
+  const lines = []
+  const innerWidth = Math.max(20, termCols - 4)
+  const midRow = Math.floor(termRows / 2)
+
+  lines.push(chalk.bold.cyan('╔' + '═'.repeat(innerWidth + 2) + '╗'))
+
+  for (let i = 1; i < midRow - 1; i++) {
+    lines.push(chalk.bold.cyan('║ ') + ' '.repeat(innerWidth) + chalk.bold.cyan(' ║'))
+  }
+
+  const loadingText = `Loading ${cveId}…`
+  const centred = centerText(loadingText, innerWidth)
+  lines.push(chalk.bold.cyan('║ ') + chalk.yellow(centred) + chalk.bold.cyan(' ║'))
+
+  const remaining = termRows - lines.length - 1
+  for (let i = 0; i < remaining; i++) {
+    lines.push(chalk.bold.cyan('║ ') + ' '.repeat(innerWidth) + chalk.bold.cyan(' ║'))
+  }
+
+  lines.push(chalk.bold.cyan('╚' + '═'.repeat(innerWidth + 2) + '╝'))
+
+  return ANSI_CLEAR + ANSI_HOME + lines.join('\n')
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// T008: buildErrorScreen
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build an error modal screen displayed when a CVE detail fetch fails.
+ * @param {string} cveId - The CVE identifier that failed to load
+ * @param {string} errorMessage - The error message to display
+ * @param {number} termRows - Current terminal height
+ * @param {number} termCols - Current terminal width
+ * @returns {string}
+ */
+export function buildErrorScreen(cveId, errorMessage, termRows, termCols) {
+  const lines = []
+  const innerWidth = Math.max(20, termCols - 4)
+  const midRow = Math.floor(termRows / 2)
+
+  lines.push(chalk.bold.cyan('╔' + '═'.repeat(innerWidth + 2) + '╗'))
+
+  for (let i = 1; i < midRow - 2; i++) {
+    lines.push(chalk.bold.cyan('║ ') + ' '.repeat(innerWidth) + chalk.bold.cyan(' ║'))
+  }
+
+  const titleText = `Failed to load ${cveId}`
+  lines.push(chalk.bold.cyan('║ ') + chalk.red.bold(centerText(titleText, innerWidth)) + chalk.bold.cyan(' ║'))
+  lines.push(chalk.bold.cyan('║ ') + ' '.repeat(innerWidth) + chalk.bold.cyan(' ║'))
+
+  const truncErr =
+    errorMessage.length > innerWidth ? errorMessage.slice(0, innerWidth - 1) + '…' : errorMessage
+  lines.push(chalk.bold.cyan('║ ') + chalk.red(truncErr.padEnd(innerWidth)) + chalk.bold.cyan(' ║'))
+
+  const remaining = termRows - lines.length - 2
+  for (let i = 0; i < remaining; i++) {
+    lines.push(chalk.bold.cyan('║ ') + ' '.repeat(innerWidth) + chalk.bold.cyan(' ║'))
+  }
+
+  const hintText = centerText('Press Esc to return to the table', innerWidth)
+  lines.push(chalk.bold.cyan('║ ') + chalk.dim(hintText) + chalk.bold.cyan(' ║'))
+  lines.push(chalk.bold.cyan('╚' + '═'.repeat(innerWidth + 2) + '╝'))
+
+  return ANSI_CLEAR + ANSI_HOME + lines.join('\n')
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// T015: handleModalKeypress
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Pure state reducer for keypresses in the modal view.
+ * Returns a new state on scroll, a control object on exit/back/open-url, or unchanged state.
+ * @param {import('./navigable-table.js').InteractiveTableState} state
+ * @param {{ name: string, ctrl?: boolean }} key - readline keypress event
+ * @returns {
+ *   import('./navigable-table.js').InteractiveTableState |
+ *   { backToTable: true } |
+ *   { exit: true } |
+ *   { openUrl: string }
+ * }
+ */
+export function handleModalKeypress(state, key) {
+  const { modalContent, modalScrollOffset, termRows, firstRefUrl } = state
+
+  if (key.ctrl && key.name === 'c') return { exit: true }
+  if (key.name === 'q') return { exit: true }
+
+  if (key.name === 'escape') return { backToTable: true }
+
+  if (key.name === 'o' && firstRefUrl) return { openUrl: firstRefUrl }
+
+  const contentLen = modalContent ? modalContent.length : 0
+  const BORDER_LINES = 3
+  const FOOTER_LINES = 4
+  const contentViewport = Math.max(1, termRows - BORDER_LINES - FOOTER_LINES)
+  const maxOffset = Math.max(0, contentLen - contentViewport)
+
+  if (key.name === 'up') {
+    return { ...state, modalScrollOffset: clamp(modalScrollOffset - 1, 0, maxOffset) }
+  }
+  if (key.name === 'down') {
+    return { ...state, modalScrollOffset: clamp(modalScrollOffset + 1, 0, maxOffset) }
+  }
+  if (key.name === 'pageup') {
+    return { ...state, modalScrollOffset: clamp(modalScrollOffset - contentViewport, 0, maxOffset) }
+  }
+  if (key.name === 'pagedown') {
+    return { ...state, modalScrollOffset: clamp(modalScrollOffset + contentViewport, 0, maxOffset) }
+  }
+
+  return state // unrecognized key — no state change
+}