@bosun-sh/logbook 1.0.0

package/src/domain/fibonacci.ts

@@ -0,0 +1,39 @@
+import { Effect } from "effect"
+import type { TaskError } from "./types.js"
+
+/**
+ * Validates that n is a positive Fibonacci number.
+ * Returns Effect.succeed(void) when valid,
+ * Effect.fail({ _tag: 'validation_error', message: 'estimation must be a Fibonacci number' }) otherwise.
+ *
+ * Algorithm: n is Fibonacci iff one of 5n²+4 or 5n²-4 is a perfect square.
+ */
+export const validateFibonacci = (n: number): Effect.Effect<void, TaskError> => {
+  // Must be a positive integer
+  if (!Number.isInteger(n) || n <= 0) {
+    return Effect.fail({
+      _tag: "validation_error",
+      message: "estimation must be a Fibonacci number",
+    })
+  }
+
+  // Check if a number is a perfect square
+  const isPerfectSquare = (num: number): boolean => {
+    if (num < 0) return false
+    const sqrt = Math.sqrt(num)
+    return sqrt === Math.floor(sqrt)
+  }
+
+  // n is Fibonacci iff 5n²+4 or 5n²-4 is a perfect square
+  const fiveSqPlusFour = 5 * n * n + 4
+  const fiveSqMinusFour = 5 * n * n - 4
+
+  if (isPerfectSquare(fiveSqPlusFour) || isPerfectSquare(fiveSqMinusFour)) {
+    return Effect.succeed(void 0)
+  }
+
+  return Effect.fail({
+    _tag: "validation_error",
+    message: "estimation must be a Fibonacci number",
+  })
+}

package/src/domain/kTokens.ts

@@ -0,0 +1,65 @@
+import { Effect } from "effect"
+import type { TaskError } from "./types.js"
+
+export interface KTokensConfig {
+  anchorPoint: number // Fibonacci number to anchor against
+  kTokensAtAnchor: number // how many kTokens map to anchorPoint
+  maxKTokens: number // cap (inclusive)
+}
+
+export const defaultConfig: KTokensConfig = {
+  anchorPoint: 8,
+  kTokensAtAnchor: 20,
+  maxKTokens: 20,
+}
+
+// Fibonacci sequence for lookup
+const FIBONACCI = [1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144]
+
+export const estimateFromKTokens = (
+  kTokens: number,
+  config: KTokensConfig = defaultConfig
+): Effect.Effect<number, TaskError> => {
+  // Fail if kTokens <= 0
+  if (kTokens <= 0) {
+    return Effect.fail({
+      _tag: "validation_error",
+      message: "predicted kilotokens must be positive",
+    })
+  }
+
+  // Fail if kTokens > config.maxKTokens
+  if (kTokens > config.maxKTokens) {
+    return Effect.fail({
+      _tag: "validation_error",
+      message: "predicted kilotokens exceed maximum allowed",
+    })
+  }
+
+  // Calculate ratio: kTokensAtAnchor / anchorPoint
+  const ratio = config.kTokensAtAnchor / config.anchorPoint
+
+  // Scale kTokens to estimate space
+  const scaled = kTokens / ratio
+
+  // Find nearest Fibonacci number, rounding UP on tie
+  let nearestFib: number = FIBONACCI[0] ?? 1
+  let minDistance = Math.abs(nearestFib - scaled)
+
+  for (const fib of FIBONACCI) {
+    const distance = Math.abs(fib - scaled)
+
+    // On exact match, return immediately
+    if (distance === 0) {
+      return Effect.succeed(fib)
+    }
+
+    // On tie, pick the larger value (UP)
+    if (distance < minDistance || (distance === minDistance && fib > nearestFib)) {
+      nearestFib = fib
+      minDistance = distance
+    }
+  }
+
+  return Effect.succeed(nearestFib)
+}

package/src/domain/status-machine.ts

