@stevecastaneda/paseo-progress 1.10.0 → 1.12.0

package/dist/server/cli.js

@@ -19796,14 +19796,14 @@ var eventSchema = external_exports.discriminatedUnion("type", [
     // True when the agent had to undo work built on another option.
     changedCourse: external_exports.boolean().optional()
   }),
-  // Adds detail to an open question; its reference and default stay.
   external_exports.object({
     ...base,
     type: external_exports.literal("question.update"),
     id: text,
     question: text.optional(),
     background: text.optional(),
-    files: external_exports.array(fileLinkSchema).optional()
+    files: external_exports.array(fileLinkSchema).optional(),
+    recommend: text.optional()
   }),
   external_exports.object({ ...base, type: external_exports.literal("question.remove"), id: text }),
   // `path` is relative to the worktree root, or absolute when outside it.
@@ -19971,6 +19971,7 @@ function reduceProgress(parsed, now) {
         if (event.question !== void 0) question.question = event.question;
         if (event.background !== void 0) question.background = event.background;
         if (event.files !== void 0) question.files = [...question.files, ...event.files];
+        if (event.recommend !== void 0) question.recommended = event.recommend;
         break;
       }
       case "question.remove":
@@ -20702,6 +20703,13 @@ function existingQuestion(state, id) {
   }
   return question;
 }
