@stevecastaneda/paseo-progress 1.0.0 → 1.2.0

package/server/open.ts

@@ -1,10 +1,11 @@
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
 import { execFile } from "node:child_process";
-import { open, readFile, realpath, stat } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, relative, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { open, readdir, readFile, realpath, stat } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { delimiter, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
-import { findAttachment, imageMimeType, previewKind } from "../shared/attachments.ts";
+import { findAttachment, type FolderEntry, imageMimeType, previewKind, splitRef, videoMimeType } from "../shared/attachments.ts";
 import { readProgress } from "./progress-file.ts";
 import { findRoot, outside } from "./paths.ts";
 import { findStore } from "./store.ts";
@@ -34,20 +35,32 @@ async function defaultBrowser(): Promise<string | null> {
   }
 }
 
-export const systemOpener: Opener = async (path) => {
-  const browser = process.platform === "darwin" ? await defaultBrowser() : null;
-  const [command, args] = openCommand(path, process.platform, browser);
-  await promisify(execFile)(command, args);
-};
+export function canOpenFiles(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): boolean {
+  if (platform === "darwin" || platform === "win32") return true;
+  if (!env.DISPLAY && !env.WAYLAND_DISPLAY) return false;
+  return (env.PATH ?? "").split(delimiter).some((directory) => directory && existsSync(join(directory, "xdg-open")));
+}
+
+export function hostOpener(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): Opener {
+  return async (path) => {
+    if (!canOpenFiles(platform, env)) throw new Error(`Can't open files on ${hostname()}`);
+    const browser = platform === "darwin" ? await defaultBrowser() : null;
+    const [command, args] = openCommand(path, platform, browser);
+    await promisify(execFile)(command, args);
+  };
+}
 
 // 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 }> {
+  const { base, inner } = splitRef(ref);
   const worktree = findRoot(directory);
   const { dashboard } = await readProgress((await findStore(worktree)).directory);
-  const path = findAttachment(dashboard, ref)?.path;
-  if (!path) throw new Error(`No local ${ref.startsWith("Q") ? "attachment" : "deliverable"} ${ref} in this worktree.`);
+  const folder = findAttachment(dashboard, base)?.path;
+  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.`);
@@ -68,17 +81,31 @@ export const MAX_PREVIEW_BYTES = 10 * 1024 * 1024;
 // Text past this is cut off in the preview; the full file is a click away.
 export const MAX_PREVIEW_TEXT_BYTES = 256 * 1024;
 
+// A video travels in pieces, so it's capped by what the app can hold, not the socket.
+export const MAX_PREVIEW_VIDEO_BYTES = 200 * 1024 * 1024;
+
+// Small enough that one piece doesn't hold up the agent output sharing the socket.
+export const VIDEO_PIECE_BYTES = 4 * 1024 * 1024;
+
+export const MAX_FOLDER_ENTRIES = 500;
+
 export type Preview =
   | { kind: "image"; dataUri: string; bytes: number }
-  | { kind: "text"; text: string; bytes: number; truncated: boolean };
+  | { kind: "video"; mimeType: string; bytes: number }
+  | { kind: "text"; text: string; bytes: number; truncated: boolean }
+  | { kind: "folder"; entries: FolderEntry[]; truncated: boolean };
 
-// An image (as a data URI) or a text file's contents, so any client (desktop
-// or phone) can show it without reaching the daemon host's disk.
 export async function previewDeliverable(directory: string, id: string): Promise<Preview> {
   const { path, target } = await resolveAttachment(directory, id, "previewed");
+  const stats = await stat(target);
+  if (stats.isDirectory()) return { kind: "folder", ...(await listFolder(target)) };
   const kind = previewKind(target);
-  if (!kind) throw new Error(`${path} isn't an image or text file, so it can't be previewed.`);
-  const { size } = await stat(target);
+  if (!kind) throw new Error(`${path} isn't an image, video or text 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 };
+  }
   if (kind === "text") {
     // Read only what's shown, so a huge log doesn't load whole.
     const file = await open(target);
@@ -89,11 +116,44 @@ export async function previewDeliverable(directory: string, id: string): Promise
       await file.close();
     }
   }