@@ -0,0 +1,49 @@
+import { Effect } from "effect"
+import type { Status, TaskError } from "./types.js"
+
+// Allowed state transitions: from → [to, to, ...]
+export const allowedTransitions: Record<Status, Status[]> = {
+  backlog: ["todo"],
+  todo: ["backlog", "in_progress"],
+  in_progress: ["todo", "pending_review", "need_info", "blocked"],
+  blocked: ["in_progress"],
+  need_info: ["in_progress"],
+  pending_review: ["done", "in_progress"],
+  done: [],
+}
+
+/**
+ * Guards a status transition, returning Effect.succeed(void) when allowed
+ * and Effect.fail({ _tag: 'transition_not_allowed', from, to }) otherwise.
+ * A same→same transition is always a no-op success.
+ * Review tasks (id starts with "review-") may go directly from in_progress to done.
+ */
+export const guardTransition = (
+  from: Status,
+  to: Status,
+  taskId?: string
+): Effect.Effect<void, TaskError> => {
+  // Same→same is always a no-op success
+  if (from === to) {
+    return Effect.void
+  }
+
+  // Check if transition is in the allowed map
+  const allowed = allowedTransitions[from]
+  if (allowed.includes(to)) {
+    return Effect.void
+  }
+
+  // Review tasks may skip pending_review and go directly to done
+  if (from === "in_progress" && to === "done" && taskId?.startsWith("review-")) {
+    return Effect.void
+  }
+
+  // Transition not allowed
+  return Effect.fail({
+    _tag: "transition_not_allowed",
+    from,
+    to,
+    taskId,
+  } as TaskError)
+}

package/src/domain/types.ts

@@ -0,0 +1,66 @@
+import { z } from "zod"
+
+export const StatusSchema = z.enum([
+  "backlog",
+  "todo",
+  "need_info",
+  "blocked",
+  "in_progress",
+  "pending_review",
+  "done",
+])
+export type Status = z.infer<typeof StatusSchema>
+
+export const CommentKindSchema = z.enum(["need_info", "regular"])
+export type CommentKind = z.infer<typeof CommentKindSchema>
+
+export const CommentSchema = z.object({
+  id: z.string().min(1),
+  timestamp: z.coerce.date(),
+  title: z.string().min(1),
+  content: z.string(),
+  reply: z.string(),
+  kind: CommentKindSchema,
+})
+export type Comment = z.infer<typeof CommentSchema>
+
+export const AgentSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string(),
+})
+export type Agent = z.infer<typeof AgentSchema>
+
+export const TaskSchema = z.object({
+  project: z.string().min(1),
+  milestone: z.string().min(1),
+  id: z.string().min(1),
+  title: z.string().min(1),
+  definition_of_done: z.string().min(1),
+  description: z.string().min(1),
+  estimation: z.number().int().positive(),
+  comments: z.array(CommentSchema),
+  assignee: AgentSchema.optional(),
+  status: StatusSchema,
+  in_progress_since: z.coerce.date().optional(),
+  priority: z.number().int().min(0).default(0),
+})
+export type Task = z.infer<typeof TaskSchema>
+
+// Error tags match Gherkin feature file error names
+export type TaskError =
+  | { readonly _tag: "not_found"; readonly taskId: string }
+  | {
+      readonly _tag: "transition_not_allowed"
+      readonly from: Status
+      readonly to: Status
+      readonly taskId?: string
+    }
+  | {
+      readonly _tag: "validation_error"
+      readonly message: string
+      readonly context?: Record<string, unknown>
+    }
+  | { readonly _tag: "missing_comment"; readonly from?: Status; readonly to?: Status }
+  | { readonly _tag: "conflict"; readonly taskId: string }
+  | { readonly _tag: "no_current_task" }

package/src/hook/hook-executor.ts

