opencastle 0.27.0 → 0.27.2

package/src/cli/convoy/lock.ts

@@ -0,0 +1,103 @@
+import { hostname as getHostname } from 'node:os'
+import { DatabaseSync } from 'node:sqlite'
+
+export class EngineAlreadyRunningError extends Error {
+  constructor(public readonly pid: number, public readonly hostname: string) {
+    super(
+      `Another opencastle process (PID ${pid} on ${hostname}) is already running against this database.`,
+    )
+    this.name = 'EngineAlreadyRunningError'
+  }
+}
+
+type LockRow = { pid: number; hostname: string; last_heartbeat: string }
+
+function checkStaleness(row: LockRow): boolean {
+  const heartbeatAge = Date.now() - new Date(row.last_heartbeat).getTime()
+  if (heartbeatAge <= 30_000) return false
+  if (row.hostname !== getHostname()) return true
+  try {
+    process.kill(row.pid, 0)
+    return false // PID is alive on this host
+  } catch {
+    return true // PID is dead
+  }
+}
+
+export function isLockStale(db: DatabaseSync): boolean {
+  const row = db
+    .prepare('SELECT pid, hostname, last_heartbeat FROM engine_lock WHERE id = 1')
+    .get() as LockRow | undefined
+  if (!row) return true
+  return checkStaleness(row)
+}
+
+export function releaseEngineLock(db: DatabaseSync): void {
+  db.exec('DELETE FROM engine_lock WHERE id = 1')
+}
+
+export function acquireEngineLock(
+  db: DatabaseSync,
+  _dbPath: string,
+): {
+  release: () => void
+  startHeartbeat: () => NodeJS.Timeout
+} {
+  // BEGIN IMMEDIATE acquires a write lock upfront, preventing concurrent writers
+  try {
+    db.exec('BEGIN IMMEDIATE')
+  } catch (err) {
+    const msg = (err as Error).message ?? ''
+    if (msg.includes('SQLITE_BUSY') || msg.includes('database is locked')) {
+      throw new EngineAlreadyRunningError(0, 'unknown')
+    }
+    throw err
+  }
+
+  const existing = db
+    .prepare('SELECT pid, hostname, last_heartbeat FROM engine_lock WHERE id = 1')
+    .get() as LockRow | undefined
+
+  if (existing) {
+    const stale = checkStaleness(existing)
+    if (!stale) {
+      db.exec('ROLLBACK')
+      throw new EngineAlreadyRunningError(existing.pid, existing.hostname)
+    }
+  }
+
+  const now = new Date().toISOString()
+  db.prepare(
+    'INSERT OR REPLACE INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+  ).run(process.pid, getHostname(), now, now)
+  db.exec('COMMIT')
+
+  let heartbeatInterval: NodeJS.Timeout | undefined
+
+  function startHeartbeat(): NodeJS.Timeout {
+    heartbeatInterval = setInterval(() => {
+      try {
+        db.prepare('UPDATE engine_lock SET last_heartbeat = ? WHERE id = 1').run(
+          new Date().toISOString(),
+        )
+      } catch {
+        // Ignore errors — DB may have been closed
+      }
+    }, 10_000)
+    return heartbeatInterval
+  }
+
+  function release(): void {
+    if (heartbeatInterval !== undefined) {
+      clearInterval(heartbeatInterval)
+      heartbeatInterval = undefined
+    }
+    try {
+      db.exec('DELETE FROM engine_lock WHERE id = 1')
+    } catch {
+      // Ignore errors — DB may have been closed
+    }
+  }
+
+  return { release, startHeartbeat }
+}

package/src/cli/convoy/log-merge.test.ts

@@ -0,0 +1,179 @@
+import { mkdtempSync, rmSync, realpathSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mergeConvoyLogs } from '../log.js'
+
+const CONVOYS_REL = '.opencastle/logs/convoys'
+const OUTPUT_REL = '.opencastle/logs/convoy-events.ndjson'
+
+function makeBase(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), 'log-merge-test-')))
+  mkdirSync(join(dir, CONVOYS_REL), { recursive: true })
+  return dir
+}
+
+function writeConvoyFile(base: string, convoyId: string, records: object[]): void {
+  const path = join(base, CONVOYS_REL, `${convoyId}.ndjson`)
+  writeFileSync(path, records.map(r => JSON.stringify(r)).join('\n') + '\n', 'utf8')
+}
+
+let tmpDir: string
+
+beforeEach(() => {
+  tmpDir = makeBase()
+})
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+describe('mergeConvoyLogs', () => {
+  it('returns zeros when convoys directory is missing', async () => {
+    rmSync(join(tmpDir, '.opencastle'), { recursive: true, force: true })
+    const result = await mergeConvoyLogs({ basePath: tmpDir })
+    expect(result).toEqual({ merged: 0, deduplicated: 0, written: 0 })
+  })
+
+  it('returns zeros when convoys directory is empty', async () => {
+    const result = await mergeConvoyLogs({ basePath: tmpDir })
+    expect(result).toEqual({ merged: 0, deduplicated: 0, written: 0 })
+  })
+
+  it('merges records from 3 convoy files', async () => {
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 1, timestamp: '2026-01-01T10:00:00.000Z', type: 'task_started' },
+    ])
+    writeConvoyFile(tmpDir, 'convoy-b', [
+      { _event_id: 2, timestamp: '2026-01-02T10:00:00.000Z', type: 'task_done' },
+    ])
+    writeConvoyFile(tmpDir, 'convoy-c', [
+      { _event_id: 3, timestamp: '2026-01-03T10:00:00.000Z', type: 'session' },
+    ])
+
+    const result = await mergeConvoyLogs({ basePath: tmpDir })
+    expect(result.merged).toBe(3)
+    expect(result.written).toBe(3)
+  })
+
+  it('output is sorted by timestamp ascending', async () => {
+    writeConvoyFile(tmpDir, 'convoy-z', [
+      { _event_id: 10, timestamp: '2026-03-01T00:00:00.000Z', type: 'task_done' },
+      { _event_id: 11, timestamp: '2026-01-01T00:00:00.000Z', type: 'task_started' },
+    ])
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 12, timestamp: '2026-02-01T00:00:00.000Z', type: 'session' },
+    ])
+
+    const outputPath = join(tmpDir, 'merged.ndjson')
+    await mergeConvoyLogs({ basePath: tmpDir, output: outputPath })
+
+    const lines = readFileSync(outputPath, 'utf8').split('\n').filter(l => l.trim())
+    const timestamps = lines.map(l => (JSON.parse(l) as { timestamp: string }).timestamp)
+    expect(timestamps).toEqual([
+      '2026-01-01T00:00:00.000Z',
+      '2026-02-01T00:00:00.000Z',
+      '2026-03-01T00:00:00.000Z',
+    ])
+  })
+
+  it('deduplicates records by _event_id (keeps first occurrence)', async () => {
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 5, timestamp: '2026-01-01T00:00:00.000Z', type: 'task_started', note: 'first' },
+    ])
+    writeConvoyFile(tmpDir, 'convoy-b', [
+      { _event_id: 5, timestamp: '2026-01-01T00:00:00.000Z', type: 'task_started', note: 'duplicate' },
+      { _event_id: 6, timestamp: '2026-01-02T00:00:00.000Z', type: 'task_done' },
+    ])
+
+    const outputPath = join(tmpDir, 'merged.ndjson')
+    const result = await mergeConvoyLogs({ basePath: tmpDir, output: outputPath })
+
+    expect(result.merged).toBe(3)
+    expect(result.deduplicated).toBe(1)
+    expect(result.written).toBe(2)
+
+    const lines = readFileSync(outputPath, 'utf8').split('\n').filter(l => l.trim())
+    expect(lines).toHaveLength(2)
+    const first = JSON.parse(lines[0]) as { note: string }
+    expect(first.note).toBe('first')
+  })
+
+  it('filters by --since (inclusive)', async () => {
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 1, timestamp: '2026-01-01T00:00:00.000Z', type: 'session' },
+      { _event_id: 2, timestamp: '2026-02-01T00:00:00.000Z', type: 'session' },
+      { _event_id: 3, timestamp: '2026-03-01T00:00:00.000Z', type: 'session' },
+    ])
+
+    const outputPath = join(tmpDir, 'merged.ndjson')
+    const result = await mergeConvoyLogs({ basePath: tmpDir, since: '2026-02-01T00:00:00.000Z', output: outputPath })
+
+    expect(result.written).toBe(2)
+    const lines = readFileSync(outputPath, 'utf8').split('\n').filter(l => l.trim())
+    expect(lines).toHaveLength(2)
+  })
+
+  it('filters by --until (inclusive)', async () => {
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 1, timestamp: '2026-01-01T00:00:00.000Z', type: 'session' },
+      { _event_id: 2, timestamp: '2026-02-01T00:00:00.000Z', type: 'session' },
+      { _event_id: 3, timestamp: '2026-03-01T00:00:00.000Z', type: 'session' },
+    ])
+
+    const outputPath = join(tmpDir, 'merged.ndjson')
+    const result = await mergeConvoyLogs({ basePath: tmpDir, until: '2026-02-01T00:00:00.000Z', output: outputPath })
+
+    expect(result.written).toBe(2)
+  })
+
+  it('filters by --since and --until together', async () => {
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 1, timestamp: '2026-01-01T00:00:00.000Z', type: 'session' },
+      { _event_id: 2, timestamp: '2026-02-15T00:00:00.000Z', type: 'session' },
+      { _event_id: 3, timestamp: '2026-03-01T00:00:00.000Z', type: 'session' },
+    ])
+
+    const outputPath = join(tmpDir, 'merged.ndjson')
+    const result = await mergeConvoyLogs({
+      basePath: tmpDir,
+      since: '2026-02-01T00:00:00.000Z',
+      until: '2026-02-28T23:59:59.999Z',
+      output: outputPath,
+    })
+
+    expect(result.written).toBe(1)
+    const lines = readFileSync(outputPath, 'utf8').split('\n').filter(l => l.trim())
+    const record = JSON.parse(lines[0]) as { timestamp: string }
+    expect(record.timestamp).toBe('2026-02-15T00:00:00.000Z')
+  })
+
+  it('writes to default output path when --output not specified', async () => {
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 1, timestamp: '2026-01-01T00:00:00.000Z', type: 'session' },
+    ])
+
+    await mergeConvoyLogs({ basePath: tmpDir })
+
+    const defaultPath = join(tmpDir, '.opencastle', 'logs', 'convoy-events.ndjson')
+    expect(existsSync(defaultPath)).toBe(true)
+  })
+
+  it('returns written: 0 when all records filtered out', async () => {
+    writeConvoyFile(tmpDir, 'convoy-a', [
+      { _event_id: 1, timestamp: '2026-01-01T00:00:00.000Z', type: 'session' },
+    ])
+
+    const result = await mergeConvoyLogs({ basePath: tmpDir, since: '2027-01-01T00:00:00.000Z' })
+    expect(result.written).toBe(0)
+    expect(result.merged).toBe(1)
+  })
+
+  it('skips malformed JSON lines gracefully', async () => {
+    const path = join(tmpDir, CONVOYS_REL, 'convoy-bad.ndjson')
+    writeFileSync(path, '{"_event_id":1,"timestamp":"2026-01-01T00:00:00.000Z","type":"session"}\nnot-valid-json\n{"_event_id":2,"timestamp":"2026-01-02T00:00:00.000Z","type":"task_done"}\n', 'utf8')
+
+    const result = await mergeConvoyLogs({ basePath: tmpDir })
+    expect(result.written).toBe(2)
+  })
+})

