@nickmeriano/task 0.1.0

package/src/author.ts

@@ -0,0 +1,57 @@
+import { execFileSync } from "node:child_process"
+import process from "node:process"
+
+export type AuthorSource = "flag" | "env" | "git" | "fallback"
+
+export interface Author {
+  name: string
+  source: AuthorSource
+}
+
+export const ANONYMOUS = "anonymous"
+
+/** Resolved at most once per process — git config doesn't change mid-command. */
+const gitNameCache = new Map<string, string | null>()
+
+/**
+ * Ask git who you are. Every way this can fail — git not installed, not a
+ * repository, `user.name` never set — is the same non-answer, so they all
+ * collapse to null rather than being told apart.
+ */
+function gitName(cwd: string): string | null {
+  const cached = gitNameCache.get(cwd)
+  if (cached !== undefined) return cached
+  let name: string | null = null
+  try {
+    const out = execFileSync("git", ["config", "--get", "user.name"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 1000,
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+    name = out.trim() || null
+  } catch {
+    name = null
+  }
+  gitNameCache.set(cwd, name)
+  return name
+}
+
+/**
+ * Who is writing this comment. No config file: git already knows your name and
+ * it's the same one your commits carry, so attribution costs zero setup.
+ *
+ *   --author <who>  →  $TASK_AUTHOR  →  git config user.name  →  "anonymous"
+ *
+ * Agents keep passing `--author claude` explicitly, which is what the first
+ * step is for.
+ */
+export function resolveAuthor(flag?: string, cwd: string = process.cwd()): Author {
+  const flagged = flag?.trim()
+  if (flagged) return { name: flagged, source: "flag" }
+  const env = process.env.TASK_AUTHOR?.trim()
+  if (env) return { name: env, source: "env" }
+  const git = gitName(cwd)
+  if (git) return { name: git, source: "git" }
+  return { name: ANONYMOUS, source: "fallback" }
+}

package/src/cli.ts

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+// The `task` CLI — tasks that live in your repo. Zero dependencies: hand-rolled
+// flag parsing, node:sqlite for storage, plain text out (--json for agents).
+//
+//   task init
+//   task add "Wire up webhooks" --tags api,infra --milestone launch
+//   task list --status todo,in_progress
+//   task start TASK-3 && task done TASK-3
+//   task serve
+
+import { readFileSync } from "node:fs"
+import { basename, join } from "node:path"
+import process from "node:process"
+import { resolveAuthor } from "./author.js"
+import { createTaskServer } from "./server.js"
+import { CONFIG_FILE, TASK_DIR, TaskStore, findBoards, findRoot, initProject } from "./store.js"
+import { STATUSES, isStatus, type Status, type Task, type TaskPatch } from "./types.js"
+
+// node:sqlite still emits an ExperimentalWarning on Node 22 — noise in a CLI
+// that runs it on every invocation. Filter that one warning, keep the rest.
+process.removeAllListeners("warning")
+process.on("warning", (warning) => {
+  if (warning.name !== "ExperimentalWarning") console.error(warning)
+})
+
+const VERSION = "0.1.0"
+const DEFAULT_PORT = 4400
+
+// ── Argument parsing: positionals + --flag value / --flag ────────────────────
+
+interface Args {
+  positional: string[]
+  flags: Record<string, string | boolean>
+}
+
+// Every valueless flag has to be listed here: an unregistered one swallows the
+// next argv token, so `task list --needs-human todo` would silently eat `todo`.
+const BOOLEAN_FLAGS = new Set([
+  "json",
+  "all",
+  "help",
+  "version",
+  "yes",
+  "needs-human",
+  "no-needs-human",
+])
+
+function parseArgs(argv: string[]): Args {
+  const positional: string[] = []
+  const flags: Record<string, string | boolean> = {}
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2)
+      const eq = name.indexOf("=")
+      if (eq >= 0) {
+        flags[name.slice(0, eq)] = name.slice(eq + 1)
+      } else if (BOOLEAN_FLAGS.has(name) || i + 1 >= argv.length || argv[i + 1].startsWith("--")) {
+        flags[name] = true
+      } else {
+        flags[name] = argv[++i]
+      }
+    } else {
+      positional.push(arg)
+    }
+  }
+  return { positional, flags }
+}
+
+function str(flags: Args["flags"], name: string): string | undefined {
+  const v = flags[name]
+  return typeof v === "string" ? v : undefined
+}
+
+function fail(message: string): never {
+  console.error(`error: ${message}`)
+  process.exit(1)
+}
+
+function openStore(): TaskStore {
+  const root = findRoot(process.cwd())
+  if (!root) fail("no .task directory found in this directory or any parent — run `task init` first")
+  return new TaskStore(root)
+}
+
+// ── Input normalization ──────────────────────────────────────────────────────
+
+function parseStatus(value: string): Status {
+  const normalized = value.toLowerCase().replace(/-/g, "_")
+  if (!isStatus(normalized)) fail(`invalid status "${value}" — one of: ${STATUSES.join(", ")}`)
+  return normalized
+}
+
+function parseTags(value: string): string[] {
+  return value.split(",").map((t) => t.trim()).filter(Boolean)
+}
+
+function patchFromFlags(flags: Args["flags"]): TaskPatch {
+  const patch: TaskPatch = {}
+  const title = str(flags, "title")
+  if (title !== undefined) patch.title = title
+  const description = str(flags, "description") ?? str(flags, "desc")
+  if (description !== undefined) patch.description = description
+  const status = str(flags, "status")
+  if (status !== undefined) patch.status = parseStatus(status)
+  const tags = str(flags, "tags") ?? str(flags, "tag")
+  if (tags !== undefined) patch.tags = parseTags(tags)
+  const milestone = str(flags, "milestone")
+  if (milestone !== undefined) patch.milestone = milestone.trim() || null
+  if (flags["needs-human"]) patch.needsHuman = true
+  if (flags["no-needs-human"]) patch.needsHuman = false
+  return patch
+}
+
+// ── Output helpers ───────────────────────────────────────────────────────────
+
+const STATUS_GLYPH: Record<Status, string> = {
+  backlog: "◌",
+  todo: "○",
+  in_progress: "◐",
+  done: "●",
+  canceled: "⊘",
+}
+
+function table(rows: string[][]): void {
+  if (rows.length === 0) return
+  const widths = rows[0].map((_, col) => Math.max(...rows.map((r) => (r[col] ?? "").length)))
+  for (const row of rows) {
+    console.log(row.map((cell, col) => (cell ?? "").padEnd(widths[col])).join("  ").trimEnd())
+  }
+}
+
+function taskRow(t: Task): string[] {
+  // Exactly six cells, always — table() lines columns up by index.
+  return [
+    t.id,
+    `${STATUS_GLYPH[t.status]} ${t.status}`,
+    t.needsHuman ? "⚑" : "",
+    t.title,
+    t.tags.join(","),
+    t.milestone ?? "",
+  ]
+}
+
+function printTask(t: Task): void {
+  console.log(`${t.id}  ${STATUS_GLYPH[t.status]} ${t.status}  ${t.title}`)
+}
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+
+function cmdInit(args: Args): void {
+  const cwd = process.cwd()
+  if (findRoot(cwd) === cwd) fail("already initialized — .task/ exists here")
+  const name = str(args.flags, "name") ?? basename(cwd)
+  const store = initProject(cwd, { name, prefix: str(args.flags, "prefix")?.toUpperCase() })
+  console.log(`Initialized ${store.config.name} (${store.config.prefix}-…) in .task/`)
+
+  console.log(`\nNext:`)
+  console.log(`  task add "My first task"     create a task`)
+  console.log(`  task list                    see what's open`)
+  console.log(`  task serve                   open the board UI`)
+  console.log(`\nCommit .task/ — tasks belong in the repo, next to the code they describe.`)
+  // Deliberately not installed for you: where an agent's skills live differs
+  // per agent and per repo layout, and a task manager guessing at that is how
+  // you end up with a copy somewhere nothing reads. `skill/` ships in this
+  // package — point your agent's skill installer at it.
+  console.log(`Teach your agent the conventions: skill/SKILL.md in this package.`)
+}
+
+function cmdAdd(args: Args): void {
+  const title = args.positional.join(" ").trim()
+  if (!title) fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--milestone …] [--needs-human]`)
+  const store = openStore()
+  const task = store.create({ title, ...patchFromFlags(args.flags) })
+  if (args.flags.json) {
+    console.log(JSON.stringify({ task }, null, 2))
+  } else {
+    printTask(task)
+  }
+}
+
+function cmdList(args: Args): void {
+  const store = openStore()
+  const statusFlag = str(args.flags, "status")
+  const statuses = statusFlag
+    ? statusFlag.split(",").map(parseStatus)
+    : args.flags.all
+      ? undefined
+      : (["backlog", "todo", "in_progress"] as Status[])
+  const tagFlag = str(args.flags, "tags") ?? str(args.flags, "tag")
+  const tasks = store.list({
+    statuses,
+    tags: tagFlag ? parseTags(tagFlag) : undefined,
+    milestone: str(args.flags, "milestone"),
+    needsHuman: args.flags["needs-human"] ? true : undefined,
+  })
+  // Present in board order: grouped by status column, then position.
+  const order = new Map(STATUSES.map((s, i) => [s, i]))
+  tasks.sort((a, b) => order.get(a.status)! - order.get(b.status)! || a.position - b.position)
+  if (args.flags.json) {
+    console.log(JSON.stringify({ tasks }, null, 2))
+  } else if (tasks.length === 0) {
+    console.log(args.flags.all ? "no tasks" : "no open tasks (--all includes done/canceled)")
+  } else {
+    table(tasks.map(taskRow))
+  }
+}
+
+function cmdShow(args: Args): void {
+  const ref = args.positional[0]
+  if (!ref) fail("usage: task show <id>")
+  const store = openStore()
+  const number = store.parseId(ref)
+  const task = store.get(number)
+  if (!task) fail(`no such task: ${store.displayId(number)}`)
+  const comments = store.comments(number)
+  if (args.flags.json) {
+    console.log(JSON.stringify({ task, comments }, null, 2))
+    return
+  }
+  console.log(`${task.id}  ${task.title}`)
+  console.log(`status    ${task.status}`)
+  if (task.needsHuman) console.log(`needs     a human`)
+  if (task.tags.length) console.log(`tags      ${task.tags.join(", ")}`)
+  if (task.milestone) console.log(`milestone ${task.milestone}`)
+  console.log(`created   ${task.createdAt}`)
+  console.log(`updated   ${task.updatedAt}`)
+  if (task.description) console.log(`\n${task.description}`)
+  if (comments.length) {
+    console.log(``)
+    for (const c of comments) {
+      console.log(`— ${c.author || "anonymous"} · ${c.createdAt}`)
+      console.log(`  ${c.body.split("\n").join("\n  ")}`)
+    }
+  }
+}
+
+function cmdUpdate(args: Args, forcedStatus?: Status): void {
+  const ref = args.positional[0]
+  if (!ref) fail("usage: task update <id> [--status …] [--title …] …")
+  const store = openStore()
+  const patch = patchFromFlags(args.flags)
+  if (forcedStatus) patch.status = forcedStatus
+  if (Object.keys(patch).length === 0) fail("nothing to update — pass at least one flag")
+  const task = store.update(store.parseId(ref), patch)
+  if (args.flags.json) {
+    console.log(JSON.stringify({ task }, null, 2))
+  } else {
+    printTask(task)
+  }
+}
+
+function cmdMove(args: Args): void {
+  const [ref, status] = args.positional
+  if (!ref || !status) fail("usage: task move <id> <status>")
+  cmdUpdate({ positional: [ref], flags: { ...args.flags, status } })
+}
+
+function cmdComment(args: Args): void {
+  const [ref, ...rest] = args.positional
+  const body = rest.join(" ").trim()
+  if (!ref || !body) fail(`usage: task comment <id> <text> [--author <who>]`)
+  const store = openStore()
+  const author = resolveAuthor(str(args.flags, "author")).name
+  const comment = store.addComment(store.parseId(ref), body, author)
+  if (args.flags.json) {
+    console.log(JSON.stringify({ comment }, null, 2))
+  } else {
+    console.log(`commented on ${comment.taskId}`)
+  }
+}
+
+const AUTHOR_SOURCE: Record<string, string> = {
+  flag: "--author",
+  env: "$TASK_AUTHOR",
+  git: "git config user.name",
+  fallback: "no name found — set git config user.name or $TASK_AUTHOR",
+}
+
+/** Deliberately never opens the store, so it answers outside a .task/ repo. */
+function cmdWhoami(args: Args): void {
+  const author = resolveAuthor(str(args.flags, "author"))
+  if (args.flags.json) {
+    console.log(JSON.stringify(author, null, 2))
+  } else {
+    console.log(`${author.name}  (${AUTHOR_SOURCE[author.source]})`)
+  }
+}
+
+function cmdDelete(args: Args): void {
+  const ref = args.positional[0]
+  if (!ref) fail("usage: task delete <id>")
+  const store = openStore()
+  const number = store.parseId(ref)
+  store.delete(number)
+  console.log(`deleted ${store.displayId(number)}`)
+}
+
+function cmdServe(args: Args): void {
+  // Serve is the one command that's monorepo-aware: anchor at the nearest
+  // board like every other command, but if there is none, serve whatever
+  // boards live *below* here instead of failing.
+  const serveRoot = findRoot(process.cwd()) ?? process.cwd()
+  const boards = findBoards(serveRoot)
+  if (boards.length === 0) {
+    fail("no .task directory found in this directory, any parent, or below — run `task init` first")
+  }
+  const port = Number(str(args.flags, "port") ?? DEFAULT_PORT)
+  if (!Number.isInteger(port) || port <= 0) fail(`invalid port: ${str(args.flags, "port")}`)
+  const server = createTaskServer(serveRoot)
+  server.on("error", (error: NodeJS.ErrnoException) => {
+    if (error.code === "EADDRINUSE") fail(`port ${port} is in use — try --port <n>`)
+    fail(error.message)
+  })
+  server.listen(port, () => {
+    const boardName = (root: string): string =>
+      (JSON.parse(readFileSync(join(root, TASK_DIR, CONFIG_FILE), "utf8")) as { name: string })
+        .name
+    if (boards.length === 1) {
+      console.log(`${boardName(boards[0].root)} · task board`)
+    } else {
+      console.log(`${boards.length} boards · task board`)
+      for (const board of boards) console.log(`  ${board.id}  ${boardName(board.root)}`)
+    }
+    console.log(`  http://localhost:${port}`)
+    console.log(`Live: edits from any terminal or agent show up as they happen. Ctrl-C to stop.`)
+  })
+}
+
+// ── Help + dispatch ──────────────────────────────────────────────────────────
+
+const HELP = `task — a task manager that lives in your repo
+
+State is a SQLite database in .task/ at the project root. Commit it: tasks and
+their status travel with the code they describe. Any command works from any
+subdirectory (it walks up to find .task/, like git).
+
+Usage
+  task init [--name <name>] [--prefix <PREFIX>]
+  task add <title> [--description <text>] [--status <s>] [--tags <a,b>]
+                   [--milestone <m>] [--needs-human]
+  task list [--status <s1,s2>] [--tag <a,b>] [--milestone <m>]
+            [--needs-human] [--all]
+  task show <id>
+  task update <id> [--title <t>] [--description <text>] [--status <s>]
+                   [--tags <a,b>] [--milestone <m>]
+                   [--needs-human | --no-needs-human]
+  task move <id> <status>       shorthand for update --status
+  task start <id>               → in_progress
+  task done <id>                → done
+  task comment <id> <text> [--author <who>]
+  task delete <id>
+  task whoami                   who your comments are attributed to
+  task serve [--port <n>]       board + table UI with live updates (default port ${DEFAULT_PORT});
+                                serves every board at or below here — in a
+                                monorepo the header becomes a board switcher
+
+Values
+  <id>          TASK-12, or just 12
+  status        ${STATUSES.join("  ")}
+  --tag a,b     matches a task carrying *either* tag
+  --needs-human this can't be finished by an agent alone
+  clearing      --tags "" drops all tags, --milestone "" clears it
+
+Comment authors resolve --author → $TASK_AUTHOR → git config user.name →
+anonymous, so there is nothing to set up. \`task whoami\` shows which one won.
+
+Every read/write command accepts --json for machine-readable output — that's
+the interface AI agents should use.
+`
+
+function main(): void {
+  const [command, ...rest] = process.argv.slice(2)
+  const args = parseArgs(rest)
+
+  if (!command || command === "help" || args.flags.help) {
+    console.log(HELP)
+    return
+  }
+  if (command === "--version" || args.flags.version) {
+    console.log(VERSION)
+    return
+  }
+
+  switch (command) {
+    case "init":
+      return cmdInit(args)
+    case "add":
+      return cmdAdd(args)
+    case "list":
+      return cmdList(args)
+    case "show":
+      return cmdShow(args)
+    case "update":
+      return cmdUpdate(args)
+    case "move":
+      return cmdMove(args)
+    case "start":
+      return cmdUpdate(args, "in_progress")
+    case "done":
+      return cmdUpdate(args, "done")
+    case "comment":
+      return cmdComment(args)
+    case "whoami":
+      return cmdWhoami(args)
+    case "delete":
+      return cmdDelete(args)
+    case "serve":
+      return cmdServe(args)
+    default:
+      fail(`unknown command "${command}" — run \`task help\``)
+  }
+}
+
+try {
+  main()
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error))
+}

package/src/index.ts

@@ -0,0 +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, findRoot, findBoards, initProject, derivePrefix, type BoardRef } from "./store.js"
+export { createTaskServer } from "./server.js"
+export { resolveAuthor, ANONYMOUS, type Author, type AuthorSource } from "./author.js"
+export * from "./types.js"