@@ -0,0 +1,70 @@
+import { Effect } from "effect"
+import type { HookEvent } from "./ports.js"
+
+export interface HookConfig {
+  event: string
+  condition?: string
+  timeout_ms?: number
+  script: string
+}
+
+const HOOK_EVENT_NAME = "task.status_changed"
+const DEFAULT_TIMEOUT_MS = 5000
+
+const evaluateCondition = (condition: string, event: HookEvent): boolean => {
+  try {
+    const fn = new Function(
+      "new_status",
+      "old_status",
+      "task_id",
+      "session_id",
+      `return (${condition})`
+    )
+    return Boolean(fn(event.new_status, event.old_status, event.task_id, event.session_id))
+  } catch {
+    return false
+  }
+}
+
+const runScript = (config: HookConfig, event: HookEvent): Promise<void> =>
+  new Promise((resolve) => {
+    const timeoutMs = config.timeout_ms ?? DEFAULT_TIMEOUT_MS
+
+    const cmd = config.script.endsWith(".ts") ? ["bun", config.script] : ["sh", "-c", config.script]
+
+    const child = Bun.spawn(cmd, {
+      env: {
+        ...process.env,
+        LOGBOOK_TASK_ID: event.task_id,
+        LOGBOOK_OLD_STATUS: event.old_status,
+        LOGBOOK_NEW_STATUS: event.new_status,
+        LOGBOOK_SESSION_ID: event.session_id,
+      },
+    })
+
+    const timer = setTimeout(() => {
+      child.kill()
+    }, timeoutMs)
+
+    void (async () => {
+      try {
+        await child.exited
+      } finally {
+        clearTimeout(timer)
+        resolve()
+      }
+    })()
+  })
+
+export const executeHooks = (
+  event: HookEvent,
+  configs: readonly HookConfig[]
+): Effect.Effect<void, never> =>
+  Effect.promise(async () => {
+    await Promise.all(
+      configs
+        .filter((c) => c.event === HOOK_EVENT_NAME)
+        .filter((c) => !c.condition || evaluateCondition(c.condition, event))
+        .map((c) => runScript(c, event))
+    )
+  })

package/src/hook/ports.ts

@@ -0,0 +1,16 @@
+import { Context, type Effect } from "effect"
+import type { Comment, Status } from "../domain/types.js"
+
+export interface HookEvent {
+  task_id: string
+  old_status: Status
+  new_status: Status
+  comment: Comment | null
+  session_id: string
+}
+
+export interface HookRunner {
+  run(event: HookEvent): Effect.Effect<void, never>
+}
+
+export const HookRunner = Context.GenericTag<HookRunner>("HookRunner")

package/src/infra/hook-config-loader.ts

