logbook-mcp 0.2.0

package/src/task/create-task.ts

@@ -0,0 +1,71 @@
+import { Effect } from "effect"
+import { estimateFromKTokens } from "../domain/kTokens.js"
+import type { Task, TaskError } from "../domain/types.js"
+import { TaskRepository } from "./ports.js"
+
+export interface CreateTaskInput {
+  project: string
+  milestone: string
+  title: string
+  definition_of_done: string
+  description: string
+  predictedKTokens: number
+}
+
+/**
+ * Creates a new task in `backlog` status assigned to `sessionId`.
+ * Validates all fields and derives a Fibonacci estimation from predictedKTokens.
+ */
+export const createTask = (
+  input: CreateTaskInput,
+  sessionId: string
+): Effect.Effect<Task, TaskError, TaskRepository> => {
+  // Validate required string fields
+  const requiredStringFields: Array<keyof CreateTaskInput> = [
+    "project",
+    "milestone",
+    "title",
+    "definition_of_done",
+    "description",
+  ]
+
+  for (const field of requiredStringFields) {
+    if (typeof input[field] !== "string" || input[field] === "") {
+      return Effect.fail({
+        _tag: "validation_error" as const,
+        message: `${field} is required`,
+      })
+    }
+  }
+
+  // Validate predictedKTokens is defined and a number
+  if (input.predictedKTokens === undefined || input.predictedKTokens === null) {
+    return Effect.fail({
+      _tag: "validation_error" as const,
+      message: "predictedKTokens is required",
+    })
+  }
+
+  // Derive Fibonacci estimation from kTokens
+  return Effect.flatMap(estimateFromKTokens(input.predictedKTokens), (estimation) => {
+    const id = crypto.randomUUID()
+    const task: Task = {
+      project: input.project,
+      milestone: input.milestone,
+      id,
+      title: input.title,
+      definition_of_done: input.definition_of_done,
+      description: input.description,
+      estimation,
+      comments: [],
+      assignee: {
+        id: sessionId,
+        title: "Agent",
+        description: "",
+      },
+      status: "backlog" as const,
+    }
+
+    return Effect.flatMap(TaskRepository, (repo) => repo.save(task)).pipe(Effect.map(() => task))
+  })
+}

package/src/task/current-task.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect"
+import type { Task, TaskError } from "../domain/types.js"
+import { TaskRepository } from "./ports.js"
+
+/**
+ * Returns the oldest in_progress task assigned to the given session (FIFO by in_progress_since).
+ * Fails with `no_current_task` when the session has no in_progress tasks.
+ */
+export const currentTask = (sessionId: string): Effect.Effect<Task, TaskError, TaskRepository> =>
+  Effect.flatMap(TaskRepository, (repo) =>
+    Effect.flatMap(repo.findByStatus("in_progress"), (tasks) => {
+      const assignedTasks = tasks.filter((t) => t.assignee.id === sessionId)
+      const sorted = [...assignedTasks].sort((a, b) => {
+        // Tasks without in_progress_since go last
+        const aTime = a.in_progress_since?.getTime() ?? Infinity
+        const bTime = b.in_progress_since?.getTime() ?? Infinity
+        return aTime - bTime
+      })
+      const first = sorted[0]
+      return first !== undefined
+        ? Effect.succeed(first)
+        : Effect.fail({ _tag: "no_current_task" as const })
+    })
+  )

package/src/task/edit-task.ts

@@ -0,0 +1,58 @@
+import { Effect } from "effect"
+import { estimateFromKTokens } from "../domain/kTokens.js"
+import type { Task, TaskError } from "../domain/types.js"
+import { TaskRepository } from "./ports.js"
+
+export interface EditTaskInput {
+  title?: string
+  description?: string
+  definition_of_done?: string
+  predictedKTokens?: number
+}
+
+/**
+ * Edits mutable fields of an existing task without changing its status.
+ * Derives Fibonacci estimation from predictedKTokens when provided.
+ * Fails with `not_found` for unknown id.
+ * Fails with `validation_error` when a `status` field is attempted via EditTaskInput.
+ */
+export const editTask = (
+  id: string,
+  updates: EditTaskInput
+): Effect.Effect<Task, TaskError, TaskRepository> => {
+  // Check for attempted status modification (runtime guard against type system bypass)
+  if ("status" in updates) {
+    return Effect.fail({
+      _tag: "validation_error" as const,
+      message: "status field cannot be edited",
+    })
+  }
+
+  // Derive estimation from predictedKTokens if present
+  if (updates.predictedKTokens !== undefined) {
+    return Effect.flatMap(estimateFromKTokens(updates.predictedKTokens), (estimation) =>
+      Effect.flatMap(TaskRepository, (repo) =>
+        Effect.flatMap(repo.findById(id), (task) => {
+          const { predictedKTokens: _, ...rest } = updates
+          const updatedTask: Task = {
+            ...task,
+            ...rest,
+            estimation,
+          }
+          return Effect.flatMap(repo.update(updatedTask), () => Effect.succeed(updatedTask))
+        })
+      )
+    )
+  }
+
+  // No estimation to derive, proceed directly with find and update
+  return Effect.flatMap(TaskRepository, (repo) =>
+    Effect.flatMap(repo.findById(id), (task) => {
+      const updatedTask: Task = {
+        ...task,
+        ...updates,
+      }
+      return Effect.flatMap(repo.update(updatedTask), () => Effect.succeed(updatedTask))
+    })
+  )
+}

package/src/task/list-tasks.ts

