@bosun-sh/logbook 1.0.0 → 2.0.0

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

@@ -1,157 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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)
-  }
-}

package/src/mcp/error-codes.ts

@@ -1,213 +0,0 @@
-import { allowedTransitions } from "../domain/status-machine.js"
-import type { Status, TaskError } from "../domain/types.js"
-
-export interface McpError {
-  code: number
-  message: string
-  data: Record<string, unknown>
-}
-
-const NORMAL_FLOW = "backlog → todo → in_progress → pending_review → done"
-
-/**
- * Builds a declarative error message for transition_not_allowed errors.
- * Includes allowed transitions, review task hint, and corrective guidance.
- */
-const buildTransitionErrorMessage = (
-  from: Status,
-  to: Status,
-  taskId?: string
-): { message: string; data: Record<string, unknown> } => {
-  const isReviewTask = taskId?.startsWith("review-") ?? false
-  const allowed = allowedTransitions[from]
-
-  let message = `Status transition not allowed: cannot move from '${from}' to '${to}'.\n\n`
-  message += `Normal flow:\n  ${NORMAL_FLOW}\n\n`
-  message += `Allowed transitions from '${from}': ${allowed.join(", ") || "none"}\n\n`
-
-  message += "Special cases:\n"
-  message +=
-    "  - Review tasks (id starting with 'review-') can skip pending_review: in_progress → done\n"
-  message += "  - blocked tasks return to in_progress\n"
-  message += "  - need_info tasks return to in_progress\n"
-  message += "  - Tasks in pending_review can return to in_progress or proceed to done\n\n"
-
-  if (allowed.length === 0) {
-    message += "This status is terminal. No further transitions are possible."
-  } else {
-    message += `To proceed: transition to one of [${allowed.join(", ")}] first.`
-  }
-
-  const hint =
-    allowed.length === 0
-      ? "No further transitions possible from done."
-      : `Try transitioning to ${allowed[0]} first.`
-
-  return {
-    message,
-    data: {
-      from,
-      to,
-      taskId,
-      allowedFrom: Object.keys(allowedTransitions).filter((s) =>
-        allowedTransitions[s as Status].includes(from)
-      ),
-      allowedTo: allowed,
-      normalFlow: NORMAL_FLOW,
-      isReviewTask,
-      hint,
-    },
-  }
-}
-
-/**
- * Builds a declarative error message for missing_comment errors.
- */
-const buildMissingCommentMessage = (
-  from?: Status,
-  to?: Status
-): { message: string; data: Record<string, unknown> } => {
-  let message = "A comment is required for this transition.\n\n"
-
-  if (from && to) {
-    message += `Transition: ${from} → ${to} requires a comment.\n`
-    if (to === "need_info") {
-      message +=
-        "Reason: need_info status requires documentation of what information is needed.\n\n"
-    } else if (to === "blocked") {
-      message += "Reason: blocked status requires documentation of why the task is blocked.\n\n"
-    }
-  }
-
-  message += "Include a comment with non-empty content to proceed."
-
-  return {
-    message,
-    data: { from, to },
-  }
-}
-
-/**
- * Builds a declarative error message for validation_error messages.
- * Matches known raw messages and enhances them with context.
- */
-const buildValidationErrorMessage = (
-  rawMessage: string,
-  context?: Record<string, unknown>
-): { message: string; data: Record<string, unknown> } => {
-  // Concurrent in_progress guard
-  if (rawMessage === "moving a second task to in_progress requires a justification comment") {
-    const inProgressTasks = (context?.inProgressTasks as Array<{ id: string; title: string }>) ?? []
-    let message =
-      "Cannot move this task to in_progress: another task is already in_progress for this session.\n\n"
-
-    if (inProgressTasks.length > 0) {
-      message += "Current in_progress tasks for this session:\n"
-      for (const t of inProgressTasks) {
-        message += `  - ${t.title} (id: ${t.id})\n`
-      }
-      message += "\n"
-    }
-
-    message +=
-      "When moving a second task to in_progress, you must provide a justification comment\n"
-    message += "explaining why this task takes priority over the existing one.\n\n"
-    message += "Include a non-empty comment explaining the priority change."
-
-    return {
-      message,
-      data: { message: rawMessage, ...context },
-    }
-  }
-
-  // Reply on regular comment
-  if (rawMessage === "reply is only valid on need_info comments") {
-    const commentId = context?.commentId as string | undefined
-    const commentKind = context?.commentKind as string | undefined
-
-    let message = "Cannot reply to this comment.\n\n"
-    if (commentId) {
-      message += `Comment id: ${commentId}\n`
-    }
-    if (commentKind) {
-      message += `Comment kind: ${commentKind}\n`
-    }
-    message +=
-      "\nReplies are only allowed on 'need_info' comments. Regular comments cannot receive replies.\n\n"
-    message +=
-      "To proceed: either remove the reply field, or change the comment kind to 'need_info'."
-
-    return {
-      message,
-      data: { message: rawMessage, ...context },
-    }
-  }
-
-  // Blocking comment without reply
-  if (rawMessage.startsWith("blocking comment ") && rawMessage.endsWith(" has no reply")) {
-    const commentId = context?.commentId as string | undefined
-    const commentTitle = context?.commentTitle as string | undefined
-    const commentContent = context?.commentContent as string | undefined
-    const commentTimestamp = context?.commentTimestamp as Date | undefined
-
-    let message =
-      "Cannot transition from need_info to in_progress: blocking comment has no reply.\n\n"
-    message += "Blocking comment:\n"
-    if (commentId) message += `  - id: ${commentId}\n`
-    if (commentTitle) message += `  - title: ${commentTitle}\n`
-    if (commentContent) {
-      const truncated =
-        commentContent.length > 50 ? `${commentContent.slice(0, 50)}...` : commentContent
-      message += `  - content: ${truncated}\n`
-    }
-    if (commentTimestamp) message += `  - created: ${commentTimestamp.toISOString()}\n`
-    message += "\nYou must reply to this need_info comment before transitioning to in_progress.\n\n"
-    message += "Include a reply in your comment to proceed."
-
-    return {
-      message,
-      data: { message: rawMessage, ...context },
-    }
-  }
-
-  // Empty blocked content
-  if (rawMessage === "blocked requires a non-empty comment") {
-    let message = "Cannot transition to blocked with an empty comment.\n\n"
-    message += "When blocking a task, you must provide a reason in the comment content.\n\n"
-    message += "Include a non-empty comment explaining why the task is blocked."
-
-    return {
-      message,
-      data: { message: rawMessage, ...context },
-    }
-  }
-
-  // Fallback: pass through unknown validation errors
-  return {
-    message: rawMessage,
-    data: { message: rawMessage, ...context },
-  }
-}
-
-export const taskErrorToMcpError = (err: TaskError): McpError => {
-  switch (err._tag) {
-    case "not_found":
-      return { code: -32001, message: "Task not found", data: { taskId: err.taskId } }
-    case "transition_not_allowed": {
-      const { message, data } = buildTransitionErrorMessage(err.from, err.to, err.taskId)
-      return { code: -32002, message, data }
-    }
-    case "validation_error": {
-      const { message, data } = buildValidationErrorMessage(err.message, err.context)
-      return { code: -32003, message, data }
-    }
-    case "missing_comment": {
-      const { message, data } = buildMissingCommentMessage(err.from, err.to)
-      return { code: -32004, message, data }
-    }
-    case "conflict":
-      return { code: -32005, message: "Task already exists", data: { taskId: err.taskId } }
-    case "no_current_task":
-      return { code: -32006, message: "No current task for this session", data: {} }
-  }
-}