@harborppm/cli 0.49.0 → 0.51.0

package/README.md

@@ -155,9 +155,11 @@ harbor risk "TITLE" --project P|--program P [--impact 1-5] [--probability 1-5]
 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]
+                       [--turned-down T] [--look-again DATE] [--supersedes "OLD"]
 harbor risks [words] [--kind risk,issue,decision] [--project P] [--closed]
 harbor raid "TITLE" [--status S] [--owner me|none|NAME] [--impact 1-5] [--probability 1-5]
-                   [--due DATE|none] [--update TEXT] [--mitigation T] [--resolution T] …
+                   [--due DATE|none] [--update TEXT] [--mitigation T] [--resolution T]
+                   [--turned-down T] [--look-again DATE|none] …
                                             one risk, issue or decision in full, or change it
 harbor review [WORDS] [--mine|--owner NAME] [--portfolio P] [--done]
                                             the review: programs worst first, with next moves

package/dist/app.mjs

@@ -2069,7 +2069,8 @@ function normalizeRaidItem(r) {
 		updates: Array.isArray(r.updates) ? r.updates : [],
 		scoreHistory: Array.isArray(r.scoreHistory) && r.scoreHistory.length ? r.scoreHistory : void 0,
 		...kind === "risk" && typeof r.happened === "boolean" ? { happened: r.happened } : {},
-		...kind === "decision" ? decisionFields(r) : {}
+		...kind === "decision" ? decisionFields(r) : {},
+		...ids$1(r.followerIds).length ? { followerIds: ids$1(r.followerIds) } : {}
 	};
 }
 /** A revisit condition that still says something, or null. */
