@harborppm/cli 0.22.0 → 0.28.0

package/README.md

@@ -92,6 +92,11 @@ 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 hill [--program P]                   where each project is on its hill
+harbor hill PROJECT --at 0-100|top|done     move it: up to 50 is figuring it out,
+                                            past 50 is getting it done
 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.
@@ -3913,6 +4062,48 @@ function CalendarView({ active, width, height, go }) {
 	});
 }
 
+//#endregion
+//#region src/lib/hill.ts
+/**
+* Hill charts, after Basecamp's Shape Up: each project is a dot on a hill.
+* Climbing the left side means still figuring out how to do it; rolling down
+* the right means the unknowns are solved and it's just the work. Owners
+* place their own dot, and a dot nobody has moved in two weeks fades, so a
+* stuck project shows without anyone saying so.
+*/
+/** Where the top of the hill is, on the 0–100 scale. */
+const HILL_TOP = 50;
+/** Days without a move before a dot reads as still. */
+const STILL_DAYS = 14;
+const HILL_PHASE_LABEL = {
+	figuring: "Figuring it out",
+	doing: "Getting it done"
+};
+/** A position kept on the scale, in whole steps. */
+function clampHill(at) {
+	if (!Number.isFinite(at)) return 0;
+	return Math.max(0, Math.min(100, Math.round(at)));
+}
+function hillPhase(at) {
+	return clampHill(at) < 50 ? "figuring" : "doing";
+}
+/** Days since the dot last moved, or null when it's never been placed. */
+function stillFor(project, today) {
+	if (!project.hillMovedAt) return null;
+	return Math.max(0, differenceInCalendarDays(/* @__PURE__ */ new Date(`${today}T12:00:00`), /* @__PURE__ */ new Date(`${project.hillMovedAt.slice(0, 10)}T12:00:00`)));
+}
+function isStill(project, today) {
+	const days = stillFor(project, today);
+	return days != null && days >= 14;
+}
+/** "Figuring it out, 40 of 100", or "Not on the hill yet". */
+function hillText(project) {
+	if (project.hillAt == null) return "Not on the hill yet";
+	const at = clampHill(project.hillAt);
+	if (at === 100) return "Over the hill: done";
+	return `${HILL_PHASE_LABEL[hillPhase(at)]} (${at} of 100)`;
+}
+
 //#endregion
 //#region src/lib/history-copy.ts
 /**
@@ -4082,6 +4273,10 @@ function describeEvent(e, names) {
 			action: "cleared the health override on",
 			detail: null
 		};
+		case "hillAt": return {
+			action: "moved",
+			detail: `on the hill to ${hillText({ hillAt: to == null ? null : Number(to) }).toLowerCase()}`
+		};
 		case "programId": return {
 			action: "moved",
 			detail: `to ${nameOf$1(names, to, "another program")}`
@@ -5326,7 +5521,7 @@ const HELP = [
 	["Enter / Esc", "open / back"],
 	["n", "new: a task, or what the screen lists"],
 	["e", "change what's open (health, lead, dates)"],
-	["[ ]", "move a card one column left or right"],
+	["[ ] / { }", "move a card a column / a project along its hill"],
 	["x / d", "mark done / delete (asks first)"],
 	["u / r", "undo your last change / retry saving"],
 	["v", "switch layout: board, list, budget, by project"],
@@ -7056,6 +7251,10 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 			else if (input === "d" && entry) go.confirm(`Take out ${money(entry.amount)}${entry.note ? ` for “${entry.note}”` : ""}? u undoes it.`, () => store.getState().removeSpend(entry.id), "Take it out");
 			return;
 		}
+		if ((input === "{" || input === "}") && project) {
+			const at = project.hillAt ?? (input === "}" ? -5 : 0);
+			return store.getState().moveOnHill(projectId, at + (input === "}" ? 5 : -5));
+		}
 		if (input === "[") return moveSelected(-1);
 		if (input === "]") return moveSelected(1);
 		if (key.return && selected) return go.openTask(selected.id);
@@ -7086,6 +7285,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;
@@ -7149,9 +7349,19 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 					})
 				})]
 			}),
-			/* @__PURE__ */ jsx(Text, {
-				color: theme.muted,
-				children: " "
+			/* @__PURE__ */ jsxs(Text, {
+				wrap: "truncate-end",
+				children: [/* @__PURE__ */ jsx(Text, {
+					color: tide?.late ? theme.warn : theme.muted,
+					children: tide ? `${tide.text} · ` : ""
+				}), /* @__PURE__ */ jsxs(Text, {
+					color: isStill(project, day) ? theme.warn : theme.muted,
+					children: [
+						project.hillAt == null ? "Not on the hill · } puts it on" : `Hill: ${hillText(project).toLowerCase()}`,
+						isStill(project, day) ? `, still ${stillFor(project, day)} days` : "",
+						project.hillAt == null ? "" : " · { } move it"
+					]
+				})]
 			}),
 			mode === "budget" ? /* @__PURE__ */ jsx(BudgetPane, {
 				project,
@@ -9623,6 +9833,14 @@ function hierarchySlice({ get, write }) {
 				...patch
 			} : p) });
 		},
