@nickmeriano/task 0.8.0 → 0.9.0

package/src/asks.test.ts

@@ -0,0 +1,355 @@
+/**
+ * Asks (TAS-38): the checklist a person owes a ticket, and everything derived
+ * from it.
+ *
+ * 1. An ask is one file under tickets/<key>/asks/, comment-shaped; `needsHuman`
+ *    is derived from open asks, never stored.
+ * 2. Done is gated: open asks refuse the move, resolving clears it, canceled
+ *    voids without ceremony. A finished ticket can't start owing again —
+ *    addAsk/reopen are refused on done/canceled.
+ * 3. Ordinals are creation-order positions — stable across resolution, the
+ *    handle `task resolve <id> <n>` takes.
+ * 4. `task inbox` answers "what do I owe NOW": open asks on effectively
+ *    in-progress tickets — file status, or a live claim branch, whose ask
+ *    files are read from the branch itself.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { execFile, execFileSync } from "node:child_process"
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { initProject } from "./file-store.ts"
+import type { Ask, Task } from "./types.ts"
+import type { InboxEntry } from "./inbox.ts"
+
+const CLI = fileURLToPath(new URL("./cli.ts", import.meta.url))
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-asks-test-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+interface CliResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+function cli(cwd: string, ...args: string[]): Promise<CliResult> {
+  return new Promise((resolve) => {
+    execFile(
+      process.execPath,
+      ["--experimental-strip-types", CLI, ...args],
+      { cwd },
+      (error, stdout, stderr) => {
+        resolve({ code: error ? ((error as { code?: number }).code ?? 1) : 0, stdout, stderr })
+      },
+    )
+  })
+}
+
+// ── The store-level contract ─────────────────────────────────────────────────
+
+test("an ask is a file; needsHuman derives from it and resolution round-trips", () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "ask board", prefix: "ASK" })
+  const task = store.create({ title: "Wire the webhook", status: "in_progress" })
+  assert.equal(store.get(task.key)!.needsHuman, false)
+
+  const ask = store.addAsk(task.key, "Mint the API token and add it to secrets", "claude")
+  assert.equal(ask.ordinal, 1)
+  assert.equal(ask.resolvedAt, null)
+
+  // One file, comment-shaped, under asks/ — mergeable by construction.
+  const dirPath = join(dir, ".task", "tickets", task.key, "asks")
+  const files = readdirSync(dirPath)
+  assert.equal(files.length, 1)
+  const text = readFileSync(join(dirPath, files[0]), "utf8")
+  assert.match(text, /^---\nauthor: "claude"\ncreated: /)
+  assert.match(text, /Mint the API token/)
+
+  const withAsk = store.get(task.key)!
+  assert.equal(withAsk.needsHuman, true)
+  assert.equal(withAsk.asks.length, 1)
+
+  const resolved = store.resolveAsk(task.key, "1", "nick")
+  assert.equal(resolved.resolvedBy, "nick")
+  assert.notEqual(resolved.resolvedAt, null)
+  assert.equal(store.get(task.key)!.needsHuman, false)
+  assert.match(readFileSync(join(dirPath, files[0]), "utf8"), /resolved_by: "nick"/)
+
+  const reopened = store.reopenAsk(task.key, resolved.id)
+  assert.equal(reopened.resolvedAt, null)
+  assert.equal(store.get(task.key)!.needsHuman, true)
+  store.close()
+})
+
+test("ordinals are creation order and stay put as asks resolve", () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "ask board", prefix: "ASK" })
+  const task = store.create({ title: "Ship it", status: "in_progress" })
+  store.addAsk(task.key, "First owed thing", "claude")
+  store.addAsk(task.key, "Second owed thing", "claude")
+  store.resolveAsk(task.key, "1", "nick")
+
+  const asks = store.asks(task.key)
+  assert.deepEqual(asks.map((a) => a.ordinal), [1, 2])
+  assert.equal(asks[0].resolvedAt !== null, true)
+  assert.equal(asks[1].text, "Second owed thing")
+
+  // The needs-human filter matches the derived flag.
+  assert.deepEqual(store.list({ needsHuman: true }).map((t) => t.key), [task.key])
+  store.close()
+})
+
+test("done is gated on zero open asks; canceled voids them", () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "ask board", prefix: "ASK" })
+  const task = store.create({ title: "Gated", status: "in_progress" })
+  store.addAsk(task.key, "Approve the cutover window", "claude")
+
+  assert.throws(
+    () => store.update(task.key, { status: "done" }),
+    /1 open ask.*done means nobody owes anything/s,
+  )
+
+  // Canceling is allowed with the asks still open — a dead ticket's asks die
+  // with it — and once canceled, no new debt can accrue.
+  store.update(task.key, { status: "canceled" })
+  assert.throws(() => store.addAsk(task.key, "Too late", "claude"), /is canceled/)
+  store.update(task.key, { status: "in_progress" })
+
+  store.resolveAsk(task.key, "1", "nick")
+  const done = store.update(task.key, { status: "done" })
+  assert.equal(done.status, "done")
+
+  // A finished ticket can't quietly start owing things again.
+  assert.throws(() => store.addAsk(task.key, "One more thing", "claude"), /is done/)
+  assert.throws(() => store.reopenAsk(task.key, "1"), /reopening an ask/)
+  store.close()
+})
+
+// ── The CLI surface ──────────────────────────────────────────────────────────
+
+test("task ask / resolve / show: the full loop, exit codes and ordinals", async () => {
+  const dir = tempDir()
+  initProject(dir, { name: "cli board", prefix: "CLI" }).close()
+  const created = await cli(dir, "add", "Needs a person", "--status", "in_progress", "--json")
+  const id = (JSON.parse(created.stdout) as { task: Task }).task.id
+
+  const asked = await cli(dir, "ask", id, "Run setup.sh once the token exists", "--author", "claude")
+  assert.equal(asked.code, 0, asked.stderr)
+  assert.ok(asked.stdout.includes(`asked on ${id} [1]`), asked.stdout)
+
+  const shown = await cli(dir, "show", id, "--json")
+  const { task } = JSON.parse(shown.stdout) as { task: Task }
+  assert.equal(task.needsHuman, true)
+  assert.equal(task.asks[0].author, "claude")
+
+  // Done refuses while the ask is open — the gate speaks CLI too.
+  const blocked = await cli(dir, "move", id, "done")
+  assert.equal(blocked.code, 1)
+  assert.match(blocked.stderr, /open ask/)
+
+  const resolved = await cli(dir, "resolve", id, "1", "--comment", "done, it's in 1Password", "--author", "nick")
+  assert.equal(resolved.code, 0, resolved.stderr)
+  assert.ok(resolved.stdout.includes(`resolved ${id} [1]`), resolved.stdout)
+  assert.match(resolved.stdout, /last open ask/)
+
+  // The note landed as an attributed comment naming the ask.
+  const detail = await cli(dir, "show", id, "--json")
+  const { comments } = JSON.parse(detail.stdout) as { comments: { author: string; body: string }[] }
+  assert.equal(comments.length, 1)
+  assert.equal(comments[0].author, "nick")
+  assert.match(comments[0].body, /Resolved ask \[1\].*1Password/)
+
+  assert.equal((await cli(dir, "move", id, "done")).code, 0)
+  assert.equal((await cli(dir, "resolve", id, "9")).code, 1)
+})
+
+test("task add --ask files asks at creation, commas and all", async () => {
+  const dir = tempDir()
+  initProject(dir, { name: "cli board", prefix: "CLI" }).close()
+  const added = await cli(
+    dir, "add", "Born owing", "--status", "todo",
+    "--ask", "Approve the plan, then the budget",
+    "--ask", "Add STRIPE_SECRET_KEY to the worker",
+    "--json",
+  )
+  assert.equal(added.code, 0, added.stderr)
+  const { task } = JSON.parse(added.stdout) as { task: Task }
+  // One ask per --ask, verbatim — a comma never splits an ask in two.
+  assert.deepEqual(
+    task.asks.map((a: Ask) => a.text),
+    ["Approve the plan, then the budget", "Add STRIPE_SECRET_KEY to the worker"],
+  )
+  assert.equal(task.needsHuman, true)
+})
+
+test("inbox is in-progress only: todo asks wait for their claim", async () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "inbox board", prefix: "INB" })
+  const active = store.create({ title: "Being worked", status: "in_progress" })
+  const queued = store.create({ title: "Waiting its turn", status: "todo" })
+  store.addAsk(active.key, "Upgrade the org to Pro", "claude")
+  store.addAsk(queued.key, "Decide pricing", "claude")
+  store.close()
+
+  // Not a git repo — the resolver degrades silently to file truth.
+  const result = await cli(dir, "inbox", "--json")
+  assert.equal(result.code, 0, result.stderr)
+  const { inbox } = JSON.parse(result.stdout) as { inbox: InboxEntry[] }
+  assert.deepEqual(inbox.map((e) => e.task.key), [active.key])
+  assert.equal(inbox[0].claim, null)
+  assert.equal(inbox[0].asks[0].text, "Upgrade the org to Pro")
+})
+
+// ── The claim-branch read (TAS-26's core) ────────────────────────────────────
+
+function sh(cwd: string, ...args: string[]): string {
+  return execFileSync(args[0], args.slice(1), { cwd, encoding: "utf8" }).trim()
+}
+
+test("a claimed ticket's asks reach the inbox from its branch", async () => {
+  const home = tempDir()
+  const bare = join(home, "origin.git")
+  sh(home, "git", "init", "--quiet", "--bare", "-b", "main", bare)
+
+  const seed = join(home, "seed")
+  sh(home, "git", "clone", "--quiet", bare, seed)
+  sh(seed, "git", "config", "user.name", "Test")
+  sh(seed, "git", "config", "user.email", "test@example.com")
+  const store = initProject(seed, { name: "claim inbox", prefix: "CIN" })
+  const key = store.create({ title: "Agent work with a human side", status: "todo" }).key
+  const branch = `task/claim/cin-${key}`
+  store.close()
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "board")
+  sh(seed, "git", "push", "--quiet", "-u", "origin", "main")
+
+  // Worker: claim (flips the ticket on the branch), file an ask mid-run, push.
+  const worker = join(home, "worker")
+  sh(home, "git", "clone", "--quiet", bare, worker)
+  sh(worker, "git", "config", "user.name", "Worker")
+  sh(worker, "git", "config", "user.email", "worker@example.com")
+  assert.equal((await cli(worker, "claim", key)).code, 0)
+  assert.equal((await cli(worker, "ask", `CIN-${key}`, "Create the OAuth app in the dashboard", "--author", "claude")).code, 0)
+  sh(worker, "git", "add", "-A")
+  sh(worker, "git", "commit", "--quiet", "-m", "ask")
+  sh(worker, "git", "push", "--quiet", "origin", branch)
+
+  // Owner, on a fresh clone of main, where the ticket still reads `todo` and
+  // has no ask files at all: the inbox says what the claim branch knows.
+  const owner = join(home, "owner")
+  sh(home, "git", "clone", "--quiet", bare, owner)
+  sh(owner, "git", "config", "user.name", "Nick")
+  sh(owner, "git", "config", "user.email", "nick@example.com")
+  assert.equal(existsSync(join(owner, ".task", "tickets", key, "asks")), false)
+  const result = await cli(owner, "inbox", "--json")
+  assert.equal(result.code, 0, result.stderr)
+  const { inbox } = JSON.parse(result.stdout) as { inbox: InboxEntry[] }
+  assert.equal(inbox.length, 1)
+  assert.equal(inbox[0].task.status, "todo") // file truth, kept honest
+  assert.equal(inbox[0].claim?.branch, branch)
+  assert.deepEqual(inbox[0].asks.map((a) => a.text), ["Create the OAuth app in the dashboard"])
+
+  // The claim owns the ticket's asks, so the owner's writes land on the
+  // branch as pushed commits — the checkout never switches, the working
+  // tree never grows an ask file.
+  const resolved = await cli(owner, "resolve", `CIN-${key}`, "1", "--author", "nick")
+  assert.equal(resolved.code, 0, resolved.stderr)
+  assert.ok(resolved.stdout.includes(`committed and pushed to ${branch}`), resolved.stdout)
+  assert.equal(existsSync(join(owner, ".task", "tickets", key, "asks")), false)
+  assert.equal(sh(owner, "git", "rev-parse", "--abbrev-ref", "HEAD"), "main")
+
+  // A third clone reads the resolution straight off origin's branch.
+  const verify = join(home, "verify")
+  sh(home, "git", "clone", "--quiet", bare, verify)
+  sh(verify, "git", "fetch", "--quiet", "origin", branch)
+  const askFile = sh(verify, "git", "ls-tree", "--name-only", `FETCH_HEAD:.task/tickets/${key}/asks`)
+  assert.match(
+    sh(verify, "git", "show", `FETCH_HEAD:.task/tickets/${key}/asks/${askFile}`),
+    /resolved_by: "nick"/,
+  )
+  const cleared = await cli(owner, "inbox", "--json")
+  assert.equal((JSON.parse(cleared.stdout) as { inbox: InboxEntry[] }).inbox.length, 0)
+
+  // Adding to a claimed ticket routes to the branch too — the worker's done
+  // gate has to see debt the owner files mid-claim.
+  const added = await cli(owner, "ask", `CIN-${key}`, "Also rotate the old key", "--author", "nick")
+  assert.equal(added.code, 0, added.stderr)
+  assert.ok(added.stdout.includes(`committed and pushed to ${branch}`), added.stdout)
+  assert.equal(existsSync(join(owner, ".task", "tickets", key, "asks")), false)
+  sh(verify, "git", "fetch", "--quiet", "origin", branch)
+  assert.equal(
+    sh(verify, "git", "ls-tree", "--name-only", `FETCH_HEAD:.task/tickets/${key}/asks`).split("\n").length,
+    2,
+  )
+  const again = await cli(owner, "inbox", "--json")
+  const entries = (JSON.parse(again.stdout) as { inbox: InboxEntry[] }).inbox
+  assert.deepEqual(entries[0].asks.map((a) => a.text), ["Also rotate the old key"])
+
+  // And the worker's next tick simply pulls its branch and has everything.
+  sh(worker, "git", "pull", "--quiet", "origin", branch)
+  const workerView = await cli(worker, "show", `CIN-${key}`, "--json")
+  const workerAsks = (JSON.parse(workerView.stdout) as { task: { asks: { text: string; resolvedBy: string | null }[] } }).task.asks
+  assert.deepEqual(
+    workerAsks.map((a) => [a.text, a.resolvedBy]),
+    [["Create the OAuth app in the dashboard", "nick"], ["Also rotate the old key", null]],
+  )
+})
+
+test("branch writes hold up in shallow clones and worktrees", async () => {
+  const home = tempDir()
+  const bare = join(home, "origin.git")
+  sh(home, "git", "init", "--quiet", "--bare", "-b", "main", bare)
+
+  const seed = join(home, "seed")
+  sh(home, "git", "clone", "--quiet", bare, seed)
+  sh(seed, "git", "config", "user.name", "Test")
+  sh(seed, "git", "config", "user.email", "test@example.com")
+  const store = initProject(seed, { name: "envs board", prefix: "ENV" })
+  const key = store.create({ title: "Worked while owed", status: "todo" }).key
+  const branch = `task/claim/env-${key}`
+  store.close()
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "board")
+  sh(seed, "git", "push", "--quiet", "-u", "origin", "main")
+  assert.equal((await cli(seed, "claim", key)).code, 0)
+  assert.equal((await cli(seed, "ask", `ENV-${key}`, "Bless the rollout", "--author", "claude")).code, 0)
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "ask")
+  sh(seed, "git", "push", "--quiet", "origin", branch)
+
+  // Shallow clone — what CI checkouts default to. The plumbing must build
+  // its commit from a fetched claim tip whose history it doesn't have.
+  const shallow = join(home, "shallow")
+  sh(home, "git", "clone", "--quiet", "--depth", "1", `file://${bare}`, shallow)
+  sh(shallow, "git", "config", "user.name", "Nick")
+  sh(shallow, "git", "config", "user.email", "nick@example.com")
+  const resolved = await cli(shallow, "resolve", `ENV-${key}`, "1", "--author", "nick")
+  assert.equal(resolved.code, 0, resolved.stderr)
+  assert.ok(resolved.stdout.includes(`committed and pushed to ${branch}`), resolved.stdout)
+
+  // Worktree — refs shared with the main checkout, index elsewhere.
+  const full = join(home, "full")
+  sh(home, "git", "clone", "--quiet", bare, full)
+  sh(full, "git", "config", "user.name", "Nick")
+  sh(full, "git", "config", "user.email", "nick@example.com")
+  const worktree = join(home, "wt")
+  sh(full, "git", "worktree", "add", "--quiet", "--detach", worktree)
+  const added = await cli(worktree, "ask", `ENV-${key}`, "Sign the SOC2 form", "--author", "nick")
+  assert.equal(added.code, 0, added.stderr)
+  assert.ok(added.stdout.includes(`committed and pushed to ${branch}`), added.stdout)
+
+  // Origin's branch carries both writes; the checkout that made them doesn't.
+  sh(full, "git", "fetch", "--quiet", "origin", branch)
+  const files = sh(full, "git", "ls-tree", "--name-only", `FETCH_HEAD:.task/tickets/${key}/asks`).split("\n")
+  assert.equal(files.length, 2)
+  assert.equal(existsSync(join(shallow, ".task", "tickets", key, "asks")), false)
+  assert.equal(existsSync(join(worktree, ".task", "tickets", key, "asks")), false)
+})