@harborppm/cli 0.77.0 → 0.78.0

package/README.md

@@ -215,6 +215,7 @@ harbor voyage PROJECT ["YOUR LINE"]
 harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
 harbor sound TASK [--answer DAYS|--ask NAMES|--settle DAYS] [--why TEXT]
 harbor soundings [PROJECT]
+harbor goals [PORTFOLIO]                    each portfolio's goals, off track first
 harbor ashore [--weeks N] [--country CODES|none] [--person NAME]
 harbor limit PROJECT [COLUMN N|none]
 harbor week [--next|--last|--week DATE] [--review]
@@ -256,7 +257,7 @@ A task has one owner (`--assignee`), who answers for it and whose load it counts
 
 `harbor limit RR` prints how many tasks each of a board's columns takes at once; `harbor limit RR doing 8` changes one (1 to 20, or `none` for no limit), if you own the harbor. `harbor projects --json` carries each board's `limits` too.
 
-`harbor premortem` runs a pre-mortem with your crew: `--start` asks everyone "it's after the end date and this project failed: what happened?", each person adds answers alone for five minutes, and then the answers show together on the project's Risks & issues tab, where each becomes a risk in one click. On its own it prints the question and the answers you can see. Once a project is Done, `harbor voyage` prints its voyage log (planned against actual dates, the biggest slips, the risks that came true, who closed the most, and the crew's lines) and adds yours. `harbor note` leaves a note for later on a project: it stays sealed (the crew sees only that it's there and who left it) until its day, until one of the program's milestones is reached, or until the project turns Off track, and then it opens at the top of the project and in the brief. `harbor sound TASK --ask crew` takes a sounding: it asks you, the task's owner and whoever has open work on its project how many working days the task will take (`--ask "Sam,Priya"` picks who). Each person answers alone with `harbor sound TASK --answer 4 --why "…"`, and nobody sees the others' numbers until everyone has; then `harbor sound TASK` shows the spread, an estimate when the guesses are close, or "talk about this first" when they're far apart, and `--settle DAYS` records what you agreed. `harbor soundings` lists them, the ones waiting on your answer first. `harbor ashore` lists the public holidays and time away in the next eight weeks; `--country US,GB` sets whose holidays the harbor takes and `--person NAME --country DE` one person's own, which the forecast and the weekly load then count as days off.
+`harbor premortem` runs a pre-mortem with your crew: `--start` asks everyone "it's after the end date and this project failed: what happened?", each person adds answers alone for five minutes, and then the answers show together on the project's Risks & issues tab, where each becomes a risk in one click. On its own it prints the question and the answers you can see. Once a project is Done, `harbor voyage` prints its voyage log (planned against actual dates, the biggest slips, the risks that came true, who closed the most, and the crew's lines) and adds yours. `harbor note` leaves a note for later on a project: it stays sealed (the crew sees only that it's there and who left it) until its day, until one of the program's milestones is reached, or until the project turns Off track, and then it opens at the top of the project and in the brief. `harbor sound TASK --ask crew` takes a sounding: it asks you, the task's owner and whoever has open work on its project how many working days the task will take (`--ask "Sam,Priya"` picks who). Each person answers alone with `harbor sound TASK --answer 4 --why "…"`, and nobody sees the others' numbers until everyone has; then `harbor sound TASK` shows the spread, an estimate when the guesses are close, or "talk about this first" when they're far apart, and `--settle DAYS` records what you agreed. `harbor soundings` lists them, the ones waiting on your answer first. `harbor goals` lists each portfolio's goals (set on the portfolio's page on the website), off track first, with each key result's progress. `harbor ashore` lists the public holidays and time away in the next eight weeks; `--country US,GB` sets whose holidays the harbor takes and `--person NAME --country DE` one person's own, which the forecast and the weekly load then count as days off.
 
 `harbor brief --say` turns the brief into the BBC's Shipping Forecast: each program an area, wind for late work, visibility for health, gale warnings for anything off track. It prints the forecast and speaks it with your computer's own voice (`say` on a Mac, Windows' speech, or `espeak-ng` on Linux, which you may need to install). With `--json` it prints the forecast and stays quiet.
 

package/dist/app.mjs

@@ -13219,6 +13219,7 @@ const PAGES = {
 	programs: "/programs",
 	projects: "/projects",
 	risks: "/risks",
+	goals: "/goals",
 	calendar: "/calendar",
 	people: "/people"
 };
@@ -13662,6 +13663,87 @@ function entriesNewestFirst(task) {
 	return [...task.time ?? []].sort((a, b) => (b.on + b.at).localeCompare(a.on + a.at));
 }
 
+// src/lib/goals.ts
+init_indexes();
+const GOAL_STATUS_LABEL = {
+	achieved: "Achieved",
+	"on-track": "On track",
+	"at-risk": "At risk",
+	"off-track": "Off track",
+	"not-started": "Not started"
+};
+const clamp = (n) => Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+/** The projects a work key result counts: those it names, and every project in a program it names. */
+function linkedProjects(kr, projects) {
+	const ids = new Set(kr.linkIds ?? []);
+	if (ids.size === 0) return [];
+	return projects.filter((p) => ids.has(p.id) || ids.has(p.programId));
+}
+/** How far along one key result is, 0 to 1. */
+function keyResultProgress(kr, work) {
+	if (kr.kind === "number") {
+		const start = kr.start ?? 0;
+		const span = (kr.target ?? 0) - start;
+		if (span === 0) return (kr.current ?? start) >= (kr.target ?? 0) ? 1 : 0;
+		return clamp(((kr.current ?? start) - start) / span);
+	}
+	let done = 0;
+	let all = 0;
+	for (const p of linkedProjects(kr, work.projects)) for (const t of tasksOf(work.tasks, p.id)) {
+		all++;
+		if (t.status === "done") done++;
+	}
+	return all === 0 ? 0 : done / all;
+}
+/** How far along a goal is: the average of its key results, 0 to 1. */
+function goalProgress(goal, work) {
+	const krs = goal.keyResults ?? [];
+	if (krs.length === 0) return 0;
+	return krs.reduce((sum, kr) => sum + keyResultProgress(kr, work), 0) / krs.length;
+}
+/** How much of the goal's time has gone by, 0 to 1, from when it was set to its due day. */
+function timeGone(goal, today) {
+	if (!goal.due) return null;
+	const start = Date.parse(`${goal.createdAt.slice(0, 10)}T00:00:00Z`);
+	const end = Date.parse(`${goal.due}T00:00:00Z`);
+	const now = Date.parse(`${today}T00:00:00Z`);
+	if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+	if (end <= start) return now >= end ? 1 : 0;
+	return clamp((now - start) / (end - start));
+}
+/**
+* Where a goal stands. Achieved at 100%. Otherwise, with a due day, progress
+* is held against the share of time gone by: within 10 points is on track,
+* within 25 at risk, further behind (or past due) off track. Without a due
+* day, any progress is on track.
+*/
+function goalStatus(progress, goal, today) {
+	if (progress >= 1) return "achieved";
+	const gone = timeGone(goal, today);
+	if (gone == null) return progress > 0 ? "on-track" : "not-started";
+	if (goal.due && today > goal.due) return "off-track";
+	if (progress === 0 && gone < .1) return "not-started";
+	const behind = gone - progress;
+	if (behind <= .1) return "on-track";
+	if (behind <= .25) return "at-risk";
+	return "off-track";
+}
+/** "12 of 40 stores", "8 of 20 tasks done". */
+function keyResultText(kr, work) {
+	if (kr.kind === "number") {
+		const unit = kr.unit ? ` ${kr.unit}` : "";
+		return `${fmt(kr.current ?? kr.start ?? 0)} of ${fmt(kr.target ?? 0)}${unit}`;
+	}
+	let done = 0;
+	let all = 0;
+	for (const p of linkedProjects(kr, work.projects)) for (const t of tasksOf(work.tasks, p.id)) {
+		all++;
+		if (t.status === "done") done++;
+	}
+	return all === 0 ? "No tasks yet" : `${done} of ${all} tasks done`;
+}
+const fmt = (n) => Number.isInteger(n) ? n.toLocaleString("en-US") : String(Math.round(n * 100) / 100);
+
 // node_modules/zod/v4/core/util.js
 function getEnumValues(entries) {
 	const numericValues = Object.values(entries).filter((v) => typeof v === "number");
@@ -21290,6 +21372,54 @@ const HARBOR_TOOLS = [
 			};
 		}
 	}),
+	tool({
+		name: "list_goals",
+		title: "Goals",
+		description: "Each portfolio's goals: what it should achieve by when, who owns it, and its key results (a number someone updates, or work in Harbor counted by finished tasks), with how far along each is and whether the goal is on track for its due day (progress held against the time gone by)." + DATA_NOTE,
+		input: object({
+			harbor: harborArg,
+			portfolio: string().max(200).optional().describe("Portfolio id or name. Default: all.")
+		}),
+		run: (ctx, input) => {
+			const { data } = ctx;
+			const today = todayISO(ctx.now);
+			const people = byId(data.people);
+			const named = byId([...data.programs, ...data.projects]);
+			return { portfolios: (input.portfolio ? [findOne(data.portfolios, input.portfolio, "portfolio")] : data.portfolios).map((pf) => ({
+				id: pf.id,
+				name: pf.name,
+				goals: (pf.goals ?? []).map((g) => {
+					const progress = goalProgress(g, data);
+					const status = goalStatus(progress, g, today);
+					return {
+						id: g.id,
+						title: g.title,
+						owner: g.ownerId ? people.get(g.ownerId)?.name ?? null : null,
+						due: g.due,
+						...g.why ? { why: g.why } : {},
+						progress: Math.round(progress * 100),
+						status,
+						statusText: GOAL_STATUS_LABEL[status],
+						keyResults: g.keyResults.map((kr) => ({
+							id: kr.id,
+							title: kr.title,
+							kind: kr.kind,
+							text: keyResultText(kr, data),
+							progress: Math.round(keyResultProgress(kr, data) * 100),
+							...kr.kind === "number" ? {
+								start: kr.start ?? 0,
+								target: kr.target,
+								current: kr.current ?? kr.start ?? 0
+							} : {
+								counts: (kr.linkIds ?? []).map((id) => named.get(id)?.name ?? id),
+								projects: linkedProjects(kr, data.projects).length
+							}
+						}))
+					};
+				})
+			})) };
+		}
+	}),
 	tool({
 		name: "long_pole",
 		title: "What's holding this up",

package/lib/cli.mjs

@@ -39,6 +39,7 @@ import {
   lifeboatsText,
   followedText,
   soundingsText,
+  goalsText,
   thanksText,
   ashoreText,
   voyageText,
@@ -260,6 +261,8 @@ export const HELP = `harbor: Harbor from the terminal
                                               your answer, or read the spread
   harbor soundings [PROJECT]                  open tasks with a sounding, and
                                               the ones waiting on your answer
+  harbor goals [PORTFOLIO]                    each portfolio's goals, how far
+                                              along and whether on track
   harbor ashore [--weeks N] [--country CODES|none] [--person NAME]
                                               public holidays and time away
                                               coming up, and whose holidays
@@ -1010,6 +1013,11 @@ const DETAIL = {
     "  these as days nobody works. Countries: AU BR CA DE ES FR GB IE IT MX NL",
     "  NZ US (national holidays only).",
   ],
+  goals: [
+    "  harbor goals [PORTFOLIO]               reads: each portfolio's goals (all when",
+    "                                         left out), off track first, with how far",
+    "                                         along each key result is",
+  ],
   soundings: [
     "  harbor soundings [PROJECT]             reads: open tasks with a sounding",
     "                                         (all projects when left out), and the",
@@ -3167,6 +3175,13 @@ export async function run(argv, io = {}) {
         soundingsText(r),
       );
     }
+    case "goals": {
+      const { positionals, harbor } = parse(spec());
+      const portfolio = positionals.join(" ").trim();
+      return call("list_goals", { harbor, ...(portfolio ? { portfolio } : {}) }, (r) =>
+        goalsText(r),
+      );
+    }
     case "ashore": {
       const { positionals, values, harbor } = parse(spec([], ["weeks", "country", "person"]));
       none(positionals);

package/lib/format.mjs

@@ -1229,3 +1229,29 @@ export function catchupText(r) {
   if (more) out.push("", `${r.handed.length} handed to you in all; harbor catchup --json lists them.`);
   return out.join("\n");
 }
+
+/** list_goals as text: each portfolio's goals, what needs attention first, with their key results. */
+export function goalsText(r) {
+  const order = ["off-track", "at-risk", "not-started", "on-track", "achieved"];
+  const withGoals = (r.portfolios ?? []).filter((p) => p.goals?.length);
+  if (!withGoals.length)
+    return "No goals yet. Set one at the top of a portfolio's page on the website.";
+  const lines = [];
+  for (const p of withGoals) {
+    if (lines.length) lines.push("");
+    lines.push(p.name);
+    const goals = [...p.goals].sort(
+      (a, b) =>
+        order.indexOf(a.status) - order.indexOf(b.status) ||
+        (a.due ?? "9999").localeCompare(b.due ?? "9999"),
+    );
+    for (const g of goals) {
+      const bits = [`${g.progress}%`, g.statusText.toLowerCase()];
+      if (g.owner) bits.push(g.owner);
+      if (g.due && g.status !== "achieved") bits.push(`by ${monthDay(g.due)}`);
+      lines.push(`  ${g.title} · ${bits.join(" · ")}`);
+      for (const k of g.keyResults) lines.push(`    ${k.title} · ${k.text}`);
+    }
+  }
+  return lines.join("\n");
+}

package/package.json

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