@nickmeriano/task 0.7.0 → 0.8.0

package/src/file-store.ts

@@ -10,23 +10,29 @@ import {
 import { basename, dirname, join } from "node:path"
 import {
   commentStem,
+  isGoalSlug,
   parseComment,
+  parseGoal,
   parseTicket,
   serializeComment,
+  serializeGoal,
   serializeTicket,
+  slugifyGoal,
+  type GoalDoc,
   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,
+  Goal,
+  GoalInput,
+  GoalPatch,
   ProjectConfig,
   Status,
   Task,
@@ -38,8 +44,11 @@ import type {
 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"
+export const TICKET_FILE = "ticket.md"
+export const COMMENTS_DIR = "comments"
+/** One file per goal — `.task/goals/<slug>.md`; archived ones one level down. */
+export const GOALS_DIR = "goals"
+export const GOALS_ARCHIVE_DIR = "archive"
 
 function now(): string {
   return new Date().toISOString()
@@ -79,6 +88,8 @@ export class FileStore implements Store {
   readonly config: ProjectConfig
   private ticketsDir: string
   private archiveDir: string
+  private goalsDir: string
+  private goalsArchiveDir: string
 
   constructor(root: string) {
     this.root = root
@@ -88,6 +99,8 @@ export class FileStore implements Store {
     ) as ProjectConfig
     this.ticketsDir = join(this.taskDir, TICKETS_DIR)
     this.archiveDir = join(this.taskDir, ARCHIVE_DIR)
+    this.goalsDir = join(this.taskDir, GOALS_DIR)
+    this.goalsArchiveDir = join(this.goalsDir, GOALS_ARCHIVE_DIR)
   }
 
   close(): void {}
@@ -184,7 +197,7 @@ export class FileStore implements Store {
       description: ticket.doc.description,
       status: ticket.doc.status,
       tags: ticket.doc.tags,
-      milestone: ticket.doc.milestone,
+      goal: ticket.doc.goal,
       needsHuman: ticket.doc.needsHuman,
       blocks,
       blockedBy: [...ticket.doc.blockedBy].sort((a, b) => a - b),
@@ -200,8 +213,8 @@ export class FileStore implements Store {
       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.goal) {
+      tickets = tickets.filter((t) => t.doc.goal === filter.goal)
     }
     if (filter.needsHuman !== undefined) {
       tickets = tickets.filter((t) => t.doc.needsHuman === filter.needsHuman)
@@ -249,12 +262,15 @@ export class FileStore implements Store {
     // 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"
+    // Dump by default: new tickets land in backlog, the no-quality-bar list;
+    // `todo` (the ready list) is an explicit choice — usually `task promote`.
+    const status = input.status ?? "backlog"
     for (const target of [...(input.blocks ?? []), ...(input.blockedBy ?? [])]) {
       if (!all.some((t) => t.number === target)) {
         throw new Error(`no such task: ${this.displayId(target)}`)
       }
     }
+    if (input.goal) this.assertGoalAssignable(input.goal)
     // 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
@@ -266,7 +282,7 @@ export class FileStore implements Store {
         description: input.description ?? "",
         status,
         tags: input.tags ?? [],
-        milestone: input.milestone ?? null,
+        goal: input.goal ?? null,
         needsHuman: input.needsHuman ?? false,
         blockedBy: [...new Set(input.blockedBy ?? [])].sort((a, b) => a - b),
         prs: input.prs ?? [],
@@ -340,7 +356,10 @@ export class FileStore implements Store {
     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.goal !== undefined) {
+      if (patch.goal) this.assertGoalAssignable(patch.goal)
+      set("goal", patch.goal)
+    }
     if (patch.needsHuman !== undefined) set("needsHuman", patch.needsHuman)
     if (patch.prs !== undefined) set("prs", patch.prs)
     if (patch.status !== undefined) {
@@ -479,6 +498,175 @@ export class FileStore implements Store {
     return this.get(number)!
   }
 
+  // ── Goals ──────────────────────────────────────────────────────────────────
+
+  private goalPath(slug: string, archived: boolean): string {
+    return join(archived ? this.goalsArchiveDir : this.goalsDir, `${slug}.md`)
+  }
+
+  private readGoalDir(archived: boolean): Goal[] {
+    const dir = archived ? this.goalsArchiveDir : this.goalsDir
+    if (!existsSync(dir)) return []
+    const goals: Goal[] = []
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name.startsWith(".")) continue
+      const slug = entry.name.slice(0, -3)
+      const path = join(dir, entry.name)
+      const doc = parseGoal(readFileSync(path, "utf8"), path)
+      goals.push(this.toGoal(slug, doc, archived))
+    }
+    goals.sort((a, b) => a.slug.localeCompare(b.slug))
+    return goals
+  }
+
+  private toGoal(slug: string, doc: GoalDoc, archived: boolean): Goal {
+    return {
+      slug,
+      title: doc.title,
+      description: doc.description,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      // Absent on live goals, so existing payloads carry no new field.
+      ...(archived ? { archived: true } : {}),
+    }
+  }
+
+  goals(archived = false): Goal[] {
+    return this.readGoalDir(archived)
+  }
+
+  getGoal(slug: string): Goal | null {
+    for (const archived of [false, true]) {
+      const path = this.goalPath(slug, archived)
+      if (!existsSync(path)) continue
+      return this.toGoal(slug, parseGoal(readFileSync(path, "utf8"), path), archived)
+    }
+    return null
+  }
+
+  /**
+   * The gate every ticket write goes through: a `goal:` may only reference a
+   * *live* goal. Naming an archived one is refused too — assigning new work to
+   * a goal that's been shelved is the same mistake as editing an archived
+   * ticket, and gets the same answer.
+   */
+  private assertGoalAssignable(slug: string): void {
+    if (existsSync(this.goalPath(slug, false))) return
+    if (existsSync(this.goalPath(slug, true))) {
+      throw new Error(`goal "${slug}" is archived — run \`task goal unarchive ${slug}\` first`)
+    }
+    throw new Error(`no such goal: "${slug}" — create it with \`task goal add\``)
+  }
+
+  private writeGoal(slug: string, doc: GoalDoc, archived: boolean): void {
+    mkdirSync(archived ? this.goalsArchiveDir : this.goalsDir, { recursive: true })
+    writeAtomic(this.goalPath(slug, archived), serializeGoal(doc))
+  }
+
+  createGoal(input: GoalInput): Goal {
+    const title = input.title.trim()
+    if (!title) throw new Error("a goal needs a title")
+    const slug = input.slug ?? slugifyGoal(title)
+    if (!isGoalSlug(slug)) {
+      throw new Error(
+        `invalid goal slug: "${slug}" — lowercase letters, digits and dashes ("archive" is reserved)`,
+      )
+    }
+    if (this.getGoal(slug)) throw new Error(`goal "${slug}" already exists`)
+    const timestamp = now()
+    const doc: GoalDoc = {
+      title,
+      description: input.description ?? "",
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    }
+    this.writeGoal(slug, doc, false)
+    return this.toGoal(slug, doc, false)
+  }
+
+  updateGoal(slug: string, patch: GoalPatch): Goal {
+    const path = this.goalPath(slug, false)
+    if (!existsSync(path)) {
+      if (existsSync(this.goalPath(slug, true))) {
+        throw new Error(`goal "${slug}" is archived — run \`task goal unarchive ${slug}\` first`)
+      }
+      throw new Error(`no such goal: "${slug}"`)
+    }
+    const doc = parseGoal(readFileSync(path, "utf8"), path)
+    if (patch.title !== undefined) {
+      const title = patch.title.trim()
+      if (!title) throw new Error("a goal needs a title")
+      doc.title = title
+    }
+    if (patch.description !== undefined) doc.description = patch.description
+    doc.updatedAt = now()
+    this.writeGoal(slug, doc, false)
+    return this.toGoal(slug, doc, false)
+  }
+
+  /**
+   * A goal leaves the board only after its work has: archiving is refused
+   * while any open task still points here. Done/canceled stragglers are fine —
+   * their references stay readable from the archive either way.
+   */
+  archiveGoal(slug: string): Goal {
+    const path = this.goalPath(slug, false)
+    if (!existsSync(path)) {
+      if (existsSync(this.goalPath(slug, true))) {
+        throw new Error(`goal "${slug}" is already archived`)
+      }
+      throw new Error(`no such goal: "${slug}"`)
+    }
+    const open = this.readAll().filter(
+      (t) => t.doc.goal === slug && t.doc.status !== "done" && t.doc.status !== "canceled",
+    )
+    if (open.length > 0) {
+      const ids = open.map((t) => this.displayId(t.number)).join(", ")
+      throw new Error(`goal "${slug}" still has open tasks (${ids}) — finish or reassign them first`)
+    }
+    mkdirSync(this.goalsArchiveDir, { recursive: true })
+    renameSync(path, this.goalPath(slug, true))
+    return this.getGoal(slug)!
+  }
+
+  unarchiveGoal(slug: string): Goal {
+    const path = this.goalPath(slug, true)
+    if (!existsSync(path)) {
+      throw new Error(
+        existsSync(this.goalPath(slug, false))
+          ? `goal "${slug}" isn't archived`
+          : `no such goal: "${slug}"`,
+      )
+    }
+    mkdirSync(this.goalsDir, { recursive: true })
+    renameSync(path, this.goalPath(slug, false))
+    return this.getGoal(slug)!
+  }
+
+  /**
+   * Deleting is for goals that never happened. Any live reference — whatever
+   * its status — blocks it: pruning organization off finished tickets is a
+   * human call, so the human makes it by clearing the refs first. Archived
+   * tickets' references are left to dangle; every reader tolerates that.
+   */
+  deleteGoal(slug: string): void {
+    const path = this.goalPath(slug, false)
+    if (!existsSync(path)) {
+      if (existsSync(this.goalPath(slug, true))) {
+        throw new Error(`goal "${slug}" is archived — run \`task goal unarchive ${slug}\` first`)
+      }
+      throw new Error(`no such goal: "${slug}"`)
+    }
+    const referencing = this.readAll().filter((t) => t.doc.goal === slug)
+    if (referencing.length > 0) {
+      const ids = referencing.map((t) => this.displayId(t.number)).join(", ")
+      throw new Error(
+        `goal "${slug}" is referenced by ${ids} — clear those with \`task update <id> --goal ""\` first`,
+      )
+    }
+    rmSync(path)
+  }
+
   // ── Comments ───────────────────────────────────────────────────────────────
 
   /**
@@ -549,12 +737,15 @@ export class FileStore implements Store {
   }
 }
 
-// ── Opening, initializing, migrating ─────────────────────────────────────────
+// ── Opening and initializing ─────────────────────────────────────────────────
+
+/** The database a pre-0.6 board committed. Never read anymore, only ignored. */
+const LEGACY_DB_FILE = "tasks.db"
 
 /** 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}
+# around from a pre-0.6 board) is legacy and stays out of git.
+${LEGACY_DB_FILE}
 *.db-journal
 *.db-wal
 *.db-shm
@@ -562,16 +753,22 @@ ${DB_FILE}
 `
 
 /**
- * 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`.
+ * The board in `root`. Text files are the only backend; a board whose state is
+ * still a pre-0.6 committed SQLite database is refused loudly rather than read
+ * as empty — silently starting a parallel text board next to a database full
+ * of tickets is the one failure mode worse than an error.
  */
 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)
+  if (!existsSync(join(taskDir, TICKETS_DIR))) {
+    const config = JSON.parse(readFileSync(join(taskDir, CONFIG_FILE), "utf8")) as ProjectConfig
+    if ((config.version ?? 1) < 2 && existsSync(join(taskDir, LEGACY_DB_FILE))) {
+      throw new Error(
+        "this board still stores its state in a pre-0.6 SQLite database — run `npx @nickmeriano/task@0.6 migrate` once, then retry",
+      )
+    }
+  }
+  return new FileStore(root)
 }
 
 export interface InitOptions {
@@ -600,94 +797,3 @@ export function initProject(root: string, options: InitOptions): Store {
   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()
-  }
-}

package/src/index.ts

@@ -1,7 +1,6 @@
 // Programmatic access to the same store the CLI and `task serve` use — for
 // scripts that want to read or write .task/ without shelling out.
 export {
-  TaskStore,
   boardConfig,
   derivePrefix,
   findBoards,
@@ -16,17 +15,20 @@ export {
   FileStore,
   TICKETS_DIR,
   initProject,
-  migrateBoard,
   openBoard,
 } from "./file-store.ts"
 export {
   parseTicket,
+  parseTicketLenient,
   serializeTicket,
   parseComment,
+  parseCommentLenient,
   serializeComment,
   type TicketDoc,
   type CommentDoc,
 } from "./ticket-doc.ts"
+export { checkBoards, checkRoot, type CheckIssue, type CheckResult } from "./check.ts"
+export { searchStore, type SearchMatch, type SearchResult } from "./search.ts"
 export {
   DEFAULT_CLAIM_PREFIX,
   ClaimError,

package/src/overview.test.ts

@@ -0,0 +1,51 @@
+/**
+ * `task overview` derives everything at read time — these tests pin the
+ * derivations: per-status counts, per-goal progress, needs-human, staleness
+ * against an injected clock, oldest-open, and the "unknown, not zero" answer
+ * for claims when there is no origin to ask.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { initProject } from "./file-store.ts"
+import { STALE_DAYS, buildOverview } from "./overview.ts"
+
+function tempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-overview-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+test("overview derives board health at read time", () => {
+  const root = tempRoot()
+  const store = initProject(root, { name: "health", prefix: "HLT" })
+  store.createGoal({ title: "Launch" })
+  const a = store.create({ title: "Oldest", status: "todo", goal: "launch" })
+  const b = store.create({ title: "Shipped", status: "todo", goal: "launch" })
+  store.update(b.number, { status: "done" })
+  store.create({ title: "Waiting on a person", status: "todo", needsHuman: true })
+  store.create({ title: "Still parked", status: "backlog" })
+
+  // Age the first ticket by hand — the store always writes "now".
+  const ticketPath = join(root, ".task", "tickets", String(a.number), "ticket.md")
+  const aged = readFileSync(ticketPath, "utf8")
+    .replace(/created: .*/, "created: 2020-01-01T00:00:00.000Z")
+    .replace(/updated: .*/, "updated: 2020-01-01T00:00:00.000Z")
+  writeFileSync(ticketPath, aged)
+
+  const overview = buildOverview(store, Date.parse("2020-01-10T00:00:00.000Z") + STALE_DAYS * 86_400_000)
+  assert.equal(overview.board, "health")
+  assert.equal(overview.prefix, "HLT")
+  assert.deepEqual(overview.statuses, { backlog: 1, todo: 2, in_progress: 0, done: 1, canceled: 0 })
+  assert.equal(overview.open, 3)
+  assert.equal(overview.needsHuman, 1)
+  // No origin to ask — unknown, not zero.
+  assert.equal(overview.claimed, null)
+  assert.deepEqual(overview.goals, [{ slug: "launch", title: "Launch", done: 1, total: 2 }])
+  // Only the aged ticket is stale at that clock (the others were written just now).
+  assert.deepEqual(overview.stale.map((t) => t.id), ["HLT-1"])
+  assert.equal(overview.oldestOpen?.id, "HLT-1")
+})

package/src/overview.ts

@@ -0,0 +1,90 @@
+/**
+ * `task overview` — one screen of board health (TAS-27): the numbers an agent
+ * wants before choosing work and the numbers a human wants in a standup.
+ * Nothing configurable, no charts, and nothing stored — every figure is
+ * derived from the board at read time, the same rule goals follow.
+ */
+
+import { claimBranch, claimNamespace, remoteClaims } from "./claim.ts"
+import type { Store } from "./store.ts"
+import { STATUSES, type Status } from "./types.ts"
+
+/** Untouched this long, an open ticket is stale. Fixed on purpose. */
+export const STALE_DAYS = 14
+
+const OPEN_STATUSES: readonly Status[] = ["backlog", "todo", "in_progress"]
+
+export interface GoalProgress {
+  slug: string
+  title: string
+  done: number
+  total: number
+}
+
+export interface TicketRef {
+  id: string
+  title: string
+}
+
+export interface Overview {
+  board: string
+  prefix: string
+  /** Live board only — the archive is history, not health. */
+  statuses: Record<Status, number>
+  open: number
+  needsHuman: number
+  /**
+   * Open tickets whose claim branch exists on origin right now; null when
+   * origin can't be asked (no remote, offline) — unknown, not zero.
+   */
+  claimed: string[] | null
+  goals: GoalProgress[]
+  /** Open tickets untouched for STALE_DAYS+, oldest first. */
+  stale: (TicketRef & { updatedAt: string })[]
+  oldestOpen: (TicketRef & { createdAt: string }) | null
+}
+
+export function buildOverview(store: Store, now: number = Date.now()): Overview {
+  const tasks = store.list({ statuses: undefined })
+  const statuses = Object.fromEntries(STATUSES.map((s) => [s, 0])) as Record<Status, number>
+  for (const task of tasks) statuses[task.status]++
+  const open = tasks.filter((t) => OPEN_STATUSES.includes(t.status))
+
+  let claimed: string[] | null = null
+  try {
+    const branches = remoteClaims(store.root, claimNamespace(store.config))
+    claimed = open
+      .filter((t) => branches.has(claimBranch(store.config, t.number)))
+      .map((t) => t.id)
+  } catch {
+    claimed = null
+  }
+
+  const goals = store.goals().map((goal) => {
+    const mine = tasks.filter((t) => t.goal === goal.slug)
+    const done = mine.filter((t) => t.status === "done" || t.status === "canceled").length
+    return { slug: goal.slug, title: goal.title, done, total: mine.length }
+  })
+
+  const staleBefore = now - STALE_DAYS * 24 * 60 * 60 * 1000
+  const stale = open
+    .filter((t) => Date.parse(t.updatedAt) < staleBefore)
+    .sort((a, b) => Date.parse(a.updatedAt) - Date.parse(b.updatedAt))
+    .map((t) => ({ id: t.id, title: t.title, updatedAt: t.updatedAt }))
+
+  const oldest = [...open].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))[0]
+
+  return {
+    board: store.config.name,
+    prefix: store.config.prefix,
+    statuses,
+    open: open.length,
+    needsHuman: open.filter((t) => t.needsHuman).length,
+    claimed,
+    goals,
+    stale,
+    oldestOpen: oldest
+      ? { id: oldest.id, title: oldest.title, createdAt: oldest.createdAt }
+      : null,
+  }
+}