project-logbook 0.3.0

package/README.md

@@ -0,0 +1,34 @@
+# project-logbook
+
+**Idea:** Imagine returning from a week away to 50 tickets resolved by LLM agents. Instead of scanning endless diffs, a narrative timeline summarizes each change as a brief story, bringing you up to speed in minutes.
+
+**Project Logbook** is an experimental CLI tool that automates documentation in agentic developer environments by generating a web-based timeline of recent changes. By establishing simple workflows and prompting guidelines for both humans and LLMs, it is currently best suited for smaller projects with a low-to-moderate volume of changes.
+
+![Screenshot of generated website](/static/screenshot.jpg "Generated website")
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the mandatory working protocol.
+
+
+## The Three-File Standard
+Each entry in `logbook/` consists of:
+1. `ticket.md`: Requirements and specifications.
+2. `log.md`: Technical chronological protocol (developer/AI scratchpad).
+3. `index.md`: Polished narrative of the change (human-readable story).
+
+## Installation
+```bash
+npm i project-loogbook -g
+```
+
+## Commands
+- `logbook init`: Initialize configuration and directory.
+- `logbook new <id> <slug>`: Create a new entry folder with templates.
+- `logbook start <id>`: Mark a logbook entry as active (writes `.logbook-active` lockfile). The active entry is also auto-detected from the current Git branch — a branch named `feat/LB-123-my-feature` will automatically resolve to entry `LB-123`.
+- `logbook release`: Release the active logbook entry (removes `.logbook-active` lockfile).
+- `logbook log <message>`: Append a timestamped log entry to the active `log.md`.
+- `logbook list`: List all logbook entries with their status.
+- `logbook lint`: Validate structure, frontmatter, and internal links.
+- `logbook build`: Compile logbook entries into a static HTML site (default: `public/`).
+- `logbook preview`: Build and open the logbook in your default browser.
+- `logbook upgrade`: Synchronize core project files (like `CONTRIBUTING.md`) with latest templates.
+- `logbook steer`: Output agentic protocol for AI assistants.

package/dist/commands/build.d.ts

@@ -0,0 +1 @@
+export declare function build(): Promise<void>;

package/dist/commands/build.js

