stego-cli 0.3.1 → 0.3.3

package/dist/comments/add-comment.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { CommentsCommandError } from "./errors.js";
-const COMMENT_HEADING_REGEX = /^###\s+(CMT-(\d{4,}))\s*$/;
+const COMMENT_DELIMITER_REGEX = /^<!--\s*comment:\s*(CMT-(\d{4,}))\s*-->\s*$/i;
+const LEGACY_COMMENT_HEADING_REGEX = /^###\s+(CMT-(\d{4,}))\s*$/i;
 const START_SENTINEL = "<!-- stego-comments:start -->";
 const END_SENTINEL = "<!-- stego-comments:end -->";
 /** Adds one stego comment entry to a manuscript and writes the updated file. */
@@ -18,11 +19,35 @@ export function addCommentToManuscript(request) {
     if (!sentinelState.hasSentinels && !hasYamlFrontmatter) {
         throw new CommentsCommandError("NOT_STEGO_MANUSCRIPT", 3, "File is not recognized as a Stego manuscript (missing frontmatter and comments sentinels).");
     }
-    const commentId = getNextCommentId(lines);
-    const createdAt = new Date().toISOString();
-    const meta = buildMetaPayload(request.range, request.sourceMeta);
+    const commentId = getNextCommentId(lines, sentinelState);
+    const now = new Date();
+    const createdAt = now.toISOString();
+    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+    const timezoneOffsetMinutes = -now.getTimezoneOffset();
+    const paragraphIndex = request.range
+        ? resolveParagraphIndex(lines, lineEnding, sentinelState, request.range)
+        : undefined;
+    const excerpt = request.range
+        ? extractExcerptForRange(lines, request.range)
+        : undefined;
+    const meta = buildMetaPayload({
+        createdAt,
+        timezone,
+        timezoneOffsetMinutes,
+        paragraphIndex,
+        range: request.range,
+        sourceMeta: request.sourceMeta
+    });
     const meta64 = Buffer.from(JSON.stringify(meta), "utf8").toString("base64url");
-    const entryLines = buildCommentEntryLines(commentId, createdAt, request.author, request.message, meta64);
+    const entryLines = buildCommentEntryLines({
+        commentId,
+        createdAt,
+        author: request.author,
+        message: request.message,
+        meta64,
+        paragraphIndex,
+        excerpt
+    });
     const nextLines = applyCommentEntry(lines, sentinelState, entryLines);
     const nextContent = `${nextLines.join(lineEnding)}${lineEnding}`;
     try {
@@ -50,37 +75,53 @@ export function addCommentToManuscript(request) {
     };
     return result;
 }
-function buildMetaPayload(range, sourceMeta) {
+function buildMetaPayload(input) {
     const payload = {
-        status: "open"
+        status: "open",
+        created_at: input.createdAt,
+        timezone_offset_minutes: input.timezoneOffsetMinutes
     };
-    if (range) {
-        payload.anchor = "selection";
-        payload.excerpt = {
-            start_line: range.startLine,
-            start_col: range.startCol,
-            end_line: range.endLine,
-            end_col: range.endCol
-        };
+    if (input.timezone) {
+        payload.timezone = input.timezone;
+    }
+    if (input.paragraphIndex !== undefined) {
+        payload.paragraph_index = input.paragraphIndex;
     }
-    if (sourceMeta && Object.keys(sourceMeta).length > 0) {
-        payload.signature = sourceMeta;
+    if (input.range) {
+        payload.excerpt_start_line = input.range.startLine;
+        payload.excerpt_start_col = input.range.startCol;
+        payload.excerpt_end_line = input.range.endLine;
+        payload.excerpt_end_col = input.range.endCol;
+    }
+    if (input.sourceMeta && Object.keys(input.sourceMeta).length > 0) {
+        payload.signature = input.sourceMeta;
     }
     return payload;
 }
-function buildCommentEntryLines(commentId, timestamp, author, message, meta64) {
-    const safeAuthor = author.trim() || "Saurus";
-    const normalizedMessageLines = message
+function buildCommentEntryLines(input) {
+    const safeAuthor = input.author.trim() || "Saurus";
+    const normalizedMessageLines = input.message
         .replace(/\r\n/g, "\n")
         .split("\n")
         .map((line) => line.trimEnd());
-    return [
-        `### ${commentId}`,
-        `<!-- meta64: ${meta64} -->`,
-        `> _${timestamp} | ${safeAuthor}_`,
-        ">",
-        ...normalizedMessageLines.map((line) => `> ${line}`)
+    const displayTimestamp = formatHumanTimestamp(input.createdAt);
+    const headerTimestamp = escapeThreadHeaderPart(displayTimestamp);
+    const headerAuthor = escapeThreadHeaderPart(safeAuthor);
+    const lines = [
+        `<!-- comment: ${input.commentId} -->`,
+        `<!-- meta64: ${input.meta64} -->`,
+        `> _${headerTimestamp} — ${headerAuthor}_`,
+        ">"
     ];
+    if (input.paragraphIndex !== undefined && input.excerpt) {
+        const truncatedExcerpt = input.excerpt.length > 100
+            ? `${input.excerpt.slice(0, 100).trimEnd()}…`
+            : input.excerpt;
+        lines.push(`> > “${truncatedExcerpt}”`);
+        lines.push(">");
+    }
+    lines.push(...normalizedMessageLines.map((line) => `> ${line}`));
+    return lines;
 }
 function applyCommentEntry(lines, sentinelState, entryLines) {
     if (!sentinelState.hasSentinels) {
@@ -142,11 +183,15 @@ function findTrimmedLineIndexes(lines, target) {
     }
     return indexes;
 }
-function getNextCommentId(lines) {
+function getNextCommentId(lines, sentinelState) {
+    const candidateLines = sentinelState.hasSentinels
+        ? lines.slice(sentinelState.startIndex + 1, sentinelState.endIndex)
+        : lines;
     let maxId = 0;
-    for (const line of lines) {
-        const match = line.trim().match(COMMENT_HEADING_REGEX);
-        if (!match) {
+    for (const line of candidateLines) {
+        const trimmed = line.trim();
+        const match = trimmed.match(COMMENT_DELIMITER_REGEX) ?? trimmed.match(LEGACY_COMMENT_HEADING_REGEX);
+        if (!match || !match[2]) {
             continue;
         }
         const numeric = Number.parseInt(match[2], 10);
@@ -157,6 +202,166 @@ function getNextCommentId(lines) {
     const next = maxId + 1;
     return `CMT-${String(next).padStart(4, "0")}`;
 }
+function resolveParagraphIndex(lines, lineEnding, sentinelState, range) {
+    const markdownWithoutComments = stripCommentsAppendix(lines, sentinelState, lineEnding);
+    const { body, lineOffset } = splitFrontmatterForAnchors(markdownWithoutComments);
+    const paragraphs = extractParagraphs(body).map((paragraph) => ({
+        ...paragraph,
+        startLine: paragraph.startLine + lineOffset,
+        endLine: paragraph.endLine + lineOffset
+    }));
+    const matched = findParagraphForLine(paragraphs, range.startLine) ?? findPreviousParagraphForLine(paragraphs, range.startLine);
+    return matched?.index;
+}
+function extractExcerptForRange(lines, range) {
+    const startLineIndex = range.startLine - 1;
+    const endLineIndex = range.endLine - 1;
+    if (startLineIndex < 0 || endLineIndex < 0 || startLineIndex >= lines.length || endLineIndex >= lines.length) {
+        return undefined;
+    }
+    if (startLineIndex > endLineIndex || (startLineIndex === endLineIndex && range.startCol >= range.endCol)) {
+        return undefined;
+    }
+    const startLineText = lines[startLineIndex] ?? "";
+    const endLineText = lines[endLineIndex] ?? "";
+    const safeStartCol = clamp(range.startCol, 0, startLineText.length);
+    const safeEndCol = clamp(range.endCol, 0, endLineText.length);
+    let selected = "";
+    if (startLineIndex === endLineIndex) {
+        if (safeStartCol >= safeEndCol) {
+            return undefined;
+        }
+        selected = startLineText.slice(safeStartCol, safeEndCol);
+    }
+    else {
+        const segments = [];
+        segments.push(startLineText.slice(safeStartCol));
+        for (let lineIndex = startLineIndex + 1; lineIndex < endLineIndex; lineIndex += 1) {
+            segments.push(lines[lineIndex] ?? "");
+        }
+        segments.push(endLineText.slice(0, safeEndCol));
+        selected = segments.join("\n");
+    }
+    const compact = compactExcerpt(selected);
+    return compact || undefined;
+}
+function clamp(value, min, max) {
+    if (value < min) {
+        return min;
+    }
+    if (value > max) {
+        return max;
+    }
+    return value;
+}
+function compactExcerpt(value, max = 180) {
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (compact.length <= max) {
+        return compact;
+    }
+    return `${compact.slice(0, max - 1)}…`;
+}
+function stripCommentsAppendix(lines, sentinelState, lineEnding) {
+    if (!sentinelState.hasSentinels) {
+        return lines.join(lineEnding);
+    }
+    let removeStart = sentinelState.startIndex;
+    if (removeStart > 0 && lines[removeStart - 1].trim().length === 0) {
+        removeStart -= 1;
+    }
+    const keptLines = [...lines.slice(0, removeStart), ...lines.slice(sentinelState.endIndex + 1)];
+    while (keptLines.length > 0 && keptLines[keptLines.length - 1].trim().length === 0) {
+        keptLines.pop();
+    }
+    return keptLines.join(lineEnding);
+}
+function splitFrontmatterForAnchors(markdownText) {
+    const frontmatterMatch = markdownText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!frontmatterMatch) {
+        return {
+            body: markdownText,
+            lineOffset: 0
+        };
+    }
+    const consumed = frontmatterMatch[0];
+    return {
+        body: markdownText.slice(consumed.length),
+        lineOffset: countLineBreaks(consumed)
+    };
+}
+function countLineBreaks(value) {
+    const matches = value.match(/\r?\n/g);
+    return matches ? matches.length : 0;
+}
+function extractParagraphs(markdownText) {
+    const lines = markdownText.split(/\r?\n/);
+    const paragraphs = [];
+    let currentStart = -1;
+    const currentLines = [];
+    const flush = (endIndex) => {
+        if (currentStart < 0 || currentLines.length === 0) {
+            return;
+        }
+        const joined = currentLines.join(" ").replace(/\s+/g, " ").trim();
+        if (joined.length > 0) {
+            paragraphs.push({
+                index: paragraphs.length,
+                startLine: currentStart + 1,
+                endLine: endIndex + 1,
+                text: joined
+            });
+        }
+        currentStart = -1;
+        currentLines.length = 0;
+    };
+    for (let index = 0; index < lines.length; index += 1) {
+        const trimmed = lines[index].trim();
+        if (!trimmed) {
+            flush(index - 1);
+            continue;
+        }
+        if (currentStart < 0) {
+            currentStart = index;
+        }
+        currentLines.push(trimmed);
+    }
+    flush(lines.length - 1);
+    return paragraphs;
+}
+function findParagraphForLine(paragraphs, lineNumber) {
+    return paragraphs.find((paragraph) => lineNumber >= paragraph.startLine && lineNumber <= paragraph.endLine);
+}
+function findPreviousParagraphForLine(paragraphs, lineNumber) {
+    for (let index = paragraphs.length - 1; index >= 0; index -= 1) {
+        if (paragraphs[index].endLine < lineNumber) {
+            return paragraphs[index];
+        }
+    }
+    return undefined;
+}
+function formatHumanTimestamp(raw) {
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(raw)) {
+        return raw;
+    }
+    const date = new Date(raw);
+    if (Number.isNaN(date.getTime())) {
+        return raw;
+    }
+    const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+    const month = months[date.getUTCMonth()];
+    const day = date.getUTCDate();
+    const year = date.getUTCFullYear();
+    const hours24 = date.getUTCHours();
+    const hours = hours24 % 12 || 12;
+    const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+    const ampm = hours24 < 12 ? "AM" : "PM";
+    return `${month} ${day}, ${year}, ${hours}:${minutes} ${ampm}`;
+}
+function escapeThreadHeaderPart(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/_/g, "\\_");
+}
 function trimTrailingBlankLines(lines) {
     const copy = [...lines];
     while (copy.length > 0 && copy[copy.length - 1].trim().length === 0) {

package/dist/stego-cli.js

@@ -1425,19 +1425,18 @@ function parseStegoCommentThreads(lines, relativePath, baseLine, issues) {
             index += 1;
             continue;
         }
-        const headingMatch = trimmed.match(/^###\s+(CMT-\d{4})\s*$/);
-        if (!headingMatch) {
-            issues.push(makeIssue("error", "comments", "Invalid comments appendix line. Expected heading like '### CMT-0001'.", relativePath, baseLine + index));
+        const id = parseCommentThreadDelimiter(trimmed);
+        if (!id) {
+            issues.push(makeIssue("error", "comments", "Invalid comments appendix line. Expected comment delimiter '<!-- comment: CMT-0001 -->'.", relativePath, baseLine + index));
             index += 1;
             continue;
         }
-        const id = headingMatch[1];
         index += 1;
         const rowLines = [];
         const rowLineNumbers = [];
         while (index < lines.length) {
             const nextTrimmed = lines[index].trim();
-            if (/^###\s+CMT-\d{4}\s*$/.test(nextTrimmed)) {
+            if (parseCommentThreadDelimiter(nextTrimmed)) {
                 break;
             }
             rowLines.push(lines[index]);
@@ -1477,13 +1476,13 @@ function parseStegoCommentThreads(lines, relativePath, baseLine, issues) {
             }
             const headerQuote = extractQuotedLine(rawRow);
             if (headerQuote === undefined) {
-                issues.push(makeIssue("error", "comments", `Invalid thread header '${trimmedRow}'. Expected blockquote header like '> _timestamp | author_'.`, relativePath, lineNumber));
+                issues.push(makeIssue("error", "comments", `Invalid thread header '${trimmedRow}'. Expected blockquote header like '> _timestamp — author_'.`, relativePath, lineNumber));
                 rowIndex += 1;
                 continue;
             }
             const header = parseThreadHeader(headerQuote);
             if (!header) {
-                issues.push(makeIssue("error", "comments", `Invalid thread header '${headerQuote.trim()}'. Expected '> _timestamp | author_'.`, relativePath, lineNumber));
+                issues.push(makeIssue("error", "comments", `Invalid thread header '${headerQuote.trim()}'. Expected '> _timestamp — author_'.`, relativePath, lineNumber));
                 rowIndex += 1;
                 continue;
             }
@@ -1549,6 +1548,17 @@ function parseStegoCommentThreads(lines, relativePath, baseLine, issues) {
     }
     return comments;
 }
+function parseCommentThreadDelimiter(line) {
+    const markerMatch = line.match(/^<!--\s*comment:\s*(CMT-\d{4,})\s*-->\s*$/i);
+    if (markerMatch?.[1]) {
+        return markerMatch[1].toUpperCase();
+    }
+    const legacyHeadingMatch = line.match(/^###\s+(CMT-\d{4,})\s*$/i);
+    if (legacyHeadingMatch?.[1]) {
+        return legacyHeadingMatch[1].toUpperCase();
+    }
+    return undefined;
+}
 function decodeCommentMeta64(encoded, commentId, relativePath, lineNumber, issues) {
     let rawJson = "";
     try {
@@ -1570,7 +1580,20 @@ function decodeCommentMeta64(encoded, commentId, relativePath, lineNumber, issue
         issues.push(makeIssue("error", "comments", `Invalid meta64 object for comment ${commentId}.`, relativePath, lineNumber));
         return undefined;
     }
-    const allowedKeys = new Set(["status", "anchor", "paragraph_index", "signature", "excerpt"]);
+    const allowedKeys = new Set([
+        "status",
+        "created_at",
+        "timezone",
+        "timezone_offset_minutes",
+        "paragraph_index",
+        "excerpt_start_line",
+        "excerpt_start_col",
+        "excerpt_end_line",
+        "excerpt_end_col",
+        "anchor",
+        "excerpt",
+        "signature"
+    ]);
     for (const key of Object.keys(parsed)) {
         if (!allowedKeys.has(key)) {
             issues.push(makeIssue("error", "comments", `meta64 for comment ${commentId} contains unsupported key '${key}'.`, relativePath, lineNumber));
@@ -1592,7 +1615,7 @@ function extractQuotedLine(raw) {
     return quoteMatch[1];
 }
 function parseThreadHeader(value) {
-    const match = value.trim().match(/^_(.+?)\s*\|\s*(.+?)_\s*$/);
+    const match = value.trim().match(/^_(.+?)\s*(?:—|\|)\s*(.+?)_\s*$/);
     if (!match) {
         return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stego-cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "license": "Apache-2.0",