nsauditor-ai 0.1.12 → 0.1.20

package/README.md

@@ -110,6 +110,9 @@ Results land in `./out/<host>_<timestamp>/`:
 | `scan_response_ai.json` | Raw AI API response |
 | `scan_response_ai.txt` | AI conclusion (markdown) |
 | `scan_response_ai.html` | Styled HTML report with CVE links and badges |
+| `scan_results.sarif.json` | SARIF 2.1 — only with `--output-format sarif` (renamed `scan_<host>.sarif.json` for multi-host runs) |
+| `scan_results.csv` | CSV — only with `--output-format csv` |
+| `scan_report.md` | GitHub-flavored Markdown report — only with `--output-format md` (or `markdown`) |
 
 > Works on Node 20+ (tested on Node 22).
 
@@ -184,7 +187,7 @@ NSAuditor AI supports three AI providers for vulnerability analysis. **All provi
 
 **What changes by tier is the prompt content, not the provider:**
 
-- **CE** — basic scan-summary prompts (services, ports, versions detected)
+- **CE** — basic scan-summary prompts (services, ports, versions detected). Local MITRE ATT&CK mapping via `utils/attack_map.mjs`: service-context-aware CVE→technique mapping (`mapCveToAttack`, `mapServiceToAttack`), plus a CWE→technique fallback (`cweToMitre`, `cwesToMitre`) covering ~30 common CWEs (auth, crypto, injection, memory safety, info disclosure, privilege escalation, web). The CWE fallback fires only when CVE-derived mapping returns no techniques — useful for findings annotated with `evidence.cwe[]` (per FindingSchema v0.1.13+) but no CVE context, such as agent-detected misconfigurations and compliance-flagged weaknesses
 - **Pro** — intelligence-enriched prompts (CVE matches, MITRE techniques, risk scores, verification status injected into the prompt). Same API call, vastly better output
 - **Enterprise** — Pro prompts + compliance context
 
@@ -350,9 +353,9 @@ nsauditor-ai scan [options]
 | `--host-file <path>` | File with one host per line (`#` comments, blank lines OK) | — |
 | `--plugins <list>` | Comma-separated plugin IDs or `all` | `all` |
 | `--ports <list>` | Comma-separated ports to pass to plugins | — |
-| `--out <dir>` | Custom output directory | `out/` |
+| `--out <dir>` | Custom output directory — applies to the per-scan folder *and* to alternate-format files (SARIF/CSV/Markdown) | `out/` |
 | `--parallel <n>` | Concurrent host scans | `1` |
-| `--output-format <fmt>` | Output format: `sarif` for CI/CD | — |
+| `--output-format <fmt>` | Additional output format: `sarif` (CI/CD) · `csv` (spreadsheet) · `md` or `markdown` (chat/PR/Slack quotable) | — |
 | `--fail-on <sev>` | Exit code 2 if findings ≥ severity: `critical\|high\|medium\|low\|info` | — |
 | `--insecure-https` | Accept self-signed TLS certificates | `false` |
 | `--watch` | Enable CTEM continuous scanning | `false` |
@@ -388,6 +391,9 @@ nsauditor-ai scan --host 192.168.1.8 --plugins 011,006,009,013,008
 # SARIF output for CI/CD, fail on high+ findings
 nsauditor-ai scan --host 10.0.0.5 --plugins all --output-format sarif --fail-on high
 
+# Markdown report — paste straight into a GitHub issue, Slack thread, or chat
+nsauditor-ai scan --host 10.0.0.5 --plugins all --output-format md
+
 # Continuous monitoring with webhook alerts
 nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
   --watch --interval 30 \
