@stevecastaneda/paseo-progress 0.1.8 → 0.2.1

package/server/progress-file.ts

@@ -1,24 +1,14 @@
 // Everything that reads or writes a worktree's progress files: the event log
-// the command appends to, the panel-opened marker, and the .gitignore that keeps
-// both out of git. The command and the panel's RPC handlers go through here, so
-// they always agree on where the files are and how they're read.
+// 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 { basename, dirname, join } from "node:path";
+import { join } from "node:path";
 import { EMPTY_DASHBOARD, parseProgress, reduceProgress, type Dashboard, type NextIds } from "../shared/dashboard.ts";
-import { EVENT_VERSION, eventSchema, PANEL_OPENED_FILE, PROGRESS_FILE, type ProgressEvent } from "../shared/events.ts";
+import { EVENT_VERSION, eventSchema, PANEL_OPENED_NAME, PROGRESS_FILE_NAME, type ProgressEvent } from "../shared/events.ts";
 import { withLock } from "./lock.ts";
 
-const SCRATCH_DIR = dirname(PROGRESS_FILE);
-const LOCK_FILE = `${PROGRESS_FILE}.lock`;
-
-// Names only this plugin's files, so they stay out of git without the user
-// editing their own .gitignore. Other files in .scratch/ are left to the repo.
-export const SCRATCH_GITIGNORE = `# Added by the progress plugin for Paseo so its files stay out of git.
-${basename(PROGRESS_FILE)}
-${basename(LOCK_FILE)}/
-${basename(PANEL_OPENED_FILE)}
-.gitignore
-`;
+const LOCK_NAME = `${PROGRESS_FILE_NAME}.lock`;
 
 // An event as a command builds it; `append` stamps the version and time.
 export type EventDraft = { [K in ProgressEvent["type"]]: Omit<Extract<ProgressEvent, { type: K }>, "v" | "ts"> }[ProgressEvent["type"]];
@@ -33,7 +23,7 @@ export interface ProgressRead {
   panelOpened: boolean;
 }
 
-// The parsed file per worktree, kept until its size or change time moves. The
+// The parsed file per folder, kept until its size or change time moves. The
 // file only grows, and the panel and pills read it every few seconds.
 const parsedFiles = new Map<string, { size: number; mtimeMs: number; ctimeMs: number; parsed: ReturnType<typeof parseProgress> }>();
 // Replaced file snapshots and their derived data can be collected together.
