@stevecastaneda/paseo-progress 0.1.0

package/shared/rpc.ts

@@ -0,0 +1,109 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import type { Dashboard } from "./dashboard.ts";
+
+// `panelOpened`: the Progress panel has been opened for this worktree before.
+// `version` changes whenever anything else in the result does.
+export type DashboardResult = { configured: boolean; dashboard: Dashboard; panelOpened: boolean; version: string };
+
+export const getDashboard = defineRpc({
+  name: "progress.get",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+    // The version the caller already has; if it's current, the reply is `unchanged`.
+    since: z.string().optional(),
+  }),
+  output: z.custom<DashboardResult | { unchanged: true; version: string }>(),
+});
+
+// What a message-box pill shows: counts that need the user, and whether a run
+// is open in a worktree whose panel has never been opened.
+export type AttentionResult = { configured: boolean; questions: number; stuck: number; runOpen: boolean; panelOpened: boolean };
+
+export const getAttention = defineRpc({
+  name: "progress.attention",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+  }),
+  output: z.custom<AttentionResult>(),
+});
+
+// Records that the Progress panel was opened, so the "Progress" pill goes away for good.
+export const markPanelOpened = defineRpc({
+  name: "progress.panel.opened",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+  }),
+  output: z.object({}),
+});
+
+// The `paseo-progress` launcher on the daemon host. "foreign" means another
+// file already sits at that path; the plugin leaves it alone.
+const launcherStatus = z.object({
+  path: z.string(),
+  state: z.enum(["missing", "current", "outdated", "foreign"]),
+  onPath: z.boolean(),
+});
+export type LauncherStatus = z.infer<typeof launcherStatus>;
+
+export const getLauncherStatus = defineRpc({
+  name: "progress.launcher.status",
+  input: z.object({}),
+  output: launcherStatus,
+});
+
+export const installLauncher = defineRpc({
+  name: "progress.launcher.install",
+  input: z.object({}),
+  output: launcherStatus,
+});
+
+// The paseo-progress skill, linked into each agent's skills folder.
+const skillState = z.enum(["missing", "current", "outdated", "foreign"]);
+const skillStatus = z.object({
+  state: skillState,
+  targets: z.array(z.object({ path: z.string(), state: skillState })),
+});
+export type SkillStatus = z.infer<typeof skillStatus>;
+
+export const getSkillStatus = defineRpc({
+  name: "progress.skill.status",
+  input: z.object({}),
+  output: skillStatus,
+});
+
+export const installSkill = defineRpc({
+  name: "progress.skill.install",
+  input: z.object({}),
+  output: skillStatus,
+});
+
+// Opens a recorded local deliverable on the daemon host with its default app.
+export const openDeliverable = defineRpc({
+  name: "progress.deliverable.open",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+    // A deliverable ("D3") or a question attachment ("Q7.2").
+    ref: z.string().min(1),
+  }),
+  output: z.object({ opened: z.string() }),
+});
+
+// An image or text file's contents, for the preview dialog.
+export const previewDeliverable = defineRpc({
+  name: "progress.deliverable.preview",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+    // A deliverable ("D3") or a question attachment ("Q7.2").
+    ref: z.string().min(1),
+  }),
+  output: z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("image"), dataUri: z.string(), bytes: z.number() }),
+    z.object({ kind: z.literal("text"), text: z.string(), bytes: z.number(), truncated: z.boolean() }),
+  ]),
+});

package/shared/show.ts

