@tekyzinc/gsd-t 2.33.12 → 2.34.12

package/README.md

@@ -8,6 +8,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Catches downstream effects** — analyzes impact before changes break things.
 **Protects existing work** — destructive action guard prevents schema drops, architecture replacements, and data loss without explicit approval.
 **Visualizes execution in real time** — live browser dashboard renders agent hierarchy, tool activity, and phase progression from the event stream.
+**Generates visual scan reports** — every `/gsd-t-scan` produces a self-contained HTML report with 6 live architectural diagrams, a tech debt register, and domain health scores; optional DOCX/PDF export via `--export docx|pdf`.
 
 ---
 

package/bin/gsd-t.js

@@ -1482,6 +1482,14 @@ if (require.main === module) {
     case "changelog":
       doChangelog();
       break;
+    case "scan": {
+      const exportFlag = args.find(a => a.startsWith('--export='));
+      const exportFormat = exportFlag ? exportFlag.split('=')[1] : null;
+      if (exportFormat) {
+        log(`${CYAN}  ℹ${RESET} Export flag noted: will export to ${exportFormat} after scan completes`);
+      }
+      break;
+    }
     case "help":
     case "--help":
     case "-h":

package/bin/scan-data-collector.js

@@ -0,0 +1,153 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+function read(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch { return ''; }
+}
+
+function parseDebtSummary(text) {
+  const n = (pattern) => { const m = text.match(pattern); return m ? parseInt(m[1], 10) : 0; };
+  return {
+    debtCritical: n(/Critical items?:\s*(\d+)/i),
+    debtHigh:     n(/High priority:\s*(\d+)/i),
+    debtMedium:   n(/Medium priority:\s*(\d+)/i)
+  };
+}
+
+function parseTestCoverage(text) {
+  const total   = text.match(/Total tests\s*\|\s*(\d+)/i);
+  const passing = text.match(/Passing\s*\|\s*(\d+)/i);
+  if (total && passing) return parseInt(passing[1], 10) + '/' + parseInt(total[1], 10);
+  return 'N/A';
+}
+
+function parseFilesAndLoc(text) {
+  const m = text.match(/\|\s*\*?\*?Total[^|]*\*?\*?\s*\|\s*(\d+)\s+files?\s*\|\s*\*?\*?([\d,]+)[^|]*\*?\*?\s*\|/i);
+  if (m) return { filesScanned: parseInt(m[1], 10), totalLoc: parseInt(m[2].replace(/,/g, ''), 10) };
+  return { filesScanned: 0, totalLoc: 0 };
+}
+
+function parseComponents(text) {
+  const sec = text.match(/## Component Inventory([\s\S]*?)(?=\n## |\n---|\n#[^#]|$)/);
+  if (!sec) return [];
+  return sec[1].split('\n')
+    .filter(l => /^\|/.test(l) && !/---/.test(l) && !/Component.*File/i.test(l))
+    .map(row => {
+      const cols = row.split('|').map(c => c.trim().replace(/\*\*/g, '').replace(/`/g, '')).filter(Boolean);
+      if (cols.length < 3) return null;
+      const name = cols[0];
+      if (!name || /^total/i.test(name)) return null;
+      return { name, filePath: cols[1] || '', size: cols[2] || '', purpose: cols[3] || '', files: 1, healthScore: 80 };
+    })
+    .filter(Boolean);
+}
+
+function parseSeverityMap(text) {
+  const map = {};
+  const high = text.match(/High priority:[^\n]*\(([^)]+)\)/i);
+  if (high) {
+    high[1].split(',').forEach(part => { const m = part.trim().match(/TD-\d+/); if (m) map[m[0]] = 'high'; });
+  }
+  const med = text.match(/Medium priority:[^\n]*\(([^)]+)\)/i);
+  if (med) {
+    med[1].split(',').forEach(part => {
+      const r = part.trim().match(/TD-(\d+)[–\-](\d+)/);
+      if (r) {
+        for (let i = parseInt(r[1]); i <= parseInt(r[2]); i++) {
+          map['TD-' + String(i).padStart(3, '0')] = 'medium';
+        }
+      } else { const m = part.trim().match(/TD-\d+/); if (m) map[m[0]] = 'medium'; }
+    });
+  }
+  return map;
+}
+
+function parseTechDebtItems(qualText, debtText) {
+  if (!qualText) return [];
+  const severityMap = parseSeverityMap(debtText || '');
+  const tableMatch = qualText.match(/\| ID \| Title \| Status \|([\s\S]*?)(?=\n---|\n## |$)/i);
+  if (!tableMatch) return [];
+  return tableMatch[1].split('\n')
+    .filter(l => /^\|/.test(l) && !/---/.test(l) && !/\| ID \|/i.test(l))
+    .map(row => {
+      const cols = row.split('|').map(c => c.trim()).filter(Boolean);
+      if (cols.length < 3) return null;
+      const id = cols[0]; const title = cols[1];
+      if (!cols[2].toUpperCase().includes('OPEN')) return null;
+      return { severity: severityMap[id] || 'low', domain: id, issue: title, location: '', effort: '' };
+    })
+    .filter(Boolean).slice(0, 20);
+}
+
+function parseSecurityFindings(text) {
+  if (!text) return [];
+  const findings = [];
+  for (const sec of text.split(/\n### /).slice(1)) {
+    const titleLine = sec.split('\n')[0];
+    if (!/SEC-[HM]\d+/.test(titleLine)) continue;
+    const idM   = titleLine.match(/(SEC-[HM]\d+)/);
+    const nameM = titleLine.match(/SEC-[HM]\d+:\s*(.+?)(?:\s+[-–][-–]|\s*$)/);
+    const detM  = sec.match(/- \*\*Details\*\*:\s*(.+?)(?=\n-|\n\n|$)/s);
+    const fixM  = sec.match(/- \*\*Fix\*\*:\s*(.+?)(?=\n-|\n\n|$)/s);
+    findings.push({
+      category: /SEC-H/.test(titleLine) ? 'Security' : 'Security',
+      severity: /SEC-H/.test(titleLine) ? 'high' : 'medium',
+      title:    (idM ? idM[1] : '') + (nameM ? ': ' + nameM[1].trim() : ''),
+      description:    detM ? detM[1].trim().replace(/\n/g, ' ') : '',
+      recommendation: fixM ? fixM[1].trim().replace(/\n/g, ' ') : ''
+    });
+  }
+  return findings;
+}
+
+function parseQualityFindings(text) {
+  if (!text) return [];
+  const findings = [];
+  for (const sec of text.split(/\n### /).slice(1)) {
+    const titleLine = sec.split('\n')[0];
+    const idM = titleLine.match(/((?:DC|TCG|TD)-[A-Z\-\d]+)/);
+    const nameM = titleLine.match(/(?:DC|TCG|TD)-[A-Z\-\d]+:\s*(.+?)(?:\s*$)/);
+    const locM = sec.match(/^`([^`]+)`/m);
+    const detM = sec.match(/\n(.+?)\n- \*\*Impact\*\*/s);
+    const sugM = sec.match(/- \*\*Suggestion\*\*:\s*(.+?)(?=\n-|\n\n|$)/s);
+    if (!idM) continue;
+    findings.push({
+      category: 'Quality',
+      severity: 'medium',
+      title:    (idM ? idM[1] : '') + (nameM ? ': ' + nameM[1].trim() : ''),
+      description:    locM ? locM[1] : (detM ? detM[1].trim() : ''),
+      recommendation: sugM ? sugM[1].trim().replace(/\n/g, ' ') : 'Review and schedule remediation'
+    });
+  }
+  return findings.slice(0, 3);
+}
+
+function collectScanData(projectRoot) {
+  const scanDir = path.join(projectRoot, '.gsd-t', 'scan');
+  const rs = (f) => read(path.join(scanDir, f));
+  const rr = (f) => read(path.join(projectRoot, f));
+
+  const archText  = rs('architecture.md');
+  const testText  = rs('test-baseline.md');
+  const secText   = rs('security.md');
+  const qualText  = rs('quality.md');
+  const debtText  = rr('.gsd-t/techdebt.md');
+
+  let projectName = path.basename(projectRoot);
+  try { projectName = JSON.parse(rr('package.json')).name || projectName; } catch {}
+
+  const { filesScanned, totalLoc } = parseFilesAndLoc(archText);
+  const { debtCritical, debtHigh, debtMedium } = parseDebtSummary(debtText);
+  const testCoverage = parseTestCoverage(testText);
+  const domains   = parseComponents(archText);
+  const techDebt  = parseTechDebtItems(qualText, debtText);
+  const secFinds  = parseSecurityFindings(secText);
+  const qualFinds = parseQualityFindings(qualText);
+  const findings  = secFinds.concat(qualFinds).slice(0, 10);
+
+  return { projectName, filesScanned, totalLoc, debtCritical, debtHigh, debtMedium,
+           testCoverage, domains, techDebt, findings };
+}
+
+module.exports = { collectScanData };

package/bin/scan-diagrams-generators.js

@@ -0,0 +1,187 @@
+'use strict';
+
+function genSystemArchitecture(analysisData) {
+  try {
+    const services = (analysisData.services || []).slice(0, 4);
+    if (services.length >= 2) {
+      const lines = ['graph TB',
+        '  classDef user fill:#0d2035,stroke:#06b6d4,color:#a5f3fc',
+        '  classDef svc fill:#1a0f3a,stroke:#7c3aed,color:#ddd6fe',
+        '  classDef db fill:#0a2318,stroke:#10b981,color:#a7f3d0',
+        '  User(["👤 User"]):::user'];
+      services.forEach((s, i) => { lines.push('  S' + i + '["' + s + '"]:::svc'); lines.push('  User --> S' + i); });
+      return lines.join('\n');
+    }
+    return `graph TB
+  classDef user fill:#0d2035,stroke:#06b6d4,color:#a5f3fc
+  classDef app  fill:#0f1d3a,stroke:#3b82f6,color:#bfdbfe
+  classDef api  fill:#1a0f3a,stroke:#7c3aed,color:#ddd6fe
+  classDef db   fill:#0a2318,stroke:#10b981,color:#a7f3d0
+  classDef ext  fill:#111827,stroke:#374151,color:#9ca3af
+  USER(["👤 User\\nweb & mobile"]):::user
+  subgraph PLATFORM["  Application Platform  "]
+    APP["🌐 Frontend\\nUser Interface"]:::app
+    API["⚡ Backend\\nApplication Logic"]:::api
+    DB[("🗃 Database\\nPrimary Store")]:::db
+  end
+  EXT["🌎 External Services\\nAPIs & Integrations"]:::ext
+  USER -->|"HTTPS"| APP
+  APP  -->|"REST / JSON"| API
+  API  -->|"reads / writes"| DB
+  API  -->|"calls"| EXT
+  style PLATFORM fill:#0a0f1e,stroke:#1e3a5f,color:#e2e8f0`;
+  } catch { return 'graph TB\n  App[Application] --> DB[(Database)]'; }
+}
+
+function genAppArchitecture(analysisData) {
+  try {
+    const layers = (analysisData.layers || []).slice(0, 5);
+    if (layers.length >= 3) {
+      const lines = ['graph TB'];
+      const colors = ['#0f1d3a,#3b82f6', '#1a0f3a,#7c3aed', '#0a2318,#10b981', '#1f1505,#f59e0b', '#12102a,#6366f1'];
+      layers.forEach((l, i) => {
+        const [bg, stroke] = colors[i % colors.length].split(',');
+        lines.push(`  L${i}["${l}"]`);
+        lines.push(`  style L${i} fill:${bg},stroke:${stroke},color:#e2e8f0`);
+        if (i > 0) lines.push(`  L${i - 1} --> L${i}`);
+      });
+      return lines.join('\n');
+    }
+    return `graph TB
+  classDef client fill:#0d2035,stroke:#06b6d4,color:#a5f3fc
+  classDef ctrl  fill:#0f1d3a,stroke:#3b82f6,color:#bfdbfe
+  classDef svc   fill:#1a0f3a,stroke:#7c3aed,color:#ddd6fe
+  classDef repo  fill:#1a0f3a,stroke:#8b5cf6,color:#ddd6fe
+  classDef db    fill:#0a2318,stroke:#10b981,color:#a7f3d0
+  subgraph CL["  Clients  "]
+    WEB["🌐 Web App"]:::client
+    MOB["📱 Mobile"]:::client
+  end
+  subgraph CTR["  Controller Layer  "]
+    AC["AuthController"]:::ctrl
+    TC["TasksController"]:::ctrl
+    PC["ProjectsController"]:::ctrl
+  end
+  subgraph SVC["  Service Layer  "]
+    AS["AuthService"]:::svc
+    TS["TasksService"]:::svc
+    PS["ProjectsService"]:::svc
+  end
+  DB[("🗃 Database")]:::db
+  WEB & MOB --> CTR --> SVC --> DB
+  style CL  fill:#080e1a,stroke:#0e2035
+  style CTR fill:#080e1a,stroke:#1e3a5f
+  style SVC fill:#080e1a,stroke:#2d1a5e`;
+  } catch { return 'graph TB\n  subgraph App\n    Controllers --> Services --> Repositories\n  end'; }
+}
+
+function genWorkflow(analysisData) {
+  try {
+    const states = (analysisData.states || []).slice(0, 6);
+    if (states.length >= 3) {
+      const lines = ['stateDiagram-v2', '  direction LR', '  [*] --> ' + states[0]];
+      states.forEach((s, i) => { if (i < states.length - 1) lines.push(`  ${s} --> ${states[i + 1]}`); });
+      lines.push('  ' + states[states.length - 1] + ' --> [*]');
+      return lines.join('\n');
+    }
+    return `stateDiagram-v2
+  direction LR
+  [*] --> Draft : create
+  Draft --> Open        : submit
+  Draft --> [*]         : discard
+  Open --> InProgress   : assign
+  Open --> Cancelled    : cancel
+  InProgress --> Review : mark done
+  InProgress --> Blocked : flag blocker
+  InProgress --> Open   : unassign
+  Blocked --> InProgress : resolve
+  Review --> Done       : approve
+  Review --> InProgress : reject
+  Done --> [*]
+  Cancelled --> [*]
+  note right of Blocked
+    No SLA timeout —
+    can stagnate here
+  end note`;
+  } catch { return 'stateDiagram-v2\n  [*] --> Active\n  Active --> Done\n  Done --> [*]'; }
+}
+
+function genDataFlow(analysisData) {
+  try {
+    const endpoints = (analysisData.endpoints || []).slice(0, 1);
+    const ep = endpoints[0] || 'POST /api/resource';
+    return `flowchart TD
+  classDef user   fill:#0d2035,stroke:#06b6d4,color:#a5f3fc
+  classDef fe     fill:#0f1d3a,stroke:#3b82f6,color:#bfdbfe
+  classDef api    fill:#1a0f3a,stroke:#7c3aed,color:#ddd6fe
+  classDef db     fill:#0a2318,stroke:#10b981,color:#a7f3d0
+  classDef queue  fill:#1f1505,stroke:#f59e0b,color:#fde68a
+  classDef ok     fill:#0a2318,stroke:#10b981,color:#a7f3d0
+  USR(["&#128100; User"]):::user
+  subgraph FE["Frontend"]
+    FORM["Form\\n+ Client Validation"]:::fe
+  end
+  subgraph API["API Server"]
+    PIPE["ValidationPipe\\n+ Sanitize"]:::api
+    CTRL["Controller\\n${ep}"]:::api
+    SVC["Service\\nbusiness logic"]:::api
+    REPO["Repository\\nINSERT / UPDATE"]:::api
+  end
+  DB[("&#128451; Database")]:::db
+  RD[("&#9889; Queue")]:::queue
+  RES(["&#10003; Response"]):::ok
+  USR --> FORM --> PIPE --> CTRL --> SVC --> REPO --> DB
+  SVC --> RD
+  DB --> RES
+  style FE  fill:#080e1a,stroke:#1e3a5f
+  style API fill:#080e1a,stroke:#2d1a5e`;
+  } catch { return 'flowchart TD\n  Input --> Validate --> Process --> Store --> Respond'; }
+}
+
+function genSequence(analysisData) {
+  try {
+    const ep = ((analysisData.endpoints || [])[0]) || 'POST /api/resource';
+    return `sequenceDiagram
+  autonumber
+  actor User
+  participant Client
+  participant API as API Server
+  participant DB as Database
+  participant Queue
+  User->>Client: Submit form
+  Client->>API: ${ep}
+  API->>API: validate &amp; sanitize
+  alt invalid input
+    API-->>Client: 400 Bad Request
+  else valid
+    API->>DB: INSERT record
+    DB-->>API: record id
+    API->>Queue: enqueue background job
+    API-->>Client: 201 Created
+    Client-->>User: Success feedback
+  end`;
+  } catch { return 'sequenceDiagram\n  Client->>Server: Request\n  Server->>DB: Query\n  DB-->>Server: Result\n  Server-->>Client: Response'; }
+}
+
+function genDatabaseSchema(schemaData) {
+  try {
+    if (!schemaData || !schemaData.detected || !schemaData.entities || schemaData.entities.length === 0) return '';
+    const relMap = { 'one-to-many': '||--o{', 'many-to-one': '}o--||', 'many-to-many': '}o--o{', 'one-to-one': '||--||' };
+    const lines = ['erDiagram'];
+    for (const entity of schemaData.entities.slice(0, 8)) {
+      lines.push('  ' + entity.name + ' {');
+      for (const f of (entity.fields || []).slice(0, 10)) {
+        lines.push('    ' + (f.type || 'string') + ' ' + f.name);
+      }
+      lines.push('  }');
+    }
+    for (const entity of schemaData.entities) {
+      for (const rel of (entity.relations || [])) {
+        lines.push('  ' + rel.fromEntity + ' ' + (relMap[rel.type] || '||--o{') + ' ' + rel.toEntity + ' : "has"');
+      }
+    }
+    return lines.join('\n');
+  } catch { return ''; }
+}
+
+module.exports = { genSystemArchitecture, genAppArchitecture, genWorkflow, genDataFlow, genSequence, genDatabaseSchema };

package/bin/scan-diagrams.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const {
+  genSystemArchitecture,
+  genAppArchitecture,
+  genWorkflow,
+  genDataFlow,
+  genSequence,
+  genDatabaseSchema
+} = require('./scan-diagrams-generators');
+
+const PLACEHOLDER_HTML = '<div class="diagram-placeholder">\n  <p>Diagram unavailable — rendering tools not found</p>\n  <p>Install: <code>npm install -g @mermaid-js/mermaid-cli</code></p>\n</div>';
+
+const NOTES = {
+  'system-architecture': 'C4-style context diagram showing services, databases, and external integrations',
+  'app-architecture':    'Layered diagram showing framework architecture and component boundaries',
+  'workflow':            'State machine derived from status enums and state transition logic',
+  'data-flow':           'Data flow from user input through validation, persistence, and async processing',
+  'sequence':            'Request/response sequence for the primary API endpoint',
+  'database-schema':     'Schema diagram generated from ORM, document DB, vector store, or raw SQL definitions'
+};
+
+const DIAGRAM_DEFS = [
+  { type: 'system-architecture', title: 'System Architecture',     typeBadge: 'graph TB',       gen: (a) => genSystemArchitecture(a) },
+  { type: 'app-architecture',    title: 'Application Architecture', typeBadge: 'graph TB',       gen: (a) => genAppArchitecture(a) },
+  { type: 'workflow',            title: 'Workflow',                 typeBadge: 'stateDiagram-v2', gen: (a) => genWorkflow(a) },
+  { type: 'data-flow',           title: 'Data Flow',                typeBadge: 'flowchart TD',   gen: (a) => genDataFlow(a) },
+  { type: 'sequence',            title: 'Sequence',                 typeBadge: 'sequenceDiagram', gen: (a) => genSequence(a) },
+  { type: 'database-schema',     title: 'Database Schema',          typeBadge: 'erDiagram',      gen: (_, s) => genDatabaseSchema(s) }
+];
+
+function buildPlaceholder(def, mmd) {
+  return {
+    type: def.type,
+    title: def.title,
+    typeBadge: def.typeBadge,
+    svgContent: PLACEHOLDER_HTML,
+    mmdSource: mmd || '',
+    note: NOTES[def.type] || '',
+    rendered: false,
+    rendererUsed: 'placeholder'
+  };
+}
+
+function generateDiagrams(analysisData, schemaData, options) {
+  try {
+    const { renderDiagram } = require('./scan-renderer');
+    const results = [];
+    for (const def of DIAGRAM_DEFS) {
+      try {
+        const mmd = def.gen(analysisData, schemaData);
+        const isDbSchema = def.type === 'database-schema';
+        const noSchema = !schemaData || !schemaData.detected || !mmd;
+        if (isDbSchema && noSchema) {
+          results.push(buildPlaceholder(def, ''));
+        } else {
+          const rendered = renderDiagram(mmd, def.type, options || {});
+          results.push({
+            type: def.type,
+            title: def.title,
+            typeBadge: def.typeBadge,
+            svgContent: rendered.svgContent,
+            mmdSource: mmd,
+            note: NOTES[def.type] || '',
+            rendered: rendered.rendered,
+            rendererUsed: rendered.rendererUsed
+          });
+        }
+      } catch {
+        results.push(buildPlaceholder(def, ''));
+      }
+    }
+    return results;
+  } catch {
+    return DIAGRAM_DEFS.map(def => buildPlaceholder(def));
+  }
+}
+
+module.exports = { generateDiagrams };

package/bin/scan-export.js

@@ -0,0 +1,49 @@
+'use strict';
+const { execSync } = require('child_process');
+const path = require('path');
+
+function detectTool(cmd) {
+  try {
+    const check = process.platform === 'win32' ? 'where "' + cmd + '"' : 'which "' + cmd + '"';
+    execSync(check, { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch { return false; }
+}
+
+function detectMdToPdf() {
+  try { execSync('npx md-to-pdf --version', { stdio: 'pipe', timeout: 10000 }); return true; }
+  catch { return false; }
+}
+
+function exportToDocx(htmlPath) {
+  try {
+    const outputPath = htmlPath.replace(/\.html$/, '.docx');
+    execSync('pandoc "' + htmlPath + '" -o "' + outputPath + '" --from=html', { timeout: 60000 });
+    return { success: true, outputPath };
+  } catch (err) { return { success: false, error: err.message }; }
+}
+
+function exportToPdf(htmlPath) {
+  try {
+    const outputPath = htmlPath.replace(/\.html$/, '.pdf');
+    execSync('npx md-to-pdf "' + htmlPath + '" --output "' + outputPath + '"', { timeout: 120000 });
+    return { success: true, outputPath };
+  } catch (err) { return { success: false, error: err.message }; }
+}
+
+function exportReport(htmlPath, format, options) {
+  try {
+    if (format !== 'docx' && format !== 'pdf') {
+      return { success: false, error: 'Unknown export format: ' + format + '. Use docx or pdf.' };
+    }
+    if (format === 'docx' && !detectTool('pandoc')) {
+      return { success: false, skipped: true, reason: 'Pandoc not found. Install: https://pandoc.org/installing.html' };
+    }
+    if (format === 'pdf' && !detectMdToPdf()) {
+      return { success: false, skipped: true, reason: 'md-to-pdf not found. Install: npm install -g md-to-pdf' };
+    }
+    return format === 'docx' ? exportToDocx(htmlPath, options) : exportToPdf(htmlPath, options);
+  } catch (err) { return { success: false, error: err.message }; }
+}
+
+module.exports = { exportReport };

package/bin/scan-renderer.js

@@ -0,0 +1,92 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const https = require('https');
+
+const PLACEHOLDER_HTML = '<div class="diagram-placeholder">\n  <p>Diagram unavailable — rendering tools not found</p>\n  <p>Install: <code>npm install -g @mermaid-js/mermaid-cli</code></p>\n</div>';
+
+function stripSvgDimensions(svgStr) {
+  return svgStr
+    .replace(/<svg([^>]*)\s+width="[^"]*"/, '<svg$1')
+    .replace(/<svg([^>]*)\s+height="[^"]*"/, '<svg$1');
+}
+
+function makePlaceholder() {
+  return PLACEHOLDER_HTML;
+}
+
+function tryMmdc(mmdContent) {
+  const ts = Date.now();
+  const tmpIn = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.mmd');
+  const tmpOut = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.svg');
+  try {
+    fs.writeFileSync(tmpIn, mmdContent, 'utf8');
+    execSync('mmdc -i "' + tmpIn + '" -o "' + tmpOut + '" -t dark --quiet', { timeout: 30000, stdio: 'pipe' });
+    const svg = fs.readFileSync(tmpOut, 'utf8');
+    return { svgContent: stripSvgDimensions(svg), rendered: true, rendererUsed: 'mermaid-cli' };
+  } catch { return null; }
+  finally {
+    try { fs.unlinkSync(tmpIn); } catch {}
+    try { fs.unlinkSync(tmpOut); } catch {}
+  }
+}
+
+function tryD2(mmdContent, type) {
+  if (type !== 'system-architecture' && type !== 'data-flow') return null;
+  const ts = Date.now();
+  const tmpIn = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.d2');
+  const tmpOut = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.svg');
+  try {
+    fs.writeFileSync(tmpIn, 'app -> db: query', 'utf8');
+    execSync('d2 "' + tmpIn + '" "' + tmpOut + '" --layout=dagre', { timeout: 30000, stdio: 'pipe' });
+    const svg = fs.readFileSync(tmpOut, 'utf8');
+    return { svgContent: stripSvgDimensions(svg), rendered: true, rendererUsed: 'd2' };
+  } catch { return null; }
+  finally {
+    try { fs.unlinkSync(tmpIn); } catch {}
+    try { fs.unlinkSync(tmpOut); } catch {}
+  }
+}
+
+function tryKroki(mmdContent) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify({ diagram_source: mmdContent });
+    const host = process.env.KROKI_HOST || 'kroki.io';
+    const options = {
+      hostname: host, port: 443,
+      path: '/mermaid/svg', method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+      timeout: 15000
+    };
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', c => { data += c; });
+      res.on('end', () => {
+        if (data.trimStart().startsWith('<svg')) {
+          resolve({ svgContent: stripSvgDimensions(data), rendered: true, rendererUsed: 'kroki' });
+        } else { resolve(null); }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.write(body);
+    req.end();
+  });
+}
+
+function renderDiagram(mmdContent, type, options) {
+  try {
+    const mmdc = tryMmdc(mmdContent);
+    if (mmdc) return mmdc;
+    const d2 = tryD2(mmdContent, type);
+    if (d2) return d2;
+    // tryKroki is async; skip in sync rendering path — Kroki available via async wrapper if needed
+    return { svgContent: makePlaceholder(), rendered: false, rendererUsed: 'placeholder' };
+  } catch {
+    return { svgContent: makePlaceholder(), rendered: false, rendererUsed: 'placeholder' };
+  }
+}
+
+module.exports = { renderDiagram };