@bosun-sh/logbook 1.1.0 → 2.0.0

package/src/cli/init.ts

@@ -1,230 +0,0 @@
-import { access, lstat, mkdir, readFile, symlink, writeFile } from "node:fs/promises"
-import { join } from "node:path"
-
-const CLI_DOC_CONTENT = `# Logbook CLI
-
-File-system kanban board for AI agents.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| \`logbook create-task\` | Create a new task in backlog |
-| \`logbook list-tasks\` | List tasks, optionally filtered by status |
-| \`logbook current-task\` | Get current in-progress task for this session |
-| \`logbook update-task\` | Transition task status |
-| \`logbook edit-task\` | Edit task fields without changing status |
-| \`logbook init\` | Initialize project |
-
-## Task Lifecycle
-
-\`backlog → todo → in_progress → pending_review → done\`
-
-Side-exits: \`in_progress → need_info\`, \`blocked\` (return to \`in_progress\`)
-
-## Usage Examples
-
-### Create a task
-\`\`\`bash
-logbook create-task --project myproject --milestone v1 --title "Fix bug" \\
-  --definition-of-done "Bug fixed and tested" --description "Details..." \\
-  --predicted-k-tokens 3
-\`\`\`
-
-### List tasks
-\`\`\`bash
-logbook list-tasks --status in_progress
-logbook list-tasks --status "*"
-logbook list-tasks --status todo --project myproject
-\`\`\`
-
-### Get current task
-\`\`\`bash
-logbook current-task
-\`\`\`
-
-### Update task status
-\`\`\`bash
-logbook update-task --id <uuid> --new-status in_progress
-logbook update-task --id <uuid> --new-status need_info \\
-  --comment-title "Need info" --comment-content "What does X mean?"
-\`\`\`
-
-### Edit task
-\`\`\`bash
-logbook edit-task --id <uuid> --title "New title"
-\`\`\`
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| \`LOGBOOK_TASKS_FILE\` | \`./tasks.jsonl\` | Path to JSONL task store |
-| \`LOGBOOK_HOOKS_DIR\` | \`./hooks\` | Directory for hook definitions |
-| \`LOGBOOK_SESSION_ID\` | auto-generated | Session ID to use |
-`
-
-const CLAUDE_CODE_SNIPPET = `Claude Code — add to .claude/settings.json:
-{
-  "mcpServers": {
-    "logbook": {
-      "command": "logbook-mcp"
-    }
-  }
-}`
-
-const OPENCODE_SNIPPET = `OpenCode — add to opencode.json:
-{
-  "mcp": {
-    "logbook": {
-      "type": "local",
-      "command": ["logbook-mcp"],
-      "enabled": true
-    }
-  }
-}`
-
-const GITIGNORE_SNIPPET = `.gitignore — add these runtime files:
-tasks.jsonl
-sessions.json
-.logbook-session`
-
-const NEXT_STEPS = `Next steps:
-  1. Add the config snippet for your AI client (MCP) or use CLI directly
-  2. Run: LOGBOOK_TASKS_FILE=./tasks.jsonl logbook init
-  3. See AGENTS.md for CLI commands reference
-  4. See quickstart.md for the full walkthrough`
-
-const fileExists = async (path: string): Promise<boolean> => {
-  try {
-    await access(path)
-    return true
-  } catch {
-    return false
-  }
-}
-
-const isSymlink = async (path: string): Promise<boolean> => {
-  try {
-    const stats = await lstat(path)
-    return stats.isSymbolicLink()
-  } catch {
-    return false
-  }
-}
-
-const scaffoldTasksFile = async (cwd: string): Promise<void> => {
-  const path = join(cwd, "tasks.jsonl")
-  if (await fileExists(path)) {
-    console.log("✓ tasks.jsonl already exists, skipping")
-    return
-  }
-  await writeFile(path, "", "utf8")
-  console.log("✓ tasks.jsonl created")
-}
-
-const scaffoldHooksDir = async (cwd: string): Promise<void> => {
-  const path = join(cwd, "hooks")
-  if (await fileExists(path)) {
-    console.log("✓ hooks/ already exists, skipping")
-    return
-  }
-  await mkdir(path, { recursive: false })
-  console.log("✓ hooks/ created")
-}
-
-const appendLogbookDocs = async (path: string, isAgents: boolean): Promise<void> => {
-  const existing = await readFile(path, "utf8")
-  if (isAgents) {
-    const separator = "\n\n---\n\n"
-    await writeFile(path, `${existing}${separator}${CLI_DOC_CONTENT}`, "utf8")
-  } else {
-    const cliSection = `
-
----
-
-## Logbook
-
-${CLI_DOC_CONTENT}
-`
-    await writeFile(path, `${existing}${cliSection}`, "utf8")
-  }
-}
-
-const ensureBothDocs = async (cwd: string, force: boolean): Promise<void> => {
-  const agentsPath = join(cwd, "AGENTS.md")
-  const claudePath = join(cwd, "CLAUDE.md")
-
-  const agentsExists = await fileExists(agentsPath)
-  const claudeExists = await fileExists(claudePath)
-  const agentsIsSymlink = await isSymlink(agentsPath)
-  const claudeIsSymlink = await isSymlink(claudePath)
-
-  if (!force) {
-    if (agentsExists && !agentsIsSymlink) {
-      console.log("✓ AGENTS.md already exists, appending logbook documentation")
-      await appendLogbookDocs(agentsPath, true)
-    }
-    if (claudeExists && !claudeIsSymlink) {
-      console.log("✓ CLAUDE.md already exists, appending logbook documentation")
-      await appendLogbookDocs(claudePath, false)
-    }
-    if (!agentsExists && !claudeExists) {
-      await writeFile(agentsPath, CLI_DOC_CONTENT, "utf8")
-      console.log("✓ AGENTS.md created")
-      await symlink("AGENTS.md", claudePath)
-      console.log("✓ CLAUDE.md created (symlink to AGENTS.md)")
-    }
-    return
-  }
-
-  if (agentsExists && !agentsIsSymlink) {
-    await appendLogbookDocs(agentsPath, true)
-  } else if (!agentsExists) {
-    await writeFile(agentsPath, CLI_DOC_CONTENT, "utf8")
-    console.log("✓ AGENTS.md created")
-  }
-
-  if (claudeExists && !claudeIsSymlink) {
-    await appendLogbookDocs(claudePath, false)
-  } else if (!claudeExists) {
-    const targetExists = await fileExists(agentsPath)
-    if (targetExists) {
-      await symlink("AGENTS.md", claudePath)
-      console.log("✓ CLAUDE.md created (symlink to AGENTS.md)")
-    } else {
-      await writeFile(
-        claudePath,
-        `# Logbook
-
-${CLI_DOC_CONTENT}
-`,
-        "utf8"
-      )
-      console.log("✓ CLAUDE.md created")
-    }
-  } else if (claudeIsSymlink) {
-    console.log("✓ CLAUDE.md is already a symlink to AGENTS.md, skipping")
-  }
-}
-
-const printSnippets = (): void => {
-  console.log("")
-  console.log(CLAUDE_CODE_SNIPPET)
-  console.log("")
-  console.log(OPENCODE_SNIPPET)
-  console.log("")
-  console.log(GITIGNORE_SNIPPET)
-  console.log("")
-  console.log(NEXT_STEPS)
-}
-
-export const runInit = async (
-  cwd: string = process.cwd(),
-  options: { force?: boolean } = {}
-): Promise<void> => {
-  await scaffoldTasksFile(cwd)
-  await scaffoldHooksDir(cwd)
-  await ensureBothDocs(cwd, options.force ?? false)
-  printSnippets()
-}

package/src/domain/fibonacci.ts

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

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

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

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

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

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

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