@@ -0,0 +1,174 @@
+import fs from 'fs-extra';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getConfig, getWorkspaces } from '../lib/config.js';
+import { layout, timelineTemplate } from '../lib/templates.js';
+import { getStyles } from '../lib/styles.js';
+import { getClientScript } from '../lib/logbook-client.js';
+import { mdToHtml, buildProjectMdFiles, renderPost } from '../lib/build-helpers.js';
+import { mdToHtmlWithImages, copyImages } from '../lib/image-helpers.js';
+import { getGitCommits, getGitTags } from '../lib/git-helpers.js';
+import { formatRelativeDate, getMonthYear, getSortTime } from '../utils/date.js';
+import { getLogbookEntries } from '../utils/fs.js';
+import { getAboutContent } from '../lib/about-content.js';
+const pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const version = pkg.version;
+export async function build() {
+    const config = getConfig();
+    const logbookDir = join(process.cwd(), config.logbookDir);
+    const outputDir = join(process.cwd(), config.outputDir);
+    const buildTime = new Date()
+        .toLocaleString('de-DE', {
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    })
+        .replace(',', '');
+    if (!(await fs.pathExists(logbookDir))) {
+        console.error(chalk.red(`Error: Logbook directory '${config.logbookDir}' not found.`));
+        return;
+    }
+    await fs.remove(outputDir);
+    await fs.mkdirp(outputDir);
+    await fs.copyFile(new URL('../templates/favicon.svg', import.meta.url), join(outputDir, 'favicon.svg'));
+    await fs.writeFile(join(outputDir, 'style.css'), getStyles(config.primaryColor));
+    await fs.writeFile(join(outputDir, 'logbook.js'), getClientScript());
+    const readmePath = join(process.cwd(), 'README.md');
+    let readmeHtml = '';
+    let readmeImages = [];
+    try {
+        if (await fs.pathExists(readmePath)) {
+            const readmeContent = await fs.readFile(readmePath, 'utf8');
+            const { html, imagePaths } = await mdToHtmlWithImages(readmeContent);
+            readmeHtml = html;
+            readmeImages = imagePaths;
+        }
+    }
+    catch (error) {
+        console.warn(chalk.yellow('Warning: Failed to read README.md:', error instanceof Error ? error.message : error));
+        readmeHtml = '<p>README unavailable.</p>';
+    }
+    // Copy README images to output
+    if (readmeImages.length > 0) {
+        await copyImages(process.cwd(), outputDir, readmeImages);
+    }
+    const aboutHtml = await mdToHtml(getAboutContent());
+    const logbookEntries = await getLogbookEntries(logbookDir);
+    const timelineEntries = [];
+    const availableWorkspaces = getWorkspaces();
+    for (const entry of logbookEntries) {
+        if (!entry.hasIndex)
+            continue;
+        const { data, content, slug } = entry;
+        let summary = data.summary;
+        if (!summary) {
+            const firstParagraph = content.split('\n\n').find((p) => p.trim() && !p.trim().startsWith('#'));
+            summary = firstParagraph
+                ? firstParagraph.trim().substring(0, 200).replace(/[*#`]/g, '') + '...'
+                : 'No summary available.';
+        }
+        const entryWorkspaces = Array.isArray(data.workspaces)
+            ? data.workspaces.filter((ws) => typeof ws === 'string' && availableWorkspaces.includes(ws))
+            : [];
+        const dateStartValue = data.dateStart;
+        const dateStart = typeof dateStartValue === 'string'
+            ? dateStartValue
+            : dateStartValue instanceof Date
+                ? dateStartValue.toISOString()
+                : '';
+        // Skip DRAFT entries (no valid dateStart) — they break the timeline
+        if (!dateStart || dateStart.includes('{{'))
+            continue;
+        const dateEndValue = data.dateEnd;
+        const dateEnd = typeof dateEndValue === 'string'
+            ? dateEndValue
+            : dateEndValue instanceof Date
+                ? dateEndValue.toISOString()
+                : undefined;
+        timelineEntries.push({
+            kind: 'entry',
+            slug,
+            dateStart,
+            dateEnd,
+            displayDate: formatRelativeDate(dateStart),
+            sortTime: getSortTime(dateStart, dateEnd),
+            summary: typeof summary === 'string' ? summary : 'No summary available.',
+            ticket: typeof data.ticket === 'string' ? data.ticket : slug,
+            monthGroup: getMonthYear(dateStart),
+            tags: Array.isArray(data.tags) ? data.tags.filter((t) => typeof t === 'string') : [],
+            workspaces: entryWorkspaces,
+            title: typeof data.title === 'string' ? data.title : undefined,
+            harness: typeof data.harness === 'string' ? data.harness : undefined,
+            llm: typeof data.llm === 'string' ? data.llm : undefined,
+            prompter: typeof data.prompter === 'string' ? data.prompter : undefined,
+        });
+    }
+    // Fetch global git commits and tags concurrently.
+    const [globalCommits, rawTags] = await Promise.all([getGitCommits(process.cwd()), getGitTags()]);
+    const commitItems = globalCommits.map((c) => ({
+        kind: 'commit',
+        sha: c.sha,
+        message: c.message,
+        timestamp: c.timestamp,
+        relativeTime: c.relativeTime,
+        displayDate: formatRelativeDate(c.timestamp),
+        monthGroup: getMonthYear(c.timestamp),
+        sortTime: getSortTime(c.timestamp),
+    }));
+    const tagItems = rawTags.map((t) => ({
+        kind: 'tag',
+        name: t.name,
+        timestamp: t.timestamp,
+        displayDate: formatRelativeDate(t.timestamp),
+        monthGroup: getMonthYear(t.timestamp),
+        sortTime: getSortTime(t.timestamp),
+    }));
+    console.log(chalk.gray(`Found ${timelineEntries.length} entr${timelineEntries.length === 1 ? 'y' : 'ies'}, ${commitItems.length} commit${commitItems.length === 1 ? '' : 's'} (max 100), and ${tagItems.length} tag${tagItems.length === 1 ? '' : 's'}.`));
+    timelineEntries.sort((a, b) => {
+        const aEnd = a.dateEnd ? new Date(a.dateEnd).getTime() : new Date(a.dateStart).getTime();
+        const bEnd = b.dateEnd ? new Date(b.dateEnd).getTime() : new Date(b.dateStart).getTime();
+        return bEnd - aEnd;
+    });
+    await Promise.all(timelineEntries.map((entry, i) => renderPost(entry, i, timelineEntries, { logbookDir, outputDir, config, version, buildTime })));
+    const groups = groupTimelineItems(timelineEntries, commitItems, tagItems);
+    const timelineContent = timelineTemplate({ projectName: config.projectName, version, buildTime, groups, readmeHtml, aboutHtml, jiraBaseUrl: config.jiraBaseUrl, jiraPrefix: config.jiraPrefix }); // prettier-ignore
+    const buildMeta = `Generated by ${config.projectName} v${version} • ${buildTime}`;
+    const timelineHtml = layout({
+        title: 'Timeline',
+        projectName: config.projectName,
+        basePath: './',
+        buildMeta,
+        header: timelineContent.split('</header>')[0] + '</header>',
+        content: timelineContent.split('</header>')[1],
+    });
+    await fs.writeFile(join(outputDir, 'index.html'), timelineHtml);
+    await buildProjectMdFiles(process.cwd(), outputDir, [config.logbookDir, config.outputDir, 'node_modules'], {
+        config,
+        version,
+        buildTime,
+    });
+    console.log(chalk.green(`\nSuccessfully built logbook to ${config.outputDir}/`));
+}
+function groupTimelineItems(entries, commits, tags) {
+    const toMs = (item) => {
+        if (item.kind === 'entry')
+            return item.dateEnd ? new Date(item.dateEnd).getTime() : new Date(item.dateStart).getTime();
+        return new Date(item.timestamp).getTime();
+    };
+    const all = [...entries, ...commits, ...tags];
+    all.sort((a, b) => toMs(b) - toMs(a));
+    const groups = [];
+    for (const item of all) {
+        let group = groups.find((g) => g.month === item.monthGroup);
+        if (!group) {
+            group = { month: item.monthGroup, items: [] };
+            groups.push(group);
+        }
+        group.items.push(item);
+    }
+    return groups;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,83 @@
+import fs from 'fs-extra';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import chalk from 'chalk';
+import { DEFAULT_CONFIG } from '../lib/config.js';
+import { getTemplatesDir } from '../lib/migrations.js';
+const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+const question = (prompt) => {
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            resolve(answer.trim());
+        });
+    });
+};
+function readPackageJsonName(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return null;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.name === 'string' && pkg.name ? pkg.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function init() {
+    const cwd = process.cwd();
+    const configPath = join(cwd, '.project-logbook');
+    const logbookDir = join(cwd, DEFAULT_CONFIG.logbookDir);
+    const contributingPath = join(cwd, 'CONTRIBUTING.md');
+    // 1. Config file
+    if (await fs.pathExists(configPath)) {
+        console.log(chalk.yellow('Already initialized. .project-logbook exists.'));
+        rl.close();
+        return;
+    }
+    console.log(chalk.blue('\n📒 Initializing project-logbook\n'));
+    // Detect project name from package.json
+    const detectedName = readPackageJsonName(cwd);
+    const defaultName = detectedName || DEFAULT_CONFIG.projectName;
+    const nameInput = await question(chalk.cyan(`Project name (press Enter for "${defaultName}"): `));
+    const projectName = nameInput || defaultName;
+    // Optional Jira config
+    const jiraPrefixInput = await question(chalk.cyan('Jira project prefix (e.g. MYAPP, leave blank to skip): '));
+    const jiraPrefix = jiraPrefixInput || undefined;
+    let jiraBaseUrl;
+    if (jiraPrefix) {
+        const jiraUrlInput = await question(chalk.cyan('Jira base URL (e.g. https://yourorg.atlassian.net, leave blank to skip): '));
+        jiraBaseUrl = jiraUrlInput || undefined;
+    }
+    rl.close();
+    // Build config — only write user-relevant fields, omit frontmatter.allowed (tool-managed)
+    const config = {
+        ...DEFAULT_CONFIG,
+        projectName,
+    };
+    if (jiraPrefix)
+        config.jiraPrefix = jiraPrefix;
+    if (jiraBaseUrl)
+        config.jiraBaseUrl = jiraBaseUrl;
+    await fs.writeJson(configPath, config, { spaces: 2 });
+    console.log(chalk.green('\n✔ Created .project-logbook config file.'));
+    // 2. Logbook directory
+    if (!(await fs.pathExists(logbookDir))) {
+        await fs.mkdirp(logbookDir);
+        console.log(chalk.green(`✔ Created ${DEFAULT_CONFIG.logbookDir}/ directory.`));
+    }
+    // 3. CONTRIBUTING.md (from template)
+    if (!(await fs.pathExists(contributingPath))) {
+        const templatePath = join(getTemplatesDir(), 'CONTRIBUTING.md');
+        if (await fs.pathExists(templatePath)) {
+            await fs.copyFile(templatePath, contributingPath);
+            console.log(chalk.green('✔ Created CONTRIBUTING.md with agentic workflow protocol.'));
+        }
+    }
+    // 4. Hint
+    console.log(chalk.dim('\n💡 Tip: Edit .project-logbook to customize primaryColor, add more tags, or configure Jira settings.'));
+    console.log(chalk.dim('   Run `logbook new` to create your first entry.\n'));
+}

package/dist/commands/lint.d.ts

@@ -0,0 +1 @@
+export declare function lint(): Promise<void>;

package/dist/commands/lint.js

@@ -0,0 +1,78 @@
+import fs from 'fs-extra';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getConfig } from '../lib/config.js';
+import { runLinters } from '../lib/lint-runner.js';
+import { getLogbookEntries } from '../utils/fs.js';
+export async function lint() {
+    const config = getConfig();
+    const logbookDir = join(process.cwd(), config.logbookDir);
+    if (!(await fs.pathExists(logbookDir))) {
+        console.error(chalk.red(`Error: Logbook directory '${config.logbookDir}' not found.`));
+        return;
+    }
+    let overallSuccess = true;
+    // 1. Project-level checks
+    console.log(chalk.blue('Checking project integrity...'));
+    const projectSuccess = await runLinters({ config });
+    if (!projectSuccess)
+        overallSuccess = false;
+    // 2. Entry-level checks
+    const logbookEntries = await getLogbookEntries(logbookDir);
+    let passedCount = 0;
+    let skippedCount = 0;
+    for (const entry of logbookEntries) {
+        if (!entry.hasIndex) {
+            console.error(chalk.red(`  [MISSING] ${entry.slug}/index.md`));
+            overallSuccess = false;
+            continue;
+        }
+        if (isDraft(entry)) {
+            skippedCount++;
+            continue;
+        }
+        const entrySuccess = await runLinters({
+            config,
+            entryName: entry.slug,
+            entryPath: entry.path,
+            indexPath: entry.indexPath,
+            content: entry.content,
+            frontmatter: entry.data,
+        });
+        if (entrySuccess) {
+            passedCount++;
+        }
+        else {
+            overallSuccess = false;
+        }
+    }
+    if (overallSuccess) {
+        const skippedNote = skippedCount > 0
+            ? chalk.gray(` (${skippedCount} DRAFT ${skippedCount === 1 ? 'entry' : 'entries'} skipped)`)
+            : '';
+        console.log(chalk.green(`\nAll ${passedCount} entries passed linting!`) + skippedNote);
+    }
+    else {
+        console.log(chalk.red('\nLinting failed with errors. If you are a LLM, try to fix the errors.'));
+        process.exit(1);
+    }
+}
+/**
+ * Returns true if an entry is in DRAFT state (has unfilled template placeholders),
+ * meaning it should be exempt from linting.
+ */
+function isDraft(entry) {
+    const dataValues = Object.values(entry.data)
+        .filter((v) => typeof v === 'string')
+        .join('\n');
+    const frontmatterHasPlaceholders = dataValues.includes('[DATE_END]') ||
+        dataValues.includes('[DATE_START]') ||
+        dataValues.includes('[WRITE_SUMMARY_HERE]') ||
+        dataValues.includes('[PROMPTER]') ||
+        dataValues.includes('[HARNESS]') ||
+        dataValues.includes('[LLM]');
+    const contentWithoutCode = entry.content.replace(/`[^`]*`/g, '');
+    const bodyHasPlaceholders = contentWithoutCode.includes('TODO:') ||
+        entry.content.includes('Write a polished, highly readable "short story" of the change here.');
+    return frontmatterHasPlaceholders || bodyHasPlaceholders;
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,3 @@
+export declare function list(options?: {
+    all?: boolean;
+}): Promise<void>;

package/dist/commands/list.js

@@ -0,0 +1,127 @@
+import fs from 'fs-extra';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getConfig } from '../lib/config.js';
+import { getLogbookEntries } from '../utils/fs.js';
+import { stripAnsi } from '../utils/string.js';
+import { parseTicketId } from '../utils/id.js';
+import { getActiveEntry } from '../lib/session.js';
+export async function list(options = {}) {
+    const config = getConfig();
+    const logbookDir = join(process.cwd(), config.logbookDir);
+    if (!(await fs.pathExists(logbookDir))) {
+        console.error(chalk.red(`Error: Logbook directory '${config.logbookDir}' not found. Run 'logbook init' first.`));
+        process.exit(1);
+    }
+    // Detect currently active entry (if any)
+    const active = await getActiveEntry();
+    const activeSlug = active?.slug;
+    const logbookEntries = await getLogbookEntries(logbookDir);
+    const rows = [];
+    for (const entry of logbookEntries) {
+        if (!entry.hasIndex) {
+            // Parse ticket ID and title from directory name slug
+            const parsed = parseTicketId(entry.slug);
+            let draftTicketId;
+            let draftTitle;
+            if (parsed) {
+                draftTicketId = `${parsed.prefix}-${parsed.number}`;
+                const titlePart = entry.slug.replace(/^[A-Za-z]+-\d+-/, '');
+                draftTitle = titlePart.replace(/-/g, ' ');
+            }
+            else {
+                draftTicketId = entry.slug;
+                draftTitle = '';
+            }
+            rows.push({
+                ticketId: draftTicketId,
+                title: chalk.gray(draftTitle),
+                prompter: '',
+                status: chalk.yellow('DRAFT'),
+            });
+            continue;
+        }
+        const { data, content } = entry;
+        const isActive = activeSlug === entry.slug;
+        // Check frontmatter field values for bracket-style unfilled placeholders
+        const dataValues = Object.values(data)
+            .filter((v) => typeof v === 'string')
+            .join('\n');
+        const frontmatterHasPlaceholders = dataValues.includes('[DATE_END]') ||
+            dataValues.includes('[DATE_START]') ||
+            dataValues.includes('[WRITE_SUMMARY_HERE]') ||
+            dataValues.includes('[PROMPTER]') ||
+            dataValues.includes('[HARNESS]') ||
+            dataValues.includes('[LLM]');
+        // Check body content for unfilled template hints (strip inline code spans to avoid false positives)
+        const contentWithoutCode = content.replace(/`[^`]*`/g, '');
+        const bodyHasPlaceholders = contentWithoutCode.includes('TODO:') ||
+            content.includes('Write a polished, highly readable "short story" of the change here.');
+        const hasPlaceholders = frontmatterHasPlaceholders || bodyHasPlaceholders;
+        const status = isActive ? chalk.cyan('● ACTIVE') : hasPlaceholders ? chalk.yellow('DRAFT') : chalk.green('DONE');
+        rows.push({
+            ticketId: typeof data.ticket === 'string' ? data.ticket : chalk.gray('-'),
+            title: typeof data.title === 'string' ? data.title : chalk.gray('(untitled)'),
+            prompter: typeof data.prompter === 'string' ? data.prompter : chalk.gray('-'),
+            status,
+        });
+    }
+    if (rows.length === 0) {
+        console.log(chalk.yellow('No logbook entries found. Use `logbook new <id> <slug>` to create one.'));
+        return;
+    }
+    // Sort by ticket ID descending
+    rows.sort((a, b) => {
+        const idA = parseTicketId(a.ticketId);
+        const idB = parseTicketId(b.ticketId);
+        if (idA && idB) {
+            if (idA.prefix !== idB.prefix) {
+                return idB.prefix.localeCompare(idA.prefix);
+            }
+            return idB.number - idA.number;
+        }
+        // Fallback to alphabetical if parsing fails
+        return b.ticketId.localeCompare(a.ticketId);
+    });
+    const totalEntries = rows.length;
+    let displayedRows = rows;
+    if (!options.all && rows.length > 20) {
+        displayedRows = rows.slice(0, 20);
+    }
+    // Calculate column widths
+    const colWidths = {
+        ticketId: Math.max(9, ...displayedRows.map((r) => stripAnsi(r.ticketId).length)),
+        title: Math.max(5, ...displayedRows.map((r) => stripAnsi(r.title).length)),
+        prompter: Math.max(8, ...displayedRows.map((r) => stripAnsi(r.prompter).length)),
+        status: Math.max(6, ...displayedRows.map((r) => stripAnsi(r.status).length)),
+    };
+    const pad = (s, len) => s + ' '.repeat(Math.max(0, len - stripAnsi(s).length));
+    const header = [
+        chalk.bold(pad('TICKET-ID', colWidths.ticketId)),
+        chalk.bold(pad('TITLE', colWidths.title)),
+        chalk.bold(pad('PROMPTER', colWidths.prompter)),
+        chalk.bold('STATUS'),
+    ].join('  ');
+    const divider = [
+        '─'.repeat(colWidths.ticketId),
+        '─'.repeat(colWidths.title),
+        '─'.repeat(colWidths.prompter),
+        '─'.repeat(colWidths.status),
+    ].join('  ');
+    console.log('');
+    console.log(header);
+    console.log(chalk.gray(divider));
+    for (const row of displayedRows) {
+        console.log([
+            pad(row.ticketId, colWidths.ticketId),
+            pad(row.title, colWidths.title),
+            pad(row.prompter, colWidths.prompter),
+            row.status,
+        ].join('  '));
+    }
+    console.log('');
+    const countText = displayedRows.length === totalEntries
+        ? `${totalEntries} ${totalEntries === 1 ? 'entry' : 'entries'}`
+        : `Showing latest ${displayedRows.length} of ${totalEntries} entries (use --all to show all)`;
+    console.log(chalk.gray(`${countText} in ${config.logbookDir}/`));
+}