package/src/cli/convoy/merge.test.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { execFile as execFileCb } from 'node:child_process'
 import { promisify } from 'node:util'
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { createMergeQueue } from './merge.js'
+import { createMergeQueue, MergeConflictError } from './merge.js'
 import type { MergeQueue } from './merge.js'
 
 const execFile = promisify(execFileCb)
@@ -103,7 +103,7 @@ describe('merge - no changes', () => {
 // ── merge conflict ────────────────────────────────────────────────────────────
 
 describe('merge - conflict', () => {
-  it('returns conflicted: true and aborts when two worktrees edit the same file', async () => {
+  it('throws MergeConflictError and aborts when two worktrees edit the same file', async () => {
     const worktree1 = await addWorktree(repoPath, 'worker1', featureBranch)
     const worktree2 = await addWorktree(repoPath, 'worker2', featureBranch)
 
@@ -113,10 +113,8 @@ describe('merge - conflict', () => {
     const first = await queue.merge(worktree1, 'convoy-worker1', featureBranch)
     expect(first).toEqual({ success: true, conflicted: false, message: 'Merged successfully' })
 
-    const second = await queue.merge(worktree2, 'convoy-worker2', featureBranch)
-    expect(second.success).toBe(false)
-    expect(second.conflicted).toBe(true)
-    expect(second.message).toContain('conflict')
+    await expect(queue.merge(worktree2, 'convoy-worker2', featureBranch))
+      .rejects.toThrow(MergeConflictError)
   })
 
   it('leaves the repo in a clean state (no pending merge) after aborting a conflict', async () => {
@@ -127,7 +125,8 @@ describe('merge - conflict', () => {
     writeFileSync(join(worktree2, 'shared.txt'), 'content from worker 2')
 
     await queue.merge(worktree1, 'convoy-worker1', featureBranch)
-    await queue.merge(worktree2, 'convoy-worker2', featureBranch)
+    await expect(queue.merge(worktree2, 'convoy-worker2', featureBranch))
+      .rejects.toBeInstanceOf(MergeConflictError)
 
     // --untracked-files=no excludes the .opencastle/worktrees/ dir from the check;
     // we only want to verify there is no pending merge (no staged/modified tracked files).

package/src/cli/convoy/merge.ts

@@ -10,6 +10,16 @@ export interface MergeResult {
   message: string
 }
 
+export class MergeConflictError extends Error {
+  constructor(
+    public readonly conflictingFiles: string[],
+    message?: string,
+  ) {
+    super(message ?? `Merge conflict in: ${conflictingFiles.join(', ')}`)
+    this.name = 'MergeConflictError'
+  }
+}
+
 export interface MergeQueue {
   /**
    * Merge a single worktree's changes back onto the target branch.
@@ -78,8 +88,16 @@ export function createMergeQueue(repoPath: string): MergeQueue {
         error.code === 1 &&
         ((error.stderr ?? '').includes('CONFLICT') || (error.stdout ?? '').includes('CONFLICT'))
       if (isConflict) {
+        // Collect conflicting files before aborting
+        let conflictingFiles: string[] = []
+        try {
+          const { stdout: conflictOut } = await execFile('git', [
+            '-C', repoPath, 'diff', '--name-only', '--diff-filter=U',
+          ])
+          conflictingFiles = conflictOut.split('\n').filter(Boolean)
+        } catch { /* ignore — we still abort */ }
         await execFile('git', ['-C', repoPath, 'merge', '--abort'])
-        return { success: false, conflicted: true, message: 'Merge conflict detected; merge aborted' }
+        throw new MergeConflictError(conflictingFiles)
       }
       throw err
     }