@harborppm/cli 0.15.0 → 0.18.0

package/README.md

@@ -116,8 +116,12 @@ harbor issue "TITLE" --project P|--program P [--impact 1-5] [--owner NAME]
                     [--due DATE]
 harbor decision "TITLE" --project P|--program P [--owner NAME] [--due DATE]
 harbor risks [words] [--kind risk,issue,decision] [--project P] [--closed]
+harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
+harbor voyage PROJECT ["YOUR LINE"]
 ```
 
+`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.
+
 Every command takes `--json` for the raw result (a refusal then comes out as `{"error": "…"}` on standard output, still with exit code 1), and `harbor COMMAND --help` shows just that command. Statuses are backlog, todo, doing, review and done. A `DATE` is YYYY-MM-DD, `today`, `tomorrow`, or `+N` for N days from today.
 
 When you belong to more than one harbor, say which: `--harbor NAME` on the command, or `harbor use NAME` once (it's saved with your sign-in; `harbor use none` forgets it). With neither, the commands ask rather than guess, so nothing lands in the wrong harbor. The full-screen app shares the same choice: it opens the harbor `harbor use` set, asks which one the first time if none is set, and a harbor you switch to in the app becomes the one the commands use.

package/dist/app.mjs

@@ -855,7 +855,8 @@ function normalizeRaidItem(r) {
 		createdAt: r.createdAt ?? now,
 		updatedAt: r.updatedAt ?? r.createdAt ?? now,
 		updates: Array.isArray(r.updates) ? r.updates : [],
-		scoreHistory: Array.isArray(r.scoreHistory) && r.scoreHistory.length ? r.scoreHistory : void 0
+		scoreHistory: Array.isArray(r.scoreHistory) && r.scoreHistory.length ? r.scoreHistory : void 0,
+		...kind === "risk" && typeof r.happened === "boolean" ? { happened: r.happened } : {}
 	};
 }
 /** Active first, then by score, then most recently touched. */
@@ -1434,7 +1435,8 @@ function cascadeDelete(data, kind, id) {
 				...r,
 				taskIds: r.taskIds.filter((t) => !taskIds.has(t))
 			})),
-			spendEntries: (data.spendEntries ?? []).filter((e) => !projectIds.has(e.projectId))
+			spendEntries: (data.spendEntries ?? []).filter((e) => !projectIds.has(e.projectId)),
+			reflections: (data.reflections ?? []).filter((r) => !projectIds.has(r.projectId))
 		},
 		counts: {
 			programs: programIds.size,
@@ -7668,6 +7670,7 @@ function pickData(s) {
 		ropes: s.ropes ?? NONE,
 		checkIns: s.checkIns ?? NONE,
 		spendEntries: s.spendEntries ?? NONE,
+		reflections: s.reflections ?? NONE,
 		priorityRules: s.priorityRules ?? null
 	};
 }
@@ -7878,7 +7881,8 @@ const UNDO_KEYS = [
 	"comments",
 	"attachments",
 	"checkIns",
-	"spendEntries"
+	"spendEntries",
+	"reflections"
 ];
 /** Edits to the same fields of the same things this close together are one change. */
 const FOLD_MS = 5e3;
