praxis-sec 1.0.0

package/cli/core/output/compliance.js

@@ -0,0 +1,90 @@
+import { getStandardsSummary } from '../../utils/standards/index.js';
+
+export default function renderComplianceReport(report, options = {}) {
+  const findings = report.findings || [];
+  const summary = getStandardsSummary(findings);
+
+  // Focus on OWASP LLM and NIST AI 600-1
+  const owasp = summary['owasp-llm'];
+  const nist = summary['nist-ai-600-1'];
+
+  const lines = [];
+  lines.push('================================================================================');
+  lines.push('                      PRAXIS GRC COMPLIANCE AUDIT REPORT');
+  lines.push('================================================================================');
+  lines.push(`Scanned At:     ${report.scannedAt || new Date().toISOString()}`);
+  lines.push(`Total Findings: ${findings.length}`);
+  lines.push(`Security Score: ${report.score || 100}/100 (Grade: ${report.grade || 'A'})`);
+  lines.push('');
+
+  lines.push('--------------------------------------------------------------------------------');
+  lines.push(' STANDARDS COVERAGE SUMMARY');
+  lines.push('--------------------------------------------------------------------------------');
+  if (owasp) {
+    lines.push(`  * ${owasp.title} (v${owasp.version}):`);
+    lines.push(`    - Controls Flagged: ${owasp.flaggedControls} of ${owasp.totalControls} (${owasp.coverage})`);
+  }
+  if (nist) {
+    lines.push(`  * ${nist.title} (v${nist.version}):`);
+    lines.push(`    - Controls Flagged: ${nist.flaggedControls} of ${nist.totalControls} (${nist.coverage})`);
+  }
+  lines.push('');
+
+  lines.push('--------------------------------------------------------------------------------');
+  lines.push(' DETAILED CONTROL MAPPINGS');
+  lines.push('--------------------------------------------------------------------------------');
+
+  const renderDetailedStandard = (std) => {
+    if (!std) return;
+    lines.push(`### Standard: ${std.title} (v${std.version})`);
+    lines.push(`URL: ${std.url}`);
+    lines.push('');
+    const flagged = (std.controls || []).filter(c => c.findingCount > 0);
+    if (flagged.length === 0) {
+      lines.push('  ✔ All controls in this standard are compliant (no findings).');
+      lines.push('');
+      return;
+    }
+
+    for (const ctrl of flagged) {
+      lines.push(`  [NON-COMPLIANT] Control ${ctrl.id}: ${ctrl.title}`);
+      if (ctrl.description) {
+        lines.push(`    Description: ${ctrl.description}`);
+      }
+      lines.push(`    Flagged Occurrences: ${ctrl.findingCount}`);
+      lines.push('');
+      
+      // List matching findings
+      const matchingFindings = findings.filter(f => {
+        const stdMap = f.standards || {};
+        const ctrlIds = stdMap[std.name] || [];
+        return ctrlIds.includes(ctrl.id);
+      });
+
+      for (const f of matchingFindings) {
+        lines.push(`      - [${f.severity.toUpperCase()}] ${f.file}${f.line ? ` (line ${f.line})` : ''}`);
+        lines.push(`        Finding: ${f.title}`);
+        lines.push(`        Remediation: ${f.remediation || 'Refer to Praxis guidelines'}`);
+      }
+      lines.push('');
+    }
+  };
+
+  if (owasp) renderDetailedStandard(owasp);
+  if (nist) renderDetailedStandard(nist);
+
+  lines.push('================================================================================');
+  lines.push('                              GRC RECOMMENDATIONS');
+  lines.push('================================================================================');
+  if (findings.length === 0) {
+    lines.push('  1. Maintain current posture by scheduling regular automated scans.');
+    lines.push('  2. Enable real-time commit hooks to prevent future secret exposure.');
+  } else {
+    lines.push('  1. Prioritize critical and high severity findings matching OWASP LLM01/LLM02.');
+    lines.push('  2. Implement runtime guardrails to satisfy NIST AI 600-1 inputs/outputs mapping.');
+    lines.push('  3. Remediate flagged findings before promoting code to production environments.');
+  }
+  lines.push('================================================================================');
+
+  return lines.join('\n');
+}

package/cli/core/output/html-theme.js

