scribeclock 0.0.0-stage → 0.1.1

package/dist/commands/workflow.js

@@ -0,0 +1,525 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { CliError, usageError } from "../cli/errors.js";
+import { changedFiles, commitsSince, currentBranch, detectTaskKey, gitState, gitUserEmail, githubSlug, lastCommit, remoteUrl, repoRef } from "../git.js";
+import { EXIT } from "../types.js";
+import { endOfDay, fmtDate, fmtDuration, fmtHours, parseWhen, plural, priorityRank, startOfDay, startOfMonth, startOfWeek, toCsv } from "../util/format.js";
+import { PROJECT_FLAG, bool, cmd, emit, list, num, personName, projectIdArg, renderTaskDetail, renderTaskTable, statusPaint, str, taskKey } from "./_shared.js";
+import { renderClockStatus } from "./clock.js";
+/** Calls that are nice-to-have (a missing scope must not break the whole screen). */
+async function optional(ctx, tool, args) {
+    try {
+        return await ctx.call(tool, args);
+    }
+    catch (err) {
+        if (err instanceof CliError && err.code === EXIT.SCOPE) {
+            ctx.out.info(ctx.out.dim(`(${tool} skipped: ${err.message})`));
+            return null;
+        }
+        throw err;
+    }
+}
+async function viewerId(ctx) {
+    const v = await ctx.call("get_viewer", {}, { skipOrg: true });
+    const viewer = (v.viewer ?? {});
+    return { id: typeof viewer.id === "string" ? viewer.id : null, name: typeof viewer.name === "string" ? viewer.name : null, email: typeof viewer.email === "string" ? viewer.email : null };
+}
+export const todayCommand = cmd({
+    path: "today",
+    group: "Daily workflow",
+    summary: "One screen: running timer, what's in progress, due today / overdue, your next meeting.",
+    tool: ["clock_status", "list_tasks", "list_meetings"],
+    flags: [{ name: "all", type: "boolean", description: "Include every open task, not only in-progress / due soon." }],
+    async run(ctx, inv) {
+        const now = ctx.now();
+        const [clock, tasks, meetings] = await Promise.all([
+            ctx.call("clock_status", {}, { skipOrg: true }),
+            ctx.call("list_tasks", { assignee: "me", status: "open", order_by: "due", limit: 200 }),
+            optional(ctx, "list_meetings", { since: startOfDay(now).toISOString(), until: endOfDay(now).toISOString(), limit: 20 }),
+        ]);
+        const all = (tasks.tasks ?? []);
+        const inProgress = all.filter((t) => t.status === "in-progress");
+        const dueSoon = all.filter((t) => t.status !== "in-progress" && t.due_date && new Date(String(t.due_date)) < endOfDay(now));
+        const rest = all.filter((t) => !inProgress.includes(t) && !dueSoon.includes(t));
+        const todays = (meetings?.meetings ?? []).sort((a, b) => String(a.started_at ?? "").localeCompare(String(b.started_at ?? "")));
+        const next = todays.find((m) => m.status === "scheduled" || m.status === "live" || new Date(String(m.started_at ?? 0)) > now) ?? null;
+        const result = { ok: true, date: fmtDate(now.toISOString()), clock, in_progress: inProgress, due: dueSoon, other_open: rest.length, next_meeting: next, meetings_today: todays };
+        return emit(ctx, result, () => {
+            ctx.out.log(ctx.out.bold(`Today · ${fmtDate(now.toISOString())}`));
+            renderClockStatus(ctx, clock);
+            ctx.out.log("");
+            ctx.out.log(ctx.out.bold(`In progress (${inProgress.length})`));
+            renderTaskTable(ctx, inProgress, { showAssignee: false });
+            ctx.out.log("");
+            ctx.out.log(ctx.out.bold(`Due today or overdue (${dueSoon.length})`));
+            renderTaskTable(ctx, dueSoon, { showAssignee: false });
+            if (inv.flags.all && rest.length) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold(`Other open (${rest.length})`));
+                renderTaskTable(ctx, rest, { showAssignee: false });
+            }
+            else if (rest.length)
+                ctx.out.log(ctx.out.dim(`  + ${rest.length} other open task${rest.length === 1 ? "" : "s"} (--all)`));
+            if (meetings) {
+                ctx.out.log("");
+                if (next)
+                    ctx.out.log(`${ctx.out.bold("Next meeting")}  ${fmtDate(String(next.started_at), { time: true })}  ${String(next.title ?? "")}${next.status === "live" ? ctx.out.green(" (live)") : ""}`);
+                else
+                    ctx.out.log(ctx.out.dim(`No more meetings today${todays.length ? ` (${todays.length} earlier)` : ""}.`));
+            }
+            if (!inProgress.length && all.length)
+                ctx.out.info(ctx.out.dim("Nothing in progress — `scribeclock next` suggests what to pick up."));
+        });
+    },
+});
+export const nextCommand = cmd({
+    path: "next",
+    group: "Daily workflow",
+    summary: "Suggest the next task to pick up (in progress first, then priority, due date, age).",
+    tool: "list_tasks",
+    flags: [{ name: "count", alias: "n", type: "number", description: "How many suggestions (default 5).", default: 5 }, { name: "include-unassigned", alias: "u", type: "boolean", description: "Also consider unassigned tasks." }, PROJECT_FLAG],
+    async run(ctx, inv) {
+        const now = ctx.now();
+        const mine = await ctx.call("list_tasks", { assignee: "me", status: "open", order_by: "priority", limit: 200, project_id: await projectIdArg(ctx, inv) });
+        const free = inv.flags["include-unassigned"] ? await ctx.call("list_tasks", { assignee: "unassigned", status: "open", order_by: "priority", limit: 100, project_id: await projectIdArg(ctx, inv) }) : null;
+        const candidates = [...(mine.tasks ?? []).map((t) => ({ t, mine: true })), ...((free?.tasks ?? []).map((t) => ({ t, mine: false })))];
+        const score = (t, isMine) => {
+            let s = 0;
+            const reasons = [];
+            if (t.status === "in-progress") {
+                s += 100;
+                reasons.push("already in progress");
+            }
+            if (isMine)
+                s += 20;
+            else
+                reasons.push("unassigned");
+            const pr = priorityRank(t.priority);
+            s += (3 - pr) * 10;
+            if (t.priority === "high")
+                reasons.push("high priority");
+            if (t.due_date) {
+                const days = (new Date(String(t.due_date)).getTime() - now.getTime()) / 86400000;
+                if (days < 0) {
+                    s += 40;
+                    reasons.push(`overdue ${Math.ceil(-days)}d`);
+                }
+                else if (days < 1) {
+                    s += 30;
+                    reasons.push("due today");
+                }
+                else if (days < 3) {
+                    s += 15;
+                    reasons.push("due soon");
+                }
+            }
+            if (t.created_at)
+                s += Math.min(10, (now.getTime() - new Date(String(t.created_at)).getTime()) / (7 * 86400000));
+            return { score: Math.round(s), reasons };
+        };
+        const ranked = candidates.map(({ t, mine: m }) => ({ ...score(t, m), task: t })).sort((a, b) => b.score - a.score).slice(0, Number(inv.flags.count ?? 5));
+        return emit(ctx, { ok: true, suggestions: ranked.map((r) => ({ key: r.task.key, title: r.task.title, score: r.score, reasons: r.reasons, task: r.task })) }, () => {
+            if (!ranked.length) {
+                ctx.out.log(ctx.out.dim("No open tasks assigned to you. Try --include-unassigned."));
+                return;
+            }
+            ranked.forEach((r, i) => ctx.out.log(`${ctx.out.bold(`${i + 1}. ${String(r.task.key)}`)} ${String(r.task.title)} ${ctx.out.dim(`— ${r.reasons.join(", ") || "next in your queue"}${r.task.project?.name ? ` · ${r.task.project.name}` : ""}`)}`));
+            ctx.out.info(ctx.out.dim(`Start one: scribeclock start ${String(ranked[0].task.key)}`));
+        });
+    },
+});
+export const startCommand = cmd({
+    path: "start",
+    group: "Daily workflow",
+    summary: "Claim a task, clock in against it and print its context, in one step.",
+    tool: ["claim_task", "clock_in", "get_task"],
+    positionals: [{ name: "task", required: true, description: "Task key (#123), uuid, or auto." }],
+    flags: [
+        { name: "comment", alias: "m", type: "string", description: "Note to post when claiming." },
+        { name: "force", type: "boolean", description: "Take over someone else's task." },
+        { name: "no-clock", type: "boolean", description: "Do not clock in." },
+        { name: "branch", type: "boolean", description: "Also create a git branch named from the task (off by default; this repo works on main)." },
+    ],
+    examples: ["scribeclock start #731", "scribeclock start 731 -m 'Taking this today'"],
+    async run(ctx, inv) {
+        const task_id = taskKey(ctx, inv.positionals[0], { allowAuto: false });
+        const claimed = await ctx.call("claim_task", { task_id, comment: str(inv.flags.comment), force: bool(inv.flags.force) });
+        const task = (claimed.task ?? {});
+        const key = String(task.key ?? task_id);
+        ctx.out.info(`${ctx.out.green("✓")} Claimed ${ctx.out.bold(key)}${task.title ? ` ${String(task.title)}` : ""}`);
+        let clock = null;
+        if (!inv.flags["no-clock"]) {
+            clock = await ctx.call("clock_in", { task_id: key.startsWith("#") ? key : task_id }, { skipOrg: true });
+            if (clock.already_clocked_in)
+                ctx.out.info(ctx.out.dim(`Already clocked in since ${fmtDate(String(clock.started_at), { time: true })}.`));
+            else
+                ctx.out.info(`${ctx.out.green("●")} Clocked in${clock.project_name ? ` · ${String(clock.project_name)}` : ""}${clock.task_key ? ` · ${String(clock.task_key)}` : ""}`);
+        }
+        let branch = null;
+        if (inv.flags.branch) {
+            const { branchNameFor } = await import("./gitflow.js");
+            branch = branchNameFor(ctx, { key, title: String(task.title ?? "") });
+            const r = spawnSync("git", ["switch", "-c", branch], { cwd: ctx.cwd, encoding: "utf8" });
+            if (r.status !== 0)
+                ctx.out.warn(`Could not create branch ${branch}: ${(r.stderr || r.stdout).trim()}`);
+            else
+                ctx.out.info(`${ctx.out.green("✓")} On branch ${branch}`);
+        }
+        const detail = await ctx.call("get_task", { task_id: key.startsWith("#") ? key : task_id, comment_limit: 10 });
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: true, claimed, clock, branch, task: detail.task, comments: detail.comments });
+            return EXIT.OK;
+        }
+        ctx.out.log("");
+        renderTaskDetail(ctx, detail);
+        return EXIT.OK;
+    },
+});
+export const inboxCommand = cmd({
+    path: "inbox",
+    group: "Daily workflow",
+    summary: "What is waiting on you: new assignments and comments on your tasks since you last looked.",
+    tool: ["list_tasks", "list_task_comments"],
+    flags: [
+        { name: "since", type: "string", placeholder: "<when>", description: "Look back to this time (default: last `inbox --mark-read`, else 7 days)." },
+        { name: "mark-read", type: "boolean", description: "Remember now as the last time you looked." },
+        { name: "limit", alias: "n", type: "number", description: "Tasks to scan (default 60)." },
+    ],
+    async run(ctx, inv) {
+        const now = ctx.now();
+        const sinceRaw = str(inv.flags.since);
+        const since = sinceRaw ? parseWhen(sinceRaw, now) : ctx.config.read().inbox_last_seen ? new Date(ctx.config.read().inbox_last_seen) : new Date(now.getTime() - 7 * 86400000);
+        if (!since)
+            throw usageError(`Could not understand --since "${sinceRaw}".`);
+        const me = await viewerId(ctx);
+        const tasks = await ctx.call("list_tasks", { assignee: "me", status: "all", updated_since: since.toISOString(), order_by: "updated", limit: num(inv.flags.limit) ?? 60 });
+        const changed = (tasks.tasks ?? []);
+        const assignments = changed.filter((t) => t.assigned_at && new Date(String(t.assigned_at)) >= since && t.assigned_by?.id !== me.id);
+        const commentItems = [];
+        const withComments = changed.filter((t) => Number(t.comment_count ?? 0) > 0).slice(0, 25);
+        const threads = await Promise.all(withComments.map((t) => ctx.call("list_task_comments", { task_id: String(t.id), limit: 30 }).catch(() => null)));
+        threads.forEach((thread, i) => {
+            for (const c of (thread?.comments ?? [])) {
+                const author = (c.author ?? c.created_by ?? c.user);
+                if (new Date(String(c.created_at ?? 0)) >= since && author?.id !== me.id)
+                    commentItems.push({ task: withComments[i], comment: c });
+            }
+        });
+        commentItems.sort((a, b) => String(b.comment.created_at).localeCompare(String(a.comment.created_at)));
+        const mentions = commentItems.filter((c) => me.name && String(c.comment.body ?? c.comment.content ?? "").toLowerCase().includes(`@${me.name.toLowerCase().split(" ")[0]}`));
+        if (inv.flags["mark-read"])
+            ctx.config.write({ inbox_last_seen: now.toISOString() });
+        const result = { ok: true, since: since.toISOString(), assignments, comments: commentItems.map((c) => ({ task_key: c.task.key, task_title: c.task.title, ...c.comment })), mentions: mentions.length, changed_tasks: changed.length };
+        return emit(ctx, result, () => {
+            ctx.out.log(ctx.out.bold(`Inbox since ${fmtDate(since.toISOString(), { time: true })}`));
+            ctx.out.log("");
+            ctx.out.log(ctx.out.bold(`New assignments (${assignments.length})`));
+            renderTaskTable(ctx, assignments, { showAssignee: false });
+            ctx.out.log("");
+            ctx.out.log(ctx.out.bold(`Comments on your tasks (${commentItems.length}${mentions.length ? `, ${mentions.length} mention you` : ""})`));
+            if (!commentItems.length)
+                ctx.out.log(ctx.out.dim("  (none)"));
+            for (const c of commentItems.slice(0, 30)) {
+                ctx.out.log(`  ${ctx.out.cyan(String(c.task.key))} ${personName(c.comment.author ?? c.comment.created_by ?? c.comment.user)} ${ctx.out.dim(fmtDate(String(c.comment.created_at), { time: true }))}`);
+                ctx.out.log(`    ${String(c.comment.body ?? c.comment.content ?? "").split("\n")[0].slice(0, 160)}`);
+            }
+            if (!inv.flags["mark-read"])
+                ctx.out.info(ctx.out.dim("Add --mark-read to start the next inbox from now."));
+        });
+    },
+});
+export const standupCommand = cmd({
+    path: "standup",
+    group: "Daily workflow",
+    summary: "Yesterday / today / blockers from your task updates, commits and meetings — paste it into Slack.",
+    tool: ["list_tasks", "list_task_comments", "list_meetings", "clock_status"],
+    flags: [
+        { name: "since", type: "string", placeholder: "<when>", description: "Start of 'yesterday' (default: yesterday 00:00; use 3d after a weekend)." },
+        { name: "no-git", type: "boolean", description: "Skip commits from the current repository." },
+        { name: "plain", type: "boolean", description: "No Markdown bullets/bold (for plain-text chats)." },
+    ],
+    examples: ["scribeclock standup", "scribeclock standup --since 3d | pbcopy"],
+    async run(ctx, inv) {
+        const now = ctx.now();
+        const since = str(inv.flags.since) ? parseWhen(String(inv.flags.since), now) : (() => {
+            const d = startOfDay(now);
+            d.setDate(d.getDate() - 1);
+            return d;
+        })();
+        if (!since)
+            throw usageError(`Could not understand --since "${String(inv.flags.since)}".`);
+        const me = await viewerId(ctx);
+        const [changed, open, meetings] = await Promise.all([
+            ctx.call("list_tasks", { assignee: "me", status: "all", updated_since: since.toISOString(), order_by: "updated", limit: 100 }),
+            ctx.call("list_tasks", { assignee: "me", status: "open", order_by: "due", limit: 100 }),
+            optional(ctx, "list_meetings", { since: since.toISOString(), until: now.toISOString(), limit: 20 }),
+        ]);
+        const changedTasks = (changed.tasks ?? []);
+        const openTasks = (open.tasks ?? []);
+        const completed = changedTasks.filter((t) => t.status === "completed" && t.completed_at && new Date(String(t.completed_at)) >= since);
+        const worked = changedTasks.filter((t) => !completed.includes(t) && (t.status === "in-progress" || (t.started_at && new Date(String(t.started_at)) >= since)));
+        // My own notes since then (progress reports, comments) say what happened in my words.
+        const threads = await Promise.all(changedTasks.filter((t) => Number(t.comment_count ?? 0) > 0).slice(0, 20).map(async (t) => ({ t, thread: await ctx.call("list_task_comments", { task_id: String(t.id), limit: 20 }).catch(() => null) })));
+        const myNotes = [];
+        for (const { t, thread } of threads) {
+            for (const c of (thread?.comments ?? [])) {
+                const author = (c.author ?? c.created_by ?? c.user);
+                if (author?.id !== me.id || new Date(String(c.created_at ?? 0)) < since)
+                    continue;
+                const text = String(c.body ?? c.content ?? "");
+                myNotes.push({ task: t, text: text.replace(/^Agent update: \w+\s*/i, "").split("\n").find((l) => l.trim()) ?? text, blocked: /blocked/i.test(text) });
+            }
+        }
+        const repo = inv.flags["no-git"] ? null : repoRef(ctx.cwd);
+        const commits = repo ? commitsSince(ctx.cwd, since.toISOString(), { author: gitUserEmail(ctx.cwd) ?? me.email ?? undefined, max: 30 }) : [];
+        const todays = openTasks.filter((t) => t.status === "in-progress" || (t.due_date && new Date(String(t.due_date)) < endOfDay(now))).slice(0, 8);
+        const blockers = [
+            ...myNotes.filter((n) => n.blocked).map((n) => `${String(n.task.key)} ${n.text}`),
+            ...openTasks.filter((t) => t.is_overdue).map((t) => `${String(t.key)} ${String(t.title)} is overdue (due ${fmtDate(String(t.due_date))})`),
+        ];
+        const metTitles = (meetings?.meetings ?? []).map((m) => String(m.title ?? "Meeting"));
+        const b = inv.flags.plain ? "- " : "• ";
+        const bold = (s) => (inv.flags.plain ? s : `*${s}*`);
+        const lines = [];
+        lines.push(bold(`Yesterday${since.getTime() < startOfDay(now).getTime() - 86400000 ? ` (since ${fmtDate(since.toISOString())})` : ""}`));
+        for (const t of completed)
+            lines.push(`${b}✅ ${String(t.key)} ${String(t.title)}`);
+        for (const n of myNotes.filter((n) => !n.blocked && !completed.includes(n.task)))
+            lines.push(`${b}${String(n.task.key)} ${n.text}`);
+        for (const t of worked.filter((t) => !myNotes.some((n) => n.task.id === t.id)))
+            lines.push(`${b}Worked on ${String(t.key)} ${String(t.title)}`);
+        for (const c of commits.slice(0, 8))
+            lines.push(`${b}\`${c.short}\` ${c.message}`);
+        if (commits.length > 8)
+            lines.push(`${b}…and ${commits.length - 8} more commits`);
+        for (const m of metTitles)
+            lines.push(`${b}Meeting: ${m}`);
+        if (lines.length === 1)
+            lines.push(`${b}(no task updates, commits or meetings recorded)`);
+        lines.push("");
+        lines.push(bold("Today"));
+        for (const t of todays)
+            lines.push(`${b}${String(t.key)} ${String(t.title)}${t.status === "in-progress" ? " (in progress)" : t.due_date ? ` (due ${fmtDate(String(t.due_date))})` : ""}`);
+        if (!todays.length)
+            lines.push(`${b}Pick up the next task: scribeclock next`);
+        lines.push("");
+        lines.push(bold("Blockers"));
+        for (const bl of blockers.slice(0, 6))
+            lines.push(`${b}${bl}`);
+        if (!blockers.length)
+            lines.push(`${b}None`);
+        const text = lines.join("\n");
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: true, since: since.toISOString(), yesterday: { completed, notes: myNotes, worked, commits, meetings: metTitles }, today: todays, blockers, text });
+            return EXIT.OK;
+        }
+        ctx.out.log(text);
+        return EXIT.OK;
+    },
+});
+export const timesheetCommand = cmd({
+    path: "timesheet",
+    group: "Time",
+    summary: "Hours per task, project and person for a week / month / range; --csv or --json for invoicing and payroll.",
+    tool: "list_time_entries",
+    flags: [
+        { name: "week", alias: "w", type: "boolean", description: "This week (Monday to now). Default." },
+        { name: "last-week", type: "boolean", description: "Previous Monday–Sunday." },
+        { name: "month", type: "boolean", description: "This month." },
+        { name: "last-month", type: "boolean", description: "Previous month." },
+        { name: "since", type: "string", placeholder: "<when>", description: "Custom start (YYYY-MM-DD, 14d…)." },
+        { name: "until", type: "string", placeholder: "<when>", description: "Custom end (exclusive)." },
+        { name: "person", type: "string", placeholder: "<me|all|name|email>", description: "Whose time (default me; all = team, for admins/staff)." },
+        PROJECT_FLAG,
+        { name: "task", alias: "t", type: "string", description: "Only one task." },
+        { name: "csv", type: "boolean", description: "CSV of the entries to stdout." },
+        { name: "by", type: "string", choices: ["task", "project", "person", "entry"], description: "Which breakdown to print (default: all three summaries)." },
+        { name: "entries", alias: "e", type: "boolean", description: "Also list every entry." },
+        { name: "closed-only", type: "boolean", description: "Exclude the running shift." },
+    ],
+    examples: ["scribeclock timesheet --week", "scribeclock timesheet --last-month --person all --csv > october.csv", "scribeclock timesheet --since 2026-10-01 --until 2026-10-16 --project 'Kisa Print' --json"],
+    async run(ctx, inv) {
+        const now = ctx.now();
+        let since;
+        let until;
+        if (inv.flags["last-week"]) {
+            since = startOfWeek(now);
+            since.setDate(since.getDate() - 7);
+            until = startOfWeek(now);
+        }
+        else if (inv.flags.month)
+            since = startOfMonth(now);
+        else if (inv.flags["last-month"]) {
+            since = startOfMonth(now);
+            since.setMonth(since.getMonth() - 1);
+            until = startOfMonth(now);
+        }
+        else if (inv.flags.since) {
+            const s = parseWhen(String(inv.flags.since), now);
+            if (!s)
+                throw usageError(`Could not understand --since "${String(inv.flags.since)}".`);
+            since = s;
+        }
+        else
+            since = startOfWeek(now);
+        if (inv.flags.until) {
+            const u = parseWhen(String(inv.flags.until), now);
+            if (!u)
+                throw usageError(`Could not understand --until "${String(inv.flags.until)}".`);
+            until = u;
+        }
+        const data = await ctx.call("list_time_entries", {
+            since: since.toISOString(),
+            until: until?.toISOString(),
+            person: str(inv.flags.person),
+            project_id: await projectIdArg(ctx, inv),
+            task_id: str(inv.flags.task) ? taskKey(ctx, String(inv.flags.task)) : undefined,
+            include_open: inv.flags["closed-only"] ? false : undefined,
+            limit: 2000,
+        });
+        const entries = (data.entries ?? []);
+        if (inv.flags.csv) {
+            const rows = entries.map((e) => ({
+                started_at: e.started_at,
+                ended_at: e.ended_at ?? "",
+                hours: e.hours,
+                seconds: e.seconds,
+                person: personName(e.person),
+                email: e.person?.email ?? "",
+                project: e.project?.name ?? "",
+                task_key: e.task?.key ?? "",
+                task: e.task?.title ?? "",
+                billable: e.is_billable,
+                description: e.description ?? "",
+                organization: e.organization?.name ?? "",
+            }));
+            ctx.out.log(toCsv(rows, ["started_at", "ended_at", "hours", "seconds", "person", "email", "project", "task_key", "task", "billable", "description", "organization"]));
+            return EXIT.OK;
+        }
+        return emit(ctx, data, () => {
+            const range = `${fmtDate(since.toISOString())} → ${until ? fmtDate(until.toISOString()) : "now"}`;
+            ctx.out.log(`${ctx.out.bold("Timesheet")} ${range} · ${ctx.out.bold(fmtHours(Number(data.total_seconds ?? 0)))} h in ${plural(Number(data.count ?? entries.length), "entry", "entries")}${data.truncated ? ctx.out.yellow(" (truncated; narrow the range)") : ""}`);
+            const by = str(inv.flags.by);
+            const section = (title, rows, cols) => {
+                if (!rows.length)
+                    return;
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold(title));
+                ctx.out.table(cols.map(([h]) => h), rows.map((r) => cols.map(([, f]) => f(r))));
+            };
+            if (!by || by === "task")
+                section("By task", (data.by_task ?? []), [["task", (r) => r.task_key ?? ""], ["title", (r) => r.title ?? ctx.out.dim("(no task)")], ["project", (r) => r.project_name ?? ""], ["hours", (r) => fmtHours(Number(r.seconds))], ["entries", (r) => r.entries]]);
+            if (!by || by === "project")
+                section("By project", (data.by_project ?? []), [["project", (r) => r.project_name], ["hours", (r) => fmtHours(Number(r.seconds))], ["entries", (r) => r.entries]]);
+            if (!by || by === "person")
+                section("By person", (data.by_person ?? []), [["person", (r) => r.name ?? r.email], ["hours", (r) => fmtHours(Number(r.seconds))], ["entries", (r) => r.entries]]);
+            if (inv.flags.entries || by === "entry")
+                section("Entries", entries, [["start", (e) => fmtDate(String(e.started_at), { time: true })], ["end", (e) => (e.ended_at ? fmtDate(String(e.ended_at), { time: true }) : ctx.out.green("running"))], ["hours", (e) => fmtHours(Number(e.seconds))], ["person", (e) => personName(e.person)], ["project", (e) => e.project?.name ?? ""], ["task", (e) => `${String(e.task?.key ?? "")} ${String(e.task?.title ?? "")}`.trim()], ["note", (e) => e.description ?? ""]]);
+            if (typeof data.hint === "string")
+                ctx.out.info(ctx.out.dim(data.hint));
+        });
+    },
+});
+/** Runs the configured checks (or --check commands) and returns their outcome as evidence items. */
+export async function runChecks(ctx, commands) {
+    const evidence = [];
+    const failed = [];
+    for (const command of commands) {
+        ctx.out.info(ctx.out.dim(`$ ${command}`));
+        const started = Date.now();
+        const r = spawnSync(command, { cwd: ctx.cwd, shell: true, encoding: "utf8", env: ctx.env, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+        const output = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+        const tail = output.trim().split("\n").slice(-25).join("\n").slice(-2500);
+        const ok = r.status === 0;
+        if (!ok)
+            failed.push(command);
+        evidence.push({ kind: "test_result", title: `${ok ? "PASS" : "FAIL"} ${command}`, detail: `exit ${r.status ?? "?"} in ${Math.round((Date.now() - started) / 1000)}s\n${tail}` });
+        if (!ok)
+            ctx.out.error(`${command} failed (exit ${r.status ?? "?"})`);
+        if (tail && (!ok || ctx.flags.debug))
+            ctx.out.info(ctx.out.dim(tail));
+    }
+    return { ok: failed.length === 0, evidence, failed };
+}
+export const doneCommand = cmd({
+    path: "done",
+    group: "Daily workflow",
+    summary: "Run your checks, then complete the task with the evidence attached (test output, commit, PR).",
+    description: "Runs the commands in .scribeclock.json → checks (or --check …), and when they pass reports outcome=completed on the task with the check output, the last commit and the PR (when gh is installed) as evidence. Checks that fail stop the completion (use --skip-checks to complete anyway).",
+    tool: "report_task_progress",
+    positionals: [{ name: "task", description: "Task key, uuid, or auto (default: from git)." }, { name: "summary", description: "What was done (default: built from the last commit message)." }],
+    flags: [
+        { name: "summary", alias: "m", type: "string", description: "Closing summary (what, where, how verified)." },
+        { name: "check", alias: "c", type: "array", description: "Command(s) to run (overrides .scribeclock.json checks)." },
+        { name: "skip-checks", type: "boolean", description: "Complete without running checks." },
+        { name: "evidence", alias: "e", type: "array", description: "Extra evidence links or notes." },
+        { name: "no-git", type: "boolean", description: "Do not attach the commit / branch / PR." },
+        { name: "clock-out", type: "boolean", description: "Also clock out afterwards." },
+    ],
+    examples: ['scribeclock done #731 -m "Site live at kisaprint.com; SSL and checkout verified."', "scribeclock done auto --check 'npm test' --check 'npm run lint'"],
+    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);
+        const commit = inv.flags["no-git"] ? null : lastCommit(ctx.cwd);
+        let summary = str(inv.flags.summary) ?? inv.positionals.slice(looksLikeTask ? 1 : 0).join(" ");
+        if (!summary && commit)
+            summary = `Completed: ${commit.message}`;
+        if (!summary || summary.length < 10)
+            throw usageError("Describe what was done (-m, at least 10 characters).");
+        const checks = list(inv.flags.check) ?? ctx.repo.config.checks ?? [];
+        const evidence = [];
+        if (!inv.flags["skip-checks"] && checks.length) {
+            const result = await runChecks(ctx, checks);
+            evidence.push(...result.evidence);
+            if (!result.ok) {
+                if (ctx.flags.json)
+                    ctx.out.jsonOut({ ok: false, error: "checks_failed", failed: result.failed, evidence: result.evidence });
+                throw new CliError(`${plural(result.failed.length, "check")} failed: ${result.failed.join(", ")}. The task was not completed.`, { id: "checks_failed", hint: "Fix the failures, or pass --skip-checks to complete anyway." });
+            }
+        }
+        else if (!checks.length && !inv.flags["skip-checks"])
+            ctx.out.info(ctx.out.dim("No checks configured (.scribeclock.json → checks, or --check). Completing with git evidence only."));
+        for (const e of list(inv.flags.evidence) ?? [])
+            evidence.push(/^https?:\/\//.test(e) ? { kind: /\/pull\/\d+/.test(e) ? "pull_request" : "link", url: e, title: e.slice(0, 80) } : { kind: "note", detail: e });
+        const repo = inv.flags["no-git"] ? null : repoRef(ctx.cwd);
+        const args = { task_id, outcome: "completed", summary, evidence };
+        if (repo) {
+            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 });
+            const pr = prUrl(ctx);
+            if (pr)
+                evidence.push({ kind: "pull_request", title: "Pull request", url: pr });
+            Object.assign(args, { repo, branch: currentBranch(ctx.cwd) ?? undefined, files_changed: changedFiles(ctx.cwd), last_commit: commit ? { sha: commit.sha, message: commit.message.slice(0, 300) } : undefined, git: gitState(ctx.cwd) });
+        }
+        if (!evidence.length)
+            throw usageError("Completion needs evidence.", "Run inside the repository (the last commit counts), configure checks, or pass -e <url|note>.");
+        if (ctx.flags.dryRun) {
+            ctx.out.log(`${ctx.out.dim("dry run →")} report_task_progress ${JSON.stringify({ ...args, evidence: evidence.map((e) => e.kind) })}`);
+            return EXIT.OK;
+        }
+        const data = await ctx.call("report_task_progress", args);
+        let clock = null;
+        if (inv.flags["clock-out"])
+            clock = await ctx.call("clock_out", { summary }, { skipOrg: true });
+        return emit(ctx, { ...data, clock_out: clock }, () => {
+            const t = (data.task ?? {});
+            ctx.out.log(`${ctx.out.green("✓")} Completed ${ctx.out.bold(String(t.key ?? task_id))}${t.title ? ` ${String(t.title)}` : ""} with ${plural(evidence.length, "evidence item")}.`);
+            if (clock?.was_clocked_in)
+                ctx.out.log(`${ctx.out.green("✓")} Clocked out · ${fmtDuration(Number(clock.duration_seconds ?? 0))}`);
+        });
+    },
+});
+/** The open PR for the current branch, when the GitHub CLI is available. */
+export function prUrl(ctx) {
+    const r = spawnSync("gh", ["pr", "view", "--json", "url", "-q", ".url"], { cwd: ctx.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
+    if (r.status !== 0)
+        return null;
+    const url = (r.stdout ?? "").trim();
+    return /^https?:\/\//.test(url) ? url : null;
+}
+export const WORKFLOW_COMMANDS = [todayCommand, nextCommand, startCommand, inboxCommand, standupCommand, timesheetCommand, doneCommand];
+void readFileSync;
+void detectTaskKey;
+void statusPaint;

package/dist/config.js

@@ -0,0 +1,102 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { EXIT } from "./types.js";
+import { CliError } from "./cli/errors.js";
+export const DEFAULT_ENDPOINT = "https://scribeclock.com/mcp";
+export const DOCS_URL = "https://scribeclock.com/help/mcp-server";
+export const CLI_DOCS_URL = "https://scribeclock.com/help/mcp-server#cli";
+export const SETTINGS_URL = "https://scribeclock.com/dashboard/settings/ai-agents";
+export function configDir(env = process.env) {
+    if (env.SCRIBECLOCK_CONFIG_DIR)
+        return env.SCRIBECLOCK_CONFIG_DIR;
+    const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+    return join(base, "scribeclock");
+}
+/**
+ * Where the MCP endpoint is. `--url` > SCRIBECLOCK_URL > config > default. Accepts a bare host
+ * (https://staging.example.com → https://staging.example.com/mcp), the mcp.scribeclock.com alias,
+ * or a full Supabase function URL.
+ */
+export function resolveEndpoint(flagUrl, env, configured) {
+    const raw = (flagUrl || env.SCRIBECLOCK_URL || configured || DEFAULT_ENDPOINT).trim();
+    const withScheme = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+    const url = new URL(withScheme);
+    // Bearer tokens travel on every request: plain HTTP is only acceptable to a loopback dev server.
+    if (url.protocol === "http:" && !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) {
+        throw new CliError(`Refusing to send tokens over plain HTTP to ${url.host}.`, { code: EXIT.USAGE, id: "insecure_endpoint", hint: "Use https://, or a loopback address (localhost / 127.0.0.1) for local development." });
+    }
+    url.hash = "";
+    url.search = "";
+    let path = url.pathname.replace(/\/+$/, "");
+    if (path === "" && url.hostname !== "mcp.scribeclock.com")
+        path = "/mcp";
+    return `${url.protocol}//${url.host}${path}`;
+}
+/** Credential profile name for an endpoint: one login per server. */
+export function profileFor(endpoint) {
+    const u = new URL(endpoint);
+    const path = u.pathname.replace(/\/+$/, "").replace(/[^a-zA-Z0-9]+/g, "_");
+    return `${u.hostname}${path && path !== "_mcp" ? path : ""}`;
+}
+/** Per-user, non-secret settings (`<configDir>/config.json`). */
+export class ConfigStore {
+    path;
+    cache = null;
+    constructor(dir) {
+        this.path = join(dir, "config.json");
+    }
+    read() {
+        if (this.cache)
+            return this.cache;
+        try {
+            this.cache = JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch {
+            this.cache = {};
+        }
+        return this.cache;
+    }
+    write(patch) {
+        const next = { ...this.read(), ...patch };
+        for (const k of Object.keys(next))
+            if (next[k] === undefined)
+                delete next[k];
+        writeJsonPrivate(this.path, next);
+        this.cache = next;
+        return next;
+    }
+}
+export function readRepoConfig(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 12; i++) {
+        const candidate = join(dir, ".scribeclock.json");
+        if (existsSync(candidate)) {
+            try {
+                return { path: candidate, config: JSON.parse(readFileSync(candidate, "utf8")) };
+            }
+            catch {
+                return { path: candidate, config: {} };
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { path: null, config: {} };
+}
+export function ensureDirPrivate(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+export function writeJsonPrivate(path, value) {
+    ensureDirPrivate(dirname(path));
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* best effort on platforms without POSIX modes */
+    }
+}