@stevecastaneda/paseo-progress 0.1.0

package/dist/shared/events.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+// One line of `.scratch/progress.jsonl`. The command-line tool writes these;
+// the dashboard reducer reads them. `v` lets later versions change a shape
+// without misreading old files.
+export const PROGRESS_FILE = ".scratch/progress.jsonl";
+// Present once someone has opened the Progress panel for this worktree.
+export const PANEL_OPENED_FILE = ".scratch/progress-panel-opened";
+export const EVENT_VERSION = 1;
+export const TICKET_STATUSES = ["not_started", "working", "blocked", "done", "skipped"];
+export const ticketStatusSchema = z.enum(TICKET_STATUSES);
+const text = z.string().trim().min(1);
+const minutes = z.number().int().positive().max(100_000);
+const base = { v: z.literal(EVENT_VERSION), ts: z.iso.datetime() };
+export const questionOptionSchema = z.object({
+    letter: z.string().regex(/^[A-Z]$/),
+    label: text,
+    consequence: text.optional(),
+});
+const httpUrl = z.url().refine((value) => /^https?:\/\//i.test(value), "Use an HTTP or HTTPS URL");
+// Something attached to a question: a local path or a web link.
+export const fileLinkSchema = z
+    .object({ path: text.optional(), url: httpUrl.optional(), label: text.optional() })
+    .refine((file) => Boolean(file.path) !== Boolean(file.url), "Give a path or a URL");
+export const DELIVERABLE_KINDS = ["file", "folder", "report", "screenshot", "link"];
+export const eventSchema = z.discriminatedUnion("type", [
+    z.object({
+        ...base,
+        type: z.literal("run.start"),
+        title: text,
+        subtitle: text.optional(),
+        itemLabel: text.optional(),
+    }),
+    // Closes the run. Nothing more is recorded on it; new work needs `run.start`.
+    z.object({ ...base, type: z.literal("run.finish"), outcome: text }),
+    z.object({
+        ...base,
+        type: z.literal("ticket.add"),
+        id: text,
+        title: text,
+        estimateMin: minutes,
+        status: ticketStatusSchema.optional(),
+        // Another ticket in the run this one can't start until it's done.
+        waitsFor: text.optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("ticket.update"),
+        id: text,
+        title: text.optional(),
+        estimateMin: minutes.optional(),
+        status: ticketStatusSchema.optional(),
+        // The step inside the ticket, like "Build" or "Fixes". Empty clears it.
+        stage: z.string().trim().optional(),
+        note: z.string().trim().optional(),
+        // Empty clears it.
+        waitsFor: z.string().trim().optional(),
+    }),
+    z.object({ ...base, type: z.literal("ticket.remove"), id: text }),
+    // A blocker that is not a ticket status, like a failing external service.
+    z.object({ ...base, type: z.literal("stuck.set"), id: text, reason: text, ticket: text.optional() }),
+    z.object({ ...base, type: z.literal("stuck.clear"), id: text }),
+    // The agent asks, picks `default`, and keeps working on it until answered.
+    z.object({
+        ...base,
+        type: z.literal("question.ask"),
+        id: text,
+        title: text,
+        question: text,
+        options: z.array(questionOptionSchema).max(26).optional(),
+        // An option letter, or a word such as "Your check" when there are no options.
+        default: text,
+        // True when the agent will not act on the default and waits for the answer.
+        waits: z.boolean().optional(),
+        background: text.optional(),
+        files: z.array(fileLinkSchema).optional(),
+        raisedBy: text.optional(),
+        // The ticket this question came up on.
+        ticket: text.optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("question.answer"),
+        id: text,
+        choice: text,
+        // The user's own words, quoted under the answer.
+        words: text.optional(),
+        changedCourse: z.boolean(),
+    }),
+    // Adds detail to an open question; its reference and default stay.
+    z.object({
+        ...base,
+        type: z.literal("question.update"),
+        id: text,
+        question: text.optional(),
+        background: text.optional(),
+        files: z.array(fileLinkSchema).optional(),
+    }),
+    z.object({ ...base, type: z.literal("question.remove"), id: text }),
+    // `path` is relative to the worktree root, or absolute when outside it.
+    z.object({
+        ...base,
+        type: z.literal("deliverable.add"),
+        id: text,
+        title: text,
+        path: text.optional(),
+        url: httpUrl.optional(),
+        ticket: text.optional(),
+        kind: z.enum(DELIVERABLE_KINDS).optional(),
+    }).refine((event) => Boolean(event.path) !== Boolean(event.url), "A deliverable has a path or a URL"),
+    z.object({ ...base, type: z.literal("deliverable.remove"), id: text }),
+    z.object({ ...base, type: z.literal("activity.add"), id: text, text, ticket: text.optional() }),
+    z.object({ ...base, type: z.literal("activity.update"), id: text, text }),
+    z.object({ ...base, type: z.literal("activity.remove"), id: text }),
+    // One line at the top saying what the agent is doing right now.
+    z.object({ ...base, type: z.literal("ticker.set"), text }),
+    z.object({ ...base, type: z.literal("ticker.clear") }),
+]);

package/dist/shared/format.js

@@ -0,0 +1,37 @@
+// Display helpers shared by the panel and the `show` command. Times are shown
+// in the viewer's local time zone.
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export function formatMinutes(totalMin) {
+    const whole = Math.max(0, Math.floor(totalMin));
+    if (whole < 1)
+        return "<1 min";
+    const hours = Math.floor(whole / 60);
+    const minutes = whole % 60;
+    if (!hours)
+        return `${minutes} min`;
+    return minutes ? `${hours} h ${minutes} min` : `${hours} h`;
+}
+// Estimated work done out of the total, in the units people estimate in:
+// "5 of 10 min", "1 h 30 min of 2 h". Under an hour on both sides, the unit is
+// said once.
+// Once everything is done, how long it really took instead: "1 h 20 min".
+export function formatWorkDone(doneMin, totalMin, tookMin) {
+    if (tookMin !== undefined)
+        return formatMinutes(tookMin);
+    if (totalMin < 60 && doneMin >= 1)
+        return `${Math.floor(doneMin)} of ${formatMinutes(totalMin)}`;
+    return `${doneMin < 1 ? "0 min" : formatMinutes(doneMin)} of ${formatMinutes(totalMin)}`;
+}
+export function formatClock(iso) {
+    const date = new Date(iso);
+    const hours = date.getHours();
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    return `${MONTHS[date.getMonth()]} ${date.getDate()}, ${hours % 12 || 12}:${minutes} ${hours < 12 ? "AM" : "PM"}`;
+}
+export function formatAgo(iso, nowMs) {
+    const minutes = (nowMs - Date.parse(iso)) / 60_000;
+    return minutes < 1 ? "just now" : `${formatMinutes(minutes)} ago`;
+}
+export function minutesSince(iso, nowMs) {
+    return Math.max(0, (nowMs - Date.parse(iso)) / 60_000);
+}

package/dist/shared/show.js

@@ -0,0 +1,72 @@
+import { headlineText, shortTitle } from "./dashboard.js";
+import { formatAgo, formatClock, formatMinutes, formatWorkDone, minutesSince } from "./format.js";
+const STATUS = { not_started: "Not started", working: "Working", blocked: "Blocked", done: "Done", skipped: "Skipped" };
+// The dashboard as plain text, so an agent can check what the user sees.
+export function dashboardText(dashboard, nowMs) {
+    if (!dashboard.run && !dashboard.tickets.length)
+        return "No run yet. Start one with: paseo-progress start \"<title>\"";
+    const lines = [];
+    const when = (iso) => `${formatClock(iso)} (${formatAgo(iso, nowMs)})`;
+    lines.push(dashboard.run?.title ?? "Progress");
+    if (dashboard.run?.subtitle)
+        lines.push(dashboard.run.subtitle);
+    lines.push(headlineText(dashboard));
+    if (dashboard.run?.finished) {
+        lines.push(`Finished ${when(dashboard.run.finished.at)}: ${dashboard.run.finished.outcome}`);
+        lines.push(`This run is closed. Start new work with: paseo-progress start "<title>"`);
+    }
+    if (dashboard.ticker)
+        lines.push(`Now: ${dashboard.ticker.text}`);
+    if (dashboard.updatedAt)
+        lines.push(`Last updated ${when(dashboard.updatedAt)}`);
+    if (dashboard.stale && dashboard.updatedAt)
+        lines.push(`POSSIBLY STALE: no update for ${formatMinutes(minutesSince(dashboard.updatedAt, nowMs))}.`);
+    if (dashboard.progress.totalMin) {
+        lines.push(`${dashboard.progress.percent}% of estimated work done, ${dashboard.progress.tookMin !== undefined ? "took " : ""}${formatWorkDone(dashboard.progress.doneMin, dashboard.progress.totalMin, dashboard.progress.tookMin)}`);
+    }
+    if (dashboard.issues.length) {
+        lines.push("", `Skipped lines: ${dashboard.issues.map((issue) => `line ${issue.line} (${issue.reason})`).join(", ")}`);
+    }
+    if (dashboard.stuck.length) {
+        lines.push("", "Stuck");
+        for (const item of dashboard.stuck) {
+            const detail = item.kind === "overdue" ? `no update for longer than its ${formatMinutes(item.estimateMin)} estimate`
+                : item.kind === "blocked" ? `blocked${item.note ? `: ${item.note}` : ""}`
+                    : `${item.id}: ${item.reason}`;
+            lines.push(`  ${item.title} (${detail}), since ${when(item.since)}`);
+        }
+    }
+    lines.push("", `${dashboard.run?.itemLabel ?? "Ticket"}s`);
+    for (const ticket of dashboard.tickets) {
+        const stage = ticket.status === "working" && ticket.stage ? `, ${ticket.stage} stage` : "";
+        const status = ticket.waitingFor ? `Waiting for ${ticket.waitingFor.id}` : STATUS[ticket.status];
+        lines.push(`  ${ticket.id}  ${status}${stage}  ${ticket.estimateMin} min  ${ticket.title}`);
+    }
+    if (dashboard.questions.open.length) {
+        lines.push("", "Questions waiting");
+        for (const question of dashboard.questions.open) {
+            lines.push(`  ${question.id} ${question.ticketId ? `[${question.ticketId}] ` : ""}(${question.title}): ${question.question} Default ${question.default}${question.waits ? ", waiting for the answer" : ""}`);
+            for (const option of question.options)
+                lines.push(`      ${option.letter}) ${option.label}${option.consequence ? `: ${option.consequence}` : ""}`);
+        }
+    }
+    if (dashboard.questions.answered.length) {
+        lines.push("", "Answered");
+        for (const question of dashboard.questions.answered) {
+            lines.push(`  ${question.id} (${question.title}): ${question.answer.choice}${question.answer.changedCourse ? " (changed course)" : ""}`);
+        }
+    }
+    if (dashboard.deliverables.length) {
+        lines.push("", "Latest deliverables");
+        for (const deliverable of dashboard.deliverables.slice(0, 5)) {
+            const ticket = deliverable.ticketId ? `, ${deliverable.ticketLabel ?? shortTitle(deliverable.ticketId)}` : "";
+            lines.push(`  ${deliverable.id}  ${deliverable.title}: ${deliverable.url ?? deliverable.path}${ticket}`);
+        }
+    }
+    if (dashboard.activity.length) {
+        lines.push("", "Activity");
+        for (const entry of dashboard.activity.slice(0, 5))
+            lines.push(`  ${entry.id}  ${entry.ticketId ? `[${entry.ticketId}] ` : ""}${entry.text} (${formatAgo(entry.at, nowMs)})`);
+    }
+    return lines.join("\n");
+}

package/index.client.tsx

@@ -0,0 +1,33 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { ProgressPanel } from "./client/panel";
+import { contributePills, progressPanel } from "./client/pills";
+
+export default function contribute(client: PluginClientContext) {
+  const stopPills = contributePills(client);
+  const panel = progressPanel();
+  const stopPanel = client.addWorkspacePanel({
+    id: panel.id,
+    title: "Progress",
+    icon: "ListChecks",
+    context: "workspace",
+    locations: [panel.location],
+    Component: ProgressPanel,
+  });
+  const stopCommand = client.addCommandCenterItem({
+    id: "open-progress",
+    title: "Open Progress",
+    icon: "ListChecks",
+    keywords: ["dashboard", "tickets", "status", "questions"],
+    context: "workspace",
+    // Beside the agent chat where Paseo can show both; a tab of its own on phones.
+    onSelect({ openPanel }) {
+      openPanel(panel.id, { location: panel.location });
+    },
+  });
+
+  return () => {
+    void stopPanel();
+    void stopCommand();
+    stopPills();
+  };
+}

package/index.server.ts

@@ -0,0 +1,19 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { handleGetAttention, handleGetDashboard, handleMarkPanelOpened } from "./server/dashboard";
+import { handleInstallLauncher, handleLauncherStatus } from "./server/launcher";
+import { handleOpenDeliverable, handlePreviewDeliverable } from "./server/open";
+import { handleInstallSkill, handleSkillStatus } from "./server/skill";
+import { getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, markPanelOpened, openDeliverable, previewDeliverable } from "./shared/rpc";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(getDashboard, handleGetDashboard);
+  server.handle(getAttention, handleGetAttention);
+  server.handle(markPanelOpened, handleMarkPanelOpened);
+  server.handle(getLauncherStatus, handleLauncherStatus);
+  server.handle(installLauncher, handleInstallLauncher);
+  server.handle(openDeliverable, handleOpenDeliverable);
+  server.handle(previewDeliverable, handlePreviewDeliverable);
+  server.handle(getSkillStatus, handleSkillStatus);
+  server.handle(installSkill, handleInstallSkill);
+  return () => {};
+}