@@ -398,6 +404,27 @@ nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
 nsauditor-ai scan --host-file targets.txt --plugins all --parallel 4
 ```
 
+### Pre-flight `validate` command
+
+`nsauditor-ai validate` runs a fast (<2s) environment check without scanning anything. Useful for CI/CD setups, Docker `HEALTHCHECK` probes, and first-time-user diagnosis. Each check returns a status; the overall exit code is 0 (all OK), 1 (warnings), or 2 (errors).
+
+Checks: plugin discovery, license JWT validation (if key set), AI provider configuration, output-directory writability + free space, DNS resolution.
+
+```bash
+# Human-readable output
+nsauditor-ai validate
+
+# Machine-readable JSON for CI parsing
+nsauditor-ai validate --json
+```
+
+Docker HEALTHCHECK example:
+
+```dockerfile
+HEALTHCHECK --interval=60s --timeout=5s --start-period=10s --retries=3 \
+  CMD nsauditor-ai validate --json | grep -q '"overall": "ok"' || exit 1
+```
+
 ---
 
 ## Configuration

package/cli.mjs

@@ -12,6 +12,7 @@ import { openaiSimplePrompt, openaiPrompt as openaiProPrompt, openaiPromptOptimi
 import { parseHostArg, parseHostFile } from './utils/host_iterator.mjs';
 import { buildSarifLog } from './utils/sarif.mjs';
 import { buildCsv } from './utils/export_csv.mjs';
+import { buildMarkdownReport } from './utils/report_md.mjs';
 import { recordScan, getLastScan, computeDiff, formatDiffReport, pruneForCE, HISTORY_FILE } from './utils/scan_history.mjs';
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
 import { resolveCapabilities, hasCapability } from './utils/capabilities.mjs';
@@ -21,6 +22,9 @@ import { sendWebhook, buildAlertPayload, isSafeWebhookUrl } from './utils/webhoo
 import { scrubByKey } from './utils/redact.mjs';
 import { isBlockedIp, resolveAndValidate } from './utils/net_validation.mjs';
 import { getAllTechniques } from './utils/attack_map.mjs';
+import { TOOL_VERSION } from './utils/tool_version.mjs';
+import { resolveBaseOutDir } from './utils/output_dir.mjs';
+import { toCleanPath } from './utils/path_helpers.mjs';
 
 /* ------------------------- helpers & utilities ------------------------- */
 
@@ -42,7 +46,7 @@ const nowStamp = () => {
   );
 };
 const safeHost = (h) => String(h ?? 'unknown').replace(/[\/\\?%*:|"<>]/g, '_');
-const toCleanPath = (s) => String(s ?? '').trim().replace(/^['"]+|['"]+$/g, '');
+// toCleanPath imported from ./utils/path_helpers.mjs (consolidated in v0.1.20)
 
 /** Minimal redactor used if nothing external is provided. */
 function redactSensitiveForAI(input, targetHost) {
@@ -104,10 +108,10 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
     : await resolveSecret(process.env.OPENAI_API_KEY);
   const key           = keyRaw ? String(keyRaw).trim() : null;
 
-  // Base output folder (directory ONLY; if a file path is given, take its dir)
-  const outHintRaw  = toCleanPath(process.env.SCAN_OUT_PATH || process.env.OPENAI_OUT_PATH || 'out');
-  const parsedHint  = path.parse(outHintRaw);
-  const baseOutDir  = parsedHint.ext ? (parsedHint.dir || 'out') : (outHintRaw || 'out');
+  // Base output folder (resolved via the shared helper — honors --out and
+  // the SCAN_OUT_PATH / OPENAI_OUT_PATH env vars consistently with the
+  // SARIF/CSV/MD writers below).
+  const baseOutDir  = resolveBaseOutDir();
 
   await fsp.mkdir(baseOutDir, { recursive: true });
 
@@ -797,6 +801,26 @@ async function main() {
     process.exit(0);
   }
 
+  if (cmd === 'validate') {
+    const { runValidation } = await import('./utils/validate.mjs');
+    const rawArgs = process.argv.slice(2);
+    const wantJson = rawArgs.includes('--json');
+
+    const { overall, checks, exitCode } = await runValidation();
+
+    if (wantJson) {
+      console.log(JSON.stringify({ overall, exitCode, checks }, null, 2));
+    } else {
+      const glyph = { ok: '✓', warn: '⚠', error: '✗', skip: '·' };
+      console.log(`NSAuditor AI environment validation:\n`);
+      for (const c of checks) {
+        console.log(`  ${glyph[c.status] ?? '?'} [${c.status}] ${c.name}: ${c.message}`);
+      }
+      console.log(`\nOverall: ${overall.toUpperCase()} (exit ${exitCode})`);
+    }
+    process.exit(exitCode);
+  }
+
   if (cmd !== 'scan') {
     console.error(`Unknown command: ${cmd}`);
     process.exit(2);
@@ -954,7 +978,7 @@ async function main() {
   // --- SARIF output ---
   const wantSarif = outputFormat && String(outputFormat).toLowerCase().includes('sarif');
   if (wantSarif) {
-    const outDir = 'out';
+    const outDir = resolveBaseOutDir();
     await fsp.mkdir(outDir, { recursive: true });
 
     for (const scanOut of scanOutputs) {
@@ -976,7 +1000,7 @@ async function main() {
   // --- CSV output ---
   const wantCsv = outputFormat && String(outputFormat).toLowerCase().includes('csv');
   if (wantCsv) {
-    const outDir = 'out';
+    const outDir = resolveBaseOutDir();
     await fsp.mkdir(outDir, { recursive: true });
 
     for (const scanOut of scanOutputs) {
@@ -994,6 +1018,30 @@ async function main() {
     }
   }
 
+  // --- Markdown output ---
+  // Accept "md" or "markdown" in --output-format. Word-boundary match avoids matching
+  // "md" inside other tokens (e.g. a hypothetical future format with "md" as a substring).
+  const wantMd = outputFormat && /\b(md|markdown)\b/i.test(String(outputFormat));
+  if (wantMd) {
+    const outDir = resolveBaseOutDir();
+    await fsp.mkdir(outDir, { recursive: true });
+
+    for (const scanOut of scanOutputs) {
+      if (!scanOut?.conclusion) continue;
+      const md = buildMarkdownReport({
+        host: scanOut.host,
+        conclusion: scanOut.conclusion,
+        toolVersion: TOOL_VERSION,
+      });
+      const mdFileName = scanOutputs.length > 1
+        ? `scan_${safeHost(scanOut.host)}.md`
+        : 'scan_report.md';
+      const mdPath = path.join(outDir, mdFileName);
+      await fsp.writeFile(mdPath, md, 'utf8');
+      console.log(`[MD] Wrote Markdown report: ${mdPath}`);
+    }
+  }
+
   // --- Fail-on severity threshold ---
   if (failOn) {
     const threshold = SEVERITY_RANK[String(failOn).toLowerCase()];

package/mcp_server.mjs

@@ -21,6 +21,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
 import { resolveCapabilities } from './utils/capabilities.mjs';
+import { buildMarkdownReport } from './utils/report_md.mjs';
 
 const _require = createRequire(import.meta.url);
 const { version: TOOL_VERSION } = _require('./package.json');
@@ -233,11 +234,28 @@ export async function handleScanHost(args) {
   // Note: timeout is controlled via PLUGIN_TIMEOUT_MS env var at startup.
   // Runtime override is not supported to avoid process-global state mutation.
   const output = await pm.run(host, 'all');
+
+  // Render a Markdown summary of the scan so AI assistants get a ready-to-quote
+  // report alongside the structured fields. Failure to render must not break the
+  // scan response (defensive: any conclusion-shape surprise should degrade to
+  // markdown=null, not error out the whole tool call).
+  let markdown = null;
+  try {
+    if (output.conclusion) {
+      markdown = buildMarkdownReport({
+        host: output.host,
+        conclusion: output.conclusion,
+        toolVersion: TOOL_VERSION,
+      });
+    }
+  } catch { /* swallow — markdown is best-effort */ }
+
   return {
     host: output.host,
     conclusion: output.conclusion ?? null,
     manifest: output.manifest ?? [],
     pluginsRan: output.results?.length ?? 0,
+    markdown,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.1.12",
+  "version": "0.1.20",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,
@@ -13,6 +13,18 @@
     "nsauditor-ai": "bin/nsauditor-ai.mjs",
     "nsauditor-ai-mcp": "bin/nsauditor-ai-mcp.mjs"
   },
+  "files": [
+    "bin/",
+    "config/",
+    "docs/EULA-nsauditor-ai.md",
+    "plugins/",
+    "utils/",
+    "CONTRIBUTING.md",
+    "cli.mjs",
+    "index.mjs",
+    "mcp_server.mjs",
+    "plugin_manager.mjs"
+  ],
   "dependencies": {
     "@anthropic-ai/sdk": "^0.82.0",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/utils/attack_map.mjs

@@ -24,6 +24,75 @@ export const SERVICE_TECHNIQUE_MAP = {
   mdns_llmnr_exposure:  [T('T1557.001', 'LLMNR/NBT-NS Poisoning')],
 };
 
+/**
+ * Mapping from CWE identifiers to ATT&CK techniques.
+ *
+ * Used by `cweToMitre()` and as a fallback path in `mapServiceToAttack()` for findings
+ * that have CWE annotations but no service-context-derivable technique (e.g., agent-detected
+ * misconfigurations or compliance violations that aren't tied to a specific CVE).
+ *
+ * Coverage: ~30 CWEs spanning the most common nsauditor finding categories
+ * (authentication, crypto, injection, memory safety, info disclosure, path traversal,
+ * privilege escalation, web-specific, resource consumption).
+ *
+ * IDs are uppercased CWE-NNN format. Lookup in `cweToMitre()` is case-insensitive.
+ */
+export const CWE_TECHNIQUE_MAP = {
+  // Authentication / access control
+  'CWE-287':  [T('T1078', 'Valid Accounts')],                                                // Improper Authentication
+  'CWE-306':  [T('T1078', 'Valid Accounts')],                                                // Missing Authentication
+  'CWE-521':  [T('T1110', 'Brute Force')],                                                   // Weak Password Requirements
+  'CWE-798':  [T('T1552.001', 'Unsecured Credentials: Credentials In Files')],               // Use of Hard-coded Credentials
+  'CWE-256':  [T('T1552', 'Unsecured Credentials')],                                         // Plaintext Storage of a Password
+  'CWE-862':  [T('T1078', 'Valid Accounts')],                                                // Missing Authorization
+  'CWE-863':  [T('T1078', 'Valid Accounts')],                                                // Incorrect Authorization
+
+  // Cryptography
+  'CWE-319':  [T('T1040', 'Network Sniffing')],                                              // Cleartext Transmission of Sensitive Information
+  'CWE-326':  [T('T1557', 'Adversary-in-the-Middle')],                                       // Inadequate Encryption Strength
+  'CWE-327':  [T('T1557', 'Adversary-in-the-Middle')],                                       // Use of a Broken or Risky Cryptographic Algorithm
+  'CWE-328':  [T('T1557', 'Adversary-in-the-Middle')],                                       // Use of Weak Hash
+  'CWE-331':  [T('T1557', 'Adversary-in-the-Middle')],                                       // Insufficient Entropy
+
+  // Injection
+  'CWE-77':   [T('T1059', 'Command and Scripting Interpreter')],                             // Command Injection (generic)
+  'CWE-78':   [T('T1059', 'Command and Scripting Interpreter')],                             // OS Command Injection
+  'CWE-79':   [T('T1059.007', 'Command and Scripting Interpreter: JavaScript')],             // XSS
+  'CWE-89':   [T('T1190', 'Exploit Public-Facing Application')],                             // SQL Injection
+  'CWE-94':   [T('T1059', 'Command and Scripting Interpreter')],                             // Code Injection
+  'CWE-1336': [T('T1059', 'Command and Scripting Interpreter')],                             // Template Injection
+
+  // Memory safety / RCE primitives
+  'CWE-119':  [T('T1203', 'Exploitation for Client Execution')],                             // Buffer Errors
+  'CWE-120':  [T('T1203', 'Exploitation for Client Execution')],                             // Buffer Overflow
+  'CWE-125':  [T('T1203', 'Exploitation for Client Execution')],                             // Out-of-bounds Read
+  'CWE-416':  [T('T1203', 'Exploitation for Client Execution')],                             // Use After Free
+  'CWE-502':  [T('T1190', 'Exploit Public-Facing Application')],                             // Deserialization of Untrusted Data
+  'CWE-787':  [T('T1203', 'Exploitation for Client Execution')],                             // Out-of-bounds Write
+
+  // Information disclosure
+  'CWE-200':  [T('T1592', 'Gather Victim Host Information')],                                // Information Exposure
+  'CWE-209':  [T('T1592', 'Gather Victim Host Information')],                                // Information Exposure Through Error Messages
+
+  // Path traversal / file
+  'CWE-22':   [T('T1083', 'File and Directory Discovery')],                                  // Path Traversal
+  'CWE-434':  [T('T1190', 'Exploit Public-Facing Application')],                             // Unrestricted Upload of File with Dangerous Type
+
+  // Privilege escalation / permissions
+  'CWE-250':  [T('T1068', 'Exploitation for Privilege Escalation')],                         // Execution with Unnecessary Privileges
+  'CWE-269':  [T('T1068', 'Exploitation for Privilege Escalation')],                         // Improper Privilege Management
+  'CWE-732':  [T('T1574.005', 'Hijack Execution Flow: Executable Installer File Permissions Weakness')], // Incorrect Permission Assignment
+
+  // Web-specific
+  'CWE-352':  [T('T1185', 'Browser Session Hijacking')],                                     // CSRF
+  'CWE-601':  [T('T1204.001', 'User Execution: Malicious Link')],                            // URL Redirection to Untrusted Site
+  'CWE-918':  [T('T1071', 'Application Layer Protocol')],                                    // SSRF
+
+  // Resource consumption / DoS
+  'CWE-400':  [T('T1499', 'Endpoint Denial of Service')],                                    // Uncontrolled Resource Consumption
+  'CWE-770':  [T('T1499', 'Endpoint Denial of Service')],                                    // Allocation of Resources Without Limits or Throttling
+};
+
 /**
  * Convert a technique ID to a MITRE ATT&CK URL.
  * Sub-techniques use dot notation (T1021.004) which maps to slash paths (/T1021/004/).
@@ -35,6 +104,37 @@ export function attackUrl(techniqueId) {
   return `https://attack.mitre.org/techniques/${path}/`;
 }
 
