project-logbook 1.1.0 → 1.3.0

package/dist/watch/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/watch/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0JH,kDAAkD;AAClD,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC/C,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,KAAK;YAAE,OAAO,MAAM,CAAC;IACpE,CAAC;IACD,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/watch/watcher-fs.d.ts

@@ -0,0 +1,39 @@
+/**
+ * File-system watcher setup for logbook watch.
+ *
+ * Handles debounced file-system events that trigger collector re-runs.
+ */
+import { watch as fsWatch } from 'node:fs';
+import type { Collector } from './collectors/types.js';
+import type { WatcherState } from './state.js';
+/** Context needed by the file-watcher to trigger collections and pushes. */
+interface FsWatcherContext {
+    cwd: string;
+    port: number;
+    entriesDir: string;
+    lockfilePath: string;
+    activeCollectors: Collector[];
+    state: WatcherState;
+    /** Callback to push a full status snapshot to the hub. */
+    pushStatus: (_reason: string) => Promise<void>;
+}
+/** Handles returned by setupFileWatchers for cleanup. */
+interface FsWatcherHandles {
+    /** Native fs.watch handles to close on shutdown. */
+    watchers: ReturnType<typeof fsWatch>[];
+    /** Debounce timer reference (may be null). */
+    getDebounceTimer: () => ReturnType<typeof setTimeout> | null;
+    /** Clear the debounce timer on shutdown. */
+    clearDebounce: () => void;
+}
+/**
+ * Set up file watchers for fs-triggered collectors.
+ *
+ * Watches the lockfile and entries directory for changes, debounces events,
+ * then re-runs fs-triggered collectors and pushes status to the hub.
+ *
+ * @param ctx - Watcher context with project paths, collectors, and state.
+ * @returns Handles for cleanup (watchers to close, timer to clear).
+ */
+export declare function setupFileWatchers(ctx: FsWatcherContext): FsWatcherHandles;
+export {};

package/dist/watch/watcher-fs.js

@@ -0,0 +1,105 @@
+/**
+ * File-system watcher setup for logbook watch.
+ *
+ * Handles debounced file-system events that trigger collector re-runs.
+ */
+import { watch as fsWatch, existsSync } from 'node:fs';
+import { postToHub } from './watcher-http.js';
+/** Debounce interval for file watcher events (500ms). */
+const DEBOUNCE_MS = 500;
+/**
+ * Set up file watchers for fs-triggered collectors.
+ *
+ * Watches the lockfile and entries directory for changes, debounces events,
+ * then re-runs fs-triggered collectors and pushes status to the hub.
+ *
+ * @param ctx - Watcher context with project paths, collectors, and state.
+ * @returns Handles for cleanup (watchers to close, timer to clear).
+ */
+export function setupFileWatchers(ctx) {
+    const { cwd, port, entriesDir, lockfilePath, activeCollectors, state, pushStatus } = ctx;
+    const fsWatchers = [];
+    let debounceTimer = null;
+    let lastKnownLog = state.latestLog;
+    const debouncedCollectAndPush = (reason) => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            // Run all fs-triggered collectors.
+            for (const c of activeCollectors.filter((c) => c.schedule.type === 'fs')) {
+                await c.collect(cwd, state);
+            }
+            // If latestLog changed, emit an activity event for the timeline.
+            if (state.latestLog && state.latestLog !== lastKnownLog) {
+                lastKnownLog = state.latestLog;
+                const event = {
+                    projectPath: cwd,
+                    timestamp: state.latestLogTimestamp ?? new Date().toISOString(),
+                    description: state.latestLog,
+                    source: 'logbook log',
+                };
+                try {
+                    await postToHub(port, '/_logbook/event', event);
+                }
+                catch {
+                    // Hub may have died.
+                }
+            }
+            try {
+                await pushStatus(reason);
+            }
+            catch {
+                // Hub may have died.
+            }
+        }, DEBOUNCE_MS);
+    };
+    // Watch the lockfile if it exists.
+    try {
+        if (existsSync(lockfilePath)) {
+            const w = fsWatch(lockfilePath, () => {
+                debouncedCollectAndPush('Lockfile changed — ticket started or released');
+            });
+            fsWatchers.push(w);
+        }
+        const cwdWatcher = fsWatch(cwd, (_, filename) => {
+            if (filename === '.logbook-active') {
+                debouncedCollectAndPush('Lockfile created or removed — ticket state changed');
+            }
+        });
+        fsWatchers.push(cwdWatcher);
+    }
+    catch {
+        // fs.watch not supported — fall back to polling only.
+    }
+    // Watch the entries directory recursively.
+    try {
+        if (existsSync(entriesDir)) {
+            const w = fsWatch(entriesDir, { recursive: true }, (_, filename) => {
+                if (!filename)
+                    return;
+                if (filename.endsWith('log.md')) {
+                    debouncedCollectAndPush(`Log updated: ${filename}`);
+                }
+                else if (filename.endsWith('index.md')) {
+                    debouncedCollectAndPush(`Narrative updated: ${filename}`);
+                }
+                else if (filename.endsWith('ticket.md')) {
+                    debouncedCollectAndPush(`Ticket updated: ${filename}`);
+                }
+            });
+            fsWatchers.push(w);
+        }
+    }
+    catch {
+        // Recursive watch not supported.
+    }
+    return {
+        watchers: fsWatchers,
+        getDebounceTimer: () => debounceTimer,
+        clearDebounce: () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+        },
+    };
+}
+//# sourceMappingURL=watcher-fs.js.map

