project-logbook 0.3.0

package/dist/linters/workspaces.js

@@ -0,0 +1,26 @@
+import { getWorkspaces } from '../lib/config.js';
+const linter = {
+    name: 'workspaces',
+    description: 'Validates workspaces field against package.json',
+    async check(context) {
+        if (!context.entryName || !context.frontmatter)
+            return [];
+        const { frontmatter } = context;
+        if (frontmatter.workspaces === undefined)
+            return [];
+        const issues = [];
+        const availableWorkspaces = getWorkspaces();
+        const entryWorkspaces = Array.isArray(frontmatter.workspaces) ? frontmatter.workspaces : [];
+        for (const ws of entryWorkspaces) {
+            if (!availableWorkspaces.includes(ws)) {
+                issues.push({
+                    level: 'error',
+                    category: 'workspace',
+                    message: `Invalid workspace '${ws}'. Available workspaces: ${availableWorkspaces.join(', ')}`,
+                });
+            }
+        }
+        return issues;
+    },
+};
+export default linter;

package/dist/templates/ABOUT.md

@@ -0,0 +1,23 @@
+# About this Logbook
+
+This is a **Project Logbook** — a living documentation approach that tracks project evolution through ticket-based entries.
+
+## The Problem
+
+Traditional project documentation often becomes stale quickly. Decisions get lost, the rationale behind changes remains undocumented, and onboarding new team members becomes challenging.
+
+## The Solution
+
+The Project Logbook captures every significant change as a structured entry containing:
+
+- **Ticket**: Requirements and acceptance criteria
+- **Technical Log**: Real-time implementation notes and decisions
+- **Narrative**: A polished story explaining the why and how
+
+## How It Works
+
+Each entry in this logbook represents a discrete piece of work, documented using the same tool that generated this website. The timeline presents these entries as "news items", creating a narrative history of the project.
+
+## Dogfooding
+
+This website itself is built using the logbook tool it documents. Every feature added to this CLI is first documented as a logbook entry, demonstrating the tool's capabilities in real-time.

