@harborppm/cli 0.52.0 → 0.54.0

package/lib/cli.mjs

@@ -35,6 +35,8 @@ import {
   notesText,
   daysText,
   soundingText,
+  lifeboatsText,
+  followedText,
   soundingsText,
   voyageText,
   whyText,
@@ -112,6 +114,10 @@ export const HELP = `harbor: Harbor from the terminal
                  [--off]
                                               a project's public roadmap: read,
                                               publish or take it down
+  harbor shore PROGRAM [--url URL] [--on KINDS] [--off KINDS] [--test]
+               [--remove]
+                                              a program's chat channel (Slack,
+                                              Discord, Teams) and its posts
 
   harbor init [PROJECT] [--hook] [--dry-run]  keep a project's tasks as files in
                                               this repository (.harbor/), one
@@ -125,7 +131,9 @@ export const HELP = `harbor: Harbor from the terminal
   harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                        [--ends DATE]
   harbor project "NAME" --program P [--lead me|NAME] [--starts DATE]
-                       [--ends DATE] [--budget N]
+                       [--ends DATE] [--budget N] [--from "DONE PROJECT"]
+                                              --from: plan it from a finished
+                                              project as that one really ran
   harbor add "TITLE" --project P [--assignee me|none|NAME] [--due DATE]
                      [--priority low|medium|high|urgent] [--status S]
                      [--over-limit]
@@ -155,12 +163,17 @@ export const HELP = `harbor: Harbor from the terminal
                      [--title T] [--description T] [--mitigation T]
                      [--contingency T] [--resolution T] [--rationale T]
                      [--notes T] [--turned-down T] [--look-again DATE|none]
+                     [--still-stands WHY]
                                               one risk, issue or decision in
                                               full, or change it
   harbor review [WORDS] [--mine|--owner NAME] [--portfolio P] [--done]
                                               the review: programs worst first,
                                               each with its next move (reads
                                               only; harbor submit moves a task)
+  harbor bridge [--harbor H]                  run the review as a meeting: one
+                                              project a screen, what changed
+                                              since the last one, decisions,
+                                              actions and risks logged live
   harbor next-move PROGRAM "TEXT"             write a program's next move
   harbor health --program P|--project P|--portfolio P STATE [--note WHY]
                                               set its health by hand, or auto
@@ -197,6 +210,10 @@ export const HELP = `harbor: Harbor from the terminal
                                               weeks, one at a time: still
                                               needed, a new date, or drop it
   harbor fog keep TASK                        it's still needed: out of the fog
+  harbor lifeboats [--program P]              work only one person knows, each
+                                              with a second pair of hands
+  harbor lifeboats N [--person NAME]          adds that second pair of hands
+  harbor follow TASK|RISK --person NAME       someone follows it too
   harbor agent [--agent NAME]                 the tasks given to an AI agent on
                                               the crew, in the order to do them
   harbor agent report TASK "WHAT YOU DID" [--start] [--agent NAME]
@@ -528,6 +545,23 @@ const DETAIL = {
     "  PROJECT is a name, a key like RR, or an id. When two projects share a",
     "  name, give the key.",
   ],
+  shore: [
+    "  harbor shore PROGRAM                   reads the program's chat channel and",
+    "                                         which posts go there",
+    "  harbor shore PROGRAM --url URL         writes: posts go to this Slack, Discord",
+    "                                         or Teams incoming-webhook address",
+    "  harbor shore PROGRAM --on KINDS        writes: turns posts on; KINDS are",
+    "                                         forecast, health and notes, with commas",
+    "  harbor shore PROGRAM --off KINDS       writes: turns them off",
+    "  harbor shore PROGRAM --test            writes: sends a test post",
+    "  harbor shore PROGRAM --remove          writes: stops posting and forgets the",
+    "                                         address",
+    "",
+    "  forecast is the morning harbor forecast, health a line when the program or",
+    "  one of its projects changes health, notes a note for later when it opens.",
+    "  Every post links back to Harbor. A new channel posts nothing until you turn",
+    "  something on. The address is a secret: once saved, only a hint of it shows.",
+  ],
   roadmap: [
     "  harbor roadmap PROJECT                 reads whether it's public, and its link",
     "  harbor roadmap PROJECT --publish       writes: publishes it, or keeps it live",
@@ -694,6 +728,20 @@ const DETAIL = {
     "  Piped, or with --json, it lists. The one-at-a-time sweep needs full access",
     "  (harbor login without --read-only), since dropping a task deletes it.",
   ],
+  lifeboats: [
+    "  harbor lifeboats [--program P]         reads: work only one person has",
+    "                                         touched (a project, their corner of",
+    "                                         one, a task others wait on, their",
+    "                                         serious risks), numbered, each with",
+    "                                         someone who has room to take a look",
+    "  harbor lifeboats N [--person NAME]     writes: puts that person (or NAME)",
+    "                                         on line N as a second pair of hands",
+  ],
+  follow: [
+    "  harbor follow TASK --person NAME       writes: NAME follows the task too,",
+    "                                         without taking it over",
+    '  harbor follow "RISK" --person NAME     the same for a risk or issue',
+  ],
   handback: [
     "  harbor handback PERSON                 writes, straight away: gives back",
     "                                         what was handed over for their time",
@@ -758,6 +806,10 @@ const DETAIL = {
     "                                         today unless --decided-by or",
     "                                         --decided-on say otherwise)",
     '  harbor raid "TITLE" --update "TEXT"    writes: adds a line to its updates',
+    '  harbor raid "TITLE" --still-stands "WHY"',
+    "                                         writes: a decision looked at again",
+    "                                         still stands (\"\" for no reason);",
+    "                                         clears its look again",
     "",
     "  Also --owner me|none|NAME, --impact 1-5, --probability 1-5 (risks),",
     "  --due DATE|none (review by, or decide by), --title, --description,",
@@ -767,6 +819,20 @@ const DETAIL = {
     "  enough of it to pick one out; harbor risks lists them. Changes several",
     "  at once, as one change.",
   ],
+  bridge: [
+    "  harbor bridge                          opens the full-screen app on the",
+    "                                         review meeting (b on the Programs",
+    "                                         screen, or : Run the review meeting)",
+    "",
+    "  One open project a screen, with only what changed since its program was",
+    "  last reviewed (a week back the first time): health moves, work finished,",
+    "  newly late or added, risks raised, decisions made. ←→ move between",
+    "  projects; d logs a decision, a an action (who takes it, due in a week),",
+    "  r a risk, m the program's next move; e ends it. The summary lists what",
+    "  was logged; p posts it to each program's chat channel where one is set",
+    "  (Ship to shore, set on the website), y copies it. The next meeting",
+    "  counts from when this one ended.",
+  ],
   review: [
     "  harbor review                          reads the review: every program,",
     "                                         worst health first, then soonest end,",
@@ -990,7 +1056,7 @@ export async function run(argv, io = {}) {
   }
 
   // On its own in a terminal: the full-screen app. Piped or scripted: the help.
-  if (!command || command === "app") {
+  if (!command || command === "app" || command === "bridge") {
     const terminal = io.terminal ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
     if (!command && !terminal) {
       out(HELP);
@@ -999,7 +1065,7 @@ export async function run(argv, io = {}) {
     if (!terminal) throw new HarborError("The full-screen app needs a terminal.");
     const { values } = parseArgs(rest, { flags: [], options: ["harbor", "server"] });
     // In a folder with a local plan (harbor init --local), the app opens on it.
-    if (!values.harbor && !values.server) {
+    if (!values.harbor && !values.server && command !== "bridge") {
       const bundled = await loadApp();
       const dir = await bundled.localPlanAt(io.cwd ?? process.cwd());
       if (dir) {
@@ -1056,6 +1122,7 @@ export async function run(argv, io = {}) {
       },
       theme: (await readSettings(env)).theme,
       browse: io.browse ?? openBrowser,
+      ...(command === "bridge" ? { startIn: "bridge" } : {}),
     });
     return 0;
   }
@@ -1301,6 +1368,12 @@ export async function run(argv, io = {}) {
           `⚓ Saved on ${result.project.name}. It's on the Forecast tab under Open dry dock; --apply makes it real.`,
         ),
       );
+    else if (result.drops.length)
+      out(
+        plain(
+          `Nothing was changed. --apply --confirm would delete ${result.drops.join(", ")}; --save keeps the changes to show someone.`,
+        ),
+      );
     else if (result.changes.length)
       out(
         "Nothing was changed. Add --apply to make these changes, or --save to keep them to show someone.",
@@ -1511,7 +1584,7 @@ export async function run(argv, io = {}) {
     }
     case "project": {
       const { positionals, values, harbor } = parse(
-        spec([], ["program", "lead", "starts", "ends", "budget"]),
+        spec([], ["program", "lead", "starts", "ends", "budget", "from"]),
       );
       if (!values.program) throw new HarborError("Say which program: --program NAME.");
       let budget;
@@ -1531,9 +1604,18 @@ export async function run(argv, io = {}) {
           starts: dueDate(values.starts),
           ends: dueDate(values.ends),
           budget,
+          planFrom: values.from,
+        },
+        (r) => {
+          const opened = `Opened the project ${r.created.name} in ${r.created.program} (${r.created.starts} to ${r.created.ends}, lead ${r.created.lead ?? "nobody"}).`;
+          const f = r.plannedFrom;
+          if (!f)
+            return `${opened} Add work with harbor add "TITLE" --project "${r.created.name}".`;
+          const came = f.risks
+            ? `, and ${f.risks} risk${f.risks === 1 ? "" : "s"} that came true`
+            : "";
+          return `${opened}\nPlanned from ${f.project}: ${f.tasks} task${f.tasks === 1 ? "" : "s"}, each due when it really finished last time${came}. ${f.says}`;
         },
-        (r) =>
-          `Opened the project ${r.created.name} in ${r.created.program} (${r.created.starts} to ${r.created.ends}, lead ${r.created.lead ?? "nobody"}). Add work with harbor add "TITLE" --project "${r.created.name}".`,
       );
     }
     case "forecast": {
@@ -1798,6 +1880,75 @@ export async function run(argv, io = {}) {
       );
       return 0;
     }
+    case "shore": {
+      const { positionals, values, harbor } = parse(spec(["test", "remove"], ["url", "on", "off"]));
+      const program = text(positionals, "which program");
+      const kinds = (flag) => {
+        if (values[flag] === undefined) return undefined;
+        const list = values[flag]
+          .split(",")
+          .map((k) => k.trim().toLowerCase())
+          .filter(Boolean);
+        const bad = list.find((k) => !["forecast", "health", "notes"].includes(k));
+        if (bad || !list.length)
+          throw new HarborError(`--${flag} takes forecast, health or notes, with commas between.`);
+        return list;
+      };
+      const on = kinds("on");
+      const off = kinds("off");
+      if (on && off && on.some((k) => off.includes(k)))
+        throw new HarborError("Say each kind of post once, with --on or --off.");
+      if (values.remove && (values.url || on || off || values.test))
+        throw new HarborError("--remove goes on its own.");
+      if (!hasFullAccess(creds)) {
+        throw new HarborError("Chat channels need full access. Run harbor login, then try again.");
+      }
+      const r = await client.app({
+        op: "shore",
+        ...(harbor ? { harbor } : {}),
+        program,
+        ...(values.url ? { url: values.url } : {}),
+        ...(on ? { on } : {}),
+        ...(off ? { off } : {}),
+        ...(values.test ? { test: true } : {}),
+        ...(values.remove ? { remove: true } : {}),
+      });
+      if (asJson) {
+        out(jsonText(r));
+        return 0;
+      }
+      if (!r.hook) {
+        out(
+          plain(
+            r.removed
+              ? `${r.program} doesn't post to a chat channel any more.`
+              : `${r.program} has no chat channel. harbor shore "${r.program}" --url URL --on forecast,health adds one: make an incoming webhook in the channel's settings and paste its address.`,
+          ),
+        );
+        return 0;
+      }
+      const label = {
+        forecast: "morning forecast",
+        health: "health changes",
+        notes: "notes when they open",
+      };
+      const posts = ["forecast", "health", "notes"].filter((k) => r.hook[k]).map((k) => label[k]);
+      const lines = [
+        `${r.program} posts to ${r.hook.service} (${r.hook.hint}): ${posts.length ? posts.join(", ") : "nothing yet; --on forecast,health,notes turns posts on"}.`,
+      ];
+      if (r.hook.failures > 0)
+        lines.push(
+          `The last ${r.hook.failures} post${r.hook.failures === 1 ? "" : "s"} didn't go through. Check the address, or --url swaps it.`,
+        );
+      if ("tested" in r)
+        lines.push(
+          r.tested
+            ? "Sent a test post."
+            : "The channel didn't take the test post. Check the address.",
+        );
+      out(plain(lines.join("\n")));
+      return 0;
+    }
     case "add": {
       const { positionals, values, harbor } = parse(
         spec(["over-limit"], ["project", "assignee", "due", "priority", "status"]),
@@ -2234,11 +2385,7 @@ export async function run(argv, io = {}) {
         await stalePromptCache(env);
         return 0;
       }
-      return call(
-        "fog",
-        { harbor, project: values.project, limit: 100 },
-        (r) => fogText(r),
-      );
+      return call("fog", { harbor, project: values.project, limit: 100 }, (r) => fogText(r));
     }
     case "handover": {
       const { positionals, values, harbor } = parse(
@@ -2295,6 +2442,50 @@ export async function run(argv, io = {}) {
           `${r.updated.key ?? r.updated.title} is ${r.updated.status === "review" ? "in review for a person to check" : "in play"}, with ${r.commentedAs}'s note.`,
       );
     }
+    case "lifeboats": {
+      const { positionals, values, harbor } = parse(spec([], ["program", "person"]));
+      if (positionals.length > 1)
+        throw new HarborError("harbor lifeboats takes one line number: harbor lifeboats 2.");
+      if (!positionals.length) {
+        if (values.person)
+          throw new HarborError("--person goes with a line: harbor lifeboats 2 --person NAME.");
+        return call("lifeboats", { harbor, program: values.program, limit: 100 }, (r) =>
+          lifeboatsText(r),
+        );
+      }
+      const n = Number(positionals[0]);
+      if (!Number.isInteger(n) || n < 1)
+        throw new HarborError("Give a line number from harbor lifeboats, like harbor lifeboats 2.");
+      const list = await client.call("lifeboats", {
+        harbor,
+        program: values.program,
+        limit: 100,
+      });
+      const line = list.lines[n - 1];
+      if (!line)
+        throw new HarborError(
+          list.count
+            ? `There ${list.count === 1 ? "is 1 line" : `are ${list.count} lines`}; harbor lifeboats lists them.`
+            : "Nothing only one person knows right now.",
+        );
+      return call("follow_work", { harbor, lifeboat: line.id, person: values.person }, (r) =>
+        followedText(r),
+      );
+    }
+    case "follow": {
+      const { positionals, values, harbor } = parse(spec([], ["person"]));
+      const what = positionals.join(" ").trim();
+      if (!what) throw new HarborError("Say what: harbor follow TASK --person NAME.");
+      if (!values.person)
+        throw new HarborError("Say who: harbor follow TASK --person NAME (or me).");
+      // A task key reads as a task; anything else is a risk's title.
+      const isKey = /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(what);
+      return call(
+        "follow_work",
+        { harbor, ...(isKey ? { task: what } : { raid: what }), person: values.person },
+        (r) => followedText(r),
+      );
+    }
     case "handback": {
       const { positionals, harbor } = parse(spec());
       const person = positionals.join(" ").trim();
@@ -2329,6 +2520,7 @@ export async function run(argv, io = {}) {
             "decided-on",
             "turned-down",
             "look-again",
+            "still-stands",
             ...fields,
           ],
         ),
@@ -2350,6 +2542,7 @@ export async function run(argv, io = {}) {
         revisitOn:
           values["look-again"] === undefined ? undefined : nullable(dueDate(values["look-again"])),
         update: values.update,
+        stillStands: values["still-stands"],
         ...Object.fromEntries(fields.map((f) => [f, values[f]])),
       };
       const changes = Object.entries(args).filter(

package/lib/format.mjs

@@ -393,11 +393,52 @@ export function forecastList(r) {
       const name = p.name.length > width ? `${p.name.slice(0, width - 1)}…` : p.name.padEnd(width);
       if (f.none) return `${name}  no forecast: ${f.none.replace(/^\w/, (c) => c.toLowerCase())}`;
       const end = p.ends ? ` · ${chance(f.chanceByEnd)} by its end, ${p.ends}` : "";
-      return [`${name}  ${finishRange(f)}${end}`, ...finishNotes(f)].join(" · ");
+      const slip =
+        f.costOfSlip?.atLikely >= 100 ? `late adds about ${dollars(f.costOfSlip.atLikely)}` : null;
+      return [`${name}  ${finishRange(f)}${end}`, ...finishNotes(f), slip]
+        .filter(Boolean)
+        .join(" · ");
     })
     .join("\n");
 }
 
+/** Money to the nearest hundred, as "$4,800" (src/lib/slip-cost.ts's dollars). */
+function dollars(n) {
+  const r = Math.round(Math.abs(n) / 100) * 100;
+  return `${n < 0 && r > 0 ? "-" : ""}$${r.toLocaleString("en-US")}`;
+}
+
+/**
+ * The cost of a slip, as the Forecast tab says it: what each week late
+ * costs at the project's recent spend, what the likely and very likely
+ * dates add, and where the 85% date leaves the budget. Empty when the
+ * project has no budget or recent spend.
+ */
+function slipLines(f) {
+  const c = f.costOfSlip;
+  if (!c || c.perWeekLate < 50) return [];
+  const lines = [
+    `Each week late costs about ${dollars(c.perWeekLate)}, from the spend ledger's last eight weeks.`,
+  ];
+  const adds = [
+    c.atLikely >= 100 ? `finishing ${f.likely} adds about ${dollars(c.atLikely)}` : null,
+    c.atVeryLikely >= 100 && f.veryLikely !== f.likely
+      ? `${f.veryLikely} about ${dollars(c.atVeryLikely)}`
+      : null,
+  ].filter(Boolean);
+  if (adds.length) lines.push(`Past its end date, ${adds.join("; ")}.`);
+  const over = c.overBudgetAtVeryLikely;
+  if (over !== undefined && f.veryLikely)
+    lines.push(
+      Math.abs(over) < 100
+        ? `By ${f.veryLikely} it would use about the whole budget.`
+        : over > 0
+          ? `By ${f.veryLikely} it would end about ${dollars(over)} over budget.`
+          : `By ${f.veryLikely} it would still be about ${dollars(-over)} under budget.`,
+    );
+  return lines;
+}
+
 /** One project's forecast, in a few sentences. */
 export function forecastOne(p) {
   const f = p.finish ?? {};
@@ -426,6 +467,7 @@ export function forecastOne(p) {
       `${which} is due ${f.lastDue.due}, later than the crew's pace alone would finish, so the dates wait for it.`,
     );
   }
+  lines.push(...slipLines(f));
   return lines.join("\n");
 }
 
@@ -835,3 +877,33 @@ export function fogText(r, { sweepHint = true } = {}) {
     );
   return lines.join("\n");
 }
+
+/** harbor lifeboats: work only one person knows, numbered for harbor lifeboats N. */
+export function lifeboatsText(r) {
+  const where = r.program ? ` in ${r.program}` : "";
+  if (!r.count) return `Nothing${where} that only one person knows. Good.`;
+  const lines = [
+    `${r.count} ${r.count === 1 ? "thing" : "things"} only one person knows${where}: nobody else has been assigned, commented or written in ${r.count === 1 ? "it" : "them"}.`,
+    "",
+  ];
+  r.lines.forEach((l, n) => {
+    lines.push(`  ${String(n + 1).padStart(2)}. ${l.what}`);
+    const bits = [`only ${l.onlyKnownBy}`, l.detail, l.due ? `due ${l.due}` : null];
+    lines.push(`      ${bits.filter(Boolean).join(" · ")}`);
+    if (l.suggest)
+      lines.push(`      ${l.suggest.person} could take a second look: ${l.suggest.why}`);
+  });
+  if (r.more) lines.push("", `And ${r.count - r.lines.length} more.`);
+  for (const a of r.away ?? []) lines.push("", a);
+  lines.push(
+    "",
+    "harbor lifeboats N adds the suggested second pair of hands (--person NAME for someone else).",
+  );
+  return lines.join("\n");
+}
+
+/** What follow_work did. */
+export function followedText(r) {
+  const f = r.followed;
+  return `${f.person} is a second pair of hands on ${f.what}: they follow it now, and it stays with whoever has it.`;
+}

package/package.json

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