@harborppm/cli 0.29.0 → 0.31.0

package/README.md

@@ -124,7 +124,7 @@ 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]
 harbor risks [words] [--kind risk,issue,decision] [--project P] [--closed]
-harbor brief [--portfolio P]                the weekly brief, ready to send
+harbor brief [--portfolio P] [--say]        the weekly brief, ready to send
 harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
 harbor voyage PROJECT ["YOUR LINE"]
 harbor limit PROJECT [COLUMN N|none]
@@ -134,6 +134,8 @@ harbor limit PROJECT [COLUMN N|none]
 
 `harbor premortem` runs a pre-mortem with your crew: `--start` asks everyone "it's after the end date and this project failed: what happened?", each person adds answers alone for five minutes, and then the answers show together on the project's Risks & issues tab, where each becomes a risk in one click. On its own it prints the question and the answers you can see. Once a project is Done, `harbor voyage` prints its voyage log (planned against actual dates, the biggest slips, the risks that came true, who closed the most, and the crew's lines) and adds yours.
 
+`harbor brief --say` turns the brief into the BBC's Shipping Forecast: each program an area, wind for late work, visibility for health, gale warnings for anything off track. It prints the forecast and speaks it with your computer's own voice (`say` on a Mac, Windows' speech, or `espeak-ng` on Linux).
+
 Every command takes `--json` for the raw result (a refusal then comes out as `{"error": "…"}` on standard output, still with exit code 1), and `harbor COMMAND --help` shows just that command. Statuses are backlog, todo, doing, review and done. A `DATE` is YYYY-MM-DD, `today`, `tomorrow`, or `+N` for N days from today.
 
 When you belong to more than one harbor, say which: `--harbor NAME` on the command, or `harbor use NAME` once (it's saved with your sign-in; `harbor use none` forgets it). With neither, the commands ask rather than guess, so nothing lands in the wrong harbor. The full-screen app shares the same choice: it opens the harbor `harbor use` set, asks which one the first time if none is set, and a harbor you switch to in the app becomes the one the commands use.

package/lib/cli.mjs

@@ -22,6 +22,7 @@ import {
   STATUS,
   harbors,
   limitsText,
+  hillData,
   hillList,
   myWork,
   premortemText,
@@ -106,7 +107,9 @@ 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 brief [--portfolio P]                the weekly brief, ready to send
+  harbor brief [--portfolio P] [--say]        the weekly brief, ready to send;
+                                              --say reads it aloud as a
+                                              shipping forecast
   harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
                                               a project's pre-mortem: start,
                                               answer or read it
@@ -174,6 +177,56 @@ function openBrowser(url) {
   }
 }
 
+/**
+ * How to read text aloud here, as programs to try in turn, each with its
+ * arguments (never through a shell). Text goes on stdin where it can, so
+ * nothing in it is read as an option.
+ */
+export function speechCommands(platform = process.platform) {
+  if (platform === "darwin") return [["say", ["-f", "-"]]];
+  if (platform === "win32")
+    return [
+      [
+        "powershell",
+        [
+          "-NoProfile",
+          "-Command",
+          "Add-Type -AssemblyName System.Speech; (New-Object System.Speech.Synthesis.SpeechSynthesizer).Speak([Console]::In.ReadToEnd())",
+        ],
+      ],
+    ];
+  return [
+    ["espeak-ng", ["--stdin", "-s", "155"]],
+    ["espeak", ["--stdin", "-s", "155"]],
+    ["spd-say", ["-w", "-e"]],
+  ];
+}
+
+/** Read `text` aloud with the first speech program this machine has; false when none ran. */
+async function speak(text) {
+  for (const [program, args] of speechCommands()) {
+    const ok = await new Promise((resolve) => {
+      try {
+        const child = spawn(program, args, { stdio: ["pipe", "ignore", "ignore"] });
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+        child.stdin.on("error", () => {});
+        child.stdin.end(text);
+      } catch {
+        resolve(false);
+      }
+    });
+    if (ok) return true;
+  }
+  return false;
+}
+
+/** This machine's wall-clock time as YYYY-MM-DDTHH:MM, which Harbor reads as the caller's hour. */
+export function localMinute(now = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}`;
+}
+
 const one = (positionals, what) => {
   if (positionals.length !== 1) throw new HarborError(`Give one ${what}.`);
   return positionals[0];
@@ -847,7 +900,12 @@ export async function run(argv, io = {}) {
       if (!project) {
         if (values.at !== undefined)
           throw new HarborError("Say which project: harbor hill PROJECT --at N.");
-        return call("list_projects", { harbor, program: values.program, limit: 100 }, hillList);
+        return call(
+          "list_projects",
+          { harbor, program: values.program, limit: 100 },
+          hillList,
+          (r) => hillData(r, values.program),
+        );
       }
       if (values.at === undefined) {
         throw new HarborError("Say where with --at: 0 to 100, or start, top, doing or done.");
@@ -1165,6 +1223,29 @@ export async function run(argv, io = {}) {
         () => "Checked in for today.",
       );
     }
+    case "brief": {
+      const { positionals, values, harbor } = parse(spec(["say"], ["portfolio"]));
+      none(positionals);
+      if (!values.say) {
+        return call("weekly_brief", { harbor, portfolio: values.portfolio }, (r) => r.text);
+      }
+      const result = await client
+        .call("shipping_forecast", { harbor, portfolio: values.portfolio, at: localMinute() })
+        .catch((err) => {
+          if (err instanceof HarborError) throw new HarborError(hint(err.message));
+          throw err;
+        });
+      const script = plain(result.script ?? "");
+      out(asJson ? jsonText(result) : script);
+      if (!(await (io.speak ?? speak)(script))) {
+        throw new HarborError(
+          process.platform === "linux"
+            ? "Nothing here can read aloud. Install espeak-ng (or speech-dispatcher) and try again."
+            : "Nothing here can read aloud.",
+        );
+      }
+      return 0;
+    }
     case "risks": {
       const { positionals, values, harbor } = parse(spec(["closed"], ["kind", "project"]));
       const kind = values.kind
@@ -1185,11 +1266,6 @@ export async function run(argv, io = {}) {
         (r) => raidList(r, positionals.join(" ")),
       );
     }
-    case "brief": {
-      const { positionals, values, harbor } = parse(spec([], ["portfolio"]));
-      none(positionals);
-      return call("weekly_brief", { harbor, portfolio: values.portfolio }, (r) => r.text);
-    }
     case "premortem": {
       const { positionals, values, harbor } = parse(spec(["start"]));
       const [project, ...words] = positionals;
@@ -1229,7 +1305,7 @@ export async function run(argv, io = {}) {
       if (!project) throw new HarborError("Give a project, like harbor limit RR doing 5.");
       if (!column) {
         return call("get_project", { harbor, project }, (r) =>
-          limitsText(r.name, r.limits, r.tasks),
+          limitsText(r.name, r.limits, r.tasks, r.hiddenColumns),
         );
       }
       if (value === undefined || extra.length) {
@@ -1240,7 +1316,7 @@ export async function run(argv, io = {}) {
         throw new HarborError("A limit is a whole number from 1 to 20, or none.");
       }
       return call("set_column_limit", { harbor, project, column, limit }, (r) =>
-        limitsText(r.set.project, r.limits, r.tasks),
+        limitsText(r.set.project, r.limits, r.tasks, r.hiddenColumns),
       );
     }
     case "voyage": {

package/lib/format.mjs

@@ -144,16 +144,26 @@ export function projectList(r, { done = false } = {}) {
   );
 }
 
-/** A project's column limits with how full each is: "doing 4 of 5; no limit on backlog, todo, done". */
-export function limitsText(name, limits, tasks = {}) {
+/**
+ * A project's column limits with how full each is: "doing 4 of 5; no limit on
+ * backlog, todo, done". Columns the board hides are named after, with any cap
+ * they keep for when they're shown again.
+ */
+export function limitsText(name, limits, tasks = {}, hidden = []) {
+  const label = (status) => STATUS[status] ?? status;
   const entries = Object.entries(limits ?? {});
-  const capped = entries
+  const shown = entries.filter(([status]) => !hidden.includes(status));
+  const capped = shown
     .filter(([, n]) => n != null)
-    .map(([status, n]) => `${STATUS[status] ?? status} ${tasks[status] ?? 0} of ${n}`);
-  const open = entries.filter(([, n]) => n == null).map(([status]) => STATUS[status] ?? status);
-  if (!capped.length) return `${name}'s board has no column limits.`;
+    .map(([status, n]) => `${label(status)} ${tasks[status] ?? 0} of ${n}`);
+  const open = shown.filter(([, n]) => n == null).map(([status]) => label(status));
+  const off = entries
+    .filter(([status]) => hidden.includes(status))
+    .map(([status, n]) => (n == null ? label(status) : `${label(status)} (limit ${n})`));
+  const offNote = off.length ? ` Hidden on the board: ${off.join(", ")}.` : "";
+  if (!capped.length) return `${name}'s board has no column limits.${offNote}`;
   const rest = open.length ? `; no limit on ${open.join(", ")}` : "";
-  return `${name}: ${capped.join(", ")}${rest}.`;
+  return `${name}: ${capped.join(", ")}${rest}.${offNote}`;
 }
 
 export function harbors(r) {
@@ -295,10 +305,43 @@ function hillTrack(at) {
   return cells.join("");
 }
 
+/**
+ * What harbor hill shows, for the chart and --json alike: open projects with
+ * their place on the hill (null when not on it), how many Done ones were left
+ * out, and the program asked for.
+ */
+export function hillData(r, program) {
+  const all = r.projects ?? [];
+  const open = all.filter((p) => p.health !== "done");
+  // The program's own name when every project is in it, else what was typed.
+  const named =
+    all.length && all.every((p) => p.program === all[0].program) ? all[0].program : null;
+  return {
+    ...(program ? { program: named ?? program } : {}),
+    projects: open.map((p) => ({
+      id: p.id,
+      name: p.name,
+      ...(p.key ? { key: p.key } : {}),
+      program: p.program ?? null,
+      health: p.health,
+      hill: p.hill ?? null,
+    })),
+    done: all.length - open.length,
+  };
+}
+
 /** Each open project's place on its program's hill, by program, unplaced ones named after. */
 export function hillList(r) {
   const projects = (r.projects ?? []).filter((p) => p.health !== "done");
-  if (!projects.length) return "No open projects match.";
+  if (!projects.length) {
+    if (r.done) {
+      const where = r.program ? `in ${r.program} ` : "";
+      return r.done === 1
+        ? `The one project ${where}is Done, so nothing is on the hill.`
+        : `All ${r.done} projects ${where}are Done, so nothing is on the hill.`;
+    }
+    return "No open projects match.";
+  }
   const byProgram = new Map();
   for (const p of projects) {
     const key = p.program ?? "No program";
@@ -317,6 +360,11 @@ export function hillList(r) {
       lines.push(`  ${name}  ${hillTrack(p.hill.at)} ${String(p.hill.at).padStart(3)}${still}`);
     }
     if (unplaced.length) lines.push(`  Not on the hill: ${unplaced.map((p) => p.name).join(", ")}`);
+    if (!placed.length) {
+      lines.push(
+        `  Place one with harbor hill "${unplaced[0].name}" --at 30 (0 to 100, top is 50).`,
+      );
+    }
     blocks.push(lines.join("\n"));
   }
   return blocks.join("\n\n");

package/package.json

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