@@ -0,0 +1,12 @@
+import { Effect } from "effect"
+import type { Status, Task, TaskError } from "../domain/types.js"
+import { TaskRepository } from "./ports.js"
+
+/**
+ * Returns tasks matching the given status, or all tasks when status is '*'.
+ * Fails with `validation_error` when the underlying data is malformed.
+ */
+export const listTasks = (
+  status: Status | "*"
+): Effect.Effect<readonly Task[], TaskError, TaskRepository> =>
+  Effect.flatMap(TaskRepository, (repo) => repo.findByStatus(status))

package/src/task/ports.ts

@@ -0,0 +1,15 @@
+import { Context, type Effect } from "effect"
+import type { Status, Task, TaskError } from "../domain/types.js"
+
+export interface TaskRepository {
+  /** Fails with `not_found` if id is absent. */
+  findById(id: string): Effect.Effect<Task, TaskError>
+  /** Returns empty array when nothing matches; fails with `validation_error` on malformed data. */
+  findByStatus(status: Status | "*"): Effect.Effect<readonly Task[], TaskError>
+  /** Fails with `conflict` if a task with the same id already exists. */
+  save(task: Task): Effect.Effect<void, TaskError>
+  /** Fails with `not_found` if id is absent. */
+  update(task: Task): Effect.Effect<void, TaskError>
+}
+
+export const TaskRepository = Context.GenericTag<TaskRepository>("TaskRepository")

package/src/task/update-task.ts

@@ -0,0 +1,116 @@
+import { Effect } from "effect"
+import { guardTransition } from "../domain/status-machine.js"
+import type { Comment, Status, TaskError } from "../domain/types.js"
+import { HookRunner } from "../hook/ports.js"
+import { TaskRepository } from "./ports.js"
+
+/**
+ * Transitions a task to a new status, optionally attaching or replying to a comment.
+ * Enforces transition rules, comment requirements, need_info reply cycle,
+ * and concurrent in_progress justification.
+ * Fires HookRunner after a successful status change.
+ */
+export const updateTask = (
+  id: string,
+  newStatus: Status,
+  comment: Comment | null,
+  sessionId: string
+): Effect.Effect<void, TaskError, TaskRepository | HookRunner> =>
+  Effect.gen(function* () {
+    const repo = yield* TaskRepository
+    const hookRunner = yield* HookRunner
+
+    // Step 1: find task or fail with not_found
+    const task = yield* repo.findById(id)
+
+    // Step 2: guard transition (same→same is allowed by guardTransition too)
+    yield* guardTransition(task.status, newStatus)
+
+    // Step 4: reply handling — comment id matches an existing comment
+    // Must run before the no-op check because a reply update is meaningful
+    // even when the status is not changing.
+    if (comment !== null) {
+      const existing = task.comments.find((c) => c.id === comment.id)
+      if (existing !== undefined) {
+        if (existing.kind === "regular") {
+          return yield* Effect.fail<TaskError>({
+            _tag: "validation_error",
+            message: "reply is only valid on need_info comments",
+          })
+        }
+        // existing.kind === 'need_info': merge reply and persist, no hook, no status change
+        const updatedComments = task.comments.map((c) =>
+          c.id === comment.id ? { ...c, reply: comment.reply } : c
+        )
+        const updatedTask = { ...task, comments: updatedComments }
+        yield* repo.update(updatedTask)
+        return
+      }
+    }
+
+    // Step 3: no-op when status unchanged (and no reply was handled above)
+    if (task.status === newStatus) return
+
+    // Step 5: need_info requires a comment
+    if (newStatus === "need_info" && comment === null) {
+      return yield* Effect.fail<TaskError>({ _tag: "missing_comment" })
+    }
+
+    // Step 6: blocked requires a non-empty comment
+    if (newStatus === "blocked") {
+      if (comment === null) {
+        return yield* Effect.fail<TaskError>({ _tag: "missing_comment" })
+      }
+      if (comment.content.trim() === "") {
+        return yield* Effect.fail<TaskError>({
+          _tag: "validation_error",
+          message: "blocked requires a non-empty comment",
+        })
+      }
+    }
+
+    // Step 7: transitioning FROM need_info — all need_info comments must have a reply
+    if (task.status === "need_info") {
+      const blocking = task.comments.find((c) => c.kind === "need_info" && c.reply === "")
+      if (blocking !== undefined) {
+        return yield* Effect.fail<TaskError>({
+          _tag: "validation_error",
+          message: `blocking comment ${blocking.id} has no reply`,
+        })
+      }
+    }
+
+    // Step 8: concurrent in_progress — second task for same session requires justification
+    if (newStatus === "in_progress") {
+      const inProgressTasks = yield* repo.findByStatus("in_progress")
+      const sessionInProgress = inProgressTasks.filter(
+        (t) => t.assignee.id === sessionId && t.id !== task.id
+      )
+      if (sessionInProgress.length > 0) {
+        if (comment === null || comment.content.trim() === "") {
+          return yield* Effect.fail<TaskError>({
+            _tag: "validation_error",
+            message: "moving a second task to in_progress requires a justification comment",
+          })
+        }
+      }
+    }
+
+    // Step 9: apply changes
+    const oldStatus = task.status
+    const updatedComments = comment !== null ? [...task.comments, comment] : task.comments
+    const updatedTask = {
+      ...task,
+      status: newStatus,
+      comments: updatedComments,
+      ...(newStatus === "in_progress" ? { in_progress_since: new Date() } : {}),
+    }
+    yield* repo.update(updatedTask)
+    yield* hookRunner.run({
+      task_id: id,
+      old_status: oldStatus,
+      new_status: newStatus,
+      comment,
+      session_id: sessionId,
+    })
+  })