package/dist/commands/log.d.ts

@@ -0,0 +1,3 @@
+export declare function log(messages: string[], options?: {
+    id?: string;
+}): Promise<void>;

package/dist/commands/log.js

@@ -0,0 +1,31 @@
+import fs from 'fs-extra';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getConfig } from '../lib/config.js';
+import { getActiveEntry } from '../lib/session.js';
+export async function log(messages, options = {}) {
+    const cwd = process.cwd();
+    // 1. Require an active entry
+    const active = await getActiveEntry(options, cwd);
+    if (!active) {
+        console.error(chalk.red(`Error: No active logbook entry resolved.`));
+        console.error(chalk.red(`Activate an entry via 'logbook start <id>', checkout a feature branch, or pass --id.`));
+        process.exit(1);
+    }
+    const config = getConfig();
+    const logPath = join(cwd, config.logbookDir, active.slug, 'log.md');
+    if (!(await fs.pathExists(logPath))) {
+        console.error(chalk.red(`Error: log.md not found`));
+        process.exit(1);
+    }
+    // 2. Build new lines: "- <ISO timestamp>: <message>"
+    const timestamp = new Date().toISOString();
+    const newLines = messages.map((msg) => `- ${timestamp}: ${msg}`).join('\n');
+    // 3. Append to log.md
+    const existing = await fs.readFile(logPath, 'utf8');
+    const separator = existing.endsWith('\n') ? '' : '\n';
+    await fs.writeFile(logPath, existing + separator + newLines + '\n');
+    for (const msg of messages) {
+        console.log(chalk.green(`Logged to ${active.slug} (via ${active.source}): ${timestamp}: ${msg}`));
+    }
+}

package/dist/commands/new.d.ts

@@ -0,0 +1 @@
+export declare function createNewEntry(id?: string, slug?: string): Promise<void>;