markupr 2.1.8 → 2.5.0

package/src/main/output/MarkdownPatcher.ts

@@ -1,299 +0,0 @@
-/**
- * MarkdownPatcher
- *
- * Post-processing utilities for patching generated markdown reports with
- * extracted frame links, metadata sync, and processing traces. Extracted
- * from index.ts for separation of concerns.
- */
-
-import * as fs from 'fs/promises';
-import { join, basename } from 'path';
-import type { TranscriptSegment, KeyMoment } from '../pipeline';
-
-// =============================================================================
-// Text Normalization Helpers
-// =============================================================================
-
-export function formatSecondsAsTimestamp(seconds: number): string {
-  const total = Math.max(0, Math.floor(seconds));
-  const mins = Math.floor(total / 60);
-  const secs = total % 60;
-  return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
-}
-
-function normalizeForMatch(value: string): string {
-  return value
-    .toLowerCase()
-    .replace(/[`*_~[\]().,!?;:'"\\/|-]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function buildTokenSet(value: string): Set<string> {
-  const tokens = normalizeForMatch(value)
-    .split(' ')
-    .map((token) => token.trim())
-    .filter((token) => token.length >= 3);
-  return new Set(tokens);
-}
-
-function overlapScore(a: Set<string>, b: Set<string>): number {
-  if (a.size === 0 || b.size === 0) {
-    return 0;
-  }
-  let overlap = 0;
-  for (const token of a) {
-    if (b.has(token)) {
-      overlap += 1;
-    }
-  }
-  return overlap / Math.min(a.size, b.size);
-}
-
-// =============================================================================
-// AI Frame Hint Extraction
-// =============================================================================
-
-/**
- * Parse AI-generated markdown to extract frame extraction hints.
- * Matches **Timestamp:** annotations and blockquote references back
- * to transcript segments for accurate frame timing.
- */
-export function extractAiFrameHintsFromMarkdown(
-  markdown: string,
-  transcriptSegments: TranscriptSegment[]
-): KeyMoment[] {
-  if (!markdown) {
-    return [];
-  }
-
-  const parseTimestampToSeconds = (value: string): number | null => {
-    const trimmed = value.trim();
-    const parts = trimmed.split(':').map((part) => Number.parseInt(part, 10));
-    if (parts.some((part) => !Number.isFinite(part) || part < 0)) {
-      return null;
-    }
-    if (parts.length === 2) {
-      return parts[0] * 60 + parts[1];
-    }
-    if (parts.length === 3) {
-      return parts[0] * 3600 + parts[1] * 60 + parts[2];
-    }
-    return null;
-  };
-
-  const timestampHints = Array.from(markdown.matchAll(/\*\*Timestamp:\*\*\s*([0-9]{1,2}:[0-9]{2}(?::[0-9]{2})?)/g))
-    .map((match) => parseTimestampToSeconds(match[1]))
-    .filter((value): value is number => value !== null)
-    .map((seconds) => ({
-      timestamp: Math.max(0, seconds),
-      reason: 'AI-timestamped issue context',
-      confidence: 0.96,
-    }));
-
-  const quoteLines = Array.from(markdown.matchAll(/^\s*>\s+(.+)$/gm))
-    .map((match) => match[1].trim())
-    .filter((line) => line.length >= 10);
-  if (quoteLines.length === 0 && timestampHints.length === 0) {
-    return [];
-  }
-
-  const normalizedSegments = transcriptSegments.map((segment) => ({
-    segment,
-    normalized: normalizeForMatch(segment.text || ''),
-    tokens: buildTokenSet(segment.text || ''),
-  }));
-
-  const hints: KeyMoment[] = [...timestampHints];
-  const seenQuotes = new Set<string>();
-
-  for (const quote of quoteLines) {
-    const normalizedQuote = normalizeForMatch(quote);
-    if (!normalizedQuote || seenQuotes.has(normalizedQuote)) {
-      continue;
-    }
-    seenQuotes.add(normalizedQuote);
-
-    const quoteTokens = buildTokenSet(quote);
-    let bestMatch: { score: number; segment: TranscriptSegment } | null = null;
-
-    for (const candidate of normalizedSegments) {
-      if (!candidate.normalized) {
-        continue;
-      }
-
-      let score = overlapScore(quoteTokens, candidate.tokens);
-      if (
-        normalizedQuote.length >= 16 &&
-        (candidate.normalized.includes(normalizedQuote) || normalizedQuote.includes(candidate.normalized))
-      ) {
-        score = Math.max(score, 0.9);
-      }
-
-      if (!bestMatch || score > bestMatch.score) {
-        bestMatch = { score, segment: candidate.segment };
-      }
-    }
-
-    if (!bestMatch || bestMatch.score < 0.34) {
-      continue;
-    }
-
-    const midpoint =
-      bestMatch.segment.startTime +
-      Math.max(0, (bestMatch.segment.endTime - bestMatch.segment.startTime) / 2);
-    hints.push({
-      timestamp: Math.max(0, midpoint),
-      reason: 'AI-highlighted context',
-      confidence: Math.min(0.98, 0.58 + bestMatch.score * 0.35),
-    });
-  }
-
-  if (hints.length === 0) {
-    return [];
-  }
-
-  const sorted = hints.sort((a, b) => a.timestamp - b.timestamp);
-  const deduped: KeyMoment[] = [];
-  for (const hint of sorted) {
-    const previous = deduped[deduped.length - 1];
-    if (!previous || Math.abs(previous.timestamp - hint.timestamp) >= 1.0) {
-      deduped.push(hint);
-      continue;
-    }
-    if (hint.confidence > previous.confidence) {
-      deduped[deduped.length - 1] = hint;
-    }
-  }
-
-  return deduped.slice(0, 12);
-}
-
-// =============================================================================
-// Report Patching
-// =============================================================================
-
-/**
- * Append extracted video frames to the markdown report.
- * Verifies each frame path exists before linking to avoid broken images.
- */
-export async function appendExtractedFramesToReport(
-  markdownPath: string,
-  extractedFrames: Array<{ path: string; timestamp: number; reason: string }>
-): Promise<void> {
-  if (!extractedFrames.length) {
-    return;
-  }
-
-  const verifiedFrames: Array<{ path: string; timestamp: number; reason: string }> = [];
-  for (const frame of extractedFrames) {
-    try {
-      await fs.access(frame.path);
-      verifiedFrames.push(frame);
-    } catch {
-      // Skip stale frame references so markdown never links missing files.
-    }
-  }
-  if (!verifiedFrames.length) {
-    return;
-  }
-
-  let markdown = await fs.readFile(markdownPath, 'utf-8');
-  if (markdown.includes('## Auto-Extracted Screenshots')) {
-    return;
-  }
-
-  const lines = verifiedFrames
-    .slice()
-    .sort((a, b) => a.timestamp - b.timestamp)
-    .map((frame, index) => {
-      const filename = basename(frame.path) || `frame-${String(index + 1).padStart(3, '0')}.png`;
-      const timestamp = formatSecondsAsTimestamp(frame.timestamp);
-      const reason = frame.reason?.trim() || 'Auto-extracted frame';
-      return `### [${timestamp}] ${reason}\n\n![${reason}](./screenshots/${filename})`;
-    })
-    .join('\n\n');
-
-  markdown += `\n## Auto-Extracted Screenshots\n\n${lines}\n`;
-
-  // Keep report header/session info counts aligned with the post-processed frame output.
-  const screenshotCount = verifiedFrames.length;
-  markdown = markdown.replace(
-    /(\|\s*Duration:\s*[^|]+\|\s*)\d+\s+screenshots(\s*\|\s*\d+\s+items identified\s*\n)/,
-    `$1${screenshotCount} screenshots$2`
-  );
-  markdown = markdown.replace(
-    /(-\s*\*\*Screenshots:\*\*\s*)\d+/,
-    `$1${screenshotCount}`
-  );
-
-  await fs.writeFile(markdownPath, markdown, 'utf-8');
-}
-
-/**
- * Sync extracted frame count into session metadata.json.
- */
-export async function syncExtractedFrameMetadata(
-  sessionDir: string,
-  screenshotCount: number
-): Promise<void> {
-  const metadataPath = join(sessionDir, 'metadata.json');
-  try {
-    const raw = await fs.readFile(metadataPath, 'utf-8');
-    const metadata = JSON.parse(raw) as { screenshotCount?: number };
-    metadata.screenshotCount = Math.max(
-      Number.isFinite(metadata.screenshotCount) ? Number(metadata.screenshotCount) : 0,
-      screenshotCount
-    );
-    await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), 'utf-8');
-  } catch (error) {
-    console.warn('[Main] Failed to sync extracted frame metadata:', error);
-  }
-}
-
-/**
- * Sync extracted frame count into feedback-summary.md.
- */
-export async function syncExtractedFrameSummary(
-  sessionDir: string,
-  screenshotCount: number
-): Promise<void> {
-  const summaryPath = join(sessionDir, 'feedback-summary.md');
-  try {
-    const raw = await fs.readFile(summaryPath, 'utf-8');
-    const updated = raw.replace(/(\*\*Screenshots:\*\*\s*)\d+/, `$1${screenshotCount}`);
-    if (updated !== raw) {
-      await fs.writeFile(summaryPath, updated, 'utf-8');
-    }
-  } catch (error) {
-    console.warn('[Main] Failed to sync extracted frame summary:', error);
-  }
-}
-
-/**
- * Write a processing trace JSON file for debugging/diagnostics.
- */
-export async function writeProcessingTrace(
-  sessionDir: string,
-  trace: {
-    reportPath: string;
-    totalMs: number;
-    aiMs: number;
-    saveMs: number;
-    postProcessMs: number;
-    audioBytes: number;
-    recordingBytes: number;
-    transcriptBufferEvents: number;
-    providedTranscriptSegments: number;
-    aiFrameHints: number;
-    postProcessSegments: number;
-    extractedFrames: number;
-    aiTier: 'free' | 'byok' | 'premium';
-    aiEnhanced: boolean;
-    aiFallbackReason?: string;
-    completedAt: string;
-  }
-): Promise<void> {
-  const tracePath = join(sessionDir, 'processing-trace.json');
-  await fs.writeFile(tracePath, JSON.stringify(trace, null, 2), 'utf-8');
-}