@@ -7893,7 +7897,7 @@ function reversalOf(before, after) {
 	const forward = [];
 	for (const key of UNDO_KEYS) {
 		if (before[key] === after[key]) continue;
-		const back = rowChanges(after[key], before[key]);
+		const back = rowChanges(after[key] ?? [], before[key] ?? []);
 		if (back.length === 0) continue;
 		reversal[key] = back;
 		for (const change of back) {
@@ -7926,7 +7930,7 @@ function labelOf(before, after, forward) {
 	const lead = LEAD.map((key) => forward.filter((f) => f.key === key)).find((l) => l.length > 0);
 	if (!lead || lead.length !== 1) return "your last change";
 	const { key, change } = lead[0];
-	const find = (doc, id) => doc[key].find((r) => r.id === id);
+	const find = (doc, id) => (doc[key] ?? []).find((r) => r.id === id);
 	if (change.kind === "add") {
 		const name = nameOf(change.row);
 		return name ? `deleting ${name}` : "your last change";
@@ -7964,7 +7968,7 @@ function undoStep(doc, step) {
 	for (const reversal of [...step.reversals].reverse()) for (const key of UNDO_KEYS) {
 		const changes = reversal[key];
 		if (!changes?.length) continue;
-		const rows = next[key] ?? doc[key];
+		const rows = next[key] ?? doc[key] ?? [];
 		const result = applyRowChanges(rows, changes, { keepTheirs: true });
 		next[key] = result.rows;
 		for (const clash of result.clashes) kept.add(`${key}:${clash.id}:${clash.field}`);
@@ -8596,6 +8600,7 @@ function hierarchySlice({ get, write }) {
 				comments: back(state.comments, rows.comments),
 				attachments: back(state.attachments, rows.attachments),
 				spendEntries: back(state.spendEntries, rows.spendEntries),
+				reflections: back(state.reflections, rows.reflections),
 				boardConfigs: {
 					...rows.boardConfigs ?? {},
 					...state.boardConfigs ?? {}
@@ -9062,6 +9067,50 @@ function tasksSlice({ set, get, write }) {
 	};
 }
 
+//#endregion
+//#region src/lib/premortem.ts
+/** How long everyone answers alone before the answers show together. */
+const PREMORTEM_MINUTES = 5;
+/** A new pre-mortem started now: answers show together five minutes on. */
+function newPremortem(startedById, now) {
+	return {
+		startedAt: now.toISOString(),
+		startedById,
+		revealAt: new Date(now.getTime() + 5 * 6e4).toISOString()
+	};
+}
+/**
+* A risk's title from an answer: its first sentence, kept under 120
+* characters at a word boundary, without a closing full stop.
+*/
+function riskTitle(answer) {
+	const flat = answer.replace(/\s+/g, " ").trim();
+	const first = /^(.+?[.!?])(\s|$)/.exec(flat)?.[1] ?? flat;
+	let title = first.length <= 120 ? first : `${first.slice(0, 117).replace(/\s+\S*$/, "")}…`;
+	title = title.replace(/\.$/, "");
+	return title;
+}
+/** The risk an answer becomes: on its project, open, unrated, with the whole answer as what could happen. */
+function riskFromAnswer(answer, project, portfolioId) {
+	return {
+		kind: "risk",
+		title: riskTitle(answer.body),
+		description: `${answer.body.trim()}\n\nRaised in the pre-mortem.`,
+		projectId: project.id,
+		programId: project.programId,
+		portfolioId,
+		status: "open",
+		ownerId: null,
+		dueDate: null
+	};
+}
+/** The risk's description with another answer folded in as the same worry. */
+function withFoldedAnswer(description, answer) {
+	const base = description.trim();
+	return `${base}${base ? "\n\n" : ""}Also raised: ${answer.trim()}`;
+}
+const STOP = new Set("the a an and or but of to in on for with at by from into onto was were be been being is are it its this that these those we our us they them their he she his her i my me you your had has have did do does not no so too very just than then there here what which who because about after before over under again more most some any all each other only own same can could would should will got get project failed happened went".split(" "));
+
 //#endregion
 //#region src/lib/raid-history.ts
 /**
@@ -9201,6 +9250,120 @@ function milestonesRaidSlice({ set, get, write }) {
 				updates: [...r.updates, update],
 				updatedAt: stamp()
 			} : r) });
+		},
+		startPremortem: (projectId) => {
+			const project = get().projects.find((p) => p.id === projectId);
+			if (!project || project.premortem) return;
+			const premortem = newPremortem(get().currentUserId, clockNow());
+			write({ projects: get().projects.map((p) => p.id === projectId ? {
+				...p,
+				premortem
+			} : p) });
+			get().log(`started a pre-mortem on ${project.name}`, `/projects/${projectId}?view=risks`);
+		},
+		showPremortemAnswers: (projectId) => {
+			const now = clockNow().toISOString();
+			write({ projects: get().projects.map((p) => p.id === projectId && p.premortem && p.premortem.revealAt > now ? {
+				...p,
+				premortem: {
+					...p.premortem,
+					revealAt: now
+				}
+			} : p) });
+		},
+		answerPremortem: (projectId, body) => {
+			const text = body.trim().slice(0, 600);
+			const project = get().projects.find((p) => p.id === projectId);
+			if (!text || !project?.premortem) return null;
+			const row = {
+				id: uid("rf"),
+				projectId,
+				kind: "premortem",
+				authorId: get().currentUserId,
+				body: text,
+				createdAt: stamp()
+			};
+			write({ reflections: [...get().reflections ?? [], row] });
+			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) });
+		},
+		deleteReflection: (id) => {
+			const me = get().currentUserId;
+			write({ reflections: (get().reflections ?? []).filter((r) => !(r.id === id && r.authorId === me)) });
+		},
+		raisePremortemAnswer: (id) => {
+			const answer = (get().reflections ?? []).find((r) => r.id === id);
+			if (!answer || answer.raidId) return answer?.raidId ?? null;
+			const project = get().projects.find((p) => p.id === answer.projectId);
+			if (!project) return null;
+			const program = get().programs.find((p) => p.id === project.programId);
+			const raidId = get().addRaidItem(riskFromAnswer(answer, project, program?.portfolioId ?? null));
+			write({ reflections: (get().reflections ?? []).map((r) => r.id === id ? {
+				...r,
+				raidId,
+				merged: false,
+				skipped: false
+			} : r) });
+			return raidId;
+		},
+		foldPremortemAnswer: (id, raidId) => {
+			const answer = (get().reflections ?? []).find((r) => r.id === id);
+			const risk = get().raidItems.find((r) => r.id === raidId);
+			if (!answer || answer.raidId || !risk) return;
+			write({
+				raidItems: get().raidItems.map((r) => r.id === raidId ? {
+					...r,
+					description: withFoldedAnswer(r.description, answer.body),
+					updatedAt: stamp()
+				} : r),
+				reflections: (get().reflections ?? []).map((r) => r.id === id ? {
+					...r,
+					raidId,
+					merged: true,
+					skipped: false
+				} : r)
+			});
+		},
+		skipPremortemAnswer: (id, skipped) => {
+			write({ reflections: (get().reflections ?? []).map((r) => r.id === id && !r.raidId ? {
+				...r,
+				skipped
+			} : r) });
+		},
+		writeVoyageLine: (projectId, body) => {
+			const text = body.trim().slice(0, 600);
+			const me = get().currentUserId;
+			const all = get().reflections ?? [];
+			const mine = all.find((r) => r.projectId === projectId && r.kind === "voyage" && r.authorId === me);
+			if (!text) {
+				if (mine) write({ reflections: all.filter((r) => r.id !== mine.id) });
+				return;
+			}
+			if (mine) {
+				if (mine.body !== text) write({ reflections: all.map((r) => r.id === mine.id ? {
+					...r,
+					body: text
+				} : r) });
+				return;
+			}
+			if (!get().projects.some((p) => p.id === projectId)) return;
+			const row = {
+				id: uid("rf"),
+				projectId,
+				kind: "voyage",
+				authorId: me,
+				body: text,
+				createdAt: stamp()
+			};
+			write({ reflections: [...all, row] });
 		}
 	};
 }
@@ -9443,6 +9606,7 @@ const COLLECTIONS = [
 	"ropes",
 	"checkIns",
 	"spendEntries",
+	"reflections",
 	"priorityRules"
 ];
 /** Keys whose value differs between the last saved document and the current one. */
@@ -9475,6 +9639,7 @@ const ROW_COLLECTIONS = [
 	"activity",
 	"checkIns",
 	"spendEntries",
+	"reflections",
 	"boardConfigs",
 	"ropes",
 	"readPingIds",
@@ -9517,7 +9682,7 @@ const KEYED = {
 	}
 };
 const isKeyed = (key) => key in KEYED;
-/** A collection as rows; `spendEntries` and `priorityRules` may be missing from older documents. */
+/** A collection as rows; `spendEntries`, `reflections` and `priorityRules` may be missing from older documents. */
 function rowsOf(doc, key) {
 	if (isKeyed(key)) return KEYED[key].rows(doc[key]);
 	return doc[key] ?? [];

package/lib/cli.mjs

@@ -19,6 +19,8 @@ import {
 import {
   harbors,
   myWork,
+  premortemText,
+  voyageText,
   raidList,
   programTree,
   projectList,
@@ -89,6 +91,11 @@ export const HELP = `harbor: Harbor from the terminal
   harbor decision "TITLE" --project P|--program P [--owner NAME] [--due DATE]
   harbor risks [words] [--kind risk,issue,decision] [--project P] [--closed]
                                               the register, worst first
+  harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
+                                              a project's pre-mortem: start,
+                                              answer or read it
+  harbor voyage PROJECT ["YOUR LINE"]           a Done project's voyage log, and
+                                              your line in it
 
   Every command takes --json, and --harbor NAME when you're in more than one
   harbor (or set one with harbor use). harbor help COMMAND shows just that one.
@@ -978,6 +985,53 @@ export async function run(argv, io = {}) {
         (r) => raidList(r, positionals.join(" ")),
       );
     }
+    case "premortem": {
+      const { positionals, values, harbor } = parse(spec(["start"]));
+      const [project, ...words] = positionals;
+      if (!project)
+        throw new HarborError(
+          'Give a project, then your answer: harbor premortem "NAME" "WHAT WENT WRONG".',
+        );
+      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));
+          throw err;
+        });
+        if (!answer) {
+          out(
+            asJson
+              ? jsonText(started)
+              : plain(
+                  `Started the pre-mortem on ${started.started.project}.\n${started.started.question}\nEveryone answers alone for five minutes; then the answers show together on the project's Risks & issues tab.`,
+                ),
+          );
+          return 0;
+        }
+      }
+      if (answer) {
+        return call("answer_premortem", { harbor, project, answer }, (r) =>
+          r.answersPrivate
+            ? `Added your answer (${r.answered.yourAnswers} so far). Nobody sees it until the answers show.`
+            : `Added your answer (${r.answered.yourAnswers} so far).`,
+        );
+      }
+      return call("get_premortem", { harbor, project }, premortemText);
+    }
+    case "voyage": {
+      const { positionals, harbor } = parse(spec());
+      const [project, ...words] = positionals;
+      if (!project) throw new HarborError("Give a project, and your line if you're adding one.");
+      const line = words.join(" ").trim();
+      if (line) {
+        return call(
+          "add_voyage_line",
+          { harbor, project, line },
+          (r) => `Your line is in ${r.added.project}'s voyage log.`,
+        );
+      }
+      return call("get_voyage_log", { harbor, project }, voyageText);
+    }
     case "risk":
     case "issue":
     case "decision": {

package/lib/format.mjs

@@ -183,3 +183,43 @@ export function raidList(r, words = "") {
       : "";
   return lines.join("\n") + more;
 }
+
+/** A project's pre-mortem, as get_premortem answers it. */
+export function premortemText(r) {
+  if (!r.running) {
+    return `No pre-mortem on ${r.project} yet. Start one with harbor premortem "${r.project}" --start.`;
+  }
+  const count = `${r.answerCount} answer${r.answerCount === 1 ? "" : "s"}`;
+  const head = [`Pre-mortem · ${r.project} · ${count}`, r.question];
+  if (r.answersPrivate) {
+    const s = r.secondsUntilShown ?? 0;
+    head.push(
+      `Answers show together in ${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}. Until then you see only yours.`,
+    );
+  }
+  const lines = (r.answers ?? []).map((a) => {
+    const after = a.risk
+      ? a.merged
+        ? `  (merged into the risk “${a.risk}”)`
+        : `  (risk: ${a.risk})`
+      : a.leftOut
+        ? "  (left out)"
+        : "";
+    return `  ${a.yours ? "*" : "-"} ${a.answer}${after}`;
+  });
+  if (!lines.length)
+    lines.push(`  Nothing yet. Add one: harbor premortem "${r.project}" "WHAT WENT WRONG"`);
+  return [...head, "", ...lines].join("\n");
+}
+
+/** A project's voyage log, as get_voyage_log answers it. */
+export function voyageText(r) {
+  const head = [`Voyage log · ${r.project}${r.done ? ` · Done ${r.finished}` : ""}`];
+  if (r.note) head.push(r.note);
+  head.push((r.stats ?? []).join(" · "));
+  const story = (r.story ?? []).map((s) => `  - ${s}`);
+  const crew = (r.crew ?? []).map((c) => `  - ${c.who ?? "Someone"}: ${c.line}`);
+  return [...head, "", ...story, ...(crew.length ? ["", "From the crew:", ...crew] : [])].join(
+    "\n",
+  );
+}

package/package.json

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