@nickmeriano/task 0.1.0

package/src/store.ts

@@ -0,0 +1,418 @@
+import { DatabaseSync } from "node:sqlite"
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, relative, sep } from "node:path"
+import type {
+  Comment,
+  ProjectConfig,
+  Status,
+  Task,
+  TaskFilter,
+  TaskInput,
+  TaskPatch,
+} from "./types.js"
+
+export const TASK_DIR = ".task"
+export const DB_FILE = "tasks.db"
+export const CONFIG_FILE = "config.json"
+
+/** Spacing between adjacent board positions — leaves room to drop between. */
+const POSITION_GAP = 1024
+
+/**
+ * Walk up from `from` looking for a `.task/config.json`, the way git finds its
+ * `.git`. Returns the directory that *contains* `.task`, or null.
+ */
+export function findRoot(from: string): string | null {
+  let dir = from
+  for (;;) {
+    if (existsSync(join(dir, TASK_DIR, CONFIG_FILE))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+export interface BoardRef {
+  /** POSIX-style path relative to the serve root — "." for the root board. */
+  id: string
+  /** Absolute directory containing `.task/`. */
+  root: string
+}
+
+/** Directories that never contain a board worth serving. */
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", "out", "coverage", "target"])
+
+/**
+ * The multi-board complement of `findRoot`: walk *down* from `serveRoot`
+ * collecting every directory that holds a `.task/config.json`, so one
+ * `task serve` at a monorepo root can serve every nested board. Boards are
+ * identified by relative path — unique where names need not be. Dot-dirs,
+ * dependency/build dirs and symlinks are skipped; unreadable dirs are ignored.
+ */
+export function findBoards(serveRoot: string, maxDepth = 6): BoardRef[] {
+  const boards: BoardRef[] = []
+  let level = [serveRoot]
+  for (let depth = 0; depth <= maxDepth && level.length > 0; depth++) {
+    const next: string[] = []
+    for (const dir of level) {
+      if (existsSync(join(dir, TASK_DIR, CONFIG_FILE))) {
+        const rel = relative(serveRoot, dir).split(sep).join("/")
+        boards.push({ id: rel === "" ? "." : rel, root: dir })
+      }
+      let entries
+      try {
+        entries = readdirSync(dir, { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const entry of entries) {
+        // isDirectory() is false for symlinks — that's the cycle/escape guard.
+        if (!entry.isDirectory()) continue
+        if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue
+        next.push(join(dir, entry.name))
+      }
+    }
+    level = next
+  }
+  // "." first, then lexicographic: the default board is deterministic.
+  boards.sort((a, b) => (a.id === "." ? -1 : b.id === "." ? 1 : a.id < b.id ? -1 : 1))
+  return boards
+}
+
+/** Derive an id prefix from a project name: "phone agent" → "PHONE". */
+export function derivePrefix(name: string): string {
+  const word = name.toUpperCase().replace(/[^A-Z0-9]+/g, " ").trim().split(" ")[0]
+  return (word || "TASK").slice(0, 10)
+}
+
+interface TaskRow {
+  id: number
+  title: string
+  description: string
+  status: string
+  tags: string
+  milestone: string | null
+  needs_human: number
+  position: number
+  created_at: string
+  updated_at: string
+}
+
+interface CommentRow {
+  id: number
+  task_id: number
+  author: string
+  body: string
+  created_at: string
+}
+
+function now(): string {
+  return new Date().toISOString()
+}
+
+/**
+ * The whole persistence layer: one SQLite database inside `.task/`, opened
+ * synchronously via node:sqlite (built into Node ≥22.13 — zero dependencies,
+ * nothing to compile, safe for `npx`).
+ */
+export class TaskStore {
+  readonly root: string
+  readonly taskDir: string
+  readonly config: ProjectConfig
+  private db: DatabaseSync
+
+  constructor(root: string) {
+    this.root = root
+    this.taskDir = join(root, TASK_DIR)
+    this.config = JSON.parse(
+      readFileSync(join(this.taskDir, CONFIG_FILE), "utf8"),
+    ) as ProjectConfig
+    this.db = new DatabaseSync(join(this.taskDir, DB_FILE))
+    // Multiple writers (CLI + serve + agents) are expected; wait for locks
+    // instead of failing fast with SQLITE_BUSY.
+    this.db.exec("PRAGMA busy_timeout = 3000")
+    this.db.exec("PRAGMA foreign_keys = ON")
+    migrate(this.db)
+  }
+
+  close(): void {
+    this.db.close()
+  }
+
+  displayId(number: number): string {
+    return `${this.config.prefix}-${number}`
+  }
+
+  /** Accepts "PHONE-12", "phone-12" or "12". */
+  parseId(ref: string): number {
+    const match = /^(?:[A-Za-z0-9]+-)?(\d+)$/.exec(ref.trim())
+    if (!match) throw new Error(`invalid task id: ${ref}`)
+    return Number(match[1])
+  }
+
+  private toTask(row: TaskRow): Task {
+    return {
+      id: this.displayId(row.id),
+      number: row.id,
+      title: row.title,
+      description: row.description,
+      status: row.status as Status,
+      tags: JSON.parse(row.tags) as string[],
+      milestone: row.milestone,
+      needsHuman: row.needs_human !== 0,
+      position: row.position,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    }
+  }
+
+  private toComment(row: CommentRow): Comment {
+    return {
+      id: row.id,
+      taskId: this.displayId(row.task_id),
+      author: row.author,
+      body: row.body,
+      createdAt: row.created_at,
+    }
+  }
+
+  list(filter: TaskFilter = {}): Task[] {
+    const where: string[] = []
+    const params: (string | number)[] = []
+    if (filter.statuses?.length) {
+      where.push(`status IN (${filter.statuses.map(() => "?").join(", ")})`)
+      params.push(...filter.statuses)
+    }
+    if (filter.milestone) {
+      where.push("milestone = ?")
+      params.push(filter.milestone)
+    }
+    if (filter.needsHuman !== undefined) {
+      where.push("needs_human = ?")
+      params.push(filter.needsHuman ? 1 : 0)
+    }
+    const sql = `SELECT * FROM tasks${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY position, id`
+    let rows = this.db.prepare(sql).all(...params) as unknown as TaskRow[]
+    if (filter.tags?.length) {
+      // Tags are a JSON blob, not a table — match them in JS, any-of.
+      const wanted = new Set(filter.tags)
+      rows = rows.filter((r) => (JSON.parse(r.tags) as string[]).some((t) => wanted.has(t)))
+    }
+    return rows.map((r) => this.toTask(r))
+  }
+
+  get(number: number): Task | null {
+    const row = this.db.prepare("SELECT * FROM tasks WHERE id = ?").get(number) as
+      | TaskRow
+      | undefined
+    return row ? this.toTask(row) : null
+  }
+
+  create(input: TaskInput): Task {
+    const status = input.status ?? "todo"
+    // New tasks land at the bottom of their column.
+    const max = this.db
+      .prepare("SELECT MAX(position) AS max FROM tasks WHERE status = ?")
+      .get(status) as { max: number | null }
+    const timestamp = now()
+    const result = this.db
+      .prepare(
+        `INSERT INTO tasks (title, description, status, tags, milestone, needs_human, position, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        input.title,
+        input.description ?? "",
+        status,
+        JSON.stringify(input.tags ?? []),
+        input.milestone ?? null,
+        input.needsHuman ? 1 : 0,
+        (max.max ?? 0) + POSITION_GAP,
+        timestamp,
+        timestamp,
+      )
+    return this.get(Number(result.lastInsertRowid))!
+  }
+
+  update(number: number, patch: TaskPatch): Task {
+    const existing = this.get(number)
+    if (!existing) throw new Error(`no such task: ${this.displayId(number)}`)
+
+    const sets: string[] = []
+    const params: (string | number | null)[] = []
+    const set = (column: string, value: string | number | null) => {
+      sets.push(`${column} = ?`)
+      params.push(value)
+    }
+
+    if (patch.title !== undefined) set("title", patch.title)
+    if (patch.description !== undefined) set("description", patch.description)
+    if (patch.tags !== undefined) set("tags", JSON.stringify(patch.tags))
+    if (patch.milestone !== undefined) set("milestone", patch.milestone)
+    if (patch.needsHuman !== undefined) set("needs_human", patch.needsHuman ? 1 : 0)
+    if (patch.status !== undefined) {
+      set("status", patch.status)
+      if (patch.position === undefined && patch.status !== existing.status) {
+        // Moved columns without an explicit slot → land on top, where the
+        // freshest movement is visible (Linear's behavior).
+        const min = this.db
+          .prepare("SELECT MIN(position) AS min FROM tasks WHERE status = ?")
+          .get(patch.status) as { min: number | null }
+        set("position", (min.min ?? 0) - POSITION_GAP)
+      }
+    }
+    if (patch.position !== undefined) set("position", patch.position)
+
+    if (sets.length === 0) return existing
+    set("updated_at", now())
+    params.push(number)
+    this.db.prepare(`UPDATE tasks SET ${sets.join(", ")} WHERE id = ?`).run(...params)
+    return this.get(number)!
+  }
+
+  delete(number: number): void {
+    const result = this.db.prepare("DELETE FROM tasks WHERE id = ?").run(number)
+    if (result.changes === 0) throw new Error(`no such task: ${this.displayId(number)}`)
+  }
+
+  comments(number: number): Comment[] {
+    const rows = this.db
+      .prepare("SELECT * FROM comments WHERE task_id = ? ORDER BY id")
+      .all(number) as unknown as CommentRow[]
+    return rows.map((r) => this.toComment(r))
+  }
+
+  addComment(number: number, body: string, author = ""): Comment {
+    if (!this.get(number)) throw new Error(`no such task: ${this.displayId(number)}`)
+    const result = this.db
+      .prepare("INSERT INTO comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)")
+      .run(number, author, body, now())
+    const row = this.db
+      .prepare("SELECT * FROM comments WHERE id = ?")
+      .get(Number(result.lastInsertRowid)) as unknown as CommentRow
+    return this.toComment(row)
+  }
+
+  deleteComment(number: number, commentId: number): Comment {
+    const row = this.db
+      .prepare("SELECT * FROM comments WHERE id = ? AND task_id = ?")
+      .get(commentId, number) as unknown as CommentRow | undefined
+    if (!row) throw new Error(`no such comment on ${this.displayId(number)}: ${commentId}`)
+    this.db.prepare("DELETE FROM comments WHERE id = ?").run(commentId)
+    return this.toComment(row)
+  }
+
+  commentCounts(): Map<number, number> {
+    const rows = this.db
+      .prepare("SELECT task_id, COUNT(*) AS count FROM comments GROUP BY task_id")
+      .all() as unknown as { task_id: number; count: number }[]
+    return new Map(rows.map((r) => [r.task_id, r.count]))
+  }
+}
+
+/**
+ * Schema history, one entry per version, applied in order from whatever
+ * `PRAGMA user_version` the file is at. `.task/tasks.db` is committed to git,
+ * so an existing database is the normal case, not the exception: every step
+ * has to be safe to run against a file someone else's checkout wrote.
+ *
+ * There is one linear path — a fresh database runs *every* step, so it lands
+ * on a schema byte-identical to a migrated one, and there's no second
+ * definition of "current" to keep in sync.
+ */
+const MIGRATIONS: string[] = [
+  // v1 — the original schema. `IF NOT EXISTS` is load-bearing: user_version 0
+  // means "fresh *or* written before versioning existed", and this is the step
+  // that makes both of those safe to start from.
+  //
+  // The odd indentation is deliberate and load-bearing: SQLite stores the
+  // CREATE statement *verbatim* in sqlite_master, so keeping this byte-for-byte
+  // as it originally shipped is what lets a freshly-created database and a
+  // migrated one end up with an identical schema rather than one that only
+  // matches in structure.
+  `
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      description TEXT NOT NULL DEFAULT '',
+      status TEXT NOT NULL DEFAULT 'todo',
+      priority TEXT NOT NULL DEFAULT 'none',
+      assignee TEXT,
+      labels TEXT NOT NULL DEFAULT '[]',
+      position REAL NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS comments (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      author TEXT NOT NULL DEFAULT '',
+      body TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+  `,
+
+  // v2 — labels become tags, priority/assignee give way to milestone and a
+  // needs-human flag. RENAME COLUMN (SQLite 3.25+) and DROP COLUMN (3.35+) are
+  // both available on Node ≥ 22.13, which bundles 3.49.
+  //
+  // If DROP COLUMN ever weren't available the escape hatch is the usual table
+  // rebuild — but note it would need `PRAGMA foreign_keys = OFF` issued
+  // *outside* the transaction (the pragma is a no-op inside one), because
+  // comments.task_id references tasks(id).
+  `ALTER TABLE tasks RENAME COLUMN labels TO tags;
+   ALTER TABLE tasks ADD COLUMN milestone TEXT;
+   ALTER TABLE tasks ADD COLUMN needs_human INTEGER NOT NULL DEFAULT 0;
+   ALTER TABLE tasks DROP COLUMN priority;
+   ALTER TABLE tasks DROP COLUMN assignee;`,
+]
+
+/**
+ * Bring `db` up to the newest schema. DDL and `PRAGMA user_version` are both
+ * transactional in SQLite, so a failure halfway leaves the file exactly as it
+ * was — schema *and* version.
+ */
+function migrate(db: DatabaseSync): void {
+  const { user_version: version } = db.prepare("PRAGMA user_version").get() as {
+    user_version: number
+  }
+  if (version >= MIGRATIONS.length) return
+  db.exec("BEGIN")
+  try {
+    for (const step of MIGRATIONS.slice(version)) db.exec(step)
+    db.exec(`PRAGMA user_version = ${MIGRATIONS.length}`)
+    db.exec("COMMIT")
+  } catch (error) {
+    db.exec("ROLLBACK")
+    throw error
+  }
+}
+
+export interface InitOptions {
+  name: string
+  prefix?: string
+}
+
+/**
+ * Create `.task/` in `root`: config, an empty database, and a .gitignore for
+ * SQLite's transient sidecar files (the database itself is meant to be
+ * committed — that's the point).
+ */
+export function initProject(root: string, options: InitOptions): TaskStore {
+  const taskDir = join(root, TASK_DIR)
+  if (existsSync(join(taskDir, CONFIG_FILE))) {
+    throw new Error(`already initialized: ${join(taskDir, CONFIG_FILE)} exists`)
+  }
+  mkdirSync(taskDir, { recursive: true })
+  const config: ProjectConfig = {
+    name: options.name,
+    prefix: options.prefix ?? derivePrefix(options.name),
+    version: 1,
+  }
+  writeFileSync(join(taskDir, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
+  writeFileSync(
+    join(taskDir, ".gitignore"),
+    "# SQLite transients — tasks.db itself is committed.\n*.db-journal\n*.db-wal\n*.db-shm\n",
+  )
+  return new TaskStore(root)
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+/** The five workflow states, in board order. Fixed on purpose — a task manager
+ * you can configure is a task manager you have to configure. */
+export const STATUSES = [
+  "backlog",
+  "todo",
+  "in_progress",
+  "done",
+  "canceled",
+] as const
+export type Status = (typeof STATUSES)[number]
+
+export interface Task {
+  /** Display id — `<prefix>-<number>`, e.g. "PHONE-12". */
+  id: string
+  number: number
+  title: string
+  description: string
+  status: Status
+  tags: string[]
+  milestone: string | null
+  /** This ticket can't be finished by an agent alone. */
+  needsHuman: boolean
+  /** Sort key within a status column; smaller sorts first. */
+  position: number
+  createdAt: string
+  updatedAt: string
+}
+
+export interface Comment {
+  id: number
+  taskId: string
+  author: string
+  body: string
+  createdAt: string
+}
+
+export interface ProjectConfig {
+  name: string
+  /** Uppercase id prefix, e.g. "PHONE" → PHONE-1, PHONE-2, … */
+  prefix: string
+  version: number
+}
+
+export interface TaskFilter {
+  statuses?: Status[]
+  /** Any-of: a task matches if it carries at least one of these tags. */
+  tags?: string[]
+  milestone?: string
+  /** undefined = don't filter on it at all. */
+  needsHuman?: boolean
+}
+
+export interface TaskInput {
+  title: string
+  description?: string
+  status?: Status
+  tags?: string[]
+  milestone?: string | null
+  needsHuman?: boolean
+}
+
+export interface TaskPatch {
+  title?: string
+  description?: string
+  status?: Status
+  tags?: string[]
+  milestone?: string | null
+  needsHuman?: boolean
+  /** Explicit board position (used by drag-and-drop in the UI). */
+  position?: number
+}
+
+export function isStatus(value: string): value is Status {
+  return (STATUSES as readonly string[]).includes(value)
+}