package/src/main/output/index.ts

@@ -1,186 +0,0 @@
-/**
- * Output Module
- *
- * Handles:
- * - Markdown document generation
- * - Screenshot embedding (base64)
- * - Timestamp formatting
- * - Clipboard integration
- * - File output management
- */
-
-import type { FeedbackSession, OutputDocument, Screenshot, TranscriptionSegment } from '../../shared/types';
-import { clipboardService, type ClipboardService } from './ClipboardService';
-import type { Session } from '../SessionController';
-
-export class OutputManager {
-  private clipboard: ClipboardService;
-
-  constructor() {
-    this.clipboard = clipboardService;
-  }
-  /**
-   * Generate a Markdown document from a feedback session
-   */
-  generateMarkdown(session: FeedbackSession): OutputDocument {
-    const { id, screenshots, transcription, startedAt, endedAt } = session;
-
-    // Build markdown content
-    let markdown = '# Feedback Session\n\n';
-
-    // Session metadata
-    markdown += `**Session ID:** ${id}\n`;
-    markdown += `**Started:** ${new Date(startedAt).toISOString()}\n`;
-    if (endedAt) {
-      markdown += `**Ended:** ${new Date(endedAt).toISOString()}\n`;
-      markdown += `**Duration:** ${Math.round((endedAt - startedAt) / 1000)}s\n`;
-    }
-    markdown += '\n---\n\n';
-
-    // Interleave transcription and screenshots by timestamp
-    const timeline = this.buildTimeline(transcription, screenshots);
-
-    for (const item of timeline) {
-      if (item.type === 'text') {
-        markdown += `${item.content}\n\n`;
-      } else if (item.type === 'screenshot') {
-        markdown += `![Screenshot at ${this.formatTimestamp(item.timestamp)}](${item.content})\n\n`;
-      }
-    }
-
-    return {
-      sessionId: id,
-      generatedAt: Date.now(),
-      markdown,
-      screenshots,
-    };
-  }
-
-  /**
-   * Build a timeline interleaving transcription and screenshots
-   */
-  private buildTimeline(
-    transcription: TranscriptionSegment[],
-    screenshots: Screenshot[]
-  ): Array<{ type: 'text' | 'screenshot'; content: string; timestamp: number }> {
-    const timeline: Array<{ type: 'text' | 'screenshot'; content: string; timestamp: number }> = [];
-
-    // Add transcription segments
-    for (const segment of transcription) {
-      timeline.push({
-        type: 'text',
-        content: segment.text,
-        timestamp: segment.startTime,
-      });
-    }
-
-    // Add screenshots
-    for (const screenshot of screenshots) {
-      timeline.push({
-        type: 'screenshot',
-        content: screenshot.base64 || screenshot.imagePath,
-        timestamp: screenshot.timestamp,
-      });
-    }
-
-    // Sort by timestamp
-    timeline.sort((a, b) => a.timestamp - b.timestamp);
-
-    return timeline;
-  }
-
-  /**
-   * Format a timestamp as a readable string
-   */
-  private formatTimestamp(timestamp: number): string {
-    const date = new Date(timestamp);
-    return date.toLocaleTimeString('en-US', {
-      hour: '2-digit',
-      minute: '2-digit',
-      second: '2-digit',
-    });
-  }
-
-  /**
-   * Copy a summary of the session to clipboard with notification
-   */
-  async copySessionSummary(
-    session: Session,
-    reportPath?: string
-  ): Promise<boolean> {
-    const summary = this.clipboard.generateClipboardSummary(session, {
-      mode: 'compact',
-      maxLength: 1500,
-      includeReportPath: !!reportPath,
-      reportPath,
-    });
-
-    return this.clipboard.copyWithNotification(
-      summary,
-      'Feedback Captured!'
-    );
-  }
-
-  /**
-   * Copy custom content to clipboard with notification
-   */
-  async copyToClipboard(content: string, title?: string): Promise<boolean> {
-    return this.clipboard.copyWithNotification(content, title);
-  }
-
-  /**
-   * Get the clipboard service for direct access
-   */
-  getClipboardService(): ClipboardService {
-    return this.clipboard;
-  }
-}
-
-// Singleton instance
-export const outputManager = new OutputManager();
-
-export default OutputManager;
-
-// Re-export clipboard service types and instance
-export { clipboardService, type ClipboardService, type SummaryOptions } from './ClipboardService';
-
-// Re-export file manager types and instance
-export { FileManager, fileManager, type SaveResult, type MarkdownDocument } from './FileManager';
-
-// Re-export new llms.txt-inspired markdown generator
-export {
-  markdownGenerator,
-  MarkdownGenerator,
-  adaptFeedbackSession,
-  type IMarkdownGenerator,
-  type Session as MarkdownSession,
-  type FeedbackItem,
-  type FeedbackCategory,
-  type FeedbackSeverity,
-  type GenerateOptions,
-  type MarkdownDocument as EnhancedMarkdownDocument,
-  type SessionMetadata,
-} from './MarkdownGenerator';
-
-// Re-export session adapter for type conversion
-export {
-  adaptSessionForMarkdown,
-  generateDocumentForFileManager,
-  generateClipboardSummary,
-} from './sessionAdapter';
-
-// Re-export export service for multi-format export
-export {
-  exportService,
-  ExportService,
-  generateHtmlDocument,
-  type ExportFormat,
-  type ExportOptions,
-  type ExportResult,
-  type PdfOptions,
-  type HtmlOptions,
-  type JsonOptions,
-  type MarkdownOptions,
-  type JsonExportSchema,
-  type HtmlExportOptions,
-} from './ExportService';

