@harborppm/cli 0.42.0 → 0.44.0

package/lib/cli.mjs

@@ -36,7 +36,9 @@ import {
   voyageText,
   handoverText,
   agentWorkText,
+  raidDetail,
   raidList,
+  reviewList,
   programTree,
   projectList,
   taskLine,
@@ -130,6 +132,19 @@ export const HELP = `harbor: Harbor from the terminal
   harbor risks [words] [--kind risk,issue,decision] [--project P] [--closed]
                                               the register, worst first
                                               (--closed adds closed ones)
+  harbor raid "TITLE" [--status S] [--owner me|none|NAME] [--impact 1-5]
+                     [--probability 1-5] [--due DATE|none] [--update TEXT]
+                     [--title T] [--description T] [--mitigation T]
+                     [--contingency T] [--resolution T] [--rationale T]
+                     [--notes T]
+                                              one risk, issue or decision in
+                                              full, or change it
+  harbor review [--mine|--owner NAME] [--portfolio P] [--done]
+                                              the review: programs worst first,
+                                              each with its next move
+  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
   harbor brief [--portfolio P] [--all] [--say]
                                               the weekly brief, ready to send
                                               (--all lists every late and done
@@ -320,6 +335,11 @@ const FLAG = {
   query: "the words",
   task: "the task",
   note: "the check-in",
+  health: "the health",
+  decidedBy: "--decided-by",
+  decidedOn: "--decided-on",
+  item: "the title",
+  text: "the next move",
   waitsOn: "--waits-on",
   repeat: "--repeat",
   description: "--notes",
@@ -506,12 +526,13 @@ const DETAIL = {
     "  harbor forecast PROJECT                reads one project's forecast and what",
     "                                         it rests on",
     "",
-    "  Worked out from the crew's pace alone: how many tasks they finished each",
-    "  week over the last six (or the project's life, if shorter), replayed a",
+    "  Worked out from the crew's pace: how many tasks they finished each week",
+    "  over the last six (or the project's life, if shorter), replayed a",
     "  thousand times until its open tasks run out. Probably is half of those",
     "  runs, very likely 85%, almost certainly 95%. No estimates or points.",
-    "  It warns when under two weeks of pace is all there is, and when an open",
-    "  task is due after the likely finish, since the pace can't see due dates.",
+    "  No run finishes before the last open task is due, so a task due later",
+    "  than the pace would finish sets the dates, and the forecast names it. It",
+    "  warns when under two weeks of pace is all there is.",
   ],
   report: [
     "  harbor report PROGRAM                  reads the program's status report",
@@ -608,6 +629,57 @@ const DETAIL = {
     "  PROJECT is a name, a key like RR, or an id. When two projects share a",
     "  name, give the key.",
   ],
+  raid: [
+    '  harbor raid "TITLE"                    reads one risk, issue or decision in',
+    "                                         full: rating, owner, dates, what's",
+    "                                         written about it and its updates",
+    '  harbor raid "TITLE" --status S         writes: moves it on. A risk is open,',
+    "                                         watching, mitigated or closed; an",
+    "                                         issue open, resolved or closed; a",
+    "                                         decision proposed, decided or",
+    "                                         superseded (decided names you and",
+    "                                         today unless --decided-by or",
+    "                                         --decided-on say otherwise)",
+    '  harbor raid "TITLE" --update "TEXT"    writes: adds a line to its updates',
+    "",
+    "  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",
+    "  enough of it to pick one out; harbor risks lists them. Changes several",
+    "  at once, as one change.",
+  ],
+  review: [
+    "  harbor review                          reads the review: every program,",
+    "                                         worst health first, then soonest end,",
+    "                                         with its lead, late work, priority and",
+    "                                         next move (done ones with --done)",
+    "  harbor review --mine                   only programs you lead, lead a",
+    "                                         project in or hold a task in",
+    "  harbor review --owner NAME             the same for someone else",
+    "  harbor review --portfolio P            one portfolio's",
+    "  harbor review TASK                     writes: moves a task to In review",
+    "",
+    '  Write a next move with harbor next-move PROGRAM "TEXT"; set a health by',
+    "  hand with harbor health. harbor export review prints it as CSV.",
+  ],
+  "next-move": [
+    '  harbor next-move PROGRAM "TEXT"        writes: the line the review and the',
+    "                                         brief show for what happens next",
+    '  harbor next-move PROGRAM ""            writes: clears it',
+  ],
+  health: [
+    "  harbor health --program P STATE --note WHY",
+    "                                         writes: sets a program's health by hand",
+    "  harbor health --project P STATE --note WHY",
+    "  harbor health --portfolio P STATE --note WHY",
+    "  harbor health --program P auto         writes: health follows late work again",
+    "",
+    "  STATE is on-track, at-risk, off-track, paused or done. Health is worked",
+    "  out from late work; setting it by hand needs a note saying why (done",
+    "  doesn't), and the note shows beside it everywhere. Paused or done on a",
+    "  program carries to its projects.",
+  ],
   risk: [
     '  harbor risk "TITLE" --project P        writes: logs a risk on the project',
     '  harbor risk "TITLE" --program P        writes: logs one on the program',
@@ -1511,7 +1583,29 @@ export async function run(argv, io = {}) {
     case "start":
     case "review":
     case "done": {
-      const { positionals, values, harbor } = parse(spec(["confirm", "over-limit"]));
+      const { positionals, values, harbor } = parse(
+        command === "review"
+          ? spec(["confirm", "over-limit", "mine", "done"], ["owner", "portfolio"])
+          : spec(["confirm", "over-limit"]),
+      );
+      if (command === "review" && positionals.length === 0) {
+        if (values.mine && values.owner) throw new HarborError("Say --mine or --owner, not both.");
+        return call(
+          "program_review",
+          {
+            harbor,
+            owner: values.mine ? "me" : values.owner,
+            portfolio: values.portfolio,
+            includeDone: Boolean(values.done),
+          },
+          reviewList,
+        );
+      }
+      if (values.mine || values.done || values.owner || values.portfolio) {
+        throw new HarborError(
+          "--mine, --owner, --portfolio and --done are for the review: harbor review on its own.",
+        );
+      }
       const status = { start: "doing", review: "review", done: "done" }[command];
       return call(
         "update_task",
@@ -1865,6 +1959,98 @@ export async function run(argv, io = {}) {
           : `${r.handedBack.person} is back. Nothing was still waiting to go back.`,
       );
     }
+    case "raid": {
+      const fields = [
+        "title",
+        "description",
+        "mitigation",
+        "contingency",
+        "resolution",
+        "rationale",
+        "notes",
+      ];
+      const { positionals, values, harbor } = parse(
+        spec(
+          [],
+          [
+            "status",
+            "owner",
+            "impact",
+            "probability",
+            "due",
+            "update",
+            "decided-by",
+            "decided-on",
+            ...fields,
+          ],
+        ),
+      );
+      const item = text(positionals, "which one: its title, as harbor risks lists it");
+      const scale = (v, name) => (v === "none" ? null : level(v, name));
+      const args = {
+        harbor,
+        item,
+        status: values.status?.trim().toLowerCase(),
+        owner: values.owner,
+        impact: scale(values.impact, "impact"),
+        probability: scale(values.probability, "probability"),
+        due: values.due === undefined ? undefined : nullable(dueDate(values.due)),
+        decidedBy: values["decided-by"],
+        decidedOn:
+          values["decided-on"] === undefined ? undefined : nullable(dueDate(values["decided-on"])),
+        update: values.update,
+        ...Object.fromEntries(fields.map((f) => [f, values[f]])),
+      };
+      const changes = Object.entries(args).filter(
+        ([k, v]) => !["harbor", "item"].includes(k) && v !== undefined,
+      );
+      if (!changes.length) {
+        return call("get_raid", { harbor, item }, (r) => raidDetail(r.item));
+      }
+      return call("update_raid", args, (r) => `Updated.\n\n${raidDetail(r.updated)}`);
+    }
+    case "next-move": {
+      const { positionals, harbor } = parse(spec([]));
+      if (positionals.length < 2) {
+        throw new HarborError(
+          'Give the program and its next move: harbor next-move "PROGRAM" "TEXT". harbor review shows them.',
+        );
+      }
+      const [program, ...words] = positionals;
+      return call("set_next_move", { harbor, program, text: words.join(" ") }, (r) =>
+        r.nextMove
+          ? `Next move for ${r.program}: ${r.nextMove}`
+          : `Cleared the next move for ${r.program}.`,
+      );
+    }
+    case "health": {
+      const { positionals, values, harbor } = parse(
+        spec([], ["program", "project", "portfolio", "note"]),
+      );
+      const state = one(positionals, "health: on-track, at-risk, off-track, paused, done or auto")
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_]+/g, "-");
+      const word = { "on-track": "on track", "at-risk": "at risk", "off-track": "off track" };
+      return call(
+        "set_health",
+        {
+          harbor,
+          program: values.program,
+          project: values.project,
+          portfolio: values.portfolio,
+          health: state,
+          note: values.note,
+        },
+        (r) => {
+          const name = r.program ?? r.project ?? r.portfolio;
+          const h = word[r.health] ?? r.health;
+          return r.setByHand
+            ? `${name} is ${h}, set by hand${r.note ? `: ${r.note}` : ""}.`
+            : `${name}'s health follows its work again: ${h}.`;
+        },
+      );
+    }
     case "risk":
     case "issue":
     case "decision": {

package/lib/format.mjs

@@ -270,6 +270,76 @@ export function raidList(r, words = "") {
   return lines.join("\n") + more;
 }
 
+/**
+ * One item of the register in full, as get_raid and update_raid give it:
+ * what it is and where, its rating, every written field, then its updates.
+ */
+export function raidDetail(x) {
+  const out = [`${x.kind}: ${x.title}`];
+  const facts = [
+    x.status,
+    x.probability != null ? `likelihood ${x.probability}` : null,
+    x.impact != null ? `impact ${x.impact}` : null,
+    x.score != null ? `score ${x.score}` : null,
+    x.owner ? `owner ${x.owner}` : "no owner yet",
+    x.project ?? x.program ?? x.portfolio ?? null,
+    x.due ? `${(x.dueMeans ?? "due").toLowerCase()} ${x.due}` : null,
+    x.decidedBy ? `decided by ${x.decidedBy}${x.decidedOn ? ` on ${x.decidedOn}` : ""}` : null,
+  ].filter(Boolean);
+  out.push(facts.join(" · "));
+  const words = {
+    risk: {
+      description: "What could happen",
+      mitigation: "How we reduce it",
+      contingency: "If it happens",
+    },
+    issue: { description: "What's going on", resolution: "How it gets resolved" },
+    decision: { description: "Context", resolution: "The decision", rationale: "Why" },
+  }[x.kind?.toLowerCase()] ?? { description: "Description" };
+  for (const [key, label] of Object.entries({ ...words, notes: "Notes" })) {
+    if (x[key])
+      out.push(
+        "",
+        `${label}:`,
+        ...String(x[key])
+          .split("\n")
+          .map((l) => `  ${l}`),
+      );
+  }
+  if (x.updates?.length) {
+    out.push("", "Updates:");
+    for (const u of x.updates) out.push(`  ${u.on ?? ""} ${u.by}: ${u.body.replace(/\s+/g, " ")}`);
+  }
+  return out.join("\n");
+}
+
+/**
+ * The review, as program_review gives it: programs worst first, each with
+ * its lead, end, late work and priority, and the next move under it.
+ */
+export function reviewList(r) {
+  const programs = r.programs ?? [];
+  const more = hiddenNote(r.done ?? 0, "program");
+  if (!programs.length) {
+    return r.done ? `Every program here is done.${more.replace("\n", " ")}` : "No programs here.";
+  }
+  const out = [];
+  for (const p of programs) {
+    const said = health(p.health) + (p.setByHand ? ` by hand${p.note ? `: ${p.note}` : ""}` : "");
+    const bits = [
+      said,
+      p.lead,
+      p.ends ? `ends ${p.ends}` : null,
+      p.late ? `${p.late} late` : null,
+      p.priority ?? null,
+      p.portfolio ?? null,
+    ].filter(Boolean);
+    out.push(`${p.name}  (${bits.join(" · ")})`);
+    out.push(`  ${p.nextMove ? `next: ${p.nextMove}` : "no next move yet"}`);
+  }
+  return out.join("\n") + more;
+}
+
 /** "over 95%", in steps of five, as the website says it (src/lib/tide.ts chanceText). */
 function chance(c) {
   if (c < 0.05) return "under 5%";
@@ -346,7 +416,7 @@ export function forecastOne(p) {
   if (f.lastDue) {
     const which = f.lastDue.key ? `${f.lastDue.key} “${f.lastDue.title}”` : `“${f.lastDue.title}”`;
     lines.push(
-      `${which} is due ${f.lastDue.due}, after the likely finish, so the plan runs longer than the pace says.`,
+      `${which} is due ${f.lastDue.due}, later than the crew's pace alone would finish, so the dates wait for it.`,
     );
   }
   return lines.join("\n");

package/package.json

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