@stevecastaneda/paseo-progress 1.14.1 → 1.14.3

package/server/open.ts

@@ -1,15 +1,25 @@
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
-import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
-import { open, readdir, readFile, realpath, stat } from "node:fs/promises";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import nodePath, { delimiter, dirname, join, relative, resolve } from "node:path";
-import { promisify } from "node:util";
-import { findAttachment, type FolderEntry, imageMimeType, isPieced, type PiecedKind, previewKind, splitRef, textFormat, videoMimeType } from "../shared/attachments.ts";
+import {
+  findAttachment,
+  type FolderEntry,
+  imageMimeType,
+  isPieced,
+  opensOnHost,
+  type PiecedKind,
+  previewKind,
+  splitRef,
+  textFormat,
+  videoMimeType,
+} from "../shared/attachments.ts";
 import { prepareMarkdown, previewText } from "../shared/markdown.ts";
 import { readProgress } from "./progress-file.ts";
-import { findRoot, hasGitEntry, inGitFolder, outside } from "./paths.ts";
-import { findStore, git } from "./store.ts";
+import { findRoot, outside } from "./paths.ts";
+import { findStore } from "./store.ts";
+import { openToRead, runProgram } from "./system.ts";
 
 export type Opener = (path: string) => Promise<void>;
 