@@ -43,9 +33,9 @@ const dashboards = new WeakMap<ReturnType<typeof parseProgress>, { dashboard: Da
 // reuse the last one until the file changes or a stale or overdue time passes.
 // Stale and overdue checks use the daemon host's clock, the same clock the
 // command stamps events with.
-export async function readProgress(root: string, now = new Date()): Promise<ProgressRead> {
-  const parsed = await readParsed(root);
-  const panelOpened = await exists(join(root, PANEL_OPENED_FILE));
+export async function readProgress(directory: string, now = new Date()): Promise<ProgressRead> {
+  const parsed = await readParsed(directory);
+  const panelOpened = await exists(join(directory, PANEL_OPENED_NAME));
   if (parsed === null) return { configured: false, dashboard: EMPTY_DASHBOARD, panelOpened };
   let cached = dashboards.get(parsed);
   // A backwards clock jump must also re-evaluate stale/overdue state.
@@ -61,13 +51,15 @@ export async function readProgress(root: string, now = new Date()): Promise<Prog
 // that run at once take turns, so each sees the others' events and no two hand
 // out the same id. `write` may throw to append nothing.
 export async function appendProgress<T>(
-  root: string,
+  directory: string,
   now: () => Date,
   write: (state: { dashboard: Dashboard; nextIds: NextIds }) => { event: EventDraft; result: T },
+  // Runs before the lock is released, with the whole file as it now is.
+  after?: (text: string) => Promise<void>,
 ): Promise<T> {
-  await prepareScratch(root);
-  return withLock(join(root, LOCK_FILE), async () => {
-    const text = (await readText(root)) ?? "";
+  await mkdir(directory, { recursive: true });
+  return withLock(join(directory, LOCK_NAME), async () => {
+    const text = (await readText(directory)) ?? "";
     const { dashboard, nextIds } = reduceProgress(parseProgress(text), now());
     const { event, result } = write({ dashboard, nextIds });
     const checked = eventSchema.safeParse({ v: EVENT_VERSION, ts: now().toISOString(), ...withoutUndefined(event) });
@@ -76,54 +68,46 @@ 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" : "";
-    await appendFile(join(root, PROGRESS_FILE), `${lead}${JSON.stringify(checked.data)}\n`);
+    const line = `${lead}${JSON.stringify(checked.data)}\n`;
+    await appendFile(join(directory, PROGRESS_FILE_NAME), line);
+    await after?.(text + line);
     return result;
   });
 }
 
-export async function markPanelOpened(root: string): Promise<void> {
-  await prepareScratch(root);
-  await writeFile(join(root, PANEL_OPENED_FILE), "");
-}
-
-// Creates .scratch/ in the worktree and, the first time, its .gitignore. An
-// existing .gitignore is the user's, so it is never touched.
-async function prepareScratch(root: string): Promise<void> {
-  const directory = join(root, SCRATCH_DIR);
+export async function markPanelOpened(directory: string): Promise<void> {
   await mkdir(directory, { recursive: true });
-  await writeFile(join(directory, ".gitignore"), SCRATCH_GITIGNORE, { flag: "wx" }).catch((error: NodeJS.ErrnoException) => {
-    if (error.code !== "EEXIST") throw error;
-  });
+  await writeFile(join(directory, PANEL_OPENED_NAME), "");
 }
 
-async function readText(root: string): Promise<string | null> {
+async function readText(directory: string): Promise<string | null> {
   try {
-    return await readFile(join(root, PROGRESS_FILE), "utf8");
+    return await readFile(join(directory, PROGRESS_FILE_NAME), "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
     throw error;
   }
 }
 
-async function readParsed(root: string): Promise<ReturnType<typeof parseProgress> | null> {
-  const info = await stat(join(root, PROGRESS_FILE)).catch((error: NodeJS.ErrnoException) => {
+async function readParsed(directory: string): Promise<ReturnType<typeof parseProgress> | null> {
+  const info = await stat(join(directory, PROGRESS_FILE_NAME)).catch((error: NodeJS.ErrnoException) => {
     if (error.code === "ENOENT") return null;
     throw error;
   });
   if (!info) {
-    parsedFiles.delete(root);
+    parsedFiles.delete(directory);
     return null;
   }
-  const cached = parsedFiles.get(root);
+  const cached = parsedFiles.get(directory);
   if (cached && cached.size === info.size && cached.mtimeMs === info.mtimeMs && cached.ctimeMs === info.ctimeMs) return cached.parsed;
   // Stat before reading: if the file grows in between, the next stat won't match and it's read again.
-  const text = await readText(root);
+  const text = await readText(directory);
   if (text === null) {
-    parsedFiles.delete(root);
+    parsedFiles.delete(directory);
     return null;
   }
   const parsed = parseProgress(text);
-  parsedFiles.set(root, { size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, parsed });
+  parsedFiles.set(directory, { size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, parsed });
   return parsed;
 }
 

package/server/store.ts

@@ -0,0 +1,205 @@
+// Where a worktree's progress files live, and the run history a repo can opt
+// 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 } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { appendFile, mkdir, readdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, normalize, resolve } from "node:path";
+import { promisify } from "node:util";
+import { LEGACY_FOLDER, PANEL_OPENED_NAME, PROGRESS_FILE_NAME } from "../shared/events.ts";
+import { withLock } from "./lock.ts";
+import { outside } from "./paths.ts";
+
+const LOCK_NAME = `${PROGRESS_FILE_NAME}.lock`;
+const SAVE_RUNS_KEY = "paseo-progress.saveRuns";
+// Exactly what 0.1.x wrote into .scratch/.gitignore. Only this is ever removed.
+const LEGACY_GITIGNORE = `# Added by the progress plugin for Paseo so its files stay out of git.
+${PROGRESS_FILE_NAME}
+${LOCK_NAME}/
+${PANEL_OPENED_NAME}
+.gitignore
+`;
+
+// `directory` holds the working files. `shown` names it for people.
+export type Store = { directory: string; shown: string };
+
+export async function git(cwd: string, args: string[]): Promise<{ code: number; stdout: string }> {
+  try {
+    const { stdout } = await promisify(execFile)("git", args, { cwd });
+    return { code: 0, stdout };
+  } catch (error) {
+    const failed = error as { code?: number | string; stdout?: string };
+    return { code: typeof failed.code === "number" ? failed.code : -1, stdout: failed.stdout ?? "" };
+  }
+}
+
+async function exists(path: string): Promise<boolean> {
+  return Boolean(await stat(path).catch(() => null));
+}
+
+// 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 {
+  let real = root;
+  try {
+    real = realpathSync(root);
+  } catch {}
+  const hash = createHash("sha1").update(real).digest("hex").slice(0, 8);
+  return join(home, ".local", "state", "paseo-progress", `${basename(real)}-${hash}`);
+}
+
+// Whether git tracks a 0.1.x progress file, per worktree, until the file changes.
+const trackedLegacy = new Map<string, { mtimeMs: number; tracked: boolean }>();
+
+async function legacyTracked(root: string, mtimeMs: number): Promise<boolean> {
+  const cached = trackedLegacy.get(root);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.tracked;
+  const { code } = await git(root, ["ls-files", "--error-unmatch", "--", `${LEGACY_FOLDER}/${PROGRESS_FILE_NAME}`]);
+  trackedLegacy.set(root, { mtimeMs, tracked: code === 0 });
+  return code === 0;
+}
+
+// The worktree's working files. A run 0.1.x left in .scratch moves outside the
+// first time anything asks, unless git tracks it: then it stays and is used in
+// place, so nothing changes for a repo that commits it.
+export async function findStore(root: string, home = homedir()): Promise<Store> {
+  const directory = outsideDirectory(root, home);
+  const store = { directory, shown: directory.startsWith(home) ? `~${directory.slice(home.length)}` : directory };
+  const legacy = join(root, LEGACY_FOLDER);
+  const info = await stat(join(legacy, PROGRESS_FILE_NAME)).catch(() => null);
+  if (!info) return store;
+  if (await legacyTracked(root, info.mtimeMs)) return { directory: legacy, shown: LEGACY_FOLDER };
+  await moveLegacy(legacy, directory);
+  return store;
+}
+
+// Appends the old file's lines to the new one rather than replacing it, so a
+// command that wrote to the old place mid-move loses nothing: the next move
+// picks those lines up. Then tidies what 0.1.x left behind.
+async function moveLegacy(legacy: string, directory: string): Promise<void> {
+  await mkdir(directory, { recursive: true });
+  await withLock(join(legacy, LOCK_NAME), async () => {
+    const text = await readFile(join(legacy, PROGRESS_FILE_NAME), "utf8").catch(() => null);
+    if (text === null) return;
+    await withLock(join(directory, LOCK_NAME), async () => {
+      const current = await readFile(join(directory, PROGRESS_FILE_NAME), "utf8").catch(() => "");
+      const lead = current && !current.endsWith("\n") ? "\n" : "";
+      await appendFile(join(directory, PROGRESS_FILE_NAME), `${lead}${text}`);
+    });
+    await rm(join(legacy, PROGRESS_FILE_NAME));
+    if (await exists(join(legacy, PANEL_OPENED_NAME))) {
+      await writeFile(join(directory, PANEL_OPENED_NAME), "");
+      await rm(join(legacy, PANEL_OPENED_NAME));
+    }
+  });
+  const ignore = await readFile(join(legacy, ".gitignore"), "utf8").catch(() => null);
+  if (ignore === LEGACY_GITIGNORE) await rm(join(legacy, ".gitignore"));
+  // Only if nothing else is in there; the user's own files keep the folder.
+  await rmdir(legacy).catch(() => {});
+}
+
+// The repo's saved-history folder, kept in its local git config, which every
+// worktree of the repo shares and nothing commits. Polls cost one stat; git
+// runs again only when the config file changes.
+const configFiles = new Map<string, string | null>();
+const savedFolders = new Map<string, { mtimeMs: number; folder: string | null }>();
+
+async function configFile(root: string): Promise<string | null> {
+  if (!configFiles.has(root)) {
+    const { code, stdout } = await git(root, ["rev-parse", "--git-common-dir"]);
+    configFiles.set(root, code === 0 ? join(resolve(root, stdout.trim()), "config") : null);
+  }
+  return configFiles.get(root)!;
+}
+
+// Whether the worktree is in a git repo, which saving run history needs.
+export async function inGitRepo(root: string): Promise<boolean> {
+  return (await configFile(root)) !== null;
+}
+
+// The folder runs are saved to, relative to the worktree root, or null.
+export async function historyFolder(root: string): Promise<string | null> {
+  const file = await configFile(root);
+  if (file === null) return null;
+  const mtimeMs = (await stat(file).catch(() => null))?.mtimeMs ?? 0;
+  const cached = savedFolders.get(file);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.folder;
+  const { stdout } = await git(root, ["config", "--get", SAVE_RUNS_KEY]);
+  const folder = stdout.trim() || null;
+  savedFolders.set(file, { mtimeMs, folder });
+  return folder;
+}
+
+// A folder the user picked, as a clean path inside the worktree, or why not.
+export function checkFolder(raw: string): { folder: string } | { error: string } {
+  const trimmed = raw.trim().replace(/\/+$/, "");
+  if (!trimmed) return { error: "Choose a folder" };
+  const folder = normalize(trimmed);
+  if (outside(folder) || folder === ".") return { error: "Choose a folder inside the repo" };
+  if (folder === ".git" || folder.startsWith(".git/")) return { error: "Choose a folder outside .git" };
+  return { folder };
+}
+
+// Starts or stops saving runs for the whole repo. Files already saved stay.
+export async function setHistoryFolder(root: string, raw: string | null): Promise<string | null> {
+  if (raw === null) {
+    const { code } = await git(root, ["config", "--local", "--unset-all", SAVE_RUNS_KEY]);
+    // 5: it wasn't set, which is what was asked for.
+    if (code !== 0 && code !== 5) throw new Error("Could not change this repo's git settings.");
+    return null;
+  }
+  const checked = checkFolder(raw);
+  if ("error" in checked) throw new Error(checked.error);
+  const { code } = await git(root, ["config", "--local", SAVE_RUNS_KEY, checked.folder]);
+  if (code !== 0) throw new Error("Could not save this in the repo's git settings. Is it a git repo?");
+  return checked.folder;
+}
+
+// "20261001-064512-warn-when-scratch.jsonl": when the run started, then its
+// 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);
+  return `${stamp}${slug ? `-${slug}` : ""}.jsonl`;
+}
+
+// After each change: when the repo saves runs, rewrite the current run's file
+// with every event from its start. Runs before the first start aren't saved.
+export async function saveRunCopy(root: string, text: string): Promise<void> {
+  const folder = await historyFolder(root);
+  if (!folder) return;
+  const lines = text.split("\n").filter((line) => line.trim());
+  let start = -1;
+  let event: { ts?: string; title?: string } | null = null;
+  for (let index = lines.length - 1; index >= 0; index--) {
+    try {
+      const parsed = JSON.parse(lines[index]);
+      if (parsed?.type === "run.start") {
+        start = index;
+        event = parsed;
+        break;
+      }
+    } catch {}
+  }
+  if (start < 0 || !event?.ts || !event.title) return;
+  const directory = join(root, folder);
+  await mkdir(directory, { recursive: true });
+  await writeFile(join(directory, runFileName(event.ts, event.title)), `${lines.slice(start).join("\n")}\n`);
+}
+
+// The folders directly inside one folder of the worktree ("" is the top), for
+// the folder picker. .git is left out; so are links, which could leave the repo.
+export async function listFolders(root: string, folder: string): Promise<{ folder: string; folders: string[] }> {
+  const checked = folder === "" ? { folder: "" } : checkFolder(folder);
+  if ("error" in checked) throw new Error(checked.error);
+  const entries = await readdir(join(root, checked.folder), { withFileTypes: true }).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  });
+  const folders = entries.filter((entry) => entry.isDirectory() && !(checked.folder === "" && entry.name === ".git")).map((entry) => entry.name);
+  return { folder: checked.folder, folders: folders.sort((a, b) => a.localeCompare(b)) };
+}

package/shared/events.ts

@@ -1,11 +1,13 @@
 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";
+// One line of `progress.jsonl`. The command-line tool writes these; the
+// dashboard reducer reads them. `v` lets later versions change a shape without
+// misreading old files. Which folder holds it is set up per repo.
+export const PROGRESS_FILE_NAME = "progress.jsonl";
 // Present once someone has opened the Progress panel for this worktree.
-export const PANEL_OPENED_FILE = ".scratch/progress-panel-opened";
+export const PANEL_OPENED_NAME = "progress-panel-opened";
+// Where 0.1.x kept each worktree's files. store.ts moves them out.
+export const LEGACY_FOLDER = ".scratch";
 export const EVENT_VERSION = 1;
 
 export const TICKET_STATUSES = ["not_started", "working", "blocked", "done", "skipped"] as const;

package/shared/rpc.ts

@@ -5,8 +5,13 @@ import type { Dashboard } from "./dashboard.ts";
 // `panelOpened`: the Progress panel has been opened for this worktree before.
 // `root`: the worktree root the file was read from, which stored paths are
 // relative to. It can sit above the workspace directory.
+// `file`: where the progress file is, for people. `savedTo`: the repo folder
+// each run is saved to, or null when history stays on this computer.
+// `inRepo`: saving history needs a git repo to keep the choice in.
 // `version` changes whenever anything else in the result does.
-export type DashboardResult = { configured: boolean; dashboard: Dashboard; panelOpened: boolean; root: string; version: string };
+export type DashboardResult = {
+  configured: boolean; dashboard: Dashboard; panelOpened: boolean; file: string; savedTo: string | null; inRepo: boolean; root: string; version: string;
+};
 
 export const getDashboard = defineRpc({
   name: "progress.get",
@@ -83,6 +88,30 @@ export const installSkill = defineRpc({
   output: skillStatus,
 });
 
+// The folders inside one folder of the worktree ("" is the top), for the
+// folder picker.
+export const listFolders = defineRpc({
+  name: "progress.folders.list",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+    folder: z.string(),
+  }),
+  output: z.object({ folder: z.string(), folders: z.array(z.string()) }),
+});
+
+// Starts saving each run to a folder in the repo (relative to the worktree
+// root), for every worktree of the repo, or stops when `folder` is null.
+export const setHistoryFolder = defineRpc({
+  name: "progress.history.set",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+    folder: z.string().nullable(),
+  }),
+  output: z.object({ savedTo: z.string().nullable() }),
+});
+
 // Opens a recorded local deliverable on the daemon host with its default app.
 export const openDeliverable = defineRpc({
   name: "progress.deliverable.open",