@stevecastaneda/paseo-progress 0.1.0

package/dist/server/progress-file.js

@@ -0,0 +1,123 @@
+// Everything that reads or writes a worktree's progress files: the event log
+// the command appends to, the panel-opened marker, and the .gitignore that keeps
+// both out of git. The command and the panel's RPC handlers go through here, so
+// they always agree on where the files are and how they're read.
+import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { EMPTY_DASHBOARD, parseProgress, reduceProgress } from "../shared/dashboard.js";
+import { EVENT_VERSION, eventSchema, PANEL_OPENED_FILE, PROGRESS_FILE } from "../shared/events.js";
+import { withLock } from "./lock.js";
+const SCRATCH_DIR = dirname(PROGRESS_FILE);
+const LOCK_FILE = `${PROGRESS_FILE}.lock`;
+// Names only this plugin's files, so they stay out of git without the user
+// editing their own .gitignore. Other files in .scratch/ are left to the repo.
+export const SCRATCH_GITIGNORE = `# Added by the progress plugin for Paseo so its files stay out of git.
+${basename(PROGRESS_FILE)}
+${basename(LOCK_FILE)}/
+${basename(PANEL_OPENED_FILE)}
+.gitignore
+`;
+// A draft the event schema rejects. The message names each bad field.
+export class InvalidEvent extends Error {
+}
+// The parsed file per worktree, kept until its size or change time moves. The
+// file only grows, and the panel and pills read it every few seconds.
+const parsedFiles = new Map();
+// Replaced file snapshots and their derived data can be collected together.
+const dashboards = new WeakMap();
+// The dashboard at `now`, for the panel, the pills and `show`. Repeated reads
+// reuse the last one until the file changes or a stale or overdue time passes.
+// Stale and overdue checks use the daemon host's clock, the same clock the
+// command stamps events with.
+export async function readProgress(root, now = new Date()) {
+    const parsed = await readParsed(root);
+    const panelOpened = await exists(join(root, PANEL_OPENED_FILE));
+    if (parsed === null)
+        return { configured: false, dashboard: EMPTY_DASHBOARD, panelOpened };
+    let cached = dashboards.get(parsed);
+    // A backwards clock jump must also re-evaluate stale/overdue state.
+    if (!cached || now.getTime() < cached.from || now.getTime() >= cached.until) {
+        const { dashboard, validUntil } = reduceProgress(parsed, now);
+        cached = { dashboard, from: now.getTime(), until: validUntil };
+        dashboards.set(parsed, cached);
+    }
+    return { configured: true, dashboard: cached.dashboard, panelOpened };
+}
+// Appends the one event `write` builds from the file as it is now. Commands
+// that run at once take turns, so each sees the others' events and no two hand
+// out the same id. `write` may throw to append nothing.
+export async function appendProgress(root, now, write) {
+    await prepareScratch(root);
+    return withLock(join(root, LOCK_FILE), async () => {
+        const text = (await readText(root)) ?? "";
+        const { dashboard, nextIds } = reduceProgress(parseProgress(text), now());
+        const { event, result } = write({ dashboard, nextIds });
+        const checked = eventSchema.safeParse({ v: EVENT_VERSION, ts: now().toISOString(), ...withoutUndefined(event) });
+        if (!checked.success) {
+            throw new InvalidEvent(checked.error.issues.map((issue) => `${issue.path.join(".") || "value"}: ${issue.message}`).join("; "));
+        }
+        // A line cut short (a killed command, a hand edit) would swallow this event, so start a new line.
+        const lead = text && !text.endsWith("\n") ? "\n" : "";
+        await appendFile(join(root, PROGRESS_FILE), `${lead}${JSON.stringify(checked.data)}\n`);
+        return result;
+    });
+}
+export async function markPanelOpened(root) {
+    await prepareScratch(root);
+    await writeFile(join(root, PANEL_OPENED_FILE), "");
+}
+// Creates .scratch/ in the worktree and, the first time, its .gitignore. An
+// existing .gitignore is the user's, so it is never touched.
+async function prepareScratch(root) {
+    const directory = join(root, SCRATCH_DIR);
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, ".gitignore"), SCRATCH_GITIGNORE, { flag: "wx" }).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+    });
+}
+async function readText(root) {
+    try {
+        return await readFile(join(root, PROGRESS_FILE), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function readParsed(root) {
+    const info = await stat(join(root, PROGRESS_FILE)).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!info) {
+        parsedFiles.delete(root);
+        return null;
+    }
+    const cached = parsedFiles.get(root);
+    if (cached && cached.size === info.size && cached.mtimeMs === info.mtimeMs && cached.ctimeMs === info.ctimeMs)
+        return cached.parsed;
+    // Stat before reading: if the file grows in between, the next stat won't match and it's read again.
+    const text = await readText(root);
+    if (text === null) {
+        parsedFiles.delete(root);
+        return null;
+    }
+    const parsed = parseProgress(text);
+    parsedFiles.set(root, { size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, parsed });
+    return parsed;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function withoutUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}

package/dist/shared/attachments.js

@@ -0,0 +1,86 @@
+export function deliverableAttachment(deliverable) {
+    return { ref: deliverable.id, title: deliverable.title, path: deliverable.path, url: deliverable.url, kind: deliverable.kind };
+}
+export function questionAttachments(question) {
+    return question.files.map((file, index) => ({
+        ref: `${question.id}.${index + 1}`,
+        title: file.label ?? (file.path ?? file.url ?? "").replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "",
+        path: file.path,
+        url: file.url,
+    }));
+}
+// The attachment a reference names, or null when it names nothing.
+export function findAttachment(dashboard, ref) {
+    const question = ref.match(/^(Q\d+)\./);
+    if (question) {
+        const found = [...dashboard.questions.open, ...dashboard.questions.answered].find((candidate) => candidate.id === question[1]);
+        return (found && questionAttachments(found).find((attachment) => attachment.ref === ref)) ?? null;
+    }
+    const deliverable = dashboard.deliverables.find((candidate) => candidate.id === ref);
+    return deliverable ? deliverableAttachment(deliverable) : null;
+}
+const IMAGE_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+// Plain text shown as-is in the preview dialog, and opened in the browser on
+// the host. HTML is left to the browser either way.
+const TEXT_EXTENSIONS = new Set([".md", ".markdown", ".mdx", ".txt", ".log", ".json", ".jsonl", ".yaml", ".yml", ".csv"]);
+function extension(path) {
+    return path.toLowerCase().match(/\.[a-z0-9]+$/)?.[0] ?? null;
+}
+// The image type of a path by its extension, or null when it isn't an image.
+export function imageMimeType(path) {
+    return IMAGE_TYPES[extension(path) ?? ""] ?? null;
+}
+export function previewKind(path) {
+    if (imageMimeType(path))
+        return "image";
+    return TEXT_EXTENSIONS.has(extension(path) ?? "") ? "text" : null;
+}
+// Whether the preview dialog can show it. Only a browser draws SVG: Paseo's
+// desktop app can, the phone apps' image view can't, so there an SVG opens on
+// the host like any other file.
+export function canPreview(attachment, where) {
+    if (!attachment.path)
+        return false;
+    const kind = previewKind(attachment.path);
+    if (kind === "image" && extension(attachment.path) === ".svg")
+        return where.browser;
+    return kind !== null;
+}
+const KIND_ICON = {
+    file: "File",
+    folder: "Folder",
+    report: "FileChartColumn",
+    screenshot: "Image",
+    link: "Globe",
+};
+// One icon per attachment, the same on every screen. What the agent called a
+// deliverable wins; otherwise the file itself decides.
+export function attachmentIcon(attachment) {
+    if (attachment.kind && attachment.kind !== "file")
+        return KIND_ICON[attachment.kind];
+    if (attachment.url)
+        return "Globe";
+    if (!attachment.path)
+        return "File";
+    const kind = previewKind(attachment.path);
+    return kind === "image" ? "Image" : kind === "text" ? "FileText" : /[\/]$/.test(attachment.path) ? "Folder" : "File";
+}
+// The short name people recognize: a file or folder's own name, or a link's site.
+export function shortName(attachment) {
+    if (attachment.url) {
+        try {
+            return new URL(attachment.url).host.replace(/^www\./, "");
+        }
+        catch {
+            return attachment.url;
+        }
+    }
+    return (attachment.path ?? "").replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "";
+}

package/dist/shared/dashboard.js

@@ -0,0 +1,369 @@
+import { EVENT_VERSION, eventSchema } from "./events.js";
+// Reads the JSONL text. A last line without a newline may be half written by
+// a command that is still running, so it is skipped without an issue.
+export function parseProgress(text) {
+    const events = [];
+    const issues = [];
+    // Whether or not the text ends in a newline, the last split piece is either
+    // empty or unfinished.
+    text.split("\n").slice(0, -1).forEach((raw, index) => {
+        const line = index + 1;
+        if (!raw.trim())
+            return;
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            issues.push({ line, reason: "not valid JSON" });
+            return;
+        }
+        const parsed = eventSchema.safeParse(json);
+        if (parsed.success)
+            events.push({ line, event: parsed.data });
+        else
+            issues.push({ line, reason: describeInvalid(json) });
+    });
+    return { events, issues };
+}
+function describeInvalid(json) {
+    const version = typeof json === "object" && json !== null && "v" in json ? json.v : undefined;
+    if (typeof version === "number" && version !== EVENT_VERSION)
+        return `written by a newer version of the plugin (v${version})`;
+    const type = typeof json === "object" && json !== null && "type" in json ? String(json.type) : null;
+    return type ? `invalid ${type} event` : "not a progress event";
+}
+export const STALE_AFTER_MIN = 15;
+// Every time-dependent rule asks `reached(at)` instead of comparing with `now`
+// itself. Each answer also records the moment it would flip, so `validUntil`
+// is the first millisecond at which the same events can produce a different
+// dashboard, and a new rule can't forget to tell the cache.
+function clock(now) {
+    let validUntil = Infinity;
+    return {
+        reached(at) {
+            if (now.getTime() >= at)
+                return true;
+            validUntil = Math.min(validUntil, at);
+            return false;
+        },
+        get validUntil() {
+            return validUntil;
+        },
+    };
+}
+export function isSettled(ticket) {
+    return ticket.status === "done" || ticket.status === "skipped";
+}
+// Folds the events of the latest run into what the panel shows at `now`, how
+// long that stays true while the events don't change, and the ids new items get.
+// Everything before the last `run.start` belongs to earlier runs and is ignored.
+export function reduceProgress(parsed, now) {
+    const time = clock(now);
+    let start = 0;
+    parsed.events.forEach(({ event }, index) => {
+        if (event.type === "run.start")
+            start = index;
+    });
+    const events = parsed.events.slice(start);
+    const issues = [...parsed.issues];
+    let run = null;
+    const tickets = new Map();
+    const questions = new Map();
+    const deliverables = new Map();
+    const activity = new Map();
+    let ticker = null;
+    const manualStuck = new Map();
+    let updatedAt = null;
+    for (const { line, event } of events) {
+        updatedAt = event.ts;
+        switch (event.type) {
+            case "run.start":
+                run = { title: event.title, subtitle: event.subtitle, itemLabel: event.itemLabel ?? "Ticket", startedAt: event.ts };
+                break;
+            case "run.finish":
+                if (run)
+                    run.finished = { at: event.ts, outcome: event.outcome };
+                ticker = null;
+                break;
+            case "ticket.add":
+                tickets.set(event.id, {
+                    id: event.id,
+                    title: event.title,
+                    estimateMin: event.estimateMin,
+                    status: event.status ?? "not_started",
+                    statusSince: event.ts,
+                    workingSince: event.status === "working" ? event.ts : undefined,
+                    history: [{ at: event.ts, status: event.status ?? "not_started" }],
+                    waitsFor: event.waitsFor,
+                });
+                break;
+            case "ticket.update": {
+                const ticket = tickets.get(event.id);
+                if (!ticket) {
+                    issues.push({ line, reason: `unknown ticket ${event.id}` });
+                    break;
+                }
+                if (event.title !== undefined)
+                    ticket.title = event.title;
+                if (event.estimateMin !== undefined)
+                    ticket.estimateMin = event.estimateMin;
+                const change = { at: event.ts };
+                if (event.status !== undefined && event.status !== ticket.status)
+                    change.status = event.status;
+                if (event.stage !== undefined && event.stage !== (ticket.stage ?? ""))
+                    change.stage = event.stage;
+                if (event.note)
+                    change.note = event.note;
+                if (Object.keys(change).length > 1)
+                    ticket.history.push(change);
+                if (event.status !== undefined && event.status !== ticket.status) {
+                    ticket.status = event.status;
+                    ticket.statusSince = event.ts;
+                    if (event.status === "working")
+                        ticket.workingSince = event.ts;
+                }
+                if (event.stage !== undefined && event.stage !== (ticket.stage ?? "")) {
+                    ticket.stage = event.stage || undefined;
+                    ticket.stageSince = event.stage ? event.ts : undefined;
+                }
+                if (event.note !== undefined)
+                    ticket.note = event.note || undefined;
+                if (event.waitsFor !== undefined)
+                    ticket.waitsFor = event.waitsFor || undefined;
+                break;
+            }
+            case "ticket.remove":
+                if (!tickets.delete(event.id))
+                    issues.push({ line, reason: `unknown ticket ${event.id}` });
+                break;
+            case "question.ask":
+                questions.set(event.id, {
+                    id: event.id,
+                    title: event.title,
+                    question: event.question,
+                    options: event.options ?? [],
+                    default: event.default,
+                    waits: event.waits ?? false,
+                    background: event.background,
+                    files: event.files ?? [],
+                    raisedBy: event.raisedBy,
+                    ticketId: event.ticket,
+                    askedAt: event.ts,
+                });
+                break;
+            case "question.answer": {
+                const question = questions.get(event.id);
+                if (!question)
+                    issues.push({ line, reason: `unknown question ${event.id}` });
+                else
+                    question.answer = { choice: event.choice, words: event.words, changedCourse: event.changedCourse, at: event.ts };
+                break;
+            }
+            case "question.update": {
+                const question = questions.get(event.id);
+                if (!question) {
+                    issues.push({ line, reason: `unknown question ${event.id}` });
+                    break;
+                }
+                if (event.question !== undefined)
+                    question.question = event.question;
+                if (event.background !== undefined)
+                    question.background = event.background;
+                if (event.files !== undefined)
+                    question.files = [...question.files, ...event.files];
+                break;
+            }
+            case "question.remove":
+                if (!questions.delete(event.id))
+                    issues.push({ line, reason: `unknown question ${event.id}` });
+                break;
+            case "deliverable.add":
+                deliverables.set(event.id, {
+                    id: event.id,
+                    title: event.title,
+                    path: event.path,
+                    url: event.url,
+                    ticketId: event.ticket,
+                    kind: event.kind,
+                    addedAt: event.ts,
+                });
+                break;
+            case "deliverable.remove":
+                if (!deliverables.delete(event.id))
+                    issues.push({ line, reason: `unknown deliverable ${event.id}` });
+                break;
+            case "activity.add":
+                activity.set(event.id, { id: event.id, text: event.text, ticketId: event.ticket, at: event.ts });
+                break;
+            case "activity.update": {
+                const entry = activity.get(event.id);
+                if (!entry)
+                    issues.push({ line, reason: `unknown activity ${event.id}` });
+                else
+                    Object.assign(entry, { text: event.text, editedAt: event.ts });
+                break;
+            }
+            case "activity.remove":
+                if (!activity.delete(event.id))
+                    issues.push({ line, reason: `unknown activity ${event.id}` });
+                break;
+            case "ticker.set":
+                ticker = { text: event.text, since: event.ts };
+                break;
+            case "ticker.clear":
+                ticker = null;
+                break;
+            case "stuck.set":
+                manualStuck.set(event.id, { id: event.id, reason: event.reason, ticket: event.ticket, since: event.ts });
+                break;
+            case "stuck.clear":
+                if (!manualStuck.delete(event.id))
+                    issues.push({ line, reason: `unknown stuck item ${event.id}` });
+                break;
+        }
+    }
+    const list = [...tickets.values()];
+    for (const ticket of list) {
+        const other = ticket.waitsFor ? tickets.get(ticket.waitsFor) : undefined;
+        ticket.waitingFor = other && !isSettled(other) && !isSettled(ticket)
+            ? { id: other.id, title: other.title }
+            : undefined;
+    }
+    const itemLabel = run?.itemLabel ?? "Ticket";
+    const stuck = stuckItems(list, [...activity.values()], [...manualStuck.values()], time.reached);
+    const allQuestions = [...questions.values()];
+    const open = allQuestions.filter((question) => !question.answer);
+    // A finished run has nothing left to stall, so it never goes stale.
+    const finished = Boolean(run?.finished) || (list.length > 0 && list.every(isSettled));
+    const answered = allQuestions
+        .filter((question) => question.answer)
+        .sort((a, b) => Date.parse(b.answer.at) - Date.parse(a.answer.at));
+    const dashboard = {
+        run,
+        updatedAt,
+        stale: !finished && updatedAt !== null && time.reached(Date.parse(updatedAt) + STALE_AFTER_MIN * 60_000),
+        headline: headline(list, itemLabel, open.length, stuck.length),
+        stuck,
+        questions: { open, answered },
+        activity: [...activity.values()].reverse(),
+        ticker,
+        deliverables: [...deliverables.values()].reverse().map((deliverable) => {
+            const ticket = deliverable.ticketId ? tickets.get(deliverable.ticketId) : undefined;
+            return ticket ? { ...deliverable, ticketLabel: shortTitle(ticket.title) } : deliverable;
+        }),
+        progress: progress(list, run?.startedAt),
+        tickets: list,
+        issues: issues.sort((a, b) => a.line - b.line),
+    };
+    return { dashboard, validUntil: time.validUntil, nextIds: nextIds(parsed.events.map(({ event }) => event), events.map(({ event }) => event)) };
+}
+function nextIds(all, inRun) {
+    const used = (events, type) => events.flatMap((event) => (event.type === type && "id" in event ? [event.id] : []));
+    return {
+        ticket: nextId("T", used(inRun, "ticket.add")),
+        question: nextId("Q", used(all, "question.ask"), 1),
+        deliverable: nextId("D", used(inRun, "deliverable.add"), 1),
+        activity: nextId("A", used(inRun, "activity.add"), 1),
+        stuck: nextId("S", used(inRun, "stuck.set"), 1),
+    };
+}
+function progress(tickets, startedAt) {
+    const counted = tickets.filter((ticket) => ticket.status !== "skipped");
+    const totalMin = counted.reduce((sum, ticket) => sum + ticket.estimateMin, 0);
+    const doneMin = counted.filter((ticket) => ticket.status === "done").reduce((sum, ticket) => sum + ticket.estimateMin, 0);
+    // All done: the last ticket to settle, done or skipped, ended the work.
+    const allDone = counted.length > 0 && counted.every((ticket) => ticket.status === "done") && tickets.every(isSettled);
+    const endedAt = Math.max(...tickets.map((ticket) => Date.parse(ticket.statusSince)));
+    return {
+        percent: totalMin ? Math.round((doneMin / totalMin) * 100) : 0,
+        doneMin,
+        totalMin,
+        tookMin: allDone && startedAt ? Math.max(0, (endedAt - Date.parse(startedAt)) / 60_000) : undefined,
+        segments: counted.map(({ id, estimateMin, status, waitingFor }) => ({ id, estimateMin, status, waiting: Boolean(waitingFor) })),
+    };
+}
+function lastTicketUpdate(ticket, activity) {
+    return Math.max(...ticket.history.map((change) => Date.parse(change.at)), ...activity.filter((entry) => entry.ticketId === ticket.id).map((entry) => Date.parse(entry.at)));
+}
+function stuckItems(tickets, activity, manual, reached) {
+    const items = [];
+    for (const ticket of tickets) {
+        // Blocked only on another ticket in the run is waiting, not stuck.
+        if (ticket.status === "blocked" && !ticket.waitingFor) {
+            items.push({ kind: "blocked", key: `blocked:${ticket.id}`, ticketId: ticket.id, title: ticket.title, since: ticket.statusSince, note: ticket.note });
+        }
+        else if (ticket.status === "working") {
+            // Any sign of work resets the clock: a status, stage or note change, or activity tagged to the ticket.
+            const lastUpdate = lastTicketUpdate(ticket, activity);
+            // Overdue once more than the estimate has passed, so a millisecond after it.
+            if (reached(lastUpdate + ticket.estimateMin * 60_000 + 1)) {
+                items.push({
+                    kind: "overdue",
+                    key: `overdue:${ticket.id}`,
+                    ticketId: ticket.id,
+                    title: ticket.title,
+                    since: new Date(lastUpdate).toISOString(),
+                    estimateMin: ticket.estimateMin,
+                });
+            }
+        }
+    }
+    for (const item of manual) {
+        const ticket = item.ticket ? tickets.find((candidate) => candidate.id === item.ticket) : undefined;
+        items.push({
+            kind: "manual",
+            key: `manual:${item.id}`,
+            id: item.id,
+            ticketId: item.ticket,
+            title: ticket?.title ?? item.reason,
+            reason: item.reason,
+            since: item.since,
+        });
+    }
+    return items;
+}
+// "Ticket 03: Frozen links survive deletes" → "Ticket 03".
+export function shortTitle(title) {
+    const index = title.indexOf(":");
+    return index > 0 && index <= 24 ? title.slice(0, index) : title;
+}
+function plural(count, noun) {
+    return `${count} ${count === 1 ? noun : `${noun}s`}`;
+}
+function headline(tickets, itemLabel, waiting, stuck) {
+    const counted = tickets.filter((ticket) => ticket.status !== "skipped");
+    const done = counted.filter((ticket) => ticket.status === "done").length;
+    const parts = [{ text: `${done} of ${plural(counted.length, itemLabel.toLowerCase())} done`, tone: "normal" }];
+    if (waiting)
+        parts.push({ text: `${plural(waiting, "question")} waiting for you`, tone: "normal" });
+    if (stuck)
+        parts.push({ text: `${stuck} stuck`, tone: "danger" });
+    return parts;
+}
+export function headlineText(dashboard) {
+    return dashboard.headline.map((part) => part.text).join(", ");
+}
+function nextId(prefix, used, width = 2) {
+    let max = 0;
+    for (const id of used) {
+        const match = new RegExp(`^${prefix}(\\d+)$`).exec(id);
+        if (match)
+            max = Math.max(max, Number(match[1]));
+    }
+    return `${prefix}${String(max + 1).padStart(width, "0")}`;
+}
+export const EMPTY_DASHBOARD = {
+    run: null,
+    updatedAt: null,
+    stale: false,
+    headline: [],
+    stuck: [],
+    questions: { open: [], answered: [] },
+    deliverables: [],
+    activity: [],
+    ticker: null,
+    progress: { percent: 0, doneMin: 0, totalMin: 0, segments: [] },
+    tickets: [],
+    issues: [],
+};