feat(migrate): add --logs-to-ledger to migrate logs/*.md into ledger.jsonl

Converts legacy per-task .md files in logs/ into append-only ledger
records. Resolves ID conflicts caused by the old core allowing duplicate
IDs between board/ and logs/ — completed tasks take precedence and
conflicting board tasks are renamed to the next available ID.

Made-with: Cursor

Author: 1broseidon

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainfile/cli",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "Command-line interface for Brainfile task management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package.json

@@ -0,0 +1,160 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { migrateCommand } from '../commands/migrate';
+import { readTaskFile, writeTaskFile, readLedger } from '@brainfile/core';
+
+function setupV2Workspace(tempDir: string): { dotDir: string; boardDir: string; logsDir: string } {
+  const dotDir = path.join(tempDir, '.brainfile');
+  const boardDir = path.join(dotDir, 'board');
+  const logsDir = path.join(dotDir, 'logs');
+  fs.mkdirSync(boardDir, { recursive: true });
+  fs.mkdirSync(logsDir, { recursive: true });
+
+  const config = `---
+title: Test Board
+schema: https://brainfile.md/v2/board.json
+columns:
+  - id: todo
+    title: To Do
+  - id: in-progress
+    title: In Progress
+---
+`;
+  fs.writeFileSync(path.join(dotDir, 'brainfile.md'), config, 'utf-8');
+  return { dotDir, boardDir, logsDir };
+}
+
+function writeLogTask(logsDir: string, id: string, title: string, extra: Record<string, unknown> = {}): void {
+  const task = { id, title, completedAt: '2026-01-15T12:00:00Z', ...extra };
+  writeTaskFile(path.join(logsDir, `${id}.md`), task as any, `Completed ${title}.`);
+}
+
+function writeBoardTask(boardDir: string, id: string, title: string, extra: Record<string, unknown> = {}): void {
+  const task = { id, title, column: 'todo', position: 0, ...extra };
+  writeTaskFile(path.join(boardDir, `${id}.md`), task as any, '');
+}
+
+describe('migrate --logs-to-ledger', () => {
+  let tempDir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'brainfile-logs-ledger-'));
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('migrates log .md files into ledger.jsonl and removes them', () => {
+    const { logsDir } = setupV2Workspace(tempDir);
+    writeLogTask(logsDir, 'task-1', 'First completed task');
+    writeLogTask(logsDir, 'task-2', 'Second completed task', { tags: ['bug'] });
+
+    migrateCommand({ logsToLedger: true });
+
+    const records = readLedger(logsDir);
+    expect(records.length).toBe(2);
+    expect(records.map((r) => r.id).sort()).toEqual(['task-1', 'task-2']);
+    expect(records[0].completedAt).toBe('2026-01-15T12:00:00Z');
+
+    expect(fs.existsSync(path.join(logsDir, 'task-1.md'))).toBe(false);
+    expect(fs.existsSync(path.join(logsDir, 'task-2.md'))).toBe(false);
+  });
+
+  it('skips log tasks already in the ledger', () => {
+    const { logsDir } = setupV2Workspace(tempDir);
+    writeLogTask(logsDir, 'task-1', 'Already tracked');
+
+    // Pre-populate ledger with task-1
+    const ledgerPath = path.join(logsDir, 'ledger.jsonl');
+    fs.writeFileSync(ledgerPath, JSON.stringify({
+      id: 'task-1', type: 'task', title: 'Already tracked',
+      filesChanged: ['task-1.md'], createdAt: '2026-01-01T00:00:00Z',
+      completedAt: '2026-01-15T12:00:00Z', cycleTimeHours: 360, summary: 'done',
+    }) + '\n');
+
+    migrateCommand({ logsToLedger: true });
+
+    const records = readLedger(logsDir);
+    expect(records.length).toBe(1);
+    // .md file kept (no --force)
+    expect(fs.existsSync(path.join(logsDir, 'task-1.md'))).toBe(true);
+  });
+
+  it('removes stale .md files with --force when already in ledger', () => {
+    const { logsDir } = setupV2Workspace(tempDir);
+    writeLogTask(logsDir, 'task-1', 'Already tracked');
+
+    const ledgerPath = path.join(logsDir, 'ledger.jsonl');
+    fs.writeFileSync(ledgerPath, JSON.stringify({
+      id: 'task-1', type: 'task', title: 'Already tracked',
+      filesChanged: ['task-1.md'], createdAt: '2026-01-01T00:00:00Z',
+      completedAt: '2026-01-15T12:00:00Z', cycleTimeHours: 360, summary: 'done',
+    }) + '\n');
+
+    migrateCommand({ logsToLedger: true, force: true });
+
+    expect(fs.existsSync(path.join(logsDir, 'task-1.md'))).toBe(false);
+    expect(readLedger(logsDir).length).toBe(1);
+  });
+
+  it('resolves ID conflicts by renaming the board task', () => {
+    const { boardDir, logsDir } = setupV2Workspace(tempDir);
+
+    // Simulate the old bug: task-1 exists in both board/ and logs/
+    writeLogTask(logsDir, 'task-1', 'Original completed task');
+    writeBoardTask(boardDir, 'task-1', 'Duplicate board task');
+    writeBoardTask(boardDir, 'task-5', 'Another board task');
+
+    migrateCommand({ logsToLedger: true });
+
+    // Log task should be in ledger
+    const records = readLedger(logsDir);
+    expect(records.length).toBe(1);
+    expect(records[0].id).toBe('task-1');
+    expect(records[0].title).toBe('Original completed task');
+
+    // Old board/task-1.md should be gone
+    expect(fs.existsSync(path.join(boardDir, 'task-1.md'))).toBe(false);
+
+    // Board task should have been renamed (next available after task-5 + ledger task-1)
+    const boardFiles = fs.readdirSync(boardDir).filter((f) => f.endsWith('.md'));
+    expect(boardFiles).toContain('task-5.md');
+    expect(boardFiles.length).toBe(2);
+
+    // The renamed task should have the same title as the duplicate
+    const renamedFile = boardFiles.find((f) => f !== 'task-5.md')!;
+    const renamedTask = readTaskFile(path.join(boardDir, renamedFile));
+    expect(renamedTask).not.toBeNull();
+    expect(renamedTask!.task.title).toBe('Duplicate board task');
+
+    // Log .md file should be cleaned up
+    expect(fs.existsSync(path.join(logsDir, 'task-1.md'))).toBe(false);
+  });
+
+  it('handles epic- and adr- prefixed tasks', () => {
+    const { logsDir } = setupV2Workspace(tempDir);
+    writeLogTask(logsDir, 'epic-1', 'Done epic');
+    writeLogTask(logsDir, 'adr-1', 'Done ADR');
+
+    migrateCommand({ logsToLedger: true });
+
+    const records = readLedger(logsDir);
+    expect(records.length).toBe(2);
+    expect(records.find((r) => r.id === 'epic-1')?.type).toBe('epic');
+    expect(records.find((r) => r.id === 'adr-1')?.type).toBe('adr');
+  });
+
+  it('does nothing when logs/ has no .md files', () => {
+    const { logsDir } = setupV2Workspace(tempDir);
+
+    migrateCommand({ logsToLedger: true });
+
+    expect(fs.existsSync(path.join(logsDir, 'ledger.jsonl'))).toBe(false);
+  });
+});

src/__tests__/migrate-logs-to-ledger.test.ts

@@ -160,6 +160,7 @@ Brainfile file resolution (when you don't pass --file):
     .option('--dir <path>', 'Directory containing legacy brainfile files (default: cwd)')
     .option('--force', 'Overwrite existing migration outputs (task files/backups)')
     .option('--v2', 'Deprecated alias; migration now targets v2 by default')
+    .option('--logs-to-ledger', 'Migrate logs/*.md files into ledger.jsonl (resolves ID conflicts with board)')
     .action(migrateCommand);
 
   const listCmd = program

src/cli.ts

@@ -2,7 +2,16 @@ import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import { Brainfile } from '@brainfile/core';
-import { writeTaskFile, taskFileName, type Task } from '@brainfile/core';
+import {
+  writeTaskFile,
+  taskFileName,
+  readTasksDir,
+  readLedger,
+  buildLedgerRecord,
+  appendLedgerRecord,
+  generateNextFileTaskId,
+  type Task,
+} from '@brainfile/core';
 import { ensureDotBrainfileGitignore, removeLegacyStateFile } from '../utils/dot-brainfile';
 import { ensureV2Dirs } from '../utils/v2-detect';
 import { probeWorkspaceFormat, type WorkspaceProbe } from '../utils/workspace-format';
@@ -14,13 +23,20 @@ interface MigrateOptions {
   force?: boolean;
   /** Deprecated alias; migration always targets v2 now */
   v2?: boolean;
