@harborppm/cli 0.28.0 → 0.30.0

package/README.md

@@ -57,7 +57,7 @@ Your harbor is the same one at [harborppm.com](https://harborppm.com/today?utm_s
 - **GitHub**: a pull request that names a task's key (RR-42) shows on the task and moves it along.
 - **Claude and other AI apps**, connected over MCP from [harborppm.com/ai](https://harborppm.com/ai?utm_source=npm&utm_medium=readme&utm_campaign=cli).
 
-`harbor open RR-42` opens a task on the website (in the right harbor, even when the browser had another one open), `harbor open Ridge` a project, and `harbor open` on its own opens Today. `harbor invite sam@example.com` sends Sam the same invite letter the People page does (`--viewer` to let them look but not change anything); only a harbor's owner can invite. `harbor calendar` prints your private calendar link, to add to Google, Apple or Outlook calendar: your due dates, milestones and sign-offs beside your meetings, kept up to date (`--program NAME` for everything dated in one program, `--new` to swap the link for a fresh one, `--off` to turn it off).
+`harbor open RR-42` opens a task on the website (in the right harbor, even when the browser had another one open), `harbor open Ridge` a project, and `harbor open` on its own opens Today. `harbor invite sam@example.com` sends Sam the same invite letter the People page does (`--viewer` to let them look but not change anything); only a harbor's owner can invite. `harbor calendar` prints your private calendar link, to add to Google, Apple or Outlook calendar: your due dates, milestones and sign-offs beside your meetings, kept up to date (`--program NAME` for everything dated in one program, `--new` to swap the link for a fresh one, `--off` to turn it off). `harbor roadmap "Next steps"` publishes a project as a public roadmap page (Now, Next and Shipped, task titles only) and prints its link; `--dates` adds the day each thing shipped and `--off` takes it down. Only a harbor's owner can publish.
 
 The website has the commands too: turn on **Command line at the bottom** in your menu, press `/`, and type `mine`, `add "Call the mill" #ridge @sam --due fri` or `done RR-12`.
 
@@ -103,6 +103,7 @@ harbor show TASK                            one task in full, with its web link
 harbor open [TASK|PROJECT]                  open it on the website (or Today)
 harbor invite EMAIL [--viewer]              invite someone to your harbor by email
 harbor calendar [--program P] [--new|--off] your private calendar link (.ics)
+harbor roadmap PROJECT [--dates] [--off]    publish a project's public roadmap
 
 harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                      [--ends DATE]
@@ -123,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]
@@ -133,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

@@ -79,6 +79,8 @@ export const HELP = `harbor: Harbor from the terminal
   harbor prompt --init SHELL                  how to add it: zsh, bash, fish
                                               or starship
   harbor calendar [--program P] [--new|--off] your private calendar link (.ics)
+  harbor roadmap PROJECT [--dates|--no-dates] [--off]
+                                              publish a project's public roadmap
 
   harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                        [--ends DATE]
@@ -104,7 +106,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
@@ -172,6 +176,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];
@@ -1011,6 +1065,46 @@ export async function run(argv, io = {}) {
       );
       return 0;
     }
+    case "roadmap": {
+      const { positionals, values, harbor } = parse(
+        spec(["dates", "no-dates", "site", "no-site", "off"]),
+      );
+      const project = text(positionals, "which project");
+      if (values.dates && values["no-dates"])
+        throw new HarborError("Say --dates or --no-dates, not both.");
+      if (values.site && values["no-site"])
+        throw new HarborError("Say --site or --no-site, not both.");
+      if (!hasFullAccess(creds)) {
+        throw new HarborError("Publishing needs full access. Run harbor login, then try again.");
+      }
+      const r = await client.app({
+        op: "roadmap",
+        ...(harbor ? { harbor } : {}),
+        project,
+        ...(values.off ? { off: true } : {}),
+        ...(values.dates || values["no-dates"] ? { showDates: Boolean(values.dates) } : {}),
+        ...(values.site || values["no-site"] ? { onSite: Boolean(values.site) } : {}),
+      });
+      if (asJson) {
+        out(jsonText(r));
+        return 0;
+      }
+      if (!r.url) {
+        out(
+          plain(
+            `${r.project} isn't published any more. Its link says the roadmap isn't published.`,
+          ),
+        );
+        return 0;
+      }
+      const shows = r.showDates ? "titles and the day each shipped" : "titles only";
+      out(
+        plain(
+          `${r.project}'s public roadmap (Now, Next and Shipped; ${shows}, no people):\n\n  ${r.url}${r.siteUrl ? `\n\nIt's also Harbor's own roadmap at ${r.siteUrl}.` : ""}\n\nharbor roadmap "${r.project}" --off takes it down.`,
+        ),
+      );
+      return 0;
+    }
     case "add": {
       const { positionals, values, harbor } = parse(
         spec(["over-limit"], ["project", "assignee", "due", "priority", "status"]),
@@ -1123,6 +1217,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
@@ -1143,11 +1260,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;

package/package.json

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