package/dist/watch/watcher-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-fs.js","sourceRoot":"","sources":["../../src/watch/watcher-fs.ts"],"names":[],"mappings":"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"}

package/dist/watch/watcher-http.d.ts

@@ -0,0 +1,19 @@
+/**
+ * HTTP utilities for the logbook watcher.
+ *
+ * Provides the hub communication helper and terminal logging timestamp.
+ */
+/**
+ * Send a JSON POST request to the hub.
+ *
+ * @param port - Hub port number.
+ * @param path - URL path (e.g., '/_logbook/status').
+ * @param data - JSON-serializable payload.
+ */
+export declare function postToHub(port: number, path: string, data: unknown): Promise<void>;
+/**
+ * Format a short timestamp for terminal logging (HH:MM:SS).
+ *
+ * @returns Formatted time string.
+ */
+export declare function logTime(): string;

package/dist/watch/watcher-http.js

@@ -0,0 +1,47 @@
+/**
+ * HTTP utilities for the logbook watcher.
+ *
+ * Provides the hub communication helper and terminal logging timestamp.
+ */
+import { request } from 'node:http';
+/**
+ * Send a JSON POST request to the hub.
+ *
+ * @param port - Hub port number.
+ * @param path - URL path (e.g., '/_logbook/status').
+ * @param data - JSON-serializable payload.
+ */
+export function postToHub(port, path, data) {
+    const body = JSON.stringify(data);
+    return new Promise((resolve, reject) => {
+        const req = request({
+            hostname: '127.0.0.1',
+            port,
+            path,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body),
+            },
+        }, (res) => {
+            res.resume();
+            res.on('end', resolve);
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+/**
+ * Format a short timestamp for terminal logging (HH:MM:SS).
+ *
+ * @returns Formatted time string.
+ */
+export function logTime() {
+    const now = new Date();
+    const h = String(now.getHours()).padStart(2, '0');
+    const m = String(now.getMinutes()).padStart(2, '0');
+    const s = String(now.getSeconds()).padStart(2, '0');
+    return `${h}:${m}:${s}`;
+}
+//# sourceMappingURL=watcher-http.js.map

package/dist/watch/watcher-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-http.js","sourceRoot":"","sources":["../../src/watch/watcher-http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY,EAAE,IAAa;IACjE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,GAAG,GAAG,OAAO,CACjB;YACE,QAAQ,EAAE,WAAW;YACrB,IAAI;YACJ,IAAI;YACJ,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;aAC1C;SACF,EACD,CAAC,GAAG,EAAE,EAAE;YACN,GAAG,CAAC,MAAM,EAAE,CAAC;YACb,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzB,CAAC,CACF,CAAC;QACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxB,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChB,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1B,CAAC"}

package/dist/watch/watcher.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Start the watcher loop for the given project.
+ */
+export declare function startWatcher(cwd: string, port: number): Promise<void>;

package/dist/watch/watcher.js

@@ -0,0 +1,174 @@
+/** Local project watcher — pushes status snapshots to the hub. */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import matter from 'gray-matter';
+import { getConfig, getLogbookDirPath } from '../lib/config.js';
+import { getEntryFilePaths } from '../lib/entry-paths.js';
+import { mdToHtml } from '../lib/build-helpers.js';
+import { transformLogToTimeline } from '../utils/log-timeline.js';
+import { info, success } from '../lib/theme.js';
+import { ALL_COLLECTORS } from './collectors/index.js';
+import { createEmptyState } from './state.js';
+import { evaluateStatuses } from './strategies/index.js';
+import { collectDetails } from './collector.js';
+import { postToHub, logTime } from './watcher-http.js';
+import { setupFileWatchers } from './watcher-fs.js';
+const LOCKFILE_NAME = '.logbook-active';
+/**
+ * Build and push a full status snapshot to the hub.
+ */
+async function pushStatus(cwd, port, projectName, state, reason, jiraBaseUrl, repositoryUrl, primaryColor, agentName) {
+    const statuses = evaluateStatuses(state);
+    const details = await collectDetails(cwd);
+    // Render previews: read entry files, strip frontmatter, render to HTML.
+    let renderedStory;
+    let renderedLog;
+    let renderedTicket;
+    if (state.hasActiveTicket && state.activeTicketSlug) {
+        const config = getConfig(cwd);
+        const entriesDir = getLogbookDirPath(config, cwd);
+        const paths = getEntryFilePaths(entriesDir, state.activeTicketSlug);
+        if (existsSync(paths.index)) {
+            try {
+                const raw = readFileSync(paths.index, 'utf8');
+                renderedStory = await mdToHtml(matter(raw).content);
+            }
+            catch { }
+        }
+        if (existsSync(paths.log)) {
+            try {
+                const raw = readFileSync(paths.log, 'utf8');
+                renderedLog = await transformLogToTimeline(raw);
+            }
+            catch { }
+        }
+        if (existsSync(paths.ticket)) {
+            try {
+                const raw = readFileSync(paths.ticket, 'utf8');
+                renderedTicket = await mdToHtml(raw);
+            }
+            catch { }
+        }
+    }
+    const status = {
+        projectPath: cwd,
+        projectName,
+        branch: state.branch,
+        activeTicket: state.activeTicketId ?? undefined,
+        latestLog: state.latestLog ?? undefined,
+        statuses,
+        lastActivity: state.lastActivityTimestamp,
+        details,
+        renderedStory,
+        renderedLog,
+        renderedTicket,
+        mrUrl: state.mrUrl,
+        jiraStatus: state.jiraStatus,
+        jiraBaseUrl,
+        repositoryUrl,
+        primaryColor,
+        agentName,
+        glabLastUpdated: state.glabLastUpdated,
+        jiraLastUpdated: state.jiraLastUpdated,
+    };
+    await postToHub(port, '/_logbook/status', status);
+    if (state.jiraAssignedIssues) {
+        await postToHub(port, '/_logbook/jira-issues', {
+            projectPath: cwd,
+            issues: state.jiraAssignedIssues,
+        });
+    }
+    if (state.glabOpenMrs) {
+        await postToHub(port, '/_logbook/gitlab-mrs', {
+            projectPath: cwd,
+            mrs: state.glabOpenMrs,
+        });
+    }
+    console.log(info(`[${logTime()}] ${reason}`));
+}
+/**
+ * Start the watcher loop for the given project.
+ */
+export async function startWatcher(cwd, port) {
+    const config = getConfig(cwd);
+    const projectName = config.projectName;
+    const entriesDir = getLogbookDirPath(config, cwd);
+    const lockfilePath = join(cwd, LOCKFILE_NAME);
+    // --- Check availability once at startup ---
+    const activeCollectors = [];
+    for (const collector of ALL_COLLECTORS) {
+        const isAvailable = await collector.available(cwd);
+        if (isAvailable) {
+            activeCollectors.push(collector);
+            console.log(info(`[${logTime()}] Collector '${collector.name}' active`));
+        }
+        else {
+            console.log(info(`[${logTime()}] Collector '${collector.name}' skipped (not available)`));
+        }
+    }
+    // --- Initialize shared state ---
+    const state = createEmptyState();
+    for (const collector of activeCollectors) {
+        await collector.collect(cwd, state);
+    }
+    const payload = { projectPath: cwd, projectName };
+    await postToHub(port, '/_logbook/register', payload);
+    const agentName = undefined;
+    const pushCfg = {
+        jiraBaseUrl: config.jiraBaseUrl ?? '',
+        repositoryUrl: config.repositoryUrl,
+        primaryColor: config.primaryColor,
+        agentName,
+    };
+    const ps = (reason) => pushStatus(cwd, port, projectName, state, reason, pushCfg.jiraBaseUrl, pushCfg.repositoryUrl, pushCfg.primaryColor, pushCfg.agentName);
+    await ps('Initial status collected');
+    const runAndPush = async (collector, reason) => {
+        try {
+            const prevBranch = state.branch;
+            await collector.collect(cwd, state);
+            if (collector.name === 'git' && state.branch !== prevBranch) {
+                for (const c of activeCollectors) {
+                    if (c.name === 'entries' || c.name === 'glab' || c.name === 'jira')
+                        await c.collect(cwd, state);
+                }
+            }
+            await ps(reason);
+        }
+        catch { }
+    };
+    const fsHandles = setupFileWatchers({ cwd, port, entriesDir, lockfilePath, activeCollectors, state, pushStatus: ps });
+    // --- Interval timers for interval-triggered collectors ---
+    const intervals = [];
+    for (const collector of activeCollectors) {
+        const schedule = collector.schedule;
+        if (schedule.type !== 'interval')
+            continue;
+        const timer = setInterval(() => {
+            void runAndPush(collector, `${collector.name} collector (periodic)`);
+        }, schedule.ms);
+        intervals.push(timer);
+    }
+    // --- Graceful shutdown ---
+    const cleanup = async () => {
+        for (const timer of intervals)
+            clearInterval(timer);
+        fsHandles.clearDebounce();
+        for (const w of fsHandles.watchers)
+            w.close();
+        try {
+            await Promise.race([
+                postToHub(port, '/_logbook/deregister', { projectPath: cwd }),
+                new Promise((resolve) => setTimeout(resolve, 1000)),
+            ]);
+        }
+        catch {
+            // Hub already gone.
+        }
+        console.log(info(`[${logTime()}] Watcher stopped. Goodbye.`));
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void cleanup());
+    process.on('SIGTERM', () => void cleanup());
+    console.log(success(`[${logTime()}] Watching with ${activeCollectors.length} collector(s): ${activeCollectors.map((c) => c.name).join(', ')}`));
+}
+//# sourceMappingURL=watcher.js.map

package/dist/watch/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/watch/watcher.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-logbook",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "A command-line tool for project logbooks.",
   "workspaces": [
     "demo-app"
@@ -20,6 +20,7 @@
   "scripts": {
     "dev": "tsx src/index.ts",
     "build": "rimraf dist && tsc && mkdir -p dist/templates && cp src/templates/*.* dist/templates/ && chmod +x dist/index.js",
+    "crawl": "node scripts/crawl.js",
     "prepublishOnly": "npm run build",
     "lint": "eslint src --ext .ts --fix",
     "format": "prettier --write --list-different .",
@@ -27,7 +28,7 @@
     "madge": "madge --circular --extensions ts --ts-config ./tsconfig.json src/index.ts",
     "jscpd": "jscpd src",
     "test": "vitest run",
-    "pre": "npm run format && npm run lint && npm run test && npm run build && npm run knip && npm run madge && npm run jscpd && npm run dev build && npm run dev lint && npm audit",
+    "pre": "npm run format && npm run lint && npm run test && npm run build && npm run knip && npm run madge && npm run jscpd && npm run dev build && npm run dev lint && npm audit --audit-level=high",
     "next": "node scripts/create-ticket-from-backlog.js",
     "link": "npm run build && npm link",
     "open": "npm run dev build && node scripts/open-and-view-dist.js"

package/src/templates/CONTRIBUTING.md

@@ -65,7 +65,17 @@ Once the work is ready:
 
 The linter enforces rules to be followed.
 
-### 4. Final Review
+### 4. Interactive Local QA Loop
+Development is an iterative process. Expect to go through several feedback loops with the prompter before a ticket is finalized:
+- **Test & Challenge**: The prompter will run and test your changes, challenge architectural patterns, and suggest revisions.
+- **Cycle Routine**: During each feedback round:
+  1. Update code according to feedback.
+  2. Log key decisions, errors, and pivots in `log.md` (`logbook log "..."`).
+  3. Keep the story in `index.md` fully up-to-date with any design/code changes.
+  4. Run `npm run pre` to verify linting and tests pass.
+- **Commit Optimization**: Once the implementation is solid, optimize the final git commit message to match project standards before releasing.
+
+### 5. Final Review
 Use the preview command to see how your entry looks in the context of the whole project:
 ```bash
 logbook preview
@@ -88,9 +98,31 @@ If `jiraPrefix` is configured, entry folder names and ticket references must mat
 
 ## Research Logs
 For exploratory research, technical spike investigations, and architectural decision groundwork, we use **Research Logs**.
-- **Location**: Stored in `docs/research/` (configurable via `researchDir`).
-- **Scaffolding**: Run `logbook new [ID] [Slug] --research` or `logbook new -r` to scaffold. This automatically generates a numeric ID prefixed with `RES-` (e.g. `RES-1`).
+
+- **Required Setup**: Before creating your first research log, ensure that your configured research directory exists on your filesystem (for example, create it using `mkdir -p docs/research`).
+- **Location**: Stored in `docs/research/` (configurable via `researchDir` in `.project-logbook`).
+- **Scaffolding**: Run `logbook new [ID] [Slug] --research` or `logbook new -r` to scaffold. This automatically generates a numeric ID prefixed with `RES-` (e.g., `RES-1`).
 - **Commands**: Commands like `logbook start RES-1`, `logbook log`, and `logbook release` work transparently.
 - **Auto-Activity Tracking**: Writing a log message via `logbook log` automatically updates the `updated` frontmatter field inside the research log's `index.md`.
 - **Status Lifecycle**: The frontmatter `status` field tracks progress: `active`, `paused`, `postponed`, or `completed`.
 - **Visuals**: Research logs are compiled and displayed under a dedicated "Research" tab on the built logbook homepage, sorted by their latest `updated` date.
+
+## Custom Storyline Types
+Beyond standard logbook entries and Research Logs, you can define completely custom storyline types (e.g., "analyses", "spikes", "decisions") in `.project-logbook`.
+
+- **Required Setup**: Define the custom types inside your `.project-logbook` configuration file under `customTypes` and ensure the directory exists on your filesystem:
+  ```json
+  {
+    "customTypes": {
+      "analyses": {
+        "prefix": "ANA",
+        "dir": "docs/analyses",
+        "tabTitle": "Analyses",
+        "sortBy": "updated"
+      }
+    }
+  }
+  ```
+- **Directory Setup**: Ensure the directory configured (e.g., `docs/analyses`) is created on your filesystem (for example, create it using `mkdir -p docs/analyses`).
+- **Scaffolding**: Run `logbook new [ID] [Slug] --type analyses` or `logbook new -t analyses` to scaffold the entry.
+- **Visuals**: Just like Research Logs, these custom types will automatically compile into dedicated tabs on the built logbook homepage using your specified `tabTitle`.

package/src/templates/about-watch.md

@@ -0,0 +1,29 @@
+# logbook Hub
+
+The **logbook Hub** is a real-time dashboard for monitoring multiple project-logbook instances on your machine.
+
+## How it works
+
+- The first `logbook watch` invocation binds **port 4201** and becomes the Hub server.
+- Subsequent invocations detect the Hub, register as a Watcher, and push status updates.
+- Each project appears as a card on the dashboard with status badges.
+- The dashboard updates in real time via **Server-Sent Events (SSE)**.
+
+## What you see
+
+| Element | Description |
+|---------|-------------|
+| **Badges** | Color-coded status indicators (green = good, yellow = warning, blue = info) |
+| **Branch** | Current git branch, click to open in the repository |
+| **Ticket** | Active logbook ticket, click to open in Jira (if configured) |
+| **Activity** | Recent events: log entries, starts, releases |
+| **Previews** | Story, Log, and Ticket content rendered as HTML (click buttons) |
+| **Details** | LOC stats, staged/unstaged files, commit counts (click card to expand) |
+
+## Status badges
+
+The Help tab lists every status strategy with its severity and which badges it blocks.
+
+## Jira & GitLab tabs
+
+When a project has `jiraBaseUrl` configured and `JIRA_API_TOKEN` set, assigned issues appear in the Jira tab. When `glab` CLI is installed and authenticated, open merge requests appear in the GitLab tab.

package/src/templates/adr.md

@@ -0,0 +1,34 @@
+---
+id: [ID_NUM]
+title: [YAML_TITLE]
+status: "proposed"
+date: [DATE]
+author: "[AUTHOR]"
+superseded_by: null
+tags: []
+---
+
+# ADR [ID]: [TITLE]
+
+## Context
+[Describe the issue motivating this decision and any context that influences it.]
+
+## Considered Options
+1. **[Option A]**: [Brief description.]
+2. **[Option B]**: [Brief description.]
+
+## Decision
+[State the decision and briefly explain what it means in practice.]
+
+## Rationale
+[Explain why this option was chosen over the alternatives.]
+
+## Consequences
+
+### Positive
+*   [Benefit 1]
+*   [Benefit 2]
+
+### Negative
+*   [Drawback 1]
+*   [Drawback 2]