scribeclock 0.0.0-stage → 0.1.0

package/dist/commands/tasks.js

@@ -0,0 +1,492 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { usageError } from "../cli/errors.js";
+import { changedFiles, currentBranch, gitState, lastCommit, repoRef, githubSlug, remoteUrl } from "../git.js";
+import { EXIT } from "../types.js";
+import { fmtDate, parseWhen, plural, relTime } from "../util/format.js";
+import { PROJECT_FLAG, TASK_POSITIONAL, bool, cmd, emit, guardedEmit, list, num, personName, projectIdArg, resolveProjectId, renderTaskDetail, renderTaskTable, requirePositional, statusPaint, str, taskKey } from "./_shared.js";
+const LIST_FLAGS = [
+    { name: "status", alias: "s", type: "string", description: "open (default), all, pending, in-progress, completed, cancelled", choices: ["open", "all", "pending", "in-progress", "completed", "cancelled"] },
+    { name: "assignee", alias: "a", type: "string", placeholder: "<me|unassigned|name|email>", description: "Whose tasks. Omit for everyone." },
+    { name: "mine", type: "boolean", description: "Shorthand for --assignee me." },
+    { name: "unassigned", type: "boolean", description: "Shorthand for --assignee unassigned." },
+    PROJECT_FLAG,
+    { name: "priority", type: "string", choices: ["low", "medium", "high"], description: "Only this priority." },
+    { name: "query", alias: "q", type: "string", description: 'Text in title/description, or "#42".' },
+    { name: "due-before", type: "string", placeholder: "<when>", description: "Due before (ISO, YYYY-MM-DD, today, tomorrow, 7d…)." },
+    { name: "due-after", type: "string", placeholder: "<when>", description: "Due at or after." },
+    { name: "overdue", type: "boolean", description: "Only overdue tasks (due before now)." },
+    { name: "updated-since", type: "string", placeholder: "<when>", description: "Changed since (ISO or relative like 2h, 3d)." },
+    { name: "order", alias: "o", type: "string", choices: ["updated", "created", "due", "priority", "number", "status"], description: "Sort order (default updated)." },
+    { name: "limit", alias: "n", type: "number", description: "Max tasks (default 50, max 200)." },
+    { name: "offset", type: "number", description: "Paging offset." },
+    { name: "deleted", type: "boolean", description: "Include tasks in the Trash." },
+    { name: "ids", type: "boolean", description: "Print only task keys, one per line (for scripts)." },
+];
+function when(v, ctx) {
+    if (typeof v !== "string")
+        return undefined;
+    const d = parseWhen(v, ctx.now());
+    if (!d)
+        throw usageError(`Could not understand the date "${v}".`, "Use YYYY-MM-DD, an ISO timestamp, today, yesterday, tomorrow, or 7d / 2h.");
+    return d.toISOString();
+}
+export const tasksList = cmd({
+    path: "tasks list",
+    group: "Tasks",
+    summary: "List or search tasks (mine, unassigned, overdue, by project…).",
+    tool: "list_tasks",
+    flags: LIST_FLAGS,
+    examples: ["scribeclock tasks list --mine", "scribeclock tasks list --unassigned --priority high", "scribeclock tasks list --overdue --ids", "scribeclock tasks list -q 'login' --status all --json | jq '.tasks[] | {key,title}'"],
+    async run(ctx, inv) {
+        const args = {
+            status: str(inv.flags.status),
+            assignee: inv.flags.mine ? "me" : inv.flags.unassigned ? "unassigned" : str(inv.flags.assignee),
+            project_id: await projectIdArg(ctx, inv),
+            priority: str(inv.flags.priority),
+            query: str(inv.flags.query) ?? inv.positionals.join(" ") ?? undefined,
+            due_before: inv.flags.overdue ? ctx.now().toISOString() : when(inv.flags["due-before"], ctx),
+            due_after: when(inv.flags["due-after"], ctx),
+            updated_since: when(inv.flags["updated-since"], ctx),
+            order_by: str(inv.flags.order),
+            limit: num(inv.flags.limit),
+            offset: num(inv.flags.offset),
+            include_deleted: bool(inv.flags.deleted),
+        };
+        if (args.query === "")
+            delete args.query;
+        const data = await ctx.call("list_tasks", args);
+        const tasks = (data.tasks ?? []);
+        if (inv.flags.ids && !ctx.flags.json) {
+            for (const t of tasks)
+                ctx.out.log(String(t.key ?? t.id));
+            return EXIT.OK;
+        }
+        return emit(ctx, data, () => {
+            renderTaskTable(ctx, tasks, { showAssignee: args.assignee !== "me" });
+            const total = Number(data.total ?? tasks.length);
+            ctx.out.info(ctx.out.dim(`${tasks.length} of ${total} task${total === 1 ? "" : "s"}${data.has_more ? ` · --offset ${Number(data.offset ?? 0) + tasks.length} for more` : ""}`));
+        });
+    },
+});
+export const tasksShow = cmd({
+    path: "tasks show",
+    group: "Tasks",
+    summary: "Everything about one task: detail, comments, attachments, time, GitHub activity.",
+    tool: "get_task",
+    positionals: [TASK_POSITIONAL],
+    flags: [
+        { name: "full", type: "boolean", description: "Print the whole description." },
+        { name: "comments", type: "number", description: "How many comments to fetch (default 50)." },
+    ],
+    examples: ["scribeclock tasks show #731", "scribeclock tasks show auto    # task from the current branch", "scribeclock tasks show 731 --json | jq .task.description"],
+    async run(ctx, inv) {
+        const data = await ctx.call("get_task", { task_id: taskKey(ctx, inv.positionals[0]), comment_limit: num(inv.flags.comments) });
+        return emit(ctx, data, () => renderTaskDetail(ctx, data, { full: Boolean(inv.flags.full) }));
+    },
+});
+const TASK_FIELD_FLAGS = [
+    { name: "description", alias: "d", type: "string", description: "Markdown body (@file.md reads a file)." },
+    PROJECT_FLAG,
+    { name: "priority", type: "string", choices: ["low", "medium", "high"], description: "Priority." },
+    { name: "due", type: "string", placeholder: "<date>", description: "Due date (YYYY-MM-DD, tomorrow, 7d…)." },
+    { name: "assignee", alias: "a", type: "string", placeholder: "<me|name|email|uuid>", description: "Owner (me, a name, an email, a uuid; unassigned to clear)." },
+    { name: "category", type: "string", choices: ["general", "tech", "operations", "finance", "feedback"], description: "Category." },
+    { name: "estimate", type: "number", placeholder: "<hours>", description: "Estimated hours." },
+    { name: "repo", type: "string", placeholder: "<owner/repo>", description: "GitHub repository to link (default: this repo's origin when --link-repo)." },
+];
+function readMaybeFile(v) {
+    if (typeof v !== "string")
+        return undefined;
+    if (v.startsWith("@") && v.length > 1)
+        return readFileSync(v.slice(1), "utf8");
+    return v;
+}
+export const tasksCreate = cmd({
+    path: "tasks create",
+    group: "Tasks",
+    summary: "Create a task: tasks create \"Title\" [--priority high --due tomorrow --assignee me].",
+    tool: "create_task",
+    positionals: [{ name: "title", required: true, description: "Task title." }],
+    flags: [
+        ...TASK_FIELD_FLAGS,
+        { name: "status", type: "string", choices: ["pending", "in-progress"], description: "Initial status (default pending)." },
+        { name: "comment", type: "string", description: "First comment to post." },
+        { name: "link-repo", type: "boolean", description: "Link the current git repository." },
+    ],
+    examples: ['scribeclock tasks create "Fix login redirect" --priority high --assignee me --due tomorrow', 'scribeclock tasks create "Write release notes" -d @notes.md --project "Scribe Clock"'],
+    async run(ctx, inv) {
+        const title = requirePositional(inv, 0, "A title", 'scribeclock tasks create "Fix login redirect"');
+        const due = inv.flags.due ? parseWhen(String(inv.flags.due), ctx.now()) : undefined;
+        if (inv.flags.due && !due)
+            throw usageError(`Could not understand the due date "${String(inv.flags.due)}".`);
+        const data = await ctx.call("create_task", {
+            title,
+            description: readMaybeFile(inv.flags.description),
+            project_id: await projectIdArg(ctx, inv),
+            priority: str(inv.flags.priority),
+            status: str(inv.flags.status),
+            due_date: due ? fmtDate(due.toISOString()) : undefined,
+            assignee: str(inv.flags.assignee),
+            category: str(inv.flags.category),
+            estimated_hours: num(inv.flags.estimate),
+            github_repo_full_name: str(inv.flags.repo) ?? (inv.flags["link-repo"] ? githubSlug(remoteUrl(ctx.cwd)) ?? undefined : undefined),
+            comment: str(inv.flags.comment),
+        });
+        return emit(ctx, data, () => {
+            const t = (data.task ?? data);
+            ctx.out.log(`${ctx.out.green("✓")} Created ${ctx.out.bold(String(t.key ?? ""))} ${String(t.title ?? title)}${t.url ? ctx.out.dim(`  ${String(t.url)}`) : ""}`);
+        });
+    },
+});
+export const tasksUpdate = cmd({
+    path: "tasks update",
+    group: "Tasks",
+    summary: "Edit a task's title, description, priority, due date, project, status or assignee.",
+    tool: "update_task",
+    positionals: [TASK_POSITIONAL],
+    flags: [
+        { name: "title", type: "string", description: "New title." },
+        ...TASK_FIELD_FLAGS,
+        { name: "status", type: "string", choices: ["pending", "in-progress", "completed", "cancelled"], description: "New status." },
+        { name: "clear-due", type: "boolean", description: "Remove the due date." },
+        { name: "clear-project", type: "boolean", description: "Detach from its project." },
+    ],
+    examples: ["scribeclock tasks update #731 --priority medium --due 2026-11-01", "scribeclock tasks update 731 --status in-progress --assignee me"],
+    async run(ctx, inv) {
+        const due = inv.flags.due ? parseWhen(String(inv.flags.due), ctx.now()) : undefined;
+        if (inv.flags.due && !due)
+            throw usageError(`Could not understand the due date "${String(inv.flags.due)}".`);
+        const args = {
+            task_id: taskKey(ctx, inv.positionals[0]),
+            title: str(inv.flags.title),
+            description: readMaybeFile(inv.flags.description),
+            priority: str(inv.flags.priority),
+            due_date: inv.flags["clear-due"] ? null : due ? fmtDate(due.toISOString()) : undefined,
+            project_id: inv.flags["clear-project"] ? null : await resolveProjectId(ctx, str(inv.flags.project)),
+            status: str(inv.flags.status),
+            assignee: inv.flags.assignee === "unassigned" ? null : str(inv.flags.assignee),
+            category: str(inv.flags.category),
+            estimated_hours: num(inv.flags.estimate),
+            github_repo_full_name: str(inv.flags.repo),
+        };
+        const changes = Object.entries(args).filter(([k, v]) => k !== "task_id" && v !== undefined);
+        if (!changes.length)
+            throw usageError("Nothing to change.", "Pass at least one of --title, --description, --priority, --due, --project, --status, --assignee…");
+        const data = await ctx.call("update_task", args);
+        return emit(ctx, data, () => {
+            const t = (data.task ?? data);
+            ctx.out.log(`${ctx.out.green("✓")} Updated ${ctx.out.bold(String(t.key ?? args.task_id))}: ${changes.map(([k, v]) => `${k}=${v === null ? "∅" : String(v).slice(0, 40)}`).join(", ")}`);
+        });
+    },
+});
+function simpleTaskAction(path, tool, summary, verb, extraFlags = [], build = () => ({})) {
+    return cmd({
+        path,
+        group: "Tasks",
+        summary,
+        tool,
+        positionals: [TASK_POSITIONAL],
+        flags: [{ name: "comment", alias: "m", type: "string", description: "Note to post on the task." }, ...(extraFlags ?? [])],
+        examples: [`scribeclock ${path} #731`, `scribeclock ${path} auto -m "Picking this up"`],
+        async run(ctx, inv) {
+            const args = { task_id: taskKey(ctx, inv.positionals[0]), comment: str(inv.flags.comment), ...build(inv) };
+            return guardedEmit(ctx, tool, args, (data) => {
+                const t = (data.task ?? data);
+                ctx.out.log(`${ctx.out.green("✓")} ${verb} ${ctx.out.bold(String(t.key ?? args.task_id))}${t.title ? ` ${String(t.title)}` : ""}${t.status ? ` · ${statusPaint(ctx, t.status)}` : ""}`);
+                if (typeof data.hint === "string" && !ctx.out.quiet)
+                    ctx.out.info(ctx.out.dim(data.hint));
+            });
+        },
+    });
+}
+export const tasksClaim = simpleTaskAction("tasks claim", "claim_task", "Assign a task to yourself and mark it in progress.", "Claimed", [{ name: "force", type: "boolean", description: "Take over someone else's task or reopen a closed one." }], (inv) => ({ force: bool(inv.flags.force) }));
+export const tasksRelease = simpleTaskAction("tasks release", "release_task", "Hand a task back to the queue (unassign, back to pending).", "Released");
+export const tasksComplete = cmd({
+    path: "tasks complete",
+    group: "Tasks",
+    summary: 'Mark a task completed with a closing comment: tasks complete #12 -m "what, where, how verified".',
+    tool: "complete_task",
+    positionals: [TASK_POSITIONAL],
+    flags: [{ name: "comment", alias: "m", type: "string", description: "What was done, where (files/PR) and how it was verified." }],
+    examples: ['scribeclock tasks complete #731 -m "Deployed to kisaprint.com; DNS + SSL verified in the browser."', "scribeclock done #731    # runs your checks and attaches evidence first"],
+    async run(ctx, inv) {
+        const args = { task_id: taskKey(ctx, inv.positionals[0]), comment: str(inv.flags.comment) };
+        if (!args.comment)
+            ctx.out.warn("No --comment given; the people following the task will only see the status change.");
+        const data = await ctx.call("complete_task", args);
+        return emit(ctx, data, () => {
+            const t = (data.task ?? data);
+            ctx.out.log(`${ctx.out.green("✓")} Completed ${ctx.out.bold(String(t.key ?? args.task_id))}${t.title ? ` ${String(t.title)}` : ""}`);
+        });
+    },
+});
+export const tasksDelete = simpleTaskAction("tasks delete", "delete_task", "Move a task to the Trash (asks for confirmation; restorable).", "Deleted");
+export const tasksRestore = simpleTaskAction("tasks restore", "restore_task", "Bring a task back from the Trash.", "Restored");
+export const tasksComment = cmd({
+    path: "tasks comment",
+    group: "Tasks",
+    summary: 'Post a comment on a task: tasks comment #12 "text" (or pipe it in).',
+    tool: "add_task_comment",
+    positionals: [TASK_POSITIONAL, { name: "text", description: "Comment body (omit to read stdin; @file.md reads a file)." }],
+    examples: ['scribeclock tasks comment #731 "Domain purchased, DNS propagating."', "git log -1 --format=%B | scribeclock tasks comment #731"],
+    async run(ctx, inv) {
+        let body = readMaybeFile(inv.positionals.slice(1).join(" ")) ?? "";
+        if (!body.trim()) {
+            if (ctx.stdin.isTTY)
+                throw usageError("Comment text is required.", 'Example: scribeclock tasks comment #12 "Done with the API part"');
+            body = readFileSync(0, "utf8").trim();
+        }
+        if (!body)
+            throw usageError("Comment text is empty.");
+        const data = await ctx.call("add_task_comment", { task_id: taskKey(ctx, inv.positionals[0]), body });
+        return emit(ctx, data, () => ctx.out.log(`${ctx.out.green("✓")} Comment posted on ${String(data.task?.key ?? data.task_key ?? inv.positionals[0])}.`));
+    },
+});
+export const tasksComments = cmd({
+    path: "tasks comments",
+    group: "Tasks",
+    summary: "The comment thread of a task, oldest first.",
+    tool: "list_task_comments",
+    positionals: [TASK_POSITIONAL],
+    flags: [{ name: "limit", alias: "n", type: "number", description: "Max comments (default 100)." }],
+    async run(ctx, inv) {
+        const data = await ctx.call("list_task_comments", { task_id: taskKey(ctx, inv.positionals[0]), limit: num(inv.flags.limit) });
+        return emit(ctx, data, () => {
+            const comments = (data.comments ?? []);
+            if (!comments.length)
+                ctx.out.log(ctx.out.dim("No comments yet."));
+            for (const c of comments) {
+                ctx.out.log(`${ctx.out.cyan(personName(c.author ?? c.created_by ?? c.user))} ${ctx.out.dim(fmtDate(String(c.created_at ?? ""), { time: true }))}`);
+                for (const line of String(c.body ?? c.content ?? c.note ?? "").split("\n"))
+                    ctx.out.log(`  ${line}`);
+                ctx.out.log("");
+            }
+        });
+    },
+});
+export const tasksAssign = cmd({
+    path: "tasks assign",
+    group: "Tasks",
+    summary: "Set, add or remove assignees: tasks assign #12 <who> [--add|--remove].",
+    tool: "assign_task",
+    positionals: [TASK_POSITIONAL, { name: "who", required: true, description: "me, a name, an email, a uuid, or unassigned." }],
+    flags: [
+        { name: "add", type: "boolean", description: "Add as a co-assignee instead of replacing the owner." },
+        { name: "remove", type: "boolean", description: "Remove this person." },
+    ],
+    async run(ctx, inv) {
+        const who = requirePositional(inv, 1, "An assignee", "scribeclock tasks assign #12 me");
+        const data = await ctx.call("assign_task", { task_id: taskKey(ctx, inv.positionals[0]), assignee: who === "unassigned" ? null : who, mode: inv.flags.add ? "add" : inv.flags.remove ? "remove" : "replace" });
+        return emit(ctx, data, () => {
+            const t = (data.task ?? data);
+            ctx.out.log(`${ctx.out.green("✓")} ${String(t.key ?? inv.positionals[0])} → ${t.assignees?.length ? t.assignees.map(personName).join(", ") : personName(t.assignee) || "unassigned"}`);
+        });
+    },
+});
+export const tasksAttach = cmd({
+    path: "tasks attach",
+    group: "Tasks",
+    summary: "Upload a screenshot or file and attach it to a task.",
+    tool: "attach_file_to_task",
+    positionals: [TASK_POSITIONAL, { name: "file", required: true, description: "Path of the file to upload (≤ 5 MB in one call; larger files are sent in parts)." }],
+    flags: [{ name: "comment", alias: "m", type: "string", description: "Comment to post with the attachment." }, { name: "name", type: "string", description: "File name to store (default: the file's name)." }],
+    examples: ["scribeclock tasks attach #731 ./screenshots/live-site.png -m 'Site live with SSL'"],
+    async run(ctx, inv) {
+        const path = requirePositional(inv, 1, "A file path", "scribeclock tasks attach #12 screenshot.png");
+        const bytes = readFileSync(path);
+        const filename = str(inv.flags.name) ?? basename(path);
+        const task_id = taskKey(ctx, inv.positionals[0]);
+        const PART = 4 * 1024 * 1024;
+        if (bytes.length <= 5 * 1024 * 1024) {
+            const data = await ctx.call("attach_file_to_task", { task_id, filename, content_base64: bytes.toString("base64"), comment: str(inv.flags.comment) });
+            return emit(ctx, data, () => ctx.out.log(`${ctx.out.green("✓")} Attached ${filename} (${(bytes.length / 1024).toFixed(0)} KB) to ${task_id}.`));
+        }
+        const parts = Math.ceil(bytes.length / PART);
+        const upload_id = `cli-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+        let data = {};
+        for (let i = 0; i < parts; i++) {
+            ctx.out.info(ctx.out.dim(`Uploading part ${i + 1}/${parts}…`));
+            data = await ctx.call("attach_file_to_task", { task_id, filename, upload_id, part: i + 1, parts, content_base64: bytes.subarray(i * PART, (i + 1) * PART).toString("base64"), comment: i === parts - 1 ? str(inv.flags.comment) : undefined });
+        }
+        return emit(ctx, data, () => ctx.out.log(`${ctx.out.green("✓")} Attached ${filename} (${(bytes.length / 1024 / 1024).toFixed(1)} MB, ${parts} parts) to ${task_id}.`));
+    },
+});
+export const tasksMatch = cmd({
+    path: "tasks match",
+    group: "Tasks",
+    summary: "Which of my tasks does this work belong to? tasks match \"what I did\".",
+    tool: "match_my_tasks",
+    positionals: [{ name: "work", required: true, description: "A sentence about the work." }],
+    async run(ctx, inv) {
+        const work = inv.positionals.join(" ");
+        if (!work)
+            throw usageError("Describe the work.", 'Example: scribeclock tasks match "fixed the login redirect loop"');
+        const data = await ctx.call("match_my_tasks", { work, repo: repoRef(ctx.cwd) ?? undefined });
+        return emit(ctx, data, () => {
+            const matches = (data.matches ?? []);
+            const confident = data.confident_match;
+            if (confident)
+                ctx.out.log(`${ctx.out.green("Confident match:")} ${String(confident.key)} ${String(confident.title)}`);
+            if (!matches.length)
+                ctx.out.log(ctx.out.dim("No assigned task looks related."));
+            else
+                ctx.out.table(["score", "key", "title", "status"], matches.map((m) => [m.score, m.key, m.title, statusPaint(ctx, m.status)]));
+        });
+    },
+});
+export const tasksRepo = cmd({
+    path: "tasks repo",
+    group: "Tasks",
+    summary: "Tasks for the repository you are in: mine, teammates' in-progress work, unassigned.",
+    tool: "get_repo_tasks",
+    flags: [{ name: "repo", type: "string", description: "Repository (default: this folder's origin)." }, { name: "limit", alias: "n", type: "number", description: "Per section (default 25)." }],
+    async run(ctx, inv) {
+        const repo = str(inv.flags.repo) ?? repoRef(ctx.cwd) ?? undefined;
+        const data = await ctx.call("get_repo_tasks", { repo, limit: num(inv.flags.limit) });
+        return emit(ctx, data, () => {
+            const r = data.repo;
+            ctx.out.log(`${ctx.out.bold("Repository")} ${String(r?.full_name ?? r?.name ?? repo ?? "(none)")}${r?.matched === false ? ctx.out.dim(" — not linked to any project") : ""}`);
+            const projects = (data.matched_projects ?? []);
+            if (projects.length)
+                ctx.out.log(ctx.out.dim(`Projects: ${projects.map((p) => String(p.name)).join(", ")}`));
+            const section = (title, tasks) => {
+                const arr = Array.isArray(tasks) ? tasks : Array.isArray(tasks?.tasks) ? tasks.tasks : [];
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold(`${title} (${arr.length})`));
+                renderTaskTable(ctx, arr, { showProject: true });
+            };
+            section("My tasks", data.my_tasks);
+            section("Teammates in progress", data.teammates_in_progress);
+            section("Teammates queued", data.teammates_queued);
+            section("Unassigned", data.unassigned);
+            section("Recently completed", data.recently_completed);
+            if (typeof data.hint === "string")
+                ctx.out.info(ctx.out.dim(data.hint));
+        });
+    },
+});
+export const tasksWorkload = cmd({
+    path: "tasks workload",
+    group: "Tasks",
+    summary: "Who is working on what: in progress, queued and overdue per person, plus the unassigned backlog.",
+    tool: "get_workload",
+    flags: [PROJECT_FLAG, { name: "unassigned", alias: "n", type: "number", description: "How many unassigned tasks to list (default 30)." }],
+    async run(ctx, inv) {
+        const data = await ctx.call("get_workload", { project_id: await projectIdArg(ctx, inv), unassigned_limit: num(inv.flags.unassigned) });
+        return emit(ctx, data, () => {
+            const people = (data.people ?? []);
+            ctx.out.table(["person", "in progress", "queued", "overdue", "working on"], people.map((p) => [personName(p.assignee) + (p.is_me ? ctx.out.dim(" (me)") : ""), p.in_progress_count ?? p.in_progress?.length ?? 0, p.pending_count ?? 0, Number(p.overdue_count ?? 0) ? ctx.out.red(String(p.overdue_count)) : "0", (p.in_progress ?? []).map((t) => String(t.key)).join(", ")]));
+            const un = data.unassigned;
+            if (un) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold(`Unassigned backlog (${String(un.count)})`));
+                renderTaskTable(ctx, (un.tasks ?? []), { showAssignee: false, showProject: false });
+            }
+        });
+    },
+});
+export const tasksStale = cmd({
+    path: "tasks stale",
+    group: "Tasks",
+    summary: "Open tasks nobody has touched for N days (default 14) — for nightly reports.",
+    tool: "list_tasks",
+    flags: [{ name: "days", alias: "d", type: "number", description: "Idle threshold in days.", default: 14 }, PROJECT_FLAG, { name: "assignee", alias: "a", type: "string", description: "Only this person's tasks." }, { name: "limit", alias: "n", type: "number", description: "Max tasks to scan (default 200)." }],
+    examples: ["scribeclock tasks stale --days 21", "scribeclock tasks stale --json | jq -r '.tasks[] | \"\\(.key) \\(.title)\"'"],
+    async run(ctx, inv) {
+        const days = Number(inv.flags.days ?? 14);
+        const cutoff = new Date(ctx.now().getTime() - days * 86400000);
+        const data = await ctx.call("list_tasks", { status: "open", order_by: "updated", limit: num(inv.flags.limit) ?? 200, project_id: await projectIdArg(ctx, inv), assignee: str(inv.flags.assignee) });
+        const stale = (data.tasks ?? []).filter((t) => t.updated_at && new Date(String(t.updated_at)) < cutoff);
+        const result = { ok: true, days, cutoff: cutoff.toISOString(), count: stale.length, scanned: (data.tasks ?? []).length, tasks: stale };
+        return emit(ctx, result, () => {
+            ctx.out.log(ctx.out.bold(`${plural(stale.length, "stale task")} (no update for ${days}+ days)`));
+            renderTaskTable(ctx, stale);
+            for (const t of stale.slice(0, 0))
+                void t;
+            if (stale.length)
+                ctx.out.info(ctx.out.dim(`Oldest: ${relTime(String(stale[stale.length - 1].updated_at), ctx.now())}`));
+        });
+    },
+});
+export const membersCommand = cmd({
+    path: "members",
+    group: "Team",
+    summary: "People in the organization with their open / in-progress counts.",
+    tool: "list_members",
+    positionals: [{ name: "query", description: "Filter by name, email or job title." }],
+    flags: [{ name: "limit", alias: "n", type: "number", description: "Max members (default 200)." }],
+    async run(ctx, inv) {
+        const data = await ctx.call("list_members", { query: inv.positionals.join(" ") || undefined, limit: num(inv.flags.limit) });
+        return emit(ctx, data, () => {
+            const members = (data.members ?? []);
+            ctx.out.table(["name", "email", "role", "title", "open", "in progress"], members.map((m) => [String(m.name ?? "") + (m.is_me ? ctx.out.dim(" (me)") : ""), m.email, m.role, m.job_title, m.open_count, m.in_progress_count]));
+        });
+    },
+});
+/** `progress`: report started / progress / completed / blocked with evidence from git. */
+export const progressCommand = cmd({
+    path: "progress",
+    group: "Daily workflow",
+    summary: 'Report progress on a task with evidence: progress #12 "what I did" [--done|--blocked|--started].',
+    description: "Posts a structured update on one of your tasks (report_task_progress). In a git repository the last commit, branch and changed files are attached as evidence automatically and the same note is stored as a team handoff. `--done` marks the task completed (evidence required). The task defaults to the one named in the branch or last commit.",
+    tool: "report_task_progress",
+    positionals: [{ name: "task", description: "Task key, uuid, or auto (default: from git)." }, { name: "summary", description: "What was done, 1–4 sentences (or --summary / stdin)." }],
+    flags: [
+        { name: "summary", alias: "m", type: "string", description: "The update text (alternative to the positional)." },
+        { name: "done", type: "boolean", description: "outcome=completed (marks the task done; evidence required)." },
+        { name: "blocked", type: "boolean", description: "outcome=blocked." },
+        { name: "started", type: "boolean", description: "outcome=started (moves it to in progress)." },
+        { name: "evidence", alias: "e", type: "array", placeholder: "<url|text>", description: "Extra evidence: https links become link/PR/commit items, other text becomes a note." },
+        { name: "remaining", alias: "r", type: "array", description: "What is still needed." },
+        { name: "next", type: "array", description: "Next steps, in order." },
+        { name: "no-git", type: "boolean", description: "Do not attach commit / branch / files from the repository." },
+        { name: "force", type: "boolean", description: "Reopen a completed or cancelled task (only when asked)." },
+    ],
+    examples: ['scribeclock progress #731 "Domain bought, DNS pointed at Pages; waiting for SSL."', 'scribeclock progress auto "Finished the Stripe webhook" --done -e https://github.com/o/r/pull/12', 'scribeclock progress 59 "Need the device logs" --blocked -r "logs from QA"'],
+    async run(ctx, inv) {
+        const first = inv.positionals[0];
+        const looksLikeTask = first !== undefined && (/^#?\d{1,6}$/.test(first) || /^[0-9a-f-]{36}$/i.test(first) || first === "auto");
+        const task_id = taskKey(ctx, looksLikeTask ? first : undefined);
+        let summary = str(inv.flags.summary) ?? inv.positionals.slice(looksLikeTask ? 1 : 0).join(" ");
+        if (!summary && !ctx.stdin.isTTY)
+            summary = readFileSync(0, "utf8").trim();
+        if (!summary || summary.length < 10)
+            throw usageError("Describe what was done (at least 10 characters).", 'Example: scribeclock progress #12 "Implemented the export endpoint and tests."');
+        const outcome = inv.flags.done ? "completed" : inv.flags.blocked ? "blocked" : inv.flags.started ? "started" : "progress";
+        const evidence = [];
+        for (const e of list(inv.flags.evidence) ?? []) {
+            if (/^https?:\/\//.test(e))
+                evidence.push({ kind: /\/pull\/\d+/.test(e) ? "pull_request" : /\/commit\//.test(e) ? "commit" : "link", url: e, title: e.replace(/^https?:\/\//, "").slice(0, 80) });
+            else
+                evidence.push({ kind: "note", detail: e });
+        }
+        const args = { task_id, outcome, summary, evidence, remaining: list(inv.flags.remaining), next_steps: list(inv.flags.next), force: bool(inv.flags.force) };
+        const repo = inv.flags["no-git"] ? null : repoRef(ctx.cwd);
+        if (repo) {
+            const commit = lastCommit(ctx.cwd);
+            const slug = githubSlug(remoteUrl(ctx.cwd));
+            if (commit)
+                evidence.push({ kind: "commit", title: commit.message.slice(0, 80), detail: `${commit.sha.slice(0, 10)} ${commit.message}`.slice(0, 300), url: slug ? `https://github.com/${slug}/commit/${commit.sha}` : undefined });
+            args.repo = repo;
+            args.branch = currentBranch(ctx.cwd) ?? undefined;
+            args.files_changed = changedFiles(ctx.cwd);
+            args.last_commit = commit ? { sha: commit.sha, message: commit.message.slice(0, 300) } : undefined;
+            args.git = gitState(ctx.cwd);
+        }
+        if (outcome === "completed" && !evidence.length)
+            throw usageError("--done needs evidence.", "Add -e <PR or commit url>, -e 'tests passed: 41/41', or run inside the repository so the last commit is attached.");
+        if (!evidence.length)
+            delete args.evidence;
+        const data = await ctx.call("report_task_progress", args);
+        return emit(ctx, data, () => {
+            const t = (data.task ?? {});
+            ctx.out.log(`${ctx.out.green("✓")} ${outcome} reported on ${ctx.out.bold(String(t.key ?? task_id))}${t.title ? ` ${String(t.title)}` : ""}${t.status ? ` · ${statusPaint(ctx, t.status)}` : ""}`);
+            if (evidence.length)
+                ctx.out.info(ctx.out.dim(`${plural(evidence.length, "evidence item")} attached${repo ? `; handoff stored for ${repo}` : ""}.`));
+            if (typeof data.hint === "string")
+                ctx.out.info(ctx.out.dim(data.hint));
+        });
+    },
+});
+export const TASK_COMMANDS = [tasksList, tasksShow, tasksCreate, tasksUpdate, tasksClaim, tasksRelease, tasksComplete, tasksComment, tasksComments, tasksAssign, tasksAttach, tasksDelete, tasksRestore, tasksMatch, tasksRepo, tasksWorkload, tasksStale, membersCommand, progressCommand];