@nickmeriano/task 0.4.2 → 0.6.0

package/src/file-store.ts

@@ -0,0 +1,693 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { basename, dirname, join } from "node:path"
+import {
+  commentStem,
+  parseComment,
+  parseTicket,
+  serializeComment,
+  serializeTicket,
+  type TicketDoc,
+} from "./ticket-doc.ts"
+import {
+  CONFIG_FILE,
+  DB_FILE,
+  POSITION_GAP,
+  TASK_DIR,
+  TaskStore,
+  derivePrefix,
+  type Store,
+} from "./store.ts"
+import type {
+  Comment,
+  ProjectConfig,
+  Status,
+  Task,
+  TaskFilter,
+  TaskInput,
+  TaskPatch,
+} from "./types.ts"
+
+export const TICKETS_DIR = "tickets"
+/** Finished tickets moved out of the hot path — same per-ticket layout. */
+export const ARCHIVE_DIR = "archive"
+const TICKET_FILE = "ticket.md"
+const COMMENTS_DIR = "comments"
+
+function now(): string {
+  return new Date().toISOString()
+}
+
+/**
+ * Write-then-rename, so a reader (another CLI, the serve watcher, a crashed
+ * process) never sees half a ticket.
+ */
+function writeAtomic(path: string, text: string): void {
+  const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.tmp`)
+  writeFileSync(tmp, text)
+  renameSync(tmp, path)
+}
+
+interface Ticket {
+  number: number
+  doc: TicketDoc
+}
+
+/**
+ * The canonical persistence layer: one directory per ticket under
+ * `.task/tickets/`, holding a frontmatter+markdown `ticket.md` and one file
+ * per comment. Everything is plain text committed to git, which is the point —
+ * ticket edits diff, review, and merge like code, and two branches touching
+ * different tickets (or adding comments to the same one) merge cleanly by
+ * construction.
+ *
+ * There is no database and no cache: boards are dozens of tickets, and
+ * re-reading a handful of small files per operation is cheaper than opening
+ * SQLite ever was. If boards outgrow that, a derived (gitignored) index can be
+ * added without changing the format — the files stay the source of truth.
+ */
+export class FileStore implements Store {
+  readonly root: string
+  readonly taskDir: string
+  readonly config: ProjectConfig
+  private ticketsDir: string
+  private archiveDir: string
+
+  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.ticketsDir = join(this.taskDir, TICKETS_DIR)
+    this.archiveDir = join(this.taskDir, ARCHIVE_DIR)
+  }
+
+  close(): void {}
+
+  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])
+  }
+
+  // ── Reading ────────────────────────────────────────────────────────────────
+
+  private ticketPath(number: number): string {
+    return join(this.ticketsDir, String(number), TICKET_FILE)
+  }
+
+  /**
+   * A ticket's comments live wherever the ticket does — the whole directory
+   * moves on archive, so an archived ticket's discussion stays readable.
+   */
+  private commentsPath(number: number): string {
+    const home = existsSync(join(this.archiveDir, String(number)))
+      ? this.archiveDir
+      : this.ticketsDir
+    return join(home, String(number), COMMENTS_DIR)
+  }
+
+  private readDir(dir: string): Ticket[] {
+    if (!existsSync(dir)) return []
+    const tickets: Ticket[] = []
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue
+      const path = join(dir, entry.name, TICKET_FILE)
+      if (!existsSync(path)) continue
+      tickets.push({ number: Number(entry.name), doc: parseTicket(readFileSync(path, "utf8"), path) })
+    }
+    tickets.sort((a, b) => a.number - b.number)
+    return tickets
+  }
+
+  /** Every live ticket on the board, freshly parsed — the files are the state. */
+  private readAll(): Ticket[] {
+    return this.readDir(this.ticketsDir)
+  }
+
+  private readOne(number: number): Ticket | null {
+    const path = this.ticketPath(number)
+    if (!existsSync(path)) return null
+    return { number, doc: parseTicket(readFileSync(path, "utf8"), path) }
+  }
+
+  /** Cheap presence check — the archive's numbers, without parsing anything. */
+  private archivedNumbers(): number[] {
+    if (!existsSync(this.archiveDir)) return []
+    return readdirSync(this.archiveDir)
+      .filter((name) => /^\d+$/.test(name))
+      .map(Number)
+  }
+
+  private isArchived(number: number): boolean {
+    return existsSync(join(this.archiveDir, String(number), TICKET_FILE))
+  }
+
+  /** The error every write path throws instead of touching the archive. */
+  private assertNotArchived(number: number): void {
+    if (this.isArchived(number)) {
+      const id = this.displayId(number)
+      throw new Error(`${id} is archived — run \`task unarchive ${id}\` first`)
+    }
+  }
+
+  private writeTicket(ticket: Ticket): void {
+    mkdirSync(dirname(this.ticketPath(ticket.number)), { recursive: true })
+    writeAtomic(this.ticketPath(ticket.number), serializeTicket(ticket.doc))
+  }
+
+  /**
+   * Only `blocked_by` is stored (on the blocked ticket); the `blocks` side is
+   * derived here, so the two views can never disagree.
+   */
+  private toTask(ticket: Ticket, all: Ticket[]): Task {
+    const blocks = all
+      .filter((t) => t.doc.blockedBy.includes(ticket.number))
+      .map((t) => t.number)
+    return {
+      id: this.displayId(ticket.number),
+      number: ticket.number,
+      title: ticket.doc.title,
+      description: ticket.doc.description,
+      status: ticket.doc.status,
+      tags: ticket.doc.tags,
+      milestone: ticket.doc.milestone,
+      needsHuman: ticket.doc.needsHuman,
+      blocks,
+      blockedBy: [...ticket.doc.blockedBy].sort((a, b) => a - b),
+      prs: ticket.doc.prs,
+      position: ticket.doc.position,
+      createdAt: ticket.doc.createdAt,
+      updatedAt: ticket.doc.updatedAt,
+    }
+  }
+
+  private applyFilter(tickets: Ticket[], filter: TaskFilter): Ticket[] {
+    if (filter.statuses?.length) {
+      const wanted = new Set<Status>(filter.statuses)
+      tickets = tickets.filter((t) => wanted.has(t.doc.status))
+    }
+    if (filter.milestone) {
+      tickets = tickets.filter((t) => t.doc.milestone === filter.milestone)
+    }
+    if (filter.needsHuman !== undefined) {
+      tickets = tickets.filter((t) => t.doc.needsHuman === filter.needsHuman)
+    }
+    if (filter.tags?.length) {
+      const wanted = new Set(filter.tags)
+      tickets = tickets.filter((t) => t.doc.tags.some((tag) => wanted.has(tag)))
+    }
+    return tickets
+  }
+
+  list(filter: TaskFilter = {}): Task[] {
+    if (filter.archived) {
+      // Relations are derived across both sets so an archived ticket still
+      // shows what it blocked; `archived: true` is only ever set here, so the
+      // board's payloads carry no new field.
+      const archived = this.readDir(this.archiveDir)
+      const everything = [...this.readAll(), ...archived]
+      return this.applyFilter(archived, filter)
+        .map((t) => ({ ...this.toTask(t, everything), archived: true }))
+        .sort((a, b) => a.position - b.position || a.number - b.number)
+    }
+    const all = this.readAll()
+    return this.applyFilter(all, filter)
+      .map((t) => this.toTask(t, all))
+      .sort((a, b) => a.position - b.position || a.number - b.number)
+  }
+
+  get(number: number): Task | null {
+    const all = this.readAll()
+    const ticket = all.find((t) => t.number === number)
+    if (ticket) return this.toTask(ticket, all)
+    // `show` should reach the archive without ceremony — reads are safe.
+    const path = join(this.archiveDir, String(number), TICKET_FILE)
+    if (!existsSync(path)) return null
+    const archived: Ticket = { number, doc: parseTicket(readFileSync(path, "utf8"), path) }
+    return { ...this.toTask(archived, [...all, archived]), archived: true }
+  }
+
+  // ── Writing ────────────────────────────────────────────────────────────────
+
+  create(input: TaskInput): Task {
+    const all = this.readAll()
+    // Archived numbers stay reserved — a new ticket must never take a number
+    // that old comments or PR titles still point at.
+    const taken = [...all.map((t) => t.number), ...this.archivedNumbers()]
+    const number = taken.reduce((max, n) => Math.max(max, n), 0) + 1
+    const status = input.status ?? "todo"
+    for (const target of [...(input.blocks ?? []), ...(input.blockedBy ?? [])]) {
+      if (!all.some((t) => t.number === target)) {
+        throw new Error(`no such task: ${this.displayId(target)}`)
+      }
+    }
+    // New tasks land at the bottom of their column.
+    const column = all.filter((t) => t.doc.status === status)
+    const bottom = column.length ? Math.max(...column.map((t) => t.doc.position)) : 0
+    const timestamp = now()
+    const ticket: Ticket = {
+      number,
+      doc: {
+        title: input.title,
+        description: input.description ?? "",
+        status,
+        tags: input.tags ?? [],
+        milestone: input.milestone ?? null,
+        needsHuman: input.needsHuman ?? false,
+        blockedBy: [...new Set(input.blockedBy ?? [])].sort((a, b) => a - b),
+        prs: input.prs ?? [],
+        position: bottom + POSITION_GAP,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      },
+    }
+    this.writeTicket(ticket)
+    if (input.blocks !== undefined) {
+      this.reconcileBlocks(number, [...all, ticket], input.blocks, timestamp)
+    }
+    return this.get(number)!
+  }
+
+  update(number: number, patch: TaskPatch): Task {
+    const all = this.readAll()
+    const ticket = all.find((t) => t.number === number)
+    if (!ticket) {
+      this.assertNotArchived(number)
+      throw new Error(`no such task: ${this.displayId(number)}`)
+    }
+
+    // Validate link targets before any file is written, so a bad target
+    // rejects the whole patch — the transactional behavior the SQLite store
+    // got for free.
+    for (const target of [...(patch.blocks ?? []), ...(patch.blockedBy ?? [])]) {
+      if (target === number) {
+        throw new Error(`a task can't block itself: ${this.displayId(number)}`)
+      }
+      if (!all.some((t) => t.number === target)) {
+        this.assertNotArchived(target)
+        throw new Error(`no such task: ${this.displayId(target)}`)
+      }
+    }
+
+    const timestamp = now()
+    let linksChanged = false
+    if (patch.blocks !== undefined) {
+      linksChanged = this.reconcileBlocks(number, all, patch.blocks, timestamp)
+    }
+    if (patch.blockedBy !== undefined) {
+      const wanted = [...new Set(patch.blockedBy)].sort((a, b) => a - b)
+      const current = ticket.doc.blockedBy
+      const touched = [
+        ...current.filter((n) => !wanted.includes(n)),
+        ...wanted.filter((n) => !current.includes(n)),
+      ]
+      if (touched.length > 0) {
+        linksChanged = true
+        ticket.doc.blockedBy = wanted
+        // The other end of every added or removed link gets its `updated`
+        // bumped too — its derived `blocks` view just changed. A dangling
+        // reference (hand-edit pointing at a deleted ticket) has no other end.
+        for (const n of touched) {
+          const other = all.find((t) => t.number === n)
+          if (!other) continue
+          other.doc.updatedAt = timestamp
+          this.writeTicket(other)
+        }
+      }
+    }
+
+    const doc = ticket.doc
+    let fieldsChanged = false
+    const set = <K extends keyof TicketDoc>(key: K, value: TicketDoc[K]) => {
+      doc[key] = value
+      fieldsChanged = true
+    }
+
+    if (patch.title !== undefined) set("title", patch.title)
+    if (patch.description !== undefined) set("description", patch.description)
+    if (patch.tags !== undefined) set("tags", patch.tags)
+    if (patch.milestone !== undefined) set("milestone", patch.milestone)
+    if (patch.needsHuman !== undefined) set("needsHuman", patch.needsHuman)
+    if (patch.prs !== undefined) set("prs", patch.prs)
+    if (patch.status !== undefined) {
+      const previous = doc.status
+      set("status", patch.status)
+      if (patch.position === undefined && patch.status !== previous) {
+        // Moved columns without an explicit slot → land on top, where the
+        // freshest movement is visible (Linear's behavior).
+        const column = all.filter((t) => t.number !== number && t.doc.status === patch.status)
+        const top = column.length ? Math.min(...column.map((t) => t.doc.position)) : 0
+        set("position", top - POSITION_GAP)
+      }
+    }
+    if (patch.position !== undefined) set("position", patch.position)
+
+    if (!fieldsChanged && !linksChanged) return this.toTask(ticket, all)
+    if (fieldsChanged || linksChanged) doc.updatedAt = timestamp
+    this.writeTicket(ticket)
+    return this.get(number)!
+  }
+
+  /**
+   * Make every other ticket's `blocked_by` agree with "this task blocks
+   * exactly `targets`". Returns whether anything changed; every touched ticket
+   * (and, via the caller, this one) gets its `updated` bumped.
+   */
+  private reconcileBlocks(
+    number: number,
+    all: Ticket[],
+    targets: number[],
+    timestamp: string,
+  ): boolean {
+    const wanted = new Set(targets)
+    if (wanted.has(number)) {
+      throw new Error(`a task can't block itself: ${this.displayId(number)}`)
+    }
+    let changed = false
+    for (const other of all) {
+      if (other.number === number) continue
+      const has = other.doc.blockedBy.includes(number)
+      const should = wanted.has(other.number)
+      if (has === should) continue
+      other.doc.blockedBy = should
+        ? [...other.doc.blockedBy, number].sort((a, b) => a - b)
+        : other.doc.blockedBy.filter((n) => n !== number)
+      other.doc.updatedAt = timestamp
+      this.writeTicket(other)
+      changed = true
+    }
+    if (changed) {
+      const self = all.find((t) => t.number === number)
+      if (self) {
+        self.doc.updatedAt = timestamp
+        this.writeTicket(self)
+      }
+    }
+    return changed
+  }
+
+  /** `task link A --blocks B` and friends — additive, unlike the patch form. */
+  link(number: number, relation: "blocks" | "blocked_by", target: number): Task {
+    const task = this.get(number)
+    if (!task) throw new Error(`no such task: ${this.displayId(number)}`)
+    const current = relation === "blocks" ? task.blocks : task.blockedBy
+    const patch: TaskPatch =
+      relation === "blocks"
+        ? { blocks: [...current, target] }
+        : { blockedBy: [...current, target] }
+    return this.update(number, patch)
+  }
+
+  unlink(number: number, relation: "blocks" | "blocked_by", target: number): Task {
+    const task = this.get(number)
+    if (!task) throw new Error(`no such task: ${this.displayId(number)}`)
+    const current = relation === "blocks" ? task.blocks : task.blockedBy
+    const kept = current.filter((n) => n !== target)
+    const patch: TaskPatch = relation === "blocks" ? { blocks: kept } : { blockedBy: kept }
+    return this.update(number, patch)
+  }
+
+  delete(number: number): void {
+    if (!this.readOne(number)) {
+      this.assertNotArchived(number)
+      throw new Error(`no such task: ${this.displayId(number)}`)
+    }
+    rmSync(join(this.ticketsDir, String(number)), { recursive: true })
+    // Links pointing at the deleted ticket go with it — the same cascade the
+    // relation table had, so quiet on the other tickets' `updated`.
+    for (const other of this.readAll()) {
+      if (!other.doc.blockedBy.includes(number)) continue
+      other.doc.blockedBy = other.doc.blockedBy.filter((n) => n !== number)
+      this.writeTicket(other)
+    }
+  }
+
+  // ── Archive ────────────────────────────────────────────────────────────────
+
+  /**
+   * Move a finished ticket's whole directory to `.task/archive/` — one rename,
+   * which git records as a move, so history follows the ticket. Archived
+   * tickets leave every hot path (`list`, the board, link derivation) but stay
+   * readable via `get`/`comments` and keep their number reserved forever.
+   * Links other tickets hold on this one are left in place: they're
+   * dangling-tolerant everywhere, and unarchiving puts them back in force.
+   */
+  archive(number: number): Task {
+    const ticket = this.readOne(number)
+    if (!ticket) {
+      if (this.isArchived(number)) {
+        throw new Error(`${this.displayId(number)} is already archived`)
+      }
+      throw new Error(`no such task: ${this.displayId(number)}`)
+    }
+    if (ticket.doc.status !== "done" && ticket.doc.status !== "canceled") {
+      throw new Error(
+        `${this.displayId(number)} is ${ticket.doc.status} — only done or canceled tickets can be archived`,
+      )
+    }
+    mkdirSync(this.archiveDir, { recursive: true })
+    renameSync(join(this.ticketsDir, String(number)), join(this.archiveDir, String(number)))
+    return this.get(number)!
+  }
+
+  unarchive(number: number): Task {
+    if (!this.isArchived(number)) {
+      throw new Error(
+        this.readOne(number)
+          ? `${this.displayId(number)} isn't archived`
+          : `no such task: ${this.displayId(number)}`,
+      )
+    }
+    // A checkout where everything is archived has no tickets/ at all — git
+    // doesn't keep empty directories.
+    mkdirSync(this.ticketsDir, { recursive: true })
+    renameSync(join(this.archiveDir, String(number)), join(this.ticketsDir, String(number)))
+    return this.get(number)!
+  }
+
+  // ── Comments ───────────────────────────────────────────────────────────────
+
+  /**
+   * One file per comment, append-only: two writers commenting concurrently on
+   * the same ticket produce two files and merge without a conflict — which is
+   * why they aren't lines inside `ticket.md`.
+   */
+  comments(number: number): Comment[] {
+    const dir = this.commentsPath(number)
+    if (!existsSync(dir)) return []
+    const comments: Comment[] = []
+    for (const entry of readdirSync(dir)) {
+      if (!entry.endsWith(".md") || entry.startsWith(".")) continue
+      const path = join(dir, entry)
+      const doc = parseComment(readFileSync(path, "utf8"), path)
+      comments.push({
+        id: entry.slice(0, -3),
+        taskId: this.displayId(number),
+        author: doc.author,
+        body: doc.body,
+        createdAt: doc.createdAt,
+      })
+    }
+    comments.sort(
+      (a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id),
+    )
+    return comments
+  }
+
+  addComment(number: number, body: string, author = ""): Comment {
+    if (!this.readOne(number)) {
+      this.assertNotArchived(number)
+      throw new Error(`no such task: ${this.displayId(number)}`)
+    }
+    const createdAt = now()
+    const dir = this.commentsPath(number)
+    mkdirSync(dir, { recursive: true })
+    const stem = commentStem(createdAt, author)
+    let id = stem
+    for (let n = 2; existsSync(join(dir, `${id}.md`)); n++) id = `${stem}-${n}`
+    writeAtomic(join(dir, `${id}.md`), serializeComment({ author, createdAt, body }))
+    return { id, taskId: this.displayId(number), author, body, createdAt }
+  }
+
+  deleteComment(number: number, commentId: string): Comment {
+    // Resolve the id against the directory listing rather than building a path
+    // from it — the id arrived over HTTP and must not be able to point
+    // anywhere but at an actual comment of this task.
+    const existing = this.comments(number).find((c) => c.id === commentId)
+    if (!existing) {
+      throw new Error(`no such comment on ${this.displayId(number)}: ${commentId}`)
+    }
+    rmSync(join(this.commentsPath(number), `${commentId}.md`))
+    return existing
+  }
+
+  commentCounts(): Map<number, number> {
+    const counts = new Map<number, number>()
+    for (const ticket of this.readAll()) {
+      const dir = this.commentsPath(ticket.number)
+      if (!existsSync(dir)) continue
+      const count = readdirSync(dir).filter(
+        (f) => f.endsWith(".md") && !f.startsWith("."),
+      ).length
+      if (count > 0) counts.set(ticket.number, count)
+    }
+    return counts
+  }
+}
+
+// ── Opening, initializing, migrating ─────────────────────────────────────────
+
+/** What `.task/.gitignore` says on a text-canonical board. */
+const GITIGNORE = `# Board state is the text files in tickets/ — the database (if one is still
+# around from before \`task migrate\`) is derived/legacy and stays out of git.
+${DB_FILE}
+*.db-journal
+*.db-wal
+*.db-shm
+*.tmp
+`
+
+/**
+ * The board in `root`, on whichever backend it uses: text files when the
+ * `tickets/` tree exists or the config says version ≥ 2, the legacy SQLite
+ * store otherwise. Old boards keep working untouched until `task migrate`.
+ */
+export function openBoard(root: string): Store {
+  const taskDir = join(root, TASK_DIR)
+  if (existsSync(join(taskDir, TICKETS_DIR))) return new FileStore(root)
+  const config = JSON.parse(readFileSync(join(taskDir, CONFIG_FILE), "utf8")) as ProjectConfig
+  if ((config.version ?? 1) >= 2) return new FileStore(root)
+  return new TaskStore(root)
+}
+
+export interface InitOptions {
+  name: string
+  prefix?: string
+}
+
+/**
+ * Create `.task/` in `root`: config and a .gitignore. New boards are
+ * text-canonical from the start — tickets appear under `tickets/` as they're
+ * created, and everything in `.task/` except the ignores belongs in git.
+ */
+export function initProject(root: string, options: InitOptions): Store {
+  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: 2,
+  }
+  writeFileSync(join(taskDir, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
+  writeFileSync(join(taskDir, ".gitignore"), GITIGNORE)
+  return new FileStore(root)
+}
+
+export interface MigrateResult {
+  tasks: number
+  comments: number
+}
+
+/**
+ * `task migrate` — export every ticket and comment from a legacy `tasks.db`
+ * into the text layout, flip the config to version 2, and gitignore the
+ * database. The database file itself is left on disk untouched, as a backup;
+ * it just stops being the state.
+ */
+export function migrateBoard(root: string): MigrateResult {
+  const taskDir = join(root, TASK_DIR)
+  if (existsSync(join(taskDir, TICKETS_DIR))) {
+    throw new Error("already migrated — .task/tickets/ exists")
+  }
+  if (!existsSync(join(taskDir, DB_FILE))) {
+    throw new Error(`nothing to migrate — no ${DB_FILE} in .task/`)
+  }
+
+  const legacy = new TaskStore(root)
+  let comments = 0
+  try {
+    const tasks = legacy.list({})
+    for (const task of tasks) {
+      const dir = join(taskDir, TICKETS_DIR, String(task.number))
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(
+        join(dir, TICKET_FILE),
+        serializeTicket({
+          title: task.title,
+          description: task.description,
+          status: task.status,
+          tags: task.tags,
+          milestone: task.milestone,
+          needsHuman: task.needsHuman,
+          blockedBy: task.blockedBy,
+          prs: task.prs,
+          position: task.position,
+          createdAt: task.createdAt,
+          updatedAt: task.updatedAt,
+        }),
+      )
+      const taskComments = legacy.comments(task.number)
+      if (taskComments.length === 0) continue
+      const commentsDir = join(dir, COMMENTS_DIR)
+      mkdirSync(commentsDir)
+      let previous: { createdAt: string; id: string } | null = null
+      for (const comment of taskComments) {
+        // `comments()` sorts by (createdAt, id), so ids must sort in legacy
+        // (rowid) order wherever timestamps tie — and a fresh stem for a
+        // different author can sort *before* the previous one. Chain off the
+        // previous id instead: the collision suffix below then appends `-2`,
+        // which sorts after. The frontmatter stays authoritative for the
+        // author; the filename is only an ordering key.
+        let stem = commentStem(comment.createdAt, comment.author)
+        if (
+          previous &&
+          comment.createdAt === previous.createdAt &&
+          stem.localeCompare(previous.id) < 0
+        ) {
+          stem = previous.id
+        }
+        let id = stem
+        for (let n = 2; existsSync(join(commentsDir, `${id}.md`)); n++) id = `${stem}-${n}`
+        previous = { createdAt: comment.createdAt, id }
+        writeFileSync(
+          join(commentsDir, `${id}.md`),
+          serializeComment({
+            author: comment.author,
+            createdAt: comment.createdAt,
+            body: comment.body,
+          }),
+        )
+        comments++
+      }
+    }
+
+    // Preserve whatever else the config carries; only the version flips.
+    const config = JSON.parse(readFileSync(join(taskDir, CONFIG_FILE), "utf8")) as Record<
+      string,
+      unknown
+    >
+    config.version = 2
+    writeFileSync(join(taskDir, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
+    writeFileSync(join(taskDir, ".gitignore"), GITIGNORE)
+    return { tasks: tasks.length, comments }
+  } finally {
+    legacy.close()
+  }
+}