@harborppm/cli 0.33.0 → 0.35.0

package/README.md

@@ -128,6 +128,7 @@ harbor brief [--portfolio P] [--say]        the weekly brief, ready to send
 harbor report PROGRAM                       a program's status report
 harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
 harbor voyage PROJECT ["YOUR LINE"]
+harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
 harbor limit PROJECT [COLUMN N|none]
 harbor handover PERSON [--to NAME] [--until DATE] [--note TEXT] [--keep ID,ID] [--confirm]
 harbor handback PERSON
@@ -137,7 +138,7 @@ harbor handback PERSON
 
 `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 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 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).
 

package/dist/app.mjs

@@ -3524,6 +3524,123 @@ function programLateCount(programId, data, now) {
 	return late;
 }
 
+//#endregion
+//#region src/lib/bottle-rules.ts
+/**
+* What a note for later needs before it's sealed (the rest is in bottle.ts).
+* Apart so the store's action carries only this into every page's first load.
+*/
+/** Longest note kept. */
+const BOTTLE_MAX = 1e3;
+/**
+* Why a new note can't be sealed, or null when it can: nothing written, a
+* date that isn't after today (it would open at once), or a milestone that
+* isn't this project's program's or is already reached.
+*/
+function bottleProblem(body, opens, ctx) {
+	if (!body.trim()) return "Write the note first.";
+	if (opens.on === "date") {
+		if (!/^\d{4}-\d{2}-\d{2}$/.test(opens.date)) return "Pick the day it opens.";
+		if (opens.date <= todayISO(ctx.now)) return "Pick a day after today.";
+	}
+	if (opens.on === "milestone") {
+		const m = ctx.milestones.find((x) => x.id === opens.milestoneId);
+		if (!m || m.programId !== ctx.programId) return "Pick one of this program's milestones.";
+		if (m.done) return `${m.name} is already reached.`;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/lib/bottle.ts
+/**
+* Message in a bottle: a note someone leaves on a project now that opens
+* later, on a date, when one of the program's milestones is reached, or if
+* the project turns Off track. Until then the crew sees only that a sealed
+* note is there, who left it and what opens it; the writer can read their
+* own. Once open it sits at the top of the project and in the brief.
+*
+* Notes are `reflections` of kind "bottle". Whether one is open is worked
+* out from the project as it stands (nothing stamps it), so every screen,
+* the CLI and the agents agree. Like the pre-mortem's wait, the seal is a
+* courtesy the screens keep, not a secret from the server.
+*/
+/** An opened note stays at the top of its project this many days, then folds away. */
+const BOTTLE_FRESH_DAYS = 14;
+const isBottle = (r) => r.kind === "bottle";
+/**
+* Whether a note is open, and since when. A date opens it that morning; a
+* milestone when it's marked done (dated by its due date, or today if that's
+* still ahead); Off track the first time the project went Off track after
+* the note was left. A milestone since deleted opens it, so nothing is
+* sealed for good.
+*/
+function bottleState(note, ctx) {
+	const today = todayISO(ctx.now);
+	const opens = note.opens;
+	if (!opens) return {
+		open: true,
+		openedOn: note.createdAt.slice(0, 10)
+	};
+	if (opens.on === "date") return today >= opens.date ? {
+		open: true,
+		openedOn: opens.date
+	} : sealed;
+	if (opens.on === "milestone") {
+		const m = ctx.milestones.find((x) => x.id === opens.milestoneId);
+		if (!m) return {
+			open: true,
+			openedOn: today
+		};
+		if (!m.done) return sealed;
+		return {
+			open: true,
+			openedOn: m.dueDate && m.dueDate < today ? m.dueDate : today
+		};
+	}
+	const flip = (ctx.project.healthHistory ?? []).find((h) => h.health === "off-track" && h.at >= note.createdAt);
+	if (flip) return {
+		open: true,
+		openedOn: flip.at.slice(0, 10)
+	};
+	if (ctx.project.health === "off-track") return {
+		open: true,
+		openedOn: today
+	};
+	return sealed;
+}
+const sealed = {
+	open: false,
+	openedOn: null
+};
+/** Opened in the last `days` days, so it still belongs at the top and in the brief. */
+function isFresh(state, now, days = 14) {
+	if (!state.open || !state.openedOn) return false;
+	return differenceInCalendarDays(now, parseIso(state.openedOn)) < days;
+}
+/** Notes opened in the last fortnight across these projects, newest first: the brief's. */
+function freshlyOpened(data, projects, now) {
+	const notes = (data.reflections ?? []).filter(isBottle);
+	if (notes.length === 0) return [];
+	const byProject = new Map(projects.map((p) => [p.id, p]));
+	const out = [];
+	for (const note of notes) {
+		const project = byProject.get(note.projectId);
+		if (!project) continue;
+		const state = bottleState(note, {
+			project,
+			milestones: data.milestones,
+			now
+		});
+		if (isFresh(state, now)) out.push({
+			note,
+			project,
+			state
+		});
+	}
+	return out.sort((a, b) => (b.state.openedOn ?? "").localeCompare(a.state.openedOn ?? ""));
+}
+
 //#endregion
 //#region src/lib/brief.ts
 const BRIEF_QUIET = "Nothing late or at risk. Say what shipped — or enjoy the quiet week.";
@@ -3618,6 +3735,14 @@ function composeBriefBody(opts) {
 	const lateMilestones = milestones.filter((m) => m.daysLate > 0);
 	const quiet = opts.offTrack.length === 0 && opts.atRisk.length === 0 && opts.late.length === 0 && watch.length === 0 && lateMilestones.length === 0;
 	const lines = [`Harbor brief — ${opts.workspace} — ${date}`, ""];
+	if (opts.opened?.length) {
+		lines.push("Notes that opened");
+		for (const n of opts.opened) {
+			const body = n.body.replace(/\s+/g, " ").trim();
+			lines.push(`• ${n.project}${n.who ? `, from ${n.who}` : ""}: “${body}”`);
+		}
+		lines.push("");
+	}
 	const done = () => {
 		if (!opts.shipped?.length) return;
 		lines.push("Done this week");
@@ -3861,6 +3986,7 @@ function briefOf(data, opts = {}) {
 		finished,
 		said: saidThisWeek(data, now, portfolioId ? new Set(tasks.flatMap((t) => t.assigneeId ? [t.assigneeId] : [])) : null),
 		late: lateLinesOf(data, tasks, now),
+		opened: freshlyOpened(data, projects, now),
 		talk,
 		milestonesSoon,
 		milestonesLate,
@@ -3906,6 +4032,11 @@ function composeBriefBodyFrom(brief, data, workspace) {
 			program: data.programs.find((p) => p.id === m.programId)?.name ?? null,
 			dueDate: m.dueDate,
 			daysLate: -daysUntil(m.dueDate, brief.asOf)
+		})),
+		opened: brief.opened.map((b) => ({
+			project: b.project.name,
+			who: data.people.find((p) => p.id === b.note.authorId)?.name ?? null,
+			body: b.note.body
 		}))
 	});
 }
@@ -7757,6 +7888,8 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 	const projects = useHarbor((s) => s.projects);
 	const people = useHarbor((s) => s.people);
 	const boardConfigs = useHarbor((s) => s.boardConfigs);
+	const reflections = useHarbor((s) => s.reflections);
+	const milestones = useHarbor((s) => s.milestones);
 	const project = projects.find((p) => p.id === projectId);
 	const data = useMemo(() => ({
 		tasks,
@@ -7893,7 +8026,12 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 	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;
+	const opened = freshlyOpened({
+		reflections,
+		milestones
+	}, [project], /* @__PURE__ */ new Date(`${day}T12:00:00`))[0];
+	const openedBy = opened ? people.find((p) => p.id === opened.note.authorId)?.name : null;
+	const body = height - 3 - (opened ? 1 : 0);
 	const fit = Math.max(1, Math.floor((width - 2) / 14));
 	const firstColumn = Math.min(Math.max(0, col - Math.floor(fit / 2)), Math.max(0, columns.length - fit));
 	const shownColumns = columns.slice(firstColumn, firstColumn + fit);
@@ -7968,6 +8106,21 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 					]
 				})]
 			}),
+			opened && /* @__PURE__ */ jsxs(Text, {
+				wrap: "truncate-end",
+				color: theme.warn,
+				children: [
+					"A note opened",
+					openedBy ? `, from ${openedBy}` : "",
+					":",
+					" ",
+					/* @__PURE__ */ jsxs(Text, { children: [
+						"“",
+						opened.note.body.replace(/\s+/g, " "),
+						"”"
+					] })
+				]
+			}),
 			mode === "budget" ? /* @__PURE__ */ jsx(BudgetPane, {
 				project,
 				spendEntries,
@@ -11322,13 +11475,36 @@ function milestonesRaidSlice({ set, get, write }) {
 			return row.id;
 		},
 		editReflection: (id, body) => {
-			const text = body.trim().slice(0, 600);
-			if (!text) return;
 			const me = get().currentUserId;
-			write({ reflections: (get().reflections ?? []).map((r) => r.id === id && r.authorId === me ? {
-				...r,
-				body: text
-			} : r) });
+			write({ reflections: (get().reflections ?? []).map((r) => {
+				if (r.id !== id || r.authorId !== me) return r;
+				const text = body.trim().slice(0, r.kind === "bottle" ? BOTTLE_MAX : 600);
+				return text ? {
+					...r,
+					body: text
+				} : r;
+			}) });
+		},
+		leaveBottle: (projectId, body, opens) => {
+			const s = get();
+			const project = s.projects.find((p) => p.id === projectId);
+			if (!project) return null;
+			if (bottleProblem(body, opens, {
+				programId: project.programId,
+				milestones: s.milestones,
+				now: clockNow()
+			})) return null;
+			const row = {
+				id: uid("rf"),
+				projectId,
+				kind: "bottle",
+				authorId: s.currentUserId,
+				body: body.trim().slice(0, BOTTLE_MAX),
+				createdAt: stamp(),
+				opens
+			};
+			write({ reflections: [...s.reflections ?? [], row] });
+			return row.id;
 		},
 		deleteReflection: (id) => {
 			const me = get().currentUserId;

package/lib/cli.mjs

@@ -26,6 +26,7 @@ import {
   hillList,
   myWork,
   premortemText,
+  notesText,
   voyageText,
   handoverText,
   raidList,
@@ -117,6 +118,9 @@ export const HELP = `harbor: Harbor from the terminal
                                               answer or read it
   harbor voyage PROJECT ["YOUR LINE"]         a Done project's voyage log, and
                                               your line in it