@@ -14719,6 +14720,24 @@ var init_assignment = __esmMin((() => {}));
 //#region src/lib/slices/tasks.ts
 function tasksSlice({ set, get, write }) {
 	return {
+		followWork: (personId, taskIds, raidIds = []) => {
+			const tasks = new Set(taskIds);
+			const raid = new Set(raidIds);
+			const add = (ids) => ids?.includes(personId) ? ids : [...ids ?? [], personId];
+			write({
+				tasks: get().tasks.map((t) => tasks.has(t.id) && t.assigneeId !== personId ? {
+					...t,
+					followerIds: add(t.followerIds)
+				} : t),
+				raidItems: get().raidItems.map((r) => raid.has(r.id) && r.ownerId !== personId ? {
+					...r,
+					followerIds: add(r.followerIds),
+					updatedAt: stamp()
+				} : r)
+			});
+			const who = get().people.find((p) => p.id === personId);
+			get().log(`added ${who?.name ?? "someone"} as a second pair of hands on ${taskIds.length + raidIds.length} item${taskIds.length + raidIds.length === 1 ? "" : "s"}`, "/people");
+		},
 		addTask: (t, opts) => {
 			if (!opts?.allowOverCap) {
 				if (columnWip(get(), t.projectId, t.status, 1)) return "";
@@ -25377,9 +25396,30 @@ function dockCompare(data, projectId, changes, now) {
 		pace: plan.pace,
 		shift: a && b ? dayNumber(b) - dayNumber(a) : null,
 		load,
-		stale: plan.stale
+		stale: plan.stale,
+		notes: dockNotes(plan.project, realTasks, dockTide, now)
 	};
 }
+/**
+* What to know before trusting the shift: the pace is read from weeks of
+* finished work, so a short or lumpy record (work marked done in one go) or
+* a due date that holds the finish can leave the dates where they were.
+*/
+function dockNotes(project, realTasks, docked, now) {
+	if (docked.kind !== "forecast") return [];
+	const notes = [];
+	const weekly = weeklyFinished(realTasks, project.startDate, now);
+	const finished = weekly.reduce((a, b) => a + b, 0);
+	const busiest = Math.max(0, ...weekly);
+	if (weekly.length < 2) notes.push("The pace comes from under two weeks of finished work, so treat the dates as rough.");
+	else if (docked.rough) notes.push(`Only ${finished} task${finished === 1 ? "" : "s"} finished in the last ${weekly.length} weeks, so treat the dates as rough.`);
+	if (weekly.length >= 2 && finished >= 4 && busiest * 2 > finished) notes.push(`${busiest} of the ${finished} tasks finished lately were marked done in one week, so the pace jumps from week to week and a few tasks more or less may not move the dates.`);
+	if (docked.heldBy?.dueDate) {
+		const name = taskKey(docked.heldBy, project) ?? docked.heldBy.title;
+		notes.push(`${name} is due ${shortDate(docked.heldBy.dueDate)}, after the pace would finish, so its due date sets the finish and work done before then doesn't move it.`);
+	}
+	return notes;
+}
 /** "11 days sooner", "3 days later", "Same day", or null without both forecasts. */
 function shiftText(shift) {
 	if (shift == null) return null;
@@ -25573,6 +25613,10 @@ function tryLines(data, project, changes, cmp, today) {
 	const end = docked.project.endDate;
 	if (end >= today && real.tide.kind === "forecast" && docked.tide.kind === "forecast") out.push(row(`Making ${shortDate(end)}`, end === real.project.endDate ? chanceText(real.tide.chanceByEnd) : "-", chanceText(docked.tide.chanceByEnd)));
 	if (cmp.pace !== 1) out.push(row("Crew pace", "100%", `${Math.round(cmp.pace * 100)}%`));
+	if (changes.length && cmp.notes.length) {
+		out.push("");
+		for (const n of cmp.notes) out.push(`  Note: ${n}`);
+	}
 	if (cmp.load.length) {
 		out.push("", "  Due in the next six weeks:");
 		for (const l of cmp.load) {
@@ -25621,6 +25665,14 @@ async function tryHere(opts) {
 			lines
 		};
 		if ((opts.apply || opts.save) && changes.length === 0) throw new HarborError("There are no changes to apply or save. Add some, like --drop RL-4.");
+		if (opts.apply && !opts.confirm) {
+			const gone = changes.flatMap((c) => {
+				if (c.kind !== "drop") return [];
+				const t = data.tasks.find((x) => x.id === c.taskId);
+				return t ? [`${taskKey(t, project) ?? t.id} ${t.title}`] : [];
+			});
+			if (gone.length) throw new HarborError(`--apply removes ${gone.length === 1 ? "this task" : `these ${gone.length} tasks`} from the harbor:\n${gone.map((g) => `  ${g}`).join("\n")}\nTo remove ${gone.length === 1 ? "it" : "them"}, run it again with --confirm. Nothing was changed.`);
+		}
 		if (opts.apply) {
 			const s = store.getState();
 			result.applied = applyDock({

package/lib/cli.mjs

@@ -85,7 +85,7 @@ export const HELP = `harbor: Harbor from the terminal
   harbor try PROJECT [--drop KEYS] [--add "TITLE" [--count N]]
                      [--due KEY=DATE] [--give KEY=NAME] [--end DATE]
                      [--borrow NAME[=DAYS]] [--release NAME]
-                     [--saved] [--apply|--save|--discard]
+                     [--saved] [--apply [--confirm]|--save|--discard]
                                               dry dock: the forecast with plan
                                               changes tried on a copy; nothing
                                               changes without --apply
@@ -142,6 +142,8 @@ export const HELP = `harbor: Harbor from the terminal
   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]
+                         [--turned-down T] [--look-again DATE]
+                         [--supersedes "OLD DECISION"]
   harbor risks [words] [--kind risk,issue,decision] [--project P] [--closed]
                                               the register, worst first
                                               (--closed adds closed ones)
@@ -149,7 +151,7 @@ export const HELP = `harbor: Harbor from the terminal
                      [--probability 1-5] [--due DATE|none] [--update TEXT]
                      [--title T] [--description T] [--mitigation T]
                      [--contingency T] [--resolution T] [--rationale T]
-                     [--notes T]
+                     [--notes T] [--turned-down T] [--look-again DATE|none]
                                               one risk, issue or decision in
                                               full, or change it
   harbor review [WORDS] [--mine|--owner NAME] [--portfolio P] [--done]
@@ -566,6 +568,8 @@ const DETAIL = {
     "  harbor try PROJECT [changes]           reads the forecast with the changes",
     "                                         tried on a copy of the plan",
     "  harbor try PROJECT [changes] --apply   writes: makes the changes for real",
+    "                                         (--confirm too when it drops tasks:",
+    "                                         they're removed from the harbor)",
     "  harbor try PROJECT [changes] --save    writes: keeps them on the project to",
     "                                         show someone (Forecast tab, Open dry",
     "                                         dock)",
@@ -574,7 +578,8 @@ const DETAIL = {
     "  harbor try PROJECT --discard           writes: throws the saved ones away",
     "",
     "  Changes, each taking several with commas between:",
-    "    --drop RL-4,RL-5        take tasks out of the plan (--apply removes them)",
+    "    --drop RL-4,RL-5        take tasks out of the plan (--apply --confirm",
+    "                            removes them)",
     '    --add "TITLE" --count N new work, N tasks called TITLE',
     "    --due RL-4=fri          move a due date (none takes it off)",
     "    --give RL-4=Sam         give a task to someone (none: nobody)",
@@ -588,6 +593,13 @@ const DETAIL = {
     "  date, the crew's pace, and the load of everyone the changes touch. A",
     "  borrowed person adds an average crew member's pace for each day a week",
     "  they give; a released one takes away their share of what was finished.",
+    "  Notes under it say when the dates may not move: a short or lumpy record",
+    "  of finished work, or a due date that sets the finish.",
+    "",
+    "  --json gives each plan's endDate, open, likely, veryLikely, chanceByEnd",
+    "  and tasksPerWeek (noForecast says why when there are no dates), the",
+    "  shiftDays between them, crewPacePercent (100 is the crew as it is) and",
+    "  the notes.",
   ],
   report: [
     "  harbor report PROGRAM                  reads the program's status report",
@@ -733,7 +745,8 @@ const DETAIL = {
     "  Also --owner me|none|NAME, --impact 1-5, --probability 1-5 (risks),",
     "  --due DATE|none (review by, or decide by), --title, --description,",
     "  --mitigation and --contingency (risks), --resolution (issues and",
-    "  decisions), --rationale (decisions) and --notes. TITLE is its title or",
+    "  decisions), --rationale, --turned-down and --look-again DATE|none",
+    "  (decisions) and --notes. TITLE is its title or",
     "  enough of it to pick one out; harbor risks lists them. Changes several",
     "  at once, as one change.",
   ],
@@ -784,6 +797,12 @@ const DETAIL = {
     '  harbor decision "TITLE" --project P    writes: logs a decision to make',
     '  harbor decision "TITLE" --program P    writes: logs one on the program',
     "      [--owner NAME] [--due DATE] (the date to decide by)",
+    "      [--turned-down T] (what was turned down, and why not)",
+    "      [--look-again DATE] (when it comes back to the top of the brief)",
+    '  harbor decision "TITLE" --supersedes "OLD"',
+    "                                         writes: a decision that replaces an",
+    "                                         earlier one, which reads as",
+    "                                         superseded",
   ],
 };
 
@@ -840,6 +859,9 @@ function distance(a, b) {
 /** A mistyped command, with the one it was probably meant to be. */
 export function noCommand(name) {
   if (name.startsWith("-")) return `${name} goes after a command, like harbor mine ${name}.`;
+  // A plural kind reads the register, not the command that writes one.
+  if (["decisions", "issues"].includes(name))
+    return `No command "${name}". harbor risks --kind ${name.slice(0, -1)} lists them.`;
   const near = COMMANDS.filter((c) => distance(name, c) <= (c.length > 4 ? 2 : 1));
   const guess = near.length === 1 ? ` Did you mean harbor ${near[0]}?` : "";
   return `No command "${name}".${guess} Run harbor help.`;
@@ -1169,7 +1191,7 @@ export async function run(argv, io = {}) {
 
   if (command === "try") {
     const { values, positionals } = parseArgs(rest, {
-      flags: ["apply", "save", "discard", "saved", "json"],
+      flags: ["apply", "confirm", "save", "discard", "saved", "json"],
       options: ["harbor", "drop", "add", "count", "due", "give", "end", "borrow", "release"],
     });
     if (positionals.length !== 1)
@@ -1180,6 +1202,8 @@ export async function run(argv, io = {}) {
       );
     if (["apply", "save", "discard"].filter((k) => values[k]).length > 1)
       throw new HarborError("Use one of --apply, --save or --discard.");
+    if (values.confirm && !values.apply)
+      throw new HarborError("--confirm goes with --apply, to remove the tasks it drops.");
     const creds = await readCredentials(env);
     if (!hasFullAccess(creds))
       throw new HarborError(
@@ -1198,6 +1222,7 @@ export async function run(argv, io = {}) {
       project: positionals[0],
       flags: values,
       apply: Boolean(values.apply),
+      confirm: Boolean(values.confirm),
       save: Boolean(values.save),
       discard: Boolean(values.discard),
       say,
@@ -1216,14 +1241,19 @@ export async function run(argv, io = {}) {
       return 0;
     }
     if (values.json) {
-      const side = (s) => ({
-        endDate: s.project.endDate,
-        open: s.open,
-        likely: s.tide.kind === "forecast" ? s.tide.likely : null,
-        veryLikely: s.tide.kind === "forecast" ? s.tide.veryLikely : null,
-        chanceByEnd: s.tide.kind === "forecast" ? s.tide.chanceByEnd : null,
-        forecast: s.tide.kind,
-      });
+      const side = (s) => {
+        const f = s.tide.kind === "forecast" ? s.tide : null;
+        return {
+          endDate: s.project.endDate,
+          open: s.open,
+          likely: f?.likely ?? null,
+          veryLikely: f?.veryLikely ?? null,
+          chanceByEnd: f?.chanceByEnd ?? null,
+          tasksPerWeek: f?.perWeek ?? null,
+          // Why there are no dates, when there aren't: no pace yet, paused, done.
+          noForecast: f ? null : s.tide.kind,
+        };
+      };
       const c = result.comparison;
       out(
         jsonText({
@@ -1232,10 +1262,10 @@ export async function run(argv, io = {}) {
           real: side(c.real),
           dryDock: side(c.docked),
           shiftDays: c.shift,
-          pace: c.pace,
+          crewPacePercent: Math.round(c.pace * 100),
           ...(result.applied !== undefined ? { applied: result.applied } : {}),
           ...(result.saved ? { saved: true } : {}),
-          notes,
+          notes: [...c.notes, ...notes],
         }),
       );
       return 0;
@@ -1790,7 +1820,9 @@ export async function run(argv, io = {}) {
           );
         }
         if (values.confirm || values["over-limit"]) {
-          throw new HarborError("--confirm and --over-limit are for moving a task: harbor submit TASK.");
+          throw new HarborError(
+            "--confirm and --over-limit are for moving a task: harbor submit TASK.",
+          );
         }
         if (values.mine && values.owner) throw new HarborError("Say --mine or --owner, not both.");
         return call(
@@ -1943,7 +1975,7 @@ export async function run(argv, io = {}) {
           includeClosed: Boolean(values.closed),
           limit: 50,
         },
-        (r) => raidList(r, positionals.join(" ")),
+        (r) => raidList(r, positionals.join(" "), kind),
       );
     }
     case "report": {
@@ -2272,6 +2304,8 @@ export async function run(argv, io = {}) {
             "update",
             "decided-by",
             "decided-on",
+            "turned-down",
+            "look-again",
             ...fields,
           ],
         ),
@@ -2289,6 +2323,9 @@ export async function run(argv, io = {}) {
         decidedBy: values["decided-by"],
         decidedOn:
           values["decided-on"] === undefined ? undefined : nullable(dueDate(values["decided-on"])),
+        turnedDown: values["turned-down"],
+        revisitOn:
+          values["look-again"] === undefined ? undefined : nullable(dueDate(values["look-again"])),
         update: values.update,
         ...Object.fromEntries(fields.map((f) => [f, values[f]])),
       };
@@ -2350,11 +2387,15 @@ export async function run(argv, io = {}) {
         spec(
           [],
           ["project", "program", "owner", "due"].concat(
-            command === "risk" ? ["impact", "probability"] : command === "issue" ? ["impact"] : [],
+            command === "risk"
+              ? ["impact", "probability"]
+              : command === "issue"
+                ? ["impact"]
+                : ["supersedes", "turned-down", "look-again"],
           ),
         ),
       );
-      if (!values.project && !values.program) {
+      if (!values.project && !values.program && !values.supersedes) {
         throw new HarborError("Say where it belongs: --project NAME or --program NAME.");
       }
       return call(
@@ -2369,8 +2410,14 @@ export async function run(argv, io = {}) {
           impact: level(values.impact, "impact"),
           probability: level(values.probability, "probability"),
           due: dueDate(values.due),
+          supersedes: values.supersedes,
+          turnedDown: values["turned-down"],
+          revisitOn: values["look-again"] === undefined ? undefined : dueDate(values["look-again"]),
         },
-        (r) => `Logged the ${command} “${r.raised.title}”.`,
+        (r) =>
+          r.replaces
+            ? `Logged the decision “${r.raised.title}”; it replaces “${r.replaces.title}”.`
+            : `Logged the ${command} “${r.raised.title}”.`,
       );
     }
     default:

package/lib/format.mjs

@@ -246,12 +246,19 @@ export function todayLocal(d = new Date()) {
 }
 
 /** The register, worst first: kind, title, then status, scores, owner and where it sits. */
-export function raidList(r, words = "") {
+export function raidList(r, words = "", kinds = []) {
   const want = words.trim().toLowerCase();
   const items = (r.items ?? []).filter(
     (x) => !want || `${x.title} ${x.description ?? ""}`.toLowerCase().includes(want),
   );
-  if (!items.length) return want ? "Nothing in the register matches." : "The register is clear.";
+  if (!items.length) {
+    if (want) return "Nothing in the register matches.";
+    const only =
+      kinds?.length === 1
+        ? { risk: "risks", issue: "issues", decision: "decisions" }[kinds[0]]
+        : null;
+    return only ? `No ${only} in the register.` : "The register is clear.";
+  }
   const lines = items.map((x) => {
     const bits = [
       x.status?.toLowerCase(),

package/package.json

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