tracegist-mcp-bridge 0.2.2 → 0.2.4

package/bin/lib.mjs

@@ -0,0 +1,153 @@
+import path from "node:path";
+
+const PACKAGE_SUFFIX = "-package.zip";
+const HANDOFF_SUFFIXES = ["-coding-agent-handoff.md", "-cursor-handoff.md"];
+
+export function isTraceGistPackageFile(fileName) {
+  return fileName.startsWith("tracegist-") && fileName.endsWith(PACKAGE_SUFFIX);
+}
+
+export function normalizeZipBaseName(entryName) {
+  return path.posix.basename(entryName).toLowerCase();
+}
+
+export function renderPackagesText(packages, directory) {
+  if (packages.length === 0) {
+    return [
+      `No TraceGist package zips found in ${directory}.`,
+      "Expected naming pattern: tracegist-...-package.zip",
+    ].join("\n");
+  }
+  const lines = [`Found ${packages.length} TraceGist package(s) in ${directory}:`, ""];
+  for (const pkg of packages) {
+    lines.push(
+      `- ${pkg.name}`,
+      `  path: ${pkg.path}`,
+      `  size: ${pkg.sizeBytes} bytes`,
+      `  modified: ${pkg.modifiedAt}`,
+      "",
+    );
+  }
+  return lines.join("\n");
+}
+
+export function parseMarkdownSections(markdown) {
+  const sections = [];
+  const lines = markdown.split("\n");
+  let currentName = null;
+  let currentStart = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      if (currentName !== null) {
+        sections.push({
+          name: currentName,
+          content: lines.slice(currentStart, i).join("\n"),
+        });
+      }
+      currentName = lines[i].slice(3).trim();
+      currentStart = i;
+    }
+  }
+
+  if (currentName !== null) {
+    sections.push({
+      name: currentName,
+      content: lines.slice(currentStart).join("\n"),
+    });
+  }
+
+  return sections;
+}
+
+/**
+ * Brief purpose hints for known handoff sections.
+ * Keys are matched case-insensitively against section names.
+ * Unknown sections get a generic hint so the TOC is never incomplete.
+ */
+const SECTION_HINTS = {
+  "session triage": "Tester summary: expected vs actual, severity",
+  "agent guidance": "Suggested investigation focus areas",
+  "session context note": "Starting state before the bug (not a bug itself)",
+  "notable anomalies": "Pre-flagged JS errors, failed requests, warnings",
+  "marker timeline": "Timestamped markers with ±5 s event windows — start here for analysis",
+  "user interaction timeline": "Full click/fill/navigation sequence — key for reproduction",
+  "session context": "Page URL, title, session metadata",
+  "session environment": "Browser, viewport, OS — match for reproduction",
+  "package files": "Paths to Playwright script, manifest, network bodies",
+  "marker-to-file mapping": "Which screenshots/voice files belong to each marker",
+  "backend log correlation": "Absolute timestamps for server-side log alignment",
+  "full session console timeline": "All console output (deep exports only)",
+  "full session network timeline": "All network requests (deep exports only)",
+  "full session network timeline (third-party only)":
+    "Third-party network calls (deep exports only)",
+  "full session timelines": "Placeholder when deep timelines are omitted",
+  context: "AI-generated analysis context (when available)",
+  "tracegist agent-processed context": "LLM-processed summary of the session",
+  "tester intent": "What the tester was trying to accomplish",
+  "handover tasks for coding agent": "Specific tasks the tester wants the agent to do",
+  "marker visual evidence": "Screenshot references for each marker",
+  "environment at marker time": "Environment snapshot at a specific marker",
+  "marker timeline logs (context window)": "Logs within the ±5 s marker window",
+};
+
+function getSectionHint(sectionName) {
+  return SECTION_HINTS[sectionName.toLowerCase()] || "Additional section";
+}
+
+export function renderSectionToc(sections, zipPath) {
+  const totalChars = sections.reduce((sum, s) => sum + s.content.length, 0);
+  const lines = [
+    `Handoff document for ${path.basename(zipPath)} — ${sections.length} sections, ${totalChars.toLocaleString()} chars total.`,
+    "",
+    "| # | Section | Size | Purpose |",
+    "|---|---------|------|---------|",
+  ];
+  for (let i = 0; i < sections.length; i++) {
+    const hint = getSectionHint(sections[i].name);
+    lines.push(
+      `| ${i + 1} | ${sections[i].name} | ${sections[i].content.length.toLocaleString()} chars | ${hint} |`,
+    );
+  }
+  lines.push(
+    "",
+    "**Reading guide:** For analysis, start with Session Triage → Marker Timeline → Notable Anomalies.",
+    "For reproduction, start with Session Environment → User Interaction Timeline → Package Files (Playwright script path).",
+    "",
+    'Pass `section` with a section name (e.g. "Marker Timeline") to retrieve its full content.',
+  );
+  return lines.join("\n");
+}
+
+export function looksLikeVoiceNote(entryName) {
+  const base = path.posix.basename(entryName).toLowerCase();
+  return /voice/.test(base) && /\.(webm|wav|mp3|m4a|ogg|flac)$/i.test(base);
+}
+
+export async function mapConcurrent(items, fn, concurrency) {
+  const results = new Array(items.length);
+  let i = 0;
+  const worker = async () => {
+    while (i < items.length) {
+      const idx = i++;
+      results[idx] = await fn(items[idx], idx);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+  return results;
+}
+
+export function toolError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true,
+  };
+}
+
+export function formatExecError(err) {
+  if (err instanceof Error && err.message) return err.message;
+  return String(err);
+}
+
+export { HANDOFF_SUFFIXES };