+  /** Migrate logs/*.md files into ledger.jsonl and clean up */
+  logsToLedger?: boolean;
 }
 
 /**
  * Migrate legacy workspace layouts to v2 (.brainfile/brainfile.md + board/ + logs/).
  */
 export function migrateCommand(options: MigrateOptions = {}) {
   try {
+    if (options.logsToLedger) {
+      migrateLogsToLedger(options);
+      return;
+    }
+
     const rootDir = path.resolve(options.dir || process.cwd());
     const probe = probeWorkspaceFormat(rootDir);
 
@@ -279,6 +295,120 @@ function migrateBrainfileToV2(brainfilePath: string, options: MigrateOptions): v
   console.log(chalk.gray(`  Backup:          ${backupPath}`));
 }
 
+/**
+ * Extract the type prefix from a task ID (e.g. "task" from "task-42", "epic" from "epic-3").
+ */
+function getTypePrefix(taskId: string): string {
+  const match = taskId.match(/^(.+)-\d+$/);
+  return match ? match[1] : 'task';
+}
+
+/**
+ * Migrate legacy logs/*.md files into ledger.jsonl.
+ *
+ * When the old core allowed ID reuse (e.g. task-1 in both board/ and logs/),
+ * this resolves the conflict by keeping the log entry (it was completed first)
+ * and renaming the board task to the next available ID.
+ */
+function migrateLogsToLedger(options: MigrateOptions): void {
+  const rootDir = path.resolve(options.dir || process.cwd());
+  const probe = probeWorkspaceFormat(rootDir);
+
+  if (probe.format === 'empty') {
+    console.error(chalk.red('Error: No brainfile workspace found.'));
+    process.exit(1);
+    return;
+  }
+
+  const { logsDir, boardDir } = probe.paths;
+
+  if (!fs.existsSync(logsDir)) {
+    console.log(chalk.gray('No logs/ directory found. Nothing to migrate.'));
+    return;
+  }
+
+  const logDocs = readTasksDir(logsDir);
+  if (logDocs.length === 0) {
+    console.log(chalk.gray('No .md log files found in logs/. Nothing to migrate.'));
+    return;
+  }
+
+  // Read only the actual ledger.jsonl — don't use readLedger() which falls back
+  // to reading the very .md files we're about to migrate.
+  const ledgerPath = path.join(logsDir, 'ledger.jsonl');
+  const existingLedgerIds = new Set<string>();
+  if (fs.existsSync(ledgerPath)) {
+    const lines = fs.readFileSync(ledgerPath, 'utf-8').split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const record = JSON.parse(trimmed);
+        if (record?.id) existingLedgerIds.add(record.id);
+      } catch { /* skip malformed lines */ }
+    }
+  }
+
+  const boardDocs = fs.existsSync(boardDir) ? readTasksDir(boardDir) : [];
+  const boardIdMap = new Map(boardDocs.map((d) => [d.task.id, d]));
+
+  let migratedCount = 0;
+  let skippedCount = 0;
+  let conflictCount = 0;
+
+  for (const doc of logDocs) {
+    const taskId = doc.task.id;
+
+    if (existingLedgerIds.has(taskId)) {
+      console.log(chalk.gray(`  Skip: ${taskId} (already in ledger)`));
+      if (options.force) {
+        fs.rmSync(doc.filePath!, { force: true });
+        console.log(chalk.gray(`    Removed stale log file: ${path.basename(doc.filePath!)}`));
+      }
+      skippedCount++;
+      continue;
+    }
+
+    const record = buildLedgerRecord(doc.task, doc.body, {
+      completedAt: doc.task.completedAt || doc.task.updatedAt || new Date().toISOString(),
+    });
+    appendLedgerRecord(logsDir, record);
+    existingLedgerIds.add(taskId);
+    migratedCount++;
+
+    if (boardIdMap.has(taskId)) {
+      const boardDoc = boardIdMap.get(taskId)!;
+      const prefix = getTypePrefix(taskId);
+      const newId = generateNextFileTaskId(boardDir, logsDir, prefix);
+
+      const renamedTask: Task = { ...boardDoc.task, id: newId };
+      const newBoardPath = path.join(boardDir, taskFileName(newId));
+      writeTaskFile(newBoardPath, renamedTask, boardDoc.body);
+      fs.rmSync(boardDoc.filePath!, { force: true });
+
+      console.log(chalk.yellow(`  Conflict: board/${taskId} → ${newId} (completed task takes precedence)`));
+      conflictCount++;
+    }
+
+    fs.rmSync(doc.filePath!, { force: true });
+    console.log(chalk.gray(`  Migrated: ${taskId}`));
+  }
+
+  console.log('');
+  console.log(chalk.green(`Logs-to-ledger migration complete.`));
+  console.log(chalk.gray(`  Migrated to ledger:  ${migratedCount}`));
+  if (skippedCount > 0) {
+    console.log(chalk.gray(`  Skipped (in ledger): ${skippedCount}`));
+  }
+  if (conflictCount > 0) {
+    console.log(chalk.yellow(`  ID conflicts fixed:  ${conflictCount} board task(s) renamed`));
+  }
+  if (skippedCount > 0 && !options.force) {
+    console.log('');
+    console.log(chalk.gray('Tip: Use --force to also remove stale .md files that are already in the ledger.'));
+  }
+}
+
 function backupAndRemoveLegacyRoot(rootBrainfilePath: string, dotDir: string): string {
   const backupPath = uniquePath(path.join(dotDir, 'brainfile.root.legacy.bak'));
   fs.mkdirSync(dotDir, { recursive: true });