+function recommendOption(recommend, letters) {
+  if (!letters.length) return recommend;
+  if (!/^[A-Za-z]$/.test(recommend) || !letters.includes(recommend.toUpperCase())) {
+    throw new UsageError(`--recommend must be one of the option letters: ${letters.join(", ")}.`);
+  }
+  return recommend.toUpperCase();
+}
 function existingTicket(state, id) {
   const wanted = required2(id, "ticket id").toUpperCase();
   const ticket = state.dashboard.tickets.find((candidate) => candidate.id.toUpperCase() === wanted);
@@ -20840,13 +20848,7 @@ ${modeLine(mode)}`
       const letters = options.map((option) => option.letter);
       const duplicate = letters.find((letter, index) => letters.indexOf(letter) !== index);
       if (duplicate) throw new UsageError(`Option ${duplicate} is given twice.`);
-      let recommend = required2(stringOption(values.recommend), "--recommend (the option you would pick)");
-      if (options.length) {
-        if (!/^[A-Za-z]$/.test(recommend) || !letters.includes(recommend.toUpperCase())) {
-          throw new UsageError(`--recommend must be one of the option letters: ${letters.join(", ")}.`);
-        }
-        recommend = recommend.toUpperCase();
-      }
+      const recommend = recommendOption(required2(stringOption(values.recommend), "--recommend (the option you would pick)"), letters);
       const id = state.nextIds.question;
       const big = values.big === void 0 ? void 0 : required2(stringOption(values.big), "--big reason (why the question is big)");
       const rules = QUESTION_MODE_RULES[mode];
@@ -20892,21 +20894,32 @@ ${modeLine(mode)}`
     }
   },
   "question update": {
-    usage: `question update <id> [--background <text>] [--question <text>] [--file <path or http(s) URL>[=<label>] ...]`,
-    summary: "Add detail to a question: replace its background or wording, or add files. Its reference and default stay.",
-    options: { background: { type: "string" }, question: { type: "string" }, file: { type: "string", multiple: true } },
-    run({ positionals, values, state, cwd, root }) {
+    usage: `question update <id> [--recommend <letter or word>] [--background <text>] [--question <text>] [--file <path or http(s) URL>[=<label>] ...]`,
+    summary: "Add detail to a question: change your recommendation while it's open, replace its background or wording, or add files. Its reference stays.",
+    options: { recommend: { type: "string" }, background: { type: "string" }, question: { type: "string" }, file: { type: "string", multiple: true } },
+    run({ positionals, values, state, cwd, root, mode }) {
       const question = existingQuestion(state, positionals[0]);
       const files = listOption(values.file).map((raw) => parseFile(raw, cwd, root));
+      let recommend;
+      if (values.recommend !== void 0) {
+        if (question.answer) throw new UsageError(`${question.id} was already answered, so its recommendation can't change.`);
+        const letters = question.options.map((option) => option.letter);
+        recommend = recommendOption(required2(stringOption(values.recommend), "--recommend (the option you would pick)"), letters);
+        if (recommend === question.recommended) throw new UsageError(`${question.id} already recommends ${recommend}.`);
+      }
       const event = {
         type: "question.update",
         id: question.id,
         question: stringOption(values.question),
         background: stringOption(values.background),
-        files: files.length ? files : void 0
+        files: files.length ? files : void 0,
+        recommend
       };
-      if (!event.question && !event.background && !event.files) throw new UsageError("Nothing to change. Pass --background, --question, or --file.");
-      return { event, message: `Updated ${question.id} (${question.title})` };
+      if (!event.question && !event.background && !event.files && !recommend) throw new UsageError("Nothing to change. Pass --recommend, --background, --question, or --file.");
+      if (!recommend) return { event, message: `Updated ${question.id} (${question.title})` };
+      const rules = QUESTION_MODE_RULES[mode];
+      const next = question.state === "building" ? `Undo the work built on ${question.recommended} and build ${recommend} instead.` : `Mode: ${rules.label}. ${rules.askRule({ recommend, big: Boolean(question.big) })}`;
+      return { event, message: `${question.id} now recommends ${recommend} (was ${question.recommended}). ${next}` };
     }
   },
   "question remove": {

package/index.client.tsx

@@ -9,12 +9,11 @@ const SETTINGS_ID = "settings";
 
 export default function contribute(client: PluginClientContext) {
   const stopPills = contributePills(client);
-  const panel = progressPanel(client);
+  const panel = progressPanel();
   const stopPanel = client.addWorkspacePanel({
     id: panel.id,
     title: "Progress",
     icon: "ListChecks",
-    context: "workspace",
     locations: [panel.location],
     Component: (props) => <ProgressLanguageProvider><ProgressPanel {...props} openSettings={() => client.openSettings(SETTINGS_ID)} /></ProgressLanguageProvider>,
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the paseo-progress command.",
   "license": "MIT",
   "author": "Steve Castaneda",
@@ -50,8 +50,8 @@
     "postpack": "rm -rf dist"
   },
   "devDependencies": {
-    "@getpaseo/client": "^0.11.2",
-    "@getpaseo/plugin": "^0.11.2",
+    "@getpaseo/client": "0.13.0",
+    "@getpaseo/plugin": "0.13.0",
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",

package/paseo-plugin.json

@@ -9,6 +9,6 @@
     "images/5-settings.png"
   ],
   "requirements": {
-    "paseo": ">=0.11.0"
+    "paseo": ">=0.13.0"
   }
 }

package/server/cli.ts

@@ -121,6 +121,14 @@ function existingQuestion(state: State, id: string | undefined) {
   return question;
 }
 
+function recommendOption(recommend: string, letters: string[]): string {
+  if (!letters.length) return recommend;
+  if (!/^[A-Za-z]$/.test(recommend) || !letters.includes(recommend.toUpperCase())) {
+    throw new UsageError(`--recommend must be one of the option letters: ${letters.join(", ")}.`);
+  }
+  return recommend.toUpperCase();
+}
+
 function existingTicket(state: State, id: string | undefined) {
   const wanted = required(id, "ticket id").toUpperCase();
   const ticket = state.dashboard.tickets.find((candidate) => candidate.id.toUpperCase() === wanted);
@@ -269,13 +277,7 @@ const commands: Record<string, Command> = {
       const letters = options.map((option) => option.letter);
       const duplicate = letters.find((letter, index) => letters.indexOf(letter) !== index);
       if (duplicate) throw new UsageError(`Option ${duplicate} is given twice.`);
-      let recommend = required(stringOption(values.recommend), "--recommend (the option you would pick)");
-      if (options.length) {
-        if (!/^[A-Za-z]$/.test(recommend) || !letters.includes(recommend.toUpperCase())) {
-          throw new UsageError(`--recommend must be one of the option letters: ${letters.join(", ")}.`);
-        }
-        recommend = recommend.toUpperCase();
-      }
+      const recommend = recommendOption(required(stringOption(values.recommend), "--recommend (the option you would pick)"), letters);
       const id = state.nextIds.question;
       const big = values.big === undefined ? undefined : required(stringOption(values.big), "--big reason (why the question is big)");
       const rules = QUESTION_MODE_RULES[mode];
@@ -323,21 +325,34 @@ const commands: Record<string, Command> = {
     },
   },
   "question update": {
-    usage: `question update <id> [--background <text>] [--question <text>] [--file <path or http(s) URL>[=<label>] ...]`,
-    summary: "Add detail to a question: replace its background or wording, or add files. Its reference and default stay.",
-    options: { background: { type: "string" }, question: { type: "string" }, file: { type: "string", multiple: true } },
-    run({ positionals, values, state, cwd, root }) {
+    usage: `question update <id> [--recommend <letter or word>] [--background <text>] [--question <text>] [--file <path or http(s) URL>[=<label>] ...]`,
+    summary: "Add detail to a question: change your recommendation while it's open, replace its background or wording, or add files. Its reference stays.",
+    options: { recommend: { type: "string" }, background: { type: "string" }, question: { type: "string" }, file: { type: "string", multiple: true } },
+    run({ positionals, values, state, cwd, root, mode }) {
       const question = existingQuestion(state, positionals[0]);
       const files = listOption(values.file).map((raw) => parseFile(raw, cwd, root));
+      let recommend: string | undefined;
+      if (values.recommend !== undefined) {
+        if (question.answer) throw new UsageError(`${question.id} was already answered, so its recommendation can't change.`);
+        const letters = question.options.map((option) => option.letter);
+        recommend = recommendOption(required(stringOption(values.recommend), "--recommend (the option you would pick)"), letters);
+        if (recommend === question.recommended) throw new UsageError(`${question.id} already recommends ${recommend}.`);
+      }
       const event = {
         type: "question.update" as const,
         id: question.id,
         question: stringOption(values.question),
         background: stringOption(values.background),
         files: files.length ? files : undefined,
+        recommend,
       };
-      if (!event.question && !event.background && !event.files) throw new UsageError("Nothing to change. Pass --background, --question, or --file.");
-      return { event, message: `Updated ${question.id} (${question.title})` };
+      if (!event.question && !event.background && !event.files && !recommend) throw new UsageError("Nothing to change. Pass --recommend, --background, --question, or --file.");
+      if (!recommend) return { event, message: `Updated ${question.id} (${question.title})` };
+      const rules = QUESTION_MODE_RULES[mode];
+      const next = question.state === "building"
+        ? `Undo the work built on ${question.recommended} and build ${recommend} instead.`
+        : `Mode: ${rules.label}. ${rules.askRule({ recommend, big: Boolean(question.big) })}`;
+      return { event, message: `${question.id} now recommends ${recommend} (was ${question.recommended}). ${next}` };
     },
   },
   "question remove": {

package/server/open.ts

@@ -3,9 +3,10 @@ import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { open, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
-import { delimiter, dirname, join, relative, resolve } from "node:path";
+import nodePath, { delimiter, dirname, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
-import { findAttachment, type FolderEntry, imageMimeType, previewKind, splitRef, videoMimeType } from "../shared/attachments.ts";
+import { findAttachment, type FolderEntry, imageMimeType, previewKind, splitRef, textFormat, videoMimeType } from "../shared/attachments.ts";
+import { prepareMarkdown, previewText } from "../shared/markdown.ts";
 import { readProgress } from "./progress-file.ts";
 import { findRoot, outside } from "./paths.ts";
 import { findStore } from "./store.ts";
@@ -53,7 +54,7 @@ export function hostOpener(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): O
 // A deliverable or question attachment the agent recorded, found by reference,
 // so the panel can never reach an arbitrary path. Only files inside the
 // worktree resolve.
-async function resolveAttachment(directory: string, ref: string, verb: string): Promise<{ path: string; target: string; root: string }> {
+async function resolveAttachment(directory: string, ref: string, verb: string): Promise<{ path: string; realTarget: string; realRoot: string; worktree: string }> {
   const { base, inner } = splitRef(ref);
   const worktree = findRoot(directory);
   const { dashboard } = await readProgress((await findStore(worktree)).directory);
@@ -61,18 +62,18 @@ async function resolveAttachment(directory: string, ref: string, verb: string):
   if (!folder) throw new Error(`No local ${base.startsWith("Q") ? "attachment" : "deliverable"} ${base} in this worktree.`);
   const path = inner ? join(folder, inner) : folder;
   if (outside(relative(resolve(worktree, folder), resolve(worktree, path)))) throw new Error(`${path} is outside ${folder}, so it was not ${verb}.`);
-  const root = await realpath(worktree);
-  const target = await realpath(resolve(root, path)).catch(() => null);
-  if (!target) throw new Error(`${path} no longer exists.`);
-  const inside = relative(root, target);
+  const realRoot = await realpath(worktree);
+  const realTarget = await realpath(resolve(realRoot, path)).catch(() => null);
+  if (!realTarget) throw new Error(`${path} no longer exists.`);
+  const inside = relative(realRoot, realTarget);
   if (outside(inside)) throw new Error(`${path} is outside this worktree, so it was not ${verb}.`);
-  return { path, target, root };
+  return { path, realTarget, realRoot, worktree };
 }
 
 export async function openDeliverable(directory: string, id: string, opener: Opener): Promise<{ opened: string }> {
-  const { target } = await resolveAttachment(directory, id, "opened");
-  await opener(target);
-  return { opened: target };
+  const { realTarget } = await resolveAttachment(directory, id, "opened");
+  await opener(realTarget);
+  return { opened: realTarget };
 }
 
 // Large enough for full-page screenshots; the image travels over the socket.
@@ -93,34 +94,39 @@ export type Preview =
   | { kind: "image"; dataUri: string; bytes: number }
   | { kind: "video"; mimeType: string; bytes: number }
   | { kind: "text"; text: string; bytes: number; truncated: boolean }
+  | { kind: "markdown"; markdown: string; bytes: number; truncated: boolean }
   | { kind: "html"; html: string; bytes: number }
   | { kind: "folder"; entries: FolderEntry[]; truncated: boolean };
 
 export async function previewDeliverable(directory: string, id: string): Promise<Preview> {
-  const { path, target, root } = await resolveAttachment(directory, id, "previewed");
-  const stats = await stat(target);
-  if (stats.isDirectory()) return { kind: "folder", ...(await listFolder(target)) };
-  const kind = previewKind(target);
+  const { path, realTarget, realRoot, worktree } = await resolveAttachment(directory, id, "previewed");
+  const stats = await stat(realTarget);
+  if (stats.isDirectory()) return { kind: "folder", ...(await listFolder(realTarget)) };
+  const kind = previewKind(realTarget);
   if (!kind) throw new Error(`${path} isn't an image, video, text or HTML file, so it can't be previewed.`);
   const { size } = stats;
   if (kind === "video") {
     if (size > MAX_PREVIEW_VIDEO_BYTES) throw new Error(tooLarge(path, size));
-    return { kind, mimeType: videoMimeType(target)!, bytes: size };
+    return { kind, mimeType: videoMimeType(realTarget)!, bytes: size };
   }
   if (kind === "text") {
     // Read only what's shown, so a huge log doesn't load whole.
-    const file = await open(target);
+    const file = await open(realTarget);
     try {
       const { buffer, bytesRead } = await file.read({ buffer: Buffer.alloc(Math.min(size, MAX_PREVIEW_TEXT_BYTES)), position: 0 });
-      return { kind, text: buffer.subarray(0, bytesRead).toString("utf8"), bytes: size, truncated: size > MAX_PREVIEW_TEXT_BYTES };
+      const bytes = buffer.subarray(0, bytesRead);
+      const truncated = size > MAX_PREVIEW_TEXT_BYTES;
+      if (textFormat(realTarget) === "plain") return { kind, text: previewText(bytes, truncated), bytes: size, truncated };
+      const where = { root: worktree, folder: dirname(resolve(worktree, path)), path: nodePath };
+      return { kind: "markdown", markdown: prepareMarkdown(bytes, truncated, where), bytes: size, truncated };
     } finally {
       await file.close();
     }
   }
   if (size > MAX_PREVIEW_BYTES) throw new Error(tooLarge(path, size));
-  if (kind === "html") return { kind, html: await inlineLocalFiles(await readFile(target, "utf8"), dirname(target), root), bytes: size };
-  const data = await readFile(target);
-  return { kind, dataUri: `data:${imageMimeType(target)};base64,${data.toString("base64")}`, bytes: size };
+  if (kind === "html") return { kind, html: await inlineLocalFiles(await readFile(realTarget, "utf8"), dirname(realTarget), realRoot), bytes: size };
+  const data = await readFile(realTarget);
+  return { kind, dataUri: `data:${imageMimeType(realTarget)};base64,${data.toString("base64")}`, bytes: size };
 }
 
 async function listFolder(target: string): Promise<{ entries: FolderEntry[]; truncated: boolean }> {
@@ -192,9 +198,9 @@ function tooLarge(path: string, size: number): string {
 // One piece of a video, from `offset`. Resolved by reference each time, like the
 // preview, so a piece can only come from a video the agent recorded.
 export async function readDeliverablePiece(directory: string, id: string, offset: number): Promise<{ data: string; bytes: number }> {
-  const { path, target } = await resolveAttachment(directory, id, "previewed");
-  if (previewKind(target) !== "video") throw new Error(`${path} isn't a video.`);
-  const file = await open(target);
+  const { path, realTarget } = await resolveAttachment(directory, id, "previewed");
+  if (previewKind(realTarget) !== "video") throw new Error(`${path} isn't a video.`);
+  const file = await open(realTarget);
   try {
     const { size } = await file.stat();
     if (size > MAX_PREVIEW_VIDEO_BYTES) throw new Error(tooLarge(path, size));

package/server/whats-new.ts

@@ -7,7 +7,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
 import { NOTE_KINDS, type NoteKind, type WhatsNew, type WhatsNewNote, type WhatsNewRelease } from "../shared/whats-new.ts";
-import { spans } from "../shared/write-up.ts";
+import { spans } from "../shared/blocks.ts";
 import { findPluginDirectory } from "./skill.ts";
 import { stateRoot, writeAtomic } from "./store.ts";
 

package/shared/attachments.ts

@@ -64,9 +64,20 @@ const VIDEO_TYPES: Record<string, string> = {
   ".webm": "video/webm",
 };
 
-// Plain text shown as-is in the preview dialog, and opened in the browser on
-// the host.
-const TEXT_EXTENSIONS = new Set([".md", ".markdown", ".mdx", ".txt", ".log", ".json", ".jsonl", ".yaml", ".yml", ".csv"]);
+// MDX stays plain: Paseo's Markdown would drop its components without a trace
+// and run its imports into prose.
+const TEXT_FORMATS: Record<string, "markdown" | "plain"> = {
+  ".md": "markdown",
+  ".markdown": "markdown",
+  ".mdx": "plain",
+  ".txt": "plain",
+  ".log": "plain",
+  ".json": "plain",
+  ".jsonl": "plain",
+  ".yaml": "plain",
+  ".yml": "plain",
+  ".csv": "plain",
+};
 
 function extension(path: string): string | null {
   return path.toLowerCase().match(/\.[a-z0-9]+$/)?.[0] ?? null;
@@ -82,12 +93,16 @@ export function videoMimeType(path: string): string | null {
   return VIDEO_TYPES[extension(path) ?? ""] ?? null;
 }
 
+export function textFormat(path: string): "markdown" | "plain" | null {
+  return TEXT_FORMATS[extension(path) ?? ""] ?? null;
+}
+
 export function previewKind(path: string): "image" | "video" | "text" | "html" | null {
   if (imageMimeType(path)) return "image";
   if (videoMimeType(path)) return "video";
   const ext = extension(path) ?? "";
   if (ext === ".html" || ext === ".htm") return "html";
-  return TEXT_EXTENSIONS.has(ext) ? "text" : null;
+  return textFormat(path) ? "text" : null;
 }
 
 export function isFolder(attachment: Attachment): boolean {

package/shared/{write-up.ts → blocks.ts}

@@ -1,8 +1,3 @@
-// A ticket's write-up (its Markdown source file) as simple blocks the dialog
-// can draw without a Markdown renderer: headings, paragraphs, list items and
-// code. Inline marks are kept as spans: `code` stays code, **bold** stays
-// bold, _emphasis_ loses its markers, and [links](url) keep only their text.
-
 export type Span = { text: string; code?: boolean; strong?: boolean };
 
 export type Block =
@@ -30,7 +25,7 @@ export function spans(text: string): Span[] {
   return result;
 }
 
-export function parseWriteUp(markdown: string): Block[] {
+export function parseBlocks(markdown: string): Block[] {
   const blocks: Block[] = [];
   let paragraph: string[] = [];
   // A fence opened inside a list item is indented like the item; its lines
@@ -75,21 +70,6 @@ export function parseWriteUp(markdown: string): Block[] {
   return blocks;
 }
 
-// The write-up without a leading top heading, which only repeats the ticket's title.
 export function withoutTitle(blocks: Block[]): Block[] {
   return blocks[0]?.kind === "heading" && blocks[0].level === 1 ? blocks.slice(1) : blocks;
 }
-
-// The first blocks of the write-up, up to about `maxChars` of text, for the excerpt.
-export function writeUpExcerpt(blocks: Block[], maxChars = 420): { blocks: Block[]; more: boolean } {
-  const body = withoutTitle(blocks);
-  const shown: Block[] = [];
-  let chars = 0;
-  for (const block of body) {
-    const length = block.kind === "code" ? block.text.length : block.spans.reduce((sum, span) => sum + span.text.length, 0);
-    if (shown.length && chars + length > maxChars) break;
-    shown.push(block);
-    chars += length;
-  }
-  return { blocks: shown, more: shown.length < body.length };
-}

package/shared/dashboard.ts

@@ -308,6 +308,7 @@ export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue
         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];
+        if (event.recommend !== undefined) question.recommended = event.recommend;
         break;
       }
       case "question.remove":

package/shared/events.ts

@@ -112,7 +112,6 @@ export const eventSchema = z.discriminatedUnion("type", [
     // True when the agent had to undo work built on another option.
     changedCourse: z.boolean().optional(),
   }),
-  // Adds detail to an open question; its reference and default stay.
   z.object({
     ...base,
     type: z.literal("question.update"),
@@ -120,6 +119,7 @@ export const eventSchema = z.discriminatedUnion("type", [
     question: text.optional(),
     background: text.optional(),
     files: z.array(fileLinkSchema).optional(),
+    recommend: text.optional(),
   }),
   z.object({ ...base, type: z.literal("question.remove"), id: text }),
   // `path` is relative to the worktree root, or absolute when outside it.