@harborppm/cli 0.32.0 → 0.34.0

package/README.md

@@ -129,8 +129,12 @@ harbor report PROGRAM                       a program's status report
 harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
 harbor voyage PROJECT ["YOUR LINE"]
 harbor limit PROJECT [COLUMN N|none]
+harbor handover PERSON [--to NAME] [--until DATE] [--note TEXT] [--keep ID,ID] [--confirm]
+harbor handback PERSON
 ```
 
+`harbor handover Priya` lists everything Priya carries (open tasks, sign-offs waiting on her, risks and issues she owns, projects and programs she leads) and who should take each, from who has room this week. Nothing moves until you add `--confirm`. `--until DATE` is for time away: Priya shows as away on People, and `harbor handback Priya` gives back whatever is still with whoever took it. `--note` goes with each task and risk as a comment.
+
 `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.

package/dist/app.mjs

@@ -795,6 +795,9 @@ function money(n) {
 function shortDate(value) {
 	return format(parseDate$1(value), "MMM d");
 }
+function longDate(value) {
+	return format(parseDate$1(value), "EEE, MMM d");
+}
 function isOverdue(value, done = false) {
 	if (!value || done) return false;
 	try {
@@ -10408,6 +10411,38 @@ function hierarchySlice({ get, write }) {
 			get().log(`added the sample project`, `/projects/${id}`);
 			return id;
 		},
+		addShelfPlan: (rows) => {
+			const state = get();
+			const starter = starterProgram(state);
+			const program = starter ? {
+				...starter,
+				...rows.program,
+				id: starter.id,
+				portfolioId: starter.portfolioId,
+				health: starter.health
+			} : rows.program;
+			const milestones = rows.milestones.map((m) => ({
+				...m,
+				programId: program.id
+			}));
+			const project = {
+				...rows.project,
+				programId: program.id
+			};
+			write({
+				programs: starter ? state.programs.map((g) => g.id === starter.id ? program : g) : [...state.programs, program],
+				milestones: [...state.milestones, ...milestones],
+				projects: [...state.projects, project],
+				tasks: [...state.tasks, ...rows.tasks],
+				raidItems: [...state.raidItems, ...rows.raidItems],
+				boardConfigs: {
+					...state.boardConfigs ?? {},
+					[project.id]: defaultBoardConfig()
+				}
+			});
+			get().log(`opened the ${rows.program.name} plan`, `/programs/${program.id}`);
+			return program.id;
+		},
 		updatePortfolio: (id, patch) => {
 			write({ portfolios: get().portfolios.map((p) => p.id === id ? {
 				...p,
@@ -11367,6 +11402,42 @@ function milestonesRaidSlice({ set, get, write }) {
 	};
 }
 
+//#endregion
+//#region src/lib/handover.ts
+/** The line that travels with each handed item: who it came from, to whom, until when, and the note. */
+function handoverLine(opts) {
+	const until = opts.until && opts.untilText ? `, until ${opts.untilText}` : "";
+	const note = opts.note.trim();
+	return `Handed over from ${opts.fromName} to ${opts.toName}${until}.${note ? ` ${note}` : ""}`;
+}
+/** What can go back after time away: moves whose item is still with the person who took it. */
+function returnable(data, person) {
+	const moves = person.away?.moves ?? [];
+	const tasks = byId(data.tasks);
+	const milestones = byId(data.milestones);
+	const raid = byId(data.raidItems);
+	const projects = byId(data.projects);
+	const programs = byId(data.programs);
+	return moves.filter((m) => {
+		switch (m.kind) {
+			case "task": {
+				const t = tasks.get(m.id);
+				return Boolean(t && t.assigneeId === m.toId && t.status !== "done");
+			}
+			case "signoff": {
+				const ms = milestones.get(m.id);
+				return Boolean(ms && ms.approverId === m.toId && !ms.done);
+			}
+			case "raid": {
+				const r = raid.get(m.id);
+				return Boolean(r && r.ownerId === m.toId && isActive(r));
+			}
+			case "project": return projects.get(m.id)?.ownerId === m.toId;
+			case "program": return programs.get(m.id)?.ownerId === m.toId;
+		}
+	});
+}
+
 //#endregion
 //#region src/lib/allocation.ts
 /** Allocations with `programId` set to `percent`; 0 or null removes the line. */
@@ -11390,6 +11461,57 @@ function peopleSpendSlice({ set, get, write }) {
 				allocations: withAllocation(p.allocations, programId, percent)
 			} : p) });
 		},
+		handOver: (fromId, moves, opts) => {
+			const from = get().people.find((p) => p.id === fromId);
+			if (!from) return 0;
+			const until = opts.until || null;
+			const applied = applyMoves(get(), moves, (m) => ({
+				fromName: from.name,
+				toName: get().people.find((p) => p.id === m.toId)?.name ?? "someone",
+				until,
+				untilText: until ? longDate(until) : null,
+				note: opts.note ?? ""
+			}));
+			write({
+				...applied.patch,
+				people: get().people.map((p) => p.id === fromId ? {
+					...p,
+					away: until ? {
+						until,
+						note: opts.note?.trim() || null,
+						since: stamp(),
+						moves: applied.moved
+					} : null
+				} : p)
+			});
+			get().log(until ? `handed over ${from.name}’s work until ${longDate(until)}` : `handed over ${from.name}’s work`, "/people");
+			return applied.moved.length;
+		},
+		handBack: (personId) => {
+			const person = get().people.find((p) => p.id === personId);
+			if (!person?.away) return 0;
+			const back = returnable(get(), person).map((m) => ({
+				...m,
+				toId: personId,
+				fromId: m.toId
+			}));
+			const applied = applyMoves(get(), back, (m) => ({
+				fromName: get().people.find((p) => p.id === m.fromId)?.name ?? "someone",
+				toName: person.name,
+				until: null,
+				untilText: null,
+				note: "Back from time away."
+			}));
+			write({
+				...applied.patch,
+				people: get().people.map((p) => p.id === personId ? {
+					...p,
+					away: null
+				} : p)
+			});
+			get().log(`handed ${person.name}’s work back`, "/people");
+			return applied.moved.length;
+		},
 		updatePerson: (id, patch) => {
 			write({ people: get().people.map((p) => p.id === id ? {
 				...p,
@@ -11484,6 +11606,95 @@ function peopleSpendSlice({ set, get, write }) {
 		}
 	};
 }
+/**
+* One handover's changes as a single write: each item to its new person, the
+* line that travels with it (a comment on a task, an update on a RAID item),
+* and the moves that actually applied. Done or missing items are skipped.
+*/
+function applyMoves(s, moves, lineFor) {
+	const by = s.currentUserId;
+	const at = stamp();
+	const want = (kind) => new Map(moves.filter((m) => m.kind === kind).map((m) => [m.id, m]));
+	const tasksTo = want("task");
+	const signoffsTo = want("signoff");
+	const raidTo = want("raid");
+	const projectsTo = want("project");
+	const programsTo = want("program");
+	const moved = [];
+	const done = (m) => moved.push({
+		kind: m.kind,
+		id: m.id,
+		toId: m.toId
+	});
+	const comments = [];
+	const patch = {};
+	if (tasksTo.size) patch.tasks = s.tasks.map((t) => {
+		const m = tasksTo.get(t.id);
+		if (!m || t.status === "done" || t.assigneeId === m.toId) return t;
+		done(m);
+		comments.push({
+			id: uid("c"),
+			taskId: t.id,
+			authorId: by,
+			body: handoverLine(lineFor(m)),
+			createdAt: at,
+			mentionedIds: []
+		});
+		return stampAssignment(t, {
+			...t,
+			assigneeId: m.toId
+		}, by, at);
+	});
+	if (comments.length) patch.comments = [...s.comments, ...comments];
+	if (signoffsTo.size) patch.milestones = s.milestones.map((ms) => {
+		const m = signoffsTo.get(ms.id);
+		if (!m || ms.done || ms.approverId === m.toId) return ms;
+		done(m);
+		return {
+			...ms,
+			approverId: m.toId
+		};
+	});
+	if (raidTo.size) patch.raidItems = s.raidItems.map((r) => {
+		const m = raidTo.get(r.id);
+		if (!m || r.ownerId === m.toId) return r;
+		done(m);
+		const update = {
+			id: uid("ru"),
+			authorId: by,
+			body: handoverLine(lineFor(m)),
+			createdAt: at
+		};
+		return {
+			...r,
+			ownerId: m.toId,
+			updates: [...r.updates, update],
+			updatedAt: at
+		};
+	});
+	if (projectsTo.size) patch.projects = s.projects.map((p) => {
+		const m = projectsTo.get(p.id);
+		if (!m || p.ownerId === m.toId) return p;
+		done(m);
+		return {
+			...p,
+			ownerId: m.toId
+		};
+	});
+	if (programsTo.size) patch.programs = s.programs.map((p) => {
+		const m = programsTo.get(p.id);
+		if (!m || p.ownerId === m.toId) return p;
+		done(m);
+		return {
+			...p,
+			ownerId: m.toId
+		};
+	});
+	return {
+		patch,
+		moved
+	};
+}
 
 //#endregion
 //#region src/tui/engine/store.ts
@@ -11765,6 +11976,7 @@ const FIELD = {
 	role: "role",
 	weeklyCapacity: "weekly capacity",
 	allocations: "time split",
+	away: "time away",
 	location: "location",
 	note: "note"
 };

package/lib/cli.mjs

@@ -27,6 +27,7 @@ import {
   myWork,
   premortemText,
   voyageText,
+  handoverText,
   raidList,
   programTree,
   projectList,
@@ -116,6 +117,10 @@ 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 handover PERSON [--to NAME] [--until DATE] [--note TEXT]
+                         [--keep ID,ID] [--confirm]
+                                              hand someone's work to the crew
+  harbor handback PERSON                      give it back after time away
 
   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.
@@ -284,10 +289,14 @@ const FLAG = {
   column: "the column",
   limit: "the limit",
   at: "--at",
+  until: "--until",
+  to: "--to",
+  keep: "--keep",
+  person: "the person",
 };
 
 /** 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.`;
@@ -322,8 +331,9 @@ 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(
       /^Nothing to change: pass a field to update\.$/,
@@ -344,11 +354,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".`,
   };
 }
 
@@ -377,10 +396,26 @@ const DETAIL = {
     "  PROJECT is a name, a key like RR, or an id. When two projects share a",
     "  name, give the key.",
   ],
+  handover: [
+    "  harbor handover PERSON                 reads what would move, and to whom:",
+    "                                         their open tasks, sign-offs, risks",
+    "                                         and issues, and what they lead",
+    "  harbor handover PERSON --confirm       writes: hands it over as shown",
+    "",
+    "    --to NAME       all of it to one person, instead of who has room",
+    "    --until DATE    time away: they show as away, and harbor handback PERSON",
+    "                    (or People on the website) gives back what's still with",
+    "                    whoever took it",
+    '    --note "TEXT"   goes with each task and risk as a comment',
+    "    --keep ID,ID    leave these where they are (ids or keys from the list)",
+    "",
+    '  PERSON is a name, an id, or "me".',
+  ],
   voyage: [
     "  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.",
   ],
@@ -766,9 +801,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);
@@ -1283,7 +1319,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) {
@@ -1338,7 +1374,53 @@ 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(
+        spec(["confirm"], ["to", "until", "note", "keep"]),
+      );
+      const person = positionals.join(" ").trim();
+      if (!person) throw new HarborError('Say whose work: harbor handover "NAME" (or me).');
+      if (!values.confirm) {
+        return call("handover_plan", { harbor, person, to: values.to }, (r) => handoverText(r));
+      }
+      return call(
+        "hand_over",
+        {
+          harbor,
+          person,
+          to: values.to,
+          until: dueDate(values.until),
+          note: values.note,
+          keep: values.keep
+            ? values.keep
+                .split(",")
+                .map((k) => k.trim())
+                .filter(Boolean)
+            : undefined,
+        },
+        (r) => {
+          const h = r.handedOver;
+          const names = [...new Set(h.items.map((i) => i.to))];
+          const who =
+            names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
+          const moved = `Handed ${h.person}'s work over: ${h.moved} ${h.moved === 1 ? "thing" : "things"}${who ? ` to ${who}` : ""}.`;
+          return h.awayUntil
+            ? `${moved} ${h.person} shows as away until ${h.awayUntil}; harbor handback "${h.person}" gives it back.`
+            : moved;
+        },
+      );
+    }
+    case "handback": {
+      const { positionals, harbor } = parse(spec());
+      const person = positionals.join(" ").trim();
+      if (!person) throw new HarborError('Say who is back: harbor handback "NAME".');
+      return call("hand_back", { harbor, person }, (r) =>
+        r.handedBack.moved
+          ? `Handed ${r.handedBack.moved} back to ${r.handedBack.person}.`
+          : `${r.handedBack.person} is back. Nothing was still waiting to go back.`,
+      );
     }
     case "risk":
     case "issue":

package/lib/format.mjs

@@ -369,3 +369,30 @@ export function hillList(r) {
   }
   return blocks.join("\n\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 ?? [];
+  if (items.length === 0) return `${r.person} has nothing open to hand over.`;
+  const lines = [
+    `Hand over ${r.person}'s work${r.awayUntil ? ` (away until ${r.awayUntil})` : ""}`,
+  ];
+  let group = null;
+  for (const i of items) {
+    if (i.group !== group) {
+      group = i.group;
+      lines.push("", `${group}:`);
+    }
+    lines.push(
+      `  ${i.what}${i.due && i.kind !== "project" && i.kind !== "program" ? ` (${i.due})` : ""}  → ${i.to ?? "nobody yet"}`,
+    );
+  }
+  const room = (r.takers ?? []).filter((t) => t.note).map((t) => `${t.who} ${t.note}`);
+  if (room.length) lines.push("", `This week: ${room.join(", ")}.`);
+  if (confirmHint)
+    lines.push(
+      "",
+      'Nothing has moved yet. Add --confirm to hand it over, --until DATE for time away, --note "…" to send a note with it, --to NAME to give it all to one person, or --keep ID,ID to leave some where it is.',
+    );
+  return lines.join("\n");
+}

package/package.json

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