package/src/main/output/sessionAdapter.ts

@@ -1,207 +0,0 @@
-/**
- * Session Adapter
- *
- * Converts between different session types used across the codebase.
- * This is needed because:
- * - SessionController uses its own Session/FeedbackItem types
- * - MarkdownGenerator uses enhanced Session/FeedbackItem types
- * - FileManager uses its own MarkdownDocument type
- */
-
-import type { Session as ControllerSession, FeedbackItem as ControllerFeedbackItem } from '../SessionController';
-import type { TranscriptEvent } from '../transcription/types';
-import type {
-  Session as MarkdownSession,
-  FeedbackItem as MarkdownFeedbackItem,
-  FeedbackCategory,
-  FeedbackSeverity,
-  GenerateOptions,
-} from './MarkdownGenerator';
-import type { MarkdownDocument as FileManagerDocument } from './FileManager';
-import { markdownGenerator } from './MarkdownGenerator';
-import { feedbackAnalyzer } from '../analysis';
-
-const NO_TRANSCRIPTION_PLACEHOLDER =
-  '[Narration was recorded but not transcribed. Add an OpenAI API key, or download a Tiny Whisper model for local fallback.]';
-
-/**
- * Map analyzer category labels to markdown report labels
- */
-function mapCategory(category: ReturnType<typeof feedbackAnalyzer.analyze>['category']): FeedbackCategory {
-  switch (category) {
-    case 'bug':
-      return 'Bug';
-    case 'ux-issue':
-      return 'UX Issue';
-    case 'suggestion':
-      return 'Suggestion';
-    case 'performance':
-      return 'Performance';
-    case 'question':
-      return 'Question';
-    default:
-      return 'General';
-  }
-}
-
-function mapSeverity(severity: ReturnType<typeof feedbackAnalyzer.analyze>['severity']): FeedbackSeverity {
-  switch (severity) {
-    case 'critical':
-      return 'Critical';
-    case 'high':
-      return 'High';
-    case 'medium':
-      return 'Medium';
-    default:
-      return 'Low';
-  }
-}
-
-/**
- * Convert SessionController.FeedbackItem to MarkdownGenerator.FeedbackItem
- */
-function adaptFeedbackItem(item: ControllerFeedbackItem, index: number): MarkdownFeedbackItem {
-  const transcription = item.text.trim() || NO_TRANSCRIPTION_PLACEHOLDER;
-  const analysis = feedbackAnalyzer.analyze(transcription);
-
-  return {
-    id: item.id || `item-${index + 1}`,
-    transcription,
-    timestamp: item.timestamp,
-    category: mapCategory(analysis.category),
-    severity: mapSeverity(analysis.severity),
-    title: analysis.suggestedTitle,
-    keywords: analysis.keywords,
-    screenshots: item.screenshot ? [{
-      id: item.screenshot.id,
-      timestamp: item.screenshot.timestamp,
-      width: item.screenshot.width,
-      height: item.screenshot.height,
-      imagePath: '', // Filled in by FileManager when saving
-      base64: item.screenshot.base64,
-    }] : [],
-  };
-}
-
-function buildTranscriptOnlyItems(session: ControllerSession): MarkdownFeedbackItem[] {
-  const finalTranscripts = session.transcriptBuffer
-    .filter((event) => event.isFinal && event.text.trim().length > 0)
-    .sort((a, b) => a.timestamp - b.timestamp);
-
-  const usableTranscripts = finalTranscripts.length > 0
-    ? finalTranscripts
-    : session.transcriptBuffer
-        .filter((event) => event.text.trim().length > 0)
-        .sort((a, b) => a.timestamp - b.timestamp);
-
-  if (usableTranscripts.length === 0) {
-    return [];
-  }
-
-  const grouped: Array<{ timestampMs: number; transcripts: TranscriptEvent[] }> = [];
-  const GROUP_GAP_MS = 2200;
-
-  for (const transcript of usableTranscripts) {
-    const timestampMs = Math.round(transcript.timestamp * 1000);
-    const previousGroup = grouped[grouped.length - 1];
-
-    if (!previousGroup || timestampMs - previousGroup.timestampMs > GROUP_GAP_MS) {
-      grouped.push({
-        timestampMs,
-        transcripts: [transcript],
-      });
-      continue;
-    }
-
-    previousGroup.transcripts.push(transcript);
-    previousGroup.timestampMs = timestampMs;
-  }
-
-  return grouped.map((group, index) => {
-    const transcription = group.transcripts
-      .map((transcript) => transcript.text.trim())
-      .join(' ')
-      .replace(/\s+/g, ' ')
-      .trim();
-
-    const analysis = feedbackAnalyzer.analyze(transcription);
-
-    return {
-      id: `transcript-only-${index + 1}`,
-      transcription,
-      timestamp: group.timestampMs,
-      category: mapCategory(analysis.category),
-      severity: mapSeverity(analysis.severity),
-      title: analysis.suggestedTitle,
-      keywords: analysis.keywords,
-      screenshots: [],
-    };
-  });
-}
-
-/**
- * Convert SessionController.Session to MarkdownGenerator.Session
- */
-export function adaptSessionForMarkdown(session: ControllerSession): MarkdownSession {
-  const adaptedFromScreenshots = session.feedbackItems.map((item, index) => adaptFeedbackItem(item, index));
-  const transcriptOnlyItems = buildTranscriptOnlyItems(session);
-  const hasNarratedScreenshotItems = adaptedFromScreenshots.some(
-    (item) => item.transcription !== NO_TRANSCRIPTION_PLACEHOLDER
-  );
-
-  const adaptedItems =
-    adaptedFromScreenshots.length === 0
-      ? transcriptOnlyItems
-      : hasNarratedScreenshotItems || transcriptOnlyItems.length === 0
-        ? adaptedFromScreenshots
-        : [...adaptedFromScreenshots, ...transcriptOnlyItems];
-
-  return {
-    id: session.id,
-    startTime: session.startTime,
-    endTime: session.endTime,
-    feedbackItems: adaptedItems,
-    metadata: {
-      os: process.platform,
-      sourceName: session.metadata?.sourceName || 'Screen',
-      sourceType: session.sourceId.startsWith('screen') ? 'screen' : 'window',
-    },
-  };
-}
-
-/**
- * Generate a FileManager-compatible MarkdownDocument from a SessionController session
- */
-export function generateDocumentForFileManager(
-  session: ControllerSession,
-  options?: Partial<GenerateOptions>
-): FileManagerDocument {
-  const adaptedSession = adaptSessionForMarkdown(session);
-  const fullOptions: GenerateOptions = {
-    projectName: options?.projectName || session.metadata?.sourceName || 'Feedback Session',
-    screenshotDir: options?.screenshotDir || './screenshots',
-  };
-
-  const generatedDoc = markdownGenerator.generateFullDocument(adaptedSession, fullOptions);
-
-  // Convert MarkdownGenerator.MarkdownDocument to FileManager.MarkdownDocument
-  return {
-    content: generatedDoc.content,
-    metadata: {
-      itemCount: generatedDoc.metadata.itemCount,
-      screenshotCount: generatedDoc.metadata.screenshotCount,
-      types: Object.keys(generatedDoc.metadata.types),
-    },
-  };
-}
-
-/**
- * Generate clipboard summary from a SessionController session
- */
-export function generateClipboardSummary(session: ControllerSession, projectName?: string): string {
-  const adaptedSession = adaptSessionForMarkdown(session);
-  return markdownGenerator.generateClipboardSummary(
-    adaptedSession,
-    projectName || session.metadata?.sourceName || 'Feedback Session'
-  );
-}