project-logbook 0.3.4 → 0.4.0

package/dist/utils/log-timeline.js

@@ -0,0 +1,218 @@
+/**
+ * Helpers for transforming technical log markdown into a timeline view.
+ */
+/**
+ * Regex pattern to match log entries with ISO timestamps.
+ * Matches: "2026-05-27T14:17:02.250Z: Some message"
+ * Also matches bullet points: "- 2026-05-27T14:17:02.250Z: Some message"
+ */
+const LOG_ENTRY_REGEX = /^-?\s*(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?)\s*:\s*(.+)$/;
+/**
+ * Parse technical log markdown into structured log entries.
+ * @param logMarkdown - The raw markdown content of the technical log
+ * @returns Array of parsed log entries, or null if parsing fails
+ */
+export function parseLogMarkdown(logMarkdown) {
+    if (!logMarkdown || typeof logMarkdown !== 'string') {
+        return null;
+    }
+    const lines = logMarkdown.split('\n');
+    const entries = [];
+    for (const line of lines) {
+        const match = line.match(LOG_ENTRY_REGEX);
+        if (match) {
+            const [, timestampStr, message] = match;
+            const timestamp = new Date(timestampStr);
+            if (isNaN(timestamp.getTime())) {
+                continue; // Skip invalid dates
+            }
+            entries.push({
+                timestamp,
+                isoTimestamp: timestampStr,
+                message: message.trim(),
+            });
+        }
+    }
+    // Sort entries chronologically
+    entries.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    return entries.length > 0 ? entries : null;
+}
+/**
+ * Transform log entries into a timeline with gap indicators.
+ * Shows ALL entries, but only displays timestamps for:
+ * - First entry
+ * - Entries after gaps >= threshold
+ * - Last entry
+ *
+ * This prevents timestamp clutter when LLM writes many entries in quick succession.
+ *
+ * @param entries - Parsed log entries (sorted chronologically)
+ * @param gapThresholdHours - Minimum gap in hours to show timestamp (default: 1)
+ * @returns Timeline items for rendering
+ */
+export function createTimelineFromEntries(entries, gapThresholdHours = 1) {
+    if (entries.length === 0) {
+        return [];
+    }
+    const timeline = [];
+    const gapThresholdMs = gapThresholdHours * 60 * 60 * 1000;
+    // Always show first entry with timestamp
+    timeline.push({
+        type: 'entry',
+        timestamp: entries[0].timestamp,
+        isoTimestamp: entries[0].isoTimestamp,
+        message: entries[0].message,
+        showTime: true,
+    });
+    // Process middle entries
+    for (let i = 1; i < entries.length - 1; i++) {
+        const prev = entries[i - 1];
+        const curr = entries[i];
+        const gapMs = curr.timestamp.getTime() - prev.timestamp.getTime();
+        const gapHours = (gapMs / gapThresholdMs) * gapThresholdHours;
+        if (gapHours >= gapThresholdHours) {
+            // Add gap indicator
+            timeline.push({
+                type: 'gap',
+                gapHours,
+            });
+            // Show this entry with timestamp after the gap
+            timeline.push({
+                type: 'entry',
+                timestamp: curr.timestamp,
+                isoTimestamp: curr.isoTimestamp,
+                message: curr.message,
+                showTime: true,
+            });
+        }
+        else {
+            // Show entry without timestamp (close to previous)
+            timeline.push({
+                type: 'entry',
+                message: curr.message,
+                showTime: false,
+            });
+        }
+    }
+    // Always show last entry
+    if (entries.length > 1) {
+        const last = entries[entries.length - 1];
+        const prev = entries[entries.length - 2];
+        const gapMs = last.timestamp.getTime() - prev.timestamp.getTime();
+        const gapHours = (gapMs / gapThresholdMs) * gapThresholdHours;
+        if (gapHours >= gapThresholdHours) {
+            // Add gap indicator before last entry
+            timeline.push({
+                type: 'gap',
+                gapHours,
+            });
+        }
+        // Last entry always shown with timestamp
+        timeline.push({
+            type: 'entry',
+            timestamp: last.timestamp,
+            isoTimestamp: last.isoTimestamp,
+            message: last.message,
+            showTime: true,
+        });
+    }
+    return timeline;
+}
+/**
+ * Format timestamp for display in timeline.
+ * Shows time in HH:MM format.
+ */
+function formatTime(timestamp) {
+    const hours = String(timestamp.getHours()).padStart(2, '0');
+    const minutes = String(timestamp.getMinutes()).padStart(2, '0');
+    return `${hours}:${minutes}`;
+}
+/**
+ * Escape HTML special characters.
+ */
+function escapeHtml(text) {
+    const htmlEscapes = {
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+    };
+    return text.replace(/[&<>"']/g, (char) => htmlEscapes[char]);
+}
+/**
+ * Render timeline items as HTML.
+ * Creates a beautiful timeline that shows:
+ * - ALL log entries as messages
+ * - Timestamps only for significant moments (start, after gaps, end)
+ * - Gap indicators for breaks > threshold
+ *
+ * @param timeline - Timeline items to render
+ * @returns HTML string for the timeline
+ */
+export function renderTimelineHtml(timeline) {
+    if (timeline.length === 0) {
+        return '<p>No log entries available.</p>';
+    }
+    const itemsHtml = timeline
+        .map((item) => {
+        if (item.type === 'gap') {
+            const gapHours = item.gapHours?.toFixed(1) ?? '??';
+            return `
+          <li class="timeline-gap">
+            <span class="gap-indicator">
+              ⏸ ${gapHours}h break
+            </span>
+          </li>`;
+        }
+        if (item.type === 'entry' && item.message) {
+            const escapedMessage = escapeHtml(item.message);
+            if (item.showTime && item.timestamp && item.isoTimestamp) {
+                const time = formatTime(item.timestamp);
+                return `
+          <li class="timeline-entry has-time">
+            <time class="timeline-time" datetime="${escapeHtml(item.isoTimestamp)}">${time}</time>
+            <span class="timeline-message">${escapedMessage}</span>
+          </li>`;
+            }
+            else {
+                // Entry without timestamp - just the message
+                return `
+          <li class="timeline-entry no-time">
+            <span class="timeline-message">${escapedMessage}</span>
+          </li>`;
+            }
+        }
+        return '';
+    })
+        .join('');
+    return `<ul class="timeline">${itemsHtml}</ul>`;
+}
+/**
+ * Get the last log entry from technical log markdown.
+ * Useful for displaying a "last logged" nudge in CLI output.
+ *
+ * @param logMarkdown - The raw markdown content of the technical log
+ * @returns The last LogEntry, or null if none found
+ */
+export function getLastLogEntry(logMarkdown) {
+    const entries = parseLogMarkdown(logMarkdown);
+    return entries ? entries[entries.length - 1] : null;
+}
+/**
+ * Main function to transform technical log markdown into timeline HTML.
+ * Falls back to plain markdown rendering if preprocessing fails.
+ *
+ * @param logMarkdown - The raw markdown content of the technical log
+ * @returns HTML string (timeline if successful, plain markdown otherwise)
+ */
+export async function transformLogToTimeline(logMarkdown) {
+    const entries = parseLogMarkdown(logMarkdown);
+    if (!entries || entries.length === 0) {
+        // Fall back to plain markdown rendering
+        const fallbackContent = logMarkdown && logMarkdown.trim() ? escapeHtml(logMarkdown).replace(/\n/g, '<br>') : 'No log entries available.';
+        return '<div class="log-fallback">' + fallbackContent + '</div>';
+    }
+    const timeline = createTimelineFromEntries(entries);
+    return renderTimelineHtml(timeline);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-logbook",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "A command-line tool for project logbooks.",
   "workspaces": [
     "demo-app"
@@ -42,6 +42,7 @@
     "@types/fs-extra": "^11.0.4",
     "@types/hast": "^3.0.4",
     "@types/node": "^25.7.0",
+    "@types/rss": "^0.0.32",
     "@typescript-eslint/eslint-plugin": "^8.32.1",
     "@typescript-eslint/parser": "^8.32.1",
     "@vitest/coverage-v8": "^3.1.4",
@@ -65,6 +66,7 @@
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
+    "rss": "^1.2.2",
     "simple-git": "^3.36.0",
     "unified": "^11.0.5"
   }

package/src/templates/index.md

@@ -21,6 +21,10 @@ dateEnd: "[DATE_END]"
 ## Summary
 TODO: Write a polished, highly readable ticket summary that reads like an engaging technical narrative (similar to a well-written dev blog post).
 
+### Before You Start:
+- **Check `log.md`**: Review your technical log for all the decisions, errors, and pivots you recorded during implementation.
+- **Reference the log**: Use your real-time log entries as source material for the narrative — don't try to reconstruct from memory.
+
 ### Formatting & Style Rules:
 - **Maintain the narrative tone:** TODO: Keep the storytelling flair (e.g., describing how problems accumulated or how gaps surfaced), but stay strictly factual based on the provided changes.
 - **Add thematic headings:** TODO: Break the narrative down into logical chapters using Markdown headings (e.g., ### The Friction Points, ### The Fix, ### Closing the Gap).

package/src/templates/log.md

@@ -1,4 +1,9 @@
 # Technical Log: {{id}}-{{slug}}
 
+> **REMINDER**: Log your work in real-time using `logbook log "<message>"`. Don't wait until the end!
+> 
+> Log after every significant step: investigation, errors, decisions, code changes, test runs, etc.
+>
+
 ## Protocol
 - {{fullIso}}: Started investigation.

package/src/templates/steer.txt

@@ -8,11 +8,27 @@ Phase 1: Understand
 2. Review `AGENTS.md` and `CONTRIBUTING.md` if you need architectural or workflow context.
 
 Phase 2: Execute & Trace
-1. Use `log.md` as a live technical scratchpad.
-2. Log your work in real-time using the `logbook log "<message>"` command. Record every major decision, error, and pivot. Do not reconstruct this at the end.
-   Example: logbook log "Investigated root cause — found issue in src/lib/config.ts"
-   One message per call. For multiple entries, call the command once per message.
-3. Stick to the active entry; never modify past entries in the logbook folder.
+
+**CRITICAL: Real-Time Logging**
+You MUST log your work continuously using `logbook log "<message>"`. This is not optional.
+
+1. Use `log.md` as your live technical scratchpad.
+2. After EVERY significant step, run: `logbook log "<what you just did>"`
+   - Investigated a file? Log it.
+   - Found an error? Log it.
+   - Made a design decision? Log it.
+   - Fixed a bug? Log it.
+   - Ran tests? Log the result.
+   
+   Examples:
+   - `logbook log "Investigated src/lib/config.ts - found missing validation"`
+   - `logbook log "Created new RSS module with generateRssFeed() function"`
+   - `logbook log "Test failed: TypeScript error on line 42 - fixed type assertion"`
+   - `logbook log "All 127 tests pass, pre-commit suite successful"`
+
+3. **One message per command call.** For multiple entries, call the command multiple times.
+4. Do NOT reconstruct the log at the end. If the log is empty when you finish, you did it wrong.
+5. Stick to the active entry; never modify past entries in the logbook folder.
 
 Phase 3: Synthesize
 1. When implementation is finished, write the narrative in `index.md`.

package/src/templates/styles.css

@@ -696,3 +696,119 @@ article img[src$='.webp'],
 article img[src$='.svg'] {
   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
 }
+
+/* Technical Log Timeline */
+#log .timeline {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  position: relative;
+}
+
+#log .timeline::before {
+  content: '';
+  position: absolute;
+  left: 8px;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: var(--border);
+}
+
+#log .timeline-entry {
+  position: relative;
+  padding-left: 2rem;
+  margin-bottom: 0.75rem;
+  min-height: 1.5rem;
+  display: grid;
+  grid-template-columns: 55px 1fr;
+  gap: 0.5rem;
+}
+
+#log .timeline-entry.no-time .timeline-message {
+  grid-column: 2;
+}
+
+#log .timeline-entry.has-time::before {
+  content: '';
+  position: absolute;
+  left: 5px;
+  top: 4px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--primary);
+  border: 2px solid var(--bg);
+  z-index: 1;
+}
+
+#log .timeline-entry.no-time::before {
+  content: '';
+  position: absolute;
+  left: 7px;
+  top: 0.6rem;
+  width: 4px;
+  height: 4px;
+  border-radius: 50%;
+  background: var(--text-muted);
+  opacity: 0.6;
+}
+
+#log .timeline-time {
+  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, monospace;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--primary);
+  display: inline-block;
+}
+
+#log .timeline-message {
+  font-size: 0.9375rem;
+  color: var(--text);
+  line-height: 1.5;
+}
+
+#log .timeline-entry.no-time .timeline-message {
+  color: var(--text);
+  opacity: 0.85;
+}
+
+#log .timeline-gap {
+  position: relative;
+  padding-left: 2rem;
+  margin: 1.5rem 0;
+  min-height: 1rem;
+}
+
+#log .timeline-gap::before {
+  content: '';
+  position: absolute;
+  left: 7px;
+  top: 0.4rem;
+  width: 4px;
+  height: 4px;
+  border-radius: 50%;
+  background: var(--text-muted);
+  opacity: 0.5;
+}
+
+#log .gap-indicator {
+  font-size: 0.8125rem;
+  color: var(--text-muted);
+  font-style: italic;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+#log .log-fallback {
+  font-size: 0.9375rem;
+  color: var(--text);
+  line-height: 1.6;
+  white-space: pre-wrap;
+  background: var(--primary-soft);
+  padding: 1rem;
+  border-radius: 0.5rem;
+  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, monospace;
+  font-size: 0.8125rem;
+}