@@ -0,0 +1,158 @@
+/**
+ * Shared HTML report theme — single source of truth for every Praxis HTML surface.
+ * ============================================================================
+ *
+ * Extracted (P-IMP-051c) because `cli/agents/html-reporter.js` and
+ * `cli/commands/team-report.js` each carried their own ~100-line inline stylesheet
+ * and their own severity palette. Those palettes had already drifted
+ * (`critical` was `#ef4444` in one and `#dc2626` in the other), so every brand or
+ * styling fix had to be applied twice — and the two files disagreed on the same
+ * concept.
+ *
+ * Also centralises the primitives that must never be re-implemented per report:
+ *   - `esc()`               — HTML escaping. `team-report.js` previously had none and
+ *                             interpolated finding text straight into markup, which is
+ *                             an injection sink in a file users open in a browser.
+ *   - `severityBadgeClass()` — maps a severity to a *known* CSS class, so an arbitrary
+ *                             severity string can't be injected into a class attribute.
+ *   - `countBySeverity()`    — one counting implementation, not one per report.
+ *
+ * Design constraints (per AGENTS.md): no build step, no bundler, no framework. These
+ * are plain template strings and functions, so every report stays a single
+ * self-contained offline HTML file.
+ */
+
+/** Severity → accent colour. Used for bars, legends, and inline accents. */
+export const SEVERITY_COLORS = {
+  critical: '#ef4444',
+  high: '#f97316',
+  medium: '#eab308',
+  low: '#38bdf8',
+  info: '#64748b',
+};
+
+/** Security-score letter grade → colour. */
+export const GRADE_COLORS = {
+  A: '#22c55e',
+  B: '#06b6d4',
+  C: '#eab308',
+  D: '#f97316',
+  F: '#ef4444',
+};
+
+/** Every severity we recognise, in report order. */
+export const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+
+/**
+ * Severities rendered in distribution bars/legends. Includes `info` so the segments
+ * always sum to 100% of the findings shown — omitting it left the bar visibly
+ * under-filled whenever a scan produced informational findings.
+ */
+export const DISPLAY_SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+
+/**
+ * Escapes text for interpolation into HTML markup or a quoted attribute.
+ * Null/undefined become an empty string so callers can interpolate directly.
+ */
+export function esc(str) {
+  if (str === null || str === undefined) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Maps a severity to a known-safe CSS class suffix.
+ *
+ * Returns `''` for anything unrecognised so the result is always a safe subset of
+ * the class attribute — a finding whose `severity` came from a parsed report file
+ * must never be able to break out of `class="sev-badge …"`.
+ */
+export function severityBadgeClass(severity) {
+  const key = String(severity || '').toLowerCase();
+  return SEVERITIES.includes(key) || key === 'info' ? key : '';
+}
+
+/** Renders a severity badge span. Escapes the label and sanitises the class. */
+export function severityBadge(severity, label) {
+  const cls = severityBadgeClass(severity);
+  const text = label ?? String(severity || 'unknown');
+  const classes = cls ? `sev-badge sev-${cls}` : 'sev-badge';
+  return `<span class="${classes}">${esc(text)}</span>`;
+}
+
+/** Counts findings per severity, always returning a fully-populated record. */
+export function countBySeverity(findings = []) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of Array.isArray(findings) ? findings : []) {
+    const key = String(f?.severity || '').toLowerCase();
+    if (key in counts) counts[key]++;
+  }
+  return counts;
+}
+
+/**
+ * The shared base stylesheet: reset, typography, layout container, tables, code,
+ * severity badges, and the muted/empty/footer primitives. Every report includes
+ * this, then appends its own component styles.
+ */
+export function baseStyles() {
+  return `
+      *{margin:0;padding:0;box-sizing:border-box}
+      html{scroll-behavior:smooth}
+      body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;background:#090d16;color:#cbd5e1;line-height:1.55;font-size:14px}
+      a{color:#38bdf8;text-decoration:none}
+      a:hover{text-decoration:underline}
+
+      .container{max-width:1440px;margin:1.8rem auto;padding:0 2rem}
+      h1{font-size:1.8rem;font-weight:700;color:#f8fafc;margin-bottom:0.25rem}
+      h2{font-size:1.1rem;font-weight:600;margin:2rem 0 1rem;color:#94a3b8;border-bottom:1px solid #1e293b;padding-bottom:0.5rem;text-transform:uppercase;letter-spacing:0.05em}
+
+      .table-responsive{overflow-x:auto}
+      table{width:100%;border-collapse:collapse;font-size:0.86rem;text-align:left}
+      th{background:#131d33;color:#94a3b8;padding:0.75rem 1rem;font-size:0.75rem;text-transform:uppercase;letter-spacing:0.6px;border-bottom:1px solid #1e293b}
+      td{padding:0.75rem 1rem;border-bottom:1px solid #172239;vertical-align:top}
+      tr:hover td{background:#111b30}
+      code{background:#050811;border:1px solid #1e293b;color:#7dd3fc;padding:2px 6px;border-radius:4px;font-size:0.8rem;word-break:break-word}
+      small{color:#64748b}
+
+      .sev-badge{display:inline-block;padding:3px 9px;border-radius:6px;font-size:0.72rem;font-weight:800;text-transform:uppercase;letter-spacing:0.5px}
+      .sev-critical{background:#450a0a;color:#fca5a5;border:1px solid #991b1b}
+      .sev-high{background:#431407;color:#fdba74;border:1px solid #9a3412}
+      .sev-medium{background:#422006;color:#fde047;border:1px solid #854d0e}
+      .sev-low{background:#082f49;color:#7dd3fc;border:1px solid #075985}
+      .sev-info{background:#1e293b;color:#cbd5e1;border:1px solid #334155}
+
+      .muted{color:#64748b}
+      .ok{color:#6ee7b7}
+      .fail{color:#fca5a5}
+      .empty-state{text-align:center;color:#64748b;padding:2.5rem 1rem;font-size:0.9rem}
+      .footer{text-align:center;padding:2.5rem 0 1.5rem;color:#64748b;font-size:0.8rem;border-top:1px solid #1e293b;margin-top:3rem}
+      @media(max-width:1024px){.container{padding:0 1rem}}
+    `;
+}
+
+/**
+ * Wraps body markup in a complete, self-contained HTML document.
+ *
+ * `styles` is injected verbatim and must be trusted (it is always generated by
+ * this module, never derived from scan findings). `body` and `title` are escaped.
+ */
+export function documentShell({ title, styles, body, bodyClass = '' }) {
+  const cls = bodyClass ? ` class="${esc(bodyClass)}"` : '';
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(title)}</title>
+<style>${styles}</style>
+</head>
+<body${cls}>
+${body}
+</body>
+</html>`;
+}

package/cli/core/output/index.js

@@ -0,0 +1,57 @@
+/**
+ * Output formatter registry
+ * =========================
+ *
+ * Centralized place to register output formats so `--format <name>` is a
+ * lookup, not a per-command switch statement. Eliminates the 4 separate
+ * formatter implementations that previously lived inline in
+ * `cli/commands/{audit,ci,team-report,diff}.js`.
+ *
+ * Usage:
+ *   import { render } from 'cli/core/output/index.js';
+ *   const text = render('json', report);
+ *   console.log(text);
+ *
+ * Adding a new format: write a renderer at `./your-format.js` that
+ * exports `default function(report, options): string`, then add it to
+ * the registry below.
+ */
+
+import json from './json.js';
+import sarif from './sarif.js';
+import compliance from './compliance.js';
+
+const REGISTRY = {
+  json,
+  sarif,
+  compliance,
+};
+
+export function listFormats() {
+  return Object.keys(REGISTRY);
+}
+
+export function hasFormat(name) {
+  return Object.prototype.hasOwnProperty.call(REGISTRY, name);
+}
+
+/**
+ * Render `report` into the requested format. Throws if the format is
+ * unknown so callers can present the available list.
+ */
+export function render(format, report, options = {}) {
+  const renderer = REGISTRY[format];
+  if (!renderer) {
+    throw new Error(
+      `unknown format '${format}'. available: ${listFormats().join(', ')}`
+    );
+  }
+  return renderer(report, options);
+}
+
+/**
+ * Register an additional format at runtime. Used by tests and plugins.
+ */
+export function registerFormat(name, renderer) {
+  REGISTRY[name] = renderer;
+}

package/cli/core/output/json.js

@@ -0,0 +1,48 @@
+/**
+ * JSON output formatter.
+ *
+ * Reports are emitted with `schemaVersion` so consumers can pin to a
+ * version. Bump the version when the shape changes in a breaking way.
+ *
+ * Scanner hardening: secret-category findings never expose their raw
+ * matched value — `matched` is redacted centrally so no consumer of the
+ * JSON report can leak a credential.
+ */
+
+const SCHEMA_VERSION = 3;
+
+function redactFinding(f) {
+  if (!f || typeof f !== 'object') return f;
+  const isSecret = f.category === 'secrets' || f.category === 'secret'
+    || /secret|api[_-]?key|token|password|credential/i.test(String(f.rule || ''));
+  const out = { ...f };
+  if (f.matched) {
+    out.matched = isSecret
+      ? `${String(f.matched).slice(0, 3)}***`
+      : String(f.matched).slice(0, 160);
+  }
+  if (out.file) {
+    out.file = String(out.file)
+      .replace(/\\/g, '/')
+      .replace(/^[a-zA-Z]:\/+/, '')
+      .replace(/^.*\/Praxis\/showcase-target\//, 'showcase-target/')
+      .replace(/^.*\/Praxis\//, '');
+  }
+  return out;
+}
+
+export default function json(report, options = {}) {
+  const { pretty = true } = options;
+  const enriched = {
+    schemaVersion: SCHEMA_VERSION,
+    ...report,
+  };
+  if (Array.isArray(enriched.findings)) {
+    enriched.findings = enriched.findings.map(redactFinding);
+  }
+  return pretty
+    ? JSON.stringify(enriched, null, 2)
+    : JSON.stringify(enriched);
+}
+
+export { redactFinding, SCHEMA_VERSION };

package/cli/core/output/sarif.js

@@ -0,0 +1,240 @@
+/**
+ * SARIF v2.1.0 output formatter.
+ *
+ * The single SARIF serializer for Praxis (P-IMP-062). Every emitting path must go
+ * through here: `scan --sarif`, `scan ci --sarif`, `audit --sarif`, `redteam --sarif`,
+ * `scan standard --sarif` and `--format sarif`. Four commands used to carry private
+ * copies of this logic, which meant fixes applied here reached almost nobody — most
+ * visibly `security-severity`, which the GitHub Action's `scan ci --sarif` call never
+ * emitted. Do not reintroduce a local serializer.
+ *
+ * Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ */
+
+import path from 'path';
+import { toolVersion as toolVersion_ } from '../version.js';
+
+const SARIF_VERSION = '2.1.0';
+
+/**
+ * Severity → SARIF `level` + GitHub `security-severity`.
+ *
+ * These are two different axes and both are needed:
+ *   - `level` is the coarse SARIF gate (`error` / `warning` / `note`).
+ *   - `security-severity` is the 0.0-10.0 number GitHub Code Scanning uses to rank,
+ *     colour and filter alerts.
+ *
+ * Emitting `level` alone collapsed critical and high into the same bucket, so every
+ * Code Scanning consumer saw compressed severity — the tiering the product is built on
+ * was invisible exactly where people look for it. Both fields come from this one table
+ * so they cannot drift apart.
+ *
+ * Emitted as a string because that is the form GitHub's own documentation uses.
+ */
+const SEVERITY = {
+  critical: { level: 'error', securitySeverity: '9.5' },
+  high: { level: 'error', securitySeverity: '7.5' },
+  medium: { level: 'warning', securitySeverity: '5.0' },
+  low: { level: 'note', securitySeverity: '2.5' },
+  info: { level: 'note', securitySeverity: '0.0' },
+};
+
+/** Unknown or absent severity must not silently read as low-risk. */
+const DEFAULT_SEVERITY = { level: 'warning', securitySeverity: '5.0' };
+
+const forSeverity = (severity) => SEVERITY[severity] || DEFAULT_SEVERITY;
+
+/**
+ * Normalizes Praxis's internal finding shape and renders SARIF.
+ *
+ * Commands hold findings in two shapes: a flat list using `rule`/`title`/`file`, and
+ * the per-file `[{ file, findings }]` shape the orchestrator returns. This accepts
+ * either, so no command has to know the SARIF field names — which is what let four
+ * private serializers drift apart in the first place.
+ *
+ * @param {object[]} findings
+ * @param {object} [options]  forwarded to the serializer; pass `rootPath` or artifact
+ *                            URIs will not be repo-relative.
+ */
+export function renderFindingsSARIF(findings, options = {}) {
+  const flat = Array.isArray(findings) && findings.length > 0 && findings[0] && Array.isArray(findings[0].findings)
+    ? findings.flatMap(({ file, findings: fileFindings }) =>
+      (fileFindings || []).map((f) => ({ ...f, file: f.file || file })))
+    : (findings || []);
+
+  return renderSARIFDocument({
+    findings: flat.map((f) => ({
+      ruleId: f.ruleId || f.rule || f.patternName || f.pattern || f.type,
+      title: f.title || f.patternName || f.rule,
+      file: f.file,
+      line: f.line,
+      column: f.column,
+      severity: f.severity,
+      description: f.description,
+      cwe: f.cwe,
+      owasp: f.owasp,
+      standards: f.standards,
+      category: f.category,
+    })),
+  }, options);
+}
+
+function renderSARIFDocument(report, options = {}) {
+  const {
+    toolName = 'praxis',
+    // Defaults to the real package version. This used to fall back to a hardcoded
+    // '1.0.0', so any caller that forgot to pass `toolVersion` reported a confidently
+    // wrong driver version in Code Scanning (P-IMP-065).
+    toolVersion = report.version || toolVersion_(),
+    informationUri = 'https://github.com/Ganron007/Praxis',
+    rootPath = null,
+  } = options;
+
+  const findings = report.findings || [];
+  const rules = collectRules(findings);
+  const relativize = makeRelativizer(rootPath);
+
+  const sarifReport = {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: toolName,
+            version: toolVersion,
+            informationUri,
+            rules,
+          },
+        },
+        results: findings.map((f) => toResult(f, relativize)),
+      },
+    ],
+  };
+
+  return JSON.stringify(sarifReport, null, 2);
+}
+
+/**
+ * Builds the artifact-URI normaliser.
+ *
+ * SARIF is uploaded to GitHub Code Scanning, so artifact URIs must be repo-relative.
+ * When `rootPath` is supplied, findings are relativized against it. Without it we fall
+ * back to stripping a leading drive letter or POSIX root and collapsing `..` segments.
+ *
+ * This fallback used to strip a hardcoded `/Praxis/` prefix. That was written for this
+ * repository's own dogfooding and failed open for every real user: a Windows path
+ * surfaced the username and the whole directory tree, and a POSIX path passed through
+ * untouched — publishing the local filesystem layout into a target repository.
+ */
+function makeRelativizer(rootPath) {
+  // A path that is already relative needs no relativizing. This matters: feeding
+  // `src/nested/deep.js` to `path.relative(root, ...)` resolves it against the cwd,
+  // escapes the root, and the fallback then reduces it to `deep.js` — losing the
+  // directory and making the alert unlocatable in Code Scanning.
+  const isAbsolute = (f) => path.isAbsolute(f) || /^[a-zA-Z]:[\\/]/.test(f);
+
+  if (rootPath) {
+    return (file) => {
+      const s = String(file);
+      if (!s) return s;
+      if (!isAbsolute(s)) return s.split(path.sep).join('/');
+
+      const rel = path.relative(rootPath, s);
+      // A file outside the root still must not leak an absolute path; fall back to the
+      // basename rather than emitting `../../..`.
+      if (!rel || rel.startsWith('..')) return path.basename(s);
+      return rel.split(path.sep).join('/');
+    };
+  }
+
+  return (file) => {
+    let s = String(file).split(path.sep).join('/');
+    s = s.replace(/^[a-zA-Z]:\/*/, '').replace(/^\/+/, '');
+
+    // Collapse `.`/`..` segments without escaping the repo.
+    const out = [];
+    for (const seg of s.split('/')) {
+      if (seg === '' || seg === '.') continue;
+      if (seg === '..') { out.pop(); continue; }
+      out.push(seg);
+    }
+    return out.join('/') || path.basename(String(file));
+  };
+}
+
+function collectRules(findings) {
+  const seen = new Map();
+  for (const f of findings) {
+    const id = f.ruleId || f.pattern || f.type || 'finding';
+    if (seen.has(id)) continue;
+    // Collect tags for the rule definition so GitHub Security tab groups
+    // Praxis findings by AI/LLM/MCP/supply-chain categories.
+    const ruleTags = ['praxis'];
+    if (f.category) ruleTags.push(f.category);
+    if (f.owasp) ruleTags.push(f.owasp);
+    if (f.standards) {
+      for (const [, ids] of Object.entries(f.standards)) {
+        for (const sid of ids) ruleTags.push(sid);
+      }
+    }
+    const sev = forSeverity(f.severity);
+    seen.set(id, {
+      id,
+      name: f.patternName || id,
+      shortDescription: { text: f.patternName || id },
+      fullDescription: { text: f.description || f.patternName || id },
+      defaultConfiguration: {
+        level: sev.level,
+      },
+      properties: {
+        tags: [...new Set(ruleTags)], // dedup
+        // GitHub Code Scanning ranks and filters on this numeric property.
+        'security-severity': sev.securitySeverity,
+      },
+    });
+  }
+  return [...seen.values()];
+}
+
+function toResult(f, relativize) {
+  const uri = relativize(f.file || f.path || '');
+
+  const sev = forSeverity(f.severity);
+
+  const result = {
+    ruleId: f.ruleId || f.pattern || f.type || 'finding',
+    level: sev.level,
+    message: { text: f.description || f.message || f.patternName || 'finding' },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri, uriBaseId: '%SRCROOT%' },
+          region: {
+            startLine: f.line || 1,
+            startColumn: f.column || 1,
+          },
+        },
+      },
+    ],
+  };
+
+  // Embed AI-security standard tags so SARIF consumers (GitHub Code Scanning,
+  // SonarQube, etc.) can filter / display alignment per finding.
+  const props = { 'security-severity': sev.securitySeverity };
+  if (f.cwe) props.cwe = f.cwe;
+  if (f.owasp) props.owasp = f.owasp;
+  if (f.standards && Object.keys(f.standards).length > 0) {
+    props.standards = f.standards;
+    const tags = [];
+    for (const [, ids] of Object.entries(f.standards)) {
+      for (const id of ids) tags.push(id);
+    }
+    if (tags.length > 0) props.tags = tags;
+  }
+  result.properties = props;
+
+  return result;
+}
+
+export default renderSARIFDocument;

package/cli/core/version.js

@@ -0,0 +1,67 @@
+/**
+ * Praxis's own version — the single source of truth.
+ * ============================================================================
+ *
+ * Six modules used to read `package.json` independently for the version, and a
+ * seventh (`core/output/sarif.js`) did not read it at all and fell back to a
+ * hardcoded `'1.0.0'`. That is six chances to drift at release time and one that
+ * reported a confidently wrong number in SARIF provenance.
+ *
+ * Everything imports `toolVersion()` from here instead. Two consequences worth
+ * knowing:
+ *
+ *   - The value is cached for the process lifetime, so it is cheap to call from
+ *     hot paths and cannot change mid-run.
+ *   - If the read fails it returns the string `'unknown'` rather than guessing.
+ *     A wrong version is worse than an honest one: `cache-manager` keys its cache
+ *     on this value, so a stale guess would silently reuse stale findings.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/** Returned when package.json cannot be read. Never a plausible version string. */
+export const UNKNOWN_VERSION = 'unknown';
+
+let cached = null;
+
+/**
+ * @returns {string} the Praxis version, or `'unknown'` if it cannot be determined
+ */
+export function toolVersion() {
+  if (cached !== null) return cached;
+
+  try {
+    // cli/core/ -> repo root. Resolved from import.meta.url rather than __dirname so it
+    // behaves identically on Windows and POSIX.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(fs.readFileSync(path.resolve(here, '..', '..', 'package.json'), 'utf8'));
+    const version = typeof pkg.version === 'string' ? pkg.version.trim() : '';
+    cached = version || UNKNOWN_VERSION;
+  } catch {
+    cached = UNKNOWN_VERSION;
+  }
+
+  return cached;
+}
+
+/**
+ * True when `a` is a higher version than `b`. Exported because `doctor` needs the same
+ * comparison and previously kept its own copy.
+ *
+ * Returns false for anything unparseable, so an odd version string never produces a
+ * spurious "update available".
+ */
+export function isNewerVersion(candidate, current) {
+  const parse = (v) => String(v ?? '').split(/[.+-]/).map((n) => parseInt(n, 10) || 0);
+  const a = parse(candidate);
+  const b = parse(current);
+  if (a.length === 0 || b.length === 0) return false;
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const d = (a[i] || 0) - (b[i] || 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}