@harborppm/cli 0.22.0 → 0.24.0

package/README.md

@@ -92,6 +92,8 @@ harbor harbors                              the harbors you belong to
 harbor use HARBOR|none                      the harbor to work in when you're in several
 harbor programs                             programs and their projects
 harbor projects [words] [--program P]       projects with health and open work
+harbor forecast [PROJECT] [--program P]     when projects will likely finish, from
+                                            how fast their crews finish tasks
 harbor mine                                 what's on you, late first
 harbor tasks [words] [--project P] [--assignee me|none|NAME] [--late] [--status S,S]
 harbor show TASK                            one task in full, with its web link

package/dist/app.mjs

@@ -1591,6 +1591,132 @@ function forecastAtCompletion(item, now) {
 	};
 }
 
+//#endregion
+//#region src/lib/tide.ts
+/**
+* The tide forecast: when a project will likely finish, from how fast its
+* crew has actually closed tasks. Each of a thousand runs replays the coming
+* weeks by drawing at random from the project's recent weekly counts, until
+* the open tasks run out; the spread of finish days is the forecast. No
+* estimates or story points: only tasks and when they were finished.
+*
+* Seeded from the project and the day, so the same project reads the same
+* on the server and the client and doesn't jitter between renders.
+*/
+/** How many weeks back the crew's pace is read from. */
+const TIDE_WEEKS = 6;
+const TRIALS = 1e3;
+/** A run that hasn't finished in two years is counted as not finishing. */
+const MAX_WEEKS = 104;
+/** Fewer finished tasks than this and the forecast says it's rough. */
+const ROUGH_BELOW = 5;
+const noon = (iso) => /* @__PURE__ */ new Date(`${iso.slice(0, 10)}T12:00:00`);
+/** Tasks finished in each of the last weeks, oldest first. Done tasks without a date, or dated after now, count as finished now. */
+function weeklyFinished(tasks, startDate, now, weeks = 6) {
+	const today = noon(todayISO(now));
+	const age = Math.floor(differenceInCalendarDays(today, noon(startDate)) / 7) + 1;
+	const span = Math.max(1, Math.min(weeks, age));
+	const counts = new Array(span).fill(0);
+	for (const t of tasks) {
+		if (t.status !== "done") continue;
+		const at = t.completedAt ? noon(t.completedAt) : today;
+		const back = Math.max(0, differenceInCalendarDays(today, at));
+		const week = Math.floor(back / 7);
+		if (week < span) counts[span - 1 - week] += 1;
+	}
+	return counts;
+}
+function hash(text) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i++) {
+		h ^= text.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return h >>> 0;
+}
+/** mulberry32: small, fast, and the same everywhere for the same seed. */
+function random(seed) {
+	let a = seed;
+	return () => {
+		a = a + 1831565813 | 0;
+		let t = Math.imul(a ^ a >>> 15, 1 | a);
+		t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/** Days from today to finishing, one per run; Infinity for a run that never does. */
+function simulate(remaining, weekly, seed) {
+	const next = random(seed);
+	const out = [];
+	for (let run = 0; run < TRIALS; run++) {
+		let left = remaining;
+		let days = Infinity;
+		for (let week = 0; week < MAX_WEEKS; week++) {
+			const closed = weekly[Math.floor(next() * weekly.length)];
+			if (closed >= left) {
+				const landed = Array.from({ length: closed }, () => 1 + Math.floor(next() * 7));
+				landed.sort((a, b) => a - b);
+				days = week * 7 + landed[left - 1];
+				break;
+			}
+			left -= closed;
+		}
+		out.push(days);
+	}
+	return out.sort((a, b) => a - b);
+}
+function tideForecast(project, tasks, now) {
+	const remaining = tasks.filter((t) => t.status !== "done").length;
+	if (remaining === 0) return { kind: "done" };
+	if (project.health === "paused") return {
+		kind: "paused",
+		remaining
+	};
+	const weekly = weeklyFinished(tasks, project.startDate, now);
+	const finished = weekly.reduce((a, b) => a + b, 0);
+	if (finished === 0) return {
+		kind: "no-pace",
+		remaining
+	};
+	const today = todayISO(now);
+	const runs = simulate(remaining, weekly, hash(`${project.id}|${remaining}|${today}`));
+	const base = noon(today);
+	const dayOf = (days) => Number.isFinite(days) ? todayISO(addDays(base, days)) : null;
+	const at = (share) => runs[Math.min(runs.length - 1, Math.ceil(share * runs.length) - 1)];
+	const toEnd = differenceInCalendarDays(noon(project.endDate), base);
+	const byEnd = runs.filter((d) => d <= toEnd).length / runs.length;
+	const last = Math.max(Number.isFinite(at(.99)) ? at(.99) : 728, toEnd + 14, 7);
+	const curve = [];
+	const step = Math.max(1, Math.ceil(last / 60));
+	let i = 0;
+	for (let d = 0; d <= last; d += step) {
+		while (i < runs.length && runs[i] <= d) i++;
+		curve.push({
+			date: dayOf(d),
+			chance: i / runs.length
+		});
+	}
+	return {
+		kind: "forecast",
+		remaining,
+		finished,
+		weeks: weekly.length,
+		perWeek: Math.round(finished / weekly.length * 10) / 10,
+		likely: dayOf(at(.5)),
+		veryLikely: dayOf(at(.85)),
+		almostCertain: dayOf(at(.95)),
+		chanceByEnd: Math.round(byEnd * 100) / 100,
+		curve,
+		rough: finished < ROUGH_BELOW
+	};
+}
+/** "15%", with "under 5%" and "over 95%" at the ends, where a thousand runs can't be that sure. */
+function chanceText(chance) {
+	if (chance < .05) return "under 5%";
+	if (chance > .95) return "over 95%";
+	return `${Math.round(chance * 20) * 5}%`;
+}
+
 //#endregion
 //#region src/lib/flow.ts
 const WINDOW_DAYS = 30;
@@ -2338,6 +2464,29 @@ function filterTasks(tasks, f) {
 	return tasks.filter((t) => (f.who === "any" || (f.who === "none" ? t.assigneeId === null : t.assigneeId === f.who)) && (f.priority === "any" || t.priority === f.priority));
 }
 /**
+* When the project will likely finish at its crew's recent pace, in one
+* line under its name, and whether that misses the end date. Empty when
+* there's no forecast (all done, paused, or nothing finished lately).
+*/
+function tideLine(data, project, today) {
+	const tide = tideForecast(project, tasksOf(data.tasks, project.id), parseIso(`${today}T12:00:00`));
+	if (tide.kind === "no-pace") return {
+		text: "No forecast yet: nothing finished in the last few weeks",
+		late: false
+	};
+	if (tide.kind !== "forecast") return null;
+	if (!tide.likely) return {
+		text: "Not done in the next two years at this pace",
+		late: true
+	};
+	const very = tide.veryLikely ? `, very likely by ${shortDay(tide.veryLikely, today)}` : "";
+	const end = project.endDate >= today ? ` · ${chanceText(tide.chanceByEnd)} by its end, ${shortDay(project.endDate, today)}` : "";
+	return {
+		text: `Probably done ${shortDay(tide.likely, today)}${very}${end}${tide.rough ? " · rough" : ""}`,
+		late: tide.chanceByEnd < .5
+	};
+}
+/**
 * Bands of lines, each line owned by one item (a program or a project):
 * the first line to show so the selected band fits, scrolling as little
 * as it can from the top.
@@ -7086,6 +7235,7 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 		})
 	});
 	const { done, total } = projectSummary(data, project);
+	const tide = tideLine(data, project, day);
 	const filtered = [filter.who === "none" ? "nobody's" : filter.who !== "any" ? `${people.find((p) => p.id === filter.who)?.name ?? "someone"}'s` : null, filter.priority !== "any" ? PRIORITY_LABEL[filter.priority].toLowerCase() : null].filter(Boolean);
 	const lead = people.find((p) => p.id === project.ownerId);
 	const body = height - 3;
@@ -7150,8 +7300,9 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 				})]
 			}),
 			/* @__PURE__ */ jsx(Text, {
-				color: theme.muted,
-				children: " "
+				color: tide?.late ? theme.warn : theme.muted,
+				wrap: "truncate-end",
+				children: tide ? tide.text : " "
 			}),
 			mode === "budget" ? /* @__PURE__ */ jsx(BudgetPane, {
 				project,

package/lib/cli.mjs

@@ -17,6 +17,8 @@ import {
   writeSettings,
 } from "./config.mjs";
 import {
+  forecastList,
+  forecastOne,
   STATUS,
   harbors,
   limitsText,
@@ -61,6 +63,7 @@ export const HELP = `harbor: Harbor from the terminal
   harbor projects [words] [--program P] [--done]
                                               projects with health and open work
                                               (--json adds each board's limits)
+  harbor forecast [PROJECT] [--program P]     when projects will likely finish
   harbor mine                                 what's on you, late first
   harbor tasks [words] [--project P] [--assignee me|none|NAME]
                      [--late] [--status S,S]
@@ -825,6 +828,12 @@ export async function run(argv, io = {}) {
           `Opened the project ${r.created.name} in ${r.created.program} (${r.created.starts} to ${r.created.ends}, lead ${r.created.lead ?? "nobody"}). Add work with harbor add "TITLE" --project "${r.created.name}".`,
       );
     }
+    case "forecast": {
+      const { positionals, values, harbor } = parse(spec([], ["program"]));
+      const project = positionals.join(" ").trim();
+      if (project) return call("get_project", { harbor, project }, forecastOne);
+      return call("list_projects", { harbor, program: values.program, limit: 100 }, forecastList);
+    }
     case "mine": {
       const { positionals, harbor } = parse(spec());
       none(positionals);

package/lib/format.mjs

@@ -199,6 +199,55 @@ export function raidList(r, words = "") {
   return lines.join("\n") + more;
 }
 
+/** "over 95%", in steps of five, as the website says it (src/lib/tide.ts chanceText). */
+function chance(c) {
+  if (c < 0.05) return "under 5%";
+  if (c > 0.95) return "over 95%";
+  return `${Math.round(c * 20) * 5}%`;
+}
+
+function finishRange(f) {
+  if (!f.likely) return "not in the next two years at this pace";
+  return `probably ${f.likely}${f.veryLikely ? `, very likely by ${f.veryLikely}` : ""}`;
+}
+
+/** When each open project will likely finish at its crew's recent pace. */
+export function forecastList(r) {
+  const projects = (r.projects ?? []).filter((p) => p.health !== "done");
+  if (!projects.length) return "No open projects match.";
+  const width = Math.min(32, Math.max(...projects.map((p) => p.name.length)));
+  return projects
+    .map((p) => {
+      const f = p.finish ?? {};
+      const name = p.name.length > width ? `${p.name.slice(0, width - 1)}…` : p.name.padEnd(width);
+      if (f.none) return `${name}  no forecast: ${f.none.replace(/^\w/, (c) => c.toLowerCase())}`;
+      const end = p.ends ? ` · ${chance(f.chanceByEnd)} by its end, ${p.ends}` : "";
+      return `${name}  ${finishRange(f)}${end}${f.rough ? " · rough" : ""}`;
+    })
+    .join("\n");
+}
+
+/** One project's forecast, in a few sentences. */
+export function forecastOne(p) {
+  const f = p.finish ?? {};
+  if (f.none) return `${p.name}: ${f.none}`;
+  const range = finishRange(f);
+  const lines = [
+    f.likely
+      ? `${p.name} will ${range.replace(/^probably/, "probably finish")}${f.almostCertain ? `, almost certainly by ${f.almostCertain}` : ""}.`
+      : `${p.name} won't finish in the next two years at this pace.`,
+  ];
+  if (p.ends) {
+    const c = chance(f.chanceByEnd);
+    lines.push(`${c[0].toUpperCase()}${c.slice(1)} chance of making its end date, ${p.ends}.`);
+  }
+  lines.push(
+    `${f.openTasks} task${f.openTasks === 1 ? "" : "s"} open; the crew finishes about ${f.finishedPerWeek} a week (${f.basedOn}).`,
+  );
+  if (f.rough) lines.push("Only a few tasks have finished, so treat this as rough.");
+  return lines.join("\n");
+}
+
 /** A project's pre-mortem, as get_premortem answers it. */
 export function premortemText(r) {
   if (!r.running) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",