+/**
+ * Map a single CWE identifier to ATT&CK techniques.
+ * Lookup is case-insensitive and tolerates surrounding whitespace.
+ * Returns a fresh array (callers may push into it without aliasing the static map).
+ *
+ * @param {string} cwe - e.g. "CWE-326", "cwe-89"
+ * @returns {Array<{ techniqueId: string, name: string }>} Empty if unknown or invalid input.
+ */
+export function cweToMitre(cwe) {
+  if (typeof cwe !== 'string') return [];
+  const id = cwe.trim().toUpperCase();
+  const techs = CWE_TECHNIQUE_MAP[id];
+  return techs ? [...techs] : [];
+}
+
+/**
+ * Map an array (or single string) of CWE identifiers to a deduplicated set of techniques.
+ *
+ * @param {string[]|string} cwes - Array like ['CWE-326', 'CWE-89'] or single string.
+ * @returns {Array<{ techniqueId: string, name: string }>} Deduplicated by techniqueId.
+ */
+export function cwesToMitre(cwes) {
+  if (!cwes) return [];
+  const list = Array.isArray(cwes) ? cwes : [cwes];
+  const techniques = [];
+  for (const cwe of list) {
+    techniques.push(...cweToMitre(cwe));
+  }
+  return dedup(techniques);
+}
+
 /**
  * Map a service record to matching ATT&CK techniques.
  * Inspects service type and boolean/array fields to identify relevant techniques.
@@ -93,16 +193,29 @@ export function mapServiceToAttack(service) {
   }
 
   // CVE-based mappings
+  let cveDerivedCount = 0;
   const cves = service.cves || service.cve || [];
   if (Array.isArray(cves)) {
     for (const cve of cves) {
       const cveId = typeof cve === 'string' ? cve : (cve?.id || cve?.cveId || '');
       if (cveId) {
-        techniques.push(...mapCveToAttack(cveId, svcName));
+        const cveTechs = mapCveToAttack(cveId, svcName);
+        cveDerivedCount += cveTechs.length;
+        techniques.push(...cveTechs);
       }
     }
   }
 
+  // CWE-based fallback: only applied when CVE mapping produced no techniques.
+  // Reads in priority order: service.cwes → service.cwe → service.evidence?.cwe.
+  // CVE-derived mappings are service-context-aware and authoritative; CWE mappings
+  // are heuristic and provide coverage for findings without CVE context (agent-detected
+  // misconfigurations, compliance-flagged weaknesses, etc.).
+  if (cveDerivedCount === 0) {
+    const cwes = service.cwes || service.cwe || service.evidence?.cwe || [];
+    techniques.push(...cwesToMitre(cwes));
+  }
+
   return dedup(techniques).map(t => ({ ...t, url: attackUrl(t.techniqueId) }));
 }
 

package/utils/finding_schema.mjs

@@ -6,8 +6,15 @@ export const FINDING_STATUSES   = ['UNVERIFIED', 'VERIFIED', 'POTENTIAL', 'FALSE
 export const FINDING_SEVERITIES = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
 export const FINDING_EFFORTS    = ['LOW', 'MEDIUM', 'HIGH'];
 
+const CWE_ID_PATTERN = /^CWE-\d+$/;
+
 /**
  * Validate a finding object against the schema.
+ *
+ * Optional evidence fields (validated only when present):
+ *   - evidence.cwe   string[] of CWE-NNN identifiers, e.g. ['CWE-326', 'CWE-200']
+ *   - evidence.owasp string[] of OWASP categories, e.g. ['A02:2021-Cryptographic Failures']
+ *
  * @param {object} f
  * @returns {string[]} Array of error messages; empty = valid
  */