package/dist/templates/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to Project Logbook
+
+This project follows a strict **Agentic Documentation Workflow**. Whether you are a human or an AI agent, please adhere to the following protocol to ensure the history of this project remains professional, readable, and technically traceable.
+
+## The Three-File Standard
+Every change must be documented in a dedicated folder within `logbook/` using three files:
+
+1. **`ticket.md`**: The source of truth. Contains the requirements, background, and acceptance criteria.
+2. **`log.md`**: The chronological scratchpad. A real-time trace of technical decisions, pivots, and obstacles.
+3. **`index.md`**: The narrative. A polished, high-level "story" of the change for stakeholders and future developers.
+
+## Working Protocol
+
+### 1. Inception
+Always start by creating and activating a new entry:
+```bash
+logbook new [ID] [Slug]
+logbook start [ID]
+```
+
+The `new` command accepts optional parameters. When invoked without arguments, it enters interactive mode:
+- If `jiraPrefix` is configured, suggests the next ID with that prefix (e.g., LB-14)
+- Prompts for title, auto-converts to slug
+
+`logbook start` looks up the entry folder by ID prefix, so `logbook start LB-5` resolves to `LB-5-jira-support` automatically.
+
+`logbook start` writes a `.logbook-active` JSON lockfile to ensure only one entry is worked on at a time. It also automatically records the current git user as the `prompter` in the `index.md` frontmatter — useful for tracking which human directed or reviewed an AI-assisted session.
+
+Fill the `ticket.md` immediately so the context is anchored before you start coding. Optionally run:
+```bash
+logbook steer
+```
+to receive strategic guidance for the active entry based on the ticket content.
+
+### 2. Execution
+As you code, keep the `log.md` updated in real-time using the `logbook log` command. Do not wait until the end.
+
+```bash
+logbook log "Investigated root cause — found issue in src/lib/config.ts"
+logbook log "Fixed the bug" "Added tests" "All passing"
+```
+
+Each message is automatically prefixed with an ISO timestamp and appended as a bullet to the active `log.md`. You may pass multiple quoted strings in one call. If you encounter a bug or change your design, log it immediately. This is the most valuable file for future debugging.
+
+Only update the currently active logbook entry. Do not edit other existing entries while working.
+
+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:
+```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.
+
+The linter enforces rules to be followed.
+
+### 4. Final Review
+Use the preview command to see how your entry looks in the context of the whole project:
+```bash
+logbook preview
+```
+
+## The `prompter` Field
+
+The optional `prompter` frontmatter field in `index.md` records the human who directed, reviewed, or collaborated on a session — distinct from the AI `author`. It is set automatically by `logbook start` from the git `user.name` and injected into `index.md`. In fully automated pipelines without a human prompter, it may be omitted.
+
+## Jira Integration
+
+If the project has a `jiraBaseUrl` set in `.project-logbook`, the `ticket` field in `index.md` frontmatter is used to generate a direct link to the Jira issue in the built website. Ensure `ticket` is set correctly (e.g. `LB-5`) for every entry.
+
+If `jiraPrefix` is configured, entry folder names and ticket references must match the prefix pattern.
+
+## Tone & Style
+- **Narrative over Lists**: In `index.md`, tell a story. Why did we make this change? What were the challenges?
+- **Technical Precision**: In `log.md`, be specific. Mention file paths, error messages, and specific design patterns. Log in real time — do not reconstruct after the fact.
+- **No Boilerplate in Commits**: All template placeholders must be replaced or removed before `logbook release`.

package/dist/templates/favicon.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <style>
+    .logo-path {
+      fill: white;
+      stroke: black;
+      stroke-width: 3;
+      stroke-linejoin: round;
+      stroke-linecap: round;
+    }
+  </style>
+
+  <!-- Letter 'L' -->
+  <path class="logo-path" d="M 5 20 v 60 h 22 v -10 h -12 v -50 z" />
+
+  <!-- Letter 'O' -->
+  <path class="logo-path" fill-rule="evenodd" d="M 33 20 v 60 h 28 v -60 z M 43 30 v 40 h 8 v -40 z" />
+
+  <!-- Letter 'G' -->
+  <path class="logo-path"
+    d="M 67 20 v 60 h 28 v -30 h -12 v 10 h 2 v 10 h -8 v -40 h 8 v 5 h 10 v -15 z" />
+</svg>

package/dist/templates/index.md

@@ -0,0 +1,30 @@
+---
+# The ticket field should match the ID portion (e.g., LB-34)
+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]
+# 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]
+# Set automatically by `logbook release`
+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).
+
+### 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).
+- **Use bullet points:** TODO: Whenever listing multiple items (like friction points, test scenarios, or rewritten paths), use a bulleted list instead of a dense paragraph to make it scannable.
+- **Use bold emphasis:** TODO: Bold key concepts, problems, and solutions to guide the reader's eye.
+- **Format code:** TODO: Use inline backticks for files, plugins, HTML elements, and code snippets (e.g., `src/lib/build-helpers.ts`).
+- **Keep paragraphs short:** TODO: Ensure no paragraph is longer than 3-4 sentences. Keep the pacing quick and engaging.

package/dist/templates/log.md

@@ -0,0 +1,4 @@
+# Technical Log: {{id}}-{{slug}}
+
+## Protocol
+- {{fullIso}}: Started investigation.

package/dist/templates/logbook-client.js

@@ -0,0 +1,162 @@
+(function () {
+  'use strict';
+
+  /* ── 1. Real-time relative dates ──────────────────────────────────────── */
+  function relativeDate(isoString) {
+    var d = new Date(isoString);
+    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;
+  }
+
+  function updateRelativeDates() {
+    var els = document.querySelectorAll('[data-date]');
+    for (var i = 0; i < els.length; i++) {
+      var el = els[i];
+      var iso = el.getAttribute('data-date');
+      if (iso) el.textContent = relativeDate(iso);
+    }
+  }
+
+  /* ── 2. localStorage-based "NEW" indicator ─────────────────────────────── */
+  var STORAGE_KEY = 'logbook_visited';
+
+  function getVisited() {
+    try {
+      return JSON.parse(localStorage.getItem(STORAGE_KEY) || '[]');
+    } catch (e) {
+      return [];
+    }
+  }
+
+  function markVisited(slug) {
+    try {
+      var visited = getVisited();
+      if (visited.indexOf(slug) === -1) {
+        visited.push(slug);
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(visited));
+      }
+    } catch (e) {
+      /* localStorage unavailable */
+    }
+  }
+
+  function applyNewBadges() {
+    var visited = getVisited();
+    var items = document.querySelectorAll('[data-entry-slug]');
+    for (var i = 0; i < items.length; i++) {
+      var item = items[i];
+      var slug = item.getAttribute('data-entry-slug');
+      if (slug && visited.indexOf(slug) === -1) {
+        var badge = item.querySelector('.new-badge');
+        if (badge) badge.style.display = 'inline-block';
+      }
+    }
+  }
+
+  /* ── 3. Tab switching functionality ────────────────────────────────────── */
+  function showTab(event, id) {
+    var eventTarget = event.currentTarget;
+    if (!eventTarget) return;
+
+    // Find the tabs-wrapper container that scopes this tab group
+    var wrapper = eventTarget.closest('.tabs-wrapper');
+    if (!wrapper) return;
+
+    // Hide all content sections within this wrapper only
+    var contentSections = wrapper.querySelectorAll('.content-section');
+    for (var i = 0; i < contentSections.length; i++) {
+      contentSections[i].style.display = 'none';
+    }
+
+    // Deactivate all tabs within this wrapper only
+    var tabs = wrapper.querySelectorAll('.tab');
+    for (var i = 0; i < tabs.length; i++) {
+      tabs[i].classList.remove('active');
+      tabs[i].setAttribute('aria-selected', 'false');
+      tabs[i].setAttribute('tabindex', '-1');
+    }
+
+    // Activate selected tab and content
+    var targetContent = document.getElementById(id);
+    if (targetContent) {
+      targetContent.style.display = 'block';
+    }
+
+    // Find and activate the clicked tab
+    var clickedTab = null;
+    for (var i = 0; i < tabs.length; i++) {
+      if (tabs[i].getAttribute('aria-controls') === id) {
+        clickedTab = tabs[i];
+        break;
+      }
+    }
+    if (clickedTab) {
+      clickedTab.classList.add('active');
+      clickedTab.setAttribute('aria-selected', 'true');
+      clickedTab.setAttribute('tabindex', '0');
+      clickedTab.focus();
+    }
+  }
+
+  function initTabs() {
+    var tabLists = document.querySelectorAll('[role="tablist"]');
+    for (var i = 0; i < tabLists.length; i++) {
+      var tabList = tabLists[i];
+
+      // Add keyboard navigation
+      tabList.addEventListener('keydown', function (event) {
+        var tabs = Array.from(this.querySelectorAll('.tab'));
+        var current = tabs.findIndex(function (t) {
+          return t.getAttribute('aria-selected') === 'true';
+        });
+        var next = -1;
+
+        if (event.key === 'ArrowRight') {
+          next = (current + 1) % tabs.length;
+        } else if (event.key === 'ArrowLeft') {
+          next = (current - 1 + tabs.length) % tabs.length;
+        }
+
+        if (next !== -1) {
+          event.preventDefault();
+          tabs[next].click();
+        }
+      });
+    }
+  }
+
+  /* ── Bootstrap ─────────────────────────────────────────────────────────── */
+  document.addEventListener('DOMContentLoaded', function () {
+    updateRelativeDates();
+
+    // On post pages: mark this entry as visited
+    var pageSlug = document.body.getAttribute('data-page-slug');
+    if (pageSlug) markVisited(pageSlug);
+
+    // On the timeline: apply NEW badges
+    applyNewBadges();
+
+    // Initialize tab functionality
+    initTabs();
+  });
+
+  // Expose showTab globally for onclick handlers
+  window.showTab = showTab;
+})();

package/dist/templates/steer.txt

@@ -0,0 +1,25 @@
+PROJECT LOGBOOK: AI AGENT STEERING PROTOCOL
+
+The human prompter has already initialized and activated the current logbook entry.
+Do NOT run `logbook new` or `logbook release` — these are prompter responsibilities.
+
+Phase 1: Understand
+1. Read `ticket.md` in the active entry. This is your source of truth for requirements.
+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"
+3. You may pass multiple messages in one call: logbook log "Msg A" "Msg B"
+4. 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`.
+2. Storytelling Mode: Explain the "Why" and the "Journey." Avoid simple technical bullet points.
+3. Clean up all template placeholders and complete the frontmatter (author, summary, dates).
+
+Phase 4: Verify
+1. Run `npm run pre` (which includes `logbook lint` and other quality gates).
+2. Ensure there are no linter errors, unreplaced placeholders, or architectural violations before concluding your work. 
+3. Hand back to the prompter, who will review and run `logbook release`.