+  harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
+                                              a note for later: sealed until
+                                              its day, milestone, or Off track
   harbor handover PERSON [--to NAME] [--until DATE] [--note TEXT]
                          [--keep ID,ID] [--confirm]
                                               hand someone's work to the crew
@@ -289,6 +293,8 @@ const FLAG = {
   column: "the column",
   limit: "the limit",
   at: "--at",
+  opensOn: "--opens",
+  milestone: "--milestone",
   until: "--until",
   to: "--to",
   keep: "--keep",
@@ -296,7 +302,7 @@ const FLAG = {
 };
 
 /** Harbor's refusals are worded for agents; say them as the commands and flags that answer them. */
-export function hint(message) {
+export function hint(message, project) {
   const said = message.replace(/\s*Ask the person;.*$/s, "");
   if (/confirmed: true/.test(message))
     return `${said}\nTo finish it anyway, run it again with --confirm.`;
@@ -331,8 +337,13 @@ export function hint(message) {
     .replace(/Find it with search_tasks\.$/, "Find it with harbor tasks.")
     .replace(
       /^(.+) has no pre-mortem running\. Start one with start_premortem first\.$/s,
+      // What the person typed found it, so the command they're told to run uses that (the name may be shared).
       (_, name) =>
-        `${name} has no pre-mortem running. Start one with harbor premortem "${name}" --start.`,
+        `${name} has no pre-mortem running. Start one with harbor premortem "${project ?? name}" --start.`,
+    )
+    .replace(
+      /^Say what opens the note: exactly one of opensOn, milestone or ifOffTrack\.$/,
+      "Say what opens it: --opens DATE, --milestone NAME or --off-track (one of them).",
     )
     .replace(
       /^Nothing to change: pass a field to update\.$/,
@@ -353,11 +364,20 @@ export function hint(message) {
 }
 
 /** get_premortem's answer with its note naming the command, not the agent tool, since --json shows it. */
-export function premortemForTerminal(r) {
+export function premortemForTerminal(r, project = r.project) {
   if (r.running || !r.note) return r;
   return {
     ...r,
-    note: `No pre-mortem on ${r.project} yet. Start one with harbor premortem "${r.project}" --start.`,
+    note: `No pre-mortem on ${r.project} yet. Start one with harbor premortem "${project}" --start.`,
+  };
+}
+
+/** get_voyage_log's answer with its note on an empty crew naming the command, not the agent tool. */
+export function voyageForTerminal(r, project = r.project) {
+  if (!r.crewNote) return r;
+  return {
+    ...r,
+    crewNote: `crew is the lines people add to the log; nobody has yet. Add yours with harbor voyage "${project}" "YOUR LINE".`,
   };
 }
 
@@ -386,6 +406,19 @@ const DETAIL = {
     "  PROJECT is a name, a key like RR, or an id. When two projects share a",
     "  name, give the key.",
   ],
+  note: [
+    "  harbor note PROJECT                    reads its notes for later: who left",
+    "                                         each, what opens it, and the opened ones",
+    '  harbor note PROJECT "NOTE" --opens DATE',
+    "                                         writes: seals a note that opens that day",
+    '  harbor note PROJECT "NOTE" --milestone NAME',
+    "                                         writes: opens when that milestone is reached",
+    '  harbor note PROJECT "NOTE" --off-track',
+    "                                         writes: opens if the project turns Off track",
+    "",
+    "  Until it opens, the crew sees only that a note is there and who left it.",
+    "  DATE: YYYY-MM-DD, tomorrow, or +N for N days from today.",
+  ],
   handover: [
     "  harbor handover PERSON                 reads what would move, and to whom:",
     "                                         their open tasks, sign-offs, risks",
@@ -405,6 +438,7 @@ const DETAIL = {
     "  harbor voyage PROJECT                  reads a Done project's voyage log",
     '  harbor voyage PROJECT "YOUR LINE"      writes: adds or changes your line in it',
     "",
+    "  In --json, crew is the lines people added; closedBy is who closed tasks.",
     "  PROJECT is a name, a key like RR, or an id. When two projects share a",
     "  name, give the key.",
   ],
@@ -790,9 +824,10 @@ export async function run(argv, io = {}) {
   const call = async (name, args, show, forTerminal = (r) => r) => {
     const result = forTerminal(
       await client.call(name, args).catch((err) => {
-        if (err instanceof HarborError) throw new HarborError(hint(err.message));
+        if (err instanceof HarborError) throw new HarborError(hint(err.message, args.project));
         throw err;
       }),
+      args.project,
     );
     // The prompt's counts are behind now; its next draw fetches new ones.
     if (name === "create_task" || name === "update_task") await stalePromptCache(env);
@@ -1307,7 +1342,7 @@ export async function run(argv, io = {}) {
       const answer = words.join(" ").trim();
       if (values.start) {
         const started = await client.call("start_premortem", { harbor, project }).catch((err) => {
-          if (err instanceof HarborError) throw new HarborError(hint(err.message));
+          if (err instanceof HarborError) throw new HarborError(hint(err.message, project));
           throw err;
         });
         if (!answer) {
@@ -1350,6 +1385,32 @@ export async function run(argv, io = {}) {
         limitsText(r.set.project, r.limits, r.tasks, r.hiddenColumns),
       );
     }
+    case "note": {
+      const { positionals, values, harbor } = parse(spec(["off-track"], ["opens", "milestone"]));
+      const [project, ...words] = positionals;
+      if (!project)
+        throw new HarborError(
+          'Give a project, then the note: harbor note "NAME" "NOTE" --opens +30.',
+        );
+      const note = words.join(" ").trim();
+      if (!note) {
+        if (values.opens || values.milestone || values["off-track"])
+          throw new HarborError("Write the note too, in quotes after the project.");
+        return call("get_project", { harbor, project }, (r) => notesText(r.name, r.notesForLater));
+      }
+      return call(
+        "leave_note",
+        {
+          harbor,
+          project,
+          note,
+          ...(values.opens ? { opensOn: dueDate(values.opens) } : {}),
+          ...(values.milestone ? { milestone: values.milestone } : {}),
+          ...(values["off-track"] ? { ifOffTrack: true } : {}),
+        },
+        (r) => `Sealed your note on ${r.sealed.project}. It ${r.sealed.opens}.`,
+      );
+    }
     case "voyage": {
       const { positionals, harbor } = parse(spec());
       const [project, ...words] = positionals;
@@ -1362,7 +1423,7 @@ export async function run(argv, io = {}) {
           (r) => `Your line is in ${r.added.project}'s voyage log.`,
         );
       }
-      return call("get_voyage_log", { harbor, project }, voyageText);
+      return call("get_voyage_log", { harbor, project }, voyageText, voyageForTerminal);
     }
     case "handover": {
       const { positionals, values, harbor } = parse(

package/lib/format.mjs

@@ -370,6 +370,35 @@ export function hillList(r) {
   return blocks.join("\n\n");
 }
 
+/** A project's notes for later, as get_project lists them. */
+export function notesText(project, notes) {
+  if (!notes?.length)
+    return `No notes for later on ${project}. Leave one: harbor note "${project}" "NOTE" --opens +30`;
+  const open = notes.filter((n) => n.open);
+  const sealed = notes.filter((n) => !n.open);
+  const lines = [`Notes for later · ${project}`];
+  for (const n of open) {
+    const when = n.openedOn ? `Opened ${n.openedOn}` : "Opened";
+    lines.push("", `  ${when} · left by ${n.yours ? "you" : (n.from ?? "someone")} on ${n.left}`);
+    lines.push(
+      ...String(n.note ?? "")
+        .split("\n")
+        .map((l) => `  ${l}`),
+    );
+  }
+  if (sealed.length) lines.push("");
+  for (const n of sealed) {
+    lines.push(`  Sealed · ${n.yours ? "yours" : `from ${n.from ?? "someone"}`} · ${n.opens}`);
+    if (n.yours && n.note)
+      lines.push(
+        ...String(n.note)
+          .split("\n")
+          .map((l) => `    ${l}`),
+      );
+  }
+  return lines.join("\n");
+}
+
 /** handover_plan as a list grouped like the website's dialog, each line with who takes it. */
 export function handoverText(r, { confirmHint = true } = {}) {
   const items = r.items ?? [];

package/package.json

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