+		moveOnHill: (id, at) => {
+			const hillAt = clampHill(at);
+			write({ projects: get().projects.map((p) => p.id === id ? {
+				...p,
+				hillAt,
+				hillMovedAt: stamp()
+			} : p) });
+		},
 		addCustomField: (projectId, def) => {
 			const id = uid("cf");
 			write({ projects: get().projects.map((p) => p.id === projectId ? {

package/lib/cli.mjs

@@ -17,9 +17,12 @@ import {
   writeSettings,
 } from "./config.mjs";
 import {
+  forecastList,
+  forecastOne,
   STATUS,
   harbors,
   limitsText,
+  hillList,
   myWork,
   premortemText,
   voyageText,
@@ -61,6 +64,10 @@ 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 hill [--program P]                   where each project is on its hill
+  harbor hill PROJECT --at 0-100|top|done     move it: up to 50 is figuring it
+                                              out, past 50 is getting it done
   harbor mine                                 what's on you, late first
   harbor tasks [words] [--project P] [--assignee me|none|NAME]
                      [--late] [--status S,S]
@@ -220,6 +227,7 @@ const FLAG = {
   body: "the comment",
   column: "the column",
   limit: "the limit",
+  at: "--at",
 };
 
 /** Harbor's refusals are worded for agents; say them as the commands and flags that answer them. */
@@ -825,6 +833,33 @@ 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 "hill": {
+      const { positionals, values, harbor } = parse(spec([], ["program", "at"]));
+      const project = positionals.join(" ").trim();
+      if (!project) {
+        if (values.at !== undefined)
+          throw new HarborError("Say which project: harbor hill PROJECT --at N.");
+        return call("list_projects", { harbor, program: values.program, limit: 100 }, hillList);
+      }
+      if (values.at === undefined) {
+        throw new HarborError("Say where with --at: 0 to 100, or start, top, doing or done.");
+      }
+      const at = readHillWord(values.at);
+      if (at === null)
+        throw new HarborError("--at is 0 to 100, or start, figuring, top, doing or done.");
+      return call(
+        "move_on_hill",
+        { harbor, project, at },
+        (r) =>
+          `Moved ${r.moved.project} on the hill: ${r.moved.where.replace(/^\w/, (c) => c.toLowerCase())}.`,
+      );
+    }
     case "mine": {
       const { positionals, harbor } = parse(spec());
       none(positionals);
@@ -1214,3 +1249,10 @@ export async function run(argv, io = {}) {
       throw new HarborError(`No command "${command}". Run harbor help.`);
   }
 }
+
+/** --at for harbor hill: a number 0–100 or a word (src/lib/hill.ts readHill says the same). */
+function readHillWord(text) {
+  const t = String(text).trim().toLowerCase();
+  if (/^\d{1,3}$/.test(t)) return Number(t) <= 100 ? Number(t) : null;
+  return { start: 0, figuring: 25, top: 50, doing: 75, done: 100 }[t] ?? null;
+}

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) {
@@ -238,3 +287,37 @@ export function voyageText(r) {
     "\n",
   );
 }
+
+/** A position on a 21-wide track, the top of the hill marked in the middle. */
+function hillTrack(at) {
+  const cells = Array.from({ length: 21 }, (_, i) => (i === 10 ? "┼" : "─"));
+  cells[Math.round(at / 5)] = "●";
+  return cells.join("");
+}
+
+/** Each open project's place on its program's hill, by program, unplaced ones named after. */
+export function hillList(r) {
+  const projects = (r.projects ?? []).filter((p) => p.health !== "done");
+  if (!projects.length) return "No open projects match.";
+  const byProgram = new Map();
+  for (const p of projects) {
+    const key = p.program ?? "No program";
+    if (!byProgram.has(key)) byProgram.set(key, []);
+    byProgram.get(key).push(p);
+  }
+  const width = Math.min(28, Math.max(...projects.map((p) => p.name.length)));
+  const blocks = [];
+  for (const [program, list] of byProgram) {
+    const placed = list.filter((p) => p.hill).sort((a, b) => a.hill.at - b.hill.at);
+    const unplaced = list.filter((p) => !p.hill);
+    const lines = [program, `  ${"".padEnd(width)}  figuring it out ┼ getting it done`];
+    for (const p of placed) {
+      const name = p.name.length > width ? `${p.name.slice(0, width - 1)}…` : p.name.padEnd(width);
+      const still = p.hill.daysSinceMoved >= 14 ? `  still ${p.hill.daysSinceMoved} days` : "";
+      lines.push(`  ${name}  ${hillTrack(p.hill.at)} ${String(p.hill.at).padStart(3)}${still}`);
+    }
+    if (unplaced.length) lines.push(`  Not on the hill: ${unplaced.map((p) => p.name).join(", ")}`);
+    blocks.push(lines.join("\n"));
+  }
+  return blocks.join("\n\n");
+}

package/package.json

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