@@ -0,0 +1,111 @@
+import { readdir, readFile } from "node:fs/promises"
+import { join } from "node:path"
+import { z } from "zod"
+import type { HookConfig } from "../hook/hook-executor.js"
+import { logger } from "./logger.js"
+
+const KNOWN_KEYS = ["event", "condition", "timeout_ms"] as const
+
+const HookConfigFileSchema = z.object({
+  event: z.string(),
+  condition: z.string().optional(),
+  timeout_ms: z.number().optional(),
+})
+
+/**
+ * Parses a strict subset of YAML: flat key-value pairs, no nesting.
+ * Supports quoted strings and bare integers.
+ */
+const parseSimpleYaml = (content: string): Record<string, unknown> => {
+  const result: Record<string, unknown> = {}
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith("#")) continue
+    const colonIdx = trimmed.indexOf(":")
+    if (colonIdx === -1) continue
+    const key = trimmed.slice(0, colonIdx).trim()
+    let value: unknown = trimmed.slice(colonIdx + 1).trim()
+    if (typeof value === "string" && value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1)
+    } else if (typeof value === "string" && value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1)
+    } else if (typeof value === "string" && /^\d+$/.test(value)) {
+      value = parseInt(value, 10)
+    }
+    result[key] = value
+  }
+  return result
+}
+
+const SCRIPT_CANDIDATES = ["script.ts", "script.sh"] as const
+
+const findScript = async (hookDir: string): Promise<string | undefined> => {
+  for (const name of SCRIPT_CANDIDATES) {
+    const candidate = join(hookDir, name)
+    try {
+      await readFile(candidate)
+      return candidate
+    } catch {
+      // try next candidate
+    }
+  }
+  return undefined
+}
+
+export const loadHookConfigs = async (hooksDir: string): Promise<HookConfig[]> => {
+  let entries: string[]
+  try {
+    entries = await readdir(hooksDir)
+  } catch (e: unknown) {
+    if (isEnoent(e)) return []
+    throw e
+  }
+
+  const configs: HookConfig[] = []
+
+  for (const entry of entries) {
+    const hookDir = join(hooksDir, entry)
+    try {
+      const configPath = join(hookDir, "config.yml")
+      const raw = await readFile(configPath, "utf8")
+      const parsed = parseSimpleYaml(raw)
+      const validated = HookConfigFileSchema.safeParse(parsed)
+      if (!validated.success) {
+        logger.warn("invalid hook config", { path: configPath, error: validated.error.message })
+        continue
+      }
+      // Warn on unrecognized keys
+      const parsedKeys = Object.keys(parsed)
+      for (const key of parsedKeys) {
+        if (!(KNOWN_KEYS as readonly string[]).includes(key)) {
+          const validKeysStr = KNOWN_KEYS.join(", ")
+          logger.warn("unrecognized key in hook config", {
+            hook: entry,
+            key,
+            validKeys: validKeysStr,
+          })
+        }
+      }
+      const script = await findScript(hookDir)
+      if (script === undefined) {
+        logger.warn("no script found in hook dir, skipping", { path: hookDir })
+        continue
+      }
+      const { event, condition, timeout_ms } = validated.data
+      const config: HookConfig = {
+        event,
+        script,
+        ...(condition !== undefined ? { condition } : {}),
+        ...(timeout_ms !== undefined ? { timeout_ms } : {}),
+      }
+      configs.push(config)
+    } catch (e: unknown) {
+      logger.warn("failed to load hook", { hook: entry, error: String(e) })
+    }
+  }
+
+  return configs
+}
+
+const isEnoent = (e: unknown): boolean =>
+  typeof e === "object" && e !== null && (e as { code?: unknown }).code === "ENOENT"

package/src/infra/jsonl-task-repository.ts