-  if (size > MAX_PREVIEW_BYTES) throw new Error(`${path} is ${Math.round(size / 1024 / 1024)} MB, too large to preview.`);
+  if (size > MAX_PREVIEW_BYTES) throw new Error(tooLarge(path, size));
   const data = await readFile(target);
   return { kind, dataUri: `data:${imageMimeType(target)};base64,${data.toString("base64")}`, bytes: size };
 }
 
+async function listFolder(target: string): Promise<{ entries: FolderEntry[]; truncated: boolean }> {
+  const entries: FolderEntry[] = [];
+  for (const entry of await readdir(target, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const linkedFolder = entry.isSymbolicLink() && (await stat(join(target, entry.name)).catch(() => null))?.isDirectory();
+    entries.push({ name: entry.name, folder: entry.isDirectory() || Boolean(linkedFolder) });
+  }
+  entries.sort((a, b) => Number(b.folder) - Number(a.folder) || a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }));
+  return { entries: entries.slice(0, MAX_FOLDER_ENTRIES), truncated: entries.length > MAX_FOLDER_ENTRIES };
+}
+
+function tooLarge(path: string, size: number): string {
+  return `${path} is ${Math.round(size / 1024 / 1024)} MB, too large to preview.`;
+}
+
+// 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);
+  try {
+    const { size } = await file.stat();
+    if (size > MAX_PREVIEW_VIDEO_BYTES) throw new Error(tooLarge(path, size));
+    const length = Math.max(0, Math.min(VIDEO_PIECE_BYTES, size - offset));
+    if (!length) return { data: "", bytes: size };
+    const { buffer, bytesRead } = await file.read({ buffer: Buffer.alloc(length), position: offset });
+    return { data: buffer.subarray(0, bytesRead).toString("base64"), bytes: size };
+  } finally {
+    await file.close();
+  }
+}
+
 export async function handlePreviewDeliverable(
   input: { workspaceId: string; workspaceDirectory: string; ref: string },
   _context: PluginHandlerContext,
@@ -101,9 +161,20 @@ export async function handlePreviewDeliverable(
   return previewDeliverable(input.workspaceDirectory, input.ref);
 }
 
+export async function handleReadDeliverablePiece(
+  input: { workspaceId: string; workspaceDirectory: string; ref: string; offset: number },
+  _context: PluginHandlerContext,
+) {
+  return readDeliverablePiece(input.workspaceDirectory, input.ref, input.offset);
+}
+
 export async function handleOpenDeliverable(
   input: { workspaceId: string; workspaceDirectory: string; ref: string },
   _context: PluginHandlerContext,
 ) {
-  return openDeliverable(input.workspaceDirectory, input.ref, systemOpener);
+  return openDeliverable(input.workspaceDirectory, input.ref, hostOpener(process.platform, process.env));
+}
+
+export async function handleCanOpenOnHost(_input: { workspaceId: string; workspaceDirectory: string }, _context: PluginHandlerContext) {
+  return { canOpen: canOpenFiles(process.platform, process.env) };
 }

package/shared/attachments.ts

@@ -55,6 +55,15 @@ const IMAGE_TYPES: Record<string, string> = {
   ".svg": "image/svg+xml",
 };
 
+// What Paseo's desktop app (Chromium) plays. A .mov plays when it holds H.264;
+// one that doesn't shows the player's error, and Open still works.
+const VIDEO_TYPES: Record<string, string> = {
+  ".mp4": "video/mp4",
+  ".m4v": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+};
+
 // 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"]);
@@ -68,18 +77,48 @@ export function imageMimeType(path: string): string | null {
   return IMAGE_TYPES[extension(path) ?? ""] ?? null;
 }
 
-export function previewKind(path: string): "image" | "text" | null {
+// The video type of a path by its extension, or null when it isn't a video.
+export function videoMimeType(path: string): string | null {
+  return VIDEO_TYPES[extension(path) ?? ""] ?? null;
+}
+
+export function previewKind(path: string): "image" | "video" | "text" | null {
   if (imageMimeType(path)) return "image";
+  if (videoMimeType(path)) return "video";
   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
+export function isFolder(attachment: Attachment): boolean {
+  return attachment.kind === "folder" || /[\\/]$/.test(attachment.path ?? "");
+}
+
+export interface FolderEntry {
+  name: string;
+  folder: boolean;
+}
+
+export function entryRef(folderRef: string, path: string): string {
+  return `${folderRef}/${path}`;
+}
+
+export function splitRef(ref: string): { base: string; inner: string } {
+  const [base, ...rest] = ref.split("/");
+  return { base, inner: rest.join("/") };
+}
+
+export function folderAttachments(folder: Attachment, entries: FolderEntry[]): Attachment[] {
+  const base = folder.path === "./" ? "" : (folder.path ?? "").replace(/[\\/]*$/, "/");
+  return entries.map((entry) => ({ ref: entryRef(folder.ref, entry.name), title: entry.name, path: `${base}${entry.name}${entry.folder ? "/" : ""}` }));
+}
+
+// Whether the preview dialog can show it. Only a browser draws SVG and plays
+// video: Paseo's desktop app can, the phone apps can't, so there they open on
 // the host like any other file.
 export function canPreview(attachment: Attachment, where: { browser: boolean }): boolean {
   if (!attachment.path) return false;
+  if (isFolder(attachment)) return true;
   const kind = previewKind(attachment.path);
-  if (kind === "image" && extension(attachment.path) === ".svg") return where.browser;
+  if (kind === "video" || (kind === "image" && extension(attachment.path) === ".svg")) return where.browser;
   return kind !== null;
 }
 
@@ -98,7 +137,7 @@ export function attachmentIcon(attachment: Attachment): string {
   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";
+  return kind === "image" ? "Image" : kind === "video" ? "Video" : 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.

package/shared/rpc.ts

@@ -124,7 +124,17 @@ export const openDeliverable = defineRpc({
   output: z.object({ opened: z.string() }),
 });
 
-// An image or text file's contents, for the preview dialog.
+export const canOpenOnHost = defineRpc({
+  name: "progress.host.can-open",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+  }),
+  output: z.object({ canOpen: z.boolean() }),
+});
+
+// An image or text file's contents, for the preview dialog. A video comes back
+// as its type and size only; its bytes follow in pieces (readDeliverablePiece).
 export const previewDeliverable = defineRpc({
   name: "progress.deliverable.preview",
   input: z.object({
@@ -135,6 +145,21 @@ export const previewDeliverable = defineRpc({
   }),
   output: z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("image"), dataUri: z.string(), bytes: z.number() }),
+    z.object({ kind: z.literal("video"), mimeType: z.string(), bytes: z.number() }),
     z.object({ kind: z.literal("text"), text: z.string(), bytes: z.number(), truncated: z.boolean() }),
+    z.object({ kind: z.literal("folder"), entries: z.array(z.object({ name: z.string(), folder: z.boolean() })), truncated: z.boolean() }),
   ]),
 });
+
+// One piece of a video from `offset`, base64, with the file's size so the client
+// knows when it has it all.
+export const readDeliverablePiece = defineRpc({
+  name: "progress.deliverable.piece",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+    ref: z.string().min(1),
+    offset: z.number().int().min(0),
+  }),
+  output: z.object({ data: z.string(), bytes: z.number() }),
+});

package/skills/paseo-progress/SKILL.md

@@ -27,7 +27,7 @@ Record each change as it happens, on the ticket's id from `show` (T01, T02, ...)
 | --- | --- |
 | 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` |
+| Something reviewable lands (a screenshot folder, a screen recording, 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 |
@@ -66,7 +66,7 @@ paseo-progress question ask "<short title>" "<the question, in one or two senten
 - Build no option before the user answers, not even the one you recommend. The point of asking is that the user decides before the work is done.
 - Keep working on whatever the question doesn't affect: other tickets, or other parts of this one. If nothing else is left, stop, tell the user in chat which questions you're waiting on, and leave the run open.
 - When the user replies ("Q7 A", or in their own words), run `question answer Q7 A --words "<their words>"`, then build what they chose.
-- 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 a question is about how something looks, attach the screenshot, mockup or preview link with `--file`. The user opens it from the question: images and videos 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.