project-logbook 0.3.3 → 0.3.4

package/dist/utils/date.js

@@ -1,7 +1,42 @@
-/** Format a date value as a relative time string (e.g., "today, May 16, 2026"). */
-export function formatRelativeDate(date) {
+/**
+ * Parse and validate a date input (string or Date).
+ * Returns the Date object if valid, null if invalid.
+ */
+function parseDate(date) {
     const d = new Date(date);
-    if (isNaN(d.getTime())) {
+    return isNaN(d.getTime()) ? null : d;
+}
+/**
+ * Format a date as absolute date and time (server-side).
+ * This is the primary format used in HTML data-date attributes.
+ * The client-side JavaScript will add the relative component (today, 2 days ago, etc).
+ * Format: "26 May 2026, 10:51"
+ * @param date - The date to format
+ * @returns Formatted date string with absolute date and time only
+ */
+export function formatAbsoluteDate(date) {
+    const d = parseDate(date);
+    if (!d)
+        return 'unknown';
+    const day = d.getDate();
+    const month = d.toLocaleString('en-US', { month: 'short' });
+    const year = d.getFullYear();
+    const hours = String(d.getHours()).padStart(2, '0');
+    const minutes = String(d.getMinutes()).padStart(2, '0');
+    return `${day} ${month} ${year}, ${hours}:${minutes}`;
+}
+/**
+ * Format a date as a consistent, human-readable format.
+ * Combines relative time (today, yesterday, 2 days ago) with absolute date and time.
+ * Format: "today, 26 May 2026, 10:51"
+ * This is for server-side rendering when client-side JS is not available.
+ * Normally, the client-side JS will update formatAbsoluteDate() output with this format.
+ * @param date - The date to format
+ * @returns Formatted date string with relative and absolute components
+ */
+export function formatRelativeDate(date) {
+    const d = parseDate(date);
+    if (!d) {
         return 'unknown date';
     }
     const now = new Date();
@@ -9,16 +44,15 @@ export function formatRelativeDate(date) {
     const diffDays = Math.floor(diffTime / (1000 * 60 * 60 * 24));
     const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
     const relative = diffDays === 0 ? 'today' : rtf.format(-diffDays, 'day');
-    const absolute = d.toLocaleDateString('en-US', {
-        year: 'numeric',
-        month: 'long',
-        day: 'numeric',
-    });
+    // Format as "26 May 2026, 10:51"
+    const absolute = formatAbsoluteDate(d);
     return `${relative}, ${absolute}`;
 }
 /** Format a date value as YYYY-MM-DD. */
 export function formatIsoDate(value) {
-    const d = new Date(value);
+    const d = parseDate(value);
+    if (!d)
+        return 'invalid-date';
     const yyyy = d.getFullYear();
     const mm = String(d.getMonth() + 1).padStart(2, '0');
     const dd = String(d.getDate()).padStart(2, '0');
@@ -26,8 +60,8 @@ export function formatIsoDate(value) {
 }
 /** Get "Month Year" string for a date (e.g., "May 2026"). */
 export function getMonthYear(date) {
-    const d = new Date(date);
-    if (isNaN(d.getTime()))
+    const d = parseDate(date);
+    if (!d)
         return 'Unknown Date';
     return d.toLocaleDateString('en-US', {
         year: 'numeric',
@@ -36,12 +70,19 @@ export function getMonthYear(date) {
 }
 /** Get a short "HH:mmh" string for sorting/display based on dateEnd or dateStart. */
 export function getSortTime(dateStart, dateEnd) {
-    const dStart = new Date(dateStart);
-    const dEnd = dateEnd ? new Date(dateEnd) : null;
-    const date = dEnd && !isNaN(dEnd.getTime()) ? dEnd : dStart;
-    if (isNaN(date.getTime()))
+    const dStart = parseDate(dateStart);
+    const dEnd = dateEnd ? parseDate(dateEnd) : null;
+    const date = dEnd ? dEnd : dStart;
+    if (!date)
         return '--:--h';
     const hours = date.getHours().toString().padStart(2, '0');
     const minutes = date.getMinutes().toString().padStart(2, '0');
     return `${hours}:${minutes}h`;
 }
+/**
+ * Format a timestamp for metadata/footer display (build time).
+ * Alias for formatAbsoluteDate for clarity in build context.
+ */
+export function formatDateTimeForDisplay(date) {
+    return formatAbsoluteDate(date);
+}

package/dist/utils/frontmatter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Normalizes a frontmatter field that may be a scalar string or a YAML list of strings.
+ * Used when displaying frontmatter fields like 'harness', 'llm', 'prompter' in the timeline.
+ *
+ * @param v - A frontmatter value (string, array of strings, or other type)
+ * @returns A display string joining multiple values with ' + ', or undefined if empty
+ */
+export declare function toDisplayString(v: unknown): string | undefined;
+/**
+ * Type guard: safely get a string field with optional fallback value.
+ * Used to defensively extract string fields from untyped YAML data.
+ *
+ * @param value - The value to check (may be unknown, string, or other type)
+ * @param fallback - Value to use if the input is not a string. If provided, return type is always string. If omitted, return type is string | undefined.
+ * @returns The value if it's a non-empty string, otherwise the fallback (or undefined if no fallback provided)
+ */
+export declare function asString(value: unknown): string | undefined;
+export declare function asString(value: unknown, fallback: string): string;
+/**
+ * Type guard: safely extract array of strings from a field that may be a string, array, or other type.
+ * Normalizes scalar strings to single-element arrays and filters out non-string array elements.
+ *
+ * @param value - The value to normalize (string, array, or other type)
+ * @returns Array of strings, or empty array if input is not convertible
+ */
+export declare function asStringArray(value: unknown): string[];

package/dist/utils/frontmatter.js

@@ -0,0 +1,37 @@
+/**
+ * Normalizes a frontmatter field that may be a scalar string or a YAML list of strings.
+ * Used when displaying frontmatter fields like 'harness', 'llm', 'prompter' in the timeline.
+ *
+ * @param v - A frontmatter value (string, array of strings, or other type)
+ * @returns A display string joining multiple values with ' + ', or undefined if empty
+ */
+export function toDisplayString(v) {
+    if (typeof v === 'string')
+        return v || undefined;
+    if (Array.isArray(v)) {
+        const joined = v.filter((x) => typeof x === 'string').join(' + ');
+        return joined || undefined;
+    }
+    return undefined;
+}
+export function asString(value, fallback) {
+    if (typeof value === 'string' && value)
+        return value;
+    return fallback;
+}
+/**
+ * Type guard: safely extract array of strings from a field that may be a string, array, or other type.
+ * Normalizes scalar strings to single-element arrays and filters out non-string array elements.
+ *
+ * @param value - The value to normalize (string, array, or other type)
+ * @returns Array of strings, or empty array if input is not convertible
+ */
+export function asStringArray(value) {
+    if (typeof value === 'string') {
+        return value ? [value] : [];
+    }
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string');
+    }
+    return [];
+}

package/dist/utils/fs.d.ts

@@ -11,3 +11,16 @@ export interface EntryMeta {
  * Filters for directories and parses index.md if it exists.
  */
 export declare function getLogbookEntries(logbookDir: string): Promise<EntryMeta[]>;
+/**
+ * Safely read a file if it exists, otherwise return an empty string.
+ * @param filePath - Path to the file to read
+ * @returns File contents if the file exists, otherwise empty string
+ */
+export declare function readFileIfExists(filePath: string): Promise<string>;
+/**
+ * Check if a file path exists, returning the path if it does.
+ * Useful for optional file resolution logic.
+ * @param filePath - Path to check
+ * @returns The path if it exists, otherwise null
+ */
+export declare function pathExistsOrNull(filePath: string): Promise<string | null>;

package/dist/utils/fs.js

@@ -36,3 +36,26 @@ export async function getLogbookEntries(logbookDir) {
     }
     return results;
 }
+/**
+ * Safely read a file if it exists, otherwise return an empty string.
+ * @param filePath - Path to the file to read
+ * @returns File contents if the file exists, otherwise empty string
+ */
+export async function readFileIfExists(filePath) {
+    if (await fs.pathExists(filePath)) {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    return '';
+}
+/**
+ * Check if a file path exists, returning the path if it does.
+ * Useful for optional file resolution logic.
+ * @param filePath - Path to check
+ * @returns The path if it exists, otherwise null
+ */
+export async function pathExistsOrNull(filePath) {
+    if (await fs.pathExists(filePath)) {
+        return filePath;
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-logbook",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "A command-line tool for project logbooks.",
   "workspaces": [
     "demo-app"
@@ -29,7 +29,7 @@
     "pre": "npm run format && npm run lint && npm run test && npm run build && npm run knip && npm run madge && npm run dev build && npm run dev lint",
     "next": "node scripts/create-ticket-from-backlog.js",
     "link": "npm run build && npm link",
-    "open": "npm run build && node scripts/open-and-view-dist.js"
+    "open": "npm run dev build && node scripts/open-and-view-dist.js"
   },
   "keywords": [
     "logbook",

package/src/templates/CONTRIBUTING.md

@@ -47,12 +47,21 @@ Only update the currently active logbook entry. Do not edit other existing entri
 When you finish writing `index.md`, **remove the boilerplate link line** that the template inserts:
 
 ### 3. Quality Assurance
-Before submitting your work, you MUST release the active entry and run the linter:
+Before finalizing your work, you should run the linter to verify there are no errors:
 ```bash
-logbook release
 logbook lint
 ```
-`logbook release` removes the `.logbook-active` lockfile. The linter will fail if the lockfile is still present, enforcing that no entry is left dangling in a committed state.
+
+You can also check the overall status of the logbook, configuration settings, and statistics (total tasks, done, and drafts) using:
+```bash
+logbook status
+```
+
+The linter will warn you if the lockfile `.logbook-active` is still present, which is expected during active development.
+
+Once the work is ready:
+- **If you are an AI agent**: Do not release the entry. Hand back to the prompter, who will review and run `logbook release`.
+- **If you are a human developer**: Run `logbook release` to remove the lockfile and finalize the entry.
 
 The linter enforces rules to be followed.
 

package/src/templates/index.md

@@ -3,19 +3,19 @@
 ticket: {{id}}
 # The title should be a human-readable description of the work
 title: {{title}}
-prompter: [PROMPTER]
-harness: [HARNESS]
-llm: [LLM]
-summary: [WRITE_SUMMARY_HERE]
+prompter: "[PROMPTER]"
+harness: "[HARNESS]"
+llm: "[LLM]"
+summary: "[WRITE_SUMMARY_HERE]"
 # Tags for categorizing the change (must be from allowed list in .project-logbook)
 tags: []
 # Workspace(s) this change affects (must match package.json workspaces; leave empty for single-project)
 # Example: workspaces: ["frontend", "shared"]
 workspaces: []
 # Set automatically by `logbook start`
-dateStart: [DATE_START]
+dateStart: "[DATE_START]"
 # Set automatically by `logbook release`
-dateEnd: [DATE_END]
+dateEnd: "[DATE_END]"
 ---
 
 ## Summary

package/src/templates/logbook-client.js

@@ -2,27 +2,40 @@
   'use strict';
 
   /* ── 1. Real-time relative dates ──────────────────────────────────────── */
-  function relativeDate(isoString) {
-    var d = new Date(isoString);
+  /**
+   * Calculate the relative date string (today, yesterday, 2 days ago, etc)
+   * Prepend the relative component to the locally-formatted absolute date.
+   */
+  function getRelativeComponent(d) {
     var now = new Date();
     // Normalise both to midnight local time for day-diff calculation
     var dDay = new Date(d.getFullYear(), d.getMonth(), d.getDate());
     var nDay = new Date(now.getFullYear(), now.getMonth(), now.getDate());
     var diffDays = Math.round((nDay - dDay) / 86400000);
 
-    var relative;
-    if (diffDays === 0) relative = 'today';
-    else if (diffDays === 1) relative = 'yesterday';
-    else if (diffDays < 7) relative = diffDays + ' days ago';
-    else if (diffDays < 14) relative = '1 week ago';
-    else if (diffDays < 30) relative = Math.floor(diffDays / 7) + ' weeks ago';
-    else if (diffDays < 60) relative = '1 month ago';
-    else if (diffDays < 365) relative = Math.floor(diffDays / 30) + ' months ago';
-    else if (diffDays < 730) relative = '1 year ago';
-    else relative = Math.floor(diffDays / 365) + ' years ago';
-
-    var absolute = d.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
-    return relative + ', ' + absolute;
+    if (diffDays === 0) return 'today';
+    else if (diffDays === 1) return 'yesterday';
+    else if (diffDays < 7) return diffDays + ' days ago';
+    else if (diffDays < 14) return '1 week ago';
+    else if (diffDays < 30) return Math.floor(diffDays / 7) + ' weeks ago';
+    else if (diffDays < 60) return '1 month ago';
+    else if (diffDays < 365) return Math.floor(diffDays / 30) + ' months ago';
+    else if (diffDays < 730) return '1 year ago';
+    else return Math.floor(diffDays / 365) + ' years ago';
+  }
+
+  /**
+   * Format a Date object as absolute date and time in browser's local timezone.
+   * Format: "26 May 2026, 10:51"
+   */
+  function formatAbsoluteComponent(d) {
+    var day = d.getDate();
+    var months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    var month = months[d.getMonth()];
+    var year = d.getFullYear();
+    var hours = d.getHours() < 10 ? '0' + d.getHours() : d.getHours();
+    var minutes = d.getMinutes() < 10 ? '0' + d.getMinutes() : d.getMinutes();
+    return day + ' ' + month + ' ' + year + ', ' + hours + ':' + minutes;
   }
 
   function updateRelativeDates() {
@@ -30,7 +43,20 @@
     for (var i = 0; i < els.length; i++) {
       var el = els[i];
       var iso = el.getAttribute('data-date');
-      if (iso) el.textContent = relativeDate(iso);
+      if (iso) {
+        var d = new Date(iso);
+        if (!isNaN(d.getTime())) {
+          // Format the absolute date in the user's browser/local timezone
+          var absolute = formatAbsoluteComponent(d);
+          // Prepend the relative component (e.g., "today")
+          var relative = getRelativeComponent(d);
+          if (relative) {
+            el.textContent = relative + ', ' + absolute;
+          } else {
+            el.textContent = absolute;
+          }
+        }
+      }
     }
   }
 

package/src/templates/styles.css

@@ -33,6 +33,11 @@ header h1 {
 header h1 a {
   text-decoration: none !important;
   color: black !important;
+  transition: color 0.2s;
+}
+
+header h1 a:hover {
+  color: var(--primary) !important;
 }
 
 .tagline {