@@ -28,7 +38,7 @@ export function openCommand(path: string, platform: NodeJS.Platform, browser: st
 async function defaultBrowser(): Promise<string | null> {
   try {
     const plist = join(homedir(), "Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist");
-    const { stdout } = await promisify(execFile)("plutil", ["-convert", "json", "-o", "-", plist]);
+    const { stdout } = await runProgram("plutil", ["-convert", "json", "-o", "-", plist]);
     const handlers = (JSON.parse(stdout).LSHandlers ?? []) as Array<{ LSHandlerURLScheme?: string; LSHandlerRoleAll?: string }>;
     return handlers.find((handler) => handler.LSHandlerURLScheme === "https")?.LSHandlerRoleAll ?? null;
   } catch {
@@ -47,14 +57,14 @@ export function hostOpener(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): O
     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);
+    await runProgram(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; realTarget: string; realRoot: string; worktree: string }> {
+async function resolveAttachment(directory: string, ref: string, verb: string): Promise<{ path: string; realTarget: string; worktree: string }> {
   const { base, inner } = splitRef(ref);
   const worktree = findRoot(directory);
   const { dashboard } = await readProgress((await findStore(worktree)).directory);
@@ -67,11 +77,15 @@ async function resolveAttachment(directory: string, ref: string, verb: string):
   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, realTarget, realRoot, worktree };
+  return { path, realTarget, worktree };
 }
 
+// The real file is checked, not the name the agent recorded, so a link named
+// like a picture can't hand a script to the default app.
 export async function openDeliverable(directory: string, id: string, opener: Opener): Promise<{ opened: string }> {
-  const { realTarget } = await resolveAttachment(directory, id, "opened");
+  const { path, realTarget } = await resolveAttachment(directory, id, "opened");
+  if (!(await stat(realTarget)).isFile() || !opensOnHost(realTarget))
+    throw new Error(`Progress opens only images, video, audio, PDFs and text files, not ${path}`);
   await opener(realTarget);
   return { opened: realTarget };
 }
@@ -98,15 +112,15 @@ export type Preview =
   | { kind: "pdf"; 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, realTarget, realRoot, worktree } = await resolveAttachment(directory, id, "previewed");
+  const { path, realTarget, worktree } = await resolveAttachment(directory, id, "previewed");
   const stats = await stat(realTarget);
   if (stats.isDirectory()) return { kind: "folder", ...(await listFolder(realTarget)) };
+  // A page opens in Paseo's own preview, in a tab.
   const kind = previewKind(realTarget);
-  if (!kind) throw new Error(`${path} isn't an image, video, PDF, text or HTML file, so it can't be previewed.`);
+  if (!kind || kind === "html") throw new Error(`${path} isn't an image, video, PDF or text file, so it can't be previewed.`);
   const { size } = stats;
   if (isPieced(kind)) {
     if (size > PIECED_LIMIT_BYTES[kind]) throw new Error(tooLarge(path, size));
@@ -114,7 +128,7 @@ export async function previewDeliverable(directory: string, id: string): Promise
   }
   if (kind === "text") {
     // Read only what's shown, so a huge log doesn't load whole.
-    const file = await open(realTarget);
+    const file = await openToRead(realTarget);
     try {
       const { buffer, bytesRead } = await file.read({ buffer: Buffer.alloc(Math.min(size, MAX_PREVIEW_TEXT_BYTES)), position: 0 });
       const bytes = buffer.subarray(0, bytesRead);
@@ -127,7 +141,6 @@ export async function previewDeliverable(directory: string, id: string): Promise
     }
   }
   if (size > MAX_PREVIEW_BYTES) throw new Error(tooLarge(path, size));
-  if (kind === "html") return { kind, html: await inlineLocalFiles(await readFile(realTarget, "utf8"), realTarget, realRoot), bytes: size };
   const data = await readFile(realTarget);
   return { kind, dataUri: `data:${imageMimeType(realTarget)};base64,${data.toString("base64")}`, bytes: size };
 }
@@ -143,79 +156,6 @@ async function listFolder(target: string): Promise<{ entries: FolderEntry[]; tru
   return { entries: entries.slice(0, MAX_FOLDER_ENTRIES), truncated: entries.length > MAX_FOLDER_ENTRIES };
 }
 
-// The preview gets only the page, so the files beside it that it loads (its
-// screenshots, a script, a stylesheet) are written into it. Only files inside the
-// worktree, up to MAX_PREVIEW_BYTES in all; anything else is left as written and
-// fails to load. Web addresses are left alone. A cloned repo's page runs here,
-// so it must not read and send .env or .git files: it gets a file git says it
-// keeps, or, when git ignores the page, like an agent's report in .scratch, a
-// file in the page's own folder or below. Never one in a .git folder. When git
-// can't answer, as for a file in a submodule or when git fails, the file stays out.
-async function inlineLocalFiles(html: string, page: string, root: string): Promise<string> {
-  const directory = dirname(page);
-  const inRepo = hasGitEntry(root);
-  // -v -n prints a line for every path git answers for, so a git that fails
-  // with no answer never counts as "not ignored". The "./" stops git reading a
-  // name like ":(glob)x" as a pattern.
-  const ignoreCheck = async (path: string): Promise<"ignored" | "kept" | "unknown"> => {
-    if (!inRepo) return "kept";
-    const { code, stdout } = await git(root, ["check-ignore", "-v", "-n", "--", `./${relative(root, path).split(nodePath.sep).join("/")}`]);
-    if (!stdout.trim()) return "unknown";
-    return code === 0 ? "ignored" : code === 1 ? "kept" : "unknown";
-  };
-  const pageIgnored = (await ignoreCheck(page)) === "ignored";
-  const allowed = async (file: string) => {
-    if (inGitFolder(relative(root, file))) return false;
-    if ((await ignoreCheck(file)) === "kept") return true;
-    return pageIgnored && !outside(relative(directory, file));
-  };
-  let room = MAX_PREVIEW_BYTES - Buffer.byteLength(html);
-  const inline = async (url: string, encode: (data: Buffer, file: string) => string): Promise<string | null> => {
-    if (!url || /^([a-z][a-z0-9+.-]*:|[/\\#?])/i.test(url)) return null;
-    try {
-      const file = await realpath(resolve(directory, decodeURI(url.replace(/[?#].*$/, ""))));
-      const stats = await stat(file);
-      if (outside(relative(root, file)) || !stats.isFile() || stats.size > room) return null;
-      if (!(await allowed(file))) return null;
-      const encoded = encode(await readFile(file), file);
-      if (encoded.length > room) return null;
-      room -= encoded.length;
-      return encoded;
-    } catch {
-      return null;
-    }
-  };
-  const dataUri = (data: Buffer, file: string) => `data:${imageMimeType(file) ?? videoMimeType(file) ?? "application/octet-stream"};base64,${data.toString("base64")}`;
-  // Its own end tag would close the element early.
-  const body = (tag: string) => (data: Buffer) => data.toString("utf8").replace(new RegExp(`</${tag}`, "gi"), `<\\/${tag}`);
-  html = await replaceEach(html, /<(?:img|source|video)\b[^>]*>/gi, (tag) =>
-    replaceEach(tag[0], /(?<=\s)(src|poster)(\s*=\s*)(["'])([^"']*)\3/gi, async ([, name, equals, quote, url]) => {
-      const uri = await inline(url, dataUri);
-      return uri && `${name}${equals}${quote}${uri}${quote}`;
-    }));
-  html = await replaceEach(html, /<link\b[^>]*>/gi, async ([tag]) => {
-    const href = tag.match(/\bhref\s*=\s*(["'])([^"']*)\1/i)?.[2];
-    if (!href || !/\brel\s*=\s*(["'])\s*stylesheet\s*\1/i.test(tag)) return null;
-    const css = await inline(href, body("style"));
-    return css === null ? null : `<style>${css}</style>`;
-  });
-  return replaceEach(html, /<script\b([^>]*?)\s+src\s*=\s*(["'])([^"']*)\2([^>]*)>\s*<\/script\s*>/gi, async ([, before, , src, after]) => {
-    const script = await inline(src, body("script"));
-    return script === null ? null : `<script${before}${after}>${script}</script>`;
-  });
-}
-
-// `replace` on each match in turn; a null keeps the match as it was.
-async function replaceEach(text: string, pattern: RegExp, replace: (match: RegExpMatchArray) => Promise<string | null>): Promise<string> {
-  let result = "";
-  let last = 0;
-  for (const match of text.matchAll(pattern)) {
-    result += text.slice(last, match.index) + ((await replace(match)) ?? match[0]);
-    last = match.index! + match[0].length;
-  }
-  return result + text.slice(last);
-}
-
 function tooLarge(path: string, size: number): string {
   return `${path} is ${Math.round(size / 1024 / 1024)} MB, too large to preview.`;
 }
@@ -224,7 +164,7 @@ export async function readDeliverablePiece(directory: string, id: string, offset
   const { path, realTarget } = await resolveAttachment(directory, id, "previewed");
   const kind = previewKind(realTarget);
   if (!isPieced(kind)) throw new Error(`${path} isn't a video or PDF.`);
-  const file = await open(realTarget);
+  const file = await openToRead(realTarget);
   try {
     const { size } = await file.stat();
     if (size > PIECED_LIMIT_BYTES[kind]) throw new Error(tooLarge(path, size));
@@ -237,10 +177,7 @@ export async function readDeliverablePiece(directory: string, id: string, offset
   }
 }
 
-export async function handlePreviewDeliverable(
-  input: { workspaceId: string; workspaceDirectory: string; ref: string },
-  _context: PluginHandlerContext,
-) {
+export async function handlePreviewDeliverable(input: { workspaceId: string; workspaceDirectory: string; ref: string }, _context: PluginHandlerContext) {
   return previewDeliverable(input.workspaceDirectory, input.ref);
 }
 
@@ -251,10 +188,7 @@ export async function handleReadDeliverablePiece(
   return readDeliverablePiece(input.workspaceDirectory, input.ref, input.offset);
 }
 
-export async function handleOpenDeliverable(
-  input: { workspaceId: string; workspaceDirectory: string; ref: string },
-  _context: PluginHandlerContext,
-) {
+export async function handleOpenDeliverable(input: { workspaceId: string; workspaceDirectory: string; ref: string }, _context: PluginHandlerContext) {
   return openDeliverable(input.workspaceDirectory, input.ref, hostOpener(process.platform, process.env));
 }
 

package/server/progress-file.ts

@@ -2,11 +2,12 @@
 // the command appends to and the panel-opened marker. Each function takes the
 // folder that holds them, which `findStore` in store.ts picks. The command and
 // the panel's RPC handlers go through here, so they agree on how they're read.
-import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { access, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { EMPTY_DASHBOARD, latestRun, parseProgress, reduceProgress, type Dashboard, type NextIds } from "../shared/dashboard.ts";
 import { EVENT_VERSION, eventSchema, PANEL_OPENED_NAME, PROGRESS_FILE_NAME, type ProgressEvent } from "../shared/events.ts";
 import { withLock } from "./lock.ts";
+import { appendFileIn, makeFolder, writeFileIn } from "./system.ts";
 
 const LOCK_NAME = `${PROGRESS_FILE_NAME}.lock`;
 
@@ -63,8 +64,8 @@ export async function appendProgress<T>(
   // Runs before the lock is released, with the whole file as it now is.
   after?: (text: string) => Promise<void>,
 ): Promise<T> {
-  await mkdir(directory, { recursive: true });
-  return withLock(join(directory, LOCK_NAME), async () => {
+  await makeFolder(directory);
+  return withLock(directory, LOCK_NAME, async () => {
     const text = (await readText(directory)) ?? "";
     const parsed = parseProgress(text);
     const { dashboard, nextIds } = reduceProgress(parsed, now());
@@ -76,15 +77,14 @@ export async function appendProgress<T>(
     // 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" : "";
     const line = `${lead}${JSON.stringify(checked.data)}\n`;
-    await appendFile(join(directory, PROGRESS_FILE_NAME), line);
+    await appendFileIn(directory, PROGRESS_FILE_NAME, line);
     await after?.(text + line);
     return result;
   });
 }
 
 export async function markPanelOpened(directory: string): Promise<void> {
-  await mkdir(directory, { recursive: true });
-  await writeFile(join(directory, PANEL_OPENED_NAME), "");
+  await writeFileIn(directory, PANEL_OPENED_NAME, "");
 }
 
 async function readText(directory: string): Promise<string | null> {

package/server/question-mode.ts

@@ -1,19 +1,22 @@
 // The question mode lives in Paseo's settings, which only the plugin's server
 // process can read. It mirrors the mode into a file the paseo-progress command
 // can read on its own.
-import { readFile, rm } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
 import type { PluginSettings } from "@getpaseo/plugin/server";
 import { DEFAULT_QUESTION_MODE, QUESTION_MODES, type QuestionMode } from "../shared/question-modes.ts";
 import type { questionSettings } from "../shared/settings.ts";
-import { stateRoot, writeAtomic } from "./store.ts";
+import { stateRoot } from "./store.ts";
+import { removeIn, writeFileIn } from "./system.ts";
 
 const mirrorSchema = z.object({ questionMode: z.enum(QUESTION_MODES) });
 
+const SETTINGS_NAME = "settings.json";
+
 export function questionModePath(home = homedir()): string {
-  return join(stateRoot(home), "settings.json");
+  return join(stateRoot(home), SETTINGS_NAME);
 }
 
 // The default unless the mirror says otherwise, so a missing or damaged file
@@ -27,7 +30,7 @@ export async function readQuestionMode(home = homedir()): Promise<QuestionMode>
 }
 
 export async function writeQuestionMode(mode: QuestionMode, home = homedir()): Promise<void> {
-  await writeAtomic(questionModePath(home), `${JSON.stringify({ questionMode: mode })}\n`);
+  await writeFileIn(stateRoot(home), SETTINGS_NAME, `${JSON.stringify({ questionMode: mode })}\n`, { atomic: true });
 }
 
 type Settings = Pick<PluginSettings<(typeof questionSettings)["schema"]>, "read" | "subscribe">;
@@ -48,14 +51,17 @@ export function mirrorQuestionMode(settings: Settings, home = homedir()): { stop
     return write(state);
   });
   // A change heard while the first read is in flight is newer than that read.
-  const settled = settings.read().catch(() => null).then((state) => (changed ? writes : write(state)));
+  const settled = settings
+    .read()
+    .catch(() => null)
+    .then((state) => (changed ? writes : write(state)));
   return {
     settled,
     async stop() {
       await unsubscribe();
       await settled;
       await writes;
-      await rm(questionModePath(home), { force: true });
+      await removeIn(stateRoot(home), SETTINGS_NAME);
     },
   };
 }

package/server/skill.ts

@@ -1,9 +1,8 @@
-import { exec, execFile } from "node:child_process";
-import { lstat, mkdir, readFile, readlink, symlink, unlink } from "node:fs/promises";
+import { lstat, readFile, readlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
-import { promisify } from "node:util";
 import { paseoCommands, PLUGIN_ID } from "./launcher.ts";
+import { linkFolderIn, removeLinkIn, runCommandLine, runProgram } from "./system.ts";
 
 export const SKILL_NAME = "paseo-progress";
 
@@ -37,8 +36,8 @@ export async function skillState(path: string, pluginDirectory: string): Promise
 export async function relinkSkill(paths: string[], pluginDirectory: string): Promise<boolean> {
   let wrote = false;
   for (const path of paths) {
-    if (await skillState(path, pluginDirectory) !== "outdated") continue;
-    await unlink(path);
+    if ((await skillState(path, pluginDirectory)) !== "outdated") continue;
+    await removeLinkIn(dirname(path), basename(path));
     await link(path, pluginDirectory);
     wrote = true;
   }
@@ -60,19 +59,20 @@ export async function installSkill(paths: string[], pluginDirectory: string): Pr
 }
 
 async function link(path: string, pluginDirectory: string) {
-  await mkdir(dirname(path), { recursive: true });
-  // A junction on Windows, where a directory symlink needs admin rights or
-  // Developer Mode. Other systems ignore the type and make a symlink.
-  await symlink(skillSource(pluginDirectory), path, "junction");
+  await linkFolderIn(dirname(path), basename(path), skillSource(pluginDirectory));
 }
 
 // "current" once every folder that can take the link has it.
 export async function skillStatus(paths: string[], pluginDirectory: string) {
   const targets = await Promise.all(paths.map(async (path) => ({ path, state: await skillState(path, pluginDirectory) })));
   const states = targets.map((target) => target.state);
-  const state: SkillState = states.includes("outdated") ? "outdated"
-    : states.includes("missing") ? "missing"
-    : states.includes("current") ? "current" : "foreign";
+  const state: SkillState = states.includes("outdated")
+    ? "outdated"
+    : states.includes("missing")
+      ? "missing"
+      : states.includes("current")
+        ? "current"
+        : "foreign";
   return { state, targets };
 }
 
@@ -96,8 +96,8 @@ export async function findPluginDirectory(): Promise<string> {
 function askPaseo(cli: string) {
   const options = { timeout: 10_000 };
   return process.platform === "win32"
-    ? promisify(exec)(`"${cli}" plugin ls ${PLUGIN_ID} --json`, options)
-    : promisify(execFile)(cli, ["plugin", "ls", PLUGIN_ID, "--json"], options);
+    ? runCommandLine(`"${cli}" plugin ls ${PLUGIN_ID} --json`, options)
+    : runProgram(cli, ["plugin", "ls", PLUGIN_ID, "--json"], options);
 }
 
 // Runs once per load, when the server starts: an update reloads the bundle.
@@ -106,7 +106,9 @@ function askPaseo(cli: string) {
 let repair: Promise<unknown> | null = null;
 
 export function repairSkill(): Promise<unknown> {
-  repair ??= findPluginDirectory().then((directory) => relinkSkill(defaultSkillPaths(), directory)).catch(() => {});
+  repair ??= findPluginDirectory()
+    .then((directory) => relinkSkill(defaultSkillPaths(), directory))
+    .catch(() => {});
   return repair;
 }
 
@@ -118,7 +120,11 @@ export async function handleSkillStatus() {
 // SKILL.md's frontmatter holds one-line fields; only the description is shown.
 export function skillDocument(text: string): { markdown: string; description: string } {
   const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
-  const description = /^description:[ \t]*(.*)$/m.exec(frontmatter?.[1] ?? "")?.[1].trim().replace(/^(["'])(.*)\1$/, "$2") ?? "";
+  const description =
+    /^description:[ \t]*(.*)$/m
+      .exec(frontmatter?.[1] ?? "")?.[1]
+      .trim()
+      .replace(/^(["'])(.*)\1$/, "$2") ?? "";
   return { markdown: text.slice(frontmatter?.[0].length ?? 0).trimStart(), description };
 }
 

package/server/store.ts

@@ -2,27 +2,24 @@
 // in to saving. The working files never touch the repo: they live outside it,
 // one folder per worktree, so git never sees them and nothing needs hiding.
 // Only runs the user asks to save are written into the repo, one file per run.
-import { execFile } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { lstat, mkdir, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { readdir, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, normalize, resolve, sep } from "node:path";
-import { promisify } from "node:util";
+import { basename, join, normalize, resolve } from "node:path";
 import { latestRun, parseProgress } from "../shared/dashboard.ts";
 import { hasGitEntry, inGitFolder, outside } from "./paths.ts";
+import { makeFoldersIn, runProgram, writeFileIn } from "./system.ts";
 
 const SAVE_RUNS_KEY = "paseo-progress.saveRuns";
 
 // `directory` holds the working files. `shown` names it for people.
 export type Store = { directory: string; shown: string };
 
-// Git runs in the worktree through -C, started from the folder Node itself
-// lives in: Windows looks for a program in the folder it starts in before
-// PATH, and a cloned repo can commit a git.exe.
+// Git runs in the worktree through -C, never from it: a cloned repo can commit a git.exe.
 export async function git(root: string, args: string[]): Promise<{ code: number; stdout: string }> {
   try {
-    const { stdout } = await promisify(execFile)("git", ["-C", resolve(root), ...args], { cwd: dirname(process.execPath) });
+    const { stdout } = await runProgram("git", ["-C", resolve(root), ...args]);
     return { code: 0, stdout };
   } catch (error) {
     const failed = error as { code?: number | string; stdout?: string };
@@ -35,18 +32,6 @@ export function stateRoot(home = homedir()): string {
   return join(home, ".local", "state", "paseo-progress");
 }
 
-// Readers see the old file or the new one, never half of one.
-export async function writeAtomic(path: string, text: string): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  const temp = `${path}.${randomUUID()}.tmp`;
-  try {
-    await writeFile(temp, text);
-    await rename(temp, path);
-  } finally {
-    await rm(temp, { force: true });
-  }
-}
-
 // One folder per worktree on this computer, named so a person can tell which
 // worktree it belongs to.
 export function outsideDirectory(root: string, home = homedir()): string {
@@ -131,8 +116,16 @@ export async function setHistoryFolder(root: string, raw: string | null): Promis
 // title as it was at the start, so the name never changes and two runs never
 // share one.
 export function runFileName(startedAt: string, title: string): string {
-  const stamp = startedAt.replace(/\.\d+Z$/, "").replace(/[-:]/g, "").replace("T", "-");
-  const slug = title.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+  const stamp = startedAt
+    .replace(/\.\d+Z$/, "")
+    .replace(/[-:]/g, "")
+    .replace("T", "-");
+  const slug = title
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60);
   return `${stamp}${slug ? `-${slug}` : ""}.jsonl`;
 }
 
@@ -144,25 +137,17 @@ export async function saveRunCopy(root: string, text: string): Promise<void> {
   // The run the dashboard shows. A start line it can't read is no run.
   const [start] = latestRun(parseProgress(text).events);
   if (start?.event.type !== "run.start") return;
-  const lines = text.split("\n").slice(start.line - 1).filter((line) => line.trim());
-  const directory = await runsFolder(root, folder);
+  const lines = text
+    .split("\n")
+    .slice(start.line - 1)
+    .filter((line) => line.trim());
+  // The saved-runs folder in the real worktree, made one step at a time. None
+  // when any step is a link or a file: a cloned repo can commit a link that
+  // leads out of it.
+  const directory = await makeFoldersIn(await realpath(root), folder);
   if (!directory) return;
   // A rename replaces a link at the run's file instead of writing through it.
-  await writeAtomic(join(directory, runFileName(start.event.ts, start.event.title)), `${lines.join("\n")}\n`);
-}
-
-// The saved-runs folder in the real worktree, made one step at a time, or null
-// when any step is a link or a file: a cloned repo can commit a link that leads
-// out of it.
-async function runsFolder(root: string, folder: string): Promise<string | null> {
-  let directory = await realpath(root);
-  for (const name of folder.split(sep)) {
-    directory = join(directory, name);
-    const info = await lstat(directory).catch(() => null);
-    if (!info) await mkdir(directory);
-    else if (!info.isDirectory()) return null;
-  }
-  return directory;
+  await writeFileIn(directory, runFileName(start.event.ts, start.event.title), `${lines.join("\n")}\n`, { atomic: true });
 }
 
 // The folders directly inside one folder of the worktree ("" is the top), for
@@ -175,5 +160,5 @@ export async function listFolders(root: string, folder: string): Promise<{ folde
     throw error;
   });
   const folders = entries.filter((entry) => entry.isDirectory() && !inGitFolder(entry.name)).map((entry) => entry.name);
-  return { folder: checked.folder, folders: folders.sort((a, b) => a.localeCompare(b)) };
+  return { folder: checked.folder, folders: folders.toSorted((a, b) => a.localeCompare(b)) };
 }

package/server/system.ts

@@ -0,0 +1,113 @@
+// The only module in Progress that starts programs or changes files. The lint
+// config allows node:child_process and the fs functions that change files here
+// and in tests, nowhere else, so each new call gets these defaults.
+//
+// A program starts in LAUNCH_FOLDER unless the caller names a folder it has a
+// reason for. Windows looks for a program in the folder it starts in before
+// PATH, and a relative PATH entry resolves against that folder, so a bare name
+// started in a worktree could run a program the repo committed.
+//
+// A file change names a folder the caller trusts (the plugin's state folder, a
+// folder in the user's home, a worktree's real path) and a relative name
+// inside it. The name can't climb out with `..`, and no folder between the two
+// may be a link, which a cloned repo could commit to lead the change elsewhere.
+import { exec, execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFile, chmod, type FileHandle, lstat, mkdir, open, rename, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, sep } from "node:path";
+import { promisify } from "node:util";
+
+export const LAUNCH_FOLDER = dirname(process.execPath);
+
+export type RunOptions = { cwd?: string; timeout?: number };
+
+export function runProgram(program: string, args: readonly string[], { cwd = LAUNCH_FOLDER, ...options }: RunOptions = {}) {
+  return promisify(execFile)(program, args, { ...options, cwd, encoding: "utf8" });
+}
+
+// Through cmd.exe, for Windows .cmd programs, which Node can start only that way.
+export function runCommandLine(line: string, { cwd = LAUNCH_FOLDER, ...options }: RunOptions = {}) {
+  return promisify(exec)(line, { ...options, cwd, encoding: "utf8" });
+}
+
+export function openToRead(path: string): Promise<FileHandle> {
+  return open(path, "r");
+}
+
+function stepsOf(folder: string, name: string): string[] {
+  if (isAbsolute(name) || name.split(/[\\/]/).includes("..")) throw new Error(`${name} is not a name inside ${folder}.`);
+  return name.split(sep);
+}
+
+async function placeIn(folder: string, name: string): Promise<string> {
+  const steps = stepsOf(folder, name);
+  let step = folder;
+  for (const part of steps.slice(0, -1)) {
+    step = join(step, part);
+    if ((await lstat(step).catch(() => null))?.isSymbolicLink()) throw new Error(`${step} is a link, so nothing was written through it.`);
+  }
+  return join(folder, name);
+}
+
+// `atomic` writes beside the file, then renames over it: readers see the old
+// file or the new one, never half of one, and a link at the file is replaced
+// instead of written through.
+export async function writeFileIn(folder: string, name: string, text: string, { atomic = false, executable = false } = {}): Promise<void> {
+  const path = await placeIn(folder, name);
+  await mkdir(dirname(path), { recursive: true });
+  if (!atomic) {
+    await writeFile(path, text);
+  } else {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, text);
+      await rename(temporary, path);
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+  if (executable) await chmod(path, 0o755);
+}
+
+export async function appendFileIn(folder: string, name: string, text: string): Promise<void> {
+  await appendFile(await placeIn(folder, name), text);
+}
+
+// The trusted folder itself, with any missing parents.
+export async function makeFolder(folder: string): Promise<void> {
+  await mkdir(folder, { recursive: true });
+}
+
+// Fails with EEXIST when the folder is already there, so only one caller makes it.
+export async function createFolderIn(folder: string, name: string): Promise<void> {
+  await mkdir(await placeIn(folder, name));
+}
+
+// Makes each missing folder of `name` one at a time. Null when any of them is
+// a link or a file.
+export async function makeFoldersIn(folder: string, name: string): Promise<string | null> {
+  let directory = folder;
+  for (const part of stepsOf(folder, name)) {
+    directory = join(directory, part);
+    const info = await lstat(directory).catch(() => null);
+    if (!info) await mkdir(directory);
+    else if (!info.isDirectory()) return null;
+  }
+  return directory;
+}
+
+export async function removeIn(folder: string, name: string, { recursive = false } = {}): Promise<void> {
+  await rm(await placeIn(folder, name), { recursive, force: true });
+}
+
+// A junction on Windows, where a folder symlink needs admin rights or
+// Developer Mode. Other systems ignore the type and make a symlink.
+export async function linkFolderIn(folder: string, name: string, target: string): Promise<void> {
+  const path = await placeIn(folder, name);
+  await mkdir(dirname(path), { recursive: true });
+  await symlink(target, path, "junction");
+}
+
+export async function removeLinkIn(folder: string, name: string): Promise<void> {
+  await unlink(await placeIn(folder, name));
+}