@@ -23,6 +30,29 @@ export function validateFinding(f) {
     errors.push('title required');
   if (!f?.target?.host)
     errors.push('target.host required');
+
+  if (f?.evidence?.cwe !== undefined) {
+    if (!Array.isArray(f.evidence.cwe)) {
+      errors.push('evidence.cwe must be an array');
+    } else {
+      for (const id of f.evidence.cwe) {
+        if (typeof id !== 'string' || !CWE_ID_PATTERN.test(id))
+          errors.push(`invalid cwe id: ${id}`);
+      }
+    }
+  }
+
+  if (f?.evidence?.owasp !== undefined) {
+    if (!Array.isArray(f.evidence.owasp)) {
+      errors.push('evidence.owasp must be an array');
+    } else {
+      for (const ent of f.evidence.owasp) {
+        if (typeof ent !== 'string')
+          errors.push(`invalid owasp entry: ${ent}`);
+      }
+    }
+  }
+
   return errors;
 }
 

package/utils/output_dir.mjs

@@ -0,0 +1,45 @@
+// utils/output_dir.mjs
+//
+// Single source of truth for resolving the base output directory used by
+// CLI scan-output writers (main scan, SARIF, CSV, Markdown).
+//
+// Why a dedicated module:
+//   - The CLI's `--out <dir>` flag is parsed and stamped onto
+//     `process.env.SCAN_OUT_PATH`. Multiple writers in cli.mjs read that
+//     env var to compute their target path.
+//   - Prior to v0.1.18, the SARIF/CSV/MD output blocks hardcoded `'out'`,
+//     ignoring `--out`. This helper centralizes the resolution so the bug
+//     can't recur in a new format writer (Task N.17).
+//   - `OPENAI_OUT_PATH` is honored as a legacy fallback.
+
+import path from 'node:path';
+import { toCleanPath } from './path_helpers.mjs';
+
+/**
+ * Resolve the base output directory.
+ *
+ * Source priority:
+ *   1. `process.env.SCAN_OUT_PATH` (set by `--out <dir>`)
+ *   2. `process.env.OPENAI_OUT_PATH` (legacy fallback)
+ *   3. `'out'` (default)
+ *
+ * If the resolved value points at a file (has an extension), returns its
+ * parent directory. This handles the "user passed --out report.json" case
+ * — we use the file's containing directory rather than crashing.
+ *
+ * Read fresh each call so callers see the latest env state (important
+ * because the CLI sets SCAN_OUT_PATH during arg parsing, after module load).
+ *
+ * @returns {string} A directory path; never empty (defaults to `'out'`).
+ */
+export function resolveBaseOutDir() {
+  const raw = toCleanPath(
+    process.env.SCAN_OUT_PATH || process.env.OPENAI_OUT_PATH || 'out'
+  );
+  const parsed = path.parse(raw);
+  // If env var pointed at a file (has an extension), use its parent dir.
+  // Otherwise treat the whole value as a directory.
+  return parsed.ext ? (parsed.dir || 'out') : (raw || 'out');
+}
+
+// (toCleanPath moved to utils/path_helpers.mjs in v0.1.20 — no _internals export needed.)

