@harborppm/cli 0.49.0 → 0.50.0

package/dist/app.mjs

@@ -25377,9 +25377,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 +25594,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 +25646,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
@@ -566,6 +566,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 +576,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 +591,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",
@@ -1169,7 +1179,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 +1190,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 +1210,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 +1229,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 +1250,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 +1808,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(

package/package.json

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