@harborppm/cli 0.43.0 → 0.45.0

package/lib/cli.mjs

@@ -36,7 +36,9 @@ import {
   voyageText,
   handoverText,
   agentWorkText,
+  raidDetail,
   raidList,
+  reviewList,
   programTree,
   projectList,
   taskLine,
@@ -113,7 +115,9 @@ export const HELP = `harbor: Harbor from the terminal
   harbor add "TITLE" --project P [--assignee me|none|NAME] [--due DATE]
                      [--priority low|medium|high|urgent] [--status S]
                      [--over-limit]
-  harbor start TASK | review TASK | done TASK [--confirm] [--over-limit]
+  harbor start TASK | submit TASK | done TASK [--confirm] [--over-limit]
+                                              move a task to In play, In review
+                                              or Done
   harbor edit TASK [--title T] [--assignee me|none|NAME] [--due DATE|none]
                    [--priority P] [--status S] [--notes TEXT]
                    [--repeat weekly|biweekly|monthly|never]
@@ -130,6 +134,20 @@ 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 [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 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 +338,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",
@@ -609,6 +632,59 @@ 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 "WORDS"                  only programs whose name has them',
+    "",
+    "  The review only reads. To move a task to In review, run harbor submit",
+    "  TASK (harbor review TASK did that before 0.45.0, and now says so).",
+    '  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',
@@ -718,6 +794,13 @@ async function harborNamed(client, key) {
 
 const TASK_KEY = /^[A-Za-z][A-Za-z0-9]{0,9}-\d+$/;
 
+/** True when every word of `words` is somewhere in `name`, any case. */
+const nameHas = (name, words) =>
+  words
+    .toLowerCase()
+    .split(/\s+/)
+    .every((w) => name.toLowerCase().includes(w));
+
 /**
  * A task by its key, else a project by name, else a task by id: its web
  * link and what to call it. Harbor's own refusal when nothing matches.
@@ -848,6 +931,7 @@ export async function run(argv, io = {}) {
         await writeCredentials({ ...now, harbor: h.id, harborName: h.name }, env);
       },
       theme: (await readSettings(env)).theme,
+      browse: io.browse ?? openBrowser,
     });
     return 0;
   }
@@ -1510,10 +1594,42 @@ export async function run(argv, io = {}) {
       );
     }
     case "start":
+    case "submit":
     case "review":
     case "done": {
-      const { positionals, values, harbor } = parse(spec(["confirm", "over-limit"]));
-      const status = { start: "doing", review: "review", done: "done" }[command];
+      const { positionals, values, harbor } = parse(
+        command === "review"
+          ? spec(["confirm", "over-limit", "mine", "done"], ["owner", "portfolio"])
+          : spec(["confirm", "over-limit"]),
+      );
+      if (command === "review") {
+        // The review only reads: a task key here once moved the task, so it says where that went.
+        const words = positionals.join(" ").trim();
+        if (TASK_KEY.test(words)) {
+          throw new HarborError(
+            `harbor review only reads the review now. To move ${words} to In review, run harbor submit ${words}.`,
+          );
+        }
+        if (values.confirm || values["over-limit"]) {
+          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(
+          "program_review",
+          {
+            harbor,
+            owner: values.mine ? "me" : values.owner,
+            portfolio: values.portfolio,
+            includeDone: Boolean(values.done),
+          },
+          (r) =>
+            words && r.programs.length === 0
+              ? `No program in the review matches "${words}".`
+              : reviewList(r),
+          (r) => (words ? { ...r, programs: r.programs.filter((p) => nameHas(p.name, words)) } : r),
+        );
+      }
+      const status = { start: "doing", submit: "review", done: "done" }[command];
       return call(
         "update_task",
         {
@@ -1866,6 +1982,99 @@ 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) {
+        // --json gives the item itself, as harbor show does a task.
+        return call("get_raid", { harbor, item }, raidDetail, (r) => r.item ?? r);
+      }
+      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%";

package/package.json

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