package/utils/path_helpers.mjs

@@ -0,0 +1,29 @@
+// utils/path_helpers.mjs
+//
+// Small, generic path-handling helpers used across cli.mjs and the output-dir
+// resolution logic. Extracted from cli.mjs and utils/output_dir.mjs so both
+// consumers share a single implementation (Task N.20).
+//
+// Pure synchronous functions, no I/O — safe to import from any context.
+
+/**
+ * Trim surrounding whitespace and strip surrounding quote characters
+ * (single or double, possibly stacked) from a path-like string.
+ *
+ * Useful when shells (especially Windows cmd.exe / PowerShell) pass paths
+ * with embedded quotes intact, or when env-var values arrive with stray
+ * outer whitespace.
+ *
+ * Examples:
+ *   toCleanPath('"/tmp/foo"')   → '/tmp/foo'
+ *   toCleanPath("'/tmp/bar'")   → '/tmp/bar'
+ *   toCleanPath('  /a b/c  ')   → '/a b/c'    (internal whitespace preserved)
+ *   toCleanPath(null)           → ''
+ *   toCleanPath(42)             → '42'
+ *
+ * @param {*} s - Any value; coerced to string before processing.
+ * @returns {string} Cleaned string. Empty if input is nullish or all-quote.
+ */
+export function toCleanPath(s) {
+  return String(s ?? '').trim().replace(/^['"]+|['"]+$/g, '');
+}