markupr 2.1.8 → 2.4.0

package/dist/cli/index.mjs

@@ -0,0 +1,2000 @@
+#!/usr/bin/env node
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/cli/index.ts
+import { existsSync as existsSync4 } from "fs";
+import { resolve } from "path";
+import { Command } from "commander";
+
+// src/cli/CLIPipeline.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2 } from "fs";
+import { stat, unlink as unlink2, writeFile, chmod as chmod2 } from "fs/promises";
+import { join as join3, basename as basename2 } from "path";
+import { execFile as execFileCb2 } from "child_process";
+import { tmpdir as tmpdir2 } from "os";
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/main/pipeline/TranscriptAnalyzer.ts
+var PAUSE_THRESHOLD_SECONDS = 1.5;
+var PERIODIC_INTERVAL_SECONDS = 15;
+var MAX_PERIODIC_INTERVAL_SECONDS = 20;
+var MAX_KEY_MOMENTS = 20;
+var FRAME_EDGE_MARGIN_SECONDS = 0.35;
+var TranscriptAnalyzer = class {
+  /**
+   * Analyze transcript segments and return key moments where frames
+   * should be extracted from the video recording.
+   *
+   * @param segments - Array of transcript segments with timing info
+   * @param aiHints - Optional AI-informed key-moment hints to merge
+   * @returns Array of key moments sorted by timestamp, capped at 20
+   */
+  analyze(segments, aiHints = []) {
+    if (segments.length === 0) {
+      return [];
+    }
+    const moments = [];
+    const firstSegment = segments[0];
+    const lastSegment = segments[segments.length - 1];
+    const sessionDuration = lastSegment.endTime - firstSegment.startTime;
+    const startOffset = sessionDuration > FRAME_EDGE_MARGIN_SECONDS ? FRAME_EDGE_MARGIN_SECONDS : 0;
+    moments.push({
+      timestamp: firstSegment.startTime + startOffset,
+      reason: "Session start",
+      confidence: 1
+    });
+    for (let i = 1; i < segments.length; i++) {
+      const prev = segments[i - 1];
+      const curr = segments[i];
+      const gap = curr.startTime - prev.endTime;
+      if (gap >= PAUSE_THRESHOLD_SECONDS) {
+        moments.push({
+          timestamp: prev.endTime,
+          reason: "Natural pause in narration",
+          confidence: Math.min(1, gap / 3)
+          // Longer pauses = higher confidence
+        });
+      }
+    }
+    if (lastSegment.endTime > firstSegment.startTime + startOffset) {
+      moments.push({
+        timestamp: lastSegment.endTime,
+        reason: "Session end",
+        confidence: 1
+      });
+    }
+    if (moments.length < 3 && aiHints.length === 0) {
+      if (sessionDuration > PERIODIC_INTERVAL_SECONDS) {
+        const rawCount = Math.floor(sessionDuration / PERIODIC_INTERVAL_SECONDS);
+        const interval = Math.min(
+          sessionDuration / rawCount,
+          MAX_PERIODIC_INTERVAL_SECONDS
+        );
+        for (let t = firstSegment.startTime + interval; t < lastSegment.endTime; t += interval) {
+          moments.push({
+            timestamp: t,
+            reason: "Periodic capture",
+            confidence: 0.5
+          });
+        }
+      }
+    }
+    for (const hint of aiHints) {
+      if (!Number.isFinite(hint.timestamp)) {
+        continue;
+      }
+      moments.push({
+        timestamp: Math.max(0, hint.timestamp),
+        reason: hint.reason?.trim() || "AI-highlighted context",
+        confidence: Math.max(0, Math.min(1, Number.isFinite(hint.confidence) ? hint.confidence : 0.8))
+      });
+    }
+    const deduped = this.deduplicateMoments(moments);
+    deduped.sort((a, b) => a.timestamp - b.timestamp);
+    if (deduped.length > MAX_KEY_MOMENTS) {
+      const first = deduped[0];
+      const last = deduped[deduped.length - 1];
+      const middle = deduped.slice(1, -1).sort((a, b) => {
+        const priorityDelta = this.momentPriority(b) - this.momentPriority(a);
+        if (priorityDelta !== 0) {
+          return priorityDelta;
+        }
+        return b.confidence - a.confidence;
+      }).slice(0, MAX_KEY_MOMENTS - 2);
+      const capped = [first, ...middle, last];
+      capped.sort((a, b) => a.timestamp - b.timestamp);
+      return capped;
+    }
+    return deduped;
+  }
+  /**
+   * Remove moments that are within 1 second of each other,
+   * keeping the one with higher confidence.
+   */
+  deduplicateMoments(moments) {
+    if (moments.length <= 1) {
+      return moments;
+    }
+    const sorted = [...moments].sort((a, b) => a.timestamp - b.timestamp);
+    const result = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+      const prev = result[result.length - 1];
+      const curr = sorted[i];
+      if (curr.timestamp - prev.timestamp < 1) {
+        const currPriority = this.momentPriority(curr);
+        const prevPriority = this.momentPriority(prev);
+        if (currPriority > prevPriority || currPriority === prevPriority && curr.confidence > prev.confidence) {
+          result[result.length - 1] = curr;
+        }
+      } else {
+        result.push(curr);
+      }
+    }
+    return result;
+  }
+  momentPriority(moment) {
+    const reason = (moment.reason || "").toLowerCase();
+    if (reason.includes("session start") || reason.includes("session end")) {
+      return 4;
+    }
+    if (reason.includes("ai-") || reason.includes("ai ")) {
+      return 3;
+    }
+    if (reason.includes("natural pause")) {
+      return 2;
+    }
+    if (reason.includes("periodic")) {
+      return 0;
+    }
+    return 1;
+  }
+};
+var transcriptAnalyzer = new TranscriptAnalyzer();
+
+// src/main/pipeline/FrameExtractor.ts
+import { execFile as execFileCb } from "child_process";
+import { promisify } from "util";
+import { existsSync, mkdirSync } from "fs";
+import { stat as statFile } from "fs/promises";
+import { join } from "path";
+var execFile = promisify(execFileCb);
+var DEFAULT_MAX_FRAMES = 20;
+var FFMPEG_ACCURATE_FRAME_TIMEOUT_MS = 2e4;
+var FFMPEG_FAST_FRAME_TIMEOUT_MS = 1e4;
+var FFMPEG_CHECK_TIMEOUT_MS = 5e3;
+var FRAME_EDGE_MARGIN_SECONDS2 = 0.35;
+var TIMESTAMP_DEDUPE_WINDOW_SECONDS = 0.15;
+var SAFE_CHILD_ENV = {
+  PATH: process.env.PATH,
+  HOME: process.env.HOME || process.env.USERPROFILE,
+  USERPROFILE: process.env.USERPROFILE,
+  LANG: process.env.LANG,
+  TMPDIR: process.env.TMPDIR || process.env.TEMP,
+  TEMP: process.env.TEMP
+};
+var FrameExtractor = class {
+  ffmpegPath = "ffmpeg";
+  ffprobePath = "ffprobe";
+  ffmpegChecked = false;
+  ffmpegAvailable = false;
+  /**
+   * Check if ffmpeg is installed and accessible on the system PATH.
+   * Result is cached after the first successful check.
+   */
+  async checkFfmpeg() {
+    if (this.ffmpegChecked) {
+      return this.ffmpegAvailable;
+    }
+    try {
+      await execFile(this.ffmpegPath, ["-version"], {
+        timeout: FFMPEG_CHECK_TIMEOUT_MS,
+        env: SAFE_CHILD_ENV
+      });
+      this.ffmpegAvailable = true;
+      this.log("ffmpeg is available");
+    } catch {
+      this.ffmpegAvailable = false;
+      this.log("ffmpeg is not available - frame extraction will be skipped");
+    }
+    this.ffmpegChecked = true;
+    return this.ffmpegAvailable;
+  }
+  /**
+   * Extract frames from a video file at the specified timestamps.
+   *
+   * @param request - Extraction parameters (video path, timestamps, output dir)
+   * @returns Result with extracted frame paths and ffmpeg availability status
+   */
+  async extract(request) {
+    const available = await this.checkFfmpeg();
+    if (!available) {
+      return { frames: [], ffmpegAvailable: false };
+    }
+    const maxFrames = request.maxFrames ?? DEFAULT_MAX_FRAMES;
+    let timestamps = [...request.timestamps].sort((a, b) => a - b);
+    if (timestamps.length > maxFrames) {
+      timestamps = this.selectDistributed(timestamps, maxFrames);
+    }
+    const videoDurationSeconds = await this.getVideoDurationSeconds(request.videoPath);
+    timestamps = this.normalizeTimestamps(timestamps, videoDurationSeconds);
+    if (timestamps.length === 0) {
+      return { frames: [], ffmpegAvailable: true };
+    }
+    const screenshotsDir = join(request.outputDir, "screenshots");
+    if (!existsSync(screenshotsDir)) {
+      mkdirSync(screenshotsDir, { recursive: true });
+    }
+    const frames = [];
+    for (let i = 0; i < timestamps.length; i++) {
+      const timestamp = timestamps[i];
+      const frameNumber = String(i + 1).padStart(3, "0");
+      const outputPath = join(screenshotsDir, `frame-${frameNumber}.png`);
+      try {
+        await this.extractSingleFrame(request.videoPath, timestamp, outputPath);
+        const stats = await statFile(outputPath).catch(() => null);
+        if (!stats || stats.size <= 0) {
+          throw new Error(`ffmpeg did not produce a frame file at timestamp ${timestamp.toFixed(1)}s. The video may be shorter than expected or the codec may not support seeking.`);
+        }
+        frames.push({
+          path: outputPath,
+          timestamp,
+          success: true
+        });
+        this.log(`Extracted frame ${frameNumber} at ${timestamp.toFixed(2)}s`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.log(`Failed to extract frame at ${timestamp.toFixed(2)}s: ${message}`);
+        frames.push({
+          path: outputPath,
+          timestamp,
+          success: false
+        });
+      }
+    }
+    return { frames, ffmpegAvailable: true };
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  /**
+   * Extract a single frame from the video at the given timestamp.
+   */
+  async extractSingleFrame(videoPath, timestamp, outputPath) {
+    try {
+      await this.extractSingleFrameAccurate(videoPath, timestamp, outputPath);
+      return;
+    } catch (accurateError) {
+      this.log(
+        `Accurate extraction failed at ${timestamp.toFixed(2)}s, retrying fast seek: ${accurateError instanceof Error ? accurateError.message : String(accurateError)}`
+      );
+    }
+    await this.extractSingleFrameFast(videoPath, timestamp, outputPath);
+  }
+  async extractSingleFrameAccurate(videoPath, timestamp, outputPath) {
+    const args = [
+      "-i",
+      videoPath,
+      "-ss",
+      String(timestamp),
+      "-frames:v",
+      "1",
+      "-vf",
+      "format=rgb24",
+      "-q:v",
+      "2",
+      "-y",
+      outputPath
+    ];
+    await execFile(this.ffmpegPath, args, {
+      timeout: FFMPEG_ACCURATE_FRAME_TIMEOUT_MS,
+      env: SAFE_CHILD_ENV
+    });
+  }
+  async extractSingleFrameFast(videoPath, timestamp, outputPath) {
+    const args = [
+      "-ss",
+      String(timestamp),
+      "-i",
+      videoPath,
+      "-frames:v",
+      "1",
+      "-vf",
+      "format=rgb24",
+      "-q:v",
+      "2",
+      "-y",
+      // overwrite output file if it exists
+      outputPath
+    ];
+    await execFile(this.ffmpegPath, args, {
+      timeout: FFMPEG_FAST_FRAME_TIMEOUT_MS,
+      env: SAFE_CHILD_ENV
+    });
+  }
+  /**
+   * Select evenly distributed timestamps from a sorted array.
+   * Always includes the first and last timestamp.
+   */
+  selectDistributed(sorted, count) {
+    if (sorted.length <= count) {
+      return sorted;
+    }
+    if (count <= 0) {
+      return [];
+    }
+    if (count === 1) {
+      return [sorted[0]];
+    }
+    const result = [sorted[0]];
+    const step2 = (sorted.length - 1) / (count - 1);
+    for (let i = 1; i < count - 1; i++) {
+      const index = Math.round(i * step2);
+      result.push(sorted[index]);
+    }
+    result.push(sorted[sorted.length - 1]);
+    return result;
+  }
+  async getVideoDurationSeconds(videoPath) {
+    try {
+      const { stdout } = await execFile(
+        this.ffprobePath,
+        [
+          "-v",
+          "error",
+          "-show_entries",
+          "format=duration",
+          "-of",
+          "default=noprint_wrappers=1:nokey=1",
+          videoPath
+        ],
+        { timeout: FFMPEG_CHECK_TIMEOUT_MS, env: SAFE_CHILD_ENV }
+      );
+      const parsed = Number.parseFloat(String(stdout).trim());
+      if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
+      }
+      return null;
+    } catch (error) {
+      this.log(`ffprobe duration probe failed: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+  }
+  normalizeTimestamps(timestamps, durationSeconds) {
+    const cleaned = timestamps.map((timestamp) => Number.isFinite(timestamp) ? Math.max(0, timestamp) : 0).sort((a, b) => a - b);
+    if (cleaned.length === 0) {
+      return [];
+    }
+    let clamped = cleaned;
+    if (durationSeconds && durationSeconds > 0) {
+      const minTs = Math.min(FRAME_EDGE_MARGIN_SECONDS2, Math.max(0, durationSeconds - 0.05));
+      const maxTs = Math.max(minTs, durationSeconds - FRAME_EDGE_MARGIN_SECONDS2);
+      clamped = cleaned.map((timestamp) => Math.max(minTs, Math.min(timestamp, maxTs)));
+    }
+    const deduped = [];
+    for (const timestamp of clamped) {
+      const previous = deduped[deduped.length - 1];
+      if (previous === void 0 || Math.abs(timestamp - previous) >= TIMESTAMP_DEDUPE_WINDOW_SECONDS) {
+        deduped.push(timestamp);
+      }
+    }
+    return deduped;
+  }
+  /**
+   * Log helper with consistent prefix.
+   */
+  log(message) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    console.log(`[FrameExtractor ${timestamp}] ${message}`);
+  }
+};
+var frameExtractor = new FrameExtractor();
+
+// src/main/output/MarkdownGenerator.ts
+import * as path from "path";
+var REPORT_SUPPORT_LINE = "*If this report saved you time, support development: [Ko-fi](https://ko-fi.com/eddiesanjuan)*";
+var MarkdownGeneratorImpl = class {
+  /**
+   * Generate a full markdown document with all feedback items and metadata.
+   * Follows llms.txt-inspired format for AI readability.
+   */
+  generateFullDocument(session, options) {
+    const { projectName, screenshotDir } = options;
+    const items = session.feedbackItems;
+    const duration = session.endTime ? this.formatDuration(session.endTime - session.startTime) : "In Progress";
+    const timestamp = this.formatTimestamp(session.endTime || Date.now());
+    const filename = this.generateFilename(projectName, session.startTime);
+    if (items.length === 0) {
+      const content2 = `# ${projectName} Feedback Report
+> Generated by markupr on ${timestamp}
+> Duration: ${duration}
+
+_No feedback items were captured during this session._
+
+---
+*Generated by [markupr](https://markupr.com)*
+${REPORT_SUPPORT_LINE}
+`;
+      return {
+        content: content2,
+        filename,
+        metadata: {
+          itemCount: 0,
+          screenshotCount: 0,
+          duration: session.endTime ? session.endTime - session.startTime : 0,
+          types: {}
+        }
+      };
+    }
+    const typeCounts = this.countTypes(items);
+    const severityCounts = this.countSeverities(items);
+    const screenshotCount = this.countScreenshots(items);
+    const topThemes = this.extractTopThemes(items);
+    const highImpactCount = (severityCounts.Critical || 0) + (severityCounts.High || 0);
+    const platform = session.metadata?.os || process?.platform || "Unknown";
+    let content = `# ${projectName} Feedback Report
+> Generated by markupr on ${timestamp}
+> Duration: ${duration} | Items: ${items.length} | Screenshots: ${screenshotCount}
+
+## Session Overview
+- **Session ID:** \`${session.id}\`
+- **Source:** ${session.metadata?.sourceName || "Unknown"} (${session.metadata?.sourceType || "screen"})
+- **Platform:** ${platform}
+- **Segments:** ${items.length}
+- **High-impact items:** ${highImpactCount}
+
+---
+
+## Executive Summary
+
+- ${items.length} total feedback items were captured.
+- ${highImpactCount} items are categorized as **Critical** or **High** priority.
+- ${screenshotCount} screenshots were aligned to spoken context.
+`;
+    if (topThemes.length > 0) {
+      content += `- Top themes: ${topThemes.join(", ")}.
+`;
+    }
+    content += `
+---
+
+## Actionable Feedback
+
+`;
+    items.forEach((item, index) => {
+      const id = this.generateFeedbackItemId(index);
+      const title = item.title || this.generateTitle(item.transcription);
+      const itemTimestamp = this.formatItemTimestamp(item.timestamp - session.startTime);
+      const category = item.category || "General";
+      const severity = item.severity || this.defaultSeverityForCategory(category);
+      const signals = item.keywords?.slice(0, 5) || [];
+      const suggestedAction = this.suggestAction(category, severity, item.transcription);
+      content += `### ${id}: ${title}
+- **Severity:** ${severity}
+- **Type:** ${category}
+- **Timestamp:** ${itemTimestamp}
+`;
+      if (signals.length > 0) {
+        content += `- **Signals:** ${signals.join(", ")}
+`;
+      }
+      content += `
+#### What Happened
+
+> ${this.wrapTranscription(item.transcription)}
+
+`;
+      if (item.screenshots.length > 0) {
+        content += `#### Evidence
+`;
+        item.screenshots.forEach((ss, ssIndex) => {
+          const screenshotFilename = this.generateScreenshotFilename(index, ssIndex, item.screenshots.length);
+          content += `![${id}${item.screenshots.length > 1 ? `-${ssIndex + 1}` : ""}](${screenshotDir}/${screenshotFilename})
+
+`;
+        });
+      } else {
+        content += `#### Evidence
+_No screenshot captured for this item._
+
+`;
+      }
+      content += `#### Suggested Next Step
+- ${suggestedAction}
+
+`;
+      content += `---
+
+`;
+    });
+    content += `## Summary
+
+| Type | Count |
+|------|-------|
+`;
+    Object.entries(typeCounts).forEach(([type, count]) => {
+      content += `| ${type} | ${count} |
+`;
+    });
+    content += `| **Total** | **${items.length}** |
+`;
+    content += `
+| Severity | Count |
+|----------|-------|
+`;
+    Object.entries(severityCounts).forEach(([severity, count]) => {
+      content += `| ${severity} | ${count} |
+`;
+    });
+    content += `| **Total** | **${items.length}** |
+`;
+    content += `
+---
+*Generated by [markupr](https://markupr.com)*
+${REPORT_SUPPORT_LINE}
+`;
+    return {
+      content,
+      filename,
+      metadata: {
+        itemCount: items.length,
+        screenshotCount,
+        duration: session.endTime ? session.endTime - session.startTime : 0,
+        types: typeCounts
+      }
+    };
+  }
+  /**
+   * Generate markdown from a PostProcessResult (post-recording pipeline output).
+   *
+   * Produces a clean, AI-readable document with:
+   * - Session header with human-readable timestamp
+   * - Each transcript segment as a heading with [M:SS] timestamp
+   * - Blockquoted transcript text
+   * - Associated frame images referenced as relative paths
+   *
+   * @param result - The combined transcript + frame output from PostProcessor
+   * @param sessionDir - Absolute path to the session directory (used to compute relative frame paths)
+   * @returns The generated markdown string
+   */
+  generateFromPostProcess(result, sessionDir) {
+    const { transcriptSegments, extractedFrames } = result;
+    const sessionTimestamp = this.formatDateDeterministic(/* @__PURE__ */ new Date());
+    const sessionDuration = transcriptSegments.length > 0 ? this.formatDuration(
+      (transcriptSegments[transcriptSegments.length - 1].endTime - transcriptSegments[0].startTime) * 1e3
+    ) : "0:00";
+    let md = `# markupr Session \u2014 ${sessionTimestamp}
+`;
+    md += `> Segments: ${transcriptSegments.length} | Frames: ${extractedFrames.length} | Duration: ${sessionDuration}
+
+`;
+    if (transcriptSegments.length === 0) {
+      md += `_No speech was detected during this recording._
+`;
+      return md;
+    }
+    md += `## Transcript
+
+`;
+    const segmentFrameMap = this.mapFramesToSegments(transcriptSegments, extractedFrames);
+    for (let i = 0; i < transcriptSegments.length; i++) {
+      const segment = transcriptSegments[i];
+      const formattedTime = this.formatPostProcessTimestamp(segment.startTime);
+      const title = this.generateSegmentTitle(segment.text);
+      md += `### [${formattedTime}] ${title}
+`;
+      md += `> ${this.wrapTranscription(segment.text)}
+
+`;
+      const frames = segmentFrameMap.get(i);
+      if (frames && frames.length > 0) {
+        for (const frame of frames) {
+          const frameTimestamp = this.formatPostProcessTimestamp(frame.timestamp);
+          const relativePath = this.computeRelativeFramePath(frame.path, sessionDir);
+          md += `![Frame at ${frameTimestamp}](${relativePath})
+
+`;
+        }
+      }
+    }
+    md += `---
+*Generated by [markupr](https://markupr.com)*
+${REPORT_SUPPORT_LINE}
+`;
+    return md;
+  }
+  /**
+   * Map extracted frames to their closest transcript segments.
+   * Returns a Map from segment index to an array of frames.
+   */
+  mapFramesToSegments(segments, frames) {
+    const map = /* @__PURE__ */ new Map();
+    for (const frame of frames) {
+      let bestIndex = 0;
+      let bestDistance = Infinity;
+      for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (frame.timestamp >= seg.startTime && frame.timestamp <= seg.endTime) {
+          bestIndex = i;
+          bestDistance = 0;
+          break;
+        }
+        const distance = Math.abs(frame.timestamp - seg.startTime);
+        if (distance < bestDistance) {
+          bestDistance = distance;
+          bestIndex = i;
+        }
+      }
+      const existing = map.get(bestIndex) || [];
+      existing.push(frame);
+      map.set(bestIndex, existing);
+    }
+    for (const [, frameList] of map) {
+      frameList.sort((a, b) => a.timestamp - b.timestamp);
+    }
+    return map;
+  }
+  /**
+   * Compute a relative path for a frame image from the session directory.
+   * If the frame path is already relative, return it as-is.
+   * If absolute, compute the relative path from sessionDir.
+   */
+  computeRelativeFramePath(framePath, sessionDir) {
+    if (!path.isAbsolute(framePath)) {
+      return framePath;
+    }
+    return path.relative(sessionDir, framePath);
+  }
+  /**
+   * Format a timestamp in seconds to M:SS format for post-process output.
+   * Examples: 0 -> "0:00", 15.3 -> "0:15", 125 -> "2:05"
+   */
+  formatPostProcessTimestamp(seconds) {
+    const totalSeconds = Math.max(0, Math.floor(seconds));
+    const mins = Math.floor(totalSeconds / 60);
+    const secs = totalSeconds % 60;
+    return `${mins}:${secs.toString().padStart(2, "0")}`;
+  }
+  /**
+   * Generate a short title from transcript text (first sentence, max 60 chars).
+   */
+  generateSegmentTitle(text) {
+    const firstSentence = text.split(/[.!?]/)[0].trim();
+    if (firstSentence.length <= 60) return firstSentence;
+    return firstSentence.slice(0, 57) + "...";
+  }
+  /**
+   * Generate a clipboard-friendly summary (<1500 chars).
+   * Includes priority items and a reference to the full report.
+   *
+   * @param session - Session data
+   * @param projectName - Optional project name for the header
+   * @param reportPath - Optional absolute or relative path to the full report file.
+   *                     When provided, the summary links to this path instead of the
+   *                     generic ./feedback-report.md placeholder.
+   */
+  generateClipboardSummary(session, projectName, reportPath) {
+    const name = projectName || session.metadata?.sourceName || "Project";
+    const items = session.feedbackItems;
+    let summary = `# Feedback: ${name} - ${items.length} items
+
+`;
+    const maxPriorityItems = 3;
+    summary += `## Priority Items
+`;
+    items.slice(0, maxPriorityItems).forEach((item, index) => {
+      const id = this.generateFeedbackItemId(index);
+      const title = this.generateTitle(item.transcription);
+      const oneLineSummary = this.truncateText(item.transcription, 60);
+      summary += `- **${id}:** ${title} - ${oneLineSummary}
+`;
+    });
+    if (items.length > maxPriorityItems) {
+      const remainingIds = items.slice(maxPriorityItems).map((_, i) => this.generateFeedbackItemId(i + maxPriorityItems)).join(", ");
+      summary += `
+## Other
+- ${remainingIds} (see full report)
+`;
+    }
+    summary += `
+**Full report:** ${reportPath || "./feedback-report.md"}`;
+    if (summary.length > 1500) {
+      summary = summary.slice(0, 1497) + "...";
+    }
+    return summary;
+  }
+  /**
+   * Generate a feedback item ID (FB-001, FB-002, etc.)
+   */
+  generateFeedbackItemId(index) {
+    return `FB-${(index + 1).toString().padStart(3, "0")}`;
+  }
+  // ==========================================================================
+  // Private Helper Methods
+  // ==========================================================================
+  /**
+   * Generate a title from the transcription (first sentence or 50 chars)
+   */
+  generateTitle(transcription) {
+    const firstSentence = transcription.split(/[.!?]/)[0].trim();
+    if (firstSentence.length <= 50) return firstSentence;
+    return firstSentence.slice(0, 47) + "...";
+  }
+  /**
+   * Truncate text to specified length
+   */
+  truncateText(text, maxLength) {
+    if (text.length <= maxLength) return text;
+    return text.slice(0, maxLength - 3) + "...";
+  }
+  /**
+   * Wrap transcription for markdown blockquote (handle multi-line).
+   * Splits on sentence-ending punctuation followed by whitespace so that
+   * all multi-sentence inputs (including 2-sentence ones) get proper
+   * blockquote continuation lines.
+   */
+  wrapTranscription(transcription) {
+    if (!transcription.includes(".") && !transcription.includes("!") && !transcription.includes("?")) {
+      return transcription;
+    }
+    const sentences = transcription.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean);
+    if (sentences.length <= 1) return transcription;
+    return sentences.join("\n> ");
+  }
+  /**
+   * Format duration from milliseconds to M:SS
+   */
+  formatDuration(ms) {
+    const totalSeconds = Math.floor(ms / 1e3);
+    const mins = Math.floor(totalSeconds / 60);
+    const secs = totalSeconds % 60;
+    return `${mins}:${secs.toString().padStart(2, "0")}`;
+  }
+  /**
+   * Format timestamp to a deterministic human-readable string.
+   * Uses explicit formatting instead of toLocaleString to produce
+   * consistent output across platforms and Node.js versions.
+   */
+  formatTimestamp(ms) {
+    return this.formatDateDeterministic(new Date(ms));
+  }
+  /**
+   * Produce a deterministic date string: "Feb 14, 2026 at 10:30 AM".
+   * Avoids toLocaleString which can vary across OS versions.
+   */
+  formatDateDeterministic(date) {
+    const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+    const month = months[date.getMonth()];
+    const day = date.getDate();
+    const year = date.getFullYear();
+    const rawHours = date.getHours();
+    const ampm = rawHours >= 12 ? "PM" : "AM";
+    const hours = rawHours % 12 || 12;
+    const minutes = date.getMinutes().toString().padStart(2, "0");
+    return `${month} ${day}, ${year} at ${hours}:${minutes} ${ampm}`;
+  }
+  /**
+   * Format item timestamp as MM:SS from session start
+   */
+  formatItemTimestamp(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1e3));
+    const mins = Math.floor(totalSeconds / 60);
+    const secs = totalSeconds % 60;
+    return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+  }
+  /**
+   * Generate filename following pattern: {project}-feedback-{YYYYMMDD-HHmmss}.md
+   */
+  generateFilename(projectName, startTime) {
+    const date = new Date(startTime);
+    const year = date.getFullYear();
+    const month = (date.getMonth() + 1).toString().padStart(2, "0");
+    const day = date.getDate().toString().padStart(2, "0");
+    const hours = date.getHours().toString().padStart(2, "0");
+    const minutes = date.getMinutes().toString().padStart(2, "0");
+    const seconds = date.getSeconds().toString().padStart(2, "0");
+    const dateStr = `${year}${month}${day}`;
+    const timeStr = `${hours}${minutes}${seconds}`;
+    const safeName = projectName.toLowerCase().replace(/[^a-z0-9]/g, "-").replace(/-+/g, "-");
+    return `${safeName}-feedback-${dateStr}-${timeStr}.md`;
+  }
+  /**
+   * Generate screenshot filename for a feedback item.
+   * Uses the item's position index to produce `fb-{NNN}.png`, matching the
+   * naming convention in FileManager.saveSession.
+   */
+  generateScreenshotFilename(itemIndex, screenshotIndex, total) {
+    const num = (itemIndex + 1).toString().padStart(3, "0");
+    const suffix = total > 1 ? `-${screenshotIndex + 1}` : "";
+    return `fb-${num}${suffix}.png`;
+  }
+  /**
+   * Provide a severity fallback when upstream analysis is unavailable.
+   */
+  defaultSeverityForCategory(category) {
+    switch (category) {
+      case "Bug":
+        return "High";
+      case "Performance":
+        return "High";
+      case "UX Issue":
+        return "Medium";
+      case "Suggestion":
+        return "Low";
+      case "Question":
+        return "Low";
+      default:
+        return "Medium";
+    }
+  }
+  countSeverities(items) {
+    return items.reduce((acc, item) => {
+      const severity = item.severity || this.defaultSeverityForCategory(item.category || "General");
+      acc[severity] = (acc[severity] || 0) + 1;
+      return acc;
+    }, {});
+  }
+  extractTopThemes(items) {
+    const counts = /* @__PURE__ */ new Map();
+    items.forEach((item) => {
+      (item.keywords || []).forEach((keyword) => {
+        const normalized = keyword.toLowerCase();
+        counts.set(normalized, (counts.get(normalized) || 0) + 1);
+      });
+    });
+    return Array.from(counts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([keyword]) => keyword);
+  }
+  suggestAction(category, severity, transcription) {
+    const excerpt = this.truncateText(transcription, 120);
+    switch (category) {
+      case "Bug":
+        return `Reproduce and patch this defect, then add a regression test that validates: "${excerpt}".`;
+      case "Performance":
+        return `Profile this flow, target the slow step first, and validate before/after metrics for: "${excerpt}".`;
+      case "UX Issue":
+        return `Revise the UI interaction and run a quick usability check focused on: "${excerpt}".`;
+      case "Suggestion":
+        return severity === "High" || severity === "Critical" ? `Treat this suggestion as near-term roadmap work and define implementation scope for: "${excerpt}".` : `Track this as an enhancement request and prioritize against current sprint goals: "${excerpt}".`;
+      case "Question":
+        return `Answer this explicitly in product/docs so future reviews don't block on: "${excerpt}".`;
+      default:
+        return `Investigate this item and convert it into a concrete engineering task: "${excerpt}".`;
+    }
+  }
+  /**
+   * Count feedback items by type/category
+   */
+  countTypes(items) {
+    return items.reduce((acc, item) => {
+      const type = item.category || "General";
+      acc[type] = (acc[type] || 0) + 1;
+      return acc;
+    }, {});
+  }
+  /**
+   * Count total screenshots across all items
+   */
+  countScreenshots(items) {
+    return items.reduce((sum, item) => sum + item.screenshots.length, 0);
+  }
+};
+var markdownGenerator = new MarkdownGeneratorImpl();
+
+// src/main/transcription/WhisperService.ts
+import { EventEmitter } from "events";
+import { basename, join as join2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { readFile, unlink, chmod } from "fs/promises";
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+import { tmpdir } from "os";
+import { randomUUID } from "crypto";
+import * as os from "os";
+var execFileAsync = promisify2(execFile2);
+var DEFAULT_CONFIG = {
+  modelPath: "",
+  // Set dynamically
+  language: "en",
+  threads: Math.max(1, Math.floor(os.cpus().length / 2)),
+  // Half CPU cores
+  translateToEnglish: false
+};
+var CHUNK_DURATION_MS = 3e3;
+var MAX_BUFFER_DURATION_MS = 3e4;
+var MAX_BUFFER_SIZE_BYTES = 500 * 1024;
+var SAMPLE_RATE = 16e3;
+var FILE_CHUNK_DURATION_SEC = 30;
+var FILE_CHUNK_SAMPLES = FILE_CHUNK_DURATION_SEC * SAMPLE_RATE;
+var MODEL_MEMORY_REQUIREMENTS_BYTES = {
+  "ggml-tiny.bin": 450 * 1024 * 1024,
+  "ggml-base.bin": 800 * 1024 * 1024,
+  "ggml-small.bin": 1400 * 1024 * 1024,
+  "ggml-medium.bin": 2800 * 1024 * 1024,
+  "ggml-large-v3.bin": 5200 * 1024 * 1024
+};
+var WhisperService = class extends EventEmitter {
+  config;
+  isInitialized = false;
+  isProcessing = false;
+  whisperModule = null;
+  // Audio buffering for batch processing
+  audioBuffer = [];
+  bufferStartTime = 0;
+  totalBufferDuration = 0;
+  totalBufferBytes = 0;
+  // Processing state
+  processingInterval = null;
+  // Callbacks
+  transcriptCallbacks = [];
+  errorCallbacks = [];
+  constructor(config) {
+    super();
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    if (!this.config.modelPath) {
+      this.config.modelPath = this.getDefaultModelPath();
+    }
+  }
+  // ============================================================================
+  // Public API
+  // ============================================================================
+  /**
+   * Check if Whisper model is available
+   */
+  isModelAvailable() {
+    return existsSync2(this.config.modelPath);
+  }
+  /**
+   * Get the path where models should be stored
+   */
+  getModelsDirectory() {
+    try {
+      const { app } = __require("electron");
+      return join2(app.getPath("userData"), "whisper-models");
+    } catch {
+      const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+      return join2(homeDir, ".markupr", "whisper-models");
+    }
+  }
+  /**
+   * Get the default model path (whisper-medium)
+   */
+  getDefaultModelPath() {
+    return join2(this.getModelsDirectory(), "ggml-medium.bin");
+  }
+  /**
+   * Set the model path
+   */
+  setModelPath(modelPath) {
+    this.config.modelPath = modelPath;
+    this.isInitialized = false;
+  }
+  /**
+   * Check if system has enough memory for Whisper
+   * Requirement is model-aware (tiny/base/small/medium/large).
+   */
+  hasEnoughMemory() {
+    const freeMemory = os.freemem();
+    const requiredMemory = this.getRequiredMemoryBytes();
+    return freeMemory >= requiredMemory;
+  }
+  /**
+   * Get current memory info
+   */
+  getMemoryInfo() {
+    const freeMemory = os.freemem();
+    const requiredMemory = this.getRequiredMemoryBytes();
+    return {
+      freeMemoryMB: Math.round(freeMemory / 1024 / 1024),
+      requiredMemoryMB: Math.round(requiredMemory / 1024 / 1024),
+      sufficient: freeMemory >= requiredMemory
+    };
+  }
+  /**
+   * Initialize the Whisper model
+   * Call this once before starting transcription
+   */
+  async initialize() {
+    if (this.isInitialized) {
+      return;
+    }
+    if (!this.isModelAvailable()) {
+      throw new Error(`Whisper model not found at ${this.config.modelPath}. Please download the model first.`);
+    }
+    if (!this.hasEnoughMemory()) {
+      const memInfo = this.getMemoryInfo();
+      throw new Error(
+        `Insufficient memory for Whisper. Need ~${memInfo.requiredMemoryMB}MB free, only ${memInfo.freeMemoryMB}MB available.`
+      );
+    }
+    this.log("Initializing Whisper model...");
+    try {
+      this.whisperModule = await import("whisper-node");
+      if (!this.whisperModule || typeof this.whisperModule.whisper !== "function") {
+        throw new Error("whisper-node module loaded but whisper function not found");
+      }
+      this.log("Pre-loading model with test transcription...");
+      const testBuffer = new Float32Array(1600);
+      await this.whisperModule.whisper(testBuffer, {
+        modelPath: this.config.modelPath,
+        language: this.config.language,
+        threads: this.config.threads
+      });
+      this.isInitialized = true;
+      this.log("Whisper model initialized successfully");
+    } catch (error) {
+      const initError = new Error(`Failed to initialize Whisper: ${error.message}`);
+      this.errorCallbacks.forEach((cb) => cb(initError));
+      throw initError;
+    }
+  }
+  /**
+   * Check if service is initialized and ready
+   */
+  isReady() {
+    return this.isInitialized && this.whisperModule !== null;
+  }
+  /**
+   * Start accepting audio for transcription
+   */
+  async start() {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+    this.audioBuffer = [];
+    this.bufferStartTime = Date.now();
+    this.totalBufferDuration = 0;
+    this.totalBufferBytes = 0;
+    this.processingInterval = setInterval(() => {
+      this.processBufferedAudio();
+    }, CHUNK_DURATION_MS);
+    this.log("Whisper transcription started");
+  }
+  /**
+   * Stop transcription and process remaining audio
+   */
+  async stop() {
+    if (this.processingInterval) {
+      clearInterval(this.processingInterval);
+      this.processingInterval = null;
+    }
+    await this.processBufferedAudio(true);
+    this.audioBuffer = [];
+    this.totalBufferDuration = 0;
+    this.totalBufferBytes = 0;
+    this.log("Whisper transcription stopped");
+  }
+  /**
+   * Add audio data to the buffer
+   * @param samples Float32Array of audio samples at 16kHz mono
+   * @param durationMs Duration of this chunk in milliseconds
+   */
+  addAudio(samples, durationMs) {
+    const chunkBytes = samples.byteLength;
+    if (this.totalBufferBytes + chunkBytes > MAX_BUFFER_SIZE_BYTES) {
+      this.log("Audio buffer full, force-processing before adding new audio");
+      this.processBufferedAudio(true);
+    }
+    this.audioBuffer.push(samples);
+    this.totalBufferDuration += durationMs;
+    this.totalBufferBytes += chunkBytes;
+    if (this.totalBufferDuration >= MAX_BUFFER_DURATION_MS) {
+      this.processBufferedAudio(true);
+    }
+  }
+  /**
+   * Register callback for transcript results
+   */
+  onTranscript(callback) {
+    this.transcriptCallbacks.push(callback);
+    return () => {
+      this.transcriptCallbacks = this.transcriptCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  /**
+   * Register callback for errors
+   */
+  onError(callback) {
+    this.errorCallbacks.push(callback);
+    return () => {
+      this.errorCallbacks = this.errorCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Transcribe a complete Float32 buffer in one pass.
+   * Useful for post-session retry workflows when live streaming failed.
+   */
+  async transcribeSamples(samples, startTimeSec) {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+    if (!this.whisperModule) {
+      throw new Error("Whisper module not loaded");
+    }
+    const CHUNK_TIMEOUT_MS = 6e4;
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(
+        () => reject(new Error("Whisper transcription timed out after 60s")),
+        CHUNK_TIMEOUT_MS
+      );
+    });
+    let result;
+    try {
+      result = await Promise.race([
+        this.whisperModule.whisper(samples, {
+          modelPath: this.config.modelPath,
+          language: this.config.language,
+          threads: this.config.threads,
+          translate: this.config.translateToEnglish
+        }),
+        timeoutPromise
+      ]);
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+    if (!result || result.length === 0) {
+      return [];
+    }
+    return result.map((segment) => ({
+      text: segment.text.trim(),
+      startTime: startTimeSec + segment.start,
+      endTime: startTimeSec + segment.end,
+      confidence: 0.9
+    })).filter((segment) => segment.text.length > 0);
+  }
+  /**
+   * Transcribe an audio file from disk.
+   * Loads the file, converts to Float32Array at 16kHz mono, and transcribes.
+   * For large files, processes in chunks to manage memory.
+   *
+   * @param audioPath - Path to the audio file (webm, wav, ogg, m4a)
+   * @param onProgress - Optional progress callback (0-100)
+   * @returns Array of transcript results with timestamps
+   */
+  async transcribeFile(audioPath, onProgress) {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+    if (!existsSync2(audioPath)) {
+      throw new Error(`Audio file not found: ${audioPath}`);
+    }
+    this.log(`Transcribing file: ${audioPath}`);
+    onProgress?.(0);
+    const samples = await this.loadAudioAsSamples(audioPath);
+    if (samples.length === 0) {
+      this.log("Audio file produced no samples");
+      onProgress?.(100);
+      return [];
+    }
+    const totalChunks = Math.ceil(samples.length / FILE_CHUNK_SAMPLES);
+    const results = [];
+    this.log(`Processing ${totalChunks} chunk(s) (${(samples.length / SAMPLE_RATE).toFixed(1)}s total)`);
+    for (let i = 0; i < totalChunks; i++) {
+      const chunkStart = i * FILE_CHUNK_SAMPLES;
+      const chunkEnd = Math.min(chunkStart + FILE_CHUNK_SAMPLES, samples.length);
+      const chunk = samples.subarray(chunkStart, chunkEnd);
+      const startTimeSec = chunkStart / SAMPLE_RATE;
+      const chunkResults = await this.transcribeSamples(chunk, startTimeSec);
+      results.push(...chunkResults);
+      const percent = Math.round((i + 1) / totalChunks * 100);
+      onProgress?.(percent);
+      if (i < totalChunks - 1) {
+        await new Promise((resolve2) => setTimeout(resolve2, 0));
+      }
+    }
+    this.log(`Transcription complete: ${results.length} segment(s)`);
+    return results;
+  }
+  /**
+   * Check if ffmpeg is available on the system
+   */
+  async isFfmpegAvailable() {
+    try {
+      await execFileAsync("ffmpeg", ["-version"]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  /**
+   * Load an audio file and return Float32Array samples at 16kHz mono.
+   * WAV files are parsed directly; other formats are converted via ffmpeg.
+   */
+  async loadAudioAsSamples(audioPath) {
+    const ext = audioPath.toLowerCase().split(".").pop() ?? "";
+    if (ext === "wav") {
+      return this.parseWavFile(audioPath);
+    }
+    return this.convertWithFfmpeg(audioPath);
+  }
+  /**
+   * Parse a WAV file and extract PCM data as Float32Array at 16kHz mono.
+   * Handles PCM float32 and PCM int16 formats.
+   */
+  async parseWavFile(wavPath) {
+    const buffer = await readFile(wavPath);
+    const riff = buffer.toString("ascii", 0, 4);
+    const wave = buffer.toString("ascii", 8, 12);
+    if (riff !== "RIFF" || wave !== "WAVE") {
+      throw new Error(`Invalid WAV file: missing RIFF/WAVE header in ${wavPath}`);
+    }
+    let offset = 12;
+    let audioFormat = 0;
+    let numChannels = 0;
+    let sampleRate = 0;
+    let bitsPerSample = 0;
+    let fmtFound = false;
+    while (offset < buffer.length - 8) {
+      const chunkId = buffer.toString("ascii", offset, offset + 4);
+      const chunkSize = buffer.readUInt32LE(offset + 4);
+      if (chunkId === "fmt ") {
+        audioFormat = buffer.readUInt16LE(offset + 8);
+        numChannels = buffer.readUInt16LE(offset + 10);
+        sampleRate = buffer.readUInt32LE(offset + 12);
+        bitsPerSample = buffer.readUInt16LE(offset + 22);
+        fmtFound = true;
+      }
+      if (chunkId === "data") {
+        if (!fmtFound) {
+          throw new Error("WAV file has data chunk before fmt chunk");
+        }
+        const dataStart = offset + 8;
+        const dataEnd = dataStart + chunkSize;
+        const dataSlice = buffer.subarray(dataStart, Math.min(dataEnd, buffer.length));
+        return this.extractWavSamples(dataSlice, audioFormat, numChannels, sampleRate, bitsPerSample);
+      }
+      offset += 8 + chunkSize;
+      if (chunkSize % 2 !== 0) {
+        offset += 1;
+      }
+    }
+    throw new Error(`Invalid WAV file: no data chunk found in ${wavPath}`);
+  }
+  /**
+   * Extract samples from WAV data chunk, converting to Float32Array at 16kHz mono.
+   */
+  extractWavSamples(data, audioFormat, numChannels, sampleRate, bitsPerSample) {
+    let monoFloat32;
+    if (audioFormat === 3 && bitsPerSample === 32) {
+      const totalSamples = Math.floor(data.length / 4);
+      const allSamples = new Float32Array(totalSamples);
+      for (let i = 0; i < totalSamples; i++) {
+        allSamples[i] = data.readFloatLE(i * 4);
+      }
+      monoFloat32 = this.mixToMono(allSamples, numChannels);
+    } else if (audioFormat === 1 && bitsPerSample === 16) {
+      const totalSamples = Math.floor(data.length / 2);
+      const allSamples = new Float32Array(totalSamples);
+      for (let i = 0; i < totalSamples; i++) {
+        allSamples[i] = data.readInt16LE(i * 2) / 32768;
+      }
+      monoFloat32 = this.mixToMono(allSamples, numChannels);
+    } else {
+      throw new Error(
+        `Unsupported WAV format: audioFormat=${audioFormat}, bitsPerSample=${bitsPerSample}. Expected PCM float32 (format=3, bits=32) or PCM int16 (format=1, bits=16).`
+      );
+    }
+    if (sampleRate !== SAMPLE_RATE) {
+      return this.resample(monoFloat32, sampleRate, SAMPLE_RATE);
+    }
+    return monoFloat32;
+  }
+  /**
+   * Mix multi-channel audio down to mono by averaging channels.
+   */
+  mixToMono(samples, numChannels) {
+    if (numChannels === 1) {
+      return samples;
+    }
+    const monoLength = Math.floor(samples.length / numChannels);
+    const mono = new Float32Array(monoLength);
+    for (let i = 0; i < monoLength; i++) {
+      let sum = 0;
+      for (let ch = 0; ch < numChannels; ch++) {
+        sum += samples[i * numChannels + ch];
+      }
+      mono[i] = sum / numChannels;
+    }
+    return mono;
+  }
+  /**
+   * Simple linear resampling from one sample rate to another.
+   */
+  resample(samples, fromRate, toRate) {
+    if (fromRate === toRate) {
+      return samples;
+    }
+    const ratio = fromRate / toRate;
+    const outputLength = Math.floor(samples.length / ratio);
+    const output = new Float32Array(outputLength);
+    for (let i = 0; i < outputLength; i++) {
+      const srcIndex = i * ratio;
+      const srcIndexFloor = Math.floor(srcIndex);
+      const srcIndexCeil = Math.min(srcIndexFloor + 1, samples.length - 1);
+      const frac = srcIndex - srcIndexFloor;
+      output[i] = samples[srcIndexFloor] * (1 - frac) + samples[srcIndexCeil] * frac;
+    }
+    return output;
+  }
+  /**
+   * Convert a non-WAV audio file to 16kHz mono Float32 WAV using ffmpeg,
+   * then parse the resulting WAV.
+   */
+  async convertWithFfmpeg(audioPath) {
+    const ffmpegAvailable = await this.isFfmpegAvailable();
+    if (!ffmpegAvailable) {
+      const installHint = process.platform === "darwin" ? "brew install ffmpeg" : process.platform === "win32" ? "winget install ffmpeg or download from https://ffmpeg.org" : "apt install ffmpeg (Debian/Ubuntu) or dnf install ffmpeg (Fedora)";
+      throw new Error(
+        `ffmpeg is not available on this system. ffmpeg is required to transcribe non-WAV audio files (webm, ogg, m4a). Install ffmpeg via: ${installHint}.`
+      );
+    }
+    const tempFileName = `markupr-transcode-${randomUUID()}.wav`;
+    const tempPath = join2(tmpdir(), tempFileName);
+    try {
+      this.log(`Converting ${audioPath} to WAV via ffmpeg...`);
+      await execFileAsync("ffmpeg", [
+        "-i",
+        audioPath,
+        "-ar",
+        String(SAMPLE_RATE),
+        "-ac",
+        "1",
+        "-f",
+        "wav",
+        "-acodec",
+        "pcm_f32le",
+        "-y",
+        tempPath
+      ], {
+        env: { PATH: process.env.PATH, HOME: process.env.HOME, LANG: process.env.LANG, TMPDIR: process.env.TMPDIR }
+      });
+      await chmod(tempPath, 384).catch(() => {
+      });
+      this.log("ffmpeg conversion complete, parsing WAV...");
+      return await this.parseWavFile(tempPath);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to convert audio file with ffmpeg: ${msg}`);
+    } finally {
+      try {
+        await unlink(tempPath);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Process buffered audio through Whisper
+   */
+  async processBufferedAudio(force = false) {
+    if (this.isProcessing) {
+      return;
+    }
+    if (!force && this.totalBufferDuration < CHUNK_DURATION_MS) {
+      return;
+    }
+    if (this.audioBuffer.length === 0) {
+      return;
+    }
+    if (!this.whisperModule) {
+      this.logError("Cannot process: Whisper module not loaded");
+      return;
+    }
+    this.isProcessing = true;
+    const processStartTime = this.bufferStartTime;
+    try {
+      const totalSamples = this.audioBuffer.reduce((sum, arr) => sum + arr.length, 0);
+      const combinedAudio = new Float32Array(totalSamples);
+      let offset = 0;
+      for (const chunk of this.audioBuffer) {
+        combinedAudio.set(chunk, offset);
+        offset += chunk.length;
+      }
+      const processedDuration = this.totalBufferDuration;
+      this.audioBuffer = [];
+      this.totalBufferDuration = 0;
+      this.totalBufferBytes = 0;
+      this.bufferStartTime = Date.now();
+      this.log(`Processing ${Math.round(processedDuration)}ms of audio...`);
+      const result = await this.whisperModule.whisper(combinedAudio, {
+        modelPath: this.config.modelPath,
+        language: this.config.language,
+        threads: this.config.threads,
+        translate: this.config.translateToEnglish
+      });
+      if (result && result.length > 0) {
+        for (const segment of result) {
+          const transcriptResult = {
+            text: segment.text.trim(),
+            startTime: processStartTime / 1e3 + segment.start,
+            endTime: processStartTime / 1e3 + segment.end,
+            confidence: 0.9
+            // Whisper doesn't provide confidence, use default
+          };
+          if (transcriptResult.text) {
+            this.transcriptCallbacks.forEach((cb) => cb(transcriptResult));
+            this.emit("transcript", transcriptResult);
+            const preview = transcriptResult.text.length > 50 ? `${transcriptResult.text.substring(0, 50)}...` : transcriptResult.text;
+            this.log(`Transcript: "${preview}"`);
+          }
+        }
+      }
+    } catch (error) {
+      const transcriptionError = new Error(`Whisper transcription failed: ${error.message}`);
+      this.errorCallbacks.forEach((cb) => cb(transcriptionError));
+      this.emit("error", transcriptionError);
+      this.logError("Transcription error", error);
+    } finally {
+      this.isProcessing = false;
+    }
+  }
+  /**
+   * Log helper
+   */
+  log(message) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    console.log(`[WhisperService ${timestamp}] ${message}`);
+  }
+  /**
+   * Error log helper
+   */
+  logError(message, error) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const errorStr = error instanceof Error ? error.message : String(error);
+    console.error(`[WhisperService ${timestamp}] ERROR: ${message} - ${errorStr}`);
+  }
+  getRequiredMemoryBytes() {
+    const modelName = basename(this.config.modelPath);
+    return MODEL_MEMORY_REQUIREMENTS_BYTES[modelName] ?? MODEL_MEMORY_REQUIREMENTS_BYTES["ggml-small.bin"];
+  }
+};
+var whisperService = new WhisperService();
+
+// src/cli/CLIPipeline.ts
+var EXIT_SUCCESS = 0;
+var EXIT_USER_ERROR = 1;
+var EXIT_SYSTEM_ERROR = 2;
+var EXIT_SIGINT = 130;
+var CLIPipeline = class _CLIPipeline {
+  options;
+  log;
+  progress;
+  tempFiles = [];
+  activeProcesses = /* @__PURE__ */ new Set();
+  constructor(options, log, progress) {
+    this.options = options;
+    this.log = log;
+    this.progress = progress ?? (() => {
+    });
+  }
+  /**
+   * Run the full pipeline: audio extraction -> transcription -> analysis ->
+   * frame extraction -> markdown generation.
+   */
+  async run() {
+    try {
+      return await this.runPipeline();
+    } finally {
+      await this.cleanup();
+    }
+  }
+  async runPipeline() {
+    const startTime = Date.now();
+    await this.validateVideoFile();
+    if (!(this.options.audioPath && this.options.skipFrames)) {
+      await this.checkFfmpegAvailable();
+    }
+    try {
+      if (!existsSync3(this.options.outputDir)) {
+        mkdirSync2(this.options.outputDir, { recursive: true });
+      }
+    } catch (error) {
+      const code = error.code;
+      if (code === "EACCES") {
+        throw new CLIPipelineError(
+          `Permission denied: cannot create output directory: ${this.options.outputDir}`,
+          "user"
+        );
+      }
+      throw new CLIPipelineError(
+        `Cannot create output directory: ${this.options.outputDir} (${code})`,
+        "system"
+      );
+    }
+    this.progress("Extracting audio...");
+    const audioPath = await this.resolveAudioPath();
+    this.progress("Transcribing (this may take a while)...");
+    const segments = await this.transcribe(audioPath);
+    const analyzer = new TranscriptAnalyzer();
+    const keyMoments = analyzer.analyze(segments);
+    this.log(`  Found ${keyMoments.length} key moment(s)`);
+    let extractedFrames = [];
+    if (!this.options.skipFrames) {
+      this.progress("Extracting frames...");
+      extractedFrames = await this.extractFrames(keyMoments, segments);
+    } else {
+      this.log("  Frame extraction skipped (--no-frames)");
+    }
+    this.progress("Generating report...");
+    const result = {
+      transcriptSegments: segments,
+      extractedFrames,
+      reportPath: this.options.outputDir
+    };
+    const generator = new MarkdownGeneratorImpl();
+    const markdown = generator.generateFromPostProcess(result, this.options.outputDir);
+    const outputFilename = this.generateOutputFilename();
+    const outputPath = join3(this.options.outputDir, outputFilename);
+    try {
+      await writeFile(outputPath, markdown, "utf-8");
+    } catch (error) {
+      const code = error.code;
+      throw new CLIPipelineError(
+        `Failed to write output file: ${outputPath}
+  Reason: ${code === "ENOSPC" ? "Disk is full" : error.message}`,
+        "system"
+      );
+    }
+    const durationSeconds = (Date.now() - startTime) / 1e3;
+    return {
+      outputPath,
+      transcriptSegments: segments.length,
+      extractedFrames: extractedFrames.length,
+      durationSeconds
+    };
+  }
+  /**
+   * Abort the pipeline: kill active child processes and clean up temp files.
+   */
+  async abort() {
+    for (const proc of this.activeProcesses) {
+      proc.kill("SIGTERM");
+    }
+    this.activeProcesses.clear();
+    await this.cleanup();
+  }
+  /**
+   * Clean up temp files created during the pipeline run.
+   */
+  async cleanup() {
+    for (const file of this.tempFiles) {
+      try {
+        await unlink2(file);
+      } catch {
+      }
+    }
+    this.tempFiles = [];
+  }
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+  /**
+   * Execute a child process while tracking it for cleanup on abort.
+   */
+  static SAFE_CHILD_ENV = {
+    PATH: process.env.PATH,
+    HOME: process.env.HOME || process.env.USERPROFILE,
+    USERPROFILE: process.env.USERPROFILE,
+    LANG: process.env.LANG,
+    TMPDIR: process.env.TMPDIR || process.env.TEMP,
+    TEMP: process.env.TEMP
+  };
+  execFileTracked(command, args) {
+    return new Promise((resolve2, reject) => {
+      const child = execFileCb2(command, args, { env: _CLIPipeline.SAFE_CHILD_ENV }, (error, stdout, stderr) => {
+        this.activeProcesses.delete(child);
+        if (error) reject(error);
+        else resolve2({ stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "" });
+      });
+      this.activeProcesses.add(child);
+    });
+  }
+  /**
+   * Validate the video file is a real, non-empty file with a video stream.
+   */
+  async validateVideoFile() {
+    const { videoPath } = this.options;
+    let stats;
+    try {
+      stats = await stat(videoPath);
+    } catch {
+      throw new CLIPipelineError(`Video file not found: ${videoPath}`, "user");
+    }
+    if (!stats.isFile()) {
+      throw new CLIPipelineError(`Not a regular file: ${videoPath}`, "user");
+    }
+    if (stats.size === 0) {
+      throw new CLIPipelineError(`Video file is empty (0 bytes): ${videoPath}`, "user");
+    }
+    try {
+      const { stdout } = await this.execFileTracked("ffprobe", [
+        "-v",
+        "error",
+        "-select_streams",
+        "v",
+        "-show_entries",
+        "stream=codec_type",
+        "-of",
+        "csv=p=0",
+        videoPath
+      ]);
+      if (!stdout.trim().includes("video")) {
+        throw new CLIPipelineError(
+          `No video stream found in file: ${videoPath}`,
+          "user"
+        );
+      }
+    } catch (error) {
+      if (error instanceof CLIPipelineError) throw error;
+      throw new CLIPipelineError(
+        `Cannot read video file (is ffprobe installed?): ${videoPath}`,
+        "system"
+      );
+    }
+  }
+  /**
+   * Check that ffmpeg is available on PATH.
+   */
+  async checkFfmpegAvailable() {
+    try {
+      await this.execFileTracked("ffmpeg", ["-version"]);
+    } catch {
+      const platform = process.platform;
+      const installHint = platform === "darwin" ? "brew install ffmpeg" : platform === "win32" ? "winget install ffmpeg (or download from https://ffmpeg.org)" : "apt install ffmpeg (or your package manager)";
+      throw new CLIPipelineError(
+        `ffmpeg is required but not found on your system.
+  Install via: ${installHint}
+  Or provide a separate audio file with --audio <file> and --no-frames`,
+        "system"
+      );
+    }
+  }
+  /**
+   * Resolve the audio path. If no separate audio file was provided, probe
+   * the video for an audio track and extract it to a temp WAV file.
+   */
+  async resolveAudioPath() {
+    if (this.options.audioPath) {
+      if (!existsSync3(this.options.audioPath)) {
+        throw new CLIPipelineError(
+          `Audio file not found: ${this.options.audioPath}`,
+          "user"
+        );
+      }
+      this.log(`  Using provided audio: ${this.options.audioPath}`);
+      return this.options.audioPath;
+    }
+    const hasAudio = await this.videoHasAudioTrack(this.options.videoPath);
+    if (!hasAudio) {
+      this.log("  No audio track found in video - transcription will be skipped");
+      return null;
+    }
+    this.log("  Extracting audio from video...");
+    const tempAudioPath = join3(tmpdir2(), `markupr-cli-audio-${randomUUID2()}.wav`);
+    this.tempFiles.push(tempAudioPath);
+    try {
+      await this.execFileTracked("ffmpeg", [
+        "-i",
+        this.options.videoPath,
+        "-vn",
+        "-ar",
+        "16000",
+        "-ac",
+        "1",
+        "-f",
+        "wav",
+        "-acodec",
+        "pcm_f32le",
+        "-y",
+        tempAudioPath
+      ]);
+      await chmod2(tempAudioPath, 384).catch(() => {
+      });
+      this.log("  Audio extraction complete");
+      return tempAudioPath;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      this.log(`  WARNING: Audio extraction failed: ${msg}`);
+      return null;
+    }
+  }
+  /**
+   * Use ffprobe to check whether the video file contains an audio stream.
+   */
+  async videoHasAudioTrack(videoPath) {
+    try {
+      const { stdout } = await this.execFileTracked("ffprobe", [
+        "-v",
+        "error",
+        "-select_streams",
+        "a",
+        "-show_entries",
+        "stream=codec_type",
+        "-of",
+        "csv=p=0",
+        videoPath
+      ]);
+      return stdout.trim().length > 0;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Transcribe audio using WhisperService. Falls back gracefully if the
+   * model is not available.
+   */
+  async transcribe(audioPath) {
+    if (!audioPath) {
+      this.log("  No audio available - skipping transcription");
+      return [];
+    }
+    const whisper = new WhisperService(
+      this.options.whisperModelPath ? { modelPath: this.options.whisperModelPath } : void 0
+    );
+    if (!whisper.isModelAvailable()) {
+      const modelsDir = whisper.getModelsDirectory();
+      this.log(`  Whisper model not found at: ${whisper.getConfig().modelPath}`);
+      this.log(`  Models directory: ${modelsDir}`);
+      this.log("  Transcription will be skipped. Download a model to enable transcription.");
+      return [];
+    }
+    this.log(`  Transcribing with Whisper (model: ${basename2(whisper.getConfig().modelPath)})...`);
+    try {
+      const results = await whisper.transcribeFile(audioPath, (percent) => {
+        if (this.options.verbose) {
+          process.stdout.write(`\r  Transcription progress: ${percent}%`);
+        }
+      });
+      if (this.options.verbose && results.length > 0) {
+        process.stdout.write("\n");
+      }
+      const segments = results.map((r) => ({
+        text: r.text,
+        startTime: r.startTime,
+        endTime: r.endTime,
+        confidence: r.confidence
+      }));
+      this.log(`  Transcription complete: ${segments.length} segment(s)`);
+      return segments;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      this.log(`  WARNING: Transcription failed: ${msg}`);
+      return [];
+    }
+  }
+  /**
+   * Extract video frames at key moment timestamps.
+   */
+  async extractFrames(keyMoments, segments) {
+    if (keyMoments.length === 0) {
+      this.log("  No key moments found - skipping frame extraction");
+      return [];
+    }
+    const extractor = new FrameExtractor();
+    const available = await extractor.checkFfmpeg();
+    if (!available) {
+      this.log("  WARNING: ffmpeg not found - frame extraction skipped");
+      this.log("  Install ffmpeg: brew install ffmpeg (macOS) or apt install ffmpeg (Linux)");
+      return [];
+    }
+    this.log(`  Extracting ${keyMoments.length} frame(s)...`);
+    const timestamps = keyMoments.map((m) => m.timestamp);
+    const extractionResult = await extractor.extract({
+      videoPath: this.options.videoPath,
+      timestamps,
+      outputDir: this.options.outputDir
+    });
+    const extractedFrames = extractionResult.frames.filter((f) => f.success).map((frame) => {
+      const moment = keyMoments.find(
+        (m) => Math.abs(m.timestamp - frame.timestamp) < 0.5
+      );
+      const closestSegment = this.findClosestSegment(frame.timestamp, segments);
+      return {
+        path: frame.path,
+        timestamp: frame.timestamp,
+        reason: moment?.reason ?? "Extracted frame",
+        transcriptSegment: closestSegment
+      };
+    });
+    this.log(`  Extracted ${extractedFrames.length} frame(s)`);
+    return extractedFrames;
+  }
+  /**
+   * Find the transcript segment closest to a given timestamp.
+   */
+  findClosestSegment(timestamp, segments) {
+    if (segments.length === 0) return void 0;
+    for (const segment of segments) {
+      if (timestamp >= segment.startTime && timestamp <= segment.endTime) {
+        return segment;
+      }
+    }
+    let closest = segments[0];
+    let minDistance = Math.abs(timestamp - closest.startTime);
+    for (let i = 1; i < segments.length; i++) {
+      const distance = Math.abs(timestamp - segments[i].startTime);
+      if (distance < minDistance) {
+        minDistance = distance;
+        closest = segments[i];
+      }
+    }
+    return closest;
+  }
+  /**
+   * Generate the output filename based on the video filename and current date (UTC).
+   */
+  generateOutputFilename() {
+    const videoName = basename2(this.options.videoPath).replace(/\.[^.]+$/, "").replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-");
+    const now = /* @__PURE__ */ new Date();
+    const dateStr = [
+      now.getUTCFullYear(),
+      String(now.getUTCMonth() + 1).padStart(2, "0"),
+      String(now.getUTCDate()).padStart(2, "0")
+    ].join("");
+    const timeStr = [
+      String(now.getUTCHours()).padStart(2, "0"),
+      String(now.getUTCMinutes()).padStart(2, "0"),
+      String(now.getUTCSeconds()).padStart(2, "0")
+    ].join("");
+    return `${videoName}-feedback-${dateStr}-${timeStr}.md`;
+  }
+};
+var CLIPipelineError = class extends Error {
+  severity;
+  constructor(message, severity) {
+    super(message);
+    this.name = "CLIPipelineError";
+    this.severity = severity;
+  }
+};
+
+// src/cli/index.ts
+var VERSION = true ? "2.4.0" : "0.0.0-dev";
+var SYMBOLS = {
+  check: "\u2714",
+  // checkmark
+  cross: "\u2718",
+  // cross
+  arrow: "\u2192",
+  // right arrow
+  bullet: "\u2022",
+  // bullet
+  ellipsis: "\u2026",
+  // ellipsis
+  line: "\u2500"
+  // horizontal line
+};
+function banner() {
+  console.log();
+  console.log(`  markupr v${VERSION} ${SYMBOLS.bullet} CLI Mode`);
+  console.log(`  ${SYMBOLS.line.repeat(40)}`);
+  console.log();
+}
+function step(message) {
+  console.log(`  ${SYMBOLS.arrow} ${message}`);
+}
+function success(message) {
+  console.log(`  ${SYMBOLS.check} ${message}`);
+}
+function fail(message) {
+  console.log(`  ${SYMBOLS.cross} ${message}`);
+}
+var activePipeline = null;
+function setupSignalHandlers() {
+  const handler = async () => {
+    console.log("\n  Interrupted \u2014 cleaning up...");
+    if (activePipeline) {
+      await activePipeline.abort();
+    }
+    process.exit(EXIT_SIGINT);
+  };
+  process.on("SIGINT", handler);
+  process.on("SIGTERM", handler);
+}
+setupSignalHandlers();
+var program = new Command();
+program.name("markupr").description("Analyze screen recordings and generate AI-ready Markdown reports").version(VERSION, "-v, --version").showHelpAfterError("(use --help for available options)");
+program.command("analyze").description("Analyze a video recording and generate a structured feedback report").argument("<video-file>", "Path to the video file to analyze").option("--audio <file>", "Separate audio file (if not embedded in video)").option("--output <dir>", "Output directory", "./markupr-output").option("--whisper-model <path>", "Path to Whisper model file").option("--openai-key <key>", "OpenAI API key for cloud transcription (prefer OPENAI_API_KEY env var)").option("--no-frames", "Skip frame extraction").option("--verbose", "Verbose output", false).action(async (videoFile, options) => {
+  banner();
+  const videoPath = resolve(videoFile);
+  const outputDir = resolve(options.output);
+  const audioPath = options.audio ? resolve(options.audio) : void 0;
+  const whisperModelPath = options.whisperModel ? resolve(options.whisperModel) : void 0;
+  let openaiKey;
+  if (options.openaiKey) {
+    console.warn("  WARNING: Passing API keys via CLI args is insecure (visible in ps, shell history).");
+    console.warn("  Use OPENAI_API_KEY env var instead.");
+    console.warn();
+    openaiKey = options.openaiKey;
+  } else if (process.env.OPENAI_API_KEY) {
+    openaiKey = process.env.OPENAI_API_KEY;
+  }
+  if (!existsSync4(videoPath)) {
+    fail(`Video file not found: ${videoPath}`);
+    process.exit(EXIT_USER_ERROR);
+  }
+  if (audioPath && !existsSync4(audioPath)) {
+    fail(`Audio file not found: ${audioPath}`);
+    process.exit(EXIT_USER_ERROR);
+  }
+  if (whisperModelPath && !existsSync4(whisperModelPath)) {
+    fail(`Whisper model not found: ${whisperModelPath}`);
+    process.exit(EXIT_USER_ERROR);
+  }
+  step(`Video:  ${videoPath}`);
+  if (audioPath) {
+    step(`Audio:  ${audioPath}`);
+  }
+  step(`Output: ${outputDir}`);
+  console.log();
+  const pipeline = new CLIPipeline(
+    {
+      videoPath,
+      audioPath,
+      outputDir,
+      whisperModelPath,
+      openaiKey,
+      skipFrames: !options.frames,
+      verbose: options.verbose
+    },
+    options.verbose ? step : () => {
+    },
+    step
+    // progress — always visible
+  );
+  activePipeline = pipeline;
+  try {
+    step("Starting analysis pipeline...");
+    console.log();
+    const result = await pipeline.run();
+    if (result.transcriptSegments === 0 && result.extractedFrames === 0) {
+      console.log();
+      fail("Analysis produced no output (no transcript, no frames).");
+      console.log("  Possible causes:");
+      console.log("  - Video has no audio track (provide --audio <file>)");
+      console.log("  - Whisper model not installed (check --whisper-model)");
+      console.log("  - ffmpeg not installed (brew install ffmpeg)");
+      process.exit(EXIT_USER_ERROR);
+    }
+    console.log();
+    success("Analysis complete!");
+    console.log();
+    console.log(`  Transcript segments: ${result.transcriptSegments}`);
+    console.log(`  Extracted frames:    ${result.extractedFrames}`);
+    console.log(`  Processing time:     ${result.durationSeconds.toFixed(1)}s`);
+    console.log();
+    console.log(`  Output: ${result.outputPath}`);
+    console.log(`OUTPUT:${result.outputPath}`);
+    console.log();
+  } catch (error) {
+    console.log();
+    const message = error instanceof Error ? error.message : String(error);
+    fail(`Analysis failed: ${message}`);
+    if (options.verbose && error instanceof Error && error.stack) {
+      console.log();
+      console.log(error.stack);
+    }
+    const exitCode = error instanceof CLIPipelineError && error.severity === "user" ? EXIT_USER_ERROR : EXIT_SYSTEM_ERROR;
+    process.exit(exitCode);
+  } finally {
+    activePipeline = null;
+  }
+});
+if (process.argv.length <= 2) {
+  banner();
+  program.outputHelp();
+  process.exit(EXIT_SUCCESS);
+}
+program.parse();