@@ -0,0 +1,157 @@
+import { appendFile, readFile, rename, writeFile } from "node:fs/promises"
+import { Effect } from "effect"
+import type { Status, Task, TaskError } from "../domain/types.js"
+import { TaskSchema } from "../domain/types.js"
+import type { TaskRepository } from "../task/ports.js"
+import { logger } from "./logger.js"
+
+/**
+ * JSONL-backed TaskRepository.
+ * Each line is a JSON-serialized Task.
+ * Reads scan the full file; writes are append-only for save, full-rewrite for update.
+ */
+export class JsonlTaskRepository implements TaskRepository {
+  constructor(private readonly filePath: string) {}
+
+  save(task: Task): Effect.Effect<void, TaskError> {
+    return Effect.tryPromise<void, TaskError>({
+      try: async () => {
+        const content = await readFile(this.filePath, "utf8").catch((e: unknown) => {
+          if (isEnoent(e)) return ""
+          throw e
+        })
+        const lines = splitLines(content)
+        const conflict = lines.some((line) => {
+          try {
+            const parsed = JSON.parse(line) as unknown
+            return (parsed as { id?: unknown }).id === task.id
+          } catch {
+            return false
+          }
+        })
+        if (conflict) {
+          throw mkTagged<TaskError>({ _tag: "conflict", taskId: task.id })
+        }
+        await appendFile(this.filePath, `${JSON.stringify(task)}\n`, "utf8")
+      },
+      catch: (e) => asTaskError(e, task.id),
+    })
+  }
+
+  update(task: Task): Effect.Effect<void, TaskError> {
+    return Effect.tryPromise<void, TaskError>({
+      try: async () => {
+        const content = await readFile(this.filePath, "utf8").catch((e: unknown) => {
+          if (isEnoent(e)) return ""
+          throw e
+        })
+        const lines = splitLines(content)
+        let found = false
+        const updated = lines.map((line) => {
+          try {
+            const parsed = JSON.parse(line) as unknown
+            if ((parsed as { id?: unknown }).id === task.id) {
+              found = true
+              return JSON.stringify(task)
+            }
+          } catch {
+            // keep malformed lines as-is
+          }
+          return line
+        })
+        if (!found) {
+          throw mkTagged<TaskError>({ _tag: "not_found", taskId: task.id })
+        }
+        const tmpPath = `${this.filePath}.tmp`
+        await writeFile(tmpPath, `${updated.join("\n")}\n`, "utf8")
+        await rename(tmpPath, this.filePath)
+      },
+      catch: (e) => asTaskError(e, task.id),
+    })
+  }
+
+  findById(id: string): Effect.Effect<Task, TaskError> {
+    return Effect.tryPromise<Task, TaskError>({
+      try: async () => {
+        const content = await readFile(this.filePath, "utf8").catch((e: unknown) => {
+          if (isEnoent(e)) return ""
+          throw e
+        })
+        const lines = splitLines(content)
+        for (const line of lines) {
+          const result = parseLine(line)
+          if (result._tag === "error") {
+            logger.warn("skipping malformed JSONL line", { line, reason: result.reason })
+            continue
+          }
+          if (result.task.id === id) return result.task
+        }
+        throw mkTagged<TaskError>({ _tag: "not_found", taskId: id })
+      },
+      catch: (e) => asTaskError(e, id),
+    })
+  }
+
+  findByStatus(status: Status | "*"): Effect.Effect<readonly Task[], TaskError> {
+    return Effect.tryPromise<readonly Task[], TaskError>({
+      try: async () => {
+        const content = await readFile(this.filePath, "utf8").catch((e: unknown) => {
+          if (isEnoent(e)) return ""
+          throw e
+        })
+        const lines = splitLines(content)
+        const tasks: Task[] = []
+        for (const line of lines) {
+          const result = parseLine(line)
+          if (result._tag === "error") {
+            throw mkTagged<TaskError>({ _tag: "validation_error", message: result.reason })
+          }
+          if (status === "*" || result.task.status === status) {
+            tasks.push(result.task)
+          }
+        }
+        return tasks
+      },
+      catch: (e) => asTaskError(e, ""),
+    })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (pure)
+// ---------------------------------------------------------------------------
+
+type ParseResult =
+  | { readonly _tag: "ok"; readonly task: Task }
+  | { readonly _tag: "error"; readonly reason: string }
+
+const parseLine = (line: string): ParseResult => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch (e) {
+    return { _tag: "error", reason: `invalid JSON: ${String(e)}` }
+  }
+  const result = TaskSchema.safeParse(raw)
+  if (!result.success) {
+    return { _tag: "error", reason: result.error.message }
+  }
+  return { _tag: "ok", task: result.data }
+}
+
+const splitLines = (content: string): readonly string[] =>
+  content.split("\n").filter((l) => l.trim() !== "")
+
+const isEnoent = (e: unknown): boolean =>
+  typeof e === "object" && e !== null && (e as { code?: unknown }).code === "ENOENT"
+
+/** Carries a typed TaskError through the tryPromise boundary. */
+const mkTagged = <E>(value: E): E => value
+
+const asTaskError = (e: unknown, _taskId: string): TaskError => {
+  if (isTaskError(e)) return e
+  return { _tag: "validation_error", message: String(e) } satisfies TaskError
+}
+
+const isTaskError = (e: unknown): e is TaskError =>
+  typeof e === "object" && e !== null && typeof (e as { _tag?: unknown })._tag === "string"

package/src/infra/logger.ts

@@ -0,0 +1,40 @@
+type Level = "debug" | "info" | "warn" | "error"
+type LogContext = Record<string, unknown>
+
+interface Logger {
+  debug(msg: string, ctx?: LogContext): void
+  info(msg: string, ctx?: LogContext): void
+  warn(msg: string, ctx?: LogContext): void
+  error(msg: string, ctx?: LogContext): void
+}
+
+const LEVEL_ORDER: readonly Level[] = ["debug", "info", "warn", "error"]
+
+const levelIndex = (level: Level): number => LEVEL_ORDER.indexOf(level)
+
+const makeLogger = (threshold: Level): Logger => {
+  const thresholdIdx = levelIndex(threshold)
+
+  const log = (level: Level, msg: string, ctx?: LogContext): void => {
+    if (levelIndex(level) < thresholdIdx) return
+    const entry = { level, ts: new Date().toISOString(), msg, ...ctx }
+    process.stderr.write(`${JSON.stringify(entry)}\n`)
+  }
+
+  return {
+    debug: (msg, ctx) => log("debug", msg, ctx),
+    info: (msg, ctx) => log("info", msg, ctx),
+    warn: (msg, ctx) => log("warn", msg, ctx),
+    error: (msg, ctx) => log("error", msg, ctx),
+  }
+}
+
+const resolveThreshold = (): Level => {
+  const raw = process.env.LOGBOOK_LOG_LEVEL?.toLowerCase()
+  if (raw !== undefined && (LEVEL_ORDER as readonly string[]).includes(raw)) {
+    return raw as Level
+  }
+  return "warn"
+}
+
+export const logger: Logger = makeLogger(resolveThreshold())

package/src/infra/pid-session-registry.ts

@@ -0,0 +1,67 @@
+import { readFile, writeFile } from "node:fs/promises"
+import * as path from "node:path"
+import { Effect } from "effect"
+import type { SessionRegistry } from "../task/session-registry.js"
+
+type SessionMap = Record<string, number>
+
+/**
+ * PID-based session registry persisted to sessions.json alongside the tasks file.
+ *
+ * Liveness is checked via `process.kill(pid, 0)`: throws if the PID is dead, succeeds otherwise.
+ * A missing entry (clean deregistration) is also considered dead.
+ */
+export class PidSessionRegistry implements SessionRegistry {
+  private readonly sessionsFile: string
+
+  constructor(tasksFile: string) {
+    this.sessionsFile = path.join(path.dirname(tasksFile), "sessions.json")
+  }
+
+  isAlive(sessionId: string): Effect.Effect<boolean, never> {
+    return Effect.promise(async () => {
+      const map = await this.readMap()
+      const pid = map[sessionId]
+      if (pid === undefined) return false
+      try {
+        process.kill(pid, 0)
+        return true
+      } catch {
+        // Dead PID — lazily remove to keep the file tidy
+        await this.removeEntry(sessionId)
+        return false
+      }
+    })
+  }
+
+  register(sessionId: string, pid: number): Effect.Effect<void, never> {
+    return Effect.promise(async () => {
+      const map = await this.readMap()
+      map[sessionId] = pid
+      await this.writeMap(map)
+    })
+  }
+
+  deregister(sessionId: string): Effect.Effect<void, never> {
+    return Effect.promise(() => this.removeEntry(sessionId))
+  }
+
+  private async readMap(): Promise<SessionMap> {
+    try {
+      const raw = await readFile(this.sessionsFile, "utf8")
+      return JSON.parse(raw) as SessionMap
+    } catch {
+      return {}
+    }
+  }
+
+  private async writeMap(map: SessionMap): Promise<void> {
+    await writeFile(this.sessionsFile, JSON.stringify(map), "utf8")
+  }
+
+  private async removeEntry(sessionId: string): Promise<void> {
+    const map = await this.readMap()
+    delete map[sessionId]
+    await this.writeMap(map)
+  }
+}