@harborppm/cli 0.14.1 → 0.16.0

package/README.md

@@ -55,7 +55,7 @@ Your harbor is the same one at [harborppm.com](https://harborppm.com/today?utm_s
 - **GitHub**: a pull request that names a task's key (RR-42) shows on the task and moves it along.
 - **Claude and other AI apps**, connected over MCP from [harborppm.com/ai](https://harborppm.com/ai?utm_source=npm&utm_medium=readme&utm_campaign=cli).
 
-`harbor open RR-42` opens a task on the website (in the right harbor, even when the browser had another one open), `harbor open Ridge` a project, and `harbor open` on its own opens Today. `harbor invite sam@example.com` sends Sam the same invite letter the People page does (`--viewer` to let them look but not change anything); only a harbor's owner can invite.
+`harbor open RR-42` opens a task on the website (in the right harbor, even when the browser had another one open), `harbor open Ridge` a project, and `harbor open` on its own opens Today. `harbor invite sam@example.com` sends Sam the same invite letter the People page does (`--viewer` to let them look but not change anything); only a harbor's owner can invite. `harbor calendar` prints your private calendar link, to add to Google, Apple or Outlook calendar: your due dates, milestones and sign-offs beside your meetings, kept up to date (`--program NAME` for everything dated in one program, `--new` to swap the link for a fresh one, `--off` to turn it off).
 
 The website has the commands too: turn on **Command line at the bottom** in your menu, press `/`, and type `mine`, `add "Call the mill" #ridge @sam --due fri` or `done RR-12`.
 
@@ -95,6 +95,7 @@ harbor tasks [words] [--project P] [--assignee me|none|NAME] [--late] [--status
 harbor show TASK                            one task in full, with its web link
 harbor open [TASK|PROJECT]                  open it on the website (or Today)
 harbor invite EMAIL [--viewer]              invite someone to your harbor by email
+harbor calendar [--program P] [--new|--off] your private calendar link (.ics)
 
 harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                      [--ends DATE]
@@ -115,8 +116,11 @@ 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 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.
+
 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

@@ -1434,7 +1434,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 +7669,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 +7880,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 +7896,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 +7929,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 +7967,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 +8599,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 +9066,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 +9249,93 @@ 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) });
 		}
 	};
 }
@@ -9443,6 +9578,7 @@ const COLLECTIONS = [
 	"ropes",
 	"checkIns",
 	"spendEntries",
+	"reflections",
 	"priorityRules"
 ];
 /** Keys whose value differs between the last saved document and the current one. */
@@ -9475,6 +9611,7 @@ const ROW_COLLECTIONS = [
 	"activity",
 	"checkIns",
 	"spendEntries",
+	"reflections",
 	"boardConfigs",
 	"ropes",
 	"readPingIds",
@@ -9517,7 +9654,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,7 @@ import {
 import {
   harbors,
   myWork,
+  premortemText,
   raidList,
   programTree,
   projectList,
@@ -66,6 +67,7 @@ export const HELP = `harbor: Harbor from the terminal
                                               shell prompt (never waits)
   harbor prompt --init SHELL                  how to add it: zsh, bash, fish
                                               or starship
+  harbor calendar [--program P] [--new|--off] your private calendar link (.ics)
 
   harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                        [--ends DATE]
@@ -88,6 +90,9 @@ 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
 
   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.
@@ -821,6 +826,34 @@ export async function run(argv, io = {}) {
       );
       return 0;
     }
+    case "calendar": {
+      const { values, harbor } = parse(spec(["new", "off"], ["program"]));
+      if (values.new && values.off) throw new HarborError("Say --new or --off, not both.");
+      if (!hasFullAccess(creds)) {
+        throw new HarborError("Calendar links need full access. Run harbor login, then try again.");
+      }
+      const r = await client.app({
+        op: "calendar",
+        ...(harbor ? { harbor } : {}),
+        ...(values.program ? { program: values.program } : {}),
+        action: values.off ? "off" : values.new ? "fresh" : "show",
+      });
+      if (asJson) {
+        out(jsonText(r));
+        return 0;
+      }
+      const what = r.program ? `everything dated in ${r.program}` : `your work in ${r.harbor}`;
+      if (!r.url) {
+        out(plain(`Turned off the calendar link for ${what}. Calendars using it stop updating.`));
+        return 0;
+      }
+      out(
+        plain(
+          `${values.new ? "A new calendar link" : "Your calendar link"} for ${what}${values.new ? " (the old one has stopped working)" : ""}:\n\n  ${r.url}\n\nAdd it to Google, Apple or Outlook calendar as a calendar from a URL. Anyone with the link can see these dates; harbor calendar --new swaps it for a fresh one.`,
+        ),
+      );
+      return 0;
+    }
     case "add": {
       const { positionals, values, harbor } = parse(
         spec(["over-limit"], ["project", "assignee", "due", "priority", "status"]),
@@ -949,6 +982,39 @@ 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 "risk":
     case "issue":
     case "decision": {

package/lib/format.mjs

@@ -183,3 +183,31 @@ 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");
+}

package/package.json

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