@@ -0,0 +1,68 @@
+import type { Dashboard } from "./dashboard.ts";
+import { headlineText, shortTitle } from "./dashboard.ts";
+import { formatAgo, formatClock, formatMinutes, formatWorkDone, minutesSince } from "./format.ts";
+
+const STATUS: Record<string, string> = { 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: Dashboard, nowMs: number): string {
+  if (!dashboard.run && !dashboard.tickets.length) return "No run yet. Start one with: paseo-progress start \"<title>\"";
+  const lines: string[] = [];
+  const when = (iso: string) => `${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/shared/ticket-story.ts

@@ -0,0 +1,93 @@
+import type { Activity, Deliverable, Question, Ticket } from "./dashboard.ts";
+import type { TicketStatus } from "./events.ts";
+
+// One span in a ticket's life: from a status or stage change to the next one.
+export interface TimelineStep {
+  at: string;
+  // When the next step began; null while this one is still going (or it's the end).
+  until: string | null;
+  label: string;
+  status: TicketStatus;
+  notes: string[];
+  // Length of the step; null for a finished ticket's last step, which has no end.
+  minutes: number | null;
+}
+
+// Where a related item came from: tagged with `--ticket`, or logged while the
+// ticket was the one working (older entries, recorded before tags existed).
+export type Link = "tagged" | "by-time";
+
+export interface TicketStory {
+  timeline: TimelineStep[];
+  workedMin: number;
+  deliverables: Deliverable[];
+  questions: Array<Question & { link: Link }>;
+  activity: Array<Activity & { link: Link }>;
+}
+
+const OPEN_ENDED: TicketStatus[] = ["working", "blocked", "not_started"];
+
+function labelFor(status: TicketStatus, stage: string | undefined, first: boolean): string {
+  if (first && status === "not_started") return "Added";
+  switch (status) {
+    case "working": return stage ? `${stage} stage` : "Working";
+    case "blocked": return "Blocked";
+    case "done": return "Done";
+    case "skipped": return "Skipped";
+    default: return "Back to not started";
+  }
+}
+
+export function ticketTimeline(ticket: Ticket, nowMs: number): TimelineStep[] {
+  const steps: TimelineStep[] = [];
+  let status: TicketStatus = "not_started";
+  let stage: string | undefined;
+  ticket.history.forEach((change, index) => {
+    const statusChanged = change.status !== undefined && change.status !== status;
+    const stageChanged = change.stage !== undefined && (change.stage || undefined) !== stage;
+    if (change.status !== undefined) status = change.status;
+    if (change.stage !== undefined) stage = change.stage || undefined;
+    // A new step when the status changes, or the stage changes while working.
+    if (index === 0 || statusChanged || (stageChanged && status === "working")) {
+      steps.push({ at: change.at, until: null, label: labelFor(status, stage, index === 0), status, notes: [], minutes: null });
+    }
+    if (change.note) steps[steps.length - 1].notes.push(change.note);
+  });
+  steps.forEach((step, index) => {
+    const next = steps[index + 1];
+    step.until = next?.at ?? null;
+    const end = next ? Date.parse(next.at) : OPEN_ENDED.includes(step.status) ? nowMs : null;
+    step.minutes = end === null ? null : Math.max(0, (end - Date.parse(step.at)) / 60_000);
+  });
+  return steps;
+}
+
+// Spans when this ticket was the one working, for matching untagged entries by time.
+// Each includes its start but not its end, so an entry logged at a handoff
+// belongs to the ticket that just started.
+function workingWindows(steps: TimelineStep[], nowMs: number): Array<[number, number]> {
+  return steps
+    .filter((step) => step.status === "working")
+    .map((step) => [Date.parse(step.at), step.until ? Date.parse(step.until) : nowMs + 1]);
+}
+
+export function ticketStory(ticket: Ticket, related: { deliverables: Deliverable[]; questions: Question[]; activity: Activity[] }, nowMs: number): TicketStory {
+  const timeline = ticketTimeline(ticket, nowMs);
+  const windows = workingWindows(timeline, nowMs);
+  const during = (iso: string) => windows.some(([from, to]) => Date.parse(iso) >= from && Date.parse(iso) < to);
+  const link = <T extends { ticketId?: string }>(item: T, at: string): Link | null =>
+    item.ticketId ? (item.ticketId === ticket.id ? "tagged" : null) : during(at) ? "by-time" : null;
+  return {
+    timeline,
+    workedMin: timeline.filter((step) => step.status === "working").reduce((sum, step) => sum + (step.minutes ?? 0), 0),
+    deliverables: related.deliverables.filter((deliverable) => deliverable.ticketId === ticket.id),
+    questions: related.questions.flatMap((question) => {
+      const found = link(question, question.askedAt);
+      return found ? [{ ...question, link: found }] : [];
+    }),
+    activity: related.activity.flatMap((entry) => {
+      const found = link(entry, entry.at);
+      return found ? [{ ...entry, link: found }] : [];
+    }),
+  };
+}

package/skills/paseo-progress/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: paseo-progress
+description: Record progress on the Paseo Progress dashboard with the paseo-progress command. Use when implementing a spec or a set of tickets, running any job with more than 5 steps or over 30 minutes, or when the user asks for a progress dashboard.
+---
+
+# Paseo progress
+
+The user watches a live dashboard in Paseo, drawn from the progress file in this worktree. You keep it true by running `paseo-progress` the moment each change happens: the dashboard is a side effect of the work, never a summary written afterwards. Run it from inside the worktree you are working in: it records to that worktree's dashboard, and `show` names the worktree it read. `paseo-progress --help` lists every command; `paseo-progress <command> --help` gives its options.
+
+The user answers questions by reference ("Q7 A") and reads everything else at a glance, so every line you record is written for a product manager: plain words, no jargon.
+
+## 1. Set up the run
+
+Run `paseo-progress show`. When it shows an open run for this job, continue it. A run marked Finished is closed, even if it looks like your job; start a new one. Otherwise:
+
+1. `paseo-progress start "<job title>"`, with `--subtitle` naming the spec or ticket folder.
+2. Add every ticket in order with `paseo-progress ticket add "Ticket 01: <title>" --estimate <minutes>`, with `--waits-for T02` on any that can't start before another finishes. Keep the "Ticket NN:" prefix: the dashboard shortens titles to it. For a job without tickets, add its steps instead and pass `--item-label Step` to `start`.
+3. `paseo-progress activity add "<one line: what this run will do>"`.
+
+Done when `show` lists every ticket with an estimate.
+
+## 2. Work each ticket
+
+Record each change as it happens, on the ticket's id from `show` (T01, T02, ...):
+
+| When | Command |
+| --- | --- |
+| You start a ticket | `ticket update T03 --status working --stage Build` |
+| You move to the next stage | `ticket update T03 --stage Review`, then `Fixes`, then `Verify` |
+| Something reviewable lands (a screenshot folder, a report, a preview URL) | `deliverable add "<what it shows>" <path or URL> --ticket T03` |
+| A milestone the user would want in the story | `activity add "<one line>" --ticket T03` |
+| Between bigger events | `ticker set "<what you are doing right now>"` |
+| The ticket is finished | `ticket update T03 --status done`, then start the next one |
+| The plan drops it | `ticket update T03 --status skipped --note "<why>"` |
+
+Pass `--ticket` on every activity, deliverable and question that belongs to a ticket. The user presses a ticket to see its story: each stage and how long it took, with the activity, deliverables and questions tagged to it. Leave it off only for run-wide notes. Stage changes and notes are timed from your `ticket update` calls, so make them when the change happens.
+
+A working ticket turns stuck on its own once it goes longer than its estimate without an update: a status, stage or note change, or activity tagged to it. When a ticket will run long, keep updating its stage, or raise its estimate with `--estimate`.
+
+## 3. Ask questions without stopping
+
+When a decision belongs to the user, ask it and keep working:
+
+```sh
+paseo-progress question ask "<short title>" "<the question, in one or two sentences>" \
+  --option "A=<choice> | <what happens if they pick it>" \
+  --option "B=<choice> | <what happens if they pick it>" \
+  --default <letter> --ticket T03 --raised-by "Ticket 03 design review" \
+  [--background "<what they need to decide without opening the worktree>"] \
+  [--file <path or http(s) URL>=<what it shows>]
+```
+
+- The default is the safest choice. Carry on with it straight away.
+- Add `--waits` when acting on any choice needs the user's yes: purchases, production, live vendor calls, commits. Then work on something else until they answer.
+- When the user replies ("Q7 A", or in their own words), run `question answer Q7 A --words "<their words>"`. The command reports whether the answer differs from the default; when it does, change course before anything else.
+- When a question is about how something looks, attach the screenshot, mockup or preview link with `--file`. The user opens it from the question: images preview in Paseo, links open in its browser. Add more later with `question update Q7 --file <path>=<what it shows>`.
+- When the user asks about a question, answer in chat and also put the explanation on the question with `question update Q7 --background "<text>"`, so the dashboard carries it too.
+- `question remove Q7` withdraws a question that no longer applies.
+
+## 4. Flag what is stuck
+
+- A ticket that has to wait for another ticket in this run is not stuck; that's just the order of work. Record it with `ticket add ... --waits-for T03` (or `ticket update T05 --waits-for T03`) and leave its status alone. The dashboard shows it calmly as waiting until T03 is done.
+- A ticket held up by something outside the run (a service, access, a decision nobody has made): `ticket update T03 --status blocked --note "<what it waits on>"`. That shows as stuck. Set it back to `working` when it moves again.
+- A blocker outside any ticket (a failing service, a missing key): `stuck set "<reason>" [--ticket T03]`, then `stuck clear S1` once it is gone.
+
+## 5. Finish
+
+When the job is over:
+
+1. Mark the last ticket done or skipped.
+2. Settle every open question: record the user's answer, or withdraw it with `question remove` when it no longer applies. Clear flagged blockers with `stuck clear`.
+3. `paseo-progress finish "<one line: the outcome>"`. It refuses, and says what is still open, until the steps above are done.
+4. Run `paseo-progress show`.
+
+The finished run stays on the dashboard, marked Finished with its outcome, until the next `start`. It takes no more updates.
+
+If the job pauses with questions only the user can answer, don't finish: leave the run open so the questions stay in front of them.
+
+Done when `show` says Finished with the right outcome.